From: Glenn Morris Date: Thu, 6 Sep 2007 05:07:05 +0000 (+0000) Subject: Move here from ../../man X-Git-Tag: emacs-pretest-23.0.90~11078 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4009494e10ff47635e0a1bb2c87ce55decf6bc2e;p=emacs.git Move here from ../../man --- diff --git a/doc/misc/.gitignore b/doc/misc/.gitignore new file mode 100644 index 00000000000..3ff56b474dd --- /dev/null +++ b/doc/misc/.gitignore @@ -0,0 +1,23 @@ +*.aux +*.cp +*.cps +*.dvi +*.fn +*.fns +*.ky +*.kys +*.log +*.op +*.ops +*.pdf +*.pg +*.pgs +*.ps +*.tmp +*.toc +*.tp +*.tps +*.vr +*.vrs +Makefile +makefile diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog new file mode 100644 index 00000000000..0c75ca1a4f0 --- /dev/null +++ b/doc/misc/ChangeLog @@ -0,0 +1,49 @@ +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/. + Change all setfilename commands to use ../../info. + * Makefile.in: Move the parts of the old man/Makefile.in that do not + refer to the Emacs manual here. + (infodir): New variable. + (INFO_TARGETS, info): Use infodir. Also used by all info targets. + (cc-mode.texi, faq.texi): Update references to source file locations. + * makefile.w32-in: Move the parts of the old man/makefile.w32-in that + do not refer to the Emacs manual here. + (infodir, MULTI_INSTALL_INFO, ENVADD): Go up one more level. + + * Makefile.in: Add `basename' versions of all info targets, for + convenience when rebuilding just one manual. + (../etc/GNU): Delete obsolete target. + (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi. + (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs + *.vrs *.toc here... + (maintainer-clean): ...from here. + + * makefile.w32-in (../etc/GNU): Delete obsolete target. + +;; Local Variables: +;; coding: iso-2022-7bit +;; fill-column: 79 +;; add-log-time-zone-rule: t +;; End: + + Copyright (C) 2007 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, 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; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in new file mode 100644 index 00000000000..00088b74b51 --- /dev/null +++ b/doc/misc/Makefile.in @@ -0,0 +1,368 @@ +#### Makefile for the Emacs Manual and other documentation. + +# Copyright (C) 1994, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, +# 2004, 2005, 2006, 2007 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, 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; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + +# 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@ + + +# 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 = ../info/emacs ../info/ccmode ../info/cl \ + ../info/dired-x ../info/ediff ../info/forms ../info/gnus \ + ../info/message ../info/sieve ../info/pgg ../info/emacs-mime \ + ../info/info ../info/mh-e ../info/reftex \ + ../info/sc ../info/vip ../info/viper ../info/widget \ + ../info/efaq ../info/ada-mode ../info/autotype ../info/calc \ + ../info/idlwave ../info/eudc ../info/ebrowse ../info/pcl-cvs \ + ../info/woman ../info/eshell ../info/org ../info/url \ + ../info/speedbar ../info/tramp ../info/ses ../info/smtpmail \ + ../info/flymake ../info/newsticker ../info/rcirc ../info/erc +DVI_TARGETS = emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \ + ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ + gnus.dvi message.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 emacs-xtra.dvi rcirc.dvi erc.dvi +INFOSOURCES = info.texi + +# The following rule does not work with all versions of `make'. +.SUFFIXES: .texi .dvi +.texi.dvi: + texi2dvi $< + +TEXI2DVI = texi2dvi +ENVADD = TEXINPUTS="$(srcdir):$(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)/vc2-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: $(top_srcdir)/info $(INFO_TARGETS) + +$(top_srcdir)/info: + 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. + +# The following target uses an explicit -o switch to work around +# the @setfilename directive in info.texi, which is required for +# the Texinfo distribution. + +../info/info: ${INFOSOURCES} + cd $(srcdir); $(MAKEINFO) --no-split info.texi -o $@ + +info.dvi: ${INFOSOURCES} + $(ENVADD) $(TEXI2DVI) ${srcdir}/info.texi + +../info/emacs: ${EMACSSOURCES} + cd $(srcdir); $(MAKEINFO) emacs.texi + +emacs.dvi: ${EMACSSOURCES} + $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi + +# This target is here so you could easily get the list of the *.texi +# files which belong to the Emacs manual (as opposed to the separate +# manuals for CL, CC Mode, Ebrowse, etc.). With this target, you can +# say things like "grep foo `make emacsman`". +emacsman: + @echo $(EMACSSOURCES) + +../info/ccmode: cc-mode.texi + cd $(srcdir); $(MAKEINFO) cc-mode.texi +cc-mode.dvi: cc-mode.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/cc-mode.texi + +../info/ada-mode: ada-mode.texi + cd $(srcdir); $(MAKEINFO) ada-mode.texi +ada-mode.dvi: ada-mode.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ada-mode.texi + +../info/pcl-cvs: pcl-cvs.texi + cd $(srcdir); $(MAKEINFO) pcl-cvs.texi +pcl-cvs.dvi: pcl-cvs.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi + +../info/eshell: eshell.texi + cd $(srcdir); $(MAKEINFO) eshell.texi +eshell.dvi: eshell.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi + +../info/cl: cl.texi + cd $(srcdir); $(MAKEINFO) cl.texi +cl.dvi: cl.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/cl.texi + +../info/dired-x: dired-x.texi + cd $(srcdir); $(MAKEINFO) dired-x.texi +dired-x.dvi: dired-x.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/dired-x.texi + +../info/ediff: ediff.texi + cd $(srcdir); $(MAKEINFO) ediff.texi +ediff.dvi: ediff.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi + +emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) + $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi + +../info/forms: forms.texi + cd $(srcdir); $(MAKEINFO) forms.texi +forms.dvi: forms.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/forms.texi + +# gnus/message/emacs-mime/sieve/pgg are part of Gnus: +../info/gnus: gnus.texi gnus-faq.texi + cd $(srcdir); $(MAKEINFO) gnus.texi +gnus.dvi: gnus.texi gnus-faq.texi + sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi + $(ENVADD) $(TEXI2DVI) gnustmp.texi + cp gnustmp.dvi $*.dvi + rm gnustmp.* + +../info/message: message.texi + cd $(srcdir); $(MAKEINFO) message.texi +message.dvi: message.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/message.texi + +../info/sieve: sieve.texi + cd $(srcdir); $(MAKEINFO) sieve.texi +sieve.dvi: sieve.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/sieve.texi + +../info/emacs-mime: emacs-mime.texi + cd $(srcdir); $(MAKEINFO) --enable-encoding emacs-mime.texi +emacs-mime.dvi: emacs-mime.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-mime.texi + +../info/pgg: pgg.texi + cd $(srcdir); $(MAKEINFO) pgg.texi +pgg.dvi: pgg.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/pgg.texi + +../info/mh-e: mh-e.texi + cd $(srcdir); $(MAKEINFO) mh-e.texi +mh-e.dvi: mh-e.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/mh-e.texi + +../info/reftex: reftex.texi + cd $(srcdir); $(MAKEINFO) reftex.texi +reftex.dvi: reftex.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/reftex.texi + +../info/sc: sc.texi + cd $(srcdir); $(MAKEINFO) sc.texi +sc.dvi: sc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi + +../info/vip: vip.texi + cd $(srcdir); $(MAKEINFO) vip.texi +vip.dvi: vip.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/vip.texi + +../info/viper: viper.texi + cd $(srcdir); $(MAKEINFO) viper.texi +viper.dvi: viper.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/viper.texi + +../info/widget: widget.texi + cd $(srcdir); $(MAKEINFO) widget.texi +widget.dvi: widget.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/widget.texi + +../info/efaq: faq.texi + cd $(srcdir); $(MAKEINFO) faq.texi +faq.dvi: faq.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/faq.texi + +../etc/GNU: gnu1.texi gnu.texi + cd $(srcdir) && makeinfo --no-headers -o ../etc/GNU gnu1.texi + +../info/autotype: autotype.texi + cd $(srcdir); $(MAKEINFO) autotype.texi +autotype.dvi: autotype.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/autotype.texi + +../info/calc: calc.texi + cd $(srcdir); $(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 +../info/idlwave: idlwave.texi + cd $(srcdir); $(MAKEINFO) --no-split idlwave.texi +idlwave.dvi: idlwave.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/idlwave.texi + +../info/eudc: eudc.texi + cd $(srcdir); $(MAKEINFO) eudc.texi +eudc.dvi: eudc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/eudc.texi + +../info/ebrowse: ebrowse.texi + cd $(srcdir); $(MAKEINFO) ebrowse.texi +ebrowse.dvi: ebrowse.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ebrowse.texi + +../info/woman: woman.texi + cd $(srcdir); $(MAKEINFO) woman.texi +woman.dvi: woman.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/woman.texi + +../info/org: org.texi + cd $(srcdir); $(MAKEINFO) org.texi +org.dvi: org.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/org.texi + +../info/url: url.texi + cd $(srcdir); $(MAKEINFO) url.texi +url.dvi: url.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/url.texi + +../info/speedbar: speedbar.texi + cd $(srcdir); $(MAKEINFO) speedbar.texi +speedbar.dvi: speedbar.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/speedbar.texi + +../info/tramp: tramp.texi trampver.texi + cd $(srcdir); $(MAKEINFO) -D emacs tramp.texi +tramp.dvi: tramp.texi trampver.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/tramp.texi + +../info/ses: ses.texi + cd $(srcdir); $(MAKEINFO) ses.texi +ses.dvi: ses.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ses.texi + +../info/smtpmail: smtpmail.texi + cd $(srcdir); $(MAKEINFO) smtpmail.texi +smtpmail.dvi: smtpmail.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/smtpmail.texi + +../info/flymake: flymake.texi + cd $(srcdir); $(MAKEINFO) flymake.texi +flymake.dvi: flymake.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/flymake.texi + +../info/newsticker: newsticker.texi + cd $(srcdir); $(MAKEINFO) newsticker.texi +newsticker.dvi: newsticker.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi + +../info/rcirc: rcirc.texi + cd $(srcdir); $(MAKEINFO) rcirc.texi +rcirc.dvi: rcirc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/rcirc.texi + +../info/erc: erc.texi + cd $(srcdir); $(MAKEINFO) erc.texi +erc.dvi: erc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/erc.texi + +mostlyclean: + rm -f *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* + +clean: mostlyclean + rm -f *.dvi + +distclean: clean + +maintainer-clean: distclean + rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc + 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/ada-mode.texi b/doc/misc/ada-mode.texi new file mode 100644 index 00000000000..241149803e8 --- /dev/null +++ b/doc/misc/ada-mode.texi @@ -0,0 +1,1410 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../info/ada-mode +@settitle Ada Mode + +@copying +Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, +2005, 2006, 2007 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.2 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'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 3.7 +@sp 2 +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c fixme; title page doesn't show up in ada-mode.info; why bother with +@c it? + +@node Top, Overview, (dir), (dir) + +@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 @key{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 +@key{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_unit} 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_unit} 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_unit}. + +@item Set main and Build +Sets @code{main_unit} to the current file, then executes the Build +command. + +@item Show main +Display @code{main_unit} in the message buffer. + +@item Build +Compiles all obsolete units of the current @code{main_unit}, and links +@code{main_unit}, by running @code{make_cmd} from the current project. + +This sets @code{main_unit} 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 @key{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_unit} 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 @key{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, @key{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_unit}: + +@enumerate +@item +Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to +the current file. + +@item +Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and +@code{main}, and click @key{[save]} + +@item +Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit} + +@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}. + +@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 @key{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. + +@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. + +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. + +Here is the list of variables. In the default values, the current +directory @code{"."} is the project file directory. + +@c defined in ada-xref-set-default-prj-values; same order here +@table @asis +@item @code{build_dir} [default: @code{"."}] +The compile commands will be issued in this directory. + +@item @code{src_dir} [default: @code{"."}] +A list of directories to search for source files, both for compile +commands and source navigation. + +@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{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{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{bind_opt} [default: @code{""}] +Holds user binder options; used in the default build commands. + +Lisp variable: @code{ada-prj-default-bind-opt}. + +@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{gnatmake_opt} [default: @code{"-g"}] +Holds user gnatmake options; used in the default build commands. + +If a GNAT project file is used (for example @file{project.gpr}), this +option should be set to @code{-Pproject.gpr}. + +Lisp variable: @code{ada-prj-default-gnatmake-opt}. + +@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{main} [default: current file] +Specifies the name of the executable file for the project; used in the +default build commands. + +@item @code{main_unit} [default: current Ada unit] +Specifies the name of the main Ada unit for the project; used in the +default build commands. + +@item @code{cross_prefix} [default: @code{""}] +Name of target machine in a cross-compilation environment. Used in +default compile and build commands. + +@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{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{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{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main_unit@} $@{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{run_cmd} [default: @code{"./$@{main@}"}] +Command used to run the application. + +@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] +Command executed before @code{debug_cmd}. + +@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}. + +@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:: +@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 + +@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 + +Yes, this is missing the keyword @code{body}; another compiler error +example. + +In buffer @file{hello.adb}, invoke @key{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 @key{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 @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello}. + +Now (in buffer @file{hello.adb}), invoke @key{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 @key{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 @key{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 @key{Ada | Show main}; this displays @file{Ada mode main_unit: hello_2}. + +Move to the error with @key{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 @key{Ada | Build}. +gnatmake successfully builds @file{hello_2}. This demonstrates that +Emacs has remembered the main file, in the project variable +@code{main_unit}, and used it for the Build command. + +Finally, again while in @file{hello_pkg.adb}, invoke @key{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 @key{Ada | Run}, @file{hello_2.exe} will be run. That is +because @code{main_unit} is still set to @code{hello_2}, as you can +see when you invoke @key{Ada | Project | Edit}. + +There are three ways to change @code{main_unit}: + +@enumerate +@item +Invoke @key{Ada | Set main and Build}, which sets @code{main_unit} to +the current file. + +@item +Invoke @key{Ada | Project | Edit}, edit @code{main_unit} and +@code{main}, and click @key{[save]} + +@item +Invoke @key{Ada | Project | Load}, and load a project file that specifies @code{main_unit} + +@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 @key{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 @key{Ada | Project | Load...}, and +select @file{Example_2/hello.adp}. + +Then, again in buffer @file{hello.adb}, invoke @key{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 @key{Ada | Project | Load...}, and +select @file{Example_3/Other/other.adp}. + +Then, again in @file{hello_3.adb}, invoke @key{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 @key{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, , Set source search path, Compiling Examples +@section Use GNAT project file + +In this example, we show how to use a GNAT 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{Other/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.adp}: + +@example +src_dir=.. +gnatmake_opt=-Phello_4.gpr +@end example + +@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 @key{Ada | Project | Load...}, and +select @file{Example_4/Gnat_Project/hello_4.adp}. + +Then, again in @file{hello_4.adb}, invoke @key{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 Moving Through Ada Code, Identifier completion, Compiling Examples, Top +@chapter Moving Through Ada Code +@c ----------------------------------------------------------------------- + +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@key{M-/} +Emacs inserts: @samp{my_identifier} +If you press @key{M-/} once again, Emacs replaces @samp{my_identifier} with +@samp{my_subprogram}. +Pressing @key{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 (@key{C-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 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 + +@contents +@bye + +@ignore + arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e +@end ignore diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi new file mode 100644 index 00000000000..7b51f3115ac --- /dev/null +++ b/doc/misc/autotype.texi @@ -0,0 +1,676 @@ +\input texinfo +@c This is an annex of the Emacs manual. +@c Copyright (C) 1994, 1995, 2001, 2002, 2003, 2004, +@c 2005, 2006, 2007 Free Software Foundation, Inc. +@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 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.2 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'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@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. + +@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 + +@setchapternewpage odd +@contents +@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 00000000000..93c7123d6a4 --- /dev/null +++ b/doc/misc/calc.texi @@ -0,0 +1,36190 @@ +\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 2.1 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 +@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 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 +This file documents Calc, the GNU Emacs calculator. + +Copyright @copyright{} 1990, 1991, 2001, 2002, 2003, 2004, +2005, 2006, 2007 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.2 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 freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end quotation +@end copying + +@dircategory 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 Version 2.1 +@c [volume] +@sp 5 +@center Dave Gillespie +@center daveg@@synaptics.com +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1990, 1991, 2001, 2002, 2003, 2004, + 2005, 2006, 2007 Free Software Foundation, Inc. +@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 + +@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. + +The manual is divided into three major parts:@: the ``Getting +Started'' chapter you are reading now, the Calc tutorial (chapter 2), +and the Calc reference manual (the remaining chapters and appendices). +@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. + +@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. +@texline Each +@infoline In the printed manual, each +paragraph that is referenced in the Key or Function Index is marked +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. Also, you +can jump directly to the Tutorial by pressing @kbd{h t} or @kbd{C-x * t}, +or to the Summary by pressing @kbd{h s} or @kbd{C-x * s}. 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 +between @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 a letter @kbd{l}, not a 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----- --%%-Emacs: *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. @kbd{C-x * o} is a handy +way to switch out of Calc momentarily to edit your file; 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 2.1------+----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: + +@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 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 + +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 uses any +non-numeric characters rather than blank lines to delimit the +formula it reads. 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 will 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; Robert +J. Chassell, who suggested the Calc Tutorial and exercises; and Juha +Sarlin, who first worked out how to split Calc into quickly-loading +parts. Bob Weiner helped immensely with the Lucid Emacs port. + +@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 @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. (If you +have a printed copy of the manual you can use that instead.) Press +@kbd{C-x * c} to turn Calc on or to switch into the Calc window, and +press @kbd{C-x * i} to start the Info system or to switch into its window. + +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{Warning:} Note that @samp{/} has lower precedence than +@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}. 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 u} to ``unpack'' +this vector into 8 separate stack entries, then @kbd{M-8 *} to +multiply them back together. 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}}. + +@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. + +@pindex calc-version +The @kbd{M-x calc-version} command displays the current version number +of Calc and the name of the person who installed it on your system. +(This information is also present in the @samp{*Calc Trail*} buffer, +and in the output of the @kbd{h h} command.) + +@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 +Calculations can also be entered 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 use the full Emacs cursor motion and editing keys, which 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{+} and @samp{-} [@code{neg}] (as in @samp{-x}) +and 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); + +@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 backquote, @kbd{`} (@code{calc-edit}) command creates a temporary +buffer (@samp{*Calc Edit*}) for editing the top-of-stack value using +regular Emacs commands. 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:: +* 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)}. +Also, if the variable @code{a} has been declared to have type +@code{vector} or @code{matrix} 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): + +@iftex +@begingroup +@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes +@let@calcindexersh=@calcindexernoshow +@end iftex +@ignore +@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 +@iftex +@endgroup +@end iftex +@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, Mathematica 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 Mathematica Language Mode, Maple Language Mode, Eqn 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} 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 +Maple display mode. + +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)} +! 1000 @r{(as in }!@r{n)} +mod 400 ++/- 300 +!! 210 @r{(as in n}!!@r{)} +! 210 @r{(as in n}!@r{)} +^ 200 +* 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{%%} is the Emacs symbol for ``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. + +@xref{Reporting Bugs}, for the address of Calc's author, if you +should wish to contribute your improved versions of +@code{math-tzone-names} and @code{math-daylight-savings-hook} +to the Calc distribution. + +@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-sec} [@code{sec}], 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-sech} +[@code{sech}]. (These commmands 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. Versions of +Calc starting with 2.00 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 of the @expr{M} values 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 row norm, or infinity-norm, of a vector or 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 column norm, or one-norm, of a vector or 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. + +@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. + +@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, 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 any numeric prefix argument. 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. + +As a special feature, if the numerator of the quotient is 1, then +the denominator is expanded at the top level using the distributive +law (i.e., using the @kbd{C-u -1 a x} command). Suppose the +formula on the stack is @samp{1 / (sqrt(a) + 1)}, and you wish +to eliminate the square root in the denominator by multiplying both +sides by @samp{sqrt(a) - 1}. Calc's default simplifications would +change the result @samp{(sqrt(a) - 1) / (sqrt(a) - 1) (sqrt(a) + 1)} +right back to the original form by cancellation; Calc expands the +denominator to @samp{sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1} to prevent +this. (You would now want to use an @kbd{a x} command to expand +the rest of the way, whereupon the denominator would cancel out to +the desired form, @samp{a - 1}.) When the numerator is not 1, this +initial expansion is not necessary because Calc's default +simplifications will not notice the potential cancellation. + +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 +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 +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. + +@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}. (The @kbd{r} prefix is otherwise unused +in the current version of Calc.) + +@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:: +* 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 +@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. 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. Calc's kill +commands always operate on whole stack entries. (They act the same as their +standard Emacs cousins except they ``round up'' the specified region to +encompass full lines.) 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, Grabbing From Buffers, 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 Grabbing From Buffers, Yanking Into Buffers, Yanking Into Stack, 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 2.1------+----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-open-word +@vindex calc-embedded-close-word +The @code{calc-embedded-open-word} and @code{calc-embedded-close-word} +variables are similar expressions used when you type @kbd{C-x * w} +instead of @kbd{C-x * e} 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-open-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-open-word +@defvarx calc-embedded-close-word +@defvarx calc-embedded-open-close-word-alist +See @ref{Customizing Embedded Mode}.@* +The variables @code{calc-embedded-open-word} and +@code{calc-embedded-close-word} control the region that Calc will +activate when Embedded mode is entered with @kbd{C-x * w}. They are +regular expressions. + +The default values of @code{calc-embedded-open-word} and +@code{calc-embedded-close-word} are @code{"^\\|[^-+0-9.eE]"} and +@code{"$\\|[^-+0-9.eE]"} respectively. + +The variable @code{calc-embedded-open-close-word-alist} is used to +set @code{calc-embedded-open-word} and +@code{calc-embedded-close-word} 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-WORD-REGEXP} +@var{CLOSE-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 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 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 2.1 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@: @key{RET} @: @: 1 @:@:... a a} +@r{ ... a@: @key{SPC} @: @: 1 @:@:... a a} +@r{... a b@: @key{TAB} @: @: 3 @:@:... b a} +@r{. a b c@: M-@key{TAB} @: @: 3 @:@:... b c a} +@r{... a b@: @key{LFD} @: @: 1 @:@:... a b a} +@r{ ... a@: @key{DEL} @: @: 1 @:@:...} +@r{... a b@: M-@key{DEL} @: @: 1 @:@:... b} +@r{ @: M-@key{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 @key{SPC} @: @: @:calc-refresh@:} +@r{ @: d @key{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 @key{RET} @: @: 27 @:calc-copy-selection@:} +@r{ @: j @key{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{ @: 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{ 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 00000000000..423892d7d30 --- /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 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.2 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'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@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 $Revision$ of $RCSfile$, which can be +downloaded from +@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/man/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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up + +@ifinfo +@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. +@end ifinfo + +@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 chapter +@ref{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 behaviour 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 behaviour. @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 initialised (@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 neighbouring 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 recognised 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 behaviour +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 +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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@iftex +@page +@summarycontents +@contents +@end iftex + +@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 00000000000..676b9edc5ad --- /dev/null +++ b/doc/misc/cl.texi @@ -0,0 +1,5377 @@ +\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 +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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@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. + +@menu +* Overview:: Installation, usage, etc. +* Program Structure:: Arglists, `eval-when', `defalias' +* Predicates:: `typep', `eql', 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:: `cadr', `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 +eql 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:: `eql' and `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 two Common Lisp predicates, @code{eql} and +@code{equalp}. + +@defun eql a b +This function is almost the same as @code{eq}, except that if @var{a} +and @var{b} are numbers of the same type, it compares them for numeric +equality (as if by @code{equal} instead of @code{eq}). This makes a +difference only for versions of Emacs that are compiled with +floating-point support. Emacs floats are allocated +objects just like cons cells, which means that @code{(eq 3.0 3.0)} +will not necessarily be true---if the two @code{3.0}s were allocated +separately, the pointers will be different even though the numbers are +the same. But @code{(eql 3.0 3.0)} will always be true. + +The types of the arguments must match, so @code{(eql 3 3.0)} is +still false. + +Note that Emacs integers are ``direct'' rather than allocated, which +basically means @code{(eq 3 3)} will always be true. Thus @code{eq} +and @code{eql} behave differently only if floating-point numbers are +involved, and are indistinguishable on Emacs versions that don't +support floats. + +There is a slight inconsistency with Common Lisp in the treatment of +positive and negative zeros. Some machines, notably those with IEEE +standard arithmetic, represent @code{+0} and @code{-0} as distinct +values. Normally this doesn't matter because the standard specifies +that @code{(= 0.0 -0.0)} should always be true, and this is indeed +what Emacs Lisp and Common Lisp do. But the Common Lisp standard +states that @code{(eql 0.0 -0.0)} and @code{(equal 0.0 -0.0)} should +be false on IEEE-like machines; Emacs Lisp does not do this, and in +fact the only known way to distinguish between the two zeros in Emacs +Lisp is to @code{format} them and check for a minus sign. +@end defun + +@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. + +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 or 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 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{:test '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{eql} and @code{equal} predicates do 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. + +The lack of reader macros, incidentally, is the reason behind +Emacs Lisp's unusual backquote syntax. Since backquotes are +implemented as a Lisp package and not built-in to the Emacs +parser, they are forced to use a regular macro named @code{`} +which is used with the standard function/macro call notation. + +@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} +instead of @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 + +@setchapternewpage odd +@contents +@bye + +@ignore + arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8 +@end ignore diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi new file mode 100644 index 00000000000..bf2d5288abc --- /dev/null +++ b/doc/misc/dired-x.texi @@ -0,0 +1,1275 @@ +\input texinfo @comment -*-texinfo-*- + +@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs19 +@c +@c Author: Sebastian Kremer +@c Lawrence R. Dodd +@c [Dodd's address no longer valid.] +@c Version: 2.53 +@c Date: 2001/02/25 14:05:46 +@c Keywords: dired extensions +@c dired-x.el REVISION NUMBER: 2 + +@c State: Released +@c Ident: dired-x.texi,v 2.53 2001/02/25 14:05:46 dodd Released + +@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 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.2 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'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@page + +@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 + +@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-p} 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-p} 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-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/BABYL 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 + +@setchapternewpage odd +@c @summarycontents +@contents + +@bye +@c dired-x.texi ends here. + +@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 00000000000..83e9d6b5579 --- /dev/null +++ b/doc/misc/doclicense.texi @@ -0,0 +1,416 @@ +@c -*-texinfo-*- +@center Version 1.2, November 2002 + +@display +Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display +@sp 1 +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document ``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. + +@sp 1 +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document,'' below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you.'' You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque.'' + + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +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. +@sp 1 +@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. +@sp 1 +@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. +@sp 1 +@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: + +A. 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.@* +B. 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.@* +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher.@* +D. Preserve all the copyright notices of the Document.@* +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices.@* +F. 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.@* +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice.@* +H. Include an unaltered copy of this License.@* +I. 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.@* +J. 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.@* +K. 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.@* +L. 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.@* +M. Delete any section Entitled ``Endorsements.'' Such a section + may not be included in the Modified Version.@* +N. Do not retitle any existing section to be Entitled ``Endorsements'' + or to conflict in title with any Invariant Section.@* +O. Preserve any Warranty Disclaimers.@* +@sp 1 +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. +@sp 1 +@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.'' +@sp 1 +@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. +@sp 1 +@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. +@sp 1 +@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. +@sp 1 +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. +@sp 1 +@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 +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +@end enumerate + +@unnumberedsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group +Copyright (C) @var{year} @var{your name}. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled ``GNU +Free Documentation License.'' +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group +with the Invariant Sections being @var{list their titles}, with the +Front-Cover Texts being @var{list}, and with the Back-Cover Texts being +@var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@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 00000000000..c04f99f954c --- /dev/null +++ b/doc/misc/ebrowse.texi @@ -0,0 +1,1462 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@node Top, Overview, (dir), (dir) + +@ifnottex +You can browse C++ class hierarchies from within Emacs by using +Ebrowse. +@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 + +@contents +@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 00000000000..6bb2605e0c6 --- /dev/null +++ b/doc/misc/ediff.texi @@ -0,0 +1,2546 @@ +\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 (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +2003, 2004, 2005, 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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.1 +@sp 1 +@subtitle April 2007 +@sp 5 +@author Michael Kifer +@page + +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + + +@node Top, Introduction, (dir), (dir) + + +@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 3d 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 VMS, 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), +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 + +@setchapternewpage odd +@contents +@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 00000000000..0f3c141c792 --- /dev/null +++ b/doc/misc/emacs-mime.texi @@ -0,0 +1,1832 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@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 + +@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. + +@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}. + +@end table + +@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}). + +@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ï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ï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ï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-encode-encoded-words +@vindex rfc2047-encode-encoded-words +The boolean variable specifies whether encoded words +(e.g. @samp{=?hello?=}) should be encoded again. + +@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 + +@summarycontents +@contents +@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/erc.texi b/doc/misc/erc.texi new file mode 100644 index 00000000000..3e52bb42c92 --- /dev/null +++ b/doc/misc/erc.texi @@ -0,0 +1,1027 @@ +\input texinfo +@c %**start of header +@setfilename ../info/erc +@settitle ERC Manual +@c %**end of header + +@dircategory Emacs +@direntry +* ERC: (erc). Powerful, modular, and extensible IRC client for Emacs. +@end direntry + +@syncodeindex fn cp + +@copying +This manual is for ERC version 5.2. + +Copyright @copyright{} 2005, 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, Front-Cover texts, or Back-Cover Texts. A copy of +the license is included in the section entitled ``GNU Free +Documentation License'' in the Emacs manual. + +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. + +All Emacs Lisp code contained in this document may be used, distributed, +and modified without restriction. +@end quotation +@end copying + +@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 + +@c So the toc is printed at the start +@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. +* 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.2-extras.tar.gz} +@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-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. + +@subheading GNU Arch + +ERC is developed using GNU Arch. Downloading ERC with Arch and staying +up-to-date involves the following steps. + +@enumerate +@cindex GNU Arch, installing +@item Install arch + +@itemize @bullet +@item Debian: @kbd{apt-get install tla}. +@item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}. +@end itemize + +@cindex GNU Arch, downloading ERC +@item Register the archive. +@example +tla register-archive -f http://arch.sv.gnu.org/archives/erc/erc +@end example + +@item Download the ERC source code. +@example +# Download ERC into the @file{erc} directory. +tla get erc@@sv.gnu.org/erc--main--0 erc +@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. + +@example +# Change to the source directory you are interested in. +cd erc/ + +# Display the summary of changes +tla missing --summary +@end example + +@cindex GNU Arch, updating ERC +@item Update to the latest version by replaying missing changes. +@example +cd erc +tla update +@end example + +@end enumerate + +If you are new to Arch and want to learn more about developing ERC with +it, visit @uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment} for +full instructions. + +@subheading Development snapshots + +@cindex development snapshot +Alternatively, the latest development snapshot may be downloaded in both +``.tar.gz'' and ``.zip'' forms. + +@itemize @bullet +@item @uref{http://www.mwolson.org/static/dist/erc-latest.tar.gz} +@item @uref{http://www.mwolson.org/static/dist/erc-latest.zip} +@end itemize + + +@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 occurences 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_3: 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_3: (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 option 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/EmacsIRCClient} 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, GNU Free Documentation License, 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. + +@end itemize + +@node GNU Free Documentation License, Concept Index, History, 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: cf9cfaff-fc12-4297-ad15-ec2493002b1e +@end ignore diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi new file mode 100644 index 00000000000..3a4b705d2c9 --- /dev/null +++ b/doc/misc/eshell.texi @@ -0,0 +1,948 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Eshell: (eshell). A command shell implemented in Emacs Lisp. +@end direntry + +@setchapternewpage on + +@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 + +This manual documents Eshell, 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. +@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 00000000000..7a8dbbee524 --- /dev/null +++ b/doc/misc/eudc.texi @@ -0,0 +1,985 @@ +\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 +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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@ifnottex +@node Top, Overview, (dir), (dir) +@comment node-name, next, previous, up + + +This manual documents EUDC v1.30b, 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) + +@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 + +@setchapternewpage odd +@contents +@bye + +@ignore + arch-tag: 1b79460b-4ea1-441d-ab45-05ddd16ef241 +@end ignore diff --git a/doc/misc/faq.texi b/doc/misc/faq.texi new file mode 100644 index 00000000000..b7fe5dca4a2 --- /dev/null +++ b/doc/misc/faq.texi @@ -0,0 +1,5590 @@ +\input texinfo @c -*- mode: texinfo; -*- +@c %**start of header +@setfilename ../info/efaq +@settitle GNU Emacs FAQ +@c %**end of header + +@setchapternewpage odd + +@c This is used in many places +@set VER 22.1 + +@c This file is maintained by Romain Francoise . +@c Feel free to install changes without prior permission (but I'd +@c appreciate a notice if you do). + +@copying +Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007 +Free Software Foundation, Inc.@* +Copyright 1994,1995,1996,1997,1998,1999,2000 Reuven M. Lerner@* +Copyright 1992,1993 Steven Byrnes@* +Copyright 1990,1991,1992 Joseph Brian Wells@* + +@quotation +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. + +[This version has been heavily edited since it was included in the Emacs +distribution.] +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Emacs FAQ: (efaq). Frequently Asked Questions about Emacs. +@end direntry + +@c The @titlepage stuff only appears in the printed version +@titlepage +@sp 10 +@center @titlefont{GNU Emacs FAQ} + +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@node Top, FAQ notation, (dir), (dir) + +This is the GNU Emacs FAQ, last updated on @today{}. + +This FAQ is maintained as a part of GNU Emacs. If you find any errors, +or have any suggestions, please use @kbd{M-x report-emacs-bug} to report +them. + +@menu +* FAQ notation:: +* General questions:: +* Getting help:: +* Status of Emacs:: +* Common requests:: +* Bugs and problems:: +* Compiling and installing Emacs:: +* Finding Emacs and related packages:: +* Major packages and programs:: +* Key bindings:: +* Alternate character sets:: +* Mail and news:: +* Concept index:: +@end menu + +@c ------------------------------------------------------------ +@node FAQ notation, General questions, Top, Top +@chapter FAQ notation +@cindex FAQ notation + +This chapter describes notation used in the GNU Emacs FAQ, as well as in +the Emacs documentation. Consult this section if this is the first time +you are reading the FAQ, or if you are confused by notation or terms +used in the FAQ. + +@menu +* Basic keys:: +* Extended commands:: +* On-line manual:: +* File-name conventions:: +* Common acronyms:: +@end menu + +@node Basic keys, Extended commands, FAQ notation, FAQ notation +@section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.? +@cindex Basic keys +@cindex Control key, notation for +@cindex @key{Meta} key, notation for +@cindex Control-Meta characters, notation for +@cindex @kbd{C-h}, definition of +@cindex @kbd{C-M-h}, definition of +@cindex @key{DEL}, definition of +@cindex @key{ESC}, definition of +@cindex @key{LFD}, definition of +@cindex @key{RET}, definition of +@cindex @key{SPC}, definition of +@cindex @key{TAB}, definition of +@cindex Notation for keys + +@itemize @bullet + +@item +@kbd{C-x}: press the @key{x} key while holding down the @key{Control} key + +@item +@kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key +(if your computer doesn't have a @key{Meta} key, @pxref{No Meta key}) + +@item +@kbd{M-C-x}: press the @key{x} key while holding down both @key{Control} +and @key{Meta} + +@item +@kbd{C-M-x}: a synonym for the above + +@item +@key{LFD}: Linefeed or Newline; same as @kbd{C-j} + +@item +@key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m} + +@item +@key{DEL}: @key{Delete}, usually @strong{not} the same as +@key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if +deleting invokes Emacs help) + +@item +@key{ESC}: Escape; same as @kbd{C-[} + +@item +@key{TAB}: Tab; same as @kbd{C-i} + +@item +@key{SPC}: Space bar + +@end itemize + +Key sequences longer than one key (and some single-key sequences) are +written inside quotes or on lines by themselves, like this: + +@display + @kbd{M-x frobnicate-while-foo RET} +@end display + +@noindent +Any real spaces in such a key sequence should be ignored; only @key{SPC} +really means press the space key. + +The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value +that would be sent by pressing just @key{x} minus 96 (or 64 for +upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux +terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the +@acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially, +@key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit +7@footnote{ +DOS and Windows terminals don't set bit 7 when the @key{Meta} key is +pressed.}. + +@kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call +@kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON. +Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127. + +@inforef{Text Characters, Text Characters, emacs}, and @inforef{Keys, +Keys, emacs}, for more information. (@xref{On-line manual}, for more +information about Info.) + +@node Extended commands, On-line manual, Basic keys, FAQ notation +@section What does @file{M-x @var{command}} mean? +@cindex Extended commands +@cindex Commands, extended +@cindex M-x, meaning of + +@kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the +command, then type @key{RET}. (@xref{Basic keys}, if you're not sure +what @kbd{M-x} and @key{RET} mean.) + +@kbd{M-x} (by default) invokes the command +@code{execute-extended-command}. This command allows you to run any +Emacs command if you can remember the command's name. If you can't +remember the command's name, you can type @key{TAB} and @key{SPC} for +completion, @key{?} for a list of possibilities, and @kbd{M-p} and +@kbd{M-n} (or up-arrow and down-arrow on terminals that have these +editing keys) to see previous commands entered. An Emacs @dfn{command} +is an @dfn{interactive} Emacs function. + +@cindex @key{Do} key +Your system administrator may have bound other key sequences to invoke +@code{execute-extended-command}. A function key labeled @kbd{Do} is a +good candidate for this, on keyboards that have such a key. + +If you need to run non-interactive Emacs functions, see @ref{Evaluating +Emacs Lisp code}. + +@node On-line manual, File-name conventions, Extended commands, FAQ notation +@section How do I read topic XXX in the on-line manual? +@cindex On-line manual, reading topics in +@cindex Reading topics in the on-line manual +@cindex Finding topics in the on-line manual +@cindex Info, finding topics in + +When we refer you to some @var{topic} in the on-line manual, you can +read this manual node inside Emacs (assuming nothing is broken) by +typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}. + +This invokes Info, the GNU hypertext documentation browser. If you don't +already know how to use Info, type @key{?} from within Info. + +If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs +@key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}. + +If these commands don't work as expected, your system administrator may +not have installed the Info files, or may have installed them +improperly. In this case you should complain. + +@xref{Getting a printed manual}, if you would like a paper copy of the +Emacs manual. + +@node File-name conventions, Common acronyms, On-line manual, FAQ notation +@section What are @file{etc/SERVICE}, @file{src/config.h}, and @file{lisp/default.el}? +@cindex File-name conventions +@cindex Conventions for file names +@cindex Directories and files that come with Emacs + +These are files that come with Emacs. The Emacs distribution is divided +into subdirectories; the important ones are @file{etc}, @file{lisp}, and +@file{src}. + +If you use Emacs, but don't know where it is kept on your system, start +Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory +name displayed by this will be the full pathname of the installed +@file{etc} directory. (This full path is recorded in the Emacs variable +@code{data-directory}, and @kbd{C-h v} displays the value and the +documentation of a variable.) + +The location of your Info directory (i.e., where on-line documentation +is stored) is kept in the variable @code{Info-default-directory-list}. Use +@kbd{C-h v Info-default-directory-list @key{RET}} to see the value of +this variable, which will be a list of directory names. The last +directory in that list is probably where most Info files are stored. By +default, Info documentation is placed in @file{/usr/local/info}. + +Some of these files are available individually via FTP or e-mail; see +@ref{Informational files for Emacs}. They all are available in the +source distribution. Many of the files in the @file{etc} directory are +also available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?} +(@kbd{M-x help-for-help}). + +Your system administrator may have removed the @file{src} directory and +many files from the @file{etc} directory. + +@node Common acronyms, , File-name conventions, FAQ notation +@section What are FSF, LPF, OSF, GNU, RMS, FTP, and GPL? +@cindex FSF, definition of +@cindex LPF, definition of +@cindex OSF, definition of +@cindex GNU, definition of +@cindex RMS, definition of +@cindex Stallman, Richard, acronym for +@cindex Richard Stallman, acronym for +@cindex FTP, definition of +@cindex GPL, definition of +@cindex Acronyms, definitions for +@cindex Common acronyms, definitions for + +@table @asis + +@item FSF +Free Software Foundation + +@item LPF +League for Programming Freedom + +@item OSF +Open Software Foundation + +@item GNU +GNU's Not Unix + +@item RMS +Richard Matthew Stallman + +@item FTP +File Transfer Protocol + +@item GPL +GNU General Public License + +@end table + +Avoid confusing the FSF, the LPF, and the OSF. The LPF opposes +look-and-feel copyrights and software patents. The FSF aims to make +high quality free software available for everyone. The OSF is a +consortium of computer vendors which develops commercial software for +Unix systems. + +The word ``free'' in the title of the Free Software Foundation refers to +``freedom,'' not ``zero cost.'' Anyone can charge any price for +GPL-covered software that they want to. However, in practice, the +freedom enforced by the GPL leads to low prices, because you can always +get the software for less money from someone else, since everyone has +the right to resell or give away GPL-covered software. + +@c ------------------------------------------------------------ +@node General questions, Getting help, FAQ notation, Top +@chapter General questions +@cindex General questions + +This chapter contains general questions having to do with Emacs, the +Free Software Foundation, and related organizations. + +@menu +* The LPF:: +* Real meaning of copyleft:: +* Guidelines for newsgroup postings:: +* Newsgroup archives:: +* Reporting bugs:: +* Unsubscribing from Emacs lists:: +* Contacting the FSF:: +@end menu + +@node The LPF, Real meaning of copyleft, General questions, General questions +@section What is the LPF? +@cindex LPF, description of +@cindex League for Programming Freedom +@cindex Software patents, opposition to +@cindex Patents for software, opposition to + +The LPF opposes the expanding danger of software patents and +look-and-feel copyrights. To get more information, feel free to contact +the LPF via e-mail or otherwise. You may also contact +@email{jbw@@cs.bu.edu, Joe Wells}; he will be happy to talk to you +about the LPF. + +You can find more information about the LPF in the file @file{etc/LPF}. +More papers describing the LPF's views are available on the Internet and +also from @uref{http://lpf.ai.mit.edu/, the LPF home page}. + +@node Real meaning of copyleft, Guidelines for newsgroup postings, The LPF, General questions +@section What is the real legal meaning of the GNU copyleft? +@cindex Copyleft, real meaning of +@cindex GPL, real meaning of +@cindex General Public License, real meaning of +@cindex Discussion of the GPL + +The real legal meaning of the GNU General Public License (copyleft) will +only be known if and when a judge rules on its validity and scope. +There has never been a copyright infringement case involving the GPL to +set any precedents. Please take any discussion regarding this issue to +the newsgroup @uref{news:gnu.misc.discuss}, which was created to hold the +extensive flame wars on the subject. + +RMS writes: + +@quotation +The legal meaning of the GNU copyleft is less important than the spirit, +which is that Emacs is a free software project and that work pertaining +to Emacs should also be free software. ``Free'' means that all users +have the freedom to study, share, change and improve Emacs. To make +sure everyone has this freedom, pass along source code when you +distribute any version of Emacs or a related program, and give the +recipients the same freedom that you enjoyed. +@end quotation + +@node Guidelines for newsgroup postings, Newsgroup archives, Real meaning of copyleft, General questions +@section What are appropriate messages for @uref{news:gnu.emacs.help}, @uref{news:gnu.emacs.bug}, @uref{news:comp.emacs}, etc.? +@cindex Newsgroups, appropriate messages for +@cindex GNU newsgroups, appropriate messages for +@cindex Usenet groups, appropriate messages for +@cindex Mailing lists, appropriate messages for +@cindex Posting messages to newsgroups + +@cindex GNU mailing lists +The file @file{etc/MAILINGLISTS} describes the purpose of each GNU +mailing list. (@xref{Informational files for Emacs}, if you want a copy +of the file.) For those lists which are gatewayed with newsgroups, it +lists both the newsgroup name and the mailing list address. + +The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs +in general. This includes Emacs along with various other +implementations, such as XEmacs, JOVE, MicroEmacs, Freemacs, MG, +Unipress, CCA, and Epsilon. + +Many people post Emacs questions to @uref{news:comp.emacs} because they +don't receive any of the @code{gnu.*} newsgroups. Arguments have been +made both for and against posting GNU-Emacs-specific material to +@uref{news:comp.emacs}. You have to decide for yourself. + +Messages advocating ``non-free'' software are considered unacceptable on +any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss}, +which was created to hold the extensive flame-wars on the subject. +``Non-free'' software includes any software for which the end user can't +freely modify the source code and exchange enhancements. Be careful to +remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when +posting a followup that recommends such software. + +@uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid +posting bug reports to this newsgroup directly (@pxref{Reporting bugs}). + +@node Newsgroup archives, Reporting bugs, Guidelines for newsgroup postings, General questions +@section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups? +@cindex Archived postings from @code{gnu.emacs.help} +@cindex Usenet archives for GNU groups +@cindex Old Usenet postings for GNU groups + +The FSF has maintained archives of all of the GNU mailing lists for many +years, although there may be some unintentional gaps in coverage. The +archive is not particularly well organized or easy to retrieve +individual postings from, but pretty much everything is there. + +The archive is at @uref{ftp://lists.gnu.org/}. + +The archive can be browsed over the web at +@uref{http://lists.gnu.org/archive/html/, the GNU mail archive}. + +Web-based Usenet search services, such as +@uref{http://groups.google.com/groups/dir?sel=33592484, Google}, also +archive the @code{gnu.*} groups. + +You can read the archives of the @code{gnu.*} groups and post new +messages at @uref{http://gmane.org/, Gmane}. + +@node Reporting bugs, Unsubscribing from Emacs lists, Newsgroup archives, General questions +@section Where should I report bugs and other problems with Emacs? +@cindex Bug reporting +@cindex Good bug reports +@cindex How to submit a bug report +@cindex Reporting bugs + +The correct way to report Emacs bugs is to use the command +@kbd{M-x report-emacs-bug}. It sets up a mail buffer with the +essential information and the correct e-mail address which is +@email{bug-gnu-emacs@@gnu.org} for the released versions of Emacs. +Anything sent to @email{bug-gnu-emacs@@gnu.org} also appears in the +newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of +news to submit the bug report. This ensures a reliable return address +so you can be contacted for further details. + +Be sure to read the ``Bugs'' section of the Emacs manual before reporting +a bug! The manual describes in detail how to submit a useful bug +report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}). +(@xref{On-line manual}, if you don't know how to read the manual.) + +RMS says: + +@quotation +Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the +effect of posting on @uref{news:gnu.emacs.help}) is undesirable because +it takes the time of an unnecessarily large group of people, most of +whom are just users and have no idea how to fix these problem. +@email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people +who are more likely to know what to do and have expressed a wish to +receive more messages about Emacs than the others. +@end quotation + +RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}: + +@quotation +If you have reported a bug and you don't hear about a possible fix, +then after a suitable delay (such as a week) it is okay to post on +@code{gnu.emacs.help} asking if anyone can help you. +@end quotation + +If you are unsure whether you have found a bug, consider the following +non-exhaustive list, courtesy of RMS: + +@quotation +If Emacs crashes, that is a bug. If Emacs gets compilation errors +while building, that is a bug. If Emacs crashes while building, that +is a bug. If Lisp code does not do what the documentation says it +does, that is a bug. +@end quotation + +@node Unsubscribing from Emacs lists, Contacting the FSF, Reporting bugs, General questions +@section How do I unsubscribe from this mailing list? +@cindex Unsubscribing from GNU mailing lists +@cindex Removing yourself from GNU mailing lists + +If you are receiving a GNU mailing list named @var{list}, you might be +able to unsubscribe from it by sending a request to the address +@email{@var{list}-request@@gnu.org}. However, this will not work if you are +not listed on the main mailing list, but instead receive the mail from a +distribution point. In that case, you will have to track down at which +distribution point you are listed. Inspecting the @samp{Received} headers +on the mail messages may help, along with liberal use of the @samp{EXPN} or +@samp{VRFY} sendmail commands through @samp{telnet @var{site-address} +smtp}. Ask your postmaster for help, if you cannot figure out these +details. + +@node Contacting the FSF, , Unsubscribing from Emacs lists, General questions +@section What is the current address of the FSF? +@cindex Snail mail address of the FSF +@cindex Postal address of the FSF +@cindex Contracting the FSF +@cindex Free Software Foundation, contacting + +@table @asis + +@item E-mail +gnu@@gnu.org + +@item Telephone ++1-617-542-5942 + +@item Fax ++1-617-542-2652 + +@item World Wide Web +@uref{http://www.gnu.org/} + +@item Postal address +Free Software Foundation@* +51 Franklin Street, Fifth Floor@* +Boston, MA 02110-1301@* +USA@* + +@end table + +@cindex Ordering GNU software +For details on how to order items directly from the FSF, see the +@uref{http://www.gnu.org/order/order.html, GNU Web site}. + +@c ------------------------------------------------------------ +@node Getting help, Status of Emacs, General questions, Top +@chapter Getting help +@cindex Getting help + +This chapter tells you how to get help with Emacs + +@menu +* Basic editing:: +* Learning how to do something:: +* Getting a printed manual:: +* Emacs Lisp documentation:: +* Installing Texinfo documentation:: +* Printing a Texinfo file:: +* Viewing Info files outside of Emacs:: +* Informational files for Emacs:: +* Help installing Emacs:: +* Obtaining the FAQ:: +@end menu + +@node Basic editing, Learning how to do something, Getting help, Getting help +@section I'm just starting Emacs; how do I do basic editing? +@cindex Basic editing with Emacs +@cindex Beginning editing +@cindex Tutorial, invoking the +@cindex Self-paced tutorial, invoking the +@cindex Help system, entering the + +Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing +@kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial +is available in many foreign languages such as French, German, Japanese, +Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}} +to choose your language and start the tutorial. + +Your system administrator may have changed @kbd{C-h} to act like +@key{DEL} to deal with local keyboards. You can use @kbd{M-x +help-for-help} instead to invoke help. To discover what key (if any) +invokes help on your system, type @kbd{M-x where-is @key{RET} +help-for-help @key{RET}}. This will print a comma-separated list of key +sequences in the echo area. Ignore the last character in each key +sequence listed. Each of the resulting key sequences invokes help. + +Emacs help works best if it is invoked by a single key whose value +should be stored in the variable @code{help-char}. + +@node Learning how to do something, Getting a printed manual, Basic editing, Getting help +@section How do I find out how to do something in Emacs? +@cindex Help for Emacs +@cindex Learning to do something in Emacs +@cindex Reference card for Emacs +@cindex Overview of help systems + +There are several methods for finding out how to do things in Emacs. + +@itemize @bullet + +@cindex Reading the Emacs manual +@item +The complete text of the Emacs manual is available on-line via the Info +hypertext reader. Type @kbd{C-h r} to display the manual in Info mode. +Typing @key{h} immediately after entering Info will provide a short +tutorial on how to use it. + +@cindex Lookup a subject in a manual +@cindex Index search in a manual +@item +To quickly locate the section of the manual which discusses a certain +issue, or describes a command or a variable, type @kbd{C-h i m emacs +@key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the +topic, the command, or the variable which you are looking for. If this +does not land you on the right place in the manual, press @kbd{,} +(comma) repeatedly until you find what you need. (The @kbd{i} and +@kbd{,} keys invoke the index-searching functions, which look for the +@var{topic} you type in all the indices of the Emacs manual.) + +@cindex Apropos +@item +You can list all of the commands whose names contain a certain word +(actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x +command-apropos}). + +@cindex Command description in the manual +@item +The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts +for the name of a command, and then attempts to find the section in the +Emacs manual where that command is described. + +@cindex Finding commands and variables +@item +You can list all of the functions and variables whose names contain a +certain word using @kbd{M-x apropos}. + +@item +You can list all of the functions and variables whose documentation +matches a regular expression or a string, using @kbd{M-x +apropos-documentation}. + +@item +You can order a hardcopy of the manual from the FSF. @xref{Getting a +printed manual}. + +@cindex Reference cards, in other languages +@item +You can get a printed reference card listing commands and keys to +invoke them. You can order one from the FSF for $1 (or 10 for $5), +or you can print your own from the @file{etc/refcards/refcard.tex} or +@file{etc/refcards/refcard.ps} files in the Emacs distribution. +Beginning with version 21.1, the Emacs distribution comes with +translations of the reference card into several languages; look for +files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang} +is a two-letter code of the language. For example, the German version +of the reference card is in the files @file{etc/refcards/de-refcard.tex} +and @file{etc/recards/de-refcard.ps}. + +@item +There are many other commands in Emacs for getting help and +information. To get a list of these commands, type @samp{?} after +@kbd{C-h}. + +@end itemize + +@node Getting a printed manual, Emacs Lisp documentation, Learning how to do something, Getting help +@section How do I get a printed copy of the Emacs manual? +@cindex Printed Emacs manual, obtaining +@cindex Manual, obtaining a printed or HTML copy of +@cindex Emacs manual, obtaining a printed or HTML copy of + +You can order a printed copy of the Emacs manual from the FSF. For +details see the @uref{http://www.gnu.org/order/order.html, GNU Web site}. + +@c The number 620 below is version-dependent! +The full Texinfo source for the manual also comes in the @file{man} +directory of the Emacs distribution, if you're daring enough to try to +print out this 620-page manual yourself (@pxref{Printing a Texinfo +file}). + +If you absolutely have to print your own copy, and you don't have @TeX{}, +you can get a PostScript version from + +@uref{http://www.gnu.org/software/emacs/manual/emacs.ps.gz} + +@cindex HTML version of Emacs manual, obtaining +An HTML version of the manual is at + +@uref{http://www.gnu.org/software/emacs/manual/emacs.html} + +The manual is available in other formats at + +@uref{http://www.gnu.org/software/emacs/manual/} + +@xref{Learning how to do something}, for how to view the manual on-line. + +@node Emacs Lisp documentation, Installing Texinfo documentation, Getting a printed manual, Getting help +@section Where can I get documentation on Emacs Lisp? +@cindex Documentation on Emacs Lisp +@cindex Function documentation +@cindex Variable documentation +@cindex Emacs Lisp Reference Manual +@cindex Reference manual for Emacs Lisp + +Within Emacs, you can type @kbd{C-h f} to get the documentation for a +function, @kbd{C-h v} for a variable. + +For more information, the Emacs Lisp Reference Manual is available +on-line, in Info format. @xref{Top, Emacs Lisp,, elisp, The +Emacs Lisp Reference Manual}. + +You can also order a hardcopy of the manual, details on ordering it from +FSF are on the @uref{http://www.gnu.org/order/order.html, GNU Web site}. + +An HTML version of the Emacs Lisp Reference Manual is available at + +@uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html} + +@node Installing Texinfo documentation, Printing a Texinfo file, Emacs Lisp documentation, Getting help +@section How do I install a piece of Texinfo documentation? +@cindex Texinfo documentation, installing +@cindex Installing Texinfo documentation +@cindex New Texinfo files, installing +@cindex Documentation, installing new Texinfo files +@cindex Info files, how to install + +First, you must turn the Texinfo files into Info files. You may do this +using the stand-alone @file{makeinfo} program, available as part of the latest +Texinfo package at + +@uref{ftp://ftp.gnu.org/pub/gnu/texinfo/texinfo-4.8.tar.gz} + +and all mirrors of @samp{ftp.gnu.org} (for a list, @pxref{Current GNU +distributions}). + +For information about the Texinfo format, read the Texinfo manual which +comes with the Texinfo package. This manual also comes installed in +Info format, so you can read it on-line; type @kbd{C-h i m texinfo +@key{RET}}. + +Alternatively, you could use the Emacs command @kbd{M-x +texinfo-format-buffer}, after visiting the Texinfo source file of the +manual you want to convert. + +Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the +resulting Info files in Emacs's Info tree. To install Info files, +perform these steps: + +@enumerate +@item +Move the files to the @file{info} directory in the installed Emacs +distribution. @xref{File-name conventions}, if you don't know where that +is. + +@item +Run the @code{install-info} command, which is part of the Texinfo +distribution, to update the main Info directory menu, like this: + +@example + install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file} +@end example + +@noindent +where @var{dir-path} is the full path to the directory where you copied +the produced Info file(s), and @var{file} is the name of the Info file +you produced and want to install. + +If you don't have the @code{install-info} command installed, you can +edit the file @file{info/dir} in the installed Emacs distribution, and +add a line for the top level node in the Info package that you are +installing. Follow the examples already in this file. The format is: + +@example +* Topic: (relative-pathname). Short description of topic. +@end example + +@end enumerate + +If you want to install Info files and you don't have the necessary +privileges, you have several options: + +@itemize @bullet +@item +Info files don't actually need to be installed before being used. +You can use a prefix argument for the @code{info} command and specify +the name of the Info file in the minibuffer. This goes to the node +named @samp{Top} in that file. For example, to view a Info file named +@file{@var{info-file}} in your home directory, you can type this: + +@example +@kbd{C-u C-h i ~/@var{info-file} @key{RET}} +@end example + +Alternatively, you can feed a file name to the @code{Info-goto-node} +command (invoked by pressing @key{g} in Info mode) by typing the name +of the file in parentheses, like this: + +@example +@kbd{C-h i g (~/@var{info-file}) @key{RET}} +@end example + +@item +You can create your own Info directory. You can tell Emacs where that +Info directory is by adding its pathname to the value of the variable +@code{Info-default-directory-list}. For example, to use a private Info +directory which is a subdirectory of your home directory named @file{Info}, +you could put this in your @file{.emacs} file: + +@lisp +(setq Info-default-directory-list + (cons "~/Info" Info-default-directory-list)) +@end lisp + +You will need a top-level Info file named @file{dir} in this directory +which has everything the system @file{dir} file has in it, except it should +list only entries for Info files in that directory. You might not need +it if all files in this directory were referenced by other @file{dir} +files. The node lists from all @file{dir} files in +@code{Info-default-directory-list} are merged by the Info system. + +@end itemize + +@node Printing a Texinfo file, Viewing Info files outside of Emacs, Installing Texinfo documentation, Getting help +@section How do I print a Texinfo file? +@cindex Printing a Texinfo file +@cindex Texinfo file, printing +@cindex Printing documentation + +You can't get nicely printed output from Info files; you must still have +the original Texinfo source file for the manual you want to print. + +Assuming you have @TeX{} installed on your system, follow these steps: + +@enumerate + +@item +Make sure the first line of the Texinfo file looks like this: + +@example +\input texinfo +@end example + +You may need to change @samp{texinfo} to the full pathname of the +@file{texinfo.tex} file, which comes with Emacs as +@file{man/texinfo.tex} (or copy or link it into the current directory). + +@item +Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is +the name of the Texinfo source file for which you want to produce a +printed copy. + +The @samp{texi2dvi} script is part of the GNU Texinfo distribution +(@pxref{Installing Texinfo documentation}). + +@item +Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for +printing DVI files at your site. For example, if you have a PostScript +printer, run the @code{dvips} program to print the DVI file on that +printer. + +@end enumerate + +To get more general instructions, retrieve the latest Texinfo package +(@pxref{Installing Texinfo documentation}). + +@node Viewing Info files outside of Emacs, Informational files for Emacs, Printing a Texinfo file, Getting help +@section Can I view Info files without using Emacs? +@cindex Viewing Info files +@cindex Info file viewers +@cindex Alternative Info file viewers + +Yes. Here are some alternative programs: + +@itemize @bullet + +@item +@code{info}, a stand-alone version of the Info program, comes as part of +the Texinfo package. @xref{Installing Texinfo documentation}, for +details. + +@item +Xinfo, a stand-alone version of the Info program that runs under X +Window system. You can get it at +@uref{ftp://ftp.gnu.org/pub/gnu/xinfo/xinfo-1.01.01.tar.gz} and all +mirrors of @samp{ftp.gnu.org} (see @ref{Current GNU distributions}, for a +list of mirrors). + +@item +Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk. +You can get Tkinfo at +@uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}. + +@end itemize + +@node Informational files for Emacs, Help installing Emacs, Viewing Info files outside of Emacs, Getting help +@section What informational files are available for Emacs? +@cindex Informational files included with Emacs +@cindex Files included with Emacs +@cindex @file{COPYING}, description of file +@cindex @file{DISTRIB}, description of file +@cindex @file{FTP}, description of file +@cindex @file{GNU}, description of file +@cindex @file{INTERVIEW}, description of file +@cindex @file{LPF}, description of file +@cindex @file{MACHINES}, description of file +@cindex @file{MAILINGLISTS}, description of file +@cindex @file{NEWS}, description of file +@cindex @file{SERVICE}, description of file +@cindex @file{SUN-SUPPORT}, description of file + +This isn't a frequently asked question, but it should be! A variety of +informational files about Emacs and relevant aspects of the GNU project +are available for you to read. + +The following files are available in the @file{etc} directory of the +Emacs distribution (see @ref{File-name conventions}, if you're not sure +where that is). + +@table @file + +@item COPYING +GNU General Public License + +@item DISTRIB +Emacs Availability Information, including the popular Free Software +Foundation Order Form + +@item FTP +How to get GNU Software by Internet FTP or by UUCP + +@item GNU +The GNU Manifesto + +@item INTERVIEW +Richard Stallman discusses his public-domain UNIX-compatible software +system with BYTE editors + +@item LPF +Why you should join the League for Programming Freedom + +@item MACHINES +Status of Emacs on Various Machines and Systems + +@item MAILINGLISTS +GNU Project Electronic Mailing Lists + +@item NEWS +Emacs news, a history of recent user-visible changes + +@item SERVICE +GNU Service Directory + +@item SUN-SUPPORT +including ``Using Emacstool with GNU Emacs'' + +@end table + +More GNU information, including back issues of the @cite{GNU's +Bulletin}, are at + +@uref{http://www.gnu.org/bulletins/bulletins.html} and + +@uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html} + +@node Help installing Emacs, Obtaining the FAQ, Informational files for Emacs, Getting help +@section Where can I get help in installing Emacs? +@cindex Installation help +@cindex Help installing Emacs + +@xref{Installing Emacs}, for some basic installation hints, and see +@ref{Problems building Emacs}, or @ref{Linking with -lX11 fails}, if you +have problems with the installation. + +The file @file{etc/SERVICE} (see @ref{File-name conventions}, if you're +not sure where that is) lists companies and individuals willing to sell +you help in installing or using Emacs. An up-to-date version this file +is available on @samp{ftp.gnu.org} (@pxref{Informational files for +Emacs}). + +@node Obtaining the FAQ, , Help installing Emacs, Getting help +@section Where can I get the latest version of this FAQ? +@cindex FAQ, obtaining the +@cindex Latest FAQ version, obtaining the +@cindex Retrieving the latest FAQ version +@cindex E-mail, retrieving the FAQ via +@cindex Web, reading the FAQ on the + +The Emacs FAQ is available in several ways: + +@itemize @bullet + +@item +Inside of Emacs itself. You can get it from selecting the @samp{Emacs +FAQ} option from the @samp{Help} menu of the Emacs menu bar at the top +of any Emacs frame, or by typing @kbd{C-h C-f} (@kbd{M-x view-emacs-FAQ}). + +@item +Via USENET. If you can read news, the FAQ should be available in your +news spool, in both the @uref{news:gnu.emacs.help} and +@uref{news:comp.emacs} newsgroups. Every news reader should allow you +to read any news article that is still in the news spool, even if you +have read the article before. You may need to read the instructions for +your news reader to discover how to do this. In @file{rn}, this command +will do this for you at the article selection level: + +@example +?GNU Emacs Frequently Asked Questions?rc:m +@end example + +In Gnus, you should type @kbd{C-u C-x C-s} from the @file{*Summary*} +buffer or @kbd{C-u @key{SPC}} from the @file{*Newsgroup*} buffer to view +all articles in a newsgroup. + +If the FAQ articles have expired and have been deleted from your news +spool, it might (or might not) do some good to complain to your news +administrator, because the most recent FAQ should not expire for a +while. + +@item +In the Emacs distribution. Since Emacs 18.56, the FAQ at the time +of release has been part of the Emacs distribution as either +@file{etc/FAQ} or @file{man/faq.texi} (@pxref{File-name conventions}). + +@item +Via anonymous ftp and e-mail from @file{rtfm.mit.edu} (and its mirror in +Europe), the main repository for FAQs and other items posted to +news.answers. The Emacs FAQs are available at + +@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/} and + +@uref{ftp://ftp.uni-paderborn.de/pub/doc/FAQ/comp/emacs/} + +If you do not have access to anonymous FTP, you can access the archives +using the @file{rtfm.mit.edu} mail server. The Emacs FAQ can be +retrieved by sending mail to @email{mail-server@@rtfm.mit.edu} with a +blank subject and containing + +@example +send usenet/news.answers/GNU-Emacs-FAQ/diffs +send usenet/news.answers/GNU-Emacs-FAQ/part1 +send usenet/news.answers/GNU-Emacs-FAQ/part2 +send usenet/news.answers/GNU-Emacs-FAQ/part3 +send usenet/news.answers/GNU-Emacs-FAQ/part4 +send usenet/news.answers/GNU-Emacs-FAQ/part5 +@end example + +For more information, send email to @email{mail-server@@rtfm.mit.edu} +with @samp{help} and @samp{index} in the body on separate lines. +@end itemize + +@c ------------------------------------------------------------ +@node Status of Emacs, Common requests, Getting help, Top +@chapter Status of Emacs +@cindex Status of Emacs + +This chapter gives you basic information about Emacs, including its +latest version status. + +@menu +* Origin of the term Emacs:: +* Latest version of Emacs:: +* New in Emacs 20:: +* New in Emacs 21:: +* New in Emacs 22:: +@end menu + +@node Origin of the term Emacs, Latest version of Emacs, Status of Emacs, Status of Emacs +@section Where does the name ``Emacs'' come from? +@cindex Origin of the term ``Emacs'' +@cindex Emacs name origin +@cindex TECO +@cindex Original version of Emacs + +Emacs originally was an acronym for Editor MACroS. RMS says he ``picked +the name Emacs because @key{E} was not in use as an abbreviation on ITS at +the time.'' The first Emacs was a set of macros written in 1976 at MIT +by RMS for the editor TECO (Text Editor and COrrector, originally Tape +Editor and COrrector) under ITS on a PDP-10. RMS had already extended +TECO with a ``real-time'' full-screen mode with reprogrammable keys. +Emacs was started by @email{gls@@east.sun.com, Guy Steele} as a project +to unify the many divergent TECO command sets and key bindings at MIT, +and completed by RMS. + +Many people have said that TECO code looks a lot like line noise; you +can read more at @uref{news:alt.lang.teco}. Someone has written a TECO +implementation in Emacs Lisp (to find it, see @ref{Packages that do not +come with Emacs}); it would be an interesting project to run the +original TECO Emacs inside of Emacs. + +@cindex Why Emacs? +For some not-so-serious alternative reasons for Emacs to have that +name, check out the file @file{etc/JOKES} (@pxref{File-name +conventions}). + +@node Latest version of Emacs, New in Emacs 20, Origin of the term Emacs, Status of Emacs +@section What is the latest version of Emacs? +@cindex Version, latest +@cindex Latest version of Emacs + +Emacs @value{VER} is the current version as of this writing. + +@node New in Emacs 20, New in Emacs 21, Latest version of Emacs, Status of Emacs +@section What is different about Emacs 20? +@cindex Differences between Emacs 19 and Emacs 20 +@cindex Emacs 20, new features in + +To find out what has changed in recent versions, type @kbd{C-h C-n} +(@kbd{M-x view-emacs-news}). The oldest changes are at the bottom of +the file, so you might want to read it starting there, rather than at +the top. + +The differences between Emacs versions 18 and 19 was rather dramatic; +the introduction of frames, faces, and colors on windowing systems was +obvious to even the most casual user. + +There are differences between Emacs versions 19 and 20 as well, but many +are more subtle or harder to find. Among the changes are the inclusion +of MULE code for languages that use non-Latin characters and for mixing +several languages in the same document; the ``Customize'' facility for +modifying variables without having to use Lisp; and automatic conversion +of files from Macintosh, Microsoft, and Unix platforms. + +A number of older Lisp packages, such as Gnus, Supercite and the +calendar/diary, have been updated and enhanced to work with Emacs 20, +and are now included with the standard distribution. + + +@node New in Emacs 21, New in Emacs 22, New in Emacs 20, Status of Emacs +@section What is different about Emacs 21? +@cindex Differences between Emacs 20 and Emacs 21 +@cindex Emacs 21, new features in +@cindex Recently introduced features + +@cindex Variable-size fonts +@cindex Toolbar support +Emacs 21 features a thorough rewrite of the display engine. The new +display engine supports variable-size fonts, images, and can play sounds +on platforms which support that. As a result, the visual appearance of +Emacs, when it runs on a windowed display, is much more reminiscent of +modern GUI programs, and includes 3D widgets (used for the mode line and +the scroll bars), a configurable and extensible toolbar, tooltips +(a.k.a.@: balloon help), and other niceties. + +@cindex Colors on text-only terminals +@cindex TTY colors +In addition, Emacs 21 supports faces on text-only terminals. This means +that you can now have colors when you run Emacs on a GNU/Linux console +and on @code{xterm} with @kbd{emacs -nw}. + +@node New in Emacs 22, , New in Emacs 21, Status of Emacs +@section What is different about Emacs 22? +@cindex Differences between Emacs 21 and Emacs 22 +@cindex Emacs 22, new features in +@cindex Recently introduced features +@cindex Default features + +@itemize +@cindex GTK+ Toolkit +@cindex Drag-and-drop +@item +Emacs can be built with GTK+ widgets, and supports drag-and-drop +operation on X. + +@cindex Supported systems +@item +Emacs 22 features support for GNU/Linux systems on S390 and x86-64 +machines, as well as support for the Mac OS X and Cygwin operating +systems. + +@item +The native MS-Windows, Mac OS 9 and Mac OS X builds include full support +for images, toolbar, and tooltips. + +@item +Font Lock mode, Auto Compression mode, and File Name Shadow Mode are +enabled by default. + +@item +The maximum size of buffers has been doubled and is 256M on 32-bit +machines. + +@item +Links can be followed with @kbd{mouse-1}, in addition to @kbd{mouse-2}. + +@cindex Mouse wheel +@item +Mouse wheel support is enabled by default. + +@item +Window fringes are customizable. + +@item +The mode line of the selected window is now highlighted. + +@item +The minibuffer prompt is displayed in a distinct face. + +@item +Abbrev definitions are read automatically at startup. + +@item +Grep mode is separate from Compilation mode and has many new options and +commands specific to grep. + +@item +The original Emacs macro system has been replaced by the new Kmacro +package, which provides many new commands and features and a simple +interface that uses the function keys F3 and F4. Macros are stored in a +macro ring, and can be debugged and edited interactively. + +@item +The Grand Unified Debugger (GUD) can be used with a full graphical user +interface to GDB; this provides many features found in traditional +development environments, making it easy to manipulate breakpoints, add +watch points, display the call stack, etc. Breakpoints are visually +indicated in the source buffer. + +@item +@cindex New modes +Many new modes and packages have been included in Emacs, such as Calc, +TRAMP, URL, IDO, CUA, ERC, rcirc, Table, Image-Dired, SES, Ruler, Org, +PGG, Flymake, Password, Printing, Reveal, wdired, t-mouse, longlines, +savehist, Conf mode, Python mode, DNS mode, etc. + +@cindex Multilingual Environment +@item +Leim is now part of Emacs. Unicode support has been much improved, and +the following input methods have been added: belarusian, bulgarian-bds, +bulgarian-phonetic, chinese-sisheng, croatian, dutch, georgian, +latin-alt-postfix, latin-postfix, latin-prefix, latvian-keyboard, +lithuanian-numeric, lithuanian-keyboard, malayalam-inscript, rfc1345, +russian-computer, sgml, slovenian, tamil-inscript, ucs, +ukrainian-computer, vietnamese-telex, and welsh. + +The following language environments have also been added: Belarusian, +Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, Latin-6, +Latin-7, Latvian, Lithuanian, Malayalam, Russian, Slovenian, Swedish, +Tajik, Tamil, UTF-8, Ukrainian, Welsh, and Windows-1255. + +@cindex Documentation +@cindex Emacs Lisp Manual +@item +In addition, Emacs 22 now includes the Emacs Lisp Reference Manual +(@pxref{Emacs Lisp documentation}) and the Emacs Lisp Intro. +@end itemize + +Many other changes have been made in Emacs 22, use @kbd{C-h n} to get a +full list. + +@c ------------------------------------------------------------ +@node Common requests, Bugs and problems, Status of Emacs, Top +@chapter Common requests +@cindex Common requests + +@menu +* Setting up a customization file:: +* Using Customize:: +* Colors on a TTY:: +* Debugging a customization file:: +* Displaying the current line or column:: +* Displaying the current file name in the titlebar:: +* Turning on abbrevs by default:: +* Associating modes with files:: +* Highlighting a region:: +* Replacing highlighted text:: +* Controlling case sensitivity:: +* Working with unprintable characters:: +* Searching for/replacing newlines:: +* Yanking text in isearch:: +* Wrapping words automatically:: +* Turning on auto-fill by default:: +* Spell-checkers:: +* Checking TeX and *roff documents:: +* Changing load-path:: +* Using an already running Emacs process:: +* Compiler error messages:: +* Indenting switch statements:: +* Customizing C and C++ indentation:: +* Horizontal scrolling:: +* Overwrite mode:: +* Turning off beeping:: +* Turning the volume down:: +* Automatic indentation:: +* Matching parentheses:: +* Hiding #ifdef lines:: +* Repeating commands:: +* Valid X resources:: +* Evaluating Emacs Lisp code:: +* Changing the length of a Tab:: +* Inserting text at the beginning of each line:: +* Underlining paragraphs:: +* Forcing the cursor to remain in the same column:: +* Forcing Emacs to iconify itself:: +* Using regular expressions:: +* Replacing text across multiple files:: +* Documentation for etags:: +* Disabling backups:: +* Disabling auto-save-mode:: +* Going to a line by number:: +* Modifying pull-down menus:: +* Deleting menus and menu options:: +* Turning on syntax highlighting:: +* Scrolling only one line:: +* Editing MS-DOS files:: +* Filling paragraphs with a single space:: +* Escape sequences in shell output:: +* Fullscreen mode on MS-Windows:: +@end menu + +@node Setting up a customization file, Using Customize, Common requests, Common requests +@section How do I set up a @file{.emacs} file properly? +@cindex @file{.emacs} file, setting up +@cindex @file{.emacs} file, locating +@cindex Init file, setting up +@cindex Customization file, setting up + +@inforef{Init File, Init File, emacs}. + +In general, new Emacs users should not have @file{.emacs} files, because +it causes confusing non-standard behavior. Then they send questions to +@email{help-gnu-emacs@@gnu.org} asking why Emacs isn't behaving as +documented. + +Beginning with version 20.1, Emacs includes the new Customize facility +(@pxref{Using Customize}). This allows users who are unfamiliar with +Emacs Lisp to modify their @file{.emacs} files in a relatively +straightforward way, using menus rather than Lisp code. Most packages +support Customize as of this writing. + +While Customize might indeed make it easier to configure Emacs, +consider taking a bit of time to learn Emacs Lisp and modifying your +@file{.emacs} directly. Simple configuration options are described +rather completely in @inforef{Init File, Init File, emacs}, for users +interested in performing frequently requested, basic tasks. + +Sometimes users are unsure as to where their @file{.emacs} file should +be found. Visiting the file as @file{~/.emacs} from Emacs will find +the correct file. + +@node Using Customize, Colors on a TTY, Setting up a customization file, Common requests +@section How do I start using Customize? +@cindex Customize groups +@cindex Customizing variables +@cindex Customizing faces + +The main Customize entry point is @kbd{M-x customize @key{RET}}. This +command takes you to a buffer listing all the available Customize +groups. From there, you can access all customizable options and faces, +change their values, and save your changes to your init file. +@inforef{Easy Customization, Easy Customization, emacs}. + +If you know the name of the group in advance (e.g. ``shell''), use +@kbd{M-x customize-group @key{RET}}. + +If you wish to customize a single option, use @kbd{M-x customize-option +@key{RET}}. This command prompts you for the name of the option to +customize, with completion. + +@node Colors on a TTY, Debugging a customization file, Using Customize, Common requests +@section How do I get colors and syntax highlighting on a TTY? +@cindex Colors on a TTY +@cindex Syntax highlighting on a TTY +@cindex Console, colors + +In Emacs 21.1 and later, colors and faces are supported in non-windowed mode, +i.e.@: on Unix and GNU/Linux text-only terminals and consoles, and when +invoked as @samp{emacs -nw} on X, MS-Windows, and Mac. (Colors and faces were +supported in the MS-DOS port since Emacs 19.29.) Emacs automatically +detects color support at startup and uses it if available. If you think +that your terminal supports colors, but Emacs won't use them, check the +@code{termcap} entry for your display type for color-related +capabilities. + +The command @kbd{M-x list-colors-display} pops up a window which +exhibits all the colors Emacs knows about on the current display. + +Syntax highlighting is on by default since version 22.1. + +@node Debugging a customization file, Displaying the current line or column, Colors on a TTY, Common requests +@section How do I debug a @file{.emacs} file? +@cindex Debugging @file{.emacs} file +@cindex @file{.emacs} debugging +@cindex Init file debugging +@cindex @samp{-debug-init} option + +Start Emacs with the @samp{-debug-init} command-line option. This +enables the Emacs Lisp debugger before evaluating your @file{.emacs} +file, and places you in the debugger if something goes wrong. The top +line in the @file{trace-back} buffer will be the error message, and the +second or third line of that buffer will display the Lisp code from your +@file{.emacs} file that caused the problem. + +You can also evaluate an individual function or argument to a function +in your @file{.emacs} file by moving the cursor to the end of the +function or argument and typing @kbd{C-x C-e} (@kbd{M-x +eval-last-sexp}). + +Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of +variables which you are trying to set or use. + +@node Displaying the current line or column, Displaying the current file name in the titlebar, Debugging a customization file, Common requests +@section How do I make Emacs display the current line (or column) number? +@cindex @code{line-number-mode} +@cindex Displaying the current line or column +@cindex Line number, displaying the current +@cindex Column, displaying the current +@cindex @code{mode-line-format} + +To have Emacs automatically display the current line number of the point +in the mode line, do @kbd{M-x line-number-mode}. You can also put the +form + +@lisp +(setq line-number-mode t) +@end lisp + +@noindent +in your @file{.emacs} file to achieve this whenever you start Emacs. +(Line number display is on by default, unless your site-specific +initialization disables it.) Note that Emacs will not display the line +number if the buffer's size in bytes is larger than the value of the +variable @code{line-number-display-limit}. + +You can similarly display the current column with +@kbd{M-x column-number-mode}, or by putting the form + +@lisp +(setq column-number-mode t) +@end lisp + +@noindent +in your @file{.emacs} file. + +The @code{"%c"} format specifier in the variable @code{mode-line-format} +will insert the current column's value into the mode line. See the +documentation for @code{mode-line-format} (using @kbd{C-h v +mode-line-format @key{RET}}) for more information on how to set and use +this variable. + +Users of all Emacs versions can display the current column using the +@samp{column} package written by @email{abraham@@dina.kvl.dk, Per +Abrahamsen}. @xref{Packages that do not come with Emacs}, for +instructions on how to get it. + +@cindex Set number capability in @code{vi} emulators +None of the @code{vi} emulation modes provide the ``set number'' +capability of @code{vi} (as far as we know). The @samp{setnu} package +written by @email{kyle@@wonderworks.com, Kyle Jones} provides this +feature. So too does @samp{wb-line-number}, written by +@email{naoki.y.nakamura@@nifty.com, Naoki Nakamura}. + +@node Displaying the current file name in the titlebar, Turning on abbrevs by default, Displaying the current line or column, Common requests +@section How can I modify the titlebar to contain the current file name? +@cindex Titlebar, displaying the current file name in +@cindex File name, displaying in the titlebar +@cindex @code{frame-title-format} + +The contents of an Emacs frame's titlebar is controlled by the variable +@code{frame-title-format}, which has the same structure as the variable +@code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x +describe-variable} to get information about one or both of these +variables.) + +By default, the titlebar for a frame does contain the name of the buffer +currently being visited, except if there is a single frame. In such a +case, the titlebar contains Emacs invocation name and the name of the +machine at which Emacs was invoked. This is done by setting +@code{frame-title-format} to the default value of + +@lisp +(multiple-frames "%b" ("" invocation-name "@@" system-name)) +@end lisp + +To modify the behavior such that frame titlebars contain the buffer's +name regardless of the number of existing frames, include the following +in your @file{.emacs}: + +@lisp +(setq frame-title-format "%b") +@end lisp + +@node Turning on abbrevs by default, Associating modes with files, Displaying the current file name in the titlebar, Common requests +@section How do I turn on abbrevs by default just in mode @var{mymode}? +@cindex Abbrevs, turning on by default + +Put this in your @file{.emacs} file: + +@lisp +(condition-case () + (quietly-read-abbrev-file) + (file-error nil)) + +(add-hook '@var{mymode}-mode-hook + (lambda () + (setq abbrev-mode t))) +@end lisp + +Starting with Emacs 22, the standard abbrevs file is read automatically +at startup, so the first of these two forms becomes unnecessary. + +@node Associating modes with files, Highlighting a region, Turning on abbrevs by default, Common requests +@section How do I make Emacs use a certain major mode for certain files? +@cindex Associating modes with files +@cindex File extensions and modes +@cindex @code{auto-mode-alist}, modifying +@cindex Modes, associating with file extensions + +If you want to use a certain mode @var{foo} for all files whose names end +with the extension @file{.@var{bar}}, this will do it for you: + +@lisp +(setq auto-mode-alist (cons '("\\.@var{bar}\\'" . @var{foo}-mode) auto-mode-alist)) +@end lisp + +Otherwise put this somewhere in the first line of any file you want to +edit in the mode @var{foo} (in the second line, if the first line begins +with @samp{#!}): + +@example +-*- @var{foo} -*- +@end example + +@cindex Major mode for shell scripts +Beginning with Emacs 19, the variable @code{interpreter-mode-alist} +specifies which mode to use when loading a shell script. (Emacs +determines which interpreter you're using by examining the first line of +the script.) This feature only applies when the file name doesn't +indicate which mode to use. Use @kbd{C-h v} (or @kbd{M-x +describe-variable}) on @code{interpreter-mode-alist} to learn more. + +@node Highlighting a region, Replacing highlighted text, Associating modes with files, Common requests +@section How can I highlight a region of text in Emacs? +@cindex Highlighting text +@cindex Text, highlighting +@cindex @code{transient-mark-mode} +@cindex Region, highlighting a + +You can cause the region to be highlighted when the mark is active by +including + +@lisp +(transient-mark-mode t) +@end lisp + +@noindent +in your @file{.emacs} file. + +@node Replacing highlighted text, Controlling case sensitivity, Highlighting a region, Common requests +@section How can I replace highlighted text with what I type? +@cindex @code{delete-selection-mode} +@cindex Replacing highlighted text +@cindex Highlighting and replacing text + +Use @code{delete-selection-mode}, which you can start automatically by +placing the following Lisp form in your @file{.emacs} file: + +@lisp +(delete-selection-mode 1) +@end lisp + +According to the documentation string for @code{delete-selection-mode} +(which you can read using @kbd{M-x describe-function @key{RET} +delete-selection-mode @key{RET}}): + +@quotation +When ON, typed text replaces the selection if the selection is active. +When OFF, typed text is just inserted at point. +@end quotation + +This mode also allows you to delete (not kill) the highlighted region by +pressing @key{DEL}. + +@node Controlling case sensitivity, Working with unprintable characters, Replacing highlighted text, Common requests +@section How do I control Emacs's case-sensitivity when searching/replacing? +@cindex @code{case-fold-search} +@cindex Case sensitivity of searches +@cindex Searching without case sensitivity +@cindex Ignoring case in searches + +For searching, the value of the variable @code{case-fold-search} +determines whether they are case sensitive: + +@lisp +(setq case-fold-search nil) ; make searches case sensitive +(setq case-fold-search t) ; make searches case insensitive +@end lisp + +@cindex Case sensitivity in replacements +@cindex Replacing, and case sensitivity +@cindex @code{case-replace} +Similarly, for replacing, the variable @code{case-replace} determines +whether replacements preserve case. + +You can also toggle case sensitivity at will in isearch with @kbd{M-c}. + +To change the case sensitivity just for one major mode, use the major +mode's hook. For example: + +@lisp +(add-hook '@var{foo}-mode-hook + (lambda () + (setq case-fold-search nil))) +@end lisp + +@node Working with unprintable characters, Searching for/replacing newlines, Controlling case sensitivity, Common requests +@section How do I search for, delete, or replace unprintable (eight-bit or control) characters? +@cindex Unprintable characters, working with +@cindex Working with unprintable characters +@cindex Control characters, working with +@cindex Eight-bit characters, working with +@cindex Searching for unprintable characters +@cindex Regexps and unprintable characters + +To search for a single character that appears in the buffer as, for +example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}. (This assumes +the value of @code{search-quote-char} is 17 (i.e., @kbd{C-q}).) +Searching for @strong{all} unprintable characters is best done with a +regular expression (@dfn{regexp}) search. The easiest regexp to use for +the unprintable chars is the complement of the regexp for the printable +chars. + +@itemize @bullet + +@item +Regexp for the printable chars: @samp{[\t\n\r\f -~]} + +@item +Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]} + +@end itemize + +To type these special characters in an interactive argument to +@code{isearch-forward-regexp} or @code{re-search-forward}, you need to +use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand +respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So, +to search for unprintable characters using @code{re-search-forward}: + +@kbd{M-x re-search-forward @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET}} + +Using @code{isearch-forward-regexp}: + +@kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]} + +To delete all unprintable characters, simply use replace-regexp: + +@kbd{M-x replace-regexp @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET} @key{RET}} + +Replacing is similar to the above. To replace all unprintable +characters with a colon, use: + +M-x replace-regexp @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET} : @key{RET} + +@node Searching for/replacing newlines, Yanking text in isearch, Working with unprintable characters, Common requests +@section How do I input a newline character in isearch or query-replace? +@cindex Searching for newlines +@cindex Replacing newlines + +Use @kbd{C-q C-j}. For more information, see @inforef{Special Isearch, +Special Input for Incremental Search, emacs}. + + +@node Yanking text in isearch, Wrapping words automatically, Searching for/replacing newlines, Common requests +@section How do I copy text from the kill ring into the search string? +@cindex Yanking text into the search string +@cindex isearch yanking + +Use @kbd{M-y}. @inforef{Isearch Yank, Isearch Yanking, emacs}. + +@node Wrapping words automatically, Turning on auto-fill by default, Yanking text in isearch, Common requests +@section How do I make Emacs wrap words for me? +@cindex Wrapping word automatically +@cindex Wrapping lines +@cindex Line wrap +@cindex @code{auto-fill-mode}, introduction to +@cindex Maximum line width, default value +@cindex @code{fill-column}, default value + +Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}. +The default maximum line width is 70, determined by the variable +@code{fill-column}. To learn how to turn this on automatically, see +@ref{Turning on auto-fill by default}. + +@node Turning on auto-fill by default, Spell-checkers, Wrapping words automatically, Common requests +@section How do I turn on @code{auto-fill-mode} by default? +@cindex @code{auto-fill-mode}, activating automatically +@cindex Filling automatically +@cindex Automatic entry to @code{auto-fill-mode} + +To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x +auto-fill-mode}. + +To turn it on for every buffer in a certain mode, you must use the hook +for that mode. For example, to turn on @code{auto-fill} mode for all +text buffers, including the following in your @file{.emacs} file: + +@lisp +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end lisp + +If you want @code{auto-fill} mode on in all major modes, do this: + +@lisp +(setq-default auto-fill-function 'do-auto-fill) +@end lisp + +@node Spell-checkers, Checking TeX and *roff documents, Turning on auto-fill by default, Common requests +@section Where can I get a better spelling checker for Emacs? +@cindex Checking spelling +@cindex Spelling, checking text documents + +Use Ispell. @xref{Ispell}. + +@node Checking TeX and *roff documents, Changing load-path, Spell-checkers, Common requests +@section How can I spell-check @TeX{} or *roff documents? +@cindex Spelling, checking @TeX{} documents +@cindex @TeX{} documents, checking spelling in + +Use Ispell. Ispell can handle @TeX{} and *roff documents. +@xref{Ispell}. + +@node Changing load-path, Using an already running Emacs process, Checking TeX and *roff documents, Common requests +@section How do I change @code{load-path}? +@cindex @code{load-path}, modifying +@cindex Modifying @code{load-path} +@cindex Adding to @code{load-path} + +In general, you should only add to the @code{load-path}. You can add +directory @var{/dir/subdir} to the load path like this: + +@lisp +(setq load-path (cons "/dir/subdir/" load-path)) +@end lisp + +To do this relative to your home directory: + +@lisp +(setq load-path (cons "~/mysubdir/" load-path)) +@end lisp + +@node Using an already running Emacs process, Compiler error messages, Changing load-path, Common requests +@section How do I use an already running Emacs from another window? +@cindex @code{emacsclient} +@cindex Emacs server functions +@cindex Using an existing Emacs process + +@code{emacsclient}, which comes with Emacs, is for editing a file using +an already running Emacs rather than starting up a new Emacs. It does +this by sending a request to the already running Emacs, which must be +expecting the request. + +@itemize @bullet + +@item +Setup: + +Emacs must have executed the @code{server-start} function for +@samp{emacsclient} to work. This can be done either by a command line +option: + +@example +emacs -f server-start +@end example + +or by invoking @code{server-start} from @file{.emacs}: + +@lisp +(if (@var{some conditions are met}) (server-start)) +@end lisp + +When this is done, Emacs creates a Unix domain socket named +@file{server} in @file{/tmp/emacs@var{userid}}. See +@code{server-socket-dir}. + +To get your news reader, mail reader, etc., to invoke +@samp{emacsclient}, try setting the environment variable @code{EDITOR} +(or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may +have to specify the full pathname of the @samp{emacsclient} program +instead. Examples: + +@example +# csh commands: +setenv EDITOR emacsclient + +# using full pathname +setenv EDITOR /usr/local/emacs/etc/emacsclient + +# sh command: +EDITOR=emacsclient ; export EDITOR +@end example + +@item +Normal use: + +When @samp{emacsclient} is run, it connects to the socket and passes its +command line options to Emacs, which at the next opportunity will visit +the files specified. (Line numbers can be specified just like with +Emacs.) The user will have to switch to the Emacs window by hand. When +the user is done editing a file, the user can type @kbd{C-x #} (or +@kbd{M-x server-edit}) to indicate this. If there is another buffer +requested by @code{emacsclient}, Emacs will switch to it; otherwise +@code{emacsclient} will exit, signaling the calling program to continue. + +@cindex @code{gnuserv} +There is an enhanced version of @samp{emacsclient} called +@samp{gnuserv}, written by @email{ange@@hplb.hpl.hp.com, Andy Norman} +(@pxref{Packages that do not come with Emacs}). @samp{gnuserv} uses +Internet domain sockets, so it can work across most network connections. + +The most recent @samp{gnuserv} package is available at + +@uref{http://meltin.net/hacks/emacs/} + +@end itemize + +@node Compiler error messages, Indenting switch statements, Using an already running Emacs process, Common requests +@section How do I make Emacs recognize my compiler's funny error messages? +@cindex Compiler error messages, recognizing +@cindex Recognizing non-standard compiler errors +@cindex Regexps for recognizing compiler errors +@cindex Errors, recognizing compiler + +Customize the @code{compilation-error-regexp-alist} variable. + +@node Indenting switch statements, Customizing C and C++ indentation, Compiler error messages, Common requests +@section How do I change the indentation for @code{switch}? +@cindex @code{switch}, indenting +@cindex Indenting of @code{switch} + +Many people want to indent their @code{switch} statements like this: + +@example +f() +@{ + switch(x) @{ + case A: + x1; + break; + case B: + x2; + break; + default: + x3; + @} +@} +@end example + +The solution at first appears to be: set @code{c-indent-level} to 4 and +@code{c-label-offset} to -2. However, this will give you an indentation +spacing of four instead of two. + +The @emph{real} solution is to use @code{cc-mode} (the default mode for +C programming in Emacs 20 and later) and add the following line to your +@file{.emacs}: + +@lisp +(c-set-offset 'case-label '+) +@end lisp + +There appears to be no way to do this with the old @code{c-mode}. + +@node Customizing C and C++ indentation, Horizontal scrolling, Indenting switch statements, Common requests +@section How to customize indentation in C, C@t{++}, and Java buffers? +@cindex Indentation, how to customize +@cindex Customize indentation + +The Emacs @code{cc-mode} features an interactive procedure for +customizing the indentation style, which is fully explained in the +@cite{CC Mode} manual that is part of the Emacs distribution, see +@ref{Customizing Indentation, , Customization Indentation, ccmode, +The CC Mode Manual}. Here's a short summary of the procedure: + +@enumerate +@item +Go to the beginning of the first line where you don't like the +indentation and type @kbd{C-c C-o}. Emacs will prompt you for the +syntactic symbol; type @key{RET} to accept the default it suggests. + +@item +Emacs now prompts for the offset of this syntactic symbol, showing the +default (the current definition) inside parentheses. You can choose +one of these: + +@table @code +@item 0 +No extra indentation. +@item + +Indent one basic offset. +@item - +Outdent one basic offset. +@item ++ +Indent two basic offsets +@item -- +Outdent two basic offsets. +@item * +Indent half basic offset. +@item / +Outdent half basic offset. +@end table + +@item +After choosing one of these symbols, type @kbd{C-c C-q} to reindent +the line or the block according to what you just specified. + +@item +If you don't like the result, go back to step 1. Otherwise, add the +following line to your @file{.emacs}: + +@lisp +(c-set-offset '@var{syntactic-symbol} @var{offset}) +@end lisp + +@noindent +where @var{syntactic-symbol} is the name Emacs shows in the minibuffer +when you type @kbd{C-c C-o} at the beginning of the line, and +@var{offset} is one of the indentation symbols listed above (@code{+}, +@code{/}, @code{0}, etc.) that you've chosen during the interactive +procedure. + +@item +Go to the next line whose indentation is not to your liking and repeat +the process there. +@end enumerate + +It is recommended to put all the resulting @code{(c-set-offset ...)} +customizations inside a C mode hook, like this: + +@lisp +(defun my-c-mode-hook () + (c-set-offset ...) + (c-set-offset ...)) +(add-hook 'c-mode-hook 'my-c-mode-hook) +@end lisp + +@noindent +Using @code{c-mode-hook} avoids the need to put a @w{@code{(require +'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset} +might be unavailable when @code{cc-mode} is not loaded. + +Note that @code{c-mode-hook} runs for C source files only; use +@code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for +Java sources, etc. If you want the same customizations to be in +effect in @emph{all} languages supported by @code{cc-mode}, use +@code{c-mode-common-hook}. + +@node Horizontal scrolling, Overwrite mode, Customizing C and C++ indentation, Common requests +@section How can I make Emacs automatically scroll horizontally? +@cindex @code{hscroll-mode} +@cindex Horizontal scrolling +@cindex Scrolling horizontally + +In Emacs 21 and later, this is on by default: if the variable +@code{truncate-lines} is non-@code{nil} in the current buffer, Emacs +automatically scrolls the display horizontally when point moves off the +left or right edge of the window. + +Note that this is overridden by the variable +@code{truncate-partial-width-windows} if that variable is non-nil +and the current buffer is not full-frame width. + +In Emacs 20, use the @code{hscroll-mode}. Here is some information from +the documentation, available by typing @kbd{C-h f hscroll-mode @key{RET}}: + +Automatically scroll horizontally when the point moves off the +left or right edge of the window. + +@itemize @minus +@item +Type @kbd{M-x hscroll-mode} to enable it in the current buffer. + +@item +Type @kbd{M-x hscroll-global-mode} to enable it in every buffer. + +@item +@code{turn-on-hscroll} is useful in mode hooks as in: + +@lisp +(add-hook 'text-mode-hook 'turn-on-hscroll) +@end lisp + +@item +@code{hscroll-margin} controls how close the cursor can get to the +edge of the window. + +@item +@code{hscroll-step-percent} controls how far to jump once we decide to do so. +@end itemize + +@node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests +@section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting? +@cindex @key{Insert} +@cindex @code{overwrite-mode} +@cindex Overwriting existing text +@cindex Toggling @code{overwrite-mode} + +@kbd{M-x overwrite-mode} (a minor mode). This toggles +@code{overwrite-mode} on and off, so exiting from @code{overwrite-mode} +is as easy as another @kbd{M-x overwrite-mode}. + +On some systems, @key{Insert} toggles @code{overwrite-mode} on and off. + +@node Turning off beeping, Turning the volume down, Overwrite mode, Common requests +@section How do I stop Emacs from beeping on a terminal? +@cindex Beeping, turning off +@cindex Visible bell +@cindex Bell, visible + +@email{martin@@cc.gatech.edu, Martin R. Frank} writes: + +Tell Emacs to use the @dfn{visible bell} instead of the audible bell, +and set the visible bell to nothing. + +That is, put the following in your @code{TERMCAP} environment variable +(assuming you have one): + +@example +... :vb=: ... +@end example + +And evaluate the following Lisp form: + +@example +(setq visible-bell t) +@end example + +@node Turning the volume down, Automatic indentation, Turning off beeping, Common requests +@section How do I turn down the bell volume in Emacs running under X? +@cindex Bell, volume of +@cindex Volume of bell + +On X Window system, you can adjust the bell volume and duration for all +programs with the shell command @code{xset}. + +Invoking @code{xset} without any arguments produces some basic +information, including the following: + +@example +usage: xset [-display host:dpy] option ... + To turn bell off: + -b b off b 0 + To set bell volume, pitch and duration: + b [vol [pitch [dur]]] b on +@end example + +@node Automatic indentation, Matching parentheses, Turning the volume down, Common requests +@section How do I tell Emacs to automatically indent a new line to the indentation of the previous line? +@cindex Indenting new lines +@cindex New lines, indenting of +@cindex Previous line, indenting according to +@cindex Text indentation + +Such behavior is automatic in Emacs 20 and later. From the +@file{etc/NEWS} file for Emacs 20.2: + +@example +** In Text mode, now only blank lines separate paragraphs. This makes +it possible to get the full benefit of Adaptive Fill mode in Text mode, +and other modes derived from it (such as Mail mode). @key{TAB} in Text +mode now runs the command @code{indent-relative}; this makes a practical +difference only when you use indented paragraphs. + +As a result, the old Indented Text mode is now identical to Text mode, +and is an alias for it. + +If you want spaces at the beginning of a line to start a paragraph, use +the new mode, Paragraph Indent Text mode. +@end example + +@cindex Prefixing lines +@cindex Fill prefix +If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill +by default}), you can tell Emacs to prefix every line with a certain +character sequence, the @dfn{fill prefix}. Type the prefix at the +beginning of a line, position point after it, and then type @kbd{C-x .} +(@code{set-fill-prefix}) to set the fill prefix. Thereafter, +auto-filling will automatically put the fill prefix at the beginning of +new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill +prefix when refilling the paragraph. + +If you have paragraphs with different levels of indentation, you will +have to set the fill prefix to the correct value each time you move to a +new paragraph. There are many packages available to deal with this +(@pxref{Packages that do not come with Emacs}). Look for ``fill'' and +``indent'' keywords for guidance. + +@node Matching parentheses, Hiding #ifdef lines, Automatic indentation, Common requests +@section How do I show which parenthesis matches the one I'm looking at? +@cindex Parentheses, matching +@cindex @file{paren.el} +@cindex Highlighting matching parentheses +@cindex Pairs of parentheses, highlighting +@cindex Matching parentheses + +Call @code{show-paren-mode} in your @file{.emacs} file: + +@lisp +(show-paren-mode 1) +@end lisp + +You can also enable this mode by selecting the @samp{Paren Match +Highlighting} option from the @samp{Options} menu of the Emacs menu bar +at the top of any Emacs frame. + +Alternatives to this mode include: + +@itemize @bullet + +@item +If you're looking at a right parenthesis (or brace or bracket) you can +delete it and reinsert it. Emacs will momentarily move the cursor to +the matching parenthesis. + +@item +@kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp}) +will skip over one set of balanced parentheses, so you can see which +parentheses match. (You can train it to skip over balanced brackets +and braces at the same time by modifying the syntax table.) + +@cindex Show matching paren as in @code{vi} +@item +Here is some Emacs Lisp that will make the @key{%} key show the matching +parenthesis, like in @code{vi}. In addition, if the cursor isn't over a +parenthesis, it simply inserts a % like normal. + +@lisp +;; By an unknown contributor + +(global-set-key "%" 'match-paren) + +(defun match-paren (arg) + "Go to the matching paren if on a paren; otherwise insert %." + (interactive "p") + (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1)) + ((looking-at "\\s\)") (forward-char 1) (backward-list 1)) + (t (self-insert-command (or arg 1))))) +@end lisp + +@end itemize + +@node Hiding #ifdef lines, Repeating commands, Matching parentheses, Common requests +@section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler? +@cindex @code{#ifdef}, selective display of +@cindex @code{hide-ifdef-mode} +@cindex Hiding @code{#ifdef} text +@cindex Selectively displaying @code{#ifdef} code + +@kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want +to investigate @file{cpp.el}, which is distributed with Emacs. + +@node Repeating commands, Valid X resources, Hiding #ifdef lines, Common requests +@section How do I repeat a command as many times as possible? +@cindex Repeating commands many times +@cindex Commands, repeating many times +@cindex @code{.}, equivalent to @code{vi} command + +As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z}) +that repeats the last command. If you preface it with a prefix +argument, the prefix arg is applied to the command. + +You can also type @kbd{C-x @key{ESC} @key{ESC}} +(@code{repeat-complex-command}) to reinvoke commands that used the +minibuffer to get arguments. In @code{repeat-complex-command} you can +type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your +keyboard has these keys) to scan through all the different complex +commands you've typed. + +To repeat a set of commands, use keyboard macros. Use @kbd{C-x (} and +@kbd{C-x )} to make a keyboard macro that invokes the command and then +type @kbd{C-x e}. (@inforef{Keyboard Macros, Keyboard Macros, emacs}.) + +If you're really desperate for the @code{.} command in @code{vi} that +redoes the last insertion/deletion, use VIPER, a @code{vi} emulation +mode which comes with Emacs, and which appears to support it. +(@xref{VIPER}.) + +@node Valid X resources, Evaluating Emacs Lisp code, Repeating commands, Common requests +@section What are the valid X resource settings (i.e., stuff in .Xdefaults)? +@cindex Resources, X +@cindex X resources +@cindex Setting X resources + +@inforef{X Resources, X Resources, emacs}. + +You can also use a resource editor, such as editres (for X11R5 and +onwards), to look at the resource names for the menu bar, assuming Emacs +was compiled with the X toolkit. + +@node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests +@section How do I execute (``evaluate'') a piece of Emacs Lisp code? +@cindex Evaluating Lisp code +@cindex Lisp forms, evaluating + +There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an +Emacs Lisp @dfn{form}: + +@itemize @bullet + +@item +If you want it evaluated every time you run Emacs, put it in a file +named @file{.emacs} in your home directory. This is known as ``your +@file{.emacs} file,'' and contains all of your personal customizations. + +@item +You can type the form in the @file{*scratch*} buffer, and then type +@key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form +will be inserted in the buffer. + +@item +In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form +before or around point. + +@item +Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately +before point and prints its value in the echo area. + +@item +Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp +form in the minibuffer which will be evaluated once you press @key{RET}. + +@item +You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp +forms in a file. (To do this from Lisp use the function @code{load} +instead.) + +The functions @code{load-library}, @code{eval-region}, +@code{eval-buffer}, @code{require}, and @code{autoload} are also +useful; see @ref{Emacs Lisp documentation}, if you want to learn more +about them. + +@end itemize + +@node Changing the length of a Tab, Inserting text at the beginning of each line, Evaluating Emacs Lisp code, Common requests +@section How do I change Emacs's idea of the @key{TAB} character's length? +@cindex Tab length +@cindex Length of tab character +@cindex @code{default-tab-width} + +Set the variable @code{default-tab-width}. For example, to set +@key{TAB} stops every 10 characters, insert the following in your +@file{.emacs} file: + +@lisp +(setq default-tab-width 10) +@end lisp + +Do not confuse variable @code{tab-width} with variable +@code{tab-stop-list}. The former is used for the display of literal +@key{TAB} characters. The latter controls what characters are inserted +when you press the @key{TAB} character in certain modes. + +@node Inserting text at the beginning of each line, Underlining paragraphs, Changing the length of a Tab, Common requests +@section How do I insert at the beginning of every line? +@cindex Prefixing a region with some text +@cindex Prefix character, inserting in mail/news replies +@cindex Replies to mail/news, inserting a prefix character +@cindex @code{mail-yank-prefix} +@cindex Mail replies, inserting a prefix character +@cindex News replies, inserting a prefix character + +To do this to an entire buffer, type @kbd{M-< M-x replace-regexp +@key{RET} ^ @key{RET} your text @key{RET}}. + +To do this to a region, use @code{string-insert-rectangle}. +Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you +want to prefix, move the cursor to last line to be prefixed, and type +@kbd{M-x string-insert-rectangle @key{RET}}. To do this for the whole +buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}. + +If you are trying to prefix a yanked mail message with @samp{>}, you +might want to set the variable @code{mail-yank-prefix}. In Message +buffers, you can even use @kbd{M-;} to cite yanked messages (@kbd{M-;} +runs the function @code{comment-region}, it is a general-purpose +mechanism to comment regions) (@pxref{Changing the included text prefix}). + +@node Underlining paragraphs, Forcing the cursor to remain in the same column, Inserting text at the beginning of each line, Common requests +@section How do I insert @samp{_^H} before each character in a region to get an underlined paragraph? +@cindex Underlining a region of text +@cindex @code{underline-region} + +Mark the region and then type @kbd{M-x underline-region @key{RET}}. + +@node Forcing the cursor to remain in the same column, Forcing Emacs to iconify itself, Underlining paragraphs, Common requests +@section How do I make Emacs behave like this: when I go up or down, the cursor should stay in the same column even if the line is too short? +@cindex @code{picture-mode} +@cindex Remaining in the same column, regardless of contents +@cindex Vertical movement in empty documents + +Use @kbd{M-x picture-mode}. + +See also the variable @code{track-eol} and the command +@code{set-goal-column} bound to @kbd{C-x C-n} +(@pxref{Moving Point, , , emacs, The GNU Emacs Manual}). + +@node Forcing Emacs to iconify itself, Using regular expressions, Forcing the cursor to remain in the same column, Common requests +@section How do I tell Emacs to iconify itself? +@cindex Iconification under the X Window System +@cindex X Window System and iconification +@cindex Suspending Emacs + +@kbd{C-z} iconifies Emacs when running under X and suspends Emacs +otherwise. @inforef{Frame Commands, Frame Commands, emacs}. + +@node Using regular expressions, Replacing text across multiple files, Forcing Emacs to iconify itself, Common requests +@section How do I use regexps (regular expressions) in Emacs? +@cindex Regexps +@cindex Regular expressions +@cindex Differences between Unix and Emacs regexps +@cindex Unix regexps, differences from Emacs +@cindex Text strings, putting regexps in + +@inforef{Regexp Backslash, Regexp Backslash, emacs}. + +The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators +are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is +@samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)} +in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}. + +Note the doubled backslashes! + +@itemize @bullet + +@item +Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set +(@samp{[^...]}) can match a newline character (@key{LFD} a.k.a.@: +@kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the +characters not to match. + +@item +The character syntax regexps (e.g., @samp{\sw}) are not +meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This +is actually typical for regexp syntax.) + +@end itemize + +@node Replacing text across multiple files, Documentation for etags, Using regular expressions, Common requests +@section How do I perform a replace operation across more than one file? +@cindex Replacing strings across files +@cindex Multiple files, replacing across +@cindex Files, replacing strings across multiple +@cindex Recursive search/replace operations + +As of Emacs 19.29, Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x +d}) supports the command @code{dired-do-query-replace} (@kbd{Q}), which +allows users to replace regular expressions in multiple files. + +You can use this command to perform search/replace operations on +multiple files by following the following steps: + +@itemize @bullet +@item +Assemble a list of files you want to operate on with either +@code{find-dired}, @code{find-name-dired} or @code{find-grep-dired}. + +@item +Mark all files in the resulting Dired buffer using @kbd{t}. + +@item +Use @kbd{Q} to start a @code{query-replace-regexp} session on the marked +files. + +@item +To accept all replacements in each file, hit @kbd{!}. +@end itemize + +Another way to do the same thing is to use the ``tags'' feature of +Emacs: it includes the command @code{tags-query-replace} which performs +a query-replace across all the files mentioned in the @file{TAGS} file. +@inforef{Tags Search, Tags Search, emacs}. + +@node Documentation for etags, Disabling backups, Replacing text across multiple files, Common requests +@section Where is the documentation for @code{etags}? +@cindex Documentation for @code{etags} +@cindex @code{etags}, documentation for + +The @code{etags} man page should be in the same place as the +@code{emacs} man page. + +Quick command-line switch descriptions are also available. For example, +@samp{etags -H}. + +@node Disabling backups, Disabling auto-save-mode, Documentation for etags, Common requests +@section How do I disable backup files? +@cindex Backups, disabling +@cindex Disabling backups + +You probably don't want to do this, since backups are useful, especially +when something goes wrong. + +To avoid seeing backup files (and other ``uninteresting'' files) in Dired, +load @code{dired-x} by adding the following to your @file{.emacs} file: + +@lisp +(add-hook 'dired-load-hook + (lambda () + (load "dired-x"))) +@end lisp + +With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer. +You can make omitting the default for new dired buffers by putting the +following in your @file{.emacs}: + +@lisp +(add-hook 'dired-mode-hook 'dired-omit-toggle) +@end lisp + +If you're tired of seeing backup files whenever you do an @samp{ls} at +the Unix shell, try GNU @code{ls} with the @samp{-B} option. GNU +@code{ls} is part of the GNU Fileutils package, available from +@samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}). + +To disable or change the way backups are made, @inforef{Backup Names, , +emacs}. + +@cindex Backup files in a single directory +Beginning with Emacs 21.1, you can control where Emacs puts backup files +by customizing the variable @code{backup-directory-alist}. This +variable's value specifies that files whose names match specific patters +should have their backups put in certain directories. A typical use is +to add the element @code{("." . @var{dir})} to force Emacs to put +@strong{all} backup files in the directory @file{dir}. + +@node Disabling auto-save-mode, Going to a line by number, Disabling backups, Common requests +@section How do I disable @code{auto-save-mode}? +@cindex Disabling @code{auto-save-mode} +@cindex Auto-saving +@cindex Saving at frequent intervals + +You probably don't want to do this, since auto-saving is useful, +especially when Emacs or your computer crashes while you are editing a +document. + +Instead, you might want to change the variable +@code{auto-save-interval}, which specifies how many keystrokes Emacs +waits before auto-saving. Increasing this value forces Emacs to wait +longer between auto-saves, which might annoy you less. + +You might also want to look into Sebastian Kremer's @code{auto-save} +package (@pxref{Packages that do not come with Emacs}). This +package also allows you to place all auto-save files in one directory, +such as @file{/tmp}. + +To disable or change how @code{auto-save-mode} works, @inforef{Auto +Save, , emacs}. + +@node Going to a line by number, Modifying pull-down menus, Disabling auto-save-mode, Common requests +@section How can I go to a certain line given its number? +@cindex Going to a line by number +@cindex Compilation error messages +@cindex Recompilation + +Are you sure you indeed need to go to a line by its number? Perhaps all +you want is to display a line in your source file for which a compiler +printed an error message? If so, compiling from within Emacs using the +@kbd{M-x compile} and @kbd{M-x recompile} commands is a much more +effective way of doing that. Emacs automatically intercepts the compile +error messages, inserts them into a special buffer called +@code{*compilation*}, and lets you visit the locus of each message in +the source. Type @kbd{C-x `} to step through the offending lines one by +one (starting with Emacs 22, you can also use @kbd{M-g M-p} and +@kbd{M-g M-n} to go to the previous and next matches directly). Click +@kbd{Mouse-2} or press @key{RET} on a message text in the +@code{*compilation*} buffer to go to the line whose number is mentioned +in that message. + +But if you indeed need to go to a certain text line, type @kbd{M-g M-g} +(which is the default binding of the @code{goto-line} function starting +with Emacs 22). Emacs will prompt you for the number of the line and go +to that line. + +You can do this faster by invoking @code{goto-line} with a numeric +argument that is the line's number. For example, @kbd{C-u 286 M-g M-g} +will jump to line number 286 in the current buffer. + +@node Modifying pull-down menus, Deleting menus and menu options, Going to a line by number, Common requests +@section How can I create or modify new pull-down menu options? +@cindex Pull-down menus, creating or modifying +@cindex Menus, creating or modifying +@cindex Creating new menu options +@cindex Modifying pull-down menus +@cindex Menus and keymaps +@cindex Keymaps and menus + +Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers}) +represents a local or global keymap. Selecting a menu title with the +mouse displays that keymap's non-@code{nil} contents in the form of a menu. + +So to add a menu option to an existing menu, all you have to do is add a +new definition to the appropriate keymap. Adding a @samp{Forward Word} +item to the @samp{Edit} menu thus requires the following Lisp code: + +@lisp +(define-key global-map + [menu-bar edit forward] + '("Forward word" . forward-word)) +@end lisp + +@noindent +The first line adds the entry to the global keymap, which includes +global menu bar entries. Replacing the reference to @code{global-map} +with a local keymap would add this menu option only within a particular +mode. + +The second line describes the path from the menu-bar to the new entry. +Placing this menu entry underneath the @samp{File} menu would mean +changing the word @code{edit} in the second line to @code{file}. + +The third line is a cons cell whose first element is the title that will +be displayed, and whose second element is the function that will be +called when that menu option is invoked. + +To add a new menu, rather than a new option to an existing menu, we must +define an entirely new keymap: + +@lisp +(define-key global-map [menu-bar words] + (cons "Words" (make-sparse-keymap "Words"))) +@end lisp + +The above code creates a new sparse keymap, gives it the name +@samp{Words}, and attaches it to the global menu bar. Adding the +@samp{Forward Word} item to this new menu would thus require the +following code: + +@lisp +(define-key global-map + [menu-bar words forward] + '("Forward word" . forward-word)) +@end lisp + +@noindent +Note that because of the way keymaps work, menu options are displayed +with the more recently defined items at the top. Thus if you were to +define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that +order), the menu option @samp{baz} would appear at the top, and +@samp{foo} would be at the bottom. + +One way to avoid this problem is to use the function @code{define-key-after}, +which works the same as @code{define-key}, but lets you modify where items +appear. The following Lisp code would insert the @samp{Forward Word} +item in the @samp{Edit} menu immediately following the @samp{Undo} item: + +@lisp +(define-key-after + (lookup-key global-map [menu-bar edit]) + [forward] + '("Forward word" . forward-word) + 'undo) +@end lisp + +Note how the second and third arguments to @code{define-key-after} are +different from those of @code{define-key}, and that we have added a new +(final) argument, the function after which our new key should be +defined. + +To move a menu option from one position to another, simply evaluate +@code{define-key-after} with the appropriate final argument. + +More detailed information---and more examples of how to create and +modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under +``Menu Keymaps.'' (@xref{Emacs Lisp documentation}, for information on +this manual.) + +@node Deleting menus and menu options, Turning on syntax highlighting, Modifying pull-down menus, Common requests +@section How do I delete menus and menu options? +@cindex Deleting menus and menu options +@cindex Menus, deleting + +The simplest way to remove a menu is to set its keymap to @samp{nil}. +For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down +menus}), use: + +@lisp +(define-key global-map [menu-bar words] nil) +@end lisp + +Similarly, removing a menu option requires redefining a keymap entry to +@code{nil}. For example, to delete the @samp{Forward word} menu option +from the @samp{Edit} menu (we added it in @ref{Modifying pull-down +menus}), use: + +@lisp +(define-key global-map [menu-bar edit forward] nil) +@end lisp + +@node Turning on syntax highlighting, Scrolling only one line, Deleting menus and menu options, Common requests +@section How do I turn on syntax highlighting? +@cindex Syntax highlighting +@cindex @code{font-lock-mode} +@cindex Highlighting based on syntax +@cindex Colorizing text +@cindex FAQ, @code{font-lock-mode} + +@code{font-lock-mode} is the standard way to have Emacs perform syntax +highlighting in the current buffer. It is enabled by default in Emacs +22.1 and later. + +With @code{font-lock-mode} turned on, different types of text will +appear in different colors. For instance, in a programming mode, +variables will appear in one face, keywords in a second, and comments in +a third. + +@cindex hilit19 is deprecated +Earlier versions of Emacs supported hilit19, a similar package. Use of +hilit19 is now considered non-standard, although @file{hilit19.el} comes +with the stock Emacs distribution. It is no longer maintained. + +To turn @code{font-lock-mode} off within an existing buffer, use +@kbd{M-x font-lock-mode @key{RET}}. + +In Emacs 21 and earlier versions, you could use the following code in +your @file{.emacs} file to turn on @code{font-lock-mode} globally: + +@lisp +(global-font-lock-mode 1) +@end lisp + +Highlighting a buffer with @code{font-lock-mode} can take quite a while, +and cause an annoying delay in display, so several features exist to +work around this. + +@cindex Just-In-Time syntax highlighting +In Emacs 21 and later, turning on @code{font-lock-mode} automatically +activates the new @dfn{Just-In-Time fontification} provided by +@code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of +portions of buffer until you actually need to see them, and can also +fontify while Emacs is idle. This makes display of the visible portion +of a buffer almost instantaneous. For details about customizing +@code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}. + +@cindex Levels of syntax highlighting +@cindex Decoration level, in @code{font-lock-mode} +In versions of Emacs before 21, different levels of decoration are +available, from slight to gaudy. More decoration means you need to wait +more time for a buffer to be fontified (or a faster machine). To +control how decorated your buffers should become, set the value of +@code{font-lock-maximum-decoration} in your @file{.emacs} file, with a +@code{nil} value indicating default (usually minimum) decoration, and a +@code{t} value indicating the maximum decoration. For the gaudiest +possible look, then, include the line + +@lisp +(setq font-lock-maximum-decoration t) +@end lisp + +@noindent +in your @file{.emacs} file. You can also set this variable such that +different modes are highlighted in a different ways; for more +information, see the documentation for +@code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x +describe-variable @key{RET}}). + +Also see the documentation for the function @code{font-lock-mode}, +available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x +describe-function @key{RET} font-lock-mode @key{RET}}). + +To print buffers with the faces (i.e., colors and fonts) intact, use +@kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x +ps-print-region-with-faces}. You will need a way to send text to a +PostScript printer, or a PostScript interpreter such as Ghostscript; +consult the documentation of the variables @code{ps-printer-name}, +@code{ps-lpr-command}, and @code{ps-lpr-switches} for more details. + +@node Scrolling only one line, Editing MS-DOS files, Turning on syntax highlighting, Common requests +@section How can I force Emacs to scroll only one line when I move past the bottom of the screen? +@cindex Scrolling only one line +@cindex Reducing the increment when scrolling + +Customize the @code{scroll-conservatively} variable with @kbd{M-x +customize-variable @key{RET} scroll-conservatively @key{RET}} and set it +to a large value like, say, 10000. For an explanation of what this +means, @inforef{Auto Scrolling, Auto Scrolling, emacs}. + +Alternatively, use the following Lisp form in your @file{.emacs}: + +@lisp +(setq scroll-conservatively most-positive-fixnum) +@end lisp + +@node Editing MS-DOS files, Filling paragraphs with a single space, Scrolling only one line, Common requests +@section How can I edit MS-DOS files using Emacs? +@cindex Editing MS-DOS files +@cindex MS-DOS files, editing +@cindex Microsoft files, editing +@cindex Windows files, editing + +As of Emacs 20, detection and handling of MS-DOS (and Windows) files is +performed transparently. You can open MS-DOS files on a Unix system, +edit it, and save it without having to worry about the file format. + +When editing an MS-DOS style file, the mode line will indicate that it +is a DOS file. On Unix and GNU/Linux systems, and also on a Macintosh, +the string @samp{(DOS)} will appear near the left edge of the mode line; +on DOS and Windows, where the DOS end-of-line (EOL) format is the +default, a backslash (@samp{\}) will appear in the mode line. + +If you are running a version of Emacs before 20.1, get @code{crypt++} +(@pxref{Packages that do not come with Emacs}). Among other things, +@code{crypt++} transparently modifies MS-DOS files as they are loaded +and saved, allowing you to ignore the different conventions that Unix +and MS-DOS have for delineating the end of a line. + +@node Filling paragraphs with a single space, Escape sequences in shell output, Editing MS-DOS files, Common requests +@section How can I tell Emacs to fill paragraphs with a single space after each period? +@cindex One space following periods +@cindex Single space following periods +@cindex Periods, one space following + +Add the following line to your @file{.emacs} file: + +@lisp +(setq sentence-end-double-space nil) +@end lisp + +@node Escape sequences in shell output, Fullscreen mode on MS-Windows, Filling paragraphs with a single space, Common requests +@section Why these strange escape sequences from @code{ls} from the Shell mode? +@cindex Escape sequences in @code{ls} output +@cindex @code{ls} in Shell mode + +This happens because @code{ls} is aliased to @samp{ls --color} in your +shell init file. You have two alternatives to solve this: + +@itemize @bullet +@item +Make the alias conditioned on the @code{EMACS} variable in the +environment. When Emacs runs a subsidiary shell, it exports the +@code{EMACS} variable to that shell, with value equal to the absolute +file name of Emacs. You can +unalias @code{ls} when that happens, thus limiting the alias to your +interactive sessions. + +@item +Install the @code{ansi-color} package (bundled with Emacs 21.1 and +later), which converts these ANSI escape sequences into colors. +@end itemize + +@node Fullscreen mode on MS-Windows, , Escape sequences in shell output, Common requests +@section How can I start Emacs in fullscreen mode on MS-Windows? +@cindex Maximize frame +@cindex Fullscreen mode + +Use the function @code{w32-send-sys-command}. For example, you can +put the following in your @file{.emacs} file: + +@lisp +(add-hook 'term-setup-hook + #'(lambda () (w32-send-sys-command ?\xF030))) +@end lisp + +To avoid the slightly distracting visual effect of Emacs starting with +its default frame size and then growing to fullscreen, you can add an +@samp{Emacs.Geometry} entry to the Windows registry settings (see +@pxref{(emacs)X Resources}). + +To compute the correct values for width and height, first maximize the +Emacs frame and then evaluate @code{(frame-height)} and +@code{(frame-width)} with @kbd{M-:}. + +@c ------------------------------------------------------------ +@node Bugs and problems, Compiling and installing Emacs, Common requests, Top +@chapter Bugs and problems +@cindex Bugs and problems + +The Emacs manual lists some common kinds of trouble users could get +into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU +Emacs Manual}, so you might look there if the problem you encounter +isn't described in this chapter. If you decide you've discovered a bug, +see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for +instructions how to do that. + +The file @file{etc/PROBLEMS} in the Emacs distribution lists various +known problems with building and using Emacs on specific platforms; +type @kbd{C-h C-e} to read it. + +@menu +* Problems with very large files:: +* ^M in the shell buffer:: +* Shell process exits abnormally:: +* Problems with Shell Mode on MS-Windows:: +* Termcap/Terminfo entries for Emacs:: +* Spontaneous entry into isearch-mode:: +* Problems talking to certain hosts:: +* Errors with init files:: +* Emacs ignores X resources:: +* Emacs ignores frame parameters:: +* Emacs takes a long time to visit files:: +* Editing files with $ in the name:: +* Shell mode loses the current directory:: +* Security risks with Emacs:: +* Dired claims that no file is on this line:: +@end menu + +@node Problems with very large files, ^M in the shell buffer, Bugs and problems, Bugs and problems +@section Does Emacs have problems with files larger than 8 megabytes? +@cindex Very large files, opening +@cindex Large files, opening +@cindex Opening very large files +@cindex Maximum file size +@cindex Files, maximum size + +Old versions (i.e., anything before 19.29) of Emacs had problems editing +files larger than 8 megabytes. In versions 19.29 and later, the maximum +buffer size is at least 2^27-1, or 134,217,727 bytes, or 132 MBytes. +And in Emacs 22, the maximum buffer size has been increased to +268,435,455 bytes (or 256 MBytes) on 32-bit machines. + +@node ^M in the shell buffer, Shell process exits abnormally, Problems with very large files, Bugs and problems +@section How do I get rid of @samp{^M} or echoed commands in my shell buffer? +@cindex Shell buffer, echoed commands and @samp{^M} in +@cindex Echoed commands in @code{shell-mode} + +Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to +make them go away. If that doesn't work, you have several options: + +For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc}) +file: + +@example +if ($?EMACS) then + if ("$EMACS" =~ /*) then + if ($?tcsh) unset edit + stty nl + endif +endif +@end example + +Or put this in your @file{.emacs_tcsh} or @file{~/.emacs.d/init_tcsh.sh} file: + +@example +unset edit +stty nl +@end example + +Alternatively, use @code{csh} in your shell buffers instead of +@code{tcsh}. One way is: + +@lisp +(setq explicit-shell-file-name "/bin/csh") +@end lisp + +@noindent +and another is to do this in your @file{.cshrc} (or @file{.tcshrc}) +file: + +@example +setenv ESHELL /bin/csh +@end example + +@noindent +(You must start Emacs over again with the environment variable properly +set for this to take effect.) + +You can also set the @code{ESHELL} environment variable in Emacs Lisp +with the following Lisp form, + +@lisp +(setenv "ESHELL" "/bin/csh") +@end lisp + +The above solutions try to prevent the shell from producing the +@samp{^M} characters in the first place. If this is not possible +(e.g., if you use a Windows shell), you can get Emacs to remove these +characters from the buffer by adding this to your @file{.emacs} init +file: + +@smalllisp +(add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m) +@end smalllisp + +On a related note: if your shell is echoing your input line in the shell +buffer, you might want to customize the @code{comint-process-echoes} +variable in your shell buffers, or try the following command in your +shell start-up file: + +@example +stty -icrnl -onlcr -echo susp ^Z +@end example + +@node Shell process exits abnormally, Problems with Shell Mode on MS-Windows, ^M in the shell buffer, Bugs and problems +@section Why do I get ``Process shell exited abnormally with code 1''? +@cindex Abnormal exits from @code{shell-mode} +@cindex @code{shell-mode} exits +@cindex Process shell exited + +The most likely reason for this message is that the @samp{env} program +is not properly installed. Compile this program for your architecture, +and install it with @samp{a+x} permission in the architecture-dependent +Emacs program directory. (You can find what this directory is at your +site by inspecting the value of the variable @code{exec-directory} by +typing @kbd{C-h v exec-directory @key{RET}}.) + +You should also check for other programs named @samp{env} in your path +(e.g., SunOS has a program named @file{/usr/bin/env}). We don't +understand why this can cause a failure and don't know a general +solution for working around the problem in this case. + +The @samp{make clean} command will remove @samp{env} and other vital +programs, so be careful when using it. + +It has been reported that this sometimes happened when Emacs was started +as an X client from an xterm window (i.e., had a controlling tty) but the +xterm was later terminated. + +See also @samp{PROBLEMS} (in the @file{etc} subdirectory of the +top-level directory when you unpack the Emacs source) for other +possible causes of this message. + +@node Problems with Shell Mode on MS-Windows, Termcap/Terminfo entries for Emacs, Shell process exits abnormally, Bugs and problems +@section Why do I get an error message when I try to run @kbd{M-x shell}? + +@cindex Shell Mode, and MS-Windows +@cindex @code{explicit-shell-file-name} +On MS-Windows, this might happen because Emacs tries to look for the +shell in a wrong place. The default file name @file{/bin/sh} is +usually incorrect for non-Unix systems. If you know where your shell +executable is, set the variable @code{explicit-shell-file-name} in +your @file{.emacs} file to point to its full file name, like this: + +@lisp +(setq explicit-shell-file-name "d:/shells/bash.exe") +@end lisp + +If you don't know what shell does Emacs use, try the @kbd{M-!} +command; if that works, put the following line into your +@file{.emacs}: + +@lisp +(setq explicit-shell-file-name shell-file-name) +@end lisp + +@cindex Antivirus programs, and Shell Mode +Some people have trouble with Shell Mode because of intrusive +antivirus software; disabling the resident antivirus program solves +the problems in those cases. + +@node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Problems with Shell Mode on MS-Windows, Bugs and problems +@section Where is the termcap/terminfo entry for terminal type @samp{emacs}? +@cindex Termcap +@cindex Terminfo +@cindex Emacs entries for termcap/terminfo + +The termcap entry for terminal type @samp{emacs} is ordinarily put in +the @samp{TERMCAP} environment variable of subshells. It may help in +certain situations (e.g., using rlogin from shell buffer) to add an +entry for @samp{emacs} to the system-wide termcap file. Here is a +correct termcap entry for @samp{emacs}: + +@example +emacs:tc=unknown: +@end example + +To make a terminfo entry for @samp{emacs}, use @code{tic} or +@code{captoinfo}. You need to generate +@file{/usr/lib/terminfo/e/emacs}. It may work to simply copy +@file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}. + +Having a termcap/terminfo entry will not enable the use of full screen +programs in shell buffers. Use @kbd{M-x terminal-emulator} for that +instead. + +A workaround to the problem of missing termcap/terminfo entries is to +change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown} +in your shell start up file. @code{csh} users could put this in their +@file{.cshrc} files: + +@example +if ("$term" == emacs) set term=dumb +@end example + +@node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems +@section Why does Emacs spontaneously start displaying @samp{I-search:} and beeping? +@cindex Spontaneous entry into isearch-mode +@cindex isearch-mode, spontaneous entry into +@cindex Beeping without obvious reason + +Your terminal (or something between your terminal and the computer) is +sending @kbd{C-s} and @kbd{C-q} for flow control, and Emacs is receiving +these characters and interpreting them as commands. (The @kbd{C-s} +character normally invokes the @code{isearch-forward} command.) For +possible solutions, see @ref{Handling C-s and C-q with flow control}. + +@node Problems talking to certain hosts, Errors with init files, Spontaneous entry into isearch-mode, Bugs and problems +@section Why can't Emacs talk to certain hosts (or certain hostnames)? +@cindex Hosts, Emacs cannot talk to +@cindex @code{gethostbyname}, problematic version + +The problem may be that Emacs is linked with a wimpier version of +@code{gethostbyname} than the rest of the programs on the machine. This +is often manifested as a message on startup of ``X server not responding. +Check your @samp{DISPLAY} environment variable.'' or a message of +``Unknown host'' from @code{open-network-stream}. + +On a Sun, this may be because Emacs had to be linked with the static C +library. The version of @code{gethostbyname} in the static C library +may only look in @file{/etc/hosts} and the NIS (YP) maps, while the +version in the dynamic C library may be smart enough to check DNS in +addition to or instead of NIS. On a Motorola Delta running System V +R3.6, the version of @code{gethostbyname} in the standard library works, +but the one that works with NIS doesn't (the one you get with -linet). +Other operating systems have similar problems. + +Try these options: + +@itemize @bullet + +@item +Explicitly add the host you want to communicate with to @file{/etc/hosts}. + +@item +Relink Emacs with this line in @file{src/config.h}: + +@example +#define LIBS_SYSTEM -lresolv +@end example + +@item +Replace @code{gethostbyname} and friends in @file{libc.a} with more +useful versions such as the ones in @file{libresolv.a}. Then relink +Emacs. + +@item +If you are actually running NIS, make sure that @code{ypbind} is +properly told to do DNS lookups with the correct command line switch. + +@end itemize + +@node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems +@section Why does Emacs say @samp{Error in init file}? +@cindex Error in @file{.emacs} +@cindex Error in init file +@cindex Init file, errors in +@cindex @file{.emacs} file, errors in +@cindex Debugging @file{.emacs} file + +An error occurred while loading either your @file{.emacs} file or the +system-wide file @file{lisp/default.el}. Emacs 21.1 and later pops the +@file{*Messages*} buffer, and puts there some additional information +about the error, to provide some hints for debugging. + +For information on how to debug your @file{.emacs} file, see +@ref{Debugging a customization file}. + +It may be the case that you need to load some package first, or use a +hook that will be evaluated after the package is loaded. A common case +of this is explained in @ref{Terminal setup code works after Emacs has +begun}. + +@node Emacs ignores X resources, Emacs ignores frame parameters, Errors with init files, Bugs and problems +@section Why does Emacs ignore my X resources (my .Xdefaults file)? +@cindex X resources being ignored +@cindex Ignored X resources +@cindex @file{.Xdefaults} + +As of version 19, Emacs searches for X resources in the files specified +by the following environment variables: + +@itemize @bullet + +@item @code{XFILESEARCHPATH} +@item @code{XUSERFILESEARCHPATH} +@item @code{XAPPLRESDIR} + +@end itemize + +This emulates the functionality provided by programs written using the +Xt toolkit. + +@code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list +of file names separated by colons. @code{XAPPLRESDIR} should be a list +of directory names separated by colons. + +Emacs searches for X resources: + +@enumerate + +@item +specified on the command line, with the @samp{-xrm RESOURCESTRING} option, + +@item +then in the value of the @samp{XENVIRONMENT} environment variable, + +@itemize @minus + +@item +or if that is unset, in the file named +@file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is +the name of the machine Emacs is running on), + +@end itemize + +@item +then in the screen-specific and server-wide resource properties provided +by the server, + +@itemize @minus + +@item +or if those properties are unset, in the file named @file{~/.Xdefaults} +if it exists, + +@end itemize + +@item +then in the files listed in @samp{XUSERFILESEARCHPATH}, + +@itemize @minus + +@item +or in files named @file{@var{lang}/Emacs} in directories listed in +@samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG} +environment variable), if the @samp{LANG} environment variable is set, +@item +or in files named Emacs in the directories listed in @samp{XAPPLRESDIR} +@item +or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable +is set), +@item +or in @file{~/Emacs}, + +@end itemize + +@item +then in the files listed in @code{XFILESEARCHPATH}. + +@end enumerate + +@node Emacs ignores frame parameters, Emacs takes a long time to visit files, Emacs ignores X resources, Bugs and problems +@section Why don't my customizations of the frame parameters work? +@cindex Frame parameters + +This probably happens because you have set the frame parameters in the +variable @code{initial-frame-alist}. That variable holds parameters +used only for the first frame created when Emacs starts. To customize +the parameters of all frames, change the variable +@code{default-frame-alist} instead. + +These two variables exist because many users customize the initial frame +in a special way. For example, you could determine the position and +size of the initial frame, but would like to control the geometry of the +other frames by individually positioning each one of them. + + +@node Emacs takes a long time to visit files, Editing files with $ in the name, Emacs ignores frame parameters, Bugs and problems +@section Why does Emacs take 20 seconds to visit a file? +@cindex Visiting files takes a long time +@cindex Delay when visiting files +@cindex Files, take a long time to visit + +Old versions of Emacs (i.e., versions before Emacs 20.x) often +encountered this when the master lock file, @file{!!!SuperLock!!!}, has +been left in the lock directory somehow. Delete it. + +@email{meuer@@geom.umn.edu, Mark Meuer} says that NeXT NFS has a bug +where an exclusive create succeeds but returns an error status. This +can cause the same problem. Since Emacs's file locking doesn't work +over NFS anyway, the best solution is to recompile Emacs with +@code{CLASH_DETECTION} undefined. + +@node Editing files with $ in the name, Shell mode loses the current directory, Emacs takes a long time to visit files, Bugs and problems +@section How do I edit a file with a @samp{$} in its name? +@cindex Editing files with @samp{$} in the name +@cindex @samp{$} in file names +@cindex File names containing @samp{$}, editing + +When entering a file name in the minibuffer, Emacs will attempt to expand +a @samp{$} followed by a word as an environment variable. To suppress +this behavior, type @kbd{$$} instead. + +@node Shell mode loses the current directory, Security risks with Emacs, Editing files with $ in the name, Bugs and problems +@section Why does shell mode lose track of the shell's current directory? +@cindex Current directory and @code{shell-mode} +@cindex @code{shell-mode} and current directory +@cindex Directory, current in @code{shell-mode} + +Emacs has no way of knowing when the shell actually changes its +directory. This is an intrinsic limitation of Unix. So it tries to +guess by recognizing @samp{cd} commands. If you type @kbd{cd} followed +by a directory name with a variable reference (@kbd{cd $HOME/bin}) or +with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to +correctly guess the shell's new current directory. A huge variety of +fixes and enhancements to shell mode for this problem have been written +to handle this problem (@pxref{Finding a package with particular +functionality}). + +You can tell Emacs the shell's current directory with the command +@kbd{M-x dirs}. + +@node Security risks with Emacs, Dired claims that no file is on this line, Shell mode loses the current directory, Bugs and problems +@section Are there any security risks in Emacs? +@cindex Security with Emacs +@cindex @samp{movemail} and security +@cindex @code{file-local-variable} and security +@cindex Synthetic X events and security +@cindex X events and security + +@itemize @bullet + +@item +The @file{movemail} incident. (No, this is not a risk.) + +In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in +chapter 4. The site at LBL had installed the @file{/etc/movemail} +program setuid root. (As of version 19, @file{movemail} is in your +architecture-specific directory; type @kbd{C-h v exec-directory +@key{RET}} to see what it is.) Since @code{movemail} had not been +designed for this situation, a security hole was created and users could +get root privileges. + +@code{movemail} has since been changed so that this security hole will +not exist, even if it is installed setuid root. However, +@code{movemail} no longer needs to be installed setuid root, which +should eliminate this particular risk. + +We have heard unverified reports that the 1988 Internet worm took +advantage of this configuration problem. + +@item +The @code{file-local-variable} feature. (Yes, a risk, but easy to +change.) + +There is an Emacs feature that allows the setting of local values for +variables when editing a file by including specially formatted text near +the end of the file. This feature also includes the ability to have +arbitrary Emacs Lisp code evaluated when the file is visited. +Obviously, there is a potential for Trojan horses to exploit this +feature. + +As of Emacs 22, Emacs has a list of local variables that are known to +be safe to set. If a file tries to set any variable outside this +list, it asks the user to confirm whether the variables should be set. +You can also tell Emacs whether to allow the evaluation of Emacs Lisp +code found at the bottom of files by setting the variable +@code{enable-local-eval}. + +For more information, @inforef{File Variables, File Variables, emacs}. + +@item +Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or +better.) + +Emacs accepts synthetic X events generated by the @code{SendEvent} +request as though they were regular events. As a result, if you are +using the trivial host-based authentication, other users who can open X +connections to your X workstation can make your Emacs process do +anything, including run other processes with your privileges. + +The only fix for this is to prevent other users from being able to open +X connections. The standard way to prevent this is to use a real +authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using +the @code{xauth} program has any effect, then you are probably using +@samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior +authentication method; ask your system administrator. + +If real authentication is not a possibility, you may be satisfied by +just allowing hosts access for brief intervals while you start your X +programs, then removing the access. This reduces the risk somewhat by +narrowing the time window when hostile users would have access, but +@emph{does not eliminate the risk}. + +On most computers running Unix and X, you enable and disable +access using the @code{xhost} command. To allow all hosts access to +your X server, use + +@example +xhost + +@end example + +@noindent +at the shell prompt, which (on an HP machine, at least) produces the +following message: + +@example +access control disabled, clients can connect from any host +@end example + +To deny all hosts access to your X server (except those explicitly +allowed by name), use + +@example +xhost - +@end example + +On the test HP computer, this command generated the following message: + +@example +access control enabled, only authorized clients can connect +@end example + +@end itemize + +@node Dired claims that no file is on this line, , Security risks with Emacs, Bugs and problems +@section Dired says, @samp{no file on this line} when I try to do something. +@cindex Dired does not see a file + +@c FIXME: I think this is fixed in Emacs 21, but I didn't have time to +@c check. +Chances are you're using a localized version of Unix that doesn't use US +date format in dired listings. You can check this by looking at dired +listings or by typing @kbd{ls -l} to a shell and looking at the dates that +come out. + +Dired uses a regular expression to find the beginning of a file name. +In a long Unix-style directory listing (@samp{ls -l}), the file name +starts after the date. The regexp has thus been written to look for the +date, the format of which can vary on non-US systems. + +There are two approaches to solving this. The first one involves +setting things up so that @samp{ls -l} outputs US date format. This can +be done by setting the locale. See your OS manual for more information. + +The second approach involves changing the regular expression used by +dired, @code{directory-listing-before-filename-regexp}. + +@c ------------------------------------------------------------ +@node Compiling and installing Emacs, Finding Emacs and related packages, Bugs and problems, Top +@chapter Compiling and installing Emacs +@cindex Compiling and installing Emacs + +@menu +* Installing Emacs:: +* Updating Emacs:: +* Problems building Emacs:: +* Linking with -lX11 fails:: +@end menu + +@node Installing Emacs, Updating Emacs, Compiling and installing Emacs, Compiling and installing Emacs +@section How do I install Emacs? +@cindex Installing Emacs +@cindex Unix systems, installing Emacs on +@cindex Downloading and installing Emacs +@cindex Retrieving and installing Emacs +@cindex Building Emacs from source +@cindex Source code, building Emacs from +@cindex Unpacking and installing Emacs + +This answer is meant for users of Unix and Unix-like systems. Users of +other operating systems should see the series of questions beginning +with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source +and binaries, and how to install Emacs on those systems. + +For Unix and Unix-like systems, the easiest way is often to compile it +from scratch. You will need: + +@itemize @bullet + +@item +Emacs sources. @xref{Current GNU distributions}, for a list of ftp sites +that make them available. On @file{ftp.gnu.org}, the main GNU +distribution site, sources are available as + +@uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-@value{VER}.tar.gz} + +The above will obviously change as new versions of Emacs come out. For +instance, when Emacs 22.42 is released, it will most probably be +available as + +@uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-22.42.tar.gz} + +Again, you should use one of the GNU mirror sites (see @ref{Current GNU +distributions}, and adjust the URL accordingly) so as to reduce load on +@file{ftp.gnu.org}. + +@item +@code{gzip}, the GNU compression utility. You can get @code{gzip} via +anonymous ftp at mirrors of @file{ftp.gnu.org} sites; it should compile +and install without much trouble on most systems. Once you have +retrieved the Emacs sources, you will probably be able to uncompress +them with the command + +@example +gunzip --verbose emacs-@value{VER}.tar.gz +@end example + +@noindent +changing the Emacs version (@value{VER}), as necessary. Once +@code{gunzip} has finished doing its job, a file by the name of +@file{emacs-@value{VER}.tar} should be in your build directory. + +@item +@code{tar}, the @dfn{tape archiving} program, which moves multiple files +into and out of archive files, or @dfn{tarfiles}. All of the files +comprising the Emacs source come in a single tarfile, and must be +extracted using @code{tar} before you can build Emacs. Typically, the +extraction command would look like + +@example +tar -xvvf emacs-@value{VER}.tar +@end example + +@noindent +The @samp{x} indicates that we want to extract files from this tarfile, +the two @samp{v}s force verbose output, and the @samp{f} tells +@code{tar} to use a disk file, rather than one on the tape drive. + +If you're using GNU @code{tar} (available at mirrors of +@file{ftp.gnu.org}), you can combine this step and the previous one by +using the command + +@example +tar -zxvvf emacs-@value{VER}.tar.gz +@end example + +@noindent +The additional @samp{z} at the beginning of the options list tells GNU +@code{tar} to uncompress the file with @code{gunzip} before extracting +the tarfile's components. + +@end itemize + +At this point, the Emacs sources (all 70+ megabytes of them) should be +sitting in a directory called @file{emacs-@value{VER}}. On most common +Unix and Unix-like systems, you should be able to compile Emacs (with X +Window system support) with the following commands: + +@example +cd emacs-@value{VER} # change directory to emacs-@value{VER} +./configure # configure Emacs for your particular system +make # use Makefile to build components, then Emacs +@end example + +If the @code{make} completes successfully, the odds are fairly good that +the build has gone well. (@xref{Problems building Emacs}, if you weren't +successful.) + +By default, Emacs is installed in the following directories: + +@table @file +@item /usr/local/bin +binaries. + +@item /usr/local/share/emacs/@value{VER} +Lisp code and support files. + +@item /usr/local/info +Info documentation. +@end table + +To install files in those default directories, become the superuser and +type + +@example +make install +@end example + +Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs} +and any Emacs Info files that might be in @file{/usr/local/info}. + +Much more verbose instructions (with many more hints and suggestions) +come with the Emacs sources, in the file @file{INSTALL}. + +@node Updating Emacs, Problems building Emacs, Installing Emacs, Compiling and installing Emacs +@section How do I update Emacs to the latest version? +@cindex Updating Emacs + +@xref{Installing Emacs}, and follow the instructions there for +installation. + +Most files are placed in version-specific directories. Emacs +@value{VER}, for instance, places files in +@file{/usr/local/share/emacs/@value{VER}}. + +Upgrading should overwrite only, @file{/usr/local/bin/emacs} (the Emacs +binary) and documentation in @file{/usr/local/info}. Back up these +files before you upgrade, and you shouldn't have too much trouble. + +@node Problems building Emacs, Linking with -lX11 fails, Updating Emacs, Compiling and installing Emacs +@section What should I do if I have trouble building Emacs? +@cindex Problems building Emacs +@cindex Errors when building Emacs + +First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs +source) to see if there is already a solution for your problem. Next, +look for other questions in this FAQ that have to do with Emacs +installation and compilation problems. + +If you'd like to have someone look at your problem and help solve it, +see @ref{Help installing Emacs}. + +If you cannot find a solution in the documentation, send a message to +@email{bug-gnu-emacs@@gnu.org}. + +Please don't post it to @uref{news:gnu.emacs.help} or send e-mail to +@email{help-gnu-emacs@@gnu.org}. For further guidelines, see +@ref{Guidelines for newsgroup postings} and @ref{Reporting bugs}. + +@node Linking with -lX11 fails, , Problems building Emacs, Compiling and installing Emacs +@section Why does linking Emacs with -lX11 fail? +@cindex Linking with -lX11 fails +@cindex lX11, linking fails with + +Emacs needs to be linked with the static version of the X11 library, +@file{libX11.a}. This may be missing. + +On OpenWindows, you may need to use @code{add_services} to add the +``OpenWindows Programmers'' optional software category from the CD-ROM. + +On HP-UX 8.0, you may need to run @code{update} again to load the +X11-PRG ``fileset.'' This may be missing even if you specified ``all +filesets'' the first time. If @file{libcurses.a} is missing, you may +need to load the ``Berkeley Development Option.'' + +@email{zoo@@armadillo.com, David Zuhn} says that MIT X builds shared +libraries by default, and only shared libraries, on those platforms that +support them. These shared libraries can't be used when undumping +@code{temacs} (the last stage of the Emacs build process). To get +regular libraries in addition to shared libraries, add this to +@file{site.cf}: + +@example +#define ForceNormalLib YES +@end example + +Other systems may have similar problems. You can always define +@code{CANNOT_DUMP} and link with the shared libraries instead. + +@cindex X Menus don't work +To get the Xmenu stuff to work, you need to find a copy of MIT's +@file{liboldX.a}. + +@c ------------------------------------------------------------ +@node Finding Emacs and related packages, Major packages and programs, Compiling and installing Emacs, Top +@chapter Finding Emacs and related packages +@cindex Finding Emacs and related packages + +@menu +* Finding Emacs on the Internet:: +* Finding a package with particular functionality:: +* Packages that do not come with Emacs:: +* Current GNU distributions:: +* Difference between Emacs and XEmacs:: +* Emacs for MS-DOS:: +* Emacs for Windows:: +* Emacs for OS/2:: +* Emacs for Atari ST:: +* Emacs for the Amiga :: +* Emacs for NeXTSTEP:: +* Emacs for Apple computers:: +* Emacs for VMS and DECwindows:: +* Modes for various languages:: +@end menu + +@node Finding Emacs on the Internet, Finding a package with particular functionality, Finding Emacs and related packages, Finding Emacs and related packages +@section Where can I get Emacs on the net (or by snail mail)? +@cindex Finding Emacs on the Internet +@cindex Snail mail, ordering Emacs via +@cindex Postal service, ordering Emacs via +@cindex Distribution, retrieving Emacs +@cindex Internet, retrieving from + +Look in the files @file{etc/DISTRIB} and @file{etc/FTP} for +information on nearby archive sites. If you don't already have Emacs, +see @ref{Informational files for Emacs}, for how to get these files. + +@xref{Installing Emacs}, for information on how to obtain and build the latest +version of Emacs, and see @ref{Current GNU distributions}, for a list of +archive sites that make GNU software available. + +@node Finding a package with particular functionality, Packages that do not come with Emacs, Finding Emacs on the Internet, Finding Emacs and related packages +@section How do I find a Emacs Lisp package that does XXX? +@cindex Package, finding +@cindex Finding an Emacs Lisp package +@cindex Functionality, finding a particular package + +First of all, you should check to make sure that the package isn't +already available. For example, typing @kbd{M-x apropos @key{RET} +wordstar @key{RET}} lists all functions and variables containing the +string @samp{wordstar}. + +It is also possible that the package is on your system, but has not been +loaded. To see which packages are available for loading, look through +your computer's lisp directory (@pxref{File-name conventions}). The Lisp +source to most packages contains a short description of how they +should be loaded, invoked, and configured---so before you use or +modify a Lisp package, see if the author has provided any hints in the +source code. + +The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse +the constituent Emacs packages. + +For advice on how to find extra packages that are not part of Emacs, +see @ref{Packages that do not come with Emacs}. + +@node Packages that do not come with Emacs, Current GNU distributions, Finding a package with particular functionality, Finding Emacs and related packages +@section Where can I get Emacs Lisp packages that don't come with Emacs? +@cindex Unbundled packages +@cindex Finding other packages +@cindex Lisp packages that do not come with Emacs +@cindex Packages, those that do not come with Emacs +@cindex Emacs Lisp List +@cindex Emacs Lisp Archive + +@uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.html, The Emacs Lisp +List (ELL)}, maintained by @email{stephen@@anc.ed.ac.uk, Stephen Eglen}, +aims to provide one compact list with links to all of the current Emacs +Lisp files on the Internet. The ELL can be browsed over the web, or +from Emacs with @uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.el, +the @file{ell} package}. + +Many authors post their packages to the @uref{news:gnu.emacs.sources, +Emacs sources newsgroup}. You can search the archives of this +group with @uref{http://groups.google.com/group/gnu.emacs.sources, Google}, +or @uref{http://dir.gmane.org/gmane.emacs.sources, Gmane}, for example. + +Several packages are stored in +@uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}. + +For a long time, the Emacs Lisp Archive provided a central repository +for Emacs packages. Sadly, it has not been active for some time, +although you can still access the old files at + +@uref{http://www.club.cc.cmu.edu/pub/gnu/elisp-archive/} + +Read the file @file{etc/MORE.STUFF} for more information about +external packages. + +@node Current GNU distributions, Difference between Emacs and XEmacs, Packages that do not come with Emacs, Finding Emacs and related packages +@section Where can I get other up-to-date GNU stuff? +@cindex Current GNU distributions +@cindex Sources for current GNU distributions +@cindex Stuff, current GNU +@cindex Up-to-date GNU stuff +@cindex Finding current GNU software +@cindex Official GNU software sites + +The most up-to-date official GNU software is normally kept at + +@uref{ftp://ftp.gnu.org/pub/gnu} + +Read the files @file{etc/DISTRIB} and @file{etc/FTP} for more +information. + +A list of sites mirroring @samp{ftp.gnu.org} can be found at + +@uref{http://www.gnu.org/order/ftp.html} + +@node Difference between Emacs and XEmacs, Emacs for MS-DOS, Current GNU distributions, Finding Emacs and related packages +@section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)? +@cindex XEmacs +@cindex Difference Emacs and XEmacs +@cindex Lucid Emacs +@cindex Epoch + +XEmacs is a branch version of Emacs. It was first called Lucid Emacs, +and was initially derived from a prerelease version of Emacs 19. In +this FAQ, we use the name ``Emacs'' only for the official version. + +Emacs and XEmacs each come with Lisp packages that are lacking in the +other. The two versions have some significant differences at the Lisp +programming level. Their current features are roughly comparable, +though the support for some operating systems, character sets and +specific packages might be quite different. + +Some XEmacs code has been contributed to Emacs, and we would like to +use other parts, but the earlier XEmacs maintainers did not always +keep track of the authors of contributed code, which makes it +impossible for the FSF to get copyright papers signed for that code. +(The FSF requires these papers for all the code included in the Emacs +release, aside from generic C support packages that retain their +separate identity and are not integrated into the code of Emacs +proper.) + +If you want to talk about these two versions and distinguish them, +please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs'' +with ``GNU Emacs'' would be misleading, since XEmacs too has its +origin in the work of the GNU Project. Terms such as ``Emacsen'' and +``(X)Emacs'' are not wrong, but they are not very clear, so it +is better to write ``Emacs and XEmacs.'' + +@node Emacs for MS-DOS, Emacs for Windows, Difference between Emacs and XEmacs, Finding Emacs and related packages +@section Where can I get Emacs for my PC running MS-DOS? +@cindex MS-DOS, Emacs for +@cindex DOS, Emacs for +@cindex Compiling Emacs for DOS +@cindex Emacs for MS-DOS +@cindex Tools needed to compile Emacs under DOS + +A pre-built binary distribution of Emacs is available from the +SimTel.NET archives. This version apparently works under MS-DOS and +Windows (3.X, 9X, ME, NT, and 2000) and supports long file names under +Windows 9X, Windows ME, and Windows 2000. More information is available +from + +@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/emacs.README} + +The binary itself is available in the files @file{em*.zip} in the +directory + +@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/} + +If you prefer to compile Emacs for yourself, you can do so with the +current distribution directly. You will need a 386 (or +better) processor, and to be running MS-DOS 3.0 or later. According to +@email{eliz@@gnu.org, Eli Zaretskii} and +@email{hankedr@@dms.auburn.edu, Darrel Hankerson}, you will need the +following: + +@table @emph + +@item Compiler +DJGPP version 1.12 maint 1 or later. Djgpp 2.0 or later is +recommended, since 1.x is very old an unmaintained. Djgpp 2 supports +long file names on Windows 9X/ME/2K. + +You can get the latest release of DJGPP by retrieving all of +the files in + +@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2*} + +@item Unpacking program +The easiest way is to use @code{djtar} which comes with DJGPP v2.x, +because it can open gzip'ed tarfiles (i.e., those ending with +@file{.tar.gz}) in one step. @code{Djtar} comes in +@file{djdev@var{nnn}.zip} archive (where @var{nnn} is the DJGPP version +number), from the URL mentioned above. + +@strong{Warning!} Do @strong{not} use the popular WinZip program to +unpack the Emacs distribution! WinZip is known to corrupt some of the +files by converting them to the DOS CR-LF format, it doesn't always +preserve the directory structure recorded in the compressed Emacs +archive, and commits other atrocities. Some of these problems could +actually prevent Emacs from building successfully! + +@item make, mv, sed, and rm +All of these utilities are available at + +@uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu} + +16-bit utilities can be found in GNUish, at + +@uref{http://www.simtel.net/pub/gnuish/} + +@noindent +(@code{mv} and @code{rm} are in the Fileutils package, @code{sed} and +@code{make} are each one in a separate package named after them.) + +@end table + +The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the +directory of the Emacs sources contains some additional information +regarding Emacs under MS-DOS. + +For a list of other MS-DOS implementations of Emacs (and Emacs +look-alikes), consult the list of ``Emacs implementations and literature,'' +available at + +@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/} + +Note that while many of these programs look similar to Emacs, they often +lack certain features, such as the Emacs Lisp extension language. + +@node Emacs for Windows, Emacs for OS/2, Emacs for MS-DOS, Finding Emacs and related packages +@section Where can I get Emacs for Microsoft Windows? +@cindex FAQ for NT Emacs +@cindex Emacs for MS-Windows +@cindex Microsoft Windows, Emacs for +@cindex Windows 9X, ME, NT, 2K, and CE, Emacs for + +For information on Emacs for Windows 95 and NT, read the FAQ produced by +@email{voelker@@cs.washington.edu, Geoff Voelker} and currently maintained +by @email{ramprasad@@gnu.org, Ramprasad B}, available at + +@uref{http://www.gnu.org/software/emacs/windows/ntemacs.html} + +@xref{Emacs for MS-DOS}, for Windows 3.1. + +A port of Emacs 20.7 for Windows CE, based on NTEmacs, is available at + +@uref{http://www.rainer-keuchel.de/software.html} + +@noindent +This port was done by @email{coyxc@@rainer-keuchel.de, Rainer Keuchel}, +and supports all Emacs features except async subprocesses and menus. +You will need MSVC 6.0 and a Windows CE SDK to build this port. + +@node Emacs for OS/2, Emacs for Atari ST, Emacs for Windows, Finding Emacs and related packages +@section Where can I get Emacs for my PC running OS/2? +@cindex OS/2, Emacs for + +Emacs 20.6 is ported for emx on OS/2 2.0 or 2.1, and is available at + +@uref{ftp://hobbes.nmsu.edu/pub/os2/apps/editors/emacs/} + +@noindent +and also at + +@uref{http://www.dotemacs.de/os2/emacs.html} + +Instructions for installation, basic setup, and other useful information +for OS/2 users of Emacs can be found at + +@uref{http://home.snafu.de/ohei/emacs/emacs206-os2.html} + +@node Emacs for Atari ST, Emacs for the Amiga , Emacs for OS/2, Finding Emacs and related packages +@section Where can I get Emacs for my Atari ST? +@cindex Atari ST, Emacs for +@cindex TOS, Emacs for + +Roland Sch@"auble reports that Emacs 18.58 running on plain TOS and MiNT +is available at +@uref{ftp://atari.archive.umich.edu/Editors/Emacs-18-58/1858b-d3.zoo}. + +@node Emacs for the Amiga , Emacs for NeXTSTEP, Emacs for Atari ST, Finding Emacs and related packages +@section Where can I get Emacs for my Amiga? +@cindex Amiga, Emacs for + +The files you need are available at + +@uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/} + +@email{dgilbert@@gamiga.guelphnet.dweomer.org, David Gilbert} has released a +beta version of Emacs 19.25 for the Amiga. You can get the binary at + +@uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/a2.0bEmacs-bin.lha} + +@node Emacs for NeXTSTEP, Emacs for Apple computers, Emacs for the Amiga , Finding Emacs and related packages +@section Where can I get Emacs for NeXTSTEP? +@cindex NeXTSTEP, Emacs for + +Emacs.app is a NeXTSTEP version of Emacs 19.34 which supports colors, +menus, and multiple frames. You can get it from + +@uref{ftp://next-ftp.peak.org/pub/next-ftp/next/apps/emacs/Emacs_for_NeXTstep.4.20a1.NIHS.b.tar.gz} + +@node Emacs for Apple computers, Emacs for VMS and DECwindows, Emacs for NeXTSTEP, Finding Emacs and related packages +@section Where can I get Emacs for my Apple computer? +@cindex Apple computers, Emacs for +@cindex Macintosh, Emacs for + +Beginning with version 21.1, the Macintosh is supported in the official +Emacs distribution; see the files @file{mac/README} and +@file{mac/INSTALL} in the Emacs distribution for build instructions. + +Beginning with version 22.1, Emacs supports Mac OS X natively. + +@node Emacs for VMS and DECwindows, Modes for various languages, Emacs for Apple computers, Finding Emacs and related packages +@section Where do I get Emacs that runs on VMS under DECwindows? +@cindex DECwindows, Emacs for +@cindex VMS, Emacs for + +Up-to-date information about GNU software (including Emacs) for VMS is +available at @uref{http://www.lp.se/gnu-vms/}. + +@node Modes for various languages, , Emacs for VMS and DECwindows, Finding Emacs and related packages +@section Where can I get modes for Lex, Yacc/Bison, Bourne shell, csh, C@t{++}, Objective-C, Pascal, Java, and Awk? +@cindex Awk, mode for +@cindex @code{awk-mode} +@cindex Bison, mode for +@cindex Bourne Shell, mode for +@cindex C@t{++}, mode for +@cindex Java, mode for +@cindex Lex mode +@cindex Objective-C, mode for +@cindex @code{pascal-mode} +@cindex Shell mode +@cindex Yacc mode +@cindex @file{csh} mode +@cindex @code{sh-mode} +@cindex @code{cc-mode} + +Most of these modes are now available in standard Emacs distribution. +To get additional modes, see @ref{Finding a package with particular +functionality}. + +Barry Warsaw's @code{cc-mode} now works for C, C@t{++}, Objective-C, and +Java code. It is distributed with Emacs, but has +@uref{http://cc-mode.sourceforge.net/, its own homepage}. + +@c ------------------------------------------------------------ +@node Major packages and programs, Key bindings, Finding Emacs and related packages, Top +@chapter Major packages and programs +@cindex Major packages and programs + +@menu +* VM:: +* Supercite:: +* Calc:: +* VIPER:: +* AUCTeX:: +* BBDB:: +* Ispell:: +* Emacs/W3:: +* EDB:: +* Mailcrypt:: +* JDE:: +* Patch:: +@end menu + +@node VM, Supercite, Major packages and programs, Major packages and programs +@section VM (View Mail) --- another mail reader within Emacs, with MIME support +@cindex VM +@cindex Alternative mail software +@cindex View Mail +@cindex E-mail reader, VM + +@table @b + +@item Author +@email{kyle_jones@@wonderworks.com, Kyle Jones} + +@item Latest version +7.19 + +@item Distribution +@uref{ftp://ftp.wonderworks.com/pub/vm/vm.tar.gz} + +@item Informational newsgroup +@uref{news:gnu.emacs.vm.info}@* + +@item Bug reports newsgroup +@uref{news:gnu.emacs.vm.bug}@* +Or send reports to @email{bug-vm@@wonderworks.com} +@end table + +VM 7 works well with Emacs 21 and Emacs 22. Older versions of VM +suitable for use with older versions of Emacs are available from +@uref{ftp://ftp.wonderworks.com/pub/vm/, the same FTP site}. + + +@node Supercite, Calc, VM, Major packages and programs +@section Supercite --- mail and news citation package within Emacs +@cindex Supercite +@cindex Superyank +@cindex Mail and news citations +@cindex News and mail citations +@cindex Citations in mail and news + +@table @b + +@item Author +@email{barry@@python.org, Barry Warsaw} + +@item Latest version +3.54 (comes bundled with Emacs since version 20) + +@item Distribution +@uref{http://www.python.org/emacs/supercite.tar.gz} + +@item Mailing list +Subscription requests to @email{supercite-request@@python.org}@* +Submissions @email{supercite@@python.org} + +@end table + +Superyank is an old version of Supercite. + +@node Calc, VIPER, Supercite, Major packages and programs +@section Calc --- poor man's Mathematica within Emacs +@cindex Programmable calculator +@cindex Calc +@cindex Mathematical package + +@table @b + +@item Author +@email{daveg@@csvax.cs.caltech.edu, Dave Gillespie} + +@item Latest version +2.1 (part of Emacs since version 22.1) + +@item Distribution +No separate distribution outside of Emacs. Older versions +are available at @uref{ftp://ftp.gnu.org/pub/gnu/calc/}. + +@end table + +Note that Calc 2.02f needs patching to work with Emacs 21 and later. + +@cindex @code{calculator}, a package +Emacs 21.1 and later comes with a package called @file{calculator.el}. +It doesn't support all the mathematical wizardry offered by Calc, such +as matrices, special functions, and statistics, but is more than +adequate as a replacement for @code{xcalc} and similar programs. + +@node VIPER, AUCTeX, Calc, Major packages and programs +@section VIPER --- @code{vi} emulation for Emacs +@cindex @code{vi} emulation +@cindex VIPER +@cindex Emulation of @code{vi} + +Since Emacs 19.29, the preferred @code{vi} emulation in Emacs is VIPER +(@kbd{M-x viper-mode @key{RET}}), which comes with Emacs. It extends +and supersedes VIP (including VIP 4.3) and provides @code{vi} emulation +at several levels, from one that closely follows @code{vi} to one that +departs from @code{vi} in several significant ways. + +For Emacs 19.28 and earlier, the following version of VIP is generally +better than the one distributed with Emacs: + +@table @b +@item Author +@email{sane@@cs.uiuc.edu, Aamod Sane} + +@item Latest version +4.3 + +@item Distribution +@uref{ftp://www.club.cc.cmu.edu/pub/gnu/elisp-archive/modes/vip-mode.tar.Z} + +@end table + +@node AUCTeX, BBDB, VIPER, Major packages and programs +@section AUC@TeX{} --- enhanced @TeX{} modes with debugging facilities +@cindex Mode for @TeX{} +@cindex @TeX{} mode +@cindex AUC@TeX{} mode for editing @TeX{} +@cindex Writing and debugging @TeX{} + +AUC@TeX{} is a set of sophisticated major modes for @TeX{}, LaTeX, +ConTeXt, and Texinfo offering context-sensitive syntax highlighting, +indentation, formatting and folding, macro completion, @TeX{} shell +functionality, and debugging. Be also sure to check out +@ref{Introduction, RefTeX, Introduction, reftex, Ref@TeX{} User Manual}. +Current versions of AUC@TeX{} include the +@uref{http://www.gnu.org/software/auctex/preview-latex,preview-latex} +package for WYSIWYG previews of various LaTeX constructs in the Emacs +source buffer. + +@table @b + +@item Authors +@email{krab@@iesd.auc.dk, Kresten Krab Thorup}, @* +@email{abraham@@dina.kvl.dk, Per Abrahamsen}, @* and others. + +@item Maintainer +@email{dak@@gnu.org, David Kastrup} + +@item Latest version +11.84 + +@item Distribution +@uref{ftp://ftp.gnu.org/pub/gnu/auctex/} + +@item Web site +@uref{http://www.gnu.org/software/auctex/} + +@item Mailing list: +Subscription requests to @email{auctex-request@@gnu.org}@* +Submissions to @email{auctex@@gnu.org} + +@end table + +@node BBDB, Ispell, AUCTeX, Major packages and programs +@section BBDB --- personal Info Rolodex integrated with mail/news readers +@cindex BBDB +@cindex Rolodex-like functionality +@cindex Integrated contact database +@cindex Contact database +@cindex Big Brother Database +@cindex Address book + +@table @b + +@item Maintainer +@email{waider@@waider.ie, Ronan Waide} + +@item Latest version +2.34 + +@item Distribution +@uref{http://bbdb.sourceforge.net/} + +@item Mailing lists +Subscription requests to @email{bbdb-info-request@@lists.sourceforge.net}@* +Submissions to @email{bbdb-info@@lists.sourceforge.net}@* +Release announcements: @email{bbdb-announce-request@@lists.sourceforge.net} + +@end table + +@node Ispell, Emacs/W3, BBDB, Major packages and programs +@section Ispell --- spell checker in C with interface for Emacs +@cindex Spell-checker +@cindex Checking spelling +@cindex Ispell + +@table @b + +@item Author +@email{geoff@@cs.hmc.edu, Geoff Kuenning} + +@item Latest version +3.3.02 + +@item Distribution +@uref{http://fmg-www.cs.ucla.edu/geoff/tars/ispell-3.3.02.tar.gz}@* + +@item Web site +@uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html} + +@end table + +This Ispell program is distinct from GNU Ispell 4.0. GNU Ispell 4.0 is +no longer a supported product. + +@node Emacs/W3, EDB, Ispell, Major packages and programs +@section Emacs/W3 --- A World Wide Web browser inside of Emacs +@cindex WWW browser +@cindex Web browser +@cindex HTML browser in Emacs +@cindex @code{w3-mode} + +@table @b + +@item Author +@email{wmperry@@gnu.org, Bill Perry} + +@item Maintainer +Emacs/W3 needs a maintainer. It has lain dormant for several years. If +you would like to take over the project, please contact +@email{maintainers@@gnu.org}. + +@item Latest version +4.0pre.47 + +@item Distribution +@uref{http://savannah.gnu.org/projects/w3} + +@item Mailing lists +Receive announcements from @email{w3-announce@@gnu.org}@* +Help to develop Emacs/W3 at @email{w3-dev@@gnu.org} + +@end table + +@node EDB, Mailcrypt, Emacs/W3, Major packages and programs +@section EDB --- Database program for Emacs; replaces forms editing modes +@cindex EDB +@cindex Database +@cindex Forms mode + +@table @b +@item Author +@email{mernst@@theory.lcs.mit.edu, Michael Ernst} + +@item Latest version +1.21 + +@item Distribution +@uref{ftp://theory.lcs.mit.edu/pub/emacs/edb} + +@end table + +@node Mailcrypt, JDE, EDB, Major packages and programs +@section Mailcrypt --- PGP interface within Emacs mail and news +@cindex PGP +@cindex GPG +@cindex Interface to PGP from Emacs mail and news +@cindex News, interface to PGP from +@cindex Mail, interface to PGP from +@cindex Encryption software, interface to + +@table @b + +@item Authors +@email{patl@@lcs.mit.edu, Patrick J. LoPresti} and +@email{jin@@atype.com, Jin S. Choi} + +@item Maintainer +@email{warner-mailcrypt@@lothar.com, Brian Warner} + +@item Latest version +3.5.8 + +@item Distribution +@uref{http://dl.sourceforge.net/sourceforge/mailcrypt/mailcrypt-3.5.8.tar.gz} + +@item Web site +@uref{http://mailcrypt.sourceforge.net/} + +@end table + +Note that a new package called PGG is bundled with Emacs starting with +version 22.1. It is a modern interface to various PGP implementations, +including @uref{http://www.gnupg.org/, The GNU Privacy Guard} and +supports symmetric encryption. + +@node JDE, Patch, Mailcrypt, Major packages and programs +@section JDE --- Integrated development environment for Java +@cindex Java development environment +@cindex Integrated Java development environment +@cindex JDE + +@table @b + +@item Author +@email{paulk@@mathworks.com, Paul Kinnucan} + +@item Latest version +2.3.5 + +@item Web site +@uref{http://jdee.sunsite.dk/} + +@item Mailing lists +Subscription requests to @email{jde-subscribe@@sunsite.dk}@* +Receive announcements from @email{jde-announce-subscribe@@sunsite.dk} + +@end table + +@node Patch, , JDE, Major packages and programs +@section Patch --- program to apply ``diffs'' for updating files +@cindex Updating files with diffs +@cindex Patching source files with diffs +@cindex Diffs and patching +@cindex @file{patch} + +@table @b + +@item Author +@email{lwall@@wall.org, Larry Wall} (with GNU modifications) + +@item Latest version +2.5.4 + +@item Distribution +@xref{Current GNU distributions}. + +@end table + +@c ------------------------------------------------------------ +@node Key bindings, Alternate character sets, Major packages and programs, Top +@chapter Key bindings +@cindex Key bindings + +@menu +* Binding keys to commands:: +* Invalid prefix characters:: +* Terminal setup code works after Emacs has begun:: +* Using function keys under X:: +* Working with function and arrow keys:: +* X key translations for Emacs:: +* Handling C-s and C-q with flow control:: +* Binding C-s and C-q:: +* Backspace invokes help:: +* stty and Backspace key:: +* Swapping keys:: +* Producing C-XXX with the keyboard:: +* No Meta key:: +* No Escape key:: +* Compose Character:: +* Binding combinations of modifiers and function keys:: +* Meta key does not work in xterm:: +* ExtendChar key does not work as Meta:: +* SPC no longer completes file names:: +@end menu + +@node Binding keys to commands, Invalid prefix characters, Key bindings, Key bindings +@section How do I bind keys (including function keys) to commands? +@cindex Binding keys to commands +@cindex Keys, binding to commands +@cindex Commands, binding keys to + +Keys can be bound to commands either interactively or in your +@file{.emacs} file. To interactively bind keys for all modes, type +@kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}. + +To bind a key just in the current major mode, type @kbd{M-x +local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}. + +@inforef{Key Bindings, Key Bindings, emacs}, for further details. + +To make the process of binding keys interactively easier, use the +following ``trick'': First bind the key interactively, then immediately +type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed +to bind the key is in the kill ring, and can be yanked into your +@file{.emacs} file. If the key binding is global, no changes to the +command are required. For example, + +@lisp +(global-set-key (quote [f1]) (quote help-for-help)) +@end lisp + +@noindent +can be placed directly into the @file{.emacs} file. If the key binding is +local, the command is used in conjunction with the @samp{add-hook} function. +For example, in TeX mode, a local binding might be + +@lisp +(add-hook 'tex-mode-hook + (lambda () + (local-set-key (quote [f1]) (quote help-for-help)))) +@end lisp + + +@itemize @bullet + +@item +Control characters in key sequences, in the form yanked from the kill +ring are given in their graphic form---i.e., @key{CTRL} is shown as +@samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may want +to convert these into their vector or string forms. + +@item +If a prefix key of the character sequence to be bound is already +bound as a complete key, then you must unbind it before the new +binding. For example, if @kbd{ESC @{} is previously bound: + +@lisp +(global-unset-key [?\e ?@{]) ;; or +(local-unset-key [?\e ?@{]) +@end lisp + +@item +Aside from commands and ``lambda lists,'' a vector or string also +can be bound to a key and thus treated as a macro. For example: + +@lisp +(global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or +(global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g") +@end lisp + +@end itemize + +@node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings +@section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}? +@cindex Prefix characters, invalid +@cindex Invalid prefix characters +@cindex Misspecified key sequences + +Usually, one of two things has happened. In one case, the control +character in the key sequence has been misspecified (e.g. @samp{C-f} +used instead of @samp{\C-f} within a Lisp expression). In the other +case, a @dfn{prefix key} in the keystroke sequence you were trying to bind +was already bound as a @dfn{complete key}. Historically, the @samp{ESC [} +prefix was usually the problem, in which case you should evaluate either +of these forms before attempting to bind the key sequence: + +@lisp +(global-unset-key [?\e ?[]) ;; or +(global-unset-key "\e[") +@end lisp + +@node Terminal setup code works after Emacs has begun, Using function keys under X, Invalid prefix characters, Key bindings +@section Why doesn't this [terminal or window-system setup] code work in my @file{.emacs} file, but it works just fine after Emacs starts up? +@cindex Terminal setup code in @file{.emacs} + +During startup, Emacs initializes itself according to a given code/file +order. If some of the code executed in your @file{.emacs} file needs to +be postponed until the initial terminal or window-system setup code has +been executed but is not, then you will experience this problem (this +code/file execution order is not enforced after startup). + +To postpone the execution of Emacs Lisp code until after terminal or +window-system setup, treat the code as a @dfn{lambda list} and set the +value of either the @code{term-setup-hook} or @code{window-setup-hook} +variable to this lambda function. For example, + +@lisp +(add-hook 'term-setup-hook + (lambda () + (when (string-match "\\`vt220" (or (getenv "TERM") "")) + ;; Make vt220's "Do" key behave like M-x: + (global-set-key [do] 'execute-extended-command)))) +@end lisp + +For information on what Emacs does every time it is started, see the +@file{lisp/startup.el} file. + +@node Using function keys under X, Working with function and arrow keys, Terminal setup code works after Emacs has begun, Key bindings +@section How do I use function keys under X? +@cindex Function keys +@cindex X Window System and function keys +@cindex Binding function keys + +With Emacs 19, functions keys under X are bound like any other key. @xref{Binding keys to commands}, for details. + +@node Working with function and arrow keys, X key translations for Emacs, Using function keys under X, Key bindings +@section How do I tell what characters or symbols my function or arrow keys emit? +@cindex Working with arrow keys +@cindex Arrow keys, symbols generated by +@cindex Working with function keys +@cindex Function keys, symbols generated by +@cindex Symbols generated by function keys + +Type @kbd{C-h c} then the function or arrow keys. The command will +return either a function key symbol or character sequence (see the +Emacs on-line documentation for an explanation). This works for other +keys as well. + +@node X key translations for Emacs, Handling C-s and C-q with flow control, Working with function and arrow keys, Key bindings +@section How do I set the X key ``translations'' for Emacs? +@cindex X key translations +@cindex Key translations under X +@cindex Translations for keys under X + +Emacs is not written using the Xt library by default, so there are no +``translations'' to be set. (We aren't sure how to set such translations +if you do build Emacs with Xt; please let us know if you've done this!) + +The only way to affect the behavior of keys within Emacs is through +@code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs). The +@code{define-key} command should be used in conjunction with the +@code{function-key-map} map. For instance, + +@lisp +(define-key function-key-map [M-@key{TAB}] [?\M-\t]) +@end lisp + +@noindent +defines the @kbd{M-@key{TAB}} key sequence. + +@node Handling C-s and C-q with flow control, Binding C-s and C-q, X key translations for Emacs, Key bindings +@section How do I handle @kbd{C-s} and @kbd{C-q} being used for flow control? +@cindex Flow control, @kbd{C-s} and @kbd{C-q} with +@cindex @kbd{C-s} and @kbd{C-q} with flow control + +@kbd{C-s} and @kbd{C-q} are used in the XON/XOFF flow control protocol. +This messes things up when you're using Emacs over a serial line, +because Emacs binds these keys to commands by default. Because Emacs +won't honor them as flow control characters, too many of these +characters are not passed on and overwhelm output buffers. Sometimes, +intermediate software using XON/XOFF flow control will prevent Emacs +from ever seeing @kbd{C-s} and @kbd{C-q}. + +Possible solutions: + +@itemize @bullet + +@item +Disable the use of @kbd{C-s} and @kbd{C-q} for flow control. + +You need to determine the cause of the flow control. + +@itemize @minus + +@item +your terminal + +Your terminal may use XON/XOFF flow control to have time to display +all the characters it receives. For example, VT series terminals do +this. It may be possible to turn this off from a setup menu. For +example, on a VT220 you may select ``No XOFF'' in the setup menu. This +is also true for some terminal emulation programs on PCs. + +When you turn off flow control at the terminal, you will also need to +turn it off at the other end, which might be at the computer you are +logged in to or at some terminal server in between. + +If you turn off flow control, characters may be lost; using a printer +connected to the terminal may fail. You may be able to get around +this problem by modifying the @samp{termcap} entry for your terminal to +include extra NUL padding characters. + +@item +a modem + +If you are using a dialup connection, the modems may be using +XON/XOFF flow control. It's not clear how to get around this. + +@item +a router or terminal server + +Some network box between the terminal and your computer may be using +XON/XOFF flow control. It may be possible to make it use some other +kind of flow control. You will probably have to ask your local +network experts for help with this. + +@item +@code{tty} and/or @code{pty} devices + +If your connection to Emacs goes through multiple @code{tty} and/or +@code{pty} devices, they may be using XON/XOFF flow control even when it +is not necessary. + +@email{eirik@@theory.tn.cornell.edu, Eirik Fuller} writes: + +@quotation +Some versions of @code{rlogin} (and possibly @code{telnet}) do not pass +flow control characters to the remote system to which they connect. On +such systems, Emacs on the remote system cannot disable flow control on +the local system. Sometimes @samp{rlogin -8} will avoid this problem. + +One way to cure this is to disable flow control on the local host (the +one running @code{rlogin}, not the one running @code{rlogind}) using the +@code{stty} command, before starting the @code{rlogin} process. On many +systems, @samp{stty start u stop u} will do this. + +Some versions of @samp{tcsh} will prevent even this from working. One +way around this is to start another shell before starting rlogin, +and issue the @samp{stty} command to disable flow control from that shell. +@end quotation + +Use @samp{stty -ixon} instead of @samp{stty start u stop u} on some systems. + +@end itemize + +@item +Make Emacs speak the XON/XOFF flow control protocol. + +You can make Emacs treat @kbd{C-s} and @kbd{C-q} as flow control characters by +evaluating the form + +@lisp +(enable-flow-control) +@end lisp + +@noindent +to unconditionally enable flow control or + +@lisp +(enable-flow-control-on "vt100" "h19") +@end lisp + +@noindent +(using your terminal names instead of @samp{vt100} or @samp{h19}) to +enable selectively. These commands will automatically swap @kbd{C-s} +and @kbd{C-q} to @kbd{C-\} and @kbd{C-^}. Variables can be used to +change the default swap keys (@code{flow-control-c-s-replacement} and +@code{flow-control-c-q-replacement}). + +If you are fixing this for yourself, simply put the form in your +@file{.emacs} file. If you are fixing this for your entire site, the +best place to put it is in the @file{site-lisp/site-start.el} file. +(Here @file{site-lisp} is actually a subdirectory of your Emacs +installation directory, typically @file{/usr/local/share/emacs}.) +Putting this form in @file{site-lisp/default.el} has the problem that +if the user's @file{.emacs} file has an error, this will prevent +@file{default.el} from being loaded and Emacs may be unusable for the +user, even for correcting their @file{.emacs} file (unless they're +smart enough to move it to another name). + +@code{enable-flow-control} can be invoked interactively as well: +@kbd{M-x enable-flow-control @key{RET}}. + +@end itemize + +For further discussion of this issue, read the file @file{etc/PROBLEMS} +(in the Emacs source directory when you unpack the Emacs distribution). + +@node Binding C-s and C-q, Backspace invokes help, Handling C-s and C-q with flow control, Key bindings +@section How do I bind @kbd{C-s} and @kbd{C-q} (or any key) if these keys are filtered out? +@cindex Binding @kbd{C-s} and @kbd{C-q} +@cindex @kbd{C-s} and @kbd{C-q}, binding + +To bind @kbd{C-s} and @kbd{C-q}, use either @code{enable-flow-control} +or @code{enable-flow-control-on}. @xref{Handling C-s and C-q with flow +control}, for usage and implementation details. + +To bind other keys, use @code{keyboard-translate}. @xref{Swapping +keys}, for usage details. To do this for an entire site, you should +swap the keys in @file{site-lisp/site-start.el}. @xref{Handling C-s +and C-q with flow control}, for an explanation of why +@file{site-lisp/default.el} should not be used. + +@itemize @bullet + +@item +If you do this for an entire site, the users will be confused by +the disparity between what the documentation says and how Emacs +actually behaves. + +@end itemize + +@node Backspace invokes help, stty and Backspace key, Binding C-s and C-q, Key bindings +@section Why does the @key{Backspace} key invoke help? +@cindex Backspace key invokes help +@cindex Help invoked by Backspace +@cindex DEL key does not delete + +The @key{Backspace} key (on most keyboards) generates @acronym{ASCII} code 8. +@kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes +help-command. This is intended to be easy to remember since the first +letter of @samp{help} is @samp{h}. The easiest solution to this problem +is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the +@key{Delete} key) for deleting the previous character. + +For many people this solution may be problematic: + +@itemize @bullet + +@item +They normally use @key{Backspace} outside of Emacs for deleting the +previous character. This can be solved by making @key{DEL} the command +for deleting the previous character outside of Emacs. On many Unix +systems, this command will remap @key{DEL}: + +@example +stty erase `^?' +@end example + +@item +The user may prefer the @key{Backspace} key for deleting the +previous character because it is more conveniently located on their +keyboard or because they don't even have a separate @key{Delete} key. +In this case, the @key{Backspace} key should be made to behave like +@key{Delete}. There are several methods. + +@itemize @minus +@item +Some terminals (e.g., VT3## terminals) and terminal emulators (e.g., +TeraTerm) allow the character generated by the @key{Backspace} key to be +changed from a setup menu. + +@item +You may be able to get a keyboard that is completely programmable, or a +terminal emulator that supports remapping of any key to any other key. + +@item +With Emacs 21.1 and later, you can control the effect of the +@key{Backspace} and @key{Delete} keys, on both dumb terminals and a +windowed displays, by customizing the option +@code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x +normal-erase-is-backspace}. See the documentation of these symbols +(@pxref{Emacs Lisp documentation}) for more info. + +@item +It is possible to swap the @key{Backspace} and @key{DEL} keys inside +Emacs: + +@lisp +(keyboard-translate ?\C-h ?\C-?) +@end lisp + +@noindent +This is the recommended method of forcing @key{Backspace} to act as +@key{DEL}, because it works even in modes which bind @key{DEL} to +something other than @code{delete-backward-char}. + +Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by +default deletes forward: + +@lisp +(keyboard-translate ?\C-? ?\C-d) +@end lisp + +@xref{Swapping keys}, for further details about @code{keyboard-translate}. + +@item +Another approach is to switch key bindings and put help on @kbd{C-x h} +instead: + +@lisp +(global-set-key "\C-h" 'delete-backward-char) + +;; overrides mark-whole-buffer +(global-set-key "\C-xh" 'help-command) +@end lisp + +@noindent +This method is not recommended, though: it only solves the problem for +those modes which bind @key{DEL} to @code{delete-backward-char}. Modes +which bind @key{DEL} to something else, such as @code{view-mode}, will +not work as you expect when you press the @key{Backspace} key. For this +reason, we recommend the @code{keyboard-translate} method, shown +above. + +Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}. +@end itemize + +Don't try to bind @key{DEL} to @code{help-command}, because there are +many modes that have local bindings of @key{DEL} that will interfere. + +@end itemize + +When Emacs 21 or later runs on a windowed display, it binds the +@key{Delete} key to a command which deletes the character at point, to +make Emacs more consistent with keyboard operation on these systems. + +For more information about troubleshooting this problem, see @ref{DEL +Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs +Manual}. + +@node stty and Backspace key, Swapping keys, Backspace invokes help, Key bindings +@section Why doesn't Emacs look at the @file{stty} settings for @key{Backspace} vs. @key{Delete}? +@cindex @file{stty} and Emacs +@cindex Backspace and @file{stty} +@cindex Delete and @file{stty} + +Good question! + +@c FIXME: RMS explained the reasons for this on emacs-hackers. It's +@c probably worth putting that explanation here. + +@node Swapping keys, Producing C-XXX with the keyboard, stty and Backspace key, Key bindings +@section How do I swap two keys? +@cindex Swapping keys +@cindex Keys, swapping +@cindex @code{keyboard-translate} + +You can swap two keys (or key sequences) by using the +@code{keyboard-translate} function. For example, to turn @kbd{C-h} +into @key{DEL} and @key{DEL} to @kbd{C-h}, use + +@lisp +(keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL +(keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'. +@end lisp + +@noindent +The first key sequence of the pair after the function identifies what is +produced by the keyboard; the second, what is matched for in the +keymaps. + +However, in the specific case of @kbd{C-h} and @key{DEL}, you should +toggle @code{normal-erase-is-backspace-mode} instead of calling +@code{keyboard-translate}. @inforef{DEL Does Not Delete, DEL Does Not Delete, +emacs}. + +Keyboard translations are not the same as key bindings in keymaps. +Emacs contains numerous keymaps that apply in different situations, but +there is only one set of keyboard translations, and it applies to every +character that Emacs reads from the terminal. Keyboard translations +take place at the lowest level of input processing; the keys that are +looked up in keymaps contain the characters that result from keyboard +translation. + +@node Producing C-XXX with the keyboard, No Meta key, Swapping keys, Key bindings +@section How do I produce C-XXX with my keyboard? +@cindex Producing control characters +@cindex Generating control characters +@cindex Control characters, generating + +On terminals (but not under X), some common ``aliases'' are: + +@table @asis + +@item @kbd{C-2} or @kbd{C-@key{SPC}} +@kbd{C-@@} + +@item @kbd{C-6} +@kbd{C-^} + +@item @kbd{C-7} or @kbd{C-S--} +@kbd{C-_} + +@item @kbd{C-4} +@kbd{C-\} + +@item @kbd{C-5} +@kbd{C-]} + +@item @kbd{C-/} +@kbd{C-?} + +@end table + +Often other aliases exist; use the @kbd{C-h c} command and try +@key{CTRL} with all of the digits on your keyboard to see what gets +generated. You can also try the @kbd{C-h w} command if you know the +name of the command. + +@node No Meta key, No Escape key, Producing C-XXX with the keyboard, Key bindings +@section What if I don't have a @key{Meta} key? +@cindex No @key{Meta} key +@cindex @key{Meta} key, what to do if you lack it + +On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it. + +Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact, +Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway +(depending on the value of @code{meta-prefix-char}). Note that you +press @key{Meta} and @key{a} together, but with @key{ESC}, you press +@key{ESC}, release it, and then press @key{a}. + +@node No Escape key, Compose Character, No Meta key, Key bindings +@section What if I don't have an @key{Escape} key? +@cindex No Escape key +@cindex Lacking an Escape key +@cindex Escape key, lacking + +Type @kbd{C-[} instead. This should send @acronym{ASCII} code 27 just like an +Escape key would. @kbd{C-3} may also work on some terminal (but not +under X). For many terminals (notably DEC terminals) @key{F11} +generates @key{ESC}. If not, the following form can be used to bind it: + +@lisp +;; F11 is the documented ESC replacement on DEC terminals. +(define-key function-key-map [f11] [?\e]) +@end lisp + +@node Compose Character, Binding combinations of modifiers and function keys, No Escape key, Key bindings +@section Can I make my @key{Compose Character} key behave like a @key{Meta} key? +@cindex @key{Compose Character} key, using as @key{Meta} +@cindex @key{Meta}, using @key{Compose Character} for + +On a dumb terminal such as a VT220, no. It is rumored that certain +VT220 clones could have their @key{Compose} key configured this way. If +you're using X, you might be able to do this with the @code{xmodmap} +command. + +@node Binding combinations of modifiers and function keys, Meta key does not work in xterm, Compose Character, Key bindings +@section How do I bind a combination of modifier key and function key? +@cindex Modifiers and function keys +@cindex Function keys and modifiers +@cindex Binding modifiers and function keys + +With Emacs 19 and later, you can represent modified function keys in +vector format by adding prefixes to the function key symbol. For +example (from the on-line documentation): + +@lisp +(global-set-key [?\C-x right] 'forward-page) +@end lisp + +@noindent +where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}. + +You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper}, +@key{Super}, @key{Alt}, and @key{Shift} with function keys. To +represent these modifiers, prepend the strings @samp{C-}, @samp{M-}, +@samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here +is how to make @kbd{H-M-RIGHT} move forward a word: + +@lisp +(global-set-key [H-M-right] 'forward-word) +@end lisp + +@itemize @bullet + +@item +Not all modifiers are permitted in all situations. @key{Hyper}, +@key{Super}, and @key{Alt} are not available on Unix character +terminals. Non-@acronym{ASCII} keys and mouse events (e.g. @kbd{C-=} and +@kbd{Mouse-1}) also fall under this category. + +@end itemize + +@xref{Binding keys to commands}, for general key binding instructions. + +@node Meta key does not work in xterm, ExtendChar key does not work as Meta, Binding combinations of modifiers and function keys, Key bindings +@section Why doesn't my @key{Meta} key work in an @code{xterm} window? +@cindex @key{Meta} key and @code{xterm} +@cindex Xterm and @key{Meta} key + +@inforef{Unibyte Mode, Single-Byte Character Set Support, emacs}. + +If the advice in the Emacs manual fails, try all of these methods before +asking for further help: + +@itemize @bullet + +@item +You may have big problems using @code{mwm} as your window manager. +(Does anyone know a good generic solution to allow the use of the +@key{Meta} key in Emacs with @file{mwm}?) + +@item +For X11: Make sure it really is a @key{Meta} key. Use @code{xev} to +find out what keysym your @key{Meta} key generates. It should be either +@code{Meta_L} or @code{Meta_R}. If it isn't, use @file{xmodmap} to fix +the situation. If @key{Meta} does generate @code{Meta_L} or +@code{Meta_R}, but @kbd{M-x} produces a non-@acronym{ASCII} character, put this in +your @file{~/.Xdefaults} file: + +@example + XTerm*eightBitInput: false + XTerm*eightBitOutput: true +@end example + +@item +Make sure the @code{pty} the @code{xterm} is using is passing 8 bit +characters. @samp{stty -a} (or @samp{stty everything}) should show +@samp{cs8} somewhere. If it shows @samp{cs7} instead, use @samp{stty +cs8 -istrip} (or @samp{stty pass8}) to fix it. + +@item +If there is an @code{rlogin} connection between @code{xterm} and Emacs, the +@samp{-8} argument may need to be given to rlogin to make it pass all 8 bits +of every character. + +@item +If Emacs is running on Ultrix, it is reported that evaluating +@code{(set-input-mode t nil)} helps. + +@item +If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when +you type @kbd{M-W}, which is the same conversion Emacs would make if it +got the @kbd{M-W} anyway. In X11R4, the following resource +specification will do this: + +@example +XTerm.VT100.EightBitInput: false +@end example + +@noindent +(This changes the behavior of the @code{insert-eight-bit} action.) + +With older @code{xterm}s, you can specify this behavior with a translation: + +@example +XTerm.VT100.Translations: #override \ + Meta: string(0x1b) insert() +@end example + +@noindent +You might have to replace @samp{Meta} with @samp{Alt}. + +@end itemize + +@node ExtendChar key does not work as Meta, SPC no longer completes file names, Meta key does not work in xterm, Key bindings +@section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x? +@cindex @key{ExtendChar} key as @key{Meta} +@cindex @key{Meta}, using @key{ExtendChar} for +@cindex HP-UX, the @key{ExtendChar} key + +This is a result of an internationalization extension in X11R4 and the +fact that HP is now using this extension. Emacs assumes that the +@code{XLookupString} function returns the same result regardless of the +@key{Meta} key state which is no longer necessarily true. Until Emacs +is fixed, the temporary kludge is to run this command after each time +the X server is started but preferably before any xterm clients are: + +@example +xmodmap -e 'remove mod1 = Mode_switch' +@end example + +@c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is +@c solved? + +This will disable the use of the extra keysyms systemwide, which may be +undesirable if you actually intend to use them. + +@node SPC no longer completes file names, , ExtendChar key does not work as Meta, Key bindings +@section Why doesn't SPC complete file names anymore? +@cindex @kbd{SPC} file name completion + +Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in +the minibuffer, so that file names with embedded spaces could be typed +without the need to quote the spaces. + +You can get the old behavior by binding @kbd{SPC} to +@code{minibuffer-complete-word} in the minibuffer, as follows: + +@lisp +(define-key minibuffer-local-filename-completion-map (kbd "SPC") + 'minibuffer-complete-word) + +(define-key minibuffer-local-must-match-filename-map (kbd "SPC") + 'minibuffer-complete-word) +@end lisp + +@c ------------------------------------------------------------ +@node Alternate character sets, Mail and news, Key bindings, Top +@chapter Alternate character sets +@cindex Alternate character sets + +@menu +* Emacs does not display 8-bit characters:: +* Inputting eight-bit characters:: +* Kanji and Chinese characters:: +* Right-to-left alphabets:: +* How to add fonts:: +@end menu + +@node Emacs does not display 8-bit characters, Inputting eight-bit characters, Alternate character sets, Alternate character sets +@section How do I make Emacs display 8-bit characters? +@cindex Displaying eight-bit characters +@cindex Eight-bit characters, displaying + +@inforef{Unibyte Mode, Single-byte Character Set +Support, emacs}. On a Unix, when Emacs runs on a text-only terminal +display or is invoked with @samp{emacs -nw}, you typically need to use +@code{set-terminal-coding-system} to tell Emacs what the terminal can +display, even after setting the language environment; otherwise +non-@acronym{ASCII} characters will display as @samp{?}. On other operating +systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the +character set supported by the display, and sets up the required +terminal coding system automatically. + +@node Inputting eight-bit characters, Kanji and Chinese characters, Emacs does not display 8-bit characters, Alternate character sets +@section How do I input eight-bit characters? +@cindex Entering eight-bit characters +@cindex Eight-bit characters, entering +@cindex Input, 8-bit characters + +Various methods are available for input of eight-bit characters. See +@inforef{Unibyte Mode, Single-byte Character Set +Support, emacs}. For more sophisticated methods, @inforef{Input +Methods, Input Methods, emacs}. + +@node Kanji and Chinese characters, Right-to-left alphabets, Inputting eight-bit characters, Alternate character sets +@section Where can I get an Emacs that handles kanji, Chinese, or other Far-Eastern character sets? +@cindex Kanji, handling with Emacs +@cindex Chinese, handling with Emacs +@cindex Japanese, handling with Emacs +@cindex Korean, handling with Emacs + +Emacs 20 and later includes many of the features of MULE, the MULtilingual +Enhancement to Emacs. @xref{Installing Emacs}, for information on where +to find and download the latest version of Emacs. + +@node Right-to-left alphabets, How to add fonts, Kanji and Chinese characters, Alternate character sets +@section Where is an Emacs that can handle Semitic (right-to-left) alphabets? +@cindex Right-to-left alphabets +@cindex Hebrew, handling with Emacs +@cindex Semitic alphabets +@cindex Arabic alphabets + +Emacs 20 and later supports Hebrew characters (ISO 8859-8), but does not +yet support right-to-left character entry and display. + +@email{joel@@exc.com, Joel M. Hoffman} has written a Lisp package called +@file{hebrew.el} that allows right-to-left editing of Hebrew. It +reportedly works out of the box with Emacs 19, but requires patches for +Emacs 18. Write to Joel if you want the patches or package. + +@c FIXME: Should we mention Ehud Karni's package? + +@file{hebrew.el} requires a Hebrew screen font, but no other hardware support. +Joel has a screen font for PCs running MS-DOS or GNU/Linux. + +You might also try querying @code{archie} for files named with +@file{hebrew}; several ftp sites in Israel may also have the necessary +files. + +@node How to add fonts, , Right-to-left alphabets, Alternate character sets +@section How do I add fonts for use with Emacs? +@cindex add fonts for use with Emacs +@cindex intlfonts + +First, download and install the BDF font files and any auxiliary +packages they need. The GNU Intlfonts distribution can be found on +@uref{http://directory.fsf.org/localization/intlfonts.html, the GNU +Software Directory Web site}. + +Next, if you are on X Window system, issue the following two commands +from the shell's prompt: + +@example + xset +fp /usr/local/share/emacs/fonts + xset fp rehash +@end example + +@noindent +(Modify the first command if you installed the fonts in a directory +that is not @file{/usr/local/share/emacs/fonts}.) You also need to +arrange for these two commands to run whenever you log in, e.g., by +adding them to your window-system startup file, such as +@file{~/.xsessionrc} or @file{~/.gnomerc}. + +Now, add the following line to your @file{~/.emacs} init file: + +@lisp + (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf") +@end lisp + +@noindent +(Again, modify the file name if you installed the fonts elsewhere.) + +Finally, if you wish to use the installed fonts with @code{ps-print}, +add the following line to your @file{~/.emacs}: + +@lisp + (setq ps-multibyte-buffer 'bdf-font-except-latin) +@end lisp + +A few additional steps are necessary for MS-Windows; they are listed +below. + +First, make sure @emph{all} the directories with BDF font files are +mentioned in @code{bdf-directory-list}. On Unix and GNU/Linux +systems, one normally runs @kbd{make install} to install the BDF fonts +in the same directory. By contrast, Windows users typically don't run +the Intlfonts installation command, but unpack the distribution in +some directory, which leaves the BDF fonts in its subdirectories. For +example, assume that you unpacked Intlfonts in @file{C:/Intlfonts}; +then you should set @code{bdf-directory-list} as follows: + +@lisp + (setq bdf-directory-list + '("C:/Intlfonts/Asian" + "C:/Intlfonts/Chinese" "C:/Intlfonts/Chinese.X" + "C:/Intlfonts/Chinese.BIG" "C:/Intlfonts/Ethiopic" + "C:/Intlfonts/European" "C:/Intlfonts/European.BIG" + "C:/Intlfonts/Japanese" "C:/Intlfonts/Japanese.X" + "C:/Intlfonts/Japanese.BIG" "C:/Intlfonts/Korean.X" + "C:/Intlfonts/Misc")) +@end lisp + +@cindex @code{w32-bdf-filename-alist} +@cindex @code{w32-find-bdf-fonts} +Next, you need to set up the variable @code{w32-bdf-filename-alist} to +an alist of the BDF fonts and their corresponding file names. +Assuming you have set @code{bdf-directory-list} to name all the +directories with the BDF font files, the following Lisp snippet will +set up @code{w32-bdf-filename-alist}: + +@lisp + (setq w32-bdf-filename-alist + (w32-find-bdf-fonts bdf-directory-list)) +@end lisp + +Now, create fontsets for the BDF fonts: + +@lisp + (create-fontset-from-fontset-spec + "-*-fixed-medium-r-normal-*-16-*-*-*-c-*-fontset-bdf, + japanese-jisx0208:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1983-*, + katakana-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*, + latin-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*, + japanese-jisx0208-1978:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1978-*, + thai-tis620:-misc-fixed-medium-r-normal--16-160-72-72-m-80-tis620.2529-1, + lao:-misc-fixed-medium-r-normal--16-160-72-72-m-80-MuleLao-1, + tibetan-1-column:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-80-MuleTibetan-1, + ethiopic:-Admas-Ethiomx16f-Medium-R-Normal--16-150-100-100-M-160-Ethiopic-Unicode, + tibetan:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-160-MuleTibetan-0") +@end lisp + +Many of the international bdf fonts from Intlfonts are type 0, and +therefore need to be added to font-encoding-alist: + +@lisp + (setq font-encoding-alist + (append '(("MuleTibetan-0" (tibetan . 0)) + ("GB2312" (chinese-gb2312 . 0)) + ("JISX0208" (japanese-jisx0208 . 0)) + ("JISX0212" (japanese-jisx0212 . 0)) + ("VISCII" (vietnamese-viscii-lower . 0)) + ("KSC5601" (korean-ksc5601 . 0)) + ("MuleArabic-0" (arabic-digit . 0)) + ("MuleArabic-1" (arabic-1-column . 0)) + ("MuleArabic-2" (arabic-2-column . 0))) + font-encoding-alist)) +@end lisp + +You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium} +fontset, or you can select it by setting the default font in your +@file{~/.emacs}: + +@lisp + (set-default-font "fontset-bdf") +@end lisp + + +@c ------------------------------------------------------------ +@node Mail and news, Concept index, Alternate character sets, Top +@chapter Mail and news +@cindex Mail and news + +@menu +* Changing the included text prefix:: +* Saving a copy of outgoing mail:: +* Expanding aliases when sending mail:: +* Rmail thinks all messages are one big one:: +* Sorting the messages in an Rmail folder:: +* Rmail writes to /usr/spool/mail:: +* Recovering mail files when Rmail munges them:: +* Replying to the sender of a message:: +* MIME with Emacs mail packages:: +* Automatically starting a mail or news reader:: +* Reading news with Emacs:: +* Gnus does not work with NNTP:: +* Viewing articles with embedded underlining:: +* Saving a multi-part Gnus posting:: +* Starting Gnus faster:: +* Catching up in all newsgroups:: +* Killing based on nonstandard headers:: +* Removing flashing messages:: +* Catch-up is slow in Gnus:: +* Gnus hangs for a long time:: +* Learning more about Gnus:: +@end menu + +@node Changing the included text prefix, Saving a copy of outgoing mail, Mail and news, Mail and news +@section How do I change the included text prefix in mail/news followups? +@cindex Prefix in mail/news followups, changing +@cindex Included text prefix, changing +@cindex Setting the included text character +@cindex Quoting in mail messages + +If you read mail with Rmail or news with Gnus, set the variable +@code{mail-yank-prefix}. For VM, set @code{vm-included-text-prefix}. +For mh-e, set @code{mh-ins-buf-prefix}. + +For fancier control of citations, use Supercite. @xref{Supercite}. + +To prevent Emacs from including various headers of the replied-to +message, set the value of @code{mail-yank-ignored-headers} to an +appropriate regexp. + +@node Saving a copy of outgoing mail, Expanding aliases when sending mail, Changing the included text prefix, Mail and news +@section How do I save a copy of outgoing mail? +@cindex Saving a copy of outgoing mail +@cindex Copying outgoing mail to a file +@cindex Filing outgoing mail +@cindex Automatic filing of outgoing mail +@cindex Mail, saving outgoing automatically + +You can either mail yourself a copy by including a @samp{BCC} header in the +mail message, or store a copy of the message directly to a file by +including an @samp{FCC} header. + +If you use standard mail, you can automatically create a @samp{BCC} to +yourself by putting + +@lisp +(setq mail-self-blind t) +@end lisp + +@noindent +in your @file{.emacs} file. You can automatically include an @samp{FCC} +field by putting something like the following in your @file{.emacs} +file: + +@lisp +(setq mail-archive-file-name (expand-file-name "~/outgoing")) +@end lisp + +The output file will be in Unix mail format, which can be read directly +by VM, but not always by Rmail. @xref{Learning how to do something}. + +If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your +components file. + +It does not work to put @samp{set record filename} in the @file{.mailrc} +file. + +@node Expanding aliases when sending mail, Rmail thinks all messages are one big one, Saving a copy of outgoing mail, Mail and news +@section Why doesn't Emacs expand my aliases when sending mail? +@cindex Expanding aliases when sending mail +@cindex Mail alias expansion +@cindex Sending mail with aliases + +@itemize @bullet + +@item +You must separate multiple addresses in the headers of the mail buffer +with commas. This is because Emacs supports RFC822 standard addresses +like this one: + +@example +To: Willy Smith +@end example + +However, you do not need to---and probably should not, unless your +system's version of @file{/usr/ucb/mail} (a.k.a.@: @code{mailx}) +supports RFC822---separate addresses with commas in your +@file{~/.mailrc} file. + +@item +Emacs normally only reads the @file{.mailrc} file once per session, +when you start to compose your first mail message. If you edit +@file{.mailrc}, you can type @kbd{M-x rebuild-mail-abbrevs @key{RET}} to +make Emacs reread @file{~/.mailrc}. + +@item +If you like, you can expand mail aliases as abbrevs, as soon as you +type them in. To enable this feature, execute the following: + +@lisp +(add-hook 'mail-mode-hook 'mail-abbrevs-setup) +@end lisp + +Note that the aliases are expanded automatically only after you type +@key{RET} or a punctuation character (e.g. @kbd{,}). You can force their +expansion by moving point to the end of the alias and typing @kbd{C-x a e} +(@kbd{M-x expand-abbrev}). +@end itemize + +@node Rmail thinks all messages are one big one, Sorting the messages in an Rmail folder, Expanding aliases when sending mail, Mail and news +@section Why does Rmail think all my saved messages are one big message? +@cindex Rmail thinks all messages are one large message + +A file created through the @samp{FCC} field in a message is in Unix mail +format, not the format that Rmail uses (BABYL format). Rmail will try +to convert a Unix mail file into BABYL format on input, but sometimes it +makes errors. For guaranteed safety, you can make the +@file{saved-messages} file be an inbox for your Rmail file by using the +function @code{set-rmail-inbox-list}. + +@node Sorting the messages in an Rmail folder, Rmail writes to /usr/spool/mail, Rmail thinks all messages are one big one, Mail and news +@section How can I sort the messages in my Rmail folder? +@cindex Rmail, sorting messages in +@cindex Folder, sorting messages in an Rmail +@cindex Sorting messages in an Rmail folder + +In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions +and their key bindings. + +@node Rmail writes to /usr/spool/mail, Recovering mail files when Rmail munges them, Sorting the messages in an Rmail folder, Mail and news +@section Why does Rmail need to write to @file{/usr/spool/mail}? +@cindex Rmail and @file{/usr/spool/mail} +@cindex @file{/usr/spool/mail} and Rmail + +This is the behavior of the @code{movemail} program which Rmail uses. +This indicates that @code{movemail} is configured to use lock files. + +RMS writes: + +@quotation +Certain systems require lock files to interlock access to mail files. +On these systems, @code{movemail} must write lock files, or you risk losing +mail. You simply must arrange to let @code{movemail} write them. + +Other systems use the @code{flock} system call to interlock access. On +these systems, you should configure @code{movemail} to use @code{flock}. +@end quotation + +@node Recovering mail files when Rmail munges them, Replying to the sender of a message, Rmail writes to /usr/spool/mail, Mail and news +@section How do I recover my mail files after Rmail munges their format? +@cindex Recovering munged mail files +@cindex Rmail munged my files +@cindex Mail files, recovering those munged by Rmail + +If you have just done @kbd{M-x rmail-input} on a file and you don't want +to save it in Rmail's format (called BABYL), just kill the buffer (with +@kbd{C-x k}). + +@cindex Exporting messages as Unix mail files +If you typed @kbd{M-x rmail} and it read some messages out of your inbox +and you want to put them in a Unix mail file, use @kbd{C-o} on each +message. + +@cindex Converting from BABYL to Unix mail format +@cindex @code{unrmail} command +If you want to convert an existing file from BABYL format to Unix mail +format, use the command @kbd{M-x unrmail}: it will prompt you for the +input and output file names. + +@pindex b2m +Alternatively, you could use the @code{b2m} program supplied with +Emacs. @code{b2m} is a filter, and is used like this: + +@example + b2m < @var{babyl-file} > @var{mbox-file} +@end example + +@noindent +where @var{babyl-file} is the name of the BABYL file, and +@var{mbox-file} is the name of the file where the converted mail will +be written. + +@node Replying to the sender of a message, MIME with Emacs mail packages, Recovering mail files when Rmail munges them, Mail and news +@section How can I force Rmail to reply to the sender of a message, but not the other recipients? +@cindex Replying only to the sender of a message +@cindex Sender, replying only to +@cindex Rmail, replying to the sender of a message in + +@email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit +@key{r} to reply in Rmail, by default it CCs all of the original +recipients (everyone on the original @samp{To} and @samp{CC} +lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}), +it replies only to the sender. However, going through the whole +@kbd{C-u} business every time you want to reply is a pain. This is the +best fix I've been able to come up with: + +@lisp +(defun rmail-reply-t () + "Reply only to the sender of the current message. (See rmail-reply.)" + (interactive) + (rmail-reply t)) + +(add-hook 'rmail-mode-hook + (lambda () + (define-key rmail-mode-map "r" 'rmail-reply-t) + (define-key rmail-mode-map "R" 'rmail-reply))) +@end lisp + +@node MIME with Emacs mail packages, Automatically starting a mail or news reader, Replying to the sender of a message, Mail and news +@section How can I get my favorite Emacs mail package to support MIME? +@cindex MIME and Emacs mail packages +@cindex Mail packages and MIME +@cindex FAQ for MIME and Emacs + +Version 6.x of VM supports MIME. @xref{VM}. Gnus supports MIME in mail +and news messages as of version 5.8.1 (Pterodactyl). Rmail has limited +support for single-part MIME messages beginning with Emacs 20.3. + +@node Automatically starting a mail or news reader, Reading news with Emacs, MIME with Emacs mail packages, Mail and news +@section How do I make Emacs automatically start my mail/news reader? +@cindex Mail reader, starting automatically +@cindex News reader, starting automatically +@cindex Starting mail/news reader automatically + +To start Emacs in Gnus: + +@example +emacs -f gnus +@end example + +@noindent +in Rmail: + +@example +emacs -f rmail +@end example + +A more convenient way to start with Gnus: + +@example +alias gnus 'emacs -f gnus' +gnus +@end example + +It is probably unwise to automatically start your mail or news reader +from your @file{.emacs} file. This would cause problems if you needed to run +two copies of Emacs at the same time. Also, this would make it difficult for +you to start Emacs quickly when you needed to. + +@node Reading news with Emacs, Gnus does not work with NNTP, Automatically starting a mail or news reader, Mail and news +@section How do I read news under Emacs? +@cindex Reading news under Emacs +@cindex Usenet reader in Emacs +@cindex Gnus newsreader + +Use @kbd{M-x gnus}. It is documented in Info (@pxref{Learning how to do +something}). + +@node Gnus does not work with NNTP, Viewing articles with embedded underlining, Reading news with Emacs, Mail and news +@section Why doesn't Gnus work via NNTP? +@cindex Gnus and NNTP +@cindex NNTP, Gnus fails to work with + +There is a bug in NNTP version 1.5.10, such that when multiple requests +are sent to the NNTP server, the server only handles the first one +before blocking waiting for more input which never comes. NNTP version +1.5.11 claims to fix this. + +You can work around the bug inside Emacs like this: + +@lisp +(setq nntp-maximum-request 1) +@end lisp + +You can find out what version of NNTP your news server is running by +telnetting to the NNTP port (usually 119) on the news server machine +(i.e., @kbd{telnet server-machine 119}). The server should give its +version number in the welcome message. Type @kbd{quit} to get out. + +@xref{Spontaneous entry into isearch-mode}, for some additional ideas. + +@node Viewing articles with embedded underlining, Saving a multi-part Gnus posting, Gnus does not work with NNTP, Mail and news +@section How do I view news articles with embedded underlining (e.g., ClariNews)? +@cindex Underlining, embedded in news articles +@cindex News articles with embedded underlining +@cindex Embedded underlining in news articles + +Underlining appears like this: + +@example +_^Hu_^Hn_^Hd_^He_^Hr_^Hl_^Hi_^Hn_^Hi_^Hn_^Hg +@end example + +@email{abraham@@dina.kvl.dk, Per Abrahamsen} suggests using the following +code, which uses the underline face to turn such text into true +underlining, inconjunction with Gnus: + +@lisp +(defun gnus-article-prepare-overstrike () + ;; Prepare article for overstrike commands. + (save-excursion + (set-buffer gnus-article-buffer) + (let ((buffer-read-only nil)) + (goto-char (point-min)) + (while (search-forward "\b" nil t) + (let ((next (following-char)) + (previous (char-after (- (point) 2)))) + (cond ((eq next previous) + (delete-region (- (point) 2) (point)) + (put-text-property (point) (1+ (point)) + 'face 'bold)) + ((eq next ?_) + (delete-region (1- (point)) (1+ (point))) + (put-text-property (1- (point)) (point) + 'face 'underline)) + ((eq previous ?_) + (delete-region (- (point) 2) (point)) + (put-text-property (point) (1+ (point)) + 'face 'underline)))))))) + +(add-hook 'gnus-article-prepare-hook 'gnus-article-prepare-overstrike) +@end lisp + +Latest versions of Gnus do such a conversion automatically. + +If you prefer to do away with underlining altogether, you can +destructively remove it with @kbd{M-x ununderline-region}; do this +automatically via + +@lisp +(add-hook 'gnus-article-prepare-hook + (lambda () (ununderline-region (point-min) (point-max)))) +@end lisp + +@node Saving a multi-part Gnus posting, Starting Gnus faster, Viewing articles with embedded underlining, Mail and news +@section How do I save all the items of a multi-part posting in Gnus? +@cindex Multi-part postings in Gnus, saving +@cindex Saving multi-part postings in Gnus +@cindex Gnus, saving multi-part postings in + +Use @code{gnus-uu}. Type @kbd{C-c C-v C-h} in the Gnus summary buffer +to see a list of available commands. + +@node Starting Gnus faster, Catching up in all newsgroups, Saving a multi-part Gnus posting, Mail and news +@section How do I make Gnus start up faster? +@cindex Faster, starting Gnus +@cindex Starting Gnus faster +@cindex Gnus, starting faster + +From the Gnus FAQ (@pxref{Learning more about Gnus}): + +@quotation +@email{pktiwari@@eos.ncsu.edu, Pranav Kumar Tiwari} writes: I posted +the same query recently and I got an answer to it. I am going to +repeat the answer. What you need is a newer version of gnus, version +5.0.4+. I am using 5.0.12 and it works fine with me with the +following settings: + +@lisp +(setq gnus-check-new-newsgroups nil + gnus-read-active-file 'some + gnus-nov-is-evil nil + gnus-select-method '(nntp gnus-nntp-server)) +@end lisp +@end quotation + +@node Catching up in all newsgroups, Killing based on nonstandard headers, Starting Gnus faster, Mail and news +@section How do I catch up all newsgroups in Gnus? +@cindex Catching up all newsgroups in Gnus +@cindex Gnus, Catching up all newsgroups in + +In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e} + +Leave off the initial @kbd{M-<} if you only want to catch up from point +to the end of the @file{*Newsgroup*} buffer. + +@node Killing based on nonstandard headers, Removing flashing messages, Catching up in all newsgroups, Mail and news +@section Why can't I kill in Gnus based on the Newsgroups/Keywords/Control headers? +@cindex Killing articles based on nonstandard headers +@cindex Newsgroups header, killing articles based on +@cindex Keywords header, killing articles based on +@cindex Control header, killing articles based on + +Gnus will complain that the @samp{Newsgroups}, @samp{Keywords}, and +@samp{Control} headers are ``Unknown header'' fields. + +For the @samp{Newsgroups} header, there is an easy workaround: kill on the +@samp{Xref} header instead, which will be present on any cross-posted article +(as long as your site carries the cross-post group). + +If you really want to kill on one of these headers, you can do it like +this: + +@lisp +(gnus-kill nil "^Newsgroups: .*\\(bad\\.group\\|worse\\.group\\)") +@end lisp + +@node Removing flashing messages, Catch-up is slow in Gnus, Killing based on nonstandard headers, Mail and news +@section How do I get rid of flashing messages in Gnus for slow connections? +@cindex Flashing Gnus messages, removing +@cindex Removing flashing Gnus messages +@cindex Slow connections causing flashing messages in Gnus +@cindex Gnus, flashing messages in + +Set @code{nntp-debug-read} to @code{nil}. + +@node Catch-up is slow in Gnus, Gnus hangs for a long time, Removing flashing messages, Mail and news +@section Why is catch up slow in Gnus? +@cindex Slow catch up in Gnus +@cindex Gnus is slow when catching up +@cindex Crosspostings make Gnus catching up slow + +Because Gnus is marking crosspostings read. You can control this with +the variable @code{gnus-use-cross-reference}. + +@node Gnus hangs for a long time, Learning more about Gnus, Catch-up is slow in Gnus, Mail and news +@section Why does Gnus hang for a long time when posting? +@cindex Hangs in Gnus +@cindex Gnus hangs while posting +@cindex Posting, Gnus hangs wile + +@email{tale@@uunet.uu.net, David Lawrence} explains: + +@quotation +The problem is almost always interaction between NNTP and C News. NNTP +POST asks C News's @code{inews} to not background itself but rather hang +around and give its exit status so it knows whether the post was successful. +(That wait will on some systems not return the exit status of the +waited for job is a different sort of problem.) It ends up taking a +long time because @code{inews} is calling @code{relaynews}, which often +waits for another @code{relaynews} to free the lock on the news system +so it can file the article. + +My preferred solution is to change @code{inews} to not call +@code{relaynews}, but rather use @code{newsspool}. This loses some +error-catching functionality, but is for the most part safe as +@code{inews} will detect a lot of the errors on its own. The C News +folks have sped up @code{inews}, too, so speed should look better to +most folks as that update propagates around. +@end quotation + +@node Learning more about Gnus, , Gnus hangs for a long time, Mail and news +@section Where can I find out more about Gnus? +@cindex FAQ for Gnus +@cindex Gnus FAQ +@cindex Learning more about Gnus + +For more information on Gnus, consult the Gnus manual and FAQ, which are +part of the Gnus distribution. + +@node Concept index, , Mail and news, Top +@unnumbered Concept Index +@printindex cp + +@contents +@bye + +@ignore + arch-tag: fee0d62d-06cf-43d8-ac21-123408eaf10f +@end ignore diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi new file mode 100644 index 00000000000..16947d7f2de --- /dev/null +++ b/doc/misc/flymake.texi @@ -0,0 +1,762 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License'' +in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 +@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 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-face +A custom face for highlighting lines for which at least one error has +been reported. + +@item flymake-warnline-face +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 (buffer) + (let* ((temp-file (flymake-init-create-temp-buffer-copy + buffer 'flymake-create-temp-inplace)) + (local-file (concat (flymake-build-relative-filename + (file-name-directory + (buffer-file-name + (current-buffer))) + (file-name-directory temp-file)) + (file-name-nondirectory temp-file)))) + (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-face} and +@code{flymake-warnline-face}. 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 00000000000..4114453df6c --- /dev/null +++ b/doc/misc/forms.texi @@ -0,0 +1,985 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@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. + +@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 + +@contents +@bye + +@ignore + arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed +@end ignore diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi new file mode 100644 index 00000000000..6bfb3477627 --- /dev/null +++ b/doc/misc/gnus-faq.texi @@ -0,0 +1,2307 @@ +@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 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 +Updated FAQ to reflect release of Gnus 5.10 and start of +No Gnus development. +@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 +* [1.1]:: What is the latest version of Gnus? +* [1.2]:: What's new in 5.10? +* [1.3]:: Where and how to get Gnus? +* [1.4]:: What to do with the tarball now? +* [1.5]:: I sometimes read references to No Gnus and Oort Gnus, what + are those? +* [1.6]:: Which version of Emacs do I need? +* [1.7]:: How do I run Gnus on both Emacs and XEmacs? +@end menu + +@node [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.10.8) should be at +least as stable as the latest release of the 5.8 series. + +@node [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 [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 +20 is outdated). +@c +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 [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 [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 [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 [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 +* [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? +* [2.2]:: Gnus doesn't remember which groups I'm subscribed to, + what's this? +* [2.3]:: How to change the format of the lines in Group buffer? +* [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? +* [2.5]:: How to manually sort the groups in Group buffer? How to + sort the groups in a topic? +@end menu + +@node [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 [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 [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 [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 [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 +* [3.1]:: I just installed Gnus, started it via @samp{M-x gnus} + but it only says "nntp (news) open error", what to do? +* [3.2]:: I'm working under Windows and have no idea what ~/.gnus.el + means. +* [3.3]:: My news server requires authentication, how to store user + name and password on disk? +* [3.4]:: Gnus seems to start up OK, but I can't find out how to + subscribe to a group. +* [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? +* [3.6]:: I want Gnus to fetch news from several servers, is this + possible? +* [3.7]:: And how about local spool files? +* [3.8]:: OK, reading news works now, but I want to be able to read + my mail with Gnus, too. How to do it? +* [3.9]:: And what about IMAP? +* [3.10]:: At the office we use one of those MS Exchange servers, can + I use Gnus to read my mail from it? +* [3.11]:: Can I tell Gnus not to delete the mails on the server it + retrieves via POP3? +@end menu + +@node [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 +* [4.1]:: When I enter a group, all read messages are gone. How to + view them again? +* [4.2]:: How to tell Gnus to show an important message every time I + enter a group, even when it's read? +* [4.3]:: How to view the headers of a message? +* [4.4]:: How to view the raw unformatted message? +* [4.5]:: How can I change the headers Gnus displays by default at + the top of the article buffer? +* [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? +* [4.7]:: Can I use some other browser than w3 to render my + HTML-mails? +* [4.8]:: Is there anything I can do to make poorly formatted mails + more readable? +* [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? +* [4.10]:: How can I disable threading in some (e.g. mail-) groups, + or set other variables specific for some groups? +* [4.11]:: Can I highlight messages written by me and follow-ups to + those? +* [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? +* [4.13]:: I don't like the layout of summary and article buffer, how + to change it? Perhaps even a three pane display? +* [4.14]:: I don't like the way the Summary buffer looks, how to + tweak it? +* [4.15]:: How to split incoming mails in several groups? +@end menu + +@node [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [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 +* [5.1]:: What are the basic commands I need to know for sending + mail and postings? +* [5.2]:: How to enable automatic word-wrap when composing messages? +* [5.3]:: How to set stuff like From, Organization, Reply-To, + signature...? +* [5.4]:: Can I set things like From, Signature etc group based on + the group I post too? +* [5.5]:: Is there a spell-checker? Perhaps even on-the-fly + spell-checking? +* [5.6]:: Can I set the dictionary based on the group I'm posting + to? +* [5.7]:: Is there some kind of address-book, so I needn't remember + all those email addresses? +* [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? +* [5.9]:: Sometimes I accidentally hit r instead of f in newsgroups. + Can Gnus warn me, when I'm replying by mail in newsgroups? +* [5.10]:: How to tell Gnus not to generate a sender header? +* [5.11]:: I want Gnus to locally store copies of my send mail and + news, how to do it? +* [5.12]:: People tell me my Message-IDs are not correct, why aren't + they and how to fix it? +@end menu + +@node [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 [5.2] +@subsubheading Question 5.2 + +How to enable automatic word-wrap when composing messages? + +@subsubheading Answer + +Say + +@example +(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 [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 [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 [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 [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 [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 [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 [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 [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 [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 [5.12] +@subsubheading Question 5.12 + +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 a 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, e.g. +@uref{http://www.stura.tu-freiberg.de/~dlx/addfqdn.html}. +(Sorry but this website is in German, if you know of an +English one offering the same, drop me a note). + +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 +* [6.1]:: How to import my old mail into Gnus? +* [6.2]:: How to archive interesting messages? +* [6.3]:: How to search for a specific message? +* [6.4]:: How to get rid of old unwanted mail? +* [6.5]:: I want that all read messages are expired (at least in some + groups). How to do it? +* [6.6]:: I don't want expiration to delete my mails but to move them + to another group. +@end menu + +@node [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 [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 [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 [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 [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 [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 +* [7.1]:: I don't have a permanent connection to the net, how can I + minimize the time I've got to be connected? +* [7.2]:: So what was this thing about the Agent? +* [7.3]:: I want to store article bodies on disk, too. How to do it? +* [7.4]:: How to tell Gnus not to try to send mails / postings while + I'm offline? +@end menu + +@node [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 [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 [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 [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 +* [8.1]:: How to find information and help inside Emacs? +* [8.2]:: I can't find anything in the Gnus manual about X (e.g. + attachments, PGP, MIME...), is it not documented? +* [8.3]:: Which websites should I know? +* [8.4]:: Which mailing lists and newsgroups are there? +* [8.5]:: Where to report bugs? +* [8.6]:: I need real-time help, where to find it? +@end menu + +@node [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 [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 [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 [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. +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. + +If you want to stay in the big8, +news.software.newssreaders is also read by some Gnus +users (but chances for qualified help are much better in +the above groups) and if you speak German, there's +de.comm.software.gnus. + +@node [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 [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 +* [9.1]:: Starting Gnus is really slow, how to speed it up? +* [9.2]:: How to speed up the process of entering a group? +* [9.3]:: Sending mail becomes slower and slower, what's up? +@end menu + +@node [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 [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 [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.texi b/doc/misc/gnus.texi new file mode 100644 index 00000000000..7cabf674102 --- /dev/null +++ b/doc/misc/gnus.texi @@ -0,0 +1,29508 @@ +\input texinfo + +@setfilename ../info/gnus +@settitle Gnus Manual +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex pg cp + +@copying +Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, +2002, 2003, 2004, 2005, 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@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.11} +\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 + +@ifnottex +@insertcopying +@end ifnottex + +@dircategory Emacs +@direntry +* Gnus: (gnus). The newsreader Gnus. +@end direntry +@iftex +@finalout +@end iftex +@setchapternewpage odd + + + +@titlepage +@title Gnus Manual + +@author by Lars Magne Ingebrigtsen +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + + +@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.11. + +@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. + +@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. + +@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. +* 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. +* 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. + +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. +* Rmail Babyl:: Emacs programs use the Rmail Babyl format. +* 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 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. +* GroupLens:: Getting predictions on what you like to read. +* Advanced Scoring:: Using logical expressions to build score rules. +* Score Decays:: It can be useful to let scores wither away. + +GroupLens + +* Using GroupLens:: How to make Gnus use GroupLens. +* Rating Articles:: Letting GroupLens know how you rate articles. +* Displaying Predictions:: Displaying predictions given by GroupLens. +* GroupLens Variables:: Customizing GroupLens. + +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. +* 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. + +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 + + +@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 run after starting up Gnus successfully. + +@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. +* 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. If you +want to work on this, please contact the Gnus mailing list. + +@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 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}. + + +@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-maximum-newsgroup +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-maximum-newsgroup} 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-maximum-newsgroup} 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 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. + + +@node Group Parameters +@section Group Parameters +@cindex group parameters + +The group parameters store information local to a particular group. +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 + +@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 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 + +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. +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} 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. +@code{dummy-variable} 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 + +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}). + +@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. + + +@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 next 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 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. + +@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. + +@item gnus-group-name-charset-method-alist +@vindex gnus-group-name-charset-method-alist +An alist of method and the charset for group names. It is used to show +non-@acronym{ASCII} group names. + +For example: +@lisp +(setq gnus-group-name-charset-method-alist + '(((nntp "news.com.cn") . cn-gb-2312))) +@end lisp + +@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. It +is used to show non-@acronym{ASCII} 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))) +@end lisp + +@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. +* 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. + +@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. + +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. + +All limiting commands work on subsets of the articles already fetched +from the servers. None of these commands 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 / 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 / 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 / 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}). + +@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}). + +@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-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-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 + '((lambda (t1 t2) + (not (gnus-thread-sort-by-number t1 t2))) + 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-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 +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 + + + +@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 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}). + +@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 +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. + +@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, @dfn{Babyl}. 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. +@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}, and +@code{gnus-summary-write-body-to-file}. + +@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. +@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 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éjà 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 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 b} 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 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 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{nil}. + +@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 "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-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-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-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}). + + +@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}. +@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 & +@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}). + +@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. + +@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 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. + +@vindex gnus-nov-is-evil +If you want Gnus to get the @code{Xref}s right all the time, you have to +set @code{gnus-nov-is-evil} to @code{t}, which slows things down +considerably. + +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 Gnus is called PGG (@pxref{Top, ,PGG, pgg, PGG +Manual}), but 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{pgg}, but +@code{mailcrypt} and @code{gpg} are also supported although +deprecated. + +@item mml2015-use +@vindex mml2015-use +Symbol indicating elisp interface to OpenPGP implementation for +@acronym{PGP/MIME} messages. The default is @code{pgg}, but +@code{mailcrypt} and @code{gpg} are also supported although +deprecated. + +@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-owner +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-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}). + +@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}). 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 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}). + +@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{last}: Do this treatment on the last 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, 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 +@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 given a prefix, make a +wide reply. 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 given a prefix, make +a wide reply. 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 emphasised 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. 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}. + +When sending mail, Message invokes @code{message-send-mail-function}. +The default 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}. + +Other possible choices for @code{message-send-mail-function} includes +@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail}, +and @code{feedmail-send-it}. + +@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. + + +@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: + +@lisp +(nnfolder "archive" + (nnfolder-directory "~/Mail/archive") + (nnfolder-active-file "~/Mail/archive/active") + (nnfolder-get-new-mail nil) + (nnfolder-inhibit-expiry t)) +@end lisp + +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 + +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. + +@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 telnet 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-telnet) + (nntp-via-address "the.firewall.machine") + (nntp-address "the.real.nntp.host") + (nntp-end-of-line "\n")) +@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}. + +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 +telnet connection to the news server as follows: + +@lisp +(nntp "outside" + (nntp-pre-command "runsocks") + (nntp-open-connection-function nntp-open-via-telnet) + (nntp-address "the.news.server") + (nntp-end-of-line "\n")) +@end lisp + +This means that you have to have set up @code{ssh-agent} correctly to +provide automatic authorization, of course. And to get a compressed +connection, you have to have the @samp{Compression} option in the +@code{ssh} @file{config} file. + + +@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. +Six pre-made functions are supplied. These functions can be grouped in +two categories: direct connection functions (four pre-made), and +indirect ones (two 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. +@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-telnet-stream +@item nntp-open-telnet-stream +Opens a connection to an @acronym{NNTP} server by simply @samp{telnet}'ing +it. 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-telnet-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. +@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-telnet +@findex nntp-open-via-rlogin-and-telnet +Does an @samp{rlogin} on a remote system, and then does a @samp{telnet} +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-telnet}-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, otherwise 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. +@end table + +@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 + +@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 connection function. + +@item nntp-telnet-command +@vindex nntp-telnet-command +Command to use when connecting to the @acronym{NNTP} server through +@samp{telnet}. This is @emph{not} for an intermediate host. This is +just for the real @acronym{NNTP} server. The default is +@samp{telnet}. + +@item nntp-telnet-switches +@vindex nntp-telnet-switches +A list of switches to pass to @code{nntp-telnet-command}. The default +is @samp{("-8")}. + +@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 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 + +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 receive 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 +@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}. + +@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 +(This 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. + +@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 +@vindex nnmail-spool-file +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 (and the obsolescent @code{nnmail-spool-file}) 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 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-fix-eudora-headers +@findex nnmail-fix-eudora-headers +@cindex Eudora +Eudora produces broken @code{References} headers, but OK +@code{In-Reply-To} headers. This function will get rid of the +@code{References} headers. + +@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 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. +* Rmail Babyl:: Emacs programs use the Rmail Babyl format. +* 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 Rmail Babyl +@subsubsection Rmail Babyl +@cindex nnbabyl +@cindex Rmail mbox + +@vindex nnbabyl-active-file +@vindex nnbabyl-mbox-file +The @dfn{nnbabyl} back end will use a Babyl mail box (aka. @dfn{Rmail +mbox}) 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 Rmail mbox file. The default is @file{~/RMAIL} + +@item nnbabyl-active-file +@vindex nnbabyl-active-file +The name of the active file for the rmail box. 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 is 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. + +@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 by Stallman. + +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'être} 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. If it is @code{nil}, in Emacs the coding system defaults to +the value of @code{default-file-name-coding-system}. If you are using +XEmacs and want to use non-@acronym{ASCII} group names, you should set +the value for the @code{nnmail-pathname-coding-system} variable properly. + +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-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 @code{"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. + +@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. + +@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 +@cindex Rmail mbox +@item babyl +The Babyl (Rmail) mail box. + +@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 D c} 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 even have to configure anything. + +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 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 gnus-agent-cat-name +The name of the category. + +@item gnus-agent-cat-groups +The list of groups that are in this category. + +@item gnus-agent-cat-predicate +A predicate which (generally) gives a rough outline of which articles +are eligible for downloading; and + +@item gnus-agent-cat-score-file +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 gnus-agent-cat-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 gnus-agent-cat-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 gnus-agent-cat-low-score +an integer that overrides the value of @code{gnus-agent-low-score}. + +@item gnus-agent-cat-high-score +an integer that overrides the value of @code{gnus-agent-high-score}. + +@item gnus-agent-cat-length-when-short +an integer that overrides the value of +@code{gnus-agent-short-article}. + +@item gnus-agent-cat-length-when-long +an integer that overrides the value of @code{gnus-agent-long-article}. + +@c @item gnus-agent-cat-disable-undownloaded-faces +@c a symbol indicating whether the summary buffer should @emph{not} display +@c undownloaded articles using the gnus-summary-*-undownloaded-face +@c faces. The symbol nil will enable the use of undownloaded faces while +@c all other symbols disable them. + +@item gnus-agent-cat-enable-undownloaded-faces +a symbol indicating whether the summary buffer should display +undownloaded articles using the gnus-summary-*-undownloaded-face +faces. The symbol nil will disable the use of undownloaded faces while +all other symbols enable them. +@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-fetch-series +Download all processable articles in this group. +(@code{gnus-agent-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 occasional Agent users, the undownloaded faces may appear to be an +absolutely horrible idea. The issue being that, since most of their +articles have not been fetched into the Agent, most of the normal +faces will be obscured by the undownloaded faces. If this is your +situation, you have two choices available. First, you can completely +disable the undownload faces by customizing +@code{gnus-summary-highlight} to delete the three cons-cells that +refer to the @code{gnus-summary-*-undownloaded-face} faces. Second, +if you prefer to take a more fine-grained approach, you may set the +@code{agent-disable-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}). + +@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 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. + +The first thing to keep in mind is that all flags (read, ticked, etc) +are kept on the @acronym{IMAP} server, rather than in @file{.newsrc} as is the +case for nntp. Thus Gnus need to remember flag changes when +disconnected, and synchronize these flags when you plug back in. + +Gnus keeps track of flag changes when reading nnimap groups under the +Agent. When you plug back in, Gnus will check if you have any changed +any flags and ask if you wish to synchronize these with the server. +The 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. + +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 + +Technical note: the synchronization algorithm does not work by ``pushing'' +all local flags to the server, but rather incrementally update 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 and +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 Outgoing Messages +@subsection Outgoing Messages + +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. + +When Gnus is plugged again, 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. + + + +@node Agent Variables +@subsection Agent Variables + +@table @code +@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-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-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 backends should be auto-agentized. It is typically only useful +to agentize remote backends. 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. +* GroupLens:: Getting predictions on what you like to read. +* 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 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, if 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-done +Save the changes you have made and return to the summary buffer +(@code{gnus-score-edit-done}). + +@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-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. + +Now, there's not much you can do about this 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 Gnus by default. +You can fetch it from +@uref{http://www.stud.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 GroupLens +@section GroupLens +@cindex GroupLens + +@sc{Note:} Unfortunately the GroupLens system seems to have shut down, +so this section is mostly of historical interest. + +@uref{http://www.cs.umn.edu/Research/GroupLens/, GroupLens} is a +collaborative filtering system that helps you work together with other +people to find the quality news articles out of the huge volume of +news articles generated every day. + +To accomplish this the GroupLens system combines your opinions about +articles you have already read with the opinions of others who have done +likewise and gives you a personalized prediction for each unread news +article. Think of GroupLens as a matchmaker. GroupLens watches how you +rate articles, and finds other people that rate articles the same way. +Once it has found some people you agree with it tells you, in the form +of a prediction, what they thought of the article. You can use this +prediction to help you decide whether or not you want to read the +article. + +@menu +* Using GroupLens:: How to make Gnus use GroupLens. +* Rating Articles:: Letting GroupLens know how you rate articles. +* Displaying Predictions:: Displaying predictions given by GroupLens. +* GroupLens Variables:: Customizing GroupLens. +@end menu + + +@node Using GroupLens +@subsection Using GroupLens + +To use GroupLens you must register a pseudonym with your local +@uref{http://www.cs.umn.edu/Research/GroupLens/bbb.html, Better Bit +Bureau (BBB)} is the only better bit in town at the moment. + +Once you have registered you'll need to set a couple of variables. + +@table @code + +@item gnus-use-grouplens +@vindex gnus-use-grouplens +Setting this variable to a non-@code{nil} value will make Gnus hook into +all the relevant GroupLens functions. + +@item grouplens-pseudonym +@vindex grouplens-pseudonym +This variable should be set to the pseudonym you got when registering +with the Better Bit Bureau. + +@item grouplens-newsgroups +@vindex grouplens-newsgroups +A list of groups that you want to get GroupLens predictions for. + +@end table + +That's the minimum of what you need to get up and running with GroupLens. +Once you've registered, GroupLens will start giving you scores for +articles based on the average of what other people think. But, to get +the real benefit of GroupLens you need to start rating articles +yourself. Then the scores GroupLens gives you will be personalized for +you, based on how the people you usually agree with have already rated. + + +@node Rating Articles +@subsection Rating Articles + +In GroupLens, an article is rated on a scale from 1 to 5, inclusive. +Where 1 means something like this article is a waste of bandwidth and 5 +means that the article was really good. The basic question to ask +yourself is, ``on a scale from 1 to 5 would I like to see more articles +like this one?'' + +There are four ways to enter a rating for an article in GroupLens. + +@table @kbd + +@item r +@kindex r (GroupLens) +@findex bbb-summary-rate-article +This function will prompt you for a rating on a scale of one to five. + +@item k +@kindex k (GroupLens) +@findex grouplens-score-thread +This function will prompt you for a rating, and rate all the articles in +the thread. This is really useful for some of those long running giant +threads in rec.humor. + +@end table + +The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be +the score of the article you're reading. + +@table @kbd + +@item 1-5 n +@kindex n (GroupLens) +@findex grouplens-next-unread-article +Rate the article and go to the next unread article. + +@item 1-5 , +@kindex , (GroupLens) +@findex grouplens-best-unread-article +Rate the article and go to the next unread article with the highest score. + +@end table + +If you want to give the current article a score of 4 and then go to the +next article, just type @kbd{4 n}. + + +@node Displaying Predictions +@subsection Displaying Predictions + +GroupLens makes a prediction for you about how much you will like a +news article. The predictions from GroupLens are on a scale from 1 to +5, where 1 is the worst and 5 is the best. You can use the predictions +from GroupLens in one of three ways controlled by the variable +@code{gnus-grouplens-override-scoring}. + +@vindex gnus-grouplens-override-scoring +There are three ways to display predictions in grouplens. You may +choose to have the GroupLens scores contribute to, or override the +regular Gnus scoring mechanism. override is the default; however, some +people prefer to see the Gnus scores plus the grouplens scores. To get +the separate scoring behavior you need to set +@code{gnus-grouplens-override-scoring} to @code{'separate}. To have the +GroupLens predictions combined with the grouplens scores set it to +@code{'override} and to combine the scores set +@code{gnus-grouplens-override-scoring} to @code{'combine}. When you use +the combine option you will also want to set the values for +@code{grouplens-prediction-offset} and +@code{grouplens-score-scale-factor}. + +@vindex grouplens-prediction-display +In either case, GroupLens gives you a few choices for how you would like +to see your predictions displayed. The display of predictions is +controlled by the @code{grouplens-prediction-display} variable. + +The following are valid values for that variable. + +@table @code +@item prediction-spot +The higher the prediction, the further to the right an @samp{*} is +displayed. + +@item confidence-interval +A numeric confidence interval. + +@item prediction-bar +The higher the prediction, the longer the bar. + +@item confidence-bar +Numerical confidence. + +@item confidence-spot +The spot gets bigger with more confidence. + +@item prediction-num +Plain-old numeric value. + +@item confidence-plus-minus +Prediction +/- confidence. + +@end table + + +@node GroupLens Variables +@subsection GroupLens Variables + +@table @code + +@item gnus-summary-grouplens-line-format +The summary line format used in GroupLens-enhanced summary buffers. It +accepts the same specs as the normal summary line format (@pxref{Summary +Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-23,23n%]%) +%s\n}. + +@item grouplens-bbb-host +Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the +default. + +@item grouplens-bbb-port +Port of the host running the bbbd server. The default is 9000. + +@item grouplens-score-offset +Offset the prediction by this value. In other words, subtract the +prediction value by this number to arrive at the effective score. The +default is 0. + +@item grouplens-score-scale-factor +This variable allows the user to magnify the effect of GroupLens scores. +The scale factor is applied after the offset. The default is 1. + +@end table + + +@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. +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 +@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. +* 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 + +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. + +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}. + +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 @samp{alt.nocem.misc} newsgroup. + +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 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" "news.admin.net-abuse.bulletins" + "alt.nocem.misc" "news.admin.net-abuse.announce") +@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 +("Automoose-1" "clewis@@ferret.ocunix.on.ca" + "cosmo.roadkill" "SpamHippo" "hweede@@snafu.de") +@end lisp +fine, upstanding citizens all of them. + +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 pgg-verify +This should be a function for verifying that the NoCeM issuer is who she +says she is. The default is @code{pgg-verify}, which returns +non-@code{nil} if the verification is successful, otherwise (including +the case the NoCeM message was not signed) returns @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{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. 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 has), 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. +@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. + +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 where Smiley will look for these +files: + +@table @code + +@item smiley-data-directory +@vindex smiley-data-directory +Where Smiley will look for smiley faces files. + +@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. + +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 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}). + +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-show-raw-article) + (gnus-summary-save-in-pipe "razor-report -f -d") + (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 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.cypherspace.org/~adam/hashcash/}. Even more +information can be found at @uref{http://www.camram.org/}. + +If you wish to call hashcash for each message you send, say something +like: + +@lisp +(require 'hashcash) +(add-hook 'message-send-hook 'mail-add-payment) +@end lisp + +The @file{hashcash.el} library can be found in the Gnus development +contrib directory or at +@uref{http://users.actrix.gen.nz/mycroft/hashcash.el}. + +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 0, meaning nothing will be +done. 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 +@vindex hashcash +Where the @code{hashcash} binary is installed. + +@end table + +Currently there is no built in functionality in Gnus to verify +hashcash cookies, it is expected that this is performed by your hand +customized mail filtering scripts. Improvements in this area would be +a useful contribution, however. + +@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. + +@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 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 backend 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 backend 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 @file{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.ham}. +@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:: +* 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. Note that this ham processor has no effect in @emph{spam} +or @emph{unclassified} groups. + +@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. + +@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. Note that this ham processor has no effect in @emph{spam} +or @emph{unclassified} groups. + +@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 use the @code{X-Report-Spam} header that +Gmane provides. + +@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. You must have the @code{hashcash.el} +package loaded for @code{spam-use-hashcash} to work properly. +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 +@file{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. Note that this ham processor has no effect in +@emph{spam} or @emph{unclassified} groups. + +@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 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. Note that this ham processor has no effect in +@emph{spam} or @emph{unclassified} groups. + +@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 @file{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 @file{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. Note that this ham processor has no effect in @emph{spam} or +@emph{unclassified} groups. + +@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 + +Add +@lisp +(spam-use-blackbox . spam-check-blackbox) +@end lisp +to @code{spam-list-of-checks}. + +Add +@lisp +(gnus-group-ham-exit-processor-blackbox ham spam-use-blackbox) +(gnus-group-spam-exit-processor-blackbox spam spam-use-blackbox) +@end lisp + +to @code{spam-list-of-processors}. + +Add +@lisp +(spam-use-blackbox spam-blackbox-register-routine + nil + spam-blackbox-unregister-routine + nil) +@end lisp + +to @code{spam-registration-functions}. Write the register/unregister +routines using the bogofilter register/unregister routines as a +start, or other register/unregister routines more appropriate to +Blackbox. + +@item +Functionality + +Write the @code{spam-check-blackbox} function. It 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. + +Make sure to add @code{spam-use-blackbox} to +@code{spam-list-of-statistical-checks} if Blackbox is a statistical +mail analyzer that needs the full message body to operate. + +@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}. + +@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 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 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 + +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. + +There are some vague differences between Gnus on the various +platforms---XEmacs features more graphics (a logo and a toolbar)---but +other than that, things should look pretty much the same under all +Emacsen. + + +@node Gnus Development +@subsection Gnus Development + +Gnus is developed in a two-phased cycle. The first phase involves much +discussion on the @samp{ding@@gnus.org} mailing list, 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 ``Red Gnus'' and ``Quassia Gnus''. + +After futzing around for 50-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.6.32'' instead. Normal people are +supposed to be able to use these, and these are mostly discussed on the +@samp{gnu.emacs.gnus} newsgroup. + +@cindex Incoming* +@vindex mail-source-delete-incoming +Some variable defaults differ between alpha Gnusae and released Gnusae. +In particular, @code{mail-source-delete-incoming} defaults to @code{nil} in +alpha Gnusae and @code{t} in released Gnusae. This is to prevent +lossage of mail if an alpha release hiccups while handling the mail. + +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. + + + +@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 +(@pxref{GroupLens}). + +@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ç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å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, +Marc Horowitz, +Gunnar Horrigmo, +Richard Hoskins, +Brad Howes, +Miguel de Icaza, +Franç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. +@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 (@pxref{GroupLens}). + +@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. @xref{Thwarting Email Spam}. +@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 + +@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} + +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 + +@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. This is a new +feature in Gnus 5.10.9. (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 + +@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 goes +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 differently. + + +@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} +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. + +@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 NNTP 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 @acronym{NNTP} 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 +This one has to be @code{nil}. If not, grabbing article headers from +the @acronym{NNTP} server will not be very fast. Not all @acronym{NNTP} servers +support @sc{xover}; Gnus will detect this by itself. +@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. + + +@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 @samp{Gnus v5.10.6} 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. + +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,96 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 + +@summarycontents +@contents +@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 00000000000..5b416d3cb41 --- /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 00000000000..4f216ac87b8 --- /dev/null +++ b/doc/misc/idlwave.texi @@ -0,0 +1,4327 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../info/idlwave +@settitle IDLWAVE User Manual +@dircategory Emacs +@direntry +* IDLWAVE: (idlwave). Major mode and shell for IDL files. +@end direntry +@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 + +@ifinfo +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 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end ifinfo + +@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 +This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for +IDLWAVE version @value{VERSION}, @value{DATE}. +@sp 2 +Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, + 2006, 2007 Free Software Foundation, Inc. +@sp 2 +@cindex Copyright, of IDLWAVE +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end titlepage +@contents + +@page + +@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. + +@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 00000000000..285ef09554e --- /dev/null +++ b/doc/misc/info.texi @@ -0,0 +1,1503 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and +modify this GNU Manual, like GNU software. Buying copies from GNU +Press supports the FSF 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, 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 + +@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 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 How to search 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 M-s @r{(Info mode)} + In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}. That is for +compatibility with other GNU packages that use @kbd{M-s} for a similar +kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the +command @code{Info-search}. + +@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 How to search 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/makefile.w32-in b/doc/misc/makefile.w32-in new file mode 100644 index 00000000000..7e3723c1949 --- /dev/null +++ b/doc/misc/makefile.w32-in @@ -0,0 +1,389 @@ +#### -*- Makefile -*- for the Emacs Manual and other documentation. + +# Copyright (C) 2003, 2004, 2005, 2006, 2007 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, 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; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + +# 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 $(infodir)/ccmode \ + $(infodir)/cl $(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 +DVI_TARGETS = emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \ + ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ + gnus.dvi message.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 emacs-xtra.dvi rcirc.dvi erc.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)/vc2-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. + +# 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)/dir: + $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) + +$(infodir)/info: $(INFOSOURCES) + $(MAKEINFO) --no-split -o $@ info.texi + +info.dvi: $(INFOSOURCES) + $(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi + +$(infodir)/emacs: $(EMACSSOURCES) + $(MAKEINFO) emacs.texi + +emacs.dvi: $(EMACSSOURCES) + $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi + +# This target is here so you could easily get the list of the *.texi +# files which belong to the Emacs manual (as opposed to the separate +# manuals for CL, CC Mode, Ebrowse, etc.). With this target, you can +# say things like "grep foo `make emacsman`". +emacsman: + @echo $(EMACSSOURCES) + +$(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)/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)/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 + +../etc/GNU: gnu1.texi gnu.texi + $(MAKEINFO) --no-headers -o ../etc/GNU gnu1.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 + +emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) + $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.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)/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 + +mostlyclean: + - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* + +clean: mostlyclean + - $(DEL) *.dvi + - $(DEL) $(infodir)/emacs* $(infodir)/ccmode* \ + $(infodir)/cl* $(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* + +distclean: clean + +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 00000000000..2bca4b046e5 --- /dev/null +++ b/doc/misc/message.texi @@ -0,0 +1,2362 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Message: (message). Mail and news composition mode that goes with Gnus. +@end direntry +@iftex +@finalout +@end iftex +@setchapternewpage odd + +@titlepage +@title Message Manual + +@author by Lars Magne Ingebrigtsen +@page + +@vskip 0pt plus 1filll +@insertcopying +@end titlepage +@page + +@node Top +@top Message + +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.11. + + +@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 will be removed from the @code{Cc} header. + +@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:}. + + + +@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-f +@kindex C-c C-f C-f +@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-o +@kindex C-c C-f C-o +@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}. + +@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}. + +@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 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 + +@vindex message-mail-alias-type +The @code{message-mail-alias-type} variable controls what type of mail +alias expansion to use. Currently only one form is supported---Message +uses @code{mailabbrev} to handle mail aliases. 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. + + +@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 + +@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. + +@end table + + +@node Mail Variables +@section Mail Variables + +@table @code +@item message-send-mail-function +@vindex 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 +Function used to send the current buffer as mail. The default is +@code{message-send-mail-with-sendmail}. Other valid values include +@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail}, +@code{message-smtpmail-send-it}, @code{smtpmail-send-it} and +@code{feedmail-send-it}. + +@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 + +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 and +empty lines which uses @code{message-yank-cited-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 no text or 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-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 sc-cite-original +@findex message-cite-original-without-signature +@cindex Supercite +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. You can also set it to @code{sc-cite-original} to use +Supercite. + +@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. +The default is @file{~/.signature}. + +@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-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-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. + +@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 + +@summarycontents +@contents +@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 00000000000..a6341e80465 --- /dev/null +++ b/doc/misc/mh-e.texi @@ -0,0 +1,9793 @@ +\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.0.3 +@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 2006-11-12 +@set UPDATE-MONTH November, 2006 + +@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 Free +Software Foundation, Inc. + +@quotation +The MH-E manual is free documentation; you can redistribute it and/or +modify it under the terms of either: + +@enumerate a +@item +the GNU Free Documentation License, Version 1.2 or any later version +published by the Free Software Foundation; with no Invariant Sections, +no Front-Cover Texts, and no Back-Cover Texts. + +@item +the GNU General Public License as published by the Free Software +Foundation; either version 3, or (at your option) any later version. +@end enumerate + +The MH-E manual 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 or GNU Free Documentation License for more +details. + +The GNU General Public License and the GNU Free Documentation License +appear as appendices to this document. You may also request copies by +writing to the Free Software Foundation, Inc., 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301, USA. +@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 +@setchapternewpage odd +@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 22.1. It is supported +in GNU Emacs 21, 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. 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 + +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}, 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}. 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 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 mailutils installed (for example) and +@code{mh-variant-in-use} was initialized to nmh but you want to use +mailutils, then you can set @code{mh-variant} to @samp{mailutils}. + +@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.0; nmh 1.1; GNU Emacs 22.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.0; nmh 1.1; GNU Emacs 22.1 +-------- +# + +--:-- @{draft@} All L10 (MH-Letter)---------------------------------- +To: wohler +Subject: Test +X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.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 22 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 ------------------------- +@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, report a bug (@pxref{Bug +Reports}). + +@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. + +@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 +@kindex S-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} or with @kbd{S-Mouse-2} to view +the content of the link in an external browser. 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 + +@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-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 + +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 @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-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 + +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. +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. + +@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.0; nmh 1.1; GNU Emacs 22.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. + +@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. 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) 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) 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 mailutils 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 will appear in Emacs 22.1, +expected to be released in 2006. + +Bill Wohler, February 2006 + +@node GFDL, GPL, History, Top +@appendix GNU FREE DOCUMENTATION LICENSE +@center Version 1.2, November 2002 + +@display +Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display +@sp 1 +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document ``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. + +@sp 1 +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque.'' + + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +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. +@sp 1 +@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. +@sp 1 +@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. +@sp 1 +@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: + +A. 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.@* +B. 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.@* +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher.@* +D. Preserve all the copyright notices of the Document.@* +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices.@* +F. 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.@* +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice.@* +H. Include an unaltered copy of this License.@* +I. 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.@* +J. 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.@* +K. 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.@* +L. 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.@* +M. Delete any section Entitled ``Endorsements.'' Such a section + may not be included in the Modified Version.@* +N. Do not retitle any existing section to be Entitled ``Endorsements'' + or to conflict in title with any Invariant Section.@* +O. Preserve any Warranty Disclaimers.@* +@sp 1 +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. +@sp 1 +@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.'' +@sp 1 +@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. +@sp 1 +@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. +@sp 1 +@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. +@sp 1 +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. +@sp 1 +@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 +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +@end enumerate + +@unnumberedsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group +Copyright (C) @var{year} @var{your name}. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group +with the Invariant Sections being @var{list their titles}, with the +Front-Cover Texts being @var{list}, and with the Back-Cover Texts being +@var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@node GPL, Key Index, GFDL, Top +@appendix GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) 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 +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program,'' below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification.'') Each licensee is addressed as ``you.'' + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute 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 and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +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 +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the 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 a version number of this License which applies to it and ``any +later version,'' you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, 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 +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE 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. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec 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 +convey 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 an idea of what it does.} +Copyright (C) @var{yyyy} @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, write to the Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) @var{yyyy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `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, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +@group +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end group +@end smallexample + +This 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. + +@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 00000000000..48d7f992667 --- /dev/null +++ b/doc/misc/newsticker.texi @@ -0,0 +1,290 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header +@setfilename ../info/newsticker +@set VERSION 1.9 +@set UPDATED November 2005 +@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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License'' +in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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://de.geocities.com/ulf_jasper} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Newsticker +@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 +should work 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", or "RSS +aggregator". + +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 requires a program which can retrieve files via http and +prints them to stdout. By default Newsticker will use +@uref{http://www.gnu.org/software/wget/wget.html, wget} for this task. + + +@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 in a special buffer, called @samp{*newsticker*}. It will +also start the asynchronous download of headlines. The modeline in +the @samp{*newsticker*} buffer informs whenever new headlines have +arrived. Clicking mouse-button 2 or pressing RET in this buffer 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. + +Newsticker options are organized in the following groups. + +@itemize + +@item +@code{newsticker-feed} 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-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. +@end itemize + +@item +@code{newsticker-layout} contains options that define how the +buffer for reading news headlines is formatted. + +@itemize +@item +@vindex newsticker-heading-format +@code{newsticker-item-format} defines how the title of a headline +is formatted. +@end itemize + +@item +@code{newsticker-ticker} contains options that define how headlines +are shown in the echo area. + +@itemize +@item +@vindex newsticker-display-interval +@vindex newsticker-scroll-smoothly +@code{newsticker-display-interval} and +@code{newsticker-scroll-smoothly} define how headlines are shown in +the echo area. +@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. +@end itemize + +@item +@code{newsticker-miscellaneous} contains other Newsticker options. + +@end itemize + +Please have a look at the customization buffers for the complete list +of options. + +@node Remarks +@chapter Remarks + +This newsticker is designed do its job silently in the background +without disturbing you. However, it is probably impossible to prevent +such a tool from slightly attenuating your Editor's responsiveness +every once in a while. + +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/org.texi b/doc/misc/org.texi new file mode 100644 index 00000000000..f3b13511571 --- /dev/null +++ b/doc/misc/org.texi @@ -0,0 +1,7931 @@ +\input texinfo +@c %**start of header +@setfilename ../info/org +@settitle Org Mode Manual + +@set VERSION 5.07 +@set DATE August 2007 + +@dircategory Emacs +@direntry +* Org Mode: (org). Outline-based notes management and organizer +@end direntry + +@c Version and Contact Info +@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage} +@set AUTHOR Carsten Dominik +@set MAINTAINER Carsten Dominik +@set MAINTAINEREMAIL @email{dominik at science dot uva dot nl} +@set MAINTAINERCONTACT @uref{mailto:dominik at science dot uva dot nl,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-mode (version @value{VERSION}). + +Copyright @copyright{} 2004, 2005, 2006, 2007 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.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end quotation +@end copying + +@titlepage +@title Org Mode 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:: +* Timestamps:: Assign date and time to items +* 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-mode files +* Miscellaneous:: All the rest which did not fit elsewhere +* Extensions and Hacking:: It is possible to write add-on code +* History and Acknowledgments:: How Org-mode came into being +* Index:: The fast road to specific information +* Key Index:: Key bindings and where they are described + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Summary:: Brief summary of what Org-mode does +* Installation:: How to install a downloaded version of Org-mode +* Activation:: How to activate Org-mode for certain buffers. +* Feedback:: Bug reports, ideas, patches etc. + +Document Structure + +* Outlines:: Org-mode 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 +* orgstruct-mode:: Structure editing outside Org-mode + +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. + +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-mode 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-mode:: 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 +* Remember:: Org-trees store quick notes + +Internal links + +* Radio targets:: Make targets trigger links in plain text. + +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 + +TODO items + +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* 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 the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements + +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 +* 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 + +Defining Columns + +* Scope of column definitions:: Where defined, where valid? +* Column attributes:: Appearance and content of a column + +Timestamps + +* Time stamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Progress logging:: Documenting when what work was done. + +Creating timestamps + +* The date/time prompt:: How org-mode helps you entering date and time +* Custom time format:: Making dates look differently + +Deadlines and Scheduling + +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again + +Progress Logging + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Clocking work time:: When exactly did you work on this item? + +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 + +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 +* 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. +* Extracting Agenda Information for 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 + +* ASCII export:: Exporting to plain ASCII +* HTML export:: Exporting to HTML +* LaTeX export:: Exporting to LaTeX +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format +* Text interpretation:: How the exporter looks at the file + +HTML export + +* HTML Export commands:: How to invoke LaTeX export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links:: Transformation of links for HTML +* Images:: How to include images +* CSS support:: Changing the appearence of the output + +LaTeX export + +* LaTeX export commands:: How to invoke LaTeX export +* Quoting LaTeX code:: Incorporating literal LaTeX code + +Text interpretation by the exporter + +* Comment lines:: Some lines will not be exported +* Initial text:: Text before the first headline +* Footnotes:: Numbers like [1] +* Enhancing text:: Subscripts, symbols and more +* Export options:: How to influence the export settings + +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-mode 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-mode on a tty +* Interaction:: Other Emacs packages +* Bugs:: Things which do not work perfectly + +Interaction with other packages + +* Cooperation:: Packages Org-mode cooperates with +* Conflicts:: Packages that lead to conflicts + +Extensions, Hooks and Hacking + +* Extensions:: Existing 3rd-part extensions +* 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 + +Tables in arbitrary syntax + +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify + +@end detailmenu +@end menu + +@node Introduction, Document structure, Top, Top +@chapter Introduction +@cindex introduction + +@menu +* Summary:: Brief summary of what Org-mode does +* Installation:: How to install a downloaded version of Org-mode +* Activation:: How to activate Org-mode for certain buffers. +* Feedback:: Bug reports, ideas, patches etc. +@end menu + +@node Summary, Installation, Introduction, Introduction +@section Summary +@cindex summary + +Org-mode is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. + +Org-mode develops organizational tasks around NOTES files that contain +lists or information about projects as plain text. Org-mode 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-mode 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-mode 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 webpages. + +An important design aspect that distinguishes Org-mode 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-mode, +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-mode 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-mode 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 export} +@r{@bullet{} publishing tool to create a set of interlinked webpages} +@end example + +Org-mode'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-mode with +the minor Orgstruct-mode. + +@cindex FAQ +There is a website for Org-mode which provides links to the newest +version of Org-mode, as well as additional information, frequently asked +questions (FAQ), links to tutorials etc. This page is located at +@uref{http://www.astro.uva.nl/~dominik/Tools/org/}. + +@page + + +@node Installation, Activation, Summary, Introduction +@section Installation +@cindex installation +@cindex XEmacs + +@b{Important:} @i{If Org-mode 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-mode from the Web, you must take the +following steps to install it: Go into the Org-mode 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, create your own two directories for these files, enter them +into the Makefile, and make sure Emacs finds the Lisp files by adding +the following line to @file{.emacs}: + +@example +(setq load-path (cons "~/path/to/lispdir" load-path)) +@end example + +@b{XEmacs users now need to install the file @file{noutline.el} from +the @file{xemacs} subdirectory of the Org-mode distribution. Use the +command:} + +@example +@b{make install-noutline} +@end example + +@noindent Now byte-compile and install the Lisp files with the shell +commands: + +@example +make +make install +@end example + +@noindent If you want to install the info documentation, use this command: + +@example +make install-info +@end example + +@noindent Then add to @file{.emacs}: + +@lisp +;; This line only if org-mode is not part of the X/Emacs distribution. +(require 'org-install) +@end lisp + +@node Activation, Feedback, Installation, Introduction +@section Activation +@cindex activation +@cindex autoload +@cindex global keybindings +@cindex keybindings, global + +@iftex +@b{Important:} @i{If you use copy-and-paste to copy lisp code from the +PDF documentation as viewed by Acrobat reader 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 two lines +define @emph{global} keys for the commands @command{org-store-link} and +@command{org-agenda} - 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) +@end lisp + +Furthermore, you must activate @code{font-lock-mode} in org-mode +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-mode 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}. + +@node Feedback, , Activation, Introduction +@section Feedback +@cindex feedback +@cindex bug reports +@cindex maintainer +@cindex author + +If you find problems with Org-mode, or if you have questions, remarks, +or ideas about it, please contact the maintainer @value{MAINTAINER} at +@value{MAINTAINEREMAIL}. + +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-mode (@kbd{C-h v org-version @key{RET}}), as well as +the Org-mode 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-mode 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 Document structure, Tables, Introduction, Top +@chapter Document Structure +@cindex document structure +@cindex structure of document + +Org-mode is based on outline mode and provides flexible commands to +edit the structure of the document. + +@menu +* Outlines:: Org-mode 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 +* orgstruct-mode:: Structure editing outside Org-mode +@end menu + +@node Outlines, Headlines, Document structure, Document structure +@section Outlines +@cindex outlines +@cindex outline-mode + +Org-mode 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-mode 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-mode 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-mode 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 numerical prefix 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-c C-a +@item C-c C-a +Show all. +@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 +exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda +command (@pxref{Agenda commands}). With prefix arg 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 numerical +prefix ARG, go up to this level and then take that tree. If ARG is +negative, go up that many levels. With @kbd{C-u} prefix, do not remove +the previously used indirect buffer. +@end table + +When Emacs first visits an Org-mode 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 + +@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.} +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.} +@key{RET} @r{Select this location.} +@end example +@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 arg, 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. 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 M-S-@key{RET} +@item M-S-@key{RET} +Insert new TODO entry with same level as current heading. +@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 +@kindex C-c C-x C-k +@item C-c C-x C-w +@itemx C-c C-x C-k +Kill subtree, i.e. remove it from buffer but save in kill ring. +@kindex C-c C-x M-w +@item C-c C-x M-w +Copy subtree to kill ring. +@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 prefix arg, or by yanking after a +headline marker like @samp{****}. +@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, and each of these in reverse order. 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. +@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}. +@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 C-a +@item C-c C-x C-a +Toggle the ARCHIVE tag for the current headline. When the tag is set, +the headline changes to a shadowish face, and the subtree below it is +hidden. +@kindex C-u C-c C-x C-a +@item C-u C-c C-x C-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, either in the current file, or even in a different +file, the archive file. + +@table @kbd +@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 + +@example +#+ARCHIVE: %s_done:: +@end example + +@noindent +You may have several such lines in the buffer, they will then be valid +for the entries following the line (the first will also apply to any +text before it). + +@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. A +sparse tree means 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}, and +@code{org-show-siblings} 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. The most +basic one is @command{org-occur}: + +@table @kbd +@kindex C-c / +@item C-c / +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, 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}. + +Other commands use sparse trees as well. For example @kbd{C-c +C-v} creates a sparse TODO tree (@pxref{TODO basics}). + +@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-mode supports editing such lists, +and the HTML exporter (@pxref{Exporting}) does parse and format them. + +Org-mode knows ordered and unordered lists. 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 not to use it for plain list items.} as +bullets. Ordered list items start with @samp{1.} or @samp{1)}. 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. Eowyns 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, not individual scenes matter but the film as a whole. +@end group +@end example + +Org-mode supports these lists by tuning filling and wrapping commands to +deal with them correctly@footnote{Org-mode 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)}}. + +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 curent line in a heuristic way. +@kindex M-@key{RET} +@item M-@key{RET} +Insert new item at current level. With prefix arg, 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. 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} +Jump to the previous/next item in the current list. +@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, make 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 prefix arg, select the nth bullet from this list. +@end table + +@node Drawers, orgstruct-mode, 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}, and +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}). + +@node orgstruct-mode, , Drawers, 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-mode 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-mode has a very fast and intuitive table editor built-in. +Spreadsheet-like calculations are supported in connection with the +Emacs @file{calc} package. + +@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. +@end menu + +@node Built-in table editor, Narrow columns, Tables, Tables +@section The built-in table editor +@cindex table editor, built-in + +Org-mode 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. + +When typing text into a field, Org-mode 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 not, lines are split at whitespace into fields. You can use a prefix +argument to indicate the minimum number of consecutive spaces required +to identify a field separator (default: just one).@* +If there is no active region, this command creates an empty Org-mode +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 (with arg: below) the current row. +@c +@kindex C-c - +@item C-c - +Insert a horizontal line below current row. With prefix arg, the line +is created above the current 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 right 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 C-c C-q +@item C-c C-q +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 +prefix ARG 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 ARG, 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. 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 +@kindex C-c @key{TAB} +@item C-c @key{TAB} +This is an alias for @kbd{C-u C-c `} to make the current field fully +visible. +@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 an Excel 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-mode +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 as a TAB-separated file. Useful for data exchange with, +for example, Excel or database programs. +@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-mode 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 colum 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 colum 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-mode 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, , 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-mode's +implementation is not identical to other spreadsheets. For example, +Org-mode 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-mode, 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-mode's @code{B3} behaves like @code{$B$3} in other spreadsheets. + +@noindent +Org-mode 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, @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-mode'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-mode'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. + +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. + +@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-mode 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 the 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 concious 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, enclode 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 the 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. + +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-mode 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-mode 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 numerical prefix (e.g. @kbd{C-5 C-c =}) +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-mode can also prepare a special buffer with all active +formulas of a table. When offering a formula for editing, Org-mode +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-mode 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-mode 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{$}. The meaning of these characters +is discussed below. 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 | +| # | Sara | 6 | 14 | 19 | 39 | 7.8 | +| # | 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 +(homework: try that with Excel :-) + +@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 + +@node Hyperlinks, TODO items, Tables, Top +@chapter Hyperlinks +@cindex hyperlinks + +Just like HTML, Org-mode provides links inside a file, and external +links to other files, Usenet articles, emails, and much more. + +@menu +* Link format:: How links in Org-mode 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-mode:: 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 +* Remember:: Org-trees store quick notes +@end menu + +@node Link format, Internal links, Hyperlinks, Hyperlinks +@section Link format +@cindex link format +@cindex format, of links + +Org-mode 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-mode +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.}. + +If no dedicated target exists, Org-mode 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-mode'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-mode 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-mode 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 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-mode supports links to files, websites, Usenet and email messages, +and BBDB database entries. 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} +file:papers/last.pdf @r{file, relative path} +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:Richard Stallman @r{BBDB link} +shell:ls *.org @r{A shell command} +elisp:(find-file-other-frame "Elisp.org") @r{An 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-mode 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-mode, External links, Hyperlinks +@section Handling links +@cindex links, handling + +Org-mode provides methods to create a link in the correct syntax, to +insert it into an org-mode 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 +which can be used in any buffer to create a link. The link will be +stored for later insertion into an Org-mode buffer (see below). For +Org-mode files, if there is a @samp{<>} at the cursor, the link +points to the target. Otherwise it points to the current headline. 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 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}. 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 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-mode +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 subdirectory 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 +@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. +@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-mode, Link abbreviations, Handling links, Hyperlinks +@section Using links outside Org-mode + +You can insert and follow links that have Org-mode syntax not only in +Org-mode, 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-mode, 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-mode author is +doing besides Emacs hacking with @code{[[ads:Dominik,C]]}. + +If you need special abbreviations just for a single Org-mode 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-mode 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, Remember, 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-mode actually uses this mechanism +for Bib@TeX{} database files, and you can use the corresponding code as +an implementation example. Search for @samp{BibTeX links} in the source +file. + + +@node Remember, , Custom searches, Hyperlinks +@section Remember +@cindex @file{remember.el} + +Another way to create org entries with links to other files is through +the @i{remember} package by John Wiegley. @i{Remember} 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. The notes produced by @i{Remember} can be stored in +different ways, and Org-mode files are a good target. Org-mode +significantly expands the possibilities of @i{remember}: You may define +templates for different note types, and to 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 +@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-mode links. + +@example +(setq org-directory "~/path/to/my/orgfiles/") +(setq org-default-notes-file "~/.notes") +(setq remember-annotation-functions '(org-remember-annotation)) +(setq remember-handler-functions '(org-remember-handler)) +(add-hook 'remember-mode-hook 'org-remember-apply-template) +@end example + +@node Remember templates, Storing notes, Setting up remember, Remember +@subsection Remember templates +@cindex templates, for remember + +In combination with Org-mode, 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 + '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org") + (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") + (?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) +@end example + +@noindent In these entries, the character specifies how to select the +template. The first 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 defaults (if not present or @code{nil}) +to @code{org-default-notes-file}, the heading to +@code{org-remember-default-headline}. Both defaults help to get to the +storing location quickly, but you can change the location interactively +while storing the note. + +When you call @kbd{M-x remember} (or @kbd{M-x org-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 or + +@example +* [2006-03-21 Tue 15:37] + + [[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.} +%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})} +%a @r{annotation, normally the link created with @code{org-store-link}} +%i @r{initial content, the region when remember is called with C-u.} + @r{The entire text will be indented like @code{%i} itself.} +%^g @r{prompt for tags, with completion on tags in target file.} +%^G @r{prompt for tags, with completion all tags in all agenda files.} +%:keyword @r{specific information for certain link types, see below} +@end example + +@noindent +For specific link types, the following keywords will be defined: + +@example +Link type | Available keywords +-------------------+---------------------------------------------- +bbdb | %:name %:company +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 you 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, , 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. The handler first prompts 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 better 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 buffer-start @tab @key{RET} @tab as level 2 heading at end of file +@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor +@item @tab @key{left}/@key{right} @tab as same level, before/after current heading +@item not on headline @tab @key{RET} + @tab at cursor position, level taken from context. +@end multitable + +So a fast way to store the note to its default location is to press +@kbd{C-c C-c @key{RET} @key{RET}}. Even shorter would be @kbd{C-u C-c +C-c}, which does the same without even asking for a file or showing the +tree. + +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 and some +additional data. If the variable @code{org-adapt-indentation} is +non-nil, the entire text is also indented so that it starts in the +same column as the headline (after the asterisks). + + +@node TODO items, Tags, Hyperlinks, Top +@chapter TODO items +@cindex TODO items + +Org-mode does not maintain TODO lists as a separate document. TODO +items are an integral part of the notes file, because TODO items +usually come up while taking notes! With Org-mode, you simply mark +any entry in a tree as being a TODO item. In this way, the +information is not duplicated, and the entire context from which the +item emerged is always present when you check. + +Of course, this technique causes TODO items to be scattered throughout +your file. Org-mode provides methods to give you an overview over all +things you have to do. + +@menu +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* 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 can become a TODO item by starting it with the word 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 S-@key{right} +@kindex S-@key{left} +@item S-@key{right} +@itemx S-@key{left} +Select the following/preceding TODO state, similar to cycling. Mostly +useful if more than two TODO states are possible (@pxref{TODO +extensions}). +@kindex C-c C-c +@item C-c C-c +Use the fast tag interface to quickly and directly select a specific +TODO state. For this you need to assign keys to TODO state, like this: +@example +#+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) +@end example +@noindent See @ref{Per file keywords} and @ref{Setting tags} for more +information. +@kindex C-c C-v +@cindex sparse tree, for TODO +@item C-c C-v +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 prefix arg, 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 numerical prefix N, show the tree for the +Nth keyword in the variable @code{org-todo-keywords}. With two prefix +args, find all TODO and DONE entries. +@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}). +@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 + +@node TODO extensions, Priorities, TODO basics, TODO items +@section Extended use of TODO keywords +@cindex extended TODO keywords + +The default implementation of TODO entries is just two states: TODO and +DONE. You can use the TODO feature for more complicated things by +configuring the variable @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 the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements +@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 prefix argument to quickly select a specific state. For +example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY. +If you define many keywords, you can use in-buffer completion (see +@ref{Completion}) 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 prefix arg as well when +creating the global todo list: @kbd{C-3 C-c t}. + +@node Multiple sets in one file, Per file keywords, 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} +@item 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-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}. +@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. +@end table + +@node Per file keywords, , Multiple sets in one file, 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 Priorities, Breaking down tasks, TODO extensions, TODO items +@section Priorities +@cindex priorities + +If you use Org-mode extensively to organize your work, you may end up +with a number of TODO entries so large that you'd like to prioritize +them. This can be done by placing a @emph{priority cookie} into the +headline, like this + +@example +*** TODO [#A] Write letter to Sam Fortune +@end example + +@noindent +With its standard setup, Org-mode supports 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}). + +@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. Note that these keys +are also used to modify time stamps (@pxref{Creating timestamps}). +Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}). +@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}.}. 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 a checkbox +by starting it with the string @samp{[ ]}. This feature is similar to +TODO items (@pxref{TODO items}), but 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 try Piotr Zielinski's +@file{org-mouse.el}. Here is an example of a checkbox list. + +@example +* TODO Organize party [3/6] + - call people [1/3] + - [ ] Peter + - [X] Sarah + - [ ] Sam + - [X] order food + - [ ] think about what music to play + - [X] talk to the neighbors +@end example + +@cindex statistics, for checkboxes +@cindex checkbox statistics +The @samp{[3/6]} and @samp{[1/3]} in the first and second line are +cookies indicating how many checkboxes are present in this entry, and +how many of them have been checked off. 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 +that headline/item. You have to insert the cookie yourself by typing +either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n +out of m} result, in the second case 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 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 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. If you +want to toggle all boxes in the region independently, use a prefix +argument. +@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 synch. 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 + +If you wish to implement a system of labels and contexts for +cross-correlating information, an excellent way is to assign @i{tags} to +headlines. Org-mode has extensive support for using tags. + +Every headline can contain a list of tags, 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; like +@samp{:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}. + +@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 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:}. When executing tag searches and +Org-mode finds that a certain headline matches the search criterion, it +will not check any sublevel headline, assuming that these likely also +match, and that the list of matches can become very long. This may +not be what you want, however, and you can influence inheritance and +searching using the variables @code{org-use-tag-inheritance} and +@code{org-tags-match-list-sublevels}. + +@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-c +@item C-c C-c +@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}). +@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: Just add an empty TAGS option line to that file: + +@example +#+TAGS: +@end example + +The default support method for entering tags is minibuffer completion. +However, Org-mode also implements a much better method: @emph{fast tag +selection}. This method allows to select and deselect tags with a +single key per tag. To function efficiently, you should assign unique +keys to most tags. This can be done globally with + +@lisp +(setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l))) +@end lisp + +@noindent or on a per-file basis with + +@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. With +curly braces@footnote{In @code{org-mode-alist} use +@code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several +groups are allowed.} + +@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. + +@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of +these lines to activate any changes. + +If at least one tag has a selection key, 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 legal 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 keypress 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 tags system has been set up, it can be used to collect related +information into special lists. + +@table @kbd +@kindex C-c \ +@item C-c \ +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 +If you are using multi-state TODO keywords (@pxref{TODO extensions}), it +can be useful to also match on the TODO keyword. This can be done by +adding a condition after a slash to a tags match. The syntax is 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, use @kbd{C-c a +M}, or equivalently start the todo part after the slash with @samp{!}. +Examples: + +@table @samp +@item WORK/WAITING +Select @samp{:WORK:}-tagged TODO lines with the specific TODO +keyword @samp{WAITING}. +@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}. + +@cindex level, require for tags match +You can also require a headline to be of a certain level, by writing +instead of any TAG an expression like @samp{LEVEL=3}. For example, a +search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that +have the tag BOSS and are @emph{not} marked with the todo keyword DONE. + +@node Properties and columns, Timestamps, 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. For example, in 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:}, it can be more +efficient to use a property @code{RELEASE} with a value @code{1.0} or +@code{2.0}. Second, you can use properties to implement (very basic) +database capabilities in an Org-mode buffer, for example to create a +list of Music CD's you own. You can edit and view properties +conveniently 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 +* 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" Phillips 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-mode 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. +@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. +@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}). 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.} +@end example + +@node Property searches, Column view, Special properties, Properties and columns +@section Property searches +@cindex properties, searching + +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, a search string + +@example ++WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with=@{Sarah\|Denny@} +@end example + +@noindent +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}, and a @samp{:with:} property that is matched by +the regular expression @samp{Sarah\|Denny}. + +@node Column view, Property API, Property searches, 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 +@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 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.} + @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.} + @{X@} @r{Checkbox status, [X] if all children are [X].} +@end example + +@noindent +Here is an example for a complete columns definition, along with allowed +values. + +@example +:COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status %10Time_Spent@{:@} +: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 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_Spent} 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. + +@node Using 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 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. +@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 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 right of the current column. +@kindex S-M-@key{left} +@item S-M-@key{left} +Delete the current column. +@end table + +@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 Timestamps, Agenda views, Properties and columns, Top +@chapter Timestamps +@cindex time stamps +@cindex date stamps + +Items can be labeled with timestamps to make them useful for project +planning. + +@menu +* Time stamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Progress logging:: Documenting when what work was done. +@end menu + + +@node Time stamps, Creating timestamps, Timestamps, Timestamps +@section Time stamps, 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. If +you cannot get used to these, 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 +@cindex timestamp +A simple time stamp just assigns a date/time to an item. This is just +like writing down an appointment in a paper agenda, or like writing down +an event in a diary, when you want to take note of when something +happened. 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, Time stamps, Timestamps +@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 a previously used time stamp, it is updated to NOW. 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, goto 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 prefix arg, 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 differently +@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 prompt suggests to enter an +ISO date. But it will in fact accept any string containing some date +and/or time information. 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 will replace anything not +specified with the current date and time. For example: + +@example + 3-2-5 --> 2003-02-05 + feb 15 --> currentyear-02-15 + sep 12 9 --> 2009-09-12 + 12:45 --> today 12:45 + 22 sept 0:34 --> currentyear-09-22 0:34 + 12 --> currentyear-currentmonth-12 + Fri --> nearest Friday (today or later) + +4 --> 4 days from now (if +N is the only thing given) +@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: + +@table @kbd +@kindex < +@item < +Scroll calendar backwards by one month. +@kindex > +@item > +Scroll calendar forwards by one month. +@kindex mouse-1 +@item mouse-1 +Select date by clicking on it. +@kindex S-@key{right} +@item S-@key{right} +One day forward. +@kindex S-@key{left} +@item S-@key{left} +One day back. +@kindex S-@key{down} +@item S-@key{down} +One week forward. +@kindex S-@key{up} +@item S-@key{up} +One week back. +@kindex M-S-@key{right} +@item M-S-@key{right} +One month forward. +@kindex M-S-@key{left} +@item M-S-@key{left} +One month back. +@kindex @key{RET} +@item @key{RET} +Choose date in calendar (only if nothing was typed into minibuffer). +@end table + +@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, Progress logging, Creating timestamps, Timestamps +@section Deadlines and Scheduling + +A time stamp may be preceded by special keywords to facilitate planning +of work: + +@table @var +@item DEADLINE +@cindex DEADLINE keyword +The task (most likely a TODO item) is supposed to be finished on that +date, and it will be listed then. In addition, the compilation 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 +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 +@end table + +@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 deadline/schedule + +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. +@c FIXME Any CLOSED timestamp will be removed.???????? +@c +@kindex C-c C-w +@cindex sparse tree, for deadlines +@item C-c C-w +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 C-w} 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. +@end table + +@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling +@subsection Repeated Tasks + +Some tasks need to be repeated again and again, and Org-mode therefore +allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for +example: +@example +** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +@end example + +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 + +You will also be prompted for a note that will be put under the DEADLINE +line 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. + +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 Progress logging, , Deadlines and scheduling, Timestamps +@section Progress Logging +@cindex progress logging +@cindex logging, of progress + +Org-mode can automatically record a time stamp when you mark a TODO item +as DONE, or even each time when you change the state of a TODO item. +You can also measure precisely the time you spent on specific items in a +project by starting and stopping a clock when you start and stop working +on an aspect of a project. + +@menu +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Clocking work time:: When exactly did you work on this item? +@end menu + +@node Closing items, Tracking TODO state changes, Progress logging, Progress logging +@subsection Closing items + +If you want to keep track of @emph{when} a certain TODO item was +finished, turn on logging with@footnote{The corresponding in-buffer +setting is: @code{#+STARTUP: logdone}} + +@lisp +(setq org-log-done t) +@end lisp + +@noindent +Then each time you turn a TODO entry into DONE using either @kbd{C-c +C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, 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. 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 closed on each day, giving you an +overview of what has been done on a day. 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 '(done)) +@end lisp + +@node Tracking TODO state changes, Clocking work time, 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 you may even want to attach notes to that state change. With the +setting + +@lisp +(setq org-log-done '(state)) +@end lisp + +@noindent +each state change will prompt you for a note that will be attached to +the current headline. Very likely you do not want this verbose tracking +all the time, so it is probably better to configure this behavior with +in-buffer options. For example, if you are tracking purchases, put +these into a separate file that starts with: + +@example +#+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT +#+STARTUP: lognotestate +@end example + + +@node Clocking work time, , Tracking TODO state changes, Progress logging +@subsection 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. +@kindex C-c C-x C-o +@item C-c C-x C-o +Stop the clock (clock-out). The 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-done} 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-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. +@example +#+BEGIN: clocktable :maxlevel 2 :emphasize nil + +#+END: clocktable +@end example +@noindent +If such a block already exists, its content is replaced by the new +table. The @samp{BEGIN} line can specify options: +@example +:maxlevels @r{Maximum level depth to which times are listed in the table.} +:emphasize @r{When @code{t}, emphasize level one and level two items} +:block @r{The time block to consider. This block is specified relative} + @r{to the current time and may be any of these keywords:} + @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},} + @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}. +:tstart @r{A time string specifying when to start considering times} +:tend @r{A time string specifying when to stop considering times} +@end example +So to get a clock summary for the current day, you could write +@example +#+BEGIN: clocktable :maxlevel 2 :block today + +#+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 +@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 clocktable blocks in a buffer. +@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 Agenda views, Embedded LaTeX, Timestamps, Top +@chapter Agenda Views +@cindex agenda views + +Due to the way Org-mode 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 over open action items, or over events that +are important for a particular date, this information must be collected, +sorted and displayed in an organized way. + +Org-mode can select items based on various criteria, and display them +in a separate buffer. Six 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{tags view}, showings headlines based on +the tags associated with them, +@item +a @emph{timeline view} that shows all events in a single Org-mode file, +in time-sorted view, +@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-mode 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 +@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 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.}. Thus even +if you only work with a single Org-mode file, this file should be put +into that list@footnote{When using the dispatcher, pressing @kbd{1} +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 prefix arg, 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. +@end table + +@noindent +The Org menu contains the current list of files and can be used +to visit any of them. + +@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 # @r{/} ! +Create a list of stuck projects (@pxref{Stuck projects}). +@item 1 +Restrict an agenda command to the current buffer. After pressing +@kbd{1}, you still need to press the character selecting the command. +@item 0 +If there is an active region, restrict the following agenda command to +the region. Otherwise, restrict it to the current subtree. After +pressing @kbd{0}, 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 +* 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 @kbd{C-u} prefix (or +when the variable @code{org-agenda-include-all-todo} is @code{t}), all +unfinished TODO items (including those without a date) are also listed at +the beginning of the buffer, before the first date.@* +@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-mode. It can be very useful to combine output from Org-mode 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-mode 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-mode 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 + +@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{Time stamps}) 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 + +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, Stuck projects, 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 Stuck projects, , Timeline, 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. + +Lets 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. Lets 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: + +@example +#+CATEGORY: Thesis +@end example + +If there are several such lines in a file, each specifies the category +for the text below it (but the first category also applies to any text +before the first CATEGORY line). 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 Marwin 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 Marwin 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}. + + +@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}). +@kindex p +@item p +Previous line (same as @key{down}). +@tsubheading{View/GoTo org file} +@kindex mouse-3 +@kindex @key{SPC} +@item mouse-3 +@itemx @key{SPC} +Display the original location of the item in another window. +@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 numerical prefix ARG, go up to this level and then take that tree. +If ARG is negative, go up that many levels. With @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 where 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. + +@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 subseqent agenda commands. Since +month and year views are slow to create, the do not become the default. +@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 S-@key{left} and +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. +@c +@kindex s +@item s +Save all Org-mode 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 . +Goto today. + +@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-mode 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 $ +@item $ +Archive the subtree corresponding to the current headline. +@c +@kindex T +@item T +Show all tags associated with the current item. Because of +inheritance, this may be more than the tags listed in the line itself. +@c +@kindex : +@item : +Set tags for the current headline. +@c +@kindex a +@item a +Toggle the ARCHIVE tag for the current headline. +@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-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 S-@key{right} +@item S-@key{right} +Change the time stamp associated with the current line by one day into +the future. With 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. + +@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. +@c +@c FIXME: This should be a different key. +@kindex C-c C-x C-c +@item C-c C-x C-c +Export a single iCalendar file containing entries from all agenda files. + +@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 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. +* Extracting Agenda Information for 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 "\\"))) +@end group +@end lisp + +@noindent +The initial single-character string in each entry defines the character +you have to press after the dispatcher command @kbd{C-c a} in order to +access the command. 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}. +@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))))) +@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. + +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, Extracting Agenda Information for other programs, 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' @file{htmlize.el}.} and postscript. 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}), 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 filenames.}. 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 filenames 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")))) +@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. Any other extension produces a plain ASCII file. + +The export files are @emph{not} created when you use one of those +commands interactively. 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 filenames 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 +@example +emacs -eval '(org-batch-store-agenda-views \ + org-agenda-ndays 30 \ + 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 Extracting Agenda Information for other programs, , Exporting Agenda Views, Custom agenda views +@subsection Extracting Agenda Information for other programs +@cindex agenda, pipe +@cindex Scripts, for agenda processing + +Org-mode 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-mode 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); + + # proccess and print + print "[ ] $head\n"; +@} +@end group +@end example + +@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 read 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. + +@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 or +punctuation. 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 turn 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-mode 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-mode 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. + +When exporting, Org-mode uses special conventions to enrich the output +produced. @xref{Text interpretation}, for more details. + +@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. +@end table + +@menu +* ASCII export:: Exporting to plain ASCII +* HTML export:: Exporting to HTML +* LaTeX export:: Exporting to LaTeX +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format +* Text interpretation:: How the exporter looks at the file +@end menu + +@node ASCII export, HTML export, Exporting, 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, only the region will be +exported. If the selected region is a single tree, the tree head will +become the document title. If the tree head entry has or inherits an +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 bodyline 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 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 Grubers @emph{markdown} +language, but with additional support for tables. + +@menu +* HTML Export commands:: How to invoke LaTeX export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links:: Transformation of links for HTML +* Images:: How to include images +* CSS support:: Changing the appearence of the output +@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, only +the region will be exported. If the selected region is a single tree, +the tree head will become the document title. If the tree head entry +has or inherits an 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 H +Export the active region to a temporary buffer. With prefix arg, do not +produce file header and foot, 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 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 + +@example +#+BEGIN_HTML +All lines between these markers are exported literally +#+END_HTML +@end example + + +@node Links, Images, 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 +files only if they match a dedicated @samp{<>}. Automatic links +created by radio targets (@pxref{Radio targets}) will also work in the +HTML file. Links to external files will still work if the HTML file is +in the same directory as the Org-mode 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. For information related to +linking files while publishing them to a publishing directory see +@ref{Publishing links}. + +@node Images, CSS support, 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-mode 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 CSS support, , Images, HTML export +@subsection CSS support + +You can also give style information for the exported file. The HTML +exporter assigns the following CSS classes to appropriate parts of the +document - your style specifications may change these: +@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} +@end example + +The default style specification can be configured through the option +@code{org-export-html-style}. If you want to use a file-local style, +you may use file variables, best wrapped into a COMMENT section at the +end of the outline tree. For example@footnote{Under Emacs 21, the +continuation lines for a variable value should have no @samp{#} at the +start of the line.}: + +@example +* COMMENT html style specifications + +# Local Variables: +# org-export-html-style: " " +# End: +@end example + +Remember to execute @kbd{M-x normal-mode} after changing this to make +the new style visible to Emacs. This command restarts org-mode for the +current buffer and forces Emacs to re-evaluate the local variables +section in the buffer. + +@c FIXME: More about header and footer styles +@c FIXME: Talk about links and targets. + +@node LaTeX export, XOXO export, HTML export, Exporting +@section LaTeX export +@cindex LaTeX export + +Org-mode contains a La@TeX{} exporter written by Bastien Guerry. + +@menu +* LaTeX export commands:: How to invoke LaTeX export +* Quoting LaTeX code:: Incorporating literal LaTeX code +@end menu + +@node LaTeX export commands, Quoting LaTeX code, LaTeX export, LaTeX export +@subsection LaTeX export commands + +@table @kbd +@kindex C-c C-e l +@item C-c C-e l +Export as La@TeX{} file @file{myfile.tex}. +@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. +@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 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, , LaTeX export commands, LaTeX export +@subsection Quoting LaTeX code + +Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly +inserted into the La@TeX{} file. Forthermore, 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 + +@example +#+BEGIN_LaTeX +All lines between these markers are exported literally +#+END_LaTeX +@end example +@node XOXO export, iCalendar export, LaTeX 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, Text interpretation, 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-mode 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}. + +@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 + +How this calendar is best read and updated, depends on the application +you are using. The FAQ covers this issue. + + +@node Text interpretation, , iCalendar export, Exporting +@section Text interpretation by the exporter + +The exporter backends interpret additional structure in the Org-mode file +in order to produce better output. + +@menu +* Comment lines:: Some lines will not be exported +* Initial text:: Text before the first headline +* Footnotes:: Numbers like [1] +* Enhancing text:: Subscripts, symbols and more +* Export options:: How to influence the export settings +@end menu + +@node Comment lines, Initial text, Text interpretation, Text interpretation +@subsection 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. + +@table @kbd +@kindex C-c ; +@item C-c ; +Toggle the COMMENT keyword at the beginning of an entry. +@end table + +@node Initial text, Footnotes, Comment lines, Text interpretation +@subsection Text before the first headline + +Org-mode normally ignores any text before the first headline when +exporting, leaving this region for internal links to speed up navigation +etc. However, in publishing-oriented files, you might want to have some +text before the first headline, like a small introduction, special HTML +code with a navigation bar, etc. You can ask to have this part of the +file exported as well by setting the variable +@code{org-export-skip-text-before-1st-heading} to @code{nil}. On a +per-file basis, you can get the same effect with + +@example +#+OPTIONS: skip:nil +@end example + +The text before the first headline will be fully processed +(@pxref{Enhancing text}), and the first non-comment line becomes the +title of the exported document. If you need to include literal HTML, +use the special constructs described in @ref{Quoting HTML tags}. 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. + +Finally, if you want to use the space before the first headline for +internal purposes, but @emph{still} want to place something before the +first headline when exporting the file, you can use the @code{#+TEXT} +construct: + +@example +#+OPTIONS: skip:t +#+TEXT: This text will go before the *first* headline. +#+TEXT: We place the table of contents here: +#+TEXT: [TABLE-OF-CONTENTS] +#+TEXT: This goes between the table of contents and the first headline +@end example + +@node Footnotes, Enhancing text, Initial text, Text interpretation +@subsection Footnotes +@cindex footnotes +@cindex @file{footnote.el} + +Numbers in square brackets are treated as footnotes, so that you can use +the Emacs package @file{footnote.el} to create footnotes. For example: + +@example +The org-mode homepage[1] clearly needs help from +a good web designer. + +[1] The link is: http://www.astro.uva.nl/~dominik/Tools/org +@end example + +@noindent +@kindex C-c ! +Note that the @file{footnote} package uses @kbd{C-c !} to invoke its +commands. This binding conflicts with the org-mode command for +inserting inactive time stamps. You could use the variable +@code{footnote-prefix} to switch footnotes commands to another key. Or, +if you are too used to this binding, you could use +@code{org-replace-disputed-keys} and @code{org-disputed-keys} to change +the settings in Org-mode. + +@node Enhancing text, Export options, Footnotes, Text interpretation +@subsection Enhancing text for export +@cindex enhancing text +@cindex richer text + +Some of the export backends of Org-mode allow for sophisticated text +formatting, this is true in particular for the HTML and La@TeX{} +backends. Org-mode has a number of typing conventions that allow to +produce a richly formatted output. + +@itemize @bullet + +@cindex hand-formatted lists +@cindex lists, hand-formatted +@item +Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.} +or @samp{2)} as enumerator will be recognized and transformed if the +backend supports lists. See @xref{Plain lists}. + +@cindex underlined text +@cindex bold text +@cindex italic text +@item +You can make words @b{*bold*}, @i{/italic/}, _underlined_, +@code{=code=}, and even @samp{+strikethrough+}@footnote{but remember +that strikethrough is typographically evil and should @i{never} be +used.}. + +@cindex horizontal rules, in exported files +@item +A line consisting of only dashes, and at least 5 of them, will be +exported as a horizontal line (@samp{
} in HTML). + +@cindex LaTeX fragments, export +@cindex TeX macros, export +@item +Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML +entities or images (@pxref{Embedded LaTeX}). + +@cindex tables, export +@item +Tables are transformed into native tables under the exporter, if the +export backend supports this. Data fields before the first horizontal +separator line will be formatted as table header fields. + +@cindex fixed width +@item +If a headline starts with the word @samp{QUOTE}, the text below the +headline will be typeset as fixed-width, to allow quoting of computer +codes etc. Lines starting with @samp{:} are also typeset in fixed-width +font. +@table @kbd +@kindex C-c : +@item C-c : +Toggle fixed-width for entry (QUOTE) or region, see below. +@end table + +@cindex linebreak, forced +@item +A double backslash @emph{at the end of a line} enforces a line break at +this position. +@end itemize + +If these conversions conflict with your habits of typing ASCII text, +they can all be turned off with corresponding variables. See the +customization group @code{org-export-general}, and the following section +which explains how to set export options with special lines in a +buffer. + + +@node Export options, , Enhancing text, Text interpretation +@subsection 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 + +@example +#+TITLE: the title to be shown (default is the buffer name) +#+AUTHOR: the author (default taken from @code{user-full-name}) +#+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 ... +@end example + +@noindent +The OPTIONS line is a compact form to specify export settings. Here +you can: +@cindex headline levels +@cindex section-numbers +@cindex table of contents +@cindex linebreak preservation +@cindex quoted HTML tags +@cindex fixed-width sections +@cindex tables +@cindex @TeX{}-like syntax for sub- and superscripts +@cindex footnotes +@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 linebreak-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.} +f: @r{turn on/off foototes like this[1].} +*: @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} +timestamp: @r{turn on/off inclusion creation time into exported file} +@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. + +@node Publishing, Miscellaneous, Exporting, Top +@chapter Publishing +@cindex publishing + +Org-mode 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-mode 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-mode 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. + +@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 publishing process, for example to +run @code{make} for updating files to be published. +@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-mode 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. Other files +like images only need to be copied to the publishing destination. For +non-Org-mode files, you need to specify the 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-mode. 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.3 0.7 +@item @code{:language} @tab @code{org-export-default-language} +@item @code{:headline-levels} @tab @code{org-export-headline-levels} +@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} +@item @code{:table-of-contents} @tab @code{org-export-with-toc} +@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{:TeX-macros} @tab @code{org-export-with-TeX-macros} +@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} +@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} +@item @code{:timestamps} .@tab @code{org-export-with-timestamps} +@item @code{:tags} .@tab @code{org-export-with-tags} +@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} @tab @code{org-export-html-style} +@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{: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} +@end multitable + +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 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-mode 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 +org-publish to upload the related files, these links will work +too. @ref{Complex example} for an example of this usage. + +Sometime an Org-mode 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 Plugin 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-mode 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-mode 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 +stylesheets. 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 webserver, 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 and Hacking, Publishing, Top +@chapter Miscellaneous + +@menu +* Completion:: M-TAB knows what you need +* Customization:: Adapting Org-mode 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-mode 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-mode 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-mode. 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 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 theis variable is +@code{org-table-formula-constants}. +corresponding +@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 #+STARTUP: +This line sets options to be used at startup of Org-mode, when an +Org-mode 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 TODO state changes and clock intervals (variable +@code{org-log-done}) can be configured using these options. +@cindex @code{logdone}, STARTUP keyword +@cindex @code{nologging}, STARTUP keyword +@cindex @code{lognotedone}, STARTUP keyword +@cindex @code{lognoteclock-out}, STARTUP keyword +@cindex @code{lognotestate}, STARTUP keyword +@cindex @code{logrepeat}, STARTUP keyword +@cindex @code{nologrepeat}, STARTUP keyword +@example +logging @r{record a timestamp when an item is marked DONE} +nologging @r{don't record when items are marked DONE} +lognotedone @r{record timestamp and a note when DONE} +lognotestate @r{record timestamp and a note when TODO state changes} +logrepeat @r{record a note when re-instating a repeating item} +nologrepeat @r{do not record when re-instating repeating item} +lognoteclock-out @r{record timestamp and a note when clocking out} +@end example +Here are the options for hiding leading stars in outline headings. 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} +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 +@item #+TAGS: TAG1(c1) TAG2(c2) +These lines (several such lines are allowed) specify the legal 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: +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-mode, 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-mode, 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 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. +@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 clean outline view + +Some people find it noisy and distracting that the Org-mode headlines +are starting with a potentially large number of stars. For example +the tree from @ref{Headlines}: + +@example +* Top level headline +** Second level +*** 3rd level + some text +*** 3rd level + more text +* Another top level headline +@end example + +@noindent +Unfortunately this is deeply ingrained into the code of Org-mode and +cannot be easily changed. You can, however, modify the display in such +a way that all leading stars become invisible and the outline more easy +to read. To do this, customize the variable +@code{org-hide-leading-stars} like this: + +@lisp +(setq org-hide-leading-stars t) +@end lisp + +@noindent +or change this on a per-file basis with one of the lines (anywhere in +the buffer) + +@example +#+STARTUP: showstars +#+STARTUP: hidestars +@end example + +@noindent +Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate +the modifications. + +With stars hidden, the tree becomes: + +@example +* Top level headline + * Second level + * 3rd level + some text + * 3rd level + more text +* Another top level headline +@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. + +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: + +@example +* Top level headline + * Second level + * 3rd level + some text + * 3rd level + more text +* Another top level headline +@end example + +@noindent +In order to make the structure editing and export commands handle this +convention correctly, use + +@lisp +(setq org-odd-levels-only t) +@end lisp + +@noindent +or set this on a per-file basis with one of the following lines (don't +forget to press @kbd{C-c C-c} with the cursor in the startup line to +activate changes immediately). + +@example +#+STARTUP: odd +#+STARTUP: oddeven +@end example + +You can convert an Org-mode 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}. + +@node TTY keys, Interaction, Clean view, Miscellaneous +@section Using org-mode on a tty +@cindex tty keybindings + +Org-mode uses a number of keys that are not accessible on a tty. This +applies to most special keys like cursor keys, @key{TAB} and +@key{RET}, when these are combined with modifier keys like @key{Meta} +and/or @key{Shift}. Org-mode uses these bindings because it needs to +provide keys for a large number of commands, and because these keys +appeared particularly easy to remember. In order to still be able to +access the core functionality of Org-mode on a tty, alternative +bindings are provided. Here is a complete list of these bindings, +which are obviously more cumbersome to use. Note that sometimes a +work-around can be better. For example changing a time stamp is +really only fun with @kbd{S-@key{cursor}} keys. 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 r} @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-mode lives in the world of GNU Emacs and interacts in various ways +with other code out there. + +@menu +* Cooperation:: Packages Org-mode cooperates with +* Conflicts:: Packages that lead to conflicts +@end menu + +@node Cooperation, Conflicts, Interaction, Interaction +@subsection Packages that Org-mode cooperates with + +@table @asis +@cindex @file{calc.el} +@item @file{calc.el} by Dave Gillespie +Org-mode uses the calc package for implementing spreadsheet +functionality in its tables (@pxref{The spreadsheet}). Org-mode +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-mode 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-mode files. See @ref{CDLaTeX mode}. +@item @file{remember.el} by John Wiegley +@cindex @file{remember.el} +Org mode cooperates with remember, see @ref{Remember}. +@file{Remember.el} is not part of Emacs, find it on the web. +@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 +(@pxref{Footnotes}). +@end table + +@node Conflicts, , Cooperation, Interaction +@subsection Packages that lead to conflicts with Org-mode + +@table @asis + +@cindex @file{allout.el} +@item @file{allout.el} by Ken Manheimer +Startup of Org-mode may fail with the error message +@code{(wrong-type-argument keymapp nil)} when there is an outdated +version @file{allout.el} on the load path, for example the version +distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem will +disappear. If for some reason you cannot do this, make sure that org.el +is loaded @emph{before} @file{allout.el}, for example by putting +@code{(require 'org)} early enough into your @file{.emacs} file. + +@cindex @file{CUA.el} +@item @file{CUA.el} by Kim. F. Storm +Keybindings in Org-mode 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. If you want to use one of these +packages along with Org-mode, configure the variable +@code{org-CUA-compatible}. When set, Org-mode will move the following +keybindings in Org-mode 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-+ +@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. + +@cindex @file{footnote.el} +@item @file{footnote.el} by Steven L. Baur +Org-mode supports the syntax of the footnote package, but only the +numerical footnote markers. Also, the default key for footnote +commands, @kbd{C-c !} is already used by Org-mode. You could use the +variable @code{footnote-prefix} to switch footnotes commands to another +key. Or, you could use @code{org-replace-disputed-keys} and +@code{org-disputed-keys} to change the settings in Org-mode. + +@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-mode 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 +A single letter cannot be made bold, for example @samp{*a*}. +@item +The exporters work well, but could be made more efficient. +@end itemize + + +@node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top +@appendix Extensions, Hooks and Hacking + +This appendix lists extensions for Org-mode written by other authors. +It also covers some aspects where users can extend the functionality of +Org-mode. + +@menu +* Extensions:: Existing 3rd-part extensions +* 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 +@end menu + +@node Extensions, Adding hyperlink types, Extensions and Hacking, Extensions and Hacking +@section Third-party extensions for Org-mode +@cindex extension, third-party + +The following extensions for Org-mode have been written by other people: + +@table @asis +@cindex @file{org-publish.el} +@item @file{org-publish.el} by David O'Toole +This package provides facilities for publishing related sets of Org-mode +files together with linked files like images as webpages. It is +highly configurable and can be used for other publishing purposes as +well. As of Org-mode version 4.30, @file{org-publish.el} is part of the +Org-mode distribution. It is not yet part of Emacs, however, a delay +caused by the preparations for the 22.1 release. In the mean time, +@file{org-publish.el} can be downloaded from David's site: +@url{http://dto.freeshell.org/e/org-publish.el}. +@cindex @file{org-mouse.el} +@item @file{org-mouse.el} by Piotr Zielinski +This package implements extended mouse functionality for Org-mode. It +allows you to cycle visibility and to edit the document structure with +the mouse. Best of all, it provides a context-sensitive menu on +@key{mouse-3} that changes depending on the context of a mouse-click. +As of Org-mode version 4.53, @file{org-mouse.el} is part of the +Org-mode distribution. It is not yet part of Emacs, however, a delay +caused by the preparations for the 22.1 release. In the mean time, +@file{org-mouse.el} can be downloaded from Piotr's site: +@url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}. +@cindex @file{org-blog.el} +@item @file{org-blog.el} by David O'Toole +A blogging plug-in for @file{org-publish.el}.@* +@url{http://dto.freeshell.org/notebook/OrgMode.html}. +@cindex @file{blorg.el} +@item @file{blorg.el} by Bastien Guerry +Publish Org-mode files as +blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}. +@cindex @file{org2rem.el} +@item @file{org2rem.el} by Bastien Guerry +Translates Org-mode files into something readable by +Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. +@end table + +@page + +@node Adding hyperlink types, Tables in arbitrary syntax, Extensions, Extensions and Hacking +@section Adding hyperlink types +@cindex hyperlinks, adding new types + +Org-mode 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. Lets 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-mode + +(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 +Lets 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 manpages. 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 +retunr the value @code{nil}. If yes, the link is created by getting the +manual tpoic 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 tan Org-mode +buffer with @kbd{C-c C-l}. + +@node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Extensions and Hacking +@section Tables in arbitrary syntax +@cindex tables, 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. + +@menu +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +@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! +@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 +@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, lets say we use @samp{salesfigures}. You +will then get the following template: + +@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 lets 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: + +@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\\%%")}. + +@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. +@end table + +@node Translator functions, , 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-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 Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking +@section Dynamic blocks +@cindex dynamic blocks + +Org-mode 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. + +@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. 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 Org-mode. + +@node Special agenda views, Using the property API, Dynamic blocks, Extensions and Hacking +@section Special Agenda Views +@cindex agenda views, user-defined + +Org-mode 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-org-waiting-projects) + (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. + +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 contained in the variable +@code{org-agenda-skip-regexp} matches in the entry. +@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, , Special agenda views, Extensions and 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. +If INHERIT is non-nil and the entry does not have the property, +then also check higher levels of the hierarchy. +@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 + +@node History and Acknowledgments, Index, Extensions and Hacking, Top +@appendix History and Acknowledgments +@cindex acknowledgments +@cindex history +@cindex thanks + +Org-mode 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 unhide 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-mode 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. + +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-mode. 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} contributed the code for links to the MH-E email +system. +@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{John Foerch} figured out how to make incremental search show context +around a match in a hidden outline tree. +@item +@i{Niels Giessen} had the idea to automatically archive DONE trees. +@item +@i{Bastien Guerry} wrote the La@TeX{} exporter and has been prolific +with patches, ideas, and bug reports. +to Org-mode. +@item +@i{Kai Grossjohann} pointed out key-binding conflicts with other packages. +@item +@i{Scott Jaderholm} proposed footnotes, control over whitespace between +folded entries, and column view for properties. +@item +@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also +provided frequent feedback and some patches. +@item +@i{Jason F. McBrayer} suggested agenda export to CSV format. +@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. +@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{Kevin Rogers} contributed code to access VM files on remote hosts. +@item +@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a +conflict with @file{allout.el}. +@item +@i{Jason Riedy} sent a patch to fix a bug with export of TODO keywords. +@item +@i{Philip Rooke} created the Org-mode reference card and provided lots +of feedback. +@item +@i{Christian Schlauer} proposed angular brackets around links, among +other things. +@item +Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s +@file{organizer-mode.el}. +@item +@i{Daniel Sinder} came up with the idea of internal archiving by locking +subtrees. +@item +@i{Dale Smith} proposed link abbreviations. +@item +@i{Adam Spiers} asked for global linking commands and inspired the link +extension system. support mairix. +@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} and @file{planner.el}. The +development of Org-mode was fully independent, and both systems are +really different beasts in their basic ideas and implementation details. +I later looked at John's code, however, and learned from his +implementation of (i) links where the link itself is hidden and only a +description is shown, and (ii) popping up a calendar to select a date. +John has also contributed a number of great ideas directly to Org-mode. +@item +@i{Carsten Wimmer} suggested some changes and helped fix a bug in +linking to GNUS. +@item +@i{Roland Winkler} requested additional keybindings to make Org-mode +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 Index, Key Index, History and Acknowledgments, Top +@unnumbered Index + +@printindex cp + +@node Key Index, , Index, Top +@unnumbered Key Index + +@printindex ky + +@bye + +@ignore + arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac +@end ignore diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi new file mode 100644 index 00000000000..93bd54eb456 --- /dev/null +++ b/doc/misc/pcl-cvs.texi @@ -0,0 +1,1443 @@ +\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 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.2 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'' in the Emacs manual. + +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. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end quotation +@end copying + +@dircategory 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 + +@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. +@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 Dired Mode, , Dired under VC, 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@@cs.yale.edu, 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 + +@setchapternewpage odd +@summarycontents +@contents +@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 00000000000..6a175db4cb9 --- /dev/null +++ b/doc/misc/pgg.texi @@ -0,0 +1,498 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename ../info/pgg + +@set VERSION 0.1 + + +@copying +This file describes PGG, an Emacs interface to various PGP implementations. + +Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled ``GNU +Free Documentation License.'' +@end quotation +@end copying + +@dircategory Emacs +@direntry +* PGG: (pgg). Emacs interface to various PGP implementations. +@end direntry + +@settitle PGG @value{VERSION} + + +@titlepage +@title PGG + +@author by Daiki Ueno +@page + +@vskip 0pt plus 1filll +@insertcopying +@end titlepage +@page + +@node Top +@top PGG +This manual describes 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. + +@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 backend. + +@menu +* Initializing:: +* Backend 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 backend name. + +@node Backend methods +@section Backend methods + +In each backend, 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 backend methods (@ref{Backend 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 + +@summarycontents +@contents +@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 00000000000..6d5319cef4e --- /dev/null +++ b/doc/misc/rcirc.texi @@ -0,0 +1,768 @@ +\input texinfo +@c %**start of header +@setfilename ../info/rcirc +@settitle rcirc Manual +@c %**end of header + +@copying +Copyright @copyright{} 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license is +included in the section entitled ``GNU Free Documentation License'' in +the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Rcirc: (rcirc). Internet Relay Chat (IRC) client. +@end direntry + +@titlepage +@title rcirc Manual +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnottex +@node Top, Basics, (dir), (dir) +@top rcirc Manual +@end ifnottex + +@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. + +@menu +* Basics:: +* Reference:: +* 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:: + +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 the servers share information between them. + +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 organisations 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 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 in 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. + +@node Reference, Hacking and Tweaking, 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 legal 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 + +Some commands may not have a key binding, but only be available as typed +commands, such as: + +@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 xah}. +@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-default-server +@vindex rcirc-default-server +the default server to connect to. + +@item rcirc-default-port +@vindex rcirc-default-port +the default port to connect to. + +@item rcirc-default-nick +@vindex rcirc-default-nick +the default nick to use. +@end table + +@example +(setq rcirc-default-server "irc.mozilla.org" + rcirc-default-port 6666 + rcirc-default-nick "alx") +@end example + +@vindex rcirc-default-user-full-name +@cindex full name +@cindex real name +@cindex surname +@code{rcirc-default-user-full-name} is used to set your ``real name'' on +IRC. It defaults to @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 + +@vindex rcirc-startup-channels-alist +@cindex channels, configuration +@cindex initial channels, configuration +@cindex startup channels, configuration +@code{rcirc-startup-channels-alist} is the alist of channels to join +when connecting to a particular network. An alist is a list of lists. +Each sublist starts with a regular expression that is compared to the +server address you're connecting to. The remaining sublist items are +the channels to join. + +@example +(setq rcirc-startup-channels-alist + '(("\\.freenode\\.net$" "#emacs" "#rcirc" "#wiki"))) +@end example + +Note the subtle problem, here --- IRC clients connect to servers, and +there is no way of knowing which servers belong to a particular network. +In the example above we're exploiting a naming convention used by within +the Freenode network --- all servers within the network have a host in +the @code{freenode.net} domain. + +@vindex rcirc-authinfo +@cindex authentification +@cindex identification +@cindex nickserv +@cindex login +@code{rcirc-authinfo} 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 + +@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 + +@node Hacking and Tweaking, GNU Free Documentation License, Reference, 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 realise 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 00000000000..a2c0a9689b2 --- /dev/null +++ b/doc/misc/reftex.texi @@ -0,0 +1,5898 @@ +\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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@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. + +@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 + +@summarycontents +@contents +@bye + +@ignore + arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43 +@end ignore diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi new file mode 100644 index 00000000000..5ac3b882ccd --- /dev/null +++ b/doc/misc/sc.texi @@ -0,0 +1,2533 @@ +\input texinfo @comment -*-texinfo-*- +@comment 3.48 +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename ../info/sc +@settitle Supercite Version 3.1 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 the Supercite Version 3.1 package for citing and +attributing the replies for various GNU Emacs mail and news reading +subsystems. + +Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, +2005, 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@c @smallbook + +@dircategory Emacs +@direntry +* SC: (sc). Supercite lets you cite parts of messages you're + replying to, in flexible ways. +@end direntry + +@titlepage +@sp 6 +@center @titlefont{Supercite User's Manual} +@sp 2 +@center @titlefont{Supercite Version 3.1} +@sp 4 +@center Manual Revision: 3.48 +@center April 2007 +@sp 5 +@center Barry A@. Warsaw +@center @t{bwarsaw@@cen.com} +@center @t{@dots{}!uunet!cen.com!bwarsaw} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnottex +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up + +This document describes the Supercite Version 3.1 package for citing and +attributing the replies for various GNU Emacs mail and news reading +subsystems. 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:: +* Version 3 Changes:: +* Thanks and History:: +* The Supercite Mailing List:: + +* GNU Free Documentation License:: +* Concept Index:: +* Command Index:: +* Key Index:: +* Variable Index:: +@end menu +@end ifnottex + + +@node Introduction, Usage Overview, Top, Top +@comment node-name, next, previous, up +@chapter Introduction +@ifinfo + +@end ifinfo +Supercite version 3.1 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}. There are a few alternate spellings out there +and I won't be terribly offended if you use them. People often ask +though@dots{} + +@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, etc@. (hereafter referred to collectively as MUAs). +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. + +Supercite is currently at major revision 3.1, and is known to work in the +following environments: + +@table @asis +@item Emacs versions: + GNU Emacs 18.57 through 18.59, all Emacs 19, + all current Lucid Emacs, and Epoch 4.@refill + +@item MUAs: + VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and + beyond, PCMAIL.@refill + +@item NUAs: + RNEWS, GNUS 3.12 and beyond, GNEWS.@refill + +@end table +For systems with version numbers, all known subsequent versions also +work with Supercite. For those systems without version numbers, +Supercite probably works with any recently released version. Note that +only some of these systems will work with Supercite ``out of the box.'' +All others must overload interfacing routines to supply the necessary +glue. @xref{Getting Connected}, for more details.@refill + + +@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction +@comment node-name, next, previous, up +@kindex r +@kindex f +@kindex C-c C-y +@cindex yank +@cindex cite, citing +@cindex attribute, attributing +@comment +@section Usage Overview +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@section What Supercite Doesn't Do +@ifinfo + +@end ifinfo +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 +@comment +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 +@comment node-name, next, previous, up +@findex sc-cite-original +@section What Supercite Does +@ifinfo + +@end ifinfo +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 +@comment +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 +@comment node-name, next, previous, up +@cindex nested citations +@cindex citation +@comment +@chapter Citations +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@cindex citation string +@comment +@section Citation Elements +@ifinfo + +@end ifinfo +@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 +@comment node-name, next, previous, up +@section Recognizing Citations +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@cindex information keys +@cindex Info Alist +@cindex information extracted from mail fields +@findex sc-mail-field +@findex mail-field (sc-) +@comment +@chapter Information Keys and the Info Alist +@ifinfo + +@end ifinfo +@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 +@comment node-name, next, previous, up +@cindex reference headers +@chapter Reference Headers +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@cindex header rewrite functions, built-in +@comment +@section The Built-in Header Rewrite Functions +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@cindex electric references +@section Electric References +@ifinfo + +@end ifinfo +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, Emacs 19 MUAs, Recognizing Citations, Top +@comment node-name, next, previous, up +@cindex citation interface specification +@chapter Getting Connected +@ifinfo + +@end ifinfo +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 + +@ifinfo +@menu +* Emacs 19 MUAs:: +* Emacs 18 MUAs:: +* MH-E with any Emacsen:: +* VM with any Emacsen:: +* GNEWS with any Emacsen:: +* Overloading for Non-conforming MUAs:: +@end menu +@end ifinfo + +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{:-)}. With the recent +release of the Free Software Foundation's GNU Emacs 19, the interface +has undergone some modification and it is possible that not all MUAs +support the new interface yet. Some support only the old interface and +some do not support the interface at all. Still, it is possible for all +known MUAs to use Supercite, and the following sections will outline the +procedures you need to follow. + +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. You can either dump Supercite into your Emacs binary (ask your +local Emacs guru how to do this if you don't know), or 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" "Supercite 3.1" t) +(autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" 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 for Emacs 19, 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 Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected +@comment node-name, next, previous, up +@vindex mail-citation-hook +@cindex .emacs file +@section GNUS, RMAIL, or RNEWS with any Emacs 19 +@ifinfo + +@end ifinfo +These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's +built-in yanking facility, which provides the citing hook variable +@code{mail-citation-hook}. By default, this hook's value is @code{nil}, +but by adding the following to your @file{.emacs} file, you can tell +these MUAs to use Supercite to perform the citing of the original +message: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +GNUS users may also want to add the following bit of lisp as well. This +prevents GNUS from inserting its default attribution header. Otherwise, +both GNUS and Supercite will insert an attribution header: + +@example +(setq news-reply-header-hook nil) +@end example + +@node Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected +@comment node-name, next, previous, up +@vindex mail-citation-hook +@cindex .emacs file +@cindex overloading +@cindex sendmail.el file +@section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 +@ifinfo + +@end ifinfo +These MUAs use Emacs' built-in yanking and citing routines, contained in +the @file{sendmail.el} file. @file{sendmail.el} for Emacs 18, and its +derivative Epoch 4, do not know anything about the citation interface +required by Supercite. To connect Supercite to any of these MUAs under +Emacs 18 or Epoch 4, you should first +@pxref{Overloading for Non-conforming MUAs}. Then follow the directions +for using these MUAs under Emacs 19. +@xref{Emacs 19 MUAs}.@refill + +@cindex add-hook substitute +@cindex setq as a substitute for add-hook +@findex setq +@findex add-hook +@cindex sc-unsupp.el file +Note that those instructions will tell you to use the function +@code{add-hook}. This function is new with Emacs 19 and you will not +have it by default if you are running Emacs 18 or Epoch 4. You can +either substitute the appropriate call to @code{setq}, or you can use +the @code{add-hook} function that is provided in the @file{sc-unsupp.el} +file of unsupported Supercite hacks and ideas. Or you can upgrade to +some Emacs 19 variant! @t{:-)}@refill + +To use @code{setq} instead of @code{add-hook}, you would, for example, +change this: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +to: + +@example +(setq mail-citation-hook 'sc-cite-original) +@end example + +Note the lack of a single quote on the first argument to @code{setq}. + +@node MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected +@comment node-name, next, previous, up +@cindex .emacs file +@vindex mh-yank-hooks +@findex add-hook +@cindex mail-citation-hook +@section MH-E with any Emacsen +@ifinfo + +@end ifinfo +MH-E 4.x conforms to the @code{mail-citation-hook} interface supported +by other MUAs. At the time of this writing, MH-E 4.0 has not been +released, but if you have it, put this in your @file{.emacs} file to +connect Supercite and MH-E 4.x: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +Note that if you are using Emacs 18 or Epoch 4, you will not have the +@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to +proceed without @code{add-hook}. + +MH-E version 3.x uses a slightly different interface than other MUAs. +MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act +like a hook, and doing an @code{add-hook} will not work. + +To connect Supercite to MH-E 3.x, you should instead add the following +to your @code{.emacs} file: + +@example +(add-hook 'mh-yank-hooks 'sc-cite-original) +@end example + +@vindex mh-yank-from-start-of-msg +You also need to make sure that MH-E includes all the original mail +headers in the yanked message. The variable that controls this is +@code{mh-yank-from-start-of-msg}. By default, this variable has the +value @code{t}, which tells MH-E to include all the mail headers when +yanking the original message. Before you switched to using Supercite, +you may have set this variable to other values so as not to include the +mail headers in the yanked message. Since Supercite requires these +headers (and cleans them out for you), you need to make sure the value +is @code{t}. This lisp, in your @file{.emacs} file will do the trick: + +@example +(setq mh-yank-from-start-of-msg t) +@end example + +Note that versions of MH-E before 3.7 did not provide the +@code{mh-yank-hooks} variable. Your only option is to upgrade to MH-E +version 3.7 or later. + +@node VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected +@comment node-name, next, previous, up +@cindex .emacs file +@vindex mail-citation-hook +@vindex mail-yank-hooks +@section VM with any Emacsen +@ifinfo + +@end ifinfo +Since release 4.40, VM has supported the citation interface required by +Supercite. But since the interface has changed recently the details of +getting connected differ with the version of VM you are using. + +If you are running any release of VM after 4.40, you can add the +following to your @file{.emacs} to connect Supercite with VM: + +@example +(add-hook 'mail-yank-hooks 'sc-cite-original) +@end example + +Note that if you are using Emacs 18 or Epoch 4, you will not have the +@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to +proceed without @code{add-hook}. + +Since version 5.34, VM has supported the newer @code{mail-citation-hook} +interface, but @code{mail-yank-hooks} is still being supported for +backward compatibility. If you are running a newer version of VM and +you want to maintain consistency with other MUAs, use this bit of code +instead: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +@node GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected +@comment node-name, next, previous, up@cindex .emacs file +@vindex news-reply-mode-hook +@findex sc-perform-overloads +@findex perform-overloads (sc-) +@vindex gnews-ready-hook +@section GNEWS with any Emacsen +@ifinfo + +@end ifinfo +As far as I know, no version of GNEWS supports the citation interface +required by Supercite. To connect Supercite with GNEWS, please first +@pxref{Overloading for Non-conforming MUAs}. + +After you have followed the directions in that section. You should add +the following lisp code to your @file{.emacs} file: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +Note that if you are using Emacs 18 or Epoch 4, you will not have the +@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to +proceed without @code{add-hook}. + +@node Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected +@comment node-name, next, previous, up +@cindex overloading +@cindex sc-oloads.el +@vindex mail-citation-hook +@findex sc-perform-overloads +@cindex .emacs file +@section Overloading for Non-conforming MUAs +@ifinfo + +@end ifinfo +As mentioned elsewhere, some MUAs do not provide the necessary hooks to +connect with Supercite. Supercite version 3.1 provides an unsupported +mechanism, called @dfn{overloading} which redefines certain key +functions in the MUA, so that it will call the @code{mail-citation-hook} +variable instead of the MUA's default hard-coded citing routines. Since +most newer versions of the known MUAs support the +@code{mail-citation-hook} variable, it is recommended that you upgrade +if at all possible. But if you can't upgrade, at least you're not out +of luck! Once you set up overloading properly, you should follow the +directions for connecting Supercite to the Emacs 19 MUAs. +@xref{Emacs 19 MUAs}.@refill + +@cindex Hyperbole +@vindex hyperb:version +Users of Bob Weiner's Hyperbole package take note. Hyperbole provides +the necessary overloads (and a whole lot more!) and you can potentially +clobber it if you were to load Supercite's overloading after +Hyperbole's. For this reason, Supercite will @emph{not} perform any +overloading if it finds the variable @code{hyperb:version} is +@code{boundp} (i.e. it exists because Hyperbole has been loaded into +your Emacs session). If this is the case, Supercite will display a +warning message in the minibuffer. You should consult the Hyperbole +manual for further details. + +Overloading involves the re-definition of the citing function with the +new, @code{mail-citation-hook} savvy version. The function in +@file{sc-oloads.el} that does this is @code{sc-perform-overloads}. This +function is smart enough to only overload the MUA functions when it is +absolutely necessary, based on the version numbers it can figure out. +Also, @code{sc-perform-overloads} will only install the new functions +once. It is also smart enough to do nothing if the MUA is not yet +loaded.@refill + +The tricky part is finding the right time and place to perform the +overloading. It must be done after the MUA has been loaded into your +Emacs session, but before the first time you try to yank in a message. +Fortunately, this has been figured out for you. + +If you must overload, you should put the following lisp code in your +@file{.emacs} file, to make sure the @file{sc-oloads.el} file gets +loaded at the right time: + +@example +(autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t) +@end example + +Then you must make sure that the function @code{sc-perform-overloads} +gets run at the right time. For GNUS, put this in your @file{.emacs} +file: + +@example +(setq news-reply-mode-hook 'sc-perform-overloads) +(setq mail-setup-hook 'sc-perform-overloads) +@end example + +If you are using RNEWS, put this in your @file{.emacs} file: + +@vindex news-reply-mode-hook +@example +(setq news-reply-mode-hook 'sc-perform-overloads) +@end example + +If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file: + +@example +(setq mail-setup-hook 'sc-perform-overloads) +@end example + +If you are using GNEWS, put this in your @file{.emacs} file: + +@example +(setq news-reply-mode-hook 'sc-perform-overloads) +(setq gnews-ready-hook 'sc-perform-overloads) +@end example + +Now go back and follow the directions for getting the Emacs 19 MUAs +connected to Supercite. Be sure to @pxref{Emacs 18 MUAs} on substitutes +for Emacs 19's @code{add-hook} function.@refill + +@node Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top +@comment node-name, next, previous, up +@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 +@comment node-name, next, previous, up +@findex sc-cite-original +@findex cite-original (sc-) +@comment +@section Reply Buffer Initialization +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@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 +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@cindex attribution list +@vindex sc-preferred-attribution-list +@vindex preferred-attribution-list (sc-) +@comment +@chapter Selecting an Attribution +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@section Attribution Preferences +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@vindex sc-default-author-name +@vindex default-author-name (sc-) +@vindex sc-default-attribution +@vindex default-attribution (sc-) +@comment +@section Anonymous Attributions +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@cindex author names +@section Author Names +@ifinfo + +@end ifinfo +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. +@xref{The Supercite Mailing List}.@refill + +@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 +@comment node-name, next, previous, up +@cindex Regi +@cindex frames (Regi) +@cindex entries (Regi) +@chapter Configuring the Citation Engine +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@findex regi-interpret +@findex eval +@findex looking-at +@section Using Regi +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@vindex sc-nuke-mail-header +@section Frames You Can Customize +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@vindex sc-mode-map-prefix +@vindex mode-map-prefix (sc-) +@kindex C-c C-p +@chapter Post-yank Formatting Commands +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@vindex sc-cite-region-limit +@section Commands to Manually Cite, Recite, and Uncite +@ifinfo + +@end ifinfo +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 + +A quick note about Emacs 19. Unlike in Emacs 18, the region delimited +by @samp{point} and @samp{mark} can have two states. It can be +@dfn{active} or @dfn{inactive}. Although Emacs 19 and Lucid Emacs 19 +use different terminology and functions, both employ the same convention +such that when the region is inactive, commands that modify the region +should generate an error. The user needs to explicitly activate the +region before successfully executing the command. All Supercite +commands conform to this convention. + +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}) +@comment +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}) +@comment +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}) +@comment +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 +@comment node-name, next, previous, up +@section Insertion Commands +@ifinfo + +@end ifinfo +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}) +@comment +@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}) +@comment +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 +@comment node-name, next, previous, up +@cindex toggling variables +@section Variable Toggling Shortcuts +@ifinfo + +@end ifinfo +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 +@comment node-name, next, previous, up +@section Mail Field Commands +@ifinfo + +@end ifinfo +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}) +@comment +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. For those of you running Emacs 19, 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}) +@comment +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 +@comment node-name, next, previous, up +@section Miscellaneous Commands +@ifinfo + +@end ifinfo +@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}) +@comment +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 + +@findex sc-describe +@findex describe (sc-) +@kindex C-c C-p ? +@kindex C-c C-p h +@item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?}) +@comment +This function has been obsoleted by the @TeX{}info manual you are now +reading. It is still provided for compatibility, but it will eventually +go away. + +@findex sc-version +@findex version (sc-) +@kindex C-c C-p v +@item @code{sc-version} (@kbd{C-c C-p v}) +@comment +Echos the version of Supercite you are using. With the optional +universal argument (@kbd{C-u}), this command inserts the version +information into the current buffer. + +@findex sc-submit-bug-report +@findex submit-bug-report (sc-) +@kindex C-c C-p C-b +@item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b}) +@comment +If you encounter a bug, or wish to suggest an enhancement, use this +command to set up an outgoing mail buffer, with the proper address to +the Supercite maintainer automatically inserted in the @samp{To:@:} +field. This command also inserts information that the Supercite +maintainer can use to recreate your exact setup, making it easier to +verify your bug. +@end table + +@node Hints to MUA Authors, Version 3 Changes, Electric References, Top +@comment node-name, next, previous, up +@chapter Hints to MUA Authors +@ifinfo + +@end ifinfo +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 with the recent release of +Emacs 19, it has undergone a slight modification. Instead of the +variable @code{mail-yank-hooks}, the new preferred hook variable that +the MUA should provide is @code{mail-citation-hook}. +@code{mail-yank-hooks} can be provided for backward compatibility, but +@code{mail-citation-hook} should always take precedence. Richard +Stallman (of the FSF) suggests that the MUAs should @code{defvar} +@code{mail-citation-hook} to @code{nil} and perform some default citing +when that is the case. Take a look at Emacs 19's @file{sendmail.el} +file, specifically the @code{mail-yank-original} defun for +details.@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. Further note that for +Emacs 19, the region need not be set active. Supercite will work +properly when the region is inactive, as should any other like-minded +package.@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 users will not need to overload your routines +to use Supercite, and your MUA will join the ranks of those that conform +to this interface ``out of the box.'' + +@node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top +@comment node-name, next, previous, up +@chapter Version 3 Changes +@ifinfo + +@end ifinfo +@cindex sc-unsupp.el file +With version 3, Supercite has undergone an almost complete rewrite, and +has hopefully benefited 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. The central construct of the info alist, and its +role in Supercite has been expanded, and the other central concept, the +general package Regi, was developed to provide a theoretically unlimited +flexibility. + +But most of this work is internal and not of very great importance to the +casual user. There have been 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. Below, I briefly +outline those user-visible things that have changed since version 2. For +details, look to other sections of this manual. + +@enumerate +@item +@cindex supercite.el file +@cindex reporter.el file +@cindex regi.el file +@cindex sc.el from version 2 +@cindex sc-elec.el from version 2 +Supercite proper now comes in a single file, @file{supercite.el}, which +contains everything except the unsupported noodlings, overloading (which +should be more or less obsolete with the release of Emacs 19), and the +general lisp packages @file{reporter.el} and @file{regi.el}. Finally, +the @TeX{}info manual comes in its own file as well. In particular, the +file @file{sc.el} from the version 2 distribution is obsolete, as is the +file @file{sc-elec.el}. + +@item +@code{sc-spacify-name-chars} is gone in version 3. + +@item +@vindex sc-attrib-selection-list +@vindex attrib-selection-list +@code{sc-nickname-alist} is gone in version 3. The +@code{sc-attrib-selection-list} is a more general construct supporting +the same basic feature. + +@item +The version 2 variable @code{sc-preferred-attribution} has been changed +to @code{sc-preferred-attribution-list}, and has been expanded upon to +allow you to specify an ordered list of preferred attributions. + +@item +@code{sc-mail-fields-list} has been removed, and header nuking in +general has been greatly improved, giving you wider flexibility in +specifying which headers to keep and remove while presenting a +simplified interface to commonly chosen defaults. + +@item +Post-yank paragraph filling has been completely removed from Supercite, +other packages just do it better than Supercite ever would. Supercite +will still fill newly cited paragraphs. + +@item +@vindex sc-cite-region-limit +@vindex cite-region-limit +The variable @code{sc-all-but-cite-p} has been replaced by +@code{sc-cite-region-limit}. + +@item +Keymap hacking in the reply buffer has been greatly simplified, with, I +believe, little reduction in functionality. + +@item +Hacking of the reply buffer's docstring has been completely eliminated. +@end enumerate + +@node Thanks and History, The Supercite Mailing List, Version 3 Changes, Top +@comment node-name, next, previous, up +@chapter Thanks and History +@ifinfo + +@end ifinfo +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. Supercite version 3 represents a +nearly complete rewrite with many of the algorithms and coding styles +being vastly improved. 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. + +@node The Supercite Mailing List, GNU Free Documentation License, Thanks and History, Top +@comment node-name, next, previous, up +@cindex supercite mailing list address +@cindex mailing list address +@chapter The Supercite Mailing List +@ifinfo + +@end ifinfo +The author runs a simple mail expanding mailing list for discussion of +issues related to Supercite. This includes enhancement requests, bug +reports, general help questions, etc. To subscribe or unsubscribe to +the mailing list, send a request to the administrative address: + +@example +supercite-request@@python.org +@end example + +Please be sure to include the most reliable and shortest (preferably +Internet) address back to you. To post articles to the list, send your +message to this address (you do not need to be a member to post, but be +sure to indicate this in your article or replies may not be CC'd to +you): + +@example +supercite@@python.org +@end example + +If you are sending bug reports, they should go to the following address, +but @emph{please}! use the command @code{sc-submit-bug-report} since it +will be much easier for me to duplicate your problem if you do so. It +will set up a mail buffer automatically with this address on the +@samp{To:@:} line: + +@example +supercite-help@@python.org +@end example + +@node GNU Free Documentation License, Concept Index, The Supercite Mailing List, 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 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 +@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 +@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 +@setchapternewpage odd +@summarycontents +@contents +@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 00000000000..089e13a9cc0 --- /dev/null +++ b/doc/misc/ses.texi @@ -0,0 +1,982 @@ +\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 +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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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}. + +@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 + +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. + +@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 C-c C-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-c C-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}). +@end table + +When a printer function signals an error, the default printer +@samp{"%s"} is substituted. This is useful when your column printer +is numeric-only and you use a string as a cell value. + + +@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{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 examples of these, 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} +@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 00000000000..4b7a95be952 --- /dev/null +++ b/doc/misc/sieve.texi @@ -0,0 +1,369 @@ +\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 +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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + + +@node Top +@top Sieve Support for Emacs + +This manual documents the Emacs Sieve package. + +It 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. + +A good online Sieve resources is @uref{http://www.cyrusoft.com/sieve/}. + +@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 does +contain some 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 + +@summarycontents +@contents +@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 00000000000..644cd061b74 --- /dev/null +++ b/doc/misc/smtpmail.texi @@ -0,0 +1,427 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../info/smtpmail +@settitle Emacs SMTP Library +@syncodeindex vr fn +@copying +Copyright @copyright{} 2003, 2004, 2005, 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License'' +in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@contents +@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 00000000000..2a05993f569 --- /dev/null +++ b/doc/misc/speedbar.texi @@ -0,0 +1,1261 @@ +\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 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.2 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'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 + +@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}. + +@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 00000000000..fe6285b3bc5 --- /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 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 00000000000..b53bc59d506 --- /dev/null +++ b/doc/misc/tramp.texi @@ -0,0 +1,3297 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../info/tramp +@c %**start of header +@settitle TRAMP User Manual +@setchapternewpage odd +@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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@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 + +@tex + +@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 +@page + +@end tex + +@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. +* 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 transfer methods:: External transfer 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 caching:: 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. + +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. + +@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. + +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} or +@command{rsync}. + +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. + +Within these limitations, @value{tramp} is quite powerful. It is worth +noting that, as of the time of writing, it is far from a polished +end-user product. For a while yet you should expect to run into rough +edges and problems with the code now and then. + +It is finished enough that the developers use it for day to day work but +the installation and setup can be a little difficult to master, as can +the terminology. + +@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 out-of-band 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 out-of-band. 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 transfer methods:: External transfer 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 caching:: 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 transfer methods +@cindex external methods +@cindex out-of-band methods +@cindex methods, inline +@cindex methods, external transfer +@cindex methods, out-of-band +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 over the same connection used to log in to the remote +machine or the file can be transfered through another connection using +a remote copy program such as @command{rcp}, @command{scp} or +@command{rsync}. The former are called @dfn{inline methods}, the +latter are called @dfn{out-of-band methods} or @dfn{external transfer +methods} (@dfn{external methods} for short). + +The performance of the external transfer 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 transfer 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 caching}, 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. +With other words, a specified host name in the file name is silently +ignored. + + +@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 transfer methods +@section External transfer methods +@cindex methods, external transfer +@cindex methods, out-of-band +@cindex external transfer methods +@cindex out-of-band methods + +The external transfer 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 transfer 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 caching}. + +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 transfer methods are normally preferable to inline transfer +methods, giving better performance. + +@xref{Inline methods}. +@xref{External transfer 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, out-of-band +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 +out-of-band methods are faster than inline methods for large files. +Note, however, that out-of-band methods suffer from some limitations. +Please try first whether you really get a noticeable speed advantage +from using an out-of-band 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 caching +@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. + +By default, @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. + +@findex tramp-clear-passwd +A password is removed from the cache if a connection isn't established +successfully. You can remove a password from the cache also by +executing @kbd{M-x tramp-clear-passwd} in a buffer containing a +related remote file or directory. + +@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.el} in No Gnus. 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 +It will be activated mandatory once No Gnus has found its way into +@value{emacsname}. + + +@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}. + + +@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 transfer 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 +@comment node-name, next, previous, up +@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 @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. +@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 + +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{Default Method}) 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@footnote{If you don't use Partial Completion mode, but want to +keep full completion, load @value{tramp} like this in your +@file{.emacs}: + +@lisp +;; Preserve Tramp's completion features. +(let ((partial-completion-mode t)) + (require 'tramp)) +@end lisp +}. +@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 +@ifset emacs +@value{prefixhop}telnet@value{postfixhop} tmp/ +@value{prefixhop}toto@value{postfix} +@end ifset +@ifset xemacs +@value{prefixhop}telnet@value{postfixhop} @value{prefixhop}toto@value{postfix} +@end ifset +@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 +@trampfn{telnet, , 127.0.0.1,} @trampfn{telnet, , 192.168.0.1,} +@trampfn{telnet, , localhost,} @trampfn{telnet, , melancholia.danann.net,} +@trampfn{telnet, , melancholia,} +@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{//}. +@ifinfo +@xref{Minibuffer File, , , @value{emacsdir}}. +@end ifinfo + +@ifset emacs +As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//etc} +@key{TAB}} would result in +@file{@trampfn{telnet, , melancholia, /etc}}, whereas +@kbd{@trampfn{telnet, , melancholia, //etc} @key{TAB}} reduces the +minibuffer contents to @file{/etc}. A triple-slash stands for the +default behaviour, +i.e. @kbd{@trampfn{telnet, , melancholia, /usr/local/bin///etc} +@key{TAB}} expands directly to @file{/etc}. +@end ifset + +@ifset xemacs +As example, @kbd{@trampfn{telnet, , melancholia, /usr/local/bin//}} +would result in @file{@trampfn{telnet, , melancholia, /}}, whereas +@kbd{@trampfn{telnet, , melancholia, //}} expands the minibuffer +contents to @file{/}. +@end ifset + + +@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 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 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}. + +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 transfer 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 recognised 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-copy-beep-advice activate) + " make tramp beep after copying a file." + (interactive) + (beep)) +@end lisp + + +@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 hostname 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? + +@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 + +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 + + +@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. +@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. + + +@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) +(mapcar 'trace-function-background + (mapcar 'intern + (all-completions "tramp-" obarray 'functionp))) +(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 Concept Index +@comment node-name, next, previous, up +@unnumbered Concept Index +@printindex cp +@contents +@c End of tramp.texi - the TRAMP User Manual +@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 * Make terminology "inline" vs "out-of-band" consistent. +@c It seems that "external" is also used instead of "out-of-band". + +@c * M. Albinus +@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 00000000000..4ed196a80f0 --- /dev/null +++ b/doc/misc/trampver.texi @@ -0,0 +1,62 @@ +@c -*-texinfo-*- +@c texi/trampver.texi. Generated from trampver.texi.in by configure. + +@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.11-pre + +@c Other flags from configuration +@set instprefix /usr/local +@set lispdir /usr/local/share/emacs/site-lisp +@set infodir /usr/local/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 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 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 00000000000..0fc6b08acdc --- /dev/null +++ b/doc/misc/url.texi @@ -0,0 +1,1202 @@ +\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 GNU Emacs Lisp +@direntry +* URL: (url). URL loading package. +@end direntry + +@ifnottex +This file documents the URL loading package. + +Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002, +2004, 2005, 2006, 2007 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being +``GNU GENERAL PUBLIC LICENSE''. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' +@end ifnottex + +@c +@titlepage +@sp 6 +@center @titlefont{URL} +@center @titlefont{Programmer's Manual} +@sp 4 +@center First Edition, URL Version 2.0 +@sp 1 +@c @center December 1999 +@sp 5 +@center William M. Perry +@center @email{wmperry@@gnu.org} +@center David Love +@center @email{fx@@gnu.org} +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002, +2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being +``GNU GENERAL PUBLIC LICENSE''. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' +@end titlepage +@page +@node Top +@top URL + + + +@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 honouring 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 honoured, +@code{t} (the default) means they will always be honoured, 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 honour. 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 + +@setchapternewpage odd +@contents +@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 00000000000..a3f4a447f82 --- /dev/null +++ b/doc/misc/vip.texi @@ -0,0 +1,1958 @@ +\input texinfo + +@setfilename ../info/vip +@settitle VIP + +@copying +Copyright @copyright{} 1987, 2001, 2002, 2003, 2004, +2005, 2006, 2007 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@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 + +@dircategory Emacs +@direntry +* VIP: (vip). An older VI-emulation for Emacs. +@end direntry + +@finalout + +@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 + +@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 + +@setchapternewpage odd +@contents +@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 00000000000..55c97f18c9c --- /dev/null +++ b/doc/misc/viper.texi @@ -0,0 +1,4579 @@ +% -*-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 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.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory 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 April 2007, Viper Version 3.13.1 + +@author Michael Kifer (Viper) +@author Aamod Sane (VIP 4.4) +@author Masahiko Sato (VIP 3.5) + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@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 + +@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-ESC-keyseq-timeout 200 on tty, 0 on windowing display +Escape key sequences separated by this much delay (in milliseconds) are +interpreted as command, ignoring the special meaning of @key{ESC} in +VI. The default is suitable for most terminals. However, if your terminal +is extremely slow, you might want to increase this slightly. You will know +if your terminal is slow if the @key{ESC} key sequences emitted by the +arrow keys are interpreted as separately typed characters (and thus the +arrow keys won't work). Making this value too large will slow you down, so +exercise restraint. +@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-translate-all-ESC-keysequences @code{t} on tty, @code{nil} on windowing display +Normally, Viper lets Emacs translate only those ESC key sequences that are +defined in the low-level key-translation-map or function-key-map, such as those +emitted by the arrow and function keys. Other sequences, e.g., @kbd{\\e/}, are +treated as @kbd{ESC} command followed by a @kbd{/}. This is good for people +who type fast and tend to hit other characters right after they hit +ESC. Other people like Emacs to translate @kbd{ESC} sequences all the time. +The default is to translate all sequences only when using a dumb terminal. +This permits you to use @kbd{ESC} as a meta key in insert mode. For instance, +hitting @kbd{ESC x} fast would have the effect of typing @kbd{M-x}. +If your dumb terminal is not so dumb and understands the meta key, then you +probably will be better off setting this variable to @code{nil}. Try and see which +way suits you best. +@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-ESC-key "\e" +Specifies the key used to escape from Insert/Replace states to Vi. +Must be set in @file{.viper}. This variable cannot be +changed interactively after Viper is loaded. +@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-ESC-keyseq-timeout} +@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-ESC-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{function-key-map} as follows: + +@lisp +(cond ((string= (getenv "TERM") "xterm") +(define-key function-key-map "\e[192z" [f11]) ; L1 +(define-key function-key-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{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