From 19e364e29522a20357a236d8501725db47f7feee Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Thu, 6 Sep 2007 04:42:09 +0000 Subject: [PATCH] Move to ../doc/emacs/, misc/ --- man/.gitignore | 23 - man/ChangeLog | 8242 --------- man/Makefile.in | 368 - man/abbrevs.texi | 457 - man/ack.texi | 1574 -- man/ada-mode.texi | 1410 -- man/anti.texi | 306 - man/arevert-xtra.texi | 191 - man/autotype.texi | 676 - man/basic.texi | 776 - man/buffers.texi | 665 - man/building.texi | 1440 -- man/cal-xtra.texi | 838 - man/calc.texi | 36190 ---------------------------------------- man/calendar.texi | 1687 -- man/cc-mode.texi | 6998 -------- man/cl.texi | 5377 ------ man/cmdargs.texi | 1263 -- man/commands.texi | 294 - man/custom.texi | 2515 --- man/dired-x.texi | 1275 -- man/dired-xtra.texi | 49 - man/dired.texi | 1317 -- man/display.texi | 1259 -- man/doclicense.texi | 416 - man/ebrowse.texi | 1462 -- man/ediff.texi | 2546 --- man/emacs-mime.texi | 1832 -- man/emacs-xtra.texi | 126 - man/emacs.texi | 1365 -- man/emerge-xtra.texi | 414 - man/entering.texi | 170 - man/erc.texi | 1027 -- man/eshell.texi | 948 -- man/eudc.texi | 985 -- man/faq.texi | 5590 ------- man/files.texi | 2950 ---- man/fixit.texi | 471 - man/flymake.texi | 762 - man/forms.texi | 985 -- man/fortran-xtra.texi | 548 - man/frames.texi | 1113 -- man/glossary.texi | 1323 -- man/gnu.texi | 567 - man/gnus-faq.texi | 2307 --- man/gnus.texi | 29508 -------------------------------- man/gpl.texi | 721 - man/help.texi | 666 - man/idlwave.texi | 4327 ----- man/indent.texi | 244 - man/info.texi | 1503 -- man/killing.texi | 699 - man/kmacro.texi | 616 - man/m-x.texi | 75 - man/macos.texi | 429 - man/maintaining.texi | 862 - man/major.texi | 206 - man/makefile.w32-in | 389 - man/mark.texi | 452 - man/message.texi | 2362 --- man/mh-e.texi | 9793 ----------- man/mini.texi | 580 - man/misc.texi | 2559 --- man/msdog-xtra.texi | 687 - man/msdog.texi | 766 - man/mule.texi | 1535 -- man/newsticker.texi | 290 - man/org.texi | 7931 --------- man/pcl-cvs.texi | 1443 -- man/pgg.texi | 498 - man/picture-xtra.texi | 291 - man/programs.texi | 1773 -- man/rcirc.texi | 768 - man/reftex.texi | 5898 ------- man/regs.texi | 330 - man/rmail.texi | 1430 -- man/sc.texi | 2533 --- man/screen.texi | 359 - man/search.texi | 1361 -- man/sending.texi | 724 - man/ses.texi | 982 -- man/sieve.texi | 369 - man/smtpmail.texi | 427 - man/speedbar.texi | 1261 -- man/texinfo.tex | 8662 ---------- man/text.texi | 2901 ---- man/tramp.texi | 3297 ---- man/trampver.texi | 62 - man/trouble.texi | 1066 -- man/url.texi | 1202 -- man/vc-xtra.texi | 32 - man/vc1-xtra.texi | 151 - man/vc2-xtra.texi | 789 - man/vip.texi | 1958 --- man/viper.texi | 4579 ----- man/widget.texi | 1855 -- man/windows.texi | 387 - man/woman.texi | 1439 -- man/xresources.texi | 1216 -- 99 files changed, 220340 deletions(-) delete mode 100644 man/.gitignore delete mode 100644 man/ChangeLog delete mode 100644 man/Makefile.in delete mode 100644 man/abbrevs.texi delete mode 100644 man/ack.texi delete mode 100644 man/ada-mode.texi delete mode 100644 man/anti.texi delete mode 100644 man/arevert-xtra.texi delete mode 100644 man/autotype.texi delete mode 100644 man/basic.texi delete mode 100644 man/buffers.texi delete mode 100644 man/building.texi delete mode 100644 man/cal-xtra.texi delete mode 100644 man/calc.texi delete mode 100644 man/calendar.texi delete mode 100644 man/cc-mode.texi delete mode 100644 man/cl.texi delete mode 100644 man/cmdargs.texi delete mode 100644 man/commands.texi delete mode 100644 man/custom.texi delete mode 100644 man/dired-x.texi delete mode 100644 man/dired-xtra.texi delete mode 100644 man/dired.texi delete mode 100644 man/display.texi delete mode 100644 man/doclicense.texi delete mode 100644 man/ebrowse.texi delete mode 100644 man/ediff.texi delete mode 100644 man/emacs-mime.texi delete mode 100644 man/emacs-xtra.texi delete mode 100644 man/emacs.texi delete mode 100644 man/emerge-xtra.texi delete mode 100644 man/entering.texi delete mode 100644 man/erc.texi delete mode 100644 man/eshell.texi delete mode 100644 man/eudc.texi delete mode 100644 man/faq.texi delete mode 100644 man/files.texi delete mode 100644 man/fixit.texi delete mode 100644 man/flymake.texi delete mode 100644 man/forms.texi delete mode 100644 man/fortran-xtra.texi delete mode 100644 man/frames.texi delete mode 100644 man/glossary.texi delete mode 100644 man/gnu.texi delete mode 100644 man/gnus-faq.texi delete mode 100644 man/gnus.texi delete mode 100644 man/gpl.texi delete mode 100644 man/help.texi delete mode 100644 man/idlwave.texi delete mode 100644 man/indent.texi delete mode 100644 man/info.texi delete mode 100644 man/killing.texi delete mode 100644 man/kmacro.texi delete mode 100644 man/m-x.texi delete mode 100644 man/macos.texi delete mode 100644 man/maintaining.texi delete mode 100644 man/major.texi delete mode 100644 man/makefile.w32-in delete mode 100644 man/mark.texi delete mode 100644 man/message.texi delete mode 100644 man/mh-e.texi delete mode 100644 man/mini.texi delete mode 100644 man/misc.texi delete mode 100644 man/msdog-xtra.texi delete mode 100644 man/msdog.texi delete mode 100644 man/mule.texi delete mode 100644 man/newsticker.texi delete mode 100644 man/org.texi delete mode 100644 man/pcl-cvs.texi delete mode 100644 man/pgg.texi delete mode 100644 man/picture-xtra.texi delete mode 100644 man/programs.texi delete mode 100644 man/rcirc.texi delete mode 100644 man/reftex.texi delete mode 100644 man/regs.texi delete mode 100644 man/rmail.texi delete mode 100644 man/sc.texi delete mode 100644 man/screen.texi delete mode 100644 man/search.texi delete mode 100644 man/sending.texi delete mode 100644 man/ses.texi delete mode 100644 man/sieve.texi delete mode 100644 man/smtpmail.texi delete mode 100644 man/speedbar.texi delete mode 100644 man/texinfo.tex delete mode 100644 man/text.texi delete mode 100644 man/tramp.texi delete mode 100644 man/trampver.texi delete mode 100644 man/trouble.texi delete mode 100644 man/url.texi delete mode 100644 man/vc-xtra.texi delete mode 100644 man/vc1-xtra.texi delete mode 100644 man/vc2-xtra.texi delete mode 100644 man/vip.texi delete mode 100644 man/viper.texi delete mode 100644 man/widget.texi delete mode 100644 man/windows.texi delete mode 100644 man/woman.texi delete mode 100644 man/xresources.texi diff --git a/man/.gitignore b/man/.gitignore deleted file mode 100644 index 3ff56b474dd..00000000000 --- a/man/.gitignore +++ /dev/null @@ -1,23 +0,0 @@ -*.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/man/ChangeLog b/man/ChangeLog deleted file mode 100644 index 3cc76452fb3..00000000000 --- a/man/ChangeLog +++ /dev/null @@ -1,8242 +0,0 @@ -2007-09-05 Glenn Morris - - * custom.texi (Safe File Variables): Clarify `!' and risky variables. - -2007-09-01 Jay Belanger - - * calc.texi (Date Conversions): Clarify definition of - Julian day numbering. - (Date Forms): Clarify definition of Julian day numbering; - add some history. - -2007-08-30 Carsten Dominik - - * org.texi: Version 5.07 - -2007-08-29 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 23.0.50. - -2007-08-24 IRIE Tetsuya (tiny change) - - * message.texi (MIME): Replace mml-attach with mml-attach-file. - -2007-08-22 Carsten Dominik - - * org.texi (Adding hyperlink types): New section. - (Embedded LaTeX): Chapter updated because of LaTeX export. - (LaTeX export): New section. - (Using links out): New section. - -2007-08-22 Glenn Morris - - * faq.texi (Learning how to do something): Refcards now in - etc/refcards/ directory. - -2007-08-22 Michael Albinus - - * tramp.texi (Remote Programs): Persistency file must be cleared when - changing `tramp-remote-path'. - (Filename Syntax): Don't use @var{} constructs inside the @trampfn - macro. - -2007-08-17 Eli Zaretskii - - * basic.texi (Position Info): Add index entry for face at point. - Mention that character faces are also displayed by "C-u C-x =". - -2007-08-17 Jay Belanger - - * calc.texi: Move contents to beginning of file. - (Algebraic Entry): Fix the formatting of an example. - -2007-08-15 Jay Belanger - - * calc.texi (Basic Operations on Units): Mention exact versus - inexact conversions. - -2007-08-14 Jay Belanger - - * calc.texi (Basic Operations on Units): Mention default - values for new units. - (Quick Calculator Mode): Mention that binary format will - be displayed. - -2007-08-14 Katsumi Yamaoka - - * gnus.texi (Selecting a Group): Mention gnus-maximum-newsgroup. - -2007-08-10 Katsumi Yamaoka - - * gnus.texi (NNTP): Mention nntp-xref-number-is-evil. - -2007-08-08 Glenn Morris - - * glossary.texi (Glossary): Deprecate `iff'. - * gnus.texi, sieve.texi: Replace `iff'. - -2007-08-07 Chong Yidong - - * files.texi (File Conveniences): Document point motion keys in Image - mode. - -2007-08-03 Jay Belanger - - * calc.texi (Basic Graphics): Mention the graphing of error - forms. - (Graphics Options): Mention how `g s' handles error forms. - (Curve Fitting): Mention plotting the curves. - (Standard Nonlinear Models): Add additional models. - (Curve Fitting Details): Mention the Levenberg-Marquardt method. - (Linear Fits): Correct result. - -2007-08-01 Alan Mackenzie - - * cc-mode.texi (Mailing Lists and Bug Reports): Correct "-no-site-file" - to "--no-site-file". - -2007-07-29 Michael Albinus - - * tramp.texi (Frequently Asked Questions): Point to mode line - extension in Emacs 23.1. - - * trampver.texi: Update release number. - -2007-07-27 Glenn Morris - - * calc.texi (Copying) - * emacs.texi (Copying): Include license text from gpl.texi, rather than - in-line. - - * gpl.texi: New file with text of GPL. - * Makefile.in (EMACSSOURCES): Add gpl.texi. - -2007-07-26 Dan Nicolaescu - - * vc2-xtra.texi (Customizing VC): Add GIT and HG. - - * dired.texi (Wdired): Mention C-x C-q key binding. - -2007-07-28 Nick Roberts - - * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba". - -2007-07-25 Glenn Morris - - * calc.texi (Copying) - * emacs.texi (Copying): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Glenn Morris - - * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work - for some calendars. - -2007-07-23 Nick Roberts - - * screen.texi (Mode Line): Describe new mode-line flag that shows if - default-directory for the current buffer is on a remote machine. - -2007-07-22 Michael Albinus - - Sync with Tramp 2.1.10. - - * tramp.texi (trampfn): Expand macro implementation in order to handle - empty arguments. - (trampfnmhl, trampfnuhl, trampfnhl): Remove macros. Replace all - occurencies by trampfn. - (Frequently Asked Questions): Extend example code for host - identification in the modeline. Add bbdb to approaches shortening Tramp - file names to be typed. - - * trampver.texi: Update release number. - -2007-07-21 Eli Zaretskii - - * vc2-xtra.texi (Customizing VC) : Update the - default value. - -2007-07-21 Richard Stallman - - * files.texi (Why Version Control?): Improve previous change. - -2007-07-18 Eric S. Raymond - - * files.texi (Why Version Control?): New node. - -2007-07-17 Michael Albinus - - * tramp.texi: Move @setfilename ../info/tramp up, outside the header - section. Reported by . - (Remote processes): Arguments of the program to be debugged are taken - literally. - (Frequently Asked Questions): Simplify recentf example. - -2007-07-14 Karl Berry - - * info.texi (@copying): New Back-Cover Text. - - * info.texi (Quitting Info): Move to proper place in source. - (Reported by Benno Schulenberg.) - -2007-07-13 Eli Zaretskii - - * Makefile.in (../info/emacs-mime): Use --enable-encoding. - - * makefile.w32-in ($(infodir)/emacs-mime): Ditto. - - * emacs-mime.texi: Add @documentencoding directive. - -2007-07-12 Nick Roberts - - * tramp.texi (Remote processes): Add an anchor to the subsection - "Running a debugger on a remote host". - - * building.texi (Starting GUD): Add xref to this anchor. - -2007-07-12 Michael Albinus - - * tramp.texi (Remote processes): Don't call it "experimental" any - longer. Add subsection about running a debugger on a remote host. - -2007-07-10 Carsten Dominik - - * org.texi (Properties and columns): Chapter rewritten. - -2007-07-08 Michael Albinus - - * tramp.texi: - * trampver.texi: Migrate to Tramp 2.1. - -2007-07-02 Carsten Dominik - - * org.texi (Properties): New chapter. - -2007-07-02 Reiner Steib - - * gnus-faq.texi ([3.2]): Fix locating of environment variables in the - Control Panel. - - * gnus.texi (Misc Article): Add index entry for - gnus-single-article-buffer. - -2007-06-27 Andreas Seltenreich - - * gnus.texi (Starting Up): Fix typo. - -2007-06-25 Katsumi Yamaoka - - * gnus.texi (Asynchronous Fetching): Fix typo. - -2007-06-24 Karl Berry - - * emacs.texi: new Back-Cover Text. - -2007-06-20 Jay Belanger - - * calc.texi:Change ifinfo to ifnottex (as appropriate) throughout. - (About This Manual): Remove redundant information. - (Getting Started): Mention author. - (Basic Arithmetic, Customizing Calc): Make description of the - variable `calc-multiplication-has-precedence' match its new effect. - -2007-06-19 Jay Belanger - - * calc.texi (Basic Arithmetic, Customizing Calc): Mention - the variable `calc-multiplication-has-precedence'. - -2007-06-19 Carsten Dominik - - * org.texi (Tag): Section swapped with node Timestamps. - (Formula syntax for Lisp): Document new `L' flag. - -2007-06-06 Andreas Seltenreich - - * gnus.texi (Misc Group Stuff, Summary Buffer) - (Server Commands, Article Keymap): Fix typo. s/function/command/. - -2007-06-07 Alan Mackenzie - - * display.texi (Optional Mode Line): Document the new form of - line+column numbers, "(561,2)". - -2007-06-06 Juanma Barranquero - - * cc-mode.texi (Comment Commands, Getting Started, Style Variables): - * gnus.texi (Article Buttons, Mail Source Customization) - (Sending or Not Sending, Customizing NNDiary): - * maintaining.texi (Create Tags Table): - * message.texi (Message Headers): - * mh-e.texi (HTML): Fix typos. - -2007-06-07 Michael Albinus - - Sync with Tramp 2.0.56. - - * tramp.texi (Frequently Asked Questions): Improve ~/.zshrc - settings. Reported by Ted Zlatanov . - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-05-26 Michael Olson - - * erc.texi (Modules): Fix references to completion modules. - -2007-05-09 Reiner Steib - - * gnus.texi (Running NNDiary): Use ~/.gnus.el instead of gnusrc. - -2007-05-09 Didier Verna - - * gnus.texi (Email Based Diary): New. Proper documentation for the - nndiary back end and the gnus-diary library. - -2007-05-07 Karl Berry - - * emacs.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman - - * maintaining.texi (Create Tags Table): Clean up previous change. - -2007-05-05 Francesco Potort,Al(B - - * maintaining.texi (Create Tags Table): Add text about the dangers of - making symbolic links to tags files. - -2007-05-04 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. - -2007-05-03 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. - - * .cvsignore (*.pdf): New entry. - - * texinfo.tex: Update from current version for better pdf generation. - - * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black - for printing. - -2007-05-01 Richard Stallman - - * cmdargs.texi (Initial Options): Under --batch, mention --eval. - -2007-04-30 Reiner Steib - - * gnus.texi (Article Highlighting): Clarify gnus-cite-parse-max-size. - -2007-04-28 Glenn Morris - - * ack.texi (Acknowledgments): - * anti.texi (Antinews): - * faq.texi (New in Emacs 22): - * programs.texi (Program Modes): Restore mention of python.el pending - consideration of legal status. - -2007-04-28 Richard Stallman - - * files.texi (File Names): Fixes to ~ description on MS systems. - -2007-04-27 J.D. Smith - - * idlwave.texi: Minor updates for IDLWAVE 6.1. - -2007-04-26 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 22.1.50. - -2007-04-25 Karl Berry - - * emacs.texi: Improve line breaks on copyright page, - similar layout to lispref, 8.5x11 by default. - - * dired.texi (Image-Dired): Improve line break, fix typo. - -2007-04-24 Chong Yidong - - * programs.texi (Program Modes): - * faq.texi (New in Emacs 22): - * anti.texi (Antinews): - * ack.texi (Acknowledgments): python.el removed. - -2007-04-23 Jay Belanger - - * calc.texi (Reporting bugs): Update maintainer's address. - -2007-04-23 Chong Yidong - - * display.texi (Highlight Interactively): Correct description of - hi-lock-file-patterns-policy. - - * files.texi (File Archives): Mention self-extracting executables. - -2007-04-23 Eli Zaretskii - - * search.texi (Unconditional Replace, Query Replace): Add xref to - "Replacement and Case". - -2007-04-22 Chong Yidong - - * dired.texi (Image-Dired): Move from Thumbnails node. - * misc.texi (Thumbnails): Node deleted. - * emacs.texi (Top): Update node listing. - - * files.texi (File Conveniences): - * ack.texi (Acknowledgments): - * faq.texi (New in Emacs 22): Rename "tumme" to "image-dired". - -2007-04-21 Richard Stallman - - * display.texi (Highlight Interactively): Correct previous change. - Clarify doc of hi-lock-find-patterns, and move new features into it. - -2007-04-20 David Koppelman - - * display.texi (Highlight Interactively): Document - hi-lock-file-patterns-policy. - -2007-04-20 Martin Rudalics - - * display.texi (Scrolling): Fix typo. - -2007-04-15 Jay Belanger - - * calc.texi (Title page): Remove the date. - (Basic Arithmetic): Emphasize that / binds less strongly than *. - (The Standard Calc Interface): Change trail title. - (Floats): Mention that when non-decimal floats are entered, only - approximations are stored. - (Copying): Move to the appendices. - (GNU Free Documentation License): Add as an appendix. - -2007-04-15 Chong Yidong - - * ada-mode.texi, autotype.texi, cc-mode.texi, cl.texi: - * dired-x.texi, ebrowse.texi, ediff.texi: - * emacs-mime.texi, erc.texi, eshell.texi: - * eudc.texi, flymake.texi, forms.texi, gnus.texi: - * idlwave.texi, message.texi, newsticker.texi, org.texi: - * pcl-cvs.texi, pgg.texi, rcirc.texi, reftex.texi, sc.texi: - * ses.texi, sieve.texi, smtpmail.texi, speedbar.texi: - * tramp.texi, url.texi, vip.texi, viper.texi, widget.texi: - * woman.texi: Include GFDL. - - * doclicense.texi: Remove node heading, so that it can be included by - other files. - - * emacs.texi: Insert node heading for GFDL. - - * dired-x.texi: Relicence under GFDL. Remove date from title page. - - * calc.texi (Algebraic Tutorial): Emphasize that / binds less strongly - than *. - -2007-04-14 Carsten Dominik - - * org.texi (Formula syntax for Calc): Emphasize the operator precedence - in Calc. - -2007-04-14 Eli Zaretskii - - * cmdargs.texi (Colors): Qualify "color of window" index entry by - "command line". - - * display.texi (Faces): Refer to "Creating Frames" for face - and other frame customizations in .emacs. - - * frames.texi (Creating Frames): Mention that face customizations can - be put in .emacs. Add index entries. - -2007-04-12 Richard Stallman - - * glossary.texi (Glossary): Explain `iff'. - -2007-04-11 Karl Berry - - * gnu.texi (Top), - * macos.texi (Mac Font Specs), - * anti.texi (Antinews), - * xresources.texi (Resources), - * misc.texi (Emulation), - * calendar.texi (Daylight Saving), - * dired.texi (Dired and Find), - * rmail.texi (Remote Mailboxes), - * sending.texi (Mail Headers), - * programs.texi (Which Function), - * files.texi (Recover), - * buffers.texi (Uniquify), - * frames.texi (Wheeled Mice), - * killing.texi (Rectangles): Wording to improve breaks in - 8.5x11 format. - * mule.texi (Language Environments): \hbadness=10000 since there's - no way to reword. - * emacs.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman - - * files.texi (File Conveniences): Add xref to Tumme. - Delete text about Thumbnail mode. - -2007-04-09 Romain Francoise - - * faq.texi (New in Emacs 22): Mention improvements to the Windows and - Mac OS ports. Make it clear that mouse-1 complements and doesn't - replace mouse-2. - -2007-04-09 Alan Mackenzie - - * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its - new name. Insert concept index entries. - -2007-04-08 Richard Stallman - - * url.texi: Fix some indexing. - (Disk Caching): Drop discussion of old/other Emacs versions. - -2007-04-08 Chong Yidong - - * display.texi (Standard Faces): Document prefix arg for - list-faces-display. - - * rmail.texi (Rmail Scrolling): Document rmail-end-of-message. - - * woman.texi (Word at point, Interface Options): woman-topic-at-point - renamed to woman-use-topic-at-point. Document new behavior. - -2007-04-07 Chong Yidong - - * url.texi (Disk Caching): Say Emacs 21 "and later". - - * cc-mode.texi (Font Locking Preliminaries): Link to Emacs manual node - on Font locking which now mentions JIT lock. - - * killing.texi (Deletion): Rewrite description of M-\ prefix argument. - - * files.texi (Misc File Ops): Rewrite description of - insert-file-literally. - -2007-04-01 Michael Olson - - * erc.texi: Update for the ERC 5.2 release. - -2007-03-31 David Kastrup - - * woman.texi (Topic, Interface Options): Explain changes semantics of - woman-manpath in order to consider MANPATH_MAP entries. - -2007-03-31 Eli Zaretskii - - * misc.texi (Printing): Postscript -> PostScript. - - * emacs-mime.texi (Non-MIME): Postscript -> PostScript. - - * ack.texi (Acknowledgments): Postscript -> PostScript. - - * custom.texi (Init File, Init Non-ASCII): Fix last change. - - * emacs.texi (Top): Fix the menu due to the change in custom.texi - below. - -2007-03-30 Chong Yidong - - * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to - Init Non-ASCII. - (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead. - (Init Non-ASCII): New node. - -2007-03-28 YAMAMOTO Mitsuharu - - * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold. - -2007-03-26 Richard Stallman - - * pgg.texi (Caching passphrase): Clean up previous change. - -2007-03-25 Thien-Thi Nguyen - - * gnus.texi (Setting Process Marks): Fix typo. - -2007-03-25 Romain Francoise - - * faq.texi (New in Emacs 22): Reorganize using an itemized list for - readability, and include various fixes by Daniel Brockman, Nick Roberts - and Dieter Wilhelm. - -2007-03-24 Thien-Thi Nguyen - - * gnus.texi (Splitting Mail): Reword "splitting"-as-adj to be -as-noun. - - * gnus.texi (Mail Source Specifiers): Fix typo. - -2007-03-22 Ralf Angeli - - * reftex.texi (Imprint): Update maintainer information. - -2007-03-15 Katsumi Yamaoka - - * message.texi (Message Buffers): Update documentation for - message-generate-new-buffers. - -2007-03-15 Daiki Ueno - - * pgg.texi (Caching passphrase): Describe pgg-passphrase-coding-system. - -2007-03-21 Glenn Morris - - * eshell.texi (Known problems): Emacs 22 comes with eshell 2.4.2. - -2007-03-19 Chong Yidong - - * eshell.texi (Known problems): Emacs 21 -> 22. - - * cc-mode.texi (Performance Issues): Update note about 21.3 to 22.1. - -2007-03-18 Jay Belanger - - * calc.texi (Time Zones): Mention that the DST rules changed in 2007. - -2007-03-12 Glenn Morris - - * calc.texi (Time Zones): Switch to new North America DST rule. - - * calendar.texi, emacs.texi (Daylight Saving): Rename node from - "Daylight Savings". - - * calc.texi, calendar.texi: Replace "daylight savings" with "daylight - saving" in text throughout. - -2007-03-11 Andreas Seltenreich - - * gnus.texi (Mail and Post): Update documentation for gnus-user-agent. - The variable now uses a list of symbols instead of just a symbol. - Reported by Christoph Conrad . - -2007-03-06 Romain Francoise - - * faq.texi (New in Emacs 22): Don't say "now" too much. Add MH-E to - new packages, and mention Gnus update. - -2007-03-04 Richard Stallman - - * custom.texi (Safe File Variables): Minor correction. - -2007-02-27 Katsumi Yamaoka - - * gnus.texi (NNTP): Mention nntp-never-echoes-commands and - nntp-open-connection-functions-never-echo-commands. - -2007-02-28 Thien-Thi Nguyen - - * rmail.texi (Movemail): Add internal ref. - Don't indent the intro for the PROTO table. - Format PROTO table items with @code. - -2007-02-27 Chong Yidong - - * pgg.texi (Caching passphrase): Document gpg-agent usage, gpg-agent - problems on the console, and security risk in not using gpg-agent. - -2007-02-26 Nick Roberts - - * building.texi: Remove references to bashdb. - -2007-02-25 Carsten Dominik - - * org.texi (The spreadsheet): Renamed from "Table calculations". - Completely reorganized and rewritten. - (CamelCase links): Section removed. - (Repeating items): New section. - (Tracking TODO state changes): New section. - (Agenda views): Chapter reorganized and rewritten. - (HTML export): Section rewritten. - (Tables in arbitrary syntax): New section. - (Summary): Better feature summary. - (Activation): Document problem with cut-and-paste of Lisp code - from PDF files. - (Visibility cycling): Document indirect buffer use. - (Structure editing): Document sorting. - (Remember): Section rewritten. - (Time stamps): Better description of time stamp types. - (Tag searches): Document regular expression search for tags. - (Stuck projects): New section. - (In-buffer settings): New keywords. - (History and Acknowledgments): Updated description. - -2007-02-24 Alan Mackenzie - - * cc-mode.texi (Movement Commands): Insert two missing command names. - (Getting Started): Slight wording correction (use conditional). - -2007-02-22 Kim F. Storm - - * widget.texi (User Interface, Basic Types): Document need to put some - text before the %v escape in :format string in editable-field widget. - -2007-02-19 Juanma Barranquero - - * mule.texi (Language Environments): Update list of supported language - environments. - -2007-02-18 Romain Francoise - - * pcl-cvs.texi (Miscellaneous commands): q runs `cvs-bury-buffer', not - `cvs-mode-quit'. - -2007-02-14 Kim F. Storm - - * building.texi (Grep Searching): Fix lgrep doc. - -2007-02-12 Chong Yidong - - * back.texi: Remove unused file. - -2007-02-10 Markus Triska - - * widget.texi (Programming Example): Put constant strings in :format. - -2007-02-07 Juanma Barranquero - - * faq.texi (Fullscreen mode on MS-Windows): New node. - -2007-02-05 Francesco Potort,Al(B - - * maintaining.texi (Tag Syntax): Now --members is the default for - etags, not for ctags yet. - -2007-02-04 David Kastrup - - * faq.texi (AUCTeX): Update version number. Should probably be done - for other packages as well. - -2007-02-03 Eli Zaretskii - - * emacs.texi (Top): Update the top-level menus. Make the detailed menu - headers compliant with Texinfo guidelines and with what texnfo-upd.el - expects. Add comments to prevent people from inadvertently modifying - the key parts needed by `texinfo-multiple-files-update'. - -2007-01-29 Chong Yidong - - * frames.texi (Secondary Selection): Window clicked does not matter - when mouse-yank-at-point is non-nil. - -2007-01-28 Andreas Seltenreich - - * gnus.texi (Batching Agents): Fix example. Reported by Tassilo Horn - . - -2007-01-27 Eli Zaretskii - - * msdog.texi (ls in Lisp): Document ls-lisp-format-time-list and - ls-lisp-use-localized-time-format. - -2007-01-20 Markus Triska - - * flymake.texi (Flymake mode): find-file-hook instead of ...-hooks. - -2007-01-13 Michael Olson - - * erc.texi (Modules): Mention capab-identify module. - -2007-01-16 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Describe how to disable a - system abbrev. - -2007-01-11 Richard Stallman - - * msdog.texi (Windows Keyboard): Another small cleanup. - -2007-01-10 Richard Stallman - - * msdog.texi (Windows Keyboard): Yet another try to make - everyone happy with that passage. - -2007-01-05 Richard Stallman - - * anti.texi (Antinews): Mention M-x shell scrolling. - -2007-01-05 Nick Roberts - - * building.texi (Watch Expressions): Describe gdb-max-children. - -2007-01-05 Michael Olson - - * erc.texi (Getting Started): Update for /RECONNECT command. - -2007-01-04 Richard Stallman - - * ebrowse.texi: Change C-c b to C-c C-m. - - * msdog.texi (Windows Keyboard): Clarify previous change. - -2007-01-03 Reiner Steib - - * gnus.texi (Customizing Articles): Use index entries for gnus-treat-* - variables only in info to avoid redundant entries in the printed - manual. - -2007-01-02 Richard Stallman - - * custom.texi (Changing a Variable): Minor clarification. - (Specific Customization): customize-customized => customize-unsaved. - - * entering.texi (Entering Emacs): Clean up text about restarting - Emacs for each file. - - * misc.texi (Shell Options): Minor cleanup. - - * msdog.texi (Windows Keyboard): Explain that Windows was incompatible - with Emacs, not vice versa. - - * programs.texi (Symbol Completion): Recommend customizing - window manager. - - * xresources.texi (Resources): Minor fix. - -2007-01-02 Daiki Ueno - - * message.texi (Using PGP/MIME): Document gpg-agent usage. - -2007-01-02 Reiner Steib - - * message.texi (Security): Split into sub-nodes. - -2007-01-01 Alan Mackenzie - - * cc-mode.texi ("Limitations and Known Bugs"): Document problems with - eval-after-load in Emacs <=21 and a workaround. Document that - trigraphs are not supported. - -2007-01-01 Alan Mackenzie - - * cc-mode.texi ("Filling and Breaking"): Amend the doc for - c-context-line-break. When invoked within a string, preserve - whitespace. Add a backslash only when also in a macro. - -2007-01-01 Alan Mackenzie - - * cc-mode.texi ("Choosing a Style"): Mention c-file-style. - -2007-01-01 Alan Mackenzie - - * cc-mode.texi ("Movement Commands", "Sample .emacs File"): C-M-[ae] - are now bound by default to c-\(beginning\|end\)-of-defun by default. - -2007-01-01 Alan Mackenzie - - * cc-mode.texi ("Other Commands"): Move c-set-style (C-c .) here from - "Choosing a Style". - - * cc-mode.texi ("Styles"): Add @dfn{style}. - -2007-01-01 Jan Dj,Ad(Brv - - * xresources.texi (Table of Resources): Add scrollBarWidth resource. - -2007-01-01 Richard Stallman - - * commands.texi (User Input): Document keys stolen by window mangers. - -2006-12-31 Richard Stallman - - * custom.texi (Specific Customization): Document customize-option - instead of customize-variable. - -2006-12-31 Kim F. Storm - - * major.texi (Choosing Modes): Document auto-mode-case-fold. - -2006-12-30 Kim F. Storm - - * killing.texi (CUA Bindings): Fix typo. - - * xresources.texi (Table of Resources): Mention grow-only value for - auto-resize-tool-bars. - -2006-12-30 Michael Albinus - - Sync with Tramp 2.0.55. - - * trampver.texi: Update release number. - -2006-12-29 Reiner Steib - - * gnus.texi (Customizing Articles): Add index entries for all - gnus-treat-* variables. - -2006-12-29 Jouni K. Sepp,Ad(Bnen - - * gnus.texi (IMAP): Fix incorrect explanation of - nnimap-search-uids-not-since-is-evil in documentation for - nnimap-expunge-search-string. - -2006-12-27 Reiner Steib - - * gnus.texi (ifile spam filtering): Rename spam-ifile-database-path to - spam-ifile-database. - -2006-12-26 Reiner Steib - - * gnus.texi (Spam Package Configuration Examples): Don't encourage to - rebind C-s. - -2006-12-26 Jouni K. Sepp,Ad(Bnen - - * gnus.texi (Group Parameters, Group Maintenance, Topic Commands) - (Mail Group Commands, Expiring Mail, IMAP): Add index entries for - "expiring mail". - (IMAP): Document nnimap-search-uids-not-since-is-evil and - nnimap-nov-is-evil. - -2006-12-27 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Mention widespread Windows bindings, - and how to get them back. - -2006-12-26 Richard Stallman - - * calendar.texi (Holidays): Holiday listing is based on current - practice, but DST is not. - -2006-12-25 Richard Stallman - - * emacs.texi (Top): Update subnode menus. - - * mark.texi (Transient Mark): Fix xref. - - * killing.texi (Graphical Kill): Node deleted. - (Killing): Add xref to Cut and Paste. - (CUA Bindings): Update xref. - - * frames.texi (Cut and Paste): New section to hold other nodes. - (Mouse Commands): Node demoted. - (Cut/Paste Other App): Split out from Mouse Commands. - (Word and Line Mouse): Likewise. - (Secondary Selection, Clipboard): Nodes demoted. - -2006-12-25 Kevin Ryde - - * cl.texi (Sorting Sequences): In sort*, add a little cautionary note - about the key procedure being used heavily. - -2006-12-24 Chong Yidong - - * pgg.texi (Caching passphrase): Default for pgg-gpg-use-agent changed - to t. - (Prerequisites): Add explanation about gpg-agent. - -2006-12-24 Kevin Ryde - - * calendar.texi (Holidays): US daylight saving begins second Sunday - in March for 2007 onwards. - (Daylight Savings): Show new US default daylight saving rules, 2nd - Sun in Mar to 1st Sun in Nov, now in cal-dst.el. - -2006-12-23 Chong Yidong - - * calendar.texi (Scroll Calendar): < and > are switched. - -2006-12-23 Kevin Rodgers - - * killing.texi (Deletion): Describe M-\ prefix argument. - -2006-12-23 Richard Stallman - - * search.texi (Regexp Search): Explain why forward and reverse regexp - search are not mirror images. - -2006-12-22 Kevin Ryde - - * cl.texi (Sorting Sequences): Typo in sort*, example showed plain - "sort" instead of "sort*". - -2006-12-19 Richard Stallman - - * calc.texi (History and Acknowledgements): Recognize that Emacs - now does have floating point. - -2006-12-19 Kim F. Storm - - * major.texi (Choosing Modes): Describe match-function elements for - magic-mode-alist. - -2006-12-19 Michael Albinus - - * tramp.texi (External transfer methods): Describe new method `scpc'. - -2006-12-18 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys - peculiarities. - -2006-12-18 Richard Stallman - - * abbrevs.texi (Editing Abbrevs): Fix previous change. - -2006-12-17 Sascha Wilde - - * pgg.texi: Added short note on gpg-agent to the introduction. - -2006-12-17 Alan Mackenzie - - * programs.texi (Left Margin Paren): Remove the bit which says - that CC Mode sets open-paren-in-column-0-is-defun-start to nil. - Discuss some of the issues of setting this option to nil. - -2006-12-17 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Mention system abbrevs. - -2006-12-16 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect. - (Windows Files): `w32-get-true-file-attributes' is only relevant for - NTFS volumes. - (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS - volumes. - -2006-12-15 Eli Zaretskii - - * text.texi (HTML Mode): Fix "C-c TAB". - -2006-12-13 Reiner Steib - - * gnus.texi (Hiding Headers): Document that `long-to' and `many-to' - also applies to Cc. - -2006-12-12 Reiner Steib - - * gnus.texi (X-Face): Clarify. Say which programs are required - on Windows. - -2006-12-09 Richard Stallman - - * misc.texi (Invoking emacsclient): Simplify TCP file text. - -2006-12-08 Kevin Rodgers - - * files.texi (Misc File Ops): Document insert-file-literally. - -2006-12-08 Eli Zaretskii - - * cmdargs.texi (Colors): Note that --color is intended for overriding - the terminal defaults, not for normal invocation. - - * misc.texi (Emacs Server): Improve wording. Don't mention the - ``server program''. Add a cross-reference to "Init File" node. - (Invoking emacsclient): Add index entries. Document both short and - long versions of command-line options. Document the -f option. - -2006-12-08 Michael Olson - - * erc.texi (Modules): Remove documentation for list module. - -2006-12-06 Richard Stallman - - * text.texi (Outline Format): Say to set outline-regexp - and outline-level with major modes and file local variables. - -2006-12-05 Micha,Ak(Bl Cadilhac - - * anti.texi (Antinews): Mention the alternative to - `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'. - - * faq.texi (^M in the shell buffer): Ditto. - - * misc.texi (Interactive Shell): Ditto. - -2006-12-04 Eli Zaretskii - - * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - - * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - -2006-12-01 Eli Zaretskii - - * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a - colon in the mode line. - - * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute. - -2006-11-26 Nick Roberts - - * building.texi (Watch Expressions): Mention SPC for expanding/ - contracting watch expressions. - -2006-11-26 Kim F. Storm - - * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more. - -2006-11-26 Nick Roberts - - * building.texi (Debugger Operation): Define text command mode. - Clarify how tooltips work. - (GDB Graphical Interface): Explain how to run in text command mode - more clearly. - -2006-11-25 Juanma Barranquero - - * mule.texi (Defining Fontsets): Fix use of `charset' and `font'. - -2006-11-22 Juanma Barranquero - - * anti.texi (Antinews): Mention --server-file and TCP sockets. - -2006-11-20 Michael Olson - - * erc.texi: Call this the 5.2 stable pre-release of ERC. - -2006-11-18 Chong Yidong - - * misc.texi (Interactive Shell): INSIDE_EMACS is set to t, - and EMACS is deprecated. - -2006-11-18 Juanma Barranquero - - * makefile.w32-in (emacs.dvi): Remove xresmini.texi. - -2006-11-18 Jan Dj,Ad(Brv - - * Makefile.in (emacs.dvi): Remove xresmini.texi. - - * emacs.texi: Include xresources.texi both for info and dvi. - - * xresources.texi: Merge text from xresmini.texi. - -2006-11-17 Carsten Dominik - - * org.texi: Fix typos. - (Agenda commands): Document `C-k'. - -2006-11-16 Eli Zaretskii - - * url.texi (http/https): Fix a typo in the HTTP URL. - -2006-11-14 Stephen Leake - - * ada-mode.texi: Total rewrite. - -2006-11-13 Carsten Dominik - - * org.texi: Minor typo fixes. - -2006-11-13 Bill Wohler - - Release MH-E manual version 8.0.3. - - * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for - release 8.0.3. - - * mh-e.texi (Incorporating Mail): Use output of "mhparam Path" - to set MAILDIR. - (Reading Mail): Document the customization of read-mail-command - for MH-E. - (Viewing Attachments): Document mm-discouraged-alternatives. - (Tool Bar): Fix Texinfo for mh-xemacs-use-tool-bar-flag. - (Junk): Add more information about the settings of mh-junk-background - in a program. Add /usr/bin/mh to PATH in examples. - -2006-11-12 Richard Stallman - - * woman.texi: Update author address but say he no longer maintains it. - -2006-11-12 Roberto Rodr,Am(Bguez (tiny change) - - * glossary.texi: Fix typos. - -2006-11-10 Carsten Dominik - - * org.texi (ARCHIVE tag): Document C-TAB for forcing cycling of - archived trees. - (Checkboxes): Section moved to chapter 5, and extended. - (The date/time prompt): New section. - (Link abbreviations): New section. - (Presentation and sorting): New section. - (Custom agenda views): Section completely rewritten. - (Summary): Compare with Planner. - (Feedback): More info about creating backtraces. - (Plain lists): Modified example. - (Breaking down tasks): New section. - (Custom time format): New section. - (Time stamps): Document inactive timestamps. - (Setting tags): More details about fast tag selection. - (Block agenda): New section. - (Custom agenda views): Section rewritten. - (Block agenda): New section. - -2006-11-07 Michael Albinus - - * tramp.texi (Configuration): scp is the default method. - (Default Method): Use ssh as example for another method. - -2006-11-06 Richard Stallman - - * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti. - - * ack.texi (Acknowledgments): Fix name spelling. - -2006-11-01 Juri Linkov - - * search.texi (Word Search): Document incremental word search. - -2006-10-28 Glenn Morris - - * ack.texi (Acknowledgments): Add cal-html author. - - * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX - Calendar"). Describe new package cal-html. - * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing - Calendar Files." - -2006-10-27 Richard Stallman - - * woman.texi: Downcase nroff/troff/roff. - (Installation): Chapter deleted. Some xrefs deleted. - (Background): woman doesn't advise man ;-). - -2006-10-26 Roberto Rodr,Am(Bguez (tiny change) - - * ada-mode.texi (Project files, Identifier completion) - (Automatic Casing, Debugging, Using non-standard file names) - (Working Remotely): Fix typos. - -2006-10-23 Richard Stallman - - * abbrevs.texi (Expanding Abbrevs): Expansion happens only when - Abbrev mode is enabled. - -2006-10-20 Masatake YAMATO - - * cc-mode.texi (Sample .emacs File): Added missing `)' in - sample code `my-c-initialization-hook'. - -2006-10-19 Stuart D. Herring - - * widget.texi: Fix typos. - -2006-10-19 Michael Albinus - - * tramp.texi (Frequently Asked Questions): Remove questions marked with - "???". There have been no complaints for years, so the information - must be appropriate. - -2006-10-16 Richard Stallman - - * widget.texi: Use @var instead of capitalization. - Clarify many widget type descriptions. - - * emacs.texi: Update ISBN. - -2006-10-13 Andreas Seltenreich - - * gnus.texi (Other modes): Fix typo. Add alternative index entry for - gnus-dired-attach. - (Selecting a Group): Fix typo. - -2006-10-12 Roberto Rodr,Am(Bguez (tiny change) - - * widget.texi: Fix typos. - -2006-10-11 Kim F. Storm - - * emacs.texi (Acknowledgments): Use @dotless{i}. - -2006-10-08 Nick Roberts - - * building.texi (Breakpoints Buffer): Mention catchpoints. - -2006-10-08 Kim F. Storm - - * ack.texi (Acknowledgments): Update. - - * emacs.texi (Acknowledgments): Fix bad @/ form. - -2006-10-06 Reiner Steib - - * gnus.texi (Image Enhancements): Update for Emacs 22. - - * gnus-faq.texi ([1.3]): Update. - -2006-10-06 Richard Stallman - - * faq.texi (Displaying the current line or column): - Delete "As of Emacs 20". - -2006-10-06 Romain Francoise - - * faq.texi (VM): VM works with Emacs 22 too. - -2006-10-06 Richard Stallman - - * ebrowse.texi: Remove Emacs version "21" from title. - -2006-10-05 Kim F. Storm - - * emacs.texi (Acknowledgments): Add more contributors. - -2006-10-03 Richard Stallman - - * emacs.texi (Acknowledgments): Update version and edition. - -2006-10-02 Reiner Steib - - * gnus.texi (Foreign Groups): Say where change of editing commands are - stored. Add reference to `gnus-parameters'. - -2006-10-01 Karl Berry - - * custom.texi (Customization Groups): Page break to keep example buffer - on one page. - -2006-09-30 Karl Berry - - * programs.texi (Basic Indent): @need to improve page break. - * text.texi: Rewording to improve page breaks, and use @LaTeX{}. - -2006-09-29 Glenn Morris - - * calendar.texi (Date Formats): Doc fix for european-calendar-style. - -2006-09-29 Karl Berry - - * windows.texi (Basic Window): Remove forced @break, no longer - desirable. - * frames.texi (Frame Commands), - * mark.texi (Marking Objects): Reword to avoid bad page break. - * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break. - -2006-09-19 Richard Stallman - - * frames.texi (Dialog Boxes): Clean up wording: avoid passive, - stick to present tense. - -2006-09-18 Jan Dj,Ad(Brv - - * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog - to x-gtk-use-old-file-dialog. - (Dialog Boxes): Document x-gtk-file-dialog-help-text. - -2006-09-15 Jay Belanger - - * calc.texi, emacs.texi, mh-e.texi (GNU GENERAL PUBLIC LICENSE): - Change "Library Public License" to "Lesser Public License" - throughout. Use "yyyy" to represent year. - -2006-09-15 Carsten Dominik - - * org.texi (Setting tags): Typo fix. - -2006-09-14 Reiner Steib - - * gnus.texi (Oort Gnus): Add @xref for `mm-fill-flowed'. - -2006-09-12 Reiner Steib - - * files.texi (Visiting): Add index entry "open file". - - * reftex.texi (Citations Outside LaTeX): Simplify lisp example. - -2006-09-12 Paul Eggert - - * faq.texi (Escape sequences in shell output): EMACS is now set - to Emacs's absolute file name, not to "t". - (^M in the shell buffer): Likewise. - * misc.texi (Interactive Shell): Likewise. - -2006-09-11 Richard Stallman - - * building.texi (Compilation Mode): Clarification. - (Grep Searching): Add xref to Compilation Mode. - -2006-09-11 Reiner Steib - - * gnus.texi (Mail Source Specifiers): Mention problem of duplicate - mails with pop3-leave-mail-on-server. Fix wording. - (Limiting): Improve gnus-summary-limit-to-articles. - (X-Face): Fix typo. - -2006-09-11 Simon Josefsson - - * smtpmail.texi (Authentication): Explain TLS and SSL better, based on - suggested by Phillip Lord . - -2006-09-08 Richard Stallman - - * search.texi (Search): Ref multi-file search commands here. - (Other Repeating Search): Not here. - -2006-09-06 Simon Josefsson - - * smtpmail.texi (Authentication): Mention SSL. - -2006-09-01 Eli Zaretskii - - * rcirc.texi (Internet Relay Chat, Useful IRC commands): - Don't use @indicateurl. - - * cc-mode.texi (Subword Movement): Don't use @headitem. - (Custom Braces, Clean-ups): Don't use @tie. - -2006-08-29 Michael Albinus - - Sync with Tramp 2.0.54. - - * tramp.texi (Bug Reports): The Tramp mailing list is moderated now. - Suggested by Adrian Phillips . - -2006-08-28 Richard Stallman - - * windows.texi (Split Window): Update xref. - - * basic.texi (Continuation Lines): Update xref. - - * indent.texi (Tab Stops): Update xref. - - * emacs.texi (Top): Update subnode menu. - - * display.texi (Line Truncation, Displaying Boundaries): New nodes, - split out of Display Custom. - -2006-08-25 Kim F. Storm - - * display.texi (Display Custom): Add variables overline-margin - and x-underline-at-descent-line. - -2006-08-25 Richard Stallman - - * entering.texi (Exiting): Rewrite to give graphical displays - priority over text terminals. - - * search.texi (Incremental Search): Move index entries. - -2006-08-23 Chong Yidong - - * custom.texi (Init File): Reference Find Init to avoid "home - directory" confusion. - -2006-08-22 Nick Roberts - - * building.texi (Other GDB-UI Buffers): Describe how to edit - a value in the locals buffer. - -2006-08-21 Richard Stallman - - * search.texi (Basic Isearch): Add `isearch' index entry. - -2006-08-16 Richard Stallman - - * misc.texi (Saving Emacs Sessions): Clean up wording. - - * mark.texi (Marking Objects): Mention term "select all". - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Move node up in file. - -2006-08-15 Carsten Dominik - - * org.texi (Installation, Activation): Split from Installation and - Activation. - (Clocking work time): Documented new features. - -2006-08-15 Nick Roberts - - * building.texi (Stack Buffer): Explain fringe arrow. - -2006-08-13 Alex Schroeder - - * rcirc.texi (Configuration): Use correct variable in rcirc-authinfo - example. - -2006-08-12 Eli Zaretskii - - * faq.texi (How to add fonts): New node. - - * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored - on startup. - -2006-08-11 Romain Francoise - - * ack.texi (Acknowledgments): Delete mention to zone-mode.el. - -2006-08-10 Sven Joachim (tiny change) - - * mule.texi (Recognize Coding, Text Coding): Fix typos. - -2006-08-10 Richard Stallman - - * text.texi (Format Faces): Substantial rewrites to deal - with face merging. Empty regions don't count. Clarify - face property inheritance. - -2006-08-08 Romain Francoise - - * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen - . - -2006-08-05 Romain Francoise - - * faq.texi (New in Emacs 22): Expand. - -2006-08-04 Eli Zaretskii - - * cmdargs.texi (Window Size X) <--geometry>: Only width and height - apply to all frames. - -2006-08-03 Michael Olson - - * erc.texi: Update for ERC 5.1.4. - -2006-08-01 Richard Stallman - - * help.texi (Name Help): Add index entries for describe-variable. - -2006-08-01 Nick Roberts - - * building.texi (GDB Graphical Interface): Shorten node names. - (GDB-UI Layout): Use GDB-related. - (Other GDB-UI Buffers): Simplify English. - -2006-07-31 Richard Stallman - - * search.texi (Query Replace): Add xref for Dired's Q command. - -2006-07-28 Katsumi Yamaoka - - * gnus.texi (Oort Gnus): Mention that the Lisp files are now installed - in .../site-lisp/gnus/ by default. - [ From gnus-news.texi in the trunk. ] - -2006-07-27 Reiner Steib - - * gnus.texi (MIME Commands): Additions for yEnc. - -2006-07-31 Nick Roberts - - * building.texi (GDB commands in Fringe): Rename to... - (Source Buffers): ..this and move forward. Describe hollow arrow and - new option gdb-find-source-frame. - -2006-07-29 Richard Stallman - - * dired.texi (Operating on Files): Simplify previous change - and fix Texinfo usage. - -2006-07-29 Eli Zaretskii - - * dired.texi (Operating on Files): Add cross-references. State the - Unix commands that do similar things. - -2006-07-28 Richard Stallman - - * mark.texi (Transient Mark): Clarify that region never disappears - when Transient Mark mode is off, and not when it is on. - -2006-07-27 Richard Stallman - - * search.texi (Non-ASCII Isearch): Clarify. Mention C-q. - -2006-07-24 Richard Stallman - - * xresources.texi (GTK styles): Fix texinfo usage. - - * pgg.texi, org.texi, info.texi, forms.texi, flymake.texi: - * faq.texi: Move periods and commas inside quotes. - - * commands.texi (User Input): Explain why we teach keyboard cmds. - - * xresources.texi, xresmini.texi, search.texi, programs.texi: - * misc.texi, kmacro.texi, killing.texi, glossary.texi: - * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi: - * doclicense.texi, display.texi, dired.texi, basic.texi: - * anti.texi, ack.texi: Move periods and commas inside quotes. - -2006-07-22 Eli Zaretskii - - * cmdargs.texi (General Variables): Document EMAIL. - -2006-07-21 Eli Zaretskii - - * frames.texi (Frame Commands): Mention that focus-follows-mouse - doesn't have effect on MS-Windows. - -2006-07-20 Jay Belanger - - * calc.texi (Error forms): Mention M-+ keybinding for `calc-plus-minus'. - -2006-07-18 Chong Yidong - - * faq.texi (Security risks with Emacs): Document Emacs 22 - file-local-variable mechanism. - -2006-07-17 Richard Stallman - - * building.texi (Grep Searching): Explain about chaining grep commands. - -2006-07-12 Michael Olson - - * erc.texi: Update for ERC 5.1.3. - -2006-07-12 Alex Schroeder - - * rcirc.texi: Fix typos. - (Getting started with rcirc): New calling convention for M-x irc. - Mention #rcirc. Removed channel tracking. - (Configuration): Changed the names of all variables that got changed - recently, eg. rcirc-server to rcirc-default-server. Added - documentation for rcirc-authinfo, some background for Bitlbee, and - rcirc-track-minor-mode. - (Scrolling conservatively): Fixed the xref from Auto Scrolling to just - Scrolling. - (Reconnecting after you have lost the connection): Fixed example code - to match code changes. - -2006-07-10 Nick Roberts - - * killing.texi, gnus.texi, message.texi, mini.texi: Fix typos. - -2006-07-09 Chong Yidong - - * misc.texi (Invoking emacsclient): Document behavior when emacsclient - is invoked for multiple files. - -2006-07-08 Eli Zaretskii - - * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the - on-line manual for the rest of this node. - (Windows Mouse) : Include - unconditionally. - (Windows Processes) : Include unconditionally. - Improve wording. - (Windows Printing): Improve wording. - (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the - rest of this node. - -2006-07-07 Carsten Dominik - - * org.texi (Exporting): Document `C-c C-e' as the prefix for exporting - commands. - (Global TODO list): Document the use of the variables - `org-agenda-todo-ignore-scheduled' and - `org-agenda-todo-list-sublevels'. - -2006-07-05 Richard Stallman - - * faq.texi (Scrolling only one line): Fix xref. - -2006-07-05 Thien-Thi Nguyen - - * building.texi (Lisp Eval): - * faq.texi (Evaluating Emacs Lisp code): - Throughout, replace eval-current-buffer with eval-buffer. - -2006-07-05 Nick Roberts - - * mule.texi (Coding Systems, Specify Coding): Link descriptions - of character translation. - -2006-07-04 Nick Roberts - - * rmail.texi (Remote Mailboxes): Add missing @code keyword. - -2006-07-03 Karl Berry - - * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by - not-too-underfull hboxes in the TeX output. - * abbrevs.texi, buffers.texi, building.texi, calendar.texi, - * cmdargs.texi, custom.texi, dired.texi, macos.texi, - * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi, - * sending.texi, text.texi: Fix overfull/underfull boxes. - -2006-07-03 Romain Francoise - - * m-x.texi (M-x): Fix. - -2006-07-03 Richard Stallman - - * rcirc.texi (Scrolling conservatively): Fix xref. - - * pcl-cvs.texi (Viewing differences): Usage fix. - - * search.texi (Other Repeating Search): filename -> file name. - - * misc.texi (Narrowing): Minor cleanups. - - * files.texi (Visiting): filename -> file name. - - * emacs.texi (Top): Update subnode menus. - - * mule.texi (Coding Systems): Move char translation stuff here. - (Specify Coding, Output Coding): New nodes, out of Recognize Coding. - (Recognize Coding): Substantial local rewrites. - (International): Update menu. - - * display.texi (Auto Scrolling): New node, broken out of Scrolling. - (Scrolling): Substantial local rewrites. - (Display): Update menu and intro. - - * dired.texi: filename -> file name. - - * custom.texi (Safe File Variables): Texinfo usage fix. - -2006-07-03 Ted Zlatanov - - * help.texi, m-x.texi: Lots of cleanups. - -2006-07-03 Carsten Dominik - - * org.texi (Agenda commands): Document `s' key to save all org-mode - buffers. - -2006-06-30 Eli Zaretskii - - * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse) - (Windows Processes, Windows Misc): Shorten the printed version by - selectively conditioning less important portions by @ifnottex. - -2006-06-30 Ralf Angeli - - * pcl-cvs.texi (Customizing Faces): Remove -face suffix from face - names. Mention `cvs-msg' face. - -2006-06-29 Carsten Dominik - - * org.texi (Checkboxes): New section. - -2006-06-28 Carsten Dominik - - * org.texi (Embedded LaTeX): Fix typos and implement small improvements - throughout this chapter. - -2006-06-27 Chong Yidong - - * info.texi (Help-Small-Screen): Clarify placement of "All" and "Top" - text for standalone vs Emacs info. - (Help): Clarify header line description. Use mouse-1 for clicks. - (Help-P): Use mouse-1 for clicks. - (Help-^L): "Top" and "All" not displayed with dashes in Emacs. - (Help-^L, Help-M, Help-Int, Search Index, Go to node) - (Choose menu subtopic): Remove gratuitous Emacs command names. - (Help-FOO): Put usual behavior first. - (Help-Xref): Clicking on xrefs works in Emacs. - (Search Text): Clarify what the default behavior is. - (Create Info buffer): Fix Emacs window/X window confusion. - (Emacs Info Variables): Fix for new Emacs init file behavior. - -2006-06-27 Richard Stallman - - * mini.texi (Minibuffer File): Minor cleanup. - -2006-06-25 Nick Roberts - - * frames.texi (XTerm Mouse): Rename to... - (Text-Only Mouse): ...this. Mention t-mouse-mode. - - * emacs.texi (Top): Use new node name. - -2006-06-24 Eli Zaretskii - - * emacs.texi (Top): Update the detailed menu according to changes in - msdog.texi. - - * msdog.texi (Windows Keyboard): New section. - (Windows Mouse): New section. - (Windows System Menu): Remove section (text merged with "Windows - Keyboard"). - (Windows Misc): New section. - - * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation. - - * msdog.texi (ls in Lisp): New section. - - * files.texi (Visiting): Document case-insensitive wildcard matching - under find-file-wildcards. - -2006-06-24 Andreas Seltenreich - - * gnus.texi (Summary Buffer Lines): Fix typo. - -2006-06-23 Carsten Dominik - - * org.texi (Embedded LaTeX): New chapter. - (Archiving): Section rewritten. - (Enhancing text): Some parts moved to the new chapter about LaTeX. - -2006-06-20 Bill Wohler - - Release MH-E manual version 8.0.1. - - * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for - release 8.0.1. - (Preface): Depend on GNU mailutils 1.0 and higher. - -2006-06-19 Katsumi Yamaoka - - * message.texi (News Headers): Update message-syntax-checks section. - -2006-06-19 Karl Berry - - * info.texi (Advanced): Mention C-q, especially with ?. - -2006-06-19 Carsten Dominik - - * org.texi (Publishing links): Document the `:link-validation-function' - property. - (Extensions and Hacking): New chapter, includes some sections of the - "Miscellaneous" chapter. - -2006-06-16 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Add description of mac-function-modifier. - Now Unicode keyboard layouts work. - -2006-06-10 Carsten Dominik - - * org.texi (Progress logging): New section. - -2006-06-10 Richard Stallman - - * mule.texi (Recognize Coding): Clarify previous change. - -2006-06-09 Kenichi Handa - - * mule.texi (Recognize Coding): Describe the convention of "CODING!" - notation. - -2006-06-07 Kevin Ryde - - * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main - manual for @ifnottex, but in emacs-extra for @iftex. - - * cmdargs.texi (General Variables): Fix smtpmail xref. - -2006-05-29 Stefan Monnier - - * viper.texi (Viper Specials): - * programs.texi (Comment Commands): - * gnus.texi (Example Setup): - * faq.texi (Backspace invokes help): - * dired-x.texi (Optional Installation Dired Jump): - * custom.texi (Specifying File Variables): - * calc.texi (Defining Simple Commands): Use ;; instead of ;;; to better - follow coding conventions. - -2006-05-18 Reiner Steib - - * gnus.texi (Saving Articles): Clarify gnus-summary-save-article-mail. - -2006-06-07 Nick Roberts - - * building.texi (Watch Expressions): Move node to end. - (GDB Graphical Interface): Move description of clicks in fringe... - (GDB commands in the Fringe): ...to here. New node. - -2006-06-06 Carsten Dominik - - * org.texi (ASCII export): Document indentation adaptation. - (Setting tags): Document mutually-exclusive tags. - -2006-06-05 Romain Francoise - - * url.texi (irc): Mention new funs `url-irc-rcirc' and `url-irc-erc'. - Fix typo. - - * gnus-faq.texi (Question 8.6): Update reference to the Gnus - channel (#gnus@irc.freenode.net). - Fix typos. Update copyright notice. - - * cc-mode.texi (Getting Started, Indentation Commands, Config Basics) - (Custom Filling and Breaking, Custom Braces, Syntactic Symbols) - (Line-Up Functions, Custom Macros): - * ediff.texi (Window and Frame Configuration) - (Highlighting Difference Regions, Highlighting Difference Regions): - * emacs-mime.texi (Display Customization): - * erc.texi (History): - * eshell.texi (Known problems): - * eudc.texi (Overview, BBDB): - * gnus.texi (NNTP, IMAP, Advanced Scoring Examples) - (The problem of spam, SpamOracle, Extending the Spam package) - (Conformity, Terminology): - * idlwave.texi (Routine Info, Routine Info) - (Class and Keyword Inheritance, Padding Operators) - (Breakpoints and Stepping, Electric Debug Mode) - (Examining Variables, Troubleshooting): - * org.texi (Creating timestamps): - * reftex.texi (Commands, Options, Changes): - * tramp.texi (Inline methods, Password caching) - (Auto-save and Backup, Issues): - * vip.texi (Files, Commands in Insert Mode): - * viper.texi (Emacs Preliminaries, States in Viper) - (Packages that Change Keymaps, Viper Specials, Groundwork): - * xresmini.texi (GTK resources): - Fix various typos. - -2006-06-05 Nick Roberts - - * building.texi (GDB Graphical Interface): Update bindings. - (Commands of GUD): Add gud-print. Remove gud-run. - Restate availability more generally. - -2006-06-03 Ted Zlatanov - - * mini.texi: Lots of cleanups. - -2006-06-01 Luc Teirlinck - - * misc.texi (Shell History Copying): Update descriptions of `C-c RET' - and Mouse-2. - -2006-06-01 Jan Dj,Ad(Brv - - * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open. - -2006-05-31 Michael Ernst - - * ediff.texi: Fix typos. - -2006-05-31 Richard Stallman - - * basic.texi (Moving Point): Fix previous change. - -2006-05-30 Carsten Dominik - - * org.texi: Small typo fixes. - -2006-05-29 Michael Albinus - - * tramp.texi (Frequently Asked Questions): Disable zsh zle. - -2006-05-29 Jan Dj,Ad(Brv - - * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus. - -2006-05-28 Ted Zlatanov - - * basic.texi: Many simplifications and improvements in wording. - -2006-05-27 Thien-Thi Nguyen - - * pcl-cvs.texi: Fix typos. - (Customization): Say "us". - -2006-05-26 Eli Zaretskii - - * org.texi: Remove bogus @setfilename. - -2006-05-26 Carsten Dominik - - * org.texi (ASCII export): Omit command name. - (HTML export): Add prefix to all lines in Local Variable example. - (Acknowledgments): Typeset names in italics. - -2006-05-26 Nick Roberts - - * anti.texi (Antinews): Create a node for gdb-ui. - -2006-05-24 Carsten Dominik - - * org.texi (Plain lists): Add new item navigation commands. - (External links): Document elisp and info links. - (Custom searches): New section. - (Publishing): New chapter. - (HTML export): Include a list of supported CSS classes. - (Setting tags): Describe the fast-tag-setting interface. - -2006-05-22 Reiner Steib - - * frames.texi (Menu Bars, Tool Bars): Add index entries. - -2006-05-20 Richard Stallman - - * dired.texi (Dired Navigation): dired-goto-file is now j. - -2006-05-20 Luc Teirlinck - - * dired-x.texi: ifinfo -> ifnottex. - -2006-05-20 Eli Zaretskii - - * mule.texi (Coding Systems): Mention the undecided-* coding systems - and their aliases. - - * msdog.texi (Windows Printing): Mention non-support of plain text - printing with some el-cheapo printers, and suggest a workaround. - -2006-05-20 Kevin Ryde - - * text.texi (TeX Print): tex-dvi-view-command has a default value, - remove the bit saying you must set it. - -2006-05-19 Luc Teirlinck - - * trouble.texi (Checklist): - * text.texi (Text, Auto Fill, Text Mode): - * search.texi (Nonincremental Search): - * rmail.texi (Rmail Labels): - * mule.texi (Input Methods, Multibyte Conversion): - * misc.texi (Gnus, Where to Look, PostScript): - * maintaining.texi (Create Tags Table): - * indent.texi (Indentation Commands): - * fixit.texi (Spelling): - * emacs.texi (Copying): - * custom.texi (Init File): ifinfo -> ifnottex. - -2006-05-18 Reiner Steib - - * gnus.texi (Saving Articles): Clarify gnus-summary-save-article-mail. - -2006-05-17 Richard Stallman - - * files.texi (Diff Mode): Mention C-x `. - -2006-05-08 Richard Stallman - - * custom.texi (Disabling): Textual cleanups. - -2006-05-12 Reiner Steib - - * message.texi (Interface): Add tool bar customization. - (MIME): Index and text additions for mml-attach. - (MIME): Describe mml-dnd-protocol-alist and - mml-dnd-attach-options. - - * gnus.texi (Oort Gnus): Reorder entries in sections. - Fix some entries. - (Starting Up): Add references to "Emacs for Heathens" and to - "Finding the News". Add user-full-name and user-mail-address. - (Group Buffer Format): Add tool bar customization and update. - (Summary Buffer): Add tool bar customization. - (Posting Styles): Add message-alternative-emails. - -2006-05-12 Glenn Morris - - * calendar.texi (Displaying the Diary, Format of Diary File): - Refer to diary-view-entries, diary-list-entries, - diary-show-all-entries rather than obsolete aliases. - -2006-05-12 Eli Zaretskii - - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * building.texi (Compilation Shell): - * buffers.texi (Several Buffers) [iftex]: Replace @xref's to - emacs-xtra with @inforef's. - - * files.texi (Visiting): Fix wording. - - * mule.texi (Coding Systems, Text Coding): More indexing. - Mention that C-x RET f can set eol conversion. - -2006-05-09 Michael Albinus - - * tramp.texi (Filename completion): Improve wording. - -2006-05-07 Jan Dj,Ad(Brv - - * xresmini.texi (GTK resources): Insert GTK description. - - * xresources.texi (GTK resources): metafont should be menufont. - -2006-05-07 Romain Francoise - - * faq.texi (Using regular expressions): Fix typo. - (Packages that do not come with Emacs): Fix capitalization. - (Replacing text across multiple files): Expand node to explain how - to use `dired-do-query-replace-regexp' in more detail, based on - suggestion by Eric Hanchrow . - -2006-05-06 Michael Albinus - - * mini.texi (Completion Options): - * tramp.texi (Filename completion): Completion of remote files' - method, user name and host name is active only in partial - completion mode. - -2006-05-06 Bill Wohler - - Release MH-E manual version 8.0. - - * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for - release 8.0. - -2006-05-06 Bill Wohler - - * mh-e.texi (MH-BOOK-HOME): Change from - http://www.ics.uci.edu/~mh/book/mh to - http://rand-mh.sourceforge.net/book/mh. - Replace .htm suffix with .html for MH book files. - (Using This Manual): Update key binding for getting relevant - chapter in Info from command key. - (Ranges): Fix itemx. - -2006-05-06 Eli Zaretskii - - * makefile.w32-in (emacs.dvi): - * Makefile.in (emacs.dvi): Add xresmini.texi. - - * xresmini.texi (Table of Resources): Remove xref to non-existent - node "LessTif Resources". - - * msdog.texi (Microsoft Windows): - * calendar.texi (Calendar/Diary, Displaying the Diary) - (Special Diary Entries, Importing Diary, Holidays): - * programs.texi (Program Modes): - * text.texi (Text): - * buffers.texi (Several Buffers): - * files.texi (Comparing Files): Fix cross-references to emacs-xtra. - -2006-05-06 Eli Zaretskii - - The following changes merge the emacs-xtra manual into the main - manual, but only for on-line version of the manual. - - * vc2-xtra.texi (Version Backups, Local Version Control) - (Making Snapshots, Change Logs and VC, Version Headers) - (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for - on-line manual. - - * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's - for on-line manual. - - * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse) - (MS-DOS Display, MS-DOS File Names, MS-DOS Printing) - (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's - for on-line manual. - - * fortran-xtra.texi (Fortran, Fortran Autofill) - (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's - for on-line manual. - - * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]: - Conditional xref's for on-line manual. - - * emerge-xtra.texi (Emerge, Overview of Emerge) - (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line - manual. - - * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - (../info/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - ($(infodir)/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * trouble.texi (Quitting): - * text.texi (Text): - * programs.texi (Program Modes): - * msdog.texi (Microsoft Windows): - * frames.texi (Frames): - * files.texi (Backup, Version Control, VC Concepts) - (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions) - (Registering, VC Status, VC Undo, Multi-User Branching) - (Comparing Files): - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by - conditional xref's, depending on @iftex/@ifnottex. - - * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for - "MS-DOS". @include msdog-xtra.texi. - - * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran". - [ifnottex]: @include fortran-xtra.texi. - - * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries - for vc-xtra.texi subsections. - (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it. - (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi. - - * sending.texi (Sending Mail): A @node line without explicit Prev, - Next, and Up links. - - * abbrevs.texi (Abbrevs): A @node line without explicit Prev, - Next, and Up links. - - * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode" - and its sections. @include picture-xtra.texi. - - * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for - "Emerge". - (List Tags) [ifnottex]: @include emerge-xtra.texi. - - * cal-xtra.texi (Daylight Savings): Remove this node: it is an - exact duplicate of its name-sake in calendar.texi. - - * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for - "Advanced Calendar/Diary Usage". - (Time Intervals) [ifnottex]: @include cal-xtra.texi. - - * dired.texi (Subdirectories in Dired) [ifnottex]: @include - dired-xtra.texi. - (Dired) [ifnottex]: Add menu entry for "Subdir Switches". - - * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi. - (Files) [ifnottex]: Add menu entry for Autorevert. - - * emacs-xtra.texi (Introduction): Reword to make consistent with - printed version only. - : Remove the body of all chapters and move them to the - new *-xtra.texi files. Use @raisesections and @lowersections to - convert sections to chapters etc. - - * msdog-xtra.texi: - * fortran-xtra.texi: - * vc-xtra.texi: - * vc1-xtra.texi: - * vc2-xtra.texi: - * emerge-xtra.texi: - * cal-xtra.texi: - * dired-xtra.texi: - * arevert-xtra.texi: New files, with text from respective chapters - of emacs-xtra.texi. Convert each @chapter into @section, @section - into @subsection, etc. - - * emacs-xtra.texi (MS-DOS): Renamed from "MS-DOG". All references - updated. - - * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft - Windows". All references updated. - -2006-05-06 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Mention input from Character Palette. - (Mac Font Specs): Fix typo. - -2006-05-05 Richard Stallman - - * files.texi (Diff Mode): Minor cleanup. - -2006-05-05 Karl Berry - - * texinfo.tex (\definetextfonsizexi, \definetextfonsizex): New cmds. - (\fonttextsize): New user-level command to change text font size. - * emacs.texi: Call @fonttextsize 10, inside @tex to avoid - errors from the current release of makeinfo (4.8). - * help.texi (Library Keywords): Change widest word in multitable - template from `emulations' to `convenience'. (Not sure if this is - related to the font change.) - -2006-05-05 Eli Zaretskii - - * files.texi (File Names): Add a footnote about limited support of - ~USER on MS-Windows. - - * cmdargs.texi (Initial Options): Add a footnote about limited - support of ~USER on MS-Windows. - -2006-05-03 Richard Stallman - - * files.texi (Diff Mode): Node moved here. - (Comparing Files): Delete what duplicates new node. - (Files): Put Diff Mode in menu. - - * misc.texi (Diff Mode): Moved to files.texi. - - * emacs.texi (Top): Update menu for Diff Mode. - - * trouble.texi (Emergency Escape): Simplify. - - * emacs.texi (Top): Minor clarification. - -2006-05-03 Teodor Zlatanov - - * commands.texi, entering.texi, screen.texi: Many simplifications. - -2006-05-03 Richard Stallman - - * commands.texi (Text Characters): Delete paragraph about unibyte - non-ASCII printing chars. - - * killing.texi (Killing): Say "graphical displays". - * display.texi: Say "graphical displays". - - * cmdargs.texi (Misc X): Say "graphical displays". - -2006-05-01 Richard Stallman - - * emacs.texi (Top): Add Diff Mode to menu. - -2006-05-01 Aaron S. Hawley - - * misc.texi (Diff Mode): New node. - -2006-05-01 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Now Carbon Emacs has ATSUI support. - (Mac Environment Variables): Shorten example line. - (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI. - -2006-05-01 Nick Roberts - - * building.texi (GUD Customization): Describe cases %d and %c. - Update description for %e. - -2006-04-30 Glenn Morris - - * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra. - -2006-04-29 Dan Nicolaescu - - * custom.texi (Examining): Update C-h v output example. - -2006-04-29 Kim F. Storm - - * building.texi (Grep Searching): Add lgrep and rgrep. - -2006-04-26 Reiner Steib - - * pgg.texi (Caching passphrase): Fix markup and typos. Simplify. - -2006-04-26 Sascha Wilde (tiny change) - - * pgg.texi (Caching passphrase): Add pgg-gpg-use-agent. - -2006-04-24 Bill Wohler - - * mh-e.texi (Getting Started): Make it more explicit that you need - to install MH. Add pointers to current MH implementations. - -2006-04-23 Richard Stallman - - * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi. - - * xresmini.texi: New file. - - * xresources.texi (Face Resources): Split table into font resources - and the rest. Combine similar attributes for brevity. - -2006-04-21 Bill Wohler - - Release MH-E manual version 7.94. - - * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for - release 7.94. - -2006-04-21 Carsten Dominik - - * org.texi: Many small fixes. - (Handling links): Rename from "Managing links". - -2006-04-21 Eli Zaretskii - - * emacs-xtra.texi (MS-DOS File Names): Remove section about - backslashes and case-insensitivity in file names (moved to the - main manual). - (MS-DOS Printing): Move most of the text to the main manual. - - * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing): - New nodes. - (Windows Processes, Windows System Menu): Add index entries and - fix wording. - -2006-04-20 Reiner Steib - - * gnus.texi (Spam Statistics Package): Fix typo in @pxref. - (Splitting mail using spam-stat): Fix @xref. - -2006-04-20 Chong Yidong - - * gnus.texi (Spam Package): Major revision of the text. - Previouly this node was "Filtering Spam Using The Spam ELisp Package". - -2006-04-20 Carsten Dominik - - * org.texi (Time stamps): Better explanation of the purpose of - different time stamps. - (Structure editing, Plain lists): More details on how new items - and headings are inserted. - -2006-04-18 J.D. Smith - - * misc.texi (Shell Ring): Add notes on saved input when - navigating off the end of the history list. - -2006-04-18 Chong Yidong - - * misc.texi (Shell Options): Correct default value of - comint-scroll-show-maximum-output. - -2006-04-18 Carsten Dominik - - * org.texi (Formula syntax): Fix link to Calc Manual. - -2006-04-17 Reiner Steib - - * gnus.texi (Emacsen): Don't support Emacs 20.7 and XEmacs 21.1. - -2006-04-17 Bill Wohler - - * mh-e.texi (Folders): Update mh-before-quit-hook and - mh-quit-hook example with code that removes the buffers rather - than just bury them. - -2006-04-18 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2006-04-17 Michael Albinus - - Sync with Tramp 2.0.53. - -2006-04-13 Carsten Dominik - - * org.texi (Updating settings): New section. - (Visibility cycling): Better names for the startup folding - options. - (Exporting): Completely restructured. - (The very busy C-c C-c key): New section. - (Summary of in-buffer settings): New section. - -2006-04-12 Richard Stallman - - * search.texi: Clean up previous change. - -2006-04-12 Eli Zaretskii - - * search.texi (Regexp Backslash, Regexp Replace): Add index - entries for ``back reference'' and mention the term itself in the - text. - -2006-04-11 Richard Stallman - - * custom.texi (Safe File Variables): - Document enable-local-variables = :safe. - -2006-04-11 Karl Berry - - * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands) - (Remote Repositories, Version Backups, Local Version Control) - (Snapshots, Making and Using Snapshots, Snapshot Caveats) - (Miscellaneous Commands and Features of VC, Change Logs and VC) - (Renaming VC Work Files and Master Files) - (Inserting Version Control Headers, Customizing VC, General Options) - (Options for RCS and SCCS, Options specific for CVS): Move all - these nodes to emacs-xtra.texi, for brevity. - * cmdargs.texi, files.texi: Change cross-references. - -2006-04-11 Reiner Steib - - * gnus.texi, gnus-faq.texi, message.texi: Gnus v5.10.8 is released. - -2006-04-10 Reiner Steib - - * gnus.texi (Misc Group Stuff, Summary Buffer, Article Keymap) - (Server Commands): Key `v' is reserved for users. - -2006-04-11 J.D. Smith - - * files.texi (Old Versions): Update description of vc-annotate's - use of color to indicate date ranges. - -2006-04-11 Carsten Dominik - - * org.texi (Link format): New section, emphasis on bracket links. - (External links): Document bracket links. - (FAQ): Expand to cover shell links and the new link format. - -2006-04-09 Kevin Ryde - - * org.texi (Formula syntax): Typo in node name of calc-eval xref. - - * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail, - put info and printed manual names the right way around. - -2006-04-09 Karl Berry - - * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to - emacs-xtra.texi, leaving only MS Windows information. - * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi, - * msdog.texi, mule.texi, trouble.texi: Change cross-references and - node names. - - * emacs.texi: Move @summarycontents and @contents to the beginning - of the file. - -2006-04-07 Reiner Steib - - * gnus.texi (Summary Buffer Lines): Add `*'. - -2006-04-07 Jochen K,A|(Bpper - - * gnus.texi (Group Parameters): - Mention gnus-permanently-visible-groups. - -2006-04-06 Katsumi Yamaoka - - * gnus.texi (Face): Fix typo. - -2006-04-05 Reiner Steib - - * gnus.texi (X-Face): Clarify. - (Face): Need Emacs with PNG support. - -2006-04-08 Kevin Ryde - - * text.texi (Fill Commands): fill-nobreak-predicate is now a hook. - -2006-04-07 Richard Stallman - - * programs.texi (Comments, Comment Commands, Options for Comments) - (Multi-Line Comments): "Align", not "indent". - (Basic Indent): C-j deletes trailing whitespace before the newline. - -2006-04-06 Richard Stallman - - * idlwave.texi: Delete the blocks "not suitable for inclusion with - Emacs". - - * programs.texi (Basic Indent): Clarify relationship of C-j to TAB. - -2006-04-06 Eli Zaretskii - - * killing.texi (Rectangles): Add index entry for marking a rectangle. - -2006-04-06 J.D. Smith - - * idlwave.texi: Updated for IDLWAVE version 6.0, factoring out - blocks not suitable for inclusion with Emacs using variable - PARTOFEMACS. - -2006-04-05 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * trouble.texi (Unasked-for Search): Node deleted. - (Lossage): Delete from menu. - -2006-04-04 Richard Stallman - - * trouble.texi: Various cleanups. - (Checklist): Don't bother saying how to snail a bug report. - (Emergency Escape): Much rewriting. - (After a Crash): Rename the core dump immediately. - (Total Frustration): Call it a psychotherapist. - (Bug Criteria): Avoid "illegal instruction". - (Sending Patches): We always put the contributor's name in. - - * misc.texi (Thumbnails): Minor correction. - -2006-04-04 Simon Josefsson - - * gnus.texi (Security): Improve. - -2006-04-03 Richard Stallman - - * misc.texi (Thumbnails): Minor cleanup. - -2006-04-02 Karl Berry - - * sending.texi (Mail Sending): pxref to Top needs five args. - - * texinfo.tex: Update to current version (2006-03-21.13). - -2006-04-02 Bill Wohler - - * mh-e.texi (Getting Started, Junk, Bug Reports) - (MH FAQ and Support): Fix URLs. - -2006-03-31 Romain Francoise - - * gnus.texi (Virtual Groups): `nnvirtual-always-rescan' defaults - to t, not nil (and has for the past eight years). - -2006-03-31 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Cleanup. - - * dired.texi: Many cleanups. - (Dired Deletion): Describe dired-recursive-deletes. - (Operating on Files): dired-create-directory moved. - (Misc Dired Features): Move to here. - (Tumme): Node moved to misc.texi. - - * custom.texi: Many cleanups. - (Minor Modes): Don't mention ISO Accents Mode. - (Examining): Update C-h v output example. - (Hooks): Add index and xref for add-hook. - (Locals): Delete list of vars that are always per-buffer. Rearrange. - (Local Keymaps): Don't mention lisp-mode-map, c-mode-map. - - * misc.texi: Many cleanups. - (beginning): Add to summary of topics. - (Shell): Put eshell xref at the end. Remove eshell from table. - (Thumbnails): New node. - -2006-03-31 Reiner Steib - - * message.texi, gnus.texi: Bump version to 5.11. - -2006-03-29 Reiner Steib - - * gnus.texi (Top): Add comment about version line. - - * message.texi (Top): Ditto. Change to take named versions into - account. - -2006-03-28 Reiner Steib - - * gnus.texi (Posting Styles): Add x-face-file to example. - (X-Face): Refer to posting styles. - - * gnus-faq.texi ([5.8]): Add x-face-file. - ([8.4]): Add links to gmane.emacs.gnus.user and - gmane.emacs.gnus.general. - -2006-03-28 Eli Zaretskii - - * files.texi (File Name Cache): Make it clear that the cache is - not persistent. - -2006-03-27 Reiner Steib - - * gnus-faq.texi: Use .invalid. - ([5.4]): Fix gnus-posting-styles example. - -2006-03-27 Romain Francoise - - * faq.texi (Emacs/W3): Rename from `w3-mode'. Mention that - Emacs/W3 needs a new maintainer. - (Ispell): Update author and version info. - (Mailcrypt): Mention PGG. - (New in Emacs 22): Add PGG to the list of new packages. - Include minor changes from "Ramprasad B" - updating dead URLs. - -2006-03-25 Karl Berry - - * ada-mode.texi, autotype.texi, calc.texi, cc-mode.texi, cl.texi, - * dired-x.texi, ebrowse.texi, ediff.texi, emacs-mime.texi, - * emacs-xtra.texi, emacs.texi, erc.texi, eshell.texi, eudc.texi, - * faq.texi, forms.texi, gnu.texi, gnus.texi, idlwave.texi, - * info.texi, message.texi, mh-e.texi, pcl-cvs.texi, pgg.texi, - * rcirc.texi, reftex.texi, sc.texi, ses.texi, sieve.texi, - * speedbar.texi, url.texi, vip.texi, viper.texi, widget.texi, - * woman.texi: (1) use @copyright{} instead of (C) in typeset text; - (2) do not indent copyright year list (or anything else). - -2006-03-21 Bill Wohler - - * mh-e.texi (Folders): Various edits. - -2006-03-20 Romain Francoise - - * gnus.texi (Mail Folders): Grammar fix. - -2006-03-21 Juanma Barranquero - - * files.texi (VC Dired Mode): Remove misplaced brackets. - -2006-03-21 Andre Spiegel - - * files.texi: Various updates and clarifications in the VC chapter. - -2006-03-19 Luc Teirlinck - - * help.texi (Help Mode): Document "C-c C-c". - -2006-03-19 Bill Wohler - - * mh-e.texi (Replying): Document Mail-Followup-To. - Change manually-formatted table to multitable. Add debugging info. - Move description of mh-reply-default-reply-to into paragraph - that describes its values. - -2006-03-17 Bill Wohler - - * mh-e.texi: Use smallexample and smalllisp consistenly. - (Sending Mail Tour): Update method of entering - addresses and subject. - (Sending Mail Tour, Reading Mail Tour, Processing Mail Tour) - (Adding Attachments, Searching): Update screenshots for Emacs 22. - -2006-03-16 Luc Teirlinck - - * emacs-xtra.texi (Top): Avoid ugly continuation line in - menu in the standalone Info reader. - -2006-03-15 Chong Yidong - - * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters, - moved here from Emacs manual. - - * programs.texi (Fortran): Section moved to emacs-xtra. - (Program Modes): Xref to Fortran in emacs-xtra. - - * maintaining.texi (Emerge): Move to emacs-xtra. - * files.texi (Comparing Files): Xref to Emerge in emacs-xtra. - - * picture.texi: File deleted. - * Makefile.in: - * makefile.w32-in: Remove picture.texi. - - * text.texi (Text): Xref to Picture Mode in emacs-xtra. - * abbrevs.texi (Abbrevs): - * sending.texi (Sending Mail): Picture node removed. - - * emacs.texi (Top): Update node listings. - -2006-03-15 Carsten Dominik - - * org.texi: Version number change only. - -2006-03-14 Bill Wohler - - * mh-e.texi: Add index entries around each paragraph rather than - depend on entries from beginning of node. Doing so ensures that - index entries are less likely to be forgotten if text is cut and - pasted, and are necessary anyway if the references are on a - separate page. It seems that makeinfo is now (v. 4.8) only - producing one index entry per node, so there is no longer any - excuse not to. Use subheading instead of heading. The incorrect - use of heading produced very large fonts in Info--as large as the - main heading. - (From Bill Wohler): MH-E never did appear in Emacs 21--MH-E - versions 6 and 7 appeared *around* the time of these Emacs releases. - -2006-03-13 Carsten Dominik - - * org.texi (Clean view): Document new startup options. - -2006-03-12 Richard Stallman - - * calendar.texi: Various cleanups. - -2006-03-11 Bill Wohler - - * mh-e.texi (Preface, More About MH-E, Options, HTML, Folders) - (Composing, Scan Line Formats): Fix @refs. - (Getting Started): Define MH profile and MH profile components. - (Incorporating Mail, Reading Mail, Viewing, Printing) - (Sending Mail, Forwarding, Editing Drafts, Inserting Letter) - (Signature, Aliases, Scan Line Formats): Use @code instead of @samp - for string constants. - (Tool Bar): Remove spurious quote. - (Junk): Use ``...'' instead of "...". - (Scan Line Formats): Replace @samp with @kbd. - -2006-03-11 Luc Teirlinck - - * search.texi (Regexps): Use @samp for regexp that is not in Lisp - syntax. - -2006-03-10 Katsumi Yamaoka - - * gnus.texi (NoCeM): Mention gnus-use-nocem can also be a number. - -2006-03-10 Reiner Steib - - * gnus.texi (Fancy Mail Splitting): Improve sentences so as to be - easy to understand. - -2006-03-09 Katsumi Yamaoka - - * gnus.texi: Markup fix. - (Fancy Mail Splitting): Specify new feature. - -2006-03-08 Katsumi Yamaoka - - * gnus.texi (Fancy Mail Splitting): Improve descriptions about - partial-words matching. - -2006-03-07 Reiner Steib - - * emacs-mime.texi (Display Customization): Reword image/.* stuff. - - * gnus.texi (Oort Gnus): Add note about `gnus-load'. - (MIME Commands): Fix mm-discouraged-alternatives. - -2006-03-08 Luc Teirlinck - - * search.texi (Regexps): More accurately describe which characters - are special in which situations. Recommend _not_ to quote `]' or - `-' when they are not special. - -2006-03-07 Carsten Dominik - - * org.texi: Version number change only. - -2006-03-06 Bill Wohler - - * mh-e.texi: Move from SourceForge repository to Savannah. - This is version 7.93, which is a total rewrite from the previous - edition 1.3 for MH-E version 5.0.2, and corresponds to MH-E - version 7.93. - -2006-03-03 Reiner Steib - - * gnus.texi (Oort Gnus): Add `mm-fill-flowed'. - -2006-03-01 Carsten Dominik - - * org.texi (Interaction): Add item about `org-mouse.el' by - Piotr Zielinski. - (Managing links): Document that also mouse-1 can be used to - activate a link. - (Headlines, FAQ): Add entry about hiding leading stars. - (Miscellaneous): Resort the sections in this chapter to a more - logical sequence. - -2006-02-28 Andre Spiegel - - * files.texi (Old Versions): Clarify operation of C-x v =. - -2006-02-27 Simon Josefsson - - * emacs-mime.texi (Flowed text): Add mm-fill-flowed. (Sync - 2004-01-27 from the trunk). - -2006-02-24 Alan Mackenzie - - * cc-mode.texi: Rename c-hungry-backspace to - c-hungry-delete-backwards, at the request of RMS. Leave the old - name as an alias. - -2006-02-24 Alan Mackenzie - - * cc-mode.texi: Correct the definition of c-beginning-of-defun, to - include the function header within the defun. - -2006-02-24 Alan Mackenzie - - * cc-mode.texi: Correct two typos. - -2006-02-24 Alan Mackenzie - - * cc-mode.texi (Comment Commands): State that C-u M-; kills any - existing comment. - (Electric Keys): Add a justification for electric indentation. - (Hungry WS Deletion): Clear up the names and complications of the - BACKSPACE and DELETE keys. - -2006-02-23 Juri Linkov - - * faq.texi (Common requests): Move `Turning on auto-fill by - default' after `Wrapping words automatically'. Move `Working with - unprintable characters' before `Searching for/replacing newlines'. - Move `Replacing highlighted text' after `Highlighting a region'. - Merge `Repeating commands' and `Repeating a command as many times - as possible' into the former. - (Packages that do not come with Emacs): Add refs to Gmane and - etc/MORE.STUFF. - -2006-02-23 Juri Linkov - - * faq.texi (Newsgroup archives): Update URLs of GNU mail archives. - (Reporting bugs): Suggest using `M-x report-emacs-bug'. - Add xref to `(emacs)Reporting Bugs'. - (Getting a printed manual): Add URL to other formats of the manual. - (Common requests): Fix menu. - (Highlighting a region): Remove ref to `Turning on syntax highlighting'. - (Horizontal scrolling): Mention `truncate-partial-width-windows'. - (Inserting text at the beginning of each line): Add pxref to - `Changing the included text prefix'. - (Forcing the cursor to remain in the same column): Mention `track-eol' - and `set-goal-column'. Add pxref to `(emacs)Moving Point'. - (Replacing text across multiple files): Add keybinding `Q' for - `dired-do-query-replace'. - -2006-02-22 Carsten Dominik - - * reftex.texi: Version number and date change only. - - * org.texi (Internal Links): Rewrite to cover the modified - linking system. - -2006-02-21 Nick Roberts - - * building.texi (Watch Expressions): Update and describe - gdb-speedbar-auto-raise. - -2006-02-19 Richard M. Stallman - - * emacs.texi: Use @smallbook. - (Top): Update ref to Emacs paper, delete ref to Cookbook. - Update subnode menu. - - * building.texi (Lisp Interaction): Minor addition. - -2006-02-18 Nick Roberts - - * building.texi (Watch Expressions): Update and be more precise. - -2006-02-17 Eli Zaretskii - - * faq.texi: Remove the coding cookie, it's not needed anymore. - -2006-02-15 Francesco Potort,Al(B - - * maintaining.texi (Create Tags Table): Explain why the - exception when etags writes to files under the /dev tree. - -2006-02-14 Richard M. Stallman - - * custom.texi (Safe File Variables): Lots of clarification. - Renamed from Unsafe File Variables. - -2006-02-14 Chong Yidong - - * custom.texi (Unsafe File Variables): File variable confirmation - assumed denied in batch mode. - -2006-02-14 Richard M. Stallman - - * building.texi (GDB User Interface Layout): Don't say `inferior' - for program being debugged. - -2006-02-15 Nick Roberts - - * building.texi (GDB Graphical Interface): - Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer. - -2006-02-13 Chong Yidong - - * custom.texi (Specifying File Variables, Unsafe File Variables): - New nodes, split from File Variables. Document new file local - variable behavior. - -2006-02-13 YAMAMOTO Mitsuharu - - * display.texi (Standard Faces): - * faq.texi (Colors on a TTY): - * files.texi (Visiting): - * frames.texi (Clipboard): - * glossary.texi (Glossary) : - * xresources.texi (X Resources): Mention Mac OS port. - -2006-02-12 Karl Berry - - * faq.texi (Emacs for Atari ST): Use Sch@"auble instead of the - 8-bit accented a. - -2006-02-12 Richard M. Stallman - - * building.texi (Building): Clarify topic in intro. - - * maintaining.texi (Maintaining): Change title; clarify topic. - Delete duplicate index entries. - - * building.texi (Other GDB User Interface Buffers): Clarifications. - - * text.texi (Cell Commands): Clarifications. - - * programs.texi (Defuns): Delete duplicate explanation of - left-margin paren convention. - (Hungry Delete): Minor cleanup. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): More tumme documentation. - -2006-02-11 Alan Mackenzie - - * programs.texi ("Hungry Delete"): Correct the appellation of the - backspace and delete keys to @kbd{DEL} and @kbd{DELETE}. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): Fix small bug. - -2006-02-10 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Rename "fontset-mac" to - "fontset-standard". - -2006-02-09 Reiner Steib - - * gnus.texi (Gnus Versions): Add history beyond start of Oort. - -2006-02-09 Mathias Dahl - - * dired.texi (Tumme): Basic documentation for Tumme added. - -2006-02-08 Romain Francoise - - * faq.texi (Top): Remove paragraph about the FAQ being a - transitional document, etc. - (Searching for/replacing newlines): New node. - (Yanking text in isearch): New node. - (Inserting text at the beginning of each line): Rename and make - more general, mention `M-;' in Message mode. - -2006-02-07 Luc Teirlinck - - * mule.texi (International): - * programs.texi (Basic Indent): Fix typos. - - * faq.texi (Meta key does not work in xterm) - (Emacs does not display 8-bit characters) - (Inputting eight-bit characters): - * custom.texi (Minor Modes): - * display.texi (Text Display): - * commands.texi (Text Characters): Update xrefs. - -2006-02-07 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - Update info on old Emacs papers. - (Intro): "Graphical display", not window system. - - * xresources.texi (GTK styles): Minor clarifications. - - * trouble.texi: "Graphical display", not window system. - (Stuck Recursive): Minor clarification. - - * text.texi: Minor clarifications. - (Sentences): Explain why two-space convention is better. - Explain sentence-end-without-period here. - (Fill Commands): Not here. - (Refill): Node moved down. - (Filling): Update menu. - (Table Creation, Cell Justification, Column Commands): Clarify. - - * sending.texi: Minor clarifications. - - * search.texi (Regexp Backslash): Clarification. - - * rmail.texi: Minor cleanups. - (Rmail): Delete digression about `rmail-mode'. - (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list. - (Rmail Files): Mention C-u M-x rmail. - (Rmail Reply): Mention References. - (Rmail Display): Mention rmail-nonignored-headers. - - * programs.texi: Minor cleanups. - (Comment Commands): Mention momentary Transient Mark mode. - (Matching): Be more specific about customizing show-paren-mode. - (Info Lookup): Don't list the modes that support C-h S. - Just say what it does in an unsupported mode. - (Man Page): Delete excessive info on customizing woman. - (Motion in C): Don't mention c-for/backward-into-nomenclature. - - * abbrevs.texi: Minor clarifications. - (Dabbrev Customization): Talk about "dynamic abbrev expansion", - not "dynamic abbrevs" as if they were a kind of abbrev. - - * picture.texi (Picture): Minor cleanup. - - * mule.texi (Communication Coding): Say "other applications". - (Fontsets): Not specific to X. Add xref to X Resources. - (Unibyte Mode): Rename from Single-Byte Character Support. - "Graphical display", not window system. - (International): Update menu. - - * maintaining.texi (Format of ChangeLog): - New node, split out from ChangeLog. - (ChangeLog): Clarifications in the remaining text. - (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. - (Find Tag): Add @w. - (Tags Search): Explain tag table order here. Simplify grep ref. - (List Tags): tags-tag-face is a variable, not a face. - (Emerge): Cleanups. - - * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity. - (Keyboard Macros): Avoid "the user". - - * killing.texi: "Graphical display", not window system. - - * help.texi (Help Echo): "Graphical display", not window system. - - * glossary.texi: Say "you", not "the user". Say "graphical display". - - * frames.texi: Minor cleanups. "Graphical display", not window system. - - * files.texi (Visiting): Make drag-and-drop not X-specific. - - * custom.texi: Minor cleanups. "Graphical display", not window system. - - * cmdargs.texi: Minor cleanups. - - * building.texi (Compilation): Move and split kill-compilation para. - Add para about multiple compilers. - (Compilation Mode): Commands also available in grep mode and others. - Mention C-u C-x ` more tutorially. Clarify C-x `. - (Compilation Shell): Clarify. Put Bash example first. - (Grep Searching): Minor cleanups; add @w. - (Debuggers): Minor cleanups. - (Starting GUD): Make GDB xgraphical mode issue clearer. - (Debugger Operation): Lots of clarifications including - GDB tooltip side-effect issue. - (Commands of GUD): Clarify. - (GUD Customization): Add bashdb-mode-hook. - (GDB Graphical Interface): Rewrite for clarity. - (GDB User Interface Layout): Rewrite for clarity. - (Stack Buffer, Watch Expressions): Likewise. - (Other GDB User Interface Buffers): Cleanups. - (Lisp Libraries, External Lisp): Cleanup. - - * basic.texi (Position Info): "Graphical displays", rather than - window systems. - - * anti.texi: Minor cleanup. - -2006-02-06 Romain Francoise - - * faq.texi (VM): VM now at version 7.19. - Set myself as maintainer of this file. - -2006-02-04 Michael Olson - - * erc.texi (History): Note that ERC is now included with Emacs. - -2006-02-03 Eli Zaretskii - - * custom.texi (Init File, Find Init): Add cross-references to - where $HOME is described. - -2006-02-01 Luc Teirlinck - - * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it - is not inside the @table. - - * emacs.texi (Top): Correct node name. - - * files.texi (File Names): Fix @xref. - (Reverting): Fix typo. - - * mule.texi (International): Correct node name. - - * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table. - -2006-02-01 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - - * mule.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Text Coding): Rename from Specify Coding. - (Communication Coding, File Name Coding, Terminal Coding): - New nodes split out from Text Coding. - - * kmacro.texi: Minor clarifications. - (Keyboard Macro Ring): Comment out some excessive commands. - (Basic Keyboard Macro): Split up the table, putting part in each node. - - * major.texi: Minor clarifications. - - * misc.texi (Single Shell, Interactive Shell): Fix xrefs. - - * windows.texi: Minor clarifications. - (Change Window): Don't describe mode-line mouse cmds here. - Add xref to Mode Line Mouse. - - * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs. - - * macos.texi (Mac International): Fix xref. - - * indent.texi: Minor clarifications. - - * frames.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Frame Parameters): Don't mention commands like - set-foreground-color. Just say to customize a face. - (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual. - - * files.texi: Minor clarifications. - (Numbered Backups): New node, split out from Backup Names. - - * display.texi (Font Lock): C mode no longer depends on (-in-col-0. - - * cmdargs.texi (General Variables): Fix xref. - - * buffers.texi: Minor clarifications. - -2006-01-31 Romain Francoise - - * message.texi (Message Headers): Explain what - `message-alternative-emails' does in more detail. - Update copyright year. - -2006-01-31 Richard M. Stallman - - * display.texi (Scrolling, Horizontal Scrolling, Follow Mode): - Nodes moved to top. - - * display.texi: Minor clarifications. - (Display): Rearrange menu. - (Standard Faces): Mention query-replace face. - (Faces): Simplify. - (Font Lock): Simplify face customization info. - (Highlight Changes): Node merged into Highlight Interactively. - (Highlight Interactively): Much rewriting and cleanup. - (Optional Mode Line): Narrowed line number not good for goto-line. - Simplify face customization advice. - (Text Display): Mention use of escape-glyph face. - Move ctl-arrow and tab-width here. - (Display Custom): Move no-redraw-on-reenter to end of node. - - * search.texi: Minor clarifications. - (Isearch Scroll): Simplify. - (Other Repeating Search): Document multi-occur-in-matching-buffers. - - * regs.texi (Registers): Mention bookmarks here. - - * mark.texi: Minor clarifications. - (Selective Undo): Node deleted. - - * m-x.texi: Minor clarifications. - - * killing.texi: Minor clarifications. - Refer to "graphical" terminals, rather than window systems. - - * help.texi: Clarifications. - (Help): Don't describe C-h F and C-h K here. - (Key Help): Describe C-h K here. - (Name Help): Mention Emacs Lisp Intro. - Describe C-h F here. - (Misc Help): Mention C-h F and C-h K only briefly. - - * fixit.texi (Undo): New node, mostly copied from basic.texi. - Selective undo text merged in. - (Spelling): Mention Aspell along with Ispell. - - * emacs.texi (Top): Update subnode menus. - - * basic.texi (Basic Undo): Rename from Undo. Most of text - moved to new Undo node. - -2006-01-30 Juanma Barranquero - - * makefile.w32-in (clean): Add newsticker, sieve, pgg, erc and rcirc. - -2006-01-29 Chong Yidong - - * basic.texi (Continuation Lines, Inserting Text): - Mention longlines mode. - -2006-01-29 Richard M. Stallman - - * screen.texi: Minor cleaups. - (Screen): Clean up the intro paragraphs. - (Mode Line): Lots of rewriting. Handle frame-name better. - eol-mnemonic-... vars moved out. - - * emacs.texi (Top): Change menu item for MS-DOS node. - Update subnode menu. - - * msdog.texi (MS-DOS): Rewrite intro to explain how this - chapter relates to Windows. Title changed. - - * mini.texi: Minor cleanups. - - * mark.texi (Selective Undo): New node, text moved from basic.texi. - (Mark): Put it in the menu. - - * entering.texi: Minor cleanups. - - * emacs.texi (Top): Add xref to Mac chapter; explain Windows better. - (Intro): Refer to "graphical" terminals, rather than X. - - * display.texi (Display Custom): Add xref to Variables. - (Optional Mode Line): eol-mnemonic-... vars moved here. - - * commands.texi: Minor cleanups. Refer to "graphical" terminals, - rather than X. - - * cc-mode.texi (Indentation Commands): Inserts newline, not "linefeed". - - * basic.texi: Minor cleanups. - (Undo): selective-undo moved. - -2006-01-29 Michael Olson - - * makefile.w32-in ($(infodir)/erc, erc.dvi): New targets. - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add ERC. - - * faq.texi (New in Emacs 22): Mention ERC. - -2006-01-28 Luc Teirlinck - - * rcirc.texi: Capitalize dir entry for consistency with the entry - in info/dir and other entries in the Emacs category. - Fix typos. Delete trailing whitespace. - -2006-01-28 Bj,Av(Brn Lindstr,Av(Bm - - * rcirc.texi: Some @cindex changes, some changes from @kbd to @key. - -2006-01-27 Eli Zaretskii - - * makefile.w32-in ($(infodir)/rcirc, rcirc.dvi): New targets. - (INFO_TARGETS, DVI_TARGETS): Add rcirc. - - * Makefile.in (../info/rcirc, rcirc.dvi): New targets. - (INFO_TARGETS, DVI_TARGETS): Add rcirc. - -2006-01-27 Alex Schroeder - - * rcirc.texi: New file. - -2006-01-25 Luc Teirlinck - - * anti.texi (Antinews): Various corrections and additions. - -2006-01-23 Juri Linkov - - * custom.texi (Easy Customization, Customization Groups) - (Browsing Custom): Mention links along with buttons. - - * widget.texi (User Interface): Add S-TAB for widget-backward. - -2006-01-22 Michael Albinus - - Sync with Tramp 2.0.52. - - * tramp.texi (Frequently Asked Questions): Remove Ange-FTP item. - Add Tramp disabling item. New item for common connection problems. - (various): Apply "ftp" as method for the download URL. - (Bug Reports): Refer to FAQ for common problems. - -2006-01-21 Eli Zaretskii - - * widget.texi (User Interface): Use @key for TAB. - - * text.texi (TeX Print): Use @key for TAB. - - * ses.texi (Formulas, Printer functions): Use @key for TAB. - - * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB. - - * ebrowse.texi (Switching to Tree, Symbol Completion): Use @key - for TAB. - - * cc-mode.texi (Indentation Calculation): Use @key for TAB. - -2006-01-15 Sven Joachim (tiny change) - - * files.texi (File Aliases): Don't claim that usually separate - buffers are created for two file names that name the same data. - Mention additional situations where different names mean the same - file on disk. - -2006-01-19 Richard M. Stallman - - * killing.texi (Deletion): Upcase @key argument. - - * custom.texi (Custom Themes): Minor cleanup. - - * programs.texi (Hungry Delete): Upcase @key argument. - -2006-01-16 Katsumi Yamaoka - - * gnus.texi: Update copyright. - -2006-01-16 Juri Linkov - - * display.texi (Standard Faces): Add `mode-line-buffer-id'. - Move `mode-line-highlight' before `mode-line-buffer-id'. - -2006-01-13 Katsumi Yamaoka - - * gnus.texi (Article Washing): Additions. - -2006-01-08 Alex Schroeder - - * pgg.texi (Caching passphrase): Rewording. - -2006-01-14 Richard M. Stallman - - * basic.texi (Inserting Text): Minor cleanup. - -2006-01-13 Carsten Dominik - - * org.texi (Agenda commands): Document tags command. - -2006-01-11 Luc Teirlinck - - * custom.texi (Changing a Variable, Face Customization): - Update for changes in Custom menus. - -2006-01-10 Katsumi Yamaoka - - * gnus.texi (RSS): Document nnrss-wash-html-in-text-plain-parts. - -2006-01-06 Katsumi Yamaoka - - * gnus.texi (RSS): Addition. - -2005-12-22 Katsumi Yamaoka - - * gnus.texi (Summary Post Commands): Fix function bound to `S O p'. - -2005-12-19 Katsumi Yamaoka - - * emacs-mime.texi (Display Customization): Add setting example to - mm-discouraged-alternatives. - -2006-01-09 Stefan Monnier - - * flymake.texi (Obtaining Flymake): Remove chapter since Emacs's - version is the canonical version. - -2006-01-08 Alex Schroeder - - * pgg.texi (Caching passphrase): Rewording. - -2006-01-06 Eli Zaretskii - - * flymake.texi (Obtaining Flymake): Update Flymake's CVS - repository URL. - -2006-01-06 Carsten Dominik - - * org.texi: Removed the accidentally re-added empty line in the - direntry. - -2006-01-05 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Undo last change. - -2006-01-05 Carsten Dominik - - * org.texi (Agenda Views): Chapter reorganized. - -2006-01-02 Chong Yidong - - * custom.texi (Custom Themes): Describe the new - customize-create-theme interface. - -2005-12-30 Juri Linkov - - * basic.texi (Position Info): Update example. - -2005-12-29 Romain Francoise - - * faq.texi (Using Customize): New node. - -2005-12-28 Luc Teirlinck - - * org.texi: Remove blank line in @direntry. It is non-standard - and recursively produces blank lines all over the dir file (when - using Texinfo 4.8). - -2005-12-27 Jan Dj,Ad(Brv - - * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files. - -2005-12-24 Chong Yidong - - * custom.texi (Custom Themes): `load-theme' always loads. - -2005-12-23 Juri Linkov - - * display.texi (Highlight Interactively): Use double space to - separate sentences. Replace C-p with M-p, and C-n with M-n. - -2005-12-22 Richard M. Stallman - - * custom.texi (Easy Customization and subnodes): - Replace "active field" with "button". - Use "user option" only for variables. - Use "setting" for variable-or-face. - -2005-12-22 Luc Teirlinck - - * buffers.texi (Select Buffer): Change order in table to make - "Similar" refer to the correct item. - (Indirect Buffers): Minor rewording. - -2005-12-21 Luc Teirlinck - - * widget.texi (atoms): Delete obsolete remark about `file' widget. - -2005-12-20 Juri Linkov - - * files.texi (VC Status): Put P and N near p and n. - -2005-12-20 Carsten Dominik - - * org.texi (Tags): Boolean logic documented. - (Agenda Views): Document custom commands. - -2005-12-20 David Kastrup - - * faq.texi (AUCTeX): Update version and mailing list info. - -2005-12-19 Richard M. Stallman - - * programs.texi (Electric C): Delete the info about newline control. - (Other C Commands): Minor cleanup. - (Left Margin Paren): Minor cleanup. - -2005-12-19 Luc Teirlinck - - * custom.texi (Easy Customization): Add "Browsing Custom" to menu. - (Customization Groups): Delete text moved to "Browsing Custom". - (Browsing Custom): New node. - (Specific Customization): Clarify which commands only work for - loaded options. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Shorten text of previous change. - -2005-12-18 Aaron S. Hawley - - * files.texi (VC Status): Document log-view mode. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Mention that you can turn off tool bars - permanently via the customize interface. - -2005-12-17 Katsumi Yamaoka - - * gnus.texi (MIME Commands): Mention addition of - multipart/alternative to gnus-buttonized-mime-types and add xref - to mm-discouraged-alternatives. - - * emacs-mime.texi (Display Customization): Mention addition of - "image/.*" and add xref to gnus-buttonized-mime-types in the - mm-discouraged-alternatives section. - -2005-12-16 Carsten Dominik - - * org.texi (Tags): New section. - (Agenda Views): Chapter reorganized. - -2005-12-16 Ralf Angeli - - * killing.texi (Killing by Lines): Document `kill-whole-line' - function. - -2005-12-16 Eli Zaretskii - - * org.texi (Internal Links): Add a missing comma after an @xref. - -2005-12-16 L$,1 q(Brentey K,Aa(Broly - - * buffers.texi (Select Buffer): Change `prev-buffer' to - `previous-buffer'. Indicate that these functions use a frame - local buffer list. - -2005-12-14 Chong Yidong - - * faq.texi (Filling paragraphs with a single space): No need to - change sentence-end now. - -2005-12-13 Romain Francoise - - * faq.texi (Scrolling only one line): Use `scroll-conservatively'. - -2005-12-12 Jay Belanger - - * faq.texi (Calc): Update version number. - -2005-12-12 Carsten Dominik - - * org.texi (Progress Logging): New section. - -2005-12-12 Richard M. Stallman - - * custom.texi (Easy Customization): Change menu comment. - (Prefix Keymaps): Fix spelling of Control-X-prefix. - - * help.texi (Apropos): Rewrite. Talk about "apropos patterns". - (Help): Among the Apropos commands, describe only C-h a here. - -2005-12-11 Richard M. Stallman - - * programs.texi (Options for Comments): Comment-end starts with space. - - * glossary.texi (Glossary): Minor cleanup. - - * files.texi (Old Versions): Use @table. - -2005-12-10 Romain Francoise - - Update the Emacs FAQ for the 22.1 release. - - * faq.texi: Set VER to `22.1'. - (Basic editing): Explain how to use localized versions of the - Tutorial. Mention that `C-h r' displays the manual. Delete - obsolete WWW link to an Emacs 18 tutorial. - (Getting a printed manual): Point to the new locations of the - manuals on the GNU Web site. - (Emacs Lisp documentation): Explain that the Emacs Lisp manual is - available via Info (it was previously distributed separately). - (Installing Texinfo documentation): The latest version of Texinfo - is 4.8, not 4.0. - (Informational files for Emacs): COPYING is the GNU General Public - License, not the Emacs General Public License. - (Informational files for Emacs): Delete obsolete link to the - GNUinfo pages as they have been removed from the GNU Web site. - (New in Emacs 22): New node. - (Setting up a customization file): Say that most packages support - Customize nowadays. - (Colors on a TTY): Delete reference to instructions on how to - enable syntax highlighting, it is now enabled by default. - (Turning on abbrevs by default): Emacs now reads the abbrevs file - at startup automatically. - (Controlling case sensitivity): Mention `M-c' in isearch. - (Using an already running Emacs process): Emacs now creates the - socket in `/tmp/emacsUID'. Fix typos. Change default location of - gnuserv. As emacsclient can now run Lisp code as well, delete a - sentence praising gnuserv for that. Simplify description of how - the client/server operation works. - (Compiler error messages): Delete obsolete text (compile.el has - been rewritten). - (Indenting switch statements): Fix typo. - (Matching parentheses): Simplify setup instructions, mention the - menu bar item in the Options menu. - (Repeating a command as many times as possible): Mention `C-x e'. - (Going to a line by number): Mention new keymap and bindings - `M-g M-g', `M-g M-p' and `M-g M-n'. - (Turning on syntax highlighting): Now on by default. Simplify. - (Replacing highlighted text): Use `1', not `t'. - (Problems with very large files): The maximum size is now 256MB on - 32-bit machines. - (^M in the shell buffer): Mention `comint-process-echoes'. - (Emacs for Apple computers): Emacs 22 has native support for Mac - OS X. - (Translating names to IP addresses): Delete node. - (Binding keys to commands): Fix typo. - (SPC no longer completes file names): New node. - (MIME with Emacs mail packages): Delete section about the Emacs - MIME FAQ (it's not reachable anymore). - -2005-12-10 David Koppelman - - * display.texi (Highlight Interactively): Include - global-hi-lock-mode. Add miscellaneous details and elaborations. - -2005-12-09 Richard M. Stallman - - * display.texi (Font Lock): Delete the Global FL menu item. - -2005-12-09 Luc Teirlinck - - * custom.texi (Minibuffer Maps): Mention the maps for file name - completion. - -2005-12-09 Kim F. Storm - - * killing.texi (CUA Bindings): Describe how to use C-x and C-c as - prefix keys even when mark is active. Decribe that RET moves - cursor to next corner in rectangle; clarify insert around rectangle. - -2005-12-08 Alan Mackenzie - - * cc-mode.texi: The manual has been extensively revised: the - information about using CC Mode has been separated from the larger - and more difficult chapters about configuration. It has been - updated for CC Mode 5.31. - -2005-12-05 Katsumi Yamaoka - - * pgg.texi (User Commands): Fix description of pgg-verify-region. - (Selecting an implementation): Fix descriptions. - -2005-11-30 Katsumi Yamaoka - - * message.texi (Various Message Variables): Addition. - -2005-11-29 Katsumi Yamaoka - - * message.texi: Fix default values. - -2005-11-25 Katsumi Yamaoka - - * message.texi (Header Commands): Clarify descriptions of - message-cross-post-followup-to, message-reduce-to-to-cc, and - message-insert-wide-reply. - (Various Commands): Fix kindex for message-kill-to-signature; - clarify description of message-tab. - -2005-11-22 Katsumi Yamaoka - - * message.texi (Mailing Lists): Fix description about MFT. - - * gnus.texi (Emacs Lisp): Use ~/.gnus.el instead of ~/.emacs. - -2005-11-17 Katsumi Yamaoka - - * gnus.texi (Slow Terminal Connection): Replace old description - with new one. - -2005-11-16 Katsumi Yamaoka - - * gnus.texi (Oort Gnus): Use ~/.gnus.el instead of ~/.emacs; - replace X-Draft-Headers with X-Draft-From. - -2005-11-14 Katsumi Yamaoka - - * gnus.texi (Various Various): Fix the default value of - nnheader-max-head-length. - (Gnus Versions): Fix typo. - -2005-12-08 Luc Teirlinck - - * custom.texi (Customization): Use xref to elisp manual for - non-TeX output. - (Minor Modes): Update. - (Customization Groups, Changing a Variable, Face Customization): - Update for new appearance of Custom buffers. - (Changing a Variable): `custom-buffer-done-function' has been - replaced by `custom-buffer-done-kill'. - (Specific Customization): In the `customize-group' buffer, a - subgroup's contents are not "hidden". They are not included at - all. They have no [Show] button. - (Mouse Buttons): Add pxref to description of mouse event lists in - Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys. - (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of - ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el). - -2005-12-08 Richard M. Stallman - - * mini.texi (Completion Commands, Completion): - In file name input, SPC does not do completion. - -2005-12-08 Carsten Dominik - - * org.texi (Structure editing): Document new functionality of - M-RET. - -2005-12-08 Nick Roberts - - * building.texi (GDB Graphical Interface): Explain screen size - setting. - (Other GDB User Interface Buffers): Describe features specific to - GDB 6.4. - -2005-12-06 Luc Teirlinck - - * org.texi (Internal Links): Fix Texinfo usage. - -2005-12-06 Carsten Dominik - - * org.texi (TODO basics): Document the global todo list. - (TODO items): Documents sparse tree for specific TODO - keywords. - -2005-12-01 Nick Roberts - - * building.texi (GDB User Interface Layout): Describe how to - kill associated buffers. - (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint. - (Watch Expressions): Be more precise. - (Other GDB User Interface Buffers): Describe how to change a - register value. - -2005-11-30 Carsten Dominik - - * org.texi (Plain Lists): Typos fixed. - -2005-11-28 Jay Belanger - - * calc.texi: Change references of `M-#' to `C-x *' prefix. - -2005-11-24 Carsten Dominik - - * org.texi (Structure editing): New item moving commands added. - (Plain Lists): New section. - -2005-11-24 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Remove description of - mac-command-key-is-meta. Add descriptions of - mac-control-modifier, mac-command-modifier, and - mac-option-modifier. - (Mac International): Fix description of conversion of clipboard data. - (Mac Font Specs): Add example of font customization by face attributes. - -2005-11-22 Nick Roberts - - * building.texi (Watch Expressions): Expand description. - (Other GDB User Interface Buffers): Describe local map for - gud-watch. - -2005-11-21 Chong Yidong - - * display.texi (Font Lock): Font lock is enabled by default now. - -2005-11-20 Juri Linkov - - * basic.texi (Position Info): Update examples of the output. - Remove the fact that examples are produced in the TeXinfo buffer, - because in the Info reader users will get a different output from - `C-x ='. - - * building.texi (Compilation Mode): Remove paragraph duplicated - from the node `Compilation'. Add `compilation-skip-threshold'. - - * display.texi (Font Lock): Suggest more user-friendly method of - finding all Font Lock faces (M-x customize-group RET font-lock-faces). - -2005-11-18 Richard M. Stallman - - * files.texi (Registering): Mention @@ in mode line. - - * mini.texi (Minibuffer File): Clarify previous change. Add @findex. - -2005-11-08 Aaron S. Hawley - - * files.texi (Renaming and VC): Some back-ends don't - handle renaming. - -2005-11-18 Carsten Dominik - - * org.texi (FAQ): Document `org-table-tab-jumps-over-hlines'. - (Agenda): Document commands `org-cycle-agenda-files' and - `org-agenda-file-to-front' - (Built-in table editor): Document `org-table-sort-lines'. - (HTML formatting): Export of hand-formatted lists. - -2005-11-17 Juri Linkov - - * emacs.texi (Top): - * display.texi (Highlight Interactively): Put this font-lock based - mode near Font Lock node. - -2005-11-16 Chong Yidong - - * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs - icons. - -2005-11-12 Kim F. Storm - - * help.texi (Help): Fix C-h a entry. Add C-h d entry. - (Help Summary): Add C-h d and C-h e. - (Apropos): Clarify that all apropos commands may search for either - list of words or a regexp. Add C-h d for apropos-documentation. - Describe apropos-documentation-sort-by-scores user option. - -2005-11-10 Katsumi Yamaoka - - * gnus.texi (XVarious): Fix description of gnus-use-toolbar; add - new variable gnus-toolbar-thickness. - -2005-11-08 Katsumi Yamaoka - - * gnus.texi (XVarious): Revert description of gnus-use-toolbar. - -2005-11-07 Katsumi Yamaoka - - * gnus.texi (X-Face): Fix description. - (XVarious): Remove gnus-xmas-logo-color-alist and - gnus-xmas-logo-color-style; fix description of gnus-use-toolbar. - -2005-11-01 Katsumi Yamaoka - - * gnus.texi (Group Parameters): Mention new variable - gnus-parameters-case-fold-search. - (Home Score File): Addition. - -2005-11-09 Luc Teirlinck - - * killing.texi (CUA Bindings): Add @section. - -2005-11-10 Kim F. Storm - - * emacs.texi (Top): Add CUA Bindings entry to menu. - - * killing.texi (CUA Bindings): New node. Moved here from - misc.texi and extended with info on rectangle commands and - rectangle highlighting, interface to registers, and the global - mark feature. - - * misc.texi (Emulation): Move CUA bindings item to killing.texi. - - * regs.texi: Prev link points to CUA Bindings node. - -2005-11-07 Luc Teirlinck - - * help.texi (Help Echo): By default, help echos are only shown on - mouse-over, not on point-over. - -2005-11-04 J,Ai(Br,At(Bme Marant - - * misc.texi (Shell Mode): Describe how to activate password echoing. - -2005-11-04 Ulf Jasper - - * newsticker.texi: VERSION changed to 1.9. Updated UPDATED. - (Overview): List supported feed types. - (Installation): No installation necessary when using autoload. - (Configuration): Rename "RSS" to "news". - -2005-11-04 Ken Manheimer - - * pgg.texi (User Commands): Document additional passphrase - argument for pgg-encrypt-*, pgg-decrypt-*, and pgg-sign-* functions. - (Backend methods): Likewise for corresponding pgg-scheme-* functions. - -2005-11-04 Carsten Dominik - - * org.texi: Version number changed to 3.19. - -2005-11-04 Romain Francoise - - * mark.texi (Mark Ring): Fix typo. - -2005-11-03 Richard M. Stallman - - * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop. - -2005-11-01 Bill Wohler - - * help.texi (Help Mode): Fix typo. - -2005-11-01 Nick Roberts - - * building.texi (Other GDB User Interface Buffers): Describe - the command gdb-use-inferior-io-buffer. - -2005-10-31 Romain Francoise - - * files.texi (Compressed Files): Fix typo. - - * buffers.texi (Misc Buffer): Downcase `*shell*'. - - * windows.texi (Force Same Window): Likewise. - -2005-10-30 Bill Wohler - - * help.texi (Help Mode): URLs viewed with browse-url. - -2005-10-31 Nick Roberts - - * building.texi (GDB Graphical Interface): Don't reference - gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until - must stay in same frame. - -2005-10-29 Chong Yidong - - * custom.texi (Init File): Document ~/.emacs.d/init.el. - - * anti.texi (Antinews): Likewise. - -2005-10-29 Sascha Wilde - - * pgg.texi (How to use): Update the example to add autoload of - pgg-encrypt-symmetric-region. - (User Commands): Document pgg-encrypt-symmetric-region. - (Backend methods): Document pgg-scheme-encrypt-symmetric-region. - -2005-10-28 Bill Wohler - - * help.texi (Help): Help mode now creates hyperlinks for URLs. - -2005-10-28 Richard M. Stallman - - * files.texi (Visiting): Explain how to enter ? in a file name. - - * trouble.texi (Memory Full): Mention !MEM FULL! in mode line. - -2005-10-27 Jay Belanger - - * calc.texi (Predefined Units): Fix the symbol for a TeX points, - mention other TeX-related units. - -2005-10-25 Nick Roberts - - * building.texi (GDB Graphical Interface): Describe - gdb-mouse-until. - -2005-10-23 Richard M. Stallman - - * custom.texi (Init File): Recommend when to use site-start.el. - -2005-10-23 Lars Hansen - - * dired-x.texi (Miscellaneous Commands): Replace - dired-do-relative-symlink by dired-do-relsymlink and - dired-do-relative-symlink-regexp by dired-do-relsymlink-regexp. - -2005-10-23 Jay Belanger - - * calc.texi (Predefined Units): Use `alpha' for the fine structure - constant. - -2005-10-23 Michael Albinus - - * faq.texi (Bugs and problems): Replace - `dired-move-to-filename-regexp' by - `directory-listing-before-filename-regexp'. - -2005-10-22 Eli Zaretskii - - * newsticker.texi (UPDATED): Set value. - -2005-10-17 Katsumi Yamaoka - - * gnus.texi (Document Groups): Remove duplicate item. - -2005-10-21 Juri Linkov - - * custom.texi (Examining): Mention accessing the old variable - value via M-n in set-variable. - -2005-10-21 Carsten Dominik - - * org.texi (Summary): Mention iCalendar support. - (Exporting): Document iCalendar support. - -2005-10-18 Romain Francoise - - * files.texi (Version Systems): Capitalize GNU. - - * viper.texi (Viper Specials): Likewise. - -2005-10-18 Nick Roberts - - * building.texi (Compilation Mode): Remove redundant paragraph. - (Watch Expressions): Remove paragraph to reflect code change. - -2005-10-17 Juri Linkov - - * info.texi (Getting Started, Search Index, Expert Info): - Fix wording. - (Search Text): Replace `echo area' with `mode line'. - (Search Index): Both `i' and `,' find all index entries. - Replace example `C-f' with `C-l' (which exists in index of Info - manual) and delete spaces in its keyboard input sequence. - Delete unnecessary explanations about literal characters. - -2005-10-16 Richard M. Stallman - - * building.texi (Compilation Mode, Compilation): Clarified. - -2005-10-15 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Mention savehist library. - -2005-10-14 Katsumi Yamaoka - - * gnus.texi (Document Server Internals): Addition. - -2005-10-13 Katsumi Yamaoka - - * gnus.texi (A note on namespaces): Fix RFC reference. - -2005-10-12 Katsumi Yamaoka - - * gnus.texi (RSS): Fix key description. - -2005-10-11 Katsumi Yamaoka - - * gnus.texi: Emacs/w3 -> Emacs/W3. - (Browsing the Web): Fix description. - (Web Searches): Ditto. - (Customizing W3): Ditto. - -2005-10-07 Katsumi Yamaoka - - * gnus.texi (Maildir): Clarify expire-age and expire-group. - -2005-10-13 Kenichi Handa - - * basic.texi (Position Info): Fix previous change. - -2005-10-12 Jan Dj,Ad(Brv - - * cmdargs.texi (Icons X): Fix typo. - -2005-10-12 Kenichi Handa - - * basic.texi (Position Info): Describe the case that Emacs shows - "part of display ...". - -2005-10-11 Jay Belanger - - * calc.texi (Integration): Mention using `a i' to compute definite - integrals. - -2005-10-11 Juri Linkov - - * info.texi: Rearrange nodes. - (Top): Update menu. Change ref `Info for Experts' to - `Advanced Info Commands'. - (Getting Started): Fix description of manual's parts. - (Help-Int): Change xref `Info Search' to `Search Index', and - `Expert Info' to `Advanced'. - (Advanced): Move node one level up. - (Search Text, Search Index): New nodes split out from `Info Search'. - (Go to node, Choose menu subtopic, Create Info buffer): New nodes - split out from `Advanced'. - (Advanced, Emacs Info Variables): De-document editing an Info file - in Info. - (Emacs Info Variables): Move node from `Expert Info' to `Advanced'. - (Creating an Info File): Delete node and move its text to - `Expert Info'. - -2005-10-10 Jan Dj,Ad(Brv - - * cmdargs.texi (Icons X): -nb => -nbi. - -2005-10-10 Chong Yidong - - * frames.texi (Speedbar): A couple more clarifications. - -2005-10-11 Nick Roberts - - * building.texi (GDB User Interface Layout): Improve diagram. - (Watch Expressions): Explain how to make speedbar global. - (Other GDB User Interface Buffers): Make references more precise. - -2005-10-10 Carsten Dominik - - * org.texi (Workflow states): Documented that change in keywords - becomes active only after restart of Emacs. - -2005-10-09 Richard M. Stallman - - * frames.texi (Speedbar): Clarify the text. - -2005-10-09 Chong Yidong - - * frames.texi (Speedbar): Add information on keybindings, - dismissing the speedbar, and buffer display mode. Link to - speedbar manual. - -2005-10-09 Jan Dj,Ad(Brv - - * cmdargs.texi (Icons X): Removed options -i, -itype, --icon-type, - added -nb, --no-bitmap-icon. - -2005-10-08 Michael Albinus - - Sync with Tramp 2.0.51. - -2005-10-08 Nick Roberts - - * speedbar.texi (Introduction): Describe new location of speedbar - on menubar. - (Basic Key Bindings): Remove descriptions of bindings that have - been removed. - -2005-10-07 Nick Roberts - - * building.texi (GDB Graphical Interface): Add variables and - functions to indices. Be more precise. - -2005-10-05 Nick Roberts - - * speedbar.texi (GDB): Describe use of watch expressions. - -2005-10-03 Jan Dj,Ad(Brv - - * frames.texi (Drag and Drop): Remove the x- from - x-dnd-open-file-other-window and xdnd-protocol-alist. - -2005-09-30 Romain Francoise - - * mini.texi (Minibuffer): The default value now appears before the - colon in minibuffer prompts. - -2005-09-28 Simon Josefsson - - * message.texi (IDNA): Fix. - -2005-09-28 Katsumi Yamaoka - - * gnus.texi (NNTP): Remove nntp-buggy-select, nntp-read-timeout, - nntp-server-hook, and nntp-warn-about-losing-connection; fix - description of nntp-open-connection-function. - (Common Variables): Fix descriptions. - -2005-09-26 Katsumi Yamaoka - - * gnus.texi (Server Buffer Format): Document the %a format spec. - -2005-09-25 Richard M. Stallman - - * search.texi (Regexp Search): Doc search-whitespace-regexp. - -2005-09-22 Katsumi Yamaoka - - * gnus.texi (Mail): Fix gnus-confirm-mail-reply-to-news entry. - -2005-09-20 Emanuele Giaquinta (tiny change) - - * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode. - -2005-09-23 Carsten Dominik - - * org.texi Version 3.16. - -2005-09-21 YAMAMOTO Mitsuharu - - * emacs.texi (Top): Update submenus from macos.texi. - - * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'. - (Mac OS): Update feature support status. - (Mac Input): List supported input scripts. Remove description - about `mac-keyboard-text-encoding'. Mention mouse button - emulation and related variables. - (Mac International): Mention Central European and Cyrillic - support. Now `keyboard-coding-system' is dynamically changed. - Add description about coding system for selection. Add - description about language environment. - (Mac Environment Variables): Mention - `~/.MacOSX/environment.plist'. Give example of command line - arguments. Add Preferences support. - (Mac Directories): Explicitly state that this node is for Mac OS - Classic only. - (Mac Font Specs): Mention specification for scalable fonts. List - supported charsets. Add preferred way of creating fontsets. Add - description about `mac-allow-anti-aliasing'. - (Mac Functions): Add descriptions about `mac-set-file-creator', - `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type', - and `mac-get-preference'. - -2005-09-19 Miles Bader - - * newsticker.texi: Get rid of CVS keywords. - -2005-09-15 Katsumi Yamaoka - - * gnus.texi (Finding the Parent): Fix description of how Gnus - finds article. - -2005-09-14 Jari Aalto - - * gnus.texi (Advanced Scoring Examples): New examples to teach how - to drop off non-answered articles. - -2005-09-19 Juanma Barranquero - - * makefile.w32-in (newsticker.dvi): Use parentheses instead of curly - braces (which are unsupported by NMAKE) for macro `srcdir'. - -2005-09-17 Eli Zaretskii - - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Add newsticker targets. - (../info/newsticker, newsticker.dvi): New targets. - -2005-09-17 Ulf Jasper - - * newsticker.texi: Replace @command with @code. Replace @example - with @lisp. - (Top): Added explanations to menu items. - (GNU Free Documentation License): Removed. - -2005-09-16 Romain Francoise - - Update all files to specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Richard M. Stallman - - * buffers.texi (List Buffers): Fix xref. - - * rmail.texi (Rmail Basics): Fix xref. - - * emacs.texi (Top): Update subnode menus. - - * files.texi (Saving Commands): New node, broken out of Saving. - (Customize Save): New node, broken out of Saving. - Clarify effect of write-region-inhibit-fsync. - (Misc File Ops): Say write-region-inhibit-fsync affects write-region. - - * newsticker.texi: Fix @setfilename. - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add newsticker targets. - (../info/newsticker, newsticker.dvi): New targets. - -2005-09-14 Romain Francoise - - * files.texi (Saving): Mention write-region-inhibit-fsync. - -2005-09-05 Chong Yidong - - * custom.texi (Custom Themes): New node. - -2005-09-03 Richard M. Stallman - - * search.texi (Search Case): Mention vars that control - case-fold-search for various operations. - -2005-08-30 Carsten Dominik - - * org.texi: Version 3.15. - -2005-08-29 Luc Teirlinck - - * ses.texi: Combine all three indices into one. - Correct a few typos. - -2005-08-19 Katsumi Yamaoka - - * emacs-mime.texi (time-date): Fix description of safe-date-to-time. - -2005-08-18 Katsumi Yamaoka - - * emacs-mime.texi (Handles): Remove duplicate item. - (Encoding Customization): Fix the default value for - mm-coding-system-priorities. - (Charset Translation): Emacs doesn't use mm-mime-mule-charset-alist. - (Basic Functions): Fix reference. - -2005-08-09 Katsumi Yamaoka - - * gnus.texi (Charsets): Fj hierarchy uses iso-2022-jp. - -2005-08-22 Juri Linkov - - * display.texi (Standard Faces): Merge the text from - `(elisp)Standard Faces' into this node. - -2005-08-18 Luc Teirlinck - - * emacs.texi (Top): Delete menu item for deleted node - Keyboard Translations. - -2005-08-18 Richard M. Stallman - - * faq.texi (Obtaining the FAQ): Delete refs to Lerner's email - and web site. - - * trouble.texi (Unasked-for Search): - Delete xref to Keyboard Translations. - - * glossary.texi (Glossary): Delete xref. - - * faq.texi (Swapping keys): Xref for normal-erase-is-backspace-mode, - not keyboard-translate. - - * custom.texi (Minor Modes): Say that the list here is not complete. - (Keyboard Translations): Node deleted. - (Disabling): Delete xref to it. - (Customization Groups): Fix Custom buffer example. - (Hooks): Mention remove-hooks. - -2005-08-17 Luc Teirlinck - - * building.texi (GDB Graphical Interface): Improve filling of menu - item. - -2005-08-18 Nick Roberts - - * building.texi (GDB Graphical Interface): Use better node names. - -2005-08-14 Richard M. Stallman - - * text.texi (Sentences): Fix xref. - -2005-08-14 Juri Linkov - - * building.texi (Compilation, Grep Searching): Move grep command - headings from `Compilation' to `Grep Searching'. - - * dired.texi (Dired and Find): - * maintaining.texi (Tags Search): Replace grep xref to - `Compilation' node with `Grep Searching'. - - * files.texi (Comparing Files): Replace xref to `Compilation' with - `Compilation Mode'. - -2005-08-13 Alan Mackenzie - - * search.texi (Non-ASCII Isearch): Correct a typo. - (Replacement Commands): Mention query-replace key binding. - -2005-08-11 Richard M. Stallman - - * programs.texi (Options for Comments): Fix xref. - - * search.texi (Regexp Backslash, Regexp Example): New nodes split - out of Regexps. - - * faq.texi (Using regular expressions): Fix xref. - -2005-08-09 Juri Linkov - - * building.texi (Compilation): Use `itemx' instead of `item'. - (Grep Searching): Simplify phrase. - - * display.texi (Standard Faces): Describe vertical-border on - window systems. - - * windows.texi (Split Window): Simplify phrase and mention - vertical-border face. - -2005-08-09 Richard M. Stallman - - * files.texi (Comparing Files): Clarify compare-windows. - - * calendar.texi (Scroll Calendar): Document < and > in calendar. - -2005-08-09 Juri Linkov - - * info.texi (Help-P): Replace `Prev' with `Previous'. - (Help-M, Help-Xref): Add S-TAB. - (Help-FOO): Update `u' command. - (Help-Xref): Move info about Mouse-2 from `Help-Int'. - Update info about visibility of xref parts. - (Help-Int): Fix `m' command. Rename `Info-last' to - `Info-history-back'. Add `Info-history-forward'. - (Advanced): Fix `g*' and `M-n' commands. - (Info Search): Add `index-apropos' in stand-alone browser. - Add isearch commands. - (Emacs Info Variables): Remove `Info-fontify'. - Add `Info-mode-hook'. Update face names. - Add `Info-fontify-maximum-menu-size', - `Info-fontify-visited-nodes', `Info-isearch-search'. - -2005-08-07 Michael Albinus - - Sync with Tramp 2.0.50. - - * tramp.texi: Use @option{} consequently for method names. - (Inline methods, External transfer methods): Remove references to - Cygwin. - (Issues with Cygwin ssh): Explain trouble with Cygwin's ssh - implementation. - -2005-08-06 Eli Zaretskii - - * mule.texi (Coding Systems): Rephrase the paragraph about - codepages: no need for "M-x codepage-setup" anymore, except on - MS-DOS. - - * msdog.texi (MS-DOS and MULE): Clarify that this section is for - the MS-DOS port only. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run multi-install-info.bat. - ($(infodir)/dir): New target, produced by running - multi-install-info.bat. - -2005-07-27 Reiner Steib - - * gnus.texi (Startup Files): Fix name of gnus-site-init-file. - Mention that gnus-init-file is not read when Emacs is invoked with - --no-init-file or -q. - -2005-07-22 Eli Zaretskii - - * files.texi (Quoted File Names): Add index entry. - -2005-07-19 Carsten Dominik - - * org.texi: Version 3.14. - -2005-07-04 Carsten Dominik - - * org.texi: Version 3.13. - -2005-07-19 Juri Linkov - - * files.texi (Comparing Files): Mention resync for `compare-windows'. - -2005-07-18 Juri Linkov - - * calc.texi (Time Zones, Logical Operations): - * cl.texi (Overview): - * custom.texi (Easy Customization): - * files.texi (Old Versions): - * frames.texi (Wheeled Mice): - * mule.texi (Specify Coding): - * org.texi (TODO types): - * sc.texi (Emacs 18 MUAs): - * speedbar.texi (Top): - * text.texi (Cell Justification): - * trouble.texi (After a Crash): - * url.texi (History): - * xresources.texi (GTK styles): - Delete duplicate duplicate words. - -2005-07-17 Richard M. Stallman - - * frames.texi (Creating Frames): Fix foreground color example. - - * custom.texi (Init Examples): Clean up text about conditionals. - -2005-07-16 Richard M. Stallman - - * mini.texi (Completion Commands): Fix command name for ?. - -2005-07-16 Johan Bockgard (tiny change) - - * cl.texi (Type Predicates): Document `atom' type. - -2005-07-16 Eli Zaretskii - - * display.texi (Standard Faces): Explain that customization of - `menu' face has no effect on w32 and with GTK. Add - cross-references. - - * cmdargs.texi (General Variables): Clarify the default location - of $HOME on w32 systems. - -2005-07-15 Jason Rumney - - * cmdargs.texi (General Variables): Default HOME on MS Windows has - changed. - -2005-07-08 Kenichi Handa - - * mule.texi (Recognize Coding): Recommend - revert-buffer-with-coding-system instead of revert-buffer. - -2005-07-07 Richard M. Stallman - - * anti.texi (Antinews): Mention mode-line-inverse-video. - - * files.texi (Saving): Minor correction about C-x C-w. - - * display.texi (Display Custom): Don't mention mode-line-inverse-video. - -2005-07-07 Luc Teirlinck - - * search.texi (Isearch Scroll): Add example of using the - `isearch-scroll' property. - (Slow Isearch): Reference anchor for `baud-rate' instead of entire - `Display Custom' node. - (Regexp Replace): Put text that requires Emacs Lisp knowledge last - and de-emphasize it. - (Other Repeating Search): `occur' currently can not correctly - handle multiline matches. Correct, clarify and update description - of `flush-lines' and `keep-lines'. - - * display.texi (Display Custom): Add anchor for `baud-rate'. - -2005-07-07 Richard M. Stallman - - * gnu.texi: Update where to get GNU status; add refs for how to help. - Add footnotes 6 and 7. - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - - * calc.texi (Copying): - * doclicense.texi (GNU Free Documentation License): - * faq.texi (Contacting the FSF): - * mh-e.texi (Copying): - * trouble.texi (Checklist): Update FSF's address. - -2005-07-03 Richard M. Stallman - - * flymake.texi (Example -- Configuring a tool called directly): - Update name of flymake-build-relative-filename. - -2005-06-29 Katsumi Yamaoka - - * gnus.texi (NoCeM): gnus-nocem-verifyer defaults to pgg-verify. - -2005-06-29 Carsten Dominik - - * org.texi: Version 3.12. - -2005-06-24 Richard M. Stallman - - * display.texi (Text Display): Change index entries. - -2005-06-24 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Use --force. - (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in - Makefile.in. - (gnus.dvi): Use "..." to quote Sed args, so that it works with - more shells. - -2005-06-23 Richard M. Stallman - - * anti.texi (Antinews): Renamed show-nonbreak-escape to - nobreak-char-display. - - * emacs.texi (Top): Update detailed node listing. - - * display.texi (Text Display): Renamed show-nonbreak-escape - to nobreak-char-display and no-break-space to nobreak-space. - (Standard Faces): Split up the list of standard faces - and put it in a separate node. Add nobreak-space and - escape-glyph. - - * speedbar.texi (Creating a display): Texinfo usage fixes. - - * tramp.texi (Customizing Completion, Auto-save and Backup): - Texinfo usage fixes. - -2005-06-23 Lute Kamstra - - * mule.texi (Select Input Method): Fix typo. - -2005-06-23 Kenichi Handa - - * mule.texi (International): List all supported scripts. Adjust - text for that leim is now included in the normal Emacs - distribution. - (Language Environments): List all language environments. - Intlfonts contains fonts for most supported scripts, not all.. - (Select Input Method): Refer to C-u C-x = to see how to type to - input a specifc character. - (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit. - -2005-06-23 Juanma Barranquero - - * building.texi (Grep Searching): - * dired-x.texi (Miscellaneous Commands): - * ediff.texi (Miscellaneous): - * gnus.texi (MIME Commands, Fancy Mail Splitting, Agent Visuals) - (Agent Variables): - * info.texi (Help-Xref): - * message.texi (Message Headers): - * org.texi (Remember): - * reftex.texi (Options (Defining Label Environments)): - (Options (Index Support)): - (Options (Viewing Cross-References)): - (Options (Misc)): - (Changes): - * speedbar.texi (Creating a display): - * tramp.texi (Customizing Completion, Auto-save and Backup): - Texinfo usage fix. - -2005-06-22 Miles Bader - - * display.texi (Faces): Change `vertical-divider' to `vertical-border'. - -2005-06-20 Miles Bader - - * display.texi (Faces): Add `vertical-divider'. - -2005-06-17 Richard M. Stallman - - * text.texi (Adaptive Fill): Minor clarification. - -2005-06-13 Carsten Dominik - - * org.texi: Version 3.11. - -2005-06-12 Jay Belanger - - * calc.texi (Getting Started): Remove extra menu item. - -2005-06-10 Lute Kamstra - - * emacs.texi (Top): Correct version number. - * anti.texi (Antinews): Correct version number. Use EMACSVER to - refer to the current version of Emacs. - -2005-06-08 Luc Teirlinck - - * files.texi (Log Buffer): Document when there can be more than - one file to be committed. - -2005-06-08 Juri Linkov - - * display.texi (Faces): Add `shadow' face. - -2005-06-07 Masatake YAMATO - - * display.texi (Faces): Write about mode-line-highlight. - -2005-06-06 Richard M. Stallman - - * misc.texi (Printing Package): Explain how to initialize - printing package. - - * cmdargs.texi (Action Arguments): Clarify directory default for -l. - -2005-06-05 Chong Yidong - - * emacs.texi: Rename Hardcopy to Printing. - Make PostScript and PostScript Variables subnodes of it. - - * misc.texi (Printing): Rename node from Hardcopy. - Mention menu bar options. - Move PostScript and PostScript Variables to submenu. - (Printing package): New node. - - * mark.texi (Using Region): Change Hardcopy xref to Printing. - - * dired.texi (Operating on Files): Likewise. - - * calendar.texi (Displaying the Diary): Likewise. - - * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise. - - * glossary.texi (Glossary): Likewise. - - * frames.texi (Mode Line Mouse): Mention mode-line-highlight - effect. - -2005-06-04 Richard M. Stallman - - * trouble.texi (After a Crash): Polish previous change. - -2005-05-31 Jay Belanger - - * calc.texi (Notations Used in This Manual): Use @kbd for key - sequence. - (Demonstration of Calc): Mention another way of starting Calc. - (Starting Calc): Mention long name of M-#. - (Embedded Mode Overview): Remove unnecessary instruction. - (Other M-# commands): Rephrase `M-# 0' explanation. - (Basic Embedded Mode): Rewrite discussion of prefix arguments to - reflect current behavior. - -2005-05-30 Jay Belanger - - * calc.texi (Hooks): Change description of calc-window-hook and - calc-trail-window-hook to match usage. - (Computational Functions): Add more constant-generating functions. - (Customizable Variables): Use defvar. - -2005-05-30 Noah Friedman - - * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a - recovery mechanism. - -2005-05-28 Jay Belanger - - * calc.texi (Assignments in Embedded Mode): Fix variable name. - (Basic Embedded Mode): Explain behavior of arguments to - calc-embedded-mode. - -2005-05-28 Nick Roberts - - * building.texi (Other Buffers): SPC toggles display of - floating point registers. - -2005-05-27 Jay Belanger - - * calc.texi (Queries in Keyboard Macros): Rewrite to reflect - current behavior. - -2005-05-27 Nick Roberts - - * files.texi (Log Buffer): Merge in description of Log Edit - mode from pcl-cvs.texi. - -2005-05-26 Richard M. Stallman - - * building.texi (Lisp Eval): C-M-x with arg runs Edebug. - -2005-05-25 Jay Belanger - - * calc.texi: Change Calc version number throughout. - (Keypad Mode): Change location in info output. - (Keypad mode overview): Move picture of keypad. - -2005-05-24 Luc Teirlinck - - * fixit.texi (Spelling): Delete confusing sentence; flyspell is - not enabled by default. - When not on a word, `ispell-word' by default checks the word - before point. - -2005-05-24 Nick Roberts - - * building.texi (Debugger Operation): Simplify last sentence. - -2005-05-23 Lute Kamstra - - * emacs.texi: Update FSF's address throughout. - (Preface): Use @cite. - (Distrib): Add cross reference to the node "Copying". Mention the - FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of - printed manuals. - (Intro): Use @xref for the Emacs Lisp Intro. - -2005-05-21 Jay Belanger - - * calc.texi (Storing variables): Mention that only most variables - are void to begin with. - -2005-05-21 Kevin Ryde - - * widget.texi (Basic Types): Update cross ref from "Enabling - Mouse-1 to Follow Links" to "Links and Mouse-1" per recent - lispref/text.texi change. - -2005-05-20 Carsten Dominik - - * org.texi: Version 3.09. - -2005-05-18 Carsten Dominik - - * reftex.texi: Version 4.28. - -2005-05-18 Luc Teirlinck - - * buffers.texi (Select Buffer): Document `C-u M-g M-g'. - - * basic.texi (Moving Point): Mention default for `goto-line'. - - * programs.texi (Lisp Doc): Eldoc mode shows only the first line - of a variable's docstring. - -2005-05-18 Lute Kamstra - - * maintaining.texi (Overview of Emerge): Add cross reference. - Remove duplication. - - * emacs.texi (Top): Update to the current structure of the manual. - * misc.texi (Emacs Server): Add menu description. - * files.texi (Saving): Fix menu. - * custom.texi (Customization): Fix menu. - * mule.texi (International): Fix menu. - * kmacro.texi (Keyboard Macros): Fix menu. - -2005-05-16 Luc Teirlinck - - * display.texi: Various minor changes. - (Faces): Delete text that is repeated in the next section. - -2005-05-16 Nick Roberts - - * building.texi (Debugger Operation): Mention GUD tooltips are - disabled with GDB in text command mode. - -2005-05-16 Jay Belanger - - * calc.texi (Storing Variables): Mention `calc-copy-special-constant'. - -2005-05-16 Nick Roberts - - * building.texi: Replace toolbar with "tool bar" for consistency. - (Compilation Mode): Describe compilation-context-lines - and use of arrow in compilation buffer. - (Debugger Operation): Replace help text with variable's value. - - * frames.texi (Tooltips): Replace toolbar with "tool bar" for - consistency. - -2005-05-15 Luc Teirlinck - - * major.texi (Choosing Modes): normal-mode processes the -*- line. - Add xref. - -2005-05-14 Jay Belanger - - * calc.texi (Default Simplifications): Insert missing ! (logical - not operator). - -2005-05-14 Michael Albinus - - Sync with Tramp 2.0.49. - -2005-05-14 Luc Teirlinck - - * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'. - (Position Info): Delete discussion of `goto-line'. It is already - described in `Moving point'. - - * mini.texi (Completion Commands): Correct reference. - (Completion Options): Fix typo. - - * killing.texi (Deletion): Complete description of `C-x C-o'. - -2005-05-10 Jay Belanger - - * calc.texi (Default Simplifications): Mention that 0^0 simplifies - to 1. - -2005-05-10 Richard M. Stallman - - * building.texi (Compilation): Clarify recompile's directory choice. - - * frames.texi (Tooltips): Cleanups. - - * basic.texi (Arguments): Fix punctuation. - -2005-05-09 Luc Teirlinck - - * screen.texi (Menu Bar): The up and down (not left and right) - arrow keys move through a keyboard menu. - -2005-05-08 Luc Teirlinck - - * basic.texi: Various typo and grammar fixes. - (Moving Point): C-a now runs move-beginning-of-line. - -2005-05-08 Nick Roberts - - * building.texi (Debugger Operation): Describe gud-tooltip-echo-area. - - * frames.texi (Tooltips): Describe help tooltips and GUD tooltips - as different animals. - -2005-05-07 Luc Teirlinck - - * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'. - Correct index entry. - -2005-05-07 Nick Roberts - - * building.texi (Debugger Operation): Update to reflect changes - in GUD tooltips. - -2005-04-30 Richard M. Stallman - - * files.texi (Compressed Files): Auto Compression normally enabled. - - * building.texi (Debugger Operation): Clarify previous change. - -2005-04-29 Carsten Dominik - - * org.texi: Version 3.08, structure reorganized. - -2005-04-28 Nick Roberts - - * building.texi (Debugger Operation): Add description for - GUD tooltips when program is not running. - -2005-04-26 Luc Teirlinck - - * misc.texi (Shell): Add `Shell Prompts' to menu. - (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u' - description. Delete remarks moved to new node. - (Shell Prompts): New node. - (History References): Replace remarks moved to `Shell Prompts' - with xref to that node. - (Remote Host): Clarify how to specify the terminal type when - logging in to a different machine. - -2005-04-26 Richard M. Stallman - - * emacs.texi (Top): Update submenus from files.texi. - - * files.texi (Filesets): Clarify previous change. - - * dired.texi (Misc Dired Features): Clarify previous change. - -2005-04-25 Chong Yidong - - * ack.texi (Acknowledgments): Delete info about iso-acc.el. - - * dired.texi (Misc Dired Features): Document - dired-compare-directories. - - * files.texi (Filesets): New node. - (File Conveniences): Document Image mode. - - * text.texi (TeX Print): Document tex-compile. - -2005-04-25 Luc Teirlinck - - * frames.texi (Tooltips): Tooltip mode is enabled by default. - Delete redundant reference to tooltip Custom group. It is - referred too again in the next paragraph. - -2005-04-24 Richard M. Stallman - - * ack.texi: Delete info about lazy-lock.el and fast-lock.el. - - * faq.texi: Delete info about lazy-lock.el and fast-lock.el. - -2005-04-19 Kim F. Storm - - * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings. - -2005-04-18 Lars Hansen - - * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now - turns off desktop-save-mode. - -2005-04-17 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled - by default in terminals compatible with xterm. Mention that - xterm-mouse-mode is a minor mode and put in pxref to Minor Modes - node. - -2005-04-15 Carsten Dominik - - * org.texi: Update to version 3.06. - -2005-04-13 Lute Kamstra - - * cc-mode.texi: Prevent creating an unnecessary empty cc-mode.ss file. - -2005-04-12 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default. - -2005-04-12 Jan Dj,Ad(Brv - - * xresources.texi (Table of Resources): Add cursorBlink. - -2005-04-11 Luc Teirlinck - - * rmail.texi (Rmail Summary Edit): Explain numeric arguments to - `d', `C-d' and `u'. - -2005-04-11 Richard M. Stallman - - * cmdargs.texi (Initial Options): -Q is now --quick, and does less. - (Misc X): Add -D, --basic-display. - - * maintaining.texi (Change Log): Correct the description of - the example. - - * major.texi (Choosing Modes): Document magic-mode-alist. - -2005-04-10 Thien-Thi Nguyen - - * cl.texi (Porting Common Lisp): Fix typo. - -2005-04-10 Luc Teirlinck - - * rmail.texi (Rmail Basics): Clarify description of `q' and `b'. - (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg. - (Rmail Inbox): Give full name of `rmail-primary-inbox-list'. - (Rmail Output): Clarify which statements apply to `o', `C-o' and - `w', respectively. - (Rmail Labels): Mention `l'. - (Rmail Attributes): Correct pxref. Mention `stored' attribute. - (Rmail Summary Edit): Describe `j' and RET. - -2005-04-10 Jan Dj,Ad(Brv - - * xresources.texi (Lucid Resources): Add fontSet resource. - -2005-04-06 Katsumi Yamaoka - - * gnus.texi (RSS): Addition. - -2005-04-09 Luc Teirlinck - - * display.texi (Useless Whitespace): `indicate-unused-lines' is - now called `indicate-empty-lines'. - -2005-04-06 Kim F. Storm - - * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q. - -2005-04-04 Luc Teirlinck - - * dired.texi (Dired Visiting): `dired-view-command-alist' has been - deleted. - (Marks vs Flags): Add some convenient key bindings. - (Hiding Subdirectories): Delete redundant and inaccurate sentence. - (Misc Dired Features): Correct and expand description of `w' command. - - * frames.texi (XTerm Mouse): Delete apparently false info. - The GNU/Linux console currently does not appear to support - `xterm-mouse-mode'. - -2005-04-04 Jay Belanger - - * calc.texi: Change Calc version number. - (Customizable variables): Fix description of calc-language-alist. - (Copying): Put in version 2 of GPL. - -2005-04-03 Glenn Morris - - * calendar.texi (Diary): Mention shell utility `calendar'. - -2005-04-01 Richard M. Stallman - - * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist. - -2005-04-01 Jay Belanger - - * calc.texi (Troubleshooting Commands): Remove comment about - installation. - (Installation): Remove section. - (Customizable Variables): New section. - (Basic Embedded Mode, Customizing Embedded Mode, Graphics) - (Graphical Devices): Add references to Customizable Variables. - -2005-04-01 Lute Kamstra - - * maintaining.texi (Change Log): add-change-log-entry uses - add-log-mailing-address. - -2005-03-31 Luc Teirlinck - - * files.texi (Reverting): Move `auto-revert-check-vc-info' to - `VC Mode Line' and put in an xref to that node. - (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify - its description. - -2005-03-31 Paul Eggert - - * calendar.texi (Calendar Systems): Say that the Persian calendar - implemented here is the arithmetical one championed by Birashk. - -2005-03-30 Glenn Morris - - * programs.texi (Fortran Motion): Fix previous change. - -2005-03-25 Katsumi Yamaoka - - * emacs-mime.texi (Display Customization): Markup fixes. - (rfc2047): Update. - -2005-03-23 Reiner Steib - - * gnus-faq.texi: Replaced with auto-generated version. - -2005-03-29 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info. - -2005-03-29 Chong Yidong - - * text.texi (Refill): Refer to Long Lines Mode. - (Longlines): New node. - (Auto Fill): Don't index "word wrap" here. - (Filling): Add Longlines to menu. - -2005-03-29 Richard M. Stallman - - * xresources.texi: Minor fixes. - - * misc.texi (Emacs Server): Fix Texinfo usage. - - * emacs.texi (Top): Don't use a real section heading for - "Detailed Node Listing". Fake it instead. - - * basic.texi (Position Info): Minor cleanup. - - * mule.texi (Input Methods): Minor cleanup. - -2005-03-29 Glenn Morris - - * programs.texi (ForIndent Vars): `fortran-if-indent' does other - constructs as well. - (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block. - -2005-03-29 Kenichi Handa - - * mule.texi (Input Methods): Refer to the command C-u C-x =. - - * basic.texi (Position Info): Update the description about the - command C-u C-x =. - -2005-03-28 Richard M. Stallman - - * emacs.texi (Top): Use @section for the detailed node listing. - - * calendar.texi: Minor fixes to previous change. - - * programs.texi (Fortran): Small fixes to previous changes. - - * emacs.texi (Top): Update list of subnodes of Dired. - Likewise for building.texi. - - * files.texi (File Conveniences): Delete Auto Image File mode. - -2005-03-28 Chong Yidong - - * building.texi (Flymake): New node. - - * custom.texi (Function Keys): Document kp- event types and - keypad-setup package. - - * dired.texi (Wdired): New node. - - * files.texi (File Conveniences): Reorder entries. - Explain how to turn on Auto-image-file mode. - Document Thumbs mode. - - * mule.texi (Specify Coding): Document recode-region and - recode-file-name. - - * programs.texi (Program Modes): Add Conf mode and DNS mode. - -2005-03-27 Luc Teirlinck - - * commands.texi (Keys): M-o is now a prefix key. - -2005-03-27 Glenn Morris - - * programs.texi: Reformat and update copyright years. - (Fortran): Update section. - -2005-03-26 Luc Teirlinck - - * files.texi: Several small changes in addition to: - (Visiting): Change xref for Dialog Boxes to ref. - (Version Headers): Replace references to obsolete var - `vc-header-alist' with `vc-BACKEND-header'. - (Customizing VC): Update value of `vc-handled-backends'. - -2005-03-26 Glenn Morris - - * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section; - move here from Emacs Lisp Reference Manual. - * calendar.texi (Calendar/Diary, Diary Commands) - (Special Diary Entries, Importing Diary): Change some xrefs to - point to emacs-xtra rather than elisp. - - * emacs-xtra.texi (Calendar Customizing): - Move view-diary-entries-initially, view-calendar-holidays-initially, - mark-diary-entries-in-calendar, mark-holidays-in-calendar to main - Emacs Manual. - (Appt Customizing): Merge entire section into main Emacs Manual. - * calendar.texi (Holidays): Move view-calendar-holidays-initially, - mark-holidays-in-calendar here from emacs-xtra. - (Displaying the Diary): Move view-diary-entries-initially, - mark-diary-entries-in-calendar here from emacs-xtra. - (Appointments): Move appt-display-mode-line, - appt-display-duration, appt-disp-window-function, - appt-delete-window-function here from emacs-xtra. - - * calendar.texi: Update and reformat copyright. - Change all @xrefs to the non-printing emacs-xtra to @inforefs. - (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3. - (Diary): Refer to `diary-file' rather than ~/diary. - (Diary Commands): Rename node to "Displaying the Diary". - * emacs.texi (Top): Rename "Diary Commands" section. - * misc.texi (Hardcopy): Rename "Diary Commands" xref. - -2005-03-26 Eli Zaretskii - - * misc.texi (Emacs Server): Fix the command for setting - server-name. Add an xref to Invoking emacsclient. - - * help.texi (Help Summary): Clarify when "C-h ." will do something - nontrivial. - (Apropos): Add cindex entry for apropos-sort-by-scores. - - * display.texi (Text Display): Add index entries for how no-break - characters are displayed. - -2005-03-26 Stephan Stahl (tiny change) - - * dired-x.texi (Multiple Dired Directories): default-directory was - renamed to dired-default-directory. - -2005-03-26 Eli Zaretskii - - * files.texi (Visiting): Fix cross-references introduced with the - last change. - - * xresources.texi (GTK resources): Fix last change. - -2005-03-26 Jay Belanger - - * calc.texi (Simplifying Formulas, Rewrite Rules): - Change description of top and bottom of fraction. - (Modulo Forms): Move description of how to create modulo forms to - earlier in the section. - (Fraction Mode): Suggest using : to get a fraction by dividing. - (Basic Arithmetic): Adjust placement of command name. - (Truncating the Stack): Emphasize that "hidden" entries are still - visible. - (Installation): Move discussion of printing manual to "About This - Manual". - (About This Manual): Mention how to print the manual. - (Reporting Bugs): Remove first person. - (Building Vectors): Add algebraic version of append. - (Manipulating Vectors): Fix algebraic version of calc-reverse-vector. - (Grouping Digits): Fix typo. - -2005-03-25 Chong Yidong - - * xresources.texi (X Resources): GTK options documented too. - (Resources): Clarify meaning of program name. - (Table of Resources): Add visualClass. - (GTK resources): Rewrite. - (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups. - - * display.texi (Text Display): Mention non-breaking spaces. - - * files.texi (Reverting): Document auto-revert-check-vc-info. - - * frames.texi (Mouse Commands): Document - x-mouse-click-focus-ignore-position and mouse-drag-copy-region. - - * help.texi (Help Summary): Add `C-h .'. - (Apropos): Apropos accepts a list of search terms. - Document apropos-sort-by-scores. - (Help Echo): Document display-local-help. - - * misc.texi (Emacs Server): Document server-name. - (Invoking emacsclient): Document -s option for server names. - - * text.texi (Outline Visibility): Introduce "current heading - line" (commands can be called with point on a body line). - Re-order table to follow the sequence of discussion. - hide-body won't hide lines before first header line. - (TeX Mode): Add DocTeX mode. - -2005-03-25 Werner Lemberg - - * calc.texi, cl.texi, gnus.texi, idlwave.texi, reftex.texi: - Replace `legal' with `valid'. - -2005-03-25 Werner Lemberg - - * calc.texi, reftex.texi: Replace `illegal' with `invalid'. - -2005-03-24 Jay Belanger - - * calc.texi (General Mode Commands) - (Mode Settings in Embedded Mode): Add some explanation of - recording mode settings. - -2005-03-24 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Delete mention - of iso-acc.el and iso-transl.el. - - * calc.texi: Remove praise of non-free software. - - * idlwave.texi: Don't say where to get IDL or its non-free manual. - (Installation): Node deleted. - -2005-03-23 Lute Kamstra - - * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch. - -2005-03-23 Richard M. Stallman - - * url.texi (HTTP language/coding): Improve last change. - - * search.texi: Delete explicit node pointers. - (Incremental Search): New menu. - (Basic Isearch, Repeat Isearch, Error in Isearch) - (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll) - (Slow Isearch): New subnodes. - (Configuring Scrolling): Node deleted. - (Search Case): Doc default-case-fold-search. - (Regexp Replace): Move replace-regexp doc here. - - * rmail.texi (Movemail): Put commas inside closequotes. - - * picture.texi (Insert in Picture): Document C-c arrow combos. - (Basic Picture): Clarify erasure. - - * display.texi (Font Lock): Put commas inside closequotes. - - * cmdargs.texi (General Variables): Put commas inside closequotes. - -2005-03-23 Nick Roberts - - * building.texi (Stack Buffer): Mention reverse contrast for - *selected* frame (might not be current frame). - -2005-03-22 Jay Belanger - - * calc.texi (Embedded Mode): Add new information on changing - modes. - -2005-03-21 Richard M. Stallman - - * building.texi (Starting GUD): Add bashdb. - -2005-03-20 Chong Yidong - - * basic.texi (Moving Point): Add M-g M-g binding. - (Undo): Document undo-only. - (Position Info): Document M-g M-g and C-u M-g M-g. - - * building.texi (Building): Put Grep Searching after Compilation - Shell. - (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings. - Document next-error-highlight. - (Grep Searching): Document grep-highlight-matches. - (Lisp Eval): Typing C-x C-e twice prints integers specially. - - * calendar.texi (Importing Diary): Rename node from iCalendar. - Document diary-from-outlook. - - * dired.texi (Misc Dired Features): Rename node from Misc Dired - Commands. - Mention effect of X drag and drop on Dired buffers. - - * files.texi (Visiting): Document large-file-warning-threshold. - Move paragraph on file-selection dialog. - Mention visiting files using X drag and drop. - (Reverting): Mention using Auto-Revert mode to tail files. - Document auto-revert-tail-mode. - (Version Systems): Minor correction. - (Comparing Files): Diff-mode is no longer based on Compilation - mode. - Document compare-ignore-whitespace. - (Misc File Ops): Explain passing a directory to rename-file. - Likewise for copy-file and make-symbolic-link. - - * frames.texi (Wheeled Mice): Mouse wheel support on by default. - Document mouse-wheel-progressive speed. - - * help.texi (Misc Help): Document numeric argument for C-h i. - Correctly explain the effect of just C-u as argument. - - * killing.texi (Deletion): Document numeric argument for - just-one-space. - - * mini.texi (Completion): Completion acts on text before point. - - * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager. - (Emulation): CUA mode replaces pc-bindings-mode, - pc-selection-mode, and s-region. - - * mule.texi (Input Methods): Leim is now built-in. - (Select Input Method): Document quail-show-key. - (Specify Coding): Document revert-buffer-with-coding-system. - - * programs.texi (Fortran Motion): Document f90-next-statement, - f90-previous-statement, f90-next-block, f90-previous-block, - f90-end-of-block, and f90-beginning-of-block. - - * text.texi (Format Faces): Replace old M-g key prefix with M-o. - - * emacs.texi (Acknowledgments): Updated. - - * anti.texi: Total rewrite. - -2005-03-20 Michael Albinus - - Sync with Tramp 2.0.48. - - * trampver.texi.in: Replace "Emacs" by "GNU Emacs". - - * tramp.texi: Replace "Emacs" by "GNU Emacs". Replace "Linux" by - "GNU/Linux". Change all addresses to .gnu.org. - (Default Method): Offer shortened syntax for "su" and "sudo" - methods. - -2005-03-19 Chong Yidong - - * ack.texi (Acknowledgments): Update. - -2005-03-19 Eli Zaretskii - - * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. Update - copyright years. - -2005-03-14 Nick Roberts - - * building.texi (Commands of GUD): Move paragraph on setting - breakpoints with mouse to the GDB Graphical Interface node. - -2005-03-07 Richard M. Stallman - - * url.texi: Fix usage of "e.g.". - (HTTP language/coding): Explain the rules for these strings. - - * misc.texi (Single Shell, Shell Options): Fix previous change. - - * building.texi (Debugger Operation): Update GUD tooltip enable info. - -2005-03-06 Richard M. Stallman - - * building.texi (Starting GUD): Don't explain text vs graphical - GDB here. Just mention it and xref. - Delete "just one debugger process". - (Debugger Operation): Move GUD tooltip info here. - (GUD Tooltips): Node deleted. - (GDB Graphical Interface): Explain the two GDB modes here. - - * woman.texi (Introduction): Minor cleanups. - - * url.texi (HTTP language/coding): Get rid of "Emacs 21". - - * sending.texi (Sending Mail): Minor cleanup. - (Mail Aliases): Explain quoting conventions. - Update key rebinding example. - (Header Editing): C-M-i is like M-TAB. - (Mail Mode Misc): mail-attach-file does not do MIME. - - * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes - that really belongs here. - (Remote Mailboxes): Text moved to Rmail Inbox. - (Rmail Display): Mention Mouse-1. - (Movemail): Clarify two movemail versions. - Clarify rmail-movemail-program. - - * pcl-cvs.texi (About PCL-CVS): Get rid of "Emacs 21". - (Installation): Node deleted. - - * misc.texi (Single Shell): Replace uudecode example with gpg example. - Document async shell commands. - (Shell History): Clarify. - (Shell Ring): Mention C-UP an C-DOWN. - (Shell Options): Add comint-prompt-read-only. - (Invoking emacsclient): Set EDITOR to run Emacs. - (Sorting): No need to explain what region is. - (Saving Emacs Sessions): Fix typo. - (Recursive Edit): Fix punctuation. - (Emulation): Don't mention "PC bindings" which are standard. - (Hyperlinking): Explain Mouse-1 convention here. - (Find Func): Node deleted. - - * mh-e.texi (Preface): Get rid of "Emacs 21". - - * help.texi (Name Help): Xref to Hyperlinking. - - * glossary.texi (Glossary): - Rename "Balance Parentheses" to "Balancing...". - Add "Byte Compilation". Correct "Copyleft". - New xref in "Customization". - Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar". - Add "Graphical Terminal" "Keybinding", "Margin", "Window System". - Rename "Registers" to "Register". - Replace "Selecting" with "Selected Frame", - "Selected Window", and "Selecting a Buffer". - - * files.texi (Types of Log File): Explain how projects' - methods can vary. - - * eshell.texi (Installation): Delete node (for Emacs 20). - - * display.texi (Faces): Delete "Emacs 21". - - * custom.texi (Changing a Variable): C-M-i like M-TAB. - * fixit.texi (Spelling): C-M-i like M-TAB. - * mini.texi (Completion Options): C-M-i like M-TAB. - * programs.texi (Symbol Completion): C-M-i like M-TAB. - * text.texi (Text Mode): C-M-i like M-TAB. - - * commands.texi (Keys): Mention F1 and F2 in list of prefixes. - - * calendar.texi (Specified Dates): Mention `g w'. - (Appointments): appt-activate toggles with no arg. - -2005-03-05 Thien-Thi Nguyen - - * flymake.texi: Refill and tweak style in @lisp blocks. - -2005-03-05 Juri Linkov - - * cmdargs.texi (Emacs Invocation): Add cindex - "invocation (command line arguments)" - (Misc X): Add -nbc, --no-blinking-cursor. - -2005-03-04 Ulf Jasper - - * calendar.texi (iCalendar): No need to require it now. - -2005-03-03 Reiner Steib - - * gnus.texi (Slow/Expensive Connection): Don't abbreviate "very". - -2005-03-03 Nick Roberts - - * trouble.texi (Contributing): Mention Savannah. Direct users to - emacs-devel. - -2005-03-01 Glenn Morris - - * calendar.texi (Adding to Diary): Mention redrawing of calendar - window. - -2005-03-01 Jay Belanger - - * calc.texi (Trigonometric and Hyperbolic Functions): - Mention additional functions. - (Algebraic Simplifications): Mention additional simplifications. - -2005-02-27 Richard M. Stallman - - * building.texi (Compilation): Update mode line status info. - -2005-02-27 Matt Hodges - - * calendar.texi (General Calendar): Document binding of - scroll-other-window-down. - (Mayan Calendar): Fix earliest date. - (Time Intervals): Document timeclock-change. - Fix timeclock-ask-before-exiting documentation. - -2005-02-26 Kim F. Storm - - * frames.texi (Mouse References): - Add mouse-1-click-in-non-selected-windows. - -2005-02-25 Richard M. Stallman - - * screen.texi (Screen): Explain better about cursors and mode lines; - don't presuppose text terminals. - (Point): Don't assume just one cursor. - Clarify explanation of cursors. - (Echo Area, Menu Bar): Cleanups. - - * mini.texi (Minibuffer): Prompts are highlighted. - (Minibuffer Edit): Newline = C-j only on text terminals. - Clarify resize-mini-windows values. - Mention M-PAGEUP and M-PAGEDOWN. - (Completion Commands): Mouse-1 like Mouse-2. - (Minibuffer History): Explain history commands better. - (Repetition): Add xref to Incremental Search. - - * mark.texi (Setting Mark): Clarify info about displaying mark. - Clarify explanation of C-@ and C-SPC. - (Transient Mark): Mention Delete Selection mode. - (Marking Objects): Clean up text about extending the region. - - * m-x.texi (M-x): One C-g doesn't always go to top level. - No delay before suggest-key-bindings output. - - * fixit.texi (Fixit): Mention C-/ for undo. - (Spelling): Mention ESC TAB like M-TAB. - Replacement words with r and R are rechecked. - Say where C-g leaves point. Mention ? as input. - -2005-02-23 Lute Kamstra - - * cmdargs.texi (Initial Options): Add cross reference. - -2005-02-18 Jonathan Yavner - - * ses.texi: Add concept/function/variable indices (this work was - donated by Brad Collins , copyright-assignment - papers on file at FSF). - -2005-02-16 Luc Teirlinck - - * emacs.texi (Top): Update menu for splitting of node in - msdog.texi. - * frames.texi (Frames): Update xref for splitting of node in - msdog.texi. - * trouble.texi (Quitting): Ditto. - -2005-02-16 Richard M. Stallman - - * windows.texi (Split Window): Simplify line truncation info - and xref to Display Custom. - - * trouble.texi (Quitting): Emergency escape only for text terminal. - (Screen Garbled): C-l for ungarbling is only for text terminal. - - * text.texi (Text Mode): ESC TAB alternative for M-TAB. - - * sending.texi (Header Editing): ESC TAB alternative for M-TAB. - - * programs.texi (Program Modes): Mention Python mode. - (Moving by Defuns): Repeating C-M-h extends region. - (Basic Indent): Clarify. - (Custom C Indent): Clarify. - (Expressions): Repeating C-M-@ extends region. - (Info Lookup): Clarify for C-h S. - (Symbol Completion): ESC TAB alternative for M-TAB. - (Electric C): Clarify. - - * emacs.texi (Top): Update display.texi and frames.texi submenu data. - - * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from - MS-DOS Input node. - (MS-DOS Keyboard): Start with explaining DEL and BREAK. - (MS-DOS and MULE): Clarify. - (MS-DOS Processes, Windows Processes): Fix typos. - - * major.texi (Choosing Modes): Clarify. - - * kmacro.texi (Basic Keyboard Macro): Doc F3, F4. - (Keyboard Macro Step-Edit): Clarify. - - * indent.texi (Indentation): Clarifications. - - * help.texi (Help): Correct error about C-h in query-replace. - Clarify apropos vs C-h a. Fix how to search in FAQ. - (Key Help): Describe C-h w here. - (Name Help): Minor cleanup. C-h w moved to Key Help. - Clarify the "object" joke. - (Apropos): Clarify. Mouse-1 like Mouse-2. - (Help Mode): Mouse-1 like Mouse-2. - - * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB. - - * display.texi (Display): Reorder menu. - (Faces): Cleanup. - (Font Lock): Cleanup. Mention Options menu. - Delete obsolete text. - (Scrolling): For C-l, don't presume text terminal. - (Horizontal Scrolling): Simplify intro. - (Follow Mode): Clarify. - (Cursor Display): Moved before Display Custom. - (Display Custom): Explain no-redraw-on-reenter is for text terminals. - Doc default-tab-width. Doc line truncation more thoroughly. - - * dired.texi (Dired Enter): C-x C-f can run Dired. - (Dired Visiting): Comment out `a' command. - Mouse-1 is like Mouse-2. - (Shell Commands in Dired): ? can be used more than once. - - * basic.texi (Continuation Lines): Simplify description of truncation, - and refer to Display Custom for the rest of it. - -2005-02-10 Jay Belanger - - * calc.texi: Change @LaTeX to La@TeX throughout. - Redefine @expr as @math for TeX output. - Redefine @texline as a no-op for TeX output. - Define @tfn, replace @t by @tfn throughout. - -2005-02-09 Jay Belanger - - * calc.texi: Add macro for LaTeX for info output. - -2005-02-08 Kim F. Storm - - * texinfo.tex (LaTex): Add def. - -2005-02-06 Jay Belanger - - * calc.texi (TeX Language Mode): Add mention of LaTeX mode, and - change name to "TeX and LaTeX Language Modes." Mention LaTeX mode - throughout manual. - -2005-02-06 Lute Kamstra - - * basic.texi (Undo): Fix typo. - - * cmdargs.texi (Emacs Invocation): Fix typo. - - * custom.texi (Init Examples): Fix typo. - - * abbrevs.texi (Expanding Abbrevs): Fix typo. - -2005-02-06 Richard M. Stallman - - * regs.texi (Registers): Registers can hold numbers, too. - - * killing.texi (Other Kill Commands): Cleanup. - Delete redundant explanation of kill in read-only buffer. - (Yanking): Mention term "copying". - (Accumulating Text): Fix typo. - - * entering.texi (Entering Emacs): Update rationale at start. - (Exiting): Treat iconifying on a par with suspension. - - * custom.texi (Minor Modes): Fix typo. - (Easy Customization): Fix menu style. - (Variables): Add xref. - (Examining): Setting for future sessions works through .emacs. - (Keymaps): "Text terminals", not "Many". - (Init Rebinding): Explain \C-. Show example of \M-. - Fix minor wording errors. - (Function Keys): Explain vector syntax just once. - (Named ASCII Chars): Clarify history of TAB/C-i connection. - (Init File): Mention .emacs.d directory. - (Init Examples): Add xref. - (Find Init): Mention .emacs.d directory. - - * cmdargs.texi (Emacs Invocation): +LINENUM is also an option. - (Action Arguments): Explain which kinds of -l args are found how. - (Initial Options): --batch does not inhibit site-start. - Add xrefs. - (Command Example): Use --batch, not -batch. - - * basic.texi (Inserting Text): Cleanup wording. - (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically. - C-n is not error at end of buffer. - (Undo): Doc C-/ like C-_. Add xrefs. - (Arguments): META key may be labeled ALT. - Peculiar arg meanings are explained in doc strings. - - * abbrevs.texi (Expanding Abbrevs): Clarify. - -2005-02-05 Eli Zaretskii - - * frames.texi (Frame Parameters): Add an xref to the description - of list-colors-display. Add a pointer to the X docs about colors. - - * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes. - Impove docs of list-colors-display. - -2005-02-03 Lute Kamstra - - * frames.texi (Frames, Drag and Drop): Fix typos. - -2005-02-03 Richard M. Stallman - - * windows.texi (Basic Window): Mention color-change in mode line. - (Change Window): Explain dragging vertical boundaries. - - * text.texi (Sentences): Clarify. - (Paragraphs): Explain M-a and blank lines. - (Outline Mode): Clarify text and menu. - (Hard and Soft Newlines): Mention use-hard-newlines. - - * frames.texi (Frames): Delete unnecessary mention of Windows. - (Mouse Commands): Likewise. Mention xterm mouse support. - (Clipboard): Clarify. - (Mouse References): Mention use of Mouse-1 for following links. - (Menu Mouse Clicks): Clarify. - (Mode Line Mouse): Clarify. - (Drag and Drop): Rewrite. - - * fixit.texi (Spelling): Fix typo. - - * files.texi (File Names): Clarify. - (Visiting): Update conditions for use of file dialog. Clarify. - (Saving): Doc d as answer in save-some-buffers. - (Remote Files): Clean up the text. - - * dired.texi (Misc Dired Commands): Delete dired-marked-files. - - * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer. - (List Buffers): Clarify. - (Several Buffers): Doc T command. - (Buffer Convenience): Clarify menu. - - * basic.texi (Undo): Clarify last change. - -2005-02-02 Matt Hodges - - * fixit.texi (Spelling): Fix typo. - -2005-02-01 Luc Teirlinck - - * basic.texi (Undo): Update description of `undo-outer-limit'. - -2005-02-01 Nick Roberts - - * building.texi: Update documentation relating to GDB Graphical - Interface. - -2005-01-30 Luc Teirlinck - - * custom.texi (Easy Customization): Adapt menu to node name change. - -2005-01-30 Richard M. Stallman - - * custom.texi (Easy Customization): Defn of "User Option" now - includes faces. Don't say just "option" when talking about variables. - Do say just "options" to mean "anything customizable". - (Specific Customization): Describe `customize-variable', - not `customize-option'. - - * glossary.texi (Glossary) : Add xref. - : Change definition--include faces. Change xref. - - * picture.texi (Picture): Mention artist.el. - - * sending.texi, screen.texi, programs.texi, misc.texi: - * mini.texi, major.texi, maintaining.texi, macos.texi: - * help.texi, frames.texi, files.texi: - Don't say just "option" when talking about variables. - - * display.texi, mule.texi: Don't say just "option" when talking - about variables. Other minor cleanups. - -2005-01-28 Lars Magne Ingebrigtsen - - * gnus.texi: Some edits based on comments from David Abrahams. - -2005-01-24 Katsumi Yamaoka - - * gnus.texi (RSS): Fix the keystroke. - -2005-01-26 Lute Kamstra - - * cmdargs.texi (Initial Options): Add a cross reference to `Init - File'. Mention the `-Q' option at the `--no-site-file' option. - -2005-01-24 David Kastrup - - * faq.texi: Update AUCTeX version info. - -2005-01-16 Xavier Maillard (tiny change) - - * gnus-faq.texi ([4.1]): Typo. - -2005-01-22 David Kastrup - - * building.texi (Grep Searching): Mention alias `find-grep' for - `grep-find'. - -2005-01-20 Richard M. Stallman - - * calendar.texi (Time Intervals): Delete special stuff for MS-DOS. - -2005-01-19 Jay Belanger - - * calc.texi (Keep Arguments): Mention that keeping arguments - doesn't work with keyboard macros. - -2005-01-16 Richard M. Stallman - - * autotype.texi (Autoinserting): Fix small error. - -2005-01-16 Michael Albinus - - Sync with Tramp 2.0.47. - - * tramp.texi (Compilation): New section, describing compilation of - remote files. - -2005-01-15 Sergey Poznyakoff - - * rmail.texi (Movemail): Explain differences - between standard and mailutils versions of movemail. - Describe command line and configuration options introduced - with the latter. - Explain the notion of mailbox URL, provide examples and - cross-references to mailutils documentation. - Describe various methods of specifying mailbox names, - user names and user passwords for rmail. - (Remote Mailboxes): New section. Describe - how movemail handles remote mailboxes. Describe configuration - options used to control its behavior. - (Other Mailbox Formats): Explain handling of various mailbox - formats. - -2005-01-13 Richard M. Stallman - - * commands.texi (Commands): Clarification. - -2005-01-11 Richard M. Stallman - - * programs.texi (Multi-line Indent): Fix previous change. - (Fortran Autofill): Simplify description of fortran-auto-fill-mode. - -2005-01-11 Kim F. Storm - - * widget.texi (Basic Types): Add :follow-link keyword. - -2005-01-09 Jay Belanger - - * calc.texi (Basic Commands): Describe new behavior of calc-reset. - -2005-01-08 Richard M. Stallman - - * display.texi (Faces): isearch-lazy-highlight-face renamed to - lazy-highlight. - - * search.texi (Query Replace): Mention faces query-replace - and lazy-highlight. - (Incremental Search): Update isearch highlighting info. - -2005-01-08 Jay Belanger - - * calc.texi: Change throughout to reflect new default value of - calc-settings-file. - -2005-01-06 Katsumi Yamaoka - - * message.texi (Reply): `message-reply-to-function' should return - a list. Suggested by ARISAWA Akihiro . - -2005-01-06 Hiroshi Fujishima (tiny change) - - * faq.texi (Changing load-path): Fix typo. - -2005-01-05 Jay Belanger - - * calc.texi (Programming Tutorial): Replace kbd command by - appropriate characters for a keyboard macro. - -2005-01-04 Jay Belanger - - * calc.texi (Basic Tutorial, Programming Tutorial): Remove caveats - for Lucid Emacs. - (Programming Tutorial): Mention that the user needs to be in the - right mode to compute some functions. - -2005-01-04 Richard M. Stallman - - * custom.texi (Saving Customizations): Minor improvement. - -2005-01-04 Jay Belanger - - * calc.texi (Rewrite rules): Remove an exercise (on 0^0) which is - no longer applicable. - -2005-01-03 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs no longer loads - `custom-file' after .emacs. No longer mention customizing through - Custom. - -2005-01-01 Jay Belanger - - * calc.texi (Programming Tutorial): Changed description of how to - edit keyboard macros to match current behavior. - -2005-01-01 Andreas Schwab - - * killing.texi (Graphical Kill): Move up under node Killing, - change @section to @subsection. - -2005-01-01 Richard M. Stallman - - * custom.texi (Face Customization): Mention hex color specs. - - * emacs.texi (Top): Update Killing submenu. - - * killing.texi (Killing): Reorganize section. - No more TeX-only text; put the node command at start of chapter. - But the first section heading is used only in TeX. - Rewrite the text to read better in this mode. - (Graphical Kill): New subnode gets some of the text that - used to be in the first section. - -2004-12-31 Richard M. Stallman - - * dired.texi (Shell Commands in Dired): Delete the ? example. - - * display.texi (Scrolling): Correct scroll-preserve-screen-position. - - * files.texi (Saving): Describe new require-final-newline features - and mode-require-final-newline. - -2004-12-31 Jay Belanger - - * calc.texi: Mention C-cC-c as the way to finish editing throughout. - -2004-12-29 Richard M. Stallman - - * custom.texi (File Variables): Clarify previous change. - -2004-12-27 Jan Dj,Ad(Brv - - * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is - out now. - -2004-12-27 Richard M. Stallman - - * Makefile.in (MAKEINFO): Specify --force. - - * basic.texi (Moving Point): C-e now runs move-end-of-line. - (Undo): Doc undo-outer-limit. - -2004-12-20 Jay Belanger - - * calc.texi (Types Tutorial): Emphasize that you can't divide by - zero. - -2004-12-17 Luc Teirlinck - - * cc-mode.texi (Text Filling and Line Breaking): Put period after - @xref. - (Font Locking): Avoid @strong{Note:}. - -2004-12-17 Michael Albinus - - Sync with Tramp 2.0.46. - - * tramp.texi (bottom): Add arch-tag. It was lost, somehow. - -2004-12-16 Luc Teirlinck - - * url.texi: Correct typos. - (Retrieving URLs): @var{nil}->@code{nil}. - (HTTP language/coding, mailto): Replace "GNU Emacs Manual" with - the standard "The GNU Emacs Manual" in fifth argument of @xref's. - (Dealing with HTTP documents): @inforef->@xref. - -2004-12-15 Juri Linkov - - * mark.texi (Transient Mark, Mark Ring): M-< and other - movement commands don't set mark in Transient Mark mode - if mark is active. - -2004-12-15 Jay Belanger - - * calc.texi: Consistently capitalized all mode names. - (Answers to Exercises): Mention that an answer can be a fraction - when in Fraction mode. - -2004-12-13 Jay Belanger - - * calc.texi: Fix some TeX definitions. - -2004-12-12 Juri Linkov - - * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d, - C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d. - - * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g. - (Misc Dired Commands): Add @r{(Dired)} to w. - -2004-12-12 Juri Linkov - - * mark.texi (Marking Objects): Marking commands also extend the - region when mark is active in Transient Mark mode. - -2004-12-09 Luc Teirlinck - - * reftex.texi (Imprint): Remove erroneous @value's. - -2004-12-08 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs only loads the custom - file automatically after the init file in version 22.1 or later. - Adapt text and examples to this fact. - - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, $(infodir)/org) - (org.dvi, $(infodir)/url, url.dvi, clean): Add org and url manuals. - -2004-12-08 Jay Belanger - - * calc.texi (Starting Calc): Remove comment about installation. - (Keypad Mode Overview): Remove comment about Emacs 19 support. - -2004-12-08 Luc Teirlinck - - * url.texi: Update @setfilename. - (Getting Started): No need to worry about Gnus versions. - (Dealing with HTTP documents): Use @inforef. - - * org.texi: Fix @direntry file name. - -2004-12-07 Luc Teirlinck - - * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to - be set through Custom. Otherwise, it has no effect. - -2004-12-07 Stefan - - * url.texi: New file. - - * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/url, url.dvi): Add it. - -2004-12-06 Jay Belanger - - * calc.texi (Using Calc): Remove paragraph about installation. - -2004-12-06 Jay Belanger - - * calc.texi: Use more Texinfo macros and less TeX defs. - Remove @refill's. - -2004-12-06 Richard M. Stallman - - * org.texi: New file. - -2004-12-05 Richard M. Stallman - - * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi: - * entering.texi: Rename Command Line to Emacs Invocation. - - * Makefile.in (org.dvi, ../info/org): New targets. - (INFO_TARGETS): Add ../info/org. - (DVI_TARGETS): Add org.dvi. - (maintainer-clean): Remove the info files in the info dir. - - * misc.texi (Term Mode): Correcty describe C-c. - - * custom.texi (Easy Customization): Move up to section level, - before Variables. Avoid using the term "variable"; say "option". - New initial explanation. - (Variables): In initial explanation, connect "variable" to the - already-explained "user option". - - * emacs.texi (Top): Fix ref to Command Line. - Move reference to Easy Customization. - - * xresources.texi (X Resources): Fix From link. - - * doclicense.texi (GNU Free Documentation License): Fix To link. - - * entering.texi (Entering Emacs): Fix xref, now to Command Line. - - * cmdargs.texi (Command Line): Node renamed from Command Arguments. - -2004-12-03 Richard M. Stallman - - * cmdargs.texi (Initial Options): Clarify batch mode i/o. - -2004-12-01 Luc Teirlinck - - * kmacro.texi: Several small changes in addition to the following. - (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when - defining a keyboard macro. - Mention `kmacro-ring-max'. - (Keyboard Macro Counter): Clarify description of - `kmacro-insert-counter', `kmacro-set-counter', - `kmacro-add-counter' and `kmacro-set-format'. - -2004-11-29 Reiner Steib - - * custom.texi (File Variables): Add `unibyte' and make it more - clear that `unibyte' and `coding' are special. Suggested by Simon - Krahnke . - - * mule.texi (Enabling Multibyte): Refer to File Variables. - Suggested by Simon Krahnke . - -2004-11-26 Jan Dj,Ad(Brv - - * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to - x-use-old-gtk-file-dialog. - -2004-11-26 Eli Zaretskii - - * idlwave.texi: Fix the setfilename directive to put the produced - file in ../info. - (Continued Statement Indentation): Resurrect Jan D.'s change from - 2004-11-03 that was lost when a newer version of idlwave.texi was - imported. - -2004-11-20 Richard M. Stallman - - * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line. - -2004-11-09 Lars Brinkhoff - - * building.texi (Lisp Eval): Delete hyphen in section name. - -2004-11-19 Thien-Thi Nguyen - - * files.texi (Old Versions): - No longer document annotation as "CVS only". - -2004-11-10 Andre Spiegel - - * files.texi (Version Control): Rewrite the introduction about - version systems, mentioning the new ones that we support. Thanks - to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for - suggestions. - -2004-12-08 Reiner Steib - - * gnus-faq.texi ([5.1]): Added missing bracket. - - * gnus.texi (Filtering Spam Using The Spam ELisp Package): Index - `spam-initialize'. - -2004-11-22 Reiner Steib - - * message.texi (Various Message Variables): Mention that all mail - file variables are derived from `message-directory'. - - * gnus.texi (Splitting Mail): Clarify bogus group. - -2004-11-02 Katsumi Yamaoka - - * emacs-mime.texi (Encoding Customization): Fix - mm-coding-system-priorities entry. - -2004-11-03 Jan Dj,Ad(Brv - - * frames.texi (Dialog Boxes): - * idlwave.texi (Continued Statement Indentation): - * reftex.texi (Options (Index Support)): - (Displaying and Editing the Index, Table of Contents): - * speedbar.texi (Creating a display, Major Display Modes): Replace - non-nil with non-@code{nil}. - -2004-11-02 Jan Dj,Ad(Brv - - * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog. - -2004-10-23 Eli Zaretskii - - * text.texi (Text Based Tables, Table Definition) - (Table Creation, Table Recognition, Cell Commands) - (Cell Justification, Row Commands, Column Commands) - (Fixed Width Mode, Table Conversion, Measuring Tables) - (Table Misc): New nodes, documenting the Table Mode. - -2004-10-21 Jay Belanger - - * calc.texi (Algebraic-Style Calculations): Removed a comment. - -2004-10-19 Jason Rumney - - * makefile.w32-in (info): Change order of arguments to makeinfo. - -2004-10-19 Ulf Jasper - - * calendar.texi (iCalendar): Update for package changes. - -2004-10-18 Luc Teirlinck - - * calc.texi (Reporting Bugs): Double up `@'. - -2004-10-18 Jay Belanger - - * calc.texi (Reporting Bugs): Changed the address that bugs - should be sent to. - -2004-10-15 Reiner Steib - - * gnus.texi (New Features): Add 5.11. - - * message.texi (Resending): Remove wrong default value. - - * gnus.texi (Mail Source Specifiers): Describe possible problems - of `pop3-leave-mail-on-server'. Add `pop3-movemail' and - `pop3-leave-mail-on-server' to the index. - -2004-10-15 Katsumi Yamaoka - - * message.texi (Canceling News): Add how to set a password. - -2004-10-12 Jay Belanger - - * calc.texi (Help Commands): Changed the descriptions of - calc-describe-function and calc-describe-variable to match their - current behavior. - -2004-10-12 Reiner Steib - - * gnus-faq.texi ([5.9]): Improve code for reply-in-news. - -2004-10-12 Michael Albinus - - Sync with Tramp 2.0.45. - - * tramp.texi (Frequently Asked Questions): Comment paragraph about - plink link. The URL is outdated. Originator contacted for - clarification. - -2004-10-10 Juri Linkov - - * gnus.texi (Top, Marking Articles): Join two menus in one node - because a node can have only one menu. - -2004-10-09 Luc Teirlinck - - * files.texi (Misc File Ops): View mode is a minor mode. - -2004-10-09 Juri Linkov - - * gnus.texi (Fancy Mail Splitting): Remove backslash in the - example of nnmail-split-fancy. - -2004-10-08 Glenn Morris - - * calendar.texi (iCalendar): Style changes. - -2004-10-07 Luc Teirlinck - - * search.texi (Regexps): The regexp described in the example is no - longer stored in the variable `sentence-end'. - -2004-10-06 Karl Berry - - * info.texi (@kbd{1}--@kbd{9}): No space around --, for - consistency with other uses of dashes. - -2004-10-06 Nick Roberts - - * building.texi (Starting GUD): Note that multiple debugging - sessions requires `gdb --fullname'. - -2004-10-05 Ulf Jasper - - * calendar.texi (iCalendar): New section for a new package. - -2004-10-05 Karl Berry - - * info.texi: Consistently use --- throughout, periods at end of - menu descriptions, and a couple typos. - -2004-10-05 Luc Teirlinck - - * text.texi: Various small changes in addition to the following. - (Text): Replace xref for autotype with inforef. - (Sentences): Explain nil value for `sentence-end'. - (Paragraphs): Update default values for `paragraph-start' and - `paragraph-separate'. - (Text Mode): Correct description of Text mode's effect on the - syntax table. - (Outline Visibility): `hide-other' does not hide top level headings. - `selective-display-ellipses' no longer has an effect on Outline mode. - (TeX Misc): Add missing @cindex. - Replace xref for RefTeX with inforef. - (Requesting Formatted Text): The variable - `enriched-fill-after-visiting' no longer exists. - (Editing Format Info): Update names of menu items and commands. - (Format Faces): Mention special effect of specifying the default face. - Describe inheritance of text properties. - Correct description of `fixed' face. - (Format Indentation): Correct description of effect of setting - margins. Mention `set-left-margin' and `set-right-margin'. - (Format Justification): Update names of menu items. - `set-justification-full' is now bound to `M-j b'. - Mention that `default-justification' is a per buffer variable. - (Format Properties): Update name of menu item. - (Forcing Enriched Mode): `format-decode-buffer' automatically - turns on Enriched mode if the buffer is in text/enriched format. - -2004-10-05 Emilio C. Lopes - - * calendar.texi (From Other Calendar): Add calendar-goto-iso-week. - -2004-09-28 Kim F. Storm - - * display.texi (Display Custom) : - Align with new functionality. - -2004-09-26 Jesper Harder - - * sieve.texi (Manage Sieve API): nil -> @code{nil}. - * pgg.texi (User Commands, Backend methods): Do. - * gnus.texi: Markup fixes. - (Setting Process Marks): Fix `M P a' entry. - * emacs-mime.texi: Fixes. - -2004-09-23 Reiner Steib - - * gnus-faq.texi ([5.12]): Fix code example for FQDN in Message-Ids - again. - Use 5.10 instead of 5.10.0. - -2004-09-20 Lars Magne Ingebrigtsen - - * gnus.texi (Summary Mail Commands): S D e. - -2004-09-20 Raymond Scholz (tiny change) - - * gnus.texi (Misc Article): Refer to `Summary Buffer Mode Line' in - the gnus-article-mode-line-format section. - -2004-09-20 Helmut Waitzmann (tiny change) - - * gnus.texi (Various Summary Stuff): Fix the documentation for - gnus-newsgroup-variables. - -2004-09-20 Reiner Steib - - * gnus.texi (MIME Commands): Added - gnus-mime-display-multipart-as-mixed, - gnus-mime-display-multipart-alternative-as-mixed, - gnus-mime-display-multipart-related-as-mixed. - (Mail Source Customization): Clarify `mail-source-directory'. - (Splitting Mail): Mention gnus-group-find-new-groups. - (SpamOracle): Fixed typo. - - * gnus-faq.texi: Untabify. - ([6.3]): nnir.el is in contrib directory. - - * message.texi (News Headers): Clarify how a unique ID is created. - - * gnus.texi (Batching Agents): Fixed typo in example. Reported - by Hiroshi Fujishima . - -2004-09-20 Andre Srinivasan - - * gnus.texi (Group Parameters): Added more on hooks. (Small - change.) - -2004-09-20 Florian Weimer - - * gnus.texi (Charsets): Point to relevant section in emacs-mime. - -2004-09-22 Luc Teirlinck - - * display.texi (Display Custom): Remove stray `@end defvar'. - -2004-09-23 Kim F. Storm - - * display.texi (Display Custom): Add `overflow-newline-into-fringe', - `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'. - -2004-09-22 Jay Belanger - - * calc.texi (Vectors as Lists): Added a warning that the tutorial - might be hidden during part of the session. - -2004-09-20 Jay Belanger - - * calc.texi (Notations Used in This Manual): Put in an earlier - mention that DEL could be called Backspace. - -2004-09-20 Richard M. Stallman - - * custom.texi (Hooks): Explain using setq to clear out a hook. - (File Variables): Explain multiline string constants. - (Non-ASCII Rebinding): Explain when you need to update - non-ASCII char codes in .emacs. - - * building.texi (Compilation): Explain how to make a silent - subprocess that won't be terminated. Explain compilation-environment. - -2004-09-13 Kim F. Storm - - * mini.texi (Repetition): Rename isearch-resume-enabled to - isearch-resume-in-command-history and change default to disabled. - -2004-09-10 Simon Josefsson - - * gnus.texi (IMAP): Add example. Suggested and partially written - by Steinar Bang . - -2004-09-10 Teodor Zlatanov - - * gnus.texi (IMAP): Add comments about imaps synonym to imap in - netrc syntax. - -2004-09-10 Teodor Zlatanov - - * gnus.texi (Spam ELisp Package Sequence of Events): Some clarifications. - (Spam ELisp Package Global Variables): More clarifications. - -2004-09-10 Teodor Zlatanov - - * gnus.texi (Spam ELisp Package Filtering of Incoming Mail): - Mention spam-split does not modify incoming mail. - -2004-09-10 Teodor Zlatanov - - * gnus.texi (Spam ELisp Package Sequence of Events): Fix typo. - -2004-09-10 Eli Zaretskii - - * Makefile.in (../info/gnus, gnus.dvi): Depend on gnus-faq.texi. - -2004-09-09 Kim F. Storm - - * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro' - with new `kmacro-name-last-macro'. - -2004-09-09 Reiner Steib - - * makefile.w32-in (sieve, pgg): Use $(infodir). - -2004-09-08 Juri Linkov - - * mini.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-08 Dhruva Krishnamurthy (tiny change) - - * makefile.w32-in: Fix PGG and Sieve entries. - -2004-09-03 Juri Linkov - - * search.texi (Incremental Search): Update wording for M-%. - -2004-09-02 Luc Teirlinck - - * killing.texi (Killing): Correct description of kill commands in - read-only buffer. - -2004-09-02 Teodor Zlatanov - - * building.texi (Compilation Mode): Add a paragraph about rules - for finding the compilation buffer for `next-error'. - - * search.texi (Other Repeating Search): Mention that Occur mode - supports the next-error functionality. - -2004-09-02 Juri Linkov - - * search.texi (Regexp Replace): Add missing backslash to \footnote. - -2004-08-31 Luc Teirlinck - - * kmacro.texi (Basic Keyboard Macro): - `apply-macro-to-region-lines' now operates on all lines that begin - in the region, rather than on all complete lines in the region. - -2004-08-31 Jan Dj,Ad(Brv - - * frames.texi (Drag and drop): Add documentation about - x-dnd-test-function and x-dnd-known-types. - -2004-08-30 Luc Teirlinck - - * indent.texi: Various minor changes in addition to: - (Indentation Commands): Correct description of `indent-relative'. - (Tab Stops): is no longer bound to `tab-to-tab-stop' in Text - mode. The *Tab Stops* buffer uses Overwrite Mode. - (Just Spaces): `tabify' converts sequences of at least two spaces - to tabs. - -2004-08-28 Eli Zaretskii - - * faq.texi (Emacs for MS-DOS): Update URLs for the MS-DOS port of - Emacs and related programs. - -2004-08-27 Luc Teirlinck - - * frames.texi (Secondary Selection): Setting the secondary - selection with M-Drag-Mouse-1 does not alter the kill ring, - setting it with M-Mouse-1 and M-Mouse-3 does. - (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for - toolkit scroll bars. - (Scroll Bars): Ditto. - - * windows.texi (Basic Window): When using a window system, the value - of point in a non-selected window is indicated by a hollow box. - (Split Window): Side by side windows are separated by a scroll bar, - if scroll bars are used. - C-Mouse-2 on scroll bar now also works for toolkit scroll bars. - (Change Window): Correct Mouse-2 vs Mouse-3 mess-up. - (Window Convenience): Update bindings for `winner-undo' and - `winner-redo'. - - * ack.texi (Acknowledgments): Use `@unnumbered'. - * misc.texi : Adapt sectioning in Info to the node structure. - (Invoking emacsclient): Make "Invoking emacsclient" a subsection - of "Using Emacs as a Server". - * building.texi (Building): Interchange nodes (for correct numbering). - * programs.texi (Programs): Interchange nodes (for correct numbering). - * killing.texi, entering.texi, commands.texi: Adapt sectioning in - Info to the node structure. - * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix. - Rearrange order of nodes and sections such that both "GNU GENERAL - PUBLIC LICENSE" and "GNU Free Documentation License" appear at the - end, as appropriate for appendices. - (Acknowledgments): Put inside @iftex instead of @ifnotinfo. - Use `@unnumberedsec'. - * trouble.texi: Adapt sectioning in Info to the node structure. - Adapt node pointers to change in emacs.texi. - * cmdargs.texi, doclicense.texi: Adapt node pointers. - -2004-08-27 Richard M. Stallman - - * faq.texi: Fix texinfo usage, esp. doublequotes. - (Difference between Emacs and XEmacs): Some clarification. - - * faq.texi (Difference between Emacs and XEmacs): - Explain not to contrast XEmacs with GNU Emacs. - -2004-08-26 Richard M. Stallman - - * faq.texi (Difference between Emacs and XEmacs): Rewrite. - -2004-08-25 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): Fix and simplify the - description for unibyte mode. - -2004-08-23 Luc Teirlinck - - * display.texi (Font Lock): Correct invalid (for hardcopy) @xref. - - * search.texi (Regexps): Correct cryptic (in hardcopy) @ref. - (Configuring Scrolling): Correct invalid (for hardcopy) @xref. - (Regexp Replace): Standardize reference to hardcopy Elisp Manual - in @pxref. - -2004-08-22 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit): - Change section names. - -2004-08-22 David Kastrup - - * reftex.texi (AUCTeX): Update links, section name. - - * faq.texi (Calc): Update availability (included in 22.1). - (AUCTeX): Update availability, information, versions, description. - -2004-08-21 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Ring): Rename section. - Emacs treats the head of the macro ring as the `last keyboard macro'. - (Keyboard Macro Counter): Minor change. - (Save Keyboard Macro): Some clarifications. - (Edit Keyboard Macro): Rename section. - - * buffers.texi (Buffers): Maximum buffer size is now 256M on - 32-bit machines. - (Several Buffers): Clarify which buffer is selected if `2' is - pressed in the Buffer Menu. - Auto Revert mode can be used to update the Buffer Menu - automatically. - -2004-08-21 Eli Zaretskii - - * help.texi (Misc Help): Add an index entry for finding an Info - manual by its file name. - -2004-08-20 Luc Teirlinck - - * files.texi (Backup Deletion): Correct description of - `delete-old-versions'. - (Time Stamps): `time-stamp' needs to be added to `before-save-hook'. - (Auto Save Files): Recommend `auto-save-mode' to reenable - auto-saving, rather than the abbreviation `auto-save'. - -2004-08-17 Luc Teirlinck - - * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms - for "killing" and "yanking" in main menu. - -2004-08-16 Richard M. Stallman - - * killing.texi (Yanking, Killing): Minor cleanups. - - * mark.texi (Momentary Mark): Minor cleanups. - -2004-08-15 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): - C-q always inserts the right code to pass to global-set-key. - -2004-08-14 Eli Zaretskii - - * Makefile.in (../info/tramp, tramp.dvi): Depend on trampver.texi. - -2004-08-13 Luc Teirlinck - - * regs.texi (RegNumbers): Mention `C-x r i' binding for - `insert-register', instead of `C-x r g' binding, for consistency. - -2004-08-12 Luc Teirlinck - - * fixit.texi (Spelling): Fix typo. - -2004-08-11 Luc Teirlinck - - * help.texi (Help): Fix Texinfo usage. - -2004-08-11 Martin Stjernholm - - * cc-mode.texi: Various updates for CC Mode 5.30.9. - -2004-08-10 Michael Albinus - - Sync with Tramp 2.0.44. - -2004-08-05 Lars Hansen - - * widget.texi (User Interface): Update how to separate the - editable field of an editable-field widget from other widgets. - (Programming Example): Add text after field. - -2004-07-24 Richard M. Stallman - - * text.texi (Paragraphs): Update how paragraphs are separated - and the default for paragraph-separate. - - * search.texi (Regexp Replace): Further update text for new - replacement operators. - -2004-08-31 Katsumi Yamaoka - - * emacs-mime.texi (Encoding Customization): Add a note to the - mm-content-transfer-encoding-defaults entry. - (rfc2047): Update. - - * gnus.texi (Article Highlighting): Add - gnus-cite-ignore-quoted-from. - (POP before SMTP): New node. - (Posting Styles): Addition. - (Splitting Mail): Add nnmail-split-lowercase-expanded. - (Fancy Mail Splitting): Ditto. - (X-Face): Add gnus-x-face. - -2004-08-30 Reiner Steib - - * emacs-mime.texi, gnus-faq.texi, gnus.texi, message.texi, - * pgg.texi, sieve.texi: Use @copying and @insertcopying. - -2004-08-22 Reiner Steib - - * gnus.texi (Mail Source Specifiers): Describe - `pop3-leave-mail-on-server'. - -2004-08-02 Reiner Steib - - * Makefile.in, makefile.w32-in: Added PGG and Sieve files. - - * pgg.texi, sieve.texi: Import from the v5_10 branch of the Gnus - repository. Change setfilename. - - * emacs-mime.texi, gnus-faq.texi, gnus.texi, message.texi: Ditto. - -2004-07-18 Luc Teirlinck - - * emacs-xtra.texi (Subdir switches): Dired does not remember the - `R' switch. - - * dired.texi (Dired Updating): `k' only deletes inserted - subdirectories from the Dired buffer if a prefix argument was given. - - * search.texi (Regexps): Delete redundant definition of `symbol' in - description of `\_>'. It already occurs in the description of `\_<'. - -2004-07-02 Juri Linkov - - * pcl-cvs.texi (Viewing differences): Add `d r'. - -2004-07-01 Juri Linkov - - * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e. - (Regexp Search): Add M-r. - -2004-06-30 Luc Teirlinck - - * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra. - -2004-06-29 Jesper Harder - - * ses.texi, viper.texi, search.texi, flymake.texi, faq.texi: - * eshell.texi, ediff.texi, calendar.texi: Markup fixes. - -2004-06-25 Richard M. Stallman - - * search.texi (Regexp Replace): Rewrite description of \# \, and \?. - -2004-06-25 David Kastrup - - * search.texi (Regexp Replace): Some typo corrections and - rearrangement. - -2004-06-24 David Kastrup - - * search.texi (Unconditional Replace): Use replace-string instead - of query-replace in example. - (Regexp Replace): Add explanations for `\,', `\#' and `\?' - sequences. - (Query Replace): Correct explanation of `^' which does not use - the mark stack. - -2004-06-21 Nick Roberts - - * misc.texi (Shell History Copying): Document comint-insert-input. - (Shell Ring): Describe comint-dynamic-list-input-ring here. - -2004-06-21 Karl Berry - - * info.texi (Top): Mention that only Emacs has mouse support. - (Getting Started): Mention this in a few other places. - -2004-06-20 Jesper Harder - - * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash. - * custom.texi (Customization): Do. - * anti.texi (Antinews): Do. - * abbrevs.texi (Defining Abbrevs): Do. - - * programs.texi (Info Lookup): Fix keybinding for - info-lookup-symbol. - -2004-06-16 Juanma Barranquero - - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES): - Add emacs-xtra. - ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies. - (clean): Add emacs-xtra and flymake. Remove redundancies. - -2004-06-15 Luc Teirlinck - - * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra): - Add emacs-xtra. - * emacs-xtra.texi: New file. - -2004-06-14 Luc Teirlinck - - * dired.texi (Dired Enter): Mention conditions on `ls' switches. - (Dired and Find): Mention differences with ordinary Dired buffers. - -2004-06-13 Luc Teirlinck - - * autotype.texi (Copyrights, Timestamps): Recommend - `before-save-hook' instead of `write-file-functions'. - -2004-06-13 Richard M. Stallman - - * custom.texi (Init Syntax): Explain about vars that do special - things when set with setq or with Custom. - (Init Examples): Add line-number-mode example. - -2004-06-13 Lars Hansen - - * dired-x.texi (dired-mark-omitted): Update keybinding. - -2004-06-12 Juri Linkov - - * dired.texi (Operating on Files): Add dired-do-touch. - -2004-06-10 Kim F. Storm - - * pcl-cvs.texi (Viewing differences): Add 'd y'. - -2004-06-10 Juri Linkov - - * building.texi (Lisp Eval): Add C-M-x on defface. - -2004-06-08 Luc Teirlinck - - * files.texi (Reverting): Auto-Revert mode and - Global Auto-Revert mode no longer revert remote files. - -2004-06-05 Lars Hansen - - * dired-x.texi (variable dired-omit-mode): Rename from - dired-omit-files-p. - (function dired-omit-mode): Rename from dired-omit-toggle. - Call dired-omit-mode rather than set dired-omit-files-p. - (dired-mark-omitted): Describe command. - -2004-05-29 Michael Albinus - - Version 2.0.41 of Tramp released. - -2004-05-29 Juanma Barranquero - - * makefile.w32-in (../info/flymake, flymake.dvi): New targets. - (INFO_TARGETS, DVI_TARGETS): Add Flymake. - -2004-05-29 Richard M. Stallman - - * custom.texi (Init File): Two dashes start --no-site-file. - - * cl.texi (Top): Call this chapter `Introduction'. - (Overview): In TeX, no section heading here. - - * cc-mode.texi: Put commas after i.e. and e.g. Minor cleanups. - -2004-05-29 Alan Mackenzie - - * programs.texi: Update for CC Mode 5.30 and incidental amendments. - ("AWK"): Is consistently thus spelt throughout. - (AWK, Pike): Document as "C-like modes". - (@kbd{M-j}): Document as alternative to @kbd{C-M-j}. - (M-x man): Supersedes M-x manual-entry. - Add numerous index entries. Correct "ESC a/e" to "M-a/e". - - ("Comments in C"): Delete node; the info is in CC Mode manual. - (c-comment-only-line-offset): Remove description. - - (C-c ., C-c C-c): Describe new C Mode bindings. - - (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent) - (@dfn{Style}, c-default-style, comment-column, comment-padding) - (c-up-conditional, c-beginning-of-statement, c-end-of-statement): - Amend definitions. - - (c-beginning-of-defun, c-end-of-defun, c-context-line-break): - Describe functions. - - (c-comment-start-regexp, c-hanging-comment-ender-p) - (c-hanging-comment-starter-p): Remove obsolete definitions. - - * emacs.texi: Remove the menu entry "Comments in C". - -2004-05-29 Eli Zaretskii - - * Makefile.in (../info/flymake, flymake.dvi): New targets. - (INFO_TARGETS, DVI_TARGETS): Add Flymake. - -2004-05-29 Pavel Kobiakov - - * flymake.texi: New file. - -2004-05-28 Simon Josefsson - - * smtpmail.texi (Authentication): Improve STARTTLS discussion. - -2004-05-27 Luc Teirlinck - - * dired.texi (Dired and Find): `find-ls-option' does not apply to - `M-x locate'. - -2004-05-16 Karl Berry - - * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo, - makeinfo --html fails. - * help.texi (Help Summary) [@ifnottex]: Likewise. - -2004-05-13 Nick Roberts - - * building.texi (GDB Graphical Interface): Update and describe - layout first. - -2004-05-07 Kai Grossjohann - - Version 2.0.40 of Tramp released. - -2004-04-25 Michael Albinus - - Complete rework, based on review by Karl Berry . - - * tramp.texi (Auto-save and Backup): Explain exploitation of new - variables `tramp-backup-directory-alist' and - `tramp-bkup-backup-directory-info'. - (Overview, Connection types) - (External transfer methods, Default Method) - (Windows setup hints): Remove restriction of password entering - with external methods. - (Auto-save and Backup): Make file name example - (X)Emacs neutral. In case of XEmacs, `bkup-backup-directory-info' - and `auto-save-directory' must be used. - (Frequently Asked Questions): Use "MS Windows NT/2000/XP" (not - only "NT"). Remove doubled entry "What kinds of systems does - @tramp{} work on". - (tramp): Macro removed. - (Obtaining Tramp): Flag removed from title. - (all): "tramp-" and "-" removed from flag names. Flags `tramp' - and `trampver' used properly. Flag `tramp-inst' replaced by - `installchapter'. Installation related text adapted. - -2004-05-04 Jason Rumney - - * makefile.w32-in: Revert last change. - -2004-05-03 Jason Rumney - - * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes. - -2004-04-28 Masatake YAMATO - - * widget.texi (Programming Example): Remove overlays. - -2004-04-27 Jesper Harder - - * faq.texi, viper.texi, dired-x.texi, autotype.texi: lisp -> Lisp. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Juri Linkov - - * fixit.texi (Spelling): Remove file extension from ispell xref. - -2004-04-15 Kim F. Storm - - * cmdargs.texi (Initial Options): Add -Q. - -2004-04-05 Kim F. Storm - - * custom.texi (File Variables): Add safe-local-eval-forms. - -2004-04-05 Jesper Harder - - * info.texi (Info Search): Add info-apropos. - -2004-04-02 Luc Teirlinck - - * files.texi (Reverting): Correct description of revert-buffer's - handling of point. - -2004-03-22 Juri Linkov - - * emacs.texi (Top): Add `Misc X'. - - * faq.texi, trouble.texi: Fix help key bindings. - - * glossary.texi: Improve references. - - * help.texi: Sync keywords with finder.el. - - * mini.texi (Completion): Add description for menu items. - - * misc.texi (Browse-URL, FFAP): Add information about keywords. - - * sending.texi (Mail Methods): Fix xref to Message manual. - -2004-03-17 Luc Teirlinck - - * info.texi (Advanced): Replace @unnumberedsubsec by @subheading - (as suggested by Karl Berry). Update information about colored - stars in menus. Add new subheading describing M-n. - -2004-03-12 Richard M. Stallman - - * cl.texi (Top): Rename top node's title. - - * buffers.texi (Misc Buffer): Add index entry for rename-uniquely. - -2004-03-08 Karl Berry - - * info.texi: \input texinfo.tex instead of just texinfo, to avoid - problems making the texinfo distribution. - -2004-03-04 Richard M. Stallman - - * search.texi (Regexps): Explain that ^ and $ have their - special meanings only in certain contexts. - - * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@. - - * mule.texi (Specify Coding): Doc C-x RET F. - - * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely - for multiple compile and grep buffers. - (Indirect Buffers): Don't recommand clone-indirect-buffer - for multiple compile and grep buffers. - -2004-02-29 Simon Josefsson - - * smtpmail.texi (Authentication): Changed the list of supported - authentication mechanisms from CRAM-MD5, PLAIN and LOGIN-MD5 to - CRAM-MD5 and LOGIN, tiny patch from Andreas Voegele - . - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (mostlyclean, clean, maintainer-clean): - Use $(DEL) instead of rm, and ignore exit code. - -2004-02-29 Kai Grossjohann - - Tramp version 2.0.39 released. - -2004-02-29 Michael Albinus - - * tramp.texi (Customizing Completion): Explain new functions - `tramp-parse-shostkeys' and `tramp-parse-sknownhosts'. - (all): Savannah URLs unified to "http://savannah.nongnu.org". - (Top): Refer to Savannah mailing list as the major one. Mention - older mailing lists in HTML mode only. - (Auto-save and Backup): Add auto-save. Based on wording of Kai. - (Frequently Asked Questions): Remote hosts must not be Unix-like - for "smb" method. - (Password caching): New node. - (External transfer methods): Refer to password caching for "smb" - method. - -2004-02-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2004-02-21 Juri Linkov - - * cmdargs.texi (Action Arguments): Add alias --find-file. Add - --directory, --help, --version. Move text about command-line-args - to Command Arguments. - (Initial Options): Add @cindex for --script. Fix @cindex for -q. - Add --no-desktop. Add alias --no-multibyte, --no-unibyte. - (Window Size X): Join -g and --geometry. Add @cindex. - (Borders X): Fix @cindex for -ib. Add @cindex for -bw. - (Title X): Remove alias -title. - (Misc X): New node. - -2004-02-17 Karl Berry - - * info.texi (Help-Int): Mention the new line number feature. - -2004-02-15 Jan Dj,Ad(Brv - - * frames.texi (Drag and drop): Add Motif to list of supported - protocols. - -2004-02-14 Jonathan Yavner - - * ses.texi (Advanced Features): New functionality for - ses-set-header-row (defaults to current row unless C-u used). - (Acknowledgements): Add Stefan Monnier. - -2004-02-03 Jan Dj,Ad(Brv - - * frames.texi (Drag and drop): New section. - -2004-01-24 Richard M. Stallman - - * emacs.texi (Acknowledgments): Renamed from Acknowledgements. - Include it only @ifnotinfo. Patch the preceding and following - node headers to point to each other. - -2004-01-11 Glenn Morris - - * calendar.texi (Appointments): Update section. - -2003-12-29 Kevin Ryde - - * viper.texi (Vi Macros): Fix reference to the Emacs manual. - - * programs.texi (C Modes): Fix the xref. - -2003-12-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - (Commands of GUD): Include use of toolbar + breakpoints set from - fringe/margin. - -2003-12-03 Andre Spiegel - - * files.texi: Say how to disable VC. Suggested by Alan Mackenzie - . - -2003-11-30 Kai Grossjohann - - Tramp version 2.0.38 released. - - * tramp.texi (Remote shell setup): Warn of environment variables - FRUMPLE if user frumple exists. Suggested by Sven Gabriel - . - (Configuration): Tramp now chooses base64/uuencode - automatically. Update wording accordingly. - (Top): More description for the `Default Method' menu entry. - (Default Method): Use @code, not @var, for Lisp variables. - (Default Method): New subsection `Which method is the right one - for me?' Suggested by Christian Kirsch. - (Configuration): Pointer to new subsection added. - (Default Method): Too many "use" in one sentence. - Rephrase. Reported by Christian Kirsch. - (Filename Syntax): Old `su' example is probably a left-over from - the sm/su method naming. Replace with `ssh', instead. - (External transfer methods, Auto-save and Backup): - Typo fixes. - -2003-11-02 Michael Albinus - - * tramp.texi (all): Harmonize all occurences of @tramp{}. - (Top): Mention japanese manual only if flag `jamanual' is set. - Insert section `Japanese manual' in menu. - -2003-11-29 Jan Dj,Ad(Brv - - * frames.texi (Dialog Boxes): Add use-file-dialog. - -2003-11-26 Thien-Thi Nguyen - - * eshell.texi (Known Problems): Add doc item. - -2003-11-22 Martin Stjernholm - - * ack.texi: Note that Alan Mackenzie contributed the AWK support - in CC Mode. - -2003-11-22 Martin Stjernholm - - * cc-mode.texi: Update for CC Mode 5.30. - - Note: Please refrain from doing purely cosmetic changes like - removing trailing whitespace in this manual; it clobbers cvs - merging for no good reason. - -2003-11-02 Jesper Harder (tiny change) - - * man/ack.texi, man/basic.texi, man/cmdargs.texi: - * man/commands.texi, man/custom.texi, man/display.texi: - * man/ediff.texi, man/emacs.texi, man/faq.texi, man/files.texi: - * man/frames.texi, man/glossary.texi, man/killing.texi: - * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi: - * man/mule.texi, man/rmail.texi, man/search.texi: - * man/sending.texi, man/text.texi, man/tramp.texi: - * man/trouble.texi, man/vip.texi, man/viper.texi, man/widget.texi: - * man/woman.texi: Replace @sc{ascii} and ASCII with @acronym{ASCII}. - -2003-11-01 Alan Mackenzie - - * search.texi (Scrolling During Incremental Search): Document a - new scrolling facility in isearch mode. - -2003-10-26 Karl Berry - - * info.texi (Info Search): Echo area, not echo are. From Debian - diff. - -2003-10-26 Per Abrahamsen - - * widget.texi (Defining New Widgets): Document new beavior of - :buttons and :children keywords. - -2003-10-22 Miles Bader - - * Makefile.in (info): Move before $(top_srcdir)/info. - -2003-10-22 Nick Roberts - - * building.texi (Watch Expressions): Update section on data display - to reflect code changes (GDB Graphical Interface). - -2003-10-17 Thien-Thi Nguyen - - * tramp.texi (Inline methods): Small grammar fix. - (External transfer methods): Likewise. - -2003-10-13 Richard M. Stallman - - * xresources.texi (GTK resources): Clean up previous change. - -2003-10-12 Jan Dj,Ad(Brv - - * xresources.texi (GTK resources): Add a note that some themes - disallow customizations. Add scroll theme example. - -2003-10-08 Nick Roberts - - * speedbar.texi: Remove paragraph for GUD that is no longer true. - -2003-10-06 Luc Teirlinck - - * texinfo.tex: Replace `%' in arch tagline by @ignore. - -2003-09-30 Richard M. Stallman - - * dired-x.texi (Miscellaneous Commands): Delete M-g, w, T. - - * widget.texi (User Interface): Fix typos. - - * pcl-cvs.texi, cl.texi, woman.texi, ediff.texi: Fix @strong{Note:}. - - * cmdargs.texi (General Variables): Remove MAILRC envvar. - - * misc.texi (Saving Emacs Sessions): Shorten the section, - collapsing back into one node. - -2003-09-30 Lars Hansen - - * misc.texi: Section "Saving Emacs Sessions" rewritten. - -2003-09-29 Jan Dj,Ad(Brv. - - * xresources.texi (GTK names in Emacs): Correct typo. - -2003-09-29 Thien-Thi Nguyen - - * pcl-cvs.texi (Selected Files): Fix typo. - -2003-09-24 Luc Teirlinck - - * cmdargs.texi (Font X): Mention new default font. More - fully describe long font names, wildcard patterns and the - problems involved. (Result of discussion on emacs-devel.) - -2003-09-22 Luc Teirlinck - - * emacs.texi (Acknowledgements): Correct typo. - -2003-09-22 Richard M. Stallman - - * dired.texi (Misc Dired Commands): New node. - (Dired Navigation): Add dired-goto-file. - - * files.texi (File Aliases, Misc File Ops): Add @cindex entries. - - * emacs.texi (Acknowledgements): New node, split from Distribution. - - * cmdargs.texi (Action Arguments): -f reads interactive args. - -2003-09-21 Karl Berry - - * info.texi (] and [ commands): No period at end of section title. - -2003-09-08 Lute Kamstra - - * screen.texi (Mode Line): Say that POS comes before LINE. - Mention `size-indication-mode'. - * display.texi (Optional Mode Line): Document - `size-indication-mode'. - * basic.texi (Position Info): Mention `size-indication-mode'. - -2003-09-07 Luc Teirlinck - - * xresources.texi (Resources): Refer to `editres' man page. - (Lucid Resources): Update defaults. Expand description of - `shadowThickness'. - -2003-09-04 Miles Bader - - * Makefile.in (top_srcdir): New variable. - ($(top_srcdir)/info): New rule. - (info): Depend on it. - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Correct previous change. - -2003-08-26 Per Abrahamsen - - * widget.texi (User Interface): Explain the need of static text - around an editable field. - -2003-08-19 Luc Teirlinck - - * widget.texi (Basic Types): The argument to `:help-echo' can now - be a form that evaluates to a string. - - * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter. - (Intro): Include kmacro.texi after fixit.texi instead of after - custom.texi. (As suggested by Kim Storm.) - -2003-08-18 Luc Teirlinck - - * fixit.texi (Fixit): Update `Next' pointer. - * files.texi (Files): Update `Previous' pointer. - * kmacro.texi (Keyboard Macros): Remove redundant node and section. - * emacs.texi (Intro): Include kmacro.texi after custom.texi. - (Suggested by Kim Storm.) - * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.) - -2003-08-18 Kim F. Storm - - * kmacro.texi: New file describing enhanced keyboard macro - functionality. Replaces old description in custom.texi. - - * custom.texi (Customization): Add xref to Keyboard Macros chapter. - (Keyboard Macros): Move to new kmacro.texi file. - - * emacs.texi (Keyboard Macros): Reference new keyboard macro topics. - - * calc.texi (Queries in Macros): Update xref to keyboard macro query. - -2003-08-17 Edward M. Reingold - - * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'. - -2003-08-17 Alex Schroeder - - * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not - required. - -2003-08-16 Richard M. Stallman - - * dired-x.texi (Shell Command Guessing): Explain *. - -2003-08-16 Chunyu Wang (tiny change) - - * pcl-cvs.texi (Log Edit Mode): Fix key binding for - log-edit-insert-changelog. - -2003-08-05 Richard M. Stallman - - * programs.texi (Lisp Indent): Don't describe - lisp-indent-function property here. Use xref to Lisp Manual. - -2003-08-03 Karl Berry - - * info.texi: Need @contents. - -2003-08-03 Glenn Morris - - * calendar.texi (Date Formats): Document changed behaviour of - abbreviations. - -2003-07-24 Markus Rost - - * buffers.texi (List Buffers): Fix previous change. - -2003-07-20 Kai Gro,A_(Bjohann - - Tramp version 2.0.36 released. - - * tramp.texi (Remote shell setup): Explain about problems with - non-Bourne commands in ~/.profile and ~/.shrc. - -2003-07-13 Markus Rost - - * buffers.texi (List Buffers): Adjust to new format of *Buffer - List*. - -2003-07-07 Luc Teirlinck - - * info.texi (Help-Inv, Help-M, Help-Xref): Update following - renaming of `vis-mode' to `visible-mode'. - - * display.texi (Font Lock): Fix typo. - -2003-07-07 Richard M. Stallman - - * display.texi (Font Lock): Add xref for format info on - font-lock-remove-keywords. - - * building.texi (Compilation): Document what happens with asynch - children of compiler process. - - * help.texi (Library Keywords): Use @multitable. - -2003-07-04 Luc Teirlinck - - * info.texi (Top, Help-Small-Screen): Remove accidentally added - next, prev and up pointers. - -2003-07-02 Luc Teirlinck - - * info.texi (Help): Mention existence of Emacs and stand-alone - Info at the very beginning of the tutorial. - (Help-Inv): New node. - (Help-]): New node. - (Help-M): Systematically point out the differences between default - Emacs and stand-alone versions. Delete second menu. - (Help-Xref): Systematically point out the differences between - default Emacs and stand-alone versions. - (Help-Int): Change `l' example. - (Expert Info): Fix typos. - (Emacs Info Variables): Mention `Info-hide-note-references' and - new default for `Info-scroll-prefer-subnodes'. - -2003-06-17 Kai Gro,A_(Bjohann - - Version 2.0.35 of Tramp released. - - * tramp.texi: From Michael Albinus : - (Inline methods): Add methods `remsh' and `plink1'. - (External transfer methods): Add method `remcp'. - (Multi-hop Methods): Add method `remsh'. - Small patch from Adrian Aichner : - Fix minor typos. - (Concept Index): Added to make manual searchable via - `Info-index'. - (Version Control): Add cindex entry. - -2003-06-04 Richard M. Stallman - - * programs.texi (Expressions): Delete C-M-DEL. - - * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output. - comint-move-point-for-output renamed from - comint-scroll-to-bottom-on-output. - - * custom.texi (Init Rebinding): Replace previous change with xref. - (Non-ASCII Rebinding): Explain that issue more briefly here. - -2003-05-28 Richard M. Stallman - - * indent.texi (Indentation): Condense, simplify, clarify prev change. - -2003-05-28 Nick Roberts - - * building.texi (GDB Graphical Interface): New node. - (Rewritten somewhat by RMS.) - -2003-05-28 Kai Gro,A_(Bjohann - - * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for - non-English letters. Explain how to set coding systems correctly - and how to include the right coding cookie in the file. - -2003-05-24 Kai Gro,A_(Bjohann - - * trampver.texi: Version 2.0.34 released. - -2003-05-22 Kai Gro,A_(Bjohann - - * indent.texi (Indentation): Explain the concepts. - (Just Spaces): Explain why preventing tabs for indentation might - be useful. - -2003-05-03 Glenn Morris - - * faq.texi: Improve previous changes. - -2003-05-02 Glenn Morris - - * faq.texi: Update copyright and maintenance details. - Update some package URLs, versions, and maintainers. - Remove many references to the Emacs Lisp Archive. - -2003-04-23 Simon Josefsson - - * smtpmail.texi: Fix license (the invariant sections mentioned has - never been part of the smtp manual). Align info dir entry with - other emacs packages. - -2003-04-16 Richard M. Stallman - - * search.texi (Regexps): Ref to Lisp manual for more regexp features. - -2003-04-08 Michael Albinus - - * tramp.texi: Version 2.0.33 released. - Remove installation chapter. Remove XEmacs specifics. - -2003-03-29 Richard M. Stallman - - * tramp.texi (Top): Undo the previous renaming. - (emacs-other-name, emacs-other-dir, emacs-other-file-name): Delete. - -2003-03-29 Kai Gro,A_(Bjohann - - * Makefile.in (../info/tramp): Compile Emacs, instead of XEmacs, - version of manual. - - * tramp.texi (Auto-save and Backup): New node. - -2003-03-29 Michael Albinus - - * tramp.texi (Top): Include trampver.texi. Rename "Emacs" to "GNU - Emacs" in order to have better differentiation to "XEmacs". - `emacs-other-name', `emacs-other-dir' and `emacs-other-file-name' - are new macros in order to point to the other Emacs flavor where - appropriate. In info case, point to node `Installation' in order - to explain how to generate the other way. In html case, make a - link to the other html file. - (Obtaining TRAMP): Added a paragraph saying to perform `autoconf' - after CVS checkout/update. - (Installation): Completely rewritten. - (Installation parameters, Load paths): New sections under - `Installation'. - -2003-02-28 Kai Gro,A_(Bjohann - - * tramp.texi: Version 2.0.30 released. - Replace word "path" with "localname" where used as a component of - a Tramp file name. - -2003-02-28 Michael Albinus - - * tramp.texi (Frequently Asked Questions): `tramp-chunksize' - introduced. - (Installation): Explain what to do if files from the tramp/contrib - directory are needed. - -2003-02-23 Alex Schroeder - - * smtpmail.texi (How Mail Works): New. - -2003-02-22 Alex Schroeder - - * cmdargs.texi (General Variables): Document SMTPSERVER. - - * smtpmail.texi: New file. - - * sending.texi: Remove SMTP node. - (Mail Sending): Describe `send-mail-function'. Link to SMTP - library. - - * Makefile.in: Build SMTP manual. - -2003-02-22 Alex Schroeder - - * sending.texi (Sending via SMTP): Explain MTA/MUA. - -2003-02-22 Simon Josefsson - - * sending.texi (Mail Methods): Add node about SMTP. - -2003-02-17 Jan Dj,Ad(Brv - - * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar. - -2003-02-05 Kai Gro,A_(Bjohann - - * tramp.texi: Version 2.0.29 released. - (Installation): In Emacs, use M-x texinfo-format-buffer RET, not - M-x makeinfo-buffer RET. Reported by gebser@ameritech.net. - -2003-02-01 Michael Albinus - - * tramp.texi (Frequently Asked Questions): Explain a workaround if - another package loads accidently Ange-FTP. - -2003-01-24 Michael Albinus - - * tramp.texi (Customizing Completion): Add function - `tramp-parse-sconfig'. Change example of - `tramp-set-completion-function', because parsing of ssh config - files looks more natural. - -2003-02-01 Kevin Ryde - - * glossary.texi (Glossary): Correction to cl cross reference. - -2003-01-20 Richard M. Stallman - - * killing.texi (Rectangles): Document C-x c r. - -2003-01-19 Jan Dj,Ad(Brv - - * xresources.texi (GTK resources): New node. - (GTK widget names): New node. - (GTK names in Emacs): New node. - (GTK styles): New node. - -2003-01-15 ShengHuo ZHU - - * gnus.texi: Do not use `path' in several locations. - -2003-01-09 Francesco Potort,Al(B - - * maintaining.texi (Create Tags Table): Add reference to the new - `etags --help --lang=LANG' option. - -2002-12-26 Kai Gro,A_(Bjohann - - * tramp.texi (External transfer methods): New method `smb'. From - Michael Albinus. - -2002-11-05 Karl Berry - - * info.texi (Info-fontify): Reorder face list to avoid bad line - breaks. - -2002-10-06 Kai Gro,A_(Bjohann - - * tramp.texi: Move @copying to standard place. Use - @insertcopying. - -2002-10-02 Karl Berry - - * (ada-mode.texi autotype.texi calc.texi cc-mode.texi cl.texi - dired-x.texi ebrowse.texi ediff.texi emacs-mime.texi emacs.texi - eshell.texi eudc.texi faq.texi forms.texi idlwave.texi info.texi - message.texi mh-e.texi pcl-cvs.texi reftex.texi sc.texi ses.texi - speedbar.texi vip.texi viper.texi widget.texi woman.texi): - Per rms, update all manuals to use @copying instead of @ifinfo. - Also use @ifnottex instead of @ifinfo around the top node, where - needed for the sake of the HTML output. - (The Gnus manual is not fixed since it's not clear to me how it - works; and the Tramp manual already uses @copying, although in an - unusual way. All others were changed.) - -2002-09-10 Jonathan Yavner - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add SES. - (../info/ses, ses.dvi): New targets. - * ses.texi: New file. - -2002-09-06 Pavel Jan,Am(Bk - - * texinfo.tex: Update to texinfo 4.2. - -2002-08-27 Carsten Dominik - - * reftex.texi: Update to RefTeX 4.19. - -2002-06-17 Kai Gro,A_(Bjohann - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add Tramp. - (../info/tramp, tramp.dvi): New targets. - -2002-01-04 Eli Zaretskii - - * Makefile.in (DVI_TARGETS): Add calc.dvi. - (calc.dvi): Uncomment. - -2001-12-20 Eli Zaretskii - - * Makefile.in (EMACSSOURCES): Update the list of Emacs manual - source files. - -2001-11-16 Eli Zaretskii - - * Makefile.in (emacsman): New target. - -2001-11-07 Eli Zaretskii - - * Makefile.in (INFO_TARGETS): Add ../info/calc. - (../info/calc): New target. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-05 Gerd Moellmann - - * Branch for 21.1. - -2001-04-14 Eli Zaretskii - - * Makefile.in (../info/info): Use an explicit -o switch to - makeinfo. - -2001-03-05 Gerd Moellmann - - * Makefile.in (mostlyclean, maintainer-clean): Delete more files. - -2000-12-20 Eli Zaretskii - - * Makefile.in (../info/idlwave): Use --no-split. - -2000-12-14 Dave Love - - * Makefile.in (mostlyclean): Remove gnustmp.* - (gnus.dvi): Change rule to remove @latex stuff. - -2000-10-19 Eric M. Ludlam - - * Makefile.in (Speedbar): Add build targets for speedbar.texi. - -2000-10-13 John Wiegley - - * Makefile.in: Add build targets for eshell.texi. - -2000-09-25 Gerd Moellmann - - * Makefile.in: Remove/comment speedbar stuff. - -2000-09-22 Dave Love - - * Makefile.in: Add emacs-mime. - -2000-08-08 Eli Zaretskii - - * Makefile.in (INFO_TARGETS): Add ../info/woman. - (DVI_TARGETS): Add woman.dvi. - (../info/woman, woman.dvi): New targets. - -2000-05-31 Stefan Monnier - - * .cvsignore (*.tmp): New entry. Seems to be used for @macro. - - * pcl-cvs.texi: New file. - * Makefile.in (INFO_TARGETS, DVI_TARGETS: Add pcl-cvs. - (../info/pcl-cvs, pcl-cvs.dvi): New targets. - -2000-05-11 Gerd Moellmann - - * Makefile.in (INFO_TARGETS): Add info/ebrowse. - (../info/ebrowse, ebrowse.dvi): New targets. - -2000-01-13 Gerd Moellmann - - * Makefile.in (INFO_TARGETS): Add eudc. - (DVI_TARGETS): Add eudc.dvi. - (../info/eudc, eudc.dvi): New targets. - -2000-01-05 Eli Zaretskii - - * Makefile.in (INFO_TARGETS): Rename emacs-faq to efaq (for - compatibility with 8+3 filesystems). - (../info/efaq): Rename from emacs-faq. - -2000-01-03 Eli Zaretskii - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add idlwave. - (../info/idlwave, idlwave.dvi): New targets. - -1999-10-23 Dave Love - - * Makefile.in: Use autotype.texi. - -1999-10-12 Stefan Monnier - - * Makefile.in (faq): Use ../info/emacs-faq.info (as specified in the - faq.texi file) rather than ../info/faq. - -1999-10-07 Gerd Moellmann - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add ada-mode. - (../info/ada-mode, ada-mode.dvi): New targets. - -1999-09-01 Dave Love - - * Makefile.in: Add faq. - -1999-07-12 Richard Stallman - - * Version 20.4 released. - -1998-12-04 Markus Rost - - * Makefile.in (INFO_TARGETS): Delete customize.info. - (DVI_TARGETS): Delete customize.dvi. - (../info/customize, customize.dvi): Targets deleted. - -1998-08-19 Richard Stallman - - * Version 20.3 released. - -1998-05-06 Richard Stallman - - * Makefile.in (EMACSSOURCES): Add mule.texi. - Add msdog.texi, ack.texi. Remove gnu1.texi. - -1998-04-06 Andreas Schwab - - * Makefile.in (ENVADD): Enviroment vars to pass to texi2dvi. Use - it in dvi targets. - (../etc/GNU): Change to $(srcdir) first. - -1998-03-11 Carsten Dominik - - * reftex.texi: Update for RefTeX version 3.22. - -1998-02-08 Richard Stallman - - * Makefile.in (reftex.dvi, ../info/reftex): New targets. - (INFO_TARGETS, DVI_TARGETS): Add the new targets. - -1997-09-23 Paul Eggert - - * Makefile.in: Merge changes mistakenly made to `Makefile'. - (INFO_TARGETS): Change ../info/custom to ../info/customize. - (../info/customize): Rename from ../info/custom. - (../info/viper, viper.dvi): Remove dependency on viper-cmd.texi. - -1997-09-19 Richard Stallman - - * Version 20.2 released. - -1997-09-15 Richard Stallman - - * Version 20.1 released. - -1997-08-24 Richard Stallman - - * Makefile (../info/customize, customize.dvi): New targets. - (INFO_TARGETS): Add ../info/customize. - (DVI_TARGETS): Add customize.dvi. - -1997-07-10 Richard Stallman - - * Makefile (../info/viper, viper.dvi): Delete viper-cmd.texi dep. - -1996-08-11 Richard Stallman - - * Version 19.33 released. - -1996-07-31 Richard Stallman - - * Version 19.32 released. - -1996-06-27 Lars Magne Ingebrigtsen - - * Makefile.in: Add rules for the Message manual. - -1996-06-26 Lars Magne Ingebrigtsen - - * gnus.texi: New version. - - * message.texi: New manual. - -1996-06-20 Richard Stallman - - * Makefile.in (All info targets): cd $(srcdir) to do the work. - -1996-06-19 Richard Stallman - - * Makefile.in (All info targets): Specify $(srcdir) in input files. - Specify -I option. - (All dvi targets): Set the TEXINPUTS variable. - -1996-05-25 Karl Heuer - - * Version 19.31 released. - -1996-01-07 Richard Stallman - - * Makefile.in (../info/ccmode): Rename from ../info/cc-mode. - (INFO_TARGETS): Use new name. This avoids name conflict on MSDOS. - -1995-11-29 Richard Stallman - - * Makefile.in (../info/cc-mode, cc-mode.dvi): New targets. - (INFO_TARGETS): Add ../info/cc-mode. - (DVI_TARGETS): Add cc-mode.dvi. - -1995-11-24 Richard Stallman - - * Version 19.30 released. - -1995-11-04 Lars Magne Ingebrigtsen - - * gnus.texi: New file. - -1995-11-04 Erik Naggum - - * gnus.texi: File deleted. - -1995-11-02 Stephen Gildea - - * mh-e.texi: "Function Index" -> "Command Index" to work with - Emacs 19.30 C-h C-k support of separately-documented commands. - -1995-06-26 Richard Stallman - - * Makefile.in (../info/ediff, ediff.dvi): New targets. - (INFO_TARGETS, DVI_TARGETS): Add those new targets. - -1995-04-24 Richard Stallman - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add viper targets. - (../info/viper, viper.dvi): New targets. - -1995-04-20 Kevin Rodgers - - * dired-x.texi (Installation): Change the example to set - buffer-local variables like dired-omit-files-p in - dired-mode-hook. - -1995-04-17 Richard Stallman - - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add mh-e targets. - (../info/mh-e, mh-e.dvi): New targets. - -1995-02-07 Richard Stallman - - * Makefile.in (maintainer-clean): Rename from realclean. - -1994-11-23 Richard Stallman - - * Makefile.in: New file. - * Makefile: File deleted. - -1994-11-19 Richard Stallman - - * Makefile (TEXINDEX_OBJS): Variable deleted. - (texindex, texindex.o, getopt.o): Rules deleted. - All deps on texindex deleted. - (distclean): Don't delete texindex. - (mostlyclean): Don't delete *.o. - * texindex.c, getopt.c: Files deleted. - -1994-09-07 Richard Stallman - - * Version 19.26 released. - -1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu) - - * Makefile (EMACSSOURCES): Exclude undo.texi. - -1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.25 released. - -1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.24 released. - -1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.23 released. - -1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Delete spurious tab. - -1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (.SUFFIXES): New rule. - -1994-01-15 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (dired-x.dvi, ../info/dired-x): New targets. - (INFO_TARGETS, DVI_TARGETS): Add the new targets. - -1994-01-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (../info/sc): Rename frin sc.info. - (../info/cl): Likewise. - (INFO_TARGETS): Use new names. - -1993-12-04 Richard Stallman (rms@srarc2) - - * getopt.c: New file. - * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src. - (getopt.o): New rule. - (dvi): Don't depend on texindex. - (emacs.dvi, cl.dvi, forms.dvi, vip.dvi, gnus.dvi, sc.dvi): - Depend on texindex. - -1993-12-03 Richard Stallman (rms@srarc2) - - * Makefile (../info/sc.info): Rename from ../info/sc. - (TEXI2DVI): New variable. - (emacs.dvi, cl.dvi forms.dvi, sc.dvi, vip.dvi, gnus.dvi, info.dvi): - Add explicit commands. - (TEXINDEX_OBJS): Delete duplicate getopt.o. - -1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.22 released. - -1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (TEXINDEX_OBJS): Delete spurious period. - -1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.21 released. - -1993-11-15 Paul Eggert (eggert@twinsun.com) - - * man/Makefile (../info/cl.info): Rename from ../info/cl. - -1993-11-15 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (../etc/GNU): New target. - (EMACSSOURCES): Add gnu1.texi. - -1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (realclean): Don't delete the Info files. - -1993-10-25 Brian Fox (bfox@albert.gnu.ai.mit.edu) - - * forms.texi: Fix forms.texi so that it will format correctly. - Add missing `@end iftex', fix bad reference. - - * info.texi, info-stn.texi: New files implement texinfo version of - `info' file. - - * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x - 4' where appropriate. - -1993-10-20 Brian Fox (bfox@ai.mit.edu) - - * Makefile: Fix targets for texindex, new info.texi files. - * info-stnd.texi: New file implements info for standalone info - reader. - * info.texi: Update to include recent changes to "../info/info". - New source file for ../info/info; includes info-stnd.texi. - - * texindex.c: Include "../src/config.h" if building in emacs. - - * Makefile: Change all files to FILENAME.texi, force all targets - to be FILENAME, not FILENAME.info. This changes sc.texinfo, - vip.texinfo, forms.texinfo, cl.texinfo. - Add target to build texindex.c, defining `emacs'. - - * forms.texi: Install new file to match version 2.3 of forms.el. - -1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.19 released. - -1993-08-10 Simon Leinen (simon@lia.di.epfl.ch) - - * sc.texinfo: Fix info file name. - - * Makefile (info): Add gnus and sc. - (dvi): Add gnus.dvi and sc.dvi. - (../info/sc, sc.dvi): New targets. - -1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.18 released. - -1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Fix source file names of the separate manuals. - (gnus.dvi, ../info/gnus): New targets. - -1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.17 released. - -1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * split-man: Fix typos in last change. - -1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.16 released. - -1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * version 19.15 released. - -1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Makefile (distclean): It's rm, not rf. - -1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.14 released. - -1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile: New file. - -1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.13 released. - -1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.9 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.8 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * cmdargs.texi: Document the -i, -itype, and -iconic options. - - * trouble.texi: It's `enable-flow-control-on', not - `evade-flow-control-on'. - -1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * display.texi: Document standard-display-european. - -1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.7 released. - - * emacs.texi: Add a sentence to the top menu mentioning the - specific version of Emacs this manual applies to. - -1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * basic.texi: Document next-line-add-lines variable used to - implement down-arrow. - - * killing.texi: Document kill-whole-line. - -1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * text.texi: Update unix TeX ordering information. - -1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * news.texi: Mention fill-rectangle in keybinding list. - - * killing.texi: Document fill-rectangle. - -1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * vc.texi: Bring the docs up to date with VC 5.2. - -1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * emacs.tex: Mention blackbox and gomoku under Amusements. - Assembler mode is now mentioned and appropriately indexed - under Programming Modes. - -1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu) - - * emacs.tex: Update TeX ordering information. - -1990-08-30 David Lawrence (tale@pogo.ai.mit.edu) - - * gnus.texinfo: New file. Removed installation instructions. - -1990-06-26 David Lawrence (tale@geech) - - * emacs.tex: Note that completion-ignored-extensions is not used - to filter out names when all completions are displayed in - *Completions*. - -1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. - -1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) - - * emacs.tex: Add @findex grep. - -1989-01-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * texinfo.tex: Change spelling of `\sc' font to `\smallcaps' and - then define `\sc' as the command for smallcaps in Texinfo. This - means that the @sc command will produce small caps. bfox has - made the corresponding change to makeinfo and texinfm.el. - -1988-08-16 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Correct two typos. No other changes before - Version 19 will be made. - - * vip.texinfo: Remove menu entry Adding Lisp Code in node - Customization since the menu entry did not point to anything. - Also add an @finalout command to remove overfull hboxes from the - printed output. - - * cl.texinfo: Add @bye, \input line and @settitle to file. - This file is clearly intended to be a chapter of some other work, - but the other work does not yet exist. - -1988-07-25 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * texinfo.texinfo: Three typos corrected. - -1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Update information for obtaining TeX distribution from the - University of Washington. - -;; Local Variables: -;; coding: iso-2022-7bit -;; fill-column: 79 -;; add-log-time-zone-rule: t -;; End: - - Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, - 2003, 2004, 2005, 2006, 2007 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. - -;;; arch-tag: f1d62776-3ed5-4811-9d96-267252577dbd diff --git a/man/Makefile.in b/man/Makefile.in deleted file mode 100644 index 00088b74b51..00000000000 --- a/man/Makefile.in +++ /dev/null @@ -1,368 +0,0 @@ -#### 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/man/abbrevs.texi b/man/abbrevs.texi deleted file mode 100644 index 585e28318e7..00000000000 --- a/man/abbrevs.texi +++ /dev/null @@ -1,457 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Abbrevs -@chapter Abbrevs -@cindex abbrevs -@cindex expansion (of abbrevs) - - A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert -it, into some different text. Abbrevs are defined by the user to expand -in specific ways. For example, you might define @samp{foo} as an abbrev -expanding to @samp{find outer otter}. Then you could insert -@samp{find outer otter } into the buffer by typing @kbd{f o o -@key{SPC}}. - - A second kind of abbreviation facility is called @dfn{dynamic abbrev -expansion}. You use dynamic abbrev expansion with an explicit command -to expand the letters in the buffer before point by looking for other -words in the buffer that start with those letters. @xref{Dynamic -Abbrevs}. - - ``Hippie'' expansion generalizes abbreviation expansion. -@xref{Hippie Expand, , Hippie Expansion, autotype, Features for -Automatic Typing}. - -@menu -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. -@end menu - -@node Abbrev Concepts -@section Abbrev Concepts - - An @dfn{abbrev} is a word which has been defined to @dfn{expand} into -a specified @dfn{expansion}. When you insert a word-separator character -following the abbrev, that expands the abbrev---replacing the abbrev -with its expansion. For example, if @samp{foo} is defined as an abbrev -expanding to @samp{find outer otter}, then you can insert @samp{find -outer otter.} into the buffer by typing @kbd{f o o .}. - -@findex abbrev-mode -@vindex abbrev-mode -@cindex Abbrev mode -@cindex mode, Abbrev - Abbrevs expand only when Abbrev mode (a minor mode) is enabled. -Disabling Abbrev mode does not cause abbrev definitions to be forgotten, -but they do not expand until Abbrev mode is enabled again. The command -@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it -turns Abbrev mode on if the argument is positive, off otherwise. -@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is -on when the variable is non-@code{nil}. The variable @code{abbrev-mode} -automatically becomes local to the current buffer when it is set. - - Abbrevs can have @dfn{mode-specific} definitions, active only in one major -mode. Abbrevs can also have @dfn{global} definitions that are active in -all major modes. The same abbrev can have a global definition and various -mode-specific definitions for different major modes. A mode-specific -definition for the current major mode overrides a global definition. - - You can define abbrevs interactively during the editing session. You -can also save lists of abbrev definitions in files for use in later -sessions. Some users keep extensive lists of abbrevs that they load -in every session. - -@node Defining Abbrevs -@section Defining Abbrevs - -@table @kbd -@item C-x a g -Define an abbrev, using one or more words before point as its expansion -(@code{add-global-abbrev}). -@item C-x a l -Similar, but define an abbrev specific to the current major mode -(@code{add-mode-abbrev}). -@item C-x a i g -Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). -@item C-x a i l -Define a word in the buffer as a mode-specific abbrev -(@code{inverse-add-mode-abbrev}). -@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as an abbrev expanding into @var{exp}. -@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}. -@item M-x kill-all-abbrevs -Discard all abbrev definitions, leaving a blank slate. -@end table - -@kindex C-x a g -@findex add-global-abbrev - The usual way to define an abbrev is to enter the text you want the -abbrev to expand to, position point after it, and type @kbd{C-x a g} -(@code{add-global-abbrev}). This reads the abbrev itself using the -minibuffer, and then defines it as an abbrev for one or more words before -point. Use a numeric argument to say how many words before point should be -taken as the expansion. For example, to define the abbrev @samp{foo} as -mentioned above, insert the text @samp{find outer otter} and then type -@kbd{C-u 3 C-x a g f o o @key{RET}}. - - An argument of zero to @kbd{C-x a g} means to use the contents of the -region as the expansion of the abbrev being defined. - -@kindex C-x a l -@findex add-mode-abbrev - The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but -defines a mode-specific abbrev. Mode-specific abbrevs are active only in a -particular major mode. @kbd{C-x a l} defines an abbrev for the major mode -in effect at the time @kbd{C-x a l} is typed. The arguments work the same -as for @kbd{C-x a g}. - -@kindex C-x a i g -@findex inverse-add-global-abbrev -@kindex C-x a i l -@findex inverse-add-mode-abbrev - If the abbrev text itself is already in the buffer, you can use the -commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and -@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an -abbrev by specify the expansion in the minibuffer. These commands are -called ``inverse'' because they invert the meaning of the two text -strings they use (one from the buffer and one read with the -minibuffer). - -@findex define-mode-abbrev -@findex define-global-abbrev - You can define an abbrev without inserting either the abbrev or its -expansion in the buffer using the command @code{define-global-abbrev}. -It reads two arguments---the abbrev, and its expansion. The command -@code{define-mode-abbrev} does likewise for a mode-specific abbrev. - - To change the definition of an abbrev, just define a new definition. -When the abbrev has a prior definition, the abbrev definition commands -ask for confirmation before replacing it. - -@findex kill-all-abbrevs - To remove an abbrev definition, give a negative argument to the -abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. -The former removes a global definition, while the latter removes a -mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all -abbrev definitions, both global and local. - -@node Expanding Abbrevs -@section Controlling Abbrev Expansion - - When Abbrev mode is enabled, an abbrev expands whenever it is -present in the buffer just before point and you type a self-inserting -whitespace or punctuation character (@key{SPC}, comma, etc.@:). More -precisely, any character that is not a word constituent expands an -abbrev, and any word-constituent character can be part of an abbrev. -The most common way to use an abbrev is to insert it and then insert a -punctuation or whitespace character to expand it. - -@vindex abbrev-all-caps - Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find -outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into -@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the -variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies -@samp{FIND OUTER OTTER}). - - These commands are used to control abbrev expansion: - -@table @kbd -@item M-' -Separate a prefix from a following abbrev to be expanded -(@code{abbrev-prefix-mark}). -@item C-x a e -@findex expand-abbrev -Expand the abbrev before point (@code{expand-abbrev}). -This is effective even when Abbrev mode is not enabled. -@item M-x expand-region-abbrevs -Expand some or all abbrevs found in the region. -@end table - -@kindex M-' -@findex abbrev-prefix-mark - You may wish to expand an abbrev and attach a prefix to the expansion; -for example, if @samp{cnst} expands into @samp{construction}, you might want -to use it to enter @samp{reconstruction}. It does not work to type -@kbd{recnst}, because that is not necessarily a defined abbrev. What -you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in -between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert -@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to -indicate that it has done its work. Then insert the abbrev @samp{cnst}; -the buffer now contains @samp{re-cnst}. Now insert a non-word character -to expand the abbrev @samp{cnst} into @samp{construction}. This -expansion step also deletes the hyphen that indicated @kbd{M-'} had been -used. The result is the desired @samp{reconstruction}. - - If you actually want the text of the abbrev in the buffer, rather than -its expansion, you can accomplish this by inserting the following -punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in -the buffer, not expanding it. - -@findex unexpand-abbrev - If you expand an abbrev by mistake, you can undo the expansion and -bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}). -This also undoes the insertion of the non-word character that expanded -the abbrev. If the result you want is the terminating non-word -character plus the unexpanded abbrev, you must reinsert the terminating -character, quoting it with @kbd{C-q}. You can also use the command -@kbd{M-x unexpand-abbrev} to cancel the last expansion without -deleting the terminating character. - -@findex expand-region-abbrevs - @kbd{M-x expand-region-abbrevs} searches through the region for defined -abbrevs, and for each one found offers to replace it with its expansion. -This command is useful if you have typed in text using abbrevs but forgot -to turn on Abbrev mode first. It may also be useful together with a -special set of abbrev definitions for making several global replacements at -once. This command is effective even if Abbrev mode is not enabled. - - Expanding any abbrev first runs the hook @code{pre-abbrev-expand-hook} -(@pxref{Hooks}). - -@need 1500 -@node Editing Abbrevs -@section Examining and Editing Abbrevs - -@table @kbd -@item M-x list-abbrevs -Display a list of all abbrev definitions. With a numeric argument, list -only local abbrevs. -@item M-x edit-abbrevs -Edit a list of abbrevs; you can add, alter or remove definitions. -@end table - -@findex list-abbrevs - The output from @kbd{M-x list-abbrevs} looks like this: - -@example -@var{various other tables@dots{}} -(lisp-mode-abbrev-table) -"dk" 0 "define-key" -(global-abbrev-table) -"dfn" 0 "definition" -@end example - -@noindent -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) - - A line containing a name in parentheses is the header for abbrevs in a -particular abbrev table; @code{global-abbrev-table} contains all the global -abbrevs, and the other abbrev tables that are named after major modes -contain the mode-specific abbrevs. - - Within each abbrev table, each nonblank line defines one abbrev. The -word at the beginning of the line is the abbrev. The number that -follows is the number of times the abbrev has been expanded. Emacs -keeps track of this to help you see which abbrevs you actually use, so -that you can eliminate those that you don't use often. The string at -the end of the line is the expansion. - - Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs -(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are -pre-defined by various modes, and are not saved to your abbrev file. -To disable a ``system'' abbrev, define an abbrev of the same name that -expands to itself, and save it to your abbrev file. - -@findex edit-abbrevs -@kindex C-c C-c @r{(Edit Abbrevs)} - @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev -definitions by editing a list of them in an Emacs buffer. The list has -the same format described above. The buffer of abbrevs is called -@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in -this buffer to install the abbrev definitions as specified in the -buffer---and delete any abbrev definitions not listed. - - The command @code{edit-abbrevs} is actually the same as -@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*} -whereas @code{list-abbrevs} merely displays it in another window. - -@node Saving Abbrevs -@section Saving Abbrevs - - These commands allow you to keep abbrev definitions between editing -sessions. - -@table @kbd -@item M-x write-abbrev-file @key{RET} @var{file} @key{RET} -Write a file @var{file} describing all defined abbrevs. -@item M-x read-abbrev-file @key{RET} @var{file} @key{RET} -Read the file @var{file} and define abbrevs as specified therein. -@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET} -Similar but do not display a message about what is going on. -@item M-x define-abbrevs -Define abbrevs from definitions in current buffer. -@item M-x insert-abbrevs -Insert all abbrevs and their expansions into current buffer. -@end table - -@findex write-abbrev-file - @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and -then writes a description of all current abbrev definitions into that -file. This is used to save abbrev definitions for use in a later -session. The text stored in the file is a series of Lisp expressions -that, when executed, define the same abbrevs that you currently have. - -@findex read-abbrev-file -@findex quietly-read-abbrev-file -@vindex abbrev-file-name - @kbd{M-x read-abbrev-file} reads a file name using the minibuffer -and then reads the file, defining abbrevs according to the contents of -the file. The function @code{quietly-read-abbrev-file} is similar -except that it does not display a message in the echo area; you cannot -invoke it interactively, and it is used primarily in the @file{.emacs} -file. If either of these functions is called with @code{nil} as the -argument, it uses the file name specified in the variable -@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}. -That file is your standard abbrev definition file, and Emacs loads -abbrevs from it automatically when it starts up. - -@vindex save-abbrevs - Emacs will offer to save abbrevs automatically if you have changed -any of them, whenever it offers to save all files (for @kbd{C-x s} or -@kbd{C-x C-c}). It saves them in the file specified by -@code{abbrev-file-name}. This feature can be inhibited by setting the -variable @code{save-abbrevs} to @code{nil}. - -@findex insert-abbrevs -@findex define-abbrevs - The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are -similar to the previous commands but work on text in an Emacs buffer. -@kbd{M-x insert-abbrevs} inserts text into the current buffer after point, -describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses -the entire current buffer and defines abbrevs accordingly. - -@node Dynamic Abbrevs -@section Dynamic Abbrev Expansion - - The abbrev facility described above operates automatically as you -insert text, but all abbrevs must be defined explicitly. By contrast, -@dfn{dynamic abbrevs} allow the meanings of abbreviations to be -determined automatically from the contents of the buffer, but dynamic -abbrev expansion happens only when you request it explicitly. - -@kindex M-/ -@kindex C-M-/ -@findex dabbrev-expand -@findex dabbrev-completion -@table @kbd -@item M-/ -Expand the word in the buffer before point as a @dfn{dynamic abbrev}, -by searching in the buffer for words starting with that abbreviation -(@code{dabbrev-expand}). - -@item C-M-/ -Complete the word before point as a dynamic abbrev -(@code{dabbrev-completion}). -@end table - -@vindex dabbrev-limit - For example, if the buffer contains @samp{does this follow } and you -type @kbd{f o M-/}, the effect is to insert @samp{follow} because that -is the last word in the buffer that starts with @samp{fo}. A numeric -argument to @kbd{M-/} says to take the second, third, etc.@: distinct -expansion found looking backward from point. Repeating @kbd{M-/} -searches for an alternative expansion by looking farther back. After -scanning all the text before point, it searches the text after point. -The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far -away in the buffer to search for an expansion. - -@vindex dabbrev-check-all-buffers - After scanning the current buffer, @kbd{M-/} normally searches other -buffers, unless you have set @code{dabbrev-check-all-buffers} to -@code{nil}. - -@vindex dabbrev-ignored-buffer-regexps - For finer control over which buffers to scan, customize the variable -@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular -expressions. If a buffer's name matches any of these regular -expressions, dynamic abbrev expansion skips that buffer. - - A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to -search first for expansions after point, then other buffers, and -consider expansions before point only as a last resort. If you repeat -the @kbd{M-/} to look for another expansion, do not specify an -argument. Repeating @kbd{M-/} cycles through all the expansions after -point and then the expansions before point. - - After you have expanded a dynamic abbrev, you can copy additional -words that follow the expansion in its original context. Simply type -@kbd{@key{SPC} M-/} for each additional word you want to copy. The -spacing and punctuation between words is copied along with the words. - - The command @kbd{C-M-/} (@code{dabbrev-completion}) performs -completion of a dynamic abbrev. Instead of trying the possible -expansions one by one, it finds all of them, then inserts the text -that they have in common. If they have nothing in common, @kbd{C-M-/} -displays a list of completions, from which you can select a choice in -the usual manner. @xref{Completion}. - - Dynamic abbrev expansion is completely independent of Abbrev mode; the -expansion of a word with @kbd{M-/} is completely independent of whether -it has a definition as an ordinary abbrev. - -@node Dabbrev Customization -@section Customizing Dynamic Abbreviation - - Normally, dynamic abbrev expansion ignores case when searching for -expansions. That is, the expansion need not agree in case with the word -you are expanding. - -@vindex dabbrev-case-fold-search - This feature is controlled by the variable -@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in -this search; if it is @code{nil}, the word and the expansion must match -in case. If the value of @code{dabbrev-case-fold-search} is -@code{case-fold-search}, which is true by default, then the variable -@code{case-fold-search} controls whether to ignore case while searching -for expansions. - -@vindex dabbrev-case-replace - Normally, dynamic abbrev expansion preserves the case pattern -@emph{of the dynamic abbrev you are expanding}, by converting the -expansion to that case pattern. - -@vindex dabbrev-case-fold-search - The variable @code{dabbrev-case-replace} controls whether to -preserve the case pattern of the dynamic abbrev. If it is @code{t}, -the dynamic abbrev's case pattern is preserved in most cases; if it is -@code{nil}, the expansion is always copied verbatim. If the value of -@code{dabbrev-case-replace} is @code{case-replace}, which is true by -default, then the variable @code{case-replace} controls whether to -copy the expansion verbatim. - - However, if the expansion contains a complex mixed case pattern, and -the dynamic abbrev matches this pattern as far as it goes, then the -expansion is always copied verbatim, regardless of those variables. -Thus, for example, if the buffer contains -@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it -copies the expansion verbatim including its case pattern. - -@vindex dabbrev-abbrev-char-regexp - The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, -controls which characters are considered part of a word, for dynamic expansion -purposes. The regular expression must match just one character, never -two or more. The same regular expression also determines which -characters are part of an expansion. The value @code{nil} has a special -meaning: dynamic abbrevs are made of word characters, but expansions are -made of word and symbol characters. - -@vindex dabbrev-abbrev-skip-leading-regexp - In shell scripts and makefiles, a variable name is sometimes prefixed -with @samp{$} and sometimes not. Major modes for this kind of text can -customize dynamic abbrev expansion to handle optional prefixes by setting -the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value -should be a regular expression that matches the optional prefix that -dynamic abbrev expression should ignore. - -@ignore - arch-tag: 638e0079-9540-48ec-9166-414083e16445 -@end ignore diff --git a/man/ack.texi b/man/ack.texi deleted file mode 100644 index d5dbf1ae8ca..00000000000 --- a/man/ack.texi +++ /dev/null @@ -1,1574 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@node Acknowledgments, Screen, Concept Index, Top -@unnumbered Acknowledgments - -Many people have contributed code included in the Free Software -Foundation's distribution of GNU Emacs. To show our appreciation for -their public spirit, we list here in alphabetical order those who have -written substantial portions. - -@c We should list here anyone who has contributed a new package, -@c and anyone who has made major enhancements in Emacs -@c that many users would notice and consider important. - -@itemize @bullet -@item -Per Abrahamsen wrote the customization buffer facilities, as well as -@file{double.el} for typing accented characters not normally available -from the keyboard, @file{xt-mouse.el} which handles mouse commands -through Xterm, @file{gnus-cus.el} which implements customization -commands for Gnus, @file{gnus-cite.el}, a citation-parsing facility -for news articles and @file{cpp.el} which hides or highlights parts of -C programs according to preprocessor conditionals. - -@item -Tomas Abrahamsson wrote @file{artist.el}, a package for producing @acronym{ASCII} -art with a mouse or with keyboard keys. - -@item -Jay K.@: Adams wrote @file{jka-compr.el}, providing automatic -decompression and recompression for compressed files. - -@item -Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the -point vertically fixed by scrolling the window when moving up and down -in the buffer. - -@item -Joe Arceneaux wrote the original text property implementation, and -implemented support for X11. - -@item -Miles Bader wrote @file{image-file.el}, support code for visiting -image files, @file{minibuf-eldef.el}, a minor mode whereby the default -value is shown in the minibuffer prompt only when appropriate, and -@file{button.el}, the library that implements clickable buttons. - -@item -David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by -moving the mouse in particular patterns. - -@item -Eli Barzilay wrote @file{calculator.el}, a desktop calculator for -Emacs. - -@item -Steven L.@: Baur wrote -@c If earcon.el actually works with Emacs 21, it isn't useful for lack -@c of sound files. -- fx -@c @file{earcon.el}, a facility for sound effects -@c for email and news messages, -@file{footnote.el} which lets you include -footnotes in email messages, and @file{gnus-audio.el} which provides -sound effects for Gnus. - -@item -Alexander L. Belikoff, Sergey Berezin, David Edmondson, Andreas -Fuchs, Mario Lang, Gergely Nagy, Michael Olson, and Alex Schroeder -contributed ERC, an advanced Internet Relay Chat client. - -@item -Boaz Ben-Zvi wrote @file{profile.el}, to time Emacs Lisp functions. - -@item -Anna M. Bigatti wrote @file{cal-html.el}, which produces HTML calendars. - -@item -Ray Blaak wrote @file{delphi.el}, a major mode for editing Delphi -(Object Pascal) source code. - -@item -Jim Blandy wrote Emacs 19's input system, brought its configuration and -build process up to the GNU coding standards, and contributed to the -frame support and multi-face support. Jim also wrote @file{tvi970.el}, -terminal support for the TeleVideo 970 terminals. - -@item -Per Bothner wrote @file{term.el}, a terminal emulator in an Emacs -buffer. - -@item -Terrence M.@: Brannon wrote @file{landmark.el}, a neural-network robot -that learns landmarks. - -@item -Frank Bresz wrote @file{diff.el}, a program to display @code{diff} -output. - -@item -Peter Breton implemented: - -@itemize @minus -@item -@file{dirtrack} which does better tracking of directory changes in shell -buffers, -@item -@file{filecache.el} which records which directories your files are in, -@item -@file{locate.el} which interfaces to the @code{locate} command, -@item -@file{find-lisp.el}, an Emacs Lisp emulation of the @code{find} program, -@item -@file{net-utils.el}, and -@item -the ``generic mode'' feature. -@end itemize - -@item -Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs. - -@item -Kevin Broadey wrote @file{foldout.el}, providing folding extensions to -Emacs's outline modes. - -@c @item -@c Vincent Broman wrote @file{ada.el}, a mode for editing Ada code -@c (since replaced by @file{ada-mode.el}). - -@item -David M.@: Brown wrote @file{array.el}, for editing arrays and other -tabular data. - -@item -W@l{}odek Bzyl and Ryszard Kubiak wrote @file{ogonek.el}, a package for -changing the encoding of Polish characters. - -@item -Bill Carpenter provided @file{feedmail.el}, a package for massaging -outgoing mail messages and sending them through various popular mailers. - -@item -Per Cederqvist and Inge Wallin wrote @file{ewoc.el}, an Emacs widget for -manipulating object collections. - -@item -Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for -Emacs Lisp functions, and @file{trace.el}, a tracing facility for Emacs -Lisp. - -@item -Chris Chase and Carsten Dominik wrote @file{idlwave.el}, an editing mode -for IDL and WAVE CL. - -@item -Bob Chassell wrote @file{texnfo-upd.el} and @file{makeinfo.el}, modes -and utilities for working with Texinfo files; and @file{page-ext.el}, -commands for extended page handling. - -@item -Andrew Choi wrote the Macintosh support code, and contributed -@file{mac-win.el}, support for the Mac window system. - -@item -James Clark wrote @file{sgml-mode.el}, a mode for editing SGML -documents, and contributed to Emacs's dumping procedures. - -@item -Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor. - -@item -Glynn Clements provided @file{gamegrid.el} and a couple of games that -use it, Snake and Tetris. - -@item -Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a -package for easy definition of major and minor modes. - -@item -Andrew Csillag wrote M4 mode (@file{m4-mode.el}). - -@item -Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler -for compiled Emacs Lisp code. - -@item -Mathias Dahl wrote @file{image-dired.el}, a package for viewing image -files as ``thumbnails.'' - -@item -Michael DeCorte wrote @file{emacs.csh}, a C-shell script that starts a -new Emacs job, or restarts a paused Emacs if one exists. - -@item -Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the -@file{/usr/uci/post} mailer. - -@item -Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed -text replace the current selection. - -@item -Eric Ding contributed @file{goto-addr.el}, - -@item -Jan Dj@"{a}rv added support for the GTK+ toolkit and X drag-and-drop. - -@item -Carsten Dominik wrote @file{reftex.el}, a package for setting up -labels and cross-references in La@TeX{} documents, and @file{org.el}, -a mode for maintaining notes, todo lists, and project planning. - -@item -Scott Draves wrote @file{tq.el}, help functions for maintaining -transaction queues between Emacs and its subprocesses. - -@item -Benjamin Drieu wrote @file{pong.el}, an implementation of the classical -pong game. - -@item -Viktor Dukhovni wrote support for dumping under SunOS version 4. - -@item -John Eaton co-wrote Octave mode. - -@item -Rolf Ebert co-wrote Ada mode (@file{ada-mode.el}). - -@item -Stephen Eglen implemented @file{mspools.el}, for use with Procmail, -which tells you which mail folders have mail waiting in them, and -@file{iswitchb.el}, a feature for incremental reading and completion of -buffer names. - -@item -Torbj@"orn -Einarsson contributed the Fortran 90 mode (@file{f90.el}). - -@item -Tsugutomo Enami co-wrote the support for international character sets. - -@item -Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87 -code. - -@item -Michael Ernst wrote @file{reposition.el}, a command for recentering a -function's source code and preceding comment on the screen. - -@item -Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data -Language source code. - -@item -Frederick Farnbach implemented @file{morse.el}, which converts text to -Morse code. - -@item -Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which -is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and -@file{ldap.el}, the LDAP client interface. - -@item -Fred Fish wrote the support for dumping COFF executable files. - -@item -Karl Fogel wrote: - -@itemize @minus -@item -@file{bookmark.el}, for creating named placeholders, saving them and -jumping to them later, -@item -@file{mail-hist.el}, a history mechanism for outgoing mail messages, and -@item -@file{saveplace.el}, for preserving point's location in files between -editing sessions. -@end itemize - -@item -Gary Foster wrote @file{crisp.el}, the emulation for CRiSP and Brief -editors, and @file{scroll-lock.el} (now @file{scroll-all.el}) a mode -for scrolling several buffers together. - -@item -Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, -@file{type-break.el}, which reminds you to take periodic breaks from -typing, and @code{eldoc-mode}, a mode to show the defined parameters or -the doc string for the Lisp function near point. With Roland McGrath, -he wrote @file{rsz-mini.el}, a minor mode to automatically resize the -minibuffer to fit the text it contains. - -@item -Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files. - -@item -Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote -@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF -flow control. - -@item -Kevin Gallo added multiple-frame support for Windows NT and wrote -@file{w32-win.el}, support functions for the MS-Windows window system. - -@item -Juan Le@'{o}n Lahoz Garc@'{i}a wrote @file{wdired.el}, a package for -performing file operations by directly editing Dired buffers. - -@item -Howard Gayle wrote: - -@itemize @minus -@item -the C and lisp code for display tables and case tables, -@item -@file{rot13.el}, a command to display the plain-text form of a buffer -encoded with the Caesar cipher, -@item -@file{case-table.el}, code to extend the character set and support case -tables, -@item -much of the support for the ISO-8859 European character sets (which -includes @file{iso-ascii.el}, @file{iso-insert.el}, @file{iso-swed.el}, -@file{latin-1.el}, @file{iso-syntax.el}, @file{iso-transl.el}, -@file{swedish.el}), and -@item -@file{vt100-led.el}, a package for controlling the LED's on -VT100-compatible terminals. -@end itemize - -@item -Stephen Gildea made the Emacs quick reference card, and made many -contributions for @file{time-stamp.el}, a package for maintaining -last-change time stamps in files. - -@item -Julien Gilles wrote @file{gnus-ml.el}, a mailing list minor mode for -Gnus. - -@item -David Gillespie wrote: - -@itemize @minus -@item -The Common Lisp compatibility packages, -@item -@code{Calc}, an advanced calculator and mathematical tool, -@item -@file{complete.el}, a partial completion mechanism, and -@item -@file{edmacro.el}, a package for editing keyboard macros. -@end itemize - -@item -Bob Glickstein contributed the @file{sregex.el} feature, a facility for -writing regexps using a Lisp-like syntax. - -@item -Boris Goldowsky wrote: - -@itemize @minus -@item -@file{avoid.el}, a package to keep the mouse cursor out of the way of -the text cursor, -@item -@file{shadowfile.el}, a package for keeping identical copies of files in -more than one place, -@item -@file{format.el}, a package for reading and writing files in various -formats, -@item -@file{enriched.el}, a package for saving text properties in files, and -@item -@file{facemenu.el}, a package for specifying faces. -@end itemize - -@item -Michelangelo Grigni wrote @file{ffap.el} which visits a file, -taking the file name from the buffer. - -@item -Odd Gripenstam wrote @file{dcl-mode.el} for editing DCL command files. - -@item -Kai Gro@ss{}johann and Michael Albinus wrote the Tramp package, which -provides transparent remote file editing using rcp, ssh, ftp, and other -network protocols. - -@item -Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between -the ISO 8859-1 character set and the notations for non-@acronym{ASCII} -characters used by @TeX{} and net tradition, and @file{latin-2.el}, code -which sets up case-conversion and syntax tables for the ISO Latin-2 -character set. - -@item -Henry Guillaume wrote @file{find-file.el}, a package to visit files -related to the currently visited file. - -@item -Doug Gwyn wrote the portable @code{alloca} implementation. - -@item -Ken'ichi Handa implemented most of the support for international -character sets, and wrote @file{isearch-x.el}, a facility for searching -non-@acronym{ASCII} text. Together with Naoto Takahashi, he wrote -@file{quail.el}, a simple input facility for typing non-@acronym{ASCII} text from -an @acronym{ASCII} keyboard. Ken'ichi also wrote @file{ps-bdf.el}, a BDF font -support for printing non-@acronym{ASCII} text on a PostScript printer. - -@item -Chris Hanson wrote @file{netuname.el}, a package to use HP-UX's Remote -File Access facility from Emacs. - -@item -Jesper Harder wrote @file{yenc.el}, for decoding yenc encoded messages. - -@item -K. Shane Hartman wrote: - -@itemize @minus -@item -@file{chistory.el} and @file{echistory.el}, packages for browsing -command history lists, -@item -@file{electric.el} and @file{helper.el}, providing an alternative -command loop and appropriate help facilities, -@item -@file{emacsbug.el}, a package for reporting Emacs bugs, -@item -@file{picture.el}, a mode for editing @acronym{ASCII} pictures, and -@item -@file{view.el}, a package for perusing files and buffers without editing -them. -@end itemize - -@item -John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el}, -which provide alternative mouse-based editing and scrolling features. - -@item -Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation -format of Unicode. - -@item -Markus Heritsch co-wrote Ada mode (@file{ada-mode.el}). - -@item -Karl Heuer wrote the original blessmail script, implemented the -@code{intangible} text property, and rearranged the structure of the -@code{Lisp_Object} type to allow for more data bits. - -@item -Manabu Higashida ported Emacs to MS-DOS. - -@item -Anders Holst wrote @file{hippie-exp.el}, a versatile completion and -expansion package. - -@item -Kurt Hornik co-wrote Octave mode. - -@item -Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++} -template instantiations. - -@item -Joakim Hove wrote @file{html2text.el}, a html to plain text converter. -@item -Denis Howe wrote @file{browse-url.el}, a package for invoking a WWW -browser to display a URL. - -@item -Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and -wrote many of its parts. - -@item -Andrew Innes contributed extensively to the MS-Windows support. - -@item -Seiichiro Inoue improved Emacs's XIM support. - -@item -Ulf Jasper wrote @file{icalendar.el}, a package for converting Emacs -diary entries to and from the iCalendar format, and -@file{newsticker.el}, an RSS and Atom based Newsticker. - -@item -Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game, -and @file{mldrag.el}, a package which allows the user to resize windows -by dragging mode lines and vertical window separators with the mouse. - -@item -Terry Jones wrote @file{shadow.el}, a package for finding potential -load-path problems when some Lisp file ``shadows'' another. - -@item -Simon Josefsson wrote: - -@itemize @minus -@item -@file{dns-mode.el}, an editing mode for Domain Name System master files, -@item -@file{flow-fill.el}, a package for interpreting RFC2646 formatted text -in messages, -@item -@file{fringe.el}, a package for customizing the fringe, -@item -@file{imap.el}, an Emacs Lisp library for talking to IMAP servers, -@item -@file{nnimap}, the IMAP back-end for Gnus, and -@item -@file{rfc2104.el}, a hashed message authentication facility. -@end itemize - -@item -Arne J@o{}rgensen wrote @file{latexenc.el}, a package to -automatically guess the correct coding system in LaTeX files. - -@item -Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out -mail with SMTP. - -@item -David Kaufman wrote @file{yow.c}, an essential utility program for the -hopelessly pinheaded. - -@item -Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining -bibliography databases compatible with @code{refer} (the @code{troff} -version) and @code{lookbib}, and @file{refbib.el}, a package to convert -those databases to the format used by the LaTeX text formatting package. - -@item -Taichi Kawabata added support for Devanagari script and the Indian -languages. - -@item -Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs -buffers. - -@item -Michael Kifer wrote @file{ediff.el}, an interactive interface to the -@command{diff}, @command{patch}, and @command{merge} programs, and -Viper, the newest emulation for VI. - -@item -Richard King wrote the first version of @file{userlock.el} and -@file{filelock.c}, which provide simple support for multiple users -editing the same file. He also wrote the initial version of -@file{uniquify.el}, a facility to make buffer names unique by adding -parts of the file's name to the buffer name. -@c We're not using his backquote.el any more. - -@item -Peter Kleiweg wrote @file{ps-mode.el}, a major mode for editing -PostScript files and running a PostScript interpreter interactively from -within Emacs. - -@item -Pavel Kobiakov wrote @file{flymake.el}, a minor mode for performing -on-the-fly syntax checking. - -@item -Larry K.@: Kolodney wrote @file{cvtmail.c}, a program to convert the mail -directories used by Gosling Emacs into RMAIL format. - -@item -David M.@: Koppelman wrote @file{hi-lock.el}, a minor mode for -interactive automatic highlighting of parts of the buffer text. - -@item -Koseki Yoshinori wrote @file{iimage.el}, a minor mode for displaying -inline images. - -@item -Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up -menu support. - -@item -Sebastian Kremer wrote Emacs 19's @code{dired-mode}, with contributions -by Lawrence R.@: Dodd. He also wrote @file{ls-lisp.el}, a Lisp emulation -of the @code{ls} command for platforms which don't have @code{ls} as a -standard program. - -@item -Geoff Kuenning wrote Emacs 19's @file{ispell.el}, based on work by Ken -Stevens and others. - -@item -David K@ringaccent{a}gedal wrote @file{tempo.el}, providing support for -easy insertion of boilerplate text and other common constructions. - -@item -Daniel LaLiberte wrote: - -@itemize @minus -@item -@file{edebug.el}, a source-level debugger for Emacs Lisp, -@item -@file{cl-specs.el}, specifications to help @code{edebug} debug code -written using David Gillespie's Common Lisp support, -@item -@file{cust-print.el}, a customizable package for printing lisp objects, -@item -@file{eval-reg.el}, a re-implementation of @code{eval-region} in Emacs -Lisp, and -@item -@file{isearch.el}, Emacs's incremental search minor mode. -@end itemize - -@item -James R.@: Larus wrote @file{mh-e.el}, an interface to the MH mail system. - -@item -Vinicius Jose Latorre wrote the Emacs printing facilities, as well as: - -@itemize @minus -@item -@code{ps-print}, a package for pretty-printing Emacs buffers to -PostScript printers, -@item -@file{delim-col.el}, a package to arrange text into columns, -@item -@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic -chart that can be printed to a PostScript printer. -@end itemize - -@item -Frederic Lepied contributed @file{expand.el}, which uses the abbrev -mechanism for inserting programming constructs. - -@item -Peter Liljenberg wrote @file{elint.el}, a Lint-style code checker for -Emacs Lisp programs. - -@item -Lars Lindberg wrote @file{msb.el}, which provides more flexible menus -for buffer selection, and rewrote @file{dabbrev.el}. - -@item -Anders Lindgren wrote @file{autorevert.el}, a package for automatically -reverting files visited by Emacs that were changed on disk; -@file{cwarn.el}, a package to highlight suspicious C and C@t{++} -constructs; and @file{follow.el}, a minor mode to synchronize windows -that show the same buffer. - -@item -Thomas Link wrote @file{filesets.el}, a package for handling sets of -files. - -@item -Dave Love wrote much of the code dealing with Unicode support and -Latin-N unification. He added support for many coding systems, -including those in @file{code-pages.el} and the various UTF-7 and -UTF-16 coding systems. He also wrote: - -@itemize @minus -@item -@code{autoarg-mode}, a global minor mode whereby digit keys supply -prefix arguments, and @code{autoarg-kp-mode} which redefines the keypad -numeric keys to digit arguments, -@item -@file{autoconf.el}, a mode for editing Autoconf @file{configure.in} -files, -@item -@file{cfengine.el}, a mode for editing Cfengine files, -@item -@file{elide-head.el}, a package for eliding boilerplate text, such as -copyright notices, from file headers, -@item -@file{hl-line.el}, a package that provides a minor mode for highlighting -the line in the current window on which point is, -@item -@file{latin-8.el} and @file{latin-9.el}, code which sets up -case-conversion and syntax tables for the ISO Latin-8 and Latin-9 -character sets, -@item -@file{latin1-disp.el}, a package that lets you display ISO 8859 -characters on Latin-1 terminals by setting up appropriate display -tables, -@item -@file{python.el}, a major mode for the Python programming language. -@item -@file{refill.el}, a mode for automatic paragraph refilling, akin to -typical word processors, -@item -@file{smiley-ems.el}, a facility for displaying smiley faces, and -@item -@file{tool-bar.el}, a mode to control the display of the Emacs tool bar. -@end itemize - -@item -Eric Ludlam wrote the Speedbar package and the following packages: - -@itemize @minus -@item -@file{checkdoc.el}, for checking doc strings in Emacs Lisp programs, -@item -@file{dframe.el}, providing dedicatd frame support modes, and -@item -@file{ezimage.el}, a generalized way to place images over text. -@end itemize - -@item -Alan Mackenzie wrote the integrated AWK support in CC Mode. - -@item -Christopher J.@: Madsen wrote @file{decipher.el}, a package for cracking -simple substitution ciphers. - -@item -Neil M.@: Mager wrote @file{appt.el}, functions to notify users of their -appointments. It finds appointments recorded in the diary files -generated by Edward M.@: Reingold's @code{calendar} package. - -@item -Ken Manheimer wrote @file{allout.el}, a mode for manipulating and -formatting outlines, and @file{icomplete.el}, which provides incremental -completion feedback in the minibuffer. - -@item -Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code. - -@item -Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for -hiding selected code within C @code{#ifdef} clauses. - -@item -Simon Marshall wrote @file{regexp-opt.el}, which generates a regular -expression from a list of strings. He also extended @file{comint.el}, -originally written by Olin Shivers. - -@item -Bengt Martensson, Marc Shapiro, Mike Newton, Aaron Larson, and Stefan -Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{} -bibliography files. - -@item -Charlie Martin wrote @file{autoinsert.el}, which provides automatic -mode-sensitive insertion of text into new files. - -@item -Thomas May wrote @file{blackbox.el}, a version of the traditional -blackbox game. - -@item -Roland McGrath wrote: - -@itemize @minus -@item -@file{compile.el}, a package for running compilations in a buffer, and -then visiting the locations reported in error messages, -@item -@file{etags.el}, a package for jumping to function definitions and -searching or replacing in all the files mentioned in a @file{TAGS} file, -@item -@file{find-dired.el}, for using @code{dired} commands on output from the -@code{find} program, with Sebastian Kremer, -@item -@file{map-ynp.el}, a general purpose boolean question-asker, -@item -@file{autoload.el}, providing semi-automatic maintenance of autoload -files, and -@item -@file{upd-copyr.el}, providing semi-automatic maintenance of copyright -notices in source code. -@end itemize - -@item -David Megginson wrote @file{derived.el}, which allows one to define new -major modes by inheriting key bindings and commands from existing major -modes. - -@item -Will Mengarini wrote @file{repeat.el}, a command to repeat the preceding -command with its arguments. - -@item -Wayne Mesard wrote @file{hscroll.el} which does horizontal scrolling -automatically. - -@item -Brad Miller wrote @file{gnus-gl.el}, a Gnus interface for GroupLens. - -@item -Richard Mlynarik wrote: - -@itemize @minus -@item -@file{cl-indent.el}, a package for indenting Common Lisp code, -@item -@file{ebuff-menu.el}, an ``electric'' browser for buffer listings, -@item -@file{ehelp.el}, bindings for browsing help screens, -@item -@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, -used in mail messages and news articles, -@item -@file{terminal.el}, a terminal emulator for Emacs subprocesses, and -@item -@file{yow.el}, an essential utility (try @kbd{M-x yow}). -@end itemize - -@item -Gerd Moellmann was the Emacs maintainer from the beginning of Emacs 21 -development until the release of 21.1. He wrote: - -@itemize @minus -@item -the new display engine for Emacs 21, -@item -the asynchronous timers facility (@file{atimer.c}), -@item -the @code{ebrowse} C@t{++} browser, -@item -@file{jit-lock.el}, the Just-In-Time font-lock support mode, -@item -@file{tooltip.el}, a package for displaying tooltips, and -@item -@file{authors.el} package for maintaining the @file{AUTHORS} files. -@end itemize - -@item -Stefan Monnier added support for Arch, Subversion, and Meta-CVS to VC, -and re-wrote much of the Emacs server to use the built-in networking -primitives. He also wrote: - -@itemize @minus -@item -@code{PCL-CVS}, a directory-level front end to the CVS version control -system, -@item -@file{reveal.el}, a minor mode for automatically revealing invisible -text, -@item -@file{smerge-mode.el}, a minor mode for resolving @code{diff3} -conflicts, and -@item -@file{diff-mode.el}, a mode for viewing and editing context diffs. -@end itemize - -@item -Morioka Tomohiko wrote several packages for MIME support in Gnus and -elsewhere. - -@item -Sen Nagata wrote @file{crm.el}, a package for reading multiple strings -with completion, and @file{rfc2368.el}, support for @code{mailto:} -URLs. - -@item -Erik Naggum wrote the time-conversion functions. He also wrote -@file{disp-table.el}, a package for dealing with display tables, -@file{latin-4.el} and @file{latin-5.el}, code which sets up -case-conversion and syntax tables for the ISO Latin-4 and Latin-5 -character sets, @file{mailheader.el}, a package for parsing email -headers, and @file{parse-time.el}, a package for parsing time strings. - -@item -Thomas Neumann and Eric Raymond wrote @file{makefile.el} (now -@file{make-mode.el}), a mode for editing makefiles. - -@item -Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor -mode for selectively displaying blocks of text. - -@item -Dan Nicolaescu wrote @file{romanian.el}, support for editing Romanian -text, and @file{iris-ansi.el}, support for running Emacs on SGI's -@code{xwsh} and @code{winterm} terminal emulators. - -@item -Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. - -@item -Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer -history between Emacs sessions. - -@item -Jeff Norden wrote @file{kermit.el}, a package to help the Kermit -dialup communications program run comfortably in an Emacs shell buffer. - -@item -Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP -support. - -@item -Alexandre Oliva wrote @file{gnus-mlspl.el}, a group params-based mail -splitting mechanism. - -@item -Takaaki Ota wrote @file{table.el}, a package for creating and editing -embedded text-based tables. - -@item -Pieter E.@: J.@: Pareit wrote @file{mixal-mode.el}, an editing mode for -the MIX assembly language. - -@item -David Pearson contributed @file{quickurl.el}, a simple method of -inserting a URL into the current buffer based on text at point; -@file{5x5.el}, a game to fill all squares on the field. - -@item -Jeff Peck wrote: - -@itemize @minus -@item -@file{emacstool.c}, support for running Emacs under SunView/Sun Windows, -@item -@file{sun.el}, key bindings for sunterm keys, -@item -@file{sun-curs.el}, cursor definitions for Sun Windows, and -@item -@file{sun-fns.el} and @file{sun-mouse.el}, providing mouse support for -Sun Windows. -@end itemize - -@item -Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of -the ``Towers of Hanoi'' puzzle. - -@item -William M.@: Perry wrote @file{mailcap.el}, a MIME media types -configuration facility, @file{mwheel.el}, a package for supporting -mouse wheels, and the URL package. - -@item -Per Persson wrote @file{gnus-vm.el}, the VM interface for Gnus. - -@item -Jens Petersen wrote @file{find-func.el}, which makes it easy to find -the source code for an Emacs Lisp function or variable. - -@item -Daniel Pfeiffer wrote: - -@itemize @minus -@item -@file{conf-mode.el}, a major mode for editing configuration files, -@item -@file{copyright.el}, a package for updating copyright notices in files, -@item -@file{executable.el}, a package for executing interpreter scripts, -@item -@file{sh-script.el}, a mode for editing shell scripts, -@item -@file{skeleton.el}, implementing a concise language for writing -statement skeletons, and -@item -@file{two-column.el}, a minor mode for simultaneous two-column editing. -@end itemize - -Daniel also rewrote @file{apropos.el}, originally written by Joe Wells, -and, together with Jim Blandy, co-authored @file{wyse50.el}, support for -Wyse 50 terminals. - -@item -Richard L.@: Pieri wrote @file{pop3.el}, a Post Office Protocol (RFC -1460) interface for Emacs. - -@item -Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit -widgets. - -@item -Christian Plaunt wrote @file{soundex.el}, an implementation of the -Soundex algorithm for comparing English words by their pronunciation. - -@item -David Ponce wrote: - -@itemize @minus -@item -@file{recentf.el}, a package that puts a menu of recently visited -files in the Emacs menu bar, -@item -@file{ruler-mode.el}, a minor mode for displaying a ruler in the -header line, and -@item -@file{tree-widget.el}, a package to display hierarchical data structures. -@end itemize - -@item -Francesco A.@: Potorti wrote @file{cmacexp.el}, providing a command which -runs the C preprocessor on a region of a file and displays the results. -He also expanded and redesigned the @code{etags} program. - -@item -Michael D.@: Prange and Steven A.@: Wood wrote @file{fortran.el}, a mode for -editing FORTRAN code. -@c We're not distributing his tex-mode.el anymore; we're using Ed Reingold's. - -@item -Mukesh Prasad contributed @file{vmsproc.el}, a facility for running -asynchronous subprocesses on VMS. - -@item -Marko Rahamaa wrote @file{latin-3.el}, code which sets up -case-conversion and syntax tables for the ISO Latin-3 character set. - -@item -Ashwin Ram wrote @file{refer.el}, commands to look up references in -bibliography files by keyword. - -@item -Eric S.@: Raymond wrote: - -@itemize @minus -@item -@file{vc.el}, an interface to the RCS and SCCS source code version -control systems, with Paul Eggert, -@item -@file{gud.el}, a package for running source-level debuggers like GDB -and SDB in Emacs, -@item -@file{asm-mode.el}, a mode for editing assembly language code, -@item -@file{AT386.el}, terminal support package for IBM's AT keyboards, -@item -@file{cookie1.el}, support for ``fortune-cookie'' programs like -@file{yow.el} and @file{spook.el}, -@item -@file{finder.el}, a package for finding Emacs Lisp packages by keyword -and topic, -@item -@file{keyswap.el}, code to swap the @key{BS} and @key{DEL} keys, -@item -@file{loadhist.el}, functions for loading and unloading Emacs features, -@item -@file{lisp-mnt.el}, functions for working with the special headers used -in Emacs Lisp library files, and -@item -code to set and make use of the @code{load-history} lisp variable, which -records the source file from which each lisp function loaded into Emacs -came. -@end itemize - -@item -Edward M.@: Reingold wrote the extensive calendar and diary support (try -@kbd{M-x calendar}), with contributions from Stewart Clamen, Nachum -Dershowitz, Paul Eggert, Steve Fisk, Michael Kifer, and Lara Rios. Andy -Oram contributed to its documentation. Reingold has also contributed to -@file{tex-mode.el}, a mode for editing @TeX{} files, as have William -F.@: Schelter, Dick King, Stephen Gildea, Michael Prange, and Jacob Gore. - -@item -David Reitter wrote @file{mailclient.el} which can send mail via the -system's designated mail client. - -@item -Alex Rezinsky contributed @file{which-func.el}, a mode that shows the -name of the current function in the mode line. - -@item -Rob Riepel contributed @file{tpu-edt.el} and its associated files, -providing an emulation of the VMS TPU text editor emulating the VMS EDT -editor, and @file{vt-control.el}, providing some control functions for -the DEC VT line of terminals. - -@item -Nick Roberts wrote @file{gdb-ui.el}, the graphical user interface to -GDB. - -@item -Roland B.@: Roberts contributed much of the VMS support distributed with -Emacs 19, along with Joseph M.@: Kelsey, and @file{vms-pmail.el}, support -for using Emacs within VMS MAIL. - -@item -John Robinson wrote @file{bg-mouse.el}, support for the mouse on the BBN -Bitgraph terminal. - -@item -Danny Roozendaal implemented @file{handwrite.el}, which converts text -into ``handwriting.'' - -@item -William Rosenblatt wrote @file{float.el}, implementing a floating-point -numeric type using Lisp cons cells and integers. - -@item -Guillermo J.@: Rozas wrote @file{scheme.el}, a mode for editing Scheme and -DSSSL code, and @file{fakemail.c}, an interface to the System V mailer. - -@item -Ivar Rummelhoff provided @file{winner.el}, which records -recent window configurations so you can move back to them. - -@item -Jason Rumney has ported the Emacs 21 display engine to MS-Windows, and -contributed extensively to the MS-Windows port of Emacs. - -@item -Wolfgang Rupprecht contributed Emacs 19's floating-point support -(including @file{float-sup.el} and @file{floatfns.c}), and -@file{sup-mouse.el}, support for the Supdup mouse on lisp machines. - -@item -Kevin Ryde wrote @file{info-xref.el}, a library for checking -references in Info files. - -@item -James B.@: Salem and Brewster Kahle wrote @file{completion.el}, providing -dynamic word completion. - -@item -Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor. - -@item -Holger Schauer wrote @file{fortune.el}, a package for using fortune in -message signatures. - -@item -William Schelter wrote @file{telnet.el}, support for @code{telnet} -sessions within Emacs. - -@item -Ralph Schleicher contributed @file{battery.el}, a package for displaying -laptop computer battery status, and @file{info-look.el}, a package for -looking up Info documentation for symbols in the buffer. - -@item -Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for -editing Modula-2 code, based on work by Mick Jordan and Peter Robinson. - -@item -Ronald S.@: Schnell wrote @file{dunnet.el}, a text adventure game. - -@item -Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played -against Emacs, and @file{mpuz.el}, a multiplication puzzle. - -@item -Jan Schormann wrote @file{solitaire.el}, an Emacs Lisp implementation of -the Solitaire game. - -@item -Alex Schroeder wrote @file{ansi-color.el}, a package for translating -ANSI color escape sequences to Emacs faces, and @file{sql.el}, a package -for interactively running an SQL interpreter in an Emacs buffer. - -@item -Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects. - -@item -Oliver Seidel wrote @file{todo-mode.el}, a package for maintaining -@file{TODO} list files. - -@item -Manuel Serrano contributed the Flyspell package that does spell checking -as you type. - -@item -Hovav Shacham wrote @file{windmove.el}, a set of commands for selecting -windows based on their geometrical position on the frame. - -@item -Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited -commercial email. - -@item -Richard Sharman contributed @file{hilit-chg.el}, which uses colors -to show recent editing changes. - -@item -Olin Shivers wrote: - -@itemize @minus -@item -@file{comint.el}, a library for modes running interactive command-line- -oriented subprocesses, -@item -@file{cmuscheme.el}, for running inferior Scheme processes, -@item -@file{inf-lisp.el}, for running inferior Lisp process, and -@item -@file{shell.el}, for running inferior shells. -@end itemize - -@item -Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code. - -@item -Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating -mostly-constant data. - -@item -Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive -help for key bindings. - -@item -Chris Smith wrote @file{icon.el}, a mode for editing Icon code. - -@item -David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs -Lisp interpreter as a subprocess. - -@item -Paul D.@: Smith wrote @file{snmp-mode.el}. - -@item -William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe -files, and @file{server.el}, a package allowing programs to send files -to an extant Emacs job to be edited. - -@item -Andre Spiegel made many contributions to the Emacs Version Control -package, and in particular made it support multiple back ends. - -@item -Michael Staats wrote @file{pc-select.el}, which rebinds keys for -selecting regions to follow many other systems. - -@item -Richard Stallman invented Emacs, and then wrote: - -@itemize @minus -@item -@file{easymenu.el}, a facility for defining Emacs menus, -@item -@file{menu-bar.el}, the Emacs menu bar support code, -@item -@file{paren.el}, a package to make matching parentheses stand out in -color, and -@item -most of the rest of Emacs code. -@end itemize - -@item -Sam Steingold wrote @file{gulp.el}, a facility for asking package -maintainers for updated versions of their packages via e-mail, and -@file{midnight.el}, a package for running a command every midnight. - -@item -Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for -browsing indices made from buffer contents. - -@item -Peter Stephenson contributed @file{vcursor.el}, which implements a -``virtual cursor'' that you can move with the keyboard and use for -copying text. - -@item -Ken Stevens wrote the initial version of @file{ispell.el} and maintains -that package since Ispell 3.1 release. - -@item -Jonathan Stigelman wrote @file{hilit19.el}, a package providing -automatic highlighting in source code buffers, mail readers, and other -contexts. - -@item -Kim F.@: Storm made many improvements to the Emacs display engine, -process support, and networking support. He also wrote: - -@itemize @minus -@item -@file{bindat.el}, a package for encoding and decoding binary data. -@item -@file{cua.el}, which allows Emacs to emulate the standard CUA key -bindings. -@item -@file{ido.el}, a package for selecting buffers and files quickly. -@item -@file{kmacro.el}, the keyboard macro facility. -@end itemize - -@item -Martin Stjernholm co-authored CC Mode, a major editing mode for C, -C@t{++}, Objective-C, Java, Pike, CORBA IDL, and AWK code. - -@item -Steve Strassman did not write @file{spook.el}, and even if he did, he -really didn't mean for you to use it in an anarchistic way. - -@item -Olaf Sylvester wrote @file{bs.el}, a package for manipulating Emacs -buffers. - -@item -Tibor @v{S}imko and Milan Zamazal wrote @file{slovak.el}, support for -editing text in Slovak language. - -@item -Naoto Takahashi wrote @file{utf-8.el}, support for encoding and -decoding UTF-8 data. - -@item -Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through -the keyboard. - -@item -Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing -image files as ``thumbnails.'' - -@item -Jens T.@: Berger Thielemann wrote @file{word-help.el}, which is -part of the basis for @file{info-look.el}. - -@item -Spencer Thomas wrote the original @file{dabbrev.el}, providing a command -which completes the partial word before point, based on other nearby -words for which it is a prefix. He also wrote the original dumping -support. - -@item -Jim Thompson wrote @file{ps-print.el}, which converts -Emacs text to PostScript. - -@item -Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a major mode for -editing Tcl/Tk source files and running a Tcl interpreter as an Emacs -subprocess. - -@item -Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL. -@item -Daiki Ueno wrote @file{starttls.el}, support for Transport Layer -Security protocol, and the PGG package adding GnuPG and PGP support. - -@item -Masanobu Umeda wrote: - -@itemize @minus -@item -GNUS, a feature-full reader for Usenet news, -@item -@file{prolog.el}, a mode for editing Prolog code, -@item -@file{rmailsort.el}, a package for sorting messages in RMAIL folders, -@item -@file{metamail.el}, an interface to the Metamail program, -@item -@file{gnus-kill.el}, the Kill File mode for Gnus, -@item -@file{gnus-mh.el}, an mh-e interface for Gnus, -@item -@file{gnus-msg.el}, a mail and post interface for Gnus, -@item -@file{tcp.el}, emulation of the @code{open-network-stream} function for -some Emacs configurations which lack it, and -@item -@file{timezone.el}, providing functions for dealing with time zones. -@end itemize - -@item -Rajesh Vaidheeswarran wrote @file{whitespace.el}, a package that -detects and cleans up excess whitespace in a file. - -@item -Neil W.@: Van Dyke wrote @file{webjump.el}, a ``hot links'' package. - -@item -Didier Verna contributed @file{rect.el}, a package of functions for -operations on rectangle regions of text. - -@item -Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code. - -@item -Geoffrey Voelker wrote the Windows NT support. He also wrote -@file{dos-w32.el}, functions shared by the MS-DOS and MS-Windows ports -of Emacs, and @file{w32-fns.el}, MS-Windows specific support functions. - -@item -Johan Vromans wrote @file{forms.el} and its associated files, a -mode for filling in forms. - -@item -Colin Walters wrote @file{ibuffer.el}, a Dired-like major mode for -operating on buffers. - -@item -Barry Warsaw wrote: - -@itemize @minus -@item -@file{assoc.el}, a set of utility functions for working with association -lists, -@item -@file{cc-mode.el}, a major mode for editing C, C@t{++}, and Java code, -based on earlier work by Dave Detlefs, Stewart Clamen, and Richard -Stallman, -@item -@file{elp.el}, a new profiler for Emacs Lisp programs. -@item -@file{man.el}, a mode for reading UNIX manual pages, -@item -@file{regi.el}, providing an AWK-like functionality for use in lisp -programs, -@item -@file{reporter.el}, providing customizable bug reporting for lisp -packages, and -@item -@file{supercite.el}, a minor mode for quoting sections of mail messages -and news articles. -@end itemize - -@item -Morten Welinder introduced face support into the MS-DOS port of Emacs, -and also wrote: - -@itemize @minus -@item -@file{desktop.el}, facilities for saving some of Emacs's state between -sessions, -@item -@file{timer.el}, the Emacs facility to run commands at a given time or -frequency, or when Emacs is idle, and its C-level support code, -@item -@file{pc-win.el}, the MS-DOS ``window-system'' support, -@item -@file{internal.el}, an ``internal terminal'' emulator for the MS-DOS -port of Emacs, -@item -@file{arc-mode.el}, the mode for editing compressed archives, -@item -@file{s-region.el}, commands for setting the region using the shift key -and motion commands, and -@item -@file{dos-fns.el}, functions for use under MS-DOS. -@end itemize - -He also helped port Emacs to MS-DOS. - -@item -Joseph Brian Wells wrote: - -@itemize @minus -@item -@file{apropos.el}, a command to find commands, functions, and variables -whose names contain matches for a regular expression, -@item -@file{resume.el}, support for processing command-line arguments after -resuming a suspended Emacs job, and -@item -@file{mail-extr.el}, a package for extracting names and addresses from -mail headers, with contributions from Jamie Zawinski. -@end itemize - -@item -Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}, a major -mode for editing VHDL source code. - -@item -John Wiegley wrote @file{align.el}, a set of commands for aligning text -according to regular-expression based rules; @file{timeclock.el}, a -package for keeping track of time spent on projects; -@file{pcomplete.el}, a programmable completion facility; and -@code{eshell}, a command shell implemented entirely in Emacs Lisp. - -@item -Ed Wilkinson wrote @file{b2m.c}, a program to convert mail files from -RMAIL format to Unix @code{mbox} format. - -@item -Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse -selection, and @file{thingatpt.el}, a library of functions for finding -the ``thing'' (word, line, s-expression) containing point. - -@item -Bill Wohler wrote the Emacs interface to the MH mail system. - -@item -Dale R.@: Worley wrote @file{emerge.el}, a package for interactively -merging two versions of a file. - -@item -Francis J.@: Wright wrote @code{WoMan}, a package for browsing -manual pages without the @code{man} command. - -@item -Tom Wurgler wrote @file{emacs-lock.el}, which makes it harder -to exit with valuable buffers unsaved. - -@item -Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU -linker scripts, and contributed subword handling in CC mode. - -@item -Jonathan Yavner wrote @file{testcover.el}, a package for keeping track -of the testing status of Emacs Lisp code, and the SES spreadsheet -package. - -@item -Ryan Yeske wrote @file{rcirc.el} a simple Internet Relay Chat client. -@item -Ilya Zakharevich and Bob Olson contributed @file{cperl-mode.el}, a major -mode for editing Perl code. Ilya Zakharevich also wrote @file{tmm.el}, -a mode for accessing the Emacs menu bar on a text-mode terminal. - -@item -Milan Zamazal wrote @file{czech.el}, support for editing Czech text, -@file{glasses.el}, a package for easier reading of source code which -uses illegible identifier names such as @code{cantReadThisVariable}, and -@file{tildify.el}, commands for adding hard spaces to text, @TeX{}, and -SGML/HTML files. - -@item -Victor Zandy contributed @file{zone.el}, a package for people who like -to zone out in front of Emacs. - -@item -Eli Zaretskii made many standard Emacs features work on MS-DOS. He also -wrote @file{tty-colors.el}, which implements transparent mapping of X -colors to tty colors, and (together with Kenichi Handa) -@file{codepage.el}, a package for editing text encoded in DOS/Windows -code pages. - -@item -Jamie Zawinski wrote: - -@itemize @minus -@item -Emacs 19's optimizing byte compiler, with Hallvard Furuseth, -@item -much of the support for faces and X selections, -@item -@file{mailabbrev.el}, a package providing automatic expansion of mail -aliases, and -@item -@file{tar-mode.el}, providing simple viewing and editing commands for -tar files. -@end itemize - -@item -Andrew Zhilin created the Emacs icons used beginning with Emacs 22. - -@item -Shenghuo Zhu wrote: - -@itemize @minus -@item -@file{binhex.el}, a package for reading and writing binhex files, -@item -@file{mm-partial.el}, message/partial support for MIME messages, -@item -@file{rfc1843.el}, an HZ decoding package, -@item -@file{uudecode.el}, an Emacs Lisp decoder for uuencoded data, -@item -@file{webmail.el}, an interface to Web mail. -@end itemize - -@item -Ian T.@: Zimmerman wrote @file{gametree.el}. - -@item -Neal Ziring and Felix S.@: T.@: Wu wrote @file{vi.el}, an emulation of the -VI text editor. - -@item -Detlev Zundel wrote @file{re-builder.el}, a package for building regexps -with visual feedback. - -@end itemize - -Others too numerous to mention have reported and fixed bugs, and added -features to many parts of Emacs. (Many are mentioned in the -@file{ChangeLog} files which are summarized in the file @file{AUTHORS} -in the distribution.) We thank them for their generosity as well. - -This list intended to mention every contributor of a major package or -feature we currently distribute; if you know of someone we have omitted, -please report that as a manual bug. - -@ignore - arch-tag: bb1d0fa4-0240-4992-b5d4-8602d1e3d4ba -@end ignore diff --git a/man/ada-mode.texi b/man/ada-mode.texi deleted file mode 100644 index 241149803e8..00000000000 --- a/man/ada-mode.texi +++ /dev/null @@ -1,1410 +0,0 @@ -\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/man/anti.texi b/man/anti.texi deleted file mode 100644 index ebff1c7677f..00000000000 --- a/man/anti.texi +++ /dev/null @@ -1,306 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Antinews, Mac OS, X Resources, Top -@appendix Emacs 21 Antinews - - For those users who live backwards in time, here is information about -downgrading to Emacs version 21.4. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs @value{EMACSVER} -features. - -@itemize @bullet - -@item -The buffer position and line number are now displayed at the end of -the mode line, where they can be more easily seen. - -@item -The mode line of the selected window is no longer displayed with a -special face. All mode lines are created equal. Meanwhile, you can -use the variable @code{mode-line-inverse-video} to control whether -mode lines are highlighted at all---@code{nil} means don't highlight -them. - -@item -Clicking on a link with the left mouse button (@kbd{mouse-1}) will -always set point at the position clicked, instead of following the -link. If you want to follow the link, use the middle mouse button -(@kbd{mouse-2}). - -@item -Emacs is tired of X droppings. If you drop a file or a piece of text -onto an Emacs window, nothing will happen. - -@item -On an xterm, even if you enable Xterm Mouse mode, Emacs provides a -more convincing simulation of a text terminal by not responding to -mouse clicks on the mode line, header line, or display margin. - -@item -For simplicity, windows always have fringes. We wouldn't want to -in-fringe anyone's windows. Likewise, horizontal scrolling always -works in the same automatic way. - -@item -The horizontal-bar cursor shape has been removed. - -@item -If command line arguments are given, Emacs will not display a splash -screen, so that you can immediately get on with your editing. The -command-line option @samp{--no-splash} is therefore obsolete, and has -been removed. - -@item -These command line options have also been removed: @samp{--color}, -@samp{--fullwidth}, @samp{--fullheight}, @samp{--fullscreen}, -@samp{--no-blinking-cursor}, @samp{--no-desktop}, and @samp{-Q}. - -@item -The @samp{--geometry} option applies only to the initial frame, and -the @samp{-f} option will not read arguments for interactive -functions. - -@item -We have standardized on one location for the user init file: the file -named @file{.emacs} in your home directory. Emacs will not look for -the init file in @file{~/.emacs.d/init.el}. Similarly, don't try -putting @file{.emacs_SHELL} as @file{init_SHELL.sh} in -@file{~/.emacs.d}; Emacs won't find it. - -@item -Emacs will not read @file{~/.abbrev_defs} automatically. If you want -to load abbrev definitions from a file, you must always do so -explicitly. - -@item -When you are logged in as root, all files now give you writable -buffers, reflecting the fact that you can write any files. - -@item -The maximum size of buffers and integer variables has been halved. On -32-bit machines, the maximum buffer size is now 128 megabytes. - -@item -An unquoted @samp{$} in a file name is now an error, if the following -name is not recognized as an environment variable. Thus, -the file name @file{foo$bar} would probably be an error. Meanwhile, -the @code{setenv} command does not expand @samp{$} at all. - -@item -If a single command accumulates too much undo information, Emacs never -discards it. If Emacs runs out of memory as a result, it will handle -this by crashing. - -@item -Many commands have been removed from the menus or rearranged. - -@item -The @kbd{C-h} (help) subcommands have been rearranged---especially -those that display specific files. Type @kbd{C-h C-h} to see a list -of these commands; that will show you what is different. - -@item -The @kbd{C-h v} and @kbd{C-h f} commands no longer show a hyperlink to -the C source code, even if it is available. If you want to find the -source code, grep for it. - -@item -The apropos commands will not accept a list of words to match, in -order to encourage you to be more specific. Also, the user option -@code{apropos-sort-by-scores} has been removed. - -@item -The minibuffer prompt is now displayed using the default face. -The colon is enough to show you what part is the prompt. - -@item -Minibuffer completion commands always complete the entire minibuffer -contents, just as if you had typed them at the end of the minibuffer, -no matter where point is actually located. - -@item -The command @code{backward-kill-sexp} is now bound to @kbd{C-M-delete} -and @kbd{C-M-backspace}. Be careful when using these key sequences! -It may shut down your X server, or reboot your operating system. - -@item -Commands to set the mark at a place away from point, including -@kbd{M-@@}, @kbd{M-h}, etc., don't do anything special when you repeat -them. In most cases, typing these commands multiple times is -equivalent to typing them once. @kbd{M-h} ignores numeric arguments. - -@item -The user option @code{set-mark-command-repeat-pop} has been removed. - -@item -@kbd{C-@key{SPC} C-@key{SPC}} has no special meaning--it just sets the -mark twice. Neither does @kbd{C-u C-x C-x}, which simply exchanges -point and mark like @kbd{C-x C-x}. - -@item -The function @code{sentence-end} has been eliminated in favor of a -more straightforward approach: directly setting the variable -@code{sentence-end}. For example, to end each sentence with a single -space, use - -@lisp -(setq sentence-end "[.?!][]\"')@}]*\\($\\|[ \t]\\)[ \t\n]*") -@end lisp - -@item -The variable @code{fill-nobreak-predicate} is no longer customizable, -and it can only hold a single function. - -@item -Nobreak spaces and hyphens are displayed just like normal characters, -and the user option @code{nobreak-char-display} has been removed. - -@item -@kbd{C-w} in an incremental search always grabs an entire word -into the search string. More precisely, it grabs text through -the next end of a word. - -@item -Yanking now preserves all text properties that were in the killed -text. The variable @code{yank-excluded-properties} has been removed. - -@item -Occur mode, Info mode, and Comint-derived modes now control -fontification in their own way, and @kbd{M-x font-lock-mode} has -nothing to do with it. To control fontification in Info mode, use the -variable @code{Info-fontify}. - -@item -@samp{M-x shell} is now completely standard in regard to scrolling -behavior. It no longer has the option of scrolling the input line to -the bottom of the window the way a text terminal running a shell does. - -@item -The Grep package has been merged with Compilation mode. Many -grep-specific commands and user options have thus been eliminated. -Also, @kbd{M-x grep} never tries the GNU grep @samp{-H} option, -and instead silently appends @file{/dev/null} to the command line. - -@item -In Dired's @kbd{!} command, @samp{*} and @samp{?} now -cause substitution of the file names wherever they appear---not -only when they are surrounded by whitespace. - -@item -When a file is managed with version control, the command @kbd{C-x C-q} -(whose general meaning is to make a buffer read-only or writable) now -does so by checking the file in or out. Checking the file out makes -the buffer writable; checking it in makes the buffer read-only. - -You can still use @kbd{C-x v v} to do these operations if you wish; -its meaning is unchanged. If you want to control the buffer's -read-only flag without performing any version control operation, -use @kbd{M-x toggle-read-only}. - -@item -SGML mode does not handle XML syntax, and does not have indentation -support. - -@item -Many Info mode commands have been removed. Incremental search in Info -searches only the current node. - -@item -Many @code{etags} features for customizing parsing using regexps -have been removed. - -@item -The Emacs server now runs a small C program called @file{emacsserver}, -rather than trying to handle everything in Emacs Lisp. Now there can -only be one Emacs server running at a time. The @code{server-mode} -command and @code{server-name} user option have been eliminated. - -@item -The @file{emacsclient} program no longer accepts the @samp{--eval}, -@samp{--display} and @samp{--server-file} command line options, and -can only establish local connections using Unix domain sockets. - -@item -The command @code{quail-show-key}, for showing how to input a -character, has been removed. - -@item -The default value of @code{keyboard-coding-system} is always -@code{nil}, regardless of your locale settings. If you want some -other value, set it yourself. - -@item -Unicode support and unification between Latin-@var{n} character sets -have been removed. Cutting and pasting X selections does not support -``extended segments'', so there are certain coding systems it cannot -handle. - -@item -The input methods for Emacs are included in a separate distribution -called ``Leim.'' To use this, you must extract the Leim tar file on -top of the Emacs distribution, into the same directory, before you -build Emacs. - -@item -The following input methods have been eliminated: 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. - -@item -The following language environments have been eliminated: Belarusian, -Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, -Latin-6, Latin-7, Latvian, Lithuanian, Malayalam, Russian, Russian, -Slovenian, Swedish, Tajik, Tamil, UTF-8, Ukrainian, Ukrainian, Welsh, -and Windows-1255. - -@item -The @code{code-pages} library, which contained various 8-bit coding -systems, has been removed. - -@item -The Kmacro package has been replaced with a simple and elegant -keyboard macro system. Use @kbd{C-x (} to start a new keyboard macro, -@kbd{C-x )} to end the macro, and @kbd{C-x e} to execute the last -macro. Use @kbd{M-x name-last-kbd-macro} to name the most recently -defined macro. - -@item -Emacs no longer displays your breakpoints in the source buffer, so you -have to remember where you left them. It can be difficult to inspect -the state of your debugged program from the command line, so Emacs -tries to demonstrate this in the GUD buffer. - -@item -The Calc, CUA, Ibuffer, Ido, Password, Printing, Reveal, -Ruler-mode, SES, Table, Tramp, and URL packages have been removed. -The Benchmark, Cfengine, Conf, Dns, Flymake, Python, Thumbs, and -Wdired modes have also been removed. - -@item -The Emacs Lisp Reference Manual and the Introduction to Programming in -Emacs Lisp are now distributed separately, not in the Emacs -distribution. - -@item -On MS Windows, there is no longer any support for tooltips, images, -sound, different mouse pointer shapes, or pointing devices with more -than 3 buttons. If you want these features, consider switching to -another operating system. But even if you don't want these features, -you should still switch---for freedom's sake. - -@item -Emacs will not use Unicode for clipboard operations on MS Windows. - -@item -To keep up with decreasing computer memory capacity and disk space, many -other functions and files have been eliminated in Emacs 21.4. -@end itemize - -@ignore - arch-tag: 32932bd9-46f5-41b2-8a0e-fb0cc4caeb29 -@end ignore diff --git a/man/arevert-xtra.texi b/man/arevert-xtra.texi deleted file mode 100644 index c2b1ddc2ffe..00000000000 --- a/man/arevert-xtra.texi +++ /dev/null @@ -1,191 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Autorevert -@section Auto Reverting non-file Buffers - -Normally Global Auto Revert Mode only reverts file buffers. There are -two ways to auto-revert certain non-file buffers: enabling Auto Revert -Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting -@code{global-auto-revert-non-file-buffers} to @code{t}. The latter -enables Auto Reverting for all types of buffers for which it is -implemented, that is, for the types of buffers listed in the menu -below. - -Like file buffers, non-file buffers should normally not revert while -you are working on them, or while they contain information that might -get lost after reverting. Therefore, they do not revert if they are -``modified''. This can get tricky, because deciding when a non-file -buffer should be marked modified is usually more difficult than for -file buffers. - -Another tricky detail is that, for efficiency reasons, Auto Revert -often does not try to detect all possible changes in the buffer, only -changes that are ``major'' or easy to detect. Hence, enabling -auto-reverting for a non-file buffer does not always guarantee that -all information in the buffer is up to date and does not necessarily -make manual reverts useless. - -At the other extreme, certain buffers automatically auto-revert every -@code{auto-revert-interval} seconds. (This currently only applies to -the Buffer Menu.) In this case, Auto Revert does not print any -messages while reverting, even when @code{auto-revert-verbose} is -non-@code{nil}. - -The details depend on the particular types of buffers and are -explained in the corresponding sections. - -@menu -* Auto Reverting the Buffer Menu:: -* Auto Reverting Dired:: -* Supporting additional buffers:: -@end menu - -@node Auto Reverting the Buffer Menu -@subsection Auto Reverting the Buffer Menu - -If auto-reverting of non-file buffers is enabled, the Buffer Menu -automatically reverts every @code{auto-revert-interval} seconds, -whether there is a need for it or not. (It would probably take longer -to check whether there is a need than to actually revert.) - -If the Buffer Menu inappropriately gets marked modified, just revert -it manually using @kbd{g} and auto-reverting will resume. However, if -you marked certain buffers to get deleted or to be displayed, you have -to be careful, because reverting erases all marks. The fact that -adding marks sets the buffer's modified flag prevents Auto Revert from -automatically erasing the marks. - -@node Auto Reverting Dired -@subsection Auto Reverting Dired buffers - -Auto-reverting Dired buffers currently works on GNU or Unix style -operating systems. It may not work satisfactorily on some other -systems. - -Dired buffers only auto-revert when the file list of the buffer's main -directory changes. They do not auto-revert when information about a -particular file changes or when inserted subdirectories change. To be -sure that @emph{all} listed information is up to date, you have to -manually revert using @kbd{g}, @emph{even} if auto-reverting is -enabled in the Dired buffer. Sometimes, you might get the impression -that modifying or saving files listed in the main directory actually -does cause auto-reverting. This is because making changes to a file, -or saving it, very often causes changes in the directory itself, for -instance, through backup files or auto-save files. However, this is -not guaranteed. - -If the Dired buffer is marked modified and there are no changes you -want to protect, then most of the time you can make auto-reverting -resume by manually reverting the buffer using @kbd{g}. There is one -exception. If you flag or mark files, you can safely revert the -buffer. This will not erase the flags or marks (unless the marked -file has been deleted, of course). However, the buffer will stay -modified, even after reverting, and auto-reverting will not resume. -This is because, if you flag or mark files, you may be working on the -buffer and you might not want the buffer to change without warning. -If you want auto-reverting to resume in the presence of marks and -flags, mark the buffer non-modified using @kbd{M-~}. However, adding, -deleting or changing marks or flags will mark it modified again. - -Remote Dired buffers are not auto-reverted. Neither are Dired buffers -for which you used shell wildcards or file arguments to list only some -of the files. @samp{*Find*} and @samp{*Locate*} buffers do not -auto-revert either. - -@node Supporting additional buffers -@subsection Adding Support for Auto-Reverting additional Buffers. - -This section is intended for Elisp programmers who would like to add -support for auto-reverting new types of buffers. - -To support auto-reverting the buffer must first of all have a -@code{revert-buffer-function}. @xref{Definition of -revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. - -In addition, it @emph{must} have a @code{buffer-stale-function}. - -@defvar buffer-stale-function -The value of this variable is a function to check whether a non-file -buffer needs reverting. This should be a function with one optional -argument @var{noconfirm}. The function should return non-@code{nil} -if the buffer should be reverted. The buffer is current when this -function is called. - -While this function is mainly intended for use in auto-reverting, it -could be used for other purposes as well. For instance, if -auto-reverting is not enabled, it could be used to warn the user that -the buffer needs reverting. The idea behind the @var{noconfirm} -argument is that it should be @code{t} if the buffer is going to be -reverted without asking the user and @code{nil} if the function is -just going to be used to warn the user that the buffer is out of date. -In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. -If the function is only going to be used for auto-reverting, you can -ignore the @var{noconfirm} argument. - -If you just want to automatically auto-revert every -@code{auto-revert-interval} seconds, use: - -@example -(set (make-local-variable 'buffer-stale-function) - #'(lambda (&optional noconfirm) 'fast)) -@end example - -@noindent -in the buffer's mode function. - -The special return value @samp{fast} tells the caller that the need -for reverting was not checked, but that reverting the buffer is fast. -It also tells Auto Revert not to print any revert messages, even if -@code{auto-revert-verbose} is non-@code{nil}. This is important, as -getting revert messages every @code{auto-revert-interval} seconds can -be very annoying. The information provided by this return value could -also be useful if the function is consulted for purposes other than -auto-reverting. -@end defvar - -Once the buffer has a @code{revert-buffer-function} and a -@code{buffer-stale-function}, several problems usually remain. - -The buffer will only auto-revert if it is marked unmodified. Hence, -you will have to make sure that various functions mark the buffer -modified if and only if either the buffer contains information that -might be lost by reverting or there is reason to believe that the user -might be inconvenienced by auto-reverting, because he is actively -working on the buffer. The user can always override this by manually -adjusting the modified status of the buffer. To support this, calling -the @code{revert-buffer-function} on a buffer that is marked -unmodified should always keep the buffer marked unmodified. - -It is important to assure that point does not continuously jump around -as a consequence of auto-reverting. Of course, moving point might be -inevitable if the buffer radically changes. - -You should make sure that the @code{revert-buffer-function} does not -print messages that unnecessarily duplicate Auto Revert's own messages -if @code{auto-revert-verbose} is @code{t} and effectively override a -@code{nil} value for @code{auto-revert-verbose}. Hence, adapting a -mode for auto-reverting often involves getting rid of such messages. -This is especially important for buffers that automatically -auto-revert every @code{auto-revert-interval} seconds. - -Also, you may want to update the documentation string of -@code{global-auto-revert-non-file-buffers}. - -@ifinfo -Finally, you should add a node to this chapter's menu. This node -@end ifinfo -@ifnotinfo -Finally, you should add a section to this chapter. This section -@end ifnotinfo -should at the very least make clear whether enabling auto-reverting -for the buffer reliably assures that all information in the buffer is -completely up to date (or will be after @code{auto-revert-interval} -seconds). - -@ignore - arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e -@end ignore diff --git a/man/autotype.texi b/man/autotype.texi deleted file mode 100644 index 7b51f3115ac..00000000000 --- a/man/autotype.texi +++ /dev/null @@ -1,676 +0,0 @@ -\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/man/basic.texi b/man/basic.texi deleted file mode 100644 index 333985e4a4a..00000000000 --- a/man/basic.texi +++ /dev/null @@ -1,776 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Basic, Minibuffer, Exiting, Top -@chapter Basic Editing Commands - -@kindex C-h t -@findex help-with-tutorial - Here we explain the basics of how to enter text, make corrections, -and save the text in a file. If this material is new to you, we -suggest you first run the Emacs learn-by-doing tutorial, by typing -@kbd{Control-h t} inside Emacs. (@code{help-with-tutorial}). - - To clear and redisplay the screen, type @kbd{C-l} (@code{recenter}). - -@menu - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: Moving the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Files: Basic Files. Visiting, creating, and saving files. -* Help: Basic Help. Asking what a character does. -* Blank Lines:: Making and deleting blank lines. -* Continuation Lines:: How Emacs displays lines too wide for the screen. -* Position Info:: What page, line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command N times. -* Repeating:: Repeating the previous command quickly. -@end menu - -@node Inserting Text -@section Inserting Text - -@cindex insertion -@cindex graphic characters - Typing printing characters inserts them into the text you are -editing. It inserts them into the buffer at the cursor; more -precisely, it inserts them at @dfn{point}, but the cursor normally -shows where point is. @xref{Point}. - - Insertion moves the cursor forward, and the following text moves -forward with the cursor. If the text in the buffer is @samp{FOOBAR}, -with the cursor before the @samp{B}, and you type @kbd{XX}, you get -@samp{FOOXXBAR}, with the cursor still before the @samp{B}. - - To @dfn{delete} text you have just inserted, use the large key -labeled @key{DEL}, @key{BACKSPACE} or @key{DELETE} which is a short -distance above the @key{RET} or @key{ENTER} key. Regardless of the -label on that key, Emacs thinks of it as @key{DEL}, and that's what we -call it in this manual. @key{DEL} is the key you normally use outside -Emacs to erase the last character that you typed. - - The @key{DEL} key deletes the character @emph{before} the cursor. -As a consequence, the cursor and all the characters after it move -backwards. If you type a printing character and then type @key{DEL}, -they cancel out. - - On most computers, Emacs sets up @key{DEL} automatically. In some -cases, especially with text-only terminals, Emacs may guess wrong. If -the key that ought to erase the last character doesn't do it in Emacs, -see @ref{DEL Does Not Delete}. - - Most PC keyboards have both a @key{BACKSPACE} key a little ways -above @key{RET} or @key{ENTER}, and a @key{DELETE} key elsewhere. On -these keyboards, Emacs tries to set up @key{BACKSPACE} as @key{DEL}. -The @key{DELETE} key deletes ``forwards'' like @kbd{C-d} (see below), -which means it deletes the character underneath the cursor (after -point). - -@kindex RET -@cindex newline - To end a line and start typing a new one, type @key{RET}. (This -key may be labeled @key{RETURN} or @key{ENTER}, but in Emacs we call -it @key{RET}.) This inserts a newline character in the buffer. If -point is at the end of the line, this creates a new blank line after -it. If point is in the middle of a line, the effect is to split that -line. Typing @key{DEL} when the cursor is at the beginning of a line -deletes the preceding newline character, thus joining the line with -the one before it. - - Emacs can split lines automatically when they become too long, if -you turn on a special minor mode called @dfn{Auto Fill} mode. -@xref{Filling}, for Auto Fill mode and other methods of @dfn{filling} -text. - - If you prefer printing characters to replace (overwrite) existing -text, rather than shove it to the right, you should enable Overwrite -mode, a minor mode. @xref{Minor Modes}. - -@cindex quoting -@kindex C-q -@findex quoted-insert - Only printing characters and @key{SPC} insert themselves in Emacs. -Other characters act as editing commands and do not insert themselves. -These include control characters, and characters with codes above 200 -octal. If you need to insert one of these characters in the buffer, -you must @dfn{quote} it by typing the character @kbd{Control-q} -(@code{quoted-insert}) first. (This character's name is normally -written @kbd{C-q} for short.) There are two ways to use -@kbd{C-q}: - -@itemize @bullet -@item -@kbd{C-q} followed by any non-graphic character (even @kbd{C-g}) -inserts that character. - -@item -@kbd{C-q} followed by a sequence of octal digits inserts the character -with the specified octal character code. You can use any number of -octal digits; any non-digit terminates the sequence. If the -terminating character is @key{RET}, it serves only to terminate the -sequence. Any other non-digit terminates the sequence and then acts -as normal input---thus, @kbd{C-q 1 0 1 B} inserts @samp{AB}. - -The use of octal sequences is disabled in ordinary non-binary -Overwrite mode, to give you a convenient way to insert a digit instead -of overwriting with it. -@end itemize - -@cindex 8-bit character codes -@noindent -When multibyte characters are enabled, if you specify a code in the -range 0200 through 0377 octal, @kbd{C-q} assumes that you intend to -use some ISO 8859-@var{n} character set, and converts the specified -code to the corresponding Emacs character code. @xref{Enabling -Multibyte}. You select @emph{which} of the ISO 8859 character sets to -use through your choice of language environment (@pxref{Language -Environments}). - -@vindex read-quoted-char-radix -To use decimal or hexadecimal instead of octal, set the variable -@code{read-quoted-char-radix} to 10 or 16. If the radix is greater than -10, some letters starting with @kbd{a} serve as part of a character -code, just like digits. - -A numeric argument tells @kbd{C-q} how many copies of the quoted -character to insert (@pxref{Arguments}). - -@findex newline -@findex self-insert - Customization information: @key{DEL} in most modes runs the command -@code{delete-backward-char}; @key{RET} runs the command -@code{newline}, and self-inserting printing characters run the command -@code{self-insert}, which inserts whatever character you typed. Some -major modes rebind @key{DEL} to other commands. - -@node Moving Point -@section Changing the Location of Point - -@cindex arrow keys -@cindex moving point -@cindex movement -@cindex cursor motion -@cindex moving the cursor - To do more than insert characters, you have to know how to move point -(@pxref{Point}). The simplest way to do this is with arrow keys, or by -clicking the left mouse button where you want to move to. - - There are also control and meta characters for cursor motion. Some -are equivalent to the arrow keys (it is faster to use these control -keys than move your hand over to the arrow keys). Others do more -sophisticated things. - -@kindex C-a -@kindex C-e -@kindex C-f -@kindex C-b -@kindex C-n -@kindex C-p -@kindex M-> -@kindex M-< -@kindex M-r -@kindex LEFT -@kindex RIGHT -@kindex UP -@kindex DOWN -@findex move-beginning-of-line -@findex move-end-of-line -@findex forward-char -@findex backward-char -@findex next-line -@findex previous-line -@findex beginning-of-buffer -@findex end-of-buffer -@findex goto-char -@findex goto-line -@findex move-to-window-line -@table @kbd -@item C-a -Move to the beginning of the line (@code{move-beginning-of-line}). -@item C-e -Move to the end of the line (@code{move-end-of-line}). -@item C-f -Move forward one character (@code{forward-char}). The right-arrow key -does the same thing. -@item C-b -Move backward one character (@code{backward-char}). The left-arrow -key has the same effect. -@item M-f -Move forward one word (@code{forward-word}). -@item M-b -Move backward one word (@code{backward-word}). -@item C-n -Move down one line vertically (@code{next-line}). This command -attempts to keep the horizontal position unchanged, so if you start in -the middle of one line, you move to the middle of the next. The -down-arrow key does the same thing. -@item C-p -Move up one line, vertically (@code{previous-line}). The up-arrow key -has the same effect. This command preserves position within the line, -like @kbd{C-n}. -@item M-r -Move point to left margin, vertically centered in the window -(@code{move-to-window-line}). Text does not move on the screen. -A numeric argument says which screen line to place point on, counting -downward from the top of the window (zero means the top line). A -negative argument counts lines up from the bottom (@minus{}1 means the -bottom line). -@item M-< -Move to the top of the buffer (@code{beginning-of-buffer}). With -numeric argument @var{n}, move to @var{n}/10 of the way from the top. -@xref{Arguments}, for more information on numeric arguments.@refill -@item M-> -Move to the end of the buffer (@code{end-of-buffer}). -@item C-v -@itemx @key{PAGEDOWN} -@itemx @key{PRIOR} -Scroll the display one screen forward, and move point if necessary to -put it on the screen (@code{scroll-up}). This doesn't always move -point, but it is commonly used to do so. If your keyboard has a -@key{PAGEDOWN} or @key{PRIOR} key, it does the same thing. - -Scrolling commands are described further in @ref{Scrolling}. -@item M-v -@itemx @key{PAGEUP} -@itemx @key{NEXT} -Scroll one screen backward, and move point if necessary to put it on -the screen (@code{scroll-down}). This doesn't always move point, but -it is commonly used to do so. If your keyboard has a @key{PAGEUP} or -@key{NEXT} key, it does the same thing. -@item M-x goto-char -Read a number @var{n} and move point to buffer position @var{n}. -Position 1 is the beginning of the buffer. -@item M-g M-g -@itemx M-g g -@itemx M-x goto-line -Read a number @var{n} and move point to the beginning of line number -@var{n}. Line 1 is the beginning of the buffer. If point is on or -just after a number in the buffer, and you type @key{RET} with the -minibuffer empty, that number is used for @var{n}. -@item C-x C-n -@findex set-goal-column -@kindex C-x C-n -Use the current column of point as the @dfn{semipermanent goal column} -for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). When a -semipermanent goal column is in effect, those commands always try to -move to this column, or as close as possible to it, after moving -vertically. The goal column remains in effect until canceled. -@item C-u C-x C-n -Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to -preserve the horizontal position, as usual. -@end table - -@vindex track-eol - If you set the variable @code{track-eol} to a non-@code{nil} value, -then @kbd{C-n} and @kbd{C-p}, when starting at the end of the line, move -to the end of another line. Normally, @code{track-eol} is @code{nil}. -@xref{Variables}, for how to set variables such as @code{track-eol}. - -@vindex next-line-add-newlines - @kbd{C-n} normally stops at the end of the buffer when you use it on -the last line of the buffer. However, if you set the variable -@code{next-line-add-newlines} to a non-@code{nil} value, @kbd{C-n} on -the last line of a buffer creates an additional line at the end and -moves down into it. - -@node Erasing -@section Erasing Text - -@table @kbd -@item @key{DEL} -Delete the character before point (@code{delete-backward-char}). -@item C-d -Delete the character after point (@code{delete-char}). -@item @key{DELETE} -@itemx @key{BACKSPACE} -One of these keys, whichever is the large key above the @key{RET} or -@key{ENTER} key, deletes the character before point---it is @key{DEL}. -If @key{BACKSPACE} is @key{DEL}, and your keyboard also has @key{DELETE}, -then @key{DELETE} deletes forwards, like @kbd{C-d}. -@item C-k -Kill to the end of the line (@code{kill-line}). -@item M-d -Kill forward to the end of the next word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of the previous word -(@code{backward-kill-word}). -@end table - -@cindex killing characters and lines -@cindex deleting characters and lines -@cindex erasing characters and lines - You already know about the @key{DEL} key which deletes the character -before point (that is, before the cursor). Another key, @kbd{Control-d} -(@kbd{C-d} for short), deletes the character after point (that is, the -character that the cursor is on). This shifts the rest of the text on -the line to the left. If you type @kbd{C-d} at the end of a line, it -joins that line with the following line. - - To erase a larger amount of text, use the @kbd{C-k} key, which -erases (kills) a line at a time. If you type @kbd{C-k} at the -beginning or middle of a line, it kills all the text up to the end of -the line. If you type @kbd{C-k} at the end of a line, it joins that -line with the following line. - - @xref{Killing}, for more flexible ways of killing text. - -@node Basic Undo -@section Undoing Changes - - Emacs records a list of changes made in the buffer text, so you can -you can undo recent changes, as far as the records go. -Usually each editing command makes a separate entry in the undo -records, but sometimes an entry covers just part of a command, and -very simple commands may be grouped. - -@table @kbd -@item C-x u -Undo one entry of the undo records---usually, one command worth -(@code{undo}). -@item C-_ -@itemx C-/ -The same. -@end table - - The command @kbd{C-x u} (or @kbd{C-_} or @kbd{C-/}) is how you undo. -Normally this command undoes the last change, and moves point back to -where it was before the change. - - If you repeat @kbd{C-x u} (or its aliases), each repetition undoes -another, earlier change, back to the limit of the undo information -available. If all recorded changes have already been undone, the undo -command displays an error message and does nothing. - - The undo command applies only to changes in the buffer; you can't -use it to undo mere cursor motion. However, some cursor motion -commands set the mark, so if you use these commands from time to time, -you can move back to the neighborhoods you have moved through by -popping the mark ring (@pxref{Mark Ring}). - -@node Basic Files -@section Files - - Text that you insert in an Emacs buffer lasts only as long as the -Emacs session. To keep any text permanently you must put it in a -@dfn{file}. Files are named units of text which are stored by the -operating system for you to retrieve later by name. To use the -contents of a file in any way, you must specify the file name. That -includes editing the file with Emacs. - - Suppose there is a file named @file{test.emacs} in your home -directory. To begin editing this file in Emacs, type - -@example -C-x C-f test.emacs @key{RET} -@end example - -@noindent -Here the file name is given as an @dfn{argument} to the command @kbd{C-x -C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to -read the argument, and you type @key{RET} to terminate the argument -(@pxref{Minibuffer}). - - Emacs obeys this command by @dfn{visiting} the file: it creates a -buffer, it copies the contents of the file into the buffer, and then -displays the buffer for editing. If you alter the text, you can -@dfn{save} the new text in the file by typing @kbd{C-x C-s} -(@code{save-buffer}). This copies the altered buffer contents back -into the file @file{test.emacs}, making them permanent. Until you -save, the changed text exists only inside Emacs, and the file -@file{test.emacs} is unaltered. - - To create a file, just visit it with @kbd{C-x C-f} as if it already -existed. This creates an empty buffer, in which you can insert the -text you want to put in the file. Emacs actually creates the file the -first time you save this buffer with @kbd{C-x C-s}. - - To learn more about using files in Emacs, see @ref{Files}. - -@node Basic Help -@section Help - -@cindex getting help with keys - If you forget what a key does, you can find out with the Help -character, which is @kbd{C-h} (or @key{F1}, which is an alias for -@kbd{C-h}). Type @kbd{C-h k} followed by the key of interest; for -example, @kbd{C-h k C-n} tells you what @kbd{C-n} does. @kbd{C-h} is -a prefix key; @kbd{C-h k} is just one of its subcommands (the command -@code{describe-key}). The other subcommands of @kbd{C-h} provide -different kinds of help. Type @kbd{C-h} twice to get a description of -all the help facilities. @xref{Help}. - -@node Blank Lines -@section Blank Lines - -@cindex inserting blank lines -@cindex deleting blank lines - Here are special commands and techniques for inserting and deleting -blank lines. - -@table @kbd -@item C-o -Insert one or more blank lines after the cursor (@code{open-line}). -@item C-x C-o -Delete all but one of many consecutive blank lines -(@code{delete-blank-lines}). -@end table - -@kindex C-o -@kindex C-x C-o -@cindex blank lines -@findex open-line -@findex delete-blank-lines - To insert a new line of text before an existing line, -type the new line of text, followed by @key{RET}. -However, it may be easier to see what you are doing if you first make a -blank line and then insert the desired text into it. This is easy to do -using the key @kbd{C-o} (@code{open-line}), which inserts a newline -after point but leaves point in front of the newline. After @kbd{C-o}, -type the text for the new line. @kbd{C-o F O O} has the same effect as -@w{@kbd{F O O @key{RET}}}, except for the final location of point. - - You can make several blank lines by typing @kbd{C-o} several times, or -by giving it a numeric argument specifying how many blank lines to make. -@xref{Arguments}, for how. If you have a fill prefix, the @kbd{C-o} -command inserts the fill prefix on the new line, if typed at the -beginning of a line. @xref{Fill Prefix}. - - The easy way to get rid of extra blank lines is with the command -@kbd{C-x C-o} (@code{delete-blank-lines}). @kbd{C-x C-o} in a run of -several blank lines deletes all but one of them. @kbd{C-x C-o} on a -lone blank line deletes that one. When point is on a nonblank line, -@kbd{C-x C-o} deletes all following blank lines (if any). - -@node Continuation Lines -@section Continuation Lines - -@cindex continuation line -@cindex wrapping -@cindex line wrapping -@cindex fringes, and continuation lines - When a text line is too long to fit in one screen line, Emacs -displays it on two or more screen lines. This is called -@dfn{continuation} or @dfn{line wrapping}. On graphical displays, -Emacs indicates line wrapping with small bent arrows in the left and -right window fringes. On text-only terminals, Emacs displays a -@samp{\} character at the right margin of a screen line if it is not -the last in its text line. This @samp{\} character says that the -following screen line is not really a new text line. - - When line wrapping occurs just before a character that is wider than one -column, some columns at the end of the previous screen line may be -``empty.'' In this case, Emacs displays additional @samp{\} -characters in the ``empty'' columns before the @samp{\} -character that indicates continuation. - - Continued lines can be difficult to read, since lines can break in -the middle of a word. If you prefer, you can make Emacs insert a -newline automatically when a line gets too long, by using Auto Fill -mode. Or enable Long Lines mode, which ensures that wrapping only -occurs between words. @xref{Filling}. - -@cindex truncation -@cindex line truncation, and fringes - Emacs can optionally @dfn{truncate} long lines---this means -displaying just one screen line worth, and the rest of the long line -does not appear at all. @samp{$} in the last column or a small -straight arrow in the window's right fringe indicates a truncated -line. - - @xref{Line Truncation}, for more about line truncation, -and other variables that control how text is displayed. - -@node Position Info -@section Cursor Position Information - - Here are commands to get information about the size and position of -parts of the buffer, and to count lines. - -@table @kbd -@item M-x what-page -Display the page number of point, and the line number within that page. -@item M-x what-line -Display the line number of point in the whole buffer. -@item M-x line-number-mode -@itemx M-x column-number-mode -Toggle automatic display of the current line number or column number. -@xref{Optional Mode Line}. -@item M-= -Display the number of lines in the current region (@code{count-lines-region}). -@xref{Mark}, for information about the region. -@item C-x = -Display the character code of character after point, character position of -point, and column of point (@code{what-cursor-position}). -@item M-x hl-line-mode -Enable or disable highlighting of the current line. @xref{Cursor -Display}. -@item M-x size-indication-mode -Toggle automatic display of the size of the buffer. -@xref{Optional Mode Line}. -@end table - -@findex what-page -@findex what-line -@cindex line number commands -@cindex location of point -@cindex cursor location -@cindex point location - @kbd{M-x what-line} displays the current line number -in the echo area. You can also see the current line number in the -mode line; see @ref{Mode Line}; but if you narrow the buffer, the -line number in the mode line is relative to the accessible portion -(@pxref{Narrowing}). By contrast, @code{what-line} shows both the -line number relative to the narrowed region and the line number -relative to the whole buffer. - - @kbd{M-x what-page} counts pages from the beginning of the file, and -counts lines within the page, showing both numbers in the echo area. -@xref{Pages}. - -@kindex M-= -@findex count-lines-region - Use @kbd{M-=} (@code{count-lines-region}) to displays the number of -lines in the region (@pxref{Mark}). @xref{Pages}, for the command -@kbd{C-x l} which counts the lines in the current page. - -@kindex C-x = -@findex what-cursor-position - The command @kbd{C-x =} (@code{what-cursor-position}) shows what -cursor's column position, and other information about point and the -character after it. It displays a line in the echo area that looks -like this: - -@smallexample -Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 -@end smallexample - - The four values after @samp{Char:} describe the character that follows -point, first by showing it and then by giving its character code in -decimal, octal and hex. For a non-@acronym{ASCII} multibyte character, these are -followed by @samp{file} and the character's representation, in hex, in -the buffer's coding system, if that coding system encodes the character -safely and with a single byte (@pxref{Coding Systems}). If the -character's encoding is longer than one byte, Emacs shows @samp{file ...}. - - However, if the character displayed is in the range 0200 through -0377 octal, it may actually stand for an invalid UTF-8 byte read from -a file. In Emacs, that byte is represented as a sequence of 8-bit -characters, but all of them together display as the original invalid -byte, in octal code. In this case, @kbd{C-x =} shows @samp{part of -display ...} instead of @samp{file}. - - @samp{point=} is followed by the position of point expressed as a -character count. The start of the buffer is position 1, one character -later is position 2, and so on. The next, larger, number is the total -number of characters in the buffer. Afterward in parentheses comes -the position expressed as a percentage of the total size. - - @samp{column=} is followed by the horizontal position of point, in -columns from the left edge of the window. - - If the buffer has been narrowed, making some of the text at the -beginning and the end temporarily inaccessible, @kbd{C-x =} displays -additional text describing the currently accessible range. For example, it -might display this: - -@smallexample -Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0 -@end smallexample - -@noindent -where the two extra numbers give the smallest and largest character -position that point is allowed to assume. The characters between those -two positions are the accessible ones. @xref{Narrowing}. - - If point is at the end of the buffer (or the end of the accessible -part), the @w{@kbd{C-x =}} output does not describe a character after -point. The output might look like this: - -@smallexample -point=36169 of 36168 (EOB) column=0 -@end smallexample - -@cindex character set of character at point -@cindex font of character at point -@cindex text properties at point -@cindex face at point - @w{@kbd{C-u C-x =}} displays the following additional information about a -character. - -@itemize @bullet -@item -The character set name, and the codes that identify the character -within that character set; @acronym{ASCII} characters are identified -as belonging to the @code{ascii} character set. - -@item -The character's syntax and categories. - -@item -The character's encodings, both internally in the buffer, and externally -if you were to save the file. - -@item -What keys to type to input the character in the current input method -(if it supports the character). - -@item -If you are running Emacs on a graphical display, the font name and -glyph code for the character. If you are running Emacs on a text-only -terminal, the code(s) sent to the terminal. - -@item -The character's text properties (@pxref{Text Properties,,, -elisp, the Emacs Lisp Reference Manual}), including any non-default -faces used to display the character, and any overlays containing it -(@pxref{Overlays,,, elisp, the same manual}). -@end itemize - - Here's an example showing the Latin-1 character A with grave accent, -in a buffer whose coding system is @code{iso-latin-1}, whose -terminal coding system is @code{iso-latin-1} (so the terminal actually -displays the character as @samp{@`A}), and which has font-lock-mode -(@pxref{Font Lock}) enabled: - -@smallexample - character: @`A (2240, #o4300, #x8c0, U+00C0) - charset: latin-iso8859-1 - (Right-Hand Part of Latin Alphabet 1@dots{} - code point: #x40 - syntax: w which means: word - category: l:Latin - to input: type "`A" with latin-1-prefix -buffer code: #x81 #xC0 - file code: #xC0 (encoded by coding system iso-latin-1) - display: terminal code #xC0 - -There are text properties here: - fontified t -@end smallexample - -@node Arguments -@section Numeric Arguments -@cindex numeric arguments -@cindex prefix arguments -@cindex arguments to commands - - In mathematics and computer usage, @dfn{argument} means -``data provided to a function or operation.'' You can give any Emacs -command a @dfn{numeric argument} (also called a @dfn{prefix argument}). -Some commands interpret the argument as a repetition count. For -example, @kbd{C-f} with an argument of ten moves forward ten characters -instead of one. With these commands, no argument is equivalent to an -argument of one. Negative arguments tell most such commands to move or -act in the opposite direction. - -@kindex M-1 -@kindex M-@t{-} -@findex digit-argument -@findex negative-argument - If your terminal keyboard has a @key{META} key (labeled @key{ALT} on -PC keyboards), the easiest way to specify a numeric argument is to -type digits and/or a minus sign while holding down the @key{META} key. -For example, - -@example -M-5 C-n -@end example - -@noindent -moves down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2}, -and so on, as well as @kbd{Meta--}, do this because they are keys bound -to commands (@code{digit-argument} and @code{negative-argument}) that -are defined to set up an argument for the next command. -@kbd{Meta--} without digits normally means @minus{}1. Digits and -@kbd{-} modified with Control, or Control and Meta, also specify numeric -arguments. - -@kindex C-u -@findex universal-argument - You can also specify a numeric argument by typing @kbd{C-u} -(@code{universal-argument}) followed by the digits. The advantage of -@kbd{C-u} is that you can type the digits without modifier keys; thus, -@kbd{C-u} works on all terminals. For a negative argument, type a -minus sign after @kbd{C-u}. A minus sign without digits normally -means @minus{}1. - - @kbd{C-u} alone has the special meaning of -``four times'': it multiplies the argument for the next command by -four. @kbd{C-u C-u} multiplies it by sixteen. Thus, @kbd{C-u C-u -C-f} moves forward sixteen characters. This is a good way to move -forward ``fast,'' since it moves about 1/5 of a line in the usual size -screen. Other useful combinations are @kbd{C-u C-n}, @kbd{C-u C-u -C-n} (move down a good fraction of a screen), @kbd{C-u C-u C-o} (make -``a lot'' of blank lines), and @kbd{C-u C-k} (kill four lines). - - Some commands care whether there is an argument, but ignore its -value. For example, the command @kbd{M-q} (@code{fill-paragraph}) -fills text; with an argument, it justifies the text as well. -(@xref{Filling}, for more information on @kbd{M-q}.) Plain @kbd{C-u} -is a handy way of providing an argument for such commands. - - Some commands use the value of the argument as a repeat count, but do -something peculiar when there is no argument. For example, the command -@kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines, -including their terminating newlines. But @kbd{C-k} with no argument is -special: it kills the text up to the next newline, or, if point is right at -the end of the line, it kills the newline itself. Thus, two @kbd{C-k} -commands with no arguments can kill a nonblank line, just like @kbd{C-k} -with an argument of one. (@xref{Killing}, for more information on -@kbd{C-k}.) - - A few commands treat a plain @kbd{C-u} differently from an ordinary -argument. A few others may treat an argument of just a minus sign -differently from an argument of @minus{}1. These unusual cases are -described when they come up; they exist to make an individual command -more convenient, and they are documented in that command's -documentation string. - - You can use a numeric argument before a self-inserting character to -insert multiple copies of it. This is straightforward when the -character is not a digit; for example, @kbd{C-u 6 4 a} inserts 64 -copies of the character @samp{a}. But this does not work for -inserting digits; @kbd{C-u 6 4 1} specifies an argument of 641. You -can separate the argument from the digit to insert with another -@kbd{C-u}; for example, @kbd{C-u 6 4 C-u 1} does insert 64 copies of -the character @samp{1}. - - We use the term ``prefix argument'' as well as ``numeric argument,'' -to emphasize that you type these argument before the command, and to -distinguish them from minibuffer arguments that come after the -command. - -@node Repeating -@section Repeating a Command -@cindex repeating a command - - Many simple commands, such as those invoked with a single key or -with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by -invoking them with a numeric argument that serves as a repeat count -(@pxref{Arguments}). However, if the command you want to repeat -prompts for input, or uses a numeric argument in another way, that -method won't work. - -@kindex C-x z -@findex repeat - The command @kbd{C-x z} (@code{repeat}) provides another way to repeat -an Emacs command many times. This command repeats the previous Emacs -command, whatever that was. Repeating a command uses the same arguments -that were used before; it does not read new arguments each time. - - To repeat the command more than once, type additional @kbd{z}'s: each -@kbd{z} repeats the command one more time. Repetition ends when you -type a character other than @kbd{z}, or press a mouse button. - - For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20 -characters. You can repeat that command (including its argument) three -additional times, to delete a total of 80 characters, by typing @kbd{C-x -z z z}. The first @kbd{C-x z} repeats the command once, and each -subsequent @kbd{z} repeats it once again. - -@ignore - arch-tag: cda8952a-c439-41c1-aecf-4bc0d6482956 -@end ignore diff --git a/man/buffers.texi b/man/buffers.texi deleted file mode 100644 index b43d72b1067..00000000000 --- a/man/buffers.texi +++ /dev/null @@ -1,665 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Buffers, Windows, Files, Top -@chapter Using Multiple Buffers - -@cindex buffers - The text you are editing in Emacs resides in an object called a -@dfn{buffer}. Each time you visit a file, a buffer is created to hold the -file's text. Each time you invoke Dired, a buffer is created to hold the -directory listing. If you send a message with @kbd{C-x m}, a buffer named -@samp{*mail*} is used to hold the text of the message. When you ask for a -command's documentation, that appears in a buffer called @samp{*Help*}. - -@cindex selected buffer -@cindex current buffer - At any time, one and only one buffer is @dfn{current}. It is also -called the @dfn{selected buffer}. Often we say that a command operates on -``the buffer'' as if there were only one; but really this means that the -command operates on the current buffer (most commands do). - - When Emacs has multiple windows, each window has its own chosen -buffer and displays it; at any time, only one of the windows is -selected, and its chosen buffer is the current buffer. Each window's -mode line normally displays the name of the window's chosen buffer -(@pxref{Windows}). - - Each buffer has a name, which can be of any length, and you can select -any buffer by giving its name. Most buffers are made by visiting files, -and their names are derived from the files' names. But you can also create -an empty buffer with any name you want. A newly started Emacs has a buffer -named @samp{*scratch*} which can be used for evaluating Lisp expressions in -Emacs. The distinction between upper and lower case matters in buffer -names. - - Each buffer records individually what file it is visiting, whether it is -modified, and what major mode and minor modes are in effect in it -(@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a -particular buffer, meaning its value in that buffer can be different from -the value in other buffers. @xref{Locals}. - -@cindex buffer size, maximum - A buffer's size cannot be larger than some maximum, which is defined -by the largest buffer position representable by the @dfn{Emacs integer} -data type. This is because Emacs tracks buffer positions using that -data type. For 32-bit machines, the largest buffer size is 256 -megabytes. - -@menu -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onlyness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. -@end menu - -@node Select Buffer -@section Creating and Selecting Buffers -@cindex change buffers -@cindex switch buffers - -@table @kbd -@item C-x b @var{buffer} @key{RET} -Select or create a buffer named @var{buffer} (@code{switch-to-buffer}). -@item C-x 4 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in another window -(@code{switch-to-buffer-other-window}). -@item C-x 5 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in a separate frame -(@code{switch-to-buffer-other-frame}). -@item C-x @key{LEFT} -Select the previous buffer in the list of existing buffers. -@item C-x @key{RIGHT} -Select the next buffer in the list of existing buffers. -@item C-u M-g M-g -@itemx C-u M-g g -Read a number @var{n} and move to line @var{n} in the most recently -selected buffer other than the current buffer. -@end table - -@kindex C-x b -@findex switch-to-buffer - To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname} -@key{RET}}. This runs the command @code{switch-to-buffer} with argument -@var{bufname}. You can use completion to enter the buffer -name (@pxref{Completion}). An empty argument to @kbd{C-x b} -specifies the buffer that was current most recently among those not -now displayed in any window. - -@kindex C-x @key{LEFT} -@kindex C-x @key{RIGHT} -@findex next-buffer -@findex previous-buffer - For conveniently switching between a few buffers, use the commands -@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{RIGHT}} -(@code{previous-buffer}) selects the previous buffer (following the order -of most recent selection in the current frame), while @kbd{C-x @key{LEFT}} -(@code{next-buffer}) moves through buffers in the reverse direction. - -@kindex C-x 4 b -@findex switch-to-buffer-other-window -@vindex even-window-heights - To select a buffer in a window other than the current one, type -@kbd{C-x 4 b @var{bufname} @key{RET}}. This runs the command -@code{switch-to-buffer-other-window} which displays the buffer -@var{bufname} in another window. By default, if displaying the buffer -causes two vertically adjacent windows to be displayed, the heights of -those windows are evened out; to countermand that and preserve the -window configuration, set the variable @code{even-window-heights} to -@code{nil}. - -@kindex C-x 5 b -@findex switch-to-buffer-other-frame - Similarly, @kbd{C-x 5 b @var{buffer} @key{RET}} runs the command -@code{switch-to-buffer-other-frame} which selects a buffer in another -frame. - -@vindex display-buffer-reuse-frames - You can control how certain buffers are handled by these commands by -customizing the variables @code{special-display-buffer-names}, -@code{special-display-regexps}, @code{same-window-buffer-names}, and -@code{same-window-regexps}. See @ref{Force Same Window}, and -@ref{Special Buffer Frames}, for more about these variables. In -addition, if the value of @code{display-buffer-reuse-frames} is -non-@code{nil}, and the buffer you want to switch to is already -displayed in some frame, Emacs will just raise that frame. - - Most buffers are created by visiting files, or by Emacs commands that -want to display some text, but you can also create a buffer explicitly -by typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty -buffer that is not visiting any file, and selects it for editing. Such -buffers are used for making notes to yourself. If you try to save one, -you are asked for the file name to use. The new buffer's major mode is -determined by the value of @code{default-major-mode} (@pxref{Major -Modes}). - - Note that @kbd{C-x C-f}, and any other command for visiting a file, -can also be used to switch to an existing file-visiting buffer. -@xref{Visiting}. - - @kbd{C-u M-g M-g}, that is @code{goto-line} with a prefix argument -of just @kbd{C-u}, reads a number @var{n} using the minibuffer, -selects the most recently selected buffer other than the current -buffer in another window, and then moves point to the beginning of -line number @var{n} in that buffer. This is mainly useful in a buffer -that refers to line numbers in another buffer: if point is on or just -after a number, @code{goto-line} uses that number as the default for -@var{n}. Note that prefix arguments other than just @kbd{C-u} behave -differently. @kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current} -buffer, without reading a number from the minibuffer. (Remember that -@kbd{M-g M-g} without prefix argument reads a number @var{n} and then -moves to line number @var{n} in the current buffer.) - - Emacs uses buffer names that start with a space for internal purposes. -It treats these buffers specially in minor ways---for example, by -default they do not record undo information. It is best to avoid using -such buffer names yourself. - -@node List Buffers -@section Listing Existing Buffers - -@table @kbd -@item C-x C-b -List the existing buffers (@code{list-buffers}). -@end table - -@cindex listing current buffers -@kindex C-x C-b -@findex list-buffers - To display a list of existing buffers, type @kbd{C-x C-b}. Each -line in the list shows one buffer's name, major mode and visited file. -The buffers are listed in the order that they were current; the -buffers that were current most recently come first. - - @samp{*} in the first field of a line indicates the buffer is -``modified.'' If several buffers are modified, it may be time to save -some with @kbd{C-x s} (@pxref{Save Commands}). @samp{%} indicates a -read-only buffer. @samp{.} marks the current buffer. Here is an -example of a buffer list:@refill - -@smallexample -CRM Buffer Size Mode File -. * .emacs 3294 Emacs-Lisp ~/.emacs - % *Help* 101 Help - search.c 86055 C ~/cvs/emacs/src/search.c - % src 20959 Dired by name ~/cvs/emacs/src/ - * *mail* 42 Mail - % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO - % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS - *scratch* 191 Lisp Interaction - * *Messages* 1554 Fundamental -@end smallexample - -@noindent -Note that the buffer @samp{*Help*} was made by a help request; it is -not visiting any file. The buffer @code{src} was made by Dired on the -directory @file{~/cvs/emacs/src/}. You can list only buffers that are -visiting files by giving the command a prefix argument, as in -@kbd{C-u C-x C-b}. - - @code{list-buffers} omits buffers whose names begin with a space, -unless they visit files: such buffers are used internally by Emacs. - -@need 2000 -@node Misc Buffer -@section Miscellaneous Buffer Operations - -@table @kbd -@item C-x C-q -Toggle read-only status of buffer (@code{toggle-read-only}). -@item M-x rename-buffer @key{RET} @var{name} @key{RET} -Change the name of the current buffer. -@item M-x rename-uniquely -Rename the current buffer by adding @samp{<@var{number}>} to the end. -@item M-x view-buffer @key{RET} @var{buffer} @key{RET} -Scroll through buffer @var{buffer}. -@end table - -@kindex C-x C-q -@vindex buffer-read-only -@cindex read-only buffer - A buffer can be @dfn{read-only}, which means that commands to change -its contents are not allowed. The mode line indicates read-only -buffers with @samp{%%} or @samp{%*} near the left margin. Read-only -buffers are usually made by subsystems such as Dired and Rmail that -have special commands to operate on the text; also by visiting a file -whose access control says you cannot write it. - -@findex toggle-read-only - If you wish to make changes in a read-only buffer, use the command -@kbd{C-x C-q} (@code{toggle-read-only}). It makes a read-only buffer -writable, and makes a writable buffer read-only. This -works by setting the variable @code{buffer-read-only}, which has a local -value in each buffer and makes the buffer read-only if its value is -non-@code{nil}. If you have files under version control, you may find -it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only} -instead. Then, typing @kbd{C-x C-q} not only changes the read-only -flag, but it also checks the file in or out. @xref{Version -Control}. - -@findex rename-buffer - @kbd{M-x rename-buffer} changes the name of the current buffer. You -specify the new name as a minibuffer argument; there is no default. -If you specify a name that is in use for some other buffer, an error -happens and no renaming is done. - -@findex rename-uniquely - @kbd{M-x rename-uniquely} renames the current buffer to a similar -name with a numeric suffix added to make it both different and unique. -This command does not need an argument. It is useful for creating -multiple shell buffers: if you rename the @samp{*shell*} buffer, then -do @kbd{M-x shell} again, it makes a new shell buffer named -@samp{*shell*}; meanwhile, the old shell buffer continues to exist -under its new name. This method is also good for mail buffers, -compilation buffers, and most Emacs features that create special -buffers with particular names. (With some of these features, such as -@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to -switch to some other buffer before using the command, in order for it -to make a different buffer.) - -@findex view-buffer - @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc -File Ops}) except that it examines an already existing Emacs buffer. -View mode provides commands for scrolling through the buffer -conveniently but not for changing it. When you exit View mode with -@kbd{q}, that switches back to the buffer (and the position) which was -previously displayed in the window. Alternatively, if you exit View -mode with @kbd{e}, the buffer and the value of point that resulted from -your perusal remain in effect. - - The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer} -can be used to copy text from one buffer to another. @xref{Accumulating -Text}. - -@node Kill Buffer -@section Killing Buffers - -@cindex killing buffers - If you continue an Emacs session for a while, you may accumulate a -large number of buffers. You may then find it convenient to @dfn{kill} -the buffers you no longer need. On most operating systems, killing a -buffer releases its space back to the operating system so that other -programs can use it. Here are some commands for killing buffers: - -@table @kbd -@item C-x k @var{bufname} @key{RET} -Kill buffer @var{bufname} (@code{kill-buffer}). -@item M-x kill-some-buffers -Offer to kill each buffer, one by one. -@end table - -@findex kill-buffer -@findex kill-some-buffers -@kindex C-x k - - @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you -specify in the minibuffer. The default, used if you type just -@key{RET} in the minibuffer, is to kill the current buffer. If you -kill the current buffer, another buffer becomes current: one that was -current in the recent past but is not displayed in any window now. If -you ask to kill a file-visiting buffer that is modified (has unsaved -editing), then you must confirm with @kbd{yes} before the buffer is -killed. - - The command @kbd{M-x kill-some-buffers} asks about each buffer, one by -one. An answer of @kbd{y} means to kill the buffer. Killing the current -buffer or a buffer containing unsaved changes selects a new buffer or asks -for confirmation just like @code{kill-buffer}. - - The buffer menu feature (@pxref{Several Buffers}) is also convenient -for killing various buffers. - -@vindex kill-buffer-hook - If you want to do something special every time a buffer is killed, you -can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}). - -@findex clean-buffer-list - If you run one Emacs session for a period of days, as many people do, -it can fill up with buffers that you used several days ago. The command -@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills -all the unmodified buffers that you have not used for a long time. An -ordinary buffer is killed if it has not been displayed for three days; -however, you can specify certain buffers that should never be killed -automatically, and others that should be killed if they have been unused -for a mere hour. - -@cindex Midnight mode -@vindex midnight-mode -@vindex midnight-hook - You can also have this buffer purging done for you, every day at -midnight, by enabling Midnight mode. Midnight mode operates each day at -midnight; at that time, it runs @code{clean-buffer-list}, or whichever -functions you have placed in the normal hook @code{midnight-hook} -(@pxref{Hooks}). - - To enable Midnight mode, use the Customization buffer to set the -variable @code{midnight-mode} to @code{t}. @xref{Easy Customization}. - -@node Several Buffers -@section Operating on Several Buffers -@cindex buffer menu - - The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows -you to request operations on various Emacs buffers by editing an Emacs -buffer containing a list of them. You can save buffers, kill them -(here called @dfn{deleting} them, for consistency with Dired), or display -them. - -@table @kbd -@item M-x buffer-menu -Begin editing a buffer listing all Emacs buffers. -@item M-x buffer-menu-other-window. -Similar, but do it in another window. -@end table - -@findex buffer-menu -@findex buffer-menu-other-window - The command @code{buffer-menu} writes a list of all Emacs -buffers@footnote{Buffers which don't visit files and whose names begin -with a space are omitted: these are used internally by Emacs.} into the -buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu -mode. - - The buffer is read-only, and can be -changed only through the special commands described in this section. -The usual Emacs cursor motion commands can be used in the @samp{*Buffer -List*} buffer. The following commands apply to the buffer described on -the current line. - -@table @kbd -@item d -Request to delete (kill) the buffer, then move down. The request -shows as a @samp{D} on the line, before the buffer name. Requested -deletions take place when you type the @kbd{x} command. -@item C-d -Like @kbd{d} but move up afterwards instead of down. -@item s -Request to save the buffer. The request shows as an @samp{S} on the -line. Requested saves take place when you type the @kbd{x} command. -You may request both saving and deletion for the same buffer. -@item x -Perform previously requested deletions and saves. -@item u -Remove any request made for the current line, and move down. -@item @key{DEL} -Move to previous line and remove any request made for that line. -@end table - - The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove -flags also move down (or up) one line. They accept a numeric argument -as a repeat count. - - These commands operate immediately on the buffer listed on the current -line: - -@table @kbd -@item ~ -Mark the buffer ``unmodified.'' The command @kbd{~} does this -immediately when you type it. -@item % -Toggle the buffer's read-only flag. The command @kbd{%} does -this immediately when you type it. -@item t -Visit the buffer as a tags table. @xref{Select Tags Table}. -@end table - - There are also commands to select another buffer or buffers: - -@table @kbd -@item q -Quit the buffer menu---immediately display the most recent formerly -visible buffer in its place. -@item @key{RET} -@itemx f -Immediately select this line's buffer in place of the @samp{*Buffer -List*} buffer. -@item o -Immediately select this line's buffer in another window as if by -@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible. -@item C-o -Immediately display this line's buffer in another window, but don't -select the window. -@item 1 -Immediately select this line's buffer in a full-screen window. -@item 2 -Immediately set up two windows, with this line's buffer selected in -one, and the previously current buffer (aside from the buffer -@samp{*Buffer List*}) displayed in the other. -@item b -Bury the buffer listed on this line. -@item m -Mark this line's buffer to be displayed in another window if you exit -with the @kbd{v} command. The request shows as a @samp{>} at the -beginning of the line. (A single buffer may not have both a delete -request and a display request.) -@item v -Immediately select this line's buffer, and also display in other windows -any buffers previously marked with the @kbd{m} command. If you have not -marked any buffers, this command is equivalent to @kbd{1}. -@end table - - There is also a command that affects the entire buffer list: - -@table @kbd -@item T -Delete, or reinsert, lines for non-file buffers. This command toggles -the inclusion of such buffers in the buffer list. -@end table - - What @code{buffer-menu} actually does is create and switch to a -suitable buffer, and turn on Buffer Menu mode in it. Everything else -described above is implemented by the special commands provided in -Buffer Menu mode. One consequence of this is that you can switch from -the @samp{*Buffer List*} buffer to another Emacs buffer, and edit -there. You can reselect the @samp{*Buffer List*} buffer later, to -perform the operations already requested, or you can kill it, or pay -no further attention to it. - - The list in the @samp{*Buffer List*} buffer looks exactly like the -buffer list described in @ref{List Buffers}, because they really are -the same. The only difference between @code{buffer-menu} and -@code{list-buffers} is that @code{buffer-menu} switches to the -@samp{*Buffer List*} buffer in the selected window; -@code{list-buffers} displays the same buffer in another window. If -you run @code{list-buffers} (that is, type @kbd{C-x C-b}) and select -the buffer list manually, you can use all of the commands described -here. - - Normally, the buffer @samp{*Buffer List*} is not updated -automatically when buffers are created and killed; its contents are -just text. If you have created, deleted or renamed buffers, the way -to update @samp{*Buffer List*} to show what you have done is to type -@kbd{g} (@code{revert-buffer}). You can make this happen regularly -every @code{auto-revert-interval} seconds if you enable Auto Revert -mode in this buffer, as long as it is not marked modified. Global -Auto Revert mode applies to the @samp{*Buffer List*} buffer only if -@code{global-auto-revert-non-file-buffers} is non-@code{nil}. -@iftex -@inforef{Autorevert,, emacs-xtra}, for details. -@end iftex -@ifnottex -@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. -@end ifnottex - - - The command @code{buffer-menu-other-window} works the same as -@code{buffer-menu}, except that it displays the buffers list in -another window. - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffer -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the analogue, for buffers, of a symbolic link between files. - -@table @kbd -@findex make-indirect-buffer -@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET} -Create an indirect buffer named @var{indirect-name} whose base buffer -is @var{base-buffer}. -@findex clone-indirect-buffer -@item M-x clone-indirect-buffer @key{RET} -Create an indirect buffer that is a twin copy of the current buffer. -@item C-x 4 c -@kindex C-x 4 c -@findex clone-indirect-buffer-other-window -Create an indirect buffer that is a twin copy of the current buffer, and -select it in another window (@code{clone-indirect-buffer-other-window}). -@end table - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. But in all other respects, the indirect buffer and its -base buffer are completely separate. They have different names, -different values of point, different narrowing, different markers, -different major modes, and different local variables. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. Killing the base buffer effectively kills the indirect -buffer, but killing an indirect buffer has no effect on its base buffer. - - One way to use indirect buffers is to display multiple views of an -outline. @xref{Outline Views}. - - A quick and handy way to make an indirect buffer is with the command -@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect -buffer whose base buffer is the current buffer. With a numeric -argument, it prompts for the name of the indirect buffer; otherwise it -uses the name of the current buffer, with a @samp{<@var{n}>} suffix -added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) -works like @kbd{M-x clone-indirect-buffer}, but it selects the new -buffer in another window. - - The more general way to make an indirect buffer is with the command -@kbd{M-x make-indirect-buffer}. It creates an indirect buffer from -buffer @var{base-buffer}, under the name @var{indirect-name}. It -prompts for both @var{base-buffer} and @var{indirect-name} using the -minibuffer. - -@node Buffer Convenience -@section Convenience Features and Customization of Buffer Handling - - This section describes several modes and features that make it more -convenient to switch between buffers. - -@menu -* Uniquify:: Making buffer names unique with directory parts. -* Iswitchb:: Switching between buffers with substrings. -* Buffer Menus:: Configurable buffer menu. -@end menu - -@node Uniquify -@subsection Making Buffer Names Unique - -@cindex unique buffer names -@cindex directories in buffer names - When several buffers visit identically-named files, Emacs must give -the buffers distinct names. The usual method for making buffer names -unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer -names (all but one of them). - -@vindex uniquify-buffer-name-style - Other methods work by adding parts of each file's directory to the -buffer name. To select one, customize the variable -@code{uniquify-buffer-name-style} (@pxref{Easy Customization}). - - To begin with, the @code{forward} naming method includes part of the -file's directory name at the beginning of the buffer name; using this -method, buffers visiting the files @file{/u/rms/tmp/Makefile} and -@file{/usr/projects/zaphod/Makefile} would be named -@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead -of @samp{Makefile} and @samp{Makefile<2>}). - - In contrast, the @code{post-forward} naming method would call the -buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the -@code{reverse} naming method would call them @samp{Makefile\tmp} and -@samp{Makefile\zaphod}. The nontrivial difference between -@code{post-forward} and @code{reverse} occurs when just one directory -name is not enough to distinguish two files; then @code{reverse} puts -the directory names in reverse order, so that @file{/top/middle/file} -becomes @samp{file\middle\top}, while @code{post-forward} puts them in -forward order after the file name, as in @samp{file|top/middle}. - - Which rule to follow for putting the directory names in the buffer -name is not very important if you are going to @emph{look} at the -buffer names before you type one. But as an experienced user, if you -know the rule, you won't have to look. And then you may find that one -rule or another is easier for you to remember and apply quickly. - -@node Iswitchb -@subsection Switching Between Buffers using Substrings - -@findex iswitchb-mode -@cindex Iswitchb mode -@cindex mode, Iswitchb -@kindex C-x b @r{(Iswitchb mode)} -@kindex C-x 4 b @r{(Iswitchb mode)} -@kindex C-x 5 b @r{(Iswitchb mode)} -@kindex C-x 4 C-o @r{(Iswitchb mode)} - - Iswitchb global minor mode provides convenient switching between -buffers using substrings of their names. It replaces the normal -definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x -4 C-o} with alternative commands that are somewhat ``smarter.'' - - When one of these commands prompts you for a buffer name, you can -type in just a substring of the name you want to choose. As you enter -the substring, Iswitchb mode continuously displays a list of buffers -that match the substring you have typed. - - At any time, you can type @key{RET} to select the first buffer in -the list. So the way to select a particular buffer is to make it the -first in the list. There are two ways to do this. You can type more -of the buffer name and thus narrow down the list, excluding unwanted -buffers above the desired one. Alternatively, you can use @kbd{C-s} -and @kbd{C-r} to rotate the list until the desired buffer is first. - - @key{TAB} while entering the buffer name performs completion on the -string you have entered, based on the displayed list of buffers. - - To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize -the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy -Customization}). - -@node Buffer Menus -@subsection Customizing Buffer Menus - -@findex bs-show -@cindex buffer list, customizable -@table @kbd -@item M-x bs-show -Make a list of buffers similarly to @kbd{M-x list-buffers} but -customizable. -@end table - - @kbd{M-x bs-show} pops up a buffer list similar to the one normally -displayed by @kbd{C-x C-b} but which you can customize. If you prefer -this to the usual buffer list, you can bind this command to @kbd{C-x -C-b}. To customize this buffer list, use the @code{bs} Custom group -(@pxref{Easy Customization}). - -@findex msb-mode -@cindex mode, MSB -@cindex MSB mode -@cindex buffer menu -@findex mouse-buffer-menu -@kindex C-Down-Mouse-1 - MSB global minor mode (``MSB'' stands for ``mouse select buffer'') -provides a different and customizable mouse buffer menu which you may -prefer. It replaces the bindings of @code{mouse-buffer-menu}, -normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You -can customize the menu in the @code{msb} Custom group. - -@ignore - arch-tag: 08c43460-f4f4-4b43-9cb5-1ea9ad991695 -@end ignore diff --git a/man/building.texi b/man/building.texi deleted file mode 100644 index 62e5f7b4316..00000000000 --- a/man/building.texi +++ /dev/null @@ -1,1440 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Building, Maintaining, Programs, Top -@chapter Compiling and Testing Programs -@cindex building programs -@cindex program building -@cindex running Lisp functions - - The previous chapter discusses the Emacs commands that are useful for -making changes in programs. This chapter deals with commands that assist -in the larger process of compiling and testing programs. - -@menu -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. -* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. -* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. -@end menu - -@node Compilation -@section Running Compilations under Emacs -@cindex inferior process -@cindex make -@cindex compilation errors -@cindex error log - - Emacs can run compilers for noninteractive languages such as C and -Fortran as inferior processes, feeding the error log into an Emacs buffer. -It can also parse the error messages and show you the source lines where -compilation errors occurred. - -@table @kbd -@item M-x compile -Run a compiler asynchronously under Emacs, with error messages going to -the @samp{*compilation*} buffer. -@item M-x recompile -Invoke a compiler with the same command as in the last invocation of -@kbd{M-x compile}. -@item M-x kill-compilation -Kill the running compilation subprocess. -@end table - -@findex compile - To run @code{make} or another compilation command, do @kbd{M-x -compile}. This command reads a shell command line using the minibuffer, -and then executes the command in an inferior shell, putting output in -the buffer named @samp{*compilation*}. The current buffer's default -directory is used as the working directory for the execution of the -command; normally, therefore, the compilation happens in this -directory. - -@vindex compile-command - The default for the compilation command is normally @samp{make -k}, -which is correct most of the time for nontrivial programs. -(@xref{Top,, Make, make, GNU Make Manual}.) If you have done @kbd{M-x -compile} before, the default each time is the command you used the -previous time. @code{compile} stores this command in the variable -@code{compile-command}, so setting that variable specifies the default -for the next use of @kbd{M-x compile}. If a file specifies a file -local value for @code{compile-command}, that provides the default when -you type @kbd{M-x compile} in that file's buffer. @xref{File -Variables}. - - Starting a compilation displays the buffer @samp{*compilation*} in -another window but does not select it. The buffer's mode line tells -you whether compilation is finished, with the word @samp{run}, -@samp{signal} or @samp{exit} inside the parentheses. You do not have -to keep this buffer visible; compilation continues in any case. While -a compilation is going on, the string @samp{Compiling} appears in the -mode lines of all windows. When this string disappears, the -compilation is finished. - - If you want to watch the compilation transcript as it appears, switch -to the @samp{*compilation*} buffer and move point to the end of the -buffer. When point is at the end, new compilation output is inserted -above point, which remains at the end. If point is not at the end of -the buffer, it remains fixed while more compilation output is added at -the end of the buffer. - -@cindex compilation buffer, keeping point at end -@vindex compilation-scroll-output - If you set the variable @code{compilation-scroll-output} to a -non-@code{nil} value, then the compilation buffer always scrolls to -follow output as it comes in. - -@findex recompile - To rerun the last compilation with the same command, type @kbd{M-x -recompile}. This automatically reuses the compilation command from -the last invocation of @kbd{M-x compile}. It also reuses the -@samp{*compilation*} buffer and starts the compilation in its default -directory, which is the directory in which the previous compilation -was started. - - When the compiler process terminates, for whatever reason, the mode -line of the @samp{*compilation*} buffer changes to say @samp{exit} -(followed by the exit code, @samp{[0]} for a normal exit), or -@samp{signal} (if a signal terminated the process), instead of -@samp{run}. - -@findex kill-compilation - Starting a new compilation also kills any compilation already -running in @samp{*compilation*}, as the buffer can only handle one -compilation at any time. However, @kbd{M-x compile} asks for -confirmation before actually killing a compilation that is running. -You can also kill the compilation process with @kbd{M-x -kill-compilation}. - - If you want to run two compilations at once, you should start the -first one, then rename the @samp{*compilation*} buffer (perhaps using -@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other -compilation. That will create a new @samp{*compilation*} buffer. - - Emacs does not expect a compiler process to launch asynchronous -subprocesses; if it does, and they keep running after the main -compiler process has terminated, Emacs may kill them or their output -may not arrive in Emacs. To avoid this problem, make the main process -wait for its subprocesses to finish. In a shell script, you can do this -using @samp{$!} and @samp{wait}, like this: - -@example -(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} -echo first message -wait $pid # @r{Wait for subprocess} -@end example - - If the background process does not output to the compilation buffer, -so you only need to prevent it from being killed when the main -compilation process terminates, this is sufficient: - -@example -nohup @var{command}; sleep 1 -@end example - -@vindex compilation-environment - You can control the environment passed to the compilation command -with the variable @code{compilation-environment}. Its value is a list -of environment variable settings; each element should be a string of -the form @code{"@var{envvarname}=@var{value}"}. These environment -variable settings override the usual ones. - -@node Compilation Mode -@section Compilation Mode - -@cindex Compilation mode -@cindex mode, Compilation - The @samp{*compilation*} buffer uses a special major mode, -Compilation mode, whose main feature is to provide a convenient way to -visit the source line corresponding to an error message. These -commands are also available in other special buffers that list -locations in files, including those made by @kbd{M-x grep} and -@kbd{M-x occur}. - -@table @kbd -@item M-g M-n -@itemx M-g n -@itemx C-x ` -Visit the locus of the next error message or match. -@item M-g M-p -@itemx M-g p -Visit the locus of the previous error message or match. -@item @key{RET} -Visit the locus of the error message that point is on. -This command is used in the compilation buffer. -@item Mouse-2 -Visit the locus of the error message that you click on. -@item M-n -Find and highlight the locus of the next error message, without -selecting the source buffer. -@item M-p -Find and highlight the locus of the previous error message, without -selecting the source buffer. -@item M-@} -Move point to the next error for a different file than the current -one. -@item M-@{ -Move point to the previous error for a different file than the current -one. -@item C-c C-f -Toggle Next Error Follow minor mode, which makes cursor motion in the -compilation buffer produce automatic source display. -@end table - -@findex compile-goto-error - You can visit the source for any particular error message by moving -point in the @samp{*compilation*} buffer to that error message and -typing @key{RET} (@code{compile-goto-error}). Alternatively, you can -click @kbd{Mouse-2} on the error message; you need not switch to the -@samp{*compilation*} buffer first. - -@kindex M-g M-n -@kindex M-g n -@kindex C-x ` -@findex next-error -@vindex next-error-highlight - To parse the compiler error messages sequentially, type @kbd{C-x `} -(@code{next-error}). The character following the @kbd{C-x} is the -backquote or ``grave accent,'' not the single-quote. This command is -available in all buffers, not just in @samp{*compilation*}; it -displays the next error message at the top of one window and source -location of the error in another window. It also temporarily -highlights the relevant source line, for a period controlled by the -variable @code{next-error-highlight}. - - The first time @w{@kbd{C-x `}} is used after the start of a compilation, -it moves to the first error's location. Subsequent uses of @kbd{C-x -`} advance down to subsequent errors. If you visit a specific error -message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}} -commands advance from there. When @w{@kbd{C-x `}} gets to the end of the -buffer and finds no more error messages to visit, it fails and signals -an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of -the compilation buffer, and goes to the first error's location. - -@vindex compilation-skip-threshold - By default, @w{@kbd{C-x `}} skips less important messages. The variable -@code{compilation-skip-threshold} controls this. If its value is 2, -@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less -than warning, and 0 doesn't skip any messages. The default is 1. - - When the window has a left fringe, an arrow in the fringe points to -the current message in the compilation buffer. The variable -@code{compilation-context-lines} controls the number of lines of -leading context to display before the current message. Going to an -error message location scrolls the @samp{*compilation*} buffer to put -the message that far down from the top. The value @code{nil} is -special: if there's a left fringe, the window doesn't scroll at all -if the message is already visible. If there is no left fringe, -@code{nil} means display the message at the top of the window. - - If you're not in the compilation buffer when you run -@code{next-error}, Emacs will look for a buffer that contains error -messages. First, it looks for one displayed in the selected frame, -then for one that previously had @code{next-error} called on it, and -then at the current buffer. Finally, Emacs looks at all the remaining -buffers. @code{next-error} signals an error if it can't find any such -buffer. - -@vindex compilation-error-regexp-alist -@vindex grep-regexp-alist - To parse messages from the compiler, Compilation mode uses the -variable @code{compilation-error-regexp-alist} which lists various -formats of error messages and tells Emacs how to extract the source file -and the line number from the text of a message. If your compiler isn't -supported, you can tailor Compilation mode to it by adding elements to -that list. A similar variable @code{grep-regexp-alist} tells Emacs how -to parse output of a @code{grep} command. - -@findex compilation-next-error -@findex compilation-previous-error -@findex compilation-next-file -@findex compilation-previous-file - Compilation mode also redefines the keys @key{SPC} and @key{DEL} to -scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error}) -and @kbd{M-p} (@code{compilation-previous-error}) to move to the next -or previous error message. You can also use @kbd{M-@{} -(@code{compilation-next-file} and @kbd{M-@}} -(@code{compilation-previous-file}) to move up or down to an error -message for a different source file. - -@cindex Next Error Follow mode -@findex next-error-follow-minor-mode - You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In -this minor mode, ordinary cursor motion in the compilation buffer -automatically updates the source buffer. For instance, moving the -cursor to the next error message causes the location of that error to -be displayed immediately. - - The features of Compilation mode are also available in a minor mode -called Compilation Minor mode. This lets you parse error messages in -any buffer, not just a normal compilation output buffer. Type @kbd{M-x -compilation-minor-mode} to enable the minor mode. This defines the keys -@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode. - - Compilation minor mode works in any buffer, as long as the contents -are in a format that it understands. In an Rlogin buffer (@pxref{Remote -Host}), Compilation minor mode automatically accesses remote source -files by FTP (@pxref{File Names}). - -@node Compilation Shell -@section Subshells for Compilation - - Emacs uses a shell to run the compilation command, but specifies the -option for a noninteractive shell. This means, in particular, that -the shell should start with no prompt. If you find your usual shell -prompt making an unsightly appearance in the @samp{*compilation*} -buffer, it means you have made a mistake in your shell's init file by -setting the prompt unconditionally. (This init file's name may be -@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or -various other things, depending on the shell you use.) The shell init -file should set the prompt only if there already is a prompt. Here's -how to do it in bash: - -@example -if [ "$@{PS1+set@}" = set ] -then PS1=@dots{} -fi -@end example - -@noindent -And here's how to do it in csh: - -@example -if ($?prompt) set prompt = @dots{} -@end example - - There may well be other things that your shell's init file -ought to do only for an interactive shell. You can use the same -method to conditionalize them. - - The MS-DOS ``operating system'' does not support asynchronous -subprocesses; to work around this lack, @kbd{M-x compile} runs the -compilation command synchronously on MS-DOS. As a consequence, you must -wait until the command finishes before you can do anything else in -Emacs. -@iftex -@inforef{MS-DOS,,emacs-xtra}. -@end iftex -@ifnottex -@xref{MS-DOS}. -@end ifnottex - -@node Grep Searching -@section Searching with Grep under Emacs - - Just as you can run a compiler from Emacs and then visit the lines -with compilation errors, you can also run @code{grep} and then visit -the lines on which matches were found. This works by treating the -matches reported by @code{grep} as if they were ``errors.'' The -buffer of matches uses Grep mode, which is a variant of Compilation -mode (@pxref{Compilation Mode}). - -@table @kbd -@item M-x grep -@item M-x lgrep -Run @code{grep} asynchronously under Emacs, with matching lines -listed in the buffer named @samp{*grep*}. -@item M-x grep-find -@itemx M-x find-grep -@itemx M-x rgrep -Run @code{grep} via @code{find}, with user-specified arguments, and -collect output in the buffer named @samp{*grep*}. -@item M-x kill-grep -Kill the running @code{grep} subprocess. -@end table - -@findex grep - To run @code{grep}, type @kbd{M-x grep}, then enter a command line -that specifies how to run @code{grep}. Use the same arguments you -would give @code{grep} when running it normally: a @code{grep}-style -regexp (usually in single-quotes to quote the shell's special -characters) followed by file names, which may use wildcards. If you -specify a prefix argument for @kbd{M-x grep}, it finds the tag -(@pxref{Tags}) in the buffer around point, and puts that into the -default @code{grep} command. - - Your command need not simply run @code{grep}; you can use any shell -command that produces output in the same format. For instance, you -can chain @code{grep} commands, like this: - -@example -grep -nH -e foo *.el | grep bar | grep toto -@end example - - The output from @code{grep} goes in the @samp{*grep*} buffer. You -can find the corresponding lines in the original files using @w{@kbd{C-x -`}}, @key{RET}, and so forth, just like compilation errors. - - Some grep programs accept a @samp{--color} option to output special -markers around matches for the purpose of highlighting. You can make -use of this feature by setting @code{grep-highlight-matches} to -@code{t}. When displaying a match in the source buffer, the exact -match will be highlighted, instead of the entire source line. - -@findex grep-find -@findex find-grep - The command @kbd{M-x grep-find} (also available as @kbd{M-x -find-grep}) is similar to @kbd{M-x grep}, but it supplies a different -initial default for the command---one that runs both @code{find} and -@code{grep}, so as to search every file in a directory tree. See also -the @code{find-grep-dired} command, in @ref{Dired and Find}. - -@findex lgrep -@findex rgrep - The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} -(recursive grep) are more user-friendly versions of @code{grep} and -@code{grep-find}, which prompt separately for the regular expression -to match, the files to search, and the base directory for the search. -Case sensitivity of the search is controlled by the -current value of @code{case-fold-search}. - -These commands build the shell commands based on the variables -@code{grep-template} (for @code{lgrep}) and @code{grep-find-template} -(for @code{rgrep}). - -The files to search can use aliases defined in the variable -@code{grep-files-aliases}. - -Subdirectories listed in the variable -@code{grep-find-ignored-directories} such as those typically used by -various version control systems, like CVS and arch, are automatically -skipped by @code{rgrep}. - -@node Flymake -@section Finding Syntax Errors On The Fly -@cindex checking syntax - - Flymake mode is a minor mode that performs on-the-fly syntax -checking for many programming and markup languages, including C, C++, -Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell -mode, which performs spell checking for ordinary human languages in a -similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode -runs an appropriate syntax checking tool in the background, using a -temporary copy of the buffer. It then parses the error and warning -messages, and highlights the erroneous lines in the buffer. The -syntax checking tool used depends on the language; for example, for -C/C++ files this is usually the C compiler. Flymake can also use -build tools such as @code{make} for checking complicated projects. - - To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move -to the errors spotted by Flymake mode with @kbd{M-x -flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To -display any error messages associated with the current line, use -@kbd{M-x flymake-display-err-menu-for-current-line}. - - For more details about using Flymake, see @ref{Top, Flymake, -Flymake, flymake, The Flymake Manual}. - -@node Debuggers -@section Running Debuggers Under Emacs -@cindex debuggers -@cindex GUD library -@cindex GDB -@cindex DBX -@cindex SDB -@cindex XDB -@cindex Perldb -@cindex JDB -@cindex PDB - -@c Do you believe in GUD? -The GUD (Grand Unified Debugger) library provides an interface to -various symbolic debuggers from within Emacs. We recommend the -debugger GDB, which is free software, but GUD can also run DBX, SDB or -XDB. GUD can also serve as an interface to Perl's debugging mode, the -Python debugger PDB, and to JDB, the Java Debugger. -@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference -Manual}, for information on debugging Emacs Lisp programs. - -@menu -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment through - Emacs. -@end menu - -@node Starting GUD -@subsection Starting GUD - - There are several commands for starting a debugger, each corresponding -to a particular debugger program. - -@table @kbd -@item M-x gdb @key{RET} @var{file} @key{RET} -@findex gdb -Run GDB as a subprocess of Emacs. By default, this uses an IDE-like -graphical interface; see @ref{GDB Graphical Interface}. Only GDB -works with the graphical interface. - -@item M-x dbx @key{RET} @var{file} @key{RET} -@findex dbx -Run DBX as a subprocess of Emacs. Since Emacs does not implement a -graphical interface for DBX, communication with DBX works by typing -commands in the GUD interaction buffer. The same is true for all -the other supported debuggers. - -@item M-x xdb @key{RET} @var{file} @key{RET} -@findex xdb -@vindex gud-xdb-directories -Similar, but run XDB. Use the variable -@code{gud-xdb-directories} to specify directories to search for source -files. - -@item M-x sdb @key{RET} @var{file} @key{RET} -@findex sdb -Similar, but run SDB. - - Some versions of SDB do not mention source file names in their -messages. When you use them, you need to have a valid tags table -(@pxref{Tags}) in order for GUD to find functions in the source code. -If you have not visited a tags table or the tags table doesn't list one -of the functions, you get a message saying @samp{The sdb support -requires a valid tags table to work}. If this happens, generate a valid -tags table in the working directory and try again. - -@item M-x perldb @key{RET} @var{file} @key{RET} -@findex perldb -Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. - -@item M-x jdb @key{RET} @var{file} @key{RET} -@findex jdb -Run the Java debugger to debug @var{file}. - -@item M-x pdb @key{RET} @var{file} @key{RET} -@findex pdb -Run the Python debugger to debug @var{file}. -@end table - - Each of these commands takes one argument: a command line to invoke -the debugger. In the simplest case, specify just the name of the -executable file you want to debug. You may also use options that the -debugger supports. However, shell wildcards and variables are not -allowed. GUD assumes that the first argument not starting with a -@samp{-} is the executable file name. - -Tramp provides a facility to debug programs on remote hosts. -@xref{Running a debugger on a remote host, Running a debugger on a remote host,, tramp, The Tramp Manual}. -@c Running a debugger on a remote host - -@node Debugger Operation -@subsection Debugger Operation - -@cindex fringes, and current execution line in GUD - Generally when you run a debugger with GUD, the debugger uses an Emacs -buffer for its ordinary input and output. This is called the GUD -buffer. Input and output from the program you are debugging also use -this buffer. We call this @dfn{text command mode}. The GDB Graphical -Interface can use further buffers (@pxref{GDB Graphical Interface}). - - The debugger displays the source files of the program by visiting -them in Emacs buffers. An arrow in the left fringe indicates the -current execution line.@footnote{On a text-only terminal, the arrow -appears as @samp{=>} and overlays the first two text columns.} Moving -point in this buffer does not move the arrow. The arrow is not part -of the file's text; it appears only on the screen. - - You can start editing these source files at any time in the buffers -that display them. If you do modify a source file, keep in mind that -inserting or deleting lines will throw off the arrow's positioning; -GUD has no way of figuring out which line corresponded before your -changes to the line number in a debugger message. Also, you'll -typically have to recompile and restart the program for your changes -to be reflected in the debugger's tables. - -@cindex tooltips with GUD -@vindex tooltip-gud-modes -@vindex gud-tooltip-mode -@vindex gud-tooltip-echo-area - The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. -You activate this feature by turning on the minor mode -@code{gud-tooltip-mode}. Then you can display a variable's value in a -tooltip simply by pointing at it with the mouse. This operates in the -GUD buffer and in source buffers with major modes in the list -@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} -is non-@code{nil} then the variable's value is displayed in the echo -area. When debugging a C program using the GDB Graphical Interface, you -can also display macro definitions associated with an identifier when -the program is not executing. - - GUD tooltips are disabled when you use GDB in text command mode -(@pxref{GDB Graphical Interface}), because displaying an expression's -value in GDB can sometimes expand a macro and result in a side effect -that interferes with the program's operation. The GDB graphical -interface supports GUD tooltips and assures they will not cause side -effects. - -@node Commands of GUD -@subsection Commands of GUD - - The GUD interaction buffer uses a variant of Shell mode, so the -Emacs commands of Shell mode are available (@pxref{Shell Mode}). All -the usual commands for your debugger are available, and you can use -the Shell mode history commands to repeat them. If you wish, you can -control your debugger process entirely through this buffer. - - GUD mode also provides commands for setting and clearing -breakpoints, for selecting stack frames, and for stepping through the -program. These commands are available both in the GUD buffer and -globally, but with different key bindings. It also has its own tool -bar from which you can invoke the more common commands by clicking on -the appropriate icon. This is particularly useful for repetitive -commands like @code{gud-next} and @code{gud-step}, and allows you to -keep the GUD buffer hidden. - - The breakpoint commands are normally used in source file buffers, -because that is the easiest way to specify where to set or clear the -breakpoint. Here's the global command to set a breakpoint: - -@table @kbd -@item C-x @key{SPC} -@kindex C-x SPC -Set a breakpoint on the source line that point is on. -@end table - -@kindex C-x C-a @r{(GUD)} - Here are the other special commands provided by GUD@. The keys -starting with @kbd{C-c} are available only in the GUD interaction -buffer. The key bindings that start with @kbd{C-x C-a} are available -in the GUD interaction buffer and also in source files. Some of these -commands are not available to all the supported debuggers. - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(GUD)} -@itemx C-x C-a C-l -@findex gud-refresh -Display in another window the last line referred to in the GUD -buffer (that is, the line indicated in the last location message). -This runs the command @code{gud-refresh}. - -@item C-c C-s -@kindex C-c C-s @r{(GUD)} -@itemx C-x C-a C-s -@findex gud-step -Execute a single line of code (@code{gud-step}). If the line contains -a function call, execution stops after entering the called function. - -@item C-c C-n -@kindex C-c C-n @r{(GUD)} -@itemx C-x C-a C-n -@findex gud-next -Execute a single line of code, stepping across entire function calls -at full speed (@code{gud-next}). - -@item C-c C-i -@kindex C-c C-i @r{(GUD)} -@itemx C-x C-a C-i -@findex gud-stepi -Execute a single machine instruction (@code{gud-stepi}). - -@item C-c C-p -@kindex C-c C-p @r{(GUD)} -@itemx C-x C-a C-p -@findex gud-print -Evaluate the expression at point (@code{gud-print}). If Emacs -does not print the exact expression that you want, mark it as a region -first. - -@need 3000 -@item C-c C-r -@kindex C-c C-r @r{(GUD)} -@itemx C-x C-a C-r -@findex gud-cont -Continue execution without specifying any stopping point. The program -will run until it hits a breakpoint, terminates, or gets a signal that -the debugger is checking for (@code{gud-cont}). - -@need 1000 -@item C-c C-d -@kindex C-c C-d @r{(GUD)} -@itemx C-x C-a C-d -@findex gud-remove -Delete the breakpoint(s) on the current source line, if any -(@code{gud-remove}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c C-t -@kindex C-c C-t @r{(GUD)} -@itemx C-x C-a C-t -@findex gud-tbreak -Set a temporary breakpoint on the current source line, if any -(@code{gud-tbreak}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c < -@kindex C-c < @r{(GUD)} -@itemx C-x C-a < -@findex gud-up -Select the next enclosing stack frame (@code{gud-up}). This is -equivalent to the GDB command @samp{up}. - -@item C-c > -@kindex C-c > @r{(GUD)} -@itemx C-x C-a > -@findex gud-down -Select the next inner stack frame (@code{gud-down}). This is -equivalent to the GDB command @samp{down}. - -@item C-c C-u -@kindex C-c C-u @r{(GUD)} -@itemx C-x C-a C-u -@findex gud-until -Continue execution to the current line (@code{gud-until}). The -program will run until it hits a breakpoint, terminates, gets a signal -that the debugger is checking for, or reaches the line on which the -cursor currently sits. - -@item C-c C-f -@kindex C-c C-f @r{(GUD)} -@itemx C-x C-a C-f -@findex gud-finish -Run the program until the selected stack frame returns or -stops for some other reason (@code{gud-finish}). -@end table - - If you are using GDB, these additional key bindings are available: - -@table @kbd -@item C-x C-a C-j -@kindex C-x C-a C-j @r{(GUD)} -@findex gud-jump -Only useful in a source buffer, @code{gud-jump} transfers the -program's execution point to the current line. In other words, the -next line that the program executes will be the one where you gave the -command. If the new execution line is in a different function from -the previously one, GDB prompts for confirmation since the results may -be bizarre. See the GDB manual entry regarding @code{jump} for -details. - -@item @key{TAB} -@kindex TAB @r{(GUD)} -@findex gud-gdb-complete-command -With GDB, complete a symbol name (@code{gud-gdb-complete-command}). -This key is available only in the GUD interaction buffer. -@end table - - These commands interpret a numeric argument as a repeat count, when -that makes sense. - - Because @key{TAB} serves as a completion command, you can't use it to -enter a tab as input to the program you are debugging with GDB. -Instead, type @kbd{C-q @key{TAB}} to enter a tab. - -@node GUD Customization -@subsection GUD Customization - -@vindex gdb-mode-hook -@vindex dbx-mode-hook -@vindex sdb-mode-hook -@vindex xdb-mode-hook -@vindex perldb-mode-hook -@vindex pdb-mode-hook -@vindex jdb-mode-hook - On startup, GUD runs one of the following hooks: @code{gdb-mode-hook}, -if you are using GDB; @code{dbx-mode-hook}, if you are using DBX; -@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you -are using XDB; @code{perldb-mode-hook}, for Perl debugging mode; -@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can -use these hooks to define custom key bindings for the debugger -interaction buffer. @xref{Hooks}. - - Here is a convenient way to define a command that sends a particular -command string to the debugger, and set up a key binding for it in the -debugger interaction buffer: - -@findex gud-def -@example -(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring}) -@end example - - This defines a command named @var{function} which sends -@var{cmdstring} to the debugger process, and gives it the documentation -string @var{docstring}. You can then use the command @var{function} in any -buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds -the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to -@kbd{C-x C-a @var{binding}} generally. - - The command string @var{cmdstring} may contain certain -@samp{%}-sequences that stand for data to be filled in at the time -@var{function} is called: - -@table @samp -@item %f -The name of the current source file. If the current buffer is the GUD -buffer, then the ``current source file'' is the file that the program -stopped in. - -@item %l -The number of the current source line. If the current buffer is the GUD -buffer, then the ``current source line'' is the line that the program -stopped in. - -@item %e -In transient-mark-mode the text in the region, if it is active. -Otherwise the text of the C lvalue or function-call expression at or -adjacent to point. - -@item %a -The text of the hexadecimal address at or adjacent to point. - -@item %p -The numeric argument of the called function, as a decimal number. If -the command is used without a numeric argument, @samp{%p} stands for the -empty string. - -If you don't use @samp{%p} in the command string, the command you define -ignores any numeric argument. - -@item %d -The name of the directory of the current source file. - -@item %c -Fully qualified class name derived from the expression surrounding point -(jdb only). -@end table - -@node GDB Graphical Interface -@subsection GDB Graphical Interface - - By default, the command @code{gdb} starts GDB using a graphical -interface, using Emacs windows for display program state information. -In effect, this makes Emacs into an IDE (interactive development -environment). With it, you do not need to use textual GDB commands; -you can control the debugging session with the mouse. For example, -you can click in the fringe of a source buffer to set a breakpoint -there, or on a stack frame in the stack buffer to select that frame. - - This mode requires telling GDB that its ``screen size'' is -unlimited, so it sets the height and width accordingly. For correct -operation you must not change these values during the GDB session. - -@vindex gud-gdb-command-name -@findex gdba - You can also run GDB in text command mode, like other debuggers. To -do this, replace the GDB @code{"--annotate=3"} option with -@code{"--fullname"} either in the minibuffer for the current Emacs -session, or the custom variable @code{gud-gdb-command-name} for all -future sessions. You need to use text command mode to debug multiple -programs within one Emacs session. If you have customized -@code{gud-gdb-command-name} in this way, you can use @kbd{M-x gdba} to -invoke GDB in graphical mode. Moreover, this command succeeds where -@kbd{M-x gdb} fails, such as when your @file{.gdbinit} file contains -executable GDB commands. - -@menu -* GDB-UI Layout:: Control the number of displayed buffers. -* Source Buffers:: Use the mouse in the fringe/margin to - control your program. -* Breakpoints Buffer:: A breakpoint control panel. -* Stack Buffer:: Select a frame from the call stack. -* Other GDB-UI Buffers:: Input/output, locals, registers, - assembler, threads and memory buffers. -* Watch Expressions:: Monitor variable values in the speedbar. -@end menu - -@node GDB-UI Layout -@subsubsection GDB User Interface Layout -@cindex GDB User Interface layout - -@vindex gdb-many-windows - If the variable @code{gdb-many-windows} is @code{nil} (the default -value) then @kbd{M-x gdb} normally displays only the GUD buffer. -However, if the variable @code{gdb-show-main} is also non-@code{nil}, -it starts with two windows: one displaying the GUD buffer, and the -other showing the source for the @code{main} function of the program -you are debugging. - - If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} -displays the following frame layout: - -@smallexample -@group -+--------------------------------+--------------------------------+ -| GUD buffer (I/O of GDB) | Locals buffer | -|--------------------------------+--------------------------------+ -| Primary Source buffer | I/O buffer for debugged pgm | -|--------------------------------+--------------------------------+ -| Stack buffer | Breakpoints buffer | -+--------------------------------+--------------------------------+ -@end group -@end smallexample - - However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O -buffer does not appear and the primary source buffer occupies the full -width of the frame. - -@findex gdb-restore-windows - If you change the window layout, for example, while editing and -re-compiling your program, then you can restore this standard window -layout with the command @code{gdb-restore-windows}. - -@findex gdb-many-windows - To switch between this standard layout and a simple layout -containing just the GUD buffer and a source file, type @kbd{M-x -gdb-many-windows}. - - You may also specify additional GDB-related buffers to display, -either in the same frame or a different one. Select the buffers you -want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames} -sub-menus. If the menu-bar is unavailable, type @code{M-x -gdb-display-@var{buffertype}-buffer} or @code{M-x -gdb-frame-@var{buffertype}-buffer} respectively, where -@var{buffertype} is the relevant buffer type, such as -@samp{breakpoints}. Most of these buffers are read-only, and typing -@kbd{q} in them kills them. - - When you finish debugging, kill the GUD buffer with @kbd{C-x k}, -which will also kill all the buffers associated with the session. -However you need not do this if, after editing and re-compiling your -source code within Emacs, you wish continue debugging. When you -restart execution, GDB will automatically find your new executable. -Keeping the GUD buffer has the advantage of keeping the shell history -as well as GDB's breakpoints. You do need to check that the -breakpoints in recently edited source files are still in the right -places. - -@node Source Buffers -@subsubsection Source Buffers -@cindex GDB commands in Fringe - -@c @findex gdb-mouse-set-clear-breakpoint -@c @findex gdb-mouse-toggle-breakpoint -Many GDB commands can be entered using keybindings or the tool bar but -sometimes it is quicker to use the fringe. These commands either -manipulate breakpoints or control program execution. When there is no -fringe, you can use the margin but this is only present when the -source file already has a breakpoint. - -You can click @kbd{Mouse-1} in the fringe or display margin of a -source buffer to set a breakpoint there and, on a graphical display, a -red bullet will appear on that line. If a breakpoint already exists -on that line, the same click will remove it. You can also enable or -disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. - -A solid arrow in the left fringe of a source buffer indicates the line -of the innermost frame where the debugged program has stopped. A -hollow arrow indicates the current execution line of higher level -frames. - -If you drag the arrow in the fringe with @kbd{Mouse-1} -(@code{gdb-mouse-until}), execution will continue to the line where -you release the button, provided it is still in the same frame. -Alternatively, you can click @kbd{Mouse-3} at some point in the fringe -of this buffer and execution will advance to there. A similar command -(@code{gdb-mouse-jump}) allows you to jump to a source line without -executing the intermediate lines by clicking @kbd{C-Mouse-3}. This -command allows you to go backwards which can be useful for running -through code that has already executed, in order to examine its -execution in more detail. - -@table @kbd -@item Mouse-1 -Set or clear a breakpoint. - -@item C-Mouse-1 -Enable or disable a breakpoint. - -@item Mouse-3 -Continue execution to here. - -@item C-Mouse-3 -Jump to here. -@end table - -If the variable @code{gdb-find-source-frame} is non-@code{nil} and -execution stops in a frame for which there is no source code e.g after -an interrupt, then Emacs finds and displays the first frame further up -stack for which there is source. If it is @code{nil} then the source -buffer continues to display the last frame which maybe more useful, -for example, when re-setting a breakpoint. - -@node Breakpoints Buffer -@subsubsection Breakpoints Buffer - - The breakpoints buffer shows the existing breakpoints, watchpoints and -catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has -these special commands, which mostly apply to the @dfn{current -breakpoint}, the breakpoint which point is on. - -@table @kbd -@item @key{SPC} -@kindex SPC @r{(GDB breakpoints buffer)} -@findex gdb-toggle-breakpoint -Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}). -On a graphical display, this changes the color of a bullet in the -margin of a source buffer at the relevant line. This is red when -the breakpoint is enabled and grey when it is disabled. Text-only -terminals correspondingly display a @samp{B} or @samp{b}. - -@item D -@kindex D @r{(GDB breakpoints buffer)} -@findex gdb-delete-breakpoint -Delete the current breakpoint (@code{gdb-delete-breakpoint}). - -@item @key{RET} -@kindex RET @r{(GDB breakpoints buffer)} -@findex gdb-goto-breakpoint -Visit the source line for the current breakpoint -(@code{gdb-goto-breakpoint}). - -@item Mouse-2 -@kindex Mouse-2 @r{(GDB breakpoints buffer)} -Visit the source line for the breakpoint you click on. -@end table - -@node Stack Buffer -@subsubsection Stack Buffer - - The stack buffer displays a @dfn{call stack}, with one line for each -of the nested subroutine calls (@dfn{stack frames}) now active in the -program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. - -@findex gdb-frames-select -An arrow in the fringe points to the selected frame or, if the fringe is -not present, the number of the selected frame is displayed in reverse -contrast. To select a frame in GDB, move point in the stack buffer to -that stack frame and type @key{RET} (@code{gdb-frames-select}), or click -@kbd{Mouse-2} on a stack frame. If the locals buffer is visible, -selecting a stack frame updates it to display the local variables of the -new frame. - -@node Other GDB-UI Buffers -@subsubsection Other Buffers - -@table @asis -@item Input/Output Buffer -@vindex gdb-use-separate-io-buffer -If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, -the program being debugged takes its input and displays its output -here. Otherwise it uses the GUD buffer for that. To toggle whether -GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. -This takes effect when you next restart the program you are debugging. - -The history and replay commands from Shell mode are available here, -as are the commands to send signals to the debugged program. -@xref{Shell Mode}. - -@item Locals Buffer -The locals buffer displays the values of local variables of the -current frame for simple data types (@pxref{Frame Info, Frame Info, -Information on a frame, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on the value if you want to edit it. - -Arrays and structures display their type only. With GDB 6.4 or later, -move point to their name and press @key{RET}, or alternatively click -@kbd{Mouse-2} there, to examine their values. With earlier versions -of GDB, use @kbd{Mouse-2} or @key{RET} on the type description -(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. - -@item Registers Buffer -@findex toggle-gdb-all-registers -The registers buffer displays the values held by the registers -(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on a register if you want to edit its value. -With GDB 6.4 or later, recently changed register values display with -@code{font-lock-warning-face}. With earlier versions of GDB, you can -press @key{SPC} to toggle the display of floating point registers -(@code{toggle-gdb-all-registers}). - -@item Assembler Buffer -The assembler buffer displays the current frame as machine code. An -arrow points to the current instruction, and you can set and remove -breakpoints as in a source buffer. Breakpoint icons also appear in -the fringe or margin. - -@item Threads Buffer -@findex gdb-threads-select -The threads buffer displays a summary of all threads currently in your -program (@pxref{Threads, Threads, Debugging programs with multiple -threads, gdb, The GNU debugger}). Move point to any thread in the -list and press @key{RET} to select it (@code{gdb-threads-select}) and -display the associated source in the primary source buffer. -Alternatively, click @kbd{Mouse-2} on a thread to select it. If the -locals buffer is visible, its contents update to display the variables -that are local in the new thread. - -@item Memory Buffer -The memory buffer lets you examine sections of program memory -(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). -Click @kbd{Mouse-1} on the appropriate part of the header line to -change the starting address or number of data items that the buffer -displays. Click @kbd{Mouse-3} on the header line to select the -display format or unit size for these data items. -@end table - -@node Watch Expressions -@subsubsection Watch Expressions -@cindex Watching expressions in GDB - -@findex gud-watch -@kindex C-x C-a C-w @r{(GUD)} - If you want to see how a variable changes each time your program -stops, move point into the variable name and click on the watch icon -in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you -specify a prefix argument, you can enter the variable name in the -minibuffer. - - Each watch expression is displayed in the speedbar. Complex data -types, such as arrays, structures and unions are represented in a tree -format. Leaves and simple data types show the name of the expression -and its value and, when the speedbar frame is selected, display the -type as a tooltip. Higher levels show the name, type and address -value for pointers and just the name and type otherwise. Root expressions -also display the frame address as a tooltip to help identify the frame -in which they were defined. - - To expand or contract a complex data type, click @kbd{Mouse-2} or -press @key{SPC} on the tag to the left of the expression. Emacs asks -for confirmation before expanding the expression if its number of -immediate children exceeds the value of the variable -@code{gdb-max-children}. - -@kindex D @r{(GDB speedbar)} -@findex gdb-var-delete - To delete a complex watch expression, move point to the root -expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}). - -@kindex RET @r{(GDB speedbar)} -@findex gdb-edit-value - To edit a variable with a simple data type, or a simple element of a -complex data type, move point there in the speedbar and type @key{RET} -(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to -edit it. Either way, this reads the new value using the minibuffer. - -@vindex gdb-show-changed-values - If you set the variable @code{gdb-show-changed-values} to -non-@code{nil} (the default value), Emacs uses -@code{font-lock-warning-face} to highlight values that have recently -changed and @code{shadow} face to make variables which have gone out of -scope less noticeable. When a variable goes out of scope you can't -edit its value. - -@vindex gdb-use-colon-colon-notation - If the variable @code{gdb-use-colon-colon-notation} is -non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}} -format. This allows the user to display watch expressions which share -the same variable name. The default value is @code{nil}. - -@vindex gdb-speedbar-auto-raise -To automatically raise the speedbar every time the display of watch -expressions updates, set @code{gdb-speedbar-auto-raise} to -non-@code{nil}. This can be useful if you are debugging with a full -screen Emacs frame. - -@node Executing Lisp -@section Executing Lisp Expressions - - Emacs has several different major modes for Lisp and Scheme. They are -the same in terms of editing commands, but differ in the commands for -executing Lisp expressions. Each mode has its own purpose. - -@table @asis -@item Emacs-Lisp mode -The mode for editing source files of programs to run in Emacs Lisp. -This mode defines @kbd{C-M-x} to evaluate the current defun. -@xref{Lisp Libraries}. -@item Lisp Interaction mode -The mode for an interactive session with Emacs Lisp. It defines -@kbd{C-j} to evaluate the sexp before point and insert its value in the -buffer. @xref{Lisp Interaction}. -@item Lisp mode -The mode for editing source files of programs that run in Lisps other -than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun -to an inferior Lisp process. @xref{External Lisp}. -@item Inferior Lisp mode -The mode for an interactive session with an inferior Lisp process. -This mode combines the special features of Lisp mode and Shell mode -(@pxref{Shell Mode}). -@item Scheme mode -Like Lisp mode but for Scheme programs. -@item Inferior Scheme mode -The mode for an interactive session with an inferior Scheme process. -@end table - - Most editing commands for working with Lisp programs are in fact -available globally. @xref{Programs}. - -@node Lisp Libraries -@section Libraries of Lisp Code for Emacs -@cindex libraries -@cindex loading Lisp code - - Lisp code for Emacs editing commands is stored in files whose names -conventionally end in @file{.el}. This ending tells Emacs to edit them in -Emacs-Lisp mode (@pxref{Executing Lisp}). - -@cindex byte code - Emacs Lisp code can be compiled into byte-code, which loads faster, -takes up less space, and executes faster. @xref{Byte Compilation,, -Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By -convention, the compiled code for a library goes in a separate file -whose name ends in @samp{.elc}. Thus, the compiled code for -@file{foo.el} goes in @file{foo.elc}. - -@findex load-file - To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This -command reads a file name using the minibuffer and then executes the -contents of that file as Lisp code. It is not necessary to visit the -file first; in any case, this command reads the file as found on disk, -not text in an Emacs buffer. - -@findex load -@findex load-library - Once a file of Lisp code is installed in the Emacs Lisp library -directories, users can load it using @kbd{M-x load-library}. Programs -can load it by calling @code{load}, a more primitive function that is -similar but accepts some additional arguments. - - @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it -searches a sequence of directories and tries three file names in each -directory. Suppose your argument is @var{lib}; the three names are -@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just -@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention -the result of compiling @file{@var{lib}.el}; it is better to load the -compiled file, since it will load and run faster. - - If @code{load-library} finds that @file{@var{lib}.el} is newer than -@file{@var{lib}.elc} file, it issues a warning, because it's likely -that somebody made changes to the @file{.el} file and forgot to -recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is -because people often leave unfinished edits the source file, and don't -recompile it until they think it is ready to use. - - Because the argument to @code{load-library} is usually not in itself -a valid file name, file name completion is not available. Indeed, when -using this command, you usually do not know exactly what file name -will be used. - -@vindex load-path - The sequence of directories searched by @kbd{M-x load-library} is -specified by the variable @code{load-path}, a list of strings that are -directory names. The default value of the list contains the directories where -the Lisp code for Emacs itself is stored. If you have libraries of -your own, put them in a single directory and add that directory -to @code{load-path}. @code{nil} in this list stands for the current default -directory, but it is probably not a good idea to put @code{nil} in the -list. If you find yourself wishing that @code{nil} were in the list, -most likely what you really want to do is use @kbd{M-x load-file} -this once. - -@cindex autoload - Often you do not have to give any command to load a library, because -the commands defined in the library are set up to @dfn{autoload} that -library. Trying to run any of those commands calls @code{load} to load -the library; this replaces the autoload definitions with the real ones -from the library. - -@vindex load-dangerous-libraries -@cindex Lisp files byte-compiled by XEmacs - By default, Emacs refuses to load compiled Lisp files which were -compiled with XEmacs, a modified versions of Emacs---they can cause -Emacs to crash. Set the variable @code{load-dangerous-libraries} to -@code{t} if you want to try loading them. - -@node Lisp Eval -@section Evaluating Emacs Lisp Expressions -@cindex Emacs-Lisp mode -@cindex mode, Emacs-Lisp - -@findex emacs-lisp-mode - Lisp programs intended to be run in Emacs should be edited in -Emacs-Lisp mode; this happens automatically for file names ending in -@file{.el}. By contrast, Lisp mode itself is used for editing Lisp -programs intended for other Lisp systems. To switch to Emacs-Lisp mode -explicitly, use the command @kbd{M-x emacs-lisp-mode}. - - For testing of Lisp programs to run in Emacs, it is often useful to -evaluate part of the program as it is found in the Emacs buffer. For -example, after changing the text of a Lisp function definition, -evaluating the definition installs the change for future calls to the -function. Evaluation of Lisp expressions is also useful in any kind of -editing, for invoking noninteractive functions (functions that are -not commands). - -@table @kbd -@item M-: -Read a single Lisp expression in the minibuffer, evaluate it, and print -the value in the echo area (@code{eval-expression}). -@item C-x C-e -Evaluate the Lisp expression before point, and print the value in the -echo area (@code{eval-last-sexp}). -@item C-M-x -Evaluate the defun containing or after point, and print the value in -the echo area (@code{eval-defun}). -@item M-x eval-region -Evaluate all the Lisp expressions in the region. -@item M-x eval-buffer -Evaluate all the Lisp expressions in the buffer. -@end table - -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@kindex M-@key{colon} -@end ifinfo -@ifnotinfo -@kindex M-: -@end ifnotinfo -@findex eval-expression - @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating -a Lisp expression interactively. It reads the expression using the -minibuffer, so you can execute any expression on a buffer regardless of -what the buffer contains. When the expression is evaluated, the current -buffer is once again the buffer that was current when @kbd{M-:} was -typed. - -@kindex C-M-x @r{(Emacs-Lisp mode)} -@findex eval-defun - In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command -@code{eval-defun}, which parses the defun containing or following point -as a Lisp expression and evaluates it. The value is printed in the echo -area. This command is convenient for installing in the Lisp environment -changes that you have just made in the text of a function definition. - - @kbd{C-M-x} treats @code{defvar} expressions specially. Normally, -evaluating a @code{defvar} expression does nothing if the variable it -defines already has a value. But @kbd{C-M-x} unconditionally resets the -variable to the initial value specified in the @code{defvar} expression. -@code{defcustom} expressions are treated similarly. -This special feature is convenient for debugging Lisp programs. -Typing @kbd{C-M-x} on a @code{defface} expression reinitializes -the face according to the @code{defface} specification. - -@kindex C-x C-e -@findex eval-last-sexp - The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp -expression preceding point in the buffer, and displays the value in the -echo area. It is available in all major modes, not just Emacs-Lisp -mode. It does not treat @code{defvar} specially. - - When the result of an evaluation is an integer, you can type -@kbd{C-x C-e} a second time to display the value of the integer result -in additional formats (octal, hexadecimal, and character). - - If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it -inserts the value into the current buffer at point, rather than -displaying it in the echo area. The argument's value does not matter. -@kbd{C-M-x} with a numeric argument instruments the function -definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}). - -@findex eval-region -@findex eval-buffer - The most general command for evaluating Lisp expressions from a buffer -is @code{eval-region}. @kbd{M-x eval-region} parses the text of the -region as one or more Lisp expressions, evaluating them one by one. -@kbd{M-x eval-buffer} is similar but evaluates the entire -buffer. This is a reasonable way to install the contents of a file of -Lisp code that you are ready to test. Later, as you find bugs and -change individual functions, use @kbd{C-M-x} on each function that you -change. This keeps the Lisp world in step with the source file. - -@vindex eval-expression-print-level -@vindex eval-expression-print-length -@vindex eval-expression-debug-on-error - The two customizable variables @code{eval-expression-print-level} and -@code{eval-expression-print-length} control the maximum depth and length -of lists to print in the result of the evaluation commands before -abbreviating them. @code{eval-expression-debug-on-error} controls -whether evaluation errors invoke the debugger when these commands are -used; its default is @code{t}. - -@node Lisp Interaction -@section Lisp Interaction Buffers - - The buffer @samp{*scratch*} which is selected when Emacs starts up is -provided for evaluating Lisp expressions interactively inside Emacs. - - The simplest way to use the @samp{*scratch*} buffer is to insert Lisp -expressions and type @kbd{C-j} after each expression. This command -reads the Lisp expression before point, evaluates it, and inserts the -value in printed representation before point. The result is a complete -typescript of the expressions you have evaluated and their values. - - The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which -is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}. - -@findex lisp-interaction-mode - The rationale for this feature is that Emacs must have a buffer when -it starts up, but that buffer is not useful for editing files since a -new buffer is made for every file that you visit. The Lisp interpreter -typescript is the most useful thing I can think of for the initial -buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current -buffer in Lisp Interaction mode. - -@findex ielm - An alternative way of evaluating Emacs Lisp expressions interactively -is to use Inferior Emacs-Lisp mode, which provides an interface rather -like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp -expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer -which uses this mode. For more information see that command's -documentation. - -@node External Lisp -@section Running an External Lisp - - Emacs has facilities for running programs in other Lisp systems. You can -run a Lisp process as an inferior of Emacs, and pass expressions to it to -be evaluated. You can also pass changed function definitions directly from -the Emacs buffers in which you edit the Lisp programs to the inferior Lisp -process. - -@findex run-lisp -@vindex inferior-lisp-program -@kindex C-x C-z - To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs -the program named @code{lisp}, the same program you would run by typing -@code{lisp} as a shell command, with both input and output going through -an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal -output'' from Lisp will go into the buffer, advancing point, and any -``terminal input'' for Lisp comes from text in the buffer. (You can -change the name of the Lisp executable file by setting the variable -@code{inferior-lisp-program}.) - - To give input to Lisp, go to the end of the buffer and type the input, -terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp -mode, which combines the special characteristics of Lisp mode with most -of the features of Shell mode (@pxref{Shell Mode}). The definition of -@key{RET} to send a line to a subprocess is one of the features of Shell -mode. - -@findex lisp-mode - For the source files of programs to run in external Lisps, use Lisp -mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is -used automatically for files whose names end in @file{.l}, -@file{.lsp}, or @file{.lisp}. - -@kindex C-M-x @r{(Lisp mode)} -@findex lisp-eval-defun - When you edit a function in a Lisp program you are running, the easiest -way to send the changed definition to the inferior Lisp process is the key -@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun}, -which finds the defun around or following point and sends it as input to -the Lisp process. (Emacs can send input to any inferior process regardless -of what buffer is current.) - - Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing -programs to be run in another Lisp system) and Emacs-Lisp mode (for -editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in -both modes it has the effect of installing the function definition -that point is in, but the way of doing so is different according to -where the relevant Lisp environment is found. - - -@ignore - arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed -@end ignore diff --git a/man/cal-xtra.texi b/man/cal-xtra.texi deleted file mode 100644 index 61d519cbd12..00000000000 --- a/man/cal-xtra.texi +++ /dev/null @@ -1,838 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). - -@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. -@node Advanced Calendar/Diary Usage -@section Customizing the Calendar and Diary - - There are many customizations that you can use to make the calendar and -diary suit your personal tastes. - -@menu -* Calendar Customizing:: Defaults you can set. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Diary Customizing:: Defaults you can set. -* Hebrew/Islamic Entries:: How to obtain them. -* Fancy Diary Display:: Enhancing the diary display, sorting entries, - using included diary files. -* Sexp Diary Entries:: Fancy things you can do. -@end menu - -@node Calendar Customizing -@subsection Customizing the Calendar -@vindex calendar-holiday-marker -@vindex diary-entry-marker - The variable @code{calendar-holiday-marker} specifies how to mark a -date as being a holiday. Its value may be a single-character string -to insert next to the date, or a face name to use for displaying the -date. Likewise, the variable @code{diary-entry-marker} specifies how -to mark a date that has diary entries. The calendar creates faces -named @code{holiday-face} and @code{diary-face} for these purposes; -those symbols are the default values of these variables. - -@vindex calendar-load-hook - The variable @code{calendar-load-hook} is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - -@vindex initial-calendar-window-hook - Starting the calendar runs the normal hook -@code{initial-calendar-window-hook}. Recomputation of the calendar -display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again.@refill - -@vindex today-visible-calendar-hook - The variable @code{today-visible-calendar-hook} is a normal hook run -after the calendar buffer has been prepared with the calendar when the -current date is visible in the window. One use of this hook is to -replace today's date with asterisks; to do that, use the hook function -@code{calendar-star-date}. - -@findex calendar-star-date -@example -(add-hook 'today-visible-calendar-hook 'calendar-star-date) -@end example - -@noindent -Another standard hook function marks the current date, either by -changing its face or by adding an asterisk. Here's how to use it: - -@findex calendar-mark-today -@example -(add-hook 'today-visible-calendar-hook 'calendar-mark-today) -@end example - -@noindent -@vindex calendar-today-marker -The variable @code{calendar-today-marker} specifies how to mark -today's date. Its value should be a single-character string to insert -next to the date or a face name to use for displaying the date. A -face named @code{calendar-today-face} is provided for this purpose; -that symbol is the default for this variable. - -@vindex today-invisible-calendar-hook -@noindent - A similar normal hook, @code{today-invisible-calendar-hook} is run if -the current date is @emph{not} visible in the window. - -@vindex calendar-move-hook - Each of the calendar cursor motion commands runs the hook -@code{calendar-move-hook} after it moves the cursor. - -@node Holiday Customizing -@subsection Customizing the Holidays - -@vindex calendar-holidays -@vindex christian-holidays -@vindex hebrew-holidays -@vindex islamic-holidays - Emacs knows about holidays defined by entries on one of several lists. -You can customize these lists of holidays to your own needs, adding or -deleting holidays. The lists of holidays that Emacs uses are for -general holidays (@code{general-holidays}), local holidays -(@code{local-holidays}), Christian holidays (@code{christian-holidays}), -Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim) -holidays (@code{islamic-holidays}), and other holidays -(@code{other-holidays}). - -@vindex general-holidays - The general holidays are, by default, holidays common throughout the -United States. To eliminate these holidays, set @code{general-holidays} -to @code{nil}. - -@vindex local-holidays - There are no default local holidays (but sites may supply some). You -can set the variable @code{local-holidays} to any list of holidays, as -described below. - -@vindex all-christian-calendar-holidays -@vindex all-hebrew-calendar-holidays -@vindex all-islamic-calendar-holidays - By default, Emacs does not include all the holidays of the religions -that it knows, only those commonly found in secular calendars. For a -more extensive collection of religious holidays, you can set any (or -all) of the variables @code{all-christian-calendar-holidays}, -@code{all-hebrew-calendar-holidays}, or -@code{all-islamic-calendar-holidays} to @code{t}. If you want to -eliminate the religious holidays, set any or all of the corresponding -variables @code{christian-holidays}, @code{hebrew-holidays}, and -@code{islamic-holidays} to @code{nil}.@refill - -@vindex other-holidays - You can set the variable @code{other-holidays} to any list of -holidays. This list, normally empty, is intended for individual use. - -@cindex holiday forms - Each of the lists (@code{general-holidays}, @code{local-holidays}, -@code{christian-holidays}, @code{hebrew-holidays}, -@code{islamic-holidays}, and @code{other-holidays}) is a list of -@dfn{holiday forms}, each holiday form describing a holiday (or -sometimes a list of holidays). - - Here is a table of the possible kinds of holiday form. Day numbers -and month numbers count starting from 1, but ``dayname'' numbers -count Sunday as 0. The element @var{string} is always the -name of the holiday, as a string. - -@table @code -@item (holiday-fixed @var{month} @var{day} @var{string}) -A fixed date on the Gregorian calendar. - -@item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) -The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar -(@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back -from the end of the month. - -@item (holiday-hebrew @var{month} @var{day} @var{string}) -A fixed date on the Hebrew calendar. - -@item (holiday-islamic @var{month} @var{day} @var{string}) -A fixed date on the Islamic calendar. - -@item (holiday-julian @var{month} @var{day} @var{string}) -A fixed date on the Julian calendar. - -@item (holiday-sexp @var{sexp} @var{string}) -A date calculated by the Lisp expression @var{sexp}. The expression -should use the variable @code{year} to compute and return the date of a -holiday, or @code{nil} if the holiday doesn't happen this year. The -value of @var{sexp} must represent the date as a list of the form -@code{(@var{month} @var{day} @var{year})}. - -@item (if @var{condition} @var{holiday-form}) -A holiday that happens only if @var{condition} is true. - -@item (@var{function} @r{[}@var{args}@r{]}) -A list of dates calculated by the function @var{function}, called with -arguments @var{args}. -@end table - - For example, suppose you want to add Bastille Day, celebrated in -France on July 14. You can do this as follows: - -@smallexample -(setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) -@end smallexample - -@noindent -The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the -fourteenth day of the seventh month (July). - - Many holidays occur on a specific day of the week, at a specific time -of month. Here is a holiday form describing Hurricane Supplication Day, -celebrated in the Virgin Islands on the fourth Monday in August: - -@smallexample -(holiday-float 8 1 4 "Hurricane Supplication Day") -@end smallexample - -@noindent -Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, -Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in -the month (1 specifies the first occurrence, 2 the second occurrence, -@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and -so on). - - You can specify holidays that occur on fixed days of the Hebrew, -Islamic, and Julian calendars too. For example, - -@smallexample -(setq other-holidays - '((holiday-hebrew 10 2 "Last day of Hanukkah") - (holiday-islamic 3 12 "Mohammed's Birthday") - (holiday-julian 4 2 "Jefferson's Birthday"))) -@end smallexample - -@noindent -adds the last day of Hanukkah (since the Hebrew months are numbered with -1 starting from Nisan), the Islamic feast celebrating Mohammed's -birthday (since the Islamic months are numbered from 1 starting with -Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the -Julian calendar. - - To include a holiday conditionally, use either Emacs Lisp's @code{if} or the -@code{holiday-sexp} form. For example, American presidential elections -occur on the first Tuesday after the first Monday in November of years -divisible by 4: - -@smallexample -(holiday-sexp '(if (= 0 (% year 4)) - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 year))))))) - "US Presidential Election") -@end smallexample - -@noindent -or - -@smallexample -(if (= 0 (% displayed-year 4)) - (fixed 11 - (extract-calendar-day - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 displayed-year))))))) - "US Presidential Election")) -@end smallexample - - Some holidays just don't fit into any of these forms because special -calculations are involved in their determination. In such cases you -must write a Lisp function to do the calculation. To include eclipses, -for example, add @code{(eclipses)} to @code{other-holidays} -and write an Emacs Lisp function @code{eclipses} that returns a -(possibly empty) list of the relevant Gregorian dates among the range -visible in the calendar window, with descriptive strings, like this: - -@smallexample -(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) -@end smallexample - -@node Date Display Format -@subsection Date Display Format -@vindex calendar-date-display-form - - You can customize the manner of displaying dates in the diary, in mode -lines, and in messages by setting @code{calendar-date-display-form}. -This variable holds a list of expressions that can involve the variables -@code{month}, @code{day}, and @code{year}, which are all numbers in -string form, and @code{monthname} and @code{dayname}, which are both -alphabetic strings. In the American style, the default value of this -list is as follows: - -@smallexample -((if dayname (concat dayname ", ")) monthname " " day ", " year) -@end smallexample - -@noindent -while in the European style this value is the default: - -@smallexample -((if dayname (concat dayname ", ")) day " " monthname " " year) -@end smallexample - -@noindent -The ISO standard date representation is this: - -@smallexample -(year "-" month "-" day) -@end smallexample - -@noindent -This specifies a typical American format: - -@smallexample -(month "/" day "/" (substring year -2)) -@end smallexample - -@node Time Display Format -@subsection Time Display Format -@vindex calendar-time-display-form - - The calendar and diary by default display times of day in the -conventional American style with the hours from 1 through 12, minutes, -and either @samp{am} or @samp{pm}. If you prefer the European style, -also known in the US as military, in which the hours go from 00 to 23, -you can alter the variable @code{calendar-time-display-form}. This -variable is a list of expressions that can involve the variables -@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all -numbers in string form, and @code{am-pm} and @code{time-zone}, which are -both alphabetic strings. The default value of -@code{calendar-time-display-form} is as follows: - -@smallexample -(12-hours ":" minutes am-pm - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@noindent -Here is a value that provides European style times: - -@smallexample -(24-hours ":" minutes - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@node Diary Customizing -@subsection Customizing the Diary - -@vindex holidays-in-diary-buffer - Ordinarily, the mode line of the diary buffer window indicates any -holidays that fall on the date of the diary entries. The process of -checking for holidays can take several seconds, so including holiday -information delays the display of the diary buffer noticeably. If you'd -prefer to have a faster display of the diary buffer but without the -holiday information, set the variable @code{holidays-in-diary-buffer} to -@code{nil}.@refill - -@vindex number-of-diary-entries - The variable @code{number-of-diary-entries} controls the number of -days of diary entries to be displayed at one time. It affects the -initial display when @code{view-diary-entries-initially} is @code{t}, as -well as the command @kbd{M-x diary}. For example, the default value is -1, which says to display only the current day's diary entries. If the -value is 2, both the current day's and the next day's entries are -displayed. The value can also be a vector of seven elements: for -example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries -appear on Sunday, the current date's and the next day's diary entries -appear Monday through Thursday, Friday through Monday's entries appear -on Friday, while on Saturday only that day's entries appear. - -@vindex print-diary-entries-hook -@findex print-diary-entries - The variable @code{print-diary-entries-hook} is a normal hook run -after preparation of a temporary buffer containing just the diary -entries currently visible in the diary buffer. (The other, irrelevant -diary entries are really absent from the temporary buffer; in the diary -buffer, they are merely hidden.) The default value of this hook does -the printing with the command @code{lpr-buffer}. If you want to use a -different command to do the printing, just change the value of this -hook. Other uses might include, for example, rearranging the lines into -order by day and time. - -@vindex diary-date-forms - You can customize the form of dates in your diary file, if neither the -standard American nor European styles suits your needs, by setting the -variable @code{diary-date-forms}. This variable is a list of patterns -for recognizing a date. Each date pattern is a list whose elements may -be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs -Lisp Reference Manual}) or the symbols @code{month}, @code{day}, -@code{year}, @code{monthname}, and @code{dayname}. All these elements -serve as patterns that match certain kinds of text in the diary file. -In order for the date pattern, as a whole, to match, all of its elements -must match consecutively. - - A regular expression in a date pattern matches in its usual fashion, -using the standard syntax table altered so that @samp{*} is a word -constituent. - - The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, -and @code{dayname} match the month number, day number, year number, -month name, and day name of the date being considered. The symbols that -match numbers allow leading zeros; those that match names allow -three-letter abbreviations and capitalization. All the symbols can -match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any -month'', and so on, it should match regardless of the date being -considered. - - The default value of @code{diary-date-forms} in the American style is -this: - -@example -((month "/" day "[^/0-9]") - (month "/" day "/" year "[^0-9]") - (monthname " *" day "[^,0-9]") - (monthname " *" day ", *" year "[^0-9]") - (dayname "\\W")) -@end example - - The date patterns in the list must be @emph{mutually exclusive} and -must not match any portion of the diary entry itself, just the date and -one character of whitespace. If, to be mutually exclusive, the pattern -must match a portion of the diary entry text---beyond the whitespace -that ends the date---then the first element of the date pattern -@emph{must} be @code{backup}. This causes the date recognizer to back -up to the beginning of the current word of the diary entry, after -finishing the match. Even if you use @code{backup}, the date pattern -must absolutely not match more than a portion of the first word of the -diary entry. The default value of @code{diary-date-forms} in the -European style is this list: - -@example -((day "/" month "[^/0-9]") - (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<[^*0-9]") - (day " *" monthname " *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -Notice the use of @code{backup} in the third pattern, because it needs -to match part of a word beyond the date itself to distinguish it from -the fourth pattern. - -@node Hebrew/Islamic Entries -@subsection Hebrew- and Islamic-Date Diary Entries - - Your diary file can have entries based on Hebrew or Islamic dates, as -well as entries based on the world-standard Gregorian calendar. -However, because recognition of such entries is time-consuming and most -people don't use them, you must explicitly enable their use. If you -want the diary to recognize Hebrew-date diary entries, for example, -you must do this: - -@vindex nongregorian-diary-listing-hook -@vindex nongregorian-diary-marking-hook -@findex list-hebrew-diary-entries -@findex mark-hebrew-diary-entries -@smallexample -(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) -(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) -@end smallexample - -@noindent -If you want Islamic-date entries, do this: - -@findex list-islamic-diary-entries -@findex mark-islamic-diary-entries -@smallexample -(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) -(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) -@end smallexample - - Hebrew- and Islamic-date diary entries have the same formats as -Gregorian-date diary entries, except that @samp{H} precedes a Hebrew -date and @samp{I} precedes an Islamic date. Moreover, because the -Hebrew and Islamic month names are not uniquely specified by the first -three letters, you may not abbreviate them. For example, a diary entry -for the Hebrew date Heshvan 25 could look like this: - -@smallexample -HHeshvan 25 Happy Hebrew birthday! -@end smallexample - -@noindent -and would appear in the diary for any date that corresponds to Heshvan 25 -on the Hebrew calendar. And here is an Islamic-date diary entry that matches -Dhu al-Qada 25: - -@smallexample -IDhu al-Qada 25 Happy Islamic birthday! -@end smallexample - - As with Gregorian-date diary entries, Hebrew- and Islamic-date entries -are nonmarking if they are preceded with an ampersand (@samp{&}). - - Here is a table of commands used in the calendar to create diary entries -that match the selected date and other dates that are similar in the Hebrew -or Islamic calendar: - -@table @kbd -@item i h d -Add a diary entry for the Hebrew date corresponding to the selected date -(@code{insert-hebrew-diary-entry}). -@item i h m -Add a diary entry for the day of the Hebrew month corresponding to the -selected date (@code{insert-monthly-hebrew-diary-entry}). This diary -entry matches any date that has the same Hebrew day-within-month as the -selected date. -@item i h y -Add a diary entry for the day of the Hebrew year corresponding to the -selected date (@code{insert-yearly-hebrew-diary-entry}). This diary -entry matches any date which has the same Hebrew month and day-within-month -as the selected date. -@item i i d -Add a diary entry for the Islamic date corresponding to the selected date -(@code{insert-islamic-diary-entry}). -@item i i m -Add a diary entry for the day of the Islamic month corresponding to the -selected date (@code{insert-monthly-islamic-diary-entry}). -@item i i y -Add a diary entry for the day of the Islamic year corresponding to the -selected date (@code{insert-yearly-islamic-diary-entry}). -@end table - -@findex insert-hebrew-diary-entry -@findex insert-monthly-hebrew-diary-entry -@findex insert-yearly-hebrew-diary-entry -@findex insert-islamic-diary-entry -@findex insert-monthly-islamic-diary-entry -@findex insert-yearly-islamic-diary-entry - These commands work much like the corresponding commands for ordinary -diary entries: they apply to the date that point is on in the calendar -window, and what they do is insert just the date portion of a diary entry -at the end of your diary file. You must then insert the rest of the -diary entry. - -@node Fancy Diary Display -@subsection Fancy Diary Display -@vindex diary-display-hook -@findex simple-diary-display - - Diary display works by preparing the diary buffer and then running the -hook @code{diary-display-hook}. The default value of this hook -(@code{simple-diary-display}) hides the irrelevant diary entries and -then displays the buffer. However, if you specify the hook as follows, - -@cindex diary buffer -@findex fancy-diary-display -@example -(add-hook 'diary-display-hook 'fancy-diary-display) -@end example - -@noindent -this enables fancy diary display. It displays diary entries and -holidays by copying them into a special buffer that exists only for the -sake of display. Copying to a separate buffer provides an opportunity -to change the displayed text to make it prettier---for example, to sort -the entries by the dates they apply to. - - As with simple diary display, you can print a hard copy of the buffer -with @code{print-diary-entries}. To print a hard copy of a day-by-day -diary for a week, position point on Sunday of that week, type -@kbd{7 d}, and then do @kbd{M-x print-diary-entries}. As usual, the -inclusion of the holidays slows down the display slightly; you can speed -things up by setting the variable @code{holidays-in-diary-buffer} to -@code{nil}. - -@vindex diary-list-include-blanks - Ordinarily, the fancy diary buffer does not show days for which there are -no diary entries, even if that day is a holiday. If you want such days to be -shown in the fancy diary buffer, set the variable -@code{diary-list-include-blanks} to @code{t}.@refill - -@cindex sorting diary entries - If you use the fancy diary display, you can use the normal hook -@code{list-diary-entries-hook} to sort each day's diary entries by their -time of day. Here's how: - -@findex sort-diary-entries -@example -(add-hook 'list-diary-entries-hook 'sort-diary-entries t) -@end example - -@noindent -For each day, this sorts diary entries that begin with a recognizable -time of day according to their times. Diary entries without times come -first within each day. - - Fancy diary display also has the ability to process included diary -files. This permits a group of people to share a diary file for events -that apply to all of them. Lines in the diary file of this form: - -@smallexample -#include "@var{filename}" -@end smallexample - -@noindent -includes the diary entries from the file @var{filename} in the fancy -diary buffer. The include mechanism is recursive, so that included files -can include other files, and so on; you must be careful not to have a -cycle of inclusions, of course. Here is how to enable the include -facility: - -@vindex list-diary-entries-hook -@vindex mark-diary-entries-hook -@findex include-other-diary-files -@findex mark-included-diary-files -@smallexample -(add-hook 'list-diary-entries-hook 'include-other-diary-files) -(add-hook 'mark-diary-entries-hook 'mark-included-diary-files) -@end smallexample - -The include mechanism works only with the fancy diary display, because -ordinary diary display shows the entries directly from your diary file. - -@node Sexp Diary Entries -@subsection Sexp Entries and the Fancy Diary Display -@cindex sexp diary entries - - Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. If you use the fancy -diary display, sexp entries can generate the text of the entry depending -on the date itself. For example, an anniversary diary entry can insert -the number of years since the anniversary date into the text of the -diary entry. Thus the @samp{%d} in this diary entry: - -@findex diary-anniversary -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) -@end smallexample - -@noindent -gets replaced by the age, so on October 31, 1990 the entry appears in -the fancy diary buffer like this: - -@smallexample -Arthur's birthday (42 years old) -@end smallexample - -@noindent -If the diary file instead contains this entry: - -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday -@end smallexample - -@noindent -the entry in the fancy diary buffer for October 31, 1990 appears like this: - -@smallexample -Arthur's 42nd birthday -@end smallexample - - Similarly, cyclic diary entries can interpolate the number of repetitions -that have occurred: - -@findex diary-cyclic -@smallexample -%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) -@end smallexample - -@noindent -looks like this: - -@smallexample -Renew medication (5th time) -@end smallexample - -@noindent -in the fancy diary display on September 8, 1990. - - There is an early reminder diary sexp that includes its entry in the -diary not only on the date of occurrence, but also on earlier dates. -For example, if you want a reminder a week before your anniversary, you -can use - -@findex diary-remind -@smallexample -%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary -@end smallexample - -@noindent -and the fancy diary will show -@smallexample -Ed's anniversary -@end smallexample -@noindent -both on December 15 and on December 22. - -@findex diary-date - The function @code{diary-date} applies to dates described by a month, -day, year combination, each of which can be an integer, a list of -integers, or @code{t}. The value @code{t} means all values. For -example, - -@smallexample -%%(diary-date '(10 11 12) 22 t) Rake leaves -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Rake leaves -@end smallexample - -@noindent -on October 22, November 22, and December 22 of every year. - -@findex diary-float - The function @code{diary-float} allows you to describe diary entries -that apply to dates like the third Friday of November, or the last -Tuesday in April. The parameters are the @var{month}, @var{dayname}, -and an index @var{n}. The entry appears on the @var{n}th @var{dayname} -of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and -so on. If @var{n} is negative it counts backward from the end of -@var{month}. The value of @var{month} can be a list of months, a single -month, or @code{t} to specify all months. You can also use an optional -parameter @var{day} to specify the @var{n}th @var{dayname} of -@var{month} on or after/before @var{day}; the value of @var{day} defaults -to 1 if @var{n} is positive and to the last day of @var{month} if -@var{n} is negative. For example, - -@smallexample -%%(diary-float t 1 -1) Pay rent -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Pay rent -@end smallexample - -@noindent -on the last Monday of every month. - - The generality of sexp diary entries lets you specify any diary -entry that you can describe algorithmically. A sexp diary entry -contains an expression that computes whether the entry applies to any -given date. If its value is non-@code{nil}, the entry applies to that -date; otherwise, it does not. The expression can use the variable -@code{date} to find the date being considered; its value is a list -(@var{month} @var{day} @var{year}) that refers to the Gregorian -calendar. - - The sexp diary entry applies to a date when the expression's value -is non-@code{nil}, but some values have more specific meanings. If -the value is a string, that string is a description of the event which -occurs on that date. The value can also have the form -@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to -mark the date in the calendar, and @var{string} is the description of -the event. If @var{mark} is a single-character string, that character -appears next to the date in the calendar. If @var{mark} is a face -name, the date is displayed in that face. If @var{mark} is -@code{nil}, that specifies no particular highlighting for the date. - - Suppose you get paid on the 21st of the month if it is a weekday, and -on the Friday before if the 21st is on a weekend. Here is how to write -a sexp diary entry that matches those dates: - -@smallexample -&%%(let ((dayname (calendar-day-of-week date)) - (day (car (cdr date)))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited -@end smallexample - - The following sexp diary entries take advantage of the ability (in the fancy -diary display) to concoct diary entries whose text varies based on the date: - -@findex diary-sunrise-sunset -@findex diary-phases-of-moon -@findex diary-day-of-year -@findex diary-iso-date -@findex diary-julian-date -@findex diary-astro-day-number -@findex diary-hebrew-date -@findex diary-islamic-date -@findex diary-french-date -@findex diary-mayan-date -@table @code -@item %%(diary-sunrise-sunset) -Make a diary entry for the local times of today's sunrise and sunset. -@item %%(diary-phases-of-moon) -Make a diary entry for the phases (quarters) of the moon. -@item %%(diary-day-of-year) -Make a diary entry with today's day number in the current year and the number -of days remaining in the current year. -@item %%(diary-iso-date) -Make a diary entry with today's equivalent ISO commercial date. -@item %%(diary-julian-date) -Make a diary entry with today's equivalent date on the Julian calendar. -@item %%(diary-astro-day-number) -Make a diary entry with today's equivalent astronomical (Julian) day number. -@item %%(diary-hebrew-date) -Make a diary entry with today's equivalent date on the Hebrew calendar. -@item %%(diary-islamic-date) -Make a diary entry with today's equivalent date on the Islamic calendar. -@item %%(diary-french-date) -Make a diary entry with today's equivalent date on the French Revolutionary -calendar. -@item %%(diary-mayan-date) -Make a diary entry with today's equivalent date on the Mayan calendar. -@end table - -@noindent -Thus including the diary entry - -@example -&%%(diary-hebrew-date) -@end example - -@noindent -causes every day's diary display to contain the equivalent date on the -Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the line @samp{&%%(diary-hebrew-date)} appears in the -diary for any date, but does nothing particularly useful.) - - These functions can be used to construct sexp diary entries based on -the Hebrew calendar in certain standard ways: - -@cindex rosh hodesh -@findex diary-rosh-hodesh -@cindex parasha, weekly -@findex diary-parasha -@cindex candle lighting times -@findex diary-sabbath-candles -@cindex omer count -@findex diary-omer -@cindex yahrzeits -@findex diary-yahrzeit -@table @code -@item %%(diary-rosh-hodesh) -Make a diary entry that tells the occurrence and ritual announcement of each -new Hebrew month. -@item %%(diary-parasha) -Make a Saturday diary entry that tells the weekly synagogue scripture reading. -@item %%(diary-sabbath-candles) -Make a Friday diary entry that tells the @emph{local time} of Sabbath -candle lighting. -@item %%(diary-omer) -Make a diary entry that gives the omer count, when appropriate. -@item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name} -Make a diary entry marking the anniversary of a date of death. The date -is the @emph{Gregorian} (civil) date of death. The diary entry appears -on the proper Hebrew calendar anniversary and on the day before. (In -the European style, the order of the parameters is changed to @var{day}, -@var{month}, @var{year}.) -@end table - - All the functions documented above take an optional argument -@var{mark} which specifies how to mark the date in the calendar display. -If one of these functions decides that it applies to a certain date, -it returns a value that contains @var{mark}. - -@ignore - arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431 -@end ignore diff --git a/man/calc.texi b/man/calc.texi deleted file mode 100644 index 93c7123d6a4..00000000000 --- a/man/calc.texi +++ /dev/null @@ -1,36190 +0,0 @@ -\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/man/calendar.texi b/man/calendar.texi deleted file mode 100644 index 5182474622d..00000000000 --- a/man/calendar.texi +++ /dev/null @@ -1,1687 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Calendar/Diary, Gnus, Dired, Top -@chapter The Calendar and the Diary -@cindex calendar -@findex calendar - - Emacs provides the functions of a desk calendar, with a diary of -planned or past events. It also has facilities for managing your -appointments, and keeping track of how much time you spend working on -certain projects. - - To enter the calendar, type @kbd{M-x calendar}; this displays a -three-month calendar centered on the current month, with point on the -current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it -prompts you for the month and year to be the center of the three-month -calendar. The calendar uses its own buffer, whose major mode is -Calendar mode. - - @kbd{Mouse-2} in the calendar brings up a menu of operations on a -particular date; @kbd{Mouse-3} brings up a menu of commonly used -calendar features that are independent of any particular date. To exit -the calendar, type @kbd{q}. - -@iftex - This chapter describes the basic calendar features. -@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information -about more specialized features. -@end iftex - -@menu -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -@ifnottex -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -@end ifnottex -@end menu - -@node Calendar Motion -@section Movement in the Calendar - -@cindex moving inside the calendar - Calendar mode provides commands to move through the calendar in -logical units of time such as days, weeks, months, and years. If you -move outside the three months originally displayed, the calendar -display ``scrolls'' automatically through time to make the selected -date visible. Moving to a date lets you view its holidays or diary -entries, or convert it to other calendars; moving by long time periods -is also useful simply to scroll the calendar. - -@menu -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. -@end menu - -@node Calendar Unit Motion -@subsection Motion by Standard Lengths of Time - - The commands for movement in the calendar buffer parallel the -commands for movement in text. You can move forward and backward by -days, weeks, months, and years. - -@table @kbd -@item C-f -Move point one day forward (@code{calendar-forward-day}). -@item C-b -Move point one day backward (@code{calendar-backward-day}). -@item C-n -Move point one week forward (@code{calendar-forward-week}). -@item C-p -Move point one week backward (@code{calendar-backward-week}). -@item M-@} -Move point one month forward (@code{calendar-forward-month}). -@item M-@{ -Move point one month backward (@code{calendar-backward-month}). -@item C-x ] -Move point one year forward (@code{calendar-forward-year}). -@item C-x [ -Move point one year backward (@code{calendar-backward-year}). -@end table - -@kindex C-f @r{(Calendar mode)} -@findex calendar-forward-day -@kindex C-b @r{(Calendar mode)} -@findex calendar-backward-day -@kindex C-n @r{(Calendar mode)} -@findex calendar-forward-week -@kindex C-p @r{(Calendar mode)} -@findex calendar-backward-week - The day and week commands are natural analogues of the usual Emacs -commands for moving by characters and by lines. Just as @kbd{C-n} -usually moves to the same column in the following line, in Calendar -mode it moves to the same day in the following week. And @kbd{C-p} -moves to the same day in the previous week. - - The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and -@kbd{C-p}, just as they normally are in other modes. - -@kindex M-@} @r{(Calendar mode)} -@findex calendar-forward-month -@kindex M-@{ @r{(Calendar mode)} -@findex calendar-backward-month -@kindex C-x ] @r{(Calendar mode)} -@findex calendar-forward-year -@kindex C-x [ @r{(Calendar mode)} -@findex calendar-forward-year - The commands for motion by months and years work like those for -weeks, but move a larger distance. The month commands @kbd{M-@}} and -@kbd{M-@{} move forward or backward by an entire month. The year -commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a -whole year. - - The easiest way to remember these commands is to consider months and -years analogous to paragraphs and pages of text, respectively. But -the commands themselves are not quite analogous. The ordinary Emacs -paragraph commands move to the beginning or end of a paragraph, -whereas these month and year commands move by an entire month or an -entire year, keeping the same date within the month or year. - - All these commands accept a numeric argument as a repeat count. -For convenience, the digit keys and the minus sign specify numeric -arguments in Calendar mode even without the Meta modifier. For example, -@kbd{100 C-f} moves point 100 days forward from its present location. - -@node Move to Beginning or End -@subsection Beginning or End of Week, Month or Year - - A week (or month, or year) is not just a quantity of days; we think of -weeks (months, years) as starting on particular dates. So Calendar mode -provides commands to move to the beginning or end of a week, month or -year: - -@table @kbd -@kindex C-a @r{(Calendar mode)} -@findex calendar-beginning-of-week -@item C-a -Move point to start of week (@code{calendar-beginning-of-week}). -@kindex C-e @r{(Calendar mode)} -@findex calendar-end-of-week -@item C-e -Move point to end of week (@code{calendar-end-of-week}). -@kindex M-a @r{(Calendar mode)} -@findex calendar-beginning-of-month -@item M-a -Move point to start of month (@code{calendar-beginning-of-month}). -@kindex M-e @r{(Calendar mode)} -@findex calendar-end-of-month -@item M-e -Move point to end of month (@code{calendar-end-of-month}). -@kindex M-< @r{(Calendar mode)} -@findex calendar-beginning-of-year -@item M-< -Move point to start of year (@code{calendar-beginning-of-year}). -@kindex M-> @r{(Calendar mode)} -@findex calendar-end-of-year -@item M-> -Move point to end of year (@code{calendar-end-of-year}). -@end table - - These commands also take numeric arguments as repeat counts, with the -repeat count indicating how many weeks, months, or years to move -backward or forward. - -@vindex calendar-week-start-day -@cindex weeks, which day they start on -@cindex calendar, first day of week - By default, weeks begin on Sunday. To make them begin on Monday -instead, set the variable @code{calendar-week-start-day} to 1. - -@node Specified Dates -@subsection Specified Dates - - Calendar mode provides commands for moving to a particular date -specified in various ways. - -@table @kbd -@item g d -Move point to specified date (@code{calendar-goto-date}). -@item g D -Move point to specified day of year (@code{calendar-goto-day-of-year}). -@item g w -Move point to specified week of year (@code{calendar-goto-iso-week}). -@item o -Center calendar around specified month (@code{calendar-other-month}). -@item . -Move point to today's date (@code{calendar-goto-today}). -@end table - -@kindex g d @r{(Calendar mode)} -@findex calendar-goto-date - @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day -of the month, and then moves to that date. Because the calendar includes all -dates from the beginning of the current era, you must type the year in its -entirety; that is, type @samp{1990}, not @samp{90}. - -@kindex g D @r{(Calendar mode)} -@findex calendar-goto-day-of-year -@kindex g w @r{(Calendar mode)} -@findex calendar-goto-iso-week - @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and -day number, and moves to that date. Negative day numbers count -backward from the end of the year. @kbd{g w} -(@code{calendar-goto-iso-week}) prompts for a year and week number, -and moves to that week. - -@kindex o @r{(Calendar mode)} -@findex calendar-other-month - @kbd{o} (@code{calendar-other-month}) prompts for a month and year, -then centers the three-month calendar around that month. - -@kindex . @r{(Calendar mode)} -@findex calendar-goto-today - You can return to today's date with @kbd{.}@: -(@code{calendar-goto-today}). - -@node Scroll Calendar -@section Scrolling in the Calendar - -@cindex scrolling in the calendar - The calendar display scrolls automatically through time when you -move out of the visible portion. You can also scroll it manually. -Imagine that the calendar window contains a long strip of paper with -the months on it. Scrolling the calendar means moving the strip -horizontally, so that new months become visible in the window. - -@table @kbd -@item > -Scroll calendar one month forward (@code{scroll-calendar-left}). -@item < -Scroll calendar one month backward (@code{scroll-calendar-right}). -@item C-v -@itemx @key{NEXT} -Scroll calendar three months forward -(@code{scroll-calendar-left-three-months}). -@item M-v -@itemx @key{PRIOR} -Scroll calendar three months backward -(@code{scroll-calendar-right-three-months}). -@end table - -@kindex > @r{(Calendar mode)} -@findex scroll-calendar-left -@kindex < @r{(Calendar mode)} -@findex scroll-calendar-right - The most basic calendar scroll commands scroll by one month at a -time. This means that there are two months of overlap between the -display before the command and the display after. @kbd{>} scrolls the -calendar contents one month forward in time. @kbd{<} scrolls the -contents one month backwards in time. - -@kindex C-v @r{(Calendar mode)} -@findex scroll-calendar-left-three-months -@kindex M-v @r{(Calendar mode)} -@findex scroll-calendar-right-three-months - The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire -``screenful''---three months---in analogy with the usual meaning of -these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes -earlier dates visible. These commands take a numeric argument as a -repeat count; in particular, since @kbd{C-u} multiplies the next command -by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and -typing @kbd{C-u M-v} scrolls the calendar backward by a year. - - The function keys @key{NEXT} and @key{PRIOR} are equivalent to -@kbd{C-v} and @kbd{M-v}, just as they are in other modes. - -@node Counting Days -@section Counting Days - -@table @kbd -@item M-= -Display the number of days in the current region -(@code{calendar-count-days-region}). -@end table - -@kindex M-= @r{(Calendar mode)} -@findex calendar-count-days-region - To determine the number of days in the region, type @kbd{M-=} -(@code{calendar-count-days-region}). The numbers of days shown is -@emph{inclusive}; that is, it includes the days specified by mark and -point. - -@node General Calendar -@section Miscellaneous Calendar Commands - -@table @kbd -@item p d -Display day-in-year (@code{calendar-print-day-of-year}). -@item C-c C-l -Regenerate the calendar window (@code{redraw-calendar}). -@item SPC -Scroll the next window up (@code{scroll-other-window}). -@item DEL -Scroll the next window down (@code{scroll-other-window-down}). -@item q -Exit from calendar (@code{exit-calendar}). -@end table - -@kindex p d @r{(Calendar mode)} -@cindex day of year -@findex calendar-print-day-of-year - To display the number of days elapsed since the start of the year, or -the number of days remaining in the year, type the @kbd{p d} command -(@code{calendar-print-day-of-year}). This displays both of those -numbers in the echo area. The count of days elapsed includes the -selected date. The count of days remaining does not include that -date. - -@kindex C-c C-l @r{(Calendar mode)} -@findex redraw-calendar - If the calendar window text gets corrupted, type @kbd{C-c C-l} -(@code{redraw-calendar}) to redraw it. (This can only happen if you use -non-Calendar-mode editing commands.) - -@kindex SPC @r{(Calendar mode)} - In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window}) -and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other -window up or down, respectively. This is handy when you display a list -of holidays or diary entries in another window. - -@kindex q @r{(Calendar mode)} -@findex exit-calendar - To exit from the calendar, type @kbd{q} (@code{exit-calendar}). This -buries all buffers related to the calendar, selecting other buffers. -(If a frame contains a dedicated calendar window, exiting from the -calendar iconifies that frame.) - -@node Writing Calendar Files -@section Writing Calendar Files - - These packages produce files of various formats containing calendar -and diary entries, for display purposes. - -@cindex calendar and HTML - The Calendar HTML commands produce files of HTML code that contain -calendar and diary entries. Each file applies to one month, and has a -name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and -@var{mm} are the four-digit year and two-digit month, respectively. The -variable @code{cal-html-directory} specifies the default output -directory for the HTML files. - -@vindex cal-html-css-default - Diary entries enclosed by @code{<} and @code{>} are interpreted as -HTML tags (for example: this is a diary entry with some red text). You can change the overall -appearance of the displayed HTML pages (for example, the color of -various page elements, header styles) via a stylesheet @file{cal.css} in -the directory containing the HTML files (see the value of the variable -@code{cal-html-css-default} for relevant style settings). - -@kindex t @r{(Calendar mode)} -@table @kbd -@item H m -Generate a one-month calendar (@code{cal-html-cursor-month}). -@item H y -Generate a calendar file for each month of a year, as well as an index -page (@code{cal-html-cursor-year}). By default, this command writes -files to a @var{yyyy} subdirectory - if this is altered some hyperlinks -between years will not work. -@end table - - If the variable @code{cal-html-print-day-number-flag} is -non-@code{nil}, then the monthly calendars show the day-of-the-year -number. The variable @code{cal-html-year-index-cols} specifies the -number of columns in the yearly index page. - -@cindex calendar and La@TeX{} - The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that -prints as a calendar. Depending on the command you use, the printed -calendar covers the day, week, month or year that point is in. - -@kindex t @r{(Calendar mode)} -@table @kbd -@item t m -Generate a one-month calendar (@code{cal-tex-cursor-month}). -@item t M -Generate a sideways-printing one-month calendar -(@code{cal-tex-cursor-month-landscape}). -@item t d -Generate a one-day calendar -(@code{cal-tex-cursor-day}). -@item t w 1 -Generate a one-page calendar for one week -(@code{cal-tex-cursor-week}). -@item t w 2 -Generate a two-page calendar for one week -(@code{cal-tex-cursor-week2}). -@item t w 3 -Generate an ISO-style calendar for one week -(@code{cal-tex-cursor-week-iso}). -@item t w 4 -Generate a calendar for one Monday-starting week -(@code{cal-tex-cursor-week-monday}). -@item t f w -Generate a Filofax-style two-weeks-at-a-glance calendar -(@code{cal-tex-cursor-filofax-2week}). -@item t f W -Generate a Filofax-style one-week-at-a-glance calendar -(@code{cal-tex-cursor-filofax-week}). -@item t y -Generate a calendar for one year -(@code{cal-tex-cursor-year}). -@item t Y -Generate a sideways-printing calendar for one year -(@code{cal-tex-cursor-year-landscape}). -@item t f y -Generate a Filofax-style calendar for one year -(@code{cal-tex-cursor-filofax-year}). -@end table - - Some of these commands print the calendar sideways (in ``landscape -mode''), so it can be wider than it is long. Some of them use Filofax -paper size (3.75in x 6.75in). All of these commands accept a prefix -argument which specifies how many days, weeks, months or years to print -(starting always with the selected one). - - If the variable @code{cal-tex-holidays} is non-@code{nil} (the default), -then the printed calendars show the holidays in @code{calendar-holidays}. -If the variable @code{cal-tex-diary} is non-@code{nil} (the default is -@code{nil}), diary entries are included also (in monthly, filofax, and -iso-week calendars only). If the variable @code{cal-tex-rules} is -non-@code{nil} (the default is @code{nil}), the calendar displays ruled -pages in styles that have sufficient room. Consult the documentation of -the individual cal-tex functions to see which calendars support which -features. - - You can use the variable @code{cal-tex-preamble-extra} to insert extra -La@TeX{} commands in the preamble of the generated document if you need -to. - -@node Holidays -@section Holidays -@cindex holidays - - The Emacs calendar knows about all major and many minor holidays, -and can display them. - -@table @kbd -@item h -Display holidays for the selected date -(@code{calendar-cursor-holidays}). -@item Mouse-2 Holidays -Display any holidays for the date you click on. -@item x -Mark holidays in the calendar window (@code{mark-calendar-holidays}). -@item u -Unmark calendar window (@code{calendar-unmark}). -@item a -List all holidays for the displayed three months in another window -(@code{list-calendar-holidays}). -@item M-x holidays -List all holidays for three months around today's date in another -window. -@item M-x list-holidays -List holidays in another window for a specified range of years. -@end table - -@kindex h @r{(Calendar mode)} -@findex calendar-cursor-holidays -@vindex view-calendar-holidays-initially - To see if any holidays fall on a given date, position point on that -date in the calendar window and use the @kbd{h} command. Alternatively, -click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays} -from the menu that appears. Either way, this displays the holidays for -that date, in the echo area if they fit there, otherwise in a separate -window. - -@kindex x @r{(Calendar mode)} -@findex mark-calendar-holidays -@kindex u @r{(Calendar mode)} -@findex calendar-unmark -@vindex mark-holidays-in-calendar - To view the distribution of holidays for all the dates shown in the -calendar, use the @kbd{x} command. This displays the dates that are -holidays in a different face (or places a @samp{*} after these dates, if -display with multiple faces is not available). -@iftex -@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing, calendar-holiday-marker}. -@end ifnottex - The command applies both to the currently visible months and to -other months that subsequently become visible by scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -erases any diary marks (@pxref{Diary}). If the variable -@code{mark-holidays-in-calendar} is non-@code{nil}, creating or -updating the calendar marks holidays automatically. - -@kindex a @r{(Calendar mode)} -@findex list-calendar-holidays - To get even more detailed information, use the @kbd{a} command, which -displays a separate buffer containing a list of all holidays in the -current three-month range. You can use @key{SPC} and @key{DEL} in the -calendar window to scroll that list up and down, respectively. - -@findex holidays - The command @kbd{M-x holidays} displays the list of holidays for the -current month and the preceding and succeeding months; this works even -if you don't have a calendar window. If the variable -@code{view-calendar-holidays-initially} is non-@code{nil}, creating -the calendar displays holidays in this way. If you want the list of -holidays centered around a different month, use @kbd{C-u M-x -holidays}, which prompts for the month and year. - - The holidays known to Emacs include United States holidays and the -major Christian, Jewish, and Islamic holidays; also the solstices and -equinoxes. - -@findex list-holidays - The command @kbd{M-x list-holidays} displays the list of holidays for -a range of years. This function asks you for the starting and stopping -years, and allows you to choose all the holidays or one of several -categories of holidays. You can use this command even if you don't have -a calendar window. - - The dates used by Emacs for holidays are based on @emph{current -practice}, not historical fact. For example Veteran's Day began in -1919, but is shown in earlier years. - -@node Sunrise/Sunset -@section Times of Sunrise and Sunset -@cindex sunrise and sunset - - Special calendar commands can tell you, to within a minute or two, the -times of sunrise and sunset for any date. - -@table @kbd -@item S -Display times of sunrise and sunset for the selected date -(@code{calendar-sunrise-sunset}). -@item Mouse-2 Sunrise/sunset -Display times of sunrise and sunset for the date you click on. -@item M-x sunrise-sunset -Display times of sunrise and sunset for today's date. -@item C-u M-x sunrise-sunset -Display times of sunrise and sunset for a specified date. -@end table - -@kindex S @r{(Calendar mode)} -@findex calendar-sunrise-sunset -@findex sunrise-sunset - Within the calendar, to display the @emph{local times} of sunrise and -sunset in the echo area, move point to the date you want, and type -@kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose -@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x -sunrise-sunset} is available outside the calendar to display this -information for today's date or a specified date. To specify a date -other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for -the year, month, and day. - - You can display the times of sunrise and sunset for any location and -any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a -longitude, latitude, number of minutes difference from Coordinated -Universal Time, and date, and then tells you the times of sunrise and -sunset for that location on that date. - - Because the times of sunrise and sunset depend on the location on -earth, you need to tell Emacs your latitude, longitude, and location -name before using these commands. Here is an example of what to set: - -@vindex calendar-location-name -@vindex calendar-longitude -@vindex calendar-latitude -@example -(setq calendar-latitude 40.1) -(setq calendar-longitude -88.2) -(setq calendar-location-name "Urbana, IL") -@end example - -@noindent -Use one decimal place in the values of @code{calendar-latitude} and -@code{calendar-longitude}. - - Your time zone also affects the local time of sunrise and sunset. -Emacs usually gets time zone information from the operating system, but -if these values are not what you want (or if the operating system does -not supply them), you must set them yourself. Here is an example: - -@vindex calendar-time-zone -@vindex calendar-standard-time-zone-name -@vindex calendar-daylight-time-zone-name -@example -(setq calendar-time-zone -360) -(setq calendar-standard-time-zone-name "CST") -(setq calendar-daylight-time-zone-name "CDT") -@end example - -@noindent -The value of @code{calendar-time-zone} is the number of minutes -difference between your local standard time and Coordinated Universal -Time (Greenwich time). The values of -@code{calendar-standard-time-zone-name} and -@code{calendar-daylight-time-zone-name} are the abbreviations used in -your time zone. Emacs displays the times of sunrise and sunset -@emph{corrected for daylight saving time}. @xref{Daylight Saving}, -for how daylight saving time is determined. - - As a user, you might find it convenient to set the calendar location -variables for your usual physical location in your @file{.emacs} file. -And when you install Emacs on a machine, you can create a -@file{default.el} file which sets them properly for the typical location -of most users of that machine. @xref{Init File}. - -@node Lunar Phases -@section Phases of the Moon -@cindex phases of the moon -@cindex moon, phases of - - These calendar commands display the dates and times of the phases of -the moon (new moon, first quarter, full moon, last quarter). This -feature is useful for debugging problems that ``depend on the phase of -the moon.'' - -@table @kbd -@item M -Display the dates and times for all the quarters of the moon for the -three-month period shown (@code{calendar-phases-of-moon}). -@item M-x phases-of-moon -Display dates and times of the quarters of the moon for three months around -today's date. -@end table - -@kindex M @r{(Calendar mode)} -@findex calendar-phases-of-moon - Within the calendar, use the @kbd{M} command to display a separate -buffer of the phases of the moon for the current three-month range. The -dates and times listed are accurate to within a few minutes. - -@findex phases-of-moon - Outside the calendar, use the command @kbd{M-x phases-of-moon} to -display the list of the phases of the moon for the current month and the -preceding and succeeding months. For information about a different -month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and -year. - - The dates and times given for the phases of the moon are given in -local time (corrected for daylight saving, when appropriate); but if -the variable @code{calendar-time-zone} is void, Coordinated Universal -Time (the Greenwich time zone) is used. @xref{Daylight Saving}. - -@node Other Calendars -@section Conversion To and From Other Calendars - -@cindex Gregorian calendar - The Emacs calendar displayed is @emph{always} the Gregorian calendar, -sometimes called the ``new style'' calendar, which is used in most of -the world today. However, this calendar did not exist before the -sixteenth century and was not widely used before the eighteenth century; -it did not fully displace the Julian calendar and gain universal -acceptance until the early twentieth century. The Emacs calendar can -display any month since January, year 1 of the current era, but the -calendar displayed is the Gregorian, even for a date at which the -Gregorian calendar did not exist. - - While Emacs cannot display other calendars, it can convert dates to -and from several other calendars. - -@menu -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. -@end menu - -@node Calendar Systems -@subsection Supported Calendar Systems - -@cindex ISO commercial calendar - The ISO commercial calendar is used largely in Europe. - -@cindex Julian calendar - The Julian calendar, named after Julius Caesar, was the one used in Europe -throughout medieval times, and in many countries up until the nineteenth -century. - -@cindex Julian day numbers -@cindex astronomical day numbers - Astronomers use a simple counting of days elapsed since noon, Monday, -January 1, 4713 B.C. on the Julian calendar. The number of days elapsed -is called the @dfn{Julian day number} or the @dfn{Astronomical day number}. - -@cindex Hebrew calendar - The Hebrew calendar is used by tradition in the Jewish religion. The -Emacs calendar program uses the Hebrew calendar to determine the dates -of Jewish holidays. Hebrew calendar dates begin and end at sunset. - -@cindex Islamic calendar - The Islamic calendar is used in many predominantly Islamic countries. -Emacs uses it to determine the dates of Islamic holidays. There is no -universal agreement in the Islamic world about the calendar; Emacs uses -a widely accepted version, but the precise dates of Islamic holidays -often depend on proclamation by religious authorities, not on -calculations. As a consequence, the actual dates of observance can vary -slightly from the dates computed by Emacs. Islamic calendar dates begin -and end at sunset. - -@cindex French Revolutionary calendar - The French Revolutionary calendar was created by the Jacobins after the 1789 -revolution, to represent a more secular and nature-based view of the annual -cycle, and to install a 10-day week in a rationalization measure similar to -the metric system. The French government officially abandoned this -calendar at the end of 1805. - -@cindex Mayan calendar - The Maya of Central America used three separate, overlapping calendar -systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}. -Emacs knows about all three of these calendars. Experts dispute the -exact correlation between the Mayan calendar and our calendar; Emacs uses the -Goodman-Martinez-Thompson correlation in its calculations. - -@cindex Coptic calendar -@cindex Ethiopic calendar - The Copts use a calendar based on the ancient Egyptian solar calendar. -Their calendar consists of twelve 30-day months followed by an extra -five-day period. Once every fourth year they add a leap day to this -extra period to make it six days. The Ethiopic calendar is identical in -structure, but has different year numbers and month names. - -@cindex Persian calendar - The Persians use a solar calendar based on a design of Omar Khayyam. -Their calendar consists of twelve months of which the first six have 31 -days, the next five have 30 days, and the last has 29 in ordinary years -and 30 in leap years. Leap years occur in a complicated pattern every -four or five years. -The calendar implemented here is the arithmetical Persian calendar -championed by Birashk, based on a 2,820-year cycle. It differs from -the astronomical Persian calendar, which is based on astronomical -events. As of this writing the first future discrepancy is projected -to occur on March 20, 2025. It is currently not clear what the -official calendar of Iran will be that far into the future. - -@cindex Chinese calendar - The Chinese calendar is a complicated system of lunar months arranged -into solar years. The years go in cycles of sixty, each year containing -either twelve months in an ordinary year or thirteen months in a leap -year; each month has either 29 or 30 days. Years, ordinary months, and -days are named by combining one of ten ``celestial stems'' with one of -twelve ``terrestrial branches'' for a total of sixty names that are -repeated in a cycle of sixty. - -@node To Other Calendar -@subsection Converting To Other Calendars - - The following commands describe the selected date (the date at point) -in various other calendar systems: - -@table @kbd -@item Mouse-2 Other calendars -Display the date that you click on, expressed in various other calendars. -@kindex p @r{(Calendar mode)} -@findex calendar-print-iso-date -@item p c -Display ISO commercial calendar equivalent for selected day -(@code{calendar-print-iso-date}). -@findex calendar-print-julian-date -@item p j -Display Julian date for selected day (@code{calendar-print-julian-date}). -@findex calendar-print-astro-day-number -@item p a -Display astronomical (Julian) day number for selected day -(@code{calendar-print-astro-day-number}). -@findex calendar-print-hebrew-date -@item p h -Display Hebrew date for selected day (@code{calendar-print-hebrew-date}). -@findex calendar-print-islamic-date -@item p i -Display Islamic date for selected day (@code{calendar-print-islamic-date}). -@findex calendar-print-french-date -@item p f -Display French Revolutionary date for selected day -(@code{calendar-print-french-date}). -@findex calendar-print-chinese-date -@item p C -Display Chinese date for selected day -(@code{calendar-print-chinese-date}). -@findex calendar-print-coptic-date -@item p k -Display Coptic date for selected day -(@code{calendar-print-coptic-date}). -@findex calendar-print-ethiopic-date -@item p e -Display Ethiopic date for selected day -(@code{calendar-print-ethiopic-date}). -@findex calendar-print-persian-date -@item p p -Display Persian date for selected day -(@code{calendar-print-persian-date}). -@findex calendar-print-mayan-date -@item p m -Display Mayan date for selected day (@code{calendar-print-mayan-date}). -@end table - - If you are using X, the easiest way to translate a date into other -calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other -calendars} from the menu that appears. This displays the equivalent -forms of the date in all the calendars Emacs understands, in the form of -a menu. (Choosing an alternative from this menu doesn't actually do -anything---the menu is used only for display.) - - Otherwise, move point to the date you want to convert, then type the -appropriate command starting with @kbd{p} from the table above. The -prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the -equivalent date in the echo area. - -@node From Other Calendar -@subsection Converting From Other Calendars - - You can use the other supported calendars to specify a date to move -to. This section describes the commands for doing this using calendars -other than Mayan; for the Mayan calendar, see the following section. - -@kindex g @var{char} @r{(Calendar mode)} -@findex calendar-goto-iso-date -@findex calendar-goto-iso-week -@findex calendar-goto-julian-date -@findex calendar-goto-astro-day-number -@findex calendar-goto-hebrew-date -@findex calendar-goto-islamic-date -@findex calendar-goto-french-date -@findex calendar-goto-chinese-date -@findex calendar-goto-persian-date -@findex calendar-goto-coptic-date -@findex calendar-goto-ethiopic-date -@table @kbd -@item g c -Move to a date specified in the ISO commercial calendar -(@code{calendar-goto-iso-date}). -@item g w -Move to a week specified in the ISO commercial calendar -(@code{calendar-goto-iso-week}). -@item g j -Move to a date specified in the Julian calendar -(@code{calendar-goto-julian-date}). -@item g a -Move to a date specified with an astronomical (Julian) day number -(@code{calendar-goto-astro-day-number}). -@item g h -Move to a date specified in the Hebrew calendar -(@code{calendar-goto-hebrew-date}). -@item g i -Move to a date specified in the Islamic calendar -(@code{calendar-goto-islamic-date}). -@item g f -Move to a date specified in the French Revolutionary calendar -(@code{calendar-goto-french-date}). -@item g C -Move to a date specified in the Chinese calendar -(@code{calendar-goto-chinese-date}). -@item g p -Move to a date specified in the Persian calendar -(@code{calendar-goto-persian-date}). -@item g k -Move to a date specified in the Coptic calendar -(@code{calendar-goto-coptic-date}). -@item g e -Move to a date specified in the Ethiopic calendar -(@code{calendar-goto-ethiopic-date}). -@end table - - These commands ask you for a date on the other calendar, move point to -the Gregorian calendar date equivalent to that date, and display the -other calendar's date in the echo area. Emacs uses strict completion -(@pxref{Completion}) whenever it asks you to type a month name, so you -don't have to worry about the spelling of Hebrew, Islamic, or French names. - -@findex list-yahrzeit-dates -@cindex yahrzeits - One common question concerning the Hebrew calendar is the computation -of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs -calendar includes a facility for such calculations. If you are in the -calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a -range of years and then displays a list of the yahrzeit dates for those -years for the date given by point. If you are not in the calendar, -this command first asks you for the date of death and the range of -years, and then displays the list of yahrzeit dates. - -@node Mayan Calendar -@subsection Converting from the Mayan Calendar - - Here are the commands to select dates based on the Mayan calendar: - -@table @kbd -@item g m l -Move to a date specified by the long count calendar -(@code{calendar-goto-mayan-long-count-date}). -@item g m n t -Move to the next occurrence of a place in the -tzolkin calendar (@code{calendar-next-tzolkin-date}). -@item g m p t -Move to the previous occurrence of a place in the -tzolkin calendar (@code{calendar-previous-tzolkin-date}). -@item g m n h -Move to the next occurrence of a place in the -haab calendar (@code{calendar-next-haab-date}). -@item g m p h -Move to the previous occurrence of a place in the -haab calendar (@code{calendar-previous-haab-date}). -@item g m n c -Move to the next occurrence of a place in the -calendar round (@code{calendar-next-calendar-round-date}). -@item g m p c -Move to the previous occurrence of a place in the -calendar round (@code{calendar-previous-calendar-round-date}). -@end table - -@cindex Mayan long count - To understand these commands, you need to understand the Mayan calendars. -The @dfn{long count} is a counting of days with these units: - -@display -1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal -1 katun = 20 tun@ @ @ 1 baktun = 20 katun -@end display - -@kindex g m @r{(Calendar mode)} -@findex calendar-goto-mayan-long-count-date -@noindent -Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 -tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long -count dates as early as 7.17.18.13.3, but no earlier. When you use the -@kbd{g m l} command, type the Mayan long count date with the baktun, -katun, tun, uinal, and kin separated by periods. - -@findex calendar-previous-tzolkin-date -@findex calendar-next-tzolkin-date -@cindex Mayan tzolkin calendar - The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of -independent cycles of 13 and 20 days. Since this cycle repeats -endlessly, Emacs provides commands to move backward and forward to the -previous or next point in the cycle. Type @kbd{g m p t} to go to the -previous tzolkin date; Emacs asks you for a tzolkin date and moves point -to the previous occurrence of that date. Similarly, type @kbd{g m n t} -to go to the next occurrence of a tzolkin date. - -@findex calendar-previous-haab-date -@findex calendar-next-haab-date -@cindex Mayan haab calendar - The Mayan haab calendar is a cycle of 365 days arranged as 18 months -of 20 days each, followed a 5-day monthless period. Like the tzolkin -cycle, this cycle repeats endlessly, and there are commands to move -backward and forward to the previous or next point in the cycle. Type -@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab -date and moves point to the previous occurrence of that date. -Similarly, type @kbd{g m n h} to go to the next occurrence of a haab -date. - -@c This is omitted because it is too long for smallbook format. -@c @findex calendar-previous-calendar-round-date -@findex calendar-next-calendar-round-date -@cindex Mayan calendar round - The Maya also used the combination of the tzolkin date and the haab -date. This combination is a cycle of about 52 years called a -@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for -both a haab and a tzolkin date and then moves point to the previous -occurrence of that combination. Use @kbd{g m n c} to move point to the -next occurrence of a combination. These commands signal an error if the -haab/tzolkin date combination you have typed is impossible. - - Emacs uses strict completion (@pxref{Strict Completion}) whenever it -asks you to type a Mayan name, so you don't have to worry about -spelling. - -@node Diary -@section The Diary -@cindex diary - - The Emacs diary keeps track of appointments or other events on a daily -basis, in conjunction with the calendar. To use the diary feature, you -must first create a @dfn{diary file} containing a list of events and -their dates. Then Emacs can automatically pick out and display the -events for today, for the immediate future, or for any specified -date. - - The name of the diary file is specified by the variable -@code{diary-file}; @file{~/diary} is the default. A sample diary file -is (note that the file format is essentially the same as that used by -the external shell utility @samp{calendar}): - -@example -12/22/1988 Twentieth wedding anniversary!! -&1/1. Happy New Year! -10/22 Ruth's birthday. -* 21, *: Payday -Tuesday--weekly meeting with grad students at 10am - Supowit, Shen, Bitner, and Kapoor to attend. -1/13/89 Friday the thirteenth!! -&thu 4pm squash game with Lloyd. -mar 16 Dad's birthday -April 15, 1989 Income tax due. -&* 15 time cards due. -@end example - -@noindent -This example uses extra spaces to align the event descriptions of most -of the entries. Such formatting is purely a matter of taste. - - Although you probably will start by creating a diary manually, Emacs -provides a number of commands to let you view, add, and change diary -entries. - -@menu -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. -@end menu - -@node Displaying the Diary -@subsection Displaying the Diary - - Once you have created a diary file, you can use the calendar to view -it. You can also view today's events outside of Calendar mode. - -@table @kbd -@item d -Display all diary entries for the selected date -(@code{diary-view-entries}). -@item Mouse-2 Diary -Display all diary entries for the date you click on. -@item s -Display the entire diary file (@code{diary-show-all-entries}). -@item m -Mark all visible dates that have diary entries -(@code{mark-diary-entries}). -@item u -Unmark the calendar window (@code{calendar-unmark}). -@item M-x print-diary-entries -Print hard copy of the diary display as it appears. -@item M-x diary -Display all diary entries for today's date. -@item M-x diary-mail-entries -Mail yourself email reminders about upcoming diary entries. -@end table - -@kindex d @r{(Calendar mode)} -@findex diary-view-entries -@vindex view-diary-entries-initially - Displaying the diary entries with @kbd{d} shows in a separate window -the diary entries for the selected date in the calendar. The mode line -of the new window shows the date of the diary entries and any holidays -that fall on that date. If you specify a numeric argument with @kbd{d}, -it shows all the diary entries for that many successive days. Thus, -@kbd{2 d} displays all the entries for the selected date and for the -following day. - - Another way to display the diary entries for a date is to click -@kbd{Mouse-2} on the date, and then choose @kbd{Diary entries} from -the menu that appears. If the variable -@code{view-diary-entries-initially} is non-@code{nil}, creating the -calendar lists the diary entries for the current date (provided the -current date is visible). - -@kindex m @r{(Calendar mode)} -@findex mark-diary-entries -@vindex mark-diary-entries-in-calendar - To get a broader view of which days are mentioned in the diary, use -the @kbd{m} command. This displays the dates that have diary entries in -a different face (or places a @samp{+} after these dates, if display -with multiple faces is not available). -@iftex -@inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing, diary-entry-marker}. -@end ifnottex - The command applies both to the currently visible months and to -other months that subsequently become visible by scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -turns off holiday marks (@pxref{Holidays}). If the variable -@code{mark-diary-entries-in-calendar} is non-@code{nil}, creating or -updating the calendar marks diary dates automatically. - -@kindex s @r{(Calendar mode)} -@findex diary-show-all-entries - To see the full diary file, rather than just some of the entries, use -the @kbd{s} command. - - Display of selected diary entries uses the selective display feature -to hide entries that don't apply. The diary buffer as you see it is -an illusion, so simply printing the buffer does not print what you see -on your screen. There is a special command to print hard copy of the -diary buffer @emph{as it appears}; this command is @kbd{M-x -print-diary-entries}. It sends the data directly to the printer. You -can customize it like @code{lpr-region} (@pxref{Printing}). - -@findex diary - The command @kbd{M-x diary} displays the diary entries for the current -date, independently of the calendar display, and optionally for the next -few days as well; the variable @code{number-of-diary-entries} specifies -how many days to include. -@iftex -@inforef{Diary Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Diary Customizing, number-of-diary-entries}. -@end ifnottex - - If you put @code{(diary)} in your @file{.emacs} file, this -automatically displays a window with the day's diary entries, when you -enter Emacs. The mode line of the displayed window shows the date and -any holidays that fall on that date. - -@findex diary-mail-entries -@vindex diary-mail-days - Many users like to receive notice of events in their diary as email. -To send such mail to yourself, use the command @kbd{M-x -diary-mail-entries}. A prefix argument specifies how many days -(starting with today) to check; otherwise, the variable -@code{diary-mail-days} says how many days. - -@node Format of Diary File -@subsection The Diary File -@cindex diary file - -@vindex diary-file - Your @dfn{diary file} is a file that records events associated with -particular dates. The name of the diary file is specified by the -variable @code{diary-file}; @file{~/diary} is the default. The -@code{calendar} utility program supports a subset of the format allowed -by the Emacs diary facilities, so you can use that utility to view the -diary file, with reasonable results aside from the entries it cannot -understand. - - Each entry in the diary file describes one event and consists of one -or more lines. An entry always begins with a date specification at the -left margin. The rest of the entry is simply text to describe the -event. If the entry has more than one line, then the lines after the -first must begin with whitespace to indicate they continue a previous -entry. Lines that do not begin with valid dates and do not continue a -preceding entry are ignored. - - You can inhibit the marking of certain diary entries in the calendar -window; to do this, insert an ampersand (@samp{&}) at the beginning of -the entry, before the date. This has no effect on display of the entry -in the diary window; it affects only marks on dates in the calendar -window. Nonmarking entries are especially useful for generic entries -that would otherwise mark many different dates. - - If the first line of a diary entry consists only of the date or day -name with no following blanks or punctuation, then the diary window -display doesn't include that line; only the continuation lines appear. -For example, this entry: - -@example -02/11/1989 - Bill B. visits Princeton today - 2pm Cognitive Studies Committee meeting - 2:30-5:30 Liz at Lawrenceville - 4:00pm Dentist appt - 7:30pm Dinner at George's - 8:00-10:00pm concert -@end example - -@noindent -appears in the diary window without the date line at the beginning. -This style of entry looks neater when you display just a single day's -entries, but can cause confusion if you ask for more than one day's -entries. - - You can edit the diary entries as they appear in the window, but it is -important to remember that the buffer displayed contains the @emph{entire} -diary file, with portions of it concealed from view. This means, for -instance, that the @kbd{C-f} (@code{forward-char}) command can put point -at what appears to be the end of the line, but what is in reality the -middle of some concealed line. - - @emph{Be careful when editing the diary entries!} Inserting -additional lines or adding/deleting characters in the middle of a -visible line cannot cause problems, but editing at the end of a line may -not do what you expect. Deleting a line may delete other invisible -entries that follow it. Before editing the diary, it is best to display -the entire file with @kbd{s} (@code{diary-show-all-entries}). - -@node Date Formats -@subsection Date Formats - - Here are some sample diary entries, illustrating different ways of -formatting a date. The examples all show dates in American order -(month, day, year), but Calendar mode supports European order (day, -month, year) as an option. - -@example -4/20/93 Switch-over to new tabulation system -apr. 25 Start tabulating annual results -4/30 Results for April are due -*/25 Monthly cycle finishes -Friday Don't leave without backing up files -@end example - - The first entry appears only once, on April 20, 1993. The second and -third appear every year on the specified dates, and the fourth uses a -wildcard (asterisk) for the month, so it appears on the 25th of every -month. The final entry appears every week on Friday. - - You can use just numbers to express a date, as in -@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}. -This must be followed by a nondigit. In the date itself, @var{month} -and @var{day} are numbers of one or two digits. The optional @var{year} -is also a number, and may be abbreviated to the last two digits; that -is, you can use @samp{11/12/1989} or @samp{11/12/89}. - - Dates can also have the form @samp{@var{monthname} @var{day}} or -@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can -be spelled in full or abbreviated (with or without a period). The -preferred abbreviations can be controlled using the variables -@code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and -@code{calendar-day-abbrev-array}. The default is to use the first three -letters of a name as its abbreviation. Case is not significant. - - A date may be @dfn{generic}; that is, partially unspecified. Then the -entry applies to all dates that match the specification. If the date -does not contain a year, it is generic and applies to any year. -Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*}; -this matches any month, day, or year, respectively. Thus, a diary entry -@samp{3/*/*} matches any day in March of any year; so does @samp{march -*}. - -@vindex european-calendar-style -@findex european-calendar -@findex american-calendar - If you prefer the European style of writing dates---in which the day -comes before the month---type @kbd{M-x european-calendar} while in the -calendar, or set the variable @code{european-calendar-style} to @code{t} -with @kbd{M-x customize}, or @emph{before} using any calendar or diary -command. This mode interprets all dates in the diary in the European -manner, and also uses European style for displaying diary dates. (Note -that there is no comma after the @var{monthname} in the European style.) -To go back to the (default) American style of writing dates, type -@kbd{M-x american-calendar}. - - You can use the name of a day of the week as a generic date which -applies to any date falling on that day of the week. You can abbreviate -the day of the week to three letters (with or without a period) or spell -it in full; case is not significant. - -@node Adding to Diary -@subsection Commands to Add to the Diary - - While in the calendar, there are several commands to create diary -entries: - -@table @kbd -@item i d -Add a diary entry for the selected date (@code{insert-diary-entry}). -@item i w -Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}). -@item i m -Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}). -@item i y -Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}). -@end table - -@kindex i d @r{(Calendar mode)} -@findex insert-diary-entry - You can make a diary entry for a specific date by selecting that date -in the calendar window and typing the @kbd{i d} command. This command -displays the end of your diary file in another window and inserts the -date; you can then type the rest of the diary entry. - -@kindex i w @r{(Calendar mode)} -@findex insert-weekly-diary-entry -@kindex i m @r{(Calendar mode)} -@findex insert-monthly-diary-entry -@kindex i y @r{(Calendar mode)} -@findex insert-yearly-diary-entry - If you want to make a diary entry that applies to a specific day of -the week, select that day of the week (any occurrence will do) and type -@kbd{i w}. This inserts the day-of-week as a generic date; you can then -type the rest of the diary entry. You can make a monthly diary entry in -the same fashion: select the day of the month, use the @kbd{i m} -command, and type the rest of the entry. Similarly, you can insert a -yearly diary entry with the @kbd{i y} command. - - All of the above commands make marking diary entries by default. To -make a nonmarking diary entry, give a numeric argument to the command. -For example, @kbd{C-u i w} makes a nonmarking weekly diary entry. - - When you modify the diary file, be sure to save the file before -exiting Emacs. Saving the diary file after using any of the above -insertion commands will automatically update the diary marks in the -calendar window, if appropriate. You can use the command -@code{redraw-calendar} to force an update at any time. - -@node Special Diary Entries -@subsection Special Diary Entries - - In addition to entries based on calendar dates, the diary file can -contain @dfn{sexp entries} for regular events such as anniversaries. -These entries are based on Lisp expressions (sexps) that Emacs evaluates -as it scans the diary file. Instead of a date, a sexp entry contains -@samp{%%} followed by a Lisp expression which must begin and end with -parentheses. The Lisp expression determines which dates the entry -applies to. - - Calendar mode provides commands to insert certain commonly used -sexp entries: - -@table @kbd -@item i a -Add an anniversary diary entry for the selected date -(@code{insert-anniversary-diary-entry}). -@item i b -Add a block diary entry for the current region -(@code{insert-block-diary-entry}). -@item i c -Add a cyclic diary entry starting at the date -(@code{insert-cyclic-diary-entry}). -@end table - -@kindex i a @r{(Calendar mode)} -@findex insert-anniversary-diary-entry - If you want to make a diary entry that applies to the anniversary of a -specific date, move point to that date and use the @kbd{i a} command. -This displays the end of your diary file in another window and inserts -the anniversary description; you can then type the rest of the diary -entry. The entry looks like this: - -@findex diary-anniversary -@example -%%(diary-anniversary 10 31 1948) Arthur's birthday -@end example - -@noindent -This entry applies to October 31 in any year after 1948; @samp{10 31 -1948} specifies the date. (If you are using the European calendar -style, the month and day are interchanged.) The reason this expression -requires a beginning year is that advanced diary functions can use it to -calculate the number of elapsed years. - - A @dfn{block} diary entry applies to a specified range of consecutive -dates. Here is a block diary entry that applies to all dates from June -24, 1990 through July 10, 1990: - -@findex diary-block -@example -%%(diary-block 6 24 1990 7 10 1990) Vacation -@end example - -@noindent -The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990} -indicates the stopping date. (Again, if you are using the European calendar -style, the month and day are interchanged.) - -@kindex i b @r{(Calendar mode)} -@findex insert-block-diary-entry - To insert a block entry, place point and the mark on the two -dates that begin and end the range, and type @kbd{i b}. This command -displays the end of your diary file in another window and inserts the -block description; you can then type the diary entry. - -@kindex i c @r{(Calendar mode)} -@findex insert-cyclic-diary-entry - @dfn{Cyclic} diary entries repeat after a fixed interval of days. To -create one, select the starting date and use the @kbd{i c} command. The -command prompts for the length of interval, then inserts the entry, -which looks like this: - -@findex diary-cyclic -@example -%%(diary-cyclic 50 3 1 1990) Renew medication -@end example - -@noindent -This entry applies to March 1, 1990 and every 50th day following; -@samp{3 1 1990} specifies the starting date. (If you are using the -European calendar style, the month and day are interchanged.) - - All three of these commands make marking diary entries. To insert a -nonmarking entry, give a numeric argument to the command. For example, -@kbd{C-u i a} makes a nonmarking anniversary diary entry. - - Marking sexp diary entries in the calendar is @emph{extremely} -time-consuming, since every date visible in the calendar window must be -individually checked. So it's a good idea to make sexp diary entries -nonmarking (with @samp{&}) when possible. - - Another sophisticated kind of sexp entry, a @dfn{floating} diary entry, -specifies a regularly occurring event by offsets specified in days, -weeks, and months. It is comparable to a crontab entry interpreted by -the @code{cron} utility. Here is a nonmarking, floating diary entry -that applies to the last Thursday in November: - -@findex diary-float -@example -&%%(diary-float 11 4 -1) American Thanksgiving -@end example - -@noindent -The 11 specifies November (the eleventh month), the 4 specifies Thursday -(the fourth day of the week, where Sunday is numbered zero), and the -@minus{}1 specifies ``last'' (1 would mean ``first,'' 2 would mean -``second,'' @minus{}2 would mean ``second-to-last,'' and so on). The -month can be a single month or a list of months. Thus you could change -the 11 above to @samp{'(1 2 3)} and have the entry apply to the last -Thursday of January, February, and March. If the month is @code{t}, the -entry applies to all months of the year.@refill - - Each of the standard sexp diary entries takes an optional parameter -specifying the name of a face or a single-character string to use when -marking the entry in the calendar. Most generally, sexp diary entries -can perform arbitrary computations to determine when they apply. -@iftex -@inforef{Sexp Diary Entries,, emacs-xtra}. -@end iftex -@ifnottex -@inforef{Sexp Diary Entries}. -@end ifnottex - -@node Appointments -@section Appointments -@cindex appointment notification - -@vindex appt-display-format -@vindex appt-audible -@vindex appt-display-mode-line - If you have a diary entry for an appointment, and that diary entry -begins with a recognizable time of day, Emacs can warn you several -minutes beforehand that that appointment is pending. Emacs alerts you -to the appointment by displaying a message in your chosen format, as -specified by the variable @code{appt-display-format}. If the value of -@code{appt-audible} is non-@code{nil}, the warning includes an audible -reminder. In addition, if @code{appt-display-mode-line} is -non-@code{nil}, Emacs displays the number of minutes to the -appointment on the mode line. - -@vindex appt-display-duration -@vindex appt-disp-window-function -@vindex appt-delete-window-function - If @code{appt-display-format} has the value @code{window}, then the -variable @code{appt-display-duration} controls how long the reminder -window is visible for; and the variables -@code{appt-disp-window-function} and @code{appt-delete-window-function} -give the names of functions used to create and destroy the window, -respectively. - -@findex appt-activate - To enable appointment notification, use the command @kbd{M-x -appt-activate}. With a positive argument, it enables notification; -with a negative argument, it disables notification; with no argument, -it toggles. Enabling notification also sets up an appointment list -for today from the diary file, giving all diary entries found with -recognizable times of day, and reminds you just before each of them. - - For example, suppose the diary file contains these lines: - -@example -Monday - 9:30am Coffee break - 12:00pm Lunch -@end example - -@vindex appt-message-warning-time -@noindent -Then on Mondays, you will be reminded at around 9:20am about your -coffee break and at around 11:50am about lunch. The variable -@code{appt-message-warning-time} specifies how many minutes in advance -to warn you; its default value is 12 (12 minutes). - - You can write times in am/pm style (with @samp{12:00am} standing -for midnight and @samp{12:00pm} standing for noon), or 24-hour -European/military style. You need not be consistent; your diary file -can have a mixture of the two styles. Times must be at the beginning -of lines if they are to be recognized. - -@vindex appt-display-diary - Emacs updates the appointments list from the diary file -automatically just after midnight. You can force an update at any -time by re-enabling appointment notification. Both these actions also -display the day's diary buffer, unless you set -@code{appt-display-diary} to @code{nil}. The appointments list is -also updated whenever the diary file is saved. - -@findex appt-add -@findex appt-delete -@cindex alarm clock - You can also use the appointment notification facility like an alarm -clock. The command @kbd{M-x appt-add} adds entries to the appointment -list without affecting your diary file. You delete entries from the -appointment list with @kbd{M-x appt-delete}. - -@node Importing Diary -@section Importing and Exporting Diary Entries - - You can transfer diary entries between Emacs diary files and a -variety of other formats. - -@vindex diary-outlook-formats - You can import diary entries from Outlook-generated appointment -messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x -diary-from-outlook} to import the entry. You can make this command -recognize additional appointment message formats by customizing the -variable @code{diary-outlook-formats}. - -@cindex iCalendar support - The icalendar package allows you to transfer data between your Emacs -diary file and iCalendar files, which are defined in ``RFC -2445---Internet Calendaring and Scheduling Core Object Specification -(iCalendar)'' (as well as the earlier vCalendar format). - - Importing works for ``ordinary'' (i.e. non-recurring) events, but -(at present) may not work correctly (if at all) for recurring events. -Exporting of diary files into iCalendar files should work correctly -for most diary entries. This feature is a work in progress, so the -commands may evolve in future. - -@findex icalendar-import-buffer - The command @code{icalendar-import-buffer} extracts -iCalendar data from the current buffer and adds it to your (default) -diary file. This function is also suitable for automatic extraction of -iCalendar data; for example with the Rmail mail client one could use: - -@example -(add-hook 'rmail-show-message-hook 'icalendar-import-buffer) -@end example - -@findex icalendar-import-file - The command @code{icalendar-import-file} imports an iCalendar file -and adds the results to an Emacs diary file. For example: - -@example -(icalendar-import-file "/here/is/calendar.ics" - "/there/goes/ical-diary") -@end example - -@noindent -You can use an @code{#include} directive to add the import file contents -to the main diary file, if these are different files. -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display}. -@end ifnottex - - -@findex icalendar-export-file, icalendar-export-region - Use @code{icalendar-export-file} to interactively export an entire -Emacs diary file to iCalendar format. To export only a part of a diary -file, mark the relevant area, and call @code{icalendar-export-region}. -In both cases the result is appended to the target file. - -@node Daylight Saving -@section Daylight Saving Time -@cindex daylight saving time - - Emacs understands the difference between standard time and daylight -saving time---the times given for sunrise, sunset, solstices, -equinoxes, and the phases of the moon take that into account. The rules -for daylight saving time vary from place to place and have also varied -historically from year to year. To do the job properly, Emacs needs to -know which rules to use. - -@vindex calendar-daylight-savings-starts -@vindex calendar-daylight-savings-ends - Some operating systems keep track of the rules that apply to the place -where you are; on these systems, Emacs gets the information it needs -from the system automatically. If some or all of this information is -missing, Emacs fills in the gaps with the rules currently used in -Cambridge, Massachusetts. If the resulting rules are not what you want, -you can tell Emacs the rules to use by setting certain variables: -@code{calendar-daylight-savings-starts} and -@code{calendar-daylight-savings-ends}. - - These values should be Lisp expressions that refer to the variable -@code{year}, and evaluate to the Gregorian date on which daylight -saving time starts or (respectively) ends, in the form of a list -@code{(@var{month} @var{day} @var{year})}. The values should be -@code{nil} if your area does not use daylight saving time. - - Emacs uses these expressions to determine the starting date of -daylight saving time for the holiday list and for correcting times of -day in the solar and lunar calculations. - - The values for Cambridge, Massachusetts are as follows: - -@example -(calendar-nth-named-day 2 0 3 year) -(calendar-nth-named-day 1 0 11 year) -@end example - -@noindent -That is, the second 0th day (Sunday) of the third month (March) in -the year specified by @code{year}, and the first Sunday of the eleventh month -(November) of that year. If daylight saving time were -changed to start on October 1, you would set -@code{calendar-daylight-savings-starts} to this: - -@example -(list 10 1 year) -@end example - - If there is no daylight saving time at your location, or if you want -all times in standard time, set @code{calendar-daylight-savings-starts} -and @code{calendar-daylight-savings-ends} to @code{nil}. - -@vindex calendar-daylight-time-offset - The variable @code{calendar-daylight-time-offset} specifies the -difference between daylight saving time and standard time, measured in -minutes. The value for Cambridge, Massachusetts is 60. - -@c @vindex calendar-daylight-savings-starts-time too long! -@vindex calendar-daylight-savings-ends-time - Finally, the two variables -@code{calendar-daylight-savings-starts-time} and -@code{calendar-daylight-savings-ends-time} specify the number of -minutes after midnight local time when the transition to and from -daylight saving time should occur. For Cambridge, Massachusetts both -variables' values are 120. - -@node Time Intervals -@section Summing Time Intervals -@cindex time intervals, summing -@cindex summing time intervals -@cindex timeclock - - The timeclock feature adds up time intervals, so you can (for -instance) keep track of how much time you spend working on particular -projects. - -@findex timeclock-in -@findex timeclock-out -@findex timeclock-change -@findex timeclock-workday-remaining -@findex timeclock-when-to-leave - Use the @kbd{M-x timeclock-in} command when you start working on a -project, and @kbd{M-x timeclock-out} command when you're done. Each -time you do this, it adds one time interval to the record of the -project. You can change to working on a different project with @kbd{M-x -timeclock-change}. - - Once you've collected data from a number of time intervals, you can use -@kbd{M-x timeclock-workday-remaining} to see how much time is left to -work today (assuming a typical average of 8 hours a day), and @kbd{M-x -timeclock-when-to-leave} which will calculate when you're ``done.'' - -@vindex timeclock-modeline-display -@findex timeclock-modeline-display - If you want Emacs to display the amount of time ``left'' of your -workday in the mode line, either customize the -@code{timeclock-modeline-display} variable and set its value to -@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. - -@vindex timeclock-ask-before-exiting - Terminating the current Emacs session might or might not mean that -you have stopped working on the project and, by default, Emacs asks -you. You can, however, set the value of the variable -@code{timeclock-ask-before-exiting} to @code{nil} (via @kbd{M-x -customize}) to avoid the question; then, only an explicit @kbd{M-x -timeclock-out} or @kbd{M-x timeclock-change} will tell Emacs that the -current interval is over. - -@cindex @file{.timelog} file -@vindex timeclock-file -@findex timeclock-reread-log - The timeclock functions work by accumulating the data in a file -called @file{.timelog} in your home directory. You can specify a -different name for this file by customizing the variable -@code{timeclock-file}. If you edit the timeclock file manually, or if -you change the value of any of timeclock's customizable variables, you -should run the command @kbd{M-x timeclock-reread-log} to update the -data in Emacs from the file. - -@ifnottex -@include cal-xtra.texi -@end ifnottex - -@ignore - arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92 -@end ignore diff --git a/man/cc-mode.texi b/man/cc-mode.texi deleted file mode 100644 index 423892d7d30..00000000000 --- a/man/cc-mode.texi +++ /dev/null @@ -1,6998 +0,0 @@ -\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/man/cl.texi b/man/cl.texi deleted file mode 100644 index 676b9edc5ad..00000000000 --- a/man/cl.texi +++ /dev/null @@ -1,5377 +0,0 @@ -\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/man/cmdargs.texi b/man/cmdargs.texi deleted file mode 100644 index 28bad72f0bf..00000000000 --- a/man/cmdargs.texi +++ /dev/null @@ -1,1263 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Emacs Invocation, X Resources, GNU Free Documentation License, Top -@appendix Command Line Arguments for Emacs Invocation -@cindex command line arguments -@cindex arguments (command line) -@cindex options (command line) -@cindex switches (command line) -@cindex startup (command line arguments) -@cindex invocation (command line arguments) - - GNU Emacs supports command line arguments to request various actions -when invoking Emacs. These are for compatibility with other editors and -for sophisticated activities. We don't recommend using them for -ordinary editing. - - Arguments starting with @samp{-} are @dfn{options}, and so is -@samp{+@var{linenum}}. All other arguments specify files to visit. -Emacs visits the specified files while it starts up. The last file -name on your command line becomes the current buffer; the other files -are also visited in other buffers. If there are two files, they are -both displayed; otherwise the last file is displayed along with a -buffer list that shows what other buffers there are. As with most -programs, the special argument @samp{--} says that all subsequent -arguments are file names, not options, even if they start with -@samp{-}. - - Emacs command options can specify many things, such as the size and -position of the X window Emacs uses, its colors, and so on. A few -options support advanced usage, such as running Lisp functions on files -in batch mode. The sections of this chapter describe the available -options, arranged according to their purpose. - - There are two ways of writing options: the short forms that start with -a single @samp{-}, and the long forms that start with @samp{--}. For -example, @samp{-d} is a short form and @samp{--display} is the -corresponding long form. - - The long forms with @samp{--} are easier to remember, but longer to -type. However, you don't have to spell out the whole option name; any -unambiguous abbreviation is enough. When a long option takes an -argument, you can use either a space or an equal sign to separate the -option name and the argument. Thus, you can write either -@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}. -We recommend an equal sign because it makes the relationship clearer, -and the tables below always show an equal sign. - -@cindex initial options (command line) -@cindex action options (command line) -@vindex command-line-args - Most options specify how to initialize Emacs, or set parameters for -the Emacs session. We call them @dfn{initial options}. A few options -specify things to do: for example, load libraries, call functions, or -terminate Emacs. These are called @dfn{action options}. These and file -names together are called @dfn{action arguments}. Emacs processes all -the action arguments in the order they are written. The @file{.emacs} file -can access the values of the action arguments as the elements of a list in -the variable @code{command-line-args}. - - - -@menu -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Resume Arguments:: Specifying arguments when you resume a running Emacs. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. -@end menu - -@node Action Arguments -@appendixsec Action Arguments - - Here is a table of the action arguments and options: - -@table @samp -@item @var{file} -@opindex --file -@itemx --file=@var{file} -@opindex --find-file -@itemx --find-file=@var{file} -@opindex --visit -@itemx --visit=@var{file} -@cindex visiting files, command-line argument -@vindex inhibit-startup-buffer-menu -Visit @var{file} using @code{find-file}. @xref{Visiting}. -If you visit several files at startup in this way, Emacs -also displays a Buffer Menu buffer to show you what files it -has visited. You can inhibit that by setting @code{inhibit-startup-buffer-menu} to @code{t}. - -@item +@var{linenum} @var{file} -@opindex +@var{linenum} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} in it. - -@item +@var{linenum}:@var{columnnum} @var{file} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} and put point at column number @var{columnnum}. - -@need 3000 -@item -l @var{file} -@opindex -l -@itemx --load=@var{file} -@opindex --load -@cindex loading Lisp libraries, command-line argument -Load a Lisp library named @var{file} with the function @code{load}. -@xref{Lisp Libraries}. If @var{file} is not an absolute file name, -the library can be found either in the current directory, or in the -Emacs library search path as specified with @env{EMACSLOADPATH} -(@pxref{General Variables}). - -@strong{Warning:} If previous command-line arguments have visited -files, the current directory is the directory of the last file -visited. - -@item -L @var{dir} -@opindex -L -@itemx --directory=@var{dir} -@opindex --directory -Add directory @var{dir} to the variable @code{load-path}. - -@item -f @var{function} -@opindex -f -@itemx --funcall=@var{function} -@opindex --funcall -@cindex call Lisp functions, command-line argument -Call Lisp function @var{function}. If it is an interactive function -(a command), it reads the arguments interactively just as if you had -called the same function with a key sequence. Otherwise, it calls the -function with no arguments. - -@item --eval=@var{expression} -@opindex --eval -@itemx --execute=@var{expression} -@opindex --execute -@cindex evaluate expression, command-line argument -Evaluate Lisp expression @var{expression}. - -@item --insert=@var{file} -@opindex --insert -@cindex insert file contents, command-line argument -Insert the contents of @var{file} into the current buffer. This is like -what @kbd{M-x insert-file} does. @xref{Misc File Ops}. - -@item --kill -@opindex --kill -Exit from Emacs without asking for confirmation. - -@item --help -@opindex --help -Print a usage message listing all available options, then exit -successfully. - -@item --version -@opindex --version -Print Emacs version, then exit successfully. -@end table - -@node Initial Options -@appendixsec Initial Options - - The initial options specify parameters for the Emacs session. This -section describes the more general initial options; some other options -specifically related to the X Window System appear in the following -sections. - - Some initial options affect the loading of init files. The normal -actions of Emacs are to first load @file{site-start.el} if it exists, -then your own init file @file{~/.emacs} if it exists, and finally -@file{default.el} if it exists. @xref{Init File}. Certain options -prevent loading of some of these files or substitute other files for -them. - -@table @samp -@item -t @var{device} -@opindex -t -@itemx --terminal=@var{device} -@opindex --terminal -@cindex device for Emacs terminal I/O -Use @var{device} as the device for terminal input and output. -@samp{--terminal} implies @samp{--no-window-system}. - -@item -d @var{display} -@opindex -d -@itemx --display=@var{display} -@opindex --display -@cindex display for Emacs frame -Use the X Window System and use the display named @var{display} to open -the initial Emacs frame. @xref{Display X}, for more details. - -@item -nw -@opindex -nw -@itemx --no-window-system -@opindex --no-window-system -@cindex disable window system -Don't communicate directly with the window system, disregarding the -@env{DISPLAY} environment variable even if it is set. This means that -Emacs uses the terminal from which it was launched for all its display -and input. - -@need 3000 -@cindex batch mode -@item -batch -@opindex --batch -@itemx --batch -Run Emacs in @dfn{batch mode}. Batch mode is used for running -programs written in Emacs Lisp from shell scripts, makefiles, and so -on. You should also use the @samp{-l}, @samp{-f} or @samp{--eval} -option, to invoke a Lisp program to do batch processing. - -In batch mode, Emacs does not display the text being edited, and the -standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c} -continue to have their normal effect. The functions @code{prin1}, -@code{princ} and @code{print} output to @code{stdout} instead of the -echo area, while @code{message} and error messages output to -@code{stderr}. Functions that would normally read from the minibuffer -take their input from @code{stdin} instead. - -@samp{--batch} implies @samp{-q} (do not load an init file), but -@file{site-start.el} is loaded nonetheless. It also causes Emacs to -exit after processing all the command options. In addition, it -disables auto-saving except in buffers for which it has been -explicitly requested. - -@item --script @var{file} -@opindex --script -@cindex script mode -Run Emacs in batch mode, like @samp{--batch}, and then read and -execute the Lisp code in @var{file}. - -The normal use of this option is in executable script files that run -Emacs. They can start with this text on the first line - -@example -#!/usr/bin/emacs --script -@end example - -@noindent -which will invoke Emacs with @samp{--script} and supply the name of -the script file as @var{file}. Emacs Lisp then treats @samp{#!} as a -comment delimiter. - -@item -q -@opindex -q -@itemx --no-init-file -@opindex --no-init-file -@cindex bypassing init and @file{default.el} file -@cindex init file, not loading -@cindex @file{default.el} file, not loading -Do not load your Emacs init file @file{~/.emacs}, or @file{default.el} -either. Regardless of this switch, @file{site-start.el} is still loaded. -When invoked like this, Emacs does not allow saving options -changed with the @kbd{M-x customize} command and its variants. -@xref{Easy Customization}. - -@item --no-site-file -@opindex --no-site-file -@cindex @file{site-start.el} file, not loading -Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u} -and @samp{--batch} have no effect on the loading of this file---this -option and @samp{-Q} are the only options that block it. - -@item -Q -@opindex -Q -@itemx --quick -@opindex --quick -Start emacs with minimum customizations. This is like using @samp{-q} -and @samp{--no-site-file}, but also disables the startup screen. - -@item --no-splash -@opindex --no-splash -@vindex inhibit-splash-screen -@cindex splash screen -@cindex startup message -Do not display a splash screen on startup. You can also achieve this -effect by setting the variable @code{inhibit-splash-screen} to -non-@code{nil} in you personal init file (but @emph{not} in -@file{site-start.el}). (This variable was called -@code{inhibit-startup-message} in previous Emacs versions.) - -@item --no-desktop -@opindex --no-desktop -Do not reload any saved desktop. @xref{Saving Emacs Sessions}. - -@item -u @var{user} -@opindex -u -@itemx --user=@var{user} -@opindex --user -@cindex load init file of another user -Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of -your own@footnote{ -This option has no effect on MS-Windows.}. - -@item --debug-init -@opindex --debug-init -@cindex errors in init file -Enable the Emacs Lisp debugger for errors in the init file. -@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The -GNU Emacs Lisp Reference Manual}. - -@item --unibyte -@opindex --unibyte -@itemx --no-multibyte -@opindex --no-multibyte -@cindex unibyte operation, command-line argument -Do almost everything with single-byte buffers and strings. -All buffers and strings are unibyte unless you (or a Lisp program) -explicitly ask for a multibyte buffer or string. (Note that Emacs -always loads Lisp files in multibyte mode, even if @samp{--unibyte} is -specified; see @ref{Enabling Multibyte}.) Setting the environment -variable @env{EMACS_UNIBYTE} has the same effect -(@pxref{General Variables}). - -@item --multibyte -@opindex --multibyte -@itemx --no-unibyte -@opindex --no-unibyte -Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs -uses multibyte characters by default, as usual. -@end table - -@node Command Example -@appendixsec Command Argument Example - - Here is an example of using Emacs with arguments and options. It -assumes you have a Lisp program file called @file{hack-c.el} which, when -loaded, performs some useful operation on the current buffer, expected -to be a C program. - -@example -emacs --batch foo.c -l hack-c -f save-buffer >& log -@end example - -@noindent -This says to visit @file{foo.c}, load @file{hack-c.el} (which makes -changes in the visited file), save @file{foo.c} (note that -@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and -then exit back to the shell (because of @samp{--batch}). @samp{--batch} -also guarantees there will be no problem redirecting output to -@file{log}, because Emacs will not assume that it has a display terminal -to work with. - -@node Resume Arguments -@appendixsec Resuming Emacs with Arguments - - You can specify action arguments for Emacs when you resume it after -a suspension. To prepare for this, put the following code in your -@file{.emacs} file (@pxref{Hooks}): - -@c `resume-suspend-hook' is correct. It is the name of a function. -@example -(add-hook 'suspend-hook 'resume-suspend-hook) -(add-hook 'suspend-resume-hook 'resume-process-args) -@end example - - As further preparation, you must execute the shell script -@file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} -(if you use bash as your shell). These scripts define an alias named -@code{edit}, which will resume Emacs giving it new command line -arguments such as files to visit. The scripts are found in the -@file{etc} subdirectory of the Emacs distribution. - - Only action arguments work properly when you resume Emacs. Initial -arguments are not recognized---it's too late to execute them anyway. - - Note that resuming Emacs (with or without arguments) must be done from -within the shell that is the parent of the Emacs job. This is why -@code{edit} is an alias rather than a program or a shell script. It is -not possible to implement a resumption command that could be run from -other subjobs of the shell; there is no way to define a command that could -be made the value of @env{EDITOR}, for example. Therefore, this feature -does not take the place of the Emacs Server feature (@pxref{Emacs -Server}). - - The aliases use the Emacs Server feature if you appear to have a -server Emacs running. However, they cannot determine this with complete -accuracy. They may think that a server is still running when in -actuality you have killed that Emacs, because the file -@file{/tmp/esrv@dots{}} still exists. If this happens, find that -file and delete it. - -@node Environment -@appendixsec Environment Variables -@cindex environment variables - - The @dfn{environment} is a feature of the operating system; it -consists of a collection of variables with names and values. Each -variable is called an @dfn{environment variable}; environment variable -names are case-sensitive, and it is conventional to use upper case -letters only. The values are all text strings. - - What makes the environment useful is that subprocesses inherit the -environment automatically from their parent process. This means you -can set up an environment variable in your login shell, and all the -programs you run (including Emacs) will automatically see it. -Subprocesses of Emacs (such as shells, compilers, and version-control -software) inherit the environment from Emacs, too. - -@findex setenv -@findex getenv - Inside Emacs, the command @kbd{M-x getenv} gets the value of an -environment variable. @kbd{M-x setenv} sets a variable in the Emacs -environment. (Environment variable substitutions with @samp{$} work -in the value just as in file names; see @ref{File Names with $}.) - - The way to set environment variables outside of Emacs depends on the -operating system, and especially the shell that you are using. For -example, here's how to set the environment variable @env{ORGANIZATION} -to @samp{not very much} using Bash: - -@example -export ORGANIZATION="not very much" -@end example - -@noindent -and here's how to do it in csh or tcsh: - -@example -setenv ORGANIZATION "not very much" -@end example - - When Emacs is using the X Window System, various environment -variables that control X work for Emacs as well. See the X -documentation for more information. - -@menu -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system-specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. -@end menu - -@node General Variables -@appendixsubsec General Variables - - Here is an alphabetical list of specific environment variables that -have special meanings in Emacs, giving the name of each variable and -its meaning. Most of these variables are also used by some other -programs. Emacs does not require any of these environment variables -to be set, but it uses their values if they are set. - -@table @env -@item CDPATH -Used by the @code{cd} command to search for the directory you specify, -when you specify a relative directory name. -@item EMACS_UNIBYTE -@cindex unibyte operation, environment variable -Defining this environment variable with a nonempty value directs Emacs -to do almost everything with single-byte buffers and strings. It is -equivalent to using the @samp{--unibyte} command-line option on each -invocation. @xref{Initial Options}. -@item EMACSDATA -Directory for the architecture-independent files that come with Emacs. -This is used to initialize the Lisp variable @code{data-directory}. -@item EMACSDOC -Directory for the documentation string file, -@file{DOC-@var{emacsversion}}. This is used to initialize the Lisp -variable @code{doc-directory}. -@item EMACSLOADPATH -A colon-separated list of directories@footnote{ -Here and below, whenever we say ``colon-separated list of directories,'' -it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, -the directories are separated by semi-colons instead, since DOS/Windows -file names might include a colon after a drive letter.} -to search for Emacs Lisp files---used to initialize @code{load-path}. -@item EMACSPATH -A colon-separated list of directories to search for executable -files---used to initialize @code{exec-path}. -@item EMAIL -@vindex user-mail-address@r{, initialization} -Your email address; used to initialize the Lisp variable -@code{user-mail-address}, which the Emacs mail interface puts into -the @samp{From} header of outgoing messages (@pxref{Mail Headers}). -@item ESHELL -Used for shell-mode to override the @env{SHELL} environment variable. -@item HISTFILE -The name of the file that shell commands are saved in between logins. -This variable defaults to @file{~/.bash_history} if you use Bash, to -@file{~/.sh_history} if you use ksh, and to @file{~/.history} -otherwise. -@item HOME -The location of your files in the directory tree; used for -expansion of file names starting with a tilde (@file{~}). On MS-DOS, -it defaults to the directory from which Emacs was started, with -@samp{/bin} removed from the end if it was present. On Windows, the -default value of @env{HOME} is the @file{Application Data} -subdirectory of the user profile directory (normally, this is -@file{C:/Documents and Settings/@var{username}/Application Data}, -where @var{username} is your user name), though for backwards -compatibility @file{C:/} will be used instead if a @file{.emacs} file -is found there. -@item HOSTNAME -The name of the machine that Emacs is running on. -@item INCPATH -A colon-separated list of directories. Used by the @code{complete} package -to search for files. -@item INFOPATH -A colon-separated list of directories in which to search for Info files. -@item LC_ALL -@itemx LC_COLLATE -@itemx LC_CTYPE -@itemx LC_MESSAGES -@itemx LC_MONETARY -@itemx LC_NUMERIC -@itemx LC_TIME -@itemx LANG -The user's preferred locale. The locale has six categories, specified -by the environment variables @env{LC_COLLATE} for sorting, -@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system -messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for -numbers, and @env{LC_TIME} for dates and times. If one of these -variables is not set, the category defaults to the value of the -@env{LANG} environment variable, or to the default @samp{C} locale if -@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides -the settings of all the other locale environment variables. - -On MS-Windows, if @env{LANG} is not already set in the environment -when Emacs starts, Emacs sets it based on the system-wide default -language, which you can set in the @samp{Regional Settings} Control Panel -on some versions of MS-Windows. - -The value of the @env{LC_CTYPE} category is -matched against entries in @code{locale-language-names}, -@code{locale-charset-language-names}, and -@code{locale-preferred-coding-systems}, to select a default language -environment and coding system. @xref{Language Environments}. -@item LOGNAME -The user's login name. See also @env{USER}. -@item MAIL -The name of your system mail inbox. -@item MH -Name of setup file for the mh system. (The default is @file{~/.mh_profile}.) -@item NAME -Your real-world name. -@item NNTPSERVER -The name of the news server. Used by the mh and Gnus packages. -@item ORGANIZATION -The name of the organization to which you belong. Used for setting the -`Organization:' header in your posts from the Gnus package. -@item PATH -A colon-separated list of directories in which executables reside. This -is used to initialize the Emacs Lisp variable @code{exec-path}. -@item PWD -If set, this should be the default directory when Emacs was started. -@item REPLYTO -If set, this specifies an initial value for the variable -@code{mail-default-reply-to}. @xref{Mail Headers}. -@item SAVEDIR -The name of a directory in which news articles are saved by default. -Used by the Gnus package. -@item SHELL -The name of an interpreter used to parse and execute programs run from -inside Emacs. -@item SMTPSERVER -The name of the outgoing mail server. Used by the SMTP library -(@pxref{Top,,,smtpmail,Sending mail via SMTP}). -@cindex background mode, on @command{xterm} -@item TERM -The type of the terminal that Emacs is using. This variable must be -set unless Emacs is run in batch mode. On MS-DOS, it defaults to -@samp{internal}, which specifies a built-in terminal emulation that -handles the machine's own display. If the value of @env{TERM} indicates -that Emacs runs in non-windowed mode from @command{xterm} or a similar -terminal emulator, the background mode defaults to @samp{light}, and -Emacs will choose colors that are appropriate for a light background. -@item TERMCAP -The name of the termcap library file describing how to program the -terminal specified by the @env{TERM} variable. This defaults to -@file{/etc/termcap}. -@item TMPDIR -Used by the Emerge package as a prefix for temporary files. -@item TZ -This specifies the current time zone and possibly also daylight -saving time information. On MS-DOS, if @env{TZ} is not set in the -environment when Emacs starts, Emacs defines a default value as -appropriate for the country code returned by DOS. On MS-Windows, Emacs -does not use @env{TZ} at all. -@item USER -The user's login name. See also @env{LOGNAME}. On MS-DOS, this -defaults to @samp{root}. -@item VERSION_CONTROL -Used to initialize the @code{version-control} variable (@pxref{Numbered Backups}). -@end table - -@node Misc Variables -@appendixsubsec Miscellaneous Variables - -These variables are used only on particular configurations: - -@table @env -@item COMSPEC -On MS-DOS and MS-Windows, the name of the command interpreter to use -when invoking batch files and commands internal to the shell. On MS-DOS -this is also used to make a default value for the @env{SHELL} environment -variable. - -@item NAME -On MS-DOS, this variable defaults to the value of the @env{USER} -variable. - -@item TEMP -@itemx TMP -On MS-DOS and MS-Windows, these specify the name of the directory for -storing temporary files in. - -@item EMACSTEST -On MS-DOS, this specifies a file to use to log the operation of the -internal terminal emulator. This feature is useful for submitting bug -reports. - -@item EMACSCOLORS -On MS-DOS, this specifies the screen colors. It is useful to set them -this way, since otherwise Emacs would display the default colors -momentarily when it starts up. - -The value of this variable should be the two-character encoding of the -foreground (the first character) and the background (the second -character) colors of the default face. Each character should be the -hexadecimal code for the desired color on a standard PC text-mode -display. For example, to get blue text on a light gray background, -specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and -7 is the code of the light gray color. - -The PC display usually supports only eight background colors. However, -Emacs switches the DOS display to a mode where all 16 colors can be used -for the background, so all four bits of the background color are -actually used. - -@item WINDOW_GFX -Used when initializing the Sun windows system. - -@item PRELOAD_WINSOCK -On MS-Windows, if you set this variable, Emacs will load and initialize -the network library at startup, instead of waiting until the first -time it is required. - -@item emacs_dir -On MS-Windows, @env{emacs_dir} is a special environment variable, which -indicates the full path of the directory in which Emacs is installed. -If Emacs is installed in the standard directory structure, it -calculates this value automatically. It is not much use setting this -variable yourself unless your installation is non-standard, since -unlike other environment variables, it will be overridden by Emacs at -startup. When setting other environment variables, such as -@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir} -rather than hard-coding an absolute path. This allows multiple -versions of Emacs to share the same environment variable settings, and -it allows you to move the Emacs installation directory, without -changing any environment or registry settings. -@end table - -@node MS-Windows Registry -@appendixsubsec The MS-Windows System Registry -@pindex addpm, MS-Windows installation program -@cindex registry, setting environment variables and resources on MS-Windows - -Under MS-Windows, the installation program @command{addpm.exe} adds -values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA}, -@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the -@file{HKEY_LOCAL_MACHINE} section of the system registry, under -@file{/Software/GNU/Emacs}. It does this because there is no standard -place to set environment variables across different versions of -Windows. Running @command{addpm.exe} is no longer strictly necessary -in recent versions of Emacs, but if you are upgrading from an older -version, running @command{addpm.exe} ensures that you do not have -older registry entries from a previous installation, which may not be -compatible with the latest version of Emacs. - -When Emacs starts, as well as checking the environment, it also checks -the System Registry for those variables and for @env{HOME}, @env{LANG} -and @env{PRELOAD_WINSOCK}. - -To determine the value of those variables, Emacs goes through the -following procedure. First, the environment is checked. If the -variable is not found there, Emacs looks for registry keys by that -name under @file{/Software/GNU/Emacs}; first in the -@file{HKEY_CURRENT_USER} section of the registry, and if not found -there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs -still cannot determine the values, compiled-in defaults are used. - -In addition to the environment variables above, you can also add many -of the settings which on X belong in the @file{.Xdefaults} file -(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key. -Settings you add to the @file{HKEY_LOCAL_MACHINE} section will affect -all users of the machine. Settings you add to the -@file{HKEY_CURRENT_USER} section will only affect you, and will -override machine wide settings. - -@node Display X -@appendixsec Specifying the Display Name -@cindex display name (X Window System) -@cindex @env{DISPLAY} environment variable - - The environment variable @env{DISPLAY} tells all X clients, including -Emacs, where to display their windows. Its value is set by default -in ordinary circumstances, when you start an X server and run jobs -locally. Occasionally you may need to specify the display yourself; for -example, if you do a remote login and want to run a client program -remotely, displaying on your local screen. - - With Emacs, the main reason people change the default display is to -let them log into another system, run Emacs on that system, but have the -window displayed at their local terminal. You might need to log in -to another system because the files you want to edit are there, or -because the Emacs executable file you want to run is there. - - The syntax of the @env{DISPLAY} environment variable is -@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the -host name of the X Window System server machine, @var{display} is an -arbitrarily-assigned number that distinguishes your server (X terminal) -from other servers on the same machine, and @var{screen} is a -rarely-used field that allows an X server to control multiple terminal -screens. The period and the @var{screen} field are optional. If -included, @var{screen} is usually zero. - - For example, if your host is named @samp{glasperle} and your server is -the first (or perhaps the only) server listed in the configuration, your -@env{DISPLAY} is @samp{glasperle:0.0}. - - You can specify the display name explicitly when you run Emacs, either -by changing the @env{DISPLAY} variable, or with the option @samp{-d -@var{display}} or @samp{--display=@var{display}}. Here is an example: - -@smallexample -emacs --display=glasperle:0 & -@end smallexample - - You can inhibit the direct use of the window system and GUI with the -@samp{-nw} option. It tells Emacs to display using ordinary @acronym{ASCII} on -its controlling terminal. This is also an initial option. - - Sometimes, security arrangements prevent a program on a remote system -from displaying on your local system. In this case, trying to run Emacs -produces messages like this: - -@smallexample -Xlib: connection to "glasperle:0.0" refused by server -@end smallexample - -@noindent -You might be able to overcome this problem by using the @command{xhost} -command on the local system to give permission for access from your -remote machine. - -@node Font X -@appendixsec Font Specification Options -@cindex font name (X Window System) - - By default, Emacs displays text in a twelve point Courier font (when -using X). You can specify a different font on your command line -through the option @samp{-fn @var{name}} (or @samp{--font}, which is -an alias for @samp{-fn}). - -@table @samp -@item -fn @var{name} -@opindex -fn -@itemx --font=@var{name} -@opindex --font -@cindex specify default font from the command line -Use font @var{name} as the default font. -@end table - - Under X, each font has a long name which consists of fourteen words -or numbers, separated by dashes. Some fonts also have shorter -nicknames. For instance, @samp{9x15} is such a nickname. This font -makes each character nine pixels wide and fifteen pixels high. You -can use either kind of name. Case is insignificant in both kinds. -You can use wildcard patterns for the font name; then Emacs lets X -choose one of the fonts that match the pattern. The wildcard -character @samp{*} matches any sequence of characters (including none) -and @samp{?} matches any single character. However, matching is -implementation-dependent, and can be inaccurate when wildcards match -dashes in a long name. For reliable results, supply all 14 dashes and -use wildcards only within a field. Here is an example, which happens -to specify the font whose nickname is @samp{6x13}: - -@smallexample -emacs -fn \ - "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" & -@end smallexample - -@noindent -You can also specify the font in your @file{.Xdefaults} file: - -@smallexample -emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end smallexample - - Note that if you use a wildcard pattern on the command line, you -need to enclose it in single or double quotes, to prevent the shell -from accidentally expanding it into a list of file names. On the -other hand, you should not quote the name in the @file{.Xdefaults} -file. - -The default font used by Emacs (under X) is: - -@smallexample --adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1 -@end smallexample - - A long font name has the following form: - -@smallexample --@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} -@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding} -@end smallexample - -@table @var -@item maker -This is the name of the font manufacturer. -@item family -This is the name of the font family---for example, @samp{courier}. -@item weight -This is normally @samp{bold}, @samp{medium} or @samp{light}. Other -words may appear here in some font names. -@item slant -This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique), -@samp{ri} (reverse italic), or @samp{ot} (other). -@item widthtype -This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed} -or @samp{normal}. Other words may appear here in some font names. -@item style -This is an optional additional style name. Usually it is empty---most -long font names have two hyphens in a row at this point. -@item pixels -This is the font height, in pixels. -@item height -This is the font height on the screen, measured in tenths of a printer's -point---approximately 1/720 of an inch. In other words, it is the point -size of the font, times ten. For a given vertical resolution, -@var{height} and @var{pixels} are proportional; therefore, it is common -to specify just one of them and use @samp{*} for the other. -@item horiz -This is the horizontal resolution, in pixels per inch, of the screen for -which the font is intended. -@item vert -This is the vertical resolution, in pixels per inch, of the screen for -which the font is intended. Normally the resolution of the fonts on -your system is the right value for your screen; therefore, you normally -specify @samp{*} for this and @var{horiz}. -@item spacing -This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} -(character cell). -@item width -This is the average character width, in pixels, multiplied by ten. -@item registry -@itemx encoding -These together make up the X font character set that the font depicts. -(X font character sets are not the same as Emacs charsets, but they -are solutions for the same problem.) You can use the -@command{xfontsel} program to check which choices you have. However, -normally you should use @samp{iso8859} for @var{registry} and @samp{1} -for @var{encoding}. -@end table - -@cindex listing system fonts - You will probably want to use a fixed-width default font---that is, -a font in which all characters have the same width. Any font with -@samp{m} or @samp{c} in the @var{spacing} field of the long name is a -fixed-width font. Here's how to use the @command{xlsfonts} program to -list all the fixed-width fonts available on your system: - -@example -xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' -@end example - -@noindent -To see what a particular font looks like, use the @command{xfd} command. -For example: - -@example -xfd -fn 6x13 -@end example - -@noindent -displays the entire font @samp{6x13}. - - While running Emacs, you can set the font of the current frame -(@pxref{Frame Parameters}) or for a specific kind of text -(@pxref{Faces}). - -@node Colors -@appendixsec Window Color Options -@cindex color of window, from command line -@cindex text colors, from command line - -@findex list-colors-display -@cindex available colors - On a color display, you can specify which color to use for various -parts of the Emacs display. To find out what colors are available on -your system, type @kbd{M-x list-colors-display}, or press -@kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu. -(A particular window system might support many more colors, but the -list displayed by @code{list-colors-display} shows their portable -subset that can be safely used on any display supported by Emacs.) -If you do not specify colors, on windowed displays the default for the -background is white and the default for all other colors is black. On a -monochrome display, the foreground is black, the background is white, -and the border is gray if the display supports that. On terminals, the -background is usually black and the foreground is white. - - Here is a list of the command-line options for specifying colors: - -@table @samp -@item -fg @var{color} -@opindex -fg -@itemx --foreground-color=@var{color} -@opindex --foreground-color -@cindex foreground color, command-line argument -Specify the foreground color. @var{color} should be a standard color -name, or a numeric specification of the color's red, green, and blue -components as in @samp{#4682B4} or @samp{RGB:46/82/B4}. -@item -bg @var{color} -@opindex -bg -@itemx --background-color=@var{color} -@opindex --background-color -@cindex background color, command-line argument -Specify the background color. -@item -bd @var{color} -@opindex -bd -@itemx --border-color=@var{color} -@opindex --border-color -@cindex border color, command-line argument -Specify the color of the border of the X window. -@item -cr @var{color} -@opindex -cr -@itemx --cursor-color=@var{color} -@opindex --cursor-color -@cindex cursor color, command-line argument -Specify the color of the Emacs cursor which indicates where point is. -@item -ms @var{color} -@opindex -ms -@itemx --mouse-color=@var{color} -@opindex --mouse-color -@cindex mouse pointer color, command-line argument -Specify the color for the mouse cursor when the mouse is in the Emacs window. -@item -r -@opindex -r -@itemx -rv -@opindex -rv -@itemx --reverse-video -@opindex --reverse-video -@cindex reverse video, command-line argument -Reverse video---swap the foreground and background colors. -@item --color=@var{mode} -@opindex --color -@cindex standard colors on a character terminal -@cindex override character terminal color support -For a character terminal only, specify the mode of color support. -This option is intended for overriding the number of supported colors -that the character terminal advertises in its @code{termcap} or -@code{terminfo} database. The parameter @var{mode} can be one of the -following: -@table @samp -@item never -@itemx no -Don't use colors even if the terminal's capabilities specify color -support. -@item default -@itemx auto -Same as when @option{--color} is not used at all: Emacs detects at -startup whether the terminal supports colors, and if it does, turns on -colored display. -@item always -@itemx yes -@itemx ansi8 -Turn on the color support unconditionally, and use color commands -specified by the ANSI escape sequences for the 8 standard colors. -@item @var{num} -Use color mode for @var{num} colors. If @var{num} is -1, turn off -color support (equivalent to @samp{never}); if it is 0, use the -default color support for this terminal (equivalent to @samp{auto}); -otherwise use an appropriate standard mode for @var{num} colors. -Depending on your terminal's capabilities, Emacs might be able to turn -on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If -there is no mode that supports @var{num} colors, Emacs acts as if -@var{num} were 0, i.e.@: it uses the terminal's default color support -mode. -@end table -If @var{mode} is omitted, it defaults to @var{ansi8}. -@end table - - For example, to use a coral mouse cursor and a slate blue text cursor, -enter: - -@example -emacs -ms coral -cr 'slate blue' & -@end example - - You can reverse the foreground and background colors through the -@samp{-rv} option or with the X resource @samp{reverseVideo}. - - The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on -text-only terminals as well as on graphical displays. - -@node Window Size X -@appendixsec Options for Window Size and Position -@cindex geometry of Emacs window -@cindex position and size of Emacs frame -@cindex width and height of Emacs frame -@cindex specifying fullscreen for Emacs frame - - Here is a list of the command-line options for specifying size and -position of the initial Emacs frame: - -@table @samp -@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex -g -@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex --geometry -@cindex geometry, command-line argument -Specify the size @var{width} and @var{height} (measured in character -columns and lines), and positions @var{xoffset} and @var{yoffset} -(measured in pixels). The @var{width} and @var{height} parameters -apply to all frames, whereas @var{xoffset} and @var{yoffset} only to -the initial frame. - -@item -fs -@opindex -fs -@itemx --fullscreen -@opindex --fullscreen -@cindex fullscreen, command-line argument -Specify that width and height shall be the size of the screen. - -@item -fh -@opindex -fh -@itemx --fullheight -@opindex --fullheight -@cindex fullheight, command-line argument -Specify that the height shall be the height of the screen. - -@item -fw -@opindex -fw -@itemx --fullwidth -@opindex --fullwidth -@cindex fullwidth, command-line argument -Specify that the width shall be the width of the screen. -@end table - - -@noindent -In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus - sign or a minus sign. A plus -sign before @var{xoffset} means it is the distance from the left side of -the screen; a minus sign means it counts from the right side. A plus -sign before @var{yoffset} means it is the distance from the top of the -screen, and a minus sign there indicates the distance from the bottom. -The values @var{xoffset} and @var{yoffset} may themselves be positive or -negative, but that doesn't change their meaning, only their direction. - - Emacs uses the same units as @command{xterm} does to interpret the geometry. -The @var{width} and @var{height} are measured in characters, so a large font -creates a larger frame than a small font. (If you specify a proportional -font, Emacs uses its maximum bounds width as the width unit.) The -@var{xoffset} and @var{yoffset} are measured in pixels. - - You do not have to specify all of the fields in the geometry -specification. If you omit both @var{xoffset} and @var{yoffset}, the -window manager decides where to put the Emacs frame, possibly by -letting you place it with the mouse. For example, @samp{164x55} -specifies a window 164 columns wide, enough for two ordinary width -windows side by side, and 55 lines tall. - - The default width for Emacs is 80 characters and the default height is -40 lines. You can omit either the width or the height or both. If -you start the geometry with an integer, Emacs interprets it as the -width. If you start with an @samp{x} followed by an integer, Emacs -interprets it as the height. Thus, @samp{81} specifies just the width; -@samp{x45} specifies just the height. - - If you start with @samp{+} or @samp{-}, that introduces an offset, -which means both sizes are omitted. Thus, @samp{-3} specifies the -@var{xoffset} only. (If you give just one offset, it is always -@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the -@var{yoffset}, placing the frame near the bottom left of the screen. - - You can specify a default for any or all of the fields in -@file{.Xdefaults} file, and then override selected fields with a -@samp{--geometry} option. - - Since the mode line and the echo area occupy the last 2 lines of the -frame, the height of the initial text window is 2 less than the height -specified in your geometry. In non-X-toolkit versions of Emacs, the -menu bar also takes one line of the specified number. But in the X -toolkit version, the menu bar is additional and does not count against -the specified height. The tool bar, if present, is also additional. - - Enabling or disabling the menu bar or tool bar alters the amount of -space available for ordinary text. Therefore, if Emacs starts up with -a tool bar (which is the default), and handles the geometry -specification assuming there is a tool bar, and then your -@file{~/.emacs} file disables the tool bar, you will end up with a -frame geometry different from what you asked for. To get the intended -size with no tool bar, use an X resource to specify ``no tool bar'' -(@pxref{Table of Resources}); then Emacs will already know there's no -tool bar when it processes the specified geometry. - - When using one of @samp{--fullscreen}, @samp{--fullwidth} or -@samp{--fullheight} there may be some space around the frame -anyway. That is because Emacs rounds the sizes so they are an -even number of character heights and widths. - - Some window managers have options that can make them ignore both -program-specified and user-specified positions (sawfish is one). -If these are set, Emacs fails to position the window correctly. - -@node Borders X -@appendixsec Internal and External Borders -@cindex borders (X Window System) - - An Emacs frame has an internal border and an external border. The -internal border is an extra strip of the background color around the -text portion of the frame. Emacs itself draws the internal border. -The external border is added by the window manager outside the frame; -depending on the window manager you use, it may contain various boxes -you can click on to move or iconify the window. - -@table @samp -@item -ib @var{width} -@opindex -ib -@itemx --internal-border=@var{width} -@opindex --internal-border -@cindex internal border width, command-line argument -Specify @var{width} as the width of the internal border (between the text -and the main border), in pixels. - -@item -bw @var{width} -@opindex -bw -@itemx --border-width=@var{width} -@opindex --border-width -@cindex main border width, command-line argument -Specify @var{width} as the width of the main border, in pixels. -@end table - - When you specify the size of the frame, that does not count the -borders. The frame's position is measured from the outside edge of the -external border. - - Use the @samp{-ib @var{n}} option to specify an internal border -@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to -specify the width of the external border (though the window manager may -not pay attention to what you specify). The default width of the -external border is 2. - -@node Title X -@appendixsec Frame Titles - - An Emacs frame may or may not have a specified title. The frame -title, if specified, appears in window decorations and icons as the -name of the frame. If an Emacs frame has no specified title, the -default title has the form @samp{@var{invocation-name}@@@var{machine}} -(if there is only one frame) or the selected window's buffer name (if -there is more than one frame). - - You can specify a title for the initial Emacs frame with a command -line option: - -@table @samp -@item -T @var{title} -@opindex -T -@itemx --title=@var{title} -@opindex --title -@cindex frame title, command-line argument -Specify @var{title} as the title for the initial Emacs frame. -@end table - - The @samp{--name} option (@pxref{Resources}) also specifies the title -for the initial Emacs frame. - -@node Icons X -@appendixsec Icons -@cindex icons (X Window System) - - Most window managers allow you to ``iconify'' a frame, removing -it from sight, and leaving a small, distinctive ``icon'' window in its -place. Clicking on the icon window makes the frame itself appear again. -If you have many clients running at once, you can avoid cluttering up -the screen by iconifying most of the clients. - -@table @samp -@item -nbi -@opindex -nbi -@itemx --no-bitmap-icon -@opindex --no-bitmap-icon -@cindex Emacs icon, a gnu -Do not use a picture of a gnu as the Emacs icon. - -@item -iconic -@opindex --iconic -@itemx --iconic -@cindex start iconified, command-line argument -Start Emacs in iconified state. -@end table - - By default Emacs uses an icon window containing a picture of the GNU gnu. -The @samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let the -window manager choose what sort of icon to use---usually just a small -rectangle containing the frame's title. - - The @samp{-iconic} option tells Emacs to begin running as an icon, -rather than showing a frame right away. In this situation, the icon -is the only indication that Emacs has started; the text frame doesn't -appear until you deiconify it. - -@node Misc X -@appendixsec Other Display Options - -@table @samp -@item -hb -@opindex -hb -@itemx --horizontal-scroll-bars -@opindex --horizontal-scroll-bars -@c @cindex horizontal scroll bars, command-line argument -Enable horizontal scroll bars. Since horizontal scroll bars -are not yet implemented, this actually does nothing. - -@item -vb -@opindex -vb -@itemx --vertical-scroll-bars -@opindex --vertical-scroll-bars -@cindex vertical scroll bars, command-line argument -Enable vertical scroll bars. - -@item -lsp @var{pixels} -@opindex -lsp -@itemx --line-spacing=@var{pixels} -@opindex --line-spacing -@cindex line spacing, command-line argument -Specify @var{pixels} as additional space to put between lines, in pixels. - -@item -nbc -@opindex -nbc -@itemx --no-blinking-cursor -@opindex --no-blinking-cursor -@cindex blinking cursor disable, command-line argument -Disable the blinking cursor on graphical displays. - -@item -D -@opindex -D -@itemx --basic-display -@opindex --basic-display -Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips, -and turn off the blinking cursor. This can be useful for making a -test case that simplifies debugging of display problems. -@end table - - The @samp{--xrm} option (@pxref{Resources}) specifies additional -X resource values. - -@ignore - arch-tag: fffecd9e-7329-4a51-a3cc-dd4a9889340e -@end ignore diff --git a/man/commands.texi b/man/commands.texi deleted file mode 100644 index d2daffe00bb..00000000000 --- a/man/commands.texi +++ /dev/null @@ -1,294 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Characters, Keys and Commands - - This chapter explains the character sets used by Emacs for input -commands and for the contents of files, and the fundamental concepts of -@dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard -and mouse input. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node User Input, Keys, Screen, Top -@section Kinds of User Input -@cindex input with the keyboard -@cindex keyboard input -@cindex character set (keyboard) -@cindex @acronym{ASCII} -@cindex C- -@cindex Control -@cindex control characters - - GNU Emacs is designed for use with keyboard commands because that is -the most efficient way to edit. You can do editing with the mouse, as -in other editors, and you can give commands with the menu bar and tool -bar, and scroll with the scroll bar. But if you keep on editing that -way, you won't get the benefits of Emacs. Therefore, this manual -documents primarily how to edit with the keyboard. You can force -yourself to practice using the keyboard by using the shell command -@samp{emacs -nw} to start Emacs, so that the mouse won't work. - - Emacs uses an extension of the @acronym{ASCII} character set for -keyboard input; it also accepts non-character input events including -function keys and mouse button actions. - - @acronym{ASCII} consists of 128 character codes. Some of these codes are -assigned graphic symbols such as @samp{a} and @samp{=}; the rest are -control characters, such as @kbd{Control-a} (usually written @kbd{C-a} -for short). @kbd{C-a} gets its name from the fact that you type it by -holding down the @key{CTRL} key while pressing @kbd{a}. - - Some @acronym{ASCII} control characters have special names, and most -terminals have special keys you can type them with: for example, -@key{RET}, @key{TAB}, @key{DEL} and @key{ESC}. The space character is -usually known as @key{SPC}, even though strictly speaking it is a -graphic character that is blank. - - Emacs extends the @acronym{ASCII} character set with thousands more printing -characters (@pxref{International}), additional control characters, and a -few more modifiers that can be combined with any character. - - On @acronym{ASCII} terminals, there are only 32 possible control characters. -These are the control variants of letters and @samp{@@[]\^_}. In -addition, the shift key is meaningless with control characters: -@kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot -distinguish them. - - The Emacs character set has room for control variants of all -printing characters, and distinguishes @kbd{C-A} from @kbd{C-a}. -Graphical terminals make it possible to enter all these characters. -For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5} are -meaningful Emacs commands on a graphical terminal. - - Another Emacs character-set extension is additional modifier bits. -Only one modifier bit is commonly used; it is called Meta. Every -character has a Meta variant; examples include @kbd{Meta-a} (normally -written @kbd{M-a}, for short), @kbd{M-A} (different from @kbd{M-a}, -but they are normally equivalent in Emacs), @kbd{M-@key{RET}}, and -@kbd{M-C-a}. That last means @kbd{a} with both the @key{CTRL} and -@key{META} modifiers. We usually write it as @kbd{C-M-a} rather than -@kbd{M-C-a}, for reasons of tradition. - -@cindex Meta -@cindex M- -@cindex @key{ESC} replacing @key{META} key - Some terminals have a @key{META} key, and allow you to type Meta -characters by holding this key down. Thus, you can type @kbd{Meta-a} -by holding down @key{META} and pressing @kbd{a}. The @key{META} key -works much like the @key{SHIFT} key. In fact, this key is more often -labeled @key{ALT} or @key{EDIT}, instead of @key{META}; on a Sun -keyboard, it may have a diamond on it. - - If there is no @key{META} key, you can still type Meta characters -using two-character sequences starting with @key{ESC}. Thus, you can -enter @kbd{M-a} by typing @kbd{@key{ESC} a}. You can enter -@kbd{C-M-a} by typing @kbd{@key{ESC} C-a}. Unlike @key{META}, which -modifies other characters, @key{ESC} is a separate character. You -don't hold down @key{ESC} while typing the next character; instead, -you press it and release it, then you enter the next character. -@key{ESC} is allowed on terminals with @key{META} keys, too, in case -you have formed a habit of using it. - - Emacs defines several other modifier keys that can be applied to any -input character. These are called @key{SUPER}, @key{HYPER} and -@key{ALT}. We write @samp{s-}, @samp{H-} and @samp{A-} to say that a -character uses these modifiers. Thus, @kbd{s-H-C-x} is short for -@kbd{Super-Hyper-Control-x}. Not all graphical terminals actually -provide keys for these modifier flags---in fact, many terminals have a -key labeled @key{ALT} which is really a @key{META} key. The standard -key bindings of Emacs do not include any characters with these -modifiers. But you can assign them meanings of your own by -customizing Emacs. - - If your keyboard lacks one of these modifier keys, you can enter it -using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to the next -character, @kbd{C-x @@ s} adds the ``super'' flag, and @kbd{C-x @@ a} -adds the ``alt'' flag. For instance, @kbd{C-x @@ h C-a} is a way to -enter @kbd{Hyper-Control-a}. (Unfortunately there is no way to add -two modifiers by using @kbd{C-x @@} twice for the same character, -because the first one goes to work on the @kbd{C-x}.) - - Keyboard input includes keyboard keys that are not characters at -all, such as function keys and arrow keys. Mouse buttons are also not -characters. However, you can modify these events with the modifier -keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and @key{ALT}, -just like keyboard characters. - -@cindex input event - Input characters and non-character inputs are collectively called -@dfn{input events}. @xref{Input Events,,, elisp, The Emacs Lisp -Reference Manual}, for the full Lisp-level details. If you are not -doing Lisp programming, but simply want to redefine the meaning of -some characters or non-character events, see @ref{Customization}. - - @acronym{ASCII} terminals cannot really send anything to the computer except -@acronym{ASCII} characters. These terminals use a sequence of characters to -represent each function key. But that is invisible to the Emacs user, -because the keyboard input routines catch these special sequences -and convert them to function key events before any other part of Emacs -gets to see them. - -@cindex keys stolen by window manager -@cindex window manager, keys stolen by - On graphical displays, the window manager is likely to block the -character @kbd{Meta-@key{TAB}} before Emacs can see it. It may also -block @kbd{Meta-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}. If you have -these problems, we recommend that you customize your window manager to -turn off those commands, or put them on key combinations that Emacs -does not use. - -@node Keys, Commands, User Input, Top -@section Keys - -@cindex key sequence -@cindex key - A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input -events that is meaningful as a unit---a ``single command.'' Some -Emacs command sequences are invoked by just one character or one -event; for example, just @kbd{C-f} moves forward one character in the -buffer. But Emacs also has commands that take two or more events to -invoke. - -@cindex complete key -@cindex prefix key - If a sequence of events is enough to invoke a command, it is a -@dfn{complete key}. Examples of complete keys include @kbd{C-a}, -@kbd{X}, @key{RET}, @key{NEXT} (a function key), @key{DOWN} (an arrow -key), @kbd{C-x C-f}, and @kbd{C-x 4 C-f}. If it isn't long enough to be -complete, we call it a @dfn{prefix key}. The above examples show that -@kbd{C-x} and @kbd{C-x 4} are prefix keys. Every key sequence is either -a complete key or a prefix key. - - Most single characters constitute complete keys in the standard Emacs -command bindings. A few of them are prefix keys. A prefix key combines -with the following input event to make a longer key sequence, which may -itself be complete or a prefix. For example, @kbd{C-x} is a prefix key, -so @kbd{C-x} and the next input event combine to make a two-event -key sequence. Most of these key sequences are complete keys, including -@kbd{C-x C-f} and @kbd{C-x b}. A few, such as @kbd{C-x 4} and @kbd{C-x -r}, are themselves prefix keys that lead to three-event key -sequences. There's no limit to the length of a key sequence, but in -practice people rarely use sequences longer than four events. - - You can't add input events onto a complete key. For example, the -two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f} -is a complete key in itself. It's impossible to give @kbd{C-f C-k} an -independent meaning as a command. @kbd{C-f C-k} is two key sequences, -not one.@refill - - All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, -@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x -n}, @w{@kbd{C-x r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x -6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and @key{F2} are -aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in stone; -it describes the standard key bindings. If you customize Emacs, you can make -new prefix keys, or eliminate some of the standard ones (not -recommended for most users). @xref{Key Bindings}. - - If you make or eliminate prefix keys, that changes the set of -possible key sequences. For example, if you redefine @kbd{C-f} as a -prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless -you define that too as a prefix). Conversely, if you remove the -prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4 -@var{anything}} are no longer keys. - - Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key -displays a list of the commands starting with that prefix. There are -a few prefix keys after which @kbd{C-h} does not work---for historical -reasons, they define other meanings for @kbd{C-h} which are painful to -change. @key{F1} works after all prefix keys. - -@node Commands, Text Characters, Keys, Top -@section Keys and Commands - -@cindex binding -@cindex command -@cindex function definition - This manual is full of passages that tell you what particular keys -do. But Emacs does not assign meanings to keys directly. Instead, -Emacs assigns meanings to named @dfn{commands}, and then gives keys -their meanings by @dfn{binding} them to commands. - - Every command has a name chosen by a programmer. The name is -usually made of a few English words separated by dashes; for example, -@code{next-line} or @code{forward-word}. A command also has a -@dfn{function definition} which is a Lisp program; this is how the -command does its work. In Emacs Lisp, a command is a Lisp function with -special options to read arguments and for interactive use. For more -information on commands and functions, see @ref{What Is a Function,, -What Is a Function, elisp, The Emacs Lisp Reference Manual}. (The -definition here is simplified slightly.) - - The bindings between keys and commands are recorded in tables called -@dfn{keymaps}. @xref{Keymaps}. - - When we say that ``@kbd{C-n} moves down vertically one line'' we are -glossing over a subtle distinction that is irrelevant in ordinary use, -but vital for Emacs customization. The command @code{next-line} does -a vertical move downward. @kbd{C-n} has this effect @emph{because} it -is bound to @code{next-line}. If you rebind @kbd{C-n} to the command -@code{forward-word}, @kbd{C-n} will move forward one word instead. -Rebinding keys is an important method of customization. - - In the rest of this manual, we usually ignore this distinction to -keep things simple. We will often speak of keys like @kbd{C-n} as -commands, even though strictly speaking the key is bound to a command. -Usually we state the name of the command which really does the work in -parentheses after mentioning the key that runs it. For example, we -will say that ``The command @kbd{C-n} (@code{next-line}) moves point -vertically down,'' meaning that the command @code{next-line} moves -vertically down, and the key @kbd{C-n} is normally bound to it. - - Since we are discussing customization, we should tell you about -@dfn{variables}. Often the description of a command will say, ``To -change this, set the variable @code{mumble-foo}.'' A variable is a -name used to store a value. Most of the variables documented in this -manual are meant for customization: some command or other part of -Emacs examines the variable and behaves differently according to the -value that you set. You can ignore the information about variables -until you are interested in customizing them. Then read the basic -information on variables (@pxref{Variables}) and the information about -specific variables will make sense. - -@node Text Characters, Entering Emacs, Commands, Top -@section Character Set for Text -@cindex characters (in text) - - Text in Emacs buffers is a sequence of characters. In the simplest -case, these are @acronym{ASCII} characters, each stored in one 8-bit -byte. Both @acronym{ASCII} control characters (octal codes 000 -through 037, and 0177) and @acronym{ASCII} printing characters (codes -040 through 0176) are allowed. The other modifier flags used in -keyboard input, such as Meta, are not allowed in buffers. - - Non-@acronym{ASCII} printing characters can also appear in buffers, -when multibyte characters are enabled. They have character codes -starting at 256, octal 0400, and each one is represented as a sequence -of two or more bytes. @xref{International}. Single-byte characters -with codes 128 through 255 can also appear in multibyte buffers. -However, non-@acronym{ASCII} control characters cannot appear in a -buffer. - - Some @acronym{ASCII} control characters serve special purposes in text, and have -special names. For example, the newline character (octal code 012) is -used in the buffer to end a line, and the tab character (octal code 011) -is used for indenting to the next tab stop column (normally every 8 -columns). @xref{Text Display}. - - If you disable multibyte characters, then you can use only one -alphabet of non-@acronym{ASCII} characters, which all fit in one byte. -They use octal codes 0200 through 0377. @xref{Unibyte Mode}. - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: 9be43eef-d1f4-4d03-a916-c741ea713a45 -@end ignore diff --git a/man/custom.texi b/man/custom.texi deleted file mode 100644 index d496ab84b19..00000000000 --- a/man/custom.texi +++ /dev/null @@ -1,2515 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Customization, Quitting, Amusements, Top -@chapter Customization -@cindex customization - - This chapter talks about various topics relevant to adapting the -behavior of Emacs in ways we have anticipated. -@iftex -See @cite{The Emacs Lisp Reference Manual} -@end iftex -@ifnottex -@xref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp -Reference Manual}, -@end ifnottex -for how to make more far-reaching and open-ended changes. @xref{X -Resources}, for information on using X resources to customize Emacs. - - Customization that you do within Emacs normally affects only the -particular Emacs session that you do it in---it does not persist -between sessions unless you save the customization in a file such as -your init file (@file{.emacs}) that will affect future sessions. -(@xref{Init File}.) When you tell the customization buffer to save -customizations for future sessions, this actually works by editing -@file{.emacs} for you. - - Another means of customization is the keyboard macro, which is a -sequence of keystrokes to be replayed with a single command. -@xref{Keyboard Macros}, for full instruction how to record, manage, and -replay sequences of keys. - -@menu -* Minor Modes:: Each minor mode is one feature you can turn on - independently of any others. -* Easy Customization:: Convenient way to browse and change settings. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine keys". -* Syntax:: The syntax table controls how words and - expressions are parsed. -* Init File:: How to write common customizations in the - @file{.emacs} file. -@end menu - -@node Minor Modes -@section Minor Modes -@cindex minor modes -@cindex mode, minor - - Minor modes are optional features which you can turn on or off. For -example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines -between words as you type. All the minor modes are independent of each -other and of the selected major mode. Most minor modes say in the mode -line when they are enabled; for example, @samp{Fill} in the mode line means -that Auto Fill mode is enabled. - - You should append @code{-mode} to the name of a minor mode to -produce the name of the command that turns the mode on or off. Thus, -the command to enable or disable Auto Fill mode is called -@code{auto-fill-mode}. These commands are usually invoked with -@kbd{M-x}, but you can bind keys to them if you wish. - - With no argument, the minor mode function turns the mode on if it -was off, and off if it was on. This is known as @dfn{toggling}. A -positive argument always turns the mode on, and an explicit zero -argument or a negative argument always turns it off. - - Some minor modes are global: while enabled, they affect everything -you do in the Emacs session, in all buffers. Other minor modes are -buffer-local; they apply only to the current buffer, so you can enable -the mode in certain buffers and not others. - - For most minor modes, the command name is also the name of a -variable. The variable's value is non-@code{nil} if the mode is -enabled and @code{nil} if it is disabled. Some minor-mode commands -work by just setting the variable. For example, the command -@code{abbrev-mode} works by setting the value of @code{abbrev-mode} as -a variable; it is this variable that directly turns Abbrev mode on and -off. You can directly set the variable's value instead of calling the -mode function. For other minor modes, you need to either set the -variable through the Customize interface or call the mode function to -correctly enable or disable the mode. To check which of these two -possibilities applies to a given minor mode, use @kbd{C-h v} to ask -for documentation on the variable name. - - For minor mode commands that work by just setting the minor mode -variable, that variable provides a good way for Lisp programs to turn -minor modes on and off; it is also useful in a file's local variables -list (@pxref{File Variables}). But please think twice before setting -minor modes with a local variables list, because most minor modes are -a matter of user preference---other users editing the same file might -not want the same minor modes you prefer. - - The most useful buffer-local minor modes include Abbrev mode, Auto -Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, Outline minor -mode, Overwrite mode, and Binary Overwrite mode. - - Abbrev mode allows you to define abbreviations that automatically expand -as you type them. For example, @samp{amd} might expand to @samp{abbrev -mode}. @xref{Abbrevs}, for full information. - - Auto Fill mode allows you to enter filled text without breaking lines -explicitly. Emacs inserts newlines as necessary to prevent lines from -becoming too long. @xref{Filling}. - - Auto Save mode saves the buffer contents periodically to reduce the -amount of work you can lose in case of a crash. @xref{Auto Save}. - - Enriched mode enables editing and saving of formatted text. -@xref{Formatted Text}. - - Flyspell mode automatically highlights misspelled words. -@xref{Spelling}. - - Font-Lock mode automatically highlights certain textual units found -in programs, such as comments, strings, and function names being -defined. This requires a display that can show multiple fonts or -colors. @xref{Faces}. - -@ignore - ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"}, -@samp{^}, @samp{/} and @samp{~} combine with the following letter, to -produce an accented letter in the ISO Latin-1 character set. The -newer and more general feature of input methods more or less -supersedes ISO Accents mode. @xref{Unibyte Mode}. -@end ignore - - Outline minor mode provides the same facilities as the major mode -called Outline mode; but since it is a minor mode instead, you can -combine it with any major mode. @xref{Outline Mode}. - -@cindex Overwrite mode -@cindex mode, Overwrite - Overwrite mode causes ordinary printing characters to replace existing -text instead of shoving it to the right. For example, if point is in -front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a -@kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR} -as usual. In Overwrite mode, the command @kbd{C-q} inserts the next -character whatever it may be, even if it is a digit---this gives you a -way to insert a character instead of replacing an existing character. - -@findex overwrite-mode -@kindex INSERT - The command @code{overwrite-mode} is an exception to the rule that -commands which toggle minor modes are normally not bound to keys: it is -bound to the @key{INSERT} function key. This is because many other -programs bind @key{INSERT} to similar functions. - -@findex binary-overwrite-mode - Binary Overwrite mode is a variant of Overwrite mode for editing -binary files; it treats newlines and tabs like other characters, so that -they overwrite other characters and can be overwritten by them. -In Binary Overwrite mode, digits after @kbd{C-q} specify an -octal character code, as usual. - - Here are some useful minor modes that normally apply to all buffers -at once. Since Line Number mode and Transient Mark mode can be -enabled or disabled just by setting the value of the minor mode -variable, you @emph{can} set them differently for particular buffers, -by explicitly making the corresponding variable local in those -buffers. @xref{Locals}. - - Icomplete mode displays an indication of available completions when -you are in the minibuffer and completion is active. @xref{Completion -Options}. - - Line Number mode enables continuous display in the mode line of the -line number of point, and Column Number mode enables display of the -column number. @xref{Mode Line}. - - Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}). -Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of -these modes are enabled by default when you use the X Window System. - - In Transient Mark mode, every change in the buffer contents -``deactivates'' the mark, so that commands that operate on the region -will get an error. This means you must either set the mark, or -explicitly ``reactivate'' it, before each command that uses the region. -The advantage of Transient Mark mode is that Emacs can display the -region highlighted. @xref{Mark}. - -@node Easy Customization -@section Easy Customization Interface - -@cindex settings - Emacs has many @dfn{settings} which have values that you can specify -in order to customize various commands. Many are documented in this -manual. Most settings are @dfn{user options}---that is to say, Lisp -variables (@pxref{Variables})---so their names appear in the Variable -Index (@pxref{Variable Index}). The other settings are faces and -their attributes (@pxref{Faces}). - -@findex customize -@cindex customization buffer - You can browse interactively through settings and change them using -@kbd{M-x customize}. This command creates a @dfn{customization -buffer}, which offers commands to navigate through a logically -organized structure of the Emacs settings; you can also use it to edit -and set their values, and to save settings permanently in your -@file{~/.emacs} file (@pxref{Init File}). - - The appearance of the example buffers in this section is typically -different under a graphical display, since faces are then used to indicate -buttons, links and editable fields. - -@menu -* Groups: Customization Groups. How settings are classified in a structure. -* Browsing: Browsing Custom. Browsing and searching for settings. -* Changing a Variable:: How to edit an option's value and set the option. -* Saving Customizations:: Specifying the file for saving customizations. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Making a customization buffer for specific - variables, faces, or groups. -* Custom Themes:: How to define collections of customized options - that can be loaded and unloaded together. -@end menu - -@node Customization Groups -@subsection Customization Groups -@cindex customization groups - - For customization purposes, settings are organized into @dfn{groups} -to help you find them. Groups are collected into bigger groups, all -the way up to a master group called @code{Emacs}. - - @kbd{M-x customize} creates a customization buffer that shows the -top-level @code{Emacs} group and the second-level groups immediately -under it. It looks like this, in part: - -@c we want the buffer example to all be on one page, but unfortunately -@c that's quite a bit of text, so force all space to the bottom. -@page -@smallexample -@group -/- Emacs group: ---------------------------------------------------\ - [State]: visible group members are all at standard values. - Customization of the One True Editor. - See also [Manual]. - -Editing group: [Go to Group] -Basic text editing facilities. - -External group: [Go to Group] -Interfacing to external utilities. - -@var{more second-level groups} - -\- Emacs group end ------------------------------------------------/ -@end group -@end smallexample - -@noindent -This says that the buffer displays the contents of the @code{Emacs} -group. The other groups are listed because they are its contents. But -they are listed differently, without indentation and dashes, because -@emph{their} contents are not included. Each group has a single-line -documentation string; the @code{Emacs} group also has a @samp{[State]} -line. - -@cindex editable fields (customization buffer) -@cindex buttons (customization buffer) -@cindex links (customization buffer) - Most of the text in the customization buffer is read-only, but it -typically includes some @dfn{editable fields} that you can edit. -There are also @dfn{buttons} and @dfn{links}, which do something when -you @dfn{invoke} them. To invoke a button or a link, either click on -it with @kbd{Mouse-1}, or move point to it and type @key{RET}. - - For example, the phrase @samp{[State]} that appears in -a second-level group is a button. It operates on the same -customization buffer. The phrase @samp{[Go to Group]} is a kind -of hypertext link to another group. Invoking it creates a new -customization buffer, which shows that group and its contents. - - The @code{Emacs} group includes a few settings, but mainly it -contains other groups, which contain more groups, which contain the -settings. By browsing the hierarchy of groups, you will eventually -find the feature you are interested in customizing. Then you can use -the customization buffer to set that feature's settings. You can also -go straight to a particular group by name, using the command @kbd{M-x -customize-group}. - -@node Browsing Custom -@subsection Browsing and Searching for Options and Faces -@findex customize-browse - - @kbd{M-x customize-browse} is another way to browse the available -settings. This command creates a special customization buffer which -shows only the names of groups and settings, and puts them in a -structure. - - In this buffer, you can show the contents of a group by invoking the -@samp{[+]} button. When the group contents are visible, this button -changes to @samp{[-]}; invoking that hides the group contents again. - - Each group or setting in this buffer has a link which says -@samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking this link -creates an ordinary customization buffer showing just that group and -its contents, just that user option, or just that face. This is the -way to change settings that you find with @kbd{M-x customize-browse}. - - If you can guess part of the name of the settings you are interested -in, @kbd{M-x customize-apropos} is another way to search for settings. -However, unlike @code{customize} and @code{customize-browse}, -@code{customize-apropos} can only find groups and settings that are -loaded in the current Emacs session. @xref{Specific Customization,, -Customizing Specific Items}. - -@node Changing a Variable -@subsection Changing a Variable - - Here is an example of what a variable (a user option) looks like in -the customization buffer: - -@smallexample -Kill Ring Max: [Hide Value] 60 - [State]: STANDARD. -Maximum length of kill ring before oldest elements are thrown away. -@end smallexample - - The text following @samp{[Hide Value]}, @samp{60} in this case, indicates -the current value of the variable. If you see @samp{[Show Value]} instead of -@samp{[Hide Value]}, it means that the value is hidden; the customization -buffer initially hides values that take up several lines. Invoke -@samp{[Show Value]} to show the value. - - The line after the variable name indicates the @dfn{customization -state} of the variable: in the example above, it says you have not -changed the option yet. The @samp{[State]} button at the beginning of -this line gives you a menu of various operations for customizing the -variable. - - The line after the @samp{[State]} line displays the beginning of the -variable's documentation string. If there are more lines of -documentation, this line ends with a @samp{[More]} button; invoke that -to show the full documentation string. - - To enter a new value for @samp{Kill Ring Max}, move point to the -value and edit it textually. For example, you can type @kbd{M-d}, -then insert another number. As you begin to alter the text, you will -see the @samp{[State]} line change to say that you have edited the -value: - -@smallexample -[State]: EDITED, shown value does not take effect until you set or @r{@dots{}} - save it. -@end smallexample - -@cindex user options, how to set -@cindex variables, how to set -@cindex settings, how to set - Editing the value does not actually set the variable. To do that, -you must @dfn{set} the variable. To do this, invoke the -@samp{[State]} button and choose @samp{Set for Current Session}. - - The state of the variable changes visibly when you set it: - -@smallexample -[State]: SET for current session only. -@end smallexample - - You don't have to worry about specifying a value that is not valid; -the @samp{Set for Current Session} operation checks for validity and -will not install an unacceptable value. - -@kindex M-TAB @r{(customization buffer)} -@findex widget-complete - While editing a field that is a file name, directory name, -command name, or anything else for which completion is defined, you -can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. -(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.) - - Some variables have a small fixed set of possible legitimate values. -These variables don't let you edit the value textually. Instead, a -@samp{[Value Menu]} button appears before the value; invoke this -button to change the value. For a boolean ``on or off'' value, the -button says @samp{[Toggle]}, and it changes to the other value. -@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the -changes take real effect when you use the @samp{Set for Current -Session} operation. - - Some variables have values with complex structure. For example, the -value of @code{file-coding-system-alist} is an association list. Here -is how it appears in the customization buffer: - -@smallexample -File Coding System Alist: [Hide Value] -[INS] [DEL] File regexp: \.elc\' - Choice: [Value Menu] Encoding/decoding pair: - Decoding: emacs-mule - Encoding: emacs-mule -[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' - Choice: [Value Menu] Encoding/decoding pair: - Decoding: raw-text - Encoding: raw-text-unix -[INS] [DEL] File regexp: \.tar\' - Choice: [Value Menu] Encoding/decoding pair: - Decoding: no-conversion - Encoding: no-conversion -[INS] [DEL] File regexp: - Choice: [Value Menu] Encoding/decoding pair: - Decoding: undecided - Encoding: nil -[INS] - [State]: STANDARD. -Alist to decide a coding system to use for a file I/O @r{@dots{}} - operation. [Hide Rest] -The format is ((PATTERN . VAL) ...), -where PATTERN is a regular expression matching a file name, -@r{[@dots{}more lines of documentation@dots{}]} -@end smallexample - -@noindent -Each association in the list appears on four lines, with several -editable fields and/or buttons. You can edit the regexps and coding -systems using ordinary editing commands. You can also invoke -@samp{[Value Menu]} to switch to a different kind of value---for -instance, to specify a function instead of a pair of coding systems. - -To delete an association from the list, invoke the @samp{[DEL]} button -for that item. To add an association, invoke @samp{[INS]} at the -position where you want to add it. There is an @samp{[INS]} button -between each pair of associations, another at the beginning and another -at the end, so you can add a new association at any position in the -list. - -@kindex TAB @r{(customization buffer)} -@kindex S-TAB @r{(customization buffer)} -@findex widget-forward -@findex widget-backward - Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful -for moving through the customization buffer. @key{TAB} -(@code{widget-forward}) moves forward to the next button or editable -field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to -the previous button or editable field. - - Typing @key{RET} on an editable field also moves forward, just like -@key{TAB}. We set it up this way because people often type @key{RET} -when they are finished editing a field. To insert a newline within an -editable field, use @kbd{C-o} or @kbd{C-q C-j}. - -@cindex saving a setting -@cindex settings, how to save - Setting the variable changes its value in the current Emacs session; -@dfn{saving} the value changes it for future sessions as well. To -save the variable, invoke @samp{[State]} and select the @samp{Save for -Future Sessions} operation. This works by writing code so as to set -the variable again, each time you start Emacs (@pxref{Saving -Customizations}). - - You can also restore the variable to its standard value by invoking -@samp{[State]} and selecting the @samp{Erase Customization} operation. -There are actually four reset operations: - -@table @samp -@item Undo Edits -If you have made some modifications and not yet set the variable, -this restores the text in the customization buffer to match -the actual value. - -@item Reset to Saved -This restores the value of the variable to the last saved value, -and updates the text accordingly. - -@item Erase Customization -This sets the variable to its standard value, and updates the text -accordingly. This also eliminates any saved value for the variable, -so that you will get the standard value in future Emacs sessions. - -@item Set to Backup Value -This sets the variable to a previous value that was set in the -customization buffer in this session. If you customize a variable -and then reset it, which discards the customized value, -you can get the discarded value back again with this operation. -@end table - -@cindex comments on customized settings - Sometimes it is useful to record a comment about a specific -customization. Use the @samp{Add Comment} item from the -@samp{[State]} menu to create a field for entering the comment. The -comment you enter will be saved, and displayed again if you again view -the same variable in a customization buffer, even in another session. - - The state of a group indicates whether anything in that group has been -edited, set or saved. - - Near the top of the customization buffer there are two lines of buttons: - -@smallexample - [Set for Current Session] [Save for Future Sessions] - [Undo Edits] [Reset to Saved] [Erase Customization] [Finish] -@end smallexample - -@vindex custom-buffer-done-function -@noindent -Invoking @samp{[Finish]} either buries or kills this customization -buffer according to the setting of the option -@code{custom-buffer-done-kill}; the default is to bury the buffer. -Each of the other buttons performs an operation---set, save or -reset---on each of the settings in the buffer that could meaningfully -be set, saved or reset. They do not operate on settings whose values -are hidden, nor on subgroups which are hidden or not visible in the buffer. - -@node Saving Customizations -@subsection Saving Customizations - - Saving customizations from the customization buffer works by writing -code that future sessions will read, code to set up those -customizations again. - -@vindex custom-file - Normally this saves customizations in your init file, -@file{~/.emacs}. If you wish, you can save customizations in another -file instead. To make this work, your @file{~/.emacs} should set -@code{custom-file} to the name of that file. Then you should load the -file by calling @code{load}. For example: - -@example -(setq custom-file "~/.emacs-custom.el") -(load custom-file) -@end example - - You can use @code{custom-file} to specify different customization -files for different Emacs versions, like this: - -@example -(cond ((< emacs-major-version 21) - ;; @r{Emacs 20 customization.} - (setq custom-file "~/.custom-20.el")) - ((and (= emacs-major-version 21) (< emacs-minor-version 4)) - ;; @r{Emacs 21 customization, before version 21.4.} - (setq custom-file "~/.custom-21.el")) - ((< emacs-major-version 22) - ;; @r{Emacs version 21.4 or later.} - (setq custom-file "~/.custom-21.4.el")) - (t - ;; @r{Emacs version 22.1 or later.} - (setq custom-file "~/.custom-22.el"))) - -(load custom-file) -@end example - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not let you save your -customizations in your @file{~/.emacs} init file. This is because -saving customizations from such a session would wipe out all the other -customizations you might have on your init file. - -@node Face Customization -@subsection Customizing Faces -@cindex customizing faces -@cindex bold font -@cindex italic font -@cindex fonts and faces - - In addition to variables, some customization groups also include -faces. When you show the contents of a group, both the variables and -the faces in the group appear in the customization buffer. Here is an -example of how a face looks: - -@smallexample -Custom Changed Face:(sample) [Hide Face] - [State]: STANDARD. -Face used when the customize item has been changed. -Parent groups: [Custom Magic Faces] -Attributes: [ ] Font Family: * - [ ] Width: * - [ ] Height: * - [ ] Weight: * - [ ] Slant: * - [ ] Underline: * - [ ] Overline: * - [ ] Strike-through: * - [ ] Box around text: * - [ ] Inverse-video: * - [X] Foreground: white (sample) - [X] Background: blue (sample) - [ ] Stipple: * - [ ] Inherit: * -@end smallexample - - Each face attribute has its own line. The @samp{[@var{x}]} button -before the attribute name indicates whether the attribute is -@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]} -means that it's disabled. You can enable or disable the attribute by -clicking that button. When the attribute is enabled, you can change -the attribute value in the usual ways. - - For the colors, you can specify a color name (use @kbd{M-x -list-colors-display} for a list of them) or a hexadecimal color -specification of the form @samp{#@var{rr}@var{gg}@var{bb}}. -(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is -green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a -black-and-white display, the colors you can use for the background are -@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and -@samp{gray3}. Emacs supports these shades of gray by using background -stipple patterns instead of a color. - - Setting, saving and resetting a face work like the same operations for -variables (@pxref{Changing a Variable}). - - A face can specify different appearances for different types of -display. For example, a face can make text red on a color display, but -use a bold font on a monochrome display. To specify multiple -appearances for a face, select @samp{For All Kinds of Displays} in the -menu you get from invoking @samp{[State]}. - -@findex modify-face - Another more basic way to set the attributes of a specific face is -with @kbd{M-x modify-face}. This command reads the name of a face, then -reads the attributes one by one. For the color and stipple attributes, -the attribute's current value is the default---type just @key{RET} if -you don't want to change that attribute. Type @samp{none} if you want -to clear out the attribute. - -@node Specific Customization -@subsection Customizing Specific Items - - Instead of finding the setting you want to change by navigating the -structure of groups, here are other ways to specify the settings that -you want to customize. - -@table @kbd -@item M-x customize-option @key{RET} @var{option} @key{RET} -Set up a customization buffer with just one user option variable, -@var{option}. -@item M-x customize-face @key{RET} @var{face} @key{RET} -Set up a customization buffer with just one face, @var{face}. -@item M-x customize-group @key{RET} @var{group} @key{RET} -Set up a customization buffer with just one group, @var{group}. -@item M-x customize-apropos @key{RET} @var{regexp} @key{RET} -Set up a customization buffer with all the settings and groups that -match @var{regexp}. -@item M-x customize-changed @key{RET} @var{version} @key{RET} -Set up a customization buffer with all the settings and groups -whose meaning has changed since Emacs version @var{version}. -@item M-x customize-saved -Set up a customization buffer containing all settings that you -have saved with customization buffers. -@item M-x customize-unsaved -Set up a customization buffer containing all settings that you have -set but not saved. -@end table - -@findex customize-option - If you want to alter a particular user option with the customization -buffer, and you know its name, you can use the command @kbd{M-x -customize-option} and specify the user option (variable) name. This -sets up the customization buffer with just one user option---the one -that you asked for. Editing, setting and saving the value work as -described above, but only for the specified user option. Minibuffer -completion is handy if you only know part of the name. However, this -command can only see options that have been loaded in the current -Emacs session. - -@findex customize-face - Likewise, you can modify a specific face, chosen by name, using -@kbd{M-x customize-face}. By default it operates on the face used -on the character after point. - -@findex customize-group - You can also set up the customization buffer with a specific group, -using @kbd{M-x customize-group}. The immediate contents of the chosen -group, including settings (user options and faces), and other groups, -all appear as well (even if not already loaded). However, the -subgroups' own contents are not included. - -@findex customize-apropos - For a more general way of controlling what to customize, you can use -@kbd{M-x customize-apropos}. You specify a regular expression as -argument; then all @emph{loaded} settings and groups whose names match -this regular expression are set up in the customization buffer. If -you specify an empty regular expression, this includes @emph{all} -loaded groups and settings---which takes a long time to set up. - -@findex customize-changed - When you upgrade to a new Emacs version, you might want to consider -customizing new settings, and settings whose meanings or default -values have changed. To do this, use @kbd{M-x customize-changed} and -specify a previous Emacs version number using the minibuffer. It -creates a customization buffer which shows all the settings and groups -whose definitions have been changed since the specified version, -loading them if necessary. - -@findex customize-saved -@findex customize-unsaved - If you change settings and then decide the change was a mistake, you -can use two special commands to revisit your previous changes. Use -@kbd{M-x customize-saved} to look at the settings that you have saved. -Use @kbd{M-x customize-unsaved} to look at the settings that you -have set but not saved. - -@node Custom Themes -@subsection Customization Themes -@cindex custom themes - - @dfn{Custom themes} are collections of settings that can be enabled -or disabled as a unit. You can use Custom themes to switch quickly -and easily between various collections of settings, and to transfer -such collections from one computer to another. - -@findex customize-create-theme - To define a Custom theme, use @kbd{M-x customize-create-theme}, -which brings up a buffer named @samp{*New Custom Theme*}. At the top -of the buffer is an editable field where you can specify the name of -the theme. Click on the button labelled @samp{Insert Variable} to add -a variable to the theme, and click on @samp{Insert Face} to add a -face. You can edit these values in the @samp{*New Custom Theme*} -buffer like in an ordinary Customize buffer. To remove an option from -the theme, click on its @samp{State} button and select @samp{Delete}. - -@vindex custom-theme-directory - After adding the desired options, click on @samp{Save Theme} to save -the Custom theme. This writes the theme definition to a file -@file{@var{foo}-theme.el} (where @var{foo} is the theme name you -supplied), in the directory @file{~/.emacs.d/}. You can specify the -directory by setting @code{custom-theme-directory}. - - You can view and edit the settings of a previously-defined theme by -clicking on @samp{Visit Theme} and specifying the theme name. You can -also import the variables and faces that you have set using Customize -by visiting the ``special'' theme named @samp{user}. This theme, which -records all the options that you set in the ordinary customization -buffer, is always enabled, and always takes precedence over all other -enabled Custom themes. Additionally, the @samp{user} theme is -recorded with code in your @file{.emacs} file, rather than a -@file{user-theme.el} file. - -@vindex custom-enabled-themes - Once you have defined a Custom theme, you can use it by customizing -the variable @code{custom-enabled-themes}. This is a list of Custom -themes that are @dfn{enabled}, or put into effect. If you set -@code{custom-enabled-themes} using the Customize interface, the theme -definitions are automatically loaded from the theme files, if they -aren't already. If you save the value of @code{custom-enabled-themes} -for future Emacs sessions, those Custom themes will be enabled -whenever Emacs is started up. - - If two enabled themes specify different values for an option, the -theme occurring earlier in @code{custom-enabled-themes} takes effect. - -@findex load-theme -@findex enable-theme -@findex disable-theme - You can temporarily enable a Custom theme with @kbd{M-x -enable-theme}. This prompts for a theme name in the minibuffer, loads -the theme from the theme file if necessary, and enables the theme. -You can @dfn{disable} any enabled theme with the command @kbd{M-x -disable-theme}; this returns the options specified in the theme to -their original values. To re-enable the theme, type @kbd{M-x -enable-theme} again. If a theme file is changed during your Emacs -session, you can reload it by typing @kbd{M-x load-theme}. (This also -enables the theme.) - -@node Variables -@section Variables -@cindex variable -@cindex option, user -@cindex user option - - A @dfn{variable} is a Lisp symbol which has a value. The symbol's -name is also called the name of the variable. A variable name can -contain any characters that can appear in a file, but conventionally -variable names consist of words separated by hyphens. A variable can -have a documentation string which describes what kind of value it should -have and how the value will be used. - - Emacs Lisp allows any variable (with a few exceptions) to have any -kind of value, but most variables that Emacs uses expect a value of a -certain type. Often the value should always be a string, or should -always be a number. Sometimes we say that a certain feature is turned -on if a variable is ``non-@code{nil},'' meaning that if the variable's -value is @code{nil}, the feature is off, but the feature is on for -@emph{any} other value. The conventional value to use to turn on the -feature---since you have to pick one particular value when you set the -variable---is @code{t}. - - Emacs uses many Lisp variables for internal record keeping, but the -most interesting variables for a non-programmer user are those meant -for users to change---these are called @dfn{user options}. - - Each user option that you can set with the customization buffer is -in fact a Lisp variable. Emacs does not (usually) change the values -of these variables on its own; instead, you set the values in order to -control the behavior of certain Emacs commands. Use of the -customization buffer is explained above (@pxref{Easy Customization}); -here we describe other aspects of Emacs variables. - -@menu -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -@end menu - -@node Examining -@subsection Examining and Setting Variables -@cindex setting variables - -@table @kbd -@item C-h v @var{var} @key{RET} -Display the value and documentation of variable @var{var} -(@code{describe-variable}). -@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} -Change the value of variable @var{var} to @var{value}. -@end table - - To examine the value of a single variable, use @kbd{C-h v} -(@code{describe-variable}), which reads a variable name using the -minibuffer, with completion. It displays both the value and the -documentation of the variable. For example, - -@example -C-h v fill-column @key{RET} -@end example - -@noindent -displays something like this: - -@smallexample -fill-column is a variable defined in `C source code'. -fill-column's value is 70 -Local in buffer custom.texi; global value is 70 -Automatically becomes buffer-local when set in any fashion. - -This variable is safe to use as a file local variable only if its value -satisfies the predicate `integerp'. - -Documentation: -*Column beyond which automatic line-wrapping should happen. -Interactively, you can set the buffer local value using C-x f. - -You can customize this variable. -@end smallexample - -@noindent -The line that says you can customize the variable indicates that this -variable is a user option. (The star also indicates this, but it is -an obsolete indicator that may eventually disappear.) @kbd{C-h v} is -not restricted to user options; it allows any variable name. - -@findex set-variable -The most convenient way to set a specific user option variable is with -@kbd{M-x set-variable}. This reads the variable name with the -minibuffer (with completion), and then reads a Lisp expression for the -new value using the minibuffer a second time (you can insert the old -value into the minibuffer for editing via @kbd{M-n}). For example, - -@example -M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} -@end example - -@noindent -sets @code{fill-column} to 75. - - @kbd{M-x set-variable} is limited to user option variables, but you can -set any variable with a Lisp expression, using the function @code{setq}. -Here is a @code{setq} expression to set @code{fill-column}: - -@example -(setq fill-column 75) -@end example - - To execute an expression like this one, go to the @samp{*scratch*} -buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp -Interaction}. - - Setting variables, like all means of customizing Emacs except where -otherwise stated, affects only the current Emacs session. The only -way to alter the variable in future sessions is to put something in -the @file{~/.emacs} file to set it those sessions (@pxref{Init File}). - -@node Hooks -@subsection Hooks -@cindex hook -@cindex running a hook - - @dfn{Hooks} are an important mechanism for customization of Emacs. A -hook is a Lisp variable which holds a list of functions, to be called on -some well-defined occasion. (This is called @dfn{running the hook}.) -The individual functions in the list are called the @dfn{hook functions} -of the hook. With rare exceptions, hooks in Emacs are empty when Emacs -starts up, so the only hook functions in any given hook are the ones you -explicitly put there as customization. - - Most major modes run one or more @dfn{mode hooks} as the last step of -initialization. This makes it easy for you to customize the behavior of -the mode, by setting up a hook function to override the local variable -assignments already made by the mode. But hooks are also used in other -contexts. For example, the hook @code{suspend-hook} runs just before -Emacs suspends itself (@pxref{Exiting}). - -@cindex normal hook - Most Emacs hooks are @dfn{normal hooks}. This means that running the -hook operates by calling all the hook functions, unconditionally, with -no arguments. We have made an effort to keep most hooks normal so that -you can use them in a uniform way. Every variable in Emacs whose name -ends in @samp{-hook} is a normal hook. - -@cindex abnormal hook - There are also a few @dfn{abnormal hooks}. These variables' names end -in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What -makes these hooks abnormal is that there is something peculiar about the -way its functions are called---perhaps they are given arguments, or -perhaps the values they return are used in some way. For example, -@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because -as soon as one hook function returns a non-@code{nil} value, the rest -are not called at all. The documentation of each abnormal hook variable -explains in detail what is peculiar about it. - -@findex add-hook - You can set a hook variable with @code{setq} like any other Lisp -variable, but the recommended way to add a hook function to a hook -(either normal or abnormal) is by calling @code{add-hook}. -@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}. - - For example, here's how to set up a hook to turn on Auto Fill mode -when entering Text mode and other modes based on Text mode: - -@example -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end example - - The next example shows how to use a hook to customize the indentation -of C code. (People often have strong personal preferences for one -format compared to another.) Here the hook function is an anonymous -lambda expression. - -@example -@group -(setq my-c-style - '((c-comment-only-line-offset . 4) -@end group -@group - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)) -@end group -@group - (c-offsets-alist . ((arglist-close . c-lineup-arglist) - (substatement-open . 0))))) -@end group - -@group -(add-hook 'c-mode-common-hook - '(lambda () - (c-add-style "my-style" my-c-style t))) -@end group -@end example - - It is best to design your hook functions so that the order in which -they are executed does not matter. Any dependence on the order is -``asking for trouble.'' However, the order is predictable: the most -recently added hook functions are executed first. - -@findex remove-hook - If you play with adding various different versions of a hook -function by calling @code{add-hook} over and over, remember that all -the versions you added will remain in the hook variable together. You -can clear out individual functions by calling @code{remove-hook}, or -do @code{(setq @var{hook-variable} nil)} to remove everything. - -@node Locals -@subsection Local Variables - -@table @kbd -@item M-x make-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} have a local value in the current buffer. -@item M-x kill-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} use its global value in the current buffer. -@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} -Mark variable @var{var} so that setting it will make it local to the -buffer that is current at that time. -@end table - -@cindex local variables - Almost any variable can be made @dfn{local} to a specific Emacs -buffer. This means that its value in that buffer is independent of its -value in other buffers. A few variables are always local in every -buffer. Every other Emacs variable has a @dfn{global} value which is in -effect in all buffers that have not made the variable local. - -@findex make-local-variable - @kbd{M-x make-local-variable} reads the name of a variable and makes -it local to the current buffer. Changing its value subsequently in -this buffer will not affect others, and changes in its global value -will not affect this buffer. - -@findex make-variable-buffer-local -@cindex per-buffer variables - @kbd{M-x make-variable-buffer-local} marks a variable so it will -become local automatically whenever it is set. More precisely, once a -variable has been marked in this way, the usual ways of setting the -variable automatically do @code{make-local-variable} first. We call -such variables @dfn{per-buffer} variables. Many variables in Emacs -are normally per-buffer; the variable's document string tells you when -this is so. A per-buffer variable's global value is normally never -effective in any buffer, but it still has a meaning: it is the initial -value of the variable for each new buffer. - - Major modes (@pxref{Major Modes}) always make variables local to the -buffer before setting the variables. This is why changing major modes -in one buffer has no effect on other buffers. Minor modes also work -by setting variables---normally, each minor mode has one controlling -variable which is non-@code{nil} when the mode is enabled -(@pxref{Minor Modes}). For many minor modes, the controlling variable -is per buffer, and thus always buffer-local. Otherwise, you can make -it local in a specific buffer like any other variable. - - A few variables cannot be local to a buffer because they are always -local to each display instead (@pxref{Multiple Displays}). If you try to -make one of these variables buffer-local, you'll get an error message. - -@findex kill-local-variable - @kbd{M-x kill-local-variable} makes a specified variable cease to be -local to the current buffer. The global value of the variable -henceforth is in effect in this buffer. Setting the major mode kills -all the local variables of the buffer except for a few variables -specially marked as @dfn{permanent locals}. - -@findex setq-default - To set the global value of a variable, regardless of whether the -variable has a local value in the current buffer, you can use the Lisp -construct @code{setq-default}. This construct is used just like -@code{setq}, but it sets variables' global values instead of their local -values (if any). When the current buffer does have a local value, the -new global value may not be visible until you switch to another buffer. -Here is an example: - -@example -(setq-default fill-column 75) -@end example - -@noindent -@code{setq-default} is the only way to set the global value of a variable -that has been marked with @code{make-variable-buffer-local}. - -@findex default-value - Lisp programs can use @code{default-value} to look at a variable's -default value. This function takes a symbol as argument and returns its -default value. The argument is evaluated; usually you must quote it -explicitly. For example, here's how to obtain the default value of -@code{fill-column}: - -@example -(default-value 'fill-column) -@end example - -@node File Variables -@subsection Local Variables in Files -@cindex local variables in files -@cindex file local variables - - A file can specify local variable values for use when you edit the -file with Emacs. Visiting the file checks for local variable -specifications; it automatically makes these variables local to the -buffer, and sets them to the values specified in the file. - -@menu -* Specifying File Variables:: Specifying file local variables. -* Safe File Variables:: Making sure file local variables are safe. -@end menu - -@node Specifying File Variables -@subsubsection Specifying File Variables - - There are two ways to specify file local variable values: in the first -line, or with a local variables list. Here's how to specify them in the -first line: - -@example --*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- -@end example - -@noindent -You can specify any number of variables/value pairs in this way, each -pair with a colon and semicolon as shown above. @code{mode: -@var{modename};} specifies the major mode; this should come first in the -line. The @var{value}s are not evaluated; they are used literally. -Here is an example that specifies Lisp mode and sets two variables with -numeric values: - -@smallexample -;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- -@end smallexample - - You can also specify the coding system for a file in this way: just -specify a value for the ``variable'' named @code{coding}. The ``value'' -must be a coding system name that Emacs recognizes. @xref{Coding -Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a -particular Lisp file. @xref{Enabling Multibyte}. - - The @code{eval} pseudo-variable, described below, can be specified in -the first line as well. - -@cindex shell scripts, and local file variables - In shell scripts, the first line is used to identify the script -interpreter, so you cannot put any local variables there. To -accommodate this, Emacs looks for local variable specifications in the -@emph{second} line when the first line specifies an interpreter. - - A @dfn{local variables list} goes near the end of the file, in the -last page. (It is often best to put it on a page by itself.) The local -variables list starts with a line containing the string @samp{Local -Variables:}, and ends with a line containing the string @samp{End:}. In -between come the variable names and values, one set per line, as -@samp{@var{variable}:@: @var{value}}. The @var{value}s are not -evaluated; they are used literally. If a file has both a local -variables list and a @samp{-*-} line, Emacs processes @emph{everything} -in the @samp{-*-} line first, and @emph{everything} in the local -variables list afterward. - - Here is an example of a local variables list: - -@example -;; Local Variables: ** -;; mode:lisp ** -;; comment-column:0 ** -;; comment-start: ";; " ** -;; comment-end:"**" ** -;; End: ** -@end example - - Each line starts with the prefix @samp{;; } and each line ends with -the suffix @samp{ **}. Emacs recognizes these as the prefix and -suffix based on the first line of the list, by finding them -surrounding the magic string @samp{Local Variables:}; then it -automatically discards them from the other lines of the list. - - The usual reason for using a prefix and/or suffix is to embed the -local variables list in a comment, so it won't confuse other programs -that the file is intended as input for. The example above is for a -language where comment lines start with @samp{;; } and end with -@samp{**}; the local values for @code{comment-start} and -@code{comment-end} customize the rest of Emacs for this unusual -syntax. Don't use a prefix (or a suffix) if you don't need one. - - If you write a multi-line string value, you should put the prefix -and suffix on each line, even lines that start or end within the -string. They will be stripped off for processing the list. If you -want to split a long string across multiple lines of the file, you can -use backslash-newline, which is ignored in Lisp string constants. -Here's an example of doing this: - -@example -# Local Variables: -# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ -# -Dmumble=blaah" -# End: -@end example - - Some ``variable names'' have special meanings in a local variables -list. Specifying the ``variable'' @code{mode} really sets the major -mode, while any value specified for the ``variable'' @code{eval} is -simply evaluated as an expression (its value is ignored). A value for -@code{coding} specifies the coding system for character code -conversion of this file, and a value of @code{t} for @code{unibyte} -says to visit the file in a unibyte buffer. These four ``variables'' -are not really variables; setting them in any other context has no -special meaning. - - @emph{If @code{mode} is used to set a major mode, it should be the -first ``variable'' in the list.} Otherwise, the entries that precede -it will usually be ignored, since most modes kill all local variables -as part of their initialization. - - You can use the @code{mode} ``variable'' to set minor modes as well -as the major modes; in fact, you can use it more than once, first to -set the major mode and then to set minor modes which are specific to -particular buffers. But most minor modes should not be specified in -the file at all, because they represent user preferences. - - For example, you may be tempted to try to turn on Auto Fill mode with -a local variable list. That is a mistake. The choice of Auto Fill mode -or not is a matter of individual taste, not a matter of the contents of -particular files. If you want to use Auto Fill, set up major mode hooks -with your @file{.emacs} file to turn it on (when appropriate) for you -alone (@pxref{Init File}). Don't use a local variable list to impose -your taste on everyone. - - The start of the local variables list must be no more than 3000 -characters from the end of the file, and must be in the last page if the -file is divided into pages. Otherwise, Emacs will not notice it is -there. The purpose of this rule is so that a stray @samp{Local -Variables:}@: not in the last page does not confuse Emacs, and so that -visiting a long file that is all one page and has no local variables -list need not take the time to search the whole file. - - Use the command @code{normal-mode} to reset the local variables and -major mode of a buffer according to the file name and contents, -including the local variables list if any. @xref{Choosing Modes}. - -@node Safe File Variables -@subsubsection Safety of File Variables - - File-local variables can be dangerous; when you visit someone else's -file, there's no telling what its local variables list could do to -your Emacs. Improper values of the @code{eval} ``variable,'' and -other variables such as @code{load-path}, could execute Lisp code you -didn't intend to run. - - Therefore, whenever Emacs encounters file local variable values that -are not known to be safe, it displays the file's entire local -variables list, and asks you for confirmation before setting them. -You can type @kbd{y} or @key{SPC} to put the local variables list into -effect, or @kbd{n} to ignore it. When Emacs is run in batch mode -(@pxref{Initial Options}), it can't really ask you, so it assumes the -answer @kbd{n}. - - Emacs normally recognizes certain variables/value pairs as safe. -For instance, it is safe to give @code{comment-column} or -@code{fill-column} any integer value. If a file specifies only -known-safe variable/value pairs, Emacs does not ask for confirmation -before setting them. Otherwise, you can tell Emacs to record all the -variable/value pairs in this file as safe, by typing @kbd{!} at the -confirmation prompt. When Emacs encounters these variable/value pairs -subsequently, in the same file or others, it will assume they are -safe. - -@vindex safe-local-variable-values -@cindex risky variable - Some variables, such as @code{load-path}, are considered -particularly @dfn{risky}: there is seldom any reason to specify them -as local variables, and changing them can be dangerous. If a file -contains only risky local variables, Emacs neither offers nor accepts -@kbd{!} as input at the confirmation prompt. If some of the local -variables in a file are risky, and some are only potentially unsafe, you -can enter @kbd{!} at the prompt. It applies all the variables, but only -marks the non-risky ones as safe for the future. If you really want to -record safe values for risky variables, do it directly by customizing -@samp{safe-local-variable-values} (@pxref{Easy Customization}). - -@vindex enable-local-variables - The variable @code{enable-local-variables} allows you to change the -way Emacs processes local variables. Its default value is @code{t}, -which specifies the behavior described above. If it is @code{nil}, -Emacs simply ignores all file local variables. @code{:safe} means use -only the safe values and ignore the rest. Any other value says to -query you about each file that has local variables, without trying to -determine whether the values are known to be safe. - -@vindex enable-local-eval - The variable @code{enable-local-eval} controls whether Emacs -processes @code{eval} variables. The three possibilities for the -variable's value are @code{t}, @code{nil}, and anything else, just as -for @code{enable-local-variables}. The default is @code{maybe}, which -is neither @code{t} nor @code{nil}, so normally Emacs does ask for -confirmation about processing @code{eval} variables. - -@vindex safe-local-eval-forms - But there is an exception. The @code{safe-local-eval-forms} is a -customizable list of eval forms which are safe. Emacs does not ask -for confirmation when it finds these forms for the @code{eval} -variable. - -@node Key Bindings -@section Customizing Key Bindings -@cindex key bindings - - This section describes @dfn{key bindings}, which map keys to commands, -and @dfn{keymaps}, which record key bindings. It also explains how -to customize key bindings. - - Recall that a command is a Lisp function whose definition provides for -interactive use. Like every Lisp function, a command has a function -name, which usually consists of lower-case letters and hyphens. - -@menu -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. -@end menu - -@node Keymaps -@subsection Keymaps -@cindex keymap - - The bindings between key sequences and command functions are recorded -in data structures called @dfn{keymaps}. Emacs has many of these, each -used on particular occasions. - - Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence -of @dfn{input events} that have a meaning as a unit. Input events -include characters, function keys and mouse buttons---all the inputs -that you can send to the computer with your terminal. A key sequence -gets its meaning from its @dfn{binding}, which says what command it -runs. The function of keymaps is to record these bindings. - -@cindex global keymap - The @dfn{global} keymap is the most important keymap because it is -always in effect. The global keymap defines keys for Fundamental mode; -most of these definitions are common to most or all major modes. Each -major or minor mode can have its own keymap which overrides the global -definitions of some keys. - - For example, a self-inserting character such as @kbd{g} is -self-inserting because the global keymap binds it to the command -@code{self-insert-command}. The standard Emacs editing characters such -as @kbd{C-a} also get their standard meanings from the global keymap. -Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work -by storing the new binding in the proper place in the global map. -@xref{Rebinding}. - - Meta characters work differently; Emacs translates each Meta -character into a pair of characters starting with @key{ESC}. When you -type the character @kbd{M-a} in a key sequence, Emacs replaces it with -@kbd{@key{ESC} a}. A meta key comes in as a single input event, but -becomes two events for purposes of key bindings. The reason for this is -historical, and we might change it someday. - -@cindex function key - Most modern keyboards have function keys as well as character keys. -Function keys send input events just as character keys do, and keymaps -can have bindings for them. - - On text terminals, typing a function key actually sends the computer a -sequence of characters; the precise details of the sequence depends on -which function key and on the model of terminal you are using. (Often -the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your -terminal type properly, it recognizes the character sequences forming -function keys wherever they occur in a key sequence (not just at the -beginning). Thus, for most purposes, you can pretend the function keys -reach Emacs directly and ignore their encoding as character sequences. - -@cindex mouse - Mouse buttons also produce input events. These events come with other -data---the window and position where you pressed or released the button, -and a time stamp. But only the choice of button matters for key -bindings; the other data matters only if a command looks at it. -(Commands designed for mouse invocation usually do look at the other -data.) - - A keymap records definitions for single events. Interpreting a key -sequence of multiple events involves a chain of keymaps. The first -keymap gives a definition for the first event; this definition is -another keymap, which is used to look up the second event in the -sequence, and so on. - - Key sequences can mix function keys and characters. For example, -@kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix -key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse -events with keyboard events, but we recommend against it, because such -key sequences are inconvenient to use. - - As a user, you can redefine any key; but it is usually best to stick -to key sequences that consist of @kbd{C-c} followed by a letter (upper -or lower case). These keys are ``reserved for users,'' so they won't -conflict with any properly designed Emacs extension. The function -keys @key{F5} through @key{F9} are also reserved for users. If you -redefine some other key, your definition may be overridden by certain -extensions or major modes which redefine the same key. - -@node Prefix Keymaps -@subsection Prefix Keymaps - - A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap, -which holds the definition for the event that immediately follows -that prefix. - - The definition of a prefix key is usually the keymap to use for -looking up the following event. The definition can also be a Lisp -symbol whose function definition is the following keymap; the effect is -the same, but it provides a command name for the prefix key that can be -used as a description of what the prefix key is for. Thus, the binding -of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function -definition is the keymap for @kbd{C-x} commands. The definitions of -@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in -the global map, so these prefix keys are always available. - - Aside from ordinary prefix keys, there is a fictitious ``prefix key'' -which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp -Reference Manual}, for special information about menu bar key bindings. -Mouse button events that invoke pop-up menus are also prefix keys; see -@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more -details. - - Some prefix keymaps are stored in variables with names: - -@itemize @bullet -@item -@vindex ctl-x-map -@code{ctl-x-map} is the variable name for the map used for characters that -follow @kbd{C-x}. -@item -@vindex help-map -@code{help-map} is for characters that follow @kbd{C-h}. -@item -@vindex esc-map -@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta -characters are actually defined by this map. -@item -@vindex ctl-x-4-map -@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. -@item -@vindex mode-specific-map -@code{mode-specific-map} is for characters that follow @kbd{C-c}. -@end itemize - -@node Local Keymaps -@subsection Local Keymaps - -@cindex local keymap - So far we have explained the ins and outs of the global map. Major -modes customize Emacs by providing their own key bindings in @dfn{local -keymaps}. For example, C mode overrides @key{TAB} to make it indent the -current line for C code. Portions of text in the buffer can specify -their own keymaps to substitute for the keymap of the buffer's major -mode. - -@cindex minor mode keymap - Minor modes can also have local keymaps. Whenever a minor mode is -in effect, the definitions in its keymap override both the major -mode's local keymap and the global keymap. - - A local keymap can locally redefine a key as a prefix key by defining -it as a prefix keymap. If the key is also defined globally as a prefix, -then its local and global definitions (both keymaps) effectively -combine: both of them are used to look up the event that follows the -prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as -another keymap, and that keymap defines @kbd{C-z} as a command, this -provides a local meaning for @kbd{C-c C-z}. This does not affect other -sequences that start with @kbd{C-c}; if those sequences don't have their -own local bindings, their global bindings remain in effect. - - Another way to think of this is that Emacs handles a multi-event key -sequence by looking in several keymaps, one by one, for a binding of the -whole key sequence. First it checks the minor mode keymaps for minor -modes that are enabled, then it checks the major mode's keymap, and then -it checks the global keymap. This is not precisely how key lookup -works, but it's good enough for understanding the results in ordinary -circumstances. - -@cindex rebinding major mode keys - Most major modes construct their keymaps when the mode is used for -the first time in a session. If you wish to change one of these -keymaps, you must use the major mode's @dfn{mode hook} -(@pxref{Hooks}). - -@findex define-key - For example, the command @code{texinfo-mode} to select Texinfo mode -runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook -to add local bindings (not very useful, we admit) for @kbd{C-c n} and -@kbd{C-c p} in Texinfo mode: - -@example -(add-hook 'texinfo-mode-hook - '(lambda () - (define-key texinfo-mode-map "\C-cp" - 'backward-paragraph) - (define-key texinfo-mode-map "\C-cn" - 'forward-paragraph))) -@end example - -@node Minibuffer Maps -@subsection Minibuffer Keymaps - -@cindex minibuffer keymaps -@vindex minibuffer-local-map -@vindex minibuffer-local-ns-map -@vindex minibuffer-local-completion-map -@vindex minibuffer-local-must-match-map -@vindex minibuffer-local-filename-completion-map -@vindex minibuffer-local-must-match-filename-map - The minibuffer has its own set of local keymaps; they contain various -completion and exit commands. - -@itemize @bullet -@item -@code{minibuffer-local-map} is used for ordinary input (no completion). -@item -@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits -just like @key{RET}. This is used mainly for Mocklisp compatibility. -@item -@code{minibuffer-local-completion-map} is for permissive completion. -@item -@code{minibuffer-local-must-match-map} is for strict completion and -for cautious completion. -@item -Finally, @code{minibuffer-local-filename-completion-map} and -@code{minibuffer-local-must-match-filename-map} are like the two -previous ones, but they are specifically for file name completion. -They do not bind @key{SPC}. -@end itemize - -@node Rebinding -@subsection Changing Key Bindings Interactively -@cindex key rebinding, this session -@cindex redefining keys, this session - - The way to redefine an Emacs key is to change its entry in a keymap. -You can change the global keymap, in which case the change is effective in -all major modes (except those that have their own overriding local -definitions for the same key). Or you can change the current buffer's -local map, which affects all buffers using the same major mode. - -@findex global-set-key -@findex local-set-key -@findex global-unset-key -@findex local-unset-key -@table @kbd -@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} globally to run @var{cmd}. -@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} locally (in the major mode now in effect) to run -@var{cmd}. -@item M-x global-unset-key @key{RET} @var{key} -Make @var{key} undefined in the global map. -@item M-x local-unset-key @key{RET} @var{key} -Make @var{key} undefined locally (in the major mode now in effect). -@end table - - For example, suppose you like to execute commands in a subshell within -an Emacs buffer, instead of suspending Emacs and executing commands in -your login shell. Normally, @kbd{C-z} is bound to the function -@code{suspend-emacs} (when not using the X Window System), but you can -change @kbd{C-z} to invoke an interactive subshell within Emacs, by -binding it to @code{shell} as follows: - -@example -M-x global-set-key @key{RET} C-z shell @key{RET} -@end example - -@noindent -@code{global-set-key} reads the command name after the key. After you -press the key, a message like this appears so that you can confirm that -you are binding the key you want: - -@example -Set key C-z to command: -@end example - - You can redefine function keys and mouse events in the same way; just -type the function key or click the mouse when it's time to specify the -key to rebind. - - You can rebind a key that contains more than one event in the same -way. Emacs keeps reading the key to rebind until it is a complete key -(that is, not a prefix key). Thus, if you type @kbd{C-f} for -@var{key}, that's the end; it enters the minibuffer immediately to -read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it -reads another character; if that is @kbd{4}, another prefix character, -it reads one more character, and so on. For example, - -@example -M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} -@end example - -@noindent -redefines @kbd{C-x 4 $} to run the (fictitious) command -@code{spell-other-window}. - - The two-character keys consisting of @kbd{C-c} followed by a letter -are reserved for user customizations. Lisp programs are not supposed to -define these keys, so the bindings you make for them will be available -in all major modes and will never get in the way of anything. - - You can remove the global definition of a key with -@code{global-unset-key}. This makes the key @dfn{undefined}; if you -type it, Emacs will just beep. Similarly, @code{local-unset-key} makes -a key undefined in the current major mode keymap, which makes the global -definition (or lack of one) come back into effect in that major mode. - - If you have redefined (or undefined) a key and you subsequently wish -to retract the change, undefining the key will not do the job---you need -to redefine the key with its standard definition. To find the name of -the standard definition of a key, go to a Fundamental mode buffer in a -fresh Emacs and use @kbd{C-h c}. The documentation of keys in this -manual also lists their command names. - - If you want to prevent yourself from invoking a command by mistake, it -is better to disable the command than to undefine the key. A disabled -command is less work to invoke when you really want to. -@xref{Disabling}. - -@node Init Rebinding -@subsection Rebinding Keys in Your Init File - - If you have a set of key bindings that you like to use all the time, -you can specify them in your @file{.emacs} file by using their Lisp -syntax. (@xref{Init File}.) - - The simplest method for doing this works for @acronym{ASCII} characters and -Meta-modified @acronym{ASCII} characters only. This method uses a string to -represent the key sequence you want to rebind. For example, here's how -to bind @kbd{C-z} to @code{shell}: - -@example -(global-set-key "\C-z" 'shell) -@end example - -@noindent -This example uses a string constant containing one character, -@kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The -single-quote before the command name, @code{shell}, marks it as a -constant symbol rather than a variable. If you omit the quote, Emacs -would try to evaluate @code{shell} immediately as a variable. This -probably causes an error; it certainly isn't what you want. - - Here is another example that binds the key sequence @kbd{C-x M-l}: - -@example -(global-set-key "\C-x\M-l" 'make-symbolic-link) -@end example - - To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the -string, you can use the Emacs Lisp escape sequences, @samp{\t}, -@samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds -@kbd{C-x @key{TAB}}: - -@example -(global-set-key "\C-x\t" 'indent-rigidly) -@end example - - These examples show how to write some other special @acronym{ASCII} characters -in strings for key bindings: - -@example -(global-set-key "\r" 'newline) ;; @key{RET} -(global-set-key "\d" 'delete-backward-char) ;; @key{DEL} -(global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC} -@end example - - When the key sequence includes function keys or mouse button events, -or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use -the more general method of rebinding, which uses a vector to specify the -key sequence. - - The way to write a vector in Emacs Lisp is with square brackets around -the vector elements. Use spaces to separate the elements. If an -element is a symbol, simply write the symbol's name---no other -delimiters or punctuation are needed. If a vector element is a -character, write it as a Lisp character constant: @samp{?} followed by -the character as it would appear in a string. - - Here are examples of using vectors to rebind @kbd{C-=} (a control -character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=} -is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at -all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a -keyboard-modified mouse button): - -@example -(global-set-key [?\C-=] 'make-symbolic-link) -(global-set-key [?\M-\C-=] 'make-symbolic-link) -(global-set-key [?\H-a] 'make-symbolic-link) -(global-set-key [f7] 'make-symbolic-link) -(global-set-key [C-mouse-1] 'make-symbolic-link) -@end example - - You can use a vector for the simple cases too. Here's how to -rewrite the first six examples above to use vectors: - -@example -(global-set-key [?\C-z] 'shell) -(global-set-key [?\C-x ?l] 'make-symbolic-link) -(global-set-key [?\C-x ?\t] 'indent-rigidly) -(global-set-key [?\r] 'newline) -(global-set-key [?\d] 'delete-backward-char) -(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command) -@end example - -@noindent -As you see, you represent a multi-character key sequence with a vector -by listing all of the characters, in order, within the square brackets -that delimit the vector. - - Language and coding systems can cause problems with key bindings -for non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. - -@node Function Keys -@subsection Rebinding Function Keys - - Key sequences can contain function keys as well as ordinary -characters. Just as Lisp characters (actually integers) represent -keyboard characters, Lisp symbols represent function keys. If the -function key has a word as its label, then that word is also the name of -the corresponding Lisp symbol. Here are the conventional Lisp names for -common function keys: - -@table @asis -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys. - -@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} -Other cursor repositioning keys. - -@item @code{select}, @code{print}, @code{execute}, @code{backtab} -@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} -@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar} -Miscellaneous function keys. - -@item @code{f1}, @code{f2}, @dots{} @code{f35} -Numbered function keys (across the top of the keyboard). - -@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} -@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} -@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} -Keypad keys (to the right of the regular keyboard), with names or punctuation. - -@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} -Keypad keys with digits. - -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@end table - - These names are conventional, but some systems (especially when using -X) may use different names. To make certain what symbol is used for a -given function key on your terminal, type @kbd{C-h c} followed by that -key. - - A key sequence which contains function key symbols (or anything but -@acronym{ASCII} characters) must be a vector rather than a string. -Thus, to bind function key @samp{f1} to the command @code{rmail}, -write the following: - -@example -(global-set-key [f1] 'rmail) -@end example - -@noindent -To bind the right-arrow key to the command @code{forward-char}, you can -use this expression: - -@example -(global-set-key [right] 'forward-char) -@end example - -@noindent -This uses the Lisp syntax for a vector containing the symbol -@code{right}. (This binding is present in Emacs by default.) - - @xref{Init Rebinding}, for more information about using vectors for -rebinding. - - You can mix function keys and characters in a key sequence. This -example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}. - -@example -(global-set-key [?\C-x next] 'forward-page) -@end example - -@noindent -where @code{?\C-x} is the Lisp character constant for the character -@kbd{C-x}. The vector element @code{next} is a symbol and therefore -does not take a question mark. - - You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER}, -@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent -these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-}, -@samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name. -Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a -word: - -@example -(global-set-key [H-M-right] 'forward-word) -@end example - -@cindex keypad - Many keyboards have a ``numeric keypad'' on the right hand side. -The numeric keys in the keypad double up as cursor motion keys, -toggled by a key labeled @samp{Num Lock}. By default, Emacs -translates these keys to the corresponding keys in the main keyboard. -For example, when @samp{Num Lock} is on, the key labeled @samp{8} on -the numeric keypad produces @code{kp-8}, which is translated to -@kbd{8}; when @samp{Num Lock} is off, the same key produces -@code{kp-up}, which is translated to @key{UP}. If you rebind a key -such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. -However, if you rebind a @samp{kp-} key directly, that won't affect -its non-keypad equivalent. - - Emacs provides a convenient method for binding the numeric keypad -keys, using the variables @code{keypad-setup}, -@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and -@code{keypad-numlock-shifted-setup}. These can be found in the -@samp{keyboard} customization group (@pxref{Easy Customization}). You -can rebind the keys to perform other tasks, such as issuing numeric -prefix arguments. - -@node Named ASCII Chars -@subsection Named @acronym{ASCII} Control Characters - - @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} -started out as names for certain @acronym{ASCII} control characters, -used so often that they have special keys of their own. For instance, -@key{TAB} was another name for @kbd{C-i}. Later, users found it -convenient to distinguish in Emacs between these keys and the ``same'' -control characters typed with the @key{CTRL} key. Therefore, on most -modern terminals, they are no longer the same, and @key{TAB} is -distinguishable from @kbd{C-i}. - - Emacs can distinguish these two kinds of input if the keyboard does. -It treats the ``special'' keys as function keys named @code{tab}, -@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and -@code{delete}. These function keys translate automatically into the -corresponding @acronym{ASCII} characters @emph{if} they have no -bindings of their own. As a result, neither users nor Lisp programs -need to pay attention to the distinction unless they care to. - - If you do not want to distinguish between (for example) @key{TAB} and -@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} -(octal code 011). If you do want to distinguish, make one binding for -this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. - - With an ordinary @acronym{ASCII} terminal, there is no way to distinguish -between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), -because the terminal sends the same character in both cases. - -@node Mouse Buttons -@subsection Rebinding Mouse Buttons -@cindex mouse button events -@cindex rebinding mouse buttons -@cindex click events -@cindex drag events -@cindex down events -@cindex button down events - - Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary -mouse events in Emacs are @dfn{click} events; these happen when you -press a button and release it without moving the mouse. You can also -get @dfn{drag} events, when you move the mouse while holding the button -down. Drag events happen when you finally let go of the button. - - The symbols for basic click events are @code{mouse-1} for the leftmost -button, @code{mouse-2} for the next, and so on. Here is how you can -redefine the second mouse button to split the current window: - -@example -(global-set-key [mouse-2] 'split-window-vertically) -@end example - - The symbols for drag events are similar, but have the prefix -@samp{drag-} before the word @samp{mouse}. For example, dragging the -first button generates a @code{drag-mouse-1} event. - - You can also define bindings for events that occur when a mouse button -is pressed down. These events start with @samp{down-} instead of -@samp{drag-}. Such events are generated only if they have key bindings. -When you get a button-down event, a corresponding click or drag event -will always follow. - -@cindex double clicks -@cindex triple clicks - If you wish, you can distinguish single, double, and triple clicks. A -double click means clicking a mouse button twice in approximately the -same place. The first click generates an ordinary click event. The -second click, if it comes soon enough, generates a double-click event -instead. The event type for a double-click event starts with -@samp{double-}: for example, @code{double-mouse-3}. - - This means that you can give a special meaning to the second click at -the same place, but it must act on the assumption that the ordinary -single click definition has run when the first click was received. - - This constrains what you can do with double clicks, but user interface -designers say that this constraint ought to be followed in any case. A -double click should do something similar to the single click, only -``more so.'' The command for the double-click event should perform the -extra work for the double click. - - If a double-click event has no binding, it changes to the -corresponding single-click event. Thus, if you don't define a -particular double click specially, it executes the single-click command -twice. - - Emacs also supports triple-click events whose names start with -@samp{triple-}. Emacs does not distinguish quadruple clicks as event -types; clicks beyond the third generate additional triple-click events. -However, the full number of clicks is recorded in the event list, so -if you know Emacs Lisp you can distinguish if you really want to -(@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}). -We don't recommend distinct meanings for more than three clicks, but -sometimes it is useful for subsequent clicks to cycle through the same -set of three meanings, so that four clicks are equivalent to one -click, five are equivalent to two, and six are equivalent to three. - - Emacs also records multiple presses in drag and button-down events. -For example, when you press a button twice, then move the mouse while -holding the button, Emacs gets a @samp{double-drag-} event. And at the -moment when you press it down for the second time, Emacs gets a -@samp{double-down-} event (which is ignored, like all button-down -events, if it has no binding). - -@vindex double-click-time - The variable @code{double-click-time} specifies how much time can -elapse between clicks and still allow them to be grouped as a multiple -click. Its value is in units of milliseconds. If the value is -@code{nil}, double clicks are not detected at all. If the value is -@code{t}, then there is no time limit. The default is 500. - -@vindex double-click-fuzz - The variable @code{double-click-fuzz} specifies how much the mouse -can move between clicks and still allow them to be grouped as a multiple -click. Its value is in units of pixels on windowed displays and in -units of 1/8 of a character cell on text-mode terminals; the default is -3. - - The symbols for mouse events also indicate the status of the modifier -keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, -@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} -or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. - - A frame includes areas that don't show text from the buffer, such as -the mode line and the scroll bar. You can tell whether a mouse button -comes from a special area of the screen by means of dummy ``prefix -keys.'' For example, if you click the mouse in the mode line, you get -the prefix key @code{mode-line} before the ordinary mouse-button symbol. -Thus, here is how to define the command for clicking the first button in -a mode line to run @code{scroll-up}: - -@example -(global-set-key [mode-line mouse-1] 'scroll-up) -@end example - - Here is the complete list of these dummy prefix keys and their -meanings: - -@table @code -@item mode-line -The mouse was in the mode line of a window. -@item vertical-line -The mouse was in the vertical line separating side-by-side windows. (If -you use scroll bars, they appear in place of these vertical lines.) -@item vertical-scroll-bar -The mouse was in a vertical scroll bar. (This is the only kind of -scroll bar Emacs currently supports.) -@item menu-bar -The mouse was in the menu bar. -@item header-line -The mouse was in a header line. -@ignore -@item horizontal-scroll-bar -The mouse was in a horizontal scroll bar. Horizontal scroll bars do -horizontal scrolling, and people don't use them often. -@end ignore -@end table - - You can put more than one mouse button in a key sequence, but it isn't -usual to do so. - -@node Disabling -@subsection Disabling Commands -@cindex disabled command - - Disabling a command means that invoking it interactively asks for -confirmation from the user. The purpose of disabling a command is to -prevent users from executing it by accident; we do this for commands -that might be confusing to the uninitiated. - - Attempting to invoke a disabled command interactively in Emacs -displays a window containing the command's name, its documentation, -and some instructions on what to do immediately; then Emacs asks for -input saying whether to execute the command as requested, enable it -and execute it, or cancel. If you decide to enable the command, you -must then answer another question---whether to do this permanently, or -just for the current session. (Enabling permanently works by -automatically editing your @file{.emacs} file.) You can also type -@kbd{!} to enable @emph{all} commands, for the current session only. - - The direct mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. Here is the Lisp program to do this: - -@example -(put 'delete-region 'disabled t) -@end example - - If the value of the @code{disabled} property is a string, that string -is included in the message displayed when the command is used: - -@example -(put 'delete-region 'disabled - "It's better to use `kill-region' instead.\n") -@end example - -@findex disable-command -@findex enable-command - You can make a command disabled either by editing the @file{.emacs} -file directly, or with the command @kbd{M-x disable-command}, which edits -the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command} -edits @file{.emacs} to enable a command permanently. @xref{Init File}. - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not edit your -@file{~/.emacs} init file. Doing so could lose information -because Emacs has not read your init file. - - Whether a command is disabled is independent of what key is used to -invoke it; disabling also applies if the command is invoked using -@kbd{M-x}. However, disabling a command has no effect on calling it -as a function from Lisp programs. - -@node Syntax -@section The Syntax Table -@cindex syntax table - - All the Emacs commands which parse words or balance parentheses are -controlled by the @dfn{syntax table}. The syntax table says which -characters are opening delimiters, which are parts of words, which are -string quotes, and so on. It does this by assigning each character to -one of fifteen-odd @dfn{syntax classes}. In some cases it specifies -some additional information also. - - Each major mode has its own syntax table (though related major modes -sometimes share one syntax table), which it installs in each buffer -that uses the mode. The syntax table installed in the current buffer -is the one that all commands use, so we call it ``the'' syntax table. - -@kindex C-h s -@findex describe-syntax - To display a description of the contents of the current syntax -table, type @kbd{C-h s} (@code{describe-syntax}). The description of -each character includes the string you would have to give to -@code{modify-syntax-entry} to set up that character's current syntax, -starting with the character which designates its syntax class, plus -some English text to explain its meaning. - - A syntax table is actually a Lisp object, a char-table, whose -elements are cons cells. For full information on the syntax table, -see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp -Reference Manual}. - -@node Init File -@section The Init File, @file{~/.emacs} -@cindex init file -@cindex Emacs initialization file -@cindex key rebinding, permanent -@cindex rebinding keys, permanently -@cindex startup (init file) - - When Emacs is started, it normally loads a Lisp program from the file -@file{.emacs} or @file{.emacs.el} in your home directory (@pxref{Find Init}). -We call this file your @dfn{init file} because it specifies how to -initialize Emacs for you. You can use the command line switch -@samp{-q} to prevent loading your init file, and @samp{-u} (or -@samp{--user}) to specify a different user's init file (@pxref{Initial -Options}). - - You can also use @file{~/.emacs.d/init.el} as the init file. Emacs -tries this if it cannot find @file{~/.emacs} or @file{~/.emacs.el}. - -@cindex @file{default.el}, the default init file - There can also be a @dfn{default init file}, which is the library -named @file{default.el}, found via the standard search path for -libraries. The Emacs distribution contains no such library; your site -may create one for local customizations. If this library exists, it is -loaded whenever you start Emacs (except when you specify @samp{-q}). -But your init file, if any, is loaded first; if it sets -@code{inhibit-default-init} non-@code{nil}, then @file{default} is not -loaded. - -@cindex site init file -@cindex @file{site-start.el}, the site startup file - Your site may also have a @dfn{site startup file}; this is named -@file{site-start.el}, if it exists. Like @file{default.el}, Emacs -finds this file via the standard search path for Lisp libraries. -Emacs loads this library before it loads your init file. To inhibit -loading of this library, use the option @samp{--no-site-file}. -@xref{Initial Options}. We recommend against using -@file{site-start.el} for changes that some users may not like. It is -better to put them in @file{default.el}, so that users can more easily -override them. - - You can place @file{default.el} and @file{site-start.el} in any of -the directories which Emacs searches for Lisp libraries. The variable -@code{load-path} (@pxref{Lisp Libraries}) specifies these directories. -Many sites put these files in the @file{site-lisp} subdirectory of the -Emacs installation directory, typically -@file{/usr/local/share/emacs/site-lisp}. - - If you have a large amount of code in your @file{.emacs} file, you -should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte -Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}, -for more information about compiling Emacs Lisp programs. - - If you are going to write actual Emacs Lisp programs that go beyond -minor customization, you should read the @cite{Emacs Lisp Reference Manual}. -@ifnottex -@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference -Manual}. -@end ifnottex - -@menu -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. -@end menu - -@node Init Syntax -@subsection Init File Syntax - - The @file{.emacs} file contains one or more Lisp function call -expressions. Each of these consists of a function name followed by -arguments, all surrounded by parentheses. For example, @code{(setq -fill-column 60)} calls the function @code{setq} to set the variable -@code{fill-column} (@pxref{Filling}) to 60. - - You can set any Lisp variable with @code{setq}, but with certain -variables @code{setq} won't do what you probably want in the -@file{.emacs} file. Some variables automatically become buffer-local -when set with @code{setq}; what you want in @file{.emacs} is to set -the default value, using @code{setq-default}. Some customizable minor -mode variables do special things to enable the mode when you set them -with Customize, but ordinary @code{setq} won't do that; to enable the -mode in your @file{.emacs} file, call the minor mode command. The -following section has examples of both of these methods. - - The second argument to @code{setq} is an expression for the new -value of the variable. This can be a constant, a variable, or a -function call expression. In @file{.emacs}, constants are used most -of the time. They can be: - -@table @asis -@item Numbers: -Numbers are written in decimal, with an optional initial minus sign. - -@item Strings: -@cindex Lisp string syntax -@cindex string syntax -Lisp string syntax is the same as C string syntax with a few extra -features. Use a double-quote character to begin and end a string constant. - -In a string, you can include newlines and special characters literally. -But often it is cleaner to use backslash sequences for them: @samp{\n} -for newline, @samp{\b} for backspace, @samp{\r} for carriage return, -@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for -escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or -@samp{\@var{ooo}} for the character whose octal code is @var{ooo}. -Backslash and double-quote are the only characters for which backslash -sequences are mandatory. - -@samp{\C-} can be used as a prefix for a control character, as in -@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for -a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for -@kbd{Control-Meta-A}.@refill - -@xref{Init Non-ASCII}, for information about including -non-@acronym{ASCII} in your init file. - -@item Characters: -Lisp character constant syntax consists of a @samp{?} followed by -either a character or an escape sequence starting with @samp{\}. -Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that -strings and characters are not interchangeable in Lisp; some contexts -require one and some contexts require the other. - -@xref{Init Non-ASCII}, for information about binding commands to -keys which send non-@acronym{ASCII} characters. - -@item True: -@code{t} stands for `true'. - -@item False: -@code{nil} stands for `false'. - -@item Other Lisp objects: -Write a single-quote (@code{'}) followed by the Lisp object you want. -@end table - -@node Init Examples -@subsection Init File Examples - - Here are some examples of doing certain commonly desired things with -Lisp expressions: - -@itemize @bullet -@item -Make @key{TAB} in C mode just insert a tab if point is in the middle of a -line. - -@example -(setq c-tab-always-indent nil) -@end example - -Here we have a variable whose value is normally @code{t} for `true' -and the alternative is @code{nil} for `false'. - -@item -Make searches case sensitive by default (in all buffers that do not -override this). - -@example -(setq-default case-fold-search nil) -@end example - -This sets the default value, which is effective in all buffers that do -not have local values for the variable. Setting @code{case-fold-search} -with @code{setq} affects only the current buffer's local value, which -is not what you probably want to do in an init file. - -@item -@vindex user-mail-address -Specify your own email address, if Emacs can't figure it out correctly. - -@example -(setq user-mail-address "rumsfeld@@torture.gov") -@end example - -Various Emacs packages that need your own email address use the value of -@code{user-mail-address}. - -@item -Make Text mode the default mode for new buffers. - -@example -(setq default-major-mode 'text-mode) -@end example - -Note that @code{text-mode} is used because it is the command for -entering Text mode. The single-quote before it makes the symbol a -constant; otherwise, @code{text-mode} would be treated as a variable -name. - -@need 1500 -@item -Set up defaults for the Latin-1 character set -which supports most of the languages of Western Europe. - -@example -(set-language-environment "Latin-1") -@end example - -@need 1500 -@item -Turn off Line Number mode, a global minor mode. - -@example -(line-number-mode 0) -@end example - -@need 1500 -@item -Turn on Auto Fill mode automatically in Text mode and related modes. - -@example -(add-hook 'text-mode-hook - '(lambda () (auto-fill-mode 1))) -@end example - -This shows how to add a hook function to a normal hook variable -(@pxref{Hooks}). The function we supply is a list starting with -@code{lambda}, with a single-quote in front of it to make it a list -constant rather than an expression. - -It's beyond the scope of this manual to explain Lisp functions, but for -this example it is enough to know that the effect is to execute -@code{(auto-fill-mode 1)} when Text mode is entered. You can replace -that with any other expression that you like, or with several -expressions in a row. - -Emacs comes with a function named @code{turn-on-auto-fill} whose -definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler -way to write the above example is as follows: - -@example -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end example - -@item -Load the installed Lisp library named @file{foo} (actually a file -@file{foo.elc} or @file{foo.el} in a standard Emacs directory). - -@example -(load "foo") -@end example - -When the argument to @code{load} is a relative file name, not starting -with @samp{/} or @samp{~}, @code{load} searches the directories in -@code{load-path} (@pxref{Lisp Libraries}). - -@item -Load the compiled Lisp file @file{foo.elc} from your home directory. - -@example -(load "~/foo.elc") -@end example - -Here an absolute file name is used, so no searching is done. - -@item -@cindex loading Lisp libraries automatically -@cindex autoload Lisp libraries -Tell Emacs to find the definition for the function @code{myfunction} -by loading a Lisp library named @file{mypackage} (i.e.@: a file -@file{mypackage.elc} or @file{mypackage.el}): - -@example -(autoload 'myfunction "mypackage" "Do what I say." t) -@end example - -@noindent -Here the string @code{"Do what I say."} is the function's -documentation string. You specify it in the @code{autoload} -definition so it will be available for help commands even when the -package is not loaded. The last argument, @code{t}, indicates that -this function is interactive; that is, it can be invoked interactively -by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. -If the function is not interactive, omit the @code{t} or use -@code{nil}. - -@item -Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} -(@pxref{Init Rebinding}). - -@example -(global-set-key "\C-xl" 'make-symbolic-link) -@end example - -or - -@example -(define-key global-map "\C-xl" 'make-symbolic-link) -@end example - -Note once again the single-quote used to refer to the symbol -@code{make-symbolic-link} instead of its value as a variable. - -@item -Do the same thing for Lisp mode only. - -@example -(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) -@end example - -@item -Redefine all keys which now run @code{next-line} in Fundamental mode -so that they run @code{forward-line} instead. - -@findex substitute-key-definition -@example -(substitute-key-definition 'next-line 'forward-line - global-map) -@end example - -@item -Make @kbd{C-x C-v} undefined. - -@example -(global-unset-key "\C-x\C-v") -@end example - -One reason to undefine a key is so that you can make it a prefix. -Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a -prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix -definition. - -@item -Make @samp{$} have the syntax of punctuation in Text mode. -Note the use of a character constant for @samp{$}. - -@example -(modify-syntax-entry ?\$ "." text-mode-syntax-table) -@end example - -@item -Enable the use of the command @code{narrow-to-region} without confirmation. - -@example -(put 'narrow-to-region 'disabled nil) -@end example - -@item -Adjusting the configuration to various platforms and Emacs versions. - -Users typically want Emacs to behave the same on all systems, so the -same init file is right for all platforms. However, sometimes it -happens that a function you use for customizing Emacs is not available -on some platforms or in older Emacs versions. To deal with that -situation, put the customization inside a conditional that tests whether -the function or facility is available, like this: - -@example -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode 0)) - -(if (boundp 'coding-category-utf-8) - (set-coding-priority '(coding-category-utf-8))) -@end example - -@noindent -You can also simply disregard the errors that occur if the -function is not defined. - -@example -(condition case () - (set-face-background 'region "grey75") - (error nil)) -@end example - -A @code{setq} on a variable which does not exist is generally -harmless, so those do not need a conditional. -@end itemize - -@node Terminal Init -@subsection Terminal-specific Initialization - - Each terminal type can have a Lisp library to be loaded into Emacs when -it is run on that type of terminal. For a terminal type named -@var{termtype}, the library is called @file{term/@var{termtype}} and it is -found by searching the directories @code{load-path} as usual and trying the -suffixes @samp{.elc} and @samp{.el}. Normally it appears in the -subdirectory @file{term} of the directory where most Emacs libraries are -kept.@refill - - The usual purpose of the terminal-specific library is to map the -escape sequences used by the terminal's function keys onto more -meaningful names, using @code{function-key-map}. See the file -@file{term/lk201.el} for an example of how this is done. Many function -keys are mapped automatically according to the information in the -Termcap data base; the terminal-specific library needs to map only the -function keys that Termcap does not specify. - - When the terminal type contains a hyphen, only the part of the name -before the first hyphen is significant in choosing the library name. -Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use -the library @file{term/aaa}. The code in the library can use -@code{(getenv "TERM")} to find the full terminal type name.@refill - -@vindex term-file-prefix - The library's name is constructed by concatenating the value of the -variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} -file can prevent the loading of the terminal-specific library by setting -@code{term-file-prefix} to @code{nil}. - -@vindex term-setup-hook - Emacs runs the hook @code{term-setup-hook} at the end of -initialization, after both your @file{.emacs} file and any -terminal-specific library have been read in. Add hook functions to this -hook if you wish to override part of any of the terminal-specific -libraries and to define initializations for terminals that do not have a -library. @xref{Hooks}. - -@node Find Init -@subsection How Emacs Finds Your Init File - - Normally Emacs uses the environment variable @env{HOME} -(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what -@samp{~} means in a file name. If @file{.emacs} is not found inside -@file{~/} (nor @file{.emacs.el}), Emacs looks for -@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be -byte-compiled). - - However, if you run Emacs from a shell started by @code{su}, Emacs -tries to find your own @file{.emacs}, not that of the user you are -currently pretending to be. The idea is that you should get your own -editor customizations even if you are running as the super user. - - More precisely, Emacs first determines which user's init file to use. -It gets your user name from the environment variables @env{LOGNAME} and -@env{USER}; if neither of those exists, it uses effective user-ID. -If that user name matches the real user-ID, then Emacs uses @env{HOME}; -otherwise, it looks up the home directory corresponding to that user -name in the system's data base of users. -@c LocalWords: backtab - -@node Init Non-ASCII -@subsection Non-@acronym{ASCII} Characters in Init Files -@cindex international characters in @file{.emacs} -@cindex non-@acronym{ASCII} characters in @file{.emacs} -@cindex non-@acronym{ASCII} keys, binding -@cindex rebinding non-@acronym{ASCII} keys - - Language and coding systems may cause problems if your init file -contains non-@acronym{ASCII} characters, such as accented letters, in -strings or key bindings. - - If you want to use non-@acronym{ASCII} characters in your init file, -you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on -the first line of the init file, and specify a coding system that -supports the character(s) in question. @xref{Recognize Coding}. This -is because the defaults for decoding non-@acronym{ASCII} text might -not yet be set up by the time Emacs reads those parts of your init -file which use such strings, possibly leading Emacs to decode those -strings incorrectly. You should then avoid adding Emacs Lisp code -that modifies the coding system in other ways, such as calls to -@code{set-language-environment}. - - To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init -Rebinding}). The string syntax cannot be used, since the -non-@acronym{ASCII} characters will be interpreted as meta keys. For -instance: - -@example -(global-set-key [?@var{char}] 'some-function) -@end example - -@noindent -Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. - - @strong{Warning:} if you change the keyboard encoding, or change -between multibyte and unibyte mode, or anything that would alter which -code @kbd{C-q} would insert for that character, this keybinding may -stop working. It is therefore advisable to use one and only one -coding system, for your init file as well as the files you edit. For -example, don't mix the @samp{latin-1} and @samp{latin-9} coding -systems. - -@ignore - arch-tag: c68abddb-4410-4fb5-925f-63394e971d93 -@end ignore diff --git a/man/dired-x.texi b/man/dired-x.texi deleted file mode 100644 index bf2d5288abc..00000000000 --- a/man/dired-x.texi +++ /dev/null @@ -1,1275 +0,0 @@ -\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/man/dired-xtra.texi b/man/dired-xtra.texi deleted file mode 100644 index e8fdf8ab468..00000000000 --- a/man/dired-xtra.texi +++ /dev/null @@ -1,49 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Subdir Switches -@section Subdirectory Switches in Dired - -You can insert subdirectories with specified @code{ls} switches in -Dired buffers, using @kbd{C-u i}. You can change the @code{ls} -switches of an already inserted subdirectory using @kbd{C-u l}. - -In Emacs versions 22.1 and later, Dired remembers the switches, so -that reverting the buffer will not change them back to the main -directory's switches. Deleting a subdirectory forgets about its -switches. - -Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) -to reinsert or delete subdirectories, that were inserted with explicit -switches, can bypass Dired's machinery for remembering (or forgetting) -switches. Deleting a subdirectory using @code{dired-undo} does not -forget its switches. When later reinserted using @kbd{i}, it will be -reinserted using its old switches. Using @code{dired-undo} to -reinsert a subdirectory that was deleted using the regular -Dired commands (not @code{dired-undo}) will originally insert it with -its old switches. However, reverting the buffer will relist it using -the buffer's default switches. If any of this yields problems, you -can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. - -Dired does not remember the @code{R} switch. Inserting a subdirectory -with switches that include the @code{R} switch is equivalent with -inserting each of its subdirectories using all remaining switches. -For instance, updating or killing a subdirectory that was inserted -with the @code{R} switch will not update or kill its subdirectories. - -The buffer's default switches do not affect subdirectories that were -inserted using explicitly specified switches. In particular, -commands such as @kbd{s}, that change the buffer's switches do not -affect such subdirectories. (They do affect subdirectories without -explicitly assigned switches, however.) - -You can make Dired forget about all subdirectory switches and relist -all subdirectories with the buffer's default switches using -@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. - -@ignore - arch-tag: e3865701-9179-4ffb-bc34-d321111c688d -@end ignore diff --git a/man/dired.texi b/man/dired.texi deleted file mode 100644 index 3dda3f588eb..00000000000 --- a/man/dired.texi +++ /dev/null @@ -1,1317 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Dired, Calendar/Diary, Rmail, Top -@chapter Dired, the Directory Editor -@cindex Dired -@cindex file management - - Dired makes an Emacs buffer containing a listing of a directory, and -optionally some of its subdirectories as well. You can use the normal -Emacs commands to move around in this buffer, and special Dired commands -to operate on the files listed. - - The Dired buffer is ``read-only,'' and inserting text in it is not -useful, so ordinary printing characters such as @kbd{d} and @kbd{x} -are redefined for special Dired commands. Some Dired commands -@dfn{mark} or @dfn{flag} the @dfn{current file} (that is, the file on -the current line); other commands operate on the marked files or on -the flagged files. You first mark certain files in order to operate -on all of them with on command. - - The Dired-X package provides various extra features for Dired mode. -@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}. - -@menu -* Enter: Dired Enter. How to invoke Dired. -* Navigation: Dired Navigation. Special motion commands in the Dired buffer. -* Deletion: Dired Deletion. Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Visit: Dired Visiting. Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running `diff' by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -@ifnottex -* Subdir Switches:: Subdirectory switches in Dired. -@end ifnottex -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Updating: Dired Updating. Discarding lines for files of no interest. -* Find: Dired and Find. Using `find' to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired -* Misc: Misc Dired Features. Various other features. -@end menu - -@node Dired Enter -@section Entering Dired - -@findex dired -@kindex C-x d -@vindex dired-listing-switches - To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}. The command -reads a directory name or wildcard file name pattern as a minibuffer -argument to specify the files to list. @kbd{C-x C-f} given a -directory name also invokes Dired. Where @code{dired} differs from -@code{list-directory} is that it puts the buffer into Dired mode, so -that the special commands of Dired are available. - - The variable @code{dired-listing-switches} specifies the options to -give to @code{ls} for listing the directory; this string @emph{must} -contain @samp{-l}. If you use a numeric prefix argument with the -@code{dired} command, you can specify the @code{ls} switches with the -minibuffer before you enter the directory specification. No matter -how they are specified, the @code{ls} switches can include short -options (that is, single characters) requiring no arguments, and long -options (starting with @samp{--}) whose arguments are specified with -@samp{=}. - - On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls}; -see @ref{ls in Lisp}, for options and peculiarities of that emulation. - - -@findex dired-other-window -@kindex C-x 4 d -@findex dired-other-frame -@kindex C-x 5 d - To display the Dired buffer in another window rather than in the -selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead -of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a -separate frame to display the Dired buffer. - -@node Dired Navigation -@section Navigation in the Dired Buffer - -@kindex C-n @r{(Dired)} -@kindex C-p @r{(Dired)} - All the usual Emacs cursor motion commands are available in Dired -buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the -cursor at the beginning of the file name on the line, rather than at -the beginning of the line. - -@kindex SPC @r{(Dired)} - For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent -to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines is -so common in Dired that it deserves to be easy to type.) @key{DEL} -(move up and unflag) is often useful simply for moving up. - -@findex dired-goto-file -@kindex j @r{(Dired)} - @kbd{j} (@code{dired-goto-file}) moves point to the line that -describes a specified file or directory. - - Some additional navigation commands are available when the Dired -buffer includes several directories. @xref{Subdirectory Motion}. - -@node Dired Deletion -@section Deleting Files with Dired -@cindex flagging files (in Dired) -@cindex deleting files (in Dired) - - One of the most frequent uses of Dired is to first @dfn{flag} files for -deletion, then delete the files that were flagged. - -@table @kbd -@item d -Flag this file for deletion. -@item u -Remove deletion flag on this line. -@item @key{DEL} -Move point to previous line and remove the deletion flag on that line. -@item x -Delete the files that are flagged for deletion. -@end table - -@kindex d @r{(Dired)} -@findex dired-flag-file-deletion - You can flag a file for deletion by moving to the line describing -the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The -deletion flag is visible as a @samp{D} at the beginning of the line. -This command moves point to the next line, so that repeated @kbd{d} -commands flag successive files. A numeric argument serves as a repeat -count. - -@kindex u @r{(Dired deletion)} -@kindex DEL @r{(Dired)} - The reason for flagging files for deletion, rather than deleting -files immediately, is to reduce the danger of deleting a file -accidentally. Until you direct Dired to delete the flagged files, you -can remove deletion flags using the commands @kbd{u} and @key{DEL}. -@kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes -flags rather than making flags. @key{DEL} -(@code{dired-unmark-backward}) moves upward, removing flags; it is -like @kbd{u} with argument @minus{}1. - -@kindex x @r{(Dired)} -@findex dired-do-flagged-delete -@cindex expunging (Dired) - To delete the flagged files, type @kbd{x} -(@code{dired-do-flagged-delete}). (This is also known as -@dfn{expunging}.) This command first displays a list of all the file -names flagged for deletion, and requests confirmation with @kbd{yes}. -If you confirm, Dired deletes the flagged files, then deletes their -lines from the text of the Dired buffer. The Dired buffer, with -somewhat fewer lines, remains selected. - - If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you -return immediately to Dired, with the deletion flags still present in -the buffer, and no files actually deleted. - -@cindex recursive deletion -@vindex dired-recursive-deletes - You can delete empty directories just like other files, but normally -Dired cannot delete directories that are nonempty. If the variable -@code{dired-recursive-deletes} is non-@code{nil}, then Dired can -delete nonempty directories including all their contents. That can -be somewhat risky. - -@node Flagging Many Files -@section Flagging Many Files at Once -@cindex flagging many files for deletion (in Dired) - -@table @kbd -@item # -Flag all auto-save files (files whose names start and end with @samp{#}) -for deletion (@pxref{Auto Save}). - -@item ~ -Flag all backup files (files whose names end with @samp{~}) for deletion -(@pxref{Backup}). - -@item & -Flag for deletion all files with certain kinds of names which suggest -you could easily create those files again. - -@item .@: @r{(Period)} -Flag excess numeric backup files for deletion. The oldest and newest -few backup files of any one file are exempt; the middle ones are -flagged. - -@item % d @var{regexp} @key{RET} -Flag for deletion all files whose names match the regular expression -@var{regexp}. -@end table - - The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for -deletion, based on their file names. These commands are useful -precisely because they do not themselves delete any files; you can -remove the deletion flags from any flagged files that you really wish to -keep.@refill - -@kindex & @r{(Dired)} -@findex dired-flag-garbage-files -@vindex dired-garbage-files-regexp -@cindex deleting some backup files - @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names -match the regular expression specified by the variable -@code{dired-garbage-files-regexp}. By default, this matches certain -files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and -@samp{.rej} files produced by @code{patch}. - -@kindex # @r{(Dired)} -@findex dired-flag-auto-save-files -@cindex deleting auto-save files - @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all -files whose names look like auto-save files---that is, files whose -names begin and end with @samp{#}. @xref{Auto Save}. - -@kindex ~ @r{(Dired)} -@findex dired-flag-backup-files - @kbd{~} (@code{dired-flag-backup-files}) flags for deletion all -files whose names say they are backup files---that is, files whose -names end in @samp{~}. @xref{Backup}. - -@kindex . @r{(Dired)} -@vindex dired-kept-versions -@findex dired-clean-directory - @kbd{.} (period, @code{dired-clean-directory}) flags just some of the -backup files for deletion: all but the oldest few and newest few backups -of any one file. Normally @code{dired-kept-versions} (@strong{not} -@code{kept-new-versions}; that applies only when saving) specifies the -number of newest versions of each file to keep, and -@code{kept-old-versions} specifies the number of oldest versions to -keep. - - Period with a positive numeric argument, as in @kbd{C-u 3 .}, -specifies the number of newest versions to keep, overriding -@code{dired-kept-versions}. A negative numeric argument overrides -@code{kept-old-versions}, using minus the value of the argument to -specify the number of oldest versions of each file to keep. - -@findex dired-flag-files-regexp -@kindex % d @r{(Dired)} - The @kbd{% d} command flags all files whose names match a specified -regular expression (@code{dired-flag-files-regexp}). Only the -non-directory part of the file name is used in matching. You can use -@samp{^} and @samp{$} to anchor matches. You can exclude certain -subdirectories from marking by hiding them while you use @kbd{% d}. -@xref{Hiding Subdirectories}. - -@node Dired Visiting -@section Visiting Files in Dired - - There are several Dired commands for visiting or examining the files -listed in the Dired buffer. All of them apply to the current line's -file; if that file is really a directory, these commands invoke Dired on -that subdirectory (making a separate Dired buffer). - -@table @kbd -@item f -@kindex f @r{(Dired)} -@findex dired-find-file -Visit the file described on the current line, like typing @kbd{C-x C-f} -and supplying that file name (@code{dired-find-file}). @xref{Visiting}. - -@item @key{RET} -@itemx e -@kindex RET @r{(Dired)} -@kindex e @r{(Dired)} -Equivalent to @kbd{f}. - -@ignore @c This command seems too risky to document at all. -@item a -@kindex a @r{(Dired)} -@findex dired-find-alternate-file -Like @kbd{f}, but replaces the contents of the Dired buffer with -that of an alternate file or directory (@code{dired-find-alternate-file}). -@end ignore - -@item o -@kindex o @r{(Dired)} -@findex dired-find-file-other-window -Like @kbd{f}, but uses another window to display the file's buffer -(@code{dired-find-file-other-window}). The Dired buffer remains visible -in the first window. This is like using @kbd{C-x 4 C-f} to visit the -file. @xref{Windows}. - -@item C-o -@kindex C-o @r{(Dired)} -@findex dired-display-file -Visit the file described on the current line, and display the buffer in -another window, but do not select that window (@code{dired-display-file}). - -@item Mouse-1 -@itemx Mouse-2 -@findex dired-mouse-find-file-other-window -Visit the file named by the line you click on -(@code{dired-mouse-find-file-other-window}). This uses another window -to display the file, like the @kbd{o} command. - -@item v -@kindex v @r{(Dired)} -@findex dired-view-file -View the file described on the current line, using @kbd{M-x view-file} -(@code{dired-view-file}). Viewing a file with @code{view-file} is -like visiting it, but is slanted toward moving around in the file -conveniently and does not allow changing the file. @xref{Misc File -Ops, View File, Miscellaneous File Operations}. - -@item ^ -@kindex ^ @r{(Dired)} -@findex dired-up-directory -Visit the parent directory of the current directory -(@code{dired-up-directory}). This is equivalent to moving to the line -for @file{..} and typing @kbd{f} there. -@end table - -@node Marks vs Flags -@section Dired Marks vs. Flags - -@cindex marking many files (in Dired) - Instead of flagging a file with @samp{D}, you can @dfn{mark} the -file with some other character (usually @samp{*}). Most Dired -commands to operate on files use the files marked with @samp{*}. The -only command that operates on flagged files is @kbd{x}, which expunges -them. - - Here are some commands for marking with @samp{*}, for unmarking, and -for operating on marks. (@xref{Dired Deletion}, for commands to flag -and unflag files.) - -@table @kbd -@item m -@itemx * m -@kindex m @r{(Dired)} -@kindex * m @r{(Dired)} -@findex dired-mark -Mark the current file with @samp{*} (@code{dired-mark}). With a numeric -argument @var{n}, mark the next @var{n} files starting with the current -file. (If @var{n} is negative, mark the previous @minus{}@var{n} -files.) - -@item * * -@kindex * * @r{(Dired)} -@findex dired-mark-executables -@cindex marking executable files (in Dired) -Mark all executable files with @samp{*} -(@code{dired-mark-executables}). With a numeric argument, unmark all -those files. - -@item * @@ -@kindex * @@ @r{(Dired)} -@findex dired-mark-symlinks -@cindex marking symbolic links (in Dired) -Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). -With a numeric argument, unmark all those files. - -@item * / -@kindex * / @r{(Dired)} -@findex dired-mark-directories -@cindex marking subdirectories (in Dired) -Mark with @samp{*} all files which are directories, except for -@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric -argument, unmark all those files. - -@item * s -@kindex * s @r{(Dired)} -@findex dired-mark-subdir-files -Mark all the files in the current subdirectory, aside from @file{.} -and @file{..} (@code{dired-mark-subdir-files}). - -@item u -@itemx * u -@kindex u @r{(Dired)} -@kindex * u @r{(Dired)} -@findex dired-unmark -Remove any mark on this line (@code{dired-unmark}). - -@item @key{DEL} -@itemx * @key{DEL} -@kindex * DEL @r{(Dired)} -@findex dired-unmark-backward -@cindex unmarking files (in Dired) -Move point to previous line and remove any mark on that line -(@code{dired-unmark-backward}). - -@item * ! -@itemx U -@kindex * ! @r{(Dired)} -@kindex U @r{(Dired)} -@findex dired-unmark-all-marks -Remove all marks from all the files in this Dired buffer -(@code{dired-unmark-all-marks}). - -@item * ? @var{markchar} -@itemx M-@key{DEL} -@kindex * ? @r{(Dired)} -@kindex M-DEL @r{(Dired)} -@findex dired-unmark-all-files -Remove all marks that use the character @var{markchar} -(@code{dired-unmark-all-files}). The argument is a single -character---do not use @key{RET} to terminate it. See the description -of the @kbd{* c} command below, which lets you replace one mark -character with another. - -With a numeric argument, this command queries about each marked file, -asking whether to remove its mark. You can answer @kbd{y} meaning yes, -@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining -files without asking about them. - -@item * C-n -@itemx M-@} -@findex dired-next-marked-file -@kindex * C-n @r{(Dired)} -@kindex M-@} @r{(Dired)} -Move down to the next marked file (@code{dired-next-marked-file}) -A file is ``marked'' if it has any kind of mark. - -@item * C-p -@itemx M-@{ -@findex dired-prev-marked-file -@kindex * C-p @r{(Dired)} -@kindex M-@{ @r{(Dired)} -Move up to the previous marked file (@code{dired-prev-marked-file}) - -@item t -@itemx * t -@kindex t @r{(Dired)} -@kindex * t @r{(Dired)} -@findex dired-toggle-marks -@cindex toggling marks (in Dired) -Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*} -become unmarked, and unmarked files are marked with @samp{*}. Files -marked in any other way are not affected. - -@item * c @var{old-markchar} @var{new-markchar} -@kindex * c @r{(Dired)} -@findex dired-change-marks -Replace all marks that use the character @var{old-markchar} with marks -that use the character @var{new-markchar} (@code{dired-change-marks}). -This command is the primary way to create or use marks other than -@samp{*} or @samp{D}. The arguments are single characters---do not use -@key{RET} to terminate them. - -You can use almost any character as a mark character by means of this -command, to distinguish various classes of files. If @var{old-markchar} -is a space (@samp{ }), then the command operates on all unmarked files; -if @var{new-markchar} is a space, then the command unmarks the files it -acts on. - -To illustrate the power of this command, here is how to put @samp{D} -flags on all the files that have no marks, while unflagging all those -that already have @samp{D} flags: - -@example -* c D t * c SPC D * c t SPC -@end example - -This assumes that no files were already marked with @samp{t}. - -@item % m @var{regexp} @key{RET} -@itemx * % @var{regexp} @key{RET} -@findex dired-mark-files-regexp -@kindex % m @r{(Dired)} -@kindex * % @r{(Dired)} -Mark (with @samp{*}) all files whose names match the regular expression -@var{regexp} (@code{dired-mark-files-regexp}). This command is like -@kbd{% d}, except that it marks files with @samp{*} instead of flagging -with @samp{D}. - -Only the non-directory part of the file name is used in matching. Use -@samp{^} and @samp{$} to anchor matches. You can exclude -subdirectories by temporarily hiding them (@pxref{Hiding -Subdirectories}). - -@item % g @var{regexp} @key{RET} -@findex dired-mark-files-containing-regexp -@kindex % g @r{(Dired)} -@cindex finding files containing regexp matches (in Dired) -Mark (with @samp{*}) all files whose @emph{contents} contain a match for -the regular expression @var{regexp} -(@code{dired-mark-files-containing-regexp}). This command is like -@kbd{% m}, except that it searches the file contents instead of the file -name. - -@item C-x u -@itemx C-_ -@itemx C-/ -@kindex C-_ @r{(Dired)} -@findex dired-undo -Undo changes in the Dired buffer, such as adding or removing -marks (@code{dired-undo}). @emph{This command does not revert the -actual file operations, nor recover lost files!} It just undoes -changes in the buffer itself. - -In some cases, using this after commands that operate on files can -cause trouble. For example, after renaming one or more files, -@code{dired-undo} restores the original names in the Dired buffer, -which gets the Dired buffer out of sync with the actual contents of -the directory. -@end table - -@node Operating on Files -@section Operating on Files -@cindex operating on files in Dired - - This section describes the basic Dired commands to operate on one file -or several files. All of these commands are capital letters; all of -them use the minibuffer, either to read an argument or to ask for -confirmation, before they act. All of them let you specify the -files to manipulate in these ways: - -@itemize @bullet -@item -If you give the command a numeric prefix argument @var{n}, it operates -on the next @var{n} files, starting with the current file. (If @var{n} -is negative, the command operates on the @minus{}@var{n} files preceding -the current line.) - -@item -Otherwise, if some files are marked with @samp{*}, the command operates -on all those files. - -@item -Otherwise, the command operates on the current file only. -@end itemize - -@noindent -Certain other Dired commands, such as @kbd{!} and the @samp{%} -commands, use the same conventions to decide which files to work on. - -@vindex dired-dwim-target -@cindex two directories (in Dired) - Commands which ask for a destination directory, such as those which -copy and rename files or create links for them, try to guess the default -target directory for the operation. Normally, they suggest the Dired -buffer's default directory, but if the variable @code{dired-dwim-target} -is non-@code{nil}, and if there is another Dired buffer displayed in the -next window, that other buffer's directory is suggested instead. - - Here are the file-manipulating Dired commands that operate on files. - -@table @kbd -@findex dired-do-copy -@kindex C @r{(Dired)} -@cindex copying files (in Dired) -@item C @var{new} @key{RET} -Copy the specified files (@code{dired-do-copy}). The argument @var{new} -is the directory to copy into, or (if copying a single file) the new -name. This is like the shell command @code{cp}. - -@vindex dired-copy-preserve-time -If @code{dired-copy-preserve-time} is non-@code{nil}, then copying -with this command preserves the modification time of the old file in -the copy, like @samp{cp -p}. - -@vindex dired-recursive-copies -@cindex recursive copying -The variable @code{dired-recursive-copies} controls whether to copy -directories recursively (like @samp{cp -r}). The default is -@code{nil}, which means that directories cannot be copied. - -@item D -@findex dired-do-delete -@kindex D @r{(Dired)} -Delete the specified files (@code{dired-do-delete}). This is like the -shell command @code{rm}. - -Like the other commands in this section, this command operates on the -@emph{marked} files, or the next @var{n} files. By contrast, @kbd{x} -(@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files. - -@findex dired-do-rename -@kindex R @r{(Dired)} -@cindex renaming files (in Dired) -@cindex moving files (in Dired) -@item R @var{new} @key{RET} -Rename the specified files (@code{dired-do-rename}). If you rename a -single file, the argument @var{new} is the new name of the file. If -you rename several files, the argument @var{new} is the directory into -which to move the files (this is like the shell command @code{mv}). - -Dired automatically changes the visited file name of buffers associated -with renamed files so that they refer to the new names. - -@findex dired-do-hardlink -@kindex H @r{(Dired)} -@cindex hard links (in Dired) -@item H @var{new} @key{RET} -Make hard links to the specified files (@code{dired-do-hardlink}). -This is like the shell command @code{ln}. The argument @var{new} is -the directory to make the links in, or (if making just one link) the -name to give the link. - -@findex dired-do-symlink -@kindex S @r{(Dired)} -@cindex symbolic links (creation in Dired) -@item S @var{new} @key{RET} -Make symbolic links to the specified files (@code{dired-do-symlink}). -This is like @samp{ln -s}. The argument @var{new} is the directory to -make the links in, or (if making just one link) the name to give the -link. - -@findex dired-do-chmod -@kindex M @r{(Dired)} -@cindex changing file permissions (in Dired) -@item M @var{modespec} @key{RET} -Change the mode (also called ``permission bits'') of the specified files -(@code{dired-do-chmod}). This uses the @code{chmod} program, so -@var{modespec} can be any argument that @code{chmod} can handle. - -@findex dired-do-chgrp -@kindex G @r{(Dired)} -@cindex changing file group (in Dired) -@item G @var{newgroup} @key{RET} -Change the group of the specified files to @var{newgroup} -(@code{dired-do-chgrp}). - -@findex dired-do-chown -@kindex O @r{(Dired)} -@cindex changing file owner (in Dired) -@item O @var{newowner} @key{RET} -Change the owner of the specified files to @var{newowner} -(@code{dired-do-chown}). (On most systems, only the superuser can do -this.) - -@vindex dired-chown-program -The variable @code{dired-chown-program} specifies the name of the -program to use to do the work (different systems put @code{chown} in -different places). - -@findex dired-do-touch -@kindex T @r{(Dired)} -@cindex changing file time (in Dired) -@item T @var{timestamp} @key{RET} -Touch the specified files (@code{dired-do-touch}). This means -updating their modification times to the present time. This is like -the shell command @code{touch}. - -@findex dired-do-print -@kindex P @r{(Dired)} -@cindex printing files (in Dired) -@item P @var{command} @key{RET} -Print the specified files (@code{dired-do-print}). You must specify the -command to print them with, but the minibuffer starts out with a -suitable guess made using the variables @code{lpr-command} and -@code{lpr-switches} (the same variables that @code{lpr-buffer} uses; -@pxref{Printing}). - -@findex dired-do-compress -@kindex Z @r{(Dired)} -@cindex compressing files (in Dired) -@item Z -Compress the specified files (@code{dired-do-compress}). If the file -appears to be a compressed file already, uncompress it instead. - -@findex dired-do-load -@kindex L @r{(Dired)} -@cindex loading several files (in Dired) -@item L -Load the specified Emacs Lisp files (@code{dired-do-load}). -@xref{Lisp Libraries}. - -@findex dired-do-byte-compile -@kindex B @r{(Dired)} -@cindex byte-compiling several files (in Dired) -@item B -Byte compile the specified Emacs Lisp files -(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte -Compilation, elisp, The Emacs Lisp Reference Manual}. - -@kindex A @r{(Dired)} -@findex dired-do-search -@cindex search multiple files (in Dired) -@item A @var{regexp} @key{RET} -Search all the specified files for the regular expression @var{regexp} -(@code{dired-do-search}). - -This command is a variant of @code{tags-search}. The search stops at -the first match it finds; use @kbd{M-,} to resume the search and find -the next match. @xref{Tags Search}. - -@kindex Q @r{(Dired)} -@findex dired-do-query-replace-regexp -@cindex search and replace in multiple files (in Dired) -@item Q @var{regexp} @key{RET} @var{to} @key{RET} -Perform @code{query-replace-regexp} on each of the specified files, -replacing matches for @var{regexp} with the string -@var{to} (@code{dired-do-query-replace-regexp}). - -This command is a variant of @code{tags-query-replace}. If you exit the -query replace loop, you can use @kbd{M-,} to resume the scan and replace -more matches. @xref{Tags Search}. -@end table - -@node Shell Commands in Dired -@section Shell Commands in Dired -@cindex shell commands, Dired - -@findex dired-do-shell-command -@kindex ! @r{(Dired)} -@kindex X @r{(Dired)} -The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a -shell command string in the minibuffer and runs that shell command on -all the specified files. (@kbd{X} is a synonym for @kbd{!}.) You can -specify the files to operate on in the usual ways for Dired commands -(@pxref{Operating on Files}). - - The working directory for the shell command is the top-level directory -of the Dired buffer. - - There are two ways of applying a shell command to multiple files: - -@itemize @bullet -@item -If you use @samp{*} surrounded by whitespace in the shell command, -then the command runs just once, with the list of file names -substituted for the @samp{*}. The order of file names is the order of -appearance in the Dired buffer. - -Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire -list of file names, putting them into one tar file @file{foo.tar}. - -If you want to use @samp{*} as a shell wildcard with whitespace around -it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; -but since the @samp{*} is not surrounded by whitespace, Dired does -not treat it specially. - -@item -If the command string doesn't contain @samp{*} surrounded by -whitespace, then it runs once @emph{for each file}. Normally the file -name is added at the end. - -For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each -file. - -@item -However, if the command string contains @samp{?} surrounded by -whitespace, the current file name is substituted for @samp{?} (rather -than added at the end). You can use @samp{?} this way more than once -in the command, and the same file name replaces each occurrence. -@end itemize - - To iterate over the file names in a more complicated fashion, use an -explicit shell loop. For example, here is how to uuencode each file, -making the output file name by appending @samp{.uu} to the input file -name: - -@example -for file in * ; do uuencode "$file" "$file" >"$file".uu; done -@end example - - The @kbd{!} command does not attempt to update the Dired buffer to -show new or modified files, because it doesn't understand shell -commands, and does not know what files the shell command changed. Use -the @kbd{g} command to update the Dired buffer (@pxref{Dired -Updating}). - -@node Transforming File Names -@section Transforming File Names in Dired - - This section describes Dired commands which alter file names in a -systematic way. Each command operates on some or all of the marked -files, using a new name made by transforming the existing name. - - Like the basic Dired file-manipulation commands (@pxref{Operating on -Files}), the commands described here operate either on the next -@var{n} files, or on all files marked with @samp{*}, or on the current -file. (To mark files, use the commands described in @ref{Marks vs -Flags}.) - - All of the commands described in this section work -@emph{interactively}: they ask you to confirm the operation for each -candidate file. Thus, you can select more files than you actually -need to operate on (e.g., with a regexp that matches many files), and -then filter the selected names by typing @kbd{y} or @kbd{n} when the -command prompts for confirmation. - -@table @kbd -@findex dired-upcase -@kindex % u @r{(Dired)} -@cindex upcase file names -@item % u -Rename each of the selected files to an upper-case name -(@code{dired-upcase}). If the old file names are @file{Foo} -and @file{bar}, the new names are @file{FOO} and @file{BAR}. - -@item % l -@findex dired-downcase -@kindex % l @r{(Dired)} -@cindex downcase file names -Rename each of the selected files to a lower-case name -(@code{dired-downcase}). If the old file names are @file{Foo} and -@file{bar}, the new names are @file{foo} and @file{bar}. - -@item % R @var{from} @key{RET} @var{to} @key{RET} -@kindex % R @r{(Dired)} -@findex dired-do-rename-regexp -@itemx % C @var{from} @key{RET} @var{to} @key{RET} -@kindex % C @r{(Dired)} -@findex dired-do-copy-regexp -@itemx % H @var{from} @key{RET} @var{to} @key{RET} -@kindex % H @r{(Dired)} -@findex dired-do-hardlink-regexp -@itemx % S @var{from} @key{RET} @var{to} @key{RET} -@kindex % S @r{(Dired)} -@findex dired-do-symlink-regexp -These four commands rename, copy, make hard links and make soft links, -in each case computing the new name by regular-expression substitution -from the name of the old file. -@end table - - The four regular-expression substitution commands effectively -perform a search-and-replace on the selected file names. They read -two arguments: a regular expression @var{from}, and a substitution -pattern @var{to}; they match each ``old'' file name against -@var{from}, and then replace the matching part with @var{to}. You can -use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or -part of what the pattern matched in the old file name, as in -@code{replace-regexp} (@pxref{Regexp Replace}). If the regular -expression matches more than once in a file name, only the first match -is replaced. - - For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each -selected file by prepending @samp{x-} to its name. The inverse of this, -removing @samp{x-} from the front of each file name, is also possible: -one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is -@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor -matches that should span the whole file name.) - - Normally, the replacement process does not consider the files' -directory names; it operates on the file name within the directory. If -you specify a numeric argument of zero, then replacement affects the -entire absolute file name including directory name. (A non-zero -argument specifies the number of files to operate on.) - - You may want to select the set of files to operate on using the same -regexp @var{from} that you will use to operate on them. To do this, -mark those files with @kbd{% m @var{from} @key{RET}}, then use the -same regular expression in the command to operate on the files. To -make this more convenient, the @kbd{%} commands to operate on files -use the last regular expression specified in any @kbd{%} command as a -default. - -@node Comparison in Dired -@section File Comparison with Dired -@cindex file comparison (in Dired) -@cindex compare files (in Dired) - - Here are two Dired commands that compare specified files using -@code{diff}. They show the output in a buffer using Diff mode -(@pxref{Comparing Files}). - -@table @kbd -@item = -@findex dired-diff -@kindex = @r{(Dired)} -Compare the current file (the file at point) with another file (the -file at the mark) using the @code{diff} program (@code{dired-diff}). -The file at the mark is the first argument of @code{diff}, and the -file at point is the second argument. This refers to the ordinary -Emacs mark, not Dired marks; use @kbd{C-@key{SPC}} -(@code{set-mark-command}) to set the mark at the first file's line -(@pxref{Setting Mark}). - -@findex dired-backup-diff -@kindex M-= @r{(Dired)} -@item M-= -Compare the current file with its latest backup file -(@code{dired-backup-diff}). If the current file is itself a backup, -compare it with the file it is a backup of; this way, you can compare -a file with any one of its backups. - -The backup file is the first file given to @code{diff}. -@end table - -@node Subdirectories in Dired -@section Subdirectories in Dired -@cindex subdirectories in Dired -@cindex expanding subdirectories in Dired - - A Dired buffer displays just one directory in the normal case; -but you can optionally include its subdirectories as well. - - The simplest way to include multiple directories in one Dired buffer is -to specify the options @samp{-lR} for running @code{ls}. (If you give a -numeric argument when you run Dired, then you can specify these options -in the minibuffer.) That produces a recursive directory listing showing -all subdirectories at all levels. - - More often, you will want to show only specific subdirectories. You -can do this with the @kbd{i} command: - -@table @kbd -@findex dired-maybe-insert-subdir -@kindex i @r{(Dired)} -@item i -@cindex inserted subdirectory (Dired) -@cindex in-situ subdirectory (Dired) -Insert the contents of a subdirectory later in the buffer. -@end table - -Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line -that describes a file which is a directory. It inserts the contents of -that directory into the same Dired buffer, and moves there. Inserted -subdirectory contents follow the top-level directory of the Dired -buffer, just as they do in @samp{ls -lR} output. - -If the subdirectory's contents are already present in the buffer, the -@kbd{i} command just moves to it. - -In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u -C-@key{SPC}} takes you back to the old position in the buffer (the line -describing that subdirectory). - -Use the @kbd{l} command (@code{dired-do-redisplay}) to update the -subdirectory's contents. Use @kbd{C-u k} on the subdirectory header -line to delete the subdirectory. @xref{Dired Updating}. - - - - -@ifnottex -@include dired-xtra.texi -@end ifnottex - -@node Subdirectory Motion -@section Moving Over Subdirectories - - When a Dired buffer lists subdirectories, you can use the page motion -commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories -(@pxref{Pages}). - -@cindex header line (Dired) -@cindex directory header lines - The following commands move across, up and down in the tree of -directories within one Dired buffer. They move to @dfn{directory header -lines}, which are the lines that give a directory's name, at the -beginning of the directory's contents. - -@table @kbd -@findex dired-next-subdir -@kindex C-M-n @r{(Dired)} -@item C-M-n -Go to next subdirectory header line, regardless of level -(@code{dired-next-subdir}). - -@findex dired-prev-subdir -@kindex C-M-p @r{(Dired)} -@item C-M-p -Go to previous subdirectory header line, regardless of level -(@code{dired-prev-subdir}). - -@findex dired-tree-up -@kindex C-M-u @r{(Dired)} -@item C-M-u -Go up to the parent directory's header line (@code{dired-tree-up}). - -@findex dired-tree-down -@kindex C-M-d @r{(Dired)} -@item C-M-d -Go down in the directory tree, to the first subdirectory's header line -(@code{dired-tree-down}). - -@findex dired-prev-dirline -@kindex < @r{(Dired)} -@item < -Move up to the previous directory-file line (@code{dired-prev-dirline}). -These lines are the ones that describe a directory as a file in its -parent directory. - -@findex dired-next-dirline -@kindex > @r{(Dired)} -@item > -Move down to the next directory-file line (@code{dired-prev-dirline}). -@end table - -@node Hiding Subdirectories -@section Hiding Subdirectories - -@cindex hiding in Dired (Dired) - @dfn{Hiding} a subdirectory means to make it invisible, except for its -header line. - -@table @kbd -@item $ -@findex dired-hide-subdir -@kindex $ @r{(Dired)} -Hide or reveal the subdirectory that point is in, and move point to the -next subdirectory (@code{dired-hide-subdir}). A numeric argument serves -as a repeat count. - -@item M-$ -@findex dired-hide-all -@kindex M-$ @r{(Dired)} -Hide all subdirectories in this Dired buffer, leaving only their header -lines (@code{dired-hide-all}). Or, if any subdirectory is currently -hidden, make all subdirectories visible again. You can use this command -to get an overview in very deep directory trees or to move quickly to -subdirectories far away. -@end table - - Ordinary Dired commands never consider files inside a hidden -subdirectory. For example, the commands to operate on marked files -ignore files in hidden directories even if they are marked. Thus you -can use hiding to temporarily exclude subdirectories from operations -without having to remove the Dired marks on files in those -subdirectories. - -@node Dired Updating -@section Updating the Dired Buffer -@cindex updating Dired buffer -@cindex refreshing displayed files - - This section describes commands to update the Dired buffer to reflect -outside (non-Dired) changes in the directories and files, and to delete -part of the Dired buffer. - -@table @kbd -@item g -Update the entire contents of the Dired buffer (@code{revert-buffer}). - -@item l -Update the specified files (@code{dired-do-redisplay}). You specify the -files for @kbd{l} in the same way as for file operations. - -@item k -Delete the specified @emph{file lines}---not the files, just the lines -(@code{dired-do-kill-lines}). - -@item s -Toggle between alphabetical order and date/time order -(@code{dired-sort-toggle-or-edit}). - -@item C-u s @var{switches} @key{RET} -Refresh the Dired buffer using @var{switches} as -@code{dired-listing-switches}. -@end table - -@kindex g @r{(Dired)} -@findex revert-buffer @r{(Dired)} - Type @kbd{g} (@code{revert-buffer}) to update the contents of the -Dired buffer, based on changes in the files and directories listed. -This preserves all marks except for those on files that have vanished. -Hidden subdirectories are updated but remain hidden. - -@kindex l @r{(Dired)} -@findex dired-do-redisplay - To update only some of the files, type @kbd{l} -(@code{dired-do-redisplay}). Like the Dired file-operating commands, -this command operates on the next @var{n} files (or previous -@minus{}@var{n} files), or on the marked files if any, or on the -current file. Updating the files means reading their current status, -then updating their lines in the buffer to indicate that status. - - If you use @kbd{l} on a subdirectory header line, it updates the -contents of the corresponding subdirectory. - -@kindex k @r{(Dired)} -@findex dired-do-kill-lines - To delete the specified @emph{file lines} from the buffer---not -delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like -the file-operating commands, this command operates on the next @var{n} -files, or on the marked files if any; but it does not operate on the -current file as a last resort. - - If you use @kbd{k} with a numeric prefix argument to kill the line -for a file that is a directory, which you have inserted in the Dired -buffer as a subdirectory, it deletes that subdirectory from the buffer -as well. Typing @kbd{C-u k} on the header line for a subdirectory -also deletes the subdirectory from the Dired buffer. - - The @kbd{g} command brings back any individual lines that you have -killed in this way, but not subdirectories---you must use @kbd{i} to -reinsert a subdirectory. - -@cindex Dired sorting -@cindex sorting Dired buffer -@kindex s @r{(Dired)} -@findex dired-sort-toggle-or-edit - The files in a Dired buffers are normally listed in alphabetical order -by file names. Alternatively Dired can sort them by date/time. The -Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches -between these two sorting modes. The mode line in a Dired buffer -indicates which way it is currently sorted---by name, or by date. - - @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for -@code{dired-listing-switches}. - -@node Dired and Find -@section Dired and @code{find} -@cindex @code{find} and Dired - - You can select a set of files for display in a Dired buffer more -flexibly by using the @code{find} utility to choose the files. - -@findex find-name-dired - To search for files with names matching a wildcard pattern use -@kbd{M-x find-name-dired}. It reads arguments @var{directory} and -@var{pattern}, and chooses all the files in @var{directory} or its -subdirectories whose individual names match @var{pattern}. - - The files thus chosen are displayed in a Dired buffer, in which the -ordinary Dired commands are available. - -@findex find-grep-dired - If you want to test the contents of files, rather than their names, -use @kbd{M-x find-grep-dired}. This command reads two minibuffer -arguments, @var{directory} and @var{regexp}; it chooses all the files in -@var{directory} or its subdirectories that contain a match for -@var{regexp}. It works by running the programs @code{find} and -@code{grep}. See also @kbd{M-x grep-find}, in @ref{Grep Searching}. -Remember to write the regular expression for @code{grep}, not for Emacs. -(An alternative method of showing files whose contents match a given -regexp is the @kbd{% g @var{regexp}} command, see @ref{Marks vs Flags}.) - -@findex find-dired - The most general command in this series is @kbd{M-x find-dired}, which -lets you specify any condition that @code{find} can test. It takes two -minibuffer arguments, @var{directory} and @var{find-args}; it runs -@code{find} in @var{directory}, passing @var{find-args} to tell -@code{find} what condition to test. To use this command, you need to -know how to use @code{find}. - -@vindex find-ls-option - The format of listing produced by these commands is controlled by the -variable @code{find-ls-option}, whose default value specifies using -options @samp{-ld} for @code{ls}. If your listings are corrupted, you -may need to change the value of this variable. - -@findex locate -@findex locate-with-filter -@cindex file database (locate) -@vindex locate-command - The command @kbd{M-x locate} provides a similar interface to the -@code{locate} program. @kbd{M-x locate-with-filter} is similar, but -keeps only files whose names match a given regular expression. - - These buffers don't work entirely like ordinary Dired buffers: file -operations work, but do not always automatically update the buffer. -Reverting the buffer with @kbd{g} deletes all inserted subdirectories, -and erases all flags and marks. - -@node Wdired -@section Editing the Dired Buffer - -@cindex wdired mode -@findex wdired-change-to-wdired-mode - Wdired is a special mode that allows you to perform file operations -by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands -for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q} or @kbd{M-x -wdired-change-to-wdired-mode} while in a Dired buffer. Alternatively, -use @samp{Edit File Names} in the @samp{Immediate} menu bar menu. - -@findex wdired-finish-edit - While in Wdired mode, you can rename files by editing the file names -displayed in the Dired buffer. All the ordinary Emacs editing -commands, including rectangle operations and @code{query-replace}, are -available for this. Once you are done editing, type @kbd{C-c C-c} -(@code{wdired-finish-edit}). This applies your changes and switches -back to ordinary Dired mode. - - Apart from simply renaming files, you can move a file to another -directory by typing in the new file name (either absolute or -relative). To mark a file for deletion, delete the entire file name. -To change the target of a symbolic link, edit the link target name -which appears next to the link name. - - The rest of the text in the buffer, such as the file sizes and -modification dates, is marked read-only, so you can't edit it. -However, if you set @code{wdired-allow-to-change-permissions} to -@code{t}, you can edit the file permissions. For example, you can -change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file -world-writable. These changes also take effect when you type @kbd{C-c -C-c}. - -@node Image-Dired -@section Viewing Image Thumbnails in Dired -@cindex image-dired mode -@cindex image-dired - - Image-Dired is a facility for browsing image files. It provides viewing -the images either as thumbnails or in full size, either inside Emacs -or through an external viewer. - -@kindex C-t d @r{(Image-Dired)} -@findex image-dired-display-thumbs - To enter Image-Dired, mark the image files you want to look at in -the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d} -(@code{image-dired-display-thumbs}). This creates and switches to a -buffer containing image-dired, corresponding to the marked files. - - You can also enter Image-Dired directly by typing @kbd{M-x -image-dired}. This prompts for a directory; specify one that has -image files. This creates thumbnails for all the images in that -directory, and displays them all in the ``thumbnail buffer.'' This -takes a long time if the directory contains many image files, and it -asks for confirmation if the number of image files exceeds -@code{image-dired-show-all-from-dir-max-files}. - - With point in the thumbnail buffer, you can type @kbd{RET} -(@code{image-dired-display-thumbnail-original-image}) to display a -sized version of it in another window. This sizes the image to fit -the window. Use the arrow keys to move around in the buffer. For -easy browsing, use @kbd{SPC} -(@code{image-dired-display-next-thumbnail-original}) to advance and -display the next image. Typing @kbd{DEL} -(@code{image-dired-display-previous-thumbnail-original}) backs up to -the previous thumbnail and displays that instead. - -@vindex image-dired-external-viewer - To view and the image in its original size, either provide a prefix -argument (@kbd{C-u}) before pressing @kbd{RET}, or type -@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to -display the image in an external viewer. You must first configure -@code{image-dired-external-viewer}. - - You can delete images through Image-Dired also. Type @kbd{d} -(@code{image-dired-flag-thumb-original-file}) to flag the image file -for deletion in the Dired buffer. You can also delete the thumbnail -image from the thumbnail buffer with @kbd{C-d} -(@code{image-dired-delete-char}). - - More advanced features include @dfn{image tags}, which are metadata -used to categorize image files. The tags are stored in a plain text -file configured by @code{image-dired-db-file}. - - To tag image files, mark them in the dired buffer (you can also mark -files in Dired from the thumbnail buffer by typing @kbd{m}) and type -@kbd{C-t t} (@code{image-dired-tag-files}). You will be prompted for -a tag. To mark files having a certain tag, type @kbd{C-t f} -(@code{image-dired-mark-tagged-files}). After marking image files -with a certain tag, you can use @kbd{C-t d} to view them. - - You can also tag a file directly from the thumbnail buffer by typing -@kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also -a special ``tag'' called ``comment'' for each file (it is not a tag in -the exact same sense as the other tags, it is handled slightly -different). That is used to enter a comment or description about the -image. You comment a file from the thumbnail buffer by typing -@kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add -a comment from Dired (@code{image-dired-dired-comment-files}). - - Image-Dired also provides simple image manipulation. In the -thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees -anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This -rotation is lossless, and uses an external utility called JpegTRAN. - -@node Misc Dired Features -@section Other Dired Features - -@kindex + @r{(Dired)} -@findex dired-create-directory - An unusual Dired file-operation command is @kbd{+} -(@code{dired-create-directory}). This command reads a directory name, -and creates the directory if it does not already exist. - -@cindex Adding to the kill ring in Dired. -@kindex w @r{(Dired)} -@findex dired-copy-filename-as-kill - The @kbd{w} command (@code{dired-copy-filename-as-kill}) puts the -names of the marked (or next @var{n}) files into the kill ring, as if -you had killed them with @kbd{C-w}. The names are separated by a space. - - With a zero prefix argument, this uses the absolute file name of -each marked file. With just @kbd{C-u} as the prefix argument, it uses -file names relative to the Dired buffer's default directory. (This -can still contain slashes if in a subdirectory.) As a special case, -if point is on a directory headerline, @kbd{w} gives you the absolute -name of that directory. Any prefix argument or marked files are -ignored in this case. - - The main purpose of this command is so that you can yank the file -names into arguments for other Emacs commands. It also displays what -it added to the kill ring, so you can use it to display the list of -currently marked files in the echo area. - -@findex dired-compare-directories - The command @kbd{M-x dired-compare-directories} is used to compare -the current Dired buffer with another directory. It marks all the files -that are ``different'' between the two directories. It puts these marks -in all Dired buffers where these files are listed, which of course includes -the current buffer. - - The default comparison method (used if you type @key{RET} at the -prompt) is to compare just the file names---each file name that does -not appear in the other directory is ``different.'' You can specify -more stringent comparisons by entering a Lisp expression, which can -refer to the variables @code{size1} and @code{size2}, the respective -file sizes; @code{mtime1} and @code{mtime2}, the last modification -times in seconds, as floating point numbers; and @code{fa1} and -@code{fa2}, the respective file attribute lists (as returned by the -function @code{file-attributes}). This expression is evaluated for -each pair of like-named files, and if the expression's value is -non-@code{nil}, those files are considered ``different.'' - - For instance, the sequence @code{M-x dired-compare-directories -@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this -directory than in the other, and marks files older in the other -directory than in this one. It also marks files with no counterpart, -in both directories, as always. - -@cindex drag and drop, Dired - On the X window system, Emacs supports the ``drag and drop'' -protocol. You can drag a file object from another program, and drop -it onto a Dired buffer; this either moves, copies, or creates a link -to the file in that directory. Precisely which action is taken is -determined by the originating program. Dragging files out of a Dired -buffer is currently not supported. - -@ignore - arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1 -@end ignore diff --git a/man/display.texi b/man/display.texi deleted file mode 100644 index 21a65999ec3..00000000000 --- a/man/display.texi +++ /dev/null @@ -1,1259 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Display, Search, Registers, Top -@chapter Controlling the Display - - Since only part of a large buffer fits in the window, Emacs tries to -show a part that is likely to be interesting. Display-control -commands allow you to specify which part of the text you want to see, -and how to display it. Many variables also affect the details of -redisplay. Unless otherwise stated, the variables described in this -chapter have their effect by customizing redisplay itself; therefore, -their values only make a difference at the time of redisplay. - -@menu -* Scrolling:: Commands to move text up and down in a window. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Standard Faces:: Emacs' predefined faces. -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly-spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Display Custom:: Information on variables for customizing display. -@end menu - -@node Scrolling -@section Scrolling - - If a buffer contains text that is too large to fit entirely within a -window that is displaying the buffer, Emacs shows a contiguous portion of -the text. The portion shown always contains point. - -@cindex scrolling - @dfn{Scrolling} means moving text up or down in the window so that -different parts of the text are visible. Scrolling ``forward'' or -``up'' means that text moves up, and new text appears at the bottom. -Scrolling ``backward'' or ``down'' moves text down, and new text -appears at the top. - - Scrolling happens automatically if you move point past the bottom or -top of the window. You can also scroll explicitly with the commands -in this section. - -@table @kbd -@item C-l -Clear screen and redisplay, scrolling the selected window to center -point vertically within it (@code{recenter}). -@item C-v -Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}). -@item @key{NEXT} -@itemx @key{PAGEDOWN} -Likewise, scroll forward. -@item M-v -Scroll backward (@code{scroll-down}). -@item @key{PRIOR} -@itemx @key{PAGEUP} -Likewise, scroll backward. -@item @var{arg} C-l -Scroll so point is on line @var{arg} (@code{recenter}). -@item C-M-l -Scroll heuristically to bring useful information onto the screen -(@code{reposition-window}). -@end table - -@kindex C-l -@findex recenter - The most basic scrolling command is @kbd{C-l} (@code{recenter}) with -no argument. It scrolls the selected window so that point is halfway -down from the top of the window. On a text terminal, it also clears -the screen and redisplays all windows. That is useful in case the -screen is garbled (@pxref{Screen Garbled}). - -@kindex C-v -@kindex M-v -@kindex NEXT -@kindex PRIOR -@kindex PAGEDOWN -@kindex PAGEUP -@findex scroll-up -@findex scroll-down - To read the buffer a windowful at a time, use @kbd{C-v} -(@code{scroll-up}) with no argument. This scrolls forward by nearly -the whole window height. The effect is to take the two lines at the -bottom of the window and put them at the top, followed by nearly a -whole windowful of lines that were not previously visible. If point -was in the text that scrolled off the top, it ends up at the new top -of the window. - -@vindex next-screen-context-lines - @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in -a similar way, also with overlap. The number of lines of overlap that -the @kbd{C-v} or @kbd{M-v} commands leave is controlled by the -variable @code{next-screen-context-lines}; by default, it is 2. The -function keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and -@key{PAGEUP}, are equivalent to @kbd{C-v} and @kbd{M-v}. - - The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll -the text in the selected window up or down a few lines. @kbd{C-v} -with an argument moves the text and point up, together, that many -lines; it brings the same number of new lines into view at the bottom -of the window. @kbd{M-v} with numeric argument scrolls the text -downward, bringing that many new lines into view at the top of the -window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice -versa. - - The names of scroll commands are based on the direction that the -text moves in the window. Thus, the command to scroll forward is -called @code{scroll-up} because it moves the text upward on the -screen. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names -and customary meanings from a different convention that developed -elsewhere; hence the strange result that @key{PAGEDOWN} runs -@code{scroll-up}. - -@vindex scroll-preserve-screen-position - Some users like the full-screen scroll commands to keep point at the -same screen line. To enable this behavior, set the variable -@code{scroll-preserve-screen-position} to a non-@code{nil} value. In -this mode, when these commands would scroll the text around point off -the screen, or within @code{scroll-margin} lines of the edge, they -move point to keep the same vertical position within the window. -This mode is convenient for browsing through a file by scrolling by -screenfuls; if you come back to the screen where you started, point -goes back to the line where it started. However, this mode is -inconvenient when you move to the next screen in order to move point -to the text there. - - Another way to do scrolling is with @kbd{C-l} with a numeric argument. -@kbd{C-l} does not clear the screen when given an argument; it only scrolls -the selected window. With a positive argument @var{n}, it repositions text -to put point @var{n} lines down from the top. An argument of zero puts -point on the very top line. Point does not move with respect to the text; -rather, the text and point move rigidly on the screen. @kbd{C-l} with a -negative argument puts point that many lines from the bottom of the window. -For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u -- 5 C-l} puts it five lines from the bottom. @kbd{C-u C-l} scrolls to put -point at the center (vertically) of the selected window. - -@kindex C-M-l -@findex reposition-window - The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current -window heuristically in a way designed to get useful information onto -the screen. For example, in a Lisp file, this command tries to get the -entire current defun onto the screen if possible. - -@node Auto Scrolling -@section Automatic Scrolling - -@vindex scroll-conservatively - Redisplay scrolls the buffer automatically when point moves out of -the visible portion of the text. The purpose of automatic scrolling -is to make point visible, but you can customize many aspects of how -this is done. - - Normally, automatic scrolling centers point vertically within the -window. However, if you set @code{scroll-conservatively} to a small -number @var{n}, then if you move point just a little off the -screen---less than @var{n} lines---then Emacs scrolls the text just -far enough to bring point back on screen. By default, -@code{scroll-conservatively} is@tie{}0. - -@cindex aggressive scrolling -@vindex scroll-up-aggressively -@vindex scroll-down-aggressively - When the window does scroll by a longer distance, you can control -how aggressively it scrolls, by setting the variables -@code{scroll-up-aggressively} and @code{scroll-down-aggressively}. -The value of @code{scroll-up-aggressively} should be either -@code{nil}, or a fraction @var{f} between 0 and 1. A fraction -specifies where on the screen to put point when scrolling upward. -More precisely, when a window scrolls up because point is above the -window start, the new start position is chosen to put point @var{f} -part of the window height from the top. The larger @var{f}, the more -aggressive the scrolling. - - @code{nil}, which is the default, scrolls to put point at the center. -So it is equivalent to .5. - - Likewise, @code{scroll-down-aggressively} is used for scrolling -down. The value, @var{f}, specifies how far point should be placed -from the bottom of the window; thus, as with -@code{scroll-up-aggressively}, a larger value is more aggressive. - -@vindex scroll-margin - The variable @code{scroll-margin} restricts how close point can come -to the top or bottom of a window. Its value is a number of screen -lines; if point comes within that many lines of the top or bottom of the -window, Emacs recenters the window. By default, @code{scroll-margin} is -0. - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - - @dfn{Horizontal scrolling} means shifting all the lines sideways -within a window---so that some of the text near the left margin is not -displayed at all. When the text in a window is scrolled horizontally, -text lines are truncated rather than continued (@pxref{Line -Truncation}). Whenever a window shows truncated lines, Emacs -automatically updates its horizontal scrolling whenever point moves -off the left or right edge of the screen. You can also use these -commands to do explicit horizontal scrolling. - -@table @kbd -@item C-x < -Scroll text in current window to the left (@code{scroll-left}). -@item C-x > -Scroll to the right (@code{scroll-right}). -@end table - -@kindex C-x < -@kindex C-x > -@findex scroll-left -@findex scroll-right - The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected -window to the left by @var{n} columns with argument @var{n}. This moves -part of the beginning of each line off the left edge of the window. -With no argument, it scrolls by almost the full width of the window (two -columns less, to be precise). - - @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The -window cannot be scrolled any farther to the right once it is displayed -normally (with each line starting at the window's left margin); -attempting to do so has no effect. This means that you don't have to -calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large -argument will restore the normal display. - - If you use those commands to scroll a window horizontally, that sets -a lower bound for automatic horizontal scrolling. Automatic scrolling -will continue to scroll the window, but never farther to the right -than the amount you previously set by @code{scroll-left}. - -@vindex hscroll-margin - The value of the variable @code{hscroll-margin} controls how close -to the window's edges point is allowed to get before the window will -be automatically scrolled. It is measured in columns. If the value -is 5, then moving point within 5 columns of the edge causes horizontal -scrolling away from that edge. - -@vindex hscroll-step - The variable @code{hscroll-step} determines how many columns to -scroll the window when point gets too close to the edge. If it's -zero, horizontal scrolling centers point horizontally within the -window. If it's a positive integer, it specifies the number of -columns to scroll by. If it's a floating-point number, it specifies -the fraction of the window's width to scroll by. The default is zero. - -@vindex auto-hscroll-mode - To disable automatic horizontal scrolling, set the variable -@code{auto-hscroll-mode} to @code{nil}. - -@node Follow Mode -@section Follow Mode -@cindex Follow mode -@cindex mode, Follow -@findex follow-mode -@cindex windows, synchronizing -@cindex synchronizing windows - - @dfn{Follow mode} is a minor mode that makes two windows, both -showing the same buffer, scroll as a single tall ``virtual window.'' -To use Follow mode, go to a frame with just one window, split it into -two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x -follow-mode}. From then on, you can edit the buffer in either of the -two windows, or scroll either one; the other window follows it. - - In Follow mode, if you move point outside the portion visible in one -window and into the portion visible in the other window, that selects -the other window---again, treating the two as if they were parts of -one large window. - - To turn off Follow mode, type @kbd{M-x follow-mode} a second time. - -@node Faces -@section Using Multiple Typefaces -@cindex faces - - You can specify various styles for displaying text using -@dfn{faces}. Each face can specify various @dfn{face attributes}, -such as the font family, the height, weight and slant of the -characters, the foreground and background color, and underlining or -overlining. A face does not have to specify all of these attributes; -often it inherits most of them from another face. - - On graphical display, all the Emacs face attributes are meaningful. -On a text-only terminal, only some of them work. Some text-only -terminals support inverse video, bold, and underline attributes; some -support colors. Text-only terminals generally do not support changing -the height and width or the font family. - - Emacs uses faces automatically for highlighting, through the work of -Font Lock mode. @xref{Font Lock}, for more information about Font -Lock mode and syntactic highlighting. You can print out the buffer -with the highlighting that appears on your screen using the command -@code{ps-print-buffer-with-faces}. @xref{PostScript}. - - You control the appearance of a part of the text in the buffer by -specifying the face or faces to use for it. The style of display used -for any given character is determined by combining the attributes of -all the applicable faces specified for that character. Any attribute -that isn't specified by these faces is taken from the @code{default} face, -whose attributes reflect the default settings of the frame itself. - - Enriched mode, the mode for editing formatted text, includes several -commands and menus for specifying faces for text in the buffer. -@xref{Format Faces}, for how to specify the font for text in the -buffer. @xref{Format Colors}, for how to specify the foreground and -background color. - -@cindex face colors, setting -@findex set-face-foreground -@findex set-face-background - To alter the appearance of a face, use the customization buffer. -@xref{Face Customization}. You can also use X resources to specify -attributes of particular faces (@pxref{Resources}). Alternatively, -you can change the foreground and background colors of a specific face -with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}. -These commands prompt in the minibuffer for a face name and a color -name, with completion, and then set that face to use the specified -color. Changing the colors of the @code{default} face also changes -the foreground and background colors on all frames, both existing and -those to be created in the future. (You can also set foreground and -background colors for the current frame only; see @ref{Frame -Parameters}.) - - If you want to alter the appearance of all Emacs frames, you need to -customize the frame parameters in the variable -@code{default-frame-alist}; see @ref{Creating Frames, -default-frame-alist}. - - Emacs can correctly display variable-width fonts, but Emacs commands -that calculate width and indentation do not know how to calculate -variable widths. This can sometimes lead to incorrect results when -you use variable-width fonts. In particular, indentation commands can -give inconsistent results, so we recommend you avoid variable-width -fonts for editing program source code. Filling will sometimes make -lines too long or too short. We plan to address these issues in -future Emacs versions. - -@node Standard Faces -@section Standard Faces - -@findex list-faces-display - To see what faces are currently defined, and what they look like, -type @kbd{M-x list-faces-display}. It's possible for a given face to -look different in different frames; this command shows the appearance -in the frame in which you type it. With a prefix argument, this -prompts for a regular expression, and displays only faces with names -matching that regular expression. - - Here are the standard faces for specifying text appearance. You can -apply them to specific text when you want the effects they produce. - -@table @code -@item default -This face is used for ordinary text that doesn't specify any face. -@item bold -This face uses a bold variant of the default font, if it has one. -It's up to you to choose a default font that has a bold variant, -if you want to use one. -@item italic -This face uses an italic variant of the default font, if it has one. -@item bold-italic -This face uses a bold italic variant of the default font, if it has one. -@item underline -This face underlines text. -@item fixed-pitch -This face forces use of a particular fixed-width font. -@item variable-pitch -This face forces use of a particular variable-width font. It's -reasonable to customize this face to use a different variable-width font, -if you like, but you should not make it a fixed-width font. -@item shadow -This face is used for making the text less noticeable than the surrounding -ordinary text. Usually this can be achieved by using shades of gray in -contrast with either black or white default foreground color. -@end table - - Here's an incomplete list of faces used to highlight parts of the -text temporarily for specific purposes. (Many other modes define -their own faces for this purpose.) - -@table @code -@item highlight -This face is used for highlighting portions of text, in various modes. -For example, mouse-sensitive text is highlighted using this face. -@item isearch -This face is used for highlighting the current Isearch match. -@item query-replace -This face is used for highlighting the current Query Replace match. -@item lazy-highlight -This face is used for lazy highlighting of Isearch and Query Replace -matches other than the current one. -@item region -This face is used for displaying a selected region (when Transient Mark -mode is enabled---see below). -@item secondary-selection -This face is used for displaying a secondary X selection (@pxref{Secondary -Selection}). -@item trailing-whitespace -The face for highlighting excess spaces and tabs at the end of a line -when @code{show-trailing-whitespace} is non-@code{nil}; see -@ref{Useless Whitespace}. -@item nobreak-space -The face for displaying the character ``nobreak space.'' -@item escape-glyph -The face for highlighting the @samp{\} or @samp{^} that indicates -a control character. It's also used when @samp{\} indicates a -nobreak space or nobreak (soft) hyphen. -@end table - -@cindex @code{region} face - When Transient Mark mode is enabled, the text of the region is -highlighted when the mark is active. This uses the face named -@code{region}; you can control the style of highlighting by changing the -style of this face (@pxref{Face Customization}). @xref{Transient Mark}, -for more information about Transient Mark mode and activation and -deactivation of the mark. - - These faces control the appearance of parts of the Emacs frame. -They exist as faces to provide a consistent way to customize the -appearance of these parts of the frame. - -@table @code -@item mode-line -@itemx modeline -This face is used for the mode line of the currently selected window, -and for menu bars when toolkit menus are not used. By default, it's -drawn with shadows for a ``raised'' effect on graphical displays, and -drawn as the inverse of the default face on non-windowed terminals. -@code{modeline} is an alias for the @code{mode-line} face, for -compatibility with old Emacs versions. -@item mode-line-inactive -Like @code{mode-line}, but used for mode lines of the windows other -than the selected one (if @code{mode-line-in-non-selected-windows} is -non-@code{nil}). This face inherits from @code{mode-line}, so changes -in that face affect mode lines in all windows. -@item mode-line-highlight -Like @code{highlight}, but used for portions of text on mode lines. -@item mode-line-buffer-id -This face is used for buffer identification parts in the mode line. -@item header-line -Similar to @code{mode-line} for a window's header line, which appears -at the top of a window just as the mode line appears at the bottom. -Most windows do not have a header line---only some special modes, such -Info mode, create one. -@item vertical-border -This face is used for the vertical divider between windows. -By default this face inherits from the @code{mode-line-inactive} face -on character terminals. On graphical displays the foreground color of -this face is used for the vertical line between windows without -scrollbars. -@item minibuffer-prompt -@cindex @code{minibuffer-prompt} face -@vindex minibuffer-prompt-properties -This face is used for the prompt strings displayed in the minibuffer. -By default, Emacs automatically adds this face to the value of -@code{minibuffer-prompt-properties}, which is a list of text -properties used to display the prompt text. (This variable takes -effect when you enter the minibuffer.) -@item fringe -@cindex @code{fringe} face -The face for the fringes to the left and right of windows on graphic -displays. (The fringes are the narrow portions of the Emacs frame -between the text area and the window's right and left borders.) -@xref{Fringes}. -@item scroll-bar -This face determines the visual appearance of the scroll bar. -@xref{Scroll Bars}. -@item border -This face determines the color of the frame border. -@item cursor -This face determines the color of the cursor. -@item mouse -This face determines the color of the mouse pointer. -@item tool-bar -This face determines the color of tool bar icons. @xref{Tool Bars}. -@item tooltip -This face is used for tooltips. @xref{Tooltips}. -@item menu -@cindex menu bar appearance -@cindex @code{menu} face, no effect if customized -@cindex customization of @code{menu} face -This face determines the colors and font of Emacs's menus. @xref{Menu -Bars}. Setting the font of LessTif/Motif menus is currently not -supported; attempts to set the font are ignored in this case. -Likewise, attempts to customize this face in Emacs built with GTK and -in the MS-Windows/Mac ports are ignored by the respective GUI toolkits; -you need to use system-wide styles and options to change the -appearance of the menus. -@end table - -@node Font Lock -@section Font Lock mode -@cindex Font Lock mode -@cindex mode, Font Lock -@cindex syntax highlighting and coloring - - Font Lock mode is a minor mode, always local to a particular buffer, -which highlights (or ``fontifies'') the buffer contents according to -the syntax of the text you are editing. It can recognize comments and -strings in most languages; in several languages, it can also recognize -and properly highlight various other important constructs---for -example, names of functions being defined or reserved keywords. -Some special modes, such as Occur mode and Info mode, have completely -specialized ways of assigning fonts for Font Lock mode. - -@findex font-lock-mode - Font Lock mode is turned on by default in all modes which support it. -You can toggle font-lock for each buffer with the command @kbd{M-x -font-lock-mode}. Using a positive argument unconditionally turns Font -Lock mode on, and a negative or zero argument turns it off. - -@findex global-font-lock-mode -@vindex global-font-lock-mode - If you do not wish Font Lock mode to be turned on by default, -customize the variable @code{global-font-lock-mode} using the Customize -interface (@pxref{Easy Customization}), or use the function -@code{global-font-lock-mode} in your @file{.emacs} file, like this: - -@example -(global-font-lock-mode 0) -@end example - -@noindent -This variable, like all the variables that control Font Lock mode, -take effect whenever fontification is done; that is, potentially at -any time. - -@findex turn-on-font-lock - If you have disabled Global Font Lock mode, you can still enable Font -Lock for specific major modes by adding the function -@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For -example, to enable Font Lock mode for editing C files, you can do this: - -@example -(add-hook 'c-mode-hook 'turn-on-font-lock) -@end example - - Font Lock mode uses several specifically named faces to do its job, -including @code{font-lock-string-face}, @code{font-lock-comment-face}, -and others. The easiest way to find them all is to use @kbd{M-x -customize-group @key{RET} font-lock-faces @key{RET}}. You can then -use that customization buffer to customize the appearance of these -faces. @xref{Face Customization}. - - You can also customize these faces using @kbd{M-x -set-face-foreground} or @kbd{M-x set-face-background}. @xref{Faces}. - -@vindex font-lock-maximum-decoration - The variable @code{font-lock-maximum-decoration} specifies the -preferred level of fontification, for modes that provide multiple -levels. Level 1 is the least amount of fontification; some modes -support levels as high as 3. The normal default is ``as high as -possible.'' You can specify an integer, which applies to all modes, or -you can specify different numbers for particular major modes; for -example, to use level 1 for C/C++ modes, and the default level -otherwise, use this: - -@example -(setq font-lock-maximum-decoration - '((c-mode . 1) (c++-mode . 1))) -@end example - -@vindex font-lock-maximum-size - Fontification can be too slow for large buffers, so you can suppress -it for buffers above a certain size. The variable -@code{font-lock-maximum-size} specifies a buffer size, beyond which -buffer fontification is suppressed. - -@c @w is used below to prevent a bad page-break. -@vindex font-lock-beginning-of-syntax-function -@cindex incorrect fontification -@cindex parenthesis in column zero and fontification -@cindex brace in column zero and fontification - Comment and string fontification (or ``syntactic'' fontification) -relies on analysis of the syntactic structure of the buffer text. For -the sake of speed, some modes, including Lisp mode, rely on a special -convention: an open-parenthesis or open-brace in the leftmost column -always defines the @w{beginning} of a defun, and is thus always -outside any string or comment. (@xref{Left Margin Paren}.) If you -don't follow this convention, Font Lock mode can misfontify the text -that follows an open-parenthesis or open-brace in the leftmost column -that is inside a string or comment. - -@cindex slow display during scrolling - The variable @code{font-lock-beginning-of-syntax-function} (always -buffer-local) specifies how Font Lock mode can find a position -guaranteed to be outside any comment or string. In modes which use the -leftmost column parenthesis convention, the default value of the variable -is @code{beginning-of-defun}---that tells Font Lock mode to use the -convention. If you set this variable to @code{nil}, Font Lock no longer -relies on the convention. This avoids incorrect results, but the price -is that, in some cases, fontification for a changed text must rescan -buffer text from the beginning of the buffer. This can considerably -slow down redisplay while scrolling, particularly if you are close to -the end of a large buffer. - -@findex font-lock-add-keywords - Font Lock highlighting patterns already exist for many modes, but you -may want to fontify additional patterns. You can use the function -@code{font-lock-add-keywords}, to add your own highlighting patterns for -a particular mode. For example, to highlight @samp{FIXME:} words in C -comments, use this: - -@example -(font-lock-add-keywords - 'c-mode - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t))) -@end example - -@findex font-lock-remove-keywords - To remove keywords from the font-lock highlighting patterns, use the -function @code{font-lock-remove-keywords}. @xref{Search-based -Fontification,,, elisp, The Emacs Lisp Reference Manual}, for -documentation of the format of this list. - -@cindex just-in-time (JIT) font-lock -@cindex background syntax highlighting - Fontifying large buffers can take a long time. To avoid large -delays when a file is visited, Emacs fontifies only the visible -portion of a buffer. As you scroll through the buffer, each portion -that becomes visible is fontified as soon as it is displayed. The -parts of the buffer that are not displayed are fontified -``stealthily,'' in the background, i.e.@: when Emacs is idle. You can -control this background fontification, also called @dfn{Just-In-Time} -(or @dfn{JIT}) Lock, by customizing variables in the customization -group @samp{jit-lock}. @xref{Specific Customization}. - -@node Highlight Interactively -@section Interactive Highlighting -@cindex highlighting by matching -@cindex interactive highlighting -@cindex Highlight Changes mode - -@findex highlight-changes-mode - Use @kbd{M-x highlight-changes-mode} to enable (or disable) -Highlight Changes mode, a minor mode that uses faces (colors, -typically) to indicate which parts of the buffer were changed most -recently. - -@cindex Hi Lock mode -@findex hi-lock-mode - Hi Lock mode highlights text that matches regular expressions you -specify. For example, you might wish to see all the references to a -certain variable in a program source file, highlight certain parts in -a voluminous output of some program, or make certain names stand out -in an article. Use the @kbd{M-x hi-lock-mode} command to enable (or -disable) Hi Lock mode. To enable Hi Lock mode for all buffers, use -@kbd{M-x global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)} -in your @file{.emacs} file. - - Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except -that you specify explicitly the regular expressions to highlight. You -control them with these commands: - -@table @kbd -@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET} -@kindex C-x w h -@findex highlight-regexp -Highlight text that matches @var{regexp} using face @var{face} -(@code{highlight-regexp}). The highlighting will remain as long as -the buffer is loaded. For example, to highlight all occurrences of -the word ``whim'' using the default face (a yellow background) -@kbd{C-x w h whim @key{RET} @key{RET}}. Any face can be used for -highlighting, Hi Lock provides several of its own and these are -pre-loaded into a history list. While being prompted for a face use -@kbd{M-p} and @kbd{M-n} to cycle through them. - -You can use this command multiple times, specifying various regular -expressions to highlight in different ways. - -@item C-x w r @var{regexp} @key{RET} -@kindex C-x w r -@findex unhighlight-regexp -Unhighlight @var{regexp} (@code{unhighlight-regexp}). - -If you invoke this from the menu, you select the expression to -unhighlight from a list. If you invoke this from the keyboard, you -use the minibuffer. It will show the most recently added regular -expression; use @kbd{M-p} to show the next older expression and -@kbd{M-n} to select the next newer expression. (You can also type the -expression by hand, with completion.) When the expression you want to -unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit -the minibuffer and unhighlight it. - -@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET} -@kindex C-x w l -@findex highlight-lines-matching-regexp -@cindex lines, highlighting -@cindex highlighting lines of text -Highlight entire lines containing a match for @var{regexp}, using face -@var{face} (@code{highlight-lines-matching-regexp}). - -@item C-x w b -@kindex C-x w b -@findex hi-lock-write-interactive-patterns -Insert all the current highlighting regexp/face pairs into the buffer -at point, with comment delimiters to prevent them from changing your -program. (This key binding runs the -@code{hi-lock-write-interactive-patterns} command.) - -These patterns are extracted from the comments, if appropriate, if you -invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while -Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}). - -@item C-x w i -@kindex C-x w i -@findex hi-lock-find-patterns -Extract regexp/face pairs from comments in the current buffer -(@code{hi-lock-find-patterns}). Thus, you can enter patterns -interactively with @code{highlight-regexp}, store them into the file -with @code{hi-lock-write-interactive-patterns}, edit them (perhaps -including different faces for different parenthesized parts of the -match), and finally use this command (@code{hi-lock-find-patterns}) to -have Hi Lock highlight the edited patterns. - -@vindex hi-lock-file-patterns-policy -The variable @code{hi-lock-file-patterns-policy} controls whether Hi -Lock mode should automatically extract and highlight patterns found in -a file when it is visited. Its value can be @code{nil} (never -highlight), @code{t} (highlight the patterns), @code{ask} (query the -user), or a function. If it is a function, -@code{hi-lock-find-patterns} calls it with the patterns as argument; -if the function returns non-@code{nil}, the patterns are used. The -default is @code{nil}. Note that patterns are always highlighted if -you call @code{hi-lock-find-patterns} directly, regardless of the -value of this variable. - -@vindex hi-lock-exclude-modes -Also, @code{hi-lock-find-patterns} does nothing if the current major -mode's symbol is a member of the list @code{hi-lock-exclude-modes}. -@end table - -@node Fringes -@section Window Fringes -@cindex fringes - - On a graphical display, each Emacs window normally has narrow -@dfn{fringes} on the left and right edges. The fringes display -indications about the text in the window. - - The most common use of the fringes is to indicate a continuation -line, when one line of text is split into multiple lines on the -screen. The left fringe shows a curving arrow for each screen line -except the first, indicating that ``this is not the real beginning.'' -The right fringe shows a curving arrow for each screen line except the -last, indicating that ``this is not the real end.'' - - The fringes indicate line truncation with short horizontal arrows -meaning ``there's more text on this line which is scrolled -horizontally out of view;'' clicking the mouse on one of the arrows -scrolls the display horizontally in the direction of the arrow. The -fringes can also indicate other things, such as empty lines, or where a -program you are debugging is executing (@pxref{Debuggers}). - -@findex set-fringe-style -@findex fringe-mode - You can enable and disable the fringes for all frames using -@kbd{M-x fringe-mode}. To enable and disable the fringes -for the selected frame, use @kbd{M-x set-fringe-style}. - -@node Displaying Boundaries -@section Displaying Boundaries - -@vindex indicate-buffer-boundaries - On a graphical display, Emacs can indicate the buffer boundaries in -the fringes. It indicates the first line and the last line with -angle images in the fringes. This can be combined with up and down -arrow images which say whether it is possible to scroll the window up -and down. - - The buffer-local variable @code{indicate-buffer-boundaries} controls -how the buffer boundaries and window scrolling is indicated in the -fringes. If the value is @code{left} or @code{right}, both angle and -arrow bitmaps are displayed in the left or right fringe, respectively. - - If value is an alist, each element @code{(@var{indicator} . -@var{position})} specifies the position of one of the indicators. -The @var{indicator} must be one of @code{top}, @code{bottom}, -@code{up}, @code{down}, or @code{t} which specifies the default -position for the indicators not present in the alist. -The @var{position} is one of @code{left}, @code{right}, or @code{nil} -which specifies not to show this indicator. - - For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, the bottom angle bitmap in right fringe, and -both arrow bitmaps in right fringe. To show just the angle bitmaps in -the left fringe, but no arrow bitmaps, use @code{((top . left) -(bottom . left))}. - -@vindex default-indicate-buffer-boundaries - The value of the variable @code{default-indicate-buffer-boundaries} -is the default value for @code{indicate-buffer-boundaries} in buffers -that do not override it. - -@node Useless Whitespace -@section Useless Whitespace - -@cindex trailing whitespace -@cindex whitespace, trailing -@vindex show-trailing-whitespace - It is easy to leave unnecessary spaces at the end of a line, or -empty lines at the end of a file, without realizing it. In most -cases, this @dfn{trailing whitespace} has no effect, but there are -special circumstances where it matters. It can also be a nuisance -that the line has ``changed,'' when the change is just spaces added or -removed at the end. - - You can make trailing whitespace at the end of a line visible on the -screen by setting the buffer-local variable -@code{show-trailing-whitespace} to @code{t}. Then Emacs displays -trailing whitespace in the face @code{trailing-whitespace}. - - This feature does not apply when point is at the end of the line -containing the whitespace. Strictly speaking, that is ``trailing -whitespace'' nonetheless, but displaying it specially in that case -looks ugly while you are typing in new text. In this special case, -the location of point is enough to show you that the spaces are -present. - -@findex delete-trailing-whitespace - To delete all trailing whitespace within the current buffer's -accessible portion (@pxref{Narrowing}), type @kbd{M-x -delete-trailing-whitespace @key{RET}}. (This command does not remove -the form-feed characters.) - -@vindex indicate-empty-lines -@vindex default-indicate-empty-lines -@cindex unused lines -@cindex fringes, and unused line indication - Emacs can indicate unused lines at the end of the window with a -small image in the left fringe (@pxref{Fringes}). The image appears -for window lines that do not correspond to any buffer text. Blank -lines at the end of the buffer then stand out because they do not have -this image in the fringe. - - To enable this feature, set the buffer-local variable -@code{indicate-empty-lines} to a non-@code{nil} value. The default -value of this variable is controlled by the variable -@code{default-indicate-empty-lines}; by setting that variable, you -can enable or disable this feature for all new buffers. (This feature -currently doesn't work on text-only terminals.) - -@node Selective Display -@section Selective Display -@cindex selective display -@findex set-selective-display -@kindex C-x $ - - Emacs has the ability to hide lines indented more than a certain number -of columns (you specify how many columns). You can use this to get an -overview of a part of a program. - - To hide lines in the current buffer, type @kbd{C-x $} -(@code{set-selective-display}) with a numeric argument @var{n}. Then -lines with at least @var{n} columns of indentation disappear from the -screen. The only indication of their presence is that three dots -(@samp{@dots{}}) appear at the end of each visible line that is -followed by one or more hidden ones. - - The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as -if they were not there. - - The hidden lines are still present in the buffer, and most editing -commands see them as usual, so you may find point in the middle of the -hidden text. When this happens, the cursor appears at the end of the -previous line, after the three dots. If point is at the end of the -visible line, before the newline that ends it, the cursor appears before -the three dots. - - To make all lines visible again, type @kbd{C-x $} with no argument. - -@vindex selective-display-ellipses - If you set the variable @code{selective-display-ellipses} to -@code{nil}, the three dots do not appear at the end of a line that -precedes hidden lines. Then there is no visible indication of the -hidden lines. This variable becomes local automatically when set. - - See also @ref{Outline Mode} for another way to hide part of -the text in a buffer. - -@node Optional Mode Line -@section Optional Mode Line Features - -@cindex buffer size display -@cindex display of buffer size -@findex size-indication-mode - The buffer percentage @var{pos} indicates the percentage of the -buffer above the top of the window. You can additionally display the -size of the buffer by typing @kbd{M-x size-indication-mode} to turn on -Size Indication mode. The size will be displayed immediately -following the buffer percentage like this: - -@example -@var{POS} of @var{SIZE} -@end example - -@noindent -Here @var{SIZE} is the human readable representation of the number of -characters in the buffer, which means that @samp{k} for 10^3, @samp{M} -for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. - -@cindex narrowing, and buffer size display - If you have narrowed the buffer (@pxref{Narrowing}), the size of the -accessible part of the buffer is shown. - -@cindex line number display -@cindex display of line number -@findex line-number-mode - The current line number of point appears in the mode line when Line -Number mode is enabled. Use the command @kbd{M-x line-number-mode} to -turn this mode on and off; normally it is on. The line number appears -after the buffer percentage @var{pos}, with the letter @samp{L} to -indicate what it is. - -@cindex Column Number mode -@cindex mode, Column Number -@findex column-number-mode - Similarly, you can display the current column number by turning on -Column number mode with @kbd{M-x column-number-mode}. The column -number is indicated by the letter @samp{C}. However, when both of -these modes are enabled, the line and column numbers are displayed in -parentheses, the line number first, rather than with @samp{L} and -@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more -information about minor modes and about how to use these commands. - -@cindex narrowing, and line number display - If you have narrowed the buffer (@pxref{Narrowing}), the displayed -line number is relative to the accessible portion of the buffer. -Thus, it isn't suitable as an argument to @code{goto-line}. (Use -@code{what-line} command to see the line number relative to the whole -file.) - -@vindex line-number-display-limit - If the buffer is very large (larger than the value of -@code{line-number-display-limit}), then the line number doesn't appear. -Emacs doesn't compute the line number when the buffer is large, because -that would be too slow. Set it to @code{nil} to remove the limit. - -@vindex line-number-display-limit-width - Line-number computation can also be slow if the lines in the buffer -are too long. For this reason, Emacs normally doesn't display line -numbers if the average width, in characters, of lines near point is -larger than the value of the variable -@code{line-number-display-limit-width}. The default value is 200 -characters. - -@findex display-time -@cindex time (on mode line) - Emacs can optionally display the time and system load in all mode -lines. To enable this feature, type @kbd{M-x display-time} or customize -the option @code{display-time-mode}. The information added to the mode -line usually appears after the buffer name, before the mode names and -their parentheses. It looks like this: - -@example -@var{hh}:@var{mm}pm @var{l.ll} -@end example - -@noindent -@vindex display-time-24hr-format -Here @var{hh} and @var{mm} are the hour and minute, followed always by -@samp{am} or @samp{pm}. @var{l.ll} is the average number of running -processes in the whole system recently. (Some fields may be missing if -your operating system cannot support them.) If you prefer time display -in 24-hour format, set the variable @code{display-time-24hr-format} -to @code{t}. - -@cindex mail (on mode line) -@vindex display-time-use-mail-icon -@vindex display-time-mail-face -@vindex display-time-mail-file -@vindex display-time-mail-directory - The word @samp{Mail} appears after the load level if there is mail -for you that you have not read yet. On a graphical display you can use -an icon instead of @samp{Mail} by customizing -@code{display-time-use-mail-icon}; this may save some space on the mode -line. You can customize @code{display-time-mail-face} to make the mail -indicator prominent. Use @code{display-time-mail-file} to specify -the mail file to check, or set @code{display-time-mail-directory} -to specify the directory to check for incoming mail (any nonempty regular -file in the directory is considered as ``newly arrived mail''). - -@cindex mode line, 3D appearance -@cindex attributes of mode line, changing -@cindex non-integral number of lines in a window - By default, the mode line is drawn on graphics displays with -3D-style highlighting, like that of a button when it is not being -pressed. If you don't like this effect, you can disable the 3D -highlighting of the mode line, by customizing the attributes of the -@code{mode-line} face. @xref{Face Customization}. - -@cindex non-selected windows, mode line appearance - By default, the mode line of nonselected windows is displayed in a -different face, called @code{mode-line-inactive}. Only the selected -window is displayed in the @code{mode-line} face. This helps show -which window is selected. When the minibuffer is selected, since -it has no mode line, the window from which you activated the minibuffer -has its mode line displayed using @code{mode-line}; as a result, -ordinary entry to the minibuffer does not change any mode lines. - -@vindex mode-line-in-non-selected-windows - You can disable use of @code{mode-line-inactive} by setting variable -@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode -lines are displayed in the @code{mode-line} face. - -@vindex eol-mnemonic-unix -@vindex eol-mnemonic-dos -@vindex eol-mnemonic-mac -@vindex eol-mnemonic-undecided - You can customize the mode line display for each of the end-of-line -formats by setting each of the variables @code{eol-mnemonic-unix}, -@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and -@code{eol-mnemonic-undecided} to the strings you prefer. - -@node Text Display -@section How Text Is Displayed -@cindex characters (in text) - - @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs -buffers are displayed with their graphics, as are non-ASCII multibyte -printing characters (octal codes above 0400). - - Some @acronym{ASCII} control characters are displayed in special ways. The -newline character (octal code 012) is displayed by starting a new line. -The tab character (octal code 011) is displayed by moving to the next -tab stop column (normally every 8 columns). - - Other @acronym{ASCII} control characters are normally displayed as a caret -(@samp{^}) followed by the non-control version of the character; thus, -control-A is displayed as @samp{^A}. The caret appears in face -@code{escape-glyph}. - - Non-@acronym{ASCII} characters 0200 through 0237 (octal) are -displayed with octal escape sequences; thus, character code 0230 -(octal) is displayed as @samp{\230}. The backslash appears in face -@code{escape-glyph}. - -@vindex ctl-arrow - If the variable @code{ctl-arrow} is @code{nil}, control characters in -the buffer are displayed with octal escape sequences, except for newline -and tab. Altering the value of @code{ctl-arrow} makes it local to the -current buffer; until that time, the default value is in effect. The -default is initially @code{t}. - - The display of character codes 0240 through 0377 (octal) may be -either as escape sequences or as graphics. They do not normally occur -in multibyte buffers, but if they do, they are displayed as Latin-1 -graphics. In unibyte mode, if you enable European display they are -displayed using their graphics (assuming your terminal supports them), -otherwise as escape sequences. @xref{Unibyte Mode}. - -@vindex nobreak-char-display -@cindex no-break space, display -@cindex no-break hyphen, display -@cindex soft hyphen, display - Some character sets define ``no-break'' versions of the space and -hyphen characters, which are used where a line should not be broken. -Emacs normally displays these characters with special faces -(respectively, @code{nobreak-space} and @code{escape-glyph}) to -distinguish them from ordinary spaces and hyphens. You can turn off -this feature by setting the variable @code{nobreak-char-display} to -@code{nil}. If you set the variable to any other value, that means to -prefix these characters with an escape character. - -@vindex tab-width -@vindex default-tab-width - Normally, a tab character in the buffer is displayed as whitespace which -extends to the next display tab stop position, and display tab stops come -at intervals equal to eight spaces. The number of spaces per tab is -controlled by the variable @code{tab-width}, which is made local by -changing it. Note that how the tab character -in the buffer is displayed has nothing to do with the definition of -@key{TAB} as a command. The variable @code{tab-width} must have an -integer value between 1 and 1000, inclusive. The variable -@code{default-tab-width} controls the default value of this variable -for buffers where you have not set it locally. - - You can customize the way any particular character code is displayed -by means of a display table. @xref{Display Tables,, Display Tables, -elisp, The Emacs Lisp Reference Manual}. - -@node Cursor Display -@section Displaying the Cursor - -@findex blink-cursor-mode -@vindex blink-cursor-alist -@cindex cursor, locating visually -@cindex cursor, blinking - You can customize the cursor's color, and whether it blinks, using -the @code{cursor} Custom group (@pxref{Easy Customization}). On -a graphical display, the command @kbd{M-x blink-cursor-mode} enables -or disables the blinking of the cursor. (On text terminals, the -terminal itself blinks the cursor, and Emacs has no control over it.) -You can control how the cursor appears when it blinks off by setting -the variable @code{blink-cursor-alist}. - -@vindex visible-cursor - Some text terminals offer two different cursors: the normal cursor -and the very visible cursor, where the latter may be e.g. bigger or -blinking. By default Emacs uses the very visible cursor, and switches -to it when you start or resume Emacs. If the variable -@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it -doesn't switch, so it uses the normal cursor. - -@cindex cursor in non-selected windows -@vindex cursor-in-non-selected-windows - Normally, the cursor appears in non-selected windows in the ``off'' -state, with the same appearance as when the blinking cursor blinks -``off.'' For a box cursor, this is a hollow box; for a bar cursor, -this is a thinner bar. To turn off cursors in non-selected windows, -customize the variable @code{cursor-in-non-selected-windows} and assign -it a @code{nil} value. - -@vindex x-stretch-cursor -@cindex wide block cursor - On graphical displays, Emacs can optionally draw the block cursor -as wide as the character under the cursor---for example, if the cursor -is on a tab character, it would cover the full width occupied by that -tab character. To enable this feature, set the variable -@code{x-stretch-cursor} to a non-@code{nil} value. - -@findex hl-line-mode -@findex global-hl-line-mode -@cindex highlight current line - To make the cursor even more visible, you can use HL Line mode, a -minor mode that highlights the line containing point. Use @kbd{M-x -hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x -global-hl-line-mode} enables or disables the same mode globally. - -@node Line Truncation -@section Truncation of Lines - -@cindex truncation -@cindex line truncation, and fringes - As an alternative to continuation, Emacs can display long lines by -@dfn{truncation}. This means that all the characters that do not fit -in the width of the screen or window do not appear at all. On -graphical displays, a small straight arrow in the fringe indicates -truncation at either end of the line. On text-only terminals, @samp{$} -appears in the first column when there is text truncated to the left, -and in the last column when there is text truncated to the right. - -@vindex truncate-lines -@findex toggle-truncate-lines - Horizontal scrolling automatically causes line truncation -(@pxref{Horizontal Scrolling}). You can explicitly enable line -truncation for a particular buffer with the command @kbd{M-x -toggle-truncate-lines}. This works by locally changing the variable -@code{truncate-lines}. If that variable is non-@code{nil}, long lines -are truncated; if it is @code{nil}, they are continued onto multiple -screen lines. Setting the variable @code{truncate-lines} in any way -makes it local to the current buffer; until that time, the default -value is in effect. The default value is normally @code{nil}. - -@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows. - If the variable @code{truncate-partial-width-windows} is -non-@code{nil}, it forces truncation rather than continuation in any -window less than the full width of the screen or frame, regardless of -the value of @code{truncate-lines}. For information about side-by-side -windows, see @ref{Split Window}. See also @ref{Display,, Display, -elisp, The Emacs Lisp Reference Manual}. - -@vindex overflow-newline-into-fringe - If the variable @code{overflow-newline-into-fringe} is -non-@code{nil} on a graphical display, then Emacs does not continue or -truncate a line which is exactly as wide as the window. Instead, the -newline overflows into the right fringe, and the cursor appears in the -fringe when positioned on that newline. - -@node Display Custom -@section Customization of Display - - This section describes variables (@pxref{Variables}) that you can -change to customize how Emacs displays. Beginning users can skip -it. -@c the reason for that pxref is because an xref early in the -@c ``echo area'' section leads here. - -@vindex inverse-video - If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts -to invert all the lines of the display from what they normally are. - -@vindex visible-bell - If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts -to make the whole screen blink when it would normally make an audible bell -sound. This variable has no effect if your terminal does not have a way -to make the screen blink. - -@vindex echo-keystrokes - The variable @code{echo-keystrokes} controls the echoing of multi-character -keys; its value is the number of seconds of pause required to cause echoing -to start, or zero, meaning don't echo at all. The value takes effect when -there is someting to echo. @xref{Echo Area}. - -@vindex baud-rate - The variable @anchor{baud-rate}@code{baud-rate} holds the output -speed of the terminal, as far as Emacs knows. Setting this variable -does not change the speed of actual data transmission, but the value -is used for calculations. On text-only terminals, it affects padding, -and decisions about whether to scroll part of the screen or redraw it -instead. It also affects the behavior of incremental search. - - On graphical displays, @code{baud-rate} is only used to determine -how frequently to look for pending input during display updating. A -higher value of @code{baud-rate} means that check for pending input -will be done less frequently. - -@cindex hourglass pointer display -@vindex hourglass-delay - On graphical display, Emacs can optionally display the mouse pointer -in a special shape to say that Emacs is busy. To turn this feature on -or off, customize the group @code{cursor}. You can also control the -amount of time Emacs must remain busy before the busy indicator is -displayed, by setting the variable @code{hourglass-delay}. - -@vindex overline-margin - On graphical display, this variables specifies the vertical position -of an overline above the text, including the height of the overline -itself (1 pixel). The default value is 2 pixels. - -@vindex x-underline-at-descent-line - On graphical display, Emacs normally draws an underline at the -baseline level of the font. If @code{x-underline-at-descent-line} is -non-@code{nil}, Emacs draws the underline at the same height as the -font's descent line. - -@findex tty-suppress-bold-inverse-default-colors - On some text-only terminals, bold face and inverse video together -result in text that is hard to read. Call the function -@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil} -argument to suppress the effect of bold-face in this case. - -@vindex no-redraw-on-reenter - On a text-only terminal, when you reenter Emacs after suspending, Emacs -normally clears the screen and redraws the entire display. On some -terminals with more than one page of memory, it is possible to arrange -the termcap entry so that the @samp{ti} and @samp{te} strings (output -to the terminal when Emacs is entered and exited, respectively) switch -between pages of memory so as to use one page for Emacs and another -page for other output. On such terminals, you might want to set the variable -@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to -assume, when resumed, that the screen page it is using still contains -what Emacs last wrote there. - -@ignore - arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4 -@end ignore diff --git a/man/doclicense.texi b/man/doclicense.texi deleted file mode 100644 index 83e9d6b5579..00000000000 --- a/man/doclicense.texi +++ /dev/null @@ -1,416 +0,0 @@ -@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/man/ebrowse.texi b/man/ebrowse.texi deleted file mode 100644 index c04f99f954c..00000000000 --- a/man/ebrowse.texi +++ /dev/null @@ -1,1462 +0,0 @@ -\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/man/ediff.texi b/man/ediff.texi deleted file mode 100644 index 6bb2605e0c6..00000000000 --- a/man/ediff.texi +++ /dev/null @@ -1,2546 +0,0 @@ -\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/man/emacs-mime.texi b/man/emacs-mime.texi deleted file mode 100644 index 0f3c141c792..00000000000 --- a/man/emacs-mime.texi +++ /dev/null @@ -1,1832 +0,0 @@ -\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/man/emacs-xtra.texi b/man/emacs-xtra.texi deleted file mode 100644 index 841c62a527f..00000000000 --- a/man/emacs-xtra.texi +++ /dev/null @@ -1,126 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../info/emacs-xtra -@settitle Specialized Emacs Features -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This manual describes specialized features of Emacs. - -Copyright @copyright{} 2004, 2005, 2006, 2007 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 -* Emacs-Xtra: (emacs-xtra). Specialized Emacs features. -@end direntry - -@titlepage -@title Specialized Emacs Features -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Specialized Emacs Features - -@insertcopying - -@end ifnottex - -@menu -* Introduction:: What documentation belongs here? -@iftex -* Picture Mode:: Editing pictures made up of characters using - the quarter-plane screen model. - -* Autorevert:: Auto Reverting non-file buffers. -* Subdir Switches:: Subdirectory switches in Dired. -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -* Emerge:: A convenient way of merging two versions of a program. -* Advanced VC Usage:: Advanced VC (version control) features. -* Fortran:: Fortran mode and its special features. -* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). -@end iftex -* Index:: -@end menu - -@node Introduction -@unnumbered Introduction - -This manual contains detailed information about various features that -are too specialized to be included in the printed Emacs manual. It is -intended to be readable by anyone having a basic knowledge of Emacs. -However, certain sections may be intended for a more specialized -audience, such as Elisp authors. This should be clearly pointed out -at the beginning of these sections. - -Certain packages, or collections of related features, have their own -manuals, separate from the main Emacs User's manual. This manual is -intended as a complement, rather than an alternative, to reading those -additional manuals; in a nutshell, it is a collection of smaller -specialized features, too small or too obscure to justify their own -manual. - -Sections intended specifically for Elisp programmers can follow the -style of the Elisp manual. Other sections should follow the style of -the Emacs manual. - -@iftex -@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections. -@include picture-xtra.texi - -@raisesections -@include arevert-xtra.texi - -@include dired-xtra.texi - -@include cal-xtra.texi - -@include emerge-xtra.texi - -@include vc-xtra.texi - -@include fortran-xtra.texi - -@include msdog-xtra.texi - -@lowersections -@end iftex - -@node Index -@unnumbered Index - -@printindex cp - -@bye - -@ignore - arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 -@end ignore diff --git a/man/emacs.texi b/man/emacs.texi deleted file mode 100644 index 1e6fd8461c3..00000000000 --- a/man/emacs.texi +++ /dev/null @@ -1,1365 +0,0 @@ -\input texinfo - -@setfilename ../info/emacs -@settitle GNU Emacs Manual - -@c The edition number appears in several places in this file -@set EDITION Sixteenth -@set EMACSVER 23.0.50 - -@copying -This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* -updated for Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 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.'' - -(a) The FSF's Back-Cover Text is: ``You are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Emacs: (emacs). The extensible self-documenting text editor. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -@set EMACSVER 22 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@defcodeindex op -@synindex pg cp - -@iftex -@kbdinputstyle code - -@shorttitlepage GNU Emacs Manual -@end iftex - -@titlepage -@sp 6 -@center @titlefont{GNU Emacs Manual} -@sp 4 -@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}. -@sp 5 -@center Richard Stallman -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin Street, Fifth Floor @* -Boston, MA 02110-1301 USA @* -ISBN 1-882114-86-8 - -@sp 2 -Cover art by Etienne Suvasa. - -@end titlepage - - -@summarycontents -@contents - - -@ifnottex -@node Top, Distrib, (dir), (dir) -@top The Emacs Editor - -Emacs is the extensible, customizable, self-documenting real-time -display editor. This Info file describes how to edit with Emacs and -some of how to customize it; it corresponds to GNU Emacs version -@value{EMACSVER}. - -@ifinfo -To learn more about the Info documentation system, type @kbd{h}, and -Emacs will take you to a programmed instruction sequence for the Info -commands. -@end ifinfo - -For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The -Emacs Lisp Reference Manual}. -@end ifnottex - -@ignore -These subcategories have been deleted for simplicity -and to avoid conflicts. -Completion -Backup Files -Auto-Saving: Protection Against Disasters -Snapshots -Text Mode -Outline Mode -@TeX{} Mode -Formatted Text -Shell Command History - -The ones for Dired and Rmail have had the items turned into :: items -to avoid conflicts. -Also Running Shell Commands from Emacs -and Sending Mail and Registers and Minibuffer. -@end ignore - -@menu -* Distrib:: How to get the latest Emacs distribution. -* Copying:: The GNU General Public License gives you permission - to redistribute GNU Emacs on certain terms; - it also explains that there is no warranty. -* GNU Free Documentation License:: The license for this documentation. -* Intro:: An introduction to Emacs concepts. -* Glossary:: The glossary. -* Antinews:: Information about Emacs version 21. -* Mac OS:: Using Emacs in the Mac. -* Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. -* Manifesto:: What's GNU? Gnu's Not Unix! -* Acknowledgments:: Major contributors to GNU Emacs. - -Indexes (each index contains a large menu) -* Key Index:: An item for each standard Emacs key sequence. -* Option Index:: An item for every command-line option. -* Command Index:: An item for each command name. -* Variable Index:: An item for each documented variable. -* Concept Index:: An item for each concept. - -Important General Concepts -* Screen:: How to interpret what you see on the screen. -* User Input:: Kinds of input events (characters, buttons, - function keys). -* Keys:: Key sequences: what you type to request one - editing action. -* Commands:: Named functions run by key sequences to do editing. -* Text Characters:: Character set for text (the contents of buffers - and strings). -* Entering Emacs:: Starting Emacs from the shell. -* Exiting:: Stopping or killing Emacs. -* Emacs Invocation:: Hairy startup options. - -Fundamental Editing Commands -* Basic:: The most basic editing commands. -* Minibuffer:: Entering arguments that are prompted for. -* M-x:: Invoking commands by their names. -* Help:: Commands for asking Emacs about its commands. - -Important Text-Changing Commands -* Mark:: The mark: how to delimit a ``region'' of text. -* Killing:: Killing (cutting) text. -* Yanking:: Recovering killed text. Moving text. (Pasting.) -* Accumulating Text:: Other ways of copying text. -* Rectangles:: Operating on the text inside a rectangle on the screen. -* Registers:: Saving a text string or a location in the buffer. -* Display:: Controlling what text is displayed. -* Search:: Finding or replacing occurrences of a string. -* Fixit:: Commands especially useful for fixing typos. -* Keyboard Macros:: A keyboard macro records a sequence of - keystrokes to be replayed with a single command. - -Major Structures of Emacs -* Files:: All about handling files. -* Buffers:: Multiple buffers; editing several files at once. -* Windows:: Viewing two pieces of text at once. -* Frames:: Running the same Emacs session in multiple X windows. -* International:: Using non-@acronym{ASCII} character sets (the MULE features). - -Advanced Features -* Major Modes:: Text mode vs. Lisp mode vs. C mode ... -* Indentation:: Editing the white space at the beginnings of lines. -* Text:: Commands and modes for editing English. -* Programs:: Commands and modes for editing programs. -* Building:: Compiling, running and debugging programs. -* Maintaining:: Features for maintaining large programs. -* Abbrevs:: How to define text abbreviations to reduce - the number of characters you must type. -@ifnottex -* Picture Mode:: Editing pictures made up of characters using - the quarter-plane screen model. -@end ifnottex -* Sending Mail:: Sending mail in Emacs. -* Rmail:: Reading mail in Emacs. -* Dired:: You can ``edit'' a directory to manage files in it. -* Calendar/Diary:: The calendar and diary facilities. -* Gnus:: How to read netnews with Emacs. -* Shell:: Executing shell commands from Emacs. -* Emacs Server:: Using Emacs as an editing server for @code{mail}, etc. -* Printing:: Printing hardcopies of buffers or regions. -* Sorting:: Sorting lines, paragraphs or pages within Emacs. -* Narrowing:: Restricting display and editing to a portion - of the buffer. -* Two-Column:: Splitting apart columns to edit them - in side-by-side windows. -* Editing Binary Files::Using Hexl mode to edit binary files. -* Saving Emacs Sessions:: Saving Emacs state from one session to the next. -* Recursive Edit:: A command can allow you to do editing - "within the command". This is called a - "recursive editing level". -* Emulation:: Emulating some other editors with Emacs. -* Hyperlinking:: Following links in buffers. -* Dissociated Press:: Dissociating text for fun. -* Amusements:: Various games and hacks. -* Customization:: Modifying the behavior of Emacs. -* X Resources:: X resources for customizing Emacs. - -Recovery from Problems -* Quitting:: Quitting and aborting. -* Lossage:: What to do if Emacs is hung or malfunctioning. -* Bugs:: How and when to report a bug. -* Contributing:: How to contribute improvements to Emacs. -* Service:: How to get help for your own Emacs needs. - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are some other nodes which are really inferiors of the ones -already listed, mentioned here so you can get to them in one step: - -The Organization of the Screen - -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. - -Basic Editing Commands - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: How to move the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Basic Files:: Visiting, creating, and saving files. -* Basic Help:: Asking what a character does. -* Blank Lines:: Commands to make or delete blank lines. -* Continuation Lines:: Lines too wide for the screen. -* Position Info:: What page, line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command. -* Repeating:: A short-cut for repeating the previous command. - -The Minibuffer - -* Minibuffer File:: Entering file names with the minibuffer. -* Minibuffer Edit:: How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. - -Completion - -* Example: Completion Example. Examples of using completion. -* Commands: Completion Commands. A list of completion commands. -* Strict Completion:: Different types of completion. -* Options: Completion Options. Options for completion. - -Help - -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Library Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display pre-written help files. -* Help Echo:: Help on active text and tooltips (`balloon help') - -The Mark and the Region - -* Setting Mark:: Commands to set the mark. -* Transient Mark:: How to make Emacs highlight the region-- - when there is one. -* Momentary Mark:: Enabling Transient Mark mode momentarily. -* Using Region:: Summary of ways to operate on contents of the region. -* Marking Objects:: Commands to put region around textual units. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. - -Killing and Moving Text - -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. -* CUA Bindings:: Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} for copy - and paste, with enhanced rectangle support. - -Yanking - -* Kill Ring:: Where killed text is stored. Basic yanking. -* Appending Kills:: Several kills in a row all yank together. -* Earlier Kills:: Yanking something killed some time ago. - -Registers - -* RegPos:: Saving positions in registers. -* RegText:: Saving text in registers. -* RegRect:: Saving rectangles in registers. -* RegConfig:: Saving window configurations in registers. -* RegNumbers:: Numbers in registers. -* RegFiles:: File names in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. - -Controlling the Display - -* Scrolling:: Moving text up and down in a window. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Standard Faces:: Emacs' predefined faces. -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly-spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Display Custom:: Information on variables for customizing display. - -Searching and Replacement - -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. - -Incremental Search - -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Non-ASCII Isearch:: How to search for non-ASCII characters. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Highlight Isearch:: Isearch highlights the other possible matches. -* Isearch Scroll:: Scrolling during an incremental search. -* Slow Isearch:: Incremental search features for slow terminals. - -Replacement Commands - -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. - -Commands for Fixing Typos - -* Undo:: Full details of Emacs undo commands. -* Kill Errors:: Commands to kill a batch of recently entered text. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word or a whole buffer. - -Keyboard Macros - -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. - -File Handling - -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -* Autorevert:: Auto Reverting non-file buffers. -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Version Control:: Version control systems (RCS, CVS and SCCS). -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Editing diff output. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other sites. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. - -Saving Files - -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* File Shadowing:: Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. - -Backup Files - -* One or Many: Numbered Backups. Whether to make one backup file or many. -* Names: Backup Names. How backup files are named. -* Deletion: Backup Deletion. Emacs deletes excess numbered backups. -* Copying: Backup Copying. Backups can be made by copying or renaming. - -Auto-Saving: Protection Against Disasters - -* Files: Auto Save Files. The file where auto-saved changes are - actually made until you save the file. -* Control: Auto Save Control. Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. - -Version Control - -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Old Versions:: Examining and comparing old versions. -* Secondary VC Commands:: The commands used a little less frequently. -* Branches:: Multiple lines of development. -* Remote Repositories:: Efficient access to remote CVS servers. -* Snapshots:: Sets of file versions treated as a unit. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. - -Using Multiple Buffers - -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onliness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. - -Multiple Windows - -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Force Same Window:: Forcing certain buffers to appear in the selected - window rather than in another window. -* Change Window:: Deleting windows and changing their sizes. -* Window Convenience:: Convenience functions for window handling. - -Frames and Graphical Displays - -* Cut and Paste:: Mouse commands for cut and paste. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs job can talk to several displays. -* Special Buffer Frames:: You can make certain buffers have their own frames. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Wheeled Mice:: Using mouse wheels for scrolling. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Showing "tooltips", AKA "balloon help" for active text. -* Mouse Avoidance:: Moving the mouse pointer out of the way. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text-only terminals. - -International Character Set Support - -* International Chars:: Basic concepts of multibyte characters. -* Enabling Multibyte:: Controlling whether to use multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Multibyte Conversion:: How single-byte characters convert to multibyte. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Undisplayable Characters::When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. - -Major Modes - -* Choosing Modes:: How major modes are specified or chosen. - -Indentation - -* Indentation Commands:: Various commands and techniques for indentation. -* Tab Stops:: You can set arbitrary "tab stops" and then - indent to the next tab stop when you want to. -* Just Spaces:: You can request indentation using just spaces. - -Commands for Human Languages - -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* TeX Mode:: Editing input to the formatter TeX. -* HTML Mode:: Editing HTML, SGML, and XML files. -* Nroff Mode:: Editing input to the formatter nroff. -* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. -* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. - -Filling Text - -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Refill:: Keeping paragraphs filled. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented - or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. -* Longlines:: Editing text with very long lines. - -Outline Mode - -* Format: Outline Format. What the text of an outline looks like. -* Motion: Outline Motion. Special commands for moving through - outlines. -* Visibility: Outline Visibility. Commands to control what is visible. -* Views: Outline Views. Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. - -@TeX{} Mode - -* Editing: TeX Editing. Special commands for editing in TeX mode. -* LaTeX: LaTeX Editing. Additional commands for LaTeX input files. -* Printing: TeX Print. Commands for printing part of a file with TeX. -* Misc: TeX Misc. Customization of TeX mode, and related features. - -Editing Formatted Text - -* Requesting Formatted Text:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Faces: Format Faces. Bold, italic, underline, etc. -* Color: Format Colors. Changing the color of text. -* Indent: Format Indentation. Changing the left and right margins. -* Justification: Format Justification. - Centering, setting text flush with the - left or right margin, etc. -* Other: Format Properties. The "special" text properties submenu. -* Forcing Enriched Mode:: How to force use of Enriched mode. - -Editing Text-based Tables - -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Row Commands:: Manipulating rows of table cell. -* Column Commands:: Manipulating columns of table cell. -* Fixed Width Mode:: Fixing cell width. -* Table Conversion:: Converting between plain text and tables. -* Measuring Tables:: Analyzing table dimension. -* Table Misc:: Table miscellany. - -Editing Programs - -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, and Pike modes. -* Asm Mode:: Asm mode and its special features. -* Fortran:: Fortran mode and its special features. - -Top-Level Definitions, or Defuns - -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. - -Indentation for Programs - -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. - -Commands for Editing with Parentheses - -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. - -Manipulating Comments - -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. - -Documentation Lookup - -* Info Lookup:: Looking up library functions and commands - in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. - -C and Related Modes - -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. - -Compiling and Testing Programs - -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Lisp Libraries:: Creating Lisp programs to run in Emacs. -* Lisp Eval:: Executing a single Lisp expression in Emacs. -* Lisp Interaction:: Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. - -Running Debuggers Under Emacs - -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment through - Emacs. - -Maintaining Large Programs - -* Change Log:: Maintaining a change history for your program. -* Format of ChangeLog:: What the change log file looks like. -* Tags:: Go direct to any function in your program in one - command. Tags remembers which file it is in. -* Emerge:: A convenient way of merging two versions of a program. - -Tags Tables - -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @code{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Listing and finding tags defined in a file. - -Abbrevs - -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. - -@ifnottex -Editing Pictures - -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end ifnottex - -Sending Mail - -* Mail Format:: Format of the mail being composed. -* Mail Headers:: Details of permitted mail header fields. -* Mail Aliases:: Abbreviating and grouping mail addresses. -* Mail Mode:: Special commands for editing mail being composed. -* Mail Amusements:: Distract the NSA's attention; add a fortune to a msg. -* Mail Methods:: Using alternative mail-composition methods. - -Reading Mail with Rmail - -* Rmail Basics:: Basic concepts of Rmail, and simple use. -* Rmail Scrolling:: Scrolling through a message. -* Rmail Motion:: Moving to another message. -* Rmail Deletion:: Deleting and expunging messages. -* Rmail Inbox:: How mail gets into the Rmail file. -* Rmail Files:: Using multiple Rmail files. -* Rmail Output:: Copying message out to files. -* Rmail Labels:: Classifying messages by labeling them. -* Rmail Attributes:: Certain standard labels, called attributes. -* Rmail Reply:: Sending replies to messages you are viewing. -* Rmail Summary:: Summaries show brief info on many messages. -* Rmail Sorting:: Sorting messages in Rmail. -* Rmail Display:: How Rmail displays a message; customization. -* Rmail Coding:: How Rmail handles decoding character sets. -* Rmail Editing:: Editing message text and headers in Rmail. -* Rmail Digest:: Extracting the messages from a digest message. -* Out of Rmail:: Converting an Rmail file to mailbox format. -* Rmail Rot13:: Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes. -* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in - Various Formats - -Dired, the Directory Editor - -* Dired Enter:: How to invoke Dired. -* Dired Navigation:: How to move in the Dired buffer. -* Dired Deletion:: Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Dired Visiting:: Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running `diff' by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -* Subdir Switches:: Subdirectory switches in Dired. -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Dired Updating:: Discarding lines for files of no interest. -* Dired and Find:: Using `find' to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired -* Misc Dired Features:: Various other features. - -The Calendar and the Diary - -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. - -Movement in the Calendar - -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. - -Conversion To and From Other Calendars - -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. - -The Diary - -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. - -Gnus - -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Summary of Gnus:: A short description of the basic Gnus commands. - -Running Shell Commands from Emacs - -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* Shell History:: Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Shell Options:: Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Paging in Term:: Paging in the terminal emulator. -* Remote Host:: Connecting to another computer. - -Using Emacs as a Server - -* Invoking emacsclient:: Emacs client startup options. - -Printing Hard Copies - -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. - -Hyperlinking and Navigation Features - -* Browse-URL:: Following URLs. -* Goto-address:: Activating URLs. -* FFAP:: Finding files etc. at point. - -Customization - -* Minor Modes:: Each minor mode is one feature you can turn on - independently of any others. -* Easy Customization:: Convenient way to browse and change user options. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine keys". -* Syntax:: The syntax table controls how words and - expressions are parsed. -* Init File:: How to write common customizations in the - @file{.emacs} file. - -Variables - -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. - -Customizing Key Bindings - -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. - -The Init File, @file{~/.emacs} - -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. - -Dealing with Emacs Trouble - -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: Emergency escape--- - What to do if Emacs stops responding. -* Total Frustration:: When you are at your wits' end. - -Reporting Bugs - -* Bug Criteria:: Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. - -Command Line Arguments for Emacs Invocation - -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Resume Arguments:: Specifying arguments when you resume a running Emacs. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. - -Environment Variables - -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. - -X Options and Resources - -* Resources:: Using X resources with Emacs (in general). -* Table of Resources:: Table of specific X resources that affect Emacs. -* Face Resources:: X resources for customizing faces. -* Lucid Resources:: X resources for Lucid menus. -* LessTif Resources:: X resources for LessTif and Motif menus. -* GTK resources:: Resources for GTK widgets. - -Emacs and Mac OS - -* Mac Input:: Keyboard and mouse input on Mac. -* Mac International:: International character sets on Mac. -* Mac Environment Variables:: Setting environment variables for Emacs. -* Mac Directories:: Volumes and directories on Mac. -* Mac Font Specs:: Specifying fonts on Mac. -* Mac Functions:: Mac-specific Lisp functions. - -Emacs and Microsoft Windows/MS-DOS - -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs}. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). -@end detailmenu -@end menu - -@iftex -@unnumbered Preface - - This manual documents the use and simple customization of the Emacs -editor. Simple Emacs customizations do not require you to be a -programmer, but if you are not interested in customizing, you can -ignore the customization hints. - - This is primarily a reference manual, but can also be used as a -primer. If you are new to Emacs, we recommend you start with -the on-line, learn-by-doing tutorial, before reading the manual. To -run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial -describes commands, tells you when to try them, and explains the -results. - - On first reading, just skim chapters 1 and 2, which describe the -notational conventions of the manual and the general appearance of the -Emacs display screen. Note which questions are answered in these -chapters, so you can refer back later. After reading chapter 4, you -should practice the commands shown there. The next few chapters -describe fundamental techniques and concepts that are used constantly. -You need to understand them thoroughly, so experiment with them -until you are fluent. - - Chapters 14 through 19 describe intermediate-level features that are -useful for many kinds of editing. Chapter 20 and following chapters -describe optional but useful features; read those chapters when you -need them. - - Read the Trouble chapter if Emacs does not seem to be working -properly. It explains how to cope with several common problems -(@pxref{Lossage}), as well as when and how to report Emacs bugs -(@pxref{Bugs}). - - To find the documentation of a particular command, look in the index. -Keys (character commands) and command names have separate indexes. -There is also a glossary, with a cross reference for each term. - - This manual is available as a printed book and also as an Info file. -The Info file is for on-line perusal with the Info program, which is -the principal means of accessing on-line documentation in the GNU -system. Both the Emacs Info file and an Info reader are included with -GNU Emacs. The Info file and the printed book contain substantially -the same text and are generated from the same source files, which are -also distributed with GNU Emacs. - - GNU Emacs is a member of the Emacs editor family. There are many -Emacs editors, all sharing common principles of organization. For -information on the underlying philosophy of Emacs and the lessons -learned from its development, see @cite{Emacs, the Extensible, -Customizable Self-Documenting Display Editor}, available from -@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}. - -This edition of the manual is intended for use with GNU Emacs -installed on GNU and Unix systems. GNU Emacs can also be used on VMS, -MS-DOS (also called MS-DOG), Microsoft Windows, and Macintosh systems. -Those systems use different file name syntax; in addition, VMS and -MS-DOS do not support all GNU Emacs features. @xref{Microsoft -Windows}, for information about using Emacs on Windows. -@xref{Mac OS}, for information about using Emacs on Macintosh. We -don't try to describe VMS usage in this manual. -@end iftex - -@node Distrib, Intro, Top, Top -@unnumbered Distribution - -GNU Emacs is @dfn{free software}; this means that everyone is free to -use it and free to redistribute it on certain conditions. GNU Emacs -is not in the public domain; it is copyrighted and there are -restrictions on its distribution, but these restrictions are designed -to permit everything that a good cooperating citizen would want to do. -What is not allowed is to try to prevent others from further sharing -any version of GNU Emacs that they might get from you. The precise -conditions are found in the GNU General Public License that comes with -Emacs and also appears in this manual@footnote{This manual is itself -covered by the GNU Free Documentation License. This license is -similar in spirit to the General Public License, but is more suitable -for documentation. @xref{GNU Free Documentation License}.}. -@xref{Copying}. - -One way to get a copy of GNU Emacs is from someone else who has it. -You need not ask for our permission to do so, or tell any one else; -just copy it. If you have access to the Internet, you can get the -latest distribution version of GNU Emacs by anonymous FTP; see -@url{http://www.gnu.org/software/emacs} on our website for more -information. - -You may also receive GNU Emacs when you buy a computer. Computer -manufacturers are free to distribute copies on the same terms that apply to -everyone else. These terms require them to give you the full sources, -including whatever changes they may have made, and to permit you to -redistribute the GNU Emacs received from them under the usual terms of the -General Public License. In other words, the program must be free for you -when you get it, not just free for the manufacturer. - -You can also order copies of GNU Emacs from the Free Software -Foundation. This is a convenient and reliable way to get a copy; it is -also a good way to help fund our work. We also sell hardcopy versions -of this manual and @cite{An Introduction to Programming in Emacs Lisp}, -by Robert J. Chassell. You can find an order form on our web site at -@url{http://www.gnu.org/order/order.html}. For further information, -write to - -@display -Free Software Foundation -51 Franklin Street, Fifth Floor -Boston, MA 02110-1301 -USA -@end display - -The income from distribution fees goes to support the foundation's -purpose: the development of new free software, and improvements to our -existing programs including GNU Emacs. - -If you find GNU Emacs useful, please @strong{send a donation} to the -Free Software Foundation to support our work. Donations to the Free -Software Foundation are tax deductible in the US. If you use GNU Emacs -at your workplace, please suggest that the company make a donation. If -company policy is unsympathetic to the idea of donating to charity, you -might instead suggest ordering a CD-ROM from the Foundation -occasionally, or subscribing to periodic updates. - -@iftex -@node Acknowledgments, Intro, Distrib, Top -@unnumberedsec Acknowledgments - -Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas -Abrahamsson, Jay K.@: Adams, Michael Albinus, Nagy Andras, Ralf -Angeli, Joe Arceneaux, Miles Bader, David Bakhash, Juanma Barranquero, -Eli Barzilay, Steven L.@: Baur, Jay Belanger, Alexander L.@: Belikoff, -Boaz Ben-Zvi, Karl Berry, Anna M.@: Bigatti, Ray Blaak, Jim Blandy, Johan Bockg@aa{}rd, -Per Bothner, Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel -Briot, Kevin Broadey, Vincent Broman, David M.@: Brown, Georges -Brun-Cottan, Joe Buehler, W@l{}odek Bzyl, Bill Carpenter, Per -Cederqvist, Hans Chalupsky, Chris Chase, Bob Chassell, Andrew Choi, -Sacha Chua, James Clark, Mike Clarkson, Glynn Clements, Andrew -Csillag, Doug Cutting, Mathias Dahl, Satyaki Das, Michael DeCorte, -Gary Delp, Matthieu Devin, Eri Ding, Jan Dj@"{a}rv, Carsten Dominik, -Scott Draves, Benjamin Drieu, Viktor Dukhovni, John Eaton, Rolf Ebert, -Paul Eggert, Stephen Eglen, Torbj@"orn Einarsson, Tsugutomo Enami, -Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick Farnbach, -Oscar Figueiredo, Fred Fish, Karl Fogel, Gary Foster, Romain -Francoise, Noah Friedman, Andreas Fuchs, Hallvard Furuseth, Keith -Gabryelski, Peter S.@: Galbraith, Kevin Gallagher, Kevin Gallo, Juan -Le@'{o}n Lahoz Garc@'{@dotless{i}}a, Howard Gayle, Stephen Gildea, Julien -Gilles, David Gillespie, Bob Glickstein, Deepak Goel, Boris Goldowsky, -Michelangelo Grigni, Odd Gripenstam, Kai Gro@ss{}johann, Michael -Gschwind, Henry Guillaume, Doug Gwyn, Ken'ichi Handa, Lars Hansen, -Chris Hanson, K. Shane Hartman, John Heidemann, Jon K.@: Hellan, -Jesper Harder, Markus Heritsch, Karl Heuer, Manabu Higashida, Anders -Holst, Jeffrey C.@: Honig, Kurt Hornik, Tom Houlder, Joakim Hove, -Denis Howe, Lars Ingebrigtsen, Andrew Innes, Seiichiro Inoue, Pavel -Janik, Paul Jarc, Ulf Jasper, Michael K. Johnson, Kyle Jones, Terry -Jones, Simon Josefsson, Arne J@o{}rgensen, Tomoji Kagatani, Brewster -Kahle, Lute Kamstra, David Kastrup, David Kaufman, Henry Kautz, Taichi -Kawabata, Howard Kaye, Michael Kifer, Richard King, Peter Kleiweg, -Shuhei Kobayashi, Pavel Kobiakov, Larry K.@: Kolodney, David M.@: -Koppelman, Koseki Yoshinori, Robert Krawitz, Sebastian Kremer, Ryszard -Kubiak, Geoff Kuenning, David K@aa{}gedal, Daniel LaLiberte, Mario -Lang, Aaron Larson, James R.@: Larus, Vinicius Jose Latorre, Werner -Lemberg, Frederic Lepied, Peter Liljenberg, Lars Lindberg, Chris -Lindblad, Anders Lindgren, Thomas Link, Juri Linkov, Francis Litterio, -Emilio C. Lopes, Dave Love, Sascha L@"{u}decke, Eric Ludlam,Alan -Mackenzie, Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer, -Bill Mann, Brian Marick, Simon Marshall, Bengt Martensson, Charlie -Martin, Thomas May, Roland McGrath, Will Mengarini, David Megginson, -Ben A. Mesander, Wayne Mesard, Brad Miller, Lawrence Mitchell, Richard -Mlynarik, Gerd Moellmann, Stefan Monnier, Morioka Tomohiko, Keith -Moore, Glenn Morris, Diane Murray, Sen Nagata, Erik Naggum, Thomas -Neumann, Thien-Thi Nguyen, Mike Newton, Jurgen Nickelsen, Dan -Nicolaescu, Hrvoje Niksic, Jeff Norden, Andrew Norman, Alexandre -Oliva, Bob Olson, Michael Olson, Takaaki Ota, Pieter E.@: J.@: Pareit, -David Pearson, Jeff Peck, Damon Anton Permezel, Tom Perrine, William -M.@: Perry, Per Persson, Jens Petersen, Daniel Pfeiffer, Richard L.@: -Pieri, Fred Pierresteguy, Christian Plaunt, David Ponce, Francesco -A.@: Potorti, Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko -Rahamaa, Ashwin Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, -Alex Rezinsky, Rob Riepel, David Reitter, Nick Roberts, Roland B.@: -Roberts, John Robinson, Danny Roozendaal, William Rosenblatt, -Guillermo J.@: Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, -Wolfgang Rupprecht, Kevin Ryde, James B. Salem, Masahiko Sato, Jorgen -Schaefer, Holger Schauer, William Schelter, Ralph Schleicher, Gregor -Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebelen, Jan -Schormann, Alex Schroeder, Stephen Schoef, Raymond Scholz, Randal -Schwartz, Oliver Seidel, Manuel Serrano, Hovav Shacham, Stanislav -Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Espen Skoglund, -Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul D.@: Smith, -Andre Spiegel, Michael Staats, William Sommerfeld, Michael Staats, -Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken -Stevens, Jonathan Stigelman, Martin Stjernholm, Kim F.@: Storm, Steve -Strassman, Olaf Sylvester, Naoto Takahashi, Steven Tamm, Jean-Philippe -Theberge, Jens T.@: Berger Thielemann, Spencer Thomas, Jim Thompson, -Luc Teirlinck, Tom Tromey, Enami Tsugutomo, Eli Tziperman, Daiki Ueno, -Masanobu Umeda, Rajesh Vaidheeswarran, Neil W.@: Van Dyke, Didier -Verna, Ulrik Vieth, Geoffrey Voelker, Johan Vromans, Inge Wallin, John -Paul Wallington, Colin Walters, Barry Warsaw, Morten Welinder, Joseph -Brian Wells, Rodney Whitby, John Wiegley, Ed Wilkinson, Mike Williams, -Bill Wohler, Steven A. Wood, Dale R.@: Worley, Francis J.@: Wright, -Felix S. T. Wu, Tom Wurgler, Katsumi Yamaoka, Masatake Yamato, -Jonathan Yavner, Ryan Yeske, Chong Yidong, Ilya Zakharevich, Milan -Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Shenghuo Zhu, -Ian T.@: Zimmermann, Reto Zimmermann, Neal Ziring, Teodor Zlatanov, -and Detlev Zundel. -@end iftex - -@node Intro, Glossary, Distrib, Top -@unnumbered Introduction - - You are reading about GNU Emacs, the GNU incarnation of the -advanced, self-documenting, customizable, extensible editor Emacs. -(The `G' in `GNU' is not silent.) - - We call Emacs advanced because it provides much more than simple -insertion and deletion. It can control subprocesses, indent programs -automatically, show two or more files at once, and edit formatted -text. Emacs editing commands operate in terms of characters, words, -lines, sentences, paragraphs, and pages, as well as expressions and -comments in various programming languages. - - @dfn{Self-documenting} means that at any time you can type a special -character, @kbd{Control-h}, to find out what your options are. You can -also use it to find out what any command does, or to find all the commands -that pertain to a topic. @xref{Help}. - - @dfn{Customizable} means that you can alter Emacs commands' behavior -in simple ways. For example, if you use a programming language in -which comments start with @samp{<**} and end with @samp{**>}, you can -tell the Emacs comment manipulation commands to use those strings -(@pxref{Comments}). Another sort of customization is rearrangement of -the command set. For example, you can rebind the basic cursor motion -commands (up, down, left and right) to any keys on the keyboard that -you find comfortable. @xref{Customization}. - - @dfn{Extensible} means that you can go beyond simple customization -and write entirely new commands---programs in the Lisp language to be -run by Emacs's own Lisp interpreter. Emacs is an ``on-line -extensible'' system, which means that it is divided into many -functions that call each other, any of which can be redefined in the -middle of an editing session. Almost any part of Emacs can be -replaced without making a separate copy of all of Emacs. Most of the -editing commands of Emacs are written in Lisp; the few exceptions -could have been written in Lisp but use C instead for efficiency. -Writing an extension is programming, but non-programmers can use it -afterwards. @xref{Top, Emacs Lisp Intro, Preface, eintr, An -Introduction to Programming in Emacs Lisp}, if you want to learn Emacs -Lisp programming. - - When running on a graphical display, Emacs provides its own menus -and convenient handling of mouse buttons. In addition, Emacs provides -many of the benefits of a graphical display even on a text-only -terminal. For instance, it can highlight parts of a file, display and -edit several files at once, move text between files, and edit files -while running shell commands. - -@include screen.texi -@include commands.texi -@include entering.texi -@include basic.texi -@include mini.texi -@include m-x.texi -@include help.texi -@include mark.texi -@include killing.texi -@include regs.texi -@include display.texi -@include search.texi -@include fixit.texi -@include kmacro.texi -@include files.texi -@include buffers.texi -@include windows.texi -@include frames.texi -@include mule.texi -@include major.texi -@include indent.texi -@include text.texi -@include programs.texi -@include building.texi -@include maintaining.texi -@include abbrevs.texi -@ifnottex -@include picture-xtra.texi -@end ifnottex -@include sending.texi -@include rmail.texi -@include dired.texi -@include calendar.texi -@include misc.texi -@include custom.texi -@include trouble.texi - -@node Copying, GNU Free Documentation License, Service, Top -@appendix GNU GENERAL PUBLIC LICENSE -@include gpl.texi - -@node GNU Free Documentation License, Emacs Invocation, Copying, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@include cmdargs.texi -@include xresources.texi - -@include anti.texi -@include macos.texi -@include msdog.texi -@include gnu.texi -@include glossary.texi -@ifnottex -@include ack.texi -@end ifnottex - -@c The Option Index is produced only in the on-line version, -@c because the index entries related to command-line options -@c tend to point to the same pages and all begin with a dash. -@c This, and the need to keep the node links consistent, are -@c the reasons for the funky @iftex/@ifnottex dance below. -@c The Option Index is _not_ before Key Index, because that -@c would require changes in the glossary.texi's @node line. -@c It is not after Concept Index for similar reasons. - -@iftex -@node Key Index, Command Index, Glossary, Top -@unnumbered Key (Character) Index -@printindex ky -@end iftex - -@ifnottex -@node Key Index, Option Index, Glossary, Top -@unnumbered Key (Character) Index -@printindex ky - -@node Option Index, Command Index, Key Index, Top -@unnumbered Command-Line Options Index -@printindex op - -@node Command Index, Variable Index, Option Index, Top -@unnumbered Command and Function Index -@printindex fn -@end ifnottex - -@iftex -@node Command Index, Variable Index, Key Index, Top -@unnumbered Command and Function Index -@printindex fn -@end iftex - -@node Variable Index, Concept Index, Command Index, Top -@unnumbered Variable Index -@printindex vr - -@node Concept Index, Acknowledgments, Variable Index, Top -@unnumbered Concept Index -@printindex cp - -@bye - -@ignore - arch-tag: ed48740a-410b-46ea-9387-c9a9252a3392 -@end ignore diff --git a/man/emerge-xtra.texi b/man/emerge-xtra.texi deleted file mode 100644 index e78f17e59d6..00000000000 --- a/man/emerge-xtra.texi +++ /dev/null @@ -1,414 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Emerge -@section Merging Files with Emerge -@cindex Emerge -@cindex merging files - - It's not unusual for programmers to get their signals crossed and -modify the same program in two different directions. To recover from -this confusion, you need to merge the two versions. Emerge makes this -easier. For other ways to compare files, see -@iftex -@ref{Comparing Files,,, emacs, the Emacs Manual}, -@end iftex -@ifnottex -@ref{Comparing Files}, -@end ifnottex -and @ref{Top, Ediff,, ediff, The Ediff Manual}. - -@menu -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Misc. -@end menu - -@node Overview of Emerge -@subsection Overview of Emerge - - To start Emerge, run one of these four commands: - -@table @kbd -@item M-x emerge-files -@findex emerge-files -Merge two specified files. - -@item M-x emerge-files-with-ancestor -@findex emerge-files-with-ancestor -Merge two specified files, with reference to a common ancestor. - -@item M-x emerge-buffers -@findex emerge-buffers -Merge two buffers. - -@item M-x emerge-buffers-with-ancestor -@findex emerge-buffers-with-ancestor -Merge two buffers with reference to a common ancestor in a third -buffer. -@end table - -@cindex merge buffer (Emerge) -@cindex A and B buffers (Emerge) - The Emerge commands compare two files or buffers, and display the -comparison in three buffers: one for each input text (the @dfn{A buffer} -and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging -takes place. The merge buffer shows the full merged text, not just the -differences. Wherever the two input texts differ, you can choose which -one of them to include in the merge buffer. - - The Emerge commands that take input from existing buffers use only -the accessible portions of those buffers, if they are narrowed. -@iftex -@xref{Narrowing,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Narrowing}. -@end ifnottex - - - If a common ancestor version is available, from which the two texts to -be merged were both derived, Emerge can use it to guess which -alternative is right. Wherever one current version agrees with the -ancestor, Emerge presumes that the other current version is a deliberate -change which should be kept in the merged version. Use the -@samp{with-ancestor} commands if you want to specify a common ancestor -text. These commands read three file or buffer names---variant A, -variant B, and the common ancestor. - - After the comparison is done and the buffers are prepared, the -interactive merging starts. You control the merging by typing special -@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). -For each run of differences between the input texts, you can choose -which one of them to keep, or edit them both together. - - The merge buffer uses a special major mode, Emerge mode, with commands -for making these choices. But you can also edit the buffer with -ordinary Emacs commands. - - At any given time, the attention of Emerge is focused on one -particular difference, called the @dfn{selected} difference. This -difference is marked off in the three buffers like this: - -@example -vvvvvvvvvvvvvvvvvvvv -@var{text that differs} -^^^^^^^^^^^^^^^^^^^^ -@end example - -@noindent -Emerge numbers all the differences sequentially and the mode -line always shows the number of the selected difference. - - Normally, the merge buffer starts out with the A version of the text. -But when the A version of a difference agrees with the common ancestor, -then the B version is initially preferred for that difference. - - Emerge leaves the merged text in the merge buffer when you exit. At -that point, you can save it in a file with @kbd{C-x C-w}. If you give a -numeric argument to @code{emerge-files} or -@code{emerge-files-with-ancestor}, it reads the name of the output file -using the minibuffer. (This is the last file name those commands read.) -Then exiting from Emerge saves the merged text in the output file. - - Normally, Emerge commands save the output buffer in its file when you -exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not -save the output buffer, but you can save it yourself if you wish. - -@node Submodes of Emerge -@subsection Submodes of Emerge - - You can choose between two modes for giving merge commands: Fast mode -and Edit mode. In Fast mode, basic merge commands are single -characters, but ordinary Emacs commands are disabled. This is -convenient if you use only merge commands. In Edit mode, all merge -commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs -commands are also available. This allows editing the merge buffer, but -slows down Emerge operations. - - Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to -Fast mode. The mode line indicates Edit and Fast modes with @samp{E} -and @samp{F}. - - Emerge has two additional submodes that affect how particular merge -commands work: Auto Advance mode and Skip Prefers mode. - - If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands -advance to the next difference. This lets you go through the merge -faster as long as you simply choose one of the alternatives from the -input. The mode line indicates Auto Advance mode with @samp{A}. - - If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands -skip over differences in states prefer-A and prefer-B (@pxref{State of -Difference}). Thus you see only differences for which neither version -is presumed ``correct.'' The mode line indicates Skip Prefers mode with -@samp{S}. - -@findex emerge-auto-advance-mode -@findex emerge-skip-prefers-mode - Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or -clear Auto Advance mode. Use @kbd{s s} -(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. -These commands turn on the mode with a positive argument, turns it off -with a negative or zero argument, and toggle the mode with no argument. - -@node State of Difference -@subsection State of a Difference - - In the merge buffer, a difference is marked with lines of @samp{v} and -@samp{^} characters. Each difference has one of these seven states: - -@table @asis -@item A -The difference is showing the A version. The @kbd{a} command always -produces this state; the mode line indicates it with @samp{A}. - -@item B -The difference is showing the B version. The @kbd{b} command always -produces this state; the mode line indicates it with @samp{B}. - -@item default-A -@itemx default-B -The difference is showing the A or the B state by default, because you -haven't made a choice. All differences start in the default-A state -(and thus the merge buffer is a copy of the A buffer), except those for -which one alternative is ``preferred'' (see below). - -When you select a difference, its state changes from default-A or -default-B to plain A or B. Thus, the selected difference never has -state default-A or default-B, and these states are never displayed in -the mode line. - -The command @kbd{d a} chooses default-A as the default state, and @kbd{d -b} chooses default-B. This chosen default applies to all differences -which you haven't ever selected and for which no alternative is preferred. -If you are moving through the merge sequentially, the differences you -haven't selected are those following the selected one. Thus, while -moving sequentially, you can effectively make the A version the default -for some sections of the merge buffer and the B version the default for -others by using @kbd{d a} and @kbd{d b} between sections. - -@item prefer-A -@itemx prefer-B -The difference is showing the A or B state because it is -@dfn{preferred}. This means that you haven't made an explicit choice, -but one alternative seems likely to be right because the other -alternative agrees with the common ancestor. Thus, where the A buffer -agrees with the common ancestor, the B version is preferred, because -chances are it is the one that was actually changed. - -These two states are displayed in the mode line as @samp{A*} and @samp{B*}. - -@item combined -The difference is showing a combination of the A and B states, as a -result of the @kbd{x c} or @kbd{x C} commands. - -Once a difference is in this state, the @kbd{a} and @kbd{b} commands -don't do anything to it unless you give them a numeric argument. - -The mode line displays this state as @samp{comb}. -@end table - -@node Merge Commands -@subsection Merge Commands - - Here are the Merge commands for Fast mode; in Edit mode, precede them -with @kbd{C-c C-c}: - -@table @kbd -@item p -Select the previous difference. - -@item n -Select the next difference. - -@item a -Choose the A version of this difference. - -@item b -Choose the B version of this difference. - -@item C-u @var{n} j -Select difference number @var{n}. - -@item . -Select the difference containing point. You can use this command in the -merge buffer or in the A or B buffer. - -@item q -Quit---finish the merge. - -@item C-] -Abort---exit merging and do not save the output. - -@item f -Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) - -@item e -Go into Edit mode. - -@item l -Recenter (like @kbd{C-l}) all three windows. - -@item - -Specify part of a prefix numeric argument. - -@item @var{digit} -Also specify part of a prefix numeric argument. - -@item d a -Choose the A version as the default from here down in -the merge buffer. - -@item d b -Choose the B version as the default from here down in -the merge buffer. - -@item c a -Copy the A version of this difference into the kill ring. - -@item c b -Copy the B version of this difference into the kill ring. - -@item i a -Insert the A version of this difference at point. - -@item i b -Insert the B version of this difference at point. - -@item m -Put point and mark around the difference. - -@item ^ -Scroll all three windows down (like @kbd{M-v}). - -@item v -Scroll all three windows up (like @kbd{C-v}). - -@item < -Scroll all three windows left (like @kbd{C-x <}). - -@item > -Scroll all three windows right (like @kbd{C-x >}). - -@item | -Reset horizontal scroll on all three windows. - -@item x 1 -Shrink the merge window to one line. (Use @kbd{C-u l} to restore it -to full size.) - -@item x c -Combine the two versions of this difference (@pxref{Combining in -Emerge}). - -@item x f -Show the names of the files/buffers Emerge is operating on, in a Help -window. (Use @kbd{C-u l} to restore windows.) - -@item x j -Join this difference with the following one. -(@kbd{C-u x j} joins this difference with the previous one.) - -@item x s -Split this difference into two differences. Before you use this -command, position point in each of the three buffers at the place where -you want to split the difference. - -@item x t -Trim identical lines off the top and bottom of the difference. -Such lines occur when the A and B versions are -identical but differ from the ancestor version. -@end table - -@node Exiting Emerge -@subsection Exiting Emerge - - The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing -the results into the output file if you specified one. It restores the -A and B buffers to their proper contents, or kills them if they were -created by Emerge and you haven't changed them. It also disables the -Emerge commands in the merge buffer, since executing them later could -damage the contents of the various buffers. - - @kbd{C-]} aborts the merge. This means exiting without writing the -output file. If you didn't specify an output file, then there is no -real difference between aborting and finishing the merge. - - If the Emerge command was called from another Lisp program, then its -return value is @code{t} for successful completion, or @code{nil} if you -abort. - -@node Combining in Emerge -@subsection Combining the Two Versions - - Sometimes you want to keep @emph{both} alternatives for a particular -difference. To do this, use @kbd{x c}, which edits the merge buffer -like this: - -@example -@group -#ifdef NEW -@var{version from A buffer} -#else /* not NEW */ -@var{version from B buffer} -#endif /* not NEW */ -@end group -@end example - -@noindent -@vindex emerge-combine-versions-template -While this example shows C preprocessor conditionals delimiting the two -alternative versions, you can specify the strings to use by setting -the variable @code{emerge-combine-versions-template} to a string of your -choice. In the string, @samp{%a} says where to put version A, and -@samp{%b} says where to put version B. The default setting, which -produces the results shown above, looks like this: - -@example -@group -"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" -@end group -@end example - -@node Fine Points of Emerge -@subsection Fine Points of Emerge - - During the merge, you mustn't try to edit the A and B buffers yourself. -Emerge modifies them temporarily, but ultimately puts them back the way -they were. - - You can have any number of merges going at once---just don't use any one -buffer as input to more than one merge at once, since the temporary -changes made in these buffers would get in each other's way. - - Starting Emerge can take a long time because it needs to compare the -files fully. Emacs can't do anything else until @code{diff} finishes. -Perhaps in the future someone will change Emerge to do the comparison in -the background when the input files are large---then you could keep on -doing other things with Emacs until Emerge is ready to accept -commands. - -@vindex emerge-startup-hook - After setting up the merge, Emerge runs the hook -@code{emerge-startup-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@ignore - arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e -@end ignore diff --git a/man/entering.texi b/man/entering.texi deleted file mode 100644 index e338a6a8619..00000000000 --- a/man/entering.texi +++ /dev/null @@ -1,170 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Entering Emacs, Exiting, Text Characters, Top -@chapter Entering and Exiting Emacs -@cindex entering Emacs -@cindex starting Emacs - - The usual way to invoke Emacs is with the shell command -@command{emacs}. Emacs clears the screen, then displays an initial -help message and copyright notice. Some operating systems discard -your type-ahead when Emacs starts up; they give Emacs no way to -prevent this. On those systems, wait for Emacs to clear the screen -before you start typing. - - From a shell window under the X Window System, run Emacs in the -background with @command{emacs&}. This way, Emacs won't tie up the -shell window, so you can use it to run other shell commands while -Emacs is running. You can type Emacs commands as soon as you direct -your keyboard input to an Emacs frame. - -@vindex initial-major-mode - When Emacs starts up, it creates a buffer named @samp{*scratch*}. -That's the buffer you start out in. The @samp{*scratch*} buffer uses -Lisp Interaction mode; you can use it to type Lisp expressions and -evaluate them. You can also ignore that capability and just write notes -there. You can specify a different major mode for this buffer by -setting the variable @code{initial-major-mode} in your init file. -@xref{Init File}. - - It is possible to specify files to be visited, Lisp files to be -loaded, and functions to be called through Emacs command-line -arguments. @xref{Emacs Invocation}. The feature exists mainly for -compatibility with other editors, and for scripts. - - Many editors are designed to edit one file. When done with that -file, you exit the editor. The next time you want to edit a file, you -must start the editor again. Working this way, it is convenient to -use a command-line argument to say which file to edit. - - However, killing Emacs after editing one each and starting it afresh -for the next file is both unnecessary and harmful, since it denies you -the full power of Emacs. Emacs can visit more than one file in a -single editing session, and that is the right way to use it. Exiting -the Emacs session loses valuable accumulated context, such as the kill -ring, registers, undo history, and mark ring. These features are -useful for operating on multiple files, or even continuing to edit one -file. If you kill Emacs after each file, you don't take advantage of -them. - - The recommended way to use GNU Emacs is to start it only once, just -after you log in, and do all your editing in the same Emacs session. -Each time you edit a file, you visit it with the existing Emacs, which -eventually has many files in it ready for editing. Usually you do not -kill Emacs until you are about to log out. @xref{Files}, for more -information on visiting more than one file. - - To edit a file from another program while Emacs is running, you can -use the @command{emacsclient} helper program to open a file in the -already running Emacs. @xref{Emacs Server}. - -@ifnottex -@raisesections -@end ifnottex - -@node Exiting, Basic, Entering Emacs, Top -@section Exiting Emacs -@cindex exiting -@cindex killing Emacs -@cindex suspending -@cindex leaving Emacs -@cindex quitting Emacs - - There are two commands for exiting Emacs, and three kinds of -exiting: @dfn{iconifying} Emacs, @dfn{suspending} Emacs, and -@dfn{killing} Emacs. - - @dfn{Iconifying} means replacing the Emacs frame with a small box or -``icon'' on the screen. This is the usual way to exit Emacs when -you're using a graphical display---if you bother to ``exit'' at all. -(Just switching to another application is usually sufficient.) - - @dfn{Suspending} means stopping Emacs temporarily and returning -control to its parent process (usually a shell), allowing you to -resume editing later in the same Emacs job. This is the usual way to -exit Emacs when running it on a text terminal. - - @dfn{Killing} Emacs means destroying the Emacs job. You can run Emacs -again later, but you will get a fresh Emacs; there is no way to resume -the same editing session after it has been killed. - -@table @kbd -@item C-z -Suspend Emacs (@code{suspend-emacs}) or iconify a frame -(@code{iconify-or-deiconify-frame}). -@item C-x C-c -Kill Emacs (@code{save-buffers-kill-emacs}). -@end table - -@kindex C-z -@findex iconify-or-deiconify-frame - On graphical displays, @kbd{C-z} runs the command -@code{iconify-or-deiconify-frame}, which temporarily iconifies (or -``minimizes'') the selected Emacs frame (@pxref{Frames}). You can -then use the window manager to select some other application. (You -could select another application without iconifying Emacs first, but -getting the Emacs frame out of the way can make it more convenient to -find the other application.) - -@findex suspend-emacs - On a text terminal, @kbd{C-z} runs the command @code{suspend-emacs}. -Suspending Emacs takes you back to the shell from which you invoked -Emacs. You can resume Emacs with the shell command @command{%emacs} -in most common shells. On systems that don't support suspending -programs, @kbd{C-z} starts an inferior shell that communicates -directly with the terminal, and Emacs waits until you exit the -subshell. (The way to do that is probably with @kbd{C-d} or -@command{exit}, but it depends on which shell you use.) On these -systems, you can only get back to the shell from which Emacs was run -(to log out, for example) when you kill Emacs. - -@vindex cannot-suspend - Suspending can fail if you run Emacs under a shell that doesn't -support suspendion of its subjobs, even if the system itself does -support it. In such a case, you can set the variable -@code{cannot-suspend} to a non-@code{nil} value to force @kbd{C-z} to -start an inferior shell. - -@kindex C-x C-c -@findex save-buffers-kill-emacs - To exit and kill Emacs, type @kbd{C-x C-c} -(@code{save-buffers-kill-emacs}). A two-character key is used to make -it harder to type by accident. This command first offers to save any -modified file-visiting buffers. If you do not save them all, it asks -for confirmation with @kbd{yes} before killing Emacs, since any -changes not saved now will be lost forever. Also, if any subprocesses are -still running, @kbd{C-x C-c} asks for confirmation about them, since -killing Emacs will also kill the subprocesses. - -@vindex confirm-kill-emacs - If the value of the variable @code{confirm-kill-emacs} is -non-@code{nil}, @kbd{C-x C-c} assumes that its value is a predicate -function, and calls that function. If the result is non-@code{nil}, the -session is killed, otherwise Emacs continues to run. One convenient -function to use as the value of @code{confirm-kill-emacs} is the -function @code{yes-or-no-p}. The default value of -@code{confirm-kill-emacs} is @code{nil}. - - You can't resume an Emacs session after killing it. Emacs can, -however, record certain session information when you kill it, such as -which files you visited, so the next time you start Emacs it will try -to visit the same files. @xref{Saving Emacs Sessions}. - - The operating system usually listens for certain special characters -whose meaning is to kill or suspend the program you are running. -@b{This operating system feature is turned off while you are in Emacs.} -The meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were -inspired by the use of @kbd{C-z} and @kbd{C-c} on several operating -systems as the characters for stopping or killing a program, but that is -their only relationship with the operating system. You can customize -these keys to run any commands of your choice (@pxref{Keymaps}). - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: df798d8b-f253-4113-b585-f528f078a944 -@end ignore diff --git a/man/erc.texi b/man/erc.texi deleted file mode 100644 index 3e52bb42c92..00000000000 --- a/man/erc.texi +++ /dev/null @@ -1,1027 +0,0 @@ -\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/man/eshell.texi b/man/eshell.texi deleted file mode 100644 index 3a4b705d2c9..00000000000 --- a/man/eshell.texi +++ /dev/null @@ -1,948 +0,0 @@ -\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/man/eudc.texi b/man/eudc.texi deleted file mode 100644 index 7a8dbbee524..00000000000 --- a/man/eudc.texi +++ /dev/null @@ -1,985 +0,0 @@ -\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/man/faq.texi b/man/faq.texi deleted file mode 100644 index b7fe5dca4a2..00000000000 --- a/man/faq.texi +++ /dev/null @@ -1,5590 +0,0 @@ -\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/man/files.texi b/man/files.texi deleted file mode 100644 index 7ba36916684..00000000000 --- a/man/files.texi +++ /dev/null @@ -1,2950 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Files, Buffers, Keyboard Macros, Top -@chapter File Handling -@cindex files - - The operating system stores data permanently in named @dfn{files}, so -most of the text you edit with Emacs comes from a file and is ultimately -stored in a file. - - To edit a file, you must tell Emacs to read the file and prepare a -buffer containing a copy of the file's text. This is called -@dfn{visiting} the file. Editing commands apply directly to text in the -buffer; that is, to the copy inside Emacs. Your changes appear in the -file itself only when you @dfn{save} the buffer back into the file. - - In addition to visiting and saving files, Emacs can delete, copy, -rename, and append to files, keep multiple versions of them, and operate -on file directories. - -@menu -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Version Control:: Version control systems (RCS, CVS and SCCS). -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other sites. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. -@end menu - -@node File Names -@section File Names -@cindex file names - - Most Emacs commands that operate on a file require you to specify the -file name. (Saving and reverting are exceptions; the buffer knows which -file name to use for them.) You enter the file name using the -minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available -(@pxref{Completion}) to make it easier to specify long file names. When -completing file names, Emacs ignores those whose file-name extensions -appear in the variable @code{completion-ignored-extensions}; see -@ref{Completion Options}. - - For most operations, there is a @dfn{default file name} which is used -if you type just @key{RET} to enter an empty argument. Normally the -default file name is the name of the file visited in the current buffer; -this makes it easy to operate on that file with any of the Emacs file -commands. - -@vindex default-directory - Each buffer has a default directory which is normally the same as the -directory of the file visited in that buffer. When you enter a file -name without a directory, the default directory is used. If you specify -a directory in a relative fashion, with a name that does not start with -a slash, it is interpreted with respect to the default directory. The -default directory is kept in the variable @code{default-directory}, -which has a separate value in every buffer. - -@findex cd -@findex pwd - The command @kbd{M-x pwd} displays the current buffer's default -directory, and the command @kbd{M-x cd} sets it (to a value read using -the minibuffer). A buffer's default directory changes only when the -@code{cd} command is used. A file-visiting buffer's default directory -is initialized to the directory of the file it visits. If you create -a buffer with @kbd{C-x b}, its default directory is copied from that -of the buffer that was current at the time. - - For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} -then the default directory is normally @file{/u/rms/gnu/}. If you -type just @samp{foo}, which does not specify a directory, it is short -for @file{/u/rms/gnu/foo}. @samp{../.login} would stand for -@file{/u/rms/.login}. @samp{new/foo} would stand for the file name -@file{/u/rms/gnu/new/foo}. - -@vindex insert-default-directory - The default directory actually appears in the minibuffer when the -minibuffer becomes active to read a file name. This serves two -purposes: it @emph{shows} you what the default is, so that you can type -a relative file name and know with certainty what it will mean, and it -allows you to @emph{edit} the default to specify a different directory. -This insertion of the default directory is inhibited if the variable -@code{insert-default-directory} is set to @code{nil}. - - Note that it is legitimate to type an absolute file name after you -enter the minibuffer, ignoring the presence of the default directory -name as part of the text. The final minibuffer contents may look -invalid, but that is not so. For example, if the minibuffer starts out -with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get -@samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the -first slash in the double slash; the result is @samp{/x1/rms/foo}. -@xref{Minibuffer File}. - -@cindex home directory shorthand - You can use @file{~/} in a file name to mean your home directory, -or @file{~@var{user-id}/} to mean the home directory of a user whose -login name is @code{user-id}@footnote{ -On MS-Windows and MS-DOS systems, where a user doesn't have a home -directory, Emacs replaces @file{~/} with the value of the -environment variable @code{HOME}; see @ref{General Variables}. On -these systems, the @file{~@var{user-id}/} construct is supported only -for the current user, i.e., only if @var{user-id} is the current -user's login name.}. - -@cindex environment variables in file names -@cindex expansion of environment variables -@cindex @code{$} in file names - @anchor{File Names with $}@samp{$} in a file name is used to -substitute an environment variable. The environment variable name -consists of all the alphanumeric characters after the @samp{$}; -alternatively, it can be enclosed in braces after the @samp{$}. For -example, if you have used the shell command @command{export -FOO=rms/hacks} to set up an environment variable named @env{FOO}, then -you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an -abbreviation for @file{/u/rms/hacks/test.c}. If the environment -variable is not defined, no substitution occurs: @file{/u/$notdefined} -stands for itself (assuming the environment variable @env{notdefined} -is not defined). - - Note that shell commands to set environment variables affect Emacs -only when done before Emacs is started. - - To access a file with @samp{$} in its name, if the @samp{$} causes -expansion, type @samp{$$}. This pair is converted to a single -@samp{$} at the same time as variable substitution is performed for a -single @samp{$}. Alternatively, quote the whole file name with -@samp{/:} (@pxref{Quoted File Names}). File names which begin with a -literal @samp{~} should also be quoted with @samp{/:}. - -@findex substitute-in-file-name - The Lisp function that performs the @samp{$}-substitution is called -@code{substitute-in-file-name}. The substitution is performed only on -file names read as such using the minibuffer. - - You can include non-@acronym{ASCII} characters in file names if you set the -variable @code{file-name-coding-system} to a non-@code{nil} value. -@xref{File Name Coding}. - -@node Visiting -@section Visiting Files -@cindex visiting files -@cindex open file - -@table @kbd -@item C-x C-f -Visit a file (@code{find-file}). -@item C-x C-r -Visit a file for viewing, without allowing changes to it -(@code{find-file-read-only}). -@item C-x C-v -Visit a different file instead of the one visited last -(@code{find-alternate-file}). -@item C-x 4 f -Visit a file, in another window (@code{find-file-other-window}). Don't -alter what is displayed in the selected window. -@item C-x 5 f -Visit a file, in a new frame (@code{find-file-other-frame}). Don't -alter what is displayed in the selected frame. -@item M-x find-file-literally -Visit a file with no conversion of the contents. -@end table - -@cindex files, visiting and saving -@cindex saving files - @dfn{Visiting} a file means reading its contents into an Emacs -buffer so you can edit them. Emacs makes a new buffer for each file -that you visit. We often say that this buffer ``is visiting'' that -file, or that the buffer's ``visited file'' is that file. Emacs -constructs the buffer name from the file name by throwing away the -directory, keeping just the name proper. For example, a file named -@file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}. -If there is already a buffer with that name, Emacs constructs a unique -name---the normal method is to append @samp{<2>}, @samp{<3>}, and so -on, but you can select other methods (@pxref{Uniquify}). - - Each window's mode line shows the name of the buffer that is being displayed -in that window, so you can always tell what buffer you are editing. - - The changes you make with editing commands are made in the Emacs -buffer. They do not take effect in the file that you visited, or any -permanent place, until you @dfn{save} the buffer. Saving the buffer -means that Emacs writes the current contents of the buffer into its -visited file. @xref{Saving}. - -@cindex modified (buffer) - If a buffer contains changes that have not been saved, we say the -buffer is @dfn{modified}. This is important because it implies that -some changes will be lost if the buffer is not saved. The mode line -displays two stars near the left margin to indicate that the buffer is -modified. - -@kindex C-x C-f -@findex find-file - To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow -the command with the name of the file you wish to visit, terminated by a -@key{RET}. - - The file name is read using the minibuffer (@pxref{Minibuffer}), with -defaulting and completion in the standard manner (@pxref{File Names}). -While in the minibuffer, you can abort @kbd{C-x C-f} by typing -@kbd{C-g}. File-name completion ignores certain file names; for more -about this, see @ref{Completion Options}. - - Your confirmation that @kbd{C-x C-f} has completed successfully is -the appearance of new text on the screen and a new buffer name in the -mode line. If the specified file does not exist and you could not -create it, or exists but you can't read it, then you get an error, -with an error message displayed in the echo area. - - If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make -another copy. It selects the existing buffer containing that file. -However, before doing so, it checks whether the file itself has changed -since you visited or saved it last. If the file has changed, Emacs offers -to reread it. - -@vindex large-file-warning-threshold -@cindex maximum buffer size exceeded, error message - If you try to visit a file larger than -@code{large-file-warning-threshold} (the default is 10000000, which is -about 10 megabytes), Emacs will ask you for confirmation first. You -can answer @kbd{y} to proceed with visiting the file. Note, however, -that Emacs cannot visit files that are larger than the maximum Emacs -buffer size, which is around 256 megabytes on 32-bit machines -(@pxref{Buffers}). If you try, Emacs will display an error message -saying that the maximum buffer size has been exceeded. - -@cindex file selection dialog - On graphical displays there are two additional methods for -visiting files. Firstly, when Emacs is built with a suitable GUI -toolkit, commands invoked with the mouse (by clicking on the menu bar -or tool bar) use the toolkit's standard File Selection dialog instead -of prompting for the file name in the minibuffer. On Unix and -GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and -Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. -For information on how to customize this, see @ref{Dialog Boxes}. - - Secondly, Emacs supports ``drag and drop''; dropping a file into an -ordinary Emacs window visits the file using that window. However, -dropping a file into a window displaying a Dired buffer moves or -copies the file into the displayed directory. For details, see -@ref{Drag and Drop}, and @ref{Misc Dired Features}. - -@cindex creating files - What if you want to create a new file? Just visit it. Emacs displays -@samp{(New file)} in the echo area, but in other respects behaves as if -you had visited an existing empty file. If you make any changes and -save them, the file is created. - - Emacs recognizes from the contents of a file which end-of-line -convention it uses to separate lines---newline (used on GNU/Linux and -on Unix), carriage-return linefeed (used on Microsoft systems), or -just carriage-return (used on the Macintosh)---and automatically -converts the contents to the normal Emacs convention, which is that -the newline character separates lines. This is a part of the general -feature of coding system conversion (@pxref{Coding Systems}), and -makes it possible to edit files imported from different operating -systems with equal convenience. If you change the text and save the -file, Emacs performs the inverse conversion, changing newlines back -into carriage-return linefeed or just carriage-return if appropriate. - -@vindex find-file-run-dired - If the file you specify is actually a directory, @kbd{C-x C-f} invokes -Dired, the Emacs directory browser, so that you can ``edit'' the contents -of the directory (@pxref{Dired}). Dired is a convenient way to view, delete, -or operate on the files in the directory. However, if the variable -@code{find-file-run-dired} is @code{nil}, then it is an error to try -to visit a directory. - - Files which are actually collections of other files, or @dfn{file -archives}, are visited in special modes which invoke a Dired-like -environment to allow operations on archive members. @xref{File -Archives}, for more about these features. - -@cindex wildcard characters in file names -@vindex find-file-wildcards - If the file name you specify contains shell-style wildcard -characters, Emacs visits all the files that match it. (On -case-insensitive filesystems, Emacs matches the wildcards disregarding -the letter case.) Wildcards include @samp{?}, @samp{*}, and -@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file -name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted -File Names}, for information on how to visit a file whose name -actually contains wildcard characters. You can disable the wildcard -feature by customizing @code{find-file-wildcards}. - - If you visit a file that the operating system won't let you modify, -or that is marked read-only, Emacs makes the buffer read-only too, so -that you won't go ahead and make changes that you'll have trouble -saving afterward. You can make the buffer writable with @kbd{C-x C-q} -(@code{toggle-read-only}). @xref{Misc Buffer}. - -@kindex C-x C-r -@findex find-file-read-only - If you want to visit a file as read-only in order to protect -yourself from entering changes accidentally, visit it with the command -@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. - -@kindex C-x C-v -@findex find-alternate-file - If you visit a nonexistent file unintentionally (because you typed the -wrong file name), use the @kbd{C-x C-v} command -(@code{find-alternate-file}) to visit the file you really wanted. -@kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current -buffer (after first offering to save it if it is modified). When -@kbd{C-x C-v} reads the file name to visit, it inserts the entire -default file name in the buffer, with point just after the directory -part; this is convenient if you made a slight error in typing the name. - -@kindex C-x 4 f -@findex find-file-other-window - @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} -except that the buffer containing the specified file is selected in another -window. The window that was selected before @kbd{C-x 4 f} continues to -show the same buffer it was already showing. If this command is used when -only one window is being displayed, that window is split in two, with one -window showing the same buffer as before, and the other one showing the -newly requested file. @xref{Windows}. - -@kindex C-x 5 f -@findex find-file-other-frame - @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a -new frame, or makes visible any existing frame showing the file you -seek. This feature is available only when you are using a window -system. @xref{Frames}. - -@findex find-file-literally - If you wish to edit a file as a sequence of @acronym{ASCII} characters with no special -encoding or conversion, use the @kbd{M-x find-file-literally} command. -It visits a file, like @kbd{C-x C-f}, but does not do format conversion -(@pxref{Formatted Text}), character code conversion (@pxref{Coding -Systems}), or automatic uncompression (@pxref{Compressed Files}), and -does not add a final newline because of @code{require-final-newline}. -If you already have visited the same file in the usual (non-literal) -manner, this command asks you whether to visit it literally instead. - -@vindex find-file-hook -@vindex find-file-not-found-functions - Two special hook variables allow extensions to modify the operation of -visiting files. Visiting a file that does not exist runs the functions -in the list @code{find-file-not-found-functions}; this variable holds a list -of functions, and the functions are called one by one (with no -arguments) until one of them returns non-@code{nil}. This is not a -normal hook, and the name ends in @samp{-functions} rather than @samp{-hook} -to indicate that fact. - - Successful visiting of any file, whether existing or not, calls the -functions in the list @code{find-file-hook}, with no arguments. -This variable is a normal hook. In the case of a nonexistent file, the -@code{find-file-not-found-functions} are run first. @xref{Hooks}. - - There are several ways to specify automatically the major mode for -editing the file (@pxref{Choosing Modes}), and to specify local -variables defined for that file (@pxref{File Variables}). - -@node Saving -@section Saving Files - - @dfn{Saving} a buffer in Emacs means writing its contents back into the file -that was visited in the buffer. - -@menu -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* Shadowing: File Shadowing. Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. -@end menu - -@node Save Commands -@subsection Commands for Saving Files - - These are the commands that relate to saving and writing files. - -@table @kbd -@item C-x C-s -Save the current buffer in its visited file on disk (@code{save-buffer}). -@item C-x s -Save any or all buffers in their visited files (@code{save-some-buffers}). -@item M-~ -Forget that the current buffer has been changed (@code{not-modified}). -With prefix argument (@kbd{C-u}), mark the current buffer as changed. -@item C-x C-w -Save the current buffer with a specified file name (@code{write-file}). -@item M-x set-visited-file-name -Change the file name under which the current buffer will be saved. -@end table - -@kindex C-x C-s -@findex save-buffer - When you wish to save the file and make your changes permanent, type -@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} -displays a message like this: - -@example -Wrote /u/rms/gnu/gnu.tasks -@end example - -@noindent -If the selected buffer is not modified (no changes have been made in it -since the buffer was created or last saved), saving is not really done, -because it would have no effect. Instead, @kbd{C-x C-s} displays a message -like this in the echo area: - -@example -(No changes need to be saved) -@end example - -@kindex C-x s -@findex save-some-buffers - The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any -or all modified buffers. It asks you what to do with each buffer. The -possible responses are analogous to those of @code{query-replace}: - -@table @kbd -@item y -Save this buffer and ask about the rest of the buffers. -@item n -Don't save this buffer, but ask about the rest of the buffers. -@item ! -Save this buffer and all the rest with no more questions. -@c following generates acceptable underfull hbox -@item @key{RET} -Terminate @code{save-some-buffers} without any more saving. -@item . -Save this buffer, then exit @code{save-some-buffers} without even asking -about other buffers. -@item C-r -View the buffer that you are currently being asked about. When you exit -View mode, you get back to @code{save-some-buffers}, which asks the -question again. -@item d -Diff the buffer against its corresponding file, so you can see -what changes you would be saving. -@item C-h -Display a help message about these options. -@end table - - @kbd{C-x C-c}, the key sequence to exit Emacs, invokes -@code{save-some-buffers} and therefore asks the same questions. - -@kindex M-~ -@findex not-modified - If you have changed a buffer but you do not want to save the changes, -you should take some action to prevent it. Otherwise, each time you use -@kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by -mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}), -which clears out the indication that the buffer is modified. If you do -this, none of the save commands will believe that the buffer needs to be -saved. (@samp{~} is often used as a mathematical symbol for `not'; thus -@kbd{M-~} is `not', metafied.) You could also use -@code{set-visited-file-name} (see below) to mark the buffer as visiting -a different file name, one which is not in use for anything important. -Alternatively, you can cancel all the changes made since the file was -visited or saved, by reading the text from the file again. This is -called @dfn{reverting}. @xref{Reverting}. (You could also undo all the -changes by repeating the undo command @kbd{C-x u} until you have undone -all the changes; but reverting is easier.) You can also kill the buffer. - -@findex set-visited-file-name - @kbd{M-x set-visited-file-name} alters the name of the file that the -current buffer is visiting. It reads the new file name using the -minibuffer. Then it marks the buffer as visiting that file name, and -changes the buffer name correspondingly. @code{set-visited-file-name} -does not save the buffer in the newly visited file; it just alters the -records inside Emacs in case you do save later. It also marks the -buffer as ``modified'' so that @kbd{C-x C-s} in that buffer -@emph{will} save. - -@kindex C-x C-w -@findex write-file - If you wish to mark the buffer as visiting a different file and save it -right away, use @kbd{C-x C-w} (@code{write-file}). It is -equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s} -(except that @kbd{C-x C-w} asks for confirmation if the file exists). -@kbd{C-x C-s} used on a buffer that is not visiting a file has the -same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the -buffer as visiting that file, and saves it there. The default file name in -a buffer that is not visiting a file is made by combining the buffer name -with the buffer's default directory (@pxref{File Names}). - - If the new file name implies a major mode, then @kbd{C-x C-w} switches -to that major mode, in most cases. The command -@code{set-visited-file-name} also does this. @xref{Choosing Modes}. - - If Emacs is about to save a file and sees that the date of the latest -version on disk does not match what Emacs last read or wrote, Emacs -notifies you of this fact, because it probably indicates a problem caused -by simultaneous editing and requires your immediate attention. -@xref{Interlocking,, Simultaneous Editing}. - -@node Backup -@subsection Backup Files -@cindex backup file -@vindex make-backup-files -@vindex vc-make-backup-files - - On most operating systems, rewriting a file automatically destroys all -record of what the file used to contain. Thus, saving a file from Emacs -throws away the old contents of the file---or it would, except that -Emacs carefully copies the old contents to another file, called the -@dfn{backup} file, before actually saving. - - For most files, the variable @code{make-backup-files} determines -whether to make backup files. On most operating systems, its default -value is @code{t}, so that Emacs does write backup files. - - For files managed by a version control system (@pxref{Version -Control}), the variable @code{vc-make-backup-files} determines whether -to make backup files. By default it is @code{nil}, since backup files -are redundant when you store all the previous versions in a version -control system. -@iftex -@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{General VC Options}. -@end ifnottex - - - At your option, Emacs can keep either a single backup for each file, -or make a series of numbered backup files for each file that you edit. - -@vindex backup-enable-predicate -@vindex temporary-file-directory -@vindex small-temporary-file-directory - The default value of the @code{backup-enable-predicate} variable -prevents backup files being written for files in the directories used -for temporary files, specified by @code{temporary-file-directory} or -@code{small-temporary-file-directory}. - - Emacs makes a backup for a file only the first time the file is saved -from one buffer. No matter how many times you save a file, its backup file -continues to contain the contents from before the file was visited. -Normally this means that the backup file contains the contents from before -the current editing session; however, if you kill the buffer and then visit -the file again, a new backup file will be made by the next save. - - You can also explicitly request making another backup file from a -buffer even though it has already been saved at least once. If you save -the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made -into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s} -saves the buffer, but first makes the previous file contents into a new -backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a -backup from the previous contents, and arranges to make another from the -newly saved contents if you save again. - -@menu -* One or Many: Numbered Backups. Whether to make one backup file or many. -* Names: Backup Names. How backup files are named. -* Deletion: Backup Deletion. Emacs deletes excess numbered backups. -* Copying: Backup Copying. Backups can be made by copying or renaming. -@end menu - -@node Numbered Backups -@subsubsection Numbered Backups - -@vindex version-control - The choice of single backup file or multiple numbered backup files -is controlled by the variable @code{version-control}. Its possible -values are: - -@table @code -@item t -Make numbered backups. -@item nil -Make numbered backups for files that have numbered backups already. -Otherwise, make single backups. -@item never -Never make numbered backups; always make single backups. -@end table - -@noindent -The usual way to set this variable is globally, through your -@file{.emacs} file or the customization buffer. However, you can set -@code{version-control} locally in an individual buffer to control the -making of backups for that buffer's file. For example, Rmail mode -locally sets @code{version-control} to @code{never} to make sure that -there is only one backup for an Rmail file. @xref{Locals}. - -@cindex @env{VERSION_CONTROL} environment variable - If you set the environment variable @env{VERSION_CONTROL}, to tell -various GNU utilities what to do with backup files, Emacs also obeys the -environment variable by setting the Lisp variable @code{version-control} -accordingly at startup. If the environment variable's value is @samp{t} -or @samp{numbered}, then @code{version-control} becomes @code{t}; if the -value is @samp{nil} or @samp{existing}, then @code{version-control} -becomes @code{nil}; if it is @samp{never} or @samp{simple}, then -@code{version-control} becomes @code{never}. - -@node Backup Names -@subsubsection Single or Numbered Backups - - When Emacs makes a single backup file, its name is normally -constructed by appending @samp{~} to the file name being edited; thus, -the backup file for @file{eval.c} would be @file{eval.c~}. - -@vindex make-backup-file-name-function -@vindex backup-directory-alist - You can change this behavior by defining the variable -@code{make-backup-file-name-function} to a suitable function. -Alternatively you can customize the variable -@code{backup-directory-alist} to specify that files matching certain -patterns should be backed up in specific directories. - - A typical use is to add an element @code{("." . @var{dir})} to make -all backups in the directory with absolute name @var{dir}; Emacs -modifies the backup file names to avoid clashes between files with the -same names originating in different directories. Alternatively, -adding, say, @code{("." . ".~")} would make backups in the invisible -subdirectory @file{.~} of the original file's directory. Emacs -creates the directory, if necessary, to make the backup. - - If access control stops Emacs from writing backup files under the usual -names, it writes the backup file as @file{%backup%~} in your home -directory. Only one such file can exist, so only the most recently -made such backup is available. - - If you choose to have a series of numbered backup files, backup file -names contain @samp{.~}, the number, and another @samp{~} after the -original file name. Thus, the backup files of @file{eval.c} would be -called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way -through names like @file{eval.c.~259~} and beyond. The variable -@code{backup-directory-alist} applies to numbered backups just as -usual. - -@node Backup Deletion -@subsubsection Automatic Deletion of Backups - - To prevent excessive consumption of disk space, Emacs can delete numbered -backup versions automatically. Generally Emacs keeps the first few backups -and the latest few backups, deleting any in between. This happens every -time a new backup is made. - -@vindex kept-old-versions -@vindex kept-new-versions - The two variables @code{kept-old-versions} and -@code{kept-new-versions} control this deletion. Their values are, -respectively, the number of oldest (lowest-numbered) backups to keep -and the number of newest (highest-numbered) ones to keep, each time a -new backup is made. The backups in the middle (excluding those oldest -and newest) are the excess middle versions---those backups are -deleted. These variables' values are used when it is time to delete -excess versions, just after a new backup version is made; the newly -made backup is included in the count in @code{kept-new-versions}. By -default, both variables are 2. - -@vindex delete-old-versions - If @code{delete-old-versions} is @code{t}, Emacs deletes the excess -backup files silently. If it is @code{nil}, the default, Emacs asks -you whether it should delete the excess backup versions. If it has -any other value, then Emacs never automatically deletes backups. - - Dired's @kbd{.} (Period) command can also be used to delete old versions. -@xref{Dired Deletion}. - -@node Backup Copying -@subsubsection Copying vs.@: Renaming - - Backup files can be made by copying the old file or by renaming it. -This makes a difference when the old file has multiple names (hard -links). If the old file is renamed into the backup file, then the -alternate names become names for the backup file. If the old file is -copied instead, then the alternate names remain names for the file -that you are editing, and the contents accessed by those names will be -the new contents. - - The method of making a backup file may also affect the file's owner -and group. If copying is used, these do not change. If renaming is used, -you become the file's owner, and the file's group becomes the default -(different operating systems have different defaults for the group). - - Having the owner change is usually a good idea, because then the owner -always shows who last edited the file. Also, the owners of the backups -show who produced those versions. Occasionally there is a file whose -owner should not change; it is a good idea for such files to contain -local variable lists to set @code{backup-by-copying-when-mismatch} -locally (@pxref{File Variables}). - -@vindex backup-by-copying -@vindex backup-by-copying-when-linked -@vindex backup-by-copying-when-mismatch -@vindex backup-by-copying-when-privileged-mismatch -@cindex file ownership, and backup -@cindex backup, and user-id - The choice of renaming or copying is controlled by four variables. -Renaming is the default choice. If the variable -@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, -if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, -then copying is used for files that have multiple names, but renaming -may still be used when the file being edited has only one name. If the -variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then -copying is used if renaming would cause the file's owner or group to -change. @code{backup-by-copying-when-mismatch} is @code{t} by default -if you start Emacs as the superuser. The fourth variable, -@code{backup-by-copying-when-privileged-mismatch}, gives the highest -numeric user-id for which @code{backup-by-copying-when-mismatch} will be -forced on. This is useful when low-numbered user-ids are assigned to -special system users, such as @code{root}, @code{bin}, @code{daemon}, -etc., which must maintain ownership of files. - - When a file is managed with a version control system (@pxref{Version -Control}), Emacs does not normally make backups in the usual way for -that file. But check-in and check-out are similar in some ways to -making backups. One unfortunate similarity is that these operations -typically break hard links, disconnecting the file name you visited from -any alternate names for the same file. This has nothing to do with -Emacs---the version control system does it. - -@node Customize Save -@subsection Customizing Saving of Files - -@vindex require-final-newline - If the value of the variable @code{require-final-newline} is -@code{t}, saving or writing a file silently puts a newline at the end -if there isn't already one there. If the value is @code{visit}, Emacs -adds a newline at the end of any file that doesn't have one, just -after it visits the file. (This marks the buffer as modified, and you -can undo it.) If the value is @code{visit-save}, that means to add -newlines both on visiting and on saving. If the value is @code{nil}, -Emacs leaves the end of the file unchanged; if it's neither @code{nil} -nor @code{t}, Emacs asks you whether to add a newline. The default is -@code{nil}. - -@vindex mode-require-final-newline - Many major modes are designed for specific kinds of files that are -always supposed to end in newlines. These major modes set the -variable @code{require-final-newline} according to -@code{mode-require-final-newline}. By setting the latter variable, -you can control how these modes handle final newlines. - -@vindex write-region-inhibit-fsync - When Emacs saves a file, it invokes the @code{fsync} system call to -force the data immediately out to disk. This is important for safety -if the system crashes or in case of power outage. However, it can be -disruptive on laptops using power saving, because it requires the disk -to spin up each time you save a file. Setting -@code{write-region-inhibit-fsync} to a non-@code{nil} value disables -this synchronization. Be careful---this means increased risk of data -loss. - -@node Interlocking -@subsection Protection against Simultaneous Editing - -@cindex file dates -@cindex simultaneous editing - Simultaneous editing occurs when two users visit the same file, both -make changes, and then both save them. If nobody were informed that -this was happening, whichever user saved first would later find that his -changes were lost. - - On some systems, Emacs notices immediately when the second user starts -to change the file, and issues an immediate warning. On all systems, -Emacs checks when you save the file, and warns if you are about to -overwrite another user's changes. You can prevent loss of the other -user's work by taking the proper corrective action instead of saving the -file. - -@findex ask-user-about-lock -@cindex locking files - When you make the first modification in an Emacs buffer that is -visiting a file, Emacs records that the file is @dfn{locked} by you. -(It does this by creating a symbolic link in the same directory with a -different name.) Emacs removes the lock when you save the changes. The -idea is that the file is locked whenever an Emacs buffer visiting it has -unsaved changes. - -@cindex collision - If you begin to modify the buffer while the visited file is locked by -someone else, this constitutes a @dfn{collision}. When Emacs detects a -collision, it asks you what to do, by calling the Lisp function -@code{ask-user-about-lock}. You can redefine this function for the sake -of customization. The standard definition of this function asks you a -question and accepts three possible answers: - -@table @kbd -@item s -Steal the lock. Whoever was already changing the file loses the lock, -and you gain the lock. -@item p -Proceed. Go ahead and edit the file despite its being locked by someone else. -@item q -Quit. This causes an error (@code{file-locked}), and the buffer -contents remain unchanged---the modification you were trying to make -does not actually take place. -@end table - - Note that locking works on the basis of a file name; if a file has -multiple names, Emacs does not realize that the two names are the same file -and cannot prevent two users from editing it simultaneously under different -names. However, basing locking on names means that Emacs can interlock the -editing of new files that will not really exist until they are saved. - - Some systems are not configured to allow Emacs to make locks, and -there are cases where lock files cannot be written. In these cases, -Emacs cannot detect trouble in advance, but it still can detect the -collision when you try to save a file and overwrite someone else's -changes. - - If Emacs or the operating system crashes, this may leave behind lock -files which are stale, so you may occasionally get warnings about -spurious collisions. When you determine that the collision is spurious, -just use @kbd{p} to tell Emacs to go ahead anyway. - - Every time Emacs saves a buffer, it first checks the last-modification -date of the existing file on disk to verify that it has not changed since the -file was last visited or saved. If the date does not match, it implies -that changes were made in the file in some other way, and these changes are -about to be lost if Emacs actually does save. To prevent this, Emacs -displays a warning message and asks for confirmation before saving. -Occasionally you will know why the file was changed and know that it does -not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should -cancel the save with @kbd{C-g} and investigate the situation. - - The first thing you should do when notified that simultaneous editing -has already taken place is to list the directory with @kbd{C-u C-x C-d} -(@pxref{Directories}). This shows the file's current author. You -should attempt to contact him to warn him not to continue editing. -Often the next step is to save the contents of your Emacs buffer under a -different name, and use @code{diff} to compare the two files.@refill - -@node File Shadowing -@subsection Shadowing Files -@cindex shadow files -@cindex file shadows -@findex shadow-initialize - -@table @kbd -@item M-x shadow-initialize -Set up file shadowing. -@item M-x shadow-define-literal-group -Declare a single file to be shared between sites. -@item M-x shadow-define-regexp-group -Make all files that match each of a group of files be shared between hosts. -@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} -Define a shadow file cluster @var{name}. -@item M-x shadow-copy-files -Copy all pending shadow files. -@item M-x shadow-cancel -Cancel the instruction to shadow some files. -@end table - -You can arrange to keep identical @dfn{shadow} copies of certain files -in more than one place---possibly on different machines. To do this, -first you must set up a @dfn{shadow file group}, which is a set of -identically-named files shared between a list of sites. The file -group is permanent and applies to further Emacs sessions as well as -the current one. Once the group is set up, every time you exit Emacs, -it will copy the file you edited to the other files in its group. You -can also do the copying without exiting Emacs, by typing @kbd{M-x -shadow-copy-files}. - -To set up a shadow file group, use @kbd{M-x -shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. -See their documentation strings for further information. - -Before copying a file to its shadows, Emacs asks for confirmation. -You can answer ``no'' to bypass copying of this file, this time. If -you want to cancel the shadowing permanently for a certain file, use -@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. - -A @dfn{shadow cluster} is a group of hosts that share directories, so -that copying to or from one of them is sufficient to update the file -on all of them. Each shadow cluster has a name, and specifies the -network address of a primary host (the one we copy files to), and a -regular expression that matches the host names of all the other hosts -in the cluster. You can define a shadow cluster with @kbd{M-x -shadow-define-cluster}. - -@node Time Stamps -@subsection Updating Time Stamps Automatically -@cindex time stamps -@cindex modification dates -@cindex locale, date format - -You can arrange to put a time stamp in a file, so that it will be updated -automatically each time you edit and save the file. The time stamp -has to be in the first eight lines of the file, and you should -insert it like this: - -@example -Time-stamp: <> -@end example - -@noindent -or like this: - -@example -Time-stamp: " " -@end example - -@findex time-stamp - Then add the hook function @code{time-stamp} to the hook -@code{before-save-hook}; that hook function will automatically update -the time stamp, inserting the current date and time when you save the -file. You can also use the command @kbd{M-x time-stamp} to update the -time stamp manually. For other customizations, see the Custom group -@code{time-stamp}. Note that non-numeric fields in the time stamp are -formatted according to your locale setting (@pxref{Environment}). - -@node Reverting -@section Reverting a Buffer -@findex revert-buffer -@cindex drastic changes -@cindex reread a file - - If you have made extensive changes to a file and then change your mind -about them, you can get rid of them by reading in the previous version -of the file. To do this, use @kbd{M-x revert-buffer}, which operates on -the current buffer. Since reverting a buffer unintentionally could lose -a lot of work, you must confirm this command with @kbd{yes}. - - @code{revert-buffer} tries to position point in such a way that, if -the file was edited only slightly, you will be at approximately the -same piece of text after reverting as before. However, if you have made -drastic changes, point may wind up in a totally different piece of text. - - Reverting marks the buffer as ``not modified'' until another change is -made. - - Some kinds of buffers whose contents reflect data bases other than files, -such as Dired buffers, can also be reverted. For them, reverting means -recalculating their contents from the appropriate data base. Buffers -created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer} -reports an error when asked to do so. - -@vindex revert-without-query - When you edit a file that changes automatically and frequently---for -example, a log of output from a process that continues to run---it may be -useful for Emacs to revert the file without querying you, whenever you -visit the file again with @kbd{C-x C-f}. - - To request this behavior, set the variable @code{revert-without-query} -to a list of regular expressions. When a file name matches one of these -regular expressions, @code{find-file} and @code{revert-buffer} will -revert it automatically if it has changed---provided the buffer itself -is not modified. (If you have edited the text, it would be wrong to -discard your changes.) - -@cindex Global Auto-Revert mode -@cindex mode, Global Auto-Revert -@cindex Auto-Revert mode -@cindex mode, Auto-Revert -@findex global-auto-revert-mode -@findex auto-revert-mode -@findex auto-revert-tail-mode - - You may find it useful to have Emacs revert files automatically when -they change. Three minor modes are available to do this. - - @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode, -which periodically checks all file buffers and reverts when the -corresponding file has changed. @kbd{M-x auto-revert-mode} enables a -local version, Auto-Revert mode, which applies only to the current -buffer. - - You can use Auto-Revert mode to ``tail'' a file such as a system -log, so that changes made to that file by other programs are -continuously displayed. To do this, just move the point to the end of -the buffer, and it will stay there as the file contents change. -However, if you are sure that the file will only change by growing at -the end, use Auto-Revert Tail mode instead -(@code{auto-revert-tail-mode}). It is more efficient for this. - -@vindex auto-revert-interval - The variable @code{auto-revert-interval} controls how often to check -for a changed file. Since checking a remote file is too slow, these -modes do not check or revert remote files. - - @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that -visit files under version control. - -@ifnottex -@include arevert-xtra.texi -@end ifnottex - -@node Auto Save -@section Auto-Saving: Protection Against Disasters -@cindex Auto Save mode -@cindex mode, Auto Save -@cindex crashes - - Emacs saves all the visited files from time to time (based on counting -your keystrokes) without being asked. This is called @dfn{auto-saving}. -It prevents you from losing more than a limited amount of work if the -system crashes. - - When Emacs determines that it is time for auto-saving, it considers -each buffer, and each is auto-saved if auto-saving is enabled for it -and it has been changed since the last time it was auto-saved. The -message @samp{Auto-saving...} is displayed in the echo area during -auto-saving, if any files are actually auto-saved. Errors occurring -during auto-saving are caught so that they do not interfere with the -execution of commands you have been typing. - -@menu -* Files: Auto Save Files. The file where auto-saved changes are - actually made until you save the file. -* Control: Auto Save Control. Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. -@end menu - -@node Auto Save Files -@subsection Auto-Save Files - - Auto-saving does not normally save in the files that you visited, because -it can be very undesirable to save a program that is in an inconsistent -state when you have made half of a planned change. Instead, auto-saving -is done in a different file called the @dfn{auto-save file}, and the -visited file is changed only when you request saving explicitly (such as -with @kbd{C-x C-s}). - - Normally, the auto-save file name is made by appending @samp{#} to the -front and rear of the visited file name. Thus, a buffer visiting file -@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that -are not visiting files are auto-saved only if you request it explicitly; -when they are auto-saved, the auto-save file name is made by appending -@samp{#} to the front and rear of buffer name, then -adding digits and letters at the end for uniqueness. For -example, the @samp{*mail*} buffer in which you compose messages to be -sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file -names are made this way unless you reprogram parts of Emacs to do -something different (the functions @code{make-auto-save-file-name} and -@code{auto-save-file-name-p}). The file name to be used for auto-saving -in a buffer is calculated when auto-saving is turned on in that buffer. - -@cindex auto-save for remote files -@vindex auto-save-file-name-transforms - The variable @code{auto-save-file-name-transforms} allows a degree -of control over the auto-save file name. It lets you specify a series -of regular expressions and replacements to transform the auto save -file name. The default value puts the auto-save files for remote -files (@pxref{Remote Files}) into the temporary file directory on the -local machine. - - When you delete a substantial part of the text in a large buffer, auto -save turns off temporarily in that buffer. This is because if you -deleted the text unintentionally, you might find the auto-save file more -useful if it contains the deleted text. To reenable auto-saving after -this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x -auto-save-mode}. - -@vindex auto-save-visited-file-name - If you want auto-saving to be done in the visited file rather than -in a separate auto-save file, set the variable -@code{auto-save-visited-file-name} to a non-@code{nil} value. In this -mode, there is no real difference between auto-saving and explicit -saving. - -@vindex delete-auto-save-files - A buffer's auto-save file is deleted when you save the buffer in its -visited file. (You can inhibit this by setting the variable -@code{delete-auto-save-files} to @code{nil}.) Changing the visited -file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames -any auto-save file to go with the new visited name. - -@node Auto Save Control -@subsection Controlling Auto-Saving - -@vindex auto-save-default -@findex auto-save-mode - Each time you visit a file, auto-saving is turned on for that file's -buffer if the variable @code{auto-save-default} is non-@code{nil} (but not -in batch mode; @pxref{Entering Emacs}). The default for this variable is -@code{t}, so auto-saving is the usual practice for file-visiting buffers. -Auto-saving can be turned on or off for any existing buffer with the -command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x -auto-save-mode} turns auto-saving on with a positive argument, off with a -zero or negative argument; with no argument, it toggles. - -@vindex auto-save-interval - Emacs does auto-saving periodically based on counting how many characters -you have typed since the last time auto-saving was done. The variable -@code{auto-save-interval} specifies how many characters there are between -auto-saves. By default, it is 300. Emacs doesn't accept values that are -too small: if you customize @code{auto-save-interval} to a value less -than 20, Emacs will behave as if the value is 20. - -@vindex auto-save-timeout - Auto-saving also takes place when you stop typing for a while. The -variable @code{auto-save-timeout} says how many seconds Emacs should -wait before it does an auto save (and perhaps also a garbage -collection). (The actual time period is longer if the current buffer is -long; this is a heuristic which aims to keep out of your way when you -are editing long buffers, in which auto-save takes an appreciable amount -of time.) Auto-saving during idle periods accomplishes two things: -first, it makes sure all your work is saved if you go away from the -terminal for a while; second, it may avoid some auto-saving while you -are actually typing. - - Emacs also does auto-saving whenever it gets a fatal error. This -includes killing the Emacs job with a shell command such as @samp{kill -%emacs}, or disconnecting a phone line or network connection. - -@findex do-auto-save - You can request an auto-save explicitly with the command @kbd{M-x -do-auto-save}. - -@node Recover -@subsection Recovering Data from Auto-Saves - -@findex recover-file - You can use the contents of an auto-save file to recover from a loss -of data with the command @kbd{M-x recover-file @key{RET} @var{file} -@key{RET}}. This visits @var{file} and then (after your confirmation) -restores the contents from its auto-save file @file{#@var{file}#}. -You can then save with @kbd{C-x C-s} to put the recovered text into -@var{file} itself. For example, to recover file @file{foo.c} from its -auto-save file @file{#foo.c#}, do:@refill - -@example -M-x recover-file @key{RET} foo.c @key{RET} -yes @key{RET} -C-x C-s -@end example - - Before asking for confirmation, @kbd{M-x recover-file} displays a -directory listing describing the specified file and the auto-save file, -so you can compare their sizes and dates. If the auto-save file -is older, @kbd{M-x recover-file} does not offer to read it. - -@findex recover-session - If Emacs or the computer crashes, you can recover all the files you -were editing from their auto save files with the command @kbd{M-x -recover-session}. This first shows you a list of recorded interrupted -sessions. Move point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} asks about each of the files that were -being edited during that session, asking whether to recover that file. -If you answer @kbd{y}, it calls @code{recover-file}, which works in its -normal fashion. It shows the dates of the original file and its -auto-save file, and asks once again whether to recover that file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - -@vindex auto-save-list-file-prefix - Emacs records information about interrupted sessions for later -recovery in files named -@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. All -of this name except the @file{@var{pid}-@var{hostname}} part comes -from the value of @code{auto-save-list-file-prefix}. You can record -sessions in a different place by customizing that variable. If you -set @code{auto-save-list-file-prefix} to @code{nil} in your -@file{.emacs} file, sessions are not recorded for recovery. - -@node File Aliases -@section File Name Aliases -@cindex symbolic links (visiting) -@cindex hard links (visiting) - - Symbolic links and hard links both make it possible for several file -names to refer to the same file. Hard links are alternate names that -refer directly to the file; all the names are equally valid, and no one -of them is preferred. By contrast, a symbolic link is a kind of defined -alias: when @file{foo} is a symbolic link to @file{bar}, you can use -either name to refer to the file, but @file{bar} is the real name, while -@file{foo} is just an alias. More complex cases occur when symbolic -links point to directories. - -@vindex find-file-existing-other-name -@vindex find-file-suppress-same-file-warnings - - Normally, if you visit a file which Emacs is already visiting under -a different name, Emacs displays a message in the echo area and uses -the existing buffer visiting that file. This can happen on systems -that support hard or symbolic links, or if you use a long file name on -a system that truncates long file names, or on a case-insensitive file -system. You can suppress the message by setting the variable -@code{find-file-suppress-same-file-warnings} to a non-@code{nil} -value. You can disable this feature entirely by setting the variable -@code{find-file-existing-other-name} to @code{nil}: then if you visit -the same file under two different names, you get a separate buffer for -each file name. - -@vindex find-file-visit-truename -@cindex truenames of files -@cindex file truenames - If the variable @code{find-file-visit-truename} is non-@code{nil}, -then the file name recorded for a buffer is the file's @dfn{truename} -(made by replacing all symbolic links with their target names), rather -than the name you specify. Setting @code{find-file-visit-truename} also -implies the effect of @code{find-file-existing-other-name}. - -@node Version Control -@section Version Control -@cindex version control - - @dfn{Version control systems} are packages that can record multiple -versions of a source file, usually storing the unchanged parts of the -file just once. Version control systems also record history information -such as the creation time of each version, who created it, and a -description of what was changed in that version. - - The Emacs version control interface is called VC. Its commands work -with different version control systems---currently, it supports CVS, -GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU -project distributes CVS, GNU Arch, and RCS; we recommend that you use -either CVS or GNU Arch for your projects, and RCS for individual -files. We also have free software to replace SCCS, known as CSSC; if -you are using SCCS and don't want to make the incompatible change to -RCS or CVS, you can switch to CSSC. - - VC is enabled by default in Emacs. To disable it, set the -customizable variable @code{vc-handled-backends} to @code{nil} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex - - -@menu -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Old Versions:: Examining and comparing old versions. -* Secondary VC Commands:: The commands used a little less frequently. -* Branches:: Multiple lines of development. -@ifnottex -* Remote Repositories:: Efficient access to remote CVS servers. -* Snapshots:: Sets of file versions treated as a unit. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end ifnottex -@end menu - -@node Introduction to VC -@subsection Introduction to Version Control - - VC allows you to use a version control system from within Emacs, -integrating the version control operations smoothly with editing. VC -provides a uniform interface to version control, so that regardless of -which version control system is in use, you can use it the same way. - - This section provides a general overview of version control, and -describes the version control systems that VC supports. You can skip -this section if you are already familiar with the version control system -you want to use. - -@menu -* Why Version Control?:: Understanding the problems it addresses -* Version Systems:: Supported version control back-end systems. -* VC Concepts:: Words and concepts related to version control. -* Types of Log File:: The per-file VC log in contrast to the ChangeLog. -@end menu - -@node Why Version Control? -@subsubsection Understanding the problems it addresses - - Version control systems provide you with three important capabilities: -reversibility, concurrency, and history. - - The most basic capability you get from a version-control system is -reversibility, the ability to back up to a saved, known-good state when -you discover that some modification you did was a mistake or a bad idea. - - Version-control systems also support concurrency, the ability to -have many people modifying the same collection of code or documents -knowing that conflicting modifications can be detected and resolved. - - Version-control systems give you the capability to attach a history -to your data, explanatory comments about the intention behind each -change to it. Even for a programmer working solo change histories -are an important aid to memory; for a multi-person project they -become a vitally important form of communication among developers. - -@node Version Systems -@subsubsection Supported Version Control Systems - -@cindex back end (version control) - VC currently works with six different version control systems or -``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. - -@cindex CVS - CVS is a free version control system that is used for the majority -of free software projects today. It allows concurrent multi-user -development either locally or over the network. Some of its -shortcomings, corrected by newer systems such as GNU Arch, are that it -lacks atomic commits or support for renaming files. VC supports all -basic editing operations under CVS, but for some less common tasks you -still need to call CVS from the command line. Note also that before -using CVS you must set up a repository, which is a subject too complex -to treat here. - -@cindex GNU Arch -@cindex Arch - GNU Arch is a new version control system that is designed for -distributed work. It differs in many ways from old well-known -systems, such as CVS and RCS. It supports different transports for -interoperating between users, offline operations, and it has good -branching and merging features. It also supports atomic commits, and -history of file renaming and moving. VC does not support all -operations provided by GNU Arch, so you must sometimes invoke it from -the command line, or use a specialized module. - -@cindex RCS - RCS is the free version control system around which VC was initially -built. The VC commands are therefore conceptually closest to RCS. -Almost everything you can do with RCS can be done through VC. You -cannot use RCS over the network though, and it only works at the level -of individual files, rather than projects. You should use it if you -want a simple, yet reliable tool for handling individual files. - -@cindex SVN -@cindex Subversion - Subversion is a free version control system designed to be similar -to CVS but without CVS's problems. Subversion supports atomic commits, -and versions directories, symbolic links, meta-data, renames, copies, -and deletes. It can be used via http or via its own protocol. - -@cindex MCVS -@cindex Meta-CVS - Meta-CVS is another attempt to solve problems arising in CVS. It -supports directory structure versioning, improved branching and -merging, and use of symbolic links and meta-data in repositories. - -@cindex SCCS - SCCS is a proprietary but widely used version control system. In -terms of capabilities, it is the weakest of the six that VC supports. -VC compensates for certain features missing in SCCS (snapshots, for -example) by implementing them itself, but some other VC features, such -as multiple branches, are not available with SCCS. Since SCCS is -non-free, not respecting its users freedom, you should not use it; -use its free replacement CSSC instead. But you should use CSSC only -if for some reason you cannot use RCS, or one of the higher-level -systems such as CVS or GNU Arch. - -In the following, we discuss mainly RCS, SCCS and CVS. Nearly -everything said about CVS applies to GNU Arch, Subversion and Meta-CVS -as well. - -@node VC Concepts -@subsubsection Concepts of Version Control - -@cindex master file -@cindex registered file - When a file is under version control, we also say that it is -@dfn{registered} in the version control system. Each registered file -has a corresponding @dfn{master file} which represents the file's -present state plus its change history---enough to reconstruct the -current version or any earlier version. Usually the master file also -records a @dfn{log entry} for each version, describing in words what was -changed in that version. - -@cindex work file -@cindex checking out files - The file that is maintained under version control is sometimes called -the @dfn{work file} corresponding to its master file. You edit the work -file and make changes in it, as you would with an ordinary file. (With -SCCS and RCS, you must @dfn{lock} the file before you start to edit it.) -After you are done with a set of changes, you @dfn{check the file in}, -which records the changes in the master file, along with a log entry for -them. - - To go beyond these basic concepts, you will need to understand three -ways in which version-control systems can differ from each other. They -can be locking or merging; they can be file-based or changeset-based; -and they can be centralized or decentralized. VC handles all these -choices, but they lead to differing behaviors which you will need -to understand as you use it. - -@cindex locking versus merging - A version control system typically has some mechanism to coordinate -between users who want to change the same file. One method is -@dfn{locking} (analogous to the locking that Emacs uses to detect -simultaneous editing of a file, but distinct from it). In a locking -system, such as SCCS, you must @dfn{lock} a file before you start to -edit it. The other method is @dfn{merging}; the system tries to -merge your changes with other people's changes when you check them in. - - With version control locking, work files are normally read-only so -that you cannot change them. You ask the version control system to make -a work file writable for you by locking it; only one user can do -this at any given time. When you check in your changes, that unlocks -the file, making the work file read-only again. This allows other users -to lock the file to make further changes. - - By contrast, a merging system lets each user check out and modify a -work file at any time. When you check in a a file, the system will -attempt to merge your changes with any others checked into the -repository since you checked out the file. - - Both locking and merging systems can have problems when multiple users -try to modify the same file at the same time. Locking systems have -@dfn{lock conflicts}; a user may try to check a file out and be unable -to because it is locked. In merging systems, @dfn{merge conflicts} -happen when you check in a change to a file that conflicts with a change -checked in by someone else after your checkout. Both kinds of conflict -have to be resolved by human judgment and communication. - - SCCS always uses locking. RCS is lock-based by default but can be told -to operate in a merging style. CVS is merge-based by default but can -be told to operate in a locking mode. Most later version-control -systems, such as Subversion and GNU Arch, have been fundamentally -merging-based rather than locking-based. This is because experience -has shown that the merging-based approach is generally superior to -the locking one, both in convenience to developers and in minimizing -the number and severity of conflicts that actually occur. - - While it is rather unlikely that anyone will ever again build a -fundamentally locking-based rather than merging-based version-control -system in the future, merging-based version-systems sometimes have locks -retrofitted onto them for reasons having nothing to do with technology. -@footnote{Usually the control-freak instincts of managers.} For this -reason, and to support older systems still in use, VC mode supports -both locking and merging version control and tries to hide the differences -between them as much as possible. - -@cindex files versus changesets. - On SCCS, RCS, CVS, and other early version-control systems, checkins -and other operations are @dfn{file-based}; each file has its own -@dfn{master file} with its own comment- and revision history separate -from that of all other files in the system. Later systems, beginning -with Subversion, are @dfn{changeset-based}; a checkin may include -changes to several files and that change set is treated as a unit by the -system. Any comment associated with the change doesn't belong to any -one file, but is attached to the changeset itself. - - Changeset-based version control is in general both more flexible and -more powerful than file-based version control; usually, when a change to -multiple files has to be backed out, it's good to be able to easily -identify and remove all of it. - -@cindex centralized vs. decentralized - Early version-control systems were designed around a @dfn{centralized} -model in which each project has only one repository used by all -developers. SCCS, RCS, CVS, and Subversion share this kind of model. -It has two important problems. One is that a single repository is a -single point of failure---if the repository server is down all work -stops. The other is that you need to be connected live to the server to -do checkins and checkouts; if you're offline, you can't work. - - Newer version-control systems like GNU Arch are @dfn{decentralized}. -A project may have several different repositories, and these systems -support a sort of super-merge between repositories that tries to -reconcile their change histories. At the limit, each developer has -his/her own repository, and repository merges replace checkin/commit -operations. - - VC's job is to help you manage the traffic between your personal -workfiles and a repository. Whether that repository is a single master -or one of a network of peer repositories is not something VC has to care -about. Thus, the difference between a centralized and a decentralized -version-control system is invisible to VC mode. - -@iftex -(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{CVS Options}). -@end ifnottex - - -@node Types of Log File -@subsubsection Types of Log File -@cindex types of log file -@cindex log File, types of -@cindex version control log - - Projects that use a revision control system can have @emph{two} -types of log for changes. One is the per-file log maintained by the -revision control system: each time you check in a change, you must -fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This -kind of log is called the @dfn{version control log}, also the -@dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}. - - The other kind of log is the file @file{ChangeLog} (@pxref{Change -Log}). It provides a chronological record of all changes to a large -portion of a program---typically one directory and its subdirectories. -A small program would use one @file{ChangeLog} file; a large program -may well merit a @file{ChangeLog} file in each major directory. -@xref{Change Log}. - - A project maintained with version control can use just the per-file -log, or it can use both kinds of logs. It can handle some files one -way and some files the other way. Each project has its policy, which -you should follow. - - When the policy is to use both, you typically want to write an entry -for each change just once, then put it into both logs. You can write -the entry in @file{ChangeLog}, then copy it to the log buffer when you -check in the change. Or you can write the entry in the log buffer -while checking in the change, and later use the @kbd{C-x v a} command -to copy it to @file{ChangeLog} -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex - - -@node VC Mode Line -@subsection Version Control and the Mode Line - - When you visit a file that is under version control, Emacs indicates -this on the mode line. For example, @samp{RCS-1.3} says that RCS is -used for that file, and the current version is 1.3. - - The character between the back-end name and the version number -indicates the version control status of the file. @samp{-} means that -the work file is not locked (if locking is in use), or not modified (if -locking is not in use). @samp{:} indicates that the file is locked, or -that it is modified. If the file is locked by some other user (for -instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. - -@vindex auto-revert-check-vc-info - When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is -under version control, it updates the version control information in -the mode line. However, Auto Revert mode may not properly update this -information if the version control status changes without changes to -the work file, from outside the current Emacs session. If you set -@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates -the version control status information every -@code{auto-revert-interval} seconds, even if the work file itself is -unchanged. The resulting CPU usage depends on the version control -system, but is usually not excessive. - -@node Basic VC Editing -@subsection Basic Editing under Version Control - - The principal VC command is an all-purpose command that performs -either locking or check-in, depending on the situation. - -@table @kbd -@itemx C-x v v -Perform the next logical version control operation on this file. -@end table - -@findex vc-next-action -@kindex C-x v v - The precise action of this command depends on the state of the file, -and whether the version control system uses locking or not. SCCS and -RCS normally use locking; CVS normally does not use locking. - -@findex vc-toggle-read-only -@kindex C-x C-q @r{(Version Control)} - As a special convenience that is particularly useful for files with -locking, you can let Emacs check a file in or out whenever you change -its read-only flag. This means, for example, that you cannot -accidentally edit a file without properly checking it out first. To -achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only} -in your @file{~/.emacs} file. (@xref{Init Rebinding}.) - -@menu -* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. -* Without Locking:: Without locking: default mode for CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. -* Log Buffer:: Features available in log entry buffers. -@end menu - -@node VC with Locking -@subsubsection Basic Version Control with Locking - - If locking is used for the file (as with SCCS, and RCS in its default -mode), @kbd{C-x v v} can either lock a file or check it in: - -@itemize @bullet -@item -If the file is not locked, @kbd{C-x v v} locks it, and -makes it writable so that you can change it. - -@item -If the file is locked by you, and contains changes, @kbd{C-x v v} checks -in the changes. In order to do this, it first reads the log entry -for the new version. @xref{Log Buffer}. - -@item -If the file is locked by you, but you have not changed it since you -locked it, @kbd{C-x v v} releases the lock and makes the file read-only -again. - -@item -If the file is locked by some other user, @kbd{C-x v v} asks you whether -you want to ``steal the lock'' from that user. If you say yes, the file -becomes locked by you, but a message is sent to the person who had -formerly locked the file, to inform him of what has happened. -@end itemize - - These rules also apply when you use CVS in locking mode, except -that there is no such thing as stealing a lock. - -@node Without Locking -@subsubsection Basic Version Control without Locking - - When there is no locking---the default for CVS---work files are always -writable; you do not need to do anything before you begin to edit a -file. The status indicator on the mode line is @samp{-} if the file is -unmodified; it flips to @samp{:} as soon as you save any changes in the -work file. - - Here is what @kbd{C-x v v} does when using CVS: - -@itemize @bullet -@item -If some other user has checked in changes into the master file, Emacs -asks you whether you want to merge those changes into your own work -file. You must do this before you can check in your own changes. (To -pick up any recent changes from the master file @emph{without} trying -to commit your own changes, type @kbd{C-x v m @key{RET}}.) -@xref{Merging}. - -@item -If there are no new changes in the master file, but you have made -modifications in your work file, @kbd{C-x v v} checks in your changes. -In order to do this, it first reads the log entry for the new version. -@xref{Log Buffer}. - -@item -If the file is not modified, the @kbd{C-x v v} does nothing. -@end itemize - - These rules also apply when you use RCS in the mode that does not -require locking, except that automatic merging of changes from the -master file is not implemented. Unfortunately, this means that nothing -informs you if another user has checked in changes in the same file -since you began editing it, and when this happens, his changes will be -effectively removed when you check in your version (though they will -remain in the master file, so they will not be entirely lost). You must -therefore verify that the current version is unchanged, before you -check in your changes. We hope to eliminate this risk and provide -automatic merging with RCS in a future Emacs version. - - In addition, locking is possible with RCS even in this mode, although -it is not required; @kbd{C-x v v} with an unmodified file locks the -file, just as it does with RCS in its normal (locking) mode. - -@node Advanced C-x v v -@subsubsection Advanced Control in @kbd{C-x v v} - -@cindex version number to check in/out - When you give a prefix argument to @code{vc-next-action} (@kbd{C-u -C-x v v}), it still performs the next logical version control -operation, but accepts additional arguments to specify precisely how -to do the operation. - -@itemize @bullet -@item -If the file is modified (or locked), you can specify the version -number to use for the new version that you check in. This is one way -to create a new branch (@pxref{Branches}). - -@item -If the file is not modified (and unlocked), you can specify the -version to select; this lets you start working from an older version, -or on another branch. If you do not enter any version, that takes you -to the highest version on the current branch; therefore @kbd{C-u C-x -v v @key{RET}} is a convenient way to get the latest version of a file from -the repository. - -@item -@cindex specific version control system -Instead of the version number, you can also specify the name of a -version control system. This is useful when one file is being managed -with two version control systems at the same time -@iftex -(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs -Features}). -@end iftex -@ifnottex -(@pxref{Local Version Control}). -@end ifnottex - -@end itemize - -@node Log Buffer -@subsubsection Features of the Log Entry Buffer - - When you check in changes, @kbd{C-x v v} first reads a log entry. It -pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. - - Sometimes the @samp{*VC-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{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. -@iftex -@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Change Logs and VC}, -@end ifnottex -for the opposite way of working---generating ChangeLog entries from -the revision control log. - - In the @samp{*VC-Log*} 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. (This can be a list of more than one file if -you use VC Dired mode or PCL-CVS. -@iftex -@xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{VC Dired Mode}, -@end ifnottex -and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs -Front-End to CVS}.) - - When you have finished editing the log message, type @kbd{C-c C-c} to -exit the buffer and commit the change. - - To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that -buffer. You can switch buffers and do other editing. As long as you -don't try to check in another file, the entry you were editing remains -in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any -time to complete the check-in. - - If you change several source files for the same reason, it is often -convenient to specify the same log entry for many of the files. To do -this, use the history of previous log entries. The commands @kbd{M-n}, -@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the -minibuffer history commands (except that these versions are used outside -the minibuffer). - -@vindex vc-log-mode-hook - Each time you check in a file, the log entry buffer is put into VC Log -mode, which involves running two hooks: @code{text-mode-hook} and -@code{vc-log-mode-hook}. @xref{Hooks}. - -@node Old Versions -@subsection Examining And Comparing Old Versions - - One of the convenient features of version control is the ability -to examine any version of a file, or compare two versions. - -@table @kbd -@item C-x v ~ @var{version} @key{RET} -Examine version @var{version} of the visited file, in a buffer of its -own. - -@item C-x v = -Compare the current buffer contents with the master version from which -you started editing. - -@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} -Compare the specified two versions of @var{file}. - -@item C-x v g -Display the file with per-line version information and using colors. -@end table - -@findex vc-version-other-window -@kindex C-x v ~ - To examine an old version in its entirety, visit the file and then type -@kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}). -This puts the text of version @var{version} in a file named -@file{@var{filename}.~@var{version}~}, and visits it in its own buffer -in a separate window. (In RCS, you can also select an old version -and create a branch from it. @xref{Branches}.) - -@findex vc-diff -@kindex C-x v = - It is usually more convenient to compare two versions of the file, -with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =} -compares the current buffer contents (saving them in the file if -necessary) with the master version from which you started editing the -file (this is not necessarily the latest version of the file). -@kbd{C-u C-x v =}, with a numeric argument, reads a file name and two -version numbers, then compares those versions of the specified file. -Both forms display the output in a special buffer in another window. - - You can specify a checked-in version by its number; an empty input -specifies the current contents of the work file (which may be different -from all the checked-in versions). You can also specify a snapshot name -@iftex -(@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features}) -@end iftex -@ifnottex -(@pxref{Snapshots}) -@end ifnottex -instead of one or both version numbers. - - If you supply a directory name instead of the name of a registered -file, this command compares the two specified versions of all registered -files in that directory and its subdirectories. - -@vindex vc-diff-switches -@vindex vc-rcs-diff-switches - @kbd{C-x v =} works by running a variant of the @code{diff} utility -designed to work with the version control system in use. When you -invoke @code{diff} this way, in addition to the options specified by -@code{diff-switches} (@pxref{Comparing Files}), it receives those -specified by @code{vc-diff-switches}, plus those specified for the -specific back end by @code{vc-@var{backend}-diff-switches}. For -instance, when the version control back end is RCS, @code{diff} uses -the options in @code{vc-rcs-diff-switches}. The -@samp{vc@dots{}diff-switches} variables are @code{nil} by default. - - The buffer produced by @kbd{C-x v =} supports the commands of -Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and -@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always -find the corresponding locations in the current work file. (Older -versions are not, in general, present as files on your disk.) - -@findex vc-annotate -@kindex C-x v g - For some back ends, you can display the file @dfn{annotated} with -per-line version information and using colors to enhance the visual -appearance, with the command @kbd{M-x vc-annotate}. It creates a new -buffer (the ``annotate buffer'') displaying the file's text, with each -part colored to show how old it is. Text colored red is new, blue means -old, and intermediate colors indicate intermediate ages. By default, -the color is scaled over the full range of ages, such that the oldest -changes are blue, and the newest changes are red. - - When you give a prefix argument to this command, it uses the -minibuffer to read two arguments: which version number to display and -annotate (instead of the current file contents), and the time span in -days the color range should cover. - - From the annotate buffer, these and other color scaling options are -available from the @samp{VC-Annotate} menu. In this buffer, you can -also use the following keys to browse the annotations of past revisions, -view diffs, or view log entries: - -@table @kbd -@item P -Annotate the previous revision, that is to say, the revision before -the one currently annotated. A numeric prefix argument is a repeat -count, so @kbd{C-u 10 P} would take you back 10 revisions. - -@item N -Annotate the next revision---the one after the revision currently -annotated. A numeric prefix argument is a repeat count. - -@item J -Annotate the revision indicated by the current line. - -@item A -Annotate the revision before the one indicated by the current line. -This is useful to see the state the file was in before the change on -the current line was made. - -@item D -Display the diff between the current line's revision and the previous -revision. This is useful to see what the current line's revision -actually changed in the file. - -@item L -Show the log of the current line's revision. This is useful to see -the author's description of the changes in the revision on the current -line. - -@item W -Annotate the workfile version--the one you are editing. If you used -@kbd{P} and @kbd{N} to browse to other revisions, use this key to -return to your current version. -@end table - -@node Secondary VC Commands -@subsection The Secondary Commands of VC - - This section explains the secondary commands of VC; those that you might -use once a day. - -@menu -* Registering:: Putting a file under version control. -* VC Status:: Viewing the VC status of files. -* VC Undo:: Canceling changes before or after check-in. -@ifnottex -* VC Dired Mode:: Listing files managed by version control. -* VC Dired Commands:: Commands to use in a VC Dired buffer. -@end ifnottex -@end menu - -@node Registering -@subsubsection Registering a File for Version Control - -@kindex C-x v i -@findex vc-register - You can put any file under version control by simply visiting it, and -then typing @w{@kbd{C-x v i}} (@code{vc-register}). - -@table @kbd -@item C-x v i -Register the visited file for version control. -@end table - - To register the file, Emacs must choose which version control system -to use for it. If the file's directory already contains files -registered in a version control system, Emacs uses that system. If -there is more than one system in use for a directory, Emacs uses the -one that appears first in @code{vc-handled-backends} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex -On the other hand, if there are no files already registered, Emacs uses -the first system from @code{vc-handled-backends} that could register -the file (for example, you cannot register a file under CVS if its -directory is not already part of a CVS tree); with the default value -of @code{vc-handled-backends}, this means that Emacs uses RCS in this -situation. - - If locking is in use, @kbd{C-x v i} leaves the file unlocked and -read-only. Type @kbd{C-x v v} if you wish to start editing it. After -registering a file with CVS, you must subsequently commit the initial -version by typing @kbd{C-x v v}. Until you do that, the version -appears as @samp{@@@@} in the mode line. - -@vindex vc-default-init-version -@cindex initial version number to register - The initial version number for a newly registered file is 1.1, by -default. You can specify a different default by setting the variable -@code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric -argument; then it reads the initial version number for this particular -file using the minibuffer. - -@vindex vc-initial-comment - If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an -initial comment to describe the purpose of this source file. Reading -the initial comment works like reading a log entry (@pxref{Log Buffer}). - -@node VC Status -@subsubsection VC Status Commands - -@table @kbd -@item C-x v l -Display version control state and change history. -@end table - -@kindex C-x v l -@findex vc-print-log - To view the detailed version control status and history of a file, -type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of -changes to the current file, including the text of the log entries. The -output appears in a separate window. The point is centered at the -revision of the file that is currently being visited. - - In the change log buffer, you can use the following keys to move -between the logs of revisions and of files, to view past revisions, and -to view diffs: - -@table @kbd -@item p -Move to the previous revision-item in the buffer. (Revision entries in the log -buffer are usually in reverse-chronological order, so the previous -revision-item usually corresponds to a newer revision.) A numeric -prefix argument is a repeat count. - -@item n -Move to the next revision-item (which most often corresponds to the -previous revision of the file). A numeric prefix argument is a repeat -count. - -@item P -Move to the log of the previous file, when the logs of multiple files -are in the log buffer -@iftex -(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{VC Dired Mode}). -@end ifnottex -Otherwise, just move to the beginning of the log. A numeric prefix -argument is a repeat count, so @kbd{C-u 10 P} would move backward 10 -files. - -@item N -Move to the log of the next file, when the logs of multiple files are -in the log buffer -@iftex -(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{VC Dired Mode}). -@end ifnottex -It also takes a numeric prefix argument as a repeat count. - -@item f -Visit the revision indicated at the current line, like typing @kbd{C-x -v ~} and specifying this revision's number (@pxref{Old Versions}). - -@item d -Display the diff (@pxref{Comparing Files}) between the revision -indicated at the current line and the next earlier revision. This is -useful to see what actually changed when the revision indicated on the -current line was committed. -@end table - -@node VC Undo -@subsubsection Undoing Version Control Actions - -@table @kbd -@item C-x v u -Revert the buffer and the file to the version from which you started -editing the file. - -@item C-x v c -Remove the last-entered change from the master for the visited file. -This undoes your last check-in. -@end table - -@kindex C-x v u -@findex vc-revert-buffer - If you want to discard your current set of changes and revert to the -version from which you started editing the file, use @kbd{C-x v u} -(@code{vc-revert-buffer}). This leaves the file unlocked; if locking -is in use, you must first lock the file again before you change it -again. @kbd{C-x v u} requires confirmation, unless it sees that you -haven't made any changes with respect to the master version. - - @kbd{C-x v u} is also the command to unlock a file if you lock it and -then decide not to change it. - -@kindex C-x v c -@findex vc-cancel-version - To cancel a change that you already checked in, use @kbd{C-x v c} -(@code{vc-cancel-version}). This command discards all record of the -most recent checked-in version, but only if your work file corresponds -to that version---you cannot use @kbd{C-x v c} to cancel a version -that is not the latest on its branch. @kbd{C-x v c} also offers to -revert your work file and buffer to the previous version (the one that -precedes the version that is deleted). - - If you answer @kbd{no}, VC keeps your changes in the buffer, and locks -the file. The no-revert option is useful when you have checked in a -change and then discover a trivial error in it; you can cancel the -erroneous check-in, fix the error, and check the file in again. - - When @kbd{C-x v c} does not revert the buffer, it unexpands all -version control headers in the buffer instead -@iftex -(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Version Headers}). -@end ifnottex -This is because the buffer no longer corresponds to any existing -version. If you check it in again, the check-in process will expand -the headers properly for the new version number. - - However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header -automatically. If you use that header feature, you have to unexpand it -by hand---by deleting the entry for the version that you just canceled. - - Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of -work with it. To help you be careful, this command always requires -confirmation with @kbd{yes}. Note also that this command is disabled -under CVS, because canceling versions is very dangerous and discouraged -with CVS. - -@ifnottex -@c vc1-xtra.texi needs extra level of lowering. -@lowersections -@include vc1-xtra.texi -@raisesections -@end ifnottex - -@node Branches -@subsection Multiple Branches of a File -@cindex branch (version control) -@cindex trunk (version control) - - One use of version control is to maintain multiple ``current'' -versions of a file. For example, you might have different versions of a -program in which you are gradually adding various unfinished new -features. Each such independent line of development is called a -@dfn{branch}. VC allows you to create branches, switch between -different branches, and merge changes from one branch to another. -Please note, however, that branches are not supported for SCCS. - - A file's main line of development is usually called the @dfn{trunk}. -The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At -any such version, you can start an independent branch. A branch -starting at version 1.2 would have version number 1.2.1.1, and consecutive -versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, -and so on. If there is a second branch also starting at version 1.2, it -would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. - -@cindex head version - If you omit the final component of a version number, that is called a -@dfn{branch number}. It refers to the highest existing version on that -branch---the @dfn{head version} of that branch. The branches in the -example above have branch numbers 1.2.1 and 1.2.2. - -@menu -* Switching Branches:: How to get to another existing branch. -* Creating Branches:: How to start a new branch. -* Merging:: Transferring changes between branches. -* Multi-User Branching:: Multiple users working at multiple branches - in parallel. -@end menu - -@node Switching Branches -@subsubsection Switching between Branches - - To switch between branches, type @kbd{C-u C-x v v} and specify the -version number you want to select. This version is then visited -@emph{unlocked} (write-protected), so you can examine it before locking -it. Switching branches in this way is allowed only when the file is not -locked. - - You can omit the minor version number, thus giving only the branch -number; this takes you to the head version on the chosen branch. If you -only type @key{RET}, Emacs goes to the highest version on the trunk. - - After you have switched to any branch (including the main branch), you -stay on it for subsequent VC commands, until you explicitly select some -other branch. - -@node Creating Branches -@subsubsection Creating New Branches - - To create a new branch from a head version (one that is the latest in -the branch that contains it), first select that version if necessary, -lock it with @kbd{C-x v v}, and make whatever changes you want. Then, -when you check in the changes, use @kbd{C-u C-x v v}. This lets you -specify the version number for the new version. You should specify a -suitable branch number for a branch starting at the current version. -For example, if the current version is 2.5, the branch number should be -2.5.1, 2.5.2, and so on, depending on the number of existing branches at -that point. - - To create a new branch at an older version (one that is no longer the -head of a branch), first select that version (@pxref{Switching -Branches}), then lock it with @kbd{C-x v v}. You'll be asked to -confirm, when you lock the old version, that you really mean to create a -new branch---if you say no, you'll be offered a chance to lock the -latest version instead. - - Then make your changes and type @kbd{C-x v v} again to check in a new -version. This automatically creates a new branch starting from the -selected version. You need not specially request a new branch, because -that's the only way to add a new version at a point that is not the head -of a branch. - - After the branch is created, you ``stay'' on it. That means that -subsequent check-ins create new versions on that branch. To leave the -branch, you must explicitly select a different version with @kbd{C-u C-x -v v}. To transfer changes from one branch to another, use the merge -command, described in the next section. - -@node Merging -@subsubsection Merging Branches - -@cindex merging changes - When you have finished the changes on a certain branch, you will -often want to incorporate them into the file's main line of development -(the trunk). This is not a trivial operation, because development might -also have proceeded on the trunk, so that you must @dfn{merge} the -changes into a file that has already been changed otherwise. VC allows -you to do this (and other things) with the @code{vc-merge} command. - -@table @kbd -@item C-x v m (vc-merge) -Merge changes into the work file. -@end table - -@kindex C-x v m -@findex vc-merge - @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it -into the current version of the work file. It firsts asks you in the -minibuffer where the changes should come from. If you just type -@key{RET}, Emacs merges any changes that were made on the same branch -since you checked the file out (we call this @dfn{merging the news}). -This is the common way to pick up recent changes from the repository, -regardless of whether you have already changed the file yourself. - - You can also enter a branch number or a pair of version numbers in -the minibuffer. Then @kbd{C-x v m} finds the changes from that -branch, or the differences between the two versions you specified, and -merges them into the current version of the current file. - - As an example, suppose that you have finished a certain feature on -branch 1.3.1. In the meantime, development on the trunk has proceeded -to version 1.5. To merge the changes from the branch to the trunk, -first go to the head version of the trunk, by typing @kbd{C-u C-x v v -@key{RET}}. Version 1.5 is now current. If locking is used for the file, -type @kbd{C-x v v} to lock version 1.5 so that you can change it. Next, -type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on -branch 1.3.1 (relative to version 1.3, where the branch started, up to -the last version on the branch) and merges it into the current version -of the work file. You can now check in the changed file, thus creating -version 1.6 containing the changes from the branch. - - It is possible to do further editing after merging the branch, before -the next check-in. But it is usually wiser to check in the merged -version, then lock it and make the further changes. This will keep -a better record of the history of changes. - -@cindex conflicts -@cindex resolving conflicts - When you merge changes into a file that has itself been modified, the -changes might overlap. We call this situation a @dfn{conflict}, and -reconciling the conflicting changes is called @dfn{resolving a -conflict}. - - Whenever conflicts occur during merging, VC detects them, tells you -about them in the echo area, and asks whether you want help in merging. -If you say yes, it starts an Ediff session (@pxref{Top, -Ediff, Ediff, ediff, The Ediff Manual}). - - If you say no, the conflicting changes are both inserted into the -file, surrounded by @dfn{conflict markers}. The example below shows how -a conflict region looks; the file is called @samp{name} and the current -master file version with user B's changes in it is 1.11. - -@c @w here is so CVS won't think this is a conflict. -@smallexample -@group -@w{<}<<<<<< name - @var{User A's version} -======= - @var{User B's version} -@w{>}>>>>>> 1.11 -@end group -@end smallexample - -@cindex vc-resolve-conflicts - Then you can resolve the conflicts by editing the file manually. Or -you can type @code{M-x vc-resolve-conflicts} after visiting the file. -This starts an Ediff session, as described above. Don't forget to -check in the merged version afterwards. - -@node Multi-User Branching -@subsubsection Multi-User Branching - - It is often useful for multiple developers to work simultaneously on -different branches of a file. CVS allows this by default; for RCS, it -is possible if you create multiple source directories. Each source -directory should have a link named @file{RCS} which points to a common -directory of RCS master files. Then each source directory can have its -own choice of selected versions, but all share the same common RCS -records. - - This technique works reliably and automatically, provided that the -source files contain RCS version headers -@iftex -(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Version Headers}). -@end ifnottex -The headers enable Emacs to be sure, at all times, which version -number is present in the work file. - - If the files do not have version headers, you must instead tell Emacs -explicitly in each session which branch you are working on. To do this, -first find the file, then type @kbd{C-u C-x v v} and specify the correct -branch number. This ensures that Emacs knows which branch it is using -during this particular editing session. - -@ifnottex -@include vc2-xtra.texi -@end ifnottex - -@node Directories -@section File Directories - -@cindex file directory -@cindex directory listing - The file system groups files into @dfn{directories}. A @dfn{directory -listing} is a list of all the files in a directory. Emacs provides -commands to create and delete directories, and to make directory -listings in brief format (file names only) and verbose format (sizes, -dates, and authors included). Emacs also includes a directory browser -feature called Dired; see @ref{Dired}. - -@table @kbd -@item C-x C-d @var{dir-or-pattern} @key{RET} -Display a brief directory listing (@code{list-directory}). -@item C-u C-x C-d @var{dir-or-pattern} @key{RET} -Display a verbose directory listing. -@item M-x make-directory @key{RET} @var{dirname} @key{RET} -Create a new directory named @var{dirname}. -@item M-x delete-directory @key{RET} @var{dirname} @key{RET} -Delete the directory named @var{dirname}. It must be empty, -or you get an error. -@end table - -@findex list-directory -@kindex C-x C-d - The command to display a directory listing is @kbd{C-x C-d} -(@code{list-directory}). It reads using the minibuffer a file name -which is either a directory to be listed or a wildcard-containing -pattern for the files to be listed. For example, - -@example -C-x C-d /u2/emacs/etc @key{RET} -@end example - -@noindent -lists all the files in directory @file{/u2/emacs/etc}. Here is an -example of specifying a file name pattern: - -@example -C-x C-d /u2/emacs/src/*.c @key{RET} -@end example - - Normally, @kbd{C-x C-d} displays a brief directory listing containing -just file names. A numeric argument (regardless of value) tells it to -make a verbose listing including sizes, dates, and owners (like -@samp{ls -l}). - -@vindex list-directory-brief-switches -@vindex list-directory-verbose-switches - The text of a directory listing is mostly obtained by running -@code{ls} in an inferior process. Two Emacs variables control the -switches passed to @code{ls}: @code{list-directory-brief-switches} is -a string giving the switches to use in brief listings (@code{"-CF"} by -default), and @code{list-directory-verbose-switches} is a string -giving the switches to use in a verbose listing (@code{"-l"} by -default). - -@vindex directory-free-space-program -@vindex directory-free-space-args - In verbose directory listings, Emacs adds information about the -amount of free space on the disk that contains the directory. To do -this, it runs the program specified by -@code{directory-free-space-program} with arguments -@code{directory-free-space-args}. - -@node Comparing Files -@section Comparing Files -@cindex comparing files - -@findex diff -@vindex diff-switches - The command @kbd{M-x diff} compares two files, displaying the -differences in an Emacs buffer named @samp{*diff*}. It works by -running the @code{diff} program, using options taken from the variable -@code{diff-switches}. The value of @code{diff-switches} should be a -string; the default is @code{"-c"} to specify a context diff. -@xref{Top,, Diff, diff, Comparing and Merging Files}, for more -information about @command{diff} output formats. - -@findex diff-backup - The command @kbd{M-x diff-backup} compares a specified file with its most -recent backup. If you specify the name of a backup file, -@code{diff-backup} compares it with the source file that it is a backup -of. - -@findex compare-windows - The command @kbd{M-x compare-windows} compares the text in the -current window with that in the next window. (For more information -about windows in Emacs, @ref{Windows}.) Comparison starts at point in -each window, after pushing each initial point value on the mark ring -in its respective buffer. Then it moves point forward in each window, -one character at a time, until it reaches characters that don't match. -Then the command exits. - - If point in the two windows is followed by non-matching text when -the command starts, @kbd{M-x compare-windows} tries heuristically to -advance up to matching text in the two windows, and then exits. So if -you use @kbd{M-x compare-windows} repeatedly, each time it either -skips one matching range or finds the start of another. - -@vindex compare-ignore-case -@vindex compare-ignore-whitespace - With a numeric argument, @code{compare-windows} ignores changes in -whitespace. If the variable @code{compare-ignore-case} is -non-@code{nil}, the comparison ignores differences in case as well. -If the variable @code{compare-ignore-whitespace} is non-@code{nil}, -@code{compare-windows} normally ignores changes in whitespace, and a -prefix argument turns that off. - -@cindex Smerge mode -@findex smerge-mode -@cindex failed merges -@cindex merges, failed -@cindex comparing 3 files (@code{diff3}) - You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor -mode for editing output from the @command{diff3} program. This is -typically the result of a failed merge from a version control system -``update'' outside VC, due to conflicting changes to a file. Smerge -mode provides commands to resolve conflicts by selecting specific -changes. - -@iftex -@xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Emerge}, -@end ifnottex -for the Emerge facility, which provides a powerful interface for -merging files. - -@node Diff Mode -@section Diff Mode -@cindex Diff mode -@findex diff-mode -@cindex patches, editing - - Diff mode is used for the output of @kbd{M-x diff}; it is also -useful for editing patches and comparisons produced by the -@command{diff} program. To select Diff mode manually, type @kbd{M-x -diff-mode}. - - One general feature of Diff mode is that manual edits to the patch -automatically correct line numbers, including those in the hunk -header, so that you can actually apply the edited patch. Diff mode -treats each hunk location as an ``error message,'' so that you can use -commands such as @kbd{C-x '} to visit the corresponding source -locations. It also provides the following commands to navigate, -manipulate and apply parts of patches: - -@table @kbd -@item M-n -Move to the next hunk-start (@code{diff-hunk-next}). - -@item M-p -Move to the previous hunk-start (@code{diff-hunk-prev}). - -@item M-@} -Move to the next file-start, in a multi-file patch -(@code{diff-file-next}). - -@item M-@{ -Move to the previous file-start, in a multi-file patch -(@code{diff-file-prev}). - -@item M-k -Kill the hunk at point (@code{diff-hunk-kill}). - -@item M-K -In a multi-file patch, kill the current file part. -(@code{diff-file-kill}). - -@item C-c C-a -Apply this hunk to its target file (@code{diff-apply-hunk}). With a -prefix argument of @kbd{C-u}, revert this hunk. - -@item C-c C-c -Go to the source corresponding to this hunk (@code{diff-goto-source}). - -@item C-c C-e -Start an Ediff session with the patch (@code{diff-ediff-patch}). -@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. - -@item C-c C-n -Restrict the view to the current hunk (@code{diff-restrict-view}). -@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the -view to the current patch of a multiple file patch. To widen again, -use @kbd{C-x n w}. - -@item C-c C-r -Reverse the direction of comparison for the entire buffer -(@code{diff-reverse-direction}). - -@item C-c C-s -Split the hunk at point (@code{diff-split-hunk}). This is for -manually editing patches, and only works with the unified diff format. - -@item C-c C-u -Convert the entire buffer to unified format -(@code{diff-context->unified}). With a prefix argument, convert -unified format to context format. In Transient Mark mode, when the -mark is active, this command operates only on the region. - -@item C-c C-w -Refine the current hunk so that it disregards changes in whitespace -(@code{diff-refine-hunk}). -@end table - - @kbd{C-x 4 a} in Diff mode operates on behalf of the target file, -but gets the function name from the patch itself. @xref{Change Log}. -This is useful for making log entries for functions that are deleted -by the patch. - -@node Misc File Ops -@section Miscellaneous File Operations - - Emacs has commands for performing many other operations on files. -All operate on one file; they do not accept wildcard file names. - -@findex view-file -@cindex viewing -@cindex View mode -@cindex mode, View - @kbd{M-x view-file} allows you to scan or read a file by sequential -screenfuls. It reads a file name argument using the minibuffer. After -reading the file into an Emacs buffer, @code{view-file} displays the -beginning. You can then type @key{SPC} to scroll forward one windowful, -or @key{DEL} to scroll backward. Various other commands are provided -for moving around in the file, but none for changing it; type @kbd{?} -while viewing for a list of them. They are mostly the same as normal -Emacs cursor motion commands. To exit from viewing, type @kbd{q}. -The commands for viewing are defined by a special minor mode called View -mode. - - A related command, @kbd{M-x view-buffer}, views a buffer already present -in Emacs. @xref{Misc Buffer}. - -@kindex C-x i -@findex insert-file - @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the -contents of the specified file into the current buffer at point, -leaving point unchanged before the contents and the mark after them. - -@findex insert-file-literally - @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, -except the file is inserted ``literally'': it is treated as a sequence -of @acronym{ASCII} characters with no special encoding or conversion, -similar to the @kbd{M-x find-file-literally} command -(@pxref{Visiting}). - -@findex write-region - @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it -copies the contents of the region into the specified file. @kbd{M-x -append-to-file} adds the text of the region to the end of the -specified file. @xref{Accumulating Text}. The variable -@code{write-region-inhibit-fsync} applies to these commands, as well -as saving files; see @ref{Customize Save}. - -@findex delete-file -@cindex deletion (of files) - @kbd{M-x delete-file} deletes the specified file, like the @code{rm} -command in the shell. If you are deleting many files in one directory, it -may be more convenient to use Dired (@pxref{Dired}). - -@findex rename-file - @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using -the minibuffer, then renames file @var{old} as @var{new}. If the file name -@var{new} already exists, you must confirm with @kbd{yes} or renaming is not -done; this is because renaming causes the old meaning of the name @var{new} -to be lost. If @var{old} and @var{new} are on different file systems, the -file @var{old} is copied and deleted. - - If the argument @var{new} is just a directory name, the real new -name is in that directory, with the same non-directory component as -@var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} -renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all -the remaining commands in this section. All of them ask for -confirmation when the new file name already exists, too. - -@findex add-name-to-file -@cindex hard links (creation) - The similar command @kbd{M-x add-name-to-file} is used to add an -additional name to an existing file without removing its old name. -The new name is created as a ``hard link'' to the existing file. -The new name must belong on the same file system that the file is on. -On MS-Windows, this command works only if the file resides in an NTFS -file system. On MS-DOS, it works by copying the file. - -@findex copy-file -@cindex copying files - @kbd{M-x copy-file} reads the file @var{old} and writes a new file -named @var{new} with the same contents. - -@findex make-symbolic-link -@cindex symbolic links (creation) - @kbd{M-x make-symbolic-link} reads two file names @var{target} and -@var{linkname}, then creates a symbolic link named @var{linkname}, -which points at @var{target}. The effect is that future attempts to -open file @var{linkname} will refer to whatever file is named -@var{target} at the time the opening is done, or will get an error if -the name @var{target} is nonexistent at that time. This command does -not expand the argument @var{target}, so that it allows you to specify -a relative name as the target of the link. - - Not all systems support symbolic links; on systems that don't -support them, this command is not defined. - -@node Compressed Files -@section Accessing Compressed Files -@cindex compression -@cindex uncompression -@cindex Auto Compression mode -@cindex mode, Auto Compression -@pindex gzip - - Emacs automatically uncompresses compressed files when you visit -them, and automatically recompresses them if you alter them and save -them. Emacs recognizes compressed files by their file names. File -names ending in @samp{.gz} indicate a file compressed with -@code{gzip}. Other endings indicate other compression programs. - - Automatic uncompression and compression apply to all the operations in -which Emacs uses the contents of a file. This includes visiting it, -saving it, inserting its contents into a buffer, loading it, and byte -compiling it. - -@findex auto-compression-mode -@vindex auto-compression-mode - To disable this feature, type the command @kbd{M-x -auto-compression-mode}. You can disable it permanently by -customizing the variable @code{auto-compression-mode}. - -@node File Archives -@section File Archives -@cindex mode, tar -@cindex Tar mode -@cindex file archives - - A file whose name ends in @samp{.tar} is normally an @dfn{archive} -made by the @code{tar} program. Emacs views these files in a special -mode called Tar mode which provides a Dired-like list of the contents -(@pxref{Dired}). You can move around through the list just as you -would in Dired, and visit the subfiles contained in the archive. -However, not all Dired commands are available in Tar mode. - - If Auto Compression mode is enabled (@pxref{Compressed Files}), then -Tar mode is used also for compressed archives---files with extensions -@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. - - The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file -into its own buffer. You can edit it there, and if you save the -buffer, the edited version will replace the version in the Tar buffer. -@kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts -the file and displays it in another window, so you could edit the file -and operate on the archive simultaneously. @kbd{d} marks a file for -deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in -Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} -renames a file within the archive. @kbd{g} reverts the buffer from -the archive on disk. - - The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission -bits, group, and owner, respectively. - - If your display supports colors and the mouse, moving the mouse -pointer across a file name highlights that file name, indicating that -you can click on it. Clicking @kbd{Mouse-2} on the highlighted file -name extracts the file into a buffer and displays that buffer. - - Saving the Tar buffer writes a new version of the archive to disk with -the changes you made to the components. - - You don't need the @code{tar} program to use Tar mode---Emacs reads -the archives directly. However, accessing compressed archives -requires the appropriate uncompression program. - -@cindex Archive mode -@cindex mode, archive -@cindex @code{arc} -@cindex @code{jar} -@cindex @code{zip} -@cindex @code{lzh} -@cindex @code{zoo} -@pindex arc -@pindex jar -@pindex zip -@pindex lzh -@pindex zoo -@cindex Java class archives -@cindex unzip archives - A separate but similar Archive mode is used for archives produced by -the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and -@code{zoo}, which have extensions corresponding to the program names. -Archive mode also works for those @code{exe} files that are -self-extracting executables. - - The key bindings of Archive mode are similar to those in Tar mode, -with the addition of the @kbd{m} key which marks a file for subsequent -operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. -Also, the @kbd{a} key toggles the display of detailed file -information, for those archive types where it won't fit in a single -line. Operations such as renaming a subfile, or changing its mode or -owner, are supported only for some of the archive formats. - - Unlike Tar mode, Archive mode runs the archiving program to unpack -and repack archives. Details of the program names and their options -can be set in the @samp{Archive} Customize group. However, you don't -need these programs to look at the archive table of contents, only to -extract or manipulate the subfiles in the archive. - -@node Remote Files -@section Remote Files - -@cindex Tramp -@cindex FTP -@cindex remote file access - You can refer to files on other machines using a special file name -syntax: - -@example -@group -/@var{host}:@var{filename} -/@var{user}@@@var{host}:@var{filename} -/@var{user}@@@var{host}#@var{port}:@var{filename} -/@var{method}:@var{user}@@@var{host}:@var{filename} -/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} -@end group -@end example - -@noindent -To carry out this request, Emacs uses either the FTP program or a -remote-login program such as @command{ssh}, @command{rlogin}, or -@command{telnet}. You can always specify in the file name which -method to use---for example, -@file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas -@file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}. -When you don't specify a method in the file name, Emacs chooses -the method as follows: - -@enumerate -@item -If the host name starts with @samp{ftp.} (with dot), then Emacs uses -FTP. -@item -If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses -FTP. -@item -Otherwise, Emacs uses @command{ssh}. -@end enumerate - -@noindent -Remote file access through FTP is handled by the Ange-FTP package, which -is documented in the following. Remote file access through the other -methods is handled by the Tramp package, which has its own manual. -@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. - -When the Ange-FTP package is used, Emacs logs in through FTP using your -user name or the name @var{user}. It may ask you for a password from -time to time; this is used for logging in on @var{host}. The form using -@var{port} allows you to access servers running on a non-default TCP -port. - -@cindex backups for remote files -@vindex ange-ftp-make-backup-files - If you want to disable backups for remote files, set the variable -@code{ange-ftp-make-backup-files} to @code{nil}. - - By default, the auto-save files (@pxref{Auto Save Files}) for remote -files are made in the temporary file directory on the local machine. -This is achieved using the variable @code{auto-save-file-name-transforms}. - -@cindex ange-ftp -@vindex ange-ftp-default-user -@cindex user name for remote file access - Normally, if you do not specify a user name in a remote file name, -that means to use your own user name. But if you set the variable -@code{ange-ftp-default-user} to a string, that string is used instead. - -@cindex anonymous FTP -@vindex ange-ftp-generate-anonymous-password - To visit files accessible by anonymous FTP, you use special user -names @samp{anonymous} or @samp{ftp}. Passwords for these user names -are handled specially. The variable -@code{ange-ftp-generate-anonymous-password} controls what happens: if -the value of this variable is a string, then that string is used as -the password; if non-@code{nil} (the default), then the value of -@code{user-mail-address} is used; if @code{nil}, then Emacs prompts -you for a password as usual. - -@cindex firewall, and accessing remote files -@cindex gateway, and remote file access with @code{ange-ftp} -@vindex ange-ftp-smart-gateway -@vindex ange-ftp-gateway-host - Sometimes you may be unable to access files on a remote machine -because a @dfn{firewall} in between blocks the connection for security -reasons. If you can log in on a @dfn{gateway} machine from which the -target files @emph{are} accessible, and whose FTP server supports -gatewaying features, you can still use remote file names; all you have -to do is specify the name of the gateway machine by setting the -variable @code{ange-ftp-gateway-host}, and set -@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able -to make remote file names work, but the procedure is complex. You can -read the instructions by typing @kbd{M-x finder-commentary @key{RET} -ange-ftp @key{RET}}. - -@vindex file-name-handler-alist -@cindex disabling remote files - You can entirely turn off the FTP file name feature by removing the -entries @code{ange-ftp-completion-hook-function} and -@code{ange-ftp-hook-function} from the variable -@code{file-name-handler-alist}. You can turn off the feature in -individual cases by quoting the file name with @samp{/:} (@pxref{Quoted -File Names}). - -@node Quoted File Names -@section Quoted File Names - -@cindex quoting file names -@cindex file names, quote special characters - You can @dfn{quote} an absolute file name to prevent special -characters and syntax in it from having their special effects. -The way to do this is to add @samp{/:} at the beginning. - - For example, you can quote a local file name which appears remote, to -prevent it from being treated as a remote file name. Thus, if you have -a directory named @file{/foo:} and a file named @file{bar} in it, you -can refer to that file in Emacs as @samp{/:/foo:/bar}. - - @samp{/:} can also prevent @samp{~} from being treated as a special -character for a user's home directory. For example, @file{/:/tmp/~hack} -refers to a file whose name is @file{~hack} in directory @file{/tmp}. - - Quoting with @samp{/:} is also a way to enter in the minibuffer a -file name that contains @samp{$}. In order for this to work, the -@samp{/:} must be at the beginning of the minibuffer contents. (You -can also double each @samp{$}; see @ref{File Names with $}.) - - You can also quote wildcard characters with @samp{/:}, for visiting. -For example, @file{/:/tmp/foo*bar} visits the file -@file{/tmp/foo*bar}. - - Another method of getting the same result is to enter -@file{/tmp/foo[*]bar}, which is a wildcard specification that matches -only @file{/tmp/foo*bar}. However, in many cases there is no need to -quote the wildcard characters because even unquoted they give the -right result. For example, if the only file name in @file{/tmp} that -starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, -then specifying @file{/tmp/foo*bar} will visit only -@file{/tmp/foo*bar}. - -@node File Name Cache -@section File Name Cache - -@cindex file name caching -@cindex cache of file names -@pindex find -@kindex C-@key{TAB} -@findex file-cache-minibuffer-complete - You can use the @dfn{file name cache} to make it easy to locate a -file by name, without having to remember exactly where it is located. -When typing a file name in the minibuffer, @kbd{C-@key{tab}} -(@code{file-cache-minibuffer-complete}) completes it using the file -name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the -possible completions of what you had originally typed. (However, note -that the @kbd{C-@key{tab}} character cannot be typed on most text-only -terminals.) - - The file name cache does not fill up automatically. Instead, you -load file names into the cache using these commands: - -@findex file-cache-add-directory -@table @kbd -@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} to the file name cache. -@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache. -@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache, using @command{locate} to find -them all. -@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} -Add each file name in each directory listed in @var{variable} -to the file name cache. @var{variable} should be a Lisp variable -such as @code{load-path} or @code{exec-path}, whose value is a list -of directory names. -@item M-x file-cache-clear-cache @key{RET} -Clear the cache; that is, remove all file names from it. -@end table - - The file name cache is not persistent: it is kept and maintained -only for the duration of the Emacs session. You can view the contents -of the cache with the @code{file-cache-display} command. - -@node File Conveniences -@section Convenience Features for Finding Files - - In this section, we introduce some convenient facilities for finding -recently-opened files, reading file names from a buffer, and viewing -image files. - -@findex recentf-mode -@vindex recentf-mode -@findex recentf-save-list -@findex recentf-edit-list - If you enable Recentf mode, with @kbd{M-x recentf-mode}, the -@samp{File} menu includes a submenu containing a list of recently -opened files. @kbd{M-x recentf-save-list} saves the current -@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} -edits it. - - The @kbd{M-x ffap} command generalizes @code{find-file} with more -powerful heuristic defaults (@pxref{FFAP}), often based on the text at -point. Partial Completion mode offers other features extending -@code{find-file}, which can be used with @code{ffap}. -@xref{Completion Options}. - -@findex image-mode -@findex image-toggle-display -@cindex images, viewing - Visiting image files automatically selects Image mode. This major -mode allows you to toggle between displaying the file as an image in -the Emacs buffer, and displaying its underlying text representation, -using the command @kbd{C-c C-c} (@code{image-toggle-display}). This -works only when Emacs can display the specific image type. If the -displayed image is wider or taller than the frame, the usual point -motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts -of the image to be displayed. - -@findex thumbs-mode -@findex mode, thumbs - See also the Image-Dired package (@pxref{Image-Dired}) for viewing -images as thumbnails. - -@node Filesets -@section Filesets -@cindex filesets - -@findex filesets-init - If you regularly edit a certain group of files, you can define them -as a @dfn{fileset}. This lets you perform certain operations, such as -visiting, @code{query-replace}, and shell commands on all the files -at once. To make use of filesets, you must first add the expression -@code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). -This adds a @samp{Filesets} menu to the menu bar. - -@findex filesets-add-buffer -@findex filesets-remove-buffer - The simplest way to define a fileset is by adding files to it one -at a time. To add a file to fileset @var{name}, visit the file and -type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If -there is no fileset @var{name}, this creates a new one, which -initially creates only the current file. The command @kbd{M-x -filesets-remove-buffer} removes the current file from a fileset. - - You can also edit the list of filesets directly, with @kbd{M-x -filesets-edit} (or by choosing @samp{Edit Filesets} from the -@samp{Filesets} menu). The editing is performed in a Customize buffer -(@pxref{Easy Customization}). Filesets need not be a simple list of -files---you can also define filesets using regular expression matching -file names. Some examples of these more complicated filesets are -shown in the Customize buffer. Remember to select @samp{Save for -future sessions} if you want to use the same filesets in future Emacs -sessions. - - You can use the command @kbd{M-x filesets-open} to visit all the -files in a fileset, and @kbd{M-x filesets-close} to close them. Use -@kbd{M-x filesets-run-cmd} to run a shell command on all the files in -a fileset. These commands are also available from the @samp{Filesets} -menu, where each existing fileset is represented by a submenu. - -@ignore - arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 -@end ignore diff --git a/man/fixit.texi b/man/fixit.texi deleted file mode 100644 index d1577e2f528..00000000000 --- a/man/fixit.texi +++ /dev/null @@ -1,471 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Fixit, Keyboard Macros, Search, Top -@chapter Commands for Fixing Typos -@cindex typos, fixing -@cindex mistakes, correcting - - In this chapter we describe the commands that are especially useful for -the times when you catch a mistake in your text just after you have made -it, or change your mind while composing text on the fly. - - The most fundamental command for correcting erroneous editing is the -undo command, @kbd{C-x u} or @kbd{C-_} or @kbd{C-/}. This command -undoes a single command (usually), a part of a command (in the case of -@code{query-replace}), or several consecutive self-inserting -characters. Consecutive repetitions of the undo command undo earlier -and earlier changes, back to the limit of the undo information -available. @xref{Undo}, for more information. - -@menu -* Undo:: The Undo commands. -* Kill Errors:: Commands to kill a batch of recently entered text. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. -@end menu - -@node Undo -@section Undo -@cindex undo -@cindex changes, undoing - - The @dfn{undo} commands undo recent changes in the buffer's text. -Each buffer records changes individually, and the undo command always -applies to the current buffer. You can undo all the changes in a -buffer for as far as back these records go. Usually each editing -command makes a separate entry in the undo records, but some commands -such as @code{query-replace} divide their changes into multiple -entries for flexibility in undoing. Meanwhile, self-inserting -characters are usually grouped to make undoing less tedious. - -@table @kbd -@item C-x u -@itemx C-_ -@itemx C-/ -Undo one entry in the current buffer's undo records (@code{undo}). -@end table - -@kindex C-x u -@kindex C-_ -@kindex C-/ -@findex undo - To begin to undo, type the command @kbd{C-x u} (or its aliases, -@kbd{C-_} or @kbd{C-/}). This undoes the most recent change in the -buffer, and moves point back to where it was before that change. - - Consecutive repetitions of @kbd{C-x u} (or its aliases) undo earlier -and earlier changes in the current buffer, back to the limit of the -current buffer's undo records. If all the recorded changes have -already been undone, the undo command just signals an error. - - If you notice that a buffer has been modified accidentally, the -easiest way to recover is to type @kbd{C-_} repeatedly until the stars -disappear from the front of the mode line. At this time, all the -modifications you made have been canceled. Whenever an undo command -makes the stars disappear from the mode line, it means that the buffer -contents are the same as they were when the file was last read in or -saved. - - If you do not remember whether you changed the buffer deliberately, -type @kbd{C-_} once. When you see the last change you made undone, you -will see whether it was an intentional change. If it was an accident, -leave it undone. If it was deliberate, redo the change as described -below. - -@findex undo-only - Any command other than an undo command breaks the sequence of undo -commands. Starting from that moment, the previous undo commands -become ordinary changes that you can undo. Thus, to redo changes you -have undone, type @kbd{C-f} or any other command that will harmlessly -break the sequence of undoing, then type undo commands again. On the -other hand, if you want to resume undoing, without redoing previous -undo commands, use @kbd{M-x undo-only}. This is like @code{undo}, but -will not redo changes you have just undone. - -@cindex selective undo -@kindex C-u C-x u - Ordinary undo applies to all changes made in the current buffer. You -can also perform @dfn{selective undo}, limited to the region. - - To do this, specify the region you want, then run the @code{undo} -command with a prefix argument (the value does not matter): @kbd{C-u -C-x u} or @kbd{C-u C-_}. This undoes the most recent change in the -region. To undo further changes in the same region, repeat the -@code{undo} command (no prefix argument is needed). In Transient Mark -mode (@pxref{Transient Mark}), any use of @code{undo} when there is an -active region performs selective undo; you do not need a prefix -argument. - - Some specialized buffers do not make undo records. Buffers -whose names start with spaces never do; these buffers are used -internally by Emacs and its extensions to hold text that users don't -normally look at or edit. - -@vindex undo-limit -@vindex undo-strong-limit -@vindex undo-outer-limit -@cindex undo limit - When the undo records for a buffer becomes too large, Emacs -discards the oldest undo records from time to time (during garbage -collection). You can specify how much undo records to keep by -setting three variables: @code{undo-limit}, @code{undo-strong-limit}, -and @code{undo-outer-limit}. Their values are expressed in units of -bytes of space. - - The variable @code{undo-limit} sets a soft limit: Emacs keeps undo -data for enough commands to reach this size, and perhaps exceed it, -but does not keep data for any earlier commands beyond that. Its -default value is 20000. The variable @code{undo-strong-limit} sets a -stricter limit: a previous command (not the most recent one) which -pushes the size past this amount is itself forgotten. The default -value of @code{undo-strong-limit} is 30000. - - Regardless of the values of those variables, the most recent change -is never discarded unless it gets bigger than @code{undo-outer-limit} -(normally 3,000,000). At that point, Emacs discards the undo data and -warns you about it. This is the only situation in which you cannot -undo the last command. If this happens, you can increase the value of -@code{undo-outer-limit} to make it even less likely to happen in the -future. But if you didn't expect the command to create such large -undo data, then it is probably a bug and you should report it. -@xref{Bugs,, Reporting Bugs}. - - The reason the @code{undo} command has three key bindings, @kbd{C-x -u}, @kbd{C-_} and @kbd{C-/}, is that it is worthy of a -single-character key, but @kbd{C-x u} is more straightforward for -beginners to remember and type. Meanwhile, @kbd{C--} on a text-only -terminal is really @kbd{C-_}, which makes it a natural and easily -typed binding for undoing. - -@node Kill Errors -@section Killing Your Mistakes - -@table @kbd -@item @key{DEL} -Delete last character (@code{delete-backward-char}). -@item M-@key{DEL} -Kill last word (@code{backward-kill-word}). -@item C-x @key{DEL} -Kill to beginning of sentence (@code{backward-kill-sentence}). -@end table - - The @key{DEL} character (@code{delete-backward-char}) is the most -important correction command. It deletes the character before point. -When @key{DEL} follows a self-inserting character command, you can think -of it as canceling that command. However, avoid the confusion of thinking -of @key{DEL} as a general way to cancel a command! - - When your mistake is longer than a couple of characters, it might be -more convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}. -@kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x -@key{DEL}} kills back to the start of the last sentence. @kbd{C-x -@key{DEL}} is particularly useful when you change your mind about the -phrasing of the text you are writing. @kbd{M-@key{DEL}} and @kbd{C-x -@key{DEL}} save the killed text for @kbd{C-y} and @kbd{M-y} to -retrieve. @xref{Yanking}.@refill - - @kbd{M-@key{DEL}} is often useful even when you have typed only a few -characters wrong, if you know you are confused in your typing and aren't -sure exactly what you typed. At such a time, you cannot correct with -@key{DEL} except by looking at the screen to see what you did. Often it -requires less thought to kill the whole word and start again. - -@node Transpose -@section Transposing Text - -@table @kbd -@item C-t -Transpose two characters (@code{transpose-chars}). -@item M-t -Transpose two words (@code{transpose-words}). -@item C-M-t -Transpose two balanced expressions (@code{transpose-sexps}). -@item C-x C-t -Transpose two lines (@code{transpose-lines}). -@end table - -@kindex C-t -@findex transpose-chars - The common error of transposing two characters can be fixed, when they -are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally, -@kbd{C-t} transposes the two characters on either side of point. When -given at the end of a line, rather than transposing the last character of -the line with the newline, which would be useless, @kbd{C-t} transposes the -last two characters on the line. So, if you catch your transposition error -right away, you can fix it with just a @kbd{C-t}. If you don't catch it so -fast, you must move the cursor back between the two transposed -characters before you type @kbd{C-t}. If you transposed a space with -the last character of the word before it, the word motion commands are -a good way of getting there. Otherwise, a reverse search (@kbd{C-r}) -is often the best way. @xref{Search}. - -@kindex C-x C-t -@findex transpose-lines -@kindex M-t -@findex transpose-words -@c Don't index C-M-t and transpose-sexps here, they are indexed in -@c programs.texi, in the "List Commands" node. -@c @kindex C-M-t -@c @findex transpose-sexps - @kbd{M-t} transposes the word before point with the word after point -(@code{transpose-words}). It moves point forward over a word, -dragging the word preceding or containing point forward as well. The -punctuation characters between the words do not move. For example, -@w{@samp{FOO, BAR}} transposes into @w{@samp{BAR, FOO}} rather than -@samp{@w{BAR FOO,}}. - - @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for -transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t} -(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} -except as regards what units of text they transpose. - - A numeric argument to a transpose command serves as a repeat count: it -tells the transpose command to move the character (word, expression, line) -before or containing point across several other characters (words, -expressions, lines). For example, @kbd{C-u 3 C-t} moves the character before -point forward across three other characters. It would change -@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to -repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word -before point backward across four words. @kbd{C-u - C-M-t} would cancel -the effect of plain @kbd{C-M-t}.@refill - - A numeric argument of zero is assigned a special meaning (because -otherwise a command with a repeat count of zero would do nothing): to -transpose the character (word, expression, line) ending after point -with the one ending after the mark. - -@node Fixing Case -@section Case Conversion - -@table @kbd -@item M-- M-l -Convert last word to lower case. Note @kbd{Meta--} is Meta-minus. -@item M-- M-u -Convert last word to all upper case. -@item M-- M-c -Convert last word to lower case with capital initial. -@end table - -@kindex M-@t{-} M-l -@kindex M-@t{-} M-u -@kindex M-@t{-} M-c - A very common error is to type words in the wrong case. Because of this, -the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a -special feature when used with a negative argument: they do not move the -cursor. As soon as you see you have mistyped the last word, you can simply -case-convert it and go on typing. @xref{Case}.@refill - -@node Spelling -@section Checking and Correcting Spelling -@cindex spelling, checking and correcting -@cindex checking spelling -@cindex correcting spelling - - This section describes the commands to check the spelling of a single -word or of a portion of a buffer. These commands work with the spelling -checker programs Aspell and Ispell, which are not part of Emacs. -@ifnottex -@xref{Top, Aspell,, aspell, The Aspell Manual}. -@end ifnottex - -@table @kbd -@item M-x flyspell-mode -Enable Flyspell mode, which highlights all misspelled words. -@item M-x flyspell-prog-mode -Enable Flyspell mode for comments and strings only. -@item M-$ -Check and correct spelling of the word at point (@code{ispell-word}). -@item M-@key{TAB} -@itemx @key{ESC} @key{TAB} -Complete the word before point based on the spelling dictionary -(@code{ispell-complete-word}). -@item M-x ispell -Spell-check the active region or the current buffer. -@item M-x ispell-buffer -Check and correct spelling of each word in the buffer. -@item M-x ispell-region -Check and correct spelling of each word in the region. -@item M-x ispell-message -Check and correct spelling of each word in a draft mail message, -excluding cited material. -@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET} -Restart the Aspell or Ispell process, using @var{dict} as the dictionary. -@item M-x ispell-kill-ispell -Kill the Aspell or Ispell subprocess. -@end table - -@cindex Flyspell mode -@findex flyspell-mode - Flyspell mode is a fully-automatic way to check spelling as you edit -in Emacs. It operates by checking words as you change or insert them. -When it finds a word that it does not recognize, it highlights that -word. This does not interfere with your editing, but when you see the -highlighted word, you can move to it and fix it. Type @kbd{M-x -flyspell-mode} to enable or disable this mode in the current buffer. - - When Flyspell mode highlights a word as misspelled, you can click on -it with @kbd{Mouse-2} to display a menu of possible corrections and -actions. You can also correct the word by editing it manually in any -way you like. - -@findex flyspell-prog-mode -Flyspell Prog mode works just like ordinary Flyspell mode, except that -it only checks words in comments and string constants. This feature -is useful for editing programs. Type @kbd{M-x flyspell-prog-mode} to -enable or disable this mode in the current buffer. - - The other Emacs spell-checking features check or look up words when -you give an explicit command to do so. - -@kindex M-$ -@findex ispell-word - To check the spelling of the word around or before point, and -optionally correct it as well, use the command @kbd{M-$} -(@code{ispell-word}). If the word is not correct, the command offers -you various alternatives for what to do about it. - -@findex ispell-buffer -@findex ispell-region - To check the entire current buffer, use @kbd{M-x ispell-buffer}. Use -@kbd{M-x ispell-region} to check just the current region. To check -spelling in an email message you are writing, use @kbd{M-x -ispell-message}; that command checks the whole buffer, except for -material that is indented or appears to be cited from other messages. - -@findex ispell -@cindex spell-checking the active region - The @kbd{M-x ispell} command spell-checks the active region if the -Transient Mark mode is on (@pxref{Transient Mark}), otherwise it -spell-checks the current buffer. - - Each time these commands encounter an incorrect word, they ask you -what to do. They display a list of alternatives, usually including -several ``near-misses''---words that are close to the word being -checked. Then you must type a single-character response. Here are -the valid responses: - -@table @kbd -@item @key{SPC} -Skip this word---continue to consider it incorrect, but don't change it -here. - -@item r @var{new} @key{RET} -Replace the word (just this time) with @var{new}. (The replacement -string will be rescanned for more spelling errors.) - -@item R @var{new} @key{RET} -Replace the word with @var{new}, and do a @code{query-replace} so you -can replace it elsewhere in the buffer if you wish. (The replacements -will be rescanned for more spelling errors.) - -@item @var{digit} -Replace the word (just this time) with one of the displayed -near-misses. Each near-miss is listed with a digit; type that digit to -select it. - -@item a -Accept the incorrect word---treat it as correct, but only in this -editing session. - -@item A -Accept the incorrect word---treat it as correct, but only in this -editing session and for this buffer. - -@item i -Insert this word in your private dictionary file so that Aspell or Ispell will -consider it correct from now on, even in future sessions. - -@item u -Insert the lower-case version of this word in your private dic@-tion@-ary -file. - -@item m -Like @kbd{i}, but you can also specify dictionary completion -information. - -@item l @var{word} @key{RET} -Look in the dictionary for words that match @var{word}. These words -become the new list of ``near-misses''; you can select one of them as -the replacement by typing a digit. You can use @samp{*} in @var{word} as a -wildcard. - -@item C-g -Quit interactive spell checking, leaving point at the word that was -being checked. You can restart checking again afterward with @kbd{C-u -M-$}. - -@item X -Same as @kbd{C-g}. - -@item x -Quit interactive spell checking and move point back to where it was -when you started spell checking. - -@item q -Quit interactive spell checking and kill the Ispell subprocess. - -@item C-l -Refresh the screen. - -@item C-z -This key has its normal command meaning (suspend Emacs or iconify this -frame). - -@item ? -Show the list of options. -@end table - -@findex ispell-complete-word - The command @code{ispell-complete-word}, which is bound to the key -@kbd{M-@key{TAB}} in Text mode and related modes, shows a list of -completions based on spelling correction. Insert the beginning of a -word, and then type @kbd{M-@key{TAB}}; the command displays a -completion list window. (If your window manager intercepts -@kbd{M-@key{TAB}}, type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) To -choose one of the completions listed, click @kbd{Mouse-2} or -@kbd{Mouse-1} fast on it, or move the cursor there in the completions -window and type @key{RET}. @xref{Text Mode}. - -@ignore -@findex reload-ispell - The first time you use any of the spell checking commands, it starts -an Ispell subprocess. The first thing the subprocess does is read your -private dictionary, which defaults to the file @file{~/ispell.words}. -Words that you ``insert'' with the @kbd{i} command are added to that -file, but not right away---only at the end of the interactive -replacement procedure. Use the @kbd{M-x reload-ispell} command to -reload your private dictionary if you edit the file outside of Ispell. -@end ignore - -@cindex @code{ispell} program -@findex ispell-kill-ispell - Once started, the Aspell or Ispell subprocess continues to run -(waiting for something to do), so that subsequent spell checking -commands complete more quickly. If you want to get rid of the -process, use @kbd{M-x ispell-kill-ispell}. This is not usually -necessary, since the process uses no time except when you do spelling -correction. - -@vindex ispell-dictionary - Ispell and Aspell use two dictionaries together for spell checking: the -standard dictionary and your private dictionary. The variable -@code{ispell-dictionary} specifies the file name to use for the -standard dictionary; a value of @code{nil} selects the default -dictionary. The command @kbd{M-x ispell-change-dictionary} sets this -variable and then restarts the subprocess, so that it will use -a different standard dictionary. - -@vindex ispell-complete-word-dict - Aspell and Ispell use a separate dictionary for word completion. -The variable @code{ispell-complete-word-dict} specifies the file name -of this dictionary. The completion dictionary must be different -because it cannot use root and affix information. For some languages -there is a spell checking dictionary but no word completion -dictionary. - -@ignore - arch-tag: 3359a443-96ed-448f-9f05-c8111ba8eac0 -@end ignore diff --git a/man/flymake.texi b/man/flymake.texi deleted file mode 100644 index 16947d7f2de..00000000000 --- a/man/flymake.texi +++ /dev/null @@ -1,762 +0,0 @@ -\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/man/forms.texi b/man/forms.texi deleted file mode 100644 index 4114453df6c..00000000000 --- a/man/forms.texi +++ /dev/null @@ -1,985 +0,0 @@ -\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/man/fortran-xtra.texi b/man/fortran-xtra.texi deleted file mode 100644 index 9249f5f006c..00000000000 --- a/man/fortran-xtra.texi +++ /dev/null @@ -1,548 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Fortran -@section Fortran Mode -@cindex Fortran mode -@cindex mode, Fortran - - Fortran mode provides special motion commands for Fortran statements -and subprograms, and indentation commands that understand Fortran -conventions of nesting, line numbers and continuation statements. -Fortran mode has support for Auto Fill mode that breaks long lines into -proper Fortran continuation lines. - - Special commands for comments are provided because Fortran comments -are unlike those of other languages. Built-in abbrevs optionally save -typing when you insert Fortran keywords. - - Use @kbd{M-x fortran-mode} to switch to this major mode. This -command runs the hook @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@cindex Fortran77 and Fortran90 -@findex f90-mode -@findex fortran-mode - Fortran mode is meant for editing Fortran77 ``fixed format'' (and also -``tab format'') source code. For editing the modern Fortran90 or -Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}). -Emacs normally uses Fortran mode for files with extension @samp{.f}, -@samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and -@samp{.f95}. GNU Fortran supports both kinds of format. - -@menu -* Motion: Fortran Motion. Moving point by statements or subprograms. -* Indent: Fortran Indent. Indentation commands for Fortran. -* Comments: Fortran Comments. Inserting and aligning comments. -* Autofill: Fortran Autofill. Auto fill support for Fortran. -* Columns: Fortran Columns. Measuring columns for valid Fortran. -* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. -@end menu - -@node Fortran Motion -@subsection Motion Commands - - In addition to the normal commands for moving by and operating on -``defuns'' (Fortran subprograms---functions and subroutines, as well as -modules for F90 mode), Fortran mode provides special commands to move by -statements and other program units. - -@table @kbd -@kindex C-c C-n @r{(Fortran mode)} -@findex fortran-next-statement -@findex f90-next-statement -@item C-c C-n -Move to the beginning of the next statement -(@code{fortran-next-statement}/@code{f90-next-statement}). - -@kindex C-c C-p @r{(Fortran mode)} -@findex fortran-previous-statement -@findex f90-previous-statement -@item C-c C-p -Move to the beginning of the previous statement -(@code{fortran-previous-statement}/@code{f90-previous-statement}). -If there is no previous statement (i.e. if called from the first -statement in the buffer), move to the start of the buffer. - -@kindex C-c C-e @r{(F90 mode)} -@findex f90-next-block -@item C-c C-e -Move point forward to the start of the next code block -(@code{f90-next-block}). A code block is a subroutine, -@code{if}--@code{endif} statement, and so forth. This command exists -for F90 mode only, not Fortran mode. With a numeric argument, this -moves forward that many blocks. - -@kindex C-c C-a @r{(F90 mode)} -@findex f90-previous-block -@item C-c C-a -Move point backward to the previous code block -(@code{f90-previous-block}). This is like @code{f90-next-block}, but -moves backwards. - -@kindex C-M-n @r{(Fortran mode)} -@findex fortran-end-of-block -@findex f90-end-of-block -@item C-M-n -Move to the end of the current code block -(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric -argument, move forward that number of blocks. The mark is set before -moving point. The F90 mode version of this command checks for -consistency of block types and labels (if present), but it does not -check the outermost block since that may be incomplete. - -@kindex C-M-p @r{(Fortran mode)} -@findex fortran-beginning-of-block -@findex f90-beginning-of-block -@item C-M-p -Move to the start of the current code block -(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This -is like @code{fortran-end-of-block}, but moves backwards. -@end table - -@node Fortran Indent -@subsection Fortran Indentation - - Special commands and features are needed for indenting Fortran code in -order to make sure various syntactic entities (line numbers, comment line -indicators and continuation line flags) appear in the columns that are -required for standard, fixed (or tab) format Fortran. - -@menu -* Commands: ForIndent Commands. Commands for indenting and filling Fortran. -* Contline: ForIndent Cont. How continuation lines indent. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. -@end menu - -@node ForIndent Commands -@subsubsection Fortran Indentation and Filling Commands - -@table @kbd -@item C-M-j -Break the current line at point and set up a continuation line -(@code{fortran-split-line}). -@item M-^ -Join this line to the previous line (@code{fortran-join-line}). -@item C-M-q -Indent all the lines of the subprogram point is in -(@code{fortran-indent-subprogram}). -@item M-q -Fill a comment block or statement. -@end table - -@kindex C-M-q @r{(Fortran mode)} -@findex fortran-indent-subprogram - The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command -to reindent all the lines of the Fortran subprogram (function or -subroutine) containing point. - -@kindex C-M-j @r{(Fortran mode)} -@findex fortran-split-line - The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits -a line in the appropriate fashion for Fortran. In a non-comment line, -the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. - -@kindex M-^ @r{(Fortran mode)} -@kindex C-c C-d @r{(Fortran mode)} -@findex fortran-join-line - @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, -which joins a continuation line back to the previous line, roughly as -the inverse of @code{fortran-split-line}. The point must be on a -continuation line when this command is invoked. - -@kindex M-q @r{(Fortran mode)} -@kbd{M-q} in Fortran mode fills the comment block or statement that -point is in. This removes any excess statement continuations. - -@node ForIndent Cont -@subsubsection Continuation Lines -@cindex Fortran continuation lines - -@vindex fortran-continuation-string - Most Fortran77 compilers allow two ways of writing continuation lines. -If the first non-space character on a line is in column 5, then that -line is a continuation of the previous line. We call this @dfn{fixed -format}. (In GNU Emacs we always count columns from 0; but note that -the Fortran standard counts from 1.) The variable -@code{fortran-continuation-string} specifies what character to put in -column 5. A line that starts with a tab character followed by any digit -except @samp{0} is also a continuation line. We call this style of -continuation @dfn{tab format}. (Fortran90 introduced ``free format,'' -with another style of continuation lines). - -@vindex indent-tabs-mode @r{(Fortran mode)} -@vindex fortran-analyze-depth -@vindex fortran-tab-mode-default - Fortran mode can use either style of continuation line. When you -enter Fortran mode, it tries to deduce the proper continuation style -automatically from the buffer contents. It does this by scanning up to -@code{fortran-analyze-depth} (default 100) lines from the start of the -buffer. The first line that begins with either a tab character or six -spaces determines the choice. If the scan fails (for example, if the -buffer is new and therefore empty), the value of -@code{fortran-tab-mode-default} (@code{nil} for fixed format, and -non-@code{nil} for tab format) is used. @samp{/t} in the mode line -indicates tab format is selected. Fortran mode sets the value of -@code{indent-tabs-mode} accordingly. - - If the text on a line starts with the Fortran continuation marker -@samp{$}, or if it begins with any non-whitespace character in column -5, Fortran mode treats it as a continuation line. When you indent a -continuation line with @key{TAB}, it converts the line to the current -continuation style. When you split a Fortran statement with -@kbd{C-M-j}, the continuation marker on the newline is created according -to the continuation style. - - The setting of continuation style affects several other aspects of -editing in Fortran mode. In fixed format mode, the minimum column -number for the body of a statement is 6. Lines inside of Fortran -blocks that are indented to larger column numbers always use only the -space character for whitespace. In tab format mode, the minimum -column number for the statement body is 8, and the whitespace before -column 8 must always consist of one tab character. - -@node ForIndent Num -@subsubsection Line Numbers - - If a number is the first non-whitespace in the line, Fortran -indentation assumes it is a line number and moves it to columns 0 -through 4. (Columns always count from 0 in GNU Emacs.) - -@vindex fortran-line-number-indent - Line numbers of four digits or less are normally indented one space. -The variable @code{fortran-line-number-indent} controls this; it -specifies the maximum indentation a line number can have. The default -value of the variable is 1. Fortran mode tries to prevent line number -digits passing column 4, reducing the indentation below the specified -maximum if necessary. If @code{fortran-line-number-indent} has the -value 5, line numbers are right-justified to end in column 4. - -@vindex fortran-electric-line-number - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -@code{fortran-electric-line-number} to @code{nil}. - - -@node ForIndent Conv -@subsubsection Syntactic Conventions - - Fortran mode assumes that you follow certain conventions that simplify -the task of understanding a Fortran program well enough to indent it -properly: - -@itemize @bullet -@item -Two nested @samp{do} loops never share a @samp{continue} statement. - -@item -Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} -and others are written without embedded whitespace or line breaks. - -Fortran compilers generally ignore whitespace outside of string -constants, but Fortran mode does not recognize these keywords if they -are not contiguous. Constructs such as @samp{else if} or @samp{end do} -are acceptable, but the second word should be on the same line as the -first and not on a continuation line. -@end itemize - -@noindent -If you fail to follow these conventions, the indentation commands may -indent some lines unaesthetically. However, a correct Fortran program -retains its meaning when reindented even if the conventions are not -followed. - -@node ForIndent Vars -@subsubsection Variables for Fortran Indentation - -@vindex fortran-do-indent -@vindex fortran-if-indent -@vindex fortran-structure-indent -@vindex fortran-continuation-indent -@vindex fortran-check-all-num@dots{} -@vindex fortran-minimum-statement-indent@dots{} - Several additional variables control how Fortran indentation works: - -@table @code -@item fortran-do-indent -Extra indentation within each level of @samp{do} statement (default 3). - -@item fortran-if-indent -Extra indentation within each level of @samp{if}, @samp{select case}, or -@samp{where} statements (default 3). - -@item fortran-structure-indent -Extra indentation within each level of @samp{structure}, @samp{union}, -@samp{map}, or @samp{interface} statements (default 3). - -@item fortran-continuation-indent -Extra indentation for bodies of continuation lines (default 5). - -@item fortran-check-all-num-for-matching-do -In Fortran77, a numbered @samp{do} statement is ended by any statement -with a matching line number. It is common (but not compulsory) to use a -@samp{continue} statement for this purpose. If this variable has a -non-@code{nil} value, indenting any numbered statement must check for a -@samp{do} that ends there. If you always end @samp{do} statements with -a @samp{continue} line (or if you use the more modern @samp{enddo}), -then you can speed up indentation by setting this variable to -@code{nil}. The default is @code{nil}. - -@item fortran-blink-matching-if -If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} -statement moves the cursor momentarily to the matching @samp{if} (or -@samp{do}) statement to show where it is. The default is @code{nil}. - -@item fortran-minimum-statement-indent-fixed -Minimum indentation for Fortran statements when using fixed format -continuation line style. Statement bodies are never indented less than -this much. The default is 6. - -@item fortran-minimum-statement-indent-tab -Minimum indentation for Fortran statements for tab format continuation line -style. Statement bodies are never indented less than this much. The -default is 8. -@end table - -The variables controlling the indentation of comments are described in -the following section. - -@node Fortran Comments -@subsection Fortran Comments - - The usual Emacs comment commands assume that a comment can follow a -line of code. In Fortran77, the standard comment syntax requires an -entire line to be just a comment. Therefore, Fortran mode replaces the -standard Emacs comment commands and defines some new variables. - -@vindex fortran-comment-line-start - Fortran mode can also handle the Fortran90 comment syntax where comments -start with @samp{!} and can follow other text. Because only some Fortran77 -compilers accept this syntax, Fortran mode will not insert such comments -unless you have said in advance to do so. To do this, set the variable -@code{fortran-comment-line-start} to @samp{"!"}. - -@table @kbd -@item M-; -Align comment or insert new comment (@code{fortran-indent-comment}). - -@item C-x ; -Applies to nonstandard @samp{!} comments only. - -@item C-c ; -Turn all lines of the region into comments, or (with argument) turn them back -into real code (@code{fortran-comment-region}). -@end table - -@findex fortran-indent-comment - @kbd{M-;} in Fortran mode is redefined as the command -@code{fortran-indent-comment}. Like the usual @kbd{M-;} command, this -recognizes any kind of existing comment and aligns its text appropriately; -if there is no existing comment, a comment is inserted and aligned. But -inserting and aligning comments are not the same in Fortran mode as in -other modes. - - When a new comment must be inserted, if the current line is blank, a -full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} -comment is inserted if you have said you want to use them. Otherwise a -full-line comment is inserted on a new line before the current line. - - Nonstandard @samp{!} comments are aligned like comments in other -languages, but full-line comments are different. In a standard full-line -comment, the comment delimiter itself must always appear in column zero. -What can be aligned is the text within the comment. You can choose from -three styles of alignment by setting the variable -@code{fortran-comment-indent-style} to one of these values: - -@vindex fortran-comment-indent-style -@vindex fortran-comment-line-extra-indent -@table @code -@item fixed -Align the text at a fixed column, which is the sum of -@code{fortran-comment-line-extra-indent} and the minimum statement -indentation. This is the default. - -The minimum statement indentation is -@code{fortran-minimum-statement-indent-fixed} for fixed format -continuation line style and @code{fortran-minimum-statement-indent-tab} -for tab format style. - -@item relative -Align the text as if it were a line of code, but with an additional -@code{fortran-comment-line-extra-indent} columns of indentation. - -@item nil -Don't move text in full-line comments automatically. -@end table - -@vindex fortran-comment-indent-char - In addition, you can specify the character to be used to indent within -full-line comments by setting the variable -@code{fortran-comment-indent-char} to the single-character string you want -to use. - -@vindex fortran-directive-re - Compiler directive lines, or preprocessor lines, have much the same -appearance as comment lines. It is important, though, that such lines -never be indented at all, no matter what the value of -@code{fortran-comment-indent-style}. The variable -@code{fortran-directive-re} is a regular expression that specifies which -lines are directives. Matching lines are never indented, and receive -distinctive font-locking. - - The normal Emacs comment command @kbd{C-x ;} has not been redefined. If -you use @samp{!} comments, this command can be used with them. Otherwise -it is useless in Fortran mode. - -@kindex C-c ; @r{(Fortran mode)} -@findex fortran-comment-region -@vindex fortran-comment-region - The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the -lines of the region into comments by inserting the string @samp{C$$$} at -the front of each one. With a numeric argument, it turns the region -back into live code by deleting @samp{C$$$} from the front of each line -in it. The string used for these comments can be controlled by setting -the variable @code{fortran-comment-region}. Note that here we have an -example of a command and a variable with the same name; these two uses -of the name never conflict because in Lisp and in Emacs it is always -clear from the context which one is meant. - -@node Fortran Autofill -@subsection Auto Fill in Fortran Mode - - Fortran mode has specialized support for Auto Fill mode, which is a -minor mode that automatically splits statements as you insert them -when they become too wide. Splitting a statement involves making -continuation lines using @code{fortran-continuation-string} -(@pxref{ForIndent Cont}). This splitting happens when you type -@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran -indentation commands. You activate Auto Fill in Fortran mode in the -normal way. -@iftex -@xref{Auto Fill,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Auto Fill}. -@end ifnottex - -@vindex fortran-break-before-delimiters - Auto Fill breaks lines at spaces or delimiters when the lines get -longer than the desired width (the value of @code{fill-column}). The -delimiters (besides whitespace) that Auto Fill can break at are -@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, -and @samp{,}. The line break comes after the delimiter if the -variable @code{fortran-break-before-delimiters} is @code{nil}. -Otherwise (and by default), the break comes before the delimiter. - - To enable Auto Fill in all Fortran buffers, add -@code{turn-on-auto-fill} to @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@node Fortran Columns -@subsection Checking Columns in Fortran - -@table @kbd -@item C-c C-r -Display a ``column ruler'' momentarily above the current line -(@code{fortran-column-ruler}). -@item C-c C-w -Split the current window horizontally temporarily so that it is 72 -columns wide (@code{fortran-window-create-momentarily}). This may -help you avoid making lines longer than the 72-character limit that -some Fortran compilers impose. -@item C-u C-c C-w -Split the current window horizontally so that it is 72 columns wide -(@code{fortran-window-create}). You can then continue editing. -@item M-x fortran-strip-sequence-nos -Delete all text in column 72 and beyond. -@end table - -@kindex C-c C-r @r{(Fortran mode)} -@findex fortran-column-ruler - The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column -ruler momentarily above the current line. The comment ruler is two lines -of text that show you the locations of columns with special significance in -Fortran programs. Square brackets show the limits of the columns for line -numbers, and curly brackets show the limits of the columns for the -statement body. Column numbers appear above them. - - Note that the column numbers count from zero, as always in GNU Emacs. -As a result, the numbers may be one less than those you are familiar -with; but the positions they indicate in the line are standard for -Fortran. - -@vindex fortran-column-ruler-fixed -@vindex fortran-column-ruler-tabs - The text used to display the column ruler depends on the value of the -variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is -@code{nil}, then the value of the variable -@code{fortran-column-ruler-fixed} is used as the column ruler. -Otherwise, the value of the variable @code{fortran-column-ruler-tab} is -displayed. By changing these variables, you can change the column ruler -display. - -@kindex C-c C-w @r{(Fortran mode)} -@findex fortran-window-create-momentarily - @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily -splits the current window horizontally, making a window 72 columns -wide, so you can see any lines that are too long. Type a space to -restore the normal width. - -@kindex C-u C-c C-w @r{(Fortran mode)} -@findex fortran-window-create - You can also split the window horizontally and continue editing with -the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x -fortran-window-create}). By editing in this window you can -immediately see when you make a line too wide to be correct Fortran. - -@findex fortran-strip-sequence-nos - The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in -column 72 and beyond, on all lines in the current buffer. This is the -easiest way to get rid of old sequence numbers. - -@node Fortran Abbrev -@subsection Fortran Keyword Abbrevs - - Fortran mode provides many built-in abbrevs for common keywords and -declarations. These are the same sort of abbrev that you can define -yourself. To use them, you must turn on Abbrev mode. -@iftex -@xref{Abbrevs,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Abbrevs}. -@end ifnottex - - The built-in abbrevs are unusual in one way: they all start with a -semicolon. You cannot normally use semicolon in an abbrev, but Fortran -mode makes this possible by changing the syntax of semicolon to ``word -constituent.'' - - For example, one built-in Fortran abbrev is @samp{;c} for -@samp{continue}. If you insert @samp{;c} and then insert a punctuation -character such as a space or a newline, the @samp{;c} expands automatically -to @samp{continue}, provided Abbrev mode is enabled.@refill - - Type @samp{;?} or @samp{;C-h} to display a list of all the built-in -Fortran abbrevs and what they stand for. - -@ignore - arch-tag: 23ed7c36-1517-4646-9235-2d5ade5f06f6 -@end ignore diff --git a/man/frames.texi b/man/frames.texi deleted file mode 100644 index a45b582b455..00000000000 --- a/man/frames.texi +++ /dev/null @@ -1,1113 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Frames, International, Windows, Top -@chapter Frames and Graphical Displays -@cindex frames - - When using a graphical display, you can create multiple windows at -the system in a single Emacs session. Each system-level window that -belongs to Emacs displays a @dfn{frame} which can contain one or -several Emacs windows. A frame initially contains a single -general-purpose Emacs window which you can subdivide vertically or -horizontally into smaller windows. A frame normally contains its own -echo area and minibuffer, but you can make frames that don't have -these---they use the echo area and minibuffer of another frame. - - To avoid confusion, we reserve the word ``window'' for the -subdivisions that Emacs implements, and never use it to refer to a -frame. - - Editing you do in one frame affects the other frames. For -instance, if you put text in the kill ring in one frame, you can yank it -in another frame. If you exit Emacs through @kbd{C-x C-c} in one frame, -it terminates all the frames. To delete just one frame, use @kbd{C-x 5 -0} (that is zero, not @kbd{o}). - - Emacs compiled for MS-DOS emulates some windowing functionality, -so that you can use many of the features described in this chapter. -@iftex -@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{MS-DOS Mouse}. -@end ifnottex - -@menu -* Cut and Paste:: Mouse commands for cut and paste. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs job can talk to several displays. -* Special Buffer Frames:: You can make certain buffers have their own frames. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Wheeled Mice:: Using mouse wheels for scrolling. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Displaying information at the current mouse position. -* Mouse Avoidance:: Moving the mouse pointer out of the way. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text-only terminals. -@end menu - -@node Cut and Paste -@section Killing and Yanking on Graphical Displays - - This section describes facilities for selecting a region, killing, -and yanking using the mouse. - -@menu -* Mouse Commands:: Moving, cutting, and pasting, with the mouse. -* Cut/Paste Other App:: Transfering text between Emacs and other apps. -* Word and Line Mouse:: Mouse commands for selecting whole words or lines. -* Secondary Selection:: Cutting without altering point and mark. -* Clipboard:: Using the clipboard for selections. -@end menu - -@node Mouse Commands -@subsection Mouse Commands for Editing -@cindex mouse buttons (what they do) - - The mouse commands for selecting and copying a region are mostly -compatible with the @code{xterm} program. You can use the same mouse -commands for copying between Emacs and other window-based programs. -Most of these commands also work in Emacs when you run it under an -@code{xterm} terminal. - -@kindex DELETE @r{(and mouse selection)} - If you select a region with any of these mouse commands, and then -immediately afterward type the @key{DELETE} function key, it deletes the -region that you selected. The @key{BACKSPACE} function key and the -@acronym{ASCII} character @key{DEL} do not do this; if you type any other key -in between the mouse command and @key{DELETE}, it does not do this. - -@findex mouse-set-region -@findex mouse-set-point -@findex mouse-yank-at-click -@findex mouse-save-then-click -@kindex Mouse-1 -@kindex Mouse-2 -@kindex Mouse-3 -@table @kbd -@item Mouse-1 -Move point to where you click (@code{mouse-set-point}). -This is normally the left button. - -@vindex x-mouse-click-focus-ignore-position -Normally, Emacs does not distinguish between ordinary mouse clicks and -clicks that select a frame. When you click on a frame to select it, -that also changes the selected window and cursor position according to -the mouse click position. On the X window system, you can change this -behavior by setting the variable -@code{x-mouse-click-focus-ignore-position} to @code{t}. Then the -first click selects the frame, but does not affect the selected window -or cursor position. If you click again in the same place, since that -click will be in the selected frame, it will change the window or -cursor position. - -@item Drag-Mouse-1 -Set the region to the text you select by dragging, and copy it to the -kill ring (@code{mouse-set-region}). You can specify both ends of the -region with this single command. - -@vindex mouse-scroll-min-lines -If you move the mouse off the top or bottom of the window while -dragging, the window scrolls at a steady rate until you move the mouse -back into the window. This way, you can select regions that don't fit -entirely on the screen. The number of lines scrolled per step depends -on how far away from the window edge the mouse has gone; the variable -@code{mouse-scroll-min-lines} specifies a minimum step size. - -@vindex mouse-drag-copy-region -If the variable @code{mouse-drag-copy-region} is @code{nil}, this -mouse command does not copy the selected region into the kill ring. - -@item Mouse-2 -Yank the last killed text, where you click (@code{mouse-yank-at-click}). -This is normally the middle button. - -@item Mouse-3 -This command, @code{mouse-save-then-kill}, has several functions -depending on where you click and the status of the region. - -The most basic case is when you click @kbd{Mouse-1} in one place and -then @kbd{Mouse-3} in another. This selects the text between those two -positions as the region. It also copies the new region to the kill -ring, so that you can copy it to someplace else. - -If you click @kbd{Mouse-1} in the text, scroll with the scroll bar, and -then click @kbd{Mouse-3}, it remembers where point was before scrolling -(where you put it with @kbd{Mouse-1}), and uses that position as the -other end of the region. This is so that you can select a region that -doesn't fit entirely on the screen. - -More generally, if you do not have a highlighted region, @kbd{Mouse-3} -selects the text between point and the click position as the region. It -does this by setting the mark where point was, and moving point to where -you click. - -If you have a highlighted region, or if the region was set just before -by dragging button 1, @kbd{Mouse-3} adjusts the nearer end of the region -by moving it to where you click. The adjusted region's text also -replaces the old region's text in the kill ring. - -If you originally specified the region using a double or triple -@kbd{Mouse-1}, so that the region is defined to consist of entire words -or lines, then adjusting the region with @kbd{Mouse-3} also proceeds by -entire words or lines. - -If you use @kbd{Mouse-3} a second time consecutively, at the same place, -that kills the region already selected. -@end table - - The simplest way to kill text with the mouse is to press @kbd{Mouse-1} -at one end, then press @kbd{Mouse-3} twice at the other end. -@xref{Killing}. To copy the text into the kill ring without deleting it -from the buffer, press @kbd{Mouse-3} just once---or just drag across the -text with @kbd{Mouse-1}. Then you can copy it elsewhere by yanking it. - -@vindex mouse-yank-at-point - To yank the killed or copied text somewhere else, move the mouse there -and press @kbd{Mouse-2}. @xref{Yanking}. However, if -@code{mouse-yank-at-point} is non-@code{nil}, @kbd{Mouse-2} yanks at -point. Then it does not matter where you click, or even which of the -frame's windows you click on. The default value is @code{nil}. This -variable also affects yanking the secondary selection. - -@cindex Delete Selection mode -@cindex mode, Delete Selection -@findex delete-selection-mode - Many graphical applications follow the convention that insertion while text -is selected deletes the selected text. You can make Emacs behave this -way by enabling Delete Selection mode---with @kbd{M-x -delete-selection-mode} or using Custom. Another effect of this mode -is that @key{DEL}, @kbd{C-d} and some other keys, when a selection -exists, will kill the whole selection. It also enables Transient Mark -mode (@pxref{Transient Mark}). - -@node Cut/Paste Other App -@subsection Cut and Paste with Other Window Applications - -@cindex cutting -@cindex pasting -@cindex X cutting and pasting - To copy text to another windowing application, kill it or save it in -the kill ring. Then use the ``paste'' or ``yank'' command of the -other application to insert the text. - - To copy text from another windowing application, use its ``cut'' or -``copy'' command to select the text you want. Then yank it in Emacs -with @kbd{C-y} or @kbd{Mouse-2}. - -@cindex primary selection -@cindex cut buffer -@cindex selection, primary -@vindex x-cut-buffer-max - When Emacs puts text into the kill ring, or rotates text to the -front of the kill ring, it sets the @dfn{primary selection} in the -window system. This is how other windowing applications can access -the text. On the X Window System, emacs also stores the text in the -cut buffer, but only if the text is short enough (the value of -@code{x-cut-buffer-max} specifies the maximum number of characters); -putting long strings in the cut buffer can be slow. - - The commands to yank the first entry in the kill ring actually check -first for a primary selection in another program; after that, they check -for text in the cut buffer. If neither of those sources provides text -to yank, the kill ring contents are used. - - The standard coding system for X Window System selections is -@code{compound-text-with-extensions}. To specify another coding -system for selections, use @kbd{C-x @key{RET} x} or @kbd{C-x @key{RET} -X}. @xref{Communication Coding}. - -@node Word and Line Mouse -@subsection Mouse Commands for Words and Lines - - These variants of @kbd{Mouse-1} select entire words or lines at a time. - -@table @kbd -@item Double-Mouse-1 -This key sets the region around the word which you click on. If you -click on a character with ``symbol'' syntax (such as underscore, in C -mode), it sets the region around the symbol surrounding that character. - -If you click on a character with open-parenthesis or close-parenthesis -syntax, it sets the region around the parenthetical grouping -which that character starts or ends. If you click on a character with -string-delimiter syntax (such as a singlequote or doublequote in C), it -sets the region around the string constant (using heuristics to figure -out whether that character is the beginning or the end of it). - -@item Double-Drag-Mouse-1 -This key selects a region made up of the words you drag across. - -@item Triple-Mouse-1 -This key sets the region around the line you click on. - -@item Triple-Drag-Mouse-1 -This key selects a region made up of the lines you drag across. -@end table - -@node Secondary Selection -@subsection Secondary Selection -@cindex secondary selection - - The @dfn{secondary selection} is another way of selecting text using -the X Window System. It does not use point or the mark, so you can -use it to kill text without setting point or the mark. - -@table @kbd -@findex mouse-set-secondary -@kindex M-Drag-Mouse-1 -@item M-Drag-Mouse-1 -Set the secondary selection, with one end at the place where you press -down the button, and the other end at the place where you release it -(@code{mouse-set-secondary}). The highlighting appears and changes as -you drag. You can control the appearance of the highlighting by -customizing the @code{secondary-selection} face (@pxref{Face -Customization}). - -If you move the mouse off the top or bottom of the window while -dragging, the window scrolls at a steady rate until you move the mouse -back into the window. This way, you can mark regions that don't fit -entirely on the screen. - -This way of setting the secondary selection does not alter the kill ring. - -@findex mouse-start-secondary -@kindex M-Mouse-1 -@item M-Mouse-1 -Set one endpoint for the @dfn{secondary selection} -(@code{mouse-start-secondary}). - -@findex mouse-secondary-save-then-kill -@kindex M-Mouse-3 -@item M-Mouse-3 -Make a secondary selection, using the place specified with @kbd{M-Mouse-1} -as the other end (@code{mouse-secondary-save-then-kill}). This also -puts the selected text in the kill ring. A second click at the same -place kills the secondary selection just made. - -@findex mouse-yank-secondary -@kindex M-Mouse-2 -@item M-Mouse-2 -Insert the secondary selection where you click -(@code{mouse-yank-secondary}). This places point at the end of the -yanked text. -@end table - -Double or triple clicking of @kbd{M-Mouse-1} operates on words and -lines, much like @kbd{Mouse-1}. - -If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks -at point. Then it does not matter precisely where you click, or even -which of the frame's windows you click on. @xref{Mouse Commands}. - -@node Clipboard -@subsection Using the Clipboard -@cindex clipboard -@vindex x-select-enable-clipboard -@findex menu-bar-enable-clipboard -@cindex OpenWindows -@cindex Gnome - - Apart from the primary and secondary selection types, Emacs can -handle the @dfn{clipboard} selection type which is used by some -applications, particularly under OpenWindows and Gnome. - - The command @kbd{M-x menu-bar-enable-clipboard} makes the @code{Cut}, -@code{Paste} and @code{Copy} menu items, as well as the keys of the same -names, all use the clipboard. - - You can customize the variable @code{x-select-enable-clipboard} to make -the Emacs yank functions consult the clipboard before the primary -selection, and to make the kill functions to store in the clipboard as -well as the primary selection. Otherwise they do not access the -clipboard at all. Using the clipboard is the default on MS-Windows and Mac, -but not on other systems. - -@node Mouse References -@section Following References with the Mouse -@kindex Mouse-1 @r{(selection)} -@kindex Mouse-2 @r{(selection)} - - Some read-only Emacs buffers include references you can follow, or -commands you can activate. These include names of files, of buffers, -of possible completions, of matches for a pattern, as well as the -buttons in Help buffers and customization buffers. You can follow the -reference or activate the command by moving point to it and typing -@key{RET}. You can also do this with the mouse, using either -@kbd{Mouse-1} or @kbd{Mouse-2}. - - Since yanking text into a read-only buffer is not allowed, these -buffers generally define @kbd{Mouse-2} to follow a reference or -activate a command. For example, if you click @kbd{Mouse-2} on a file -name in a Dired buffer, you visit that file. If you click -@kbd{Mouse-2} on an error message in the @samp{*Compilation*} buffer, -you go to the source code for that error message. If you click -@kbd{Mouse-2} on a completion in the @samp{*Completions*} buffer, you -choose that completion. - - However, most applications use @kbd{Mouse-1} to do this sort of -thing, so Emacs implements this too. If you click @kbd{Mouse-1} -quickly on a reference or button, it follows or activates. If you -click slowly, it moves point as usual. Dragging, meaning moving the -mouse while it is held down, also has its usual behavior of setting -the region. - -@vindex mouse-1-click-in-non-selected-windows - Normally, the @kbd{Mouse-1} click behavior is performed on links in -any window. The variable @code{mouse-1-click-in-non-selected-windows} -controls whether @kbd{Mouse-1} has this behavior even in non-selected -windows, or only in the selected window. - -@vindex mouse-highlight - You can usually tell when @kbd{Mouse-1} and @kbd{Mouse-2} have this -special sort of meaning because the sensitive text highlights when you -move the mouse over it. The variable @code{mouse-highlight} controls -whether to do this highlighting always (even when such text appears -where the mouse already is), never, or only immediately after you move -the mouse. - -@vindex mouse-1-click-follows-link - In Emacs versions before 22, only @kbd{Mouse-2} follows links and -@kbd{Mouse-1} always sets point. If you prefer this older behavior, -set the variable @code{mouse-1-click-follows-link} to @code{nil}. -This variable also lets you choose various other alternatives for -following links with the mouse. Type @kbd{C-h v -mouse-1-click-follows-link @key{RET}} for more details. - -@node Menu Mouse Clicks -@section Mouse Clicks for Menus - - Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers -bring up menus. - -@table @kbd -@item C-Mouse-1 -@kindex C-Mouse-1 -This menu is for selecting a buffer. - -The MSB (``mouse select buffer'') global minor mode makes this -menu smarter and more customizable. @xref{Buffer Menus}. - -@item C-Mouse-2 -@kindex C-Mouse-2 -This menu is for specifying faces and other text properties -for editing formatted text. @xref{Formatted Text}. - -@item C-Mouse-3 -@kindex C-Mouse-3 -This menu is mode-specific. For most modes if Menu-bar mode is on, -this menu has the same items as all the mode-specific menu-bar menus -put together. Some modes may specify a different menu for this -button.@footnote{Some systems use @kbd{Mouse-3} for a mode-specific -menu. We took a survey of users, and found they preferred to keep -@kbd{Mouse-3} for selecting and killing regions. Hence the decision -to use @kbd{C-Mouse-3} for this menu. To use @kbd{Mouse-3} instead, -do @code{(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)}.} If -Menu-bar mode is off, this menu contains all the items which would be -present in the menu bar---not just the mode-specific ones---so that -you can access them without having to display the menu bar. - -@item S-Mouse-1 -This menu is for specifying the frame's default font. -@end table - -@node Mode Line Mouse -@section Mode Line Mouse Commands -@cindex mode line, mouse -@cindex mouse on mode line - - You can use mouse clicks on window mode lines to select and manipulate -windows. - - Some areas of the mode line, such as the buffer name and the major -mode name, have their own special mouse bindings. These areas are -highlighted when you hold the mouse over them, and information about -the special bindings will be displayed (@pxref{Tooltips}). This -section's commands do not apply in those areas. - -@table @kbd -@item Mouse-1 -@kindex Mouse-1 @r{(mode line)} -@kbd{Mouse-1} on a mode line selects the window it belongs to. By -dragging @kbd{Mouse-1} on the mode line, you can move it, thus -changing the height of the windows above and below. Changing heights -with the mouse in this way never deletes windows, it just refuses to -make any window smaller than the minimum height. - -@item Mouse-2 -@kindex Mouse-2 @r{(mode line)} -@kbd{Mouse-2} on a mode line expands that window to fill its frame. - -@item Mouse-3 -@kindex Mouse-3 @r{(mode line)} -@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the -frame has only one window, it buries the current buffer instead, and -switches to another buffer. - -@item C-Mouse-2 -@kindex C-mouse-2 @r{(mode line)} -@kbd{C-Mouse-2} on a mode line splits the window above -horizontally, above the place in the mode line where you click. -@end table - -@kindex C-Mouse-2 @r{(scroll bar)} -@kindex Mouse-1 @r{(scroll bar)} - Using @kbd{Mouse-1} on the divider between two side-by-side mode -lines, you can move the vertical boundary left or right. Using -@kbd{C-Mouse-2} on a scroll bar splits the corresponding window -vertically. @xref{Split Window}. - -@node Creating Frames -@section Creating Frames -@cindex creating frames - -@kindex C-x 5 - The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with parallel -subcommands. The difference is that @kbd{C-x 5} commands create a new -frame rather than just a new window in the selected frame (@pxref{Pop -Up Window}). If an existing visible or iconified frame already displays -the requested material, these commands use the existing frame, after -raising or deiconifying as necessary. - - The various @kbd{C-x 5} commands differ in how they find or create the -buffer to select: - -@table @kbd -@item C-x 5 2 -@kindex C-x 5 2 -@findex make-frame-command -Create a new frame (@code{make-frame-command}). -@item C-x 5 b @var{bufname} @key{RET} -Select buffer @var{bufname} in another frame. This runs -@code{switch-to-buffer-other-frame}. -@item C-x 5 f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another frame. This -runs @code{find-file-other-frame}. @xref{Visiting}. -@item C-x 5 d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another frame. -This runs @code{dired-other-frame}. @xref{Dired}. -@item C-x 5 m -Start composing a mail message in another frame. This runs -@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. -@xref{Sending Mail}. -@item C-x 5 . -Find a tag in the current tag table in another frame. This runs -@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. -@xref{Tags}. -@item C-x 5 r @var{filename} @key{RET} -@kindex C-x 5 r -@findex find-file-read-only-other-frame -Visit file @var{filename} read-only, and select its buffer in another -frame. This runs @code{find-file-read-only-other-frame}. -@xref{Visiting}. -@end table - -@cindex default-frame-alist -@cindex initial-frame-alist -@cindex face customization, in @file{~/.emacs} -@cindex color customization, in @file{~/.emacs} - You can control the appearance of new frames you create by setting the -frame parameters in @code{default-frame-alist}. You can use the -variable @code{initial-frame-alist} to specify parameters that affect -only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs -Lisp Reference Manual}, for more information. - -@cindex font (default) - The easiest way to specify the principal font for all your Emacs -frames is with an X resource (@pxref{Font X}), but you can also do it by -modifying @code{default-frame-alist} to specify the @code{font} -parameter, as shown here: - -@example -(add-to-list 'default-frame-alist '(font . "10x20")) -@end example - -@noindent -Here's a similar example for specifying a foreground color: - -@example -(add-to-list 'default-frame-alist '(foreground-color . "blue")) -@end example - -@noindent -By putting such customizations in your @file{~/.emacs} init file, you -can control the appearance of all the frames Emacs creates, including -the initial one. - -@node Frame Commands -@section Frame Commands - - The following commands let you create, delete and operate on frames: - -@table @kbd -@item C-z -@kindex C-z @r{(X windows)} -@findex iconify-or-deiconify-frame -Iconify the selected Emacs frame (@code{iconify-or-deiconify-frame}). -When typed on an Emacs frame's icon, deiconify instead. - -The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under -a graphical display that allows multiple applications to operate -simultaneously in their own windows, so Emacs gives @kbd{C-z} a -different binding in that case. - -@item C-x 5 0 -@kindex C-x 5 0 -@findex delete-frame -Delete the selected frame (@code{delete-frame}). This is not allowed if -there is only one frame. - -@item C-x 5 o -@kindex C-x 5 o -@findex other-frame -Select another frame, raise it, and warp the mouse to it so that it -stays selected. If you repeat this command, it cycles through all the -frames on your terminal. - -@item C-x 5 1 -@kindex C-x 5 1 -@findex delete-other-frames -Delete all frames except the selected one. -@end table - -@vindex focus-follows-mouse - To make the command @kbd{C-x 5 o} work properly, you must tell Emacs -how the system (or the window manager) generally handles -focus-switching between windows. There are two possibilities: either -simply moving the mouse onto a window selects it (gives it focus), or -you have to click on it in a suitable way to do so. On X, this focus -policy also affects whether the focus is given to a frame that Emacs -raises. Unfortunately there is no way Emacs can find out -automatically which way the system handles this, so you have to -explicitly say, by setting the variable @code{focus-follows-mouse}. -If just moving the mouse onto a window selects it, that variable -should be @code{t}; if a click is necessary, the variable should be -@code{nil}. - -The window manager that is part of MS-Windows always gives focus to a -frame that raises, so this variable has no effect in the native -MS-Windows build of Emacs. - -@node Speedbar -@section Speedbar Frames -@cindex speedbar - -@cindex attached frame (of speedbar) - The @dfn{speedbar} is a special frame for conveniently navigating in -or operating on another frame. The speedbar, when it exists, is -always associated with a specific frame, called its @dfn{attached -frame}; all speedbar operations act on that frame. - - Type @kbd{M-x speedbar} to create the speedbar and associate it with -the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} -again, or select the speedbar and type @kbd{q}. (You can also delete -the speedbar frame like any other Emacs frame.) If you wish to -associate the speedbar with a different frame, dismiss it and call -@kbd{M-x speedbar} from that frame. - - The speedbar can operate in various modes. Its default mode is -@dfn{File Display} mode, which shows the files in the current -directory of the selected window of the attached frame, one file per -line. Clicking on a file name visits that file in the selected window -of the attached frame, and clicking on a directory name shows that -directory in the speedbar (@pxref{Mouse References}). Each line also -has a box, @samp{[+]} or @samp{<+>}, that you can click on to -@dfn{expand} the contents of that item. Expanding a directory adds -the contents of that directory to the speedbar display, underneath the -directory's own line. Expanding an ordinary file adds a list of the -tags in that file to the speedbar display; you can click on a tag name -to jump to that tag in the selected window of the attached frame. -When a file or directory is expanded, the @samp{[+]} changes to -@samp{[-]}; you can click on that box to @dfn{contract} the item, -hiding its contents. - - You navigate through the speedbar using the keyboard, too. Typing -@kbd{RET} while point is on a line in the speedbar is equivalent to -clicking the item on the current line, and @kbd{SPC} expands or -contracts the item. @kbd{U} displays the parent directory of the -current directory. To copy, delete, or rename the file on the current -line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a -new directory, type @kbd{M}. - - Another general-purpose speedbar mode is @dfn{Buffer Display} mode; -in this mode, the speedbar displays a list of Emacs buffers. To -switch to this mode, type @kbd{b} in the speedbar. To return to File -Display mode, type @kbd{f}. You can also change the display mode by -clicking @kbd{mouse-3} anywhere in the speedbar window (or -@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the -pop-up menu. - - Some major modes, including Rmail mode, Info, and GUD, have -specialized ways of putting useful items into the speedbar for you to -select. For example, in Rmail mode, the speedbar shows a list of Rmail -files, and lets you move the current message to another Rmail file by -clicking on its @samp{} box. - - For more details on using and programming the speedbar, @xref{Top, -Speedbar,,speedbar, Speedbar Manual}. - -@node Multiple Displays -@section Multiple Displays -@cindex multiple displays - - A single Emacs can talk to more than one X display. Initially, Emacs -uses just one display---the one specified with the @env{DISPLAY} -environment variable or with the @samp{--display} option (@pxref{Initial -Options}). To connect to another display, use the command -@code{make-frame-on-display}: - -@findex make-frame-on-display -@table @kbd -@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} -Create a new frame on display @var{display}. -@end table - - A single X server can handle more than one screen. When you open -frames on two screens belonging to one server, Emacs knows they share a -single keyboard, and it treats all the commands arriving from these -screens as a single stream of input. - - When you open frames on different X servers, Emacs makes a separate -input stream for each server. This way, two users can type -simultaneously on the two displays, and Emacs will not garble their -input. Each server also has its own selected frame. The commands you -enter with a particular X server apply to that server's selected frame. - - Despite these features, people using the same Emacs job from different -displays can still interfere with each other if they are not careful. -For example, if any one types @kbd{C-x C-c}, that exits the Emacs job -for all of them! - -@node Special Buffer Frames -@section Special Buffer Frames - -@vindex special-display-buffer-names - You can make certain chosen buffers, which Emacs normally displays -in ``another window,'' appear in special frames of their own. To do -this, set the variable @code{special-display-buffer-names} to a list -of buffer names; any buffer whose name is in that list automatically -gets a special frame, when an Emacs command wants to display it ``in -another window.'' - - For example, if you set the variable this way, - -@example -(setq special-display-buffer-names - '("*Completions*" "*grep*" "*tex-shell*")) -@end example - -@noindent -then completion lists, @code{grep} output and the @TeX{} mode shell -buffer get individual frames of their own. These frames, and the -windows in them, are never automatically split or reused for any other -buffers. They continue to show the buffers they were created for, -unless you alter them by hand. Killing the special buffer deletes its -frame automatically. - -@vindex special-display-regexps - More generally, you can set @code{special-display-regexps} to a list -of regular expressions; then a buffer gets its own frame if its name -matches any of those regular expressions. (Once again, this applies only -to buffers that normally get displayed for you in ``another window.'') - -@vindex special-display-frame-alist - The variable @code{special-display-frame-alist} specifies the frame -parameters for these frames. It has a default value, so you don't need -to set it. - - For those who know Lisp, an element of -@code{special-display-buffer-names} or @code{special-display-regexps} -can also be a list. Then the first element is the buffer name or -regular expression; the rest of the list specifies how to create the -frame. It can be an association list specifying frame parameter -values; these values take precedence over parameter values specified -in @code{special-display-frame-alist}. If you specify the symbol -@code{same-window} as a ``frame parameter'' in this list, with a -non-@code{nil} value, that means to use the selected window if -possible. If you use the symbol @code{same-frame} as a ``frame -parameter'' in this list, with a non-@code{nil} value, that means to -use the selected frame if possible. - - Alternatively, the value can have this form: - -@example -(@var{function} @var{args}...) -@end example - -@noindent -where @var{function} is a symbol. Then the frame is constructed by -calling @var{function}; its first argument is the buffer, and its -remaining arguments are @var{args}. - - An analogous feature lets you specify buffers which should be -displayed in the selected window. @xref{Force Same Window}. The -same-window feature takes precedence over the special-frame feature; -therefore, if you add a buffer name to -@code{special-display-buffer-names} and it has no effect, check to see -whether that feature is also in use for the same buffer name. - -@node Frame Parameters -@section Setting Frame Parameters -@cindex Auto-Raise mode -@cindex Auto-Lower mode - -@kindex S-Mouse-1 - You can specify the font and colors used for text display, and the -colors for the frame borders, the cursor, and the mouse cursor, by -customizing the faces @code{default}, @code{border}, @code{cursor} and -@code{mouse}. @xref{Face Customization}. You can also set a frame's -default font through a pop-up menu. Press @kbd{S-Mouse-1} to activate -this menu. - - These commands are available for controlling the window management -behavior of the selected frame. - -@table @kbd -@findex auto-raise-mode -@item M-x auto-raise-mode -Toggle whether or not the selected frame should auto-raise. Auto-raise -means that every time you move the mouse onto the frame, it raises the -frame. - -Some window managers also implement auto-raise. If you enable -auto-raise for Emacs frames in your window manager, it will work, but -it is beyond Emacs' control, so @code{auto-raise-mode} has no effect -on it. - -@findex auto-lower-mode -@item M-x auto-lower-mode -Toggle whether or not the selected frame should auto-lower. -Auto-lower means that every time you move the mouse off the frame, -the frame moves to the bottom of the stack on the screen. - -The command @code{auto-lower-mode} has no effect on auto-lower -implemented by the window manager. To control that, you must use the -appropriate window manager features. -@end table - - In Emacs versions that use an X toolkit, the color-setting and -font-setting functions don't affect menus and the menu bar, since they -are displayed by their own widget classes. To change the appearance of -the menus and menu bar, you must use X resources (@pxref{Resources}). -@xref{Colors}, regarding colors. @xref{Font X}, regarding choice of -font. - - Colors, fonts, and other attributes of the frame's display can also -be customized by setting frame parameters in the variable -@code{default-frame-alist} (@pxref{Creating Frames}). For a detailed -description of frame parameters and customization, see @ref{Frame -Parameters,,, elisp, The Emacs Lisp Reference Manual}. - -@node Scroll Bars -@section Scroll Bars -@cindex Scroll Bar mode -@cindex mode, Scroll Bar - - On graphical displays, Emacs normally makes a @dfn{scroll bar} at -the left of each Emacs window.@footnote{Placing it at the left is -usually more useful with overlapping frames with text starting at the -left margin.} The scroll bar runs the height of the window, and shows -a moving rectangular inner box which represents the portion of the -buffer currently displayed. The entire height of the scroll bar -represents the entire length of the buffer. - - You can use @kbd{Mouse-2} (normally, the middle button) in the scroll -bar to move or drag the inner box up and down. If you move it to the -top of the scroll bar, you see the top of the buffer. If you move it to -the bottom of the scroll bar, you see the bottom of the buffer. - - The left and right buttons in the scroll bar scroll by controlled -increments. @kbd{Mouse-1} (normally, the left button) moves the line at -the level where you click up to the top of the window. @kbd{Mouse-3} -(normally, the right button) moves the line at the top of the window -down to the level where you click. By clicking repeatedly in the same -place, you can scroll by the same distance over and over. - - You can also click @kbd{C-Mouse-2} in the scroll bar to split a -window vertically. The split occurs on the line where you click. - -@findex scroll-bar-mode -@vindex scroll-bar-mode - You can enable or disable Scroll Bar mode with the command @kbd{M-x -scroll-bar-mode}. With no argument, it toggles the use of scroll -bars. With an argument, it turns use of scroll bars on if and only if -the argument is positive. This command applies to all frames, -including frames yet to be created. Customize the variable -@code{scroll-bar-mode} to control the use of scroll bars at startup. -You can use it to specify that they are placed at the right of windows -if you prefer that. You have to set this variable through the -@samp{Customize} interface (@pxref{Easy Customization}), or it will -not work properly. - - You can also use the X resource @samp{verticalScrollBars} to control -the initial setting of Scroll Bar mode. @xref{Resources}. - -@findex toggle-scroll-bar - To enable or disable scroll bars for just the selected frame, use the -command @kbd{M-x toggle-scroll-bar}. - -@vindex scroll-bar-width -@cindex width of the scroll bar - You can control the scroll bar width by changing the value of the -@code{scroll-bar-width} frame parameter. - -@node Wheeled Mice -@section Scrolling With ``Wheeled'' Mice - -@cindex mouse wheel -@cindex wheel, mouse -@findex mouse-wheel-mode -@cindex Mouse Wheel minor mode -@cindex mode, Mouse Wheel - Some mice have a ``wheel'' instead of a third button. You can -usually click the wheel to act as either @kbd{Mouse-2} or -@kbd{Mouse-3}, depending on the setup. You can also use the wheel to -scroll windows instead of using the scroll bar or keyboard commands. -Mouse wheel support only works if the system generates appropriate -events; whenever possible, it is turned on by default. To toggle this -feature, use @kbd{M-x mouse-wheel-mode}. - -@vindex mouse-wheel-follow-mouse -@vindex mouse-wheel-scroll-amount -@vindex mouse-wheel-progressive-speed - The two variables @code{mouse-wheel-follow-mouse} and -@code{mouse-wheel-scroll-amount} determine where and by how much -buffers are scrolled. The variable -@code{mouse-wheel-progressive-speed} determines whether the scroll -speed is linked to how fast you move the wheel. - -@node Drag and Drop -@section Drag and Drop -@cindex drag and drop - - Emacs supports @dfn{drag and drop} using the mouse. For instance, -dropping text onto an Emacs frame inserts the text where it is dropped. -Dropping a file onto an Emacs frame visits that file. As a special -case, dropping the file on a Dired buffer moves or copies the file -(according to the conventions of the application it came from) into the -directory displayed in that buffer. - -@vindex dnd-open-file-other-window - Dropping a file normally visits it in the window you drop it on. If -you prefer to visit the file in a new window in such cases, customize -the variable @code{dnd-open-file-other-window}. - - The XDND and Motif drag and drop protocols, and the old KDE 1.x -protocol, are currently supported. - -@node Menu Bars -@section Menu Bars -@cindex Menu Bar mode -@cindex mode, Menu Bar -@findex menu-bar-mode -@vindex menu-bar-mode - - You can turn display of menu bars on or off with @kbd{M-x -menu-bar-mode} or by customizing the variable @code{menu-bar-mode}. -With no argument, this command toggles Menu Bar mode, a -minor mode. With an argument, the command turns Menu Bar mode on if the -argument is positive, off if the argument is not positive. You can use -the X resource @samp{menuBarLines} to control the initial setting of -Menu Bar mode. @xref{Resources}. - -@kindex C-Mouse-3 @r{(when menu bar is disabled)} - Expert users often turn off the menu bar, especially on text-only -terminals, where this makes one additional line available for text. -If the menu bar is off, you can still pop up a menu of its contents -with @kbd{C-Mouse-3} on a display which supports pop-up menus. -@xref{Menu Mouse Clicks}. - - @xref{Menu Bar}, for information on how to invoke commands with the -menu bar. @xref{X Resources}, for how to customize the menu bar -menus' visual appearance. - -@node Tool Bars -@section Tool Bars -@cindex Tool Bar mode -@cindex mode, Tool Bar -@cindex icons, toolbar - - The @dfn{tool bar} is a line (or lines) of icons at the top of the -Emacs window, just below the menu bar. You can click on these icons -with the mouse to do various jobs. - - The global tool bar contains general commands. Some major modes -define their own tool bars to replace it. A few ``special'' modes -that are not designed for ordinary editing remove some items from the -global tool bar. - - Tool bars work only on a graphical display. The tool bar uses colored -XPM icons if Emacs was built with XPM support. Otherwise, the tool -bar uses monochrome icons (PBM or XBM format). - -@findex tool-bar-mode -@vindex tool-bar-mode - You can turn display of tool bars on or off with @kbd{M-x -tool-bar-mode} or by customizing the option @code{tool-bar-mode}. - -@node Dialog Boxes -@section Using Dialog Boxes -@cindex dialog boxes - -@vindex use-dialog-box - A dialog box is a special kind of menu for asking you a yes-or-no -question or some other special question. Many Emacs commands use a -dialog box to ask a yes-or-no question, if you used the mouse to -invoke the command to begin with. - - You can customize the variable @code{use-dialog-box} to suppress the -use of dialog boxes. This also controls whether to use file selection -windows (but those are not supported on all platforms). - -@vindex use-file-dialog - A file selection window is a special kind of dialog box for asking -for file names. You can customize the variable @code{use-file-dialog} -to suppress the use of file selection windows, even if you still want -other kinds of dialogs. This variable has no effect if you have -suppressed all dialog boxes with the variable @code{use-dialog-box}. - -@vindex x-gtk-show-hidden-files - For Gtk+ version 2.4 and newer, Emacs use the Gtk+ file chooser -dialog. Emacs adds a toggle button that enables and disables showing -of hidden files (files starting with a dot) in that dialog. The -variable @code{x-gtk-show-hidden-files} controls whether to show -hidden files by default. - -@vindex x-gtk-use-old-file-dialog - For Gtk+ versions 2.4 through 2.10, you can select the old file -dialog (@code{gtk-file-selector}) by setting the variable -@code{x-gtk-use-old-file-dialog} to a non-@code{nil} value. If it is -@code{nil}, Emacs uses @code{gtk-file-chooser}. If Emacs is built -with a Gtk+ version that has only one file dialog, this variable has -no effect. - -@vindex x-gtk-file-dialog-help-text - Emacs adds help text to the Gtk+ file chooser dialog. The variable -@code{x-gtk-file-dialog-help-text} specifies the text to add; if it is -@code{nil}, that disables the added text. - -@node Tooltips -@section Tooltips -@cindex tooltips - - @dfn{Tooltips} are small windows that display text information at the -current mouse position. They activate when there is a pause in mouse -movement. There are two types of tooltip: help tooltips and GUD -tooltips. - - @dfn{Help tooltips} typically display over text---including the mode -line---but are also available for other parts of the Emacs frame, such -as the tool bar and menu items. - -@findex tooltip-mode - You can toggle display of help tooltips (Tooltip mode) with the -command @kbd{M-x tooltip-mode}. When Tooltip mode is disabled, the -help text is displayed in the echo area instead. - - @dfn{GUD tooltips} show values of variables. They are useful when -you are debugging a program. @xref{Debugger Operation}. - -@vindex tooltip-delay - The variables @code{tooltip-delay} specifies how long Emacs should -wait before displaying a tooltip. For additional customization -options for displaying tooltips, use @kbd{M-x customize-group -@key{RET} tooltip @key{RET}}. @xref{X Resources}, for information on -customizing the windows that display tooltips. - -@node Mouse Avoidance -@section Mouse Avoidance -@cindex avoiding mouse in the way of your typing -@cindex mouse avoidance - -@vindex mouse-avoidance-mode -Mouse Avoidance mode keeps the mouse pointer away from point, to avoid -obscuring text you want to edit. Whenever it moves the mouse, it also -raises the frame. To use Mouse Avoidance mode, customize the variable -@code{mouse-avoidance-mode}. You can set this to various values to -move the mouse in several ways: - -@table @code -@item banish -Move the mouse to the upper-right corner on any key-press; -@item exile -Move the mouse to the corner only if the cursor gets too close, -and allow it to return once the cursor is out of the way; -@item jump -If the cursor gets too close to the mouse, displace the mouse -a random distance & direction; -@item animate -As @code{jump}, but shows steps along the way for illusion of motion; -@item cat-and-mouse -The same as @code{animate}; -@item proteus -As @code{animate}, but changes the shape of the mouse pointer too. -@end table - -@findex mouse-avoidance-mode -You can also use the command @kbd{M-x mouse-avoidance-mode} to enable -the mode. - -@node Non-Window Terminals -@section Non-Window Terminals -@cindex non-window terminals -@cindex single-frame terminals - - On a text-only terminal, Emacs can display only one Emacs frame at a -time. However, you can still create multiple Emacs frames, and switch -between them. Switching frames on these terminals is much like -switching between different window configurations. - - Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x -5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete -the current frame. - - Each frame has a number to distinguish it. If your terminal can -display only one frame at a time, the selected frame's number @var{n} -appears near the beginning of the mode line, in the form -@samp{F@var{n}}. - -@findex set-frame-name -@findex select-frame-by-name - @samp{F@var{n}} is in fact the frame's initial name. You can give -frames more meaningful names if you wish, and you can select a frame -by its name. Use the command @kbd{M-x set-frame-name @key{RET} -@var{name} @key{RET}} to specify a new name for the selected frame, -and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}} -to select a frame according to its name. The name you specify appears -in the mode line when the frame is selected. - -@node Text-Only Mouse -@section Using a Mouse in Terminal Emulators -@cindex mouse support -@cindex terminal emulators, mouse support - -Some terminal emulators support mouse clicks in the terminal window. - -@cindex xterm -In a terminal emulator which is compatible with @code{xterm}, -you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over -simple use of the mouse---basically, only non-modified single clicks -are supported. The normal @code{xterm} mouse functionality for such -clicks is still available by holding down the @kbd{SHIFT} key when you -press the mouse button. Xterm Mouse mode is a global minor mode -(@pxref{Minor Modes}). Repeating the command turns the mode off -again. - -In the console on GNU/Linux, you can use @kbd{M-x t-mouse-mode}. You -need to have the gpm package installed and running on your system in -order for this to work. - -@ignore - arch-tag: 7dcf3a31-a43b-45d4-a900-445b10d77e49 -@end ignore diff --git a/man/glossary.texi b/man/glossary.texi deleted file mode 100644 index f289c2ca1cb..00000000000 --- a/man/glossary.texi +++ /dev/null @@ -1,1323 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Glossary, Key Index, Intro, Top -@unnumbered Glossary - -@table @asis -@item Abbrev -An abbrev is a text string which expands into a different text string -when present in the buffer. For example, you might define a few letters -as an abbrev for a long phrase that you want to insert frequently. -@xref{Abbrevs}. - -@item Aborting -Aborting means getting out of a recursive edit (q.v.@:). The -commands @kbd{C-]} and @kbd{M-x top-level} are used for this. -@xref{Quitting}. - -@item Alt -Alt is the name of a modifier bit which a keyboard input character may -have. To make a character Alt, type it while holding down the @key{ALT} -key. Such characters are given names that start with @kbd{Alt-} -(usually written @kbd{A-} for short). (Note that many terminals have a -key labeled @key{ALT} which is really a @key{META} key.) @xref{User -Input, Alt}. - -@item Argument -See `numeric argument.' - -@item @acronym{ASCII} character -An @acronym{ASCII} character is either an @acronym{ASCII} control character or an @acronym{ASCII} -printing character. @xref{User Input}. - -@item @acronym{ASCII} control character -An @acronym{ASCII} control character is the Control version of an upper-case -letter, or the Control version of one of the characters @samp{@@[\]^_?}. - -@item @acronym{ASCII} printing character -@acronym{ASCII} printing characters include letters, digits, space, and these -punctuation characters: @samp{!@@#$%^& *()_-+=|\~` @{@}[]:;"' <>,.?/}. - -@item Auto Fill Mode -Auto Fill mode is a minor mode in which text that you insert is -automatically broken into lines of a given maximum width. -@xref{Filling}. - -@item Auto Saving -Auto saving is the practice of saving the contents of an Emacs buffer in -a specially-named file, so that the information will not be lost if the -buffer is lost due to a system error or user error. @xref{Auto Save}. - -@item Autoloading -Emacs automatically loads Lisp libraries when a Lisp program requests a -function or a variable from those libraries. This is called -`autoloading'. @xref{Lisp Libraries}. - -@item Backtrace -A backtrace is a trace of a series of function calls showing how a -program arrived to a certain point. It is used mainly for finding and -correcting bugs (q.v.@:). Emacs can display a backtrace when it signals -an error or when you type @kbd{C-g} (see `quitting'). @xref{Checklist}. - -@item Backup File -A backup file records the contents that a file had before the current -editing session. Emacs makes backup files automatically to help you -track down or cancel changes you later regret making. @xref{Backup}. - -@item Balancing Parentheses -Emacs can balance parentheses (or other matching delimiters) either -manually or automatically. You do manual balancing with the commands -to move over parenthetical groupings (@pxref{Moving by Parens}). -Automatic balancing works by blinking or highlighting the delimiter -that matches the one you just inserted (@pxref{Matching,,Matching -Parens}). - -@item Balanced Expressions -A balanced expression is a syntactically recognizable expression, such -as a symbol, number, string constant, block, or parenthesized expression -in C. @xref{Expressions,Balanced Expressions}. - -@item Balloon Help -See `tooltips.' - -@item Base Buffer -A base buffer is a buffer whose text is shared by an indirect buffer -(q.v.@:). - -@item Bind -To bind a key sequence means to give it a binding (q.v.@:). -@xref{Rebinding}. - -@item Binding -A key sequence gets its meaning in Emacs by having a binding, which is a -command (q.v.@:), a Lisp function that is run when the user types that -sequence. @xref{Commands,Binding}. Customization often involves -rebinding a character to a different command function. The bindings of -all key sequences are recorded in the keymaps (q.v.@:). @xref{Keymaps}. - -@item Blank Lines -Blank lines are lines that contain only whitespace. Emacs has several -commands for operating on the blank lines in the buffer. - -@item Bookmark -Bookmarks are akin to registers (q.v.@:) in that they record positions -in buffers to which you can return later. Unlike registers, bookmarks -persist between Emacs sessions. - -@item Border -A border is a thin space along the edge of the frame, used just for -spacing, not for displaying anything. An Emacs frame has an ordinary -external border, outside of everything including the menu bar, plus an -internal border that surrounds the text windows and their scroll bars -and separates them from the menu bar and tool bar. You can customize -both borders with options and resources (@pxref{Borders X}). Borders -are not the same as fringes (q.v.@:). - -@item Buffer -The buffer is the basic editing unit; one buffer corresponds to one text -being edited. You can have several buffers, but at any time you are -editing only one, the `current buffer,' though several can be visible -when you are using multiple windows (q.v.@:). Most buffers are visiting -(q.v.@:) some file. @xref{Buffers}. - -@item Buffer Selection History -Emacs keeps a buffer selection history which records how recently each -Emacs buffer has been selected. This is used for choosing a buffer to -select. @xref{Buffers}. - -@item Bug -A bug is an incorrect or unreasonable behavior of a program, or -inaccurate or confusing documentation. Emacs developers treat bug -reports, both in Emacs code and its documentation, very seriously and -ask you to report any bugs you find. @xref{Bugs}. - -@item Button Down Event -A button down event is the kind of input event generated right away when -you press down on a mouse button. @xref{Mouse Buttons}. - -@item By Default -See `default.' - -@item Byte Compilation -See `compilation.' - -@item @kbd{C-} -@kbd{C-} in the name of a character is an abbreviation for Control. -@xref{User Input,C-}. - -@item @kbd{C-M-} -@kbd{C-M-} in the name of a character is an abbreviation for -Control-Meta. @xref{User Input,C-M-}. - -@item Case Conversion -Case conversion means changing text from upper case to lower case or -vice versa. @xref{Case}, for the commands for case conversion. - -@item Character -Characters form the contents of an Emacs buffer; see @ref{Text -Characters}. Also, key sequences (q.v.@:) are usually made up of -characters (though they may include other input events as well). -@xref{User Input}. - -@item Character Set -Emacs supports a number of character sets, each of which represents a -particular alphabet or script. @xref{International}. - -@item Character Terminal -See `text-only terminal.' - -@item Click Event -A click event is the kind of input event generated when you press a -mouse button and release it without moving the mouse. @xref{Mouse Buttons}. - -@item Clipboard -A clipboard is a buffer provided by the window system for transferring -text between applications. On the X Window system, the clipboard is -provided in addition to the primary selection (q.v.@:); on MS-Windows and Mac, -the clipboard is used @emph{instead} of the primary selection. -@xref{Clipboard}. - -@item Coding System -A coding system is an encoding for representing text characters in a -file or in a stream of information. Emacs has the ability to convert -text to or from a variety of coding systems when reading or writing it. -@xref{Coding Systems}. - -@item Command -A command is a Lisp function specially defined to be able to serve as a -key binding in Emacs. When you type a key sequence (q.v.@:), its -binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find -the command to run. @xref{Commands}. - -@item Command History -See `minibuffer history.' - -@item Command Name -A command name is the name of a Lisp symbol which is a command -(@pxref{Commands}). You can invoke any command by its name using -@kbd{M-x} (@pxref{M-x,M-x,Running Commands by Name}). - -@item Comment -A comment is text in a program which is intended only for humans reading -the program, and which is marked specially so that it will be ignored -when the program is loaded or compiled. Emacs offers special commands -for creating, aligning and killing comments. @xref{Comments}. - -@item Common Lisp -Common Lisp is a dialect of Lisp (q.v.@:) much larger and more powerful -than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL -package. @xref{Top, Common Lisp, Overview, cl, Common Lisp Extensions}. - -@item Compilation -Compilation is the process of creating an executable program from source -code. Emacs has commands for compiling files of Emacs Lisp code -(@pxref{Byte Compilation,,, elisp, the Emacs Lisp -Reference Manual}) and programs in C and other languages -(@pxref{Compilation}). - -@item Complete Key -A complete key is a key sequence which fully specifies one action to be -performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m} -are complete keys. Complete keys derive their meanings from being bound -(q.v.@:) to commands (q.v.@:). Thus, @kbd{X} is conventionally bound to -a command to insert @samp{X} in the buffer; @kbd{C-x m} is -conventionally bound to a command to begin composing a mail message. -@xref{Keys}. - -@item Completion -Completion is what Emacs does when it automatically fills out an -abbreviation for a name into the entire name. Completion is done for -minibuffer (q.v.@:) arguments when the set of possible valid inputs -is known; for example, on command names, buffer names, and -file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET} -is typed. @xref{Completion}.@refill - -@item Continuation Line -When a line of text is longer than the width of the window, it -takes up more than one screen line when displayed. We say that the -text line is continued, and all screen lines used for it after the -first are called continuation lines. @xref{Continuation Lines}. -A related Emacs feature is `filling' (q.v.@:). - -@item Control Character -A control character is a character that you type by holding down the -@key{CTRL} key. Some control characters also have their own keys, so -that you can type them without using @key{CTRL}. For example, -@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control -characters. @xref{User Input}. - -@item Copyleft -A copyleft is a notice giving the public legal permission to -redistribute and modify a program or other work of art, but requiring -modified versions to carry similar permission. Copyright is normally -used to keep users divided and helpless; with copyleft we turn that -around to empower users and encourage them to cooperate. - -The particular form of copyleft used by the GNU project is called the -GNU General Public License. @xref{Copying}. - -@item @key{CTRL} -The @key{CTRL} or ``control'' key is what you hold down -in order to enter a control character (q.v.). - -@item Current Buffer -The current buffer in Emacs is the Emacs buffer on which most editing -commands operate. You can select any Emacs buffer as the current one. -@xref{Buffers}. - -@item Current Line -The current line is the line that point is on (@pxref{Point}). - -@item Current Paragraph -The current paragraph is the paragraph that point is in. If point is -between two paragraphs, the current paragraph is the one that follows -point. @xref{Paragraphs}. - -@item Current Defun -The current defun is the defun (q.v.@:) that point is in. If point is -between defuns, the current defun is the one that follows point. -@xref{Defuns}. - -@item Cursor -The cursor is the rectangle on the screen which indicates the position -called point (q.v.@:) at which insertion and deletion takes place. -The cursor is on or under the character that follows point. Often -people speak of `the cursor' when, strictly speaking, they mean -`point.' @xref{Point,Cursor}. - -@item Customization -Customization is making minor changes in the way Emacs works. It is -often done by setting variables (@pxref{Variables}) or faces -(@pxref{Face Customization}), or by rebinding key sequences -(@pxref{Keymaps}). - -@cindex cut and paste -@item Cut and Paste -See `killing' and `yanking.' - -@item Default Argument -The default for an argument is the value that will be assumed if you -do not specify one. When the minibuffer is used to read an argument, -the default argument is used if you just type @key{RET}. -@xref{Minibuffer}. - -@item Default -A default is the value that is used for a certain purpose if and when -you do not specify a value to use. - -@item Default Directory -When you specify a file name that does not start with @samp{/} or @samp{~}, -it is interpreted relative to the current buffer's default directory. -(On MS-Windows and MS-DOS, file names which start with a drive letter -@samp{@var{x}:} are treated as absolute, not relative.) -@xref{Minibuffer File,Default Directory}. - -@item Defun -A defun is a major definition at the top level in a program. The name -`defun' comes from Lisp, where most such definitions use the construct -@code{defun}. @xref{Defuns}. - -@item @key{DEL} -@key{DEL} is a character that runs the command to delete one character -of text before the cursor. It is typically either the @key{DELETE} -key or the @key{BACKSPACE} key, whichever one is easy to type. -@xref{Erasing,DEL}. - -@item Deletion -Deletion means erasing text without copying it into the kill ring -(q.v.@:). The alternative is killing (q.v.@:). @xref{Killing,Deletion}. - -@item Deletion of Files -Deleting a file means erasing it from the file system. -@xref{Misc File Ops,Misc File Ops,Miscellaneous File Operations}. - -@item Deletion of Messages -Deleting a message means flagging it to be eliminated from your mail -file. Until you expunge (q.v.@:) the Rmail file, you can still undelete -the messages you have deleted. @xref{Rmail Deletion}. - -@item Deletion of Windows -Deleting a window means eliminating it from the screen. Other windows -expand to use up the space. The deleted window can never come back, -but no actual text is thereby lost. @xref{Windows}. - -@item Directory -File directories are named collections in the file system, within which -you can place individual files or subdirectories. @xref{Directories}. - -@item Dired -Dired is the Emacs facility that displays the contents of a file -directory and allows you to ``edit the directory,'' performing -operations on the files in the directory. @xref{Dired}. - -@item Disabled Command -A disabled command is one that you may not run without special -confirmation. The usual reason for disabling a command is that it is -confusing for beginning users. @xref{Disabling}. - -@item Down Event -Short for `button down event' (q.v.@:). - -@item Drag Event -A drag event is the kind of input event generated when you press a mouse -button, move the mouse, and then release the button. @xref{Mouse -Buttons}. - -@item Dribble File -A dribble file is a file into which Emacs writes all the characters that -you type on the keyboard. Dribble files are used to make a record -for debugging Emacs bugs. Emacs does not make a dribble file unless you -tell it to. @xref{Bugs}. - -@item Echo Area -The echo area is the bottom line of the screen, used for echoing the -arguments to commands, for asking questions, and showing brief messages -(including error messages). The messages are stored in the buffer -@samp{*Messages*} so you can review them later. @xref{Echo Area}. - -@item Echoing -Echoing is acknowledging the receipt of input events by displaying -them (in the echo area). Emacs never echoes single-character key -sequences; longer key sequences echo only if you pause while typing -them. - -@item Electric -We say that a character is electric if it is normally self-inserting -(q.v.@:), but the current major mode (q.v.@:) redefines it to do something -else as well. For example, some programming language major modes define -particular delimiter characters to reindent the line or insert one or -more newlines in addition to self-insertion. - -@item End Of Line -End of line is a character or a sequence of characters that indicate -the end of a text line. On GNU and Unix systems, this is a newline -(q.v.@:), but other systems have other conventions. @xref{Coding -Systems,end-of-line}. Emacs can recognize several end-of-line -conventions in files and convert between them. - -@item Environment Variable -An environment variable is one of a collection of variables stored by -the operating system, each one having a name and a value. Emacs can -access environment variables set by its parent shell, and it can set -variables in the environment it passes to programs it invokes. -@xref{Environment}. - -@item EOL -See `end of line.' - -@item Error -An error occurs when an Emacs command cannot execute in the current -circumstances. When an error occurs, execution of the command stops -(unless the command has been programmed to do otherwise) and Emacs -reports the error by displaying an error message (q.v.@:). Type-ahead -is discarded. Then Emacs is ready to read another editing command. - -@item Error Message -An error message is a single line of output displayed by Emacs when the -user asks for something impossible to do (such as, killing text -forward when point is at the end of the buffer). They appear in the -echo area, accompanied by a beep. - -@item @key{ESC} -@key{ESC} is a character used as a prefix for typing Meta characters on -keyboards lacking a @key{META} key. Unlike the @key{META} key (which, -like the @key{SHIFT} key, is held down while another character is -typed), you press the @key{ESC} key as you would press a letter key, and -it applies to the next character you type. - -@item Expression -See `balanced expression.' - -@item Expunging -Expunging an Rmail file or Dired buffer or a Gnus newsgroup buffer is an -operation that truly discards the messages or files you have previously -flagged for deletion. - -@item Face -A face is a style of displaying characters. It specifies attributes -such as font family and size, foreground and background colors, -underline and strike-through, background stipple, etc. Emacs provides -features to associate specific faces with portions of buffer text, in -order to display that text as specified by the face attributes. -@xref{Faces}. - -@item File Locking -Emacs uses file locking to notice when two different users -start to edit one file at the same time. @xref{Interlocking}. - -@item File Name -A file name is a name that refers to a file. File names may be relative -or absolute; the meaning of a relative file name depends on the current -directory, but an absolute file name refers to the same file regardless -of which directory is current. On GNU and Unix systems, an absolute -file name starts with a slash (the root directory) or with @samp{~/} or -@samp{~@var{user}/} (a home directory). On MS-Windows/MS-DOS, an -absolute file name can also start with a drive letter and a colon -@samp{@var{d}:}. - -Some people use the term ``pathname'' for file names, but we do not; -we use the word ``path'' only in the term ``search path'' (q.v.@:). - -@item File-Name Component -A file-name component names a file directly within a particular -directory. On GNU and Unix systems, a file name is a sequence of -file-name components, separated by slashes. For example, @file{foo/bar} -is a file name containing two components, @samp{foo} and @samp{bar}; it -refers to the file named @samp{bar} in the directory named @samp{foo} in -the current directory. MS-DOS/MS-Windows file names can also use -backslashes to separate components, as in @file{foo\bar}. - -@item Fill Prefix -The fill prefix is a string that should be expected at the beginning -of each line when filling is done. It is not regarded as part of the -text to be filled. @xref{Filling}. - -@item Filling -Filling text means shifting text between consecutive lines so that all -the lines are approximately the same length. @xref{Filling}. Some -other editors call this feature `line wrapping.' - -@item Font Lock -Font Lock is a mode that highlights parts of buffer text according to -its syntax. @xref{Font Lock}. - -@item Fontset -A fontset is a named collection of fonts. A fontset specification lists -character sets and which font to use to display each of them. Fontsets -make it easy to change several fonts at once by specifying the name of a -fontset, rather than changing each font separately. @xref{Fontsets}. - -@item Formatted Text -Formatted text is text that displays with formatting information while -you edit. Formatting information includes fonts, colors, and specified -margins. @xref{Formatted Text}. - -@item Formfeed Character -See `page.' - -@item Frame -A frame is a rectangular cluster of Emacs windows. Emacs starts out -with one frame, but you can create more. You can subdivide each frame -into Emacs windows (q.v.@:). When you are using a window system -(q.v.@:), all the frames can be visible at the same time. -@xref{Frames}. Some other editors use the term ``window'' for this, -but in Emacs a window means something else. - -@item Fringe -On a graphical display (q.v.@:), there's a narrow portion of the -frame (q.v.@:) between the text area and the window's border. Emacs -displays the fringe using a special face (q.v.@:) called -@code{fringe}. @xref{Faces,fringe}. - -@item FTP -FTP is an acronym for File Transfer Protocol. Emacs uses an FTP client -program to provide access to remote files (q.v.@:). - -@item Function Key -A function key is a key on the keyboard that sends input but does not -correspond to any character. @xref{Function Keys}. - -@item Global -Global means ``independent of the current environment; in effect -throughout Emacs.'' It is the opposite of local (q.v.@:). Particular -examples of the use of `global' appear below. - -@item Global Abbrev -A global definition of an abbrev (q.v.@:) is effective in all major -modes that do not have local (q.v.@:) definitions for the same abbrev. -@xref{Abbrevs}. - -@item Global Keymap -The global keymap (q.v.@:) contains key bindings that are in effect -except when overridden by local key bindings in a major mode's local -keymap (q.v.@:). @xref{Keymaps}. - -@item Global Mark Ring -The global mark ring records the series of buffers you have recently -set a mark (q.v.@:) in. In many cases you can use this to backtrack -through buffers you have been editing in, or in which you have found -tags (see `tags table'). @xref{Global Mark Ring}. - -@item Global Substitution -Global substitution means replacing each occurrence of one string by -another string throughout a large amount of text. @xref{Replace}. - -@item Global Variable -The global value of a variable (q.v.@:) takes effect in all buffers -that do not have their own local (q.v.@:) values for the variable. -@xref{Variables}. - -@item Graphic Character -Graphic characters are those assigned pictorial images rather than -just names. All the non-Meta (q.v.@:) characters except for the -Control (q.v.@:) characters are graphic characters. These include -letters, digits, punctuation, and spaces; they do not include -@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts -that character (in ordinary editing modes). @xref{Inserting Text}. - -@item Graphical Display -A graphical display is one that can display images and multiple fonts. -Usually it also has a window system (q.v.@:). - -@item Highlighting -Highlighting text means displaying it with a different foreground and/or -background color to make it stand out from the rest of the text in the -buffer. - -Emacs uses highlighting in several ways. When you mark a region with -the mouse, the region is always highlighted. Optionally Emacs can -also highlight the region whenever it is active (@pxref{Transient -Mark}). Incremental search also highlights matches (@pxref{Incremental -Search}). See also `font lock'. - -@item Hardcopy -Hardcopy means printed output. Emacs has commands for making printed -listings of text in Emacs buffers. @xref{Printing}. - -@item @key{HELP} -@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type -@key{HELP} at any time to ask what options you have, or to ask what any -command does. @xref{Help}. - -@item Help Echo -Help echo is a short message displayed in the echo area when the mouse -pointer is located on portions of display that require some -explanations. Emacs displays help echo for menu items, parts of the -mode line, tool-bar buttons, etc. On graphics displays, the messages -can be displayed as tooltips (q.v.@:). @xref{Tooltips}. - -@item Hook -A hook is a list of functions to be called on specific occasions, such -as saving a buffer in a file, major mode activation, etc. By -customizing the various hooks, you can modify Emacs's behavior without -changing any of its code. @xref{Hooks}. - -@item Hyper -Hyper is the name of a modifier bit which a keyboard input character may -have. To make a character Hyper, type it while holding down the -@key{HYPER} key. Such characters are given names that start with -@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input, -Hyper}. - -@item Iff -``Iff'' means ``if and only if.'' This terminology comes from -mathematics. Try to avoid using this term in documentation, since -many are unfamiliar with it and mistake it for a typo. - -@item Inbox -An inbox is a file in which mail is delivered by the operating system. -Rmail transfers mail from inboxes to Rmail files (q.v.@:) in which the -mail is then stored permanently or until explicitly deleted. -@xref{Rmail Inbox}. - -@item Incremental Search -Emacs provides an incremental search facility, whereby Emacs searches -for the string as you type it. @xref{Incremental Search}. - -@item Indentation -Indentation means blank space at the beginning of a line. Most -programming languages have conventions for using indentation to -illuminate the structure of the program, and Emacs has special -commands to adjust indentation. -@xref{Indentation}. - -@item Indirect Buffer -An indirect buffer is a buffer that shares the text of another buffer, -called its base buffer (q.v.@:). @xref{Indirect Buffers}. - -@item Info -Info is the hypertext format used by the GNU project for writing -documentation. - -@item Input Event -An input event represents, within Emacs, one action taken by the user on -the terminal. Input events include typing characters, typing function -keys, pressing or releasing mouse buttons, and switching between Emacs -frames. @xref{User Input}. - -@item Input Method -An input method is a system for entering non-@acronym{ASCII} text characters by -typing sequences of @acronym{ASCII} characters (q.v.@:). @xref{Input Methods}. - -@item Insertion -Insertion means copying text into the buffer, either from the keyboard -or from some other place in Emacs. - -@item Interlocking -Interlocking is a feature for warning when you start to alter a file -that someone else is already editing. -@xref{Interlocking,Interlocking,Simultaneous Editing}. - -@item Isearch -See `incremental search.' - -@item Justification -Justification means adding extra spaces within lines of text to make -them extend exactly to a specified width. -@xref{Format Justification}. - -@item Keybinding -See `binding.' - -@item Keyboard Macro -Keyboard macros are a way of defining new Emacs commands from -sequences of existing ones, with no need to write a Lisp program. -@xref{Keyboard Macros}. - -@cindex keyboard shortcuts -@item Keyboard Shortcut -A keyboard shortcut is a key sequence (q.v.@:) which invokes a -command. What some programs call ``assigning a keyboard shortcut,'' -Emacs calls ``binding a key sequence.'' See `binding.' - -@item Key Sequence -A key sequence (key, for short) is a sequence of input events (q.v.@:) -that are meaningful as a single unit. If the key sequence is enough to -specify one action, it is a complete key (q.v.@:); if it is not enough, -it is a prefix key (q.v.@:). @xref{Keys}. - -@item Keymap -The keymap is the data structure that records the bindings (q.v.@:) of -key sequences to the commands that they run. For example, the global -keymap binds the character @kbd{C-n} to the command function -@code{next-line}. @xref{Keymaps}. - -@item Keyboard Translation Table -The keyboard translation table is an array that translates the character -codes that come from the terminal into the character codes that make up -key sequences. - -@item Kill Ring -The kill ring is where all text you have killed recently is saved. -You can reinsert any of the killed text still in the ring; this is -called yanking (q.v.@:). @xref{Yanking}. - -@item Killing -Killing means erasing text and saving it on the kill ring so it can be -yanked (q.v.@:) later. Some other systems call this ``cutting.'' -Most Emacs commands that erase text perform killing, as opposed to -deletion (q.v.@:). @xref{Killing}. - -@item Killing a Job -Killing a job (such as, an invocation of Emacs) means making it cease -to exist. Any data within it, if not saved in a file, is lost. -@xref{Exiting}. - -@item Language Environment -Your choice of language environment specifies defaults for the input -method (q.v.@:) and coding system (q.v.@:). @xref{Language -Environments}. These defaults are relevant if you edit non-@acronym{ASCII} text -(@pxref{International}). - -@item Line Wrapping -See `filling.' - -@item Lisp -Lisp is a programming language. Most of Emacs is written in a dialect -of Lisp, called Emacs Lisp, that is extended with special features which -make it especially suitable for text editing tasks. - -@item List -A list is, approximately, a text string beginning with an open -parenthesis and ending with the matching close parenthesis. In C mode -and other non-Lisp modes, groupings surrounded by other kinds of matched -delimiters appropriate to the language, such as braces, are also -considered lists. Emacs has special commands for many operations on -lists. @xref{Moving by Parens}. - -@item Local -Local means ``in effect only in a particular context''; the relevant -kind of context is a particular function execution, a particular -buffer, or a particular major mode. It is the opposite of `global' -(q.v.@:). Specific uses of `local' in Emacs terminology appear below. - -@item Local Abbrev -A local abbrev definition is effective only if a particular major mode -is selected. In that major mode, it overrides any global definition -for the same abbrev. @xref{Abbrevs}. - -@item Local Keymap -A local keymap is used in a particular major mode; the key bindings -(q.v.@:) in the current local keymap override global bindings of the -same key sequences. @xref{Keymaps}. - -@item Local Variable -A local value of a variable (q.v.@:) applies to only one buffer. -@xref{Locals}. - -@item @kbd{M-} -@kbd{M-} in the name of a character is an abbreviation for @key{META}, -one of the modifier keys that can accompany any character. -@xref{User Input,M-}. - -@item @kbd{M-C-} -@kbd{M-C-} in the name of a character is an abbreviation for -Control-Meta; it means the same thing as @kbd{C-M-}. If your -terminal lacks a real @key{META} key, you type a Control-Meta character by -typing @key{ESC} and then typing the corresponding Control character. -@xref{User Input,C-M-}. - -@item @kbd{M-x} -@kbd{M-x} is the key sequence which is used to call an Emacs command by -name. This is how you run commands that are not bound to key sequences. -@xref{M-x,M-x,Running Commands by Name}. - -@item Mail -Mail means messages sent from one user to another through the computer -system, to be read at the recipient's convenience. Emacs has commands for -composing and sending mail, and for reading and editing the mail you have -received. @xref{Sending Mail}. @xref{Rmail}, for how to read mail. - -@item Mail Composition Method -A mail composition method is a program runnable within Emacs for editing -and sending a mail message. Emacs lets you select from several -alternative mail composition methods. @xref{Mail Methods}. - -@item Major Mode -The Emacs major modes are a mutually exclusive set of options, each of -which configures Emacs for editing a certain sort of text. Ideally, -each programming language has its own major mode. @xref{Major Modes}. - -@item Margin -The space between the usable part of a window (including the -fringe) and the window edge. - -@item Mark -The mark points to a position in the text. It specifies one end of the -region (q.v.@:), point being the other end. Many commands operate on -all the text from point to the mark. Each buffer has its own mark. -@xref{Mark}. - -@item Mark Ring -The mark ring is used to hold several recent previous locations of the -mark, just in case you want to move back to them. Each buffer has its -own mark ring; in addition, there is a single global mark ring (q.v.@:). -@xref{Mark Ring}. - -@item Menu Bar -The menu bar is the line at the top of an Emacs frame. It contains -words you can click on with the mouse to bring up menus, or you can use -a keyboard interface to navigate it. @xref{Menu Bars}. - -@item Message -See `mail.' - -@item Meta -Meta is the name of a modifier bit which you can use in a command -character. To enter a meta character, you hold down the @key{META} -key while typing the character. We refer to such characters with -names that start with @kbd{Meta-} (usually written @kbd{M-} for -short). For example, @kbd{M-<} is typed by holding down @key{META} -and at the same time typing @kbd{<} (which itself is done, on most -terminals, by holding down @key{SHIFT} and typing @kbd{,}). -@xref{User Input,Meta}. - -On some terminals, the @key{META} key is actually labeled @key{ALT} -or @key{EDIT}. - -@item Meta Character -A Meta character is one whose character code includes the Meta bit. - -@item Minibuffer -The minibuffer is the window that appears when necessary inside the -echo area (q.v.@:), used for reading arguments to commands. -@xref{Minibuffer}. - -@item Minibuffer History -The minibuffer history records the text you have specified in the past -for minibuffer arguments, so you can conveniently use the same text -again. @xref{Minibuffer History}. - -@item Minor Mode -A minor mode is an optional feature of Emacs which can be switched on -or off independently of all other features. Each minor mode has a -command to turn it on or off. @xref{Minor Modes}. - -@item Minor Mode Keymap -A minor mode keymap is a keymap that belongs to a minor mode and is -active when that mode is enabled. Minor mode keymaps take precedence -over the buffer's local keymap, just as the local keymap takes -precedence over the global keymap. @xref{Keymaps}. - -@item Mode Line -The mode line is the line at the bottom of each window (q.v.@:), giving -status information on the buffer displayed in that window. @xref{Mode -Line}. - -@item Modified Buffer -A buffer (q.v.@:) is modified if its text has been changed since the -last time the buffer was saved (or since when it was created, if it -has never been saved). @xref{Saving}. - -@item Moving Text -Moving text means erasing it from one place and inserting it in -another. The usual way to move text is by killing (q.v.@:) it and then -yanking (q.v.@:) it. @xref{Killing}. - -@item MULE -MULE refers to the Emacs features for editing multilingual non-@acronym{ASCII} text -using multibyte characters (q.v.@:). @xref{International}. - -@item Multibyte Character -A multibyte character is a character that takes up several bytes in a -buffer. Emacs uses multibyte characters to represent non-@acronym{ASCII} text, -since the number of non-@acronym{ASCII} characters is much more than 256. -@xref{International Chars, International Characters}. - -@item Named Mark -A named mark is a register (q.v.@:) in its role of recording a -location in text so that you can move point to that location. -@xref{Registers}. - -@item Narrowing -Narrowing means creating a restriction (q.v.@:) that limits editing in -the current buffer to only a part of the text in the buffer. Text -outside that part is inaccessible for editing until the boundaries are -widened again, but it is still there, and saving the file saves it -all. @xref{Narrowing}. - -@item Newline -Control-J characters in the buffer terminate lines of text and are -therefore also called newlines. @xref{Text Characters,Newline}. - -@cindex nil -@cindex t -@item @code{nil} -@code{nil} is a value usually interpreted as a logical ``false.'' Its -opposite is @code{t}, interpreted as ``true.'' - -@item Numeric Argument -A numeric argument is a number, specified before a command, to change -the effect of the command. Often the numeric argument serves as a -repeat count. @xref{Arguments}. - -@item Overwrite Mode -Overwrite mode is a minor mode. When it is enabled, ordinary text -characters replace the existing text after point rather than pushing -it to the right. @xref{Minor Modes}. - -@item Page -A page is a unit of text, delimited by formfeed characters (@acronym{ASCII} -control-L, code 014) coming at the beginning of a line. Some Emacs -commands are provided for moving over and operating on pages. -@xref{Pages}. - -@item Paragraph -Paragraphs are the medium-size unit of human-language text. There are -special Emacs commands for moving over and operating on paragraphs. -@xref{Paragraphs}. - -@item Parsing -We say that certain Emacs commands parse words or expressions in the -text being edited. Really, all they know how to do is find the other -end of a word or expression. @xref{Syntax}. - -@item Point -Point is the place in the buffer at which insertion and deletion -occur. Point is considered to be between two characters, not at one -character. The terminal's cursor (q.v.@:) indicates the location of -point. @xref{Point}. - -@item Prefix Argument -See `numeric argument.' - -@item Prefix Key -A prefix key is a key sequence (q.v.@:) whose sole function is to -introduce a set of longer key sequences. @kbd{C-x} is an example of -prefix key; any two-character sequence starting with @kbd{C-x} is -therefore a legitimate key sequence. @xref{Keys}. - -@item Primary Rmail File -Your primary Rmail file is the file named @samp{RMAIL} in your home -directory. That's where Rmail stores your incoming mail, unless you -specify a different file name. @xref{Rmail}. - -@item Primary Selection -The primary selection is one particular X selection (q.v.@:); it is the -selection that most X applications use for transferring text to and from -other applications. - -The Emacs kill commands set the primary selection and the yank command -uses the primary selection when appropriate. @xref{Killing}. - -@item Prompt -A prompt is text used to ask the user for input. Displaying a prompt -is called prompting. Emacs prompts always appear in the echo area -(q.v.@:). One kind of prompting happens when the minibuffer is used to -read an argument (@pxref{Minibuffer}); the echoing which happens when -you pause in the middle of typing a multi-character key sequence is also -a kind of prompting (@pxref{Echo Area}). - -@item Query-Replace -Query-replace is an interactive string replacement feature provided by -Emacs. @xref{Query Replace}. - -@item Quitting -Quitting means canceling a partially typed command or a running -command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. - -@item Quoting -Quoting means depriving a character of its usual special significance. -The most common kind of quoting in Emacs is with @kbd{C-q}. What -constitutes special significance depends on the context and on -convention. For example, an ``ordinary'' character as an Emacs command -inserts itself; so in this context, a special character is any character -that does not normally insert itself (such as @key{DEL}, for example), -and quoting it makes it insert itself as if it were not special. Not -all contexts allow quoting. @xref{Inserting Text,Quoting}. - -@item Quoting File Names -Quoting a file name turns off the special significance of constructs -such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}. - -@item Read-Only Buffer -A read-only buffer is one whose text you are not allowed to change. -Normally Emacs makes buffers read-only when they contain text which -has a special significance to Emacs; for example, Dired buffers. -Visiting a file that is write-protected also makes a read-only buffer. -@xref{Buffers}. - -@item Rectangle -A rectangle consists of the text in a given range of columns on a given -range of lines. Normally you specify a rectangle by putting point at -one corner and putting the mark at the diagonally opposite corner. -@xref{Rectangles}. - -@item Recursive Editing Level -A recursive editing level is a state in which part of the execution of -a command involves asking you to edit some text. This text may -or may not be the same as the text to which the command was applied. -The mode line indicates recursive editing levels with square brackets -(@samp{[} and @samp{]}). @xref{Recursive Edit}. - -@item Redisplay -Redisplay is the process of correcting the image on the screen to -correspond to changes that have been made in the text being edited. -@xref{Screen,Redisplay}. - -@item Regexp -See `regular expression.' - -@item Region -The region is the text between point (q.v.@:) and the mark (q.v.@:). -Many commands operate on the text of the region. @xref{Mark,Region}. - -@item Register -Registers are named slots in which text or buffer positions or -rectangles can be saved for later use. @xref{Registers}. A related -Emacs feature is `bookmarks' (q.v.@:). - -@item Regular Expression -A regular expression is a pattern that can match various text strings; -for example, @samp{a[0-9]+} matches @samp{a} followed by one or more -digits. @xref{Regexps}. - -@item Remote File -A remote file is a file that is stored on a system other than your own. -Emacs can access files on other computers provided that they are -connected to the same network as your machine, and (obviously) that -you have a supported method to gain access to those files. -@xref{Remote Files}. - -@item Repeat Count -See `numeric argument.' - -@item Replacement -See `global substitution.' - -@item Restriction -A buffer's restriction is the amount of text, at the beginning or the -end of the buffer, that is temporarily inaccessible. Giving a buffer a -nonzero amount of restriction is called narrowing (q.v.@:); removing -a restriction is called widening (q.v.@:). @xref{Narrowing}. - -@item @key{RET} -@key{RET} is a character that in Emacs runs the command to insert a -newline into the text. It is also used to terminate most arguments -read in the minibuffer (q.v.@:). @xref{User Input,Return}. - -@item Reverting -Reverting means returning to the original state. Emacs lets you -revert a buffer by re-reading its file from disk. @xref{Reverting}. - -@item Rmail File -An Rmail file is a file containing text in a special format used by -Rmail for storing mail. @xref{Rmail}. - -@item Saving -Saving a buffer means copying its text into the file that was visited -(q.v.@:) in that buffer. This is the way text in files actually gets -changed by your Emacs editing. @xref{Saving}. - -@item Scroll Bar -A scroll bar is a tall thin hollow box that appears at the side of a -window. You can use mouse commands in the scroll bar to scroll the -window. The scroll bar feature is supported only under windowing -systems. @xref{Scroll Bars}. - -@item Scrolling -Scrolling means shifting the text in the Emacs window so as to see a -different part of the buffer. @xref{Scrolling}. - -@item Searching -Searching means moving point to the next occurrence of a specified -string or the next match for a specified regular expression. -@xref{Search}. - -@item Search Path -A search path is a list of directory names, to be used for searching for -files for certain purposes. For example, the variable @code{load-path} -holds a search path for finding Lisp library files. @xref{Lisp Libraries}. - -@item Secondary Selection -The secondary selection is one particular X selection; some X -applications can use it for transferring text to and from other -applications. Emacs has special mouse commands for transferring text -using the secondary selection. @xref{Secondary Selection}. - -@item Selected Frame -The selected frame is the one your input currently operates on. -@xref{Frames}. - -@item Selected Window -The selected frame is the one your input currently operates on. -@xref{Basic Window}. - -@item Selecting a Buffer -Selecting a buffer means making it the current (q.v.@:) buffer. -@xref{Select Buffer}. - -@item Selection -Windowing systems allow an application program to specify -selections whose values are text. A program can also read the -selections that other programs have set up. This is the principal way -of transferring text between window applications. Emacs has commands to -work with the primary (q.v.@:) selection and the secondary (q.v.@:) -selection, and also with the clipboard (q.v.@:). - -@item Self-Documentation -Self-documentation is the feature of Emacs which can tell you what any -command does, or give you a list of all commands related to a topic -you specify. You ask for self-documentation with the help character, -@kbd{C-h}. @xref{Help}. - -@item Self-Inserting Character -A character is self-inserting if typing that character inserts that -character in the buffer. Ordinary printing and whitespace characters -are self-inserting in Emacs, except in certain special major modes. - -@item Sentences -Emacs has commands for moving by or killing by sentences. -@xref{Sentences}. - -@item Sexp -A sexp (short for ``s-expression'') is the basic syntactic unit of -Lisp in its textual form: either a list, or Lisp atom. Sexps are also -the balanced expressions (q.v.@:) of the Lisp language; this is why -the commands for editing balanced expressions have `sexp' in their -name. @xref{Expressions,Sexps}. - -@item Simultaneous Editing -Simultaneous editing means two users modifying the same file at once. -Simultaneous editing, if not detected, can cause one user to lose his -or her work. Emacs detects all cases of simultaneous editing, and -warns one of the users to investigate. -@xref{Interlocking,Interlocking,Simultaneous Editing}. - -@item @key{SPC} -@key{SPC} is the space character, which you enter by pressing the -space bar. - -@item Speedbar -The speedbar is a special tall frame that provides fast access to Emacs -buffers, functions within those buffers, Info nodes, and other -interesting parts of text within Emacs. @xref{Speedbar}. - -@item Spell Checking -Spell checking means checking correctness of the written form of each -one of the words in a text. Emacs uses the Ispell spelling-checker -program to check the spelling of parts of a buffer via a convenient user -interface. @xref{Spelling}. - -@item String -A string is a kind of Lisp data object which contains a sequence of -characters. Many Emacs variables are intended to have strings as -values. The Lisp syntax for a string consists of the characters in the -string with a @samp{"} before and another @samp{"} after. A @samp{"} -that is part of the string must be written as @samp{\"} and a @samp{\} -that is part of the string must be written as @samp{\\}. All other -characters, including newline, can be included just by writing them -inside the string; however, backslash sequences as in C, such as -@samp{\n} for newline or @samp{\241} using an octal character code, are -allowed as well. - -@item String Substitution -See `global substitution'. - -@item Syntax Highlighting -See `font lock.' - -@item Syntax Table -The syntax table tells Emacs which characters are part of a word, -which characters balance each other like parentheses, etc. -@xref{Syntax}. - -@item Super -Super is the name of a modifier bit which a keyboard input character may -have. To make a character Super, type it while holding down the -@key{SUPER} key. Such characters are given names that start with -@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input, -Super}. - -@item Suspending -Suspending Emacs means stopping it temporarily and returning control -to its parent process, which is usually a shell. Unlike killing a job -(q.v.@:), you can later resume the suspended Emacs job without losing -your buffers, unsaved edits, undo history, etc. @xref{Exiting}. - -@item @key{TAB} -@key{TAB} is the tab character. In Emacs it is typically used for -indentation or completion. - -@item Tags Table -A tags table is a file that serves as an index to the function -definitions in one or more other files. @xref{Tags}. - -@item Termscript File -A termscript file contains a record of all characters sent by Emacs to -the terminal. It is used for tracking down bugs in Emacs redisplay. -Emacs does not make a termscript file unless you tell it to. -@xref{Bugs}. - -@item Text -`Text' has two meanings (@pxref{Text}): - -@itemize @bullet -@item -Data consisting of a sequence of characters, as opposed to binary -numbers, executable programs, and the like. The basic contents of an -Emacs buffer (aside from the text properties, q.v.@:) are always text -in this sense. -@item -Data consisting of written human language, as opposed to programs, -or following the stylistic conventions of human language. -@end itemize - -@item Text-only Terminal -A text-only terminal is a display that is limited to displaying text in -character units. Such a terminal cannot control individual pixels it -displays. Emacs supports a subset of display features on text-only -terminals. - -@item Text Properties -Text properties are annotations recorded for particular characters in -the buffer. Images in the buffer are recorded as text properties; -they also specify formatting information. @xref{Editing Format Info}. - -@item Tool Bar -The tool bar is a line (sometimes multiple lines) of icons at the top -of an Emacs frame. Clicking on one of these icons executes a command. -You can think of this as a graphical relative of the menu bar (q.v.@:). -@xref{Tool Bars}. - -@item Tooltips -Tooltips are small windows displaying a help echo (q.v.@:) text that -explains parts of the display, lists useful options available via mouse -clicks, etc. @xref{Tooltips}. - -@item Top Level -Top level is the normal state of Emacs, in which you are editing the -text of the file you have visited. You are at top level whenever you -are not in a recursive editing level (q.v.@:) or the minibuffer -(q.v.@:), and not in the middle of a command. You can get back to top -level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}. - -@item Transposition -Transposing two units of text means putting each one into the place -formerly occupied by the other. There are Emacs commands to transpose -two adjacent characters, words, balanced expressions (q.v.@:) or lines -(@pxref{Transpose}). - -@item Truncation -Truncating text lines in the display means leaving out any text on a -line that does not fit within the right margin of the window -displaying it. See also `continuation line.' -@xref{Continuation Lines,Truncation}. - -@item TTY -See `text-only terminal.' - -@item Undoing -Undoing means making your previous editing go in reverse, bringing -back the text that existed earlier in the editing session. -@xref{Undo}. - -@item User Option -A user option is a face (q.v.@:) or a variable (q.v.@:) that exists so -that you can customize Emacs by setting it to a new value. -@xref{Easy Customization}. - -@item Variable -A variable is an object in Lisp that can store an arbitrary value. -Emacs uses some variables for internal purposes, and has others (known -as `user options' (q.v.@:)) just so that you can set their values to -control the behavior of Emacs. The variables used in Emacs that you -are likely to be interested in are listed in the Variables Index in -this manual (@pxref{Variable Index}). @xref{Variables}, for -information on variables. - -@item Version Control -Version control systems keep track of multiple versions of a source file. -They provide a more powerful alternative to keeping backup files (q.v.@:). -@xref{Version Control}. - -@item Visiting -Visiting a file means loading its contents into a buffer (q.v.@:) -where they can be edited. @xref{Visiting}. - -@item Whitespace -Whitespace is any run of consecutive formatting characters (space, -tab, newline, and backspace). - -@item Widening -Widening is removing any restriction (q.v.@:) on the current buffer; -it is the opposite of narrowing (q.v.@:). @xref{Narrowing}. - -@item Window -Emacs divides a frame (q.v.@:) into one or more windows, each of which -can display the contents of one buffer (q.v.@:) at any time. -@xref{Screen}, for basic information on how Emacs uses the screen. -@xref{Windows}, for commands to control the use of windows. Some -other editors use the term ``window'' for what we call a `frame' -(q.v.@:) in Emacs. - -@item Window System -A window system is software that operates on a graphical display -(q.v.@:), to subdivide the screen so that multiple applications can -have their] own windows at the same time. All modern operating systems -include a window system. - -@item Word Abbrev -See `abbrev.' - -@item Word Search -Word search is searching for a sequence of words, considering the -punctuation between them as insignificant. @xref{Word Search}. - -@item WYSIWYG -WYSIWYG stands for ``What you see is what you get.'' Emacs generally -provides WYSIWYG editing for files of characters; in Enriched mode -(@pxref{Formatted Text}), it provides WYSIWYG editing for files that -include text formatting information. - -@item Yanking -Yanking means reinserting text previously killed. It can be used to -undo a mistaken kill, or for copying or moving text. Some other -systems call this ``pasting.'' @xref{Yanking}. -@end table - -@ignore - arch-tag: 0dd53ce1-5f09-4ac2-b13b-cf22b0f28d23 -@end ignore diff --git a/man/gnu.texi b/man/gnu.texi deleted file mode 100644 index 1cf85f41c3c..00000000000 --- a/man/gnu.texi +++ /dev/null @@ -1,567 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1995, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@ifclear justgnu -@node Manifesto,, Microsoft Windows, Top -@unnumbered The GNU Manifesto -@end ifclear -@ifset justgnu -Copyright @copyright{} 1985, 1993, 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. - -@node Top -@top The GNU Manifesto -@end ifset - -@quotation -The GNU Manifesto which appears below was written by Richard Stallman at -the beginning of the GNU project, to ask for participation and support. -For the first few years, it was updated in minor ways to account for -developments, but now it seems best to leave it unchanged as most people -have seen it. - -Since that time, we have learned about certain common misunderstandings -that different wording could help avoid. Footnotes added in 1993 help -clarify these points. - -For up-to-date information about available GNU software, please see -our web site, @uref{http://www.gnu.org}. For software tasks and other -ways to contribute, see @uref{http://www.gnu.org/help}. -@end quotation - -@unnumberedsec What's GNU? Gnu's Not Unix! - -GNU, which stands for Gnu's Not Unix, is the name for the complete -Unix-compatible software system which I am writing so that I can give it -away free to everyone who can use it.@footnote{The wording here was -careless. The intention was that nobody would have to pay for -@emph{permission} to use the GNU system. But the words don't make this -clear, and people often interpret them as saying that copies of GNU -should always be distributed at little or no charge. That was never the -intent; later on, the manifesto mentions the possibility of companies -providing the service of distribution for a profit. Subsequently I have -learned to distinguish carefully between ``free'' in the sense of -freedom and ``free'' in the sense of price. Free software is software -that users have the freedom to distribute and change. Some users may -obtain copies at no charge, while others pay to obtain copies---and if -the funds help support improving the software, so much the better. The -important thing is that everyone who has a copy has the freedom to -cooperate with others in using it.} Several other volunteers are helping -me. Contributions of time, money, programs and equipment are greatly -needed. - -So far we have an Emacs text editor with Lisp for writing editor commands, -a source level debugger, a yacc-compatible parser generator, a linker, and -around 35 utilities. A shell (command interpreter) is nearly completed. A -new portable optimizing C compiler has compiled itself and may be released -this year. An initial kernel exists but many more features are needed to -emulate Unix. When the kernel and compiler are finished, it will be -possible to distribute a GNU system suitable for program development. We -will use @TeX{} as our text formatter, but an nroff is being worked on. We -will use the free, portable X window system as well. After this we will -add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of -other things, plus on-line documentation. We hope to supply, eventually, -everything useful that normally comes with a Unix system, and more. - -GNU will be able to run Unix programs, but will not be identical to Unix. -We will make all improvements that are convenient, based on our experience -with other operating systems. In particular, we plan to have longer -file names, file version numbers, a crashproof file system, file name -completion perhaps, terminal-independent display support, and perhaps -eventually a Lisp-based window system through which several Lisp programs -and ordinary Unix programs can share a screen. Both C and Lisp will be -available as system programming languages. We will try to support UUCP, -MIT Chaosnet, and Internet protocols for communication. - -GNU is aimed initially at machines in the 68000/16000 class with virtual -memory, because they are the easiest machines to make it run on. The extra -effort to make it run on smaller machines will be left to someone who wants -to use it on them. - -To avoid horrible confusion, please pronounce the `G' in the word `GNU' -when it is the name of this project. - -@unnumberedsec Why I Must Write GNU - -I consider that the golden rule requires that if I like a program I must -share it with other people who like it. Software sellers want to divide -the users and conquer them, making each user agree not to share with -others. I refuse to break solidarity with other users in this way. I -cannot in good conscience sign a nondisclosure agreement or a software -license agreement. For years I worked within the Artificial Intelligence -Lab to resist such tendencies and other inhospitalities, but eventually -they had gone too far: I could not remain in an institution where such -things are done for me against my will. - -So that I can continue to use computers without dishonor, I have decided to -put together a sufficient body of free software so that I will be able to -get along without any software that is not free. I have resigned from the -AI lab to deny MIT any legal excuse to prevent me from giving GNU away. - -@unnumberedsec Why GNU Will Be Compatible with Unix - -Unix is not my ideal system, but it is not too bad. The essential features -of Unix seem to be good ones, and I think I can fill in what Unix lacks -without spoiling them. And a system compatible with Unix would be -convenient for many other people to adopt. - -@unnumberedsec How GNU Will Be Available - -GNU is not in the public domain. Everyone will be permitted to modify and -redistribute GNU, but no distributor will be allowed to restrict its -further redistribution. That is to say, proprietary modifications will not -be allowed. I want to make sure that all versions of GNU remain free. - -@unnumberedsec Why Many Other Programmers Want to Help - -I have found many other programmers who are excited about GNU and want to -help. - -Many programmers are unhappy about the commercialization of system -software. It may enable them to make more money, but it requires them to -feel in conflict with other programmers in general rather than feel as -comrades. The fundamental act of friendship among programmers is the -sharing of programs; marketing arrangements now typically used essentially -forbid programmers to treat others as friends. The purchaser of software -must choose between friendship and obeying the law. Naturally, many decide -that friendship is more important. But those who believe in law often do -not feel at ease with either choice. They become cynical and think that -programming is just a way of making money. - -By working on and using GNU rather than proprietary programs, we can be -hospitable to everyone and obey the law. In addition, GNU serves as an -example to inspire and a banner to rally others to join us in sharing. -This can give us a feeling of harmony which is impossible if we use -software that is not free. For about half the programmers I talk to, this -is an important happiness that money cannot replace. - -@unnumberedsec How You Can Contribute - -I am asking computer manufacturers for donations of machines and money. -I'm asking individuals for donations of programs and work. - -One consequence you can expect if you donate machines is that GNU will run -on them at an early date. The machines should be complete, ready to use -systems, approved for use in a residential area, and not in need of -sophisticated cooling or power. - -I have found very many programmers eager to contribute part-time work for -GNU. For most projects, such part-time distributed work would be very hard -to coordinate; the independently-written parts would not work together. -But for the particular task of replacing Unix, this problem is absent. A -complete Unix system contains hundreds of utility programs, each of which -is documented separately. Most interface specifications are fixed by Unix -compatibility. If each contributor can write a compatible replacement for -a single Unix utility, and make it work properly in place of the original -on a Unix system, then these utilities will work right when put together. -Even allowing for Murphy to create a few unexpected problems, assembling -these components will be a feasible task. (The kernel will require closer -communication and will be worked on by a small, tight group.) - -If I get donations of money, I may be able to hire a few people full or -part time. The salary won't be high by programmers' standards, but I'm -looking for people for whom building community spirit is as important as -making money. I view this as a way of enabling dedicated people to devote -their full energies to working on GNU by sparing them the need to make a -living in another way. - -@unnumberedsec Why All Computer Users Will Benefit - -Once GNU is written, everyone will be able to obtain good system -software free, just like air.@footnote{This is another place I failed to -distinguish carefully between the two different meanings of ``free.'' -The statement as it stands is not false---you can get copies of GNU -software at no charge, from your friends or over the net. But it does -suggest the wrong idea.} - -This means much more than just saving everyone the price of a Unix license. -It means that much wasteful duplication of system programming effort will -be avoided. This effort can go instead into advancing the state of the -art. - -Complete system sources will be available to everyone. As a result, a user -who needs changes in the system will always be free to make them himself, -or hire any available programmer or company to make them for him. Users -will no longer be at the mercy of one programmer or company which owns the -sources and is in sole position to make changes. - -Schools will be able to provide a much more educational environment by -encouraging all students to study and improve the system code. Harvard's -computer lab used to have the policy that no program could be installed on -the system if its sources were not on public display, and upheld it by -actually refusing to install certain programs. I was very much inspired by -this. - -Finally, the overhead of considering who owns the system software and what -one is or is not entitled to do with it will be lifted. - -Arrangements to make people pay for using a program, including licensing of -copies, always incur a tremendous cost to society through the cumbersome -mechanisms necessary to figure out how much (that is, which programs) a -person must pay for. And only a police state can force everyone to obey -them. Consider a space station where air must be manufactured at great -cost: charging each breather per liter of air may be fair, but wearing the -metered gas mask all day and all night is intolerable even if everyone can -afford to pay the air bill. And the TV cameras everywhere to see if you -ever take the mask off are outrageous. It's better to support the air -plant with a head tax and chuck the masks. - -Copying all or parts of a program is as natural to a programmer as -breathing, and as productive. It ought to be as free. - -@unnumberedsec Some Easily Rebutted Objections to GNU's Goals - -@quotation -``Nobody will use it if it is free, because that means they can't rely -on any support.'' - -``You have to charge for the program to pay for providing the -support.'' -@end quotation - -If people would rather pay for GNU plus service than get GNU free without -service, a company to provide just service to people who have obtained GNU -free ought to be profitable.@footnote{Several such companies now exist.} - -We must distinguish between support in the form of real programming work -and mere handholding. The former is something one cannot rely on from a -software vendor. If your problem is not shared by enough people, the -vendor will tell you to get lost. - -If your business needs to be able to rely on support, the only way is to -have all the necessary sources and tools. Then you can hire any available -person to fix your problem; you are not at the mercy of any individual. -With Unix, the price of sources puts this out of consideration for most -businesses. With GNU this will be easy. It is still possible for there to -be no available competent person, but this problem cannot be blamed on -distribution arrangements. GNU does not eliminate all the world's problems, -only some of them. - -Meanwhile, the users who know nothing about computers need handholding: -doing things for them which they could easily do themselves but don't know -how. - -Such services could be provided by companies that sell just hand-holding -and repair service. If it is true that users would rather spend money and -get a product with service, they will also be willing to buy the service -having got the product free. The service companies will compete in quality -and price; users will not be tied to any particular one. Meanwhile, those -of us who don't need the service should be able to use the program without -paying for the service. - -@quotation -``You cannot reach many people without advertising, -and you must charge for the program to support that.'' - -``It's no use advertising a program people can get free.'' -@end quotation - -There are various forms of free or very cheap publicity that can be used to -inform numbers of computer users about something like GNU. But it may be -true that one can reach more microcomputer users with advertising. If this -is really so, a business which advertises the service of copying and -mailing GNU for a fee ought to be successful enough to pay for its -advertising and more. This way, only the users who benefit from the -advertising pay for it. - -On the other hand, if many people get GNU from their friends, and such -companies don't succeed, this will show that advertising was not really -necessary to spread GNU. Why is it that free market advocates don't -want to let the free market decide this?@footnote{The Free Software -Foundation raises most of its funds from a distribution service, -although it is a charity rather than a company. If @emph{no one} -chooses to obtain copies by ordering from the FSF, it will be unable -to do its work. But this does not mean that proprietary restrictions -are justified to force every user to pay. If a small fraction of all -the users order copies from the FSF, that is sufficient to keep the FSF -afloat. So we ask users to choose to support us in this way. Have you -done your part?} - -@quotation -``My company needs a proprietary operating system -to get a competitive edge.'' -@end quotation - -GNU will remove operating system software from the realm of competition. -You will not be able to get an edge in this area, but neither will your -competitors be able to get an edge over you. You and they will compete in -other areas, while benefiting mutually in this one. If your business is -selling an operating system, you will not like GNU, but that's tough on -you. If your business is something else, GNU can save you from being -pushed into the expensive business of selling operating systems. - -I would like to see GNU development supported by gifts from many -manufacturers and users, reducing the cost to each.@footnote{A group of -computer companies recently pooled funds to support maintenance of the -GNU C Compiler.} - -@quotation -``Don't programmers deserve a reward for their creativity?'' -@end quotation - -If anything deserves a reward, it is social contribution. Creativity can -be a social contribution, but only in so far as society is free to use the -results. If programmers deserve to be rewarded for creating innovative -programs, by the same token they deserve to be punished if they restrict -the use of these programs. - -@quotation -``Shouldn't a programmer be able to ask for a reward for his creativity?'' -@end quotation - -There is nothing wrong with wanting pay for work, or seeking to maximize -one's income, as long as one does not use means that are destructive. But -the means customary in the field of software today are based on -destruction. - -Extracting money from users of a program by restricting their use of it is -destructive because the restrictions reduce the amount and the ways that -the program can be used. This reduces the amount of wealth that humanity -derives from the program. When there is a deliberate choice to restrict, -the harmful consequences are deliberate destruction. - -The reason a good citizen does not use such destructive means to become -wealthier is that, if everyone did so, we would all become poorer from the -mutual destructiveness. This is Kantian ethics; or, the Golden Rule. -Since I do not like the consequences that result if everyone hoards -information, I am required to consider it wrong for one to do so. -Specifically, the desire to be rewarded for one's creativity does not -justify depriving the world in general of all or part of that creativity. - -@quotation -``Won't programmers starve?'' -@end quotation - -I could answer that nobody is forced to be a programmer. Most of us cannot -manage to get any money for standing on the street and making faces. But -we are not, as a result, condemned to spend our lives standing on the -street making faces, and starving. We do something else. - -But that is the wrong answer because it accepts the questioner's implicit -assumption: that without ownership of software, programmers cannot possibly -be paid a cent. Supposedly it is all or nothing. - -The real reason programmers will not starve is that it will still be -possible for them to get paid for programming; just not paid as much as -now. - -Restricting copying is not the only basis for business in software. It is -the most common basis because it brings in the most money. If it were -prohibited, or rejected by the customer, software business would move to -other bases of organization which are now used less often. There are -always numerous ways to organize any kind of business. - -Probably programming will not be as lucrative on the new basis as it is -now. But that is not an argument against the change. It is not considered -an injustice that sales clerks make the salaries that they now do. If -programmers made the same, that would not be an injustice either. (In -practice they would still make considerably more than that.) - -@quotation -``Don't people have a right to control how their creativity is used?'' -@end quotation - -``Control over the use of one's ideas'' really constitutes control over -other people's lives; and it is usually used to make their lives more -difficult. - -People who have studied the issue of intellectual property -rights@footnote{In the 80s I had not yet realized how confusing it was -to speak of ``the issue'' of ``intellectual property.'' That term is -obviously biased; more subtle is the fact that it lumps together -various disparate laws which raise very different issues. Nowadays I -urge people to reject the term ``intellectual property'' entirely, -lest it lead others to suppose that those laws form one coherent -issue. The way to be clear is to discuss patents, copyrights, and -trademarks separately. See -@uref{http://www.gnu.org/philosophy/not-ipr.xhtml} for more -explanation of how this term spreads confusion and bias.} carefully -(such as lawyers) say that there is no intrinsic right to intellectual -property. The kinds of supposed intellectual property rights that the -government recognizes were created by specific acts of legislation for -specific purposes. - -For example, the patent system was established to encourage inventors to -disclose the details of their inventions. Its purpose was to help society -rather than to help inventors. At the time, the life span of 17 years for -a patent was short compared with the rate of advance of the state of the -art. Since patents are an issue only among manufacturers, for whom the -cost and effort of a license agreement are small compared with setting up -production, the patents often do not do much harm. They do not obstruct -most individuals who use patented products. - -The idea of copyright did not exist in ancient times, when authors -frequently copied other authors at length in works of non-fiction. This -practice was useful, and is the only way many authors' works have survived -even in part. The copyright system was created expressly for the purpose -of encouraging authorship. In the domain for which it was -invented---books, which could be copied economically only on a printing -press---it did little harm, and did not obstruct most of the individuals -who read the books. - -All intellectual property rights are just licenses granted by society -because it was thought, rightly or wrongly, that society as a whole would -benefit by granting them. But in any particular situation, we have to ask: -are we really better off granting such license? What kind of act are we -licensing a person to do? - -The case of programs today is very different from that of books a hundred -years ago. The fact that the easiest way to copy a program is from one -neighbor to another, the fact that a program has both source code and -object code which are distinct, and the fact that a program is used rather -than read and enjoyed, combine to create a situation in which a person who -enforces a copyright is harming society as a whole both materially and -spiritually; in which a person should not do so regardless of whether the -law enables him to. - -@quotation -``Competition makes things get done better.'' -@end quotation - -The paradigm of competition is a race: by rewarding the winner, we -encourage everyone to run faster. When capitalism really works this way, -it does a good job; but its defenders are wrong in assuming it always works -this way. If the runners forget why the reward is offered and become -intent on winning, no matter how, they may find other strategies---such as, -attacking other runners. If the runners get into a fist fight, they will -all finish late. - -Proprietary and secret software is the moral equivalent of runners in a -fist fight. Sad to say, the only referee we've got does not seem to -object to fights; he just regulates them (``For every ten yards you run, -you can fire one shot''). He really ought to break them up, and penalize -runners for even trying to fight. - -@quotation -``Won't everyone stop programming without a monetary incentive?'' -@end quotation - -Actually, many people will program with absolutely no monetary incentive. -Programming has an irresistible fascination for some people, usually the -people who are best at it. There is no shortage of professional musicians -who keep at it even though they have no hope of making a living that way. - -But really this question, though commonly asked, is not appropriate to the -situation. Pay for programmers will not disappear, only become less. So -the right question is, will anyone program with a reduced monetary -incentive? My experience shows that they will. - -For more than ten years, many of the world's best programmers worked at the -Artificial Intelligence Lab for far less money than they could have had -anywhere else. They got many kinds of non-monetary rewards: fame and -appreciation, for example. And creativity is also fun, a reward in itself. - -Then most of them left when offered a chance to do the same interesting -work for a lot of money. - -What the facts show is that people will program for reasons other than -riches; but if given a chance to make a lot of money as well, they will -come to expect and demand it. Low-paying organizations do poorly in -competition with high-paying ones, but they do not have to do badly if the -high-paying ones are banned. - -@quotation -``We need the programmers desperately. If they demand that we -stop helping our neighbors, we have to obey.'' -@end quotation - -You're never so desperate that you have to obey this sort of demand. -Remember: millions for defense, but not a cent for tribute! - -@quotation -``Programmers need to make a living somehow.'' -@end quotation - -In the short run, this is true. However, there are plenty of ways that -programmers could make a living without selling the right to use a program. -This way is customary now because it brings programmers and businessmen the -most money, not because it is the only way to make a living. It is easy to -find other ways if you want to find them. Here are a number of examples. - -A manufacturer introducing a new computer will pay for the porting of -operating systems onto the new hardware. - -The sale of teaching, hand-holding and maintenance services could also -employ programmers. - -People with new ideas could distribute programs as -freeware@footnote{Subsequently we have discovered the need to -distinguish between ``free software'' and ``freeware''. The term -``freeware'' means software you are free to redistribute, but usually -you are not free to study and change the source code, so most of it is -not free software. See -@uref{http://www.gnu.org/philosophy/words-to-avoid.html} for more -explanation.}, asking for donations from satisfied users, or selling -hand-holding services. I have met people who are already working this -way successfully. - -Users with related needs can form users' groups, and pay dues. A group -would contract with programming companies to write programs that the -group's members would like to use. - -All sorts of development can be funded with a Software Tax: - -@quotation -Suppose everyone who buys a computer has to pay x percent of -the price as a software tax. The government gives this to -an agency like the NSF to spend on software development. - -But if the computer buyer makes a donation to software development -himself, he can take a credit against the tax. He can donate to -the project of his own choosing---often, chosen because he hopes to -use the results when it is done. He can take a credit for any amount -of donation up to the total tax he had to pay. - -The total tax rate could be decided by a vote of the payers of -the tax, weighted according to the amount they will be taxed on. - -The consequences: - -@itemize @bullet -@item -The computer-using community supports software development. -@item -This community decides what level of support is needed. -@item -Users who care which projects their share is spent on -can choose this for themselves. -@end itemize -@end quotation - -In the long run, making programs free is a step toward the post-scarcity -world, where nobody will have to work very hard just to make a living. -People will be free to devote themselves to activities that are fun, such -as programming, after spending the necessary ten hours a week on required -tasks such as legislation, family counseling, robot repair and asteroid -prospecting. There will be no need to be able to make a living from -programming. - -We have already greatly reduced the amount of work that the whole society -must do for its actual productivity, but only a little of this has -translated itself into leisure for workers because much nonproductive -activity is required to accompany productive activity. The main causes of -this are bureaucracy and isometric struggles against competition. Free -software will greatly reduce these drains in the area of software -production. We must do this, in order for technical gains in productivity -to translate into less work for us. - -@ignore - arch-tag: 21eb38f8-6fa0-480a-91cd-f3dab7148542 -@end ignore diff --git a/man/gnus-faq.texi b/man/gnus-faq.texi deleted file mode 100644 index 6bfb3477627..00000000000 --- a/man/gnus-faq.texi +++ /dev/null @@ -1,2307 +0,0 @@ -@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/man/gnus.texi b/man/gnus.texi deleted file mode 100644 index 7cabf674102..00000000000 --- a/man/gnus.texi +++ /dev/null @@ -1,29508 +0,0 @@ -\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/man/gpl.texi b/man/gpl.texi deleted file mode 100644 index 5b416d3cb41..00000000000 --- a/man/gpl.texi +++ /dev/null @@ -1,721 +0,0 @@ -@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/man/help.texi b/man/help.texi deleted file mode 100644 index fe7c2a85ffa..00000000000 --- a/man/help.texi +++ /dev/null @@ -1,666 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Help, Mark, M-x, Top -@chapter Help -@kindex Help -@cindex help -@cindex self-documentation -@findex help-command -@kindex C-h -@kindex F1 - - Emacs provides extensive help features, all accessible through the -@dfn{help character}, @kbd{C-h}. This is a prefix key that is used -for commands that display documentation; the next character you type -should be a @dfn{help options}, to ask for a particular kind of help. -You can cancel the @kbd{C-h} command with @kbd{C-g}. The function key -@key{F1} is equivalent to @kbd{C-h}. - -@kindex C-h C-h -@findex help-for-help - @kbd{C-h} itself is one of the help options; @kbd{C-h C-h} displays -a list of help options, with a brief description of each one -(@code{help-for-help}). You can scroll the list with @key{SPC} and -@key{DEL}, then type the help option you want. To cancel, type -@kbd{C-g}. - - @kbd{C-h} or @key{F1} means ``help'' in various other contexts as -well. For instance, you can type them after a prefix key to display -list of the keys that can follow the prefix key. (A few prefix keys -don't support @kbd{C-h} in this way, because they define other -meanings for it, but they all support @key{F1} for help.) - - Most help buffers use a special major mode, Help mode, which lets -you scroll conveniently with @key{SPC} and @key{DEL}. You can also -follow hyperlinks to URLs, and to other facilities including Info -nodes and customization buffers. @xref{Help Mode}. - -@cindex searching documentation efficiently -@cindex looking for a subject in documentation - If you are looking for a certain feature, but don't know what it is -called or where to look, we recommend three methods. First, try an -apropos command, then try searching the manual index, then look in the -FAQ and the package keywords. - -@table @kbd -@item C-h a @var{topics} @key{RET} -This searches for commands whose names match the argument -@var{topics}. The argument can be a keyword, a list of keywords, or a -regular expression (@pxref{Regexps}). This command displays all the -matches in a new buffer. @xref{Apropos}. - -@item C-h i d m emacs @key{RET} i @var{topic} @key{RET} -This searches for @var{topic} in the indices of the on-line Emacs -manual, and displays the first match found. Press @kbd{,} to see -subsequent matches. You can use a regular expression as @var{topic}. - -@item C-h i d m emacs @key{RET} s @var{topic} @key{RET} -Similar, but searches the @emph{text} of the manual rather than the -indices. - -@item C-h C-f -This displays the Emacs FAQ. You can use the Info commands -to browse it. - -@item C-h p -This displays the available Emacs packages based on keywords. -@xref{Library Keywords}. -@end table - -@menu -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Library Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display pre-written help files. -* Help Echo:: Help on active text and tooltips (`balloon help') -@end menu - -@iftex -@node Help Summary -@end iftex -@ifnottex -@node Help Summary -@section Help Summary -@end ifnottex - - Here is a summary of the Emacs interactive help commands. (The -character that follows @kbd{C-h} is the ``help option.'') @xref{Help -Files}, for other help commands that display fixed files of -information. - -@table @kbd -@item C-h a @var{topics} @key{RET} -Display a list of commands whose names match @var{topics} -(@code{apropos-command}; @pxref{Apropos}). -@item C-h b -Display all active key bindings; minor mode bindings first, then those -of the major mode, then global bindings (@code{describe-bindings}). -@item C-h c @var{key} -Given a key sequence @var{key}, show the name of the command that it -runs (@code{describe-key-briefly}). Here @kbd{c} stands for -``character.'' For more extensive information on @var{key}, use -@kbd{C-h k}. -@item C-h d @var{topics} @key{RET} -Display the commands and variables whose documentation matches -@var{topics} (@code{apropos-documentation}). -@item C-h e -Display the @code{*Messages*} buffer -(@code{view-echo-area-messages}). -@item C-h f @var{function} @key{RET} -Display documentation on the Lisp function named @var{function} -(@code{describe-function}). Since commands are Lisp functions, -this works for commands too. -@item C-h h -Display the @file{HELLO} file, which shows examples of various character -sets. -@item C-h i -Run Info, the GNU documentation browser (@code{info}). -The complete Emacs manual is available on-line in Info. -@item C-h k @var{key} -Display the name and documentation of the command that @var{key} runs -(@code{describe-key}). -@item C-h l -Display a description of the last 100 characters you typed -(@code{view-lossage}). -@item C-h m -Display documentation of the current major mode (@code{describe-mode}). -@item C-h p -Find packages by topic keyword (@code{finder-by-keyword}). -@item C-h s -Display the current contents of the syntax table, with an explanation of -what they mean (@code{describe-syntax}). @xref{Syntax}. -@item C-h t -Enter the Emacs interactive tutorial (@code{help-with-tutorial}). -@item C-h v @var{var} @key{RET} -Display the documentation of the Lisp variable @var{var} -(@code{describe-variable}). -@item C-h w @var{command} @key{RET} -Show which keys run the command named @var{command} (@code{where-is}). -@item C-h C @var{coding} @key{RET} -Describe the coding system @var{coding} -(@code{describe-coding-system}). -@item C-h C @key{RET} -Describe the coding systems currently in use. -@item C-h I @var{method} @key{RET} -Describe the input method @var{method} (@code{describe-input-method}). -@item C-h L @var{language-env} @key{RET} -Display information on the character sets, coding systems, and input -methods used in language environment @var{language-env} -(@code{describe-language-environment}). -@item C-h F @var{function} @key{RET} -Enter Info and goes to the node that documents the Emacs function -@var{function} (@code{Info-goto-emacs-command-node}). -@item C-h K @var{key} -Enter Info and goes to the node that documents the key sequence -@var{key} (@code{Info-goto-emacs-key-command-node}). -@item C-h S @var{symbol} @key{RET} -Display the Info documentation on symbol @var{symbol} according to the -programming language you are editing (@code{info-lookup-symbol}). -@item C-h . -Display the help message for a special text area, if point is in one -(@code{display-local-help}). (These include, for example, links in -@samp{*Help*} buffers.) -@end table - -@node Key Help -@section Documentation for a Key - -@kindex C-h c -@findex describe-key-briefly - The help commands to get information about a key sequence are -@kbd{C-h c} and @w{@kbd{C-h k}}. @kbd{C-h c @var{key}} displays in -the echo area the name of the command that @var{key} is bound to. For -example, @kbd{C-h c C-f} displays @samp{forward-char}. Since command -names are chosen to describe what the commands do, this gives you a -very brief description of what @var{key} does. - -@kindex C-h k -@findex describe-key - @kbd{C-h k @var{key}} is similar but gives more information: it -displays the documentation string of the command as well as its name. -It displays this information in a window, since it may not fit in the -echo area. - -@kindex C-h K -@findex Info-goto-emacs-key-command-node - To find the documentation of a key sequence @var{key}, type @kbd{C-h -K @var{key}}. This displays the appropriate manual section which -contains the documentation of @var{key}. - - @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key -sequences, including function keys, menus, and mouse events. For -instance, after @kbd{C-h k} you can select a menu item from the menu -bar, to view the documentation string of the command it runs. - -@kindex C-h w -@findex where-is - @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to -@var{command}. It displays the list in the echo area. If it says the -command is not on any key, that means you must use @kbd{M-x} to run -it. @kbd{C-h w} runs the command @code{where-is}. - -@node Name Help -@section Help by Command or Variable Name - -@kindex C-h f -@findex describe-function - @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) -displays the documentation of Lisp function @var{function}, in a -window. Since commands are Lisp functions, you can use this method to -view the documentation of any command whose name you know. For -example, - -@example -C-h f auto-fill-mode @key{RET} -@end example - -@noindent -displays the documentation of @code{auto-fill-mode}. This is the only -way to get the documentation of a command that is not bound to any key -(one which you would normally run using @kbd{M-x}). - - @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp -program. For example, if you have just written the expression -@code{(make-vector len)} and want to check that you are using -@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. -Because @kbd{C-h f} allows all function names, not just command names, -you may find that some of your favorite completion abbreviations that -work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is -unique among command names may not be unique among all function names. - - If you type @kbd{C-h f @key{RET}}, it describes the function called -by the innermost Lisp expression in the buffer around point, -@emph{provided} that function name is a valid, defined Lisp function. -(That name appears as the default while you enter the argument.) For -example, if point is located following the text @samp{(make-vector -(car x)}, the innermost list containing point is the one that starts -with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the -function @code{make-vector}. - - @kbd{C-h f} is also useful just to verify that you spelled a -function name correctly. If the minibuffer prompt for @kbd{C-h f} -shows the function name from the buffer as the default, it means that -name is defined as a Lisp function. Type @kbd{C-g} to cancel the -@kbd{C-h f} command if you don't really want to view the -documentation. - -@kindex C-h v -@findex describe-variable - @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but -describes Lisp variables instead of Lisp functions. Its default is -the Lisp symbol around or before point, if that is the name of a -defined Lisp variable. @xref{Variables}. - - Help buffers that describe Emacs variables and functions normally -have hyperlinks to the corresponding source definition, if you have -the source files installed. (@xref{Hyperlinking}.) If you know Lisp -(or C), this provides the ultimate documentation. If you don't know -Lisp, you should learn it. (The Introduction to Emacs Lisp -Programming, available from the FSF through fsf.org, is a good way to -get started.) If Emacs feels you are just @emph{using} it, treating -it as an object program, its feelings may be hurt. For real intimacy, -read the Emacs source code. - -@kindex C-h F -@findex Info-goto-emacs-command-node - To find a function's documentation in a manual, use @kbd{C-h F} -(@code{Info-goto-emacs-command-node}). This knows about various -manuals, not just the Emacs manual, and finds the right one. - -@node Apropos -@section Apropos - - The @dfn{apropos} commands answer questions like, ``What are the -commands for working with files?'' More precisely, you specify an -@dfn{apropos pattern}, which means either a word, a list of words, or -a regular expression. Each apropos command displays a list of items -that match the pattern, in a separate buffer. - -@table @kbd -@item C-h a @var{pattern} @key{RET} -Search for commands whose names match @var{pattern}. - -@item M-x apropos @key{RET} @var{pattern} @key{RET} -Search for functions and variables whose names match @var{pattern}. -Both interactive functions (commands) and noninteractive functions can -be found by this command. - -@item M-x apropos-variable @key{RET} @var{pattern} @key{RET} -Search for user-option variables whose names match @var{pattern}. - -@item M-x apropos-value @key{RET} @var{pattern} @key{RET} -Search for functions whose definitions @var{pattern}, and variables -whose values match @var{pattern}. - -@item C-h d @var{pattern} @key{RET} -Search for functions and variables whose @strong{documentation -strings} match @var{pattern}. -@end table - -@kindex C-h a -@findex apropos-command -@cindex apropos - The simplest kind of apropos pattern is one word. Anything which -contains that word matches the pattern. Thus, to find the commands -that work on files, type @kbd{C-h a file @key{RET}}. This displays a -list of all command names that contain @samp{file}, including -@code{copy-file}, @code{find-file}, and so on. Each command name -comes with a brief description and a list of keys you can currently -invoke it with. In our example, it would say that you can invoke -@code{find-file} by typing @kbd{C-x C-f}. - - The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a} -runs the command @code{apropos-command}. This command normally checks -only commands (interactive functions); if you specify a prefix -argument, it checks noninteractive functions as well. - - For more information about a function definition, variable or symbol -property listed in the apropos buffer, you can click on it with -@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}. - - When you specify more than one word in the apropos pattern, a name -must contain at least two of the words in order to match. Thus, if -you are looking for commands to kill a chunk of text before point, you -could try @kbd{C-h a kill back backward behind before @key{RET}}. The -real command name @code{kill-backward} will match that; if there were -a command @code{kill-text-before}, it would also match, since it -contains two of the specified words. - - For even greater flexibility, you can specify a regular expression -(@pxref{Regexps}). An apropos pattern is interpreted as a regular -expression if it contains any of the regular expression special -characters, @samp{^$*+?.\[}. - - Following the conventions for naming Emacs commands, here are some -words that you'll find useful in apropos patterns. By using them in -@kbd{C-h a}, you will also get a feel for the naming conventions. - -@quotation -char, line, word, sentence, paragraph, region, page, sexp, list, defun, -rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, -forward, backward, next, previous, up, down, search, goto, kill, delete, -mark, insert, yank, fill, indent, case, change, set, what, list, find, -view, describe, default. -@end quotation - -@findex apropos - Use @kbd{M-x apropos} instead of @kbd{C-h a} to list all the Lisp -symbols that match an apropos pattern, not just the symbols that are -commands. This command does not list key bindings by default; specify -a numeric argument if you want it to list them. - -@findex apropos-variable - Use @kbd{M-x apropos-variable} to list user-customizable variables -that match an apropos pattern. If you specify a prefix argument, it -lists all matching variables. - -@kindex C-h d -@findex apropos-documentation - The @code{apropos-documentation} command is like @code{apropos} -except that it searches documentation strings instead of symbol names -for matches. - -@findex apropos-value - The @code{apropos-value} command is like @code{apropos} except that -it searches variables' values for matches for the apropos pattern. -With a prefix argument, it also checks symbols' function definitions -and property lists. - -@vindex apropos-do-all - If the variable @code{apropos-do-all} is non-@code{nil}, the apropos -commands always behave as if they had been given a prefix argument. - -@vindex apropos-sort-by-scores -@cindex apropos search results, order by score - By default, apropos lists the search results in alphabetical order. -If the variable @code{apropos-sort-by-scores} is non-@code{nil}, the -apropos commands try to guess the relevance of each result, and -display the most relevant ones first. - -@vindex apropos-documentation-sort-by-scores - By default, apropos lists the search results for -@code{apropos-documentation} in order of relevance of the match. If -the variable @code{apropos-documentation-sort-by-scores} is -@code{nil}, apropos lists the symbols found in alphabetical order. - -@node Help Mode -@section Help Mode Commands - - Help buffers provide the same commands as View mode (@pxref{Misc File -Ops}), plus a few special commands of their own. - -@table @kbd -@item @key{SPC} -Scroll forward. -@item @key{DEL} -Scroll backward. -@item @key{RET} -Follow a cross reference at point. -@item @key{TAB} -Move point forward to the next cross reference. -@item S-@key{TAB} -Move point back to the previous cross reference. -@item Mouse-1 -@itemx Mouse-2 -Follow a cross reference that you click on. -@item C-c C-c -Show all documentation about the symbol at point. -@end table - - When a function name (@pxref{M-x,, Running Commands by Name}), -variable name (@pxref{Variables}), or face name (@pxref{Faces}) -appears in the documentation, it normally appears inside paired -single-quotes. To view the documentation of that command, variable or -face, you can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2}, -or move point there and type @key{RET}. Use @kbd{C-c C-b} to retrace -your steps. - -@cindex URL, viewing in help -@cindex help, viewing web pages -@cindex viewing web pages in help -@cindex web pages, viewing in help -@findex browse-url - You can follow cross references to URLs (web pages) also. This uses -the @code{browse-url} command to view the page in the browser you -choose. @xref{Browse-URL}. - -@kindex @key{TAB} @r{(Help mode)} -@findex help-next-ref -@kindex S-@key{TAB} @r{(Help mode)} -@findex help-previous-ref - There are convenient commands to move point to cross references in -the help text. @key{TAB} (@code{help-next-ref}) moves point down to -the next cross reference. @kbd{S-@key{TAB}} moves up to the previous -cross reference (@code{help-previous-ref}). - - To view all documentation about any symbol name that appears in the -text, move point to the symbol name and type @kbd{C-c C-c} -(@code{help-follow-symbol}). This shows all available documentation -about the symbol as a variable, function and/or face. As above, use -@kbd{C-c C-b} to retrace your steps. - -@node Library Keywords -@section Keyword Search for Lisp Libraries - -@kindex C-h p -@findex finder-by-keyword -The @kbd{C-h p} command lets you search the standard Emacs Lisp -libraries by topic keywords. Here is a partial list of keywords you can -use: - -@multitable {convenience} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} -@item abbrev@tab abbreviation handling, typing shortcuts, macros. -@item bib@tab code related to the @code{bib} bibliography processor. -@item c@tab support for the C language and related languages. -@item calendar@tab calendar and time management support. -@item comm@tab communications, networking, remote access to files. -@item convenience@tab convenience features for faster editing. -@item data@tab support for editing files of data. -@item docs@tab support for Emacs documentation. -@item emulations@tab emulations of other editors. -@item extensions@tab Emacs Lisp language extensions. -@item faces@tab support for multiple fonts. -@item files@tab support for editing and manipulating files. -@item frames@tab support for Emacs frames and window systems. -@item games@tab games, jokes and amusements. -@item hardware@tab support for interfacing with exotic hardware. -@item help@tab support for on-line help systems. -@item hypermedia@tab support for links between text or other media types. -@item i18n@tab internationalization and alternate character-set support. -@item internal@tab code for Emacs internals, build process, defaults. -@item languages@tab specialized modes for editing programming languages. -@item lisp@tab Lisp support, including Emacs Lisp. -@item local@tab code local to your site. -@item maint@tab maintenance aids for the Emacs development group. -@item mail@tab modes for electronic-mail handling. -@item matching@tab various sorts of searching and matching. -@item mouse@tab mouse support. -@item multimedia@tab images and sound support. -@item news@tab support for netnews reading and posting. -@item oop@tab support for object-oriented programming. -@item outlines@tab support for hierarchical outlining. -@item processes@tab process, subshell, compilation, and job control support. -@item terminals@tab support for terminal types. -@item tex@tab supporting code for the @TeX{} formatter. -@item tools@tab programming tools. -@item unix@tab front-ends/assistants for, or emulators of, UNIX-like features. -@item wp@tab word processing. -@end multitable - -@node Language Help -@section Help for International Language Support - - You can use the command @kbd{C-h L} -(@code{describe-language-environment}) to get information about a -specific language environment. @xref{Language Environments}. This -tells you which languages this language environment supports. It also -lists the character sets, coding systems, and input methods that work -with this language environment, and finally shows some sample text to -illustrate scripts. - - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which shows how to say ``hello'' in many languages. - - The command @kbd{C-h I} (@code{describe-input-method}) describes an -input method---either a specified input method, or by default the -input method currently in use. @xref{Input Methods}. - - The command @kbd{C-h C} (@code{describe-coding-system}) describes -coding systems---either a specified coding system, or the ones -currently in use. @xref{Coding Systems}. - -@node Misc Help -@section Other Help Commands - -@kindex C-h i -@findex info -@cindex Info -@cindex manuals, on-line -@cindex on-line manuals - @kbd{C-h i} (@code{info}) runs the Info program, which browses -structured documentation files. The entire Emacs manual is available -within Info, along with many other manuals for the GNU system. Type -@kbd{h} after entering Info to run a tutorial on using Info. - -@cindex find Info manual by its file name - With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer -@samp{*info*<@var{n}>}. This is useful if you want to browse multiple -Info manuals simultaneously. If you specify just @kbd{C-u} as the -prefix argument, @kbd{C-h i} prompts for the name of a documentation -file, so you can browse a file which doesn't have an entry in the -top-level Info menu. - - The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h -K @var{key}}, described above, enter Info and go straight to the -documentation of @var{function} or @var{key}. - -@kindex C-h S -@findex info-lookup-symbol - When editing a program, if you have an Info version of the manual -for the programming language, you can use @kbd{C-h S} -(@code{info-lookup-symbol}) to find symbol (keyword, function or -variable) in the proper manual. The details of how this command works -depend on the major mode. - -@kindex C-h l -@findex view-lossage - If something surprising happens, and you are not sure what you -typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays -the last 100 characters you typed in Emacs. If you see commands that -you don't know, you can use @kbd{C-h c} to find out what they do. - -@kindex C-h e -@findex view-echo-area-messages - To review recent echo area messages, use @kbd{C-h e} -(@code{view-echo-area-messages}). This displays the buffer -@code{*Messages*}, where those messages are kept. - -@kindex C-h m -@findex describe-mode - Each Emacs major mode typically redefines a few keys and makes other -changes in how editing works. @kbd{C-h m} (@code{describe-mode}) -displays documentation on the current major mode, which normally -describes the commands and features that are changed in this mode. - -@kindex C-h b -@findex describe-bindings - @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} -(@code{describe-syntax}) show other information about the current -environment within Emacs. @kbd{C-h b} displays a list of all the key -bindings now in effect: first the local bindings of the current minor -modes, then the local bindings defined by the current major mode, and -finally the global bindings (@pxref{Key Bindings}). @kbd{C-h s} -displays the contents of the syntax table, with explanations of each -character's syntax (@pxref{Syntax}). - - You can get a list of subcommands for a particular prefix key by -typing @kbd{C-h} after the prefix key. (There are a few prefix keys -for which this does not work---those that provide their own bindings -for @kbd{C-h}. One of these is @key{ESC}, because @kbd{@key{ESC} C-h} -is actually @kbd{C-M-h}, which marks a defun.) - -@node Help Files -@section Help Files - - The Emacs help commands described above display dynamic help based -on the current state within Emacs, or refer to manuals. Other help -commands display pre-written, static help files. These commands all -have the form @kbd{C-h C-@var{char}}; that is, @kbd{C-h} followed by a -control character. - -@kindex C-h C-c -@findex describe-copying -@kindex C-h C-d -@findex describe-distribution -@kindex C-h C-e -@findex view-emacs-problems -@kindex C-h C-f -@findex view-emacs-FAQ -@kindex C-h C-n -@findex view-emacs-news -@kindex C-h C-p -@findex describe-project -@kindex C-h C-t -@findex view-emacs-todo -@kindex C-h C-w -@findex describe-no-warranty - -@table @kbd -@item C-h C-c -Display the Emacs copying conditions (@code{describe-copying}). -These are the rules under which you can copy and redistribute Emacs. -@item C-h C-d -Display how to download or order the latest version of -Emacs and other GNU software (@code{describe-distribution}). -@item C-h C-e -Display the list of known Emacs problems, sometimes with suggested -workarounds (@code{view-emacs-problems}). -@item C-h C-f -Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). -@item C-h C-n -Display the Emacs ``news'' file, which lists new features in the most -recent version of Emacs (@code{view-emacs-news}). -@item C-h C-p -Display general information about the GNU Project -(@code{describe-project}). -@item C-h C-t -Display the Emacs to-do list (@code{view-todo}). -@item C-h C-w -Display the full details on the complete absence of warranty for GNU -Emacs (@code{describe-no-warranty}). -@end table - -@node Help Echo -@section Help on Active Text and Tooltips - -@cindex tooltips -@cindex balloon help - When a region of text is ``active,'' so that you can select it with -the mouse or a key like @kbd{RET}, it often has associated help text. -For instance, most parts of the mode line have help text. On -graphical displays, the help text is displayed as a ``tooltip'' -(sometimes known as ``balloon help''), when you move the mouse over -the active text. @xref{Tooltips}. On some systems, it is shown in -the echo area. On text-only terminals, if Emacs cannot follow the -mouse, it cannot show the help text on mouse-over. - -@kindex C-h . -@findex display-local-help -@vindex help-at-pt-display-when-idle - You can also access text region help info using the keyboard. The -command @kbd{C-h .} (@code{display-local-help}) displays any help text -associated with the text at point, using the echo area. If you want -help text to be displayed automatically whenever it is available at -point, set the variable @code{help-at-pt-display-when-idle} to -@code{t}. - -@ignore - arch-tag: 6f33ab62-bc75-4367-8057-fd67cc15c3a1 -@end ignore diff --git a/man/idlwave.texi b/man/idlwave.texi deleted file mode 100644 index 4f216ac87b8..00000000000 --- a/man/idlwave.texi +++ /dev/null @@ -1,4327 +0,0 @@ -\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/man/indent.texi b/man/indent.texi deleted file mode 100644 index 568b54897fa..00000000000 --- a/man/indent.texi +++ /dev/null @@ -1,244 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Indentation, Text, Major Modes, Top -@chapter Indentation -@cindex indentation -@cindex columns (indentation) - - This chapter describes the Emacs commands that add, remove, or -adjust indentation. - -@table @kbd -@item @key{TAB} -Indent the current line ``appropriately'' in a mode-dependent fashion. -@item @kbd{C-j} -Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). -@item M-^ -Merge the previous and the current line (@code{delete-indentation}). -This would cancel the effect of a preceding @kbd{C-j}. -@item C-M-o -Split the current line at point; text on the line after point becomes a -new line indented to the same column where point is located -(@code{split-line}). -@item M-m -Move (forward or back) to the first nonblank character on the current -line (@code{back-to-indentation}). -@item C-M-\ -Indent lines in the region to the same column (@code{indent-region}). -@item C-x @key{TAB} -Shift lines in the region rigidly right or left (@code{indent-rigidly}). -@item M-i -Indent from point to the next prespecified tab stop column -(@code{tab-to-tab-stop}). -@item M-x indent-relative -Indent from point to under an indentation point in the previous line. -@end table - - Emacs supports four general categories of operations that could all -be called `indentation': - -@enumerate -@item -Insert a tab character. You can type @kbd{C-q @key{TAB}} to do this. - -A tab character is displayed as a stretch of whitespace which extends -to the next display tab stop position, and the default width of a tab -stop is eight. @xref{Text Display}, for more details. - -@item -Insert whitespace up to the next tab stop. You can set tab stops at -your choice of column positions, then type @kbd{M-i} to advance to the -next tab stop. The default tab stop settings have a tab stop every -eight columns, which means by default @kbd{M-i} inserts a tab -character. To set the tab stops, use @kbd{M-x edit-tab-stops}. - -@item -Align a line with the previous line. More precisely, the command -@kbd{M-x indent-relative} indents the current line under the beginning -of some word in the previous line. In Fundamental mode and in Text -mode, @key{TAB} runs the command @code{indent-relative}. - -@item -The most sophisticated method is @dfn{syntax-driven indentation}. -Most programming languages have an indentation convention. For Lisp -code, lines are indented according to their nesting in parentheses. C -code uses the same general idea, but many details are different. - -@kindex TAB -Type @key{TAB} to do syntax-driven indentation, in a mode that -supports it. It realigns the current line according with the syntax -of the preceding lines. No matter where in the line you are when you -type @key{TAB}, it aligns the line as a whole. -@end enumerate - - Normally, most of the above methods insert an optimal mix of tabs and -spaces to align to the desired column. @xref{Just Spaces}, for how to -disable use of tabs. However, @kbd{C-q @key{TAB}} always inserts a -tab, even when tabs are disabled for the indentation commands. - -@menu -* Indentation Commands:: Various commands and techniques for indentation. -* Tab Stops:: You can set arbitrary "tab stops" and then - indent to the next tab stop when you want to. -* Just Spaces:: You can request indentation using just spaces. -@end menu - -@node Indentation Commands, Tab Stops, Indentation, Indentation -@section Indentation Commands and Techniques - -@kindex M-m -@findex back-to-indentation - To move over the indentation on a line, do @kbd{M-m} -(@code{back-to-indentation}). This command, given anywhere on a line, -positions point at the first nonblank character on the line, if any, -or else at the end of the line. - - To insert an indented line before the current line, do @kbd{C-a C-o -@key{TAB}}. To make an indented line after the current line, use -@kbd{C-e C-j}. - - If you just want to insert a tab character in the buffer, you can type -@kbd{C-q @key{TAB}}. - -@kindex C-M-o -@findex split-line - @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of -the line vertically down, so that the current line becomes two lines. -@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it -inserts after point a newline and enough indentation to reach the same -column point is on. Point remains before the inserted newline; in this -regard, @kbd{C-M-o} resembles @kbd{C-o}. - -@kindex M-^ -@findex delete-indentation - To join two lines cleanly, use the @kbd{M-^} -(@code{delete-indentation}) command. It deletes the indentation at -the front of the current line, and the line boundary as well, -replacing them with a single space. As a special case (useful for -Lisp code) the single space is omitted if the characters to be joined -are consecutive open parentheses or closing parentheses, or if the -junction follows another newline. To delete just the indentation of a -line, go to the beginning of the line and use @kbd{M-\} -(@code{delete-horizontal-space}), which deletes all spaces and tabs -around the cursor. - - If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it -appears after the newline that is deleted. @xref{Fill Prefix}. - -@kindex C-M-\ -@kindex C-x TAB -@findex indent-region -@findex indent-rigidly - There are also commands for changing the indentation of several lines -at once. They apply to all the lines that begin in the region. -@kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual'' -way, as if you had typed @key{TAB} at the beginning of the line. A -numeric argument specifies the column to indent to, and each line is -shifted left or right so that its first nonblank character appears in -that column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of -the lines in the region right by its argument (left, for negative -arguments). The whole group of lines moves rigidly sideways, which is -how the command gets its name. - -@cindex remove indentation - To remove all indentation from all of the lines in the region, -invoke @kbd{C-x @key{TAB}} with a large negative argument, such as --1000. - -@findex indent-relative - @kbd{M-x indent-relative} indents at point based on the previous line -(actually, the last nonempty line). It inserts whitespace at point, moving -point, until it is underneath the next indentation point in the previous line. -An indentation point is the end of a sequence of whitespace or the end of -the line. If point is farther right than any indentation point in the -previous line, @code{indent-relative} runs @code{tab-to-tab-stop} -@ifnottex -(@pxref{Tab Stops}), -@end ifnottex -@iftex -(see next section), -@end iftex -unless it is called with a numeric argument, in which case it does -nothing. - - @xref{Format Indentation}, for another way of specifying the -indentation for part of your text. - -@node Tab Stops, Just Spaces, Indentation Commands, Indentation -@section Tab Stops - -@cindex tab stops -@cindex using tab stops in making tables -@cindex tables, indentation for -@kindex M-i -@findex tab-to-tab-stop - For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}). -This command inserts indentation before point, enough to reach the -next tab stop column. - -@findex edit-tab-stops -@findex edit-tab-stops-note-changes -@kindex C-c C-c @r{(Edit Tab Stops)} -@vindex tab-stop-list - You can specify the tab stops used by @kbd{M-i}. They are stored in a -variable called @code{tab-stop-list}, as a list of column-numbers in -increasing order. - - The convenient way to set the tab stops is with @kbd{M-x -edit-tab-stops}, which creates and selects a buffer containing a -description of the tab stop settings. You can edit this buffer to -specify different tab stops, and then type @kbd{C-c C-c} to make those -new tab stops take effect. The buffer uses Overwrite mode -(@pxref{Minor Modes}). @code{edit-tab-stops} records which buffer was -current when you invoked it, and stores the tab stops back in that -buffer; normally all buffers share the same tab stops and changing -them in one buffer affects all, but if you happen to make -@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in -that buffer will edit the local settings. - - Here is what the text representing the tab stops looks like for ordinary -tab stops every eight columns. - -@example - : : : : : : -0 1 2 3 4 -0123456789012345678901234567890123456789012345678 -To install changes, type C-c C-c -@end example - - The first line contains a colon at each tab stop. The remaining lines -are present just to help you see where the colons are and know what to do. - - Note that the tab stops that control @code{tab-to-tab-stop} have nothing -to do with displaying tab characters in the buffer. @xref{Text Display}, -for more information on that. - -@node Just Spaces,, Tab Stops, Indentation -@section Tabs vs. Spaces - -@vindex indent-tabs-mode - Emacs normally uses both tabs and spaces to indent lines. If you -prefer, all indentation can be made from spaces only. To request -this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer -variable, so altering the variable affects only the current buffer, -but there is a default value which you can change as well. -@xref{Locals}. - - A tab is not always displayed in the same way. By default, tabs are -eight columns wide, but some people like to customize their tools to -use a different tab width. So by using spaces only, you can make sure -that your file looks the same regardless of the tab width setting. - -@findex tabify -@findex untabify - There are also commands to convert tabs to spaces or vice versa, always -preserving the columns of all nonblank text. @kbd{M-x tabify} scans the -region for sequences of spaces, and converts sequences of at least two -spaces to tabs if that can be done without changing indentation. @kbd{M-x -untabify} changes all tabs in the region to appropriate numbers of spaces. - -@ignore - arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb -@end ignore diff --git a/man/info.texi b/man/info.texi deleted file mode 100644 index 285ef09554e..00000000000 --- a/man/info.texi +++ /dev/null @@ -1,1503 +0,0 @@ -\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/man/killing.texi b/man/killing.texi deleted file mode 100644 index b626bfab385..00000000000 --- a/man/killing.texi +++ /dev/null @@ -1,699 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Killing, Yanking, Mark, Top -@chapter Killing and Moving Text - -@ifnottex -@raisesections -@end ifnottex - - @dfn{Killing} means erasing text and copying it into the @dfn{kill -ring}, from which you can bring it back into the buffer by -@dfn{yanking} it. (Some systems use the terms ``cutting'' and -``pasting'' for these operations.) This is the most common way of -moving or copying text within Emacs. Killing and yanking is very safe -because Emacs remembers several recent kills, not just the last one. -It is versatile, because the many commands for killing syntactic units -can also be used for moving those units. But there are other ways of -copying text for special purposes. - -@iftex -@section Deletion and Killing -@end iftex - -@cindex killing text -@cindex cutting text -@cindex deletion - Most commands which erase text from the buffer save it in the kill -ring. These commands are known as @dfn{kill} commands. The commands -that erase text but do not save it in the kill ring are known as -@dfn{delete} commands. The @kbd{C-x u} (@code{undo}) command -(@pxref{Undo}) can undo both kill and delete commands; the importance -of the kill ring is that you can also yank the text in a different -place or places. Emacs has only one kill ring for all buffers, so you -can kill text in one buffer and yank it in another buffer. - - The delete commands include @kbd{C-d} (@code{delete-char}) and -@key{DEL} (@code{delete-backward-char}), which delete only one -character at a time, and those commands that delete only spaces or -newlines. Commands that can erase significant amounts of nontrivial -data generally do a kill operation instead. The commands' names and -individual descriptions use the words @samp{kill} and @samp{delete} to -say which kind of operation they perform. - -@vindex kill-read-only-ok -@cindex read-only text, killing - You cannot kill read-only text, since such text does not allow any -kind of modification. But some users like to use the kill commands to -copy read-only text into the kill ring, without actually changing it. -Therefore, the kill commands work specially in a read-only buffer: -they move over text, and copy it to the kill ring, without actually -deleting it from the buffer. Normally, kill commands beep and display -an error message when this happens. But if you set the variable -@code{kill-read-only-ok} to a non-@code{nil} value, they just print a -message in the echo area to explain why the text has not been erased. - - You can also use the mouse to kill and yank. @xref{Cut and Paste}. - -@menu -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. -@end menu - -@need 1500 -@node Deletion -@subsection Deletion -@findex delete-backward-char -@findex delete-char - - Deletion means erasing text and not saving it in the kill ring. For -the most part, the Emacs commands that delete text are those that -erase just one character or only whitespace. - -@table @kbd -@item C-d -@itemx @key{DELETE} -Delete next character (@code{delete-char}). If your keyboard has a -@key{DELETE} function key (usually located in the edit keypad), Emacs -binds it to @code{delete-char} as well. -@item @key{DEL} -@itemx @key{BS} -Delete previous character (@code{delete-backward-char}). -@item M-\ -Delete spaces and tabs around point (@code{delete-horizontal-space}). -@item M-@key{SPC} -Delete spaces and tabs around point, leaving one space -(@code{just-one-space}). -@item C-x C-o -Delete blank lines around the current line (@code{delete-blank-lines}). -@item M-^ -Join two lines by deleting the intervening newline, along with any -indentation following it (@code{delete-indentation}). -@end table - -@kindex DEL -@kindex C-d - The most basic delete commands are @kbd{C-d} (@code{delete-char}) and -@key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the -character after point, the one the cursor is ``on top of.'' This -doesn't move point. @key{DEL} deletes the character before the cursor, -and moves point back. You can delete newlines like any other characters -in the buffer; deleting a newline joins two lines. Actually, @kbd{C-d} -and @key{DEL} aren't always delete commands; when given arguments, they -kill instead, since they can erase more than one character this way. - -@kindex BACKSPACE -@kindex BS -@kindex DELETE - Every keyboard has a large key which is a short distance above the -@key{RET} or @key{ENTER} key and is normally used for erasing what you -have typed. It may be labeled @key{DEL}, @key{BACKSPACE}, @key{BS}, -@key{DELETE}, or even with a left arrow. Regardless of the label on -the key, in Emacs it called @key{DEL}, and it should delete one -character backwards. - - Many keyboards (including standard PC keyboards) have a -@key{BACKSPACE} key a short ways above @key{RET} or @key{ENTER}, and a -@key{DELETE} key elsewhere. In that case, the @key{BACKSPACE} key is -@key{DEL}, and the @key{DELETE} key is equivalent to @kbd{C-d}---or it -should be. - - Why do we say ``or it should be''? When Emacs starts up using a -graphical display, it determines automatically which key or keys should be -equivalent to @key{DEL}. As a result, @key{BACKSPACE} and/or @key{DELETE} -keys normally do the right things. But in some unusual cases Emacs -gets the wrong information from the system. If these keys don't do -what they ought to do, you need to tell Emacs which key to use for -@key{DEL}. @xref{DEL Does Not Delete}, for how to do this. - -@findex normal-erase-is-backspace-mode - On most text-only terminals, Emacs cannot tell which keys the -keyboard really has, so it follows a uniform plan which may or may not -fit your keyboard. The uniform plan is that the @acronym{ASCII} @key{DEL} -character deletes, and the @acronym{ASCII} @key{BS} (backspace) character asks -for help (it is the same as @kbd{C-h}). If this is not right for your -keyboard, such as if you find that the key which ought to delete backwards -enters Help instead, see @ref{DEL Does Not Delete}. - -@kindex M-\ -@findex delete-horizontal-space -@kindex M-SPC -@findex just-one-space - The other delete commands are those which delete only whitespace -characters: spaces, tabs and newlines. @kbd{M-\} -(@code{delete-horizontal-space}) deletes all the spaces and tab -characters before and after point. With a prefix argument, this only -deletes spaces and tab characters before point. @kbd{M-@key{SPC}} -(@code{just-one-space}) does likewise but leaves a single space after -point, regardless of the number of spaces that existed previously -(even if there were none before). With a numeric argument @var{n}, it -leaves @var{n} spaces after point. - - @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines -after the current line. If the current line is blank, it deletes all -blank lines preceding the current line as well (leaving one blank line, -the current line). On a solitary blank line, it deletes that line. - - @kbd{M-^} (@code{delete-indentation}) joins the current line and the -previous line, by deleting a newline and all surrounding spaces, usually -leaving a single space. @xref{Indentation,M-^}. - -@node Killing by Lines -@subsection Killing by Lines - -@table @kbd -@item C-k -Kill rest of line or one or more lines (@code{kill-line}). -@item C-S-backspace -Kill an entire line at once (@code{kill-whole-line}) -@end table - -@kindex C-k -@findex kill-line - The simplest kill command is @kbd{C-k}. If given at the beginning of -a line, it kills all the text on the line, leaving it blank. When used -on a blank line, it kills the whole line including its newline. To kill -an entire non-blank line, go to the beginning and type @kbd{C-k} twice. - - More generally, @kbd{C-k} kills from point up to the end of the line, -unless it is at the end of a line. In that case it kills the newline -following point, thus merging the next line into the current one. -Spaces and tabs that you can't see at the end of the line are ignored -when deciding which case applies, so if point appears to be at the end -of the line, you can be sure @kbd{C-k} will kill the newline. - - When @kbd{C-k} is given a positive argument, it kills that many lines -and the newlines that follow them (however, text on the current line -before point is not killed). With a negative argument @minus{}@var{n}, it -kills @var{n} lines preceding the current line (together with the text -on the current line before point). Thus, @kbd{C-u - 2 C-k} at the front -of a line kills the two previous lines. - - @kbd{C-k} with an argument of zero kills the text before point on the -current line. - -@vindex kill-whole-line - If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at -the very beginning of a line kills the entire line including the -following newline. This variable is normally @code{nil}. - -@kindex C-S-backspace -@findex kill-whole-line - @kbd{C-S-backspace} (@code{kill-whole-line}) will kill a whole line -including its newline regardless of the position of point within the -line. Note that many character terminals will prevent you from typing -the key sequence @kbd{C-S-backspace}. - -@node Other Kill Commands -@subsection Other Kill Commands -@findex kill-region -@kindex C-w - -@table @kbd -@item C-w -Kill region (from point to the mark) (@code{kill-region}). -@item M-d -Kill word (@code{kill-word}). @xref{Words}. -@item M-@key{DEL} -Kill word backwards (@code{backward-kill-word}). -@item C-x @key{DEL} -Kill back to beginning of sentence (@code{backward-kill-sentence}). -@xref{Sentences}. -@item M-k -Kill to end of sentence (@code{kill-sentence}). -@item C-M-k -Kill the following balanced expression (@code{kill-sexp}). @xref{Expressions}. -@item M-z @var{char} -Kill through the next occurrence of @var{char} (@code{zap-to-char}). -@end table - - The most general kill command is @kbd{C-w} (@code{kill-region}), -which kills everything between point and the mark. With this command, -you can kill any contiguous sequence of characters, if you first set -the region around them. - -@kindex M-z -@findex zap-to-char - A convenient way of killing is combined with searching: @kbd{M-z} -(@code{zap-to-char}) reads a character and kills from point up to (and -including) the next occurrence of that character in the buffer. A -numeric argument acts as a repeat count. A negative argument means to -search backward and kill text before point. - - Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} -and @kbd{M-d} (@pxref{Words}); balanced expressions, with @kbd{C-M-k} -(@pxref{Expressions}); and sentences, with @kbd{C-x @key{DEL}} and -@kbd{M-k} (@pxref{Sentences}).@refill - -@node Yanking, Accumulating Text, Killing, Top -@section Yanking -@cindex moving text -@cindex copying text -@cindex kill ring -@cindex yanking -@cindex pasting - - @dfn{Yanking} means reinserting text previously killed. This is what -some systems call ``pasting.'' The usual way to move or copy text is to -kill it and then yank it elsewhere one or more times. This is very safe -because Emacs remembers many recent kills, not just the last one. - -@table @kbd -@item C-y -Yank last killed text (@code{yank}). -@item M-y -Replace text just yanked with an earlier batch of killed text -(@code{yank-pop}). -@item M-w -Save region as last killed text without actually killing it -(@code{kill-ring-save}). Some systems call this ``copying.'' -@item C-M-w -Append next kill to last batch of killed text (@code{append-next-kill}). -@end table - - On graphical displays with window systems, if there is a current -selection in some other application, and you selected it more recently -than you killed any text in Emacs, @kbd{C-y} copies the selection -instead of text killed within Emacs. - -@menu -* Kill Ring:: Where killed text is stored. Basic yanking. -* Appending Kills:: Several kills in a row all yank together. -* Earlier Kills:: Yanking something killed some time ago. -@end menu - -@node Kill Ring -@subsection The Kill Ring - - All killed text is recorded in the @dfn{kill ring}, a list of blocks of -text that have been killed. There is only one kill ring, shared by all -buffers, so you can kill text in one buffer and yank it in another buffer. -This is the usual way to move text from one file to another. -(@xref{Accumulating Text}, for some other ways.) - -@kindex C-y -@findex yank - The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent -kill. It leaves the cursor at the end of the text. It sets the mark at -the beginning of the text. @xref{Mark}. - - @kbd{C-u C-y} leaves the cursor in front of the text, and sets the -mark after it. This happens only if the argument is specified with just -a @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u} -and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}). - -@cindex yanking and text properties -@vindex yank-excluded-properties - The yank commands discard certain text properties from the text that -is yanked, those that might lead to annoying results. For instance, -they discard text properties that respond to the mouse or specify key -bindings. The variable @code{yank-excluded-properties} specifies the -properties to discard. Yanking of register contents and rectangles -also discard these properties. - -@kindex M-w -@findex kill-ring-save - To copy a block of text, you can use @kbd{M-w} -(@code{kill-ring-save}), which copies the region into the kill ring -without removing it from the buffer. This is approximately equivalent -to @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does not -alter the undo history and does not temporarily change the screen. - -@node Appending Kills -@subsection Appending Kills - -@cindex appending kills in the ring -@cindex television - Normally, each kill command pushes a new entry onto the kill ring. -However, two or more kill commands in a row combine their text into a -single entry, so that a single @kbd{C-y} yanks all the text as a unit, -just as it was before it was killed. - - Thus, if you want to yank text as a unit, you need not kill all of it -with one command; you can keep killing line after line, or word after -word, until you have killed it all, and you can still get it all back at -once. - - Commands that kill forward from point add onto the end of the previous -killed text. Commands that kill backward from point add text onto the -beginning. This way, any sequence of mixed forward and backward kill -commands puts all the killed text into one entry without rearrangement. -Numeric arguments do not break the sequence of appending kills. For -example, suppose the buffer contains this text: - -@example -This is a line @point{}of sample text. -@end example - -@noindent -with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d -M-@key{DEL}}, killing alternately forward and backward, you end up with -@samp{a line of sample} as one entry in the kill ring, and @samp{This -is@ @ text.} in the buffer. (Note the double space between @samp{is} -and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or -@kbd{M-q}.) - - Another way to kill the same text is to move back two words with -@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. -This produces exactly the same results in the buffer and in the kill -ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going -backward; once again, the result is the same. The text in the kill ring -entry always has the same order that it had in the buffer before you -killed it. - -@kindex C-M-w -@findex append-next-kill - If a kill command is separated from the last kill command by other -commands (not just numeric arguments), it starts a new entry on the kill -ring. But you can force it to append by first typing the command -@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} -tells the following command, if it is a kill command, to append the text -it kills to the last killed text, instead of starting a new entry. With -@kbd{C-M-w}, you can kill several separated pieces of text and -accumulate them to be yanked back in one place.@refill - - A kill command following @kbd{M-w} does not append to the text that -@kbd{M-w} copied into the kill ring. - -@node Earlier Kills -@subsection Yanking Earlier Kills - -@cindex yanking previous kills -@kindex M-y -@findex yank-pop - To recover killed text that is no longer the most recent kill, use the -@kbd{M-y} command (@code{yank-pop}). It takes the text previously -yanked and replaces it with the text from an earlier kill. So, to -recover the text of the next-to-the-last kill, first use @kbd{C-y} to -yank the last kill, and then use @kbd{M-y} to replace it with the -previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another -@kbd{M-y}. - - You can understand @kbd{M-y} in terms of a ``last yank'' pointer which -points at an entry in the kill ring. Each time you kill, the ``last -yank'' pointer moves to the newly made entry at the front of the ring. -@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. -@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the -text in the buffer changes to match. Enough @kbd{M-y} commands can move -the pointer to any entry in the ring, so you can get any entry into the -buffer. Eventually the pointer reaches the end of the ring; the next -@kbd{M-y} loops back around to the first entry again. - - @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does -not change the order of the entries in the ring, which always runs from -the most recent kill at the front to the oldest one still remembered. - - @kbd{M-y} can take a numeric argument, which tells it how many entries -to advance the ``last yank'' pointer by. A negative argument moves the -pointer toward the front of the ring; from the front of the ring, it -moves ``around'' to the last entry and continues forward from there. - - Once the text you are looking for is brought into the buffer, you can -stop doing @kbd{M-y} commands and it will stay there. It's just a copy -of the kill ring entry, so editing it in the buffer does not change -what's in the ring. As long as no new killing is done, the ``last -yank'' pointer remains at the same place in the kill ring, so repeating -@kbd{C-y} will yank another copy of the same previous kill. - - If you know how many @kbd{M-y} commands it would take to find the -text you want, you can yank that text in one step using @kbd{C-y} with -a numeric argument. @kbd{C-y} with an argument restores the text from -the specified kill ring entry, counting back from the most recent as -1. Thus, @kbd{C-u 2 C-y} gets the next-to-the-last block of killed -text---it is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric -argument starts counting from the ``last yank'' pointer, and sets the -``last yank'' pointer to the entry that it yanks. - -@vindex kill-ring-max - The length of the kill ring is controlled by the variable -@code{kill-ring-max}; no more than that many blocks of killed text are -saved. - -@vindex kill-ring - The actual contents of the kill ring are stored in a variable named -@code{kill-ring}; you can view the entire contents of the kill ring with -the command @kbd{C-h v kill-ring}. - -@node Accumulating Text, Rectangles, Yanking, Top -@section Accumulating Text -@findex append-to-buffer -@findex prepend-to-buffer -@findex copy-to-buffer -@findex append-to-file - -@cindex accumulating scattered text - Usually we copy or move text by killing it and yanking it, but there -are other convenient methods for copying one block of text in many -places, or for copying many scattered blocks of text into one place. To -copy one block to many places, store it in a register -(@pxref{Registers}). Here we describe the commands to accumulate -scattered pieces of text into a buffer or into a file. - -@table @kbd -@item M-x append-to-buffer -Append region to the contents of a specified buffer. -@item M-x prepend-to-buffer -Prepend region to the contents of a specified buffer. -@item M-x copy-to-buffer -Copy region into a specified buffer, deleting that buffer's old contents. -@item M-x insert-buffer -Insert the contents of a specified buffer into current buffer at point. -@item M-x append-to-file -Append region to the contents of a specified file, at the end. -@end table - - To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. -This reads a buffer name, then inserts a copy of the region into the -buffer specified. If you specify a nonexistent buffer, -@code{append-to-buffer} creates the buffer. The text is inserted -wherever point is in that buffer. If you have been using the buffer for -editing, the copied text goes into the middle of the text of the buffer, -starting from wherever point happens to be at that moment. - - Point in that buffer is left at the end of the copied text, so -successive uses of @code{append-to-buffer} accumulate the text in the -specified buffer in the same order as they were copied. Strictly -speaking, @code{append-to-buffer} does not always append to the text -already in the buffer---it appends only if point in that buffer is at the end. -However, if @code{append-to-buffer} is the only command you use to alter -a buffer, then point is always at the end. - - @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} -except that point in the other buffer is left before the copied text, so -successive prependings add text in reverse order. @kbd{M-x -copy-to-buffer} is similar, except that any existing text in the other -buffer is deleted, so the buffer is left containing just the text newly -copied into it. - - To retrieve the accumulated text from another buffer, use the -command @kbd{M-x insert-buffer}; this too takes @var{buffername} as an -argument. It inserts a copy of the whole text in buffer -@var{buffername} into the current buffer at point, and sets the mark -after the inserted text. Alternatively, you can select the other -buffer for editing, then copy text from it by killing. -@xref{Buffers}, for background information on buffers. - - Instead of accumulating text within Emacs, in a buffer, you can append -text directly into a file with @kbd{M-x append-to-file}, which takes -@var{filename} as an argument. It adds the text of the region to the end -of the specified file. The file is changed immediately on disk. - - You should use @code{append-to-file} only with files that are -@emph{not} being visited in Emacs. Using it on a file that you are -editing in Emacs would change the file behind Emacs's back, which -can lead to losing some of your editing. - -@node Rectangles, CUA Bindings, Accumulating Text, Top -@section Rectangles -@cindex rectangle -@cindex columns (and rectangles) -@cindex killing rectangular areas of text - - The rectangle commands operate on rectangular areas of the text: all -the characters between a certain pair of columns, in a certain range of -lines. Commands are provided to kill rectangles, yank killed rectangles, -clear them out, fill them with blanks or text, or delete them. Rectangle -commands are useful with text in multicolumn formats, and for changing -text into or out of such formats. - -@cindex mark rectangle - When you must specify a rectangle for a command to work on, you do it -by putting the mark at one corner and point at the opposite corner. The -rectangle thus specified is called the @dfn{region-rectangle} because -you control it in much the same way as the region is controlled. But -remember that a given combination of point and mark values can be -interpreted either as a region or as a rectangle, depending on the -command that uses them. - - If point and the mark are in the same column, the rectangle they -delimit is empty. If they are in the same line, the rectangle is one -line high. This asymmetry between lines and columns comes about -because point (and likewise the mark) is between two columns, but within -a line. - -@table @kbd -@item C-x r k -Kill the text of the region-rectangle, saving its contents as the -``last killed rectangle'' (@code{kill-rectangle}). -@item C-x r d -Delete the text of the region-rectangle (@code{delete-rectangle}). -@item C-x r y -Yank the last killed rectangle with its upper left corner at point -(@code{yank-rectangle}). -@item C-x r o -Insert blank space to fill the space of the region-rectangle -(@code{open-rectangle}). This pushes the previous contents of the -region-rectangle rightward. -@item C-x r c -Clear the region-rectangle by replacing all of its contents with spaces -(@code{clear-rectangle}). -@item M-x delete-whitespace-rectangle -Delete whitespace in each of the lines on the specified rectangle, -starting from the left edge column of the rectangle. -@item C-x r t @var{string} @key{RET} -Replace rectangle contents with @var{string} on each line -(@code{string-rectangle}). -@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} -Insert @var{string} on each line of the rectangle. -@end table - - The rectangle operations fall into two classes: commands for -deleting and inserting rectangles, and commands for blank rectangles. - -@kindex C-x r k -@kindex C-x r d -@findex kill-rectangle -@findex delete-rectangle - There are two ways to get rid of the text in a rectangle: you can -discard the text (delete it) or save it as the ``last killed'' -rectangle. The commands for these two ways are @kbd{C-x r d} -(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In -either case, the portion of each line that falls inside the rectangle's -boundaries is deleted, causing any following text on the line to -move left into the gap. - - Note that ``killing'' a rectangle is not killing in the usual sense; the -rectangle is not stored in the kill ring, but in a special place that -can only record the most recent rectangle killed. This is because yanking -a rectangle is so different from yanking linear text that different yank -commands have to be used. It is hard to define yank-popping for rectangles, -so we do not try. - -@kindex C-x r y -@findex yank-rectangle - To yank the last killed rectangle, type @kbd{C-x r y} -(@code{yank-rectangle}). Yanking a rectangle is the opposite of killing -one. Point specifies where to put the rectangle's upper left corner. -The rectangle's first line is inserted there, the rectangle's second -line is inserted at the same horizontal position, but one line -vertically down, and so on. The number of lines affected is determined -by the height of the saved rectangle. - - You can convert single-column lists into double-column lists using -rectangle killing and yanking; kill the second half of the list as a -rectangle and then yank it beside the first line of the list. -@xref{Two-Column}, for another way to edit multi-column text. - - You can also copy rectangles into and out of registers with @kbd{C-x r -r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle -Registers}. - -@kindex C-x r o -@findex open-rectangle -@kindex C-x r c -@findex clear-rectangle - There are two commands you can use for making blank rectangles: -@kbd{C-x r c} (@code{clear-rectangle}) which blanks out existing text, -and @kbd{C-x r o} (@code{open-rectangle}) which inserts a blank -rectangle. Clearing a rectangle is equivalent to deleting it and then -inserting a blank rectangle of the same size. - -@findex delete-whitespace-rectangle - The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal -whitespace starting from a particular column. This applies to each of -the lines in the rectangle, and the column is specified by the left -edge of the rectangle. The right edge of the rectangle does not make -any difference to this command. - -@kindex C-x r t -@findex string-rectangle - The command @kbd{C-x r t} (@code{string-rectangle}) replaces the -contents of a region-rectangle with a string on each line. The -string's width need not be the same as the width of the rectangle. If -the string's width is less, the text after the rectangle shifts left; -if the string is wider than the rectangle, the text after the -rectangle shifts right. - -@findex string-insert-rectangle - The command @kbd{M-x string-insert-rectangle} is similar to -@code{string-rectangle}, but inserts the string on each line, -shifting the original text to the right. - -@node CUA Bindings, Registers, Rectangles, Top -@section CUA Bindings -@findex cua-mode -@vindex cua-mode -@cindex CUA key bindings -@vindex cua-enable-cua-keys - The command @kbd{M-x cua-mode} sets up key bindings that are -compatible with the Common User Access (CUA) system used in many other -applications. @kbd{C-x} means cut (kill), @kbd{C-c} copy, @kbd{C-v} -paste (yank), and @kbd{C-z} undo. Standard Emacs commands like -@kbd{C-x C-c} still work, because @kbd{C-x} and @kbd{C-c} only take -effect when the mark is active (and the region is highlighted). -However, if you don't want to override these bindings in Emacs at all, -set @code{cua-enable-cua-keys} to @code{nil}. - - In CUA mode, using @kbd{Shift} together with the movement keys -activates and highlights the region over which they move. The -standard (unshifted) movement keys deactivate the mark, and typed text -replaces the active region as in Delete-Selection mode -(@pxref{Mouse Commands}). - - To enter an Emacs command like @kbd{C-x C-f} while the mark is -active, use one of the following methods: either hold @kbd{Shift} -together with the prefix key, e.g. @kbd{S-C-x C-f}, or quickly type -the prefix key twice, e.g. @kbd{C-x C-x C-f}. - -@cindex rectangle highlighting - CUA mode provides enhanced rectangle support with visible -rectangle highlighting. Use @kbd{C-RET} to start a rectangle, -extend it using the movement commands, and cut or copy it using -@kbd{C-x} or @kbd{C-c}. @kbd{RET} moves the cursor to the next -(clockwise) corner of the rectangle, so you can easily expand it in -any direction. Normal text you type is inserted to the left or right -of each line in the rectangle (on the same side as the cursor). - - With CUA you can easily copy text and rectangles into and out of -registers by providing a one-digit numeric prefix to the kill, copy, -and yank commands, e.g. @kbd{C-1 C-c} copies the region into register -@code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}. - -@cindex global mark - CUA mode also has a global mark feature which allows easy moving and -copying of text between buffers. Use @kbd{C-S-SPC} to toggle the -global mark on and off. When the global mark is on, all text that you -kill or copy is automatically inserted at the global mark, and text -you type is inserted at the global mark rather than at the current -position. - - For example, to copy words from various buffers into a word list in -a given buffer, set the global mark in the target buffer, then -navigate to each of the words you want in the list, mark it (e.g. with -@kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and -insert a newline after the word in the target list by pressing -@key{RET}. - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: d8da8f96-0928-449a-816e-ff2d3497866c -@end ignore diff --git a/man/kmacro.texi b/man/kmacro.texi deleted file mode 100644 index 16526e1a2b8..00000000000 --- a/man/kmacro.texi +++ /dev/null @@ -1,616 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Keyboard Macros, Files, Fixit, Top -@chapter Keyboard Macros -@cindex defining keyboard macros -@cindex keyboard macro - - In this chapter we describe how to record a sequence of editing -commands so you can repeat it conveniently later. - - A @dfn{keyboard macro} is a command defined by an Emacs user to stand for -another sequence of keys. For example, if you discover that you are -about to type @kbd{C-n M-d C-d} forty times, you can speed your work by -defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing -it 39 more times. - - You define a keyboard macro by executing and recording the commands -which are its definition. Put differently, as you define a keyboard -macro, the definition is being executed for the first time. This way, -you can see the effects of your commands, so that you don't have to -figure them out in your head. When you close the definition, the -keyboard macro is defined and also has been, in effect, executed once. -You can then do the whole thing over again by invoking the macro. - - Keyboard macros differ from ordinary Emacs commands in that they are -written in the Emacs command language rather than in Lisp. This makes it -easier for the novice to write them, and makes them more convenient as -temporary hacks. However, the Emacs command language is not powerful -enough as a programming language to be useful for writing anything -intelligent or general. For such things, Lisp must be used. - -@menu -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. -@end menu - -@node Basic Keyboard Macro -@section Basic Use - -@table @kbd -@item @key{F3} -@itemx C-x ( -Start defining a keyboard macro (@code{kmacro-start-macro}). -@item @key{F4} -If a keyboard macro is being defined, end the definition; otherwise, -execute the most recent keyboard macro -(@code{kmacro-end-or-call-macro}). -@item C-x ) -End the definition of a keyboard macro (@code{kmacro-end-macro}). -@item C-x e -Execute the most recent keyboard macro (@code{kmacro-end-and-call-macro}). -First end the definition of the keyboard macro, if currently defining it. -To immediately execute the keyboard macro again, just repeat the @kbd{e}. -@item C-u C-x ( -Re-execute last keyboard macro, then add more keys to its definition. -@item C-u C-u C-x ( -Add more keys to the last keyboard macro without re-executing it. -@item C-x C-k r -Run the last keyboard macro on each line that begins in the region -(@code{apply-macro-to-region-lines}). -@end table - -@kindex F3 -@kindex F4 -@kindex C-x ( -@kindex C-x ) -@kindex C-x e -@findex kmacro-start-macro -@findex kmacro-end-macro -@findex kmacro-end-and-call-macro - To start defining a keyboard macro, type the @kbd{F3} or @kbd{C-x (} command -(@code{kmacro-start-macro}). From then on, your keys continue to be -executed, but also become part of the definition of the macro. @samp{Def} -appears in the mode line to remind you of what is going on. When you are -finished, the @kbd{F4} or @kbd{C-x )} command (@code{kmacro-end-macro}) terminates the -definition (without becoming part of it!). For example, - -@example -C-x ( M-f foo C-x ) -@end example - -@noindent -defines a macro to move forward a word and then insert @samp{foo}. - - The macro thus defined can be invoked again with the @kbd{C-x e} -command (@code{kmacro-end-and-call-macro}), which may be given a -repeat count as a numeric argument to execute the macro many times. -If you enter @kbd{C-x e} while defining a macro, the macro is -terminated and executed immediately. - - After executing the macro with @kbd{C-x e}, you can use @kbd{e} -repeatedly to immediately repeat the macro one or more times. For example, - -@example -C-x ( xyz C-x e e e -@end example - -@noindent -inserts @samp{xyzxyzxyzxyz} in the current buffer. - - @kbd{C-x )} can also be given a repeat count as an argument, in -which case it repeats the macro that many times right after defining -it, but defining the macro counts as the first repetition (since it is -executed as you define it). Therefore, giving @kbd{C-x )} an argument -of 4 executes the macro immediately 3 additional times. An argument -of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the macro -indefinitely (until it gets an error or you type @kbd{C-g} or, on -MS-DOS, @kbd{C-@key{BREAK}}). - - The key @key{F4} is like a combination of @kbd{C-x )} and @kbd{C-x -e}. If you're defining a macro, @key{F4} ends the definition. -Otherwise it executes the last macro. For example, - -@example -F3 xyz F4 F4 F4 -@end example - -@noindent -inserts @samp{xyzxyzxyz} in the current buffer. - - If you wish to repeat an operation at regularly spaced places in the -text, define a macro and include as part of the macro the commands to move -to the next place you want to use it. For example, if you want to change -each line, you should position point at the start of a line, and define a -macro to change that line and leave point at the start of the next line. -Then repeating the macro will operate on successive lines. - - When a command reads an argument with the minibuffer, your -minibuffer input becomes part of the macro along with the command. So -when you replay the macro, the command gets the same argument as -when you entered the macro. For example, - -@example -C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x ) -@end example - -@noindent -defines a macro that copies the current line into the buffer -@samp{foo}, then returns to the original buffer. - - You can use function keys in a keyboard macro, just like keyboard -keys. You can even use mouse events, but be careful about that: when -the macro replays the mouse event, it uses the original mouse position -of that event, the position that the mouse had while you were defining -the macro. The effect of this may be hard to predict. (Using the -current mouse position would be even less predictable.) - - One thing that sometimes works badly in a keyboard macro is the -command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command -exits a recursive edit that started within the macro, it works as -you'd expect. But if it exits a recursive edit that started before -you invoked the keyboard macro, it also necessarily exits the keyboard -macro as part of the process. - - After you have terminated the definition of a keyboard macro, you can add -to the end of its definition by typing @kbd{C-u F3} or @kbd{C-u C-x (}. -This is equivalent -to plain @kbd{C-x (} followed by retyping the whole definition so far. As -a consequence it re-executes the macro as previously defined. - - You can also add to the end of the definition of the last keyboard -macro without re-executing it by typing @kbd{C-u C-u C-x (}. - - The variable @code{kmacro-execute-before-append} specifies whether -a single @kbd{C-u} prefix causes the existing macro to be re-executed -before appending to it. - -@findex apply-macro-to-region-lines -@kindex C-x C-k r - The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines}) -repeats the last defined keyboard macro on each line that begins in -the region. It does this line by line, by moving point to the -beginning of the line and then executing the macro. - -@node Keyboard Macro Ring -@section The Keyboard Macro Ring - - All defined keyboard macros are recorded in the ``keyboard macro ring,'' -a list of sequences of keys. There is only one keyboard macro ring, -shared by all buffers. - -@table @kbd -@item C-x C-k C-k -Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). -@item C-x C-k C-n -Rotate the keyboard macro ring to the next macro (defined earlier) -(@code{kmacro-cycle-ring-next}). -@item C-x C-k C-p -Rotate the keyboard macro ring to the previous macro (defined later) -(@code{kmacro-cycle-ring-previous}). -@end table - - All commands which operate on the keyboard macro ring use the -same @kbd{C-x C-k} prefix. Most of these commands can be executed and -repeated immediately after each other without repeating the @kbd{C-x -C-k} prefix. For example, - -@example -C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d -@end example - -@noindent -will rotate the keyboard macro ring to the ``second previous'' macro, -execute the resulting head macro three times, rotate back to the -original head macro, execute that once, rotate to the ``previous'' -macro, execute that, and finally delete it from the macro ring. - -@findex kmacro-end-or-call-macro-repeat -@kindex C-x C-k C-k - The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) -executes the keyboard macro at the head of the macro ring. You can -repeat the macro immediately by typing another @kbd{C-k}, or you can -rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. - - When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves like -@kbd{C-x )} except that, immediately afterward, you can use most key -bindings of this section without the @kbd{C-x C-k} prefix. For -instance, another @kbd{C-k} will re-execute the macro. - -@findex kmacro-cycle-ring-next -@kindex C-x C-k C-n -@findex kmacro-cycle-ring-previous -@kindex C-x C-k C-p - The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and -@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the -macro ring, bringing the next or previous keyboard macro to the head -of the macro ring. The definition of the new head macro is displayed -in the echo area. You can continue to rotate the macro ring -immediately by repeating just @kbd{C-n} and @kbd{C-p} until the -desired macro is at the head of the ring. To execute the new macro -ring head immediately, just type @kbd{C-k}. - - Note that Emacs treats the head of the macro ring as the ``last -defined keyboard macro.'' For instance, @kbd{C-x e} will execute that -macro, and @kbd{C-x C-k n} will give it a name. - -@ignore @c This interface is too kludgy - @c and the functionality duplicates the functionality above -- rms. -@findex kmacro-view-macro-repeat -@kindex C-x C-k C-v - The command @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat}) -displays the last keyboard macro, or when repeated (with @kbd{C-v}), -it displays the previous macro on the macro ring, just like @kbd{C-x -C-k C-p}, but without actually rotating the macro ring. If you enter -@kbd{C-k} immediately after displaying a macro from the ring, that -macro is executed, but still without altering the macro ring. - - So while e.g. @kbd{C-x C-k C-p C-p C-p C-k C-k} makes the 3rd previous -macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v -C-v C-k C-k} will display and execute the 3rd previous macro once and -then the current macro once. -@end ignore - -@ignore @c This is just too much feeping creaturism. - @c If you are reusing certain macros enough to want these, - @c you should give then names. -- rms -@findex kmacro-delete-ring-head -@kindex C-x C-k C-d - - The command @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head}) -removes and deletes the macro currently at the head of the macro -ring. You can use this to delete a macro that didn't work as -expected, or which you don't need anymore. - -@findex kmacro-swap-ring -@kindex C-x C-k C-t - - The command @kbd{C-x C-k C-t} (@code{kmacro-swap-ring}) -interchanges the head of the macro ring with the previous element on -the macro ring. - -@findex kmacro-call-ring-2nd-repeat -@kindex C-x C-k C-l - - The command @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat}) -executes the previous (rather than the head) element on the macro ring. -@end ignore - -@vindex kmacro-ring-max - The maximum number of macros stored in the keyboard macro ring is -determined by the customizable variable @code{kmacro-ring-max}. - -@node Keyboard Macro Counter -@section The Keyboard Macro Counter - -@table @kbd -@item C-x C-k C-i -Insert the keyboard macro counter value in the buffer -(@code{kmacro-insert-counter}). -@item C-x C-k C-c -Set the keyboard macro counter (@code{kmacro-set-counter}). -@item C-x C-k C-a -Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). -@item C-x C-k C-f -Specify the format for inserting the keyboard macro counter -(@code{kmacro-set-format}). -@end table - - Each keyboard macro has an associated counter. Normally, the -macro counter is initialized to 0 when you start defining the macro, -and incremented by 1 after each insertion of the counter value; -that is, if you insert the macro counter twice while defining the -macro, the counter will increase by 2 on each repetition of the macro. - -@findex kmacro-insert-counter -@kindex C-x C-k C-i - The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) inserts -the current value of the current keyboard macro's counter, and -increments the counter by 1. You can use a numeric prefix argument to -specify a different increment. If you just specify a @kbd{C-u} -prefix, then the increment is zero, so it repeats the last inserted -counter value. For example, if you enter the following sequence while -defining a macro - -@example -C-x C-k C-i C-x C-k C-i C-u C-x C-k C-i C-x C-k C-i -@end example - -@noindent -it inserts @samp{0112} in the buffer. The next two iterations -of the macro will insert @samp{3445} and @samp{6778}. - - This command usually only makes sense while defining a keyboard -macro. But its behavior when no keyboard macro is being defined or -executed is predictable: it inserts and increments the counter of the -macro at the head of the keyboard macro ring. - -@findex kmacro-set-counter -@kindex C-x C-k C-c - The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the -current macro counter to the value of the numeric argument. If you use -it inside the macro, it operates on each repetition of the macro. If -you specify just @kbd{C-u} as the prefix, while executing the macro, -that resets the counter to the value it had at the beginning of the -current repetition of the macro (undoing any increments so far in this -repetition). - -@findex kmacro-add-counter -@kindex C-x C-k C-a - The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the -prefix argument to the current macro counter. With just @kbd{C-u} as -argument, it resets the counter to the last value inserted by any -keyboard macro. (Normally, when you use this, the last insertion -will be in the same macro and it will be the same counter.) - -@findex kmacro-set-format -@kindex C-x C-k C-f - The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for -the format to use when inserting the macro counter. The default -format is @samp{%d}, which means to insert the number in decimal -without any padding. You can exit with empty minibuffer to reset the -format to this default. You can specify any format string that the -@code{format} function accepts and that makes sense with a single -integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). Do not put the format string inside double -quotes when you insert it in the minibuffer. - - If you use this command while no keyboard macro is being defined or -executed, the new format affects all subsequent macro definitions. -Existing macros continue to use the format in effect when they were -defined. If you set the format while defining a keyboard macro, this -affects the macro being defined from that point on, but it does not -affect subsequent macros. Execution of the macro will, at each step, -use the format in effect at that step during its definition. Changes -to the macro format during execution of a macro, like the -corresponding changes during its definition, have no effect on -subsequent macros. - - The format set by @kbd{C-x C-k C-f} does not affect insertion of -numbers stored in registers. - -@node Keyboard Macro Query -@section Executing Macros with Variations - -@table @kbd -@item C-x q -When this point is reached during macro execution, ask for confirmation -(@code{kbd-macro-query}). -@end table - -@kindex C-x q -@findex kbd-macro-query - Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect -similar to that of @code{query-replace}, where the macro asks you each -time around whether to make a change. While defining the macro, -type @kbd{C-x q} at the point where you want the query to occur. During -macro definition, the @kbd{C-x q} does nothing, but when you run the -macro later, @kbd{C-x q} asks you interactively whether to continue. - - The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}), -@key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}. -The answers are the same as in @code{query-replace}, though not all of -the @code{query-replace} options are meaningful. - - These responses include @key{SPC} to continue, and @key{DEL} to skip -the remainder of this repetition of the macro and start right away with -the next repetition. @key{RET} means to skip the remainder of this -repetition and cancel further repetitions. @kbd{C-l} redraws the screen -and asks you again for a character to say what to do. - - @kbd{C-r} enters a recursive editing level, in which you can perform -editing which is not part of the macro. When you exit the recursive -edit using @kbd{C-M-c}, you are asked again how to continue with the -keyboard macro. If you type a @key{SPC} at this time, the rest of the -macro definition is executed. It is up to you to leave point and the -text in a state such that the rest of the macro will do what you -want.@refill - - @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, -performs a completely different function. It enters a recursive edit -reading input from the keyboard, both when you type it during the -definition of the macro, and when it is executed from the macro. During -definition, the editing you do inside the recursive edit does not become -part of the macro. During macro execution, the recursive edit gives you -a chance to do some particularized editing on each repetition. -@xref{Recursive Edit}. - - Another way to vary the behavior of a keyboard macro is to use a -register as a counter, incrementing it on each repetition of the macro. -@xref{RegNumbers}. - -@node Save Keyboard Macro -@section Naming and Saving Keyboard Macros - -@table @kbd -@item C-x C-k n -Give a command name (for the duration of the Emacs session) to the most -recently defined keyboard macro (@code{kmacro-name-last-macro}). -@item C-x C-k b -Bind the most recently defined keyboard macro to a key sequence (for -the duration of the session) (@code{kmacro-bind-to-key}). -@item M-x insert-kbd-macro -Insert in the buffer a keyboard macro's definition, as Lisp code. -@end table - -@cindex saving keyboard macros -@findex kmacro-name-last-macro -@kindex C-x C-k n - If you wish to save a keyboard macro for later use, you can give it -a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}). -This reads a name as an argument using the minibuffer and defines that -name to execute the last keyboard macro, in its current form. (If you -later add to the definition of this macro, that does not alter the -name's definition as a macro.) The macro name is a Lisp symbol, and -defining it in this way makes it a valid command name for calling with -@kbd{M-x} or for binding a key to with @code{global-set-key} -(@pxref{Keymaps}). If you specify a name that has a prior definition -other than a keyboard macro, an error message is shown and nothing is -changed. - -@cindex binding keyboard macros -@findex kmacro-bind-to-key -@kindex C-x C-k b - You can also bind the last keyboard macro (in its current form) to a -key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the -key sequence you want to bind. You can bind to any key sequence in -the global keymap, but since most key sequences already have other -bindings, you should select the key sequence carefully. If you try to -bind to a key sequence with an existing binding (in any keymap), this -command asks you for confirmation before replacing the existing binding. - - To avoid problems caused by overriding existing bindings, the key -sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} -through @kbd{C-x C-k Z} are reserved for your own keyboard macro -bindings. In fact, to bind to one of these key sequences, you only -need to type the digit or letter rather than the whole key sequences. -For example, - -@example -C-x C-k b 4 -@end example - -@noindent -will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}. - -@findex insert-kbd-macro - Once a macro has a command name, you can save its definition in a file. -Then it can be used in another editing session. First, visit the file -you want to save the definition in. Then use this command: - -@example -M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} -@end example - -@noindent -This inserts some Lisp code that, when executed later, will define the -same macro with the same definition it has now. (You need not -understand Lisp code to do this, because @code{insert-kbd-macro} writes -the Lisp code for you.) Then save the file. You can load the file -later with @code{load-file} (@pxref{Lisp Libraries}). If the file you -save in is your init file @file{~/.emacs} (@pxref{Init File}) then the -macro will be defined each time you run Emacs. - - If you give @code{insert-kbd-macro} a numeric argument, it makes -additional Lisp code to record the keys (if any) that you have bound -to @var{macroname}, so that the macro will be reassigned the same keys -when you load the file. - -@node Edit Keyboard Macro -@section Editing a Keyboard Macro - -@table @kbd -@item C-x C-k C-e -Edit the last defined keyboard macro (@code{kmacro-edit-macro}). -@item C-x C-k e @var{name} @key{RET} -Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). -@item C-x C-k l -Edit the last 100 keystrokes as a keyboard macro -(@code{kmacro-edit-lossage}). -@end table - -@findex kmacro-edit-macro -@kindex C-x C-k C-e -@kindex C-x C-k RET - You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or -@kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro -definition in a buffer and enters a specialized major mode for editing -it. Type @kbd{C-h m} once in that buffer to display details of how to -edit the macro. When you are finished editing, type @kbd{C-c C-c}. - -@findex edit-kbd-macro -@kindex C-x C-k e - You can edit a named keyboard macro or a macro bound to a key by typing -@kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the -keyboard input that you would use to invoke the macro---@kbd{C-x e} or -@kbd{M-x @var{name}} or some other key sequence. - -@findex kmacro-edit-lossage -@kindex C-x C-k l - You can edit the last 100 keystrokes as a macro by typing -@kbd{C-x C-k l} (@code{kmacro-edit-lossage}). - -@node Keyboard Macro Step-Edit -@section Stepwise Editing a Keyboard Macro - -@findex kmacro-step-edit-macro -@kindex C-x C-k SPC - You can interactively replay and edit the last keyboard -macro, one command at a time, by typing @kbd{C-x C-k SPC} -(@code{kmacro-step-edit-macro}). Unless you quit the macro using -@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the -macro ring. - - This macro editing feature shows the last macro in the minibuffer -together with the first (or next) command to be executed, and prompts -you for an action. You can enter @kbd{?} to get a summary of your -options. These actions are available: - -@itemize @bullet{} -@item -@kbd{SPC} and @kbd{y} execute the current command, and advance to the -next command in the keyboard macro. -@item -@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command. -@item -@kbd{f} skips the current command in this execution of the keyboard -macro, but doesn't delete it from the macro. -@item -@kbd{@key{TAB}} executes the current command, as well as all similar -commands immediately following the current command; for example, @key{TAB} -may be used to insert a sequence of characters (corresponding to a -sequence of @code{self-insert-command} commands). -@item -@kbd{c} continues execution (without further editing) until the end of -the keyboard macro. If execution terminates normally, the edited -macro replaces the original keyboard macro. -@item -@kbd{C-k} skips and deletes the rest of the keyboard macro, -terminates step-editing, and replaces the original keyboard macro -with the edited macro. -@item -@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; -discarding any changes made to the keyboard macro. -@item -@kbd{i KEY... C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and inserts them before the current -command in the keyboard macro, without advancing over the current -command. -@item -@kbd{I KEY...} reads one key sequence, executes it, and inserts it -before the current command in the keyboard macro, without advancing -over the current command. -@item -@kbd{r KEY... C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and replaces the current command in -the keyboard macro with them, advancing over the inserted key -sequences. -@item -@kbd{R KEY...} reads one key sequence, executes it, and replaces the -current command in the keyboard macro with that key sequence, -advancing over the inserted key sequence. -@item -@kbd{a KEY... C-j} executes the current command, then reads and -executes a series of key sequences (not including the final -@kbd{C-j}), and inserts them after the current command in the keyboard -macro; it then advances over the current command and the inserted key -sequences. -@item -@kbd{A KEY... C-j} executes the rest of the commands in the keyboard -macro, then reads and executes a series of key sequences (not -including the final @kbd{C-j}), and appends them at the end of the -keyboard macro; it then terminates the step-editing and replaces the -original keyboard macro with the edited macro. -@end itemize - -@ignore - arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c -@end ignore diff --git a/man/m-x.texi b/man/m-x.texi deleted file mode 100644 index 7a5b80fd348..00000000000 --- a/man/m-x.texi +++ /dev/null @@ -1,75 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node M-x, Help, Minibuffer, Top -@chapter Running Commands by Name - - Every Emacs command has a name that you can use to run it. For -convenience, many commands also have key bindings. You can run those -commands by typing the keys, or run them by name. Most Emacs commands -have no key bindings, so the only way to run them is by name. -(@xref{Key Bindings}, for how to set up key bindings.) - - By convention, a command name consists of one or more words, -separated by hyphens; for example, @code{auto-fill-mode} or -@code{manual-entry}. Command names mostly use complete English words -to make them easier to remember. - -@kindex M-x - To run a command by name, start with @kbd{M-x}, type the command -name, then terminate it with @key{RET}. @kbd{M-x} uses the minibuffer -to read the command name. The string @samp{M-x} appears at the -beginning of the minibuffer as a @dfn{prompt} to remind you to enter a -command name to be run. @key{RET} exits the minibuffer and runs the -command. @xref{Minibuffer}, for more information on the minibuffer. - - You can use completion to enter the command name. For example, -to invoke the command @code{forward-char}, you can type - -@example -M-x forward-char @key{RET} -@end example - -@noindent -or - -@example -M-x forw @key{TAB} c @key{RET} -@end example - -@noindent -Note that @code{forward-char} is the same command that you invoke with -the key @kbd{C-f}. The existence of a key binding does not stop you -from running the command by name. - - To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead -of entering the command name. This takes you back to command level. - - To pass a numeric argument to the command you are invoking with -@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The -argument value appears in the prompt while the command name is being -read, and finally @kbd{M-x} passes the argument to that command. - -@vindex suggest-key-bindings - When the command you run with @kbd{M-x} has a key binding, Emacs -mentions this in the echo area after running the command. For -example, if you type @kbd{M-x forward-word}, the message says that you -can run the same command by typing @kbd{M-f}. You can turn off these -messages by setting the variable @code{suggest-key-bindings} to -@code{nil}. - - In this manual, when we speak of running a command by name, we often -omit the @key{RET} that terminates the name. Thus we might say -@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode -@key{RET}}. We mention the @key{RET} only for emphasis, such as when -the command is followed by arguments. - -@findex execute-extended-command - @kbd{M-x} works by running the command -@code{execute-extended-command}, which is responsible for reading the -name of another command and invoking it. - -@ignore - arch-tag: b67bff53-9628-4666-b94e-eda972a7ba56 -@end ignore diff --git a/man/macos.texi b/man/macos.texi deleted file mode 100644 index 28d7f43df8e..00000000000 --- a/man/macos.texi +++ /dev/null @@ -1,429 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2000, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mac OS, Microsoft Windows, Antinews, Top -@appendix Emacs and Mac OS -@cindex Mac OS -@cindex Macintosh - - This section briefly describes the peculiarities of using Emacs -under Mac OS with native window system support. For Mac OS X, Emacs -can be built either without window system support, with X11, or with -Carbon API. This section only applies to the Carbon build. For Mac -OS Classic, Emacs can be built with or without Carbon API, and this -section applies to either of them because they run on the native -window system. - - Emacs built on Mac OS X supports most of its major features except -display support of PostScript images. The following features of Emacs -are not supported on Mac OS Classic: unexec (@code{dump-emacs}), -asynchronous subprocesses (@code{start-process}), and networking -(@code{open-network-stream}). As a result, packages such as Gnus, -GUD, and Comint do not work. Synchronous subprocesses -(@code{call-process}) are supported on non-Carbon build, but -specially-crafted external programs are needed. Since external -programs to handle commands such as @code{print-buffer} and -@code{diff} are not available on Mac OS Classic, they are not -supported. Non-Carbon build on Mac OS Classic does not support some -features such as file dialogs, drag-and-drop, and Unicode menus. - -@menu -* Input: Mac Input. Keyboard and mouse input on Mac. -* Intl: Mac International. International character sets on Mac. -* Env: Mac Environment Variables. Setting environment variables for Emacs. -* Directories: Mac Directories. Volumes and directories on Mac. -* Font: Mac Font Specs. Specifying fonts on Mac. -* Functions: Mac Functions. Mac-specific Lisp functions. -@end menu - -@node Mac Input -@section Keyboard and Mouse Input on Mac -@cindex Meta (Mac OS) -@cindex keyboard coding (Mac OS) - -@vindex mac-control-modifier -@vindex mac-command-modifier -@vindex mac-option-modifier -@vindex mac-function-modifier - On Mac, Emacs can use @key{control}, @key{command}, @key{option}, and -laptop @key{function} keys as any of Emacs modifier keys except -@key{SHIFT} (i.e., @key{ALT}, @key{CTRL}, @key{HYPER}, @key{META}, and -@key{SUPER}). The assignment is controlled by the variables -@code{mac-control-modifier}, @code{mac-command-modifier}, -@code{mac-option-modifier}, and @code{mac-function-modifier}. The value -for each of these variables can be one of the following symbols: -@code{alt}, @code{control}, @code{hyper}, @code{meta}, @code{super}, and -@code{nil} (no particular assignment). By default, the @key{control} -key works as @key{CTRL}, and the @key{command} key as @key{META}. - - For the @key{option} key, if @code{mac-option-modifier} is set to -@code{nil}, which is the default, the key works as the normal -@key{option} key, i.e., dead-key processing will work. This is useful -for entering non-@acronym{ASCII} Latin characters directly from the -Mac keyboard, for example. - - Emacs recognizes the setting in the Keyboard control panel (Mac OS -Classic) or the International system preference pane (Mac OS X) and -supports international and alternative keyboard layouts (e.g., Dvorak). -Selecting one of the layouts from the keyboard layout pull-down menu -will affect how the keys typed on the keyboard are interpreted. - -@vindex mac-pass-command-to-system -@vindex mac-pass-control-to-system - Mac OS intercepts and handles certain key combinations (e.g., -@key{command}-@key{SPC} for switching input languages). These will not -be passed to Emacs. One can disable this interception by setting -@code{mac-pass-command-to-system} or @code{mac-pass-control-to-system} -to @code{nil}. - -@vindex mac-emulate-three-button-mouse - Especially for one-button mice, the multiple button feature can be -emulated by setting @code{mac-emulate-three-button-mouse} to @code{t} -or @code{reverse}. If set to @code{t} (@code{reverse}, respectively), -pressing the mouse button with the @key{option} key is recognized as -the second (third) button, and that with the @key{command} key is -recognized as the third (second) button. - -@vindex mac-wheel-button-is-mouse-2 - For multi-button mice, the wheel button and the secondary button are -recognized as the second and the third button, respectively. If -@code{mac-wheel-button-is-mouse-2} is set to @code{nil}, their roles -are exchanged. - -@node Mac International -@section International Character Set Support on Mac -@cindex Mac Roman coding system -@cindex clipboard support (Mac OS) - - Mac uses non-standard encodings for the upper 128 single-byte -characters. They also deviate from the ISO 2022 standard by using -character codes in the range 128-159. The coding systems -@code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic} -are used to represent these Mac encodings. - - You can use input methods provided either by LEIM (@pxref{Input -Methods}) or Mac OS to enter international characters. To use the -former, see the International Character Set Support section of the -manual (@pxref{International}). - - Emacs on Mac OS automatically changes the value of -@code{keyboard-coding-system} according to the current keyboard -layout. So users don't need to set it manually, and even if set, it -will be changed when the keyboard layout change is detected next time. - - The Mac clipboard and the Emacs kill ring (@pxref{Killing}) are -synchronized by default: you can yank a piece of text and paste it -into another Mac application, or cut or copy one in another Mac -application and yank it into a Emacs buffer. This feature can be -disabled by setting @code{x-select-enable-clipboard} to @code{nil}. -One can still do copy and paste with another application from the Edit -menu. - - On Mac, the role of the coding system for selection that is set by -@code{set-selection-coding-system} (@pxref{Communication Coding}) is -two-fold. First, it is used as a preferred coding system for the -traditional text flavor that does not specify any particular encodings -and is mainly used by applications on Mac OS Classic. Second, it -specifies the intermediate encoding for the UTF-16 text flavor that is -mainly used by applications on Mac OS X. - - When pasting UTF-16 text data from the clipboard, it is first -converted to the encoding specified by the selection coding system -using the converter in the Mac OS system, and then decoded into the -Emacs internal encoding using the converter in Emacs. If the first -conversion failed, then the UTF-16 data is directly converted to Emacs -internal encoding using the converter in Emacs. Copying UTF-16 text -to the clipboard goes through the inverse path. The reason for this -two-pass decoding is to avoid subtle differences in Unicode mappings -between the Mac OS system and Emacs such as various kinds of hyphens, -and to minimize users' customization. For example, users that mainly -use Latin characters would prefer Greek characters to be decoded into -the @code{mule-unicode-0100-24ff} charset, but Japanese users would -prefer them to be decoded into the @code{japanese-jisx0208} charset. -Since the coding system for selection is automatically set according -to the system locale setting, users usually don't have to set it -manually. - - The default language environment (@pxref{Language Environments}) is -set according to the locale setting at the startup time. On Mac OS, -the locale setting is consulted in the following order: - -@enumerate -@item -Environment variables @env{LC_ALL}, @env{LC_CTYPE} and @env{LANG} as -in other systems. - -@item -Preference @code{AppleLocale} that is set by default on Mac OS X 10.3 -and later. - -@item -Preference @code{AppleLanguages} that is set by default on Mac OS X -10.1 and later. - -@item -Variable @code{mac-system-locale} that is derived from the system -language and region codes. This variable is available on all -supported Mac OS versions including Mac OS Classic. -@end enumerate - - The default values of almost all variables about coding systems are -also set according to the language environment. So usually you don't -have to customize these variables manually. - -@node Mac Environment Variables -@section Environment Variables and Command Line Arguments. -@cindex environment variables (Mac OS) - - On Mac OS X, when Emacs is run in a terminal, it inherits the values -of environment variables from the shell from which it is invoked. -However, when it is run from the Finder as a GUI application, it only -inherits environment variable values defined in the file -@file{~/.MacOSX/environment.plist} that affects all the applications -invoked from the Finder or the @command{open} command. - - Command line arguments are specified like - -@example -/Applications/Emacs.app/Contents/MacOS/Emacs -g 80x25 & -@end example - -@noindent -if Emacs is installed at @file{/Applications/Emacs.app}. If Emacs is -invoked like this, then it also inherits the values of environment -variables from the shell from which it is invoked. - - On Mac OS Classic, environment variables and command line arguments -for Emacs can be set by modifying the @samp{STR#} resources 128 and -129, respectively. A common environment variable that one may want to -set is @samp{HOME}. - - The way to set an environment variable is by adding a string of the -form - -@example -ENV_VAR=VALUE -@end example - -@noindent -to resource @samp{STR#} number 128 using @code{ResEdit}. To set up the -program to use unibyte characters exclusively, for example, add the -string - -@example -EMACS_UNIBYTE=1 -@end example - -@cindex Mac Preferences - Although Emacs on Mac does not support X resources (@pxref{X -Resources}) directly, one can use the Preferences system in place of X -resources. For example, adding the line - -@example -Emacs.cursorType: bar -@end example - -@noindent -to @file{~/.Xresources} in X11 corresponds to the execution of - -@example -defaults write org.gnu.Emacs Emacs.cursorType bar -@end example - -@noindent -on Mac OS X. One can use boolean or numeric values as well as string -values as follows: - -@example -defaults write org.gnu.Emacs Emacs.toolBar -bool false -defaults write org.gnu.Emacs Emacs.lineSpacing -int 3 -@end example - -@noindent -Try @kbd{M-x man RET defaults RET} for the usage of the -@command{defaults} command. Alternatively, if you have Developer -Tools installed on Mac OS X, you can use Property List Editor to edit -the file @file{~/Library/Preferences/org.gnu.Emacs.plist}. - - -@node Mac Directories -@section Volumes and Directories on Mac -@cindex file names (Mac OS) - - This node applies to Mac OS Classic only. - - The directory structure in Mac OS Classic is seen by Emacs as - -@example -/@var{volumename}/@var{filename} -@end example - -So when Emacs requests a file name, doing file name completion on -@file{/} will display all volumes on the system. You can use @file{..} -to go up a directory level. - - On Mac OS Classic, to access files and folders on the desktop, look -in the folder @file{Desktop Folder} in your boot volume (this folder -is usually invisible in the Mac @code{Finder}). - - On Mac OS Classic, Emacs creates the Mac folder -@file{:Preferences:Emacs:} in the @file{System Folder} and uses it as -the temporary directory. Emacs maps the directory name @file{/tmp/} -to that. Therefore it is best to avoid naming a volume @file{tmp}. -If everything works correctly, the program should leave no files in it -when it exits. You should be able to set the environment variable -@code{TMPDIR} to use another directory but this folder will still be -created. - - -@node Mac Font Specs -@section Specifying Fonts on Mac -@cindex font names (Mac OS) - - It is rare that you need to specify a font name in Emacs; usually -you specify face attributes instead. For example, you can use 14pt -Courier by customizing the default face attributes for all frames: - -@lisp -(set-face-attribute 'default nil - :family "courier" :height 140) -@end lisp - -@noindent -Alternatively, an interactive one is also available -(@pxref{Face Customization}). - -But when you do need to specify a font name in Emacs on Mac, use a -standard X font name: - -@smallexample --@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} -@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset} -@end smallexample - -@noindent -@xref{Font X}. Wildcards are supported as they are on X. - - Emacs on Mac OS Classic uses QuickDraw Text routines for drawing texts -by default. Emacs on Mac OS X uses @acronym{ATSUI, Apple Type Services -for Unicode Imaging} as well as QuickDraw Text, and most of the -characters other than Chinese, Japanese, and Korean ones are drawn using -the former by default. - - @acronym{ATSUI}-compatible fonts have maker name @code{apple} and -charset @code{iso10646-1}. For example, 12-point Monaco can be specified -by the name: - -@example --apple-monaco-medium-r-normal--12-*-*-*-*-*-iso10646-1 -@end example - -Note that these names must be specified using a format containing all -14 @samp{-}s (not by -@samp{-apple-monaco-medium-r-normal--12-*-iso10646-1}, for instance), -because every @acronym{ATSUI}-compatible font is a scalable one. - - QuickDraw Text fonts have maker name @code{apple} and various charset -names other than @code{iso10646-1}. Native Apple fonts in Mac Roman -encoding has charset @code{mac-roman}. You can specify a -@code{mac-roman} font for @acronym{ASCII} characters like - -@smalllisp -(add-to-list - 'default-frame-alist - '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman")) -@end smalllisp - -@noindent -but that does not extend to ISO-8859-1: specifying a @code{mac-roman} -font for Latin-1 characters introduces wrong glyphs. - - Native Apple Traditional Chinese, Simplified Chinese, Japanese, -Korean, Central European, Cyrillic, Symbol, and Dingbats fonts have -the charsets @samp{big5-0}, @samp{gb2312.1980-0}, -@samp{jisx0208.1983-sjis} and @samp{jisx0201.1976-0}, -@samp{ksc5601.1989-0}, @samp{mac-centraleurroman}, -@samp{mac-cyrillic}, @samp{mac-symbol}, and @samp{mac-dingbats}, -respectively. - - The use of @code{create-fontset-from-fontset-spec} (@pxref{Defining -Fontsets}) for defining fontsets often results in wrong ones especially -when using only OS-bundled QuickDraw Text fonts. The recommended way to -use them is to create a fontset using -@code{create-fontset-from-mac-roman-font}: - -@lisp -(create-fontset-from-mac-roman-font - "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman" - nil "foo") -@end lisp - -@noindent -and then optionally specifying Chinese, Japanese, or Korean font -families using @code{set-fontset-font}: - -@lisp -(set-fontset-font "fontset-foo" - 'chinese-gb2312 '("song" . "gb2312.1980-0")) -@end lisp - - Single-byte fonts converted from GNU fonts in BDF format, which are not -in the Mac Roman encoding, have foundry, family, and character sets -encoded in the names of their font suitcases. E.g., the font suitcase -@samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by -the name @samp{-ETL-fixed-*-iso8859-1}. - -@vindex mac-allow-anti-aliasing - Mac OS X 10.2 or later can use two types of text renderings: Quartz 2D -(aka Core Graphics) and QuickDraw. By default, Emacs uses the former on -such versions. It can be changed by setting -@code{mac-allow-anti-aliasing} to @code{t} (Quartz 2D) or @code{nil} -(QuickDraw). Both @acronym{ATSUI} and QuickDraw Text drawings are -affected by the value of this variable. - - Appearance of text in small sizes will also be affected by the ``Turn -off text smoothing for font sizes @var{n} and smaller'' setting in the -General pane (Mac OS X 10.1 or 10.2) or in the Appearance pane (10.3 or -later) of the System Preferences. This threshold can alternatively be -set just for Emacs (i.e., not as the system-wide setting) using the -@command{defaults} command: - -@example -defaults write org.gnu.Emacs AppleAntiAliasingThreshold @var{n} -@end example - - -@node Mac Functions -@section Mac-Specific Lisp Functions -@cindex Lisp functions specific to Mac OS - -@findex do-applescript - The function @code{do-applescript} takes a string argument, -executes it as an AppleScript command, and returns the result as a -string. - -@findex mac-file-name-to-posix -@findex posix-file-name-to-mac - The function @code{mac-file-name-to-posix} takes a Mac file name and -returns the GNU or Unix equivalent. The function -@code{posix-file-name-to-mac} performs the opposite conversion. They -are useful for constructing AppleScript commands to be passed to -@code{do-applescript}. - -@findex mac-set-file-creator -@findex mac-get-file-creator -@findex mac-set-file-type -@findex mac-get-file-type - The functions @code{mac-set-file-creator}, -@code{mac-get-file-creator}, @code{mac-set-file-type}, and -@code{mac-get-file-type} can be used to set and get creator and file -codes. - -@findex mac-get-preference - The function @code{mac-get-preference} returns the preferences value -converted to a Lisp object for a specified key and application. - -@ignore - arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6 -@end ignore diff --git a/man/maintaining.texi b/man/maintaining.texi deleted file mode 100644 index 988d5890b8c..00000000000 --- a/man/maintaining.texi +++ /dev/null @@ -1,862 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Maintaining, Abbrevs, Building, Top -@chapter Maintaining Large Programs - - This chapter describes Emacs features for maintaining large -programs. The version control features (@pxref{Version Control}) are -also particularly useful for this purpose. - -@menu -* Change Log:: Maintaining a change history for your program. -* Format of ChangeLog:: What the change log file looks like. -* Tags:: Go direct to any function in your program in one - command. Tags remembers which file it is in. -@ifnottex -* Emerge:: A convenient way of merging two versions of a program. -@end ifnottex -@end menu - -@node Change Log -@section Change Logs - - A change log file contains a chronological record of when and why you -have changed a program, consisting of a sequence of entries describing -individual changes. Normally it is kept in a file called -@file{ChangeLog} in the same directory as the file you are editing, or -one of its parent directories. A single @file{ChangeLog} file can -record changes for all the files in its directory and all its -subdirectories. - -@cindex change log -@kindex C-x 4 a -@findex add-change-log-entry-other-window - The Emacs command @kbd{C-x 4 a} adds a new entry to the change log -file for the file you are editing -(@code{add-change-log-entry-other-window}). If that file is actually -a backup file, it makes an entry appropriate for the file's -parent---that is useful for making log entries for functions that -have been deleted in the current version. - - @kbd{C-x 4 a} visits the change log file and creates a new entry -unless the most recent entry is for today's date and your name. It -also creates a new item for the current file. For many languages, it -can even guess the name of the function or other object that was -changed. - -@vindex add-log-keep-changes-together - When the variable @code{add-log-keep-changes-together} is -non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file -rather than starting a new item. - -@vindex add-log-always-start-new-record - If @code{add-log-always-start-new-record} is non-@code{nil}, -@kbd{C-x 4 a} always makes a new entry, even if the last entry -was made by you and on the same date. - -@vindex change-log-version-info-enabled -@vindex change-log-version-number-regexp-list -@cindex file version in change log entries - If the value of the variable @code{change-log-version-info-enabled} -is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the -change log entry. It finds the version number by searching the first -ten percent of the file, using regular expressions from the variable -@code{change-log-version-number-regexp-list}. - -@cindex Change Log mode -@findex change-log-mode - The change log file is visited in Change Log mode. In this major -mode, each bunch of grouped items counts as one paragraph, and each -entry is considered a page. This facilitates editing the entries. -@kbd{C-j} and auto-fill indent each new line like the previous line; -this is convenient for entering the contents of an entry. - -@findex change-log-merge - You can use the command @kbd{M-x change-log-merge} to merge other -log files into a buffer in Change Log Mode, preserving the date -ordering of entries. - - Version control systems are another way to keep track of changes in your -program and keep a change log. @xref{Log Buffer}. - -@node Format of ChangeLog -@section Format of ChangeLog - - A change log entry starts with a header line that contains the current -date, your name, and your email address (taken from the variable -@code{add-log-mailing-address}). Aside from these header lines, every -line in the change log starts with a space or a tab. The bulk of the -entry consists of @dfn{items}, each of which starts with a line starting -with whitespace and a star. Here are two entries, both dated in May -1993, with two items and one item respectively. - -@iftex -@medbreak -@end iftex -@smallexample -1993-05-25 Richard Stallman - - * man.el: Rename symbols `man-*' to `Man-*'. - (manual-entry): Make prompt string clearer. - - * simple.el (blink-matching-paren-distance): - Change default to 12,000. - -1993-05-24 Richard Stallman - - * vc.el (minor-mode-map-alist): Don't use it if it's void. - (vc-cancel-version): Doc fix. -@end smallexample - - One entry can describe several changes; each change should have its -own item, or its own line in an item. Normally there should be a -blank line between items. When items are related (parts of the same -change, in different places), group them by leaving no blank line -between them. - - You should put a copyright notice and permission notice at the -end of the change log file. Here is an example: - -@smallexample -Copyright 1997, 1998 Free Software Foundation, Inc. -Copying and distribution of this file, with or without modification, are -permitted provided the copyright notice and this notice are preserved. -@end smallexample - -@noindent -Of course, you should substitute the proper years and copyright holder. - -@node Tags -@section Tags Tables -@cindex tags table - - A @dfn{tags table} is a description of how a multi-file program is -broken up into files. It lists the names of the component files and the -names and positions of the functions (or other named subunits) in each -file. Grouping the related files makes it possible to search or replace -through all the files with one command. Recording the function names -and positions makes possible the @kbd{M-.} command which finds the -definition of a function by looking up which of the files it is in. - - Tags tables are stored in files called @dfn{tags table files}. The -conventional name for a tags table file is @file{TAGS}. - - Each entry in the tags table records the name of one tag, the name of the -file that the tag is defined in (implicitly), and the position in that -file of the tag's definition. When a file parsed by @code{etags} is -generated from a different source file, like a C file generated from a -Cweb source file, the tags of the parsed file reference the source -file. - - Just what names from the described files are recorded in the tags table -depends on the programming language of the described file. They -normally include all file names, functions and subroutines, and may -also include global variables, data types, and anything else -convenient. Each name recorded is called a @dfn{tag}. - -@cindex C++ class browser, tags -@cindex tags, C++ -@cindex class browser, C++ -@cindex Ebrowse - See also the Ebrowse facility, which is tailored for C++. -@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}. - -@menu -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @code{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Listing and finding tags defined in a file. -@end menu - -@node Tag Syntax -@subsection Source File Tag Syntax - - Here is how tag syntax is defined for the most popular languages: - -@itemize @bullet -@item -In C code, any C function or typedef is a tag, and so are definitions of -@code{struct}, @code{union} and @code{enum}. -@code{#define} macro definitions, @code{#undef} and @code{enum} -constants are also -tags, unless you specify @samp{--no-defines} when making the tags table. -Similarly, global variables are tags, unless you specify -@samp{--no-globals}, and so are struct members, unless you specify -@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines} -and @samp{--no-members} can make the tags table file much smaller. - -You can tag function declarations and external variables in addition -to function definitions by giving the @samp{--declarations} option to -@code{etags}. - -@item -In C++ code, in addition to all the tag constructs of C code, member -functions are also recognized; member variables are also recognized, -unless you use the @samp{--no-members} option. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. @code{operator} definitions have -tag names like @samp{operator+}. - -@item -In Java code, tags include all the constructs recognized in C++, plus -the @code{interface}, @code{extends} and @code{implements} constructs. -Tags for variables and functions in classes are named -@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. - -@item -In La@TeX{} text, the argument of any of the commands @code{\chapter}, -@code{\section}, @code{\subsection}, @code{\subsubsection}, -@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, -@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, -@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, -@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill - -Other commands can make tags as well, if you specify them in the -environment variable @env{TEXTAGS} before invoking @code{etags}. The -value of this environment variable should be a colon-separated list of -command names. For example, - -@example -TEXTAGS="mycommand:myothercommand" -export TEXTAGS -@end example - -@noindent -specifies (using Bourne shell syntax) that the commands -@samp{\mycommand} and @samp{\myothercommand} also define tags. - -@item -In Lisp code, any function defined with @code{defun}, any variable -defined with @code{defvar} or @code{defconst}, and in general the first -argument of any expression that starts with @samp{(def} in column zero is -a tag. - -@item -In Scheme code, tags include anything defined with @code{def} or with a -construct whose name starts with @samp{def}. They also include variables -set with @code{set!} at top level in the file. -@end itemize - - Several other languages are also supported: - -@itemize @bullet - -@item -In Ada code, functions, procedures, packages, tasks and types are -tags. Use the @samp{--packages-only} option to create tags for -packages only. - -In Ada, the same name can be used for different kinds of entity -(e.g.@:, for a procedure and for a function). Also, for things like -packages, procedures and functions, there is the spec (i.e.@: the -interface) and the body (i.e.@: the implementation). To make it -easier to pick the definition you want, Ada tag name have suffixes -indicating the type of entity: - -@table @samp -@item /b -package body. -@item /f -function. -@item /k -task. -@item /p -procedure. -@item /s -package spec. -@item /t -type. -@end table - - Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go -directly to the body of the package @code{bidule}, while @kbd{M-x -find-tag @key{RET} bidule @key{RET}} will just search for any tag -@code{bidule}. - -@item -In assembler code, labels appearing at the beginning of a line, -followed by a colon, are tags. - -@item -In Bison or Yacc input files, each rule defines as a tag the nonterminal -it constructs. The portions of the file that contain C code are parsed -as C code. - -@item -In Cobol code, tags are paragraph names; that is, any word starting in -column 8 and followed by a period. - -@item -In Erlang code, the tags are the functions, records and macros defined -in the file. - -@item -In Fortran code, functions, subroutines and block data are tags. - -@item -In HTML input files, the tags are the @code{title} and the @code{h1}, -@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors -and all occurrences of @code{id=}. - -@item -In Lua input files, all functions are tags. - -@item -In makefiles, targets are tags; additionally, variables are tags -unless you specify @samp{--no-globals}. - -@item -In Objective C code, tags include Objective C definitions for classes, -class categories, methods and protocols. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. - -@item -In Pascal code, the tags are the functions and procedures defined in -the file. - -@item -In Perl code, the tags are the packages, subroutines and variables -defined by the @code{package}, @code{sub}, @code{my} and @code{local} -keywords. Use @samp{--globals} if you want to tag global variables. -Tags for subroutines are named @samp{@var{package}::@var{sub}}. The -name for subroutines defined in the default package is -@samp{main::@var{sub}}. - -@item -In PHP code, tags are functions, classes and defines. Vars are tags -too, unless you use the @samp{--no-members} option. - -@item -In PostScript code, the tags are the functions. - -@item -In Prolog code, tags are predicates and rules at the beginning of -line. - -@item -In Python code, @code{def} or @code{class} at the beginning of a line -generate a tag. -@end itemize - - You can also generate tags based on regexp matching (@pxref{Etags -Regexps}) to handle other formats and languages. - -@node Create Tags Table -@subsection Creating Tags Tables -@cindex @code{etags} program - - The @code{etags} program is used to create a tags table file. It knows -the syntax of several languages, as described in -@iftex -the previous section. -@end iftex -@ifnottex -@ref{Tag Syntax}. -@end ifnottex -Here is how to run @code{etags}: - -@example -etags @var{inputfiles}@dots{} -@end example - -@noindent -The @code{etags} program reads the specified files, and writes a tags -table named @file{TAGS} in the current working directory. - - If the specified files don't exist, @code{etags} looks for -compressed versions of them and uncompresses them to read them. Under -MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz} -if it is given @samp{mycode.c} on the command line and @file{mycode.c} -does not exist. - - @code{etags} recognizes the language used in an input file based on -its file name and contents. You can specify the language with the -@samp{--language=@var{name}} option, described below. - - If the tags table data become outdated due to changes in the files -described in the table, the way to update the tags table is the same -way it was made in the first place. If the tags table fails to record -a tag, or records it for the wrong file, then Emacs cannot possibly -find its definition until you update the tags table. However, if the -position recorded in the tags table becomes a little bit wrong (due to -other editing), the worst consequence is a slight delay in finding the -tag. Even if the stored position is very far wrong, Emacs will still -find the tag, after searching most of the file for it. That delay is -hardly noticeable with today's computers. - - Thus, there is no need to update the tags table after each edit. -You should update a tags table when you define new tags that you want -to have listed, or when you move tag definitions from one file to -another, or when changes become substantial. - - One tags table can virtually include another. Specify the included -tags file name with the @samp{--include=@var{file}} option when -creating the file that is to include it. The latter file then acts as -if it covered all the source files specified in the included file, as -well as the files it directly contains. - - If you specify the source files with relative file names when you run -@code{etags}, the tags file will contain file names relative to the -directory where the tags file was initially written. This way, you can -move an entire directory tree containing both the tags file and the -source files, and the tags file will still refer correctly to the source -files. If the tags file is in @file{/dev}, however, the file names are -made relative to the current working directory. This is useful, for -example, when writing the tags to @file{/dev/stdout}. - - When using a relative file name, it should not be a symbolic link -pointing to a tags file in a different directory, because this would -generally render the file names invalid. - - If you specify absolute file names as arguments to @code{etags}, then -the tags file will contain absolute file names. This way, the tags file -will still refer to the same files even if you move it, as long as the -source files remain in the same place. Absolute file names start with -@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. - - When you want to make a tags table from a great number of files, you -may have problems listing them on the command line, because some systems -have a limit on its length. The simplest way to circumvent this limit -is to tell @code{etags} to read the file names from its standard input, -by typing a dash in place of the file names, like this: - -@smallexample -find . -name "*.[chCH]" -print | etags - -@end smallexample - - Use the option @samp{--language=@var{name}} to specify the language -explicitly. You can intermix these options with file names; each one -applies to the file names that follow it. Specify -@samp{--language=auto} to tell @code{etags} to resume guessing the -language from the file names and file contents. Specify -@samp{--language=none} to turn off language-specific processing -entirely; then @code{etags} recognizes tags by regexp matching alone -(@pxref{Etags Regexps}). - - The option @samp{--parse-stdin=@var{file}} is mostly useful when -calling @code{etags} from programs. It can be used (only once) in -place of a file name on the command line. @code{Etags} will read from -standard input and mark the produced tags as belonging to the file -@var{file}. - - @samp{etags --help} outputs the list of the languages @code{etags} -knows, and the file name rules for guessing the language. It also prints -a list of all the available @code{etags} options, together with a short -explanation. If followed by one or more @samp{--language=@var{lang}} -options, it outputs detailed information about how tags are generated for -@var{lang}. - -@node Etags Regexps -@subsection Etags Regexps - - The @samp{--regex} option provides a general way of recognizing tags -based on regexp matching. You can freely intermix this option with -file names, and each one applies to the source files that follow it. -If you specify multiple @samp{--regex} options, all of them are used -in parallel. The syntax is: - -@smallexample ---regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} -@end smallexample - - The essential part of the option value is @var{tagregexp}, the -regexp for matching tags. It is always used anchored, that is, it -only matches at the beginning of a line. If you want to allow -indented tags, use a regexp that matches initial whitespace; start it -with @samp{[ \t]*}. - - In these regular expressions, @samp{\} quotes the next character, and -all the GCC character escape sequences are supported (@samp{\a} for -bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for -escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for -carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). - - Ideally, @var{tagregexp} should not match more characters than are -needed to recognize what you want to tag. If the syntax requires you -to write @var{tagregexp} so it matches more characters beyond the tag -itself, you should add a @var{nameregexp}, to pick out just the tag. -This will enable Emacs to find tags more accurately and to do -completion on tag names more reliably. You can find some examples -below. - - The @var{modifiers} are a sequence of zero or more characters that -modify the way @code{etags} does the matching. A regexp with no -modifiers is applied sequentially to each line of the input file, in a -case-sensitive way. The modifiers and their meanings are: - -@table @samp -@item i -Ignore case when matching this regexp. -@item m -Match this regular expression against the whole file, so that -multi-line matches are possible. -@item s -Match this regular expression against the whole file, and allow -@samp{.} in @var{tagregexp} to match newlines. -@end table - - The @samp{-R} option cancels all the regexps defined by preceding -@samp{--regex} options. It too applies to the file names following -it. Here's an example: - -@smallexample -etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ - bar.ber -R --lang=lisp los.er -@end smallexample - -@noindent -Here @code{etags} chooses the parsing language for @file{voo.doo} and -@file{bar.ber} according to their contents. @code{etags} also uses -@var{reg1} to recognize additional tags in @file{voo.doo}, and both -@var{reg1} and @var{reg2} to recognize additional tags in -@file{bar.ber}. @var{reg1} is checked against each line of -@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while -@var{reg2} is checked against the whole @file{bar.ber} file, -permitting multi-line matches, in a case-sensitive way. @code{etags} -uses only the Lisp tags rules, with no user-specified regexp matching, -to recognize tags in @file{los.er}. - - You can restrict a @samp{--regex} option to match only files of a -given language by using the optional prefix @var{@{language@}}. -(@samp{etags --help} prints the list of languages recognized by -@code{etags}.) This is particularly useful when storing many -predefined regular expressions for @code{etags} in a file. The -following example tags the @code{DEFVAR} macros in the Emacs source -files, for the C language only: - -@smallexample ---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' -@end smallexample - -@noindent -When you have complex regular expressions, you can store the list of -them in a file. The following option syntax instructs @code{etags} to -read two files of regular expressions. The regular expressions -contained in the second file are matched without regard to case. - -@smallexample ---regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} -@end smallexample - -@noindent -A regex file for @code{etags} contains one regular expression per -line. Empty lines, and lines beginning with space or tab are ignored. -When the first character in a line is @samp{@@}, @code{etags} assumes -that the rest of the line is the name of another file of regular -expressions; thus, one such file can include another file. All the -other lines are taken to be regular expressions. If the first -non-whitespace text on the line is @samp{--}, that line is a comment. - - For example, we can create a file called @samp{emacs.tags} with the -following contents: - -@smallexample - -- This is for GNU Emacs C source files -@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ -@end smallexample - -@noindent -and then use it like this: - -@smallexample -etags --regex=@@emacs.tags *.[ch] */*.[ch] -@end smallexample - - Here are some more examples. The regexps are quoted to protect them -from shell interpretation. - -@itemize @bullet - -@item -Tag Octave files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ - --regex='/###key \(.*\)/\1/' \ - --regex='/[ \t]*global[ \t].*/' \ - *.m -@end smallexample - -@noindent -Note that tags are not generated for scripts, so that you have to add -a line by yourself of the form @samp{###key @var{scriptname}} if you -want to jump to it. - -@item -Tag Tcl files: - -@smallexample -etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl -@end smallexample - -@item -Tag VHDL files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ - --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ - \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' -@end smallexample -@end itemize - -@node Select Tags Table -@subsection Selecting a Tags Table - -@vindex tags-file-name -@findex visit-tags-table - Emacs has at any time one @dfn{selected} tags table, and all the -commands for working with tags tables use the selected one. To select -a tags table, type @kbd{M-x visit-tags-table}, which reads the tags -table file name as an argument, with @file{TAGS} in the default -directory as the default. - - Emacs does not actually read in the tags table contents until you -try to use them; all @code{visit-tags-table} does is store the file -name in the variable @code{tags-file-name}, and setting the variable -yourself is just as good. The variable's initial value is @code{nil}; -that value tells all the commands for working with tags tables that -they must ask for a tags table file name to use. - - Using @code{visit-tags-table} when a tags table is already loaded -gives you a choice: you can add the new tags table to the current list -of tags tables, or start a new list. The tags commands use all the tags -tables in the current list. If you start a new list, the new tags table -is used @emph{instead} of others. If you add the new table to the -current list, it is used @emph{as well as} the others. - -@vindex tags-table-list - You can specify a precise list of tags tables by setting the variable -@code{tags-table-list} to a list of strings, like this: - -@c keep this on two lines for formatting in smallbook -@example -@group -(setq tags-table-list - '("~/emacs" "/usr/local/lib/emacs/src")) -@end group -@end example - -@noindent -This tells the tags commands to look at the @file{TAGS} files in your -@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} -directory. The order depends on which file you are in and which tags -table mentions that file, as explained above. - - Do not set both @code{tags-file-name} and @code{tags-table-list}. - -@node Find Tag -@subsection Finding a Tag - - The most important thing that a tags table enables you to do is to find -the definition of a specific tag. - -@table @kbd -@item M-.@: @var{tag} @key{RET} -Find first definition of @var{tag} (@code{find-tag}). -@item C-u M-. -Find next alternate definition of last tag specified. -@item C-u - M-. -Go back to previous tag found. -@item C-M-. @var{pattern} @key{RET} -Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). -@item C-u C-M-. -Find the next tag whose name matches the last pattern used. -@item C-x 4 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, but display it in another window -(@code{find-tag-other-window}). -@item C-x 5 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, and create a new frame to select the -buffer (@code{find-tag-other-frame}). -@item M-* -Pop back to where you previously invoked @kbd{M-.} and friends. -@end table - -@kindex M-. -@findex find-tag - @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of -a specified tag. It searches through the tags table for that tag, as a -string, and then uses the tags table info to determine the file that the -definition is in and the approximate character position in the file of -the definition. Then @code{find-tag} visits that file, moves point to -the approximate character position, and searches ever-increasing -distances away to find the tag definition. - - If an empty argument is given (just type @key{RET}), the balanced -expression in the buffer before or around point is used as the -@var{tag} argument. @xref{Expressions}. - - You don't need to give @kbd{M-.} the full name of the tag; a part -will do. This is because @kbd{M-.} finds tags in the table which -contain @var{tag} as a substring. However, it prefers an exact match -to a substring match. To find other tags that match the same -substring, give @code{find-tag} a numeric argument, as in @kbd{C-u -M-.}; this does not read a tag name, but continues searching the tags -table's text for another tag containing the same substring last used. -If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier -alternative to @kbd{C-u M-.}. - -@kindex C-x 4 . -@findex find-tag-other-window -@kindex C-x 5 . -@findex find-tag-other-frame - Like most commands that can switch buffers, @code{find-tag} has a -variant that displays the new buffer in another window, and one that -makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes -the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}}, -which invokes @code{find-tag-other-frame}. - - To move back to places you've found tags recently, use @kbd{C-u - -M-.}; more generally, @kbd{M-.} with a negative numeric argument. This -command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative -argument finds the previous tag location in another window. - -@kindex M-* -@findex pop-tag-mark -@vindex find-tag-marker-ring-length - As well as going back to places you've found tags recently, you can go -back to places @emph{from where} you found them. Use @kbd{M-*}, which -invokes the command @code{pop-tag-mark}, for this. Typically you would -find and study the definition of something with @kbd{M-.} and then -return to where you were with @kbd{M-*}. - - Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to -a depth determined by the variable @code{find-tag-marker-ring-length}. - -@findex find-tag-regexp -@kindex C-M-. - The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that -match a specified regular expression. It is just like @kbd{M-.} except -that it does regexp matching instead of substring matching. - -@node Tags Search -@subsection Searching and Replacing with Tags Tables -@cindex search and replace in multiple files -@cindex multiple-file search and replace - - The commands in this section visit and search all the files listed -in the selected tags table, one by one. For these commands, the tags -table serves only to specify a sequence of files to search. These -commands scan the list of tags tables starting with the first tags -table (if any) that describes the current file, proceed from there to -the end of the list, and then scan from the beginning of the list -until they have covered all the tables in the list. - -@table @kbd -@item M-x tags-search @key{RET} @var{regexp} @key{RET} -Search for @var{regexp} through the files in the selected tags -table. -@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} -Perform a @code{query-replace-regexp} on each file in the selected tags table. -@item M-, -Restart one of the commands above, from the current location of point -(@code{tags-loop-continue}). -@end table - -@findex tags-search - @kbd{M-x tags-search} reads a regexp using the minibuffer, then -searches for matches in all the files in the selected tags table, one -file at a time. It displays the name of the file being searched so you -can follow its progress. As soon as it finds an occurrence, -@code{tags-search} returns. - -@kindex M-, -@findex tags-loop-continue - Having found one match, you probably want to find all the rest. To find -one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the -@code{tags-search}. This searches the rest of the current buffer, followed -by the remaining files of the tags table.@refill - -@findex tags-query-replace - @kbd{M-x tags-query-replace} performs a single -@code{query-replace-regexp} through all the files in the tags table. It -reads a regexp to search for and a string to replace with, just like -ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x -tags-search}, but repeatedly, processing matches according to your -input. @xref{Replace}, for more information on query replace. - -@vindex tags-case-fold-search -@cindex case-sensitivity and tags search - You can control the case-sensitivity of tags search commands by -customizing the value of the variable @code{tags-case-fold-search}. The -default is to use the same setting as the value of -@code{case-fold-search} (@pxref{Search Case}). - - It is possible to get through all the files in the tags table with a -single invocation of @kbd{M-x tags-query-replace}. But often it is -useful to exit temporarily, which you can do with any input event that -has no special query replace meaning. You can resume the query replace -subsequently by typing @kbd{M-,}; this command resumes the last tags -search or replace command that you did. - - The commands in this section carry out much broader searches than the -@code{find-tag} family. The @code{find-tag} commands search only for -definitions of tags that match your substring or regexp. The commands -@code{tags-search} and @code{tags-query-replace} find every occurrence -of the regexp, as ordinary search commands and replace commands do in -the current buffer. - - These commands create buffers only temporarily for the files that they -have to search (those which are not already visited in Emacs buffers). -Buffers in which no match is found are quickly killed; the others -continue to exist. - - It may have struck you that @code{tags-search} is a lot like -@code{grep}. You can also run @code{grep} itself as an inferior of -Emacs and have Emacs show you the matching lines one by one. -@xref{Grep Searching}. - -@node List Tags -@subsection Tags Table Inquiries - -@table @kbd -@item M-x list-tags @key{RET} @var{file} @key{RET} -Display a list of the tags defined in the program file @var{file}. -@item M-x tags-apropos @key{RET} @var{regexp} @key{RET} -Display a list of all tags matching @var{regexp}. -@end table - -@findex list-tags - @kbd{M-x list-tags} reads the name of one of the files described by -the selected tags table, and displays a list of all the tags defined in -that file. The ``file name'' argument is really just a string to -compare against the file names recorded in the tags table; it is read as -a string rather than as a file name. Therefore, completion and -defaulting are not available, and you must enter the file name the same -way it appears in the tags table. Do not include a directory as part of -the file name unless the file name recorded in the tags table includes a -directory. - -@findex tags-apropos -@vindex tags-apropos-verbose - @kbd{M-x tags-apropos} is like @code{apropos} for tags -(@pxref{Apropos}). It finds all the tags in the selected tags table -whose entries match @var{regexp}, and displays them. If the variable -@code{tags-apropos-verbose} is non-@code{nil}, it displays the names -of the tags files together with the tag names. - -@vindex tags-tag-face -@vindex tags-apropos-additional-actions - You can customize the appearance of the output by setting the -variable @code{tags-tag-face} to a face. You can display additional -output with @kbd{M-x tags-apropos} by customizing the variable -@code{tags-apropos-additional-actions}---see its documentation for -details. - - You can also use the collection of tag names to complete a symbol -name in the buffer. @xref{Symbol Completion}. - -@ifnottex -@include emerge-xtra.texi -@end ifnottex - -@ignore - arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb -@end ignore diff --git a/man/major.texi b/man/major.texi deleted file mode 100644 index 1cb76ee5fdf..00000000000 --- a/man/major.texi +++ /dev/null @@ -1,206 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Major Modes, Indentation, International, Top -@chapter Major Modes -@cindex major modes -@cindex mode, major -@kindex TAB @r{(and major modes)} -@kindex DEL @r{(and major modes)} -@kindex C-j @r{(and major modes)} - - Emacs provides many alternative @dfn{major modes}, each of which -customizes Emacs for editing text of a particular sort. The major modes -are mutually exclusive, and each buffer has one major mode at any time. -The mode line normally shows the name of the current major mode, in -parentheses (@pxref{Mode Line}). - - The least specialized major mode is called @dfn{Fundamental mode}. -This mode has no mode-specific redefinitions or variable settings, so -that each Emacs command behaves in its most general manner, and each -user option variable is in its default state. For editing text of a -specific type that Emacs knows about, such as Lisp code or English -text, you should switch to the appropriate major mode, such as Lisp -mode or Text mode. - - Selecting a major mode changes the meanings of a few keys to become -more specifically adapted to the language being edited. The ones that -are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}. The -prefix key @kbd{C-c} normally contains mode-specific commands. In -addition, the commands which handle comments use the mode to determine -how comments are to be delimited. Many major modes redefine the -syntactical properties of characters appearing in the buffer. -@xref{Syntax}. - - The major modes fall into three major groups. The first group -contains modes for normal text, either plain or with mark-up. It -includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline -mode. The second group contains modes for specific programming -languages. These include Lisp mode (which has several variants), C -mode, Fortran mode, and others. The remaining major modes are not -intended for use on users' files; they are used in buffers created for -specific purposes by Emacs, such as Dired mode for buffers made by -Dired (@pxref{Dired}), Mail mode for buffers made by @kbd{C-x m} -(@pxref{Sending Mail}), and Shell mode for buffers used for -communicating with an inferior shell process (@pxref{Interactive -Shell}). - - Most programming-language major modes specify that only blank lines -separate paragraphs. This is to make the paragraph commands useful. -(@xref{Paragraphs}.) They also cause Auto Fill mode to use the -definition of @key{TAB} to indent the new lines it creates. This is -because most lines in a program are usually indented -(@pxref{Indentation}). - -@menu -* Choosing Modes:: How major modes are specified or chosen. -@end menu - -@node Choosing Modes,,Major Modes,Major Modes -@section How Major Modes are Chosen - -@cindex choosing a major mode - You can select a major mode explicitly for the current buffer, but -most of the time Emacs determines which mode to use based on the file -name or on special text in the file. - - To explicitly select a new major, you use an @kbd{M-x} command. -Take the name of a major mode and add @code{-mode} to get the name of -the command to select that mode. Thus, you can enter Lisp mode by -executing @kbd{M-x lisp-mode}. - -@vindex auto-mode-alist - When you visit a file, Emacs usually chooses the right major mode based -on the file's name. For example, files whose names end in @samp{.c} are -edited in C mode. The correspondence between file names and major modes is -controlled by the variable @code{auto-mode-alist}. Its value is a list in -which each element has this form, - -@example -(@var{regexp} . @var{mode-function}) -@end example - -@noindent -or this form, - -@example -(@var{regexp} @var{mode-function} @var{flag}) -@end example - -@noindent -For example, one element normally found in the list has the form -@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C -mode for files whose names end in @file{.c}. (Note that @samp{\\} is -needed in Lisp syntax to include a @samp{\} in the string, which must -be used to suppress the special meaning of @samp{.} in regexps.) If -the element has the form @code{(@var{regexp} @var{mode-function} -@var{flag})} and @var{flag} is non-@code{nil}, then after calling -@var{mode-function}, Emacs discards the suffix that matched -@var{regexp} and searches the list again for another match. - -@vindex magic-mode-alist - Sometimes the major mode is determined from the way the file's text -begins. The variable @code{magic-mode-alist} controls this. Its value -is a list of elements of these forms: - -@example -(@var{regexp} . @var{mode-function}) -(@var{match-function} . @var{mode-function}) -@end example - -@noindent -The first form looks like an element of @code{auto-mode-alist}, but it -doesn't work the same: this @var{regexp} is matched against the text -at the start of the buffer, not against the file name. Likewise, the -second form calls @var{match-function} at the beginning of the buffer, -and if the function returns non-@code{nil}, the @var{mode-function} is -called. @code{magic-mode-alist} takes priority over -@code{auto-mode-alist}. - - You can specify the major mode to use for editing a certain file by -special text in the first nonblank line of the file. The -mode name should appear in this line both preceded and followed by -@samp{-*-}. Other text may appear on the line as well. For example, - -@example -;-*-Lisp-*- -@end example - -@noindent -tells Emacs to use Lisp mode. Such an explicit specification overrides -any defaults based on the file name. Note how the semicolon is used -to make Lisp treat this line as a comment. - - Another format of mode specification is - -@example --*- mode: @var{modename};-*- -@end example - -@noindent -which allows you to specify local variables as well, like this: - -@example --*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- -@end example - -@noindent -@xref{File Variables}, for more information about this. - -@vindex auto-mode-case-fold - On systems with case-insensitive file names, only a single -case-insensitive search through the @code{auto-mode-alist} is made. -On other systems, Emacs normally performs a single case-sensitive -search through the alist, but if you set this variable to a -non-@code{nil} value, Emacs will perform a second case-insensitive -search if the first search fails. - -@vindex interpreter-mode-alist - When a file's contents begin with @samp{#!}, it can serve as an -executable shell command, which works by running an interpreter named on -the file's first line. The rest of the file is used as input to the -interpreter. - - When you visit such a file in Emacs, if the file's name does not -specify a major mode, Emacs uses the interpreter name on the first line -to choose a mode. If the first line is the name of a recognized -interpreter program, such as @samp{perl} or @samp{tcl}, Emacs uses a -mode appropriate for programs for that interpreter. The variable -@code{interpreter-mode-alist} specifies the correspondence between -interpreter program names and major modes. - - When the first line starts with @samp{#!}, you cannot (on many -systems) use the @samp{-*-} feature on the first line, because the -system would get confused when running the interpreter. So Emacs looks -for @samp{-*-} on the second line in such files as well as on the -first line. - -@vindex default-major-mode - When you visit a file that does not specify a major mode to use, or -when you create a new buffer with @kbd{C-x b}, the variable -@code{default-major-mode} specifies which major mode to use. Normally -its value is the symbol @code{fundamental-mode}, which specifies -Fundamental mode. If @code{default-major-mode} is @code{nil}, the major -mode is taken from the previously current buffer. - -@findex normal-mode - If you change the major mode of a buffer, you can go back to the major -mode Emacs would choose automatically: use the command @kbd{M-x -normal-mode} to do this. This is the same function that -@code{find-file} calls to choose the major mode. It also processes -the file's @samp{-*-} line or local variables list (if any). -@xref{File Variables}. - -@vindex change-major-mode-with-file-name - The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to -a new major mode if the new file name implies a mode (@pxref{Saving}). -(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) -However, this does not happen if the buffer contents specify a major -mode, and certain ``special'' major modes do not allow the mode to -change. You can turn off this mode-changing feature by setting -@code{change-major-mode-with-file-name} to @code{nil}. - -@ignore - arch-tag: f2558800-cf32-4839-8acb-7d3b4df2a155 -@end ignore diff --git a/man/makefile.w32-in b/man/makefile.w32-in deleted file mode 100644 index 7e3723c1949..00000000000 --- a/man/makefile.w32-in +++ /dev/null @@ -1,389 +0,0 @@ -#### -*- 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/man/mark.texi b/man/mark.texi deleted file mode 100644 index be446ab6bfc..00000000000 --- a/man/mark.texi +++ /dev/null @@ -1,452 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mark, Killing, Help, Top -@chapter The Mark and the Region -@cindex mark -@cindex setting a mark -@cindex region - - Many Emacs commands operate on an arbitrary contiguous part of the -current buffer. To specify the text for such a command to operate on, -you set @dfn{the mark} at one end of it, and move point to the other -end. The text between point and the mark is called @dfn{the region}. -Emacs highlights the region whenever there is one, if you enable -Transient Mark mode (@pxref{Transient Mark}). - - Certain Emacs commands set the mark; other editing commands do not -affect it, so the mark remains where you set it last. Each Emacs -buffer has its own mark, and setting the mark in one buffer has no -effect on other buffers' marks. When you return to a buffer that was -current earlier, its mark is at the same place as before. - - The ends of the region are always point and the mark. It doesn't -matter which of them was put in its current place first, or which one -comes earlier in the text---the region starts from point or the mark -(whichever comes first), and ends at point or the mark (whichever -comes last). Every time you move point, or set the mark in a new -place, the region changes. - - Many commands that insert text, such as @kbd{C-y} (@code{yank}) and -@kbd{M-x insert-buffer}, position point and the mark at opposite ends -of the inserted text, so that the region consists of the text just -inserted. - - Aside from delimiting the region, the mark is also useful for -remembering a spot that you may want to go back to. To make this -feature more useful, each buffer remembers 16 previous locations of the -mark in the @dfn{mark ring}. - -@menu -* Setting Mark:: Commands to set the mark. -* Transient Mark:: How to make Emacs highlight the region-- - when there is one. -* Momentary Mark:: Enabling Transient Mark mode momentarily. -* Using Region:: Summary of ways to operate on contents of the region. -* Marking Objects:: Commands to put region around textual units. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. -@end menu - -@node Setting Mark -@section Setting the Mark - - Here are some commands for setting the mark: - -@table @kbd -@item C-@key{SPC} -Set the mark where point is (@code{set-mark-command}). -@item C-@@ -The same. -@item C-x C-x -Interchange mark and point (@code{exchange-point-and-mark}). -@item Drag-Mouse-1 -Set point and the mark around the text you drag across. -@item Mouse-3 -Set the mark where point is, then move point to where you click -(@code{mouse-save-then-kill}). -@end table - - For example, suppose you wish to convert part of the buffer to -upper case, using the @kbd{C-x C-u} (@code{upcase-region}) command, -which operates on the text in the region. You can first go to the -beginning of the text to be capitalized, type @kbd{C-@key{SPC}} to put -the mark there, move to the end, and then type @kbd{C-x C-u}. Or, you -can set the mark at the end of the text, move to the beginning, and then -type @kbd{C-x C-u}. - -@kindex C-SPC -@findex set-mark-command - The most common way to set the mark is with the @kbd{C-@key{SPC}} command -(@code{set-mark-command}). This sets the mark where point is. Then you -can move point away, leaving the mark behind. - - There are two ways to set the mark with the mouse. You can drag mouse -button one across a range of text; that puts point where you release the -mouse button, and sets the mark at the other end of that range. Or you -can click mouse button three, which sets the mark at point (like -@kbd{C-@key{SPC}}) and then moves point where you clicked (like -@kbd{Mouse-1}). - - Using the mouse to mark a region copies the region into the kill -ring in addition to setting the mark; that gives behavior consistent -with other window-driven applications. If you don't want to modify -the kill ring, you must use keyboard commands to set the mark. -@xref{Mouse Commands}. - -@kindex C-x C-x -@findex exchange-point-and-mark - When Emacs was developed, terminals had only one cursor, so Emacs -does not show where the mark is located--you have to remember. If you -enable Transient Mark mode (see below), then the region is highlighted -when it is active; you can tell mark is at the other end of the -highlighted region. But this only applies when the mark is active. - - The usual solution to this problem is to set the mark and then use -it soon, before you forget where it is. Alternatively, you can see -where the mark is with the command @kbd{C-x C-x} -(@code{exchange-point-and-mark}) which puts the mark where point was -and point where the mark was. The extent of the region is unchanged, -but the cursor and point are now at the previous position of the mark. -In Transient Mark mode, this command also reactivates the mark. - - @kbd{C-x C-x} is also useful when you are satisfied with the position -of point but want to move the other end of the region (where the mark -is); do @kbd{C-x C-x} to put point at that end of the region, and then -move it. Using @kbd{C-x C-x} a second time, if necessary, puts the mark at -the new position with point back at its original position. - - For more facilities that allow you to go to previously set marks, see -@ref{Mark Ring}. - -@kindex C-@@ - There is no such character as @kbd{C-@key{SPC}} in @acronym{ASCII}; -when you type @key{SPC} while holding down @key{CTRL} on a text -terminal, what you get is the character @kbd{C-@@}. This key is also -bound to @code{set-mark-command}--so unless you are unlucky enough to -have a text terminal where typing @kbd{C-@key{SPC}} does not produce -@kbd{C-@@}, you might as well think of this character as -@kbd{C-@key{SPC}}. - -@node Transient Mark -@section Transient Mark Mode -@cindex mode, Transient Mark -@cindex Transient Mark mode -@cindex highlighting region -@cindex region highlighting - - On a terminal that supports colors, Emacs has the ability to -highlight the current region. But normally it does not. Why not? - - In the normal mode of use, every command that sets the mark also -activates it, and nothing ever deactivates it. Thus, once you have -set the mark in a buffer, there is @emph{always} a region in that -buffer. Highlighting the region all the time would be a nuisance. So -normally Emacs highlights the region only immediately after you have -selected one with the mouse. - - If you want region highlighting, you can use Transient Mark mode. -This is a more rigid mode of operation in which the region ``lasts'' -only until you use it; operating on the region text deactivates the -mark, so there is no region any more. Therefore, you must explicitly -set up a region for each command that uses one. - - When Transient Mark mode is enabled, Emacs highlights the region, -whenever there is a region. In Transient Mark mode, most of the time -there is no region; therefore, highlighting the region when it exists -is useful and not annoying. - -@findex transient-mark-mode - To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}. -This command toggles the mode; you can use the same command to turn -the mode off again. - - Here are the details of Transient Mark mode: - -@itemize @bullet -@item -To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}). -This makes the mark active and thus begins highlighting of the region. -As you move point, you will see the highlighted region grow and -shrink. - -@item -The mouse commands for specifying the mark also make it active. So do -keyboard commands whose purpose is to specify a region, including -@kbd{M-@@}, @kbd{C-M-@@}, @kbd{M-h}, @kbd{C-M-h}, @kbd{C-x C-p}, and -@kbd{C-x h}. - -@item -You can tell that the mark is active because the region is highlighted. - -@item -When the mark is active, you can execute commands that operate on the -region, such as killing, indenting, or writing to a file. - -@item -Any change to the buffer, such as inserting or deleting a character, -deactivates the mark. This means any subsequent command that operates -on a region will get an error and refuse to operate. You can make the -region active again by typing @kbd{C-x C-x}. - -@item -If Delete Selection mode is also enabled, some commands delete the -region when used while the mark is active. @xref{Mouse Commands}. - -@item -Quitting with @kbd{C-g} deactivates the mark. - -@item -Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in -addition to some other primary purpose, do not activate the new mark. -You can activate the new region by executing @kbd{C-x C-x} -(@code{exchange-point-and-mark}). - -@item -Commands that normally set the mark before moving long distances (like -@kbd{M-<} and @kbd{C-s}) do not alter the mark in Transient Mark mode -when the mark is active. - -@item -Some commands operate on the region if a region is active. For -instance, @kbd{C-x u} in Transient Mark mode operates on the region, -when there is a region. (Outside Transient Mark mode, you must type -@kbd{C-u C-x u} if you want it to operate on the region.) -@xref{Undo}. Other commands that act this way are identified in their -own documentation. -@end itemize - - The highlighting of the region uses the @code{region} face; you can -customize the appearance of the highlighted region by changing this -face. @xref{Face Customization}. - -@vindex highlight-nonselected-windows - When multiple windows show the same buffer, they can have different -regions, because they can have different values of point (though they -all share one common mark position). Ordinarily, only the selected -window highlights its region (@pxref{Windows}). However, if the -variable @code{highlight-nonselected-windows} is non-@code{nil}, then -each window highlights its own region (provided that Transient Mark mode -is enabled and the mark in the window's buffer is active). - -@vindex mark-even-if-inactive - If the variable @code{mark-even-if-inactive} is non-@code{nil} in -Transient Mark mode, then commands can use the mark and the region -even when it is inactive. Region highlighting appears and disappears -just as it normally does in Transient Mark mode, but the mark doesn't -really go away when the highlighting disappears, so you can still use -region commands. - -@cindex Zmacs mode - Transient Mark mode is also sometimes known as ``Zmacs mode'' -because the Zmacs editor on the MIT Lisp Machine handled the mark in a -similar way. - -@node Momentary Mark -@section Using Transient Mark Mode Momentarily - - If you don't like Transient Mark mode in general, you might still -want to use it once in a while. To do this, type @kbd{C-@key{SPC} -C-@key{SPC}} or @kbd{C-u C-x C-x}. These commands set or activate the -mark, and enable Transient Mark mode only until the mark is -deactivated. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -@kindex C-@key{SPC} C-@key{SPC} -Set the mark at point (like plain @kbd{C-@key{SPC}}), and enable -Transient Mark mode just once until the mark is deactivated. (This is -not really a separate command; you are using the @kbd{C-@key{SPC}} -command twice.) - -@item C-u C-x C-x -@kindex C-u C-x C-x -Activate the mark without changing it; enable Transient Mark mode just -once, until the mark is deactivated. (This is the @kbd{C-x C-x} -command, @code{exchange-point-and-mark}, with a prefix argument.) -@end table - - One of the secondary features of Transient Mark mode is that certain -commands operate only on the region, when there is an active region. -If you don't use Transient Mark mode, the region once set never -becomes inactive, so there is no way for these commands to make such a -distinction. Enabling Transient Mark mode momentarily gives you a way -to use these commands on the region. - - Momentary use of Transient Mark mode is also a way to highlight the -region for the time being. - -@node Using Region -@section Operating on the Region - -@cindex operations on a marked region - Once you have a region and the mark is active, here are some of the -ways you can operate on the region: - -@itemize @bullet -@item -Kill it with @kbd{C-w} (@pxref{Killing}). -@item -Save it in a register with @kbd{C-x r s} (@pxref{Registers}). -@item -Save it in a buffer or a file (@pxref{Accumulating Text}). -@item -Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}). -@item -Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). -@item -Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}). -@item -Print hardcopy with @kbd{M-x print-region} (@pxref{Printing}). -@item -Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). -@item -Undo changes within it using @kbd{C-u C-x u} (@pxref{Undo}). -@end itemize - - Most commands that operate on the text in the region have the word -@code{region} in their names. - -@node Marking Objects -@section Commands to Mark Textual Objects - -@cindex marking sections of text - Here are the commands for placing point and the mark around a textual -object such as a word, list, paragraph or page. - -@table @kbd -@item M-@@ -Set mark after end of next word (@code{mark-word}). This command and -the following one do not move point. -@item C-M-@@ -Set mark after end of following balanced expression (@code{mark-sexp}). -@item M-h -Put region around current paragraph (@code{mark-paragraph}). -@item C-M-h -Put region around current defun (@code{mark-defun}). -@item C-x h -Put region around the entire buffer (@code{mark-whole-buffer}). -@item C-x C-p -Put region around current page (@code{mark-page}). -@end table - -@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next -word, while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the -next balanced expression (@pxref{Expressions}). These commands handle -arguments just like @kbd{M-f} and @kbd{C-M-f}. Repeating these -commands extends the region. For example, you can type either -@kbd{C-u 2 M-@@} or @kbd{M-@@ M-@@} to mark the next two words. These -commands also extend the region in Transient Mark mode, regardless of -the last command. - -@kindex C-x h -@findex mark-whole-buffer - Other commands set both point and mark, to delimit an object in the -buffer. For example, @kbd{M-h} (@code{mark-paragraph}) moves point to -the beginning of the paragraph that surrounds or follows point, and -puts the mark at the end of that paragraph (@pxref{Paragraphs}). It -prepares the region so you can indent, case-convert, or kill a whole -paragraph. With a prefix argument, if the argument's value is positive, -@kbd{M-h} marks that many paragraphs starting with the one surrounding -point. If the prefix argument is @minus{}@var{n}, @kbd{M-h} also -marks @var{n} paragraphs, running back form the one surrounding point. -In that last case, point moves forward to the end of that paragraph, -and the mark goes at the start of the region. Repeating the @kbd{M-h} -command extends the region to subsequent paragraphs. - - @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the -mark after, the current (or following) major top-level definition, or -defun (@pxref{Moving by Defuns}). Repeating @kbd{C-M-h} extends -the region to subsequent defuns. - - @kbd{C-x C-p} (@code{mark-page}) puts point before the current page, -and mark at the end (@pxref{Pages}). The mark goes after the -terminating page delimiter (to include it in the region), while point -goes after the preceding page delimiter (to exclude it). A numeric -argument specifies a later page (if positive) or an earlier page (if -negative) instead of the current page. - - Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire -buffer as the region, by putting point at the beginning and the mark at -the end. (In some programs this is called ``select all.'') - - In Transient Mark mode, all of these commands activate the mark. - -@node Mark Ring -@section The Mark Ring - -@kindex C-u C-SPC -@cindex mark ring -@kindex C-u C-@@ - Aside from delimiting the region, the mark is also useful for -remembering a spot that you may want to go back to. To make this -feature more useful, each buffer remembers 16 previous locations of the -mark, in the @dfn{mark ring}. Commands that set the mark also push the -old mark onto this ring. To return to a marked location, use @kbd{C-u -C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command -@code{set-mark-command} given a numeric argument. It moves point to -where the mark was, and restores the mark from the ring of former -marks. - -@vindex set-mark-command-repeat-pop - If you set @code{set-mark-command-repeat-pop} to non-@code{nil}, -then when you repeat the character @kbd{C-@key{SPC}} after typing -@kbd{C-u C-@key{SPC}}, each repetition moves point to a previous mark -position from the ring. The mark positions you move through in this -way are not lost; they go to the end of the ring. - - Each buffer has its own mark ring. All editing commands use the current -buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in -the same buffer. - - Many commands that can move long distances, such as @kbd{M-<} -(@code{beginning-of-buffer}), start by setting the mark and saving the -old mark on the mark ring. This is to make it easier for you to move -back later. Searches set the mark if they move point. However, in -Transient Mark mode, these commands do not set the mark when the mark -is already active. You can tell when a command sets the mark because -it displays @samp{Mark set} in the echo area. - - If you want to move back to the same place over and over, the mark -ring may not be convenient enough. If so, you can record the position -in a register for later retrieval (@pxref{RegPos,, Saving Positions in -Registers}). - -@vindex mark-ring-max - The variable @code{mark-ring-max} specifies the maximum number of -entries to keep in the mark ring. If that many entries exist and -another one is pushed, the earliest one in the list is discarded. Repeating -@kbd{C-u C-@key{SPC}} cycles through the positions currently in the -ring. - -@vindex mark-ring - The variable @code{mark-ring} holds the mark ring itself, as a list of -marker objects, with the most recent first. This variable is local in -every buffer. - -@node Global Mark Ring -@section The Global Mark Ring -@cindex global mark ring - - In addition to the ordinary mark ring that belongs to each buffer, -Emacs has a single @dfn{global mark ring}. It records a sequence of -buffers in which you have recently set the mark, so you can go back -to those buffers. - - Setting the mark always makes an entry on the current buffer's mark -ring. If you have switched buffers since the previous mark setting, the -new mark position makes an entry on the global mark ring also. The -result is that the global mark ring records a sequence of buffers that -you have been in, and, for each buffer, a place where you set the mark. - -@kindex C-x C-@key{SPC} -@findex pop-global-mark - The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to -the buffer and position of the latest entry in the global ring. It also -rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take -you to earlier and earlier buffers. - -@ignore - arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20 -@end ignore diff --git a/man/message.texi b/man/message.texi deleted file mode 100644 index 2bca4b046e5..00000000000 --- a/man/message.texi +++ /dev/null @@ -1,2362 +0,0 @@ -\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/man/mh-e.texi b/man/mh-e.texi deleted file mode 100644 index a6341e80465..00000000000 --- a/man/mh-e.texi +++ /dev/null @@ -1,9793 +0,0 @@ -\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/man/mini.texi b/man/mini.texi deleted file mode 100644 index b57e79420b6..00000000000 --- a/man/mini.texi +++ /dev/null @@ -1,580 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Minibuffer, M-x, Basic, Top -@chapter The Minibuffer -@cindex minibuffer - - The @dfn{minibuffer} is where Emacs commands read complicated -arguments (anything more a single number). We call it the -``minibuffer'' because it's a special-purpose buffer with a small -amount of screen space. Minibuffer arguments can be file names, -buffer names, Lisp function names, Emacs command names, Lisp -expressions, and many other things---whatever the command wants to -read. You can use the usual Emacs editing commands in the minibuffer -to edit the argument text. - -@cindex prompt - When the minibuffer is in use, it appears in the echo area, with a -cursor. The minibuffer display starts with a @dfn{prompt} in a -distinct color; it says what kind of input is expected and how it will -be used. Often the prompt is derived from the name of the command -that is reading the argument. The prompt normally ends with a colon. - -@cindex default argument - Sometimes a @dfn{default argument} appears in the prompt, inside -parentheses before the colon. The default will be used as the -argument value if you just type @key{RET}. For example, commands that -read buffer names show a buffer name as the default. You can type -@key{RET} to operate on that default buffer. - - The simplest way to enter a minibuffer argument is to type the text, -then @key{RET} to exit the minibuffer. You can cancel the minibuffer, -and the command that wants the argument, by typing @kbd{C-g}. - - Since the minibuffer appears in the echo area, it can conflict with -other uses of the echo area. Here is how Emacs handles such -conflicts: - -@itemize @bullet -@item -An error occurs while the minibuffer is active. - -The error message hides the minibuffer for a few seconds, or until you -type something. Then the minibuffer comes back. - -@item -A command such as @kbd{C-x =} needs to display a message in the echo -area. - -The message hides the minibuffer for a few seconds, or until you type -something. Then the minibuffer comes back. - -@item -Keystrokes don't echo while the minibuffer is in use. -@end itemize - -@menu -* File: Minibuffer File. Entering file names with the minibuffer. -* Edit: Minibuffer Edit. How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. -@end menu - -@node Minibuffer File -@section Minibuffers for File Names - - When you use the minibuffer to enter a file name, it starts out with -some initial text---the @dfn{default directory}, ending in a slash. -The file you specify will be in this directory unless you alter or -replace it. - -@c Separate paragraph to clean up ugly page break--rms -@need 1500 - For example, if the minibuffer starts out with these contents: - -@example -Find File: /u2/emacs/src/ -@end example - -@noindent -(where @samp{Find File:@: } is the prompt), and you type -@kbd{buffer.c} as input, that specifies the file -@file{/u2/emacs/src/buffer.c}. You can specify the parent directory -by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you -will get @file{/u2/emacs/lisp/simple.el}. Alternatively, you can use -@kbd{M-@key{DEL}} to kill the directory names you don't want -(@pxref{Words}). - - You can kill the entire default with @kbd{C-a C-k}, but there's no -need to do that. It's easier to ignore the default, and enter an -absolute file name starting with a slash or a tilde after the default -directory. For example, to specify @file{/etc/termcap}, just type -that name: - -@example -Find File: /u2/emacs/src//etc/termcap -@end example - -@noindent -@cindex // in file name -@cindex double slash in file name -@cindex slashes repeated in file name -@findex file-name-shadow-mode -GNU Emacs interprets a double slash (which is not normally useful in -file names) as, ``ignore everything before the second slash in the -pair.'' In the example above. @samp{/u2/emacs/src/} is ignored, so -you get @file{/etc/termcap}. The ignored part of the file name is -dimmed if the terminal allows it; to disable this dimming, turn off -File Name Shadow mode (a minor mode) with the command -@kbd{M-x file-name-shadow-mode}. - - If the variable @code{insert-default-directory} is @code{nil}, the -default directory is never inserted in the minibuffer---so the -minibuffer starts out empty. Nonetheless, relative file name -arguments are still interpreted based on the same default directory. - -@node Minibuffer Edit -@section Editing in the Minibuffer - - The minibuffer is an Emacs buffer (albeit a peculiar one), and the -usual Emacs commands are available for editing the argument text. - - Since @key{RET} in the minibuffer is defined to exit the minibuffer, -you can't use it to insert a newline in the minibuffer. To do that, -type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the -@acronym{ASCII} character control-J.) - - The minibuffer has its own window, which normally has space in the -frame at all times, but it only acts like an Emacs window when the -minibuffer is active. When active, this window is much like any other -Emacs window; for instance, you can switch to another window (with -@kbd{C-x o}), edit text there, then return to the minibuffer window to -finish the argument. You can even kill text in another window, return -to the minibuffer window, and then yank the text into the argument. -@xref{Windows}. - -@cindex height of minibuffer -@cindex size of minibuffer -@cindex growing minibuffer -@cindex resizing minibuffer - There are some restrictions on the minibuffer window, however: you -cannot kill it, or split it, or switch buffers in it---the minibuffer -and its window are permanently attached. - -@vindex resize-mini-windows - The minibuffer window expands vertically as necessary to hold the -text that you put in the minibuffer. If @code{resize-mini-windows} is -@code{t} (the default), the window always resizes as needed by its -contents. If its value is the symbol @code{grow-only}, the window -grows automatically as needed, but shrinks (back to the normal size) -only when the minibuffer becomes inactive. If its value is -@code{nil}, you have to adjust the height yourself. - -@vindex max-mini-window-height - The variable @code{max-mini-window-height} controls the maximum -height for resizing the minibuffer window: a floating-point number -specifies a fraction of the frame's height; an integer specifies the -maximum number of lines; @code{nil} means do not resize the minibuffer -window automatically. The default value is 0.25. - - The @kbd{C-M-v} command in the minibuffer scrolls the help text from -commands that display help text of any sort in another window. -@kbd{M-@key{PAGEUP}} and @kbd{M-@key{PAGEDOWN}} also operate on that -help text. This is especially useful with long lists of possible -completions. @xref{Other Window}. - -@vindex enable-recursive-minibuffers - Emacs normally disallows most commands that use the minibuffer while -the minibuffer is active. (Entering the minibuffer from the -minibuffer can be confusing.) To allow such commands in the -minibuffer, set the variable @code{enable-recursive-minibuffers} to -@code{t}. - -@node Completion -@section Completion -@cindex completion - - Some arguments allow @dfn{completion} to enter their value. This -means that after you type part of the argument, Emacs can fill in the -rest, or some of it, based on what you have typed so far. - - When completion is available, certain keys---@key{TAB}, @key{RET}, -and @key{SPC}---are rebound to complete the text in the minibuffer -before point into a longer string chosen from a set of @dfn{completion -alternatives} provided by the command that requested the argument. -(@key{SPC} does not do completion in reading file names, because it is -common to use spaces in file names on some systems.) @kbd{?} displays -a list of the possible completions at any time. - - For example, @kbd{M-x} uses the minibuffer to read the name of a -command, so it provides a list of all Emacs command names for -completion candidates. The completion keys match the minibuffer text -against these candidates, find any additional name characters implied -by the text already present in the minibuffer, and add those -characters. This makes it possible to type @kbd{M-x ins @key{SPC} b -@key{RET}} instead of @kbd{M-x insert-buffer @key{RET}}, for example. - - Case is significant in completion when it is significant in the -argument you are entering (buffer names, file names, command names, -for instance). Thus, @samp{fo} does not complete to @samp{Foo}. -Completion ignores case distinctions for certain arguments in which -case does not matter. - - Completion acts only on the text before point. If there is text in -the minibuffer after point---i.e., if you move point backward after -typing some text into the minibuffer---it remains unchanged. - -@menu -* Example: Completion Example. Examples of using completion. -* Commands: Completion Commands. A list of completion commands. -* Strict Completion:: Different types of completion. -* Options: Completion Options. Options for completion. -@end menu - -@node Completion Example -@subsection Completion Example - -@kindex TAB @r{(completion)} - A concrete example may help here. If you type @kbd{M-x au -@key{TAB}}, the @key{TAB} looks for alternatives (in this case, -command names) that start with @samp{au}. There are several, -including @code{auto-fill-mode} and @code{auto-save-mode}, but they -all begin with @code{auto-}, so the @samp{au} in the minibuffer -completes to @samp{auto-}. - - If you type @key{TAB} again immediately, it cannot determine the -next character; it could be any of @samp{cfilrs}. So it does not add -any characters; instead, @key{TAB} displays a list of all possible -completions in another window. - - Now type @kbd{f @key{TAB}}. This @key{TAB} sees @samp{auto-f}. The -only command name starting with that is @code{auto-fill-mode}, so -completion fills in the rest of that. You have been able to enter -@samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}. - -@node Completion Commands -@subsection Completion Commands - - Here is a list of the completion commands defined in the minibuffer -when completion is allowed. - -@table @kbd -@item @key{TAB} -@findex minibuffer-complete -Complete the text before point in the minibuffer as much as possible -(@code{minibuffer-complete}). -@item @key{SPC} -Complete up to one word from the minibuffer text before point -(@code{minibuffer-complete-word}). @key{SPC} for completion is not -available when entering a file name, since file names often include -spaces. -@item @key{RET} -Submit the text in the minibuffer as the argument, possibly completing -first as described -@iftex -in the next subsection (@code{minibuffer-complete-and-exit}). -@end iftex -@ifnottex -in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict -Completion}. -@end ifnottex -@item ? -Display a list of possible completions of the text before point -(@code{minibuffer-completion-help}). -@end table - -@kindex SPC -@findex minibuffer-complete-word - @key{SPC} completes like @key{TAB}, but only up to the next hyphen -or space. If you have @samp{auto-f} in the minibuffer and type -@key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but -it only inserts @samp{ill-}, giving @samp{auto-fill-}. Another -@key{SPC} at this point completes all the way to -@samp{auto-fill-mode}. The command that implements this behavior is -called @code{minibuffer-complete-word}. - - When you display a list of possible completions, you can choose -one from it: - -@table @kbd -@findex mouse-choose-completion -@item Mouse-1 -@itemx Mouse-2 -Clicking mouse button 1 or 2 on a completion possibility chooses that -completion (@code{mouse-choose-completion}). You must click in the -list of completions, not in the minibuffer. - -@findex switch-to-completions -@item @key{PRIOR} -@itemx M-v -Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the -minibuffer, selects the window showing the completion list buffer -(@code{switch-to-completions}). This paves the way for using the -commands below. (Selecting that window in other ways has the same -effect.) - -@findex choose-completion -@item @key{RET} -Typing @key{RET} @emph{in the completion list buffer} chooses the -completion that point is in or next to (@code{choose-completion}). To -use this command, you must first switch to the completion list window. - -@findex next-completion -@item @key{RIGHT} -Typing the right-arrow key @key{RIGHT} @emph{in the completion list -buffer} moves point to the following completion possibility -(@code{next-completion}). - -@findex previous-completion -@item @key{LEFT} -Typing the left-arrow key @key{LEFT} @emph{in the completion list -buffer} moves point to the previous completion possibility -(@code{previous-completion}). -@end table - -@node Strict Completion -@subsection Strict Completion - - There are three different ways that @key{RET} can do completion, -depending on how the argument will be used. - -@itemize @bullet -@item -@dfn{Strict} completion accepts only known completion candidates. For -example, when @kbd{C-x k} reads the name of a buffer to kill, only the -name of an existing buffer makes sense. In strict completion, -@key{RET} refuses to exit if the text in the minibuffer does not -complete to an exact match. - -@item -@dfn{Cautious} completion is similar to strict completion, except that -@key{RET} exits only if the text is an already exact match. -Otherwise, @key{RET} does not exit, but it does complete the text. If -that completes to an exact match, a second @key{RET} will exit. - -Cautious completion is used for reading file names for files that must -already exist, for example. - -@item -@dfn{Permissive} completion allows any input; the completion -candidates are just suggestions. For example, when @kbd{C-x C-f} -reads the name of a file to visit, any file name is allowed, including -nonexistent file (in case you want to create a file). In permissive -completion, @key{RET} does not complete, it just submits the argument -as you have entered it. -@end itemize - - The completion commands display a list of all possible completions -whenever they can't determine even one more character by completion. -Also, typing @kbd{?} explicitly requests such a list. You can scroll -the list with @kbd{C-M-v} (@pxref{Other Window}). - -@node Completion Options -@subsection Completion Options - -@vindex completion-ignored-extensions -@cindex ignored file names, in completion - When completing file names, certain file names are usually ignored. -The variable @code{completion-ignored-extensions} contains a list of -strings; a file name ending in any of those strings is ignored as a -completion candidate. The standard value of this variable has several -elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and -@code{"~"}. The effect is that, for example, @samp{foo} can complete -to @samp{foo.c} even though @samp{foo.o} exists as well. However, if -@emph{all} the possible completions end in ``ignored'' strings, then -they are not ignored. Displaying a list of possible completions -disregards @code{completion-ignored-extensions}; it shows them all. - - If an element of @code{completion-ignored-extensions} ends in a -slash (@file{/}), it's a subdirectory name; then that directory and -its contents are ignored. Elements of -@code{completion-ignored-extensions} which do not end in a slash are -ordinary file names, and do not apply to names of directories. - -@vindex completion-auto-help - If @code{completion-auto-help} is set to @code{nil}, the completion -commands never display a list of possibilities; you must type @kbd{?} -to display the list. - -@cindex Partial Completion mode -@vindex partial-completion-mode -@findex partial-completion-mode - Partial Completion mode implements a more powerful kind of -completion that can complete multiple words in parallel. For example, -it can complete the command name abbreviation @code{p-b} into -@code{print-buffer} if no other command starts with two words whose -initials are @samp{p} and @samp{b}. - - To enable this mode, use @kbd{M-x partial-completion-mode}, or -customize the variable @code{partial-completion-mode}. This mode -binds special partial completion commands to @key{TAB}, @key{SPC}, -@key{RET}, and @kbd{?} in the minibuffer. The usual completion -commands are available on @kbd{M-@key{TAB}} (or @kbd{C-M-i}), -@kbd{M-@key{SPC}}, @kbd{M-@key{RET}} and @kbd{M-?}. - - Partial completion of directories in file names uses @samp{*} to -indicate the places for completion; thus, @file{/u*/b*/f*} might -complete to @file{/usr/bin/foo}. For remote files, partial completion -enables completion of methods, user names and host names. -@xref{Remote Files}. - -@vindex PC-include-file-path -@vindex PC-disable-includes - Partial Completion mode also extends @code{find-file} so that -@samp{<@var{include}>} looks for the file named @var{include} in the -directories in the path @code{PC-include-file-path}. If you set -@code{PC-disable-includes} to non-@code{nil}, this feature is -disabled. - -@cindex Icomplete mode -@findex icomplete-mode - Icomplete mode presents a constantly-updated display that tells you -what completions are available for the text you've entered so far. The -command to enable or disable this minor mode is @kbd{M-x -icomplete-mode}. - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history of minibuffer input - - Every argument that you enter with the minibuffer is saved on a -@dfn{minibuffer history list} so you can easily use it again later. -Special commands fetch the text of an earlier argument into the -minibuffer, replacing the old minibuffer contents. You can think of -them as moving through the history of previous arguments. - -@table @kbd -@item @key{UP} -@itemx M-p -Move to the previous item in the minibuffer history, an earlier argument -(@code{previous-history-element}). -@item @key{DOWN} -@itemx M-n -Move to the next item in the minibuffer history -(@code{next-history-element}). -@item M-r @var{regexp} @key{RET} -Move to an earlier item in the minibuffer history that -matches @var{regexp} (@code{previous-matching-history-element}). -@item M-s @var{regexp} @key{RET} -Move to a later item in the minibuffer history that matches -@var{regexp} (@code{next-matching-history-element}). -@end table - -@kindex M-p @r{(minibuffer history)} -@kindex M-n @r{(minibuffer history)} -@findex next-history-element -@findex previous-history-element - To move through the minibuffer history list one item at a time, use -@kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the -next earlier minibuffer input, and use @kbd{M-n} or down-arrow -(@code{next-history-element}) to fetch the next later input. These -commands don't move the cursor, they pull different saved strings into -the minibuffer. But you can think of them as ``moving'' through the -history list. - - The input that you fetch from the history entirely replaces the -contents of the minibuffer. To use it again unchanged, just type -@key{RET}. You can also edit the text before you reuse it; this does -not change the history element that you ``moved'' to, but your new -argument does go at the end of the history list in its own right. - - For many minibuffer arguments there is a ``default'' value. You can -insert the default value into the minibuffer as text by using -@kbd{M-n}. You can think of this as moving ``into the future'' in the -history. - -@findex previous-matching-history-element -@findex next-matching-history-element -@kindex M-r @r{(minibuffer history)} -@kindex M-s @r{(minibuffer history)} - There are also commands to search forward or backward through the -history; they search for history elements that match a regular -expression. @kbd{M-r} (@code{previous-matching-history-element}) -searches older elements in the history, while @kbd{M-s} -(@code{next-matching-history-element}) searches newer elements. These -commands are unusual; they use the minibuffer to read the regular -expression even though they are invoked from the minibuffer. As with -incremental searching, an upper-case letter in the regular expression -makes the search case-sensitive (@pxref{Search Case}). - -@ignore - We may change the precise way these commands read their arguments. -Perhaps they will search for a match for the string given so far in the -minibuffer; perhaps they will search for a literal match rather than a -regular expression match; perhaps they will only accept matches at the -beginning of a history element; perhaps they will read the string to -search for incrementally like @kbd{C-s}. To find out what interface is -actually available, type @kbd{C-h f previous-matching-history-element}. -@end ignore - - All uses of the minibuffer record your input on a history list, but -there are separate history lists for different kinds of arguments. -For example, there is a list for file names, used by all the commands -that read file names. (As a special feature, this history list -records the absolute file name, even if the name you entered was not -absolute.) - - There are several other specific history lists, including one for -buffer names, one for arguments of commands like @code{query-replace}, -one used by @kbd{M-x} for command names, and one used by -@code{compile} for compilation commands. Finally, there is one -``miscellaneous'' history list that most minibuffer arguments use. - -@vindex history-length - The variable @code{history-length} specifies the maximum length of a -minibuffer history list; adding a new element deletes the oldest -element if the list gets too long. If the value of -@code{history-length} is @code{t}, though, there is no maximum length. - -@vindex history-delete-duplicates - The variable @code{history-delete-duplicates} specifies whether to -delete duplicates in history. If it is @code{t}, adding a new element -deletes from the list all other elements that are equal to it. - -@node Repetition -@section Repeating Minibuffer Commands -@cindex command history -@cindex history of commands - - Every command that uses the minibuffer once is recorded on a special -history list, the @dfn{command history}, together with the values of -its arguments, so that you can repeat the entire command. In -particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} -uses the minibuffer to read the command name. - -@findex list-command-history -@table @kbd -@item C-x @key{ESC} @key{ESC} -Re-execute a recent minibuffer command from the command history - (@code{repeat-complex-command}). -@item M-x list-command-history -Display the entire command history, showing all the commands -@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. -@end table - -@kindex C-x ESC ESC -@findex repeat-complex-command - @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command -that used the minibuffer. With no argument, it repeats the last such -command. A numeric argument specifies which command to repeat; 1 -means the last one, 2 the previous, and so on. - - @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command -into a Lisp expression and then entering a minibuffer initialized with -the text for that expression. Even if you don't understand Lisp -syntax, it will probably be obvious which command is displayed for -repetition. If you type just @key{RET}, that repeats the command -unchanged. You can also change the command by editing the Lisp -expression before you execute it. The repeated command is added to -the front of the command history unless it is identical to the most -recently item. - - Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can -use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, -@kbd{M-s}; @pxref{Minibuffer History}) to move through the history list -of saved entire commands. After finding the desired previous command, -you can edit its expression as usual and then repeat it by typing -@key{RET}. - -@vindex isearch-resume-in-command-history - Incremental search does not, strictly speaking, use the minibuffer. -Therefore, although it behaves like a complex command, it normally -does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. -You can make incremental search commands appear in the history by -setting @code{isearch-resume-in-command-history} to a non-@code{nil} -value. @xref{Incremental Search}. - -@vindex command-history - The list of previous minibuffer-using commands is stored as a Lisp -list in the variable @code{command-history}. Each element is a Lisp -expression which describes one command and its arguments. Lisp programs -can re-execute a command by calling @code{eval} with the -@code{command-history} element. - -@ignore - arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f -@end ignore diff --git a/man/misc.texi b/man/misc.texi deleted file mode 100644 index c4cdea4359d..00000000000 --- a/man/misc.texi +++ /dev/null @@ -1,2559 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Miscellaneous Commands - - This chapter contains several brief topics that do not fit anywhere -else: reading netnews, running shell commands and shell subprocesses, -using a single shared Emacs for utilities that expect to run an editor -as a subprocess, printing hardcopy, sorting text, narrowing display to -part of the buffer, editing double-column files and binary files, -saving an Emacs session for later resumption, following hyperlinks, -browsing images, emulating other editors, and various diversions and -amusements. - -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Gnus, Shell, Calendar/Diary, Top -@section Gnus -@cindex Gnus -@cindex reading netnews - -Gnus is an Emacs package primarily designed for reading and posting -Usenet news. It can also be used to read and respond to messages from a -number of other sources---mail, remote directories, digests, and so on. - -Here we introduce Gnus and describe several basic features. -@ifnottex -For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. -@end ifnottex -@iftex -For full details on Gnus, type @kbd{M-x info} and then select the Gnus -manual. -@end iftex - -@findex gnus -To start Gnus, type @kbd{M-x gnus @key{RET}}. - -@menu -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Summary of Gnus:: A short description of the basic Gnus commands. -@end menu - -@node Buffers of Gnus -@subsection Gnus Buffers - -Unlike most Emacs packages, Gnus uses several buffers to display -information and to receive commands. The three Gnus buffers users use -most are the @dfn{group buffer}, the @dfn{summary buffer} and the -@dfn{article buffer}. - -The @dfn{group buffer} contains a list of newsgroups. This is the -first buffer Gnus displays when it starts up. It normally displays -only the groups to which you subscribe and that contain unread -articles. Use this buffer to select a specific group. - -The @dfn{summary buffer} lists one line for each article in a single -group. By default, the author, the subject and the line number are -displayed for each article, but this is customizable, like most aspects -of Gnus display. The summary buffer is created when you select a group -in the group buffer, and is killed when you exit the group. Use this -buffer to select an article. - -The @dfn{article buffer} displays the article. In normal Gnus usage, -you see this buffer but you don't select it---all useful -article-oriented commands work in the summary buffer. But you can -select the article buffer, and execute all Gnus commands from that -buffer, if you want to. - -@node Gnus Startup -@subsection When Gnus Starts Up - -At startup, Gnus reads your @file{.newsrc} news initialization file -and attempts to communicate with the local news server, which is a -repository of news articles. The news server need not be the same -computer you are logged in on. - -If you start Gnus and connect to the server, but do not see any -newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get -a listing of all the groups. Then type @kbd{u} to toggle -subscription to groups. - -The first time you start Gnus, Gnus subscribes you to a few selected -groups. All other groups start out as @dfn{killed groups} for you; you -can list them with @kbd{A k}. All new groups that subsequently come to -exist at the news server become @dfn{zombie groups} for you; type @kbd{A -z} to list them. You can subscribe to a group shown in these lists -using the @kbd{u} command. - -When you quit Gnus with @kbd{q}, it automatically records in your -@file{.newsrc} and @file{.newsrc.eld} initialization files the -subscribed or unsubscribed status of all groups. You should normally -not edit these files manually, but you may if you know how. - -@node Summary of Gnus -@subsection Summary of Gnus Commands - -Reading news is a two-step process: - -@enumerate -@item -Choose a group in the group buffer. - -@item -Select articles from the summary buffer. Each article selected is -displayed in the article buffer in a large window, below the summary -buffer in its small window. -@end enumerate - - Each Gnus buffer has its own special commands; the meanings of any -given key in the various Gnus buffers are usually analogous, even if -not identical. Here are commands for the group and summary buffers: - -@table @kbd -@kindex q @r{(Gnus Group mode)} -@findex gnus-group-exit -@item q -In the group buffer, update your @file{.newsrc} initialization file -and quit Gnus. - -In the summary buffer, exit the current group and return to the -group buffer. Thus, typing @kbd{q} twice quits Gnus. - -@kindex L @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item L -In the group buffer, list all the groups available on your news -server (except those you have killed). This may be a long list! - -@kindex l @r{(Gnus Group mode)} -@findex gnus-group-list-groups -@item l -In the group buffer, list only the groups to which you subscribe and -which contain unread articles. - -@kindex u @r{(Gnus Group mode)} -@findex gnus-group-unsubscribe-current-group -@cindex subscribe groups -@cindex unsubscribe groups -@item u -In the group buffer, unsubscribe from (or subscribe to) the group listed -in the line that point is on. When you quit Gnus by typing @kbd{q}, -Gnus lists in your @file{.newsrc} file which groups you have subscribed -to. The next time you start Gnus, you won't see this group, -because Gnus normally displays only subscribed-to groups. - -@kindex C-k @r{(Gnus)} -@findex gnus-group-kill-group -@item C-k -In the group buffer, ``kill'' the current line's group---don't -even list it in @file{.newsrc} from now on. This affects future -Gnus sessions as well as the present session. - -When you quit Gnus by typing @kbd{q}, Gnus writes information -in the file @file{.newsrc} describing all newsgroups except those you -have ``killed.'' - -@kindex SPC @r{(Gnus)} -@findex gnus-group-read-group -@item @key{SPC} -In the group buffer, select the group on the line under the cursor -and display the first unread article in that group. - -@need 1000 -In the summary buffer, - -@itemize @bullet -@item -Select the article on the line under the cursor if none is selected. - -@item -Scroll the text of the selected article (if there is one). - -@item -Select the next unread article if at the end of the current article. -@end itemize - -Thus, you can move through all the articles by repeatedly typing @key{SPC}. - -@kindex DEL @r{(Gnus)} -@item @key{DEL} -In the group buffer, move point to the previous group containing -unread articles. - -@findex gnus-summary-prev-page -In the summary buffer, scroll the text of the article backwards. - -@kindex n @r{(Gnus)} -@findex gnus-group-next-unread-group -@findex gnus-summary-next-unread-article -@item n -Move point to the next unread group, or select the next unread article. - -@kindex p @r{(Gnus)} -@findex gnus-group-prev-unread-group -@findex gnus-summary-prev-unread-article -@item p -Move point to the previous unread group, or select the previous -unread article. - -@kindex C-n @r{(Gnus Group mode)} -@findex gnus-group-next-group -@kindex C-p @r{(Gnus Group mode)} -@findex gnus-group-prev-group -@kindex C-n @r{(Gnus Summary mode)} -@findex gnus-summary-next-subject -@kindex C-p @r{(Gnus Summary mode)} -@findex gnus-summary-prev-subject -@item C-n -@itemx C-p -Move point to the next or previous item, even if it is marked as read. -This does not select the article or group on that line. - -@kindex s @r{(Gnus Summary mode)} -@findex gnus-summary-isearch-article -@item s -In the summary buffer, do an incremental search of the current text in -the article buffer, just as if you switched to the article buffer and -typed @kbd{C-s}. - -@kindex M-s @r{(Gnus Summary mode)} -@findex gnus-summary-search-article-forward -@item M-s @var{regexp} @key{RET} -In the summary buffer, search forward for articles containing a match -for @var{regexp}. - -@end table - -@ignore -@node Where to Look -@subsection Where to Look Further - -@c Too many references to the name of the manual if done with xref in TeX! -Gnus is powerful and customizable. Here are references to a few -@ifnottex -additional topics: - -@end ifnottex -@iftex -additional topics in @cite{The Gnus Manual}: - -@itemize @bullet -@item -Follow discussions on specific topics.@* -See section ``Threading.'' - -@item -Read digests. See section ``Document Groups.'' - -@item -Refer to and jump to the parent of the current article.@* -See section ``Finding the Parent.'' - -@item -Refer to articles by using Message-IDs included in the messages.@* -See section ``Article Keymap.'' - -@item -Save articles. See section ``Saving Articles.'' - -@item -Have Gnus score articles according to various criteria, like author -name, subject, or string in the body of the articles.@* -See section ``Scoring.'' - -@item -Send an article to a newsgroup.@* -See section ``Composing Messages.'' -@end itemize -@end iftex -@ifnottex -@itemize @bullet -@item -Follow discussions on specific topics.@* -@xref{Threading, , Reading Based on Conversation Threads, -gnus, The Gnus Manual}. - -@item -Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}. - -@item -Refer to and jump to the parent of the current article.@* -@xref{Finding the Parent, , , gnus, The Gnus Manual}. - -@item -Refer to articles by using Message-IDs included in the messages.@* -@xref{Article Keymap, , , gnus, The Gnus Manual}. - -@item -Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}. - -@item -Have Gnus score articles according to various criteria, like author -name, subject, or string in the body of the articles.@* -@xref{Scoring, , , gnus, The Gnus Manual}. - -@item -Send an article to a newsgroup.@* -@xref{Composing Messages, , , gnus, The Gnus Manual}. -@end itemize -@end ifnottex -@end ignore - -@node Shell, Emacs Server, Gnus, Top -@section Running Shell Commands from Emacs -@cindex subshell -@cindex shell commands - - Emacs has commands for passing single command lines to inferior shell -processes; it can also run a shell interactively with input and output -to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal -emulator window. - -@table @kbd -@item M-! @var{cmd} @key{RET} -Run the shell command line @var{cmd} and display the output -(@code{shell-command}). -@item M-| @var{cmd} @key{RET} -Run the shell command line @var{cmd} with region contents as input; -optionally replace the region with the output -(@code{shell-command-on-region}). -@item M-x shell -Run a subshell with input and output through an Emacs buffer. -You can then give commands interactively. -@item M-x term -Run a subshell with input and output through an Emacs buffer. -You can then give commands interactively. -Full terminal emulation is available. -@end table - - @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It -is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell, -Eshell: The Emacs Shell}. - -@menu -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* History: Shell History. Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Options: Shell Options. Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Paging in Term:: Paging in the terminal emulator. -* Remote Host:: Connecting to another computer. -@end menu - -@node Single Shell -@subsection Single Shell Commands - -@kindex M-! -@findex shell-command - @kbd{M-!} (@code{shell-command}) reads a line of text using the -minibuffer and executes it as a shell command in a subshell made just -for that command. Standard input for the command comes from the null -device. If the shell command produces any output, the output appears -either in the echo area (if it is short), or in an Emacs buffer named -@samp{*Shell Command Output*}, which is displayed in another window -but not selected (if the output is long). - - For instance, one way to decompress a file @file{foo.gz} from Emacs -is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command -normally creates the file @file{foo} and produces no terminal output. - - A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal -output into the current buffer instead of a separate buffer. It puts -point before the output, and sets the mark after the output. For -instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the -uncompressed equivalent of @file{foo.gz} into the current buffer. - - If the shell command line ends in @samp{&}, it runs asynchronously. -For a synchronous shell command, @code{shell-command} returns the -command's exit status (0 means success), when it is called from a Lisp -program. You do not get any status information for an asynchronous -command, since it hasn't finished yet when @code{shell-command} returns. - -@kindex M-| -@findex shell-command-on-region - @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but -passes the contents of the region as the standard input to the shell -command, instead of no input. With a numeric argument, meaning insert -the output in the current buffer, it deletes the old region and the -output replaces it as the contents of the region. It returns the -command's exit status, like @kbd{M-!}. - - One use for @kbd{M-|} is to run @code{gpg} to see what keys are in -the buffer. For instance, if the buffer contains a GPG key, type -@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to -the @code{gpg} program. That program will ignore everything except -the encoded keys, and will output a list of the keys the buffer -contains. - -@vindex shell-file-name - Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify -the shell to use. This variable is initialized based on your -@env{SHELL} environment variable when Emacs is started. If the file -name is relative, Emacs searches the directories in the list -@code{exec-path}; this list is initialized based on the environment -variable @env{PATH} when Emacs is started. Your @file{.emacs} file -can override either or both of these default initializations. - - Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete, -unless you end the command with @samp{&} to make it asynchronous. To -stop waiting, type @kbd{C-g} to quit; that terminates the shell -command with the signal @code{SIGINT}---the same signal that @kbd{C-c} -normally generates in the shell. Emacs then waits until the command -actually terminates. If the shell command doesn't stop (because it -ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends -the command a @code{SIGKILL} signal which is impossible to ignore. - - Asynchronous commands ending in @samp{&} feed their output into -the buffer @samp{*Async Shell Command*}. Output arrives in that -buffer regardless of whether it is visible in a window. - - To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command -@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. - -@vindex shell-command-default-error-buffer - Error output from these commands is normally intermixed with the -regular output. But if the variable -@code{shell-command-default-error-buffer} has a string as value, and -it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output -before point in that buffer. - -@node Interactive Shell -@subsection Interactive Inferior Shell - -@findex shell - To run a subshell interactively, putting its typescript in an Emacs -buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named -@samp{*shell*} and runs a subshell with input coming from and output going -to that buffer. That is to say, any ``terminal output'' from the subshell -goes into the buffer, advancing point, and any ``terminal input'' for -the subshell comes from text in the buffer. To give input to the subshell, -go to the end of the buffer and type the input, terminated by @key{RET}. - - Emacs does not wait for the subshell to do anything. You can switch -windows or buffers and edit them while the shell is waiting, or while it is -running a command. Output from the subshell waits until Emacs has time to -process it; this happens whenever Emacs is waiting for keyboard input or -for time to elapse. - -@cindex @code{comint-highlight-input} face -@cindex @code{comint-highlight-prompt} face - Input lines, once you submit them, are displayed using the face -@code{comint-highlight-input}, and prompts are displayed using the -face @code{comint-highlight-prompt}. This makes it easier to see -previous input lines in the buffer. @xref{Faces}. - - To make multiple subshells, you can invoke @kbd{M-x shell} with a -prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer -name and create (or reuse) a subshell in that buffer. You can also -rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then -create a new @samp{*shell*} buffer using plain @kbd{M-x shell}. -Subshells in different buffers run independently and in parallel. - -@vindex explicit-shell-file-name -@cindex environment variables for subshells -@cindex @env{ESHELL} environment variable -@cindex @env{SHELL} environment variable - The file name used to load the subshell is the value of the variable -@code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise, -the environment variable @env{ESHELL} is used, or the environment -variable @env{SHELL} if there is no @env{ESHELL}. If the file name -specified is relative, the directories in the list @code{exec-path} are -searched; this list is initialized based on the environment variable -@env{PATH} when Emacs is started. Your @file{.emacs} file can override -either or both of these default initializations. - - Emacs sends the new shell the contents of the file -@file{~/.emacs_@var{shellname}} as input, if it exists, where -@var{shellname} is the name of the file that the shell was loaded -from. For example, if you use bash, the file sent to it is -@file{~/.emacs_bash}. If this file is not found, Emacs tries to fallback -on @file{~/.emacs.d/init_@var{shellname}.sh}. - - To specify a coding system for the shell, you can use the command -@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can -also change the coding system for a running subshell by typing -@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication -Coding}. - -@cindex @env{INSIDE_EMACS} environment variable - Emacs sets the envitonment variable @env{INSIDE_EMACS} to @code{t} -in the subshell. Programs can check this variable to determine -whether they are running inside an Emacs subshell. - -@cindex @env{EMACS} environment variable - Emacs also sets the @env{EMACS} environment variable to @code{t} if -it is not already defined. @strong{Warning:} This environment -variable is deprecated. Programs that check this variable should be -changed to check @env{INSIDE_EMACS} instead. - -@node Shell Mode -@subsection Shell Mode -@cindex Shell mode -@cindex mode, Shell - - Shell buffers use Shell mode, which defines several special keys -attached to the @kbd{C-c} prefix. They are chosen to resemble the usual -editing and job control characters present in shells that are not under -Emacs, except that you must type @kbd{C-c} first. Here is a complete list -of the special key bindings of Shell mode: - -@table @kbd -@item @key{RET} -@kindex RET @r{(Shell mode)} -@findex comint-send-input -At end of buffer send line as input; otherwise, copy current line to -end of buffer and send it (@code{comint-send-input}). Copying a line -in this way omits any prompt at the beginning of the line (text output -by programs preceding your input). @xref{Shell Prompts}, for how -Shell mode recognizes prompts. - -@item @key{TAB} -@kindex TAB @r{(Shell mode)} -@findex comint-dynamic-complete -Complete the command name or file name before point in the shell buffer -(@code{comint-dynamic-complete}). @key{TAB} also completes history -references (@pxref{History References}) and environment variable names. - -@vindex shell-completion-fignore -@vindex comint-completion-fignore -The variable @code{shell-completion-fignore} specifies a list of file -name extensions to ignore in Shell mode completion. The default -setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to -ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other -related Comint modes use the variable @code{comint-completion-fignore} -instead. - -@item M-? -@kindex M-? @r{(Shell mode)} -@findex comint-dynamic-list-filename@dots{} -Display temporarily a list of the possible completions of the file name -before point in the shell buffer -(@code{comint-dynamic-list-filename-completions}). - -@item C-d -@kindex C-d @r{(Shell mode)} -@findex comint-delchar-or-maybe-eof -Either delete a character or send @acronym{EOF} -(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell -buffer, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other -position in the buffer, @kbd{C-d} deletes a character as usual. - -@item C-c C-a -@kindex C-c C-a @r{(Shell mode)} -@findex comint-bol-or-process-mark -Move to the beginning of the line, but after the prompt if any -(@code{comint-bol-or-process-mark}). If you repeat this command twice -in a row, the second time it moves back to the process mark, which is -the beginning of the input that you have not yet sent to the subshell. -(Normally that is the same place---the end of the prompt on this -line---but after @kbd{C-c @key{SPC}} the process mark may be in a -previous line.) - -@item C-c @key{SPC} -Accumulate multiple lines of input, then send them together. This -command inserts a newline before point, but does not send the preceding -text as input to the subshell---at least, not yet. Both lines, the one -before this newline and the one after, will be sent together (along with -the newline that separates them), when you type @key{RET}. - -@item C-c C-u -@kindex C-c C-u @r{(Shell mode)} -@findex comint-kill-input -Kill all text pending at end of buffer to be sent as input -(@code{comint-kill-input}). If point is not at end of buffer, -this only kills the part of this text that precedes point. - -@item C-c C-w -@kindex C-c C-w @r{(Shell mode)} -Kill a word before point (@code{backward-kill-word}). - -@item C-c C-c -@kindex C-c C-c @r{(Shell mode)} -@findex comint-interrupt-subjob -Interrupt the shell or its current subjob if any -(@code{comint-interrupt-subjob}). This command also kills -any shell input pending in the shell buffer and not yet sent. - -@item C-c C-z -@kindex C-c C-z @r{(Shell mode)} -@findex comint-stop-subjob -Stop the shell or its current subjob if any (@code{comint-stop-subjob}). -This command also kills any shell input pending in the shell buffer and -not yet sent. - -@item C-c C-\ -@findex comint-quit-subjob -@kindex C-c C-\ @r{(Shell mode)} -Send quit signal to the shell or its current subjob if any -(@code{comint-quit-subjob}). This command also kills any shell input -pending in the shell buffer and not yet sent. - -@item C-c C-o -@kindex C-c C-o @r{(Shell mode)} -@findex comint-delete-output -Delete the last batch of output from a shell command -(@code{comint-delete-output}). This is useful if a shell command spews -out lots of output that just gets in the way. This command used to be -called @code{comint-kill-output}. - -@item C-c C-s -@kindex C-c C-s @r{(Shell mode)} -@findex comint-write-output -Write the last batch of output from a shell command to a file -(@code{comint-write-output}). With a prefix argument, the file is -appended to instead. Any prompt at the end of the output is not -written. - -@item C-c C-r -@itemx C-M-l -@kindex C-c C-r @r{(Shell mode)} -@kindex C-M-l @r{(Shell mode)} -@findex comint-show-output -Scroll to display the beginning of the last batch of output at the top -of the window; also move the cursor there (@code{comint-show-output}). - -@item C-c C-e -@kindex C-c C-e @r{(Shell mode)} -@findex comint-show-maximum-output -Scroll to put the end of the buffer at the bottom of the window -(@code{comint-show-maximum-output}). - -@item C-c C-f -@kindex C-c C-f @r{(Shell mode)} -@findex shell-forward-command -@vindex shell-command-regexp -Move forward across one shell command, but not beyond the current line -(@code{shell-forward-command}). The variable @code{shell-command-regexp} -specifies how to recognize the end of a command. - -@item C-c C-b -@kindex C-c C-b @r{(Shell mode)} -@findex shell-backward-command -Move backward across one shell command, but not beyond the current line -(@code{shell-backward-command}). - -@item M-x dirs -Ask the shell what its current directory is, so that Emacs can agree -with the shell. - -@item M-x send-invisible @key{RET} @var{text} @key{RET} -@findex send-invisible -Send @var{text} as input to the shell, after reading it without -echoing. This is useful when a shell command runs a program that asks -for a password. - -Please note that Emacs will not echo passwords by default. If you -really want them to be echoed, evaluate the following Lisp -expression: - -@example -(remove-hook 'comint-output-filter-functions - 'comint-watch-for-password-prompt) -@end example - -@item M-x comint-continue-subjob -@findex comint-continue-subjob -Continue the shell process. This is useful if you accidentally suspend -the shell process.@footnote{You should not suspend the shell process. -Suspending a subjob of the shell is a completely different matter---that -is normal practice, but you must use the shell to continue the subjob; -this command won't do it.} - -@item M-x comint-strip-ctrl-m -@findex comint-strip-ctrl-m -Discard all control-M characters from the current group of shell output. -The most convenient way to use this command is to make it run -automatically when you get output from the subshell. To do that, -evaluate this Lisp expression: - -@example -(add-hook 'comint-output-filter-functions - 'comint-strip-ctrl-m) -@end example - -@item M-x comint-truncate-buffer -@findex comint-truncate-buffer -This command truncates the shell buffer to a certain maximum number of -lines, specified by the variable @code{comint-buffer-maximum-size}. -Here's how to do this automatically each time you get output from the -subshell: - -@example -(add-hook 'comint-output-filter-functions - 'comint-truncate-buffer) -@end example -@end table - -@cindex Comint mode -@cindex mode, Comint - Shell mode is a derivative of Comint mode, a general-purpose mode for -communicating with interactive subprocesses. Most of the features of -Shell mode actually come from Comint mode, as you can see from the -command names listed above. The special features of Shell mode include -the directory tracking feature, and a few user commands. - - Other Emacs features that use variants of Comint mode include GUD -(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). - -@findex comint-run - You can use @kbd{M-x comint-run} to execute any program of your choice -in a subprocess using unmodified Comint mode---without the -specializations of Shell mode. - -@node Shell Prompts -@subsection Shell Prompts - -@vindex shell-prompt-pattern -@vindex comint-prompt-regexp -@vindex comint-use-prompt-regexp -@cindex prompt, shell - A prompt is text output by a program to show that it is ready to -accept new user input. Normally, Comint mode (and thus Shell mode) -considers the prompt to be any text output by a program at the -beginning of an input line. However, if the variable -@code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode -uses a regular expression to recognize prompts. In Shell mode, -@code{shell-prompt-pattern} specifies the regular expression. - - The value of @code{comint-use-prompt-regexp} also affects many -motion and paragraph commands. If the value is non-@code{nil}, the -general Emacs motion commands behave as they normally do in buffers -without special text properties. However, if the value is @code{nil}, -the default, then Comint mode divides the buffer into two types of -``fields'' (ranges of consecutive characters having the same -@code{field} text property): input and output. Prompts are part of -the output. Most Emacs motion commands do not cross field boundaries, -unless they move over multiple lines. For instance, when point is in -input on the same line as a prompt, @kbd{C-a} puts point at the -beginning of the input if @code{comint-use-prompt-regexp} is -@code{nil} and at the beginning of the line otherwise. - - In Shell mode, only shell prompts start new paragraphs. Thus, a -paragraph consists of a prompt and the input and output that follow -it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the -default, most paragraph commands do not cross field boundaries. This -means that prompts, ranges of input, and ranges of non-prompt output -behave mostly like separate paragraphs; with this setting, numeric -arguments to most paragraph commands yield essentially undefined -behavior. For the purpose of finding paragraph boundaries, Shell mode -uses @code{shell-prompt-pattern}, regardless of -@code{comint-use-prompt-regexp}. - -@node Shell History -@subsection Shell Command History - - Shell buffers support three ways of repeating earlier commands. You -can use keys like those used for the minibuffer history; these work -much as they do in the minibuffer, inserting text from prior commands -while point remains always at the end of the buffer. You can move -through the buffer to previous inputs in their original place, then -resubmit them or copy them to the end. Or you can use a -@samp{!}-style history reference. - -@menu -* Ring: Shell Ring. Fetching commands from the history list. -* Copy: Shell History Copying. Moving to a command and then copying it. -* History References:: Expanding @samp{!}-style history references. -@end menu - -@node Shell Ring -@subsubsection Shell History Ring - -@table @kbd -@findex comint-previous-input -@kindex M-p @r{(Shell mode)} -@item M-p -@itemx C-@key{UP} -Fetch the next earlier old shell command. - -@kindex M-n @r{(Shell mode)} -@findex comint-next-input -@item M-n -@itemx C-@key{DOWN} -Fetch the next later old shell command. - -@kindex M-r @r{(Shell mode)} -@kindex M-s @r{(Shell mode)} -@findex comint-previous-matching-input -@findex comint-next-matching-input -@item M-r @var{regexp} @key{RET} -@itemx M-s @var{regexp} @key{RET} -Search backwards or forwards for old shell commands that match @var{regexp}. - -@item C-c C-x -@kindex C-c C-x @r{(Shell mode)} -@findex comint-get-next-from-history -Fetch the next subsequent command from the history. - -@item C-c . -@kindex C-c . @r{(Shell mode)} -@findex comint-input-previous-argument -Fetch one argument from an old shell command. - -@item C-c C-l -@kindex C-c C-l @r{(Shell mode)} -@findex comint-dynamic-list-input-ring -Display the buffer's history of shell commands in another window -(@code{comint-dynamic-list-input-ring}). -@end table - - Shell buffers provide a history of previously entered shell commands. To -reuse shell commands from the history, use the editing commands @kbd{M-p}, -@kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer -history commands except that they operate on the text at the end of the -shell buffer, where you would normally insert text to send to the shell. - - @kbd{M-p} fetches an earlier shell command to the end of the shell -buffer. Successive use of @kbd{M-p} fetches successively earlier -shell commands, each replacing any text that was already present as -potential shell input. @kbd{M-n} does likewise except that it finds -successively more recent shell commands from the buffer. -@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like -@kbd{M-n}. - - The history search commands @kbd{M-r} and @kbd{M-s} read a regular -expression and search through the history for a matching command. Aside -from the choice of which command to fetch, they work just like @kbd{M-p} -and @kbd{M-n}. If you enter an empty regexp, these commands reuse the -same regexp used last time. - - When you find the previous input you want, you can resubmit it by -typing @key{RET}, or you can edit it first and then resubmit it if you -wish. Any partial input you were composing before navigating the -history list is restored when you go to the beginning or end of the -history ring. - - Often it is useful to reexecute several successive shell commands that -were previously executed in sequence. To do this, first find and -reexecute the first command of the sequence. Then type @kbd{C-c C-x}; -that will fetch the following command---the one that follows the command -you just repeated. Then type @key{RET} to reexecute this command. You -can reexecute several successive commands by typing @kbd{C-c C-x -@key{RET}} over and over. - - The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) -copies an individual argument from a previous command, like @kbd{ESC -.} in Bash. The simplest use copies the last argument from the -previous shell command. With a prefix argument @var{n}, it copies the -@var{n}th argument instead. Repeating @kbd{C-c .} copies from an -earlier shell command instead, always using the same value of @var{n} -(don't give a prefix argument when you repeat the @kbd{C-c .} -command). - - These commands get the text of previous shell commands from a special -history list, not from the shell buffer itself. Thus, editing the shell -buffer, or even killing large parts of it, does not affect the history -that these commands access. - -@vindex shell-input-ring-file-name - Some shells store their command histories in files so that you can -refer to commands from previous shell sessions. Emacs reads -the command history file for your chosen shell, to initialize its own -command history. The file name is @file{~/.bash_history} for bash, -@file{~/.sh_history} for ksh, and @file{~/.history} for other shells. - -@node Shell History Copying -@subsubsection Shell History Copying - -@table @kbd -@kindex C-c C-p @r{(Shell mode)} -@findex comint-previous-prompt -@item C-c C-p -Move point to the previous prompt (@code{comint-previous-prompt}). - -@kindex C-c C-n @r{(Shell mode)} -@findex comint-next-prompt -@item C-c C-n -Move point to the following prompt (@code{comint-next-prompt}). - -@kindex C-c RET @r{(Shell mode)} -@findex comint-copy-old-input -@item C-c @key{RET} -Copy the input command which point is in, inserting the copy at the end -of the buffer (@code{comint-copy-old-input}). This is useful if you -move point back to a previous command. After you copy the command, you -can submit the copy as input with @key{RET}. If you wish, you can -edit the copy before resubmitting it. If you use this command on an -output line, it copies that line to the end of the buffer. - -@item Mouse-2 -If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy -the old input command that you click on, inserting the copy at the end -of the buffer (@code{comint-insert-input}). If -@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is -not over old input, just yank as usual. -@end table - - Moving to a previous input and then copying it with @kbd{C-c -@key{RET}} or @kbd{Mouse-2} produces the same results---the same -buffer contents---that you would get by using @kbd{M-p} enough times -to fetch that previous input from the history list. However, @kbd{C-c -@key{RET}} copies the text from the buffer, which can be different -from what is in the history list if you edit the input text in the -buffer after it has been sent. - -@node History References -@subsubsection Shell History References -@cindex history reference - - Various shells including csh and bash support @dfn{history -references} that begin with @samp{!} and @samp{^}. Shell mode -recognizes these constructs, and can perform the history substitution -for you. - - If you insert a history reference and type @key{TAB}, this searches -the input history for a matching command, performs substitution if -necessary, and places the result in the buffer in place of the history -reference. For example, you can fetch the most recent command -beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the -command if you wish, and then resubmit the command to the shell by -typing @key{RET}. - -@vindex comint-input-autoexpand -@findex comint-magic-space - Shell mode can optionally expand history references in the buffer -when you send them to the shell. To request this, set the variable -@code{comint-input-autoexpand} to @code{input}. You can make -@key{SPC} perform history expansion by binding @key{SPC} to the -command @code{comint-magic-space}. - - Shell mode recognizes history references when they follow a prompt. -@xref{Shell Prompts}, for how Shell mode recognizes prompts. - -@node Directory Tracking -@subsection Directory Tracking -@cindex directory tracking - -@vindex shell-pushd-regexp -@vindex shell-popd-regexp -@vindex shell-cd-regexp - Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} -commands given to the inferior shell, so it can keep the -@samp{*shell*} buffer's default directory the same as the shell's -working directory. It recognizes these commands syntactically, by -examining lines of input that are sent. - - If you use aliases for these commands, you can tell Emacs to -recognize them also. For example, if the value of the variable -@code{shell-pushd-regexp} matches the beginning of a shell command -line, that line is regarded as a @code{pushd} command. Change this -variable when you add aliases for @samp{pushd}. Likewise, -@code{shell-popd-regexp} and @code{shell-cd-regexp} are used to -recognize commands with the meaning of @samp{popd} and @samp{cd}. -These commands are recognized only at the beginning of a shell command -line. - -@ignore @c This seems to have been deleted long ago. -@vindex shell-set-directory-error-hook - If Emacs gets an error while trying to handle what it believes is a -@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook -@code{shell-set-directory-error-hook} (@pxref{Hooks}). -@end ignore - -@findex dirs - If Emacs gets confused about changes in the current directory of the -subshell, use the command @kbd{M-x dirs} to ask the shell what its -current directory is. This command works for shells that support the -most common command syntax; it may not work for unusual shells. - -@findex dirtrack-mode - You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an -alternative and more aggressive method of tracking changes in the -current directory. - -@node Shell Options -@subsection Shell Mode Options - -@vindex comint-scroll-to-bottom-on-input - If the variable @code{comint-scroll-to-bottom-on-input} is -non-@code{nil}, insertion and yank commands scroll the selected window -to the bottom before inserting. The default is @code{nil}. - -@vindex comint-scroll-show-maximum-output - If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then -arrival of output when point is at the end tries to scroll the last -line of text to the bottom line of the window, showing as much useful -text as possible. (This mimics the scrolling behavior of most -terminals.) The default is @code{t}. - -@vindex comint-move-point-for-output - By setting @code{comint-move-point-for-output}, you can opt for -having point jump to the end of the buffer whenever output arrives---no -matter where in the buffer point was before. If the value is -@code{this}, point jumps in the selected window. If the value is -@code{all}, point jumps in each window that shows the Comint buffer. If -the value is @code{other}, point jumps in all nonselected windows that -show the current buffer. The default value is @code{nil}, which means -point does not jump to the end. - -@vindex comint-prompt-read-only - If you set @code{comint-prompt-read-only}, the prompts in the Comint -buffer are read-only. - -@vindex comint-input-ignoredups - The variable @code{comint-input-ignoredups} controls whether successive -identical inputs are stored in the input history. A non-@code{nil} -value means to omit an input that is the same as the previous input. -The default is @code{nil}, which means to store each input even if it is -equal to the previous input. - -@vindex comint-completion-addsuffix -@vindex comint-completion-recexact -@vindex comint-completion-autolist - Three variables customize file name completion. The variable -@code{comint-completion-addsuffix} controls whether completion inserts a -space or a slash to indicate a fully completed file or directory name -(non-@code{nil} means do insert a space or slash). -@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} -to choose the shortest possible completion if the usual Emacs completion -algorithm cannot add even a single character. -@code{comint-completion-autolist}, if non-@code{nil}, says to list all -the possible completions whenever completion is not exact. - -@vindex shell-completion-execonly - Command completion normally considers only executable files. -If you set @code{shell-completion-execonly} to @code{nil}, -it considers nonexecutable files as well. - -@findex shell-pushd-tohome -@findex shell-pushd-dextract -@findex shell-pushd-dunique - You can configure the behavior of @samp{pushd}. Variables control -whether @samp{pushd} behaves like @samp{cd} if no argument is given -(@code{shell-pushd-tohome}), pop rather than rotate with a numeric -argument (@code{shell-pushd-dextract}), and only add directories to the -directory stack if they are not already on it -(@code{shell-pushd-dunique}). The values you choose should match the -underlying shell, of course. - - If you want Shell mode to handle color output from shell commands, -you can enable ANSI Color mode. Here is how to do this: - -@example -(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on) -@end example - -@node Terminal emulator -@subsection Emacs Terminal Emulator -@findex term - - To run a subshell in a terminal emulator, putting its typescript in -an Emacs buffer, use @kbd{M-x term}. This creates (or reuses) a -buffer named @samp{*terminal*}, and runs a subshell with input coming -from your keyboard, and output going to that buffer. - - The terminal emulator uses Term mode, which has two input modes. In -line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. - - In char mode, each character is sent directly to the inferior -subshell, as ``terminal input.'' Any ``echoing'' of your input is the -responsibility of the subshell. The sole exception is the terminal -escape character, which by default is @kbd{C-c} (@pxref{Term Mode}). -Any ``terminal output'' from the subshell goes into the buffer, -advancing point. - - Some programs (such as Emacs itself) need to control the appearance -on the terminal screen in detail. They do this by sending special -control codes. The exact control codes needed vary from terminal to -terminal, but nowadays most terminals and terminal emulators -(including @code{xterm}) understand the ANSI-standard (VT100-style) -escape sequences. Term mode recognizes these escape sequences, and -handles each one appropriately, changing the buffer so that the -appearance of the window matches what it would be on a real terminal. -You can actually run Emacs inside an Emacs Term window. - - The file name used to load the subshell is determined the same way -as for Shell mode. To make multiple terminal emulators, rename the -buffer @samp{*terminal*} to something different using @kbd{M-x -rename-uniquely}, just as with Shell mode. - - Unlike Shell mode, Term mode does not track the current directory by -examining your input. But some shells can tell Term what the current -directory is. This is done automatically by @code{bash} version 1.15 -and later. - -@node Term Mode -@subsection Term Mode -@cindex Term mode -@cindex mode, Term - - The terminal emulator uses Term mode, which has two input modes. In -line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. -In char mode, each character is sent directly to the inferior -subshell, except for the Term escape character, normally @kbd{C-c}. - - To switch between line and char mode, use these commands: - -@table @kbd -@kindex C-c C-j @r{(Term mode)} -@findex term-char-mode -@item C-c C-j -Switch to line mode. Do nothing if already in line mode. - -@kindex C-c C-k @r{(Term mode)} -@findex term-line-mode -@item C-c C-k -Switch to char mode. Do nothing if already in char mode. -@end table - - The following commands are only available in char mode: - -@table @kbd -@item C-c C-c -Send a literal @key{C-c} to the sub-shell. - -@item C-c @var{char} -This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For -example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which -is normally @samp{other-window}. -@end table - -@node Paging in Term -@subsection Page-At-A-Time Output -@cindex page-at-a-time - - Term mode has a page-at-a-time feature. When enabled it makes -output pause at the end of each screenful. - -@table @kbd -@kindex C-c C-q @r{(Term mode)} -@findex term-pager-toggle -@item C-c C-q -Toggle the page-at-a-time feature. This command works in both line -and char modes. When page-at-a-time is enabled, the mode-line -displays the word @samp{page}. -@end table - - With page-at-a-time enabled, whenever Term receives more than a -screenful of output since your last input, it pauses, displaying -@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next -screenful of output. Type @kbd{?} to see your other options. The -interface is similar to the @code{more} program. - -@node Remote Host -@subsection Remote Host Shell -@cindex remote host -@cindex connecting to remote host -@cindex Telnet -@cindex Rlogin - - You can login to a remote computer, using whatever commands you -would from a regular terminal (e.g.@: using the @code{telnet} or -@code{rlogin} commands), from a Term window. - - A program that asks you for a password will normally suppress -echoing of the password, so the password will not show up in the -buffer. This will happen just as if you were using a real terminal, -if the buffer is in char mode. If it is in line mode, the password is -temporarily visible, but will be erased when you hit return. (This -happens automatically; there is no special password processing.) - - When you log in to a different machine, you need to specify the type -of terminal you're using, by setting the @env{TERM} environment -variable in the environment for the remote login command. (If you use -bash, you do that by writing the variable assignment before the remote -login command, without separating comma.) Terminal types @samp{ansi} -or @samp{vt100} will work on most systems. - -@c If you are talking to a Bourne-compatible -@c shell, and your system understands the @env{TERMCAP} variable, -@c you can use the command @kbd{M-x shell-send-termcap}, which -@c sends a string specifying the terminal type and size. -@c (This command is also useful after the window has changed size.) - -@c You can of course run @samp{gdb} on that remote computer. One useful -@c trick: If you invoke gdb with the @code{--fullname} option, -@c it will send special commands to Emacs that will cause Emacs to -@c pop up the source files you're debugging. This will work -@c whether or not gdb is running on a different computer than Emacs, -@c as long as Emacs can access the source files specified by gdb. - -@ignore - You cannot log in to a remote computer using the Shell mode. -@c (This will change when Shell is re-written to use Term.) -Instead, Emacs provides two commands for logging in to another computer -and communicating with it through an Emacs buffer using Comint mode: - -@table @kbd -@item M-x telnet @key{RET} @var{hostname} @key{RET} -Set up a Telnet connection to the computer named @var{hostname}. -@item M-x rlogin @key{RET} @var{hostname} @key{RET} -Set up an Rlogin connection to the computer named @var{hostname}. -@end table - -@findex telnet - Use @kbd{M-x telnet} to set up a Telnet connection to another -computer. (Telnet is the standard Internet protocol for remote login.) -It reads the host name of the other computer as an argument with the -minibuffer. Once the connection is established, talking to the other -computer works like talking to a subshell: you can edit input with the -usual Emacs commands, and send it a line at a time by typing @key{RET}. -The output is inserted in the Telnet buffer interspersed with the input. - -@findex rlogin -@vindex rlogin-explicit-args - Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is -another remote login communication protocol, essentially much like the -Telnet protocol but incompatible with it, and supported only by certain -systems. Rlogin's advantages are that you can arrange not to have to -give your user name and password when communicating between two machines -you frequently use, and that you can make an 8-bit-clean connection. -(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")} -before you run Rlogin.) - - @kbd{M-x rlogin} sets up the default file directory of the Emacs -buffer to access the remote host via FTP (@pxref{File Names}), and it -tracks the shell commands that change the current directory, just like -Shell mode. - -@findex rlogin-directory-tracking-mode - There are two ways of doing directory tracking in an Rlogin -buffer---either with remote directory names -@file{/@var{host}:@var{dir}/} or with local names (that works if the -``remote'' machine shares file systems with your machine of origin). -You can use the command @code{rlogin-directory-tracking-mode} to switch -modes. No argument means use remote directory names, a positive -argument means use local names, and a negative argument means turn -off directory tracking. - -@end ignore - -@node Emacs Server, Printing, Shell, Top -@section Using Emacs as a Server -@pindex emacsclient -@cindex Emacs as a server -@cindex server, using Emacs as -@cindex @env{EDITOR} environment variable - - Various programs such as @code{mail} can invoke your choice of editor -to edit a particular piece of text, such as a message that you are -sending. By convention, most of these programs use the environment -variable @env{EDITOR} to specify which editor to run. If you set -@env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an -inconvenient fashion, by starting a new, separate Emacs process. This -is inconvenient because it takes time and because the new Emacs process -doesn't share the buffers with any existing Emacs process. - - You can arrange to use your existing Emacs process as the editor for -programs like @code{mail} by using the Emacs client program and the -server that is part of Emacs. Here is how. - -@cindex @env{TEXEDIT} environment variable -@findex server-start - First, the preparations. Within Emacs, call the function -@code{server-start}. (Your @file{.emacs} init file can do this -automatically if you add the expression @code{(server-start)} to it, -see @ref{Init File}.) Then, outside Emacs, set the @env{EDITOR} -environment variable to @samp{emacsclient}. (Note that some programs -use a different environment variable; for example, to make @TeX{} use -@samp{emacsclient}, you should set the @env{TEXEDIT} environment -variable to @samp{emacsclient +%d %s}.) - -@pindex emacs.bash -@cindex Bash command to use Emacs server - As an alternative to using @code{emacsclient}, the file -@file{etc/emacs.bash} defines a Bash command @code{edit} which will -communicate with a running Emacs session, or start one if none exist. - -@kindex C-x # -@findex server-edit - Now, whenever any program invokes your specified @env{EDITOR} -program, the effect is to send a message to your principal Emacs telling -it to visit a file. (That's what the program @code{emacsclient} does.) -Emacs displays the buffer immediately and you can immediately begin -editing it in the already running Emacs session. - - When you've finished editing that buffer, type @kbd{C-x #} -(@code{server-edit}). This saves the file and sends a message back to -the @code{emacsclient} program telling it to exit. The programs that -use @env{EDITOR} wait for the ``editor'' (actually, @code{emacsclient}) -to exit. @kbd{C-x #} also checks for other pending external requests -to edit various files, and selects the next such file. - - You can switch to a server buffer manually if you wish; you don't -have to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the way to -say that you are finished with one. - -@vindex server-kill-new-buffers -@vindex server-temp-file-regexp - Finishing with a server buffer also kills the buffer, unless it -already existed in the Emacs session before the server asked to create -it. However, if you set @code{server-kill-new-buffers} to @code{nil}, -then a different criterion is used: finishing with a server buffer -kills it if the file name matches the regular expression -@code{server-temp-file-regexp}. This is set up to distinguish certain -``temporary'' files. - -@vindex server-window - If you set the variable @code{server-window} to a window or a frame, -@kbd{C-x #} displays the server buffer in that window or in that frame. - -@vindex server-name - You can run multiple Emacs servers on the same machine by giving -each one a unique ``server name'', using the variable -@code{server-name}. For example, @kbd{M-x set-variable @key{RET} -server-name @key{RET} foo @key{RET}} sets the server name to -@samp{foo}. The @code{emacsclient} program can specify a server by -name using the @samp{-s} option. @xref{Invoking emacsclient}. - - While @code{mail} or another application is waiting for -@code{emacsclient} to finish, @code{emacsclient} does not read terminal -input. So the terminal that @code{mail} was using is effectively -blocked for the duration. In order to edit with your principal Emacs, -you need to be able to use it without using that terminal. There are -three ways to do this: - -@itemize @bullet -@item -Using a window system, run @code{mail} and the principal Emacs in two -separate windows. While @code{mail} is waiting for @code{emacsclient}, -the window where it was running is blocked, but you can use Emacs by -switching windows. - -@item -Using virtual terminals, run @code{mail} in one virtual terminal -and run Emacs in another. - -@item -Use Shell mode or Term mode in Emacs to run the other program such as -@code{mail}; then, @code{emacsclient} blocks only the subshell under -Emacs, and you can still use Emacs to edit the file. -@end itemize - - If you run @code{emacsclient} with the option @samp{--no-wait}, it -returns immediately without waiting for you to ``finish'' the buffer -in Emacs. Note that server buffers created in this way are not killed -automatically when you finish with them. - -@menu -* Invoking emacsclient:: Emacs client startup options. -@end menu - -@node Invoking emacsclient,, Emacs Server, Emacs Server -@subsection Invoking @code{emacsclient} -@cindex @code{emacsclient} invocation and options - - To run the @code{emacsclient} program, specify file names as arguments, -and optionally line numbers as well, like this: - -@example -emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{} -@end example - -@noindent -This tells Emacs to visit each of the specified files; if you specify a -line number for a certain file, Emacs moves to that line in the file. -If you specify a column number as well, Emacs puts point on that column -in the line. - - Ordinarily, @code{emacsclient} does not return until you use the -@kbd{C-x #} command on each of these buffers. When that happens, -Emacs sends a message to the @code{emacsclient} program telling it to -return. - - If you invoke @code{emacsclient} for more than one file, the -additional client buffers are buried at the bottom of the buffer list -(@pxref{Buffers}). If you call @kbd{C-x #} after you are done editing -a client buffer, the next client buffer is automatically selected. - - But if you use the option @samp{-n} or @samp{--no-wait} when running -@code{emacsclient}, then it returns immediately. (You can take as -long as you like to edit the files in Emacs.) - - The option @samp{-a @var{command}} or -@samp{--alternate-editor=@var{command}} specifies a command to run if -@code{emacsclient} fails to contact Emacs. This is useful when -running @code{emacsclient} in a script. For example, the following -setting for the @env{EDITOR} environment variable will always give you -an editor, even if no Emacs server is running: - -@example -EDITOR="emacsclient --alternate-editor emacs +%d %s" -@end example - -@noindent -@cindex @env{ALTERNATE_EDITOR} environment variable -The environment variable @env{ALTERNATE_EDITOR} has the same effect, with -the value of the @samp{--alternate-editor} option taking precedence. - -If you use several displays, you can tell Emacs on which display to -open the given files with the @samp{-d @var{display}} or -@samp{--display=@var{display}} option to @code{emacsclient}. This is -handy when connecting from home to an Emacs session running on your -machine at your workplace. - -If there is more than one Emacs server running, you can specify a -server name with the @samp{-s @var{name}} or -@samp{--socket-name=@var{name}} option to @code{emacsclient}. (This -option is not supported on MS-Windows.) - -You can also use @code{emacsclient} to execute any piece of Emacs Lisp -code, using the @samp{-e} or @samp{--eval} option. When this option -is given, the rest of the arguments is interpreted as a list of -expressions to evaluate, not a list of files to visit. - -@cindex @env{EMACS_SERVER_FILE} environment variable -When you start the Emacs server (by calling @code{server-start}), -Emacs creates a file with information about TCP connection to the -server: the host where Emacs is running, the port where it is -listening, and an authentication string. @code{emacsclient} uses this -information if it needs to connect to the server via TCP. By default, -the file goes in the @file{~/.emacs.d/server/} directory@footnote{On -MS-Windows, if @env{HOME} is not set or the TCP configuration file -cannot be found there, Emacs also looks for the file in the -@file{.emacs.d/server/} subdirectory of the directory pointed to by -the @env{APPDATA} environment variable.}. You can specify the file -name to use with the @samp{-f @var{file}} or -@samp{--server-file=@var{file}} options, or by setting -@env{EMACS_SERVER_FILE} environment variable to the file name. - -@node Printing, Sorting, Emacs Server, Top -@section Printing Hard Copies -@cindex hardcopy -@cindex printing - - Emacs provides commands for printing hard copies of either an entire -buffer or just part of one, with or without page headers. You can -invoke the printing commands directly, as detailed in the following -section, or using the @samp{File} menu on the menu bar. See also the -hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary -(@pxref{Displaying the Diary}). - -@table @kbd -@item M-x print-buffer -Print hardcopy of current buffer with page headings containing the file -name and page number. -@item M-x lpr-buffer -Print hardcopy of current buffer without page headings. -@item M-x print-region -Like @code{print-buffer} but print only the current region. -@item M-x lpr-region -Like @code{lpr-buffer} but print only the current region. -@end table - -@findex print-buffer -@findex print-region -@findex lpr-buffer -@findex lpr-region -@vindex lpr-switches - The hardcopy commands (aside from the PostScript commands) pass extra -switches to the @code{lpr} program based on the value of the variable -@code{lpr-switches}. Its value should be a list of strings, each string -an option starting with @samp{-}. For example, to specify a line width -of 80 columns for all the printing you do in Emacs, set -@code{lpr-switches} like this: - -@example -(setq lpr-switches '("-w80")) -@end example - -@vindex printer-name - You can specify the printer to use by setting the variable -@code{printer-name}. - -@vindex lpr-headers-switches -@vindex lpr-commands -@vindex lpr-add-switches - The variable @code{lpr-command} specifies the name of the printer -program to run; the default value depends on your operating system type. -On most systems, the default is @code{"lpr"}. The variable -@code{lpr-headers-switches} similarly specifies the extra switches to -use to make page headers. The variable @code{lpr-add-switches} controls -whether to supply @samp{-T} and @samp{-J} options (suitable for -@code{lpr}) to the printer program: @code{nil} means don't add them. -@code{lpr-add-switches} should be @code{nil} if your printer program is -not compatible with @code{lpr}. - -@menu -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. -@end menu - -@node PostScript, PostScript Variables,, Printing -@section PostScript Hardcopy - - These commands convert buffer contents to PostScript, -either printing it or leaving it in another Emacs buffer. - -@table @kbd -@item M-x ps-print-buffer -Print hardcopy of the current buffer in PostScript form. -@item M-x ps-print-region -Print hardcopy of the current region in PostScript form. -@item M-x ps-print-buffer-with-faces -Print hardcopy of the current buffer in PostScript form, showing the -faces used in the text by means of PostScript features. -@item M-x ps-print-region-with-faces -Print hardcopy of the current region in PostScript form, showing the -faces used in the text. -@item M-x ps-spool-buffer -Generate PostScript for the current buffer text. -@item M-x ps-spool-region -Generate PostScript for the current region. -@item M-x ps-spool-buffer-with-faces -Generate PostScript for the current buffer, showing the faces used. -@item M-x ps-spool-region-with-faces -Generate PostScript for the current region, showing the faces used. -@item M-x handwrite -Generates/prints PostScript for the current buffer as if handwritten. -@end table - -@findex ps-print-region -@findex ps-print-buffer -@findex ps-print-region-with-faces -@findex ps-print-buffer-with-faces - The PostScript commands, @code{ps-print-buffer} and -@code{ps-print-region}, print buffer contents in PostScript form. One -command prints the entire buffer; the other, just the region. The -corresponding @samp{-with-faces} commands, -@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces}, -use PostScript features to show the faces (fonts and colors) in the text -properties of the text being printed. - - If you are using a color display, you can print a buffer of program -code with color highlighting by turning on Font-Lock mode in that -buffer, and using @code{ps-print-buffer-with-faces}. - -@findex ps-spool-region -@findex ps-spool-buffer -@findex ps-spool-region-with-faces -@findex ps-spool-buffer-with-faces - The commands whose names have @samp{spool} instead of @samp{print} -generate the PostScript output in an Emacs buffer instead of sending -it to the printer. - -@findex handwrite -@cindex handwriting -@kbd{M-x handwrite} is more frivolous. It generates a PostScript -rendition of the current buffer as a cursive handwritten document. It -can be customized in group @code{handwrite}. This function only -supports ISO 8859-1 characters. - -@ifnottex - The following section describes variables for customizing these commands. -@end ifnottex - -@node PostScript Variables, Printing Package, PostScript, Printing -@section Variables for PostScript Hardcopy - -@vindex ps-lpr-command -@vindex ps-lpr-switches -@vindex ps-printer-name - All the PostScript hardcopy commands use the variables -@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print -the output. @code{ps-lpr-command} specifies the command name to run, -@code{ps-lpr-switches} specifies command line options to use, and -@code{ps-printer-name} specifies the printer. If you don't set the -first two variables yourself, they take their initial values from -@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} -is @code{nil}, @code{printer-name} is used. - -@vindex ps-print-header - The variable @code{ps-print-header} controls whether these commands -add header lines to each page---set it to @code{nil} to turn headers -off. - -@cindex color emulation on black-and-white printers -@vindex ps-print-color-p - If your printer doesn't support colors, you should turn off color -processing by setting @code{ps-print-color-p} to @code{nil}. By -default, if the display supports colors, Emacs produces hardcopy output -with color information; on black-and-white printers, colors are emulated -with shades of gray. This might produce illegible output, even if your -screen colors only use shades of gray. - -@vindex ps-use-face-background - By default, PostScript printing ignores the background colors of the -faces, unless the variable @code{ps-use-face-background} is -non-@code{nil}. This is to avoid unwanted interference with the zebra -stripes and background image/text. - -@vindex ps-paper-type -@vindex ps-page-dimensions-database - The variable @code{ps-paper-type} specifies which size of paper to -format for; legitimate values include @code{a4}, @code{a3}, -@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, -@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, -@code{tabloid}. The default is @code{letter}. You can define -additional paper sizes by changing the variable -@code{ps-page-dimensions-database}. - -@vindex ps-landscape-mode - The variable @code{ps-landscape-mode} specifies the orientation of -printing on the page. The default is @code{nil}, which stands for -``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' -mode. - -@vindex ps-number-of-columns - The variable @code{ps-number-of-columns} specifies the number of -columns; it takes effect in both landscape and portrait mode. The -default is 1. - -@vindex ps-font-family -@vindex ps-font-size -@vindex ps-font-info-database - The variable @code{ps-font-family} specifies which font family to use -for printing ordinary text. Legitimate values include @code{Courier}, -@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and -@code{Times}. The variable @code{ps-font-size} specifies the size of -the font for ordinary text. It defaults to 8.5 points. - -@vindex ps-multibyte-buffer -@cindex Intlfonts for PostScript printing -@cindex fonts for PostScript printing - Emacs supports more scripts and characters than a typical PostScript -printer. Thus, some of the characters in your buffer might not be -printable using the fonts built into your printer. You can augment -the fonts supplied with the printer with those from the GNU Intlfonts -package, or you can instruct Emacs to use Intlfonts exclusively. The -variable @code{ps-multibyte-buffer} controls this: the default value, -@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 -characters; a value of @code{non-latin-printer} is for printers which -have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean -characters built into them. A value of @code{bdf-font} arranges for -the BDF fonts from the Intlfonts package to be used for @emph{all} -characters. Finally, a value of @code{bdf-font-except-latin} -instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 -characters, and Intlfonts BDF fonts for the rest. - -@vindex bdf-directory-list - To be able to use the BDF fonts, Emacs needs to know where to find -them. The variable @code{bdf-directory-list} holds the list of -directories where Emacs should look for the fonts; the default value -includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. - - Many other customization variables for these commands are defined and -described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. - -@node Printing Package,, PostScript Variables, Printing -@section Printing Package -@cindex Printing package - - The basic Emacs facilities for printing hardcopy can be extended -using the Printing package. This provides an easy-to-use interface -for choosing what to print, previewing PostScript files before -printing, and setting various printing options such as print headers, -landscape or portrait modes, duplex modes, and so forth. On GNU/Linux -or Unix systems, the Printing package relies on the @file{gs} and -@file{gv} utilities, which are distributed as part of the GhostScript -program. On MS-Windows, the @file{gstools} port of Ghostscript can be -used. - -@findex pr-interface - To use the Printing package, add @code{(require 'printing)} to your -init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. -This function replaces the usual printing commands in the menu bar -with a @samp{Printing} submenu that contains various printing options. -You can also type @kbd{M-x pr-interface RET}; this creates a -@samp{*Printing Interface*} buffer, similar to a customization buffer, -where you can set the printing options. After selecting what and how -to print, you start the print job using the @samp{Print} button (click -@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For -further information on the various options, use the @samp{Interface -Help} button. - -@node Sorting, Narrowing, Printing, Top -@section Sorting Text -@cindex sorting - - Emacs provides several commands for sorting text in the buffer. All -operate on the contents of the region. -They divide the text of the region into many @dfn{sort records}, -identify a @dfn{sort key} for each record, and then reorder the records -into the order determined by the sort keys. The records are ordered so -that their keys are in alphabetical order, or, for numeric sorting, in -numeric order. In alphabetic sorting, all upper-case letters `A' through -`Z' come before lower-case `a', in accord with the @acronym{ASCII} character -sequence. - - The various sort commands differ in how they divide the text into sort -records and in which part of each record is used as the sort key. Most of -the commands make each line a separate sort record, but some commands use -paragraphs or pages as sort records. Most of the sort commands use each -entire sort record as its own sort key, but some use only a portion of the -record as the sort key. - -@findex sort-lines -@findex sort-paragraphs -@findex sort-pages -@findex sort-fields -@findex sort-numeric-fields -@vindex sort-numeric-base -@table @kbd -@item M-x sort-lines -Divide the region into lines, and sort by comparing the entire -text of a line. A numeric argument means sort into descending order. - -@item M-x sort-paragraphs -Divide the region into paragraphs, and sort by comparing the entire -text of a paragraph (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-pages -Divide the region into pages, and sort by comparing the entire -text of a page (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-fields -Divide the region into lines, and sort by comparing the contents of -one field in each line. Fields are defined as separated by -whitespace, so the first run of consecutive non-whitespace characters -in a line constitutes field 1, the second such run constitutes field -2, etc. - -Specify which field to sort by with a numeric argument: 1 to sort by -field 1, etc. A negative argument means count fields from the right -instead of from the left; thus, minus 1 means sort by the last field. -If several lines have identical contents in the field being sorted, they -keep the same relative order that they had in the original buffer. - -@item M-x sort-numeric-fields -Like @kbd{M-x sort-fields} except the specified field is converted -to an integer for each line, and the numbers are compared. @samp{10} -comes before @samp{2} when considered as text, but after it when -considered as a number. By default, numbers are interpreted according -to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or -@samp{0} are interpreted as hexadecimal and octal, respectively. - -@item M-x sort-columns -Like @kbd{M-x sort-fields} except that the text within each line -used for comparison comes from a fixed range of columns. See below -for an explanation. - -@item M-x reverse-region -Reverse the order of the lines in the region. This is useful for -sorting into descending order by fields or columns, since those sort -commands do not have a feature for doing that. -@end table - - For example, if the buffer contains this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -whether the file has changed on disk since it was last visited or -saved. If it has, you are asked to confirm that you want to change -the buffer. -@end smallexample - -@noindent -applying @kbd{M-x sort-lines} to the entire buffer produces this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the upper-case @samp{O} sorts before all lower-case letters. If -you use @kbd{C-u 2 M-x sort-fields} instead, you get this: - -@smallexample -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -On systems where clash detection (locking of files being edited) is -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, -@samp{systems} and @samp{the}. - -@findex sort-columns - @kbd{M-x sort-columns} requires more explanation. You specify the -columns by putting point at one of the columns and the mark at the other -column. Because this means you cannot put point or the mark at the -beginning of the first line of the text you want to sort, this command -uses an unusual definition of ``region'': all of the line point is in is -considered part of the region, and so is all of the line the mark is in, -as well as all the lines in between. - - For example, to sort a table by information found in columns 10 to 15, -you could put the mark on column 10 in the first line of the table, and -point on column 15 in the last line of the table, and then run -@code{sort-columns}. Equivalently, you could run it with the mark on -column 15 in the first line and point on column 10 in the last line. - - This can be thought of as sorting the rectangle specified by point and -the mark, except that the text on each line to the left or right of the -rectangle moves along with the text inside the rectangle. -@xref{Rectangles}. - -@vindex sort-fold-case - Many of the sort commands ignore case differences when comparing, if -@code{sort-fold-case} is non-@code{nil}. - -@node Narrowing, Two-Column, Sorting, Top -@section Narrowing -@cindex widening -@cindex restriction -@cindex narrowing -@cindex accessible portion - - @dfn{Narrowing} means focusing in on some portion of the buffer, -making the rest temporarily inaccessible. The portion which you can -still get to is called the @dfn{accessible portion}. Canceling the -narrowing, which makes the entire buffer once again accessible, is -called @dfn{widening}. The bounds of narrowing in effect in a buffer -are called the buffer's @dfn{restriction}. - - Narrowing can make it easier to concentrate on a single subroutine or -paragraph by eliminating clutter. It can also be used to limit the -range of operation of a replace command or repeating keyboard macro. - -@table @kbd -@item C-x n n -Narrow down to between point and mark (@code{narrow-to-region}). -@item C-x n w -Widen to make the entire buffer accessible again (@code{widen}). -@item C-x n p -Narrow down to the current page (@code{narrow-to-page}). -@item C-x n d -Narrow down to the current defun (@code{narrow-to-defun}). -@end table - - When you have narrowed down to a part of the buffer, that part appears -to be all there is. You can't see the rest, you can't move into it -(motion commands won't go outside the accessible part), you can't change -it in any way. However, it is not gone, and if you save the file all -the inaccessible text will be saved. The word @samp{Narrow} appears in -the mode line whenever narrowing is in effect. - -@kindex C-x n n -@findex narrow-to-region - The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}). -It sets the current buffer's restrictions so that the text in the current -region remains accessible, but all text before the region or after the -region is inaccessible. Point and mark do not change. - -@kindex C-x n p -@findex narrow-to-page -@kindex C-x n d -@findex narrow-to-defun - Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow -down to the current page. @xref{Pages}, for the definition of a page. -@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun -containing point (@pxref{Defuns}). - -@kindex C-x n w -@findex widen - The way to cancel narrowing is to widen with @kbd{C-x n w} -(@code{widen}). This makes all text in the buffer accessible again. - - You can get information on what part of the buffer you are narrowed down -to using the @kbd{C-x =} command. @xref{Position Info}. - - Because narrowing can easily confuse users who do not understand it, -@code{narrow-to-region} is normally a disabled command. Attempting to use -this command asks for confirmation and gives you the option of enabling it; -if you enable the command, confirmation will no longer be required for -it. @xref{Disabling}. - -@node Two-Column, Editing Binary Files, Narrowing, Top -@section Two-Column Editing -@cindex two-column editing -@cindex splitting columns -@cindex columns, splitting - - Two-column mode lets you conveniently edit two side-by-side columns of -text. It uses two side-by-side windows, each showing its own -buffer. - - There are three ways to enter two-column mode: - -@table @asis -@item @kbd{@key{F2} 2} or @kbd{C-x 6 2} -@kindex F2 2 -@kindex C-x 6 2 -@findex 2C-two-columns -Enter two-column mode with the current buffer on the left, and on the -right, a buffer whose name is based on the current buffer's name -(@code{2C-two-columns}). If the right-hand buffer doesn't already -exist, it starts out empty; the current buffer's contents are not -changed. - -This command is appropriate when the current buffer is empty or contains -just one column and you want to add another column. - -@item @kbd{@key{F2} s} or @kbd{C-x 6 s} -@kindex F2 s -@kindex C-x 6 s -@findex 2C-split -Split the current buffer, which contains two-column text, into two -buffers, and display them side by side (@code{2C-split}). The current -buffer becomes the left-hand buffer, but the text in the right-hand -column is moved into the right-hand buffer. The current column -specifies the split point. Splitting starts with the current line and -continues to the end of the buffer. - -This command is appropriate when you have a buffer that already contains -two-column text, and you wish to separate the columns temporarily. - -@item @kbd{@key{F2} b @var{buffer} @key{RET}} -@itemx @kbd{C-x 6 b @var{buffer} @key{RET}} -@kindex F2 b -@kindex C-x 6 b -@findex 2C-associate-buffer -Enter two-column mode using the current buffer as the left-hand buffer, -and using buffer @var{buffer} as the right-hand buffer -(@code{2C-associate-buffer}). -@end table - - @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which -is a string that appears on each line between the two columns. You can -specify the width of the separator with a numeric argument to -@kbd{@key{F2} s}; that many characters, before point, constitute the -separator string. By default, the width is 1, so the column separator -is the character before point. - - When a line has the separator at the proper place, @kbd{@key{F2} s} -puts the text after the separator into the right-hand buffer, and -deletes the separator. Lines that don't have the column separator at -the proper place remain unsplit; they stay in the left-hand buffer, and -the right-hand buffer gets an empty line to correspond. (This is the -way to write a line that ``spans both columns while in two-column -mode'': write it in the left-hand buffer, and put an empty line in the -right-hand buffer.) - -@kindex F2 RET -@kindex C-x 6 RET -@findex 2C-newline - The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} -(@code{2C-newline}) inserts a newline in each of the two buffers at -corresponding positions. This is the easiest way to add a new line to -the two-column text while editing it in split buffers. - -@kindex F2 1 -@kindex C-x 6 1 -@findex 2C-merge - When you have edited both buffers as you wish, merge them with -@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the -text from the right-hand buffer as a second column in the other buffer. -To go back to two-column editing, use @kbd{@key{F2} s}. - -@kindex F2 d -@kindex C-x 6 d -@findex 2C-dissociate - Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, -leaving each as it stands (@code{2C-dissociate}). If the other buffer, -the one not current when you type @kbd{@key{F2} d}, is empty, -@kbd{@key{F2} d} kills it. - -@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top -@section Editing Binary Files - -@cindex Hexl mode -@cindex mode, Hexl -@cindex editing binary files -@cindex hex editing - There is a special major mode for editing binary files: Hexl mode. To -use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit -the file. This command converts the file's contents to hexadecimal and -lets you edit the translation. When you save the file, it is converted -automatically back to binary. - - You can also use @kbd{M-x hexl-mode} to translate an existing buffer -into hex. This is useful if you visit a file normally and then discover -it is a binary file. - - Ordinary text characters overwrite in Hexl mode. This is to reduce -the risk of accidentally spoiling the alignment of data in the file. -There are special commands for insertion. Here is a list of the -commands of Hexl mode: - -@c I don't think individual index entries for these commands are useful--RMS. -@table @kbd -@item C-M-d -Insert a byte with a code typed in decimal. - -@item C-M-o -Insert a byte with a code typed in octal. - -@item C-M-x -Insert a byte with a code typed in hex. - -@item C-x [ -Move to the beginning of a 1k-byte ``page.'' - -@item C-x ] -Move to the end of a 1k-byte ``page.'' - -@item M-g -Move to an address specified in hex. - -@item M-j -Move to an address specified in decimal. - -@item C-c C-c -Leave Hexl mode, going back to the major mode this buffer had before you -invoked @code{hexl-mode}. -@end table - -@noindent -Other Hexl commands let you insert strings (sequences) of binary -bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a -hexl-@key{RET}} for details. - - -@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top -@section Saving Emacs Sessions -@cindex saving sessions -@cindex restore session -@cindex remember editing session -@cindex reload files -@cindex desktop - - Use the desktop library to save the state of Emacs from one session -to another. Once you save the Emacs @dfn{desktop}---the buffers, -their file names, major modes, buffer positions, and so on---then -subsequent Emacs sessions reload the saved desktop. - -@findex desktop-save -@vindex desktop-save-mode - You can save the desktop manually with the command @kbd{M-x -desktop-save}. You can also enable automatic saving of the desktop -when you exit Emacs, and automatic restoration of the last saved -desktop when Emacs starts: use the Customization buffer (@pxref{Easy -Customization}) to set @code{desktop-save-mode} to @code{t} for future -sessions, or add this line in your @file{~/.emacs} file: - -@example -(desktop-save-mode 1) -@end example - -@findex desktop-change-dir -@findex desktop-revert - If you turn on @code{desktop-save-mode} in your @file{~/.emacs}, -then when Emacs starts, it looks for a saved desktop in the current -directory. Thus, you can have separate saved desktops in different -directories, and the starting directory determines which one Emacs -reloads. You can save the current desktop and reload one saved in -another directory by typing @kbd{M-x desktop-change-dir}. Typing -@kbd{M-x desktop-revert} reverts to the desktop previously reloaded. - - Specify the option @samp{--no-desktop} on the command line when you -don't want it to reload any saved desktop. This turns off -@code{desktop-save-mode} for the current session. Starting Emacs with -the @samp{--no-init-file} option also disables desktop reloading, -since it bypasses the @file{.emacs} init file, where -@code{desktop-save-mode} is usually turned on. - -@vindex desktop-restore-eager - By default, all the buffers in the desktop are restored at one go. -However, this may be slow if there are a lot of buffers in the -desktop. You can specify the maximum number of buffers to restore -immediately with the variable @code{desktop-restore-eager}; the -remaining buffers are restored ``lazily,'' when Emacs is idle. - -@findex desktop-clear -@vindex desktop-globals-to-clear -@vindex desktop-clear-preserve-buffers-regexp - Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills -all buffers except for internal ones, and clears the global variables -listed in @code{desktop-globals-to-clear}. If you want this to -preserve certain buffers, customize the variable -@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular -expression matching the names of buffers not to kill. - - If you want to save minibuffer history from one session to -another, use the @code{savehist} library. - -@node Recursive Edit, Emulation, Saving Emacs Sessions, Top -@section Recursive Editing Levels -@cindex recursive editing level -@cindex editing level, recursive - - A @dfn{recursive edit} is a situation in which you are using Emacs -commands to perform arbitrary editing while in the middle of another -Emacs command. For example, when you type @kbd{C-r} inside of a -@code{query-replace}, you enter a recursive edit in which you can change -the current buffer. On exiting from the recursive edit, you go back to -the @code{query-replace}. - -@kindex C-M-c -@findex exit-recursive-edit -@cindex exiting recursive edit - @dfn{Exiting} the recursive edit means returning to the unfinished -command, which continues execution. The command to exit is @kbd{C-M-c} -(@code{exit-recursive-edit}). - - You can also @dfn{abort} the recursive edit. This is like exiting, -but also quits the unfinished command immediately. Use the command -@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. - - The mode line shows you when you are in a recursive edit by displaying -square brackets around the parentheses that always surround the major and -minor mode names. Every window's mode line shows this in the same way, -since being in a recursive edit is true of Emacs as a whole rather than -any particular window or buffer. - - It is possible to be in recursive edits within recursive edits. For -example, after typing @kbd{C-r} in a @code{query-replace}, you may type a -command that enters the debugger. This begins a recursive editing level -for the debugger, within the recursive editing level for @kbd{C-r}. -Mode lines display a pair of square brackets for each recursive editing -level currently in progress. - - Exiting the inner recursive edit (such as with the debugger @kbd{c} -command) resumes the command running in the next level up. When that -command finishes, you can then use @kbd{C-M-c} to exit another recursive -editing level, and so on. Exiting applies to the innermost level only. -Aborting also gets out of only one level of recursive edit; it returns -immediately to the command level of the previous recursive edit. If you -wish, you can then abort the next recursive editing level. - - Alternatively, the command @kbd{M-x top-level} aborts all levels of -recursive edits, returning immediately to the top-level command reader. - - The text being edited inside the recursive edit need not be the same text -that you were editing at top level. It depends on what the recursive edit -is for. If the command that invokes the recursive edit selects a different -buffer first, that is the buffer you will edit recursively. In any case, -you can switch buffers within the recursive edit in the normal manner (as -long as the buffer-switching keys have not been rebound). You could -probably do all the rest of your editing inside the recursive edit, -visiting files and all. But this could have surprising effects (such as -stack overflow) from time to time. So remember to exit or abort the -recursive edit when you no longer need it. - - In general, we try to minimize the use of recursive editing levels in -GNU Emacs. This is because they constrain you to ``go back'' in a -particular order---from the innermost level toward the top level. When -possible, we present different activities in separate buffers so that -you can switch between them as you please. Some commands switch to a -new major mode which provides a command to switch back. These -approaches give you more flexibility to go back to unfinished tasks in -the order you choose. - -@node Emulation, Hyperlinking, Recursive Edit, Top -@section Emulation -@cindex emulating other editors -@cindex other editors -@cindex EDT -@cindex vi -@cindex PC key bindings -@cindex scrolling all windows -@cindex PC selection -@cindex Motif key bindings -@cindex Macintosh key bindings -@cindex WordStar - - GNU Emacs can be programmed to emulate (more or less) most other -editors. Standard facilities can emulate these: - -@table @asis -@item CRiSP/Brief (PC editor) -@findex crisp-mode -@vindex crisp-override-meta-x -@findex scroll-all-mode -@cindex CRiSP mode -@cindex Brief emulation -@cindex emulation of Brief -@cindex mode, CRiSP -You can turn on key bindings to emulate the CRiSP/Brief editor with -@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs -unless you set the variable @code{crisp-override-meta-x}. You can -also use the command @kbd{M-x scroll-all-mode} or set the variable -@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature -(scrolling all windows together). - -@item EDT (DEC VMS editor) -@findex edt-emulation-on -@findex edt-emulation-off -Turn on EDT emulation with the command @kbd{M-x edt-emulation-on}, -while @kbd{M-x edt-emulation-off} restores normal Emacs command -bindings. - -Most of the EDT emulation commands are keypad keys, and most standard -Emacs key bindings are still available. The EDT emulation rebindings -are done in the global keymap, so there is no problem switching -buffers or major modes while in EDT emulation. - -@item TPU (DEC VMS editor) -@findex tpu-edt-on -@cindex TPU -@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. - -@item vi (Berkeley editor) -@findex viper-mode -Viper is the newest emulator for vi. It implements several levels of -emulation; level 1 is closest to vi itself, while level 5 departs -somewhat from strict emulation to take advantage of the capabilities of -Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you -the rest of the way and ask for the emulation level. @inforef{Top, -Viper, viper}. - -@item vi (another emulator) -@findex vi-mode -@kbd{M-x vi-mode} enters a major mode that replaces the previously -established major mode. All of the vi commands that, in real vi, enter -``input'' mode are programmed instead to return to the previous major -mode. Thus, ordinary Emacs serves as vi's ``input'' mode. - -Because vi emulation works through major modes, it does not work -to switch buffers during emulation. Return to normal Emacs first. - -If you plan to use vi emulation much, you probably want to bind a key -to the @code{vi-mode} command. - -@item vi (alternate emulator) -@findex vip-mode -@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi -more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator -is changed from ordinary Emacs so you can use @key{ESC} to go back to -emulated vi command mode. To get from emulated vi command mode back to -ordinary Emacs, type @kbd{C-z}. - -This emulation does not work through major modes, and it is possible -to switch buffers in various ways within the emulator. It is not -so necessary to assign a key to the command @code{vip-mode} as -it is with @code{vi-mode} because terminating insert mode does -not use it. - -@inforef{Top, VIP, vip}, for full information. - -@item WordStar (old wordprocessor) -@findex wordstar-mode -@kbd{M-x wordstar-mode} provides a major mode with WordStar-like -key bindings. -@end table - -@node Hyperlinking, Dissociated Press, Emulation, Top -@section Hyperlinking and Navigation Features - -@cindex hyperlinking -@cindex navigation - Various modes documented elsewhere have hypertext features so that -you can follow links, usually by clicking @kbd{Mouse-2} on the link or -typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1} -quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer -if you want to set point instead.) - - Info mode, Help mode and the Dired-like modes are examples of modes -that have links in the buffer. The Tags facility links between uses -and definitions in source files, see @ref{Tags}. Imenu provides -navigation amongst items indexed in the current buffer, see -@ref{Imenu}. Info-lookup provides mode-specific lookup of definitions -in Info indexes, see @ref{Documentation}. Speedbar maintains a frame -in which links to files, and locations in files are displayed, see -@ref{Speedbar}. - - Other non-mode-specific facilities described in this section enable -following links from the current buffer in a context-sensitive -fashion. - -@menu -* Browse-URL:: Following URLs. -* Goto-address:: Activating URLs. -* FFAP:: Finding files etc. at point. -@end menu - -@node Browse-URL -@subsection Following URLs -@cindex World Wide Web -@cindex Web -@findex browse-url -@findex browse-url-at-point -@findex browse-url-at-mouse -@cindex Browse-URL -@cindex URLs - -@table @kbd -@item M-x browse-url @key{RET} @var{url} @key{RET} -Load a URL into a Web browser. -@end table - -The Browse-URL package provides facilities for following URLs specifying -links on the World Wide Web. Usually this works by invoking a web -browser, but you can, for instance, arrange to invoke @code{compose-mail} -from @samp{mailto:} URLs. - - The general way to use this feature is to type @kbd{M-x browse-url}, -which displays a specified URL. If point is located near a plausible -URL, that URL is used as the default. Other commands are available -which you might like to bind to keys, such as -@code{browse-url-at-point} and @code{browse-url-at-mouse}. - -@vindex browse-url-browser-function - You can customize Browse-URL's behavior via various options in the -@code{browse-url} Customize group, particularly -@code{browse-url-browser-function}. You can invoke actions dependent -on the type of URL by defining @code{browse-url-browser-function} as -an association list. The package's commentary available via @kbd{C-h -p} under the @samp{hypermedia} keyword provides more information. -Packages with facilities for following URLs should always go through -Browse-URL, so that the customization options for Browse-URL will -affect all browsing in Emacs. - -@node Goto-address -@subsection Activating URLs -@findex goto-address -@cindex Goto-address -@cindex URLs, activating - -@table @kbd -@item M-x goto-address -Activate URLs and e-mail addresses in the current buffer. -@end table - - You can make URLs in the current buffer active with @kbd{M-x -goto-address}. This finds all the URLs in the buffer, and establishes -bindings for @kbd{Mouse-2} and @kbd{C-c @key{RET}} on them. After -activation, if you click on a URL with @kbd{Mouse-2}, or move to a URL -and type @kbd{C-c @key{RET}}, that will display the web page that the URL -specifies. For a @samp{mailto} URL, it sends mail instead, using your -selected mail-composition method (@pxref{Mail Methods}). - - It can be useful to add @code{goto-address} to mode hooks and the -hooks used to display an incoming message. -@code{rmail-show-message-hook} is the appropriate hook for Rmail, and -@code{mh-show-mode-hook} for MH-E. This is not needed for Gnus, -which has a similar feature of its own. - - -@node FFAP -@subsection Finding Files and URLs at Point -@findex find-file-at-point -@findex ffap -@findex dired-at-point -@findex ffap-next -@findex ffap-menu -@cindex finding file at point - - FFAP mode replaces certain key bindings for finding files, including -@kbd{C-x C-f}, with commands that provide more sensitive defaults. -These commands behave like the ordinary ones when given a prefix -argument. Otherwise, they get the default file name or URL from the -text around point. If what is found in the buffer has the form of a -URL rather than a file name, the commands use @code{browse-url} to -view it. - - This feature is useful for following references in mail or news -buffers, @file{README} files, @file{MANIFEST} files, and so on. The -@samp{ffap} package's commentary available via @kbd{C-h p} under the -@samp{files} keyword and the @code{ffap} Custom group provide details. - -@cindex FFAP minor mode -@findex ffap-mode - You can turn on FFAP minor mode by calling @code{ffap-bindings} to -make the following key bindings and to install hooks for using -@code{ffap} in Rmail, Gnus and VM article buffers. - -@table @kbd -@item C-x C-f @var{filename} @key{RET} -@kindex C-x C-f @r{(FFAP)} -Find @var{filename}, guessing a default from text around point -(@code{find-file-at-point}). -@item C-x C-r -@kindex C-x C-r @r{(FFAP)} -@code{ffap-read-only}, analogous to @code{find-file-read-only}. -@item C-x C-v -@kindex C-x C-v @r{(FFAP)} -@code{ffap-alternate-file}, analogous to @code{find-alternate-file}. -@item C-x d @var{directory} @key{RET} -@kindex C-x d @r{(FFAP)} -Start Dired on @var{directory}, defaulting to the directory name at -point (@code{dired-at-point}). -@item C-x C-d -@code{ffap-list-directory}, analogous to @code{list-directory}. -@item C-x 4 f -@kindex C-x 4 f @r{(FFAP)} -@code{ffap-other-window}, analogous to @code{find-file-other-window}. -@item C-x 4 r -@code{ffap-read-only-other-window}, analogous to -@code{find-file-read-only-other-window}. -@item C-x 4 d -@code{ffap-dired-other-window}, analogous to @code{dired-other-window}. -@item C-x 5 f -@kindex C-x 5 f @r{(FFAP)} -@code{ffap-other-frame}, analogous to @code{find-file-other-frame}. -@item C-x 5 r -@code{ffap-read-only-other-frame}, analogous to -@code{find-file-read-only-other-frame}. -@item C-x 5 d -@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. -@item M-x ffap-next -Search buffer for next file name or URL, then find that file or URL. -@item S-Mouse-3 -@kindex S-Mouse-3 @r{(FFAP)} -@code{ffap-at-mouse} finds the file guessed from text around the position -of a mouse click. -@item C-S-Mouse-3 -@kindex C-S-Mouse-3 @r{(FFAP)} -Display a menu of files and URLs mentioned in current buffer, then -find the one you select (@code{ffap-menu}). -@end table - -@node Dissociated Press, Amusements, Hyperlinking, Top -@section Dissociated Press - -@findex dissociated-press - @kbd{M-x dissociated-press} is a command for scrambling a file of text -either word by word or character by character. Starting from a buffer of -straight English, it produces extremely amusing output. The input comes -from the current Emacs buffer. Dissociated Press writes its output in a -buffer named @samp{*Dissociation*}, and redisplays that buffer after every -couple of lines (approximately) so you can read the output as it comes out. - - Dissociated Press asks every so often whether to continue generating -output. Answer @kbd{n} to stop it. You can also stop at any time by -typing @kbd{C-g}. The dissociation output remains in the -@samp{*Dissociation*} buffer for you to copy elsewhere if you wish. - -@cindex presidentagon - Dissociated Press operates by jumping at random from one point in the -buffer to another. In order to produce plausible output rather than -gibberish, it insists on a certain amount of overlap between the end of -one run of consecutive words or characters and the start of the next. -That is, if it has just output `president' and then decides to jump -to a different point in the file, it might spot the `ent' in `pentagon' -and continue from there, producing `presidentagon'.@footnote{This -dissociword actually appeared during the Vietnam War, when it was very -appropriate. Bush has made it appropriate again.} Long sample texts -produce the best results. - -@cindex againformation - A positive argument to @kbd{M-x dissociated-press} tells it to operate -character by character, and specifies the number of overlap characters. A -negative argument tells it to operate word by word, and specifies the number -of overlap words. In this mode, whole words are treated as the elements to -be permuted, rather than characters. No argument is equivalent to an -argument of two. For your againformation, the output goes only into the -buffer @samp{*Dissociation*}. The buffer you start with is not changed. - -@cindex Markov chain -@cindex ignoriginal -@cindex techniquitous - Dissociated Press produces results fairly like those of a Markov -chain based on a frequency table constructed from the sample text. It -is, however, an independent, ignoriginal invention. Dissociated Press -techniquitously copies several consecutive characters from the sample -between random choices, whereas a Markov chain would choose randomly -for each word or character. This makes for more plausible sounding -results, and runs faster. - -@cindex outragedy -@cindex buggestion -@cindex properbose -@cindex mustatement -@cindex developediment -@cindex userenced - It is a mustatement that too much use of Dissociated Press can be a -developediment to your real work, sometimes to the point of outragedy. -And keep dissociwords out of your documentation, if you want it to be well -userenced and properbose. Have fun. Your buggestions are welcome. - -@node Amusements, Customization, Dissociated Press, Top -@section Other Amusements -@cindex boredom -@findex hanoi -@findex yow -@findex gomoku -@cindex tower of Hanoi - - If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are -considerably bored, give it a numeric argument. If you are very, very -bored, try an argument of 9. Sit back and watch. - -@cindex Go Moku - If you want a little more personal involvement, try @kbd{M-x gomoku}, -which plays the game Go Moku with you. - -@findex blackbox -@findex mpuz -@findex 5x5 -@cindex puzzles - @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles. -@code{blackbox} challenges you to determine the location of objects -inside a box by tomography. @code{mpuz} displays a multiplication -puzzle with letters standing for digits in a code that you must -guess---to guess a value, type a letter and then the digit you think it -stands for. The aim of @code{5x5} is to fill in all the squares. - -@findex decipher -@cindex ciphers -@cindex cryptanalysis -@kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted -in a simple monoalphabetic substitution cipher. - -@findex dunnet - @kbd{M-x dunnet} runs an adventure-style exploration game, which is -a bigger sort of puzzle. - -@findex lm -@cindex landmark game -@kbd{M-x lm} runs a relatively non-participatory game in which a robot -attempts to maneuver towards a tree at the center of the window based on -unique olfactory cues from each of the four directions. - -@findex life -@cindex Life -@kbd{M-x life} runs Conway's ``Life'' cellular automaton. - -@findex morse-region -@findex unmorse-region -@cindex Morse code -@cindex --/---/.-./.../. -@kbd{M-x morse-region} converts text in a region to Morse code and -@kbd{M-x unmorse-region} converts it back. No cause for remorse. - -@findex pong -@cindex Pong game -@kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing -bats. - -@findex solitaire -@cindex solitaire -@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs -across other pegs. - -@findex studlify-region -@cindex StudlyCaps -@kbd{M-x studlify-region} studlify-cases the region, producing -text like this: - -@example -M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region. -@end example - -@findex tetris -@cindex Tetris -@findex snake -@cindex Snake -@kbd{M-x tetris} runs an implementation of the well-known Tetris game. -Likewise, @kbd{M-x snake} provides an implementation of Snake. - - When you are frustrated, try the famous Eliza program. Just do -@kbd{M-x doctor}. End each input by typing @key{RET} twice. - -@cindex Zippy - When you are feeling strange, type @kbd{M-x yow}. - -@findex zone -The command @kbd{M-x zone} plays games with the display when Emacs is -idle. - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474 -@end ignore diff --git a/man/msdog-xtra.texi b/man/msdog-xtra.texi deleted file mode 100644 index 432f28888f6..00000000000 --- a/man/msdog-xtra.texi +++ /dev/null @@ -1,687 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node MS-DOS -@section Emacs and MS-DOS -@cindex MS-DOG -@cindex MS-DOS peculiarities - - This section briefly describes the peculiarities of using Emacs on -the MS-DOS ``operating system'' (also known as ``MS-DOG''). -@iftex -Information about Emacs and Microsoft's current operating system -Windows (also known as ``Losedows) is in the main Emacs manual -(@pxref{Microsoft Systems,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -Information about peculiarities common to MS-DOS and Microsoft's -current operating systems Windows (also known as ``Losedows) is in -@ref{Microsoft Windows}. -@end ifnottex - - If you build Emacs for MS-DOS, the binary will also run on Windows -3.X, Windows NT, Windows 9X/ME, Windows 2000/XP, or OS/2 as a DOS -application; all of this chapter applies for all of those systems, if -you use an Emacs that was built for MS-DOS. - -@iftex - @xref{Text and Binary,,,emacs, the Emacs Manual}, for information -@end iftex -@ifnottex - @xref{Text and Binary}, for information -@end ifnottex -about Emacs' special handling of text files under MS-DOS (and Windows). - -@menu -* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. -* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. -* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. -* Files: MS-DOS File Names. File name conventions on MS-DOS. -* Printing: MS-DOS Printing. Printing specifics on MS-DOS. -* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. -* Processes: MS-DOS Processes. Running subprocesses on MS-DOS. -@end menu - -@node MS-DOS Keyboard -@subsection Keyboard Usage on MS-DOS - -@kindex DEL @r{(MS-DOS)} -@kindex BS @r{(MS-DOS)} - The key that is called @key{DEL} in Emacs (because that's how it is -designated on most workstations) is known as @key{BS} (backspace) on a -PC. That is why the PC-specific terminal initialization remaps the -@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act -as @kbd{C-d} for the same reasons. - -@kindex C-g @r{(MS-DOS)} -@kindex C-BREAK @r{(MS-DOS)} -@cindex quitting on MS-DOS - Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit -character, just like @kbd{C-g}. This is because Emacs cannot detect -that you have typed @kbd{C-g} until it is ready for more input. As a -consequence, you cannot use @kbd{C-g} to stop a running command -@iftex -(@pxref{Quitting,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Quitting}). -@end ifnottex -By contrast, @kbd{C-@key{BREAK}} @emph{is} detected as soon as you -type it (as @kbd{C-g} is on other systems), so it can be used to stop -a running command and for emergency escape -@iftex -(@pxref{Emergency Escape,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Emergency Escape}). -@end ifnottex - -@cindex Meta (under MS-DOS) -@cindex Hyper (under MS-DOS) -@cindex Super (under MS-DOS) -@vindex dos-super-key -@vindex dos-hyper-key - The PC keyboard maps use the left @key{ALT} key as the @key{META} key. -You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: -choose either the right @key{CTRL} key or the right @key{ALT} key by -setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 -or 2 respectively. If neither @code{dos-super-key} nor -@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is -also mapped to the @key{META} key. However, if the MS-DOS international -keyboard support program @file{KEYB.COM} is installed, Emacs will -@emph{not} map the right @key{ALT} to @key{META}, since it is used for -accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard -layouts; in this case, you may only use the left @key{ALT} as @key{META} -key. - -@kindex C-j @r{(MS-DOS)} -@vindex dos-keypad-mode - The variable @code{dos-keypad-mode} is a flag variable that controls -what key codes are returned by keys in the numeric keypad. You can also -define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the -following line into your @file{_emacs} file: - -@smallexample -;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} -(define-key function-key-map [kp-enter] [?\C-j]) -@end smallexample - -@node MS-DOS Mouse -@subsection Mouse Usage on MS-DOS - -@cindex mouse support under MS-DOS - Emacs on MS-DOS supports a mouse (on the default terminal only). -The mouse commands work as documented, including those that use menus -and the menu bar -@iftex -(@pxref{Menu Bar,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Menu Bar}). -@end ifnottex - Scroll bars don't work in MS-DOS Emacs. PC mice usually have only -two buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you -press both of them together, that has the effect of @kbd{Mouse-3}. If -the mouse does have 3 buttons, Emacs detects that at startup, and all -the 3 buttons function normally, as on X. - - Help strings for menu-bar and pop-up menus are displayed in the echo -area when the mouse pointer moves across the menu items. Highlighting -of mouse-sensitive text -@iftex -(@pxref{Mouse References,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Mouse References}) -@end ifnottex -is also supported. - -@cindex mouse, set number of buttons -@findex msdos-set-mouse-buttons - Some versions of mouse drivers don't report the number of mouse -buttons correctly. For example, mice with a wheel report that they -have 3 buttons, but only 2 of them are passed to Emacs; the clicks on -the wheel, which serves as the middle button, are not passed. In -these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command -to tell Emacs how many mouse buttons to expect. You could make such a -setting permanent by adding this fragment to your @file{_emacs} init -file: - -@example -;; @r{Treat the mouse like a 2-button mouse.} -(msdos-set-mouse-buttons 2) -@end example - -@cindex Windows clipboard support - Emacs built for MS-DOS supports clipboard operations when it runs on -Windows. Commands that put text on the kill ring, or yank text from -the ring, check the Windows clipboard first, just as Emacs does on the -X Window System -@iftex -(@pxref{Mouse Commands,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Mouse Commands}). -@end ifnottex -Only the primary selection and the cut buffer are supported by MS-DOS -Emacs on Windows; the secondary selection always appears as empty. - - Due to the way clipboard access is implemented by Windows, the -length of text you can put into the clipboard is limited by the amount -of free DOS memory that is available to Emacs. Usually, up to 620KB of -text can be put into the clipboard, but this limit depends on the system -configuration and is lower if you run Emacs as a subprocess of -another program. If the killed text does not fit, Emacs outputs a -message saying so, and does not put the text into the clipboard. - - Null characters also cannot be put into the Windows clipboard. If the -killed text includes null characters, Emacs does not put such text into -the clipboard, and displays in the echo area a message to that effect. - -@vindex dos-display-scancodes - The variable @code{dos-display-scancodes}, when non-@code{nil}, -directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of -each keystroke; this feature serves as a complement to the -@code{view-lossage} command, for debugging. - -@node MS-DOS Display -@subsection Display on MS-DOS -@cindex faces under MS-DOS -@cindex fonts, emulating under MS-DOS - - Display on MS-DOS cannot use font variants, like bold or italic, but -it does support multiple faces, each of which can specify a foreground -and a background color. Therefore, you can get the full functionality -of Emacs packages that use fonts (such as @code{font-lock}, Enriched -Text mode, and others) by defining the relevant faces to use different -colors. Use the @code{list-colors-display} command -@iftex -(@pxref{Frame Parameters,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Frame Parameters}) -@end ifnottex -and the @code{list-faces-display} command -@iftex -(@pxref{Faces,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Faces}) -@end ifnottex -to see what colors and faces are available and what they look like. - - @xref{MS-DOS and MULE}, later in this chapter, for information on -how Emacs displays glyphs and characters that aren't supported by the -native font built into the DOS display. - -@cindex cursor shape on MS-DOS - When Emacs starts, it changes the cursor shape to a solid box. This -is for compatibility with other systems, where the box cursor is the -default in Emacs. This default shape can be changed to a bar by -specifying the @code{cursor-type} parameter in the variable -@code{default-frame-alist} -@iftex -(@pxref{Creating Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Creating Frames}). -@end ifnottex -The MS-DOS terminal doesn't support a vertical-bar cursor, -so the bar cursor is horizontal, and the @code{@var{width}} parameter, -if specified by the frame parameters, actually determines its height. -For this reason, the @code{bar} and @code{hbar} cursor types produce -the same effect on MS-DOS. As an extension, the bar cursor -specification can include the starting scan line of the cursor as well -as its width, like this: - -@example - '(cursor-type bar @var{width} . @var{start}) -@end example - -@noindent -In addition, if the @var{width} parameter is negative, the cursor bar -begins at the top of the character cell. - -@cindex frames on MS-DOS - The MS-DOS terminal can only display a single frame at a time. The -Emacs frame facilities work on MS-DOS much as they do on text-only -terminals -@iftex -(@pxref{Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Frames}). -@end ifnottex -When you run Emacs from a DOS window on MS-Windows, you can make the -visible frame smaller than the full screen, but Emacs still cannot -display more than a single frame at a time. - -@cindex frame size under MS-DOS -@findex mode4350 -@findex mode25 - The @code{mode4350} command switches the display to 43 or 50 -lines, depending on your hardware; the @code{mode25} command switches -to the default 80x25 screen size. - - By default, Emacs only knows how to set screen sizes of 80 columns by -25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has -special video modes that will switch the display to other sizes, you can -have Emacs support those too. When you ask Emacs to switch the frame to -@var{n} rows by @var{m} columns dimensions, it checks if there is a -variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, -uses its value (which must be an integer) as the video mode to switch -to. (Emacs switches to that video mode by calling the BIOS @code{Set -Video Mode} function with the value of -@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) -For example, suppose your adapter will switch to 66x80 dimensions when -put into video mode 85. Then you can make Emacs support this screen -size by putting the following into your @file{_emacs} file: - -@example -(setq screen-dimensions-66x80 85) -@end example - - Since Emacs on MS-DOS can only set the frame size to specific -supported dimensions, it cannot honor every possible frame resizing -request. When an unsupported size is requested, Emacs chooses the next -larger supported size beyond the specified size. For example, if you -ask for 36x80 frame, you will get 40x80 instead. - - The variables @code{screen-dimensions-@var{n}x@var{m}} are used only -when they exactly match the specified size; the search for the next -larger supported size ignores them. In the above example, even if your -VGA supports 38x80 dimensions and you define a variable -@code{screen-dimensions-38x80} with a suitable value, you will still get -40x80 screen when you ask for a 36x80 frame. If you want to get the -38x80 size in this case, you can do it by setting the variable named -@code{screen-dimensions-36x80} with the same video mode value as -@code{screen-dimensions-38x80}. - - Changing frame dimensions on MS-DOS has the effect of changing all the -other frames to the new dimensions. - -@node MS-DOS File Names -@subsection File Names on MS-DOS -@cindex file names under MS-DOS -@cindex init file, default name under MS-DOS - - On MS-DOS, file names are case-insensitive and limited to eight -characters, plus optionally a period and three more characters. Emacs -knows enough about these limitations to handle file names that were -meant for other operating systems. For instance, leading dots -@samp{.} in file names are invalid in MS-DOS, so Emacs transparently -converts them to underscores @samp{_}; thus your default init file -@iftex -(@pxref{Init File,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Init File}) -@end ifnottex -is called @file{_emacs} on MS-DOS. Excess characters before or after -the period are generally ignored by MS-DOS itself; thus, if you visit -the file @file{LongFileName.EvenLongerExtension}, you will silently -get @file{longfile.eve}, but Emacs will still display the long file -name on the mode line. Other than that, it's up to you to specify -file names which are valid under MS-DOS; the transparent conversion as -described above only works on file names built into Emacs. - -@cindex backup file names on MS-DOS - The above restrictions on the file names on MS-DOS make it almost -impossible to construct the name of a backup file -@iftex -(@pxref{Backup Names,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Backup Names}) -@end ifnottex -without losing some of the original file name characters. For -example, the name of a backup file for @file{docs.txt} is -@file{docs.tx~} even if single backup is used. - -@cindex file names under Windows 95/NT -@cindex long file names in DOS box under Windows 95/NT - If you run Emacs as a DOS application under Windows 9X, Windows ME, or -Windows 2000/XP, you can turn on support for long file names. If you do -that, Emacs doesn't truncate file names or convert them to lower case; -instead, it uses the file names that you specify, verbatim. To enable -long file name support, set the environment variable @env{LFN} to -@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow -DOS programs to access long file names, so Emacs built for MS-DOS will -only see their short 8+3 aliases. - -@cindex @env{HOME} directory under MS-DOS - MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends -that the directory where it is installed is the value of the @env{HOME} -environment variable. That is, if your Emacs binary, -@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then -Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In -particular, that is where Emacs looks for the init file @file{_emacs}. -With this in mind, you can use @samp{~} in file names as an alias for -the home directory, as you would on GNU or Unix. You can also set -@env{HOME} variable in the environment before starting Emacs; its -value will then override the above default behavior. - - Emacs on MS-DOS handles the directory name @file{/dev} specially, -because of a feature in the emulator libraries of DJGPP that pretends -I/O devices have names in that directory. We recommend that you avoid -using an actual directory named @file{/dev} on any disk. - -@node MS-DOS Printing -@subsection Printing and MS-DOS - - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and @code{ps-print-buffer} -(@pxref{PostScript,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}) -@end ifnottex -can work on MS-DOS by sending the output to one of the printer ports, -if a Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS. - -@iftex -@xref{Windows Printing,,,emacs, the Emacs Manual}, -@end iftex -@ifnottex -@xref{Windows Printing}, -@end ifnottex -for details about setting up printing to a networked printer. - - Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even -though they are connected to a Windows machine which uses a different -encoding for the same locale. For example, in the Latin-1 locale, DOS -uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and -MULE}. When you print to such printers from Windows, you can use the -@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before -@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS -codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET -M-x lpr-region RET} will print the region while converting it to the -codepage 850 encoding. You may need to create the @code{cp@var{nnn}} -coding system with @kbd{M-x codepage-setup}. - -@vindex dos-printer -@vindex dos-ps-printer - For backwards compatibility, the value of @code{dos-printer} -(@code{dos-ps-printer}), if it has a value, overrides the value of -@code{printer-name} (@code{ps-printer-name}), on MS-DOS. - - -@node MS-DOS and MULE -@subsection International Support on MS-DOS -@cindex international support @r{(MS-DOS)} - - Emacs on MS-DOS supports the same international character sets as it -does on GNU, Unix and other platforms -@iftex -(@pxref{International,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{International}), -@end ifnottex -including coding systems for converting between the different -character sets. However, due to incompatibilities between -MS-DOS/MS-Windows and other systems, there are several DOS-specific -aspects of this support that you should be aware of. This section -describes these aspects. - - The description below is largely specific to the MS-DOS port of -Emacs, especially where it talks about practical implications for -Emacs users. For other operating systems, see the @file{code-pages.el} -package, which implements support for MS-DOS- and MS-Windows-specific -encodings for all platforms other than MS-DOS. - -@table @kbd -@item M-x dos-codepage-setup -Set up Emacs display and coding systems as appropriate for the current -DOS codepage. - -@item M-x codepage-setup -Create a coding system for a certain DOS codepage. -@end table - -@cindex codepage, MS-DOS -@cindex DOS codepages - MS-DOS is designed to support one character set of 256 characters at -any given time, but gives you a variety of character sets to choose -from. The alternative character sets are known as @dfn{DOS codepages}. -Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 -characters (codes 128 through 255) vary from one codepage to another. -Each DOS codepage is identified by a 3-digit number, such as 850, 862, -etc. - - In contrast to X, which lets you use several fonts at the same time, -MS-DOS normally doesn't allow use of several codepages in a single -session. MS-DOS was designed to load a single codepage at system -startup, and require you to reboot in order to change -it@footnote{Normally, one particular codepage is burnt into the -display memory, while other codepages can be installed by modifying -system configuration files, such as @file{CONFIG.SYS}, and rebooting. -While there is third-party software that allows changing the codepage -without rebooting, we describe here how a stock MS-DOS system -behaves.}. Much the same limitation applies when you run DOS -executables on other systems such as MS-Windows. - -@cindex unibyte operation @r{(MS-DOS)} - If you invoke Emacs on MS-DOS with the @samp{--unibyte} option -@iftex -(@pxref{Initial Options,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Initial Options}), -@end ifnottex -Emacs does not perform any conversion of non-@acronym{ASCII} -characters. Instead, it reads and writes any non-@acronym{ASCII} -characters verbatim, and sends their 8-bit codes to the display -verbatim. Thus, unibyte Emacs on MS-DOS supports the current -codepage, whatever it may be, but cannot even represent any other -characters. - -@vindex dos-codepage - For multibyte operation on MS-DOS, Emacs needs to know which -characters the chosen DOS codepage can display. So it queries the -system shortly after startup to get the chosen codepage number, and -stores the number in the variable @code{dos-codepage}. Some systems -return the default value 437 for the current codepage, even though the -actual codepage is different. (This typically happens when you use the -codepage built into the display hardware.) You can specify a different -codepage for Emacs to use by setting the variable @code{dos-codepage} in -your init file. - -@cindex language environment, automatic selection on @r{MS-DOS} - Multibyte Emacs supports only certain DOS codepages: those which can -display Far-Eastern scripts, like the Japanese codepage 932, and those -that encode a single ISO 8859 character set. - - The Far-Eastern codepages can directly display one of the MULE -character sets for these countries, so Emacs simply sets up to use the -appropriate terminal coding system that is supported by the codepage. -The special features described in the rest of this section mostly -pertain to codepages that encode ISO 8859 character sets. - - For the codepages which correspond to one of the ISO character sets, -Emacs knows the character set name based on the codepage number. Emacs -automatically creates a coding system to support reading and writing -files that use the current codepage, and uses this coding system by -default. The name of this coding system is @code{cp@var{nnn}}, where -@var{nnn} is the codepage number.@footnote{The standard Emacs coding -systems for ISO 8859 are not quite right for the purpose, because -typically the DOS codepage does not match the standard ISO character -codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has -code 231 in the standard Latin-1 character set, but the corresponding -DOS codepage 850 uses code 135 for this glyph.} - -@cindex mode line @r{(MS-DOS)} - All the @code{cp@var{nnn}} coding systems use the letter @samp{D} -(for ``DOS'') as their mode-line mnemonic. Since both the terminal -coding system and the default coding system for file I/O are set to -the proper @code{cp@var{nnn}} coding system at startup, it is normal -for the mode line on MS-DOS to begin with @samp{-DD\-}. -@iftex -@xref{Mode Line,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Mode Line}. -@end ifnottex -Far-Eastern DOS terminals do not use the @code{cp@var{nnn}} coding -systems, and thus their initial mode line looks like the Emacs -default. - - Since the codepage number also indicates which script you are using, -Emacs automatically runs @code{set-language-environment} to select the -language environment for that script -@iftex -(@pxref{Language Environments,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Language Environments}). -@end ifnottex - - If a buffer contains a character belonging to some other ISO 8859 -character set, not the one that the chosen DOS codepage supports, Emacs -displays it using a sequence of @acronym{ASCII} characters. For example, if the -current codepage doesn't have a glyph for the letter @samp{@`o} (small -@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where -the braces serve as a visual indication that this is a single character. -(This may look awkward for some non-Latin characters, such as those from -Greek or Hebrew alphabets, but it is still readable by a person who -knows the language.) Even though the character may occupy several -columns on the screen, it is really still just a single character, and -all Emacs commands treat it as one. - -@cindex IBM graphics characters (MS-DOS) -@cindex box-drawing characters (MS-DOS) -@cindex line-drawing characters (MS-DOS) - Not all characters in DOS codepages correspond to ISO 8859 -characters---some are used for other purposes, such as box-drawing -characters and other graphics. Emacs maps these characters to two -special character sets called @code{eight-bit-control} and -@code{eight-bit-graphic}, and displays them as their IBM glyphs. -However, you should be aware that other systems might display these -characters differently, so you should avoid them in text that might be -copied to a different operating system, or even to another DOS machine -that uses a different codepage. - -@vindex dos-unsupported-character-glyph - Emacs supports many other characters sets aside from ISO 8859, but it -cannot display them on MS-DOS. So if one of these multibyte characters -appears in a buffer, Emacs on MS-DOS displays them as specified by the -@code{dos-unsupported-character-glyph} variable; by default, this glyph -is an empty triangle. Use the @kbd{C-u C-x =} command to display the -actual code and character set of such characters. -@iftex -@xref{Position Info,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Position Info}. -@end ifnottex - -@findex codepage-setup - By default, Emacs defines a coding system to support the current -codepage. To define a coding system for some other codepage (e.g., to -visit a file written on a DOS machine in another country), use the -@kbd{M-x codepage-setup} command. It prompts for the 3-digit code of -the codepage, with completion, then creates the coding system for the -specified codepage. You can then use the new coding system to read and -write files, but you must specify it explicitly for the file command -when you want to use it -@iftex -(@pxref{Text Coding,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Text Coding}). -@end ifnottex - - These coding systems are also useful for visiting a file encoded using -a DOS codepage, using Emacs running on some other operating system. - -@cindex MS-Windows codepages - MS-Windows provides its own codepages, which are different from the -DOS codepages for the same locale. For example, DOS codepage 850 -supports the same character set as Windows codepage 1252; DOS codepage -855 supports the same character set as Windows codepage 1251, etc. -The MS-Windows version of Emacs uses the current codepage for display -when invoked with the @samp{-nw} option. Support for codepages in the -Windows port of Emacs is part of the @file{code-pages.el} package. - -@node MS-DOS Processes -@subsection Subprocesses on MS-DOS - -@cindex compilation under MS-DOS -@cindex inferior processes under MS-DOS -@findex compile @r{(MS-DOS)} -@findex grep @r{(MS-DOS)} - Because MS-DOS is a single-process ``operating system,'' -asynchronous subprocesses are not available. In particular, Shell -mode and its variants do not work. Most Emacs features that use -asynchronous subprocesses also don't work on MS-DOS, including -Shell mode and GUD. When in doubt, try and see; commands that -don't work output an error message saying that asynchronous processes -aren't supported. - - Compilation under Emacs with @kbd{M-x compile}, searching files with -@kbd{M-x grep} and displaying differences between files with @kbd{M-x -diff} do work, by running the inferior processes synchronously. This -means you cannot do any more editing until the inferior process -finishes. - - Spell checking also works, by means of special support for synchronous -invocation of the @code{ispell} program. This is slower than the -asynchronous invocation on other platforms - - Instead of the Shell mode, which doesn't work on MS-DOS, you can use -the @kbd{M-x eshell} command. This invokes the Eshell package that -implements a Posix-like shell entirely in Emacs Lisp. - - By contrast, Emacs compiled as a native Windows application -@strong{does} support asynchronous subprocesses. -@iftex -@xref{Windows Processes,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Windows Processes}. -@end ifnottex - -@cindex printing under MS-DOS - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and -@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing}. -@end ifnottex - - When you run a subprocess synchronously on MS-DOS, make sure the -program terminates and does not try to read keyboard input. If the -program does not terminate on its own, you will be unable to terminate -it, because MS-DOS provides no general way to terminate a process. -Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these -cases. - - Accessing files on other machines is not supported on MS-DOS. Other -network-oriented commands such as sending mail, Web browsing, remote -login, etc., don't work either, unless network access is built into -MS-DOS with some network redirector. - -@cindex directory listing on MS-DOS -@vindex dired-listing-switches @r{(MS-DOS)} - Dired on MS-DOS uses the @code{ls-lisp} package where other -platforms use the system @code{ls} command. Therefore, Dired on -MS-DOS supports only some of the possible options you can mention in -the @code{dired-listing-switches} variable. The options that work are -@samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S}, -@samp{-s}, @samp{-t}, and @samp{-u}. - -@ignore - arch-tag: 868d50ff-07f8-4a13-a807-dab6f1cdb431 -@end ignore diff --git a/man/msdog.texi b/man/msdog.texi deleted file mode 100644 index 0ed15229b7c..00000000000 --- a/man/msdog.texi +++ /dev/null @@ -1,766 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Microsoft Windows, Manifesto, Mac OS, Top -@appendix Emacs and Microsoft Windows/MS-DOS -@cindex Microsoft Windows -@cindex MS-Windows, Emacs peculiarities - - This section describes peculiarities of using Emacs on Microsoft -Windows. Some of these peculiarities are also relevant to Microsoft's -older MS-DOS ``operating system'' (also known as ``MS-DOG''). -However, Emacs features that are relevant @emph{only} to MS-DOS are -described in a separate -@iftex -manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -section (@pxref{MS-DOS}). -@end ifnottex - - - The behavior of Emacs on MS-Windows is reasonably similar to what is -documented in the rest of the manual, including support for long file -names, multiple frames, scroll bars, mouse menus, and subprocesses. -However, a few special considerations apply, and they are described -here. - -@menu -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs}. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -@ifnottex -* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). -@end ifnottex -@end menu - -@node Text and Binary -@section Text Files and Binary Files -@cindex text and binary files on MS-DOS/MS-Windows - - GNU Emacs uses newline characters to separate text lines. This is the -convention used on GNU, Unix, and other Posix-compliant systems. - -@cindex end-of-line conversion on MS-DOS/MS-Windows - By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed, -a two-character sequence, to separate text lines. (Linefeed is the same -character as newline.) Therefore, convenient editing of typical files -with Emacs requires conversion of these end-of-line (EOL) sequences. -And that is what Emacs normally does: it converts carriage-return -linefeed into newline when reading files, and converts newline into -carriage-return linefeed when writing files. The same mechanism that -handles conversion of international character codes does this conversion -also (@pxref{Coding Systems}). - -@cindex cursor location, on MS-DOS -@cindex point location, on MS-DOS - One consequence of this special format-conversion of most files is -that character positions as reported by Emacs (@pxref{Position Info}) do -not agree with the file size information known to the operating system. - - In addition, if Emacs recognizes from a file's contents that it uses -newline rather than carriage-return linefeed as its line separator, it -does not perform EOL conversion when reading or writing that file. -Thus, you can read and edit files from GNU and Unix systems on MS-DOS -with no special effort, and they will retain their Unix-style -end-of-line convention after you edit them. - - The mode line indicates whether end-of-line translation was used for -the current buffer. If MS-DOS end-of-line translation is in use for the -buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after -the coding system mnemonic near the beginning of the mode line -(@pxref{Mode Line}). If no EOL translation was performed, the string -@samp{(Unix)} is displayed instead of the backslash, to alert you that the -file's EOL format is not the usual carriage-return linefeed. - -@cindex DOS-to-Unix conversion of files - To visit a file and specify whether it uses DOS-style or Unix-style -end-of-line, specify a coding system (@pxref{Text Coding}). For -example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt} -visits the file @file{foobar.txt} without converting the EOLs; if some -line ends with a carriage-return linefeed pair, Emacs will display -@samp{^M} at the end of that line. Similarly, you can direct Emacs to -save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f} -command. For example, to save a buffer with Unix EOL format, type -@kbd{C-x @key{RET} f unix @key{RET} C-x C-s}. If you visit a file -with DOS EOL conversion, then save it with Unix EOL format, that -effectively converts the file to Unix EOL style, like @code{dos2unix}. - -@cindex untranslated file system -@findex add-untranslated-filesystem - When you use NFS, Samba, or some other similar method to access file -systems that reside on computers using GNU or Unix systems, Emacs -should not perform end-of-line translation on any files in these file -systems---not even when you create a new file. To request this, -designate these file systems as @dfn{untranslated} file systems by -calling the function @code{add-untranslated-filesystem}. It takes one -argument: the file system name, including a drive letter and -optionally a directory. For example, - -@example -(add-untranslated-filesystem "Z:") -@end example - -@noindent -designates drive Z as an untranslated file system, and - -@example -(add-untranslated-filesystem "Z:\\foo") -@end example - -@noindent -designates directory @file{\foo} on drive Z as an untranslated file -system. - - Most often you would use @code{add-untranslated-filesystem} in your -@file{.emacs} file, or in @file{site-start.el} so that all the users at -your site get the benefit of it. - -@findex remove-untranslated-filesystem - To countermand the effect of @code{add-untranslated-filesystem}, use -the function @code{remove-untranslated-filesystem}. This function takes -one argument, which should be a string just like the one that was used -previously with @code{add-untranslated-filesystem}. - - Designating a file system as untranslated does not affect character -set conversion, only end-of-line conversion. Essentially, it directs -Emacs to create new files with the Unix-style convention of using -newline at the end of a line. @xref{Coding Systems}. - -@vindex file-name-buffer-file-type-alist -@cindex binary files, on MS-DOS/MS-Windows - Some kinds of files should not be converted at all, because their -contents are not really text. Therefore, Emacs on MS-Windows distinguishes -certain files as @dfn{binary files}. (This distinction is not part of -MS-Windows; it is made by Emacs only.) Binary files include executable -programs, compressed archives, etc. Emacs uses the file name to decide -whether to treat a file as binary: the variable -@code{file-name-buffer-file-type-alist} defines the file-name patterns -that indicate binary files. If a file name matches one of the patterns -for binary files (those whose associations are of the type -@code{(@var{pattern} . t)}, Emacs reads and writes that file using the -@code{no-conversion} coding system (@pxref{Coding Systems}) which turns -off @emph{all} coding-system conversions, not only the EOL conversion. -@code{file-name-buffer-file-type-alist} also includes file-name patterns -for files which are known to be Windows-style text files with -carriage-return linefeed EOL format, such as @file{CONFIG.SYS}; Emacs -always writes those files with Windows-style EOLs. - - If a file which belongs to an untranslated file system matches one of -the file-name patterns in @code{file-name-buffer-file-type-alist}, the -EOL conversion is determined by @code{file-name-buffer-file-type-alist}. - -@node Windows Files -@section File Names on MS-Windows -@cindex file names on MS-Windows - - MS-Windows and MS-DOS normally use a backslash, @samp{\}, to -separate name units within a file name, instead of the slash used on -other systems. Emacs on MS-DOS/MS-Windows permits use of either slash or -backslash, and also knows about drive letters in file names. - -@cindex file-name completion, on MS-Windows - On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by -default ignores letter-case in file names during completion. - -@vindex w32-get-true-file-attributes - If the variable @code{w32-get-true-file-attributes} is -non-@code{nil} (the default), Emacs tries to determine the accurate -link counts for files. This option is only useful on NTFS volumes, -and it considerably slows down Dired and other features, so use it -only on fast machines. - -@node ls in Lisp -@section Emulation of @code{ls} on MS-Windows -@cindex Dired, and MS-Windows/MS-DOS -@cindex @code{ls} emulation - - Dired normally uses the external program @code{ls} (or its close -work-alike) to produce the directory listing displayed in Dired -buffers (@pxref{Dired}). However, MS-Windows and MS-DOS systems don't -come with such a program, although several ports of @sc{gnu} @code{ls} -are available. Therefore, Emacs on those systems @emph{emulates} -@code{ls} in Lisp, by using the @file{ls-lisp.el} package. While -@file{ls-lisp.el} provides a reasonably full emulation of @code{ls}, -there are some options and features peculiar to that emulation; -@iftex -for more details, see the documentation of the variables whose names -begin with @code{ls-lisp}. -@end iftex -@ifnottex -they are described in this section. - - The @code{ls} emulation supports many of the @code{ls} switches, but -it doesn't support all of them. Here's the list of the switches it -does support: @option{-A}, @option{-a}, @option{-B}, @option{-C}, -@option{-c}, @option{-i}, @option{-G}, @option{-g}, @option{-R}, -@option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U}, -@option{-u}, and @option{-X}. The @option{-F} switch is partially -supported (it appends the character that classifies the file, but does -not prevent symlink following). - -@vindex ls-lisp-use-insert-directory-program - On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs -is built, so the Lisp emulation of @code{ls} is always used on those -platforms. If you have a ported @code{ls}, setting -@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value -will revert to using an external program named by the variable -@code{insert-directory-program}. - -@vindex ls-lisp-ignore-case - By default, @file{ls-lisp.el} uses a case-sensitive sort order for -the directory listing it produces; this is so the listing looks the -same as on other platforms. If you wish that the files be sorted in -case-insensitive order, set the variable @code{ls-lisp-ignore-case} to -a non-@code{nil} value. - -@vindex ls-lisp-dirs-first - By default, files and subdirectories are sorted together, to emulate -the behavior of @code{ls}. However, native MS-Windows/MS-DOS file -managers list the directories before the files; if you want that -behavior, customize the option @code{ls-lisp-dirs-first} to a -non-@code{nil} value. - -@vindex ls-lisp-verbosity - The variable @code{ls-lisp-verbosity} controls the file attributes -that @file{ls-lisp.el} displays. The value should be a list that -contains one or more of the symbols @code{links}, @code{uid}, and -@code{gid}. @code{links} means display the count of different file -names that are associated with (a.k.a.@: @dfn{links to}) the file's -data; this is only useful on NTFS volumes. @code{uid} means display -the numerical identifier of the user who owns the file. @code{gid} -means display the numerical identifier of the file owner's group. The -default value is @code{(links uid gid)} i.e.@: all the 3 optional -attributes are displayed. - -@vindex ls-lisp-emulation - The variable @code{ls-lisp-emulation} controls the flavour of the -@code{ls} emulation by setting the defaults for the 3 options -described above: @code{ls-lisp-ignore-case}, -@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of -this option can be one of the following symbols: - -@table @code -@item GNU -@itemx nil -Emulate @sc{gnu} systems; this is the default. This sets -@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to -@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}. -@item UNIX -Emulate Unix systems. Like @code{GNU}, but sets -@code{ls-lisp-verbosity} to @code{(links uid)}. -@item MacOS -Emulate MacOS. Sets @code{ls-lisp-ignore-case} to @code{t}, and -@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}. -@item MS-Windows -Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and -@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to -@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X. -Note that the default emulation is @emph{not} @code{MS-Windows}, even -on Windows, since many users of Emacs on those platforms prefer the -@sc{gnu} defaults. -@end table - -@noindent -Any other value of @code{ls-lisp-emulation} means the same as -@code{GNU}. Note that this option needs to be set @emph{before} -@file{ls-lisp.el} is loaded, which means that on MS-Windows and MS-DOS -you will have to set the value from your @file{.emacs} file and then -restart Emacs, since @file{ls-lisp.el} is preloaded. - -@vindex ls-lisp-support-shell-wildcards - The variable @code{ls-lisp-support-shell-wildcards} controls how -file-name patterns are supported: if it is non-@code{nil} (the -default), they are treated as shell-style wildcards; otherwise they -are treated as Emacs regular expressions. - -@vindex ls-lisp-format-time-list - The variable @code{ls-lisp-format-time-list} defines how to format -the date and time of files. @emph{The value of this variable is -ignored}, unless Emacs cannot determine the current locale. (However, -if the value of @code{ls-lisp-use-localized-time-format} is -non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if -the current locale is available; see below.) - -The value of @code{ls-lisp-format-time-list} is a list of 2 strings. -The first string is used if the file was modified within the current -year, while the second string is used for older files. In each of -these two strings you can use @samp{%}-sequences to substitute parts -of the time. For example: -@lisp -("%b %e %H:%M" "%b %e %Y") -@end lisp - -@noindent -Note that the strings substituted for these @samp{%}-sequences depend -on the current locale. @xref{Time Parsing,,, elisp, The Emacs Lisp -Reference Manual}, for more about format time specs. - -@vindex ls-lisp-use-localized-time-format - Normally, Emacs formats the file time stamps in either traditional -or ISO-style time format. However, if the value of the variable -@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs -formats file time stamps according to what -@code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in -@code{ls-lisp-format-time-list} produce locale-dependent month and day -names, which might cause misalignment of columns in Dired display. -@end ifnottex - -@node Windows HOME -@section HOME Directory on MS-Windows -@cindex @code{HOME} directory on MS-Windows - - The Windows equivalent of the @code{HOME} directory is the -@dfn{user-specific application data directory}. The actual location -depends on your Windows version and system configuration; typical values -are @file{C:\Documents and Settings\@var{username}\Application Data} on -Windows 2K/XP and later, and either @file{C:\WINDOWS\Application Data} -or @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the -older Windows 9X/ME systems. - -@cindex init file @file{.emacs} on MS-Windows - The home directory is where your init file @file{.emacs} is stored. -When Emacs starts, it first checks whether the environment variable -@env{HOME} is set. If it is, it looks for the init file in the -directory pointed by @env{HOME}. If @env{HOME} is not defined, Emacs -checks for an existing @file{.emacs} file in @file{C:\}, the root -directory of drive @file{C:}@footnote{ -The check in @file{C:\} is in preference to the application data -directory for compatibility with older versions of Emacs, which didn't -check the application data directory. -}. If there's no such file in @file{C:\}, Emacs next uses the Windows -system calls to find out the exact location of your application data -directory. If that fails as well, Emacs falls back to @file{C:\}. - - Whatever the final place is, Emacs sets the value of the @env{HOME} -environment variable to point to it, and it will use that location for -other files and directories it normally creates in the user's home -directory. - - You can always find out where Emacs thinks is your home directory's -location by typing @kbd{C-x d ~/ @key{RET}}. This should present the -list of files in the home directory, and show its full name on the -first line. Likewise, to visit your init file, type @kbd{C-x C-f -~/.emacs @key{RET}}. - -@cindex @file{_emacs} init file, MS-Windows - Because MS-DOS does not allow file names with leading dots, and -because older Windows systems made it hard to create files with such -names, the Windows port of Emacs supports an alternative name -@file{_emacs} as a fallback, if such a file exists in the home -directory, whereas @file{.emacs} does not. - -@node Windows Keyboard -@section Keyboard Usage on MS-Windows -@cindex keyboard, MS-Windows - - This section describes the Windows-specific features related to -keyboard input in Emacs. - -@cindex MS-Windows keyboard shortcuts - Many key combinations (known as ``keyboard shortcuts'') that have -conventional uses in MS-Windows programs conflict with traditional -Emacs key bindings. (These Emacs key bindings were established years -before Microsoft was founded.) Examples of conflicts include -@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. -You can redefine some of them with meanings more like the MS-Windows -meanings by enabling CUA Mode (@pxref{CUA Bindings}). - -@kindex F10 @r{(MS-Windows)} -@cindex menu bar access using keyboard @r{(MS-Windows)} - The @key{F10} key on Windows activates the menu bar in a way that -makes it possible to use the menus without a mouse. In this mode, the -arrow keys traverse the menus, @key{RET} selects a highlighted menu -item, and @key{ESC} closes the menu. - -@iftex -@inforef{Windows Keyboard, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex -@ifnottex -@vindex w32-alt-is-meta -@cindex @code{Alt} key (MS-Windows) - By default, the key labeled @key{Alt} is mapped as the @key{META} -key. If you wish it to produce the @code{Alt} modifier instead, set -the variable @code{w32-alt-is-meta} to a @code{nil} value. - -@vindex w32-capslock-is-shiftlock - By default, the @key{CapsLock} key only affects normal character -keys (it converts lower-case characters to their upper-case -variants). However, if you set the variable -@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the -@key{CapsLock} key will affect non-character keys as well, as if you -pressed the @key{Shift} key while typing the non-character key. - -@vindex w32-enable-caps-lock - If the variable @code{w32-enable-caps-lock} is set to a @code{nil} -value, the @key{CapsLock} key produces the symbol @code{capslock} -instead of the shifted version of they keys. The default value is -@code{t}. - -@vindex w32-enable-num-lock -@cindex keypad keys (MS-Windows) - Similarly, if @code{w32-enable-num-lock} is @code{nil}, the -@key{NumLock} key will produce the symbol @code{kp-numlock}. The -default is @code{t}, which causes @key{NumLock} to work as expected: -toggle the meaning of the keys on the numeric keypad. -@end ifnottex - -@vindex w32-apps-modifier - The variable @code{w32-apps-modifier} controls the effect of the -@key{Apps} key (usually located between the right @key{Alt} and the -right @key{Ctrl} keys). Its value can be one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} for the respective modifier, or @code{nil} to appear -as the key @code{apps}. The default is @code{nil}. - -@vindex w32-lwindow-modifier -@vindex w32-rwindow-modifier -@vindex w32-scroll-lock-modifier - The variable @code{w32-lwindow-modifier} determines the effect of -the left Windows key (usually labeled with @key{start} and the Windows -logo). If its value is @code{nil} (the default), the key will produce -the symbol @code{lwindow}. Setting it to one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} will produce the respective modifier. A similar -variable @code{w32-rwindow-modifier} controls the effect of the right -Windows key, and @code{w32-scroll-lock-modifier} does the same for the -@key{ScrLock} key. If these variables are set to @code{nil}, the -right Windows key produces the symbol @code{rwindow} and @key{ScrLock} -produces the symbol @code{scroll}. - -@vindex w32-pass-alt-to-system -@cindex Windows system menu -@cindex @code{Alt} key invokes menu (Windows) - Emacs compiled as a native Windows application normally turns off -the Windows feature that tapping the @key{ALT} key invokes the Windows -menu. The reason is that the @key{ALT} serves as @key{META} in Emacs. -When using Emacs, users often press the @key{META} key temporarily and -then change their minds; if this has the effect of bringing up the -Windows menu, it alters the meaning of subsequent commands. Many -users find this frustrating. - - You can re-enable Windows' default handling of tapping the @key{ALT} -key by setting @code{w32-pass-alt-to-system} to a non-@code{nil} -value. - -@ifnottex -@vindex w32-pass-lwindow-to-system -@vindex w32-pass-rwindow-to-system - The variables @code{w32-pass-lwindow-to-system} and -@code{w32-pass-rwindow-to-system} determine whether the respective -keys are passed to Windows or swallowed by Emacs. If the value is -@code{nil}, the respective key is silently swallowed by Emacs, -otherwise it is passed to Windows. The default is @code{t} for both -of these variables. Passing each of these keys to Windows produces -its normal effect: for example, @kbd{@key{Lwindow}} opens the -@code{Start} menu, etc.@footnote{ -Some combinations of the ``Windows'' keys with other keys are caught -by Windows at low level in a way that Emacs currently cannot prevent. -For example, @kbd{@key{Lwindow} r} always pops up the Windows -@samp{Run} dialog. Customizing the value of -@code{w32-phantom-key-code} might help in some cases, though.} - -@vindex w32-recognize-altgr -@kindex AltGr @r{(MS-Windows)} -@cindex AltGr key (MS-Windows) - The variable @code{w32-recognize-altgr} controls whether the -@key{AltGr} key (if it exists on your keyboard), or its equivalent, -the combination of the right @key{Alt} and left @key{Ctrl} keys -pressed together, is recognized as the @key{AltGr} key. The default -is @code{t}, which means these keys produce @code{AltGr}; setting it -to @code{nil} causes @key{AltGr} or the equivalent key combination to -be interpreted as the combination of @key{CTRL} and @key{META} -modifiers. -@end ifnottex - -@node Windows Mouse -@section Mouse Usage on MS-Windows -@cindex mouse, and MS-Windows - - This section describes the Windows-specific variables related to -mouse. - -@vindex w32-mouse-button-tolerance -@cindex simulation of middle mouse button - The variable @code{w32-mouse-button-tolerance} specifies the -time interval, in milliseconds, for faking middle mouse button press -on 2-button mice. If both mouse buttons are depressed within this -time interval, Emacs generates a middle mouse button click event -instead of a double click on one of the buttons. - -@vindex w32-pass-extra-mouse-buttons-to-system - If the variable @code{w32-pass-extra-mouse-buttons-to-system} is -non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to -Windows. - -@vindex w32-swap-mouse-buttons - The variable @code{w32-swap-mouse-buttons} controls which of the 3 -mouse buttons generates the @kbd{mouse-2} events. When it is -@code{nil} (the default), the middle button generates @kbd{mouse-2} -and the right button generates @kbd{mouse-3} events. If this variable -is non-@code{nil}, the roles of these two buttons are reversed. - -@node Windows Processes -@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP -@cindex subprocesses on MS-Windows - -@cindex DOS applications, running from Emacs - Emacs compiled as a native Windows application (as opposed to the DOS -version) includes full support for asynchronous subprocesses. -In the Windows version, synchronous and asynchronous subprocesses work -fine on both -Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows -applications. However, when you run a DOS application in a subprocess, -you may encounter problems or be unable to run the application at all; -and if you run two DOS applications at the same time in two -subprocesses, you may have to reboot your system. - -Since the standard command interpreter (and most command line utilities) -on Windows 9X are DOS applications, these problems are significant when -using that system. But there's nothing we can do about them; only -Microsoft can fix them. - -If you run just one DOS application subprocess, the subprocess should -work as expected as long as it is ``well-behaved'' and does not perform -direct screen access or other unusual actions. If you have a CPU -monitor application, your machine will appear to be 100% busy even when -the DOS application is idle, but this is only an artifact of the way CPU -monitors measure processor load. - -You must terminate the DOS application before you start any other DOS -application in a different subprocess. Emacs is unable to interrupt or -terminate a DOS subprocess. The only way you can terminate such a -subprocess is by giving it a command that tells its program to exit. - -If you attempt to run two DOS applications at the same time in separate -subprocesses, the second one that is started will be suspended until the -first one finishes, even if either or both of them are asynchronous. - -@cindex kill DOS application -If you can go to the first subprocess, and tell it to exit, the second -subprocess should continue normally. However, if the second subprocess -is synchronous, Emacs itself will be hung until the first subprocess -finishes. If it will not finish without user input, then you have no -choice but to reboot if you are running on Windows 9X. If you are -running on Windows NT/2K/XP, you can use a process viewer application to kill -the appropriate instance of NTVDM instead (this will terminate both DOS -subprocesses). - -If you have to reboot Windows 9X in this situation, do not use the -@code{Shutdown} command on the @code{Start} menu; that usually hangs the -system. Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose -@code{Shutdown}. That usually works, although it may take a few minutes -to do its job. - -@vindex w32-quote-process-args - The variable @code{w32-quote-process-args} controls how Emacs quotes -the process arguments. Non-@code{nil} means quote with the @code{"} -character. If the value is a character, use that character to escape -any quote characters that appear; otherwise chose a suitable escape -character based on the type of the program. - -@ifnottex -@findex w32-shell-execute - The function @code{w32-shell-execute} can be useful for writing -customized commands that run MS-Windows applications registered to -handle a certain standard Windows operation for a specific type of -document or file. This function is a wrapper around the Windows -@code{ShellExecute} API. See the MS-Windows API documentation for -more details. -@end ifnottex - -@node Windows Printing -@section Printing and MS-Windows - - Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and -@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and -MS-Windows by sending the output to one of the printer ports, if a -Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS and MS-Windows. - - Emacs on Windows automatically determines your default printer and -sets the variable @var{printer-name} to that printer's name. But in -some rare cases this can fail, or you may wish to use a different -printer from within Emacs. The rest of this section explains how to -tell Emacs which printer to use. - -@vindex printer-name@r{, (MS-DOS/MW-Windows)} - If you want to use your local printer, then set the Lisp variable -@code{lpr-command} to @code{""} (its default value on Windows) and -@code{printer-name} to the name of the printer port---for example, -@code{"PRN"}, the usual local printer port or @code{"LPT2"}, or -@code{"COM1"} for a serial printer. You can also set -@code{printer-name} to a file name, in which case ``printed'' output -is actually appended to that file. If you set @code{printer-name} to -@code{"NUL"}, printed output is silently discarded (sent to the system -null device). - - You can also use a printer shared by another machine by setting -@code{printer-name} to the UNC share name for that printer---for -example, @code{"//joes_pc/hp4si"}. (It doesn't matter whether you use -forward slashes or backslashes here.) To find out the names of shared -printers, run the command @samp{net view} from the command prompt to -obtain a list of servers, and @samp{net view @var{server-name}} to see -the names of printers (and directories) shared by that server. -Alternatively, click the @samp{Network Neighborhood} icon on your -desktop, and look for machines which share their printers via the -network. - -@cindex @samp{net use}, and printing on MS-Windows -@cindex networked printers (MS-Windows) - If the printer doesn't appear in the output of @samp{net view}, or -if setting @code{printer-name} to the UNC share name doesn't produce a -hardcopy on that printer, you can use the @samp{net use} command to -connect a local print port such as @code{"LPT2"} to the networked -printer. For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{ -Note that the @samp{net use} command requires the UNC share name to be -typed with the Windows-style backslashes, while the value of -@code{printer-name} can be set with either forward- or backslashes.} -causes Windows to @dfn{capture} the @code{LPT2} port and redirect the -printed material to the printer connected to the machine @code{joes_pc}. -After this command, setting @code{printer-name} to @code{"LPT2"} -should produce the hardcopy on the networked printer. - - With some varieties of Windows network software, you can instruct -Windows to capture a specific printer port such as @code{"LPT2"}, and -redirect it to a networked printer via the @w{@code{Control -Panel->Printers}} applet instead of @samp{net use}. - - If you set @code{printer-name} to a file name, it's best to use an -absolute file name. Emacs changes the working directory according to -the default directory of the current buffer, so if the file name in -@code{printer-name} is relative, you will end up with several such -files, each one in the directory of the buffer from which the printing -was done. - - If the value of @code{printer-name} is correct, but printing does -not produce the hardcopy on your printer, it is possible that your -printer does not support printing plain text (some cheap printers omit -this functionality). In that case, try the PostScript print commands, -described below. - -@findex print-buffer @r{(MS-DOS)} -@findex print-region @r{(MS-DOS)} -@vindex lpr-headers-switches @r{(MS-DOS)} - The commands @code{print-buffer} and @code{print-region} call the -@code{pr} program, or use special switches to the @code{lpr} program, to -produce headers on each printed page. MS-DOS and MS-Windows don't -normally have these programs, so by default, the variable -@code{lpr-headers-switches} is set so that the requests to print page -headers are silently ignored. Thus, @code{print-buffer} and -@code{print-region} produce the same output as @code{lpr-buffer} and -@code{lpr-region}, respectively. If you do have a suitable @code{pr} -program (for example, from GNU Coreutils), set -@code{lpr-headers-switches} to @code{nil}; Emacs will then call -@code{pr} to produce the page headers, and print the resulting output as -specified by @code{printer-name}. - -@vindex print-region-function @r{(MS-DOS)} -@cindex lpr usage under MS-DOS -@vindex lpr-command @r{(MS-DOS)} -@vindex lpr-switches @r{(MS-DOS)} - Finally, if you do have an @code{lpr} work-alike, you can set the -variable @code{lpr-command} to @code{"lpr"}. Then Emacs will use -@code{lpr} for printing, as on other systems. (If the name of the -program isn't @code{lpr}, set @code{lpr-command} to specify where to -find it.) The variable @code{lpr-switches} has its standard meaning -when @code{lpr-command} is not @code{""}. If the variable -@code{printer-name} has a string value, it is used as the value for the -@code{-P} option to @code{lpr}, as on Unix. - -@findex ps-print-buffer @r{(MS-DOS)} -@findex ps-spool-buffer @r{(MS-DOS)} -@vindex ps-printer-name @r{(MS-DOS)} -@vindex ps-lpr-command @r{(MS-DOS)} -@vindex ps-lpr-switches @r{(MS-DOS)} - A parallel set of variables, @code{ps-lpr-command}, -@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript -Variables}), defines how PostScript files should be printed. These -variables are used in the same way as the corresponding variables -described above for non-PostScript printing. Thus, the value of -@code{ps-printer-name} is used as the name of the device (or file) to -which PostScript output is sent, just as @code{printer-name} is used -for non-PostScript printing. (There are two distinct sets of -variables in case you have two printers attached to two different -ports, and only one of them is a PostScript printer.) - - The default value of the variable @code{ps-lpr-command} is @code{""}, -which causes PostScript output to be sent to the printer port specified -by @code{ps-printer-name}, but @code{ps-lpr-command} can also be set to -the name of a program which will accept PostScript files. Thus, if you -have a non-PostScript printer, you can set this variable to the name of -a PostScript interpreter program (such as Ghostscript). Any switches -that need to be passed to the interpreter program are specified using -@code{ps-lpr-switches}. (If the value of @code{ps-printer-name} is a -string, it will be added to the list of switches as the value for the -@code{-P} option. This is probably only useful if you are using -@code{lpr}, so when using an interpreter typically you would set -@code{ps-printer-name} to something other than a string so it is -ignored.) - - For example, to use Ghostscript for printing on the system's default -printer, put this in your @file{.emacs} file: - -@example -(setq ps-printer-name t) -(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe") -(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH" - "-sDEVICE=mswinpr2" - "-sPAPERSIZE=a4")) -@end example - -@noindent -(This assumes that Ghostscript is installed in the -@file{D:/gs6.01} directory.) - -@node Windows Misc -@section Miscellaneous Windows-specific features - - This section describes miscellaneous Windows-specific features. - -@vindex w32-use-visible-system-caret -@cindex screen reader software, MS-Windows - The variable @code{w32-use-visible-system-caret} is a flag that -determines whether to make the system caret visible. The default is -@code{nil}, which means Emacs draws its own cursor to indicate the -position of point. A non-@code{nil} value means Emacs will indicate -point location by the system caret; this facilitates use of screen -reader software. When this variable is non-@code{nil}, other -variables affecting the cursor display have no effect. - -@iftex -@inforef{Windows Misc, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex - -@ifnottex -@vindex w32-grab-focus-on-raise -@cindex frame focus policy, MS-Windows - The variable @code{w32-grab-focus-on-raise}, if set to a -non-@code{nil} value causes a frame to grab focus when it is raised. -The default is @code{t}, which fits well with the Windows default -click-to-focus policy. - -@vindex w32-list-proportional-fonts - The variable @code{w32-list-proportional-fonts} controls whether -proportional fonts are included in the font selection dialog. If its -value is non-@code{nil}, these fonts will be included. The default is -@code{nil}. -@end ifnottex - -@ifnottex -@include msdog-xtra.texi -@end ifnottex - -@ignore - arch-tag: f39d2590-5dcc-4318-88d9-0eb73ca10fa2 -@end ignore diff --git a/man/mule.texi b/man/mule.texi deleted file mode 100644 index c71c820dc27..00000000000 --- a/man/mule.texi +++ /dev/null @@ -1,1535 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node International, Major Modes, Frames, Top -@chapter International Character Set Support -@cindex MULE -@cindex international scripts -@cindex multibyte characters -@cindex encoding of characters - -@cindex Celtic -@cindex Chinese -@cindex Cyrillic -@cindex Czech -@cindex Devanagari -@cindex Hindi -@cindex Marathi -@cindex Ethiopic -@cindex German -@cindex Greek -@cindex Hebrew -@cindex IPA -@cindex Japanese -@cindex Korean -@cindex Lao -@cindex Latin -@cindex Polish -@cindex Romanian -@cindex Slovak -@cindex Slovenian -@cindex Thai -@cindex Tibetan -@cindex Turkish -@cindex Vietnamese -@cindex Dutch -@cindex Spanish - Emacs supports a wide variety of international character sets, -including European and Vietnamese variants of the Latin alphabet, as -well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek, -Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA, -Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts. -Emacs also supports various encodings of these characters used by -other internationalized software, such as word processors and mailers. - - Emacs allows editing text with international characters by supporting -all the related activities: - -@itemize @bullet -@item -You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and -pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as -compilers, spell-checkers, and mailers). Setting your language -environment (@pxref{Language Environments}) takes care of setting up the -coding systems and other options for a specific language or culture. -Alternatively, you can specify how Emacs should encode or decode text -for each command; see @ref{Text Coding}. - -@item -You can display non-@acronym{ASCII} characters encoded by the various -scripts. This works by using appropriate fonts on graphics displays -(@pxref{Defining Fontsets}), and by sending special codes to text-only -displays (@pxref{Terminal Coding}). If some characters are displayed -incorrectly, refer to @ref{Undisplayable Characters}, which describes -possible problems and explains how to solve them. - -@item -You can insert non-@acronym{ASCII} characters or search for them. To do that, -you can specify an input method (@pxref{Select Input Method}) suitable -for your language, or use the default input method set up when you set -your language environment. If -your keyboard can produce non-@acronym{ASCII} characters, you can select an -appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs -will accept those characters. Latin-1 characters can also be input by -using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. - -On X Window systems, your locale should be set to an appropriate value -to make sure Emacs interprets keyboard input correctly; see -@ref{Language Environments, locales}. -@end itemize - - The rest of this chapter describes these issues in detail. - -@menu -* International Chars:: Basic concepts of multibyte characters. -* Enabling Multibyte:: Controlling whether to use multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Multibyte Conversion:: How single-byte characters convert to multibyte. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Undisplayable Characters:: When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. -@end menu - -@node International Chars -@section Introduction to International Character Sets - - The users of international character sets and scripts have -established many more-or-less standard coding systems for storing -files. Emacs internally uses a single multibyte character encoding, -so that it can intermix characters from all these scripts in a single -buffer or string. This encoding represents each non-@acronym{ASCII} -character as a sequence of bytes in the range 0200 through 0377. -Emacs translates between the multibyte character encoding and various -other coding systems when reading and writing files, when exchanging -data with subprocesses, and (in some cases) in the @kbd{C-q} command -(@pxref{Multibyte Conversion}). - -@kindex C-h h -@findex view-hello-file -@cindex undisplayable characters -@cindex @samp{?} in display - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which shows how to say ``hello'' in many languages. -This illustrates various scripts. If some characters can't be -displayed on your terminal, they appear as @samp{?} or as hollow boxes -(@pxref{Undisplayable Characters}). - - Keyboards, even in the countries where these character sets are used, -generally don't have keys for all the characters in them. So Emacs -supports various @dfn{input methods}, typically one for each script or -language, to make it convenient to type them. - -@kindex C-x RET - The prefix key @kbd{C-x @key{RET}} is used for commands that pertain -to multibyte characters, coding systems, and input methods. - -@node Enabling Multibyte -@section Enabling Multibyte Characters - - By default, Emacs starts in multibyte mode, because that allows you to -use all the supported languages and scripts without limitations. - -@cindex turn multibyte support on or off - You can enable or disable multibyte character support, either for -Emacs as a whole, or for a single buffer. When multibyte characters -are disabled in a buffer, we call that @dfn{unibyte mode}. Then each -byte in that buffer represents a character, even codes 0200 through -0377. - - The old features for supporting the European character sets, ISO -Latin-1 and ISO Latin-2, work in unibyte mode as they did in Emacs 19 -and also work for the other ISO 8859 character sets. However, there -is no need to turn off multibyte character support to use ISO Latin; -the Emacs multibyte character set includes all the characters in these -character sets, and Emacs can translate automatically to and from the -ISO codes. - - To edit a particular file in unibyte representation, visit it using -@code{find-file-literally}. @xref{Visiting}. To convert a buffer in -multibyte representation into a single-byte representation of the same -characters, the easiest way is to save the contents in a file, kill the -buffer, and find the file again with @code{find-file-literally}. You -can also use @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}) and specify @samp{raw-text} as -the coding system with which to find or save a file. @xref{Text -Coding}. Finding a file as @samp{raw-text} doesn't disable format -conversion, uncompression and auto mode selection as -@code{find-file-literally} does. - -@vindex enable-multibyte-characters -@vindex default-enable-multibyte-characters - To turn off multibyte character support by default, start Emacs with -the @samp{--unibyte} option (@pxref{Initial Options}), or set the -environment variable @env{EMACS_UNIBYTE}. You can also customize -@code{enable-multibyte-characters} or, equivalently, directly set the -variable @code{default-enable-multibyte-characters} to @code{nil} in -your init file to have basically the same effect as @samp{--unibyte}. - -@findex toggle-enable-multibyte-characters - To convert a unibyte session to a multibyte session, set -@code{default-enable-multibyte-characters} to @code{t}. Buffers which -were created in the unibyte session before you turn on multibyte support -will stay unibyte. You can turn on multibyte support in a specific -buffer by invoking the command @code{toggle-enable-multibyte-characters} -in that buffer. - -@cindex Lisp files, and multibyte operation -@cindex multibyte operation, and Lisp files -@cindex unibyte operation, and Lisp files -@cindex init file, and non-@acronym{ASCII} characters -@cindex environment variables, and non-@acronym{ASCII} characters - With @samp{--unibyte}, multibyte strings are not created during -initialization from the values of environment variables, -@file{/etc/passwd} entries etc.@: that contain non-@acronym{ASCII} 8-bit -characters. - - Emacs normally loads Lisp files as multibyte, regardless of whether -you used @samp{--unibyte}. This includes the Emacs initialization file, -@file{.emacs}, and the initialization files of Emacs packages such as -Gnus. However, you can specify unibyte loading for a particular Lisp -file, by putting @w{@samp{-*-unibyte: t;-*-}} in a comment on the first -line (@pxref{File Variables}). Then that file is always loaded as -unibyte text, even if you did not start Emacs with @samp{--unibyte}. -The motivation for these conventions is that it is more reliable to -always load any particular Lisp file in the same way. However, you can -load a Lisp file as unibyte, on any one occasion, by typing @kbd{C-x -@key{RET} c raw-text @key{RET}} immediately before loading it. - - The mode line indicates whether multibyte character support is -enabled in the current buffer. If it is, there are two or more -characters (most often two dashes) near the beginning of the mode -line, before the indication of the visited file's end-of-line -convention (colon, backslash, etc.). When multibyte characters -are not enabled, nothing precedes the colon except a single dash. -@xref{Mode Line}, for more details about this. - -@node Language Environments -@section Language Environments -@cindex language environments - - All supported character sets are supported in Emacs buffers whenever -multibyte characters are enabled; there is no need to select a -particular language in order to display its characters in an Emacs -buffer. However, it is important to select a @dfn{language environment} -in order to set various defaults. The language environment really -represents a choice of preferred script (more or less) rather than a -choice of language. - - The language environment controls which coding systems to recognize -when reading text (@pxref{Recognize Coding}). This applies to files, -incoming mail, netnews, and any other text you read into Emacs. It may -also specify the default coding system to use when you create a file. -Each language environment also specifies a default input method. - -@findex set-language-environment -@vindex current-language-environment - To select a language environment, you can customize the variable -@code{current-language-environment} or use the command @kbd{M-x -set-language-environment}. It makes no difference which buffer is -current when you use this command, because the effects apply globally to -the Emacs session. The supported language environments include: - -@cindex Euro sign -@cindex UTF-8 -@quotation -ASCII, Belarusian, Brazilian Portuguese, Bulgarian, Chinese-BIG5, -Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Croatian, Cyrillic-ALT, -Cyrillic-ISO, Cyrillic-KOI8, Czech, Devanagari, Dutch, English, -Esperanto, Ethiopic, French, Georgian, German, Greek, Hebrew, IPA, -Italian, Japanese, Kannada, Korean, Lao, Latin-1, Latin-2, Latin-3, -Latin-4, Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated -Latin-1 with the Euro sign), Latvian, Lithuanian, Malayalam, Polish, -Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Tajik, Tamil, -Thai, Tibetan, Turkish, UTF-8 (for a setup which prefers Unicode -characters and files encoded in UTF-8), Ukrainian, Vietnamese, Welsh, -and Windows-1255 (for a setup which prefers Cyrillic characters and -files encoded in Windows-1255). -@tex -\hbadness=10000\par % just avoid underfull hbox warning -@end tex -@end quotation - -@cindex fonts for various scripts -@cindex Intlfonts package, installation - To display the script(s) used by your language environment on a -graphical display, you need to have a suitable font. If some of the -characters appear as empty boxes, you should install the GNU Intlfonts -package, which includes fonts for most supported scripts.@footnote{If -you run Emacs on X, you need to inform the X server about the location -of the newly installed fonts with the following commands: - -@example - xset fp+ /usr/local/share/emacs/fonts - xset fp rehash -@end example -} -@xref{Fontsets}, for more details about setting up your fonts. - -@findex set-locale-environment -@vindex locale-language-names -@vindex locale-charset-language-names -@cindex locales - Some operating systems let you specify the character-set locale you -are using by setting the locale environment variables @env{LC_ALL}, -@env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is -set, the first one that is nonempty specifies your locale for this -purpose.} During startup, Emacs looks up your character-set locale's -name in the system locale alias table, matches its canonical name -against entries in the value of the variables -@code{locale-charset-language-names} and @code{locale-language-names}, -and selects the corresponding language environment if a match is found. -(The former variable overrides the latter.) It also adjusts the display -table and terminal coding system, the locale coding system, the -preferred coding system as needed for the locale, and---last but not -least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard. - - If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG} -environment variables while running Emacs, you may want to invoke the -@code{set-locale-environment} function afterwards to readjust the -language environment from the new locale. - -@vindex locale-preferred-coding-systems - The @code{set-locale-environment} function normally uses the preferred -coding system established by the language environment to decode system -messages. But if your locale matches an entry in the variable -@code{locale-preferred-coding-systems}, Emacs uses the corresponding -coding system instead. For example, if the locale @samp{ja_JP.PCK} -matches @code{japanese-shift-jis} in -@code{locale-preferred-coding-systems}, Emacs uses that encoding even -though it might normally use @code{japanese-iso-8bit}. - - You can override the language environment chosen at startup with -explicit use of the command @code{set-language-environment}, or with -customization of @code{current-language-environment} in your init -file. - -@kindex C-h L -@findex describe-language-environment - To display information about the effects of a certain language -environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env} -@key{RET}} (@code{describe-language-environment}). This tells you -which languages this language environment is useful for, and lists the -character sets, coding systems, and input methods that go with it. It -also shows some sample text to illustrate scripts used in this -language environment. If you give an empty input for @var{lang-env}, -this command describes the chosen language environment. - -@vindex set-language-environment-hook - You can customize any language environment with the normal hook -@code{set-language-environment-hook}. The command -@code{set-language-environment} runs that hook after setting up the new -language environment. The hook functions can test for a specific -language environment by checking the variable -@code{current-language-environment}. This hook is where you should -put non-default settings for specific language environment, such as -coding systems for keyboard input and terminal output, the default -input method, etc. - -@vindex exit-language-environment-hook - Before it starts to set up the new language environment, -@code{set-language-environment} first runs the hook -@code{exit-language-environment-hook}. This hook is useful for undoing -customizations that were made with @code{set-language-environment-hook}. -For instance, if you set up a special key binding in a specific language -environment using @code{set-language-environment-hook}, you should set -up @code{exit-language-environment-hook} to restore the normal binding -for that key. - -@node Input Methods -@section Input Methods - -@cindex input methods - An @dfn{input method} is a kind of character conversion designed -specifically for interactive input. In Emacs, typically each language -has its own input method; sometimes several languages which use the same -characters can share one input method. A few languages support several -input methods. - - The simplest kind of input method works by mapping @acronym{ASCII} letters -into another alphabet; this allows you to use one other alphabet -instead of @acronym{ASCII}. The Greek and Russian input methods -work this way. - - A more powerful technique is composition: converting sequences of -characters into one letter. Many European input methods use composition -to produce a single non-@acronym{ASCII} letter from a sequence that consists of a -letter followed by accent characters (or vice versa). For example, some -methods convert the sequence @kbd{a'} into a single accented letter. -These input methods have no special commands of their own; all they do -is compose sequences of printing characters. - - The input methods for syllabic scripts typically use mapping followed -by composition. The input methods for Thai and Korean work this way. -First, letters are mapped into symbols for particular sounds or tone -marks; then, sequences of these which make up a whole syllable are -mapped into one syllable sign. - - Chinese and Japanese require more complex methods. In Chinese input -methods, first you enter the phonetic spelling of a Chinese word (in -input method @code{chinese-py}, among others), or a sequence of -portions of the character (input methods @code{chinese-4corner} and -@code{chinese-sw}, and others). One input sequence typically -corresponds to many possible Chinese characters. You select the one -you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n}, -@kbd{C-p}, and digits, which have special meanings in this situation. - - The possible characters are conceptually arranged in several rows, -with each row holding up to 10 alternatives. Normally, Emacs displays -just one row at a time, in the echo area; @code{(@var{i}/@var{j})} -appears at the beginning, to indicate that this is the @var{i}th row -out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to -display the next row or the previous row. - - Type @kbd{C-f} and @kbd{C-b} to move forward and backward among -the alternatives in the current row. As you do this, Emacs highlights -the current alternative with a special color; type @code{C-@key{SPC}} -to select the current alternative and use it as input. The -alternatives in the row are also numbered; the number appears before -the alternative. Typing a digit @var{n} selects the @var{n}th -alternative of the current row and uses it as input. - - @key{TAB} in these Chinese input methods displays a buffer showing -all the possible characters at once; then clicking @kbd{Mouse-2} on -one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they -do the highlighting in the buffer showing the possible characters, -rather than in the echo area. - - In Japanese input methods, first you input a whole word using -phonetic spelling; then, after the word is in the buffer, Emacs -converts it into one or more characters using a large dictionary. One -phonetic spelling corresponds to a number of different Japanese words; -to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through -the alternatives. - - Sometimes it is useful to cut off input method processing so that the -characters you have just entered will not combine with subsequent -characters. For example, in input method @code{latin-1-postfix}, the -sequence @kbd{e '} combines to form an @samp{e} with an accent. What if -you want to enter them as separate characters? - - One way is to type the accent twice; this is a special feature for -entering the separate letter and accent. For example, @kbd{e ' '} gives -you the two characters @samp{e'}. Another way is to type another letter -after the @kbd{e}---something that won't combine with that---and -immediately delete it. For example, you could type @kbd{e e @key{DEL} -'} to get separate @samp{e} and @samp{'}. - - Another method, more general but not quite as easy to type, is to use -@kbd{C-\ C-\} between two characters to stop them from combining. This -is the command @kbd{C-\} (@code{toggle-input-method}) used twice. -@ifnottex -@xref{Select Input Method}. -@end ifnottex - -@cindex incremental search, input method interference - @kbd{C-\ C-\} is especially useful inside an incremental search, -because it stops waiting for more characters to combine, and starts -searching for what you have already entered. - - To find out how to input the character after point using the current -input method, type @kbd{C-u C-x =}. @xref{Position Info}. - -@vindex input-method-verbose-flag -@vindex input-method-highlight-flag - The variables @code{input-method-highlight-flag} and -@code{input-method-verbose-flag} control how input methods explain -what is happening. If @code{input-method-highlight-flag} is -non-@code{nil}, the partial sequence is highlighted in the buffer (for -most input methods---some disable this feature). If -@code{input-method-verbose-flag} is non-@code{nil}, the list of -possible characters to type next is displayed in the echo area (but -not when you are in the minibuffer). - -@node Select Input Method -@section Selecting an Input Method - -@table @kbd -@item C-\ -Enable or disable use of the selected input method. - -@item C-x @key{RET} C-\ @var{method} @key{RET} -Select a new input method for the current buffer. - -@item C-h I @var{method} @key{RET} -@itemx C-h C-\ @var{method} @key{RET} -@findex describe-input-method -@kindex C-h I -@kindex C-h C-\ -Describe the input method @var{method} (@code{describe-input-method}). -By default, it describes the current input method (if any). This -description should give you the full details of how to use any -particular input method. - -@item M-x list-input-methods -Display a list of all the supported input methods. -@end table - -@findex set-input-method -@vindex current-input-method -@kindex C-x RET C-\ - To choose an input method for the current buffer, use @kbd{C-x -@key{RET} C-\} (@code{set-input-method}). This command reads the -input method name from the minibuffer; the name normally starts with the -language environment that it is meant to be used with. The variable -@code{current-input-method} records which input method is selected. - -@findex toggle-input-method -@kindex C-\ - Input methods use various sequences of @acronym{ASCII} characters to -stand for non-@acronym{ASCII} characters. Sometimes it is useful to -turn off the input method temporarily. To do this, type @kbd{C-\} -(@code{toggle-input-method}). To reenable the input method, type -@kbd{C-\} again. - - If you type @kbd{C-\} and you have not yet selected an input method, -it prompts for you to specify one. This has the same effect as using -@kbd{C-x @key{RET} C-\} to specify an input method. - - When invoked with a numeric argument, as in @kbd{C-u C-\}, -@code{toggle-input-method} always prompts you for an input method, -suggesting the most recently selected one as the default. - -@vindex default-input-method - Selecting a language environment specifies a default input method for -use in various buffers. When you have a default input method, you can -select it in the current buffer by typing @kbd{C-\}. The variable -@code{default-input-method} specifies the default input method -(@code{nil} means there is none). - - In some language environments, which support several different input -methods, you might want to use an input method different from the -default chosen by @code{set-language-environment}. You can instruct -Emacs to select a different default input method for a certain -language environment, if you wish, by using -@code{set-language-environment-hook} (@pxref{Language Environments, -set-language-environment-hook}). For example: - -@lisp -(defun my-chinese-setup () - "Set up my private Chinese environment." - (if (equal current-language-environment "Chinese-GB") - (setq default-input-method "chinese-tonepy"))) -(add-hook 'set-language-environment-hook 'my-chinese-setup) -@end lisp - -@noindent -This sets the default input method to be @code{chinese-tonepy} -whenever you choose a Chinese-GB language environment. - -@findex quail-set-keyboard-layout - Some input methods for alphabetic scripts work by (in effect) -remapping the keyboard to emulate various keyboard layouts commonly used -for those scripts. How to do this remapping properly depends on your -actual keyboard layout. To specify which layout your keyboard has, use -the command @kbd{M-x quail-set-keyboard-layout}. - -@findex quail-show-key - You can use the command @kbd{M-x quail-show-key} to show what key (or -key sequence) to type in order to input the character following point, -using the selected keyboard layout. The command @kbd{C-u C-x =} also -shows that information in addition to the other information about the -character. - -@findex list-input-methods - To see a list of all the supported input methods, type @kbd{M-x -list-input-methods}. The list gives information about each input -method, including the string that stands for it in the mode line. - -@node Multibyte Conversion -@section Unibyte and Multibyte Non-@acronym{ASCII} characters - - When multibyte characters are enabled, character codes 0240 (octal) -through 0377 (octal) are not really legitimate in the buffer. The valid -non-@acronym{ASCII} printing characters have codes that start from 0400. - - If you type a self-inserting character in the range 0240 through -0377, or if you use @kbd{C-q} to insert one, Emacs assumes you -intended to use one of the ISO Latin-@var{n} character sets, and -converts it to the Emacs code representing that Latin-@var{n} -character. You select @emph{which} ISO Latin character set to use -through your choice of language environment -@iftex -(see above). -@end iftex -@ifnottex -(@pxref{Language Environments}). -@end ifnottex -If you do not specify a choice, the default is Latin-1. - - If you insert a character in the range 0200 through 0237, which -forms the @code{eight-bit-control} character set, it is inserted -literally. You should normally avoid doing this since buffers -containing such characters have to be written out in either the -@code{emacs-mule} or @code{raw-text} coding system, which is usually -not what you want. - -@node Coding Systems -@section Coding Systems -@cindex coding systems - - Users of various languages have established many more-or-less standard -coding systems for representing them. Emacs does not use these coding -systems internally; instead, it converts from various coding systems to -its own system when reading data, and converts the internal coding -system to other coding systems when writing data. Conversion is -possible in reading or writing files, in sending or receiving from the -terminal, and in exchanging data with subprocesses. - - Emacs assigns a name to each coding system. Most coding systems are -used for one language, and the name of the coding system starts with the -language name. Some coding systems are used for several languages; -their names usually start with @samp{iso}. There are also special -coding systems @code{no-conversion}, @code{raw-text} and -@code{emacs-mule} which do not convert printing characters at all. - -@cindex international files from DOS/Windows systems - A special class of coding systems, collectively known as -@dfn{codepages}, is designed to support text encoded by MS-Windows and -MS-DOS software. The names of these coding systems are -@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the -codepage. You can use these encodings just like any other coding -system; for example, to visit a file encoded in codepage 850, type -@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename} -@key{RET}}@footnote{ -In the MS-DOS port of Emacs, you need to create a @code{cp@var{nnn}} -coding system with @kbd{M-x codepage-setup}, before you can use it. -@iftex -@xref{MS-DOS and MULE,,,emacs-extra,Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{MS-DOS and MULE}. -@end ifnottex -}. - - In addition to converting various representations of non-@acronym{ASCII} -characters, a coding system can perform end-of-line conversion. Emacs -handles three different conventions for how to separate lines in a file: -newline, carriage-return linefeed, and just carriage-return. - -@table @kbd -@item C-h C @var{coding} @key{RET} -Describe coding system @var{coding}. - -@item C-h C @key{RET} -Describe the coding systems currently in use. - -@item M-x list-coding-systems -Display a list of all the supported coding systems. -@end table - -@kindex C-h C -@findex describe-coding-system - The command @kbd{C-h C} (@code{describe-coding-system}) displays -information about particular coding systems, including the end-of-line -conversion specified by those coding systems. You can specify a coding -system name as the argument; alternatively, with an empty argument, it -describes the coding systems currently selected for various purposes, -both in the current buffer and as the defaults, and the priority list -for recognizing coding systems (@pxref{Recognize Coding}). - -@findex list-coding-systems - To display a list of all the supported coding systems, type @kbd{M-x -list-coding-systems}. The list gives information about each coding -system, including the letter that stands for it in the mode line -(@pxref{Mode Line}). - -@cindex end-of-line conversion -@cindex line endings -@cindex MS-DOS end-of-line conversion -@cindex Macintosh end-of-line conversion - Each of the coding systems that appear in this list---except for -@code{no-conversion}, which means no conversion of any kind---specifies -how and whether to convert printing characters, but leaves the choice of -end-of-line conversion to be decided based on the contents of each file. -For example, if the file appears to use the sequence carriage-return -linefeed to separate lines, DOS end-of-line conversion will be used. - - Each of the listed coding systems has three variants which specify -exactly what to do for end-of-line conversion: - -@table @code -@item @dots{}-unix -Don't do any end-of-line conversion; assume the file uses -newline to separate lines. (This is the convention normally used -on Unix and GNU systems.) - -@item @dots{}-dos -Assume the file uses carriage-return linefeed to separate lines, and do -the appropriate conversion. (This is the convention normally used on -Microsoft systems.@footnote{It is also specified for MIME @samp{text/*} -bodies and in other network transport contexts. It is different -from the SGML reference syntax record-start/record-end format which -Emacs doesn't support directly.}) - -@item @dots{}-mac -Assume the file uses carriage-return to separate lines, and do the -appropriate conversion. (This is the convention normally used on the -Macintosh system.) -@end table - - These variant coding systems are omitted from the -@code{list-coding-systems} display for brevity, since they are entirely -predictable. For example, the coding system @code{iso-latin-1} has -variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and -@code{iso-latin-1-mac}. - -@cindex @code{undecided}, coding system - The coding systems @code{unix}, @code{dos}, and @code{mac} are -aliases for @code{undecided-unix}, @code{undecided-dos}, and -@code{undecided-mac}, respectively. These coding systems specify only -the end-of-line conversion, and leave the character code conversion to -be deduced from the text itself. - - The coding system @code{raw-text} is good for a file which is mainly -@acronym{ASCII} text, but may contain byte values above 127 which are -not meant to encode non-@acronym{ASCII} characters. With -@code{raw-text}, Emacs copies those byte values unchanged, and sets -@code{enable-multibyte-characters} to @code{nil} in the current buffer -so that they will be interpreted properly. @code{raw-text} handles -end-of-line conversion in the usual way, based on the data -encountered, and has the usual three variants to specify the kind of -end-of-line conversion to use. - - In contrast, the coding system @code{no-conversion} specifies no -character code conversion at all---none for non-@acronym{ASCII} byte values and -none for end of line. This is useful for reading or writing binary -files, tar files, and other files that must be examined verbatim. It, -too, sets @code{enable-multibyte-characters} to @code{nil}. - - The easiest way to edit a file with no conversion of any kind is with -the @kbd{M-x find-file-literally} command. This uses -@code{no-conversion}, and also suppresses other Emacs features that -might convert the file contents before you see them. @xref{Visiting}. - - The coding system @code{emacs-mule} means that the file contains -non-@acronym{ASCII} characters stored with the internal Emacs encoding. It -handles end-of-line conversion based on the data encountered, and has -the usual three variants to specify the kind of end-of-line conversion. - -@findex unify-8859-on-decoding-mode -@anchor{Character Translation} - The @dfn{character translation} feature can modify the effect of -various coding systems, by changing the internal Emacs codes that -decoding produces. For instance, the command -@code{unify-8859-on-decoding-mode} enables a mode that ``unifies'' the -Latin alphabets when decoding text. This works by converting all -non-@acronym{ASCII} Latin-@var{n} characters to either Latin-1 or -Unicode characters. This way it is easier to use various -Latin-@var{n} alphabets together. (In a future Emacs version we hope -to move towards full Unicode support and complete unification of -character sets.) - -@vindex enable-character-translation - If you set the variable @code{enable-character-translation} to -@code{nil}, that disables all character translation (including -@code{unify-8859-on-decoding-mode}). - -@node Recognize Coding -@section Recognizing Coding Systems - - Emacs tries to recognize which coding system to use for a given text -as an integral part of reading that text. (This applies to files -being read, output from subprocesses, text from X selections, etc.) -Emacs can select the right coding system automatically most of the -time---once you have specified your preferences. - - Some coding systems can be recognized or distinguished by which byte -sequences appear in the data. However, there are coding systems that -cannot be distinguished, not even potentially. For example, there is no -way to distinguish between Latin-1 and Latin-2; they use the same byte -values with different meanings. - - Emacs handles this situation by means of a priority list of coding -systems. Whenever Emacs reads a file, if you do not specify the coding -system to use, Emacs checks the data against each coding system, -starting with the first in priority and working down the list, until it -finds a coding system that fits the data. Then it converts the file -contents assuming that they are represented in this coding system. - - The priority list of coding systems depends on the selected language -environment (@pxref{Language Environments}). For example, if you use -French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use -Czech, you probably want Latin-2 to be preferred. This is one of the -reasons to specify a language environment. - -@findex prefer-coding-system - However, you can alter the coding system priority list in detail -with the command @kbd{M-x prefer-coding-system}. This command reads -the name of a coding system from the minibuffer, and adds it to the -front of the priority list, so that it is preferred to all others. If -you use this command several times, each use adds one element to the -front of the priority list. - - If you use a coding system that specifies the end-of-line conversion -type, such as @code{iso-8859-1-dos}, what this means is that Emacs -should attempt to recognize @code{iso-8859-1} with priority, and should -use DOS end-of-line conversion when it does recognize @code{iso-8859-1}. - -@vindex file-coding-system-alist - Sometimes a file name indicates which coding system to use for the -file. The variable @code{file-coding-system-alist} specifies this -correspondence. There is a special function -@code{modify-coding-system-alist} for adding elements to this list. For -example, to read and write all @samp{.txt} files using the coding system -@code{chinese-iso-8bit}, you can execute this Lisp expression: - -@smallexample -(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit) -@end smallexample - -@noindent -The first argument should be @code{file}, the second argument should be -a regular expression that determines which files this applies to, and -the third argument says which coding system to use for these files. - -@vindex inhibit-eol-conversion -@cindex DOS-style end-of-line display - Emacs recognizes which kind of end-of-line conversion to use based on -the contents of the file: if it sees only carriage-returns, or only -carriage-return linefeed sequences, then it chooses the end-of-line -conversion accordingly. You can inhibit the automatic use of -end-of-line conversion by setting the variable @code{inhibit-eol-conversion} -to non-@code{nil}. If you do that, DOS-style files will be displayed -with the @samp{^M} characters visible in the buffer; some people -prefer this to the more subtle @samp{(DOS)} end-of-line type -indication near the left edge of the mode line (@pxref{Mode Line, -eol-mnemonic}). - -@vindex inhibit-iso-escape-detection -@cindex escape sequences in files - By default, the automatic detection of coding system is sensitive to -escape sequences. If Emacs sees a sequence of characters that begin -with an escape character, and the sequence is valid as an ISO-2022 -code, that tells Emacs to use one of the ISO-2022 encodings to decode -the file. - - However, there may be cases that you want to read escape sequences -in a file as is. In such a case, you can set the variable -@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code -detection ignores any escape sequences, and never uses an ISO-2022 -encoding. The result is that all escape sequences become visible in -the buffer. - - The default value of @code{inhibit-iso-escape-detection} is -@code{nil}. We recommend that you not change it permanently, only for -one specific operation. That's because many Emacs Lisp source files -in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the -coding system @code{iso-2022-7bit}, and they won't be -decoded correctly when you visit those files if you suppress the -escape sequence detection. - -@vindex auto-coding-alist -@vindex auto-coding-regexp-alist -@vindex auto-coding-functions - The variables @code{auto-coding-alist}, -@code{auto-coding-regexp-alist} and @code{auto-coding-functions} are -the strongest way to specify the coding system for certain patterns of -file names, or for files containing certain patterns; these variables -even override @samp{-*-coding:-*-} tags in the file itself. Emacs -uses @code{auto-coding-alist} for tar and archive files, to prevent it -from being confused by a @samp{-*-coding:-*-} tag in a member of the -archive and thinking it applies to the archive file as a whole. -Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that -RMAIL files, whose names in general don't match any particular -pattern, are decoded correctly. One of the builtin -@code{auto-coding-functions} detects the encoding for XML files. - -@vindex rmail-decode-mime-charset - When you get new mail in Rmail, each message is translated -automatically from the coding system it is written in, as if it were a -separate file. This uses the priority list of coding systems that you -have specified. If a MIME message specifies a character set, Rmail -obeys that specification, unless @code{rmail-decode-mime-charset} is -@code{nil}. - -@vindex rmail-file-coding-system - For reading and saving Rmail files themselves, Emacs uses the coding -system specified by the variable @code{rmail-file-coding-system}. The -default value is @code{nil}, which means that Rmail files are not -translated (they are read and written in the Emacs internal character -code). - -@node Specify Coding -@section Specifying a File's Coding System - - If Emacs recognizes the encoding of a file incorrectly, you can -reread the file using the correct coding system by typing @kbd{C-x -@key{RET} r @var{coding-system} @key{RET}}. To see what coding system -Emacs actually used to decode the file, look at the coding system -mnemonic letter near the left edge of the mode line (@pxref{Mode -Line}), or type @kbd{C-h C @key{RET}}. - -@vindex coding - You can specify the coding system for a particular file in the file -itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning, -or a local variables list at the end (@pxref{File Variables}). You do -this by defining a value for the ``variable'' named @code{coding}. -Emacs does not really have a variable @code{coding}; instead of -setting a variable, this uses the specified coding system for the -file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies -use of the Latin-1 coding system, as well as C mode. When you specify -the coding explicitly in the file, that overrides -@code{file-coding-system-alist}. - - If you add the character @samp{!} at the end of the coding system -name in @code{coding}, it disables any character translation -(@pxref{Character Translation}) while decoding the file. This is -useful when you need to make sure that the character codes in the -Emacs buffer will not vary due to changes in user settings; for -instance, for the sake of strings in Emacs Lisp source files. - -@node Output Coding -@section Choosing Coding Systems for Output - -@vindex buffer-file-coding-system - Once Emacs has chosen a coding system for a buffer, it stores that -coding system in @code{buffer-file-coding-system}. That makes it the -default for operations that write from this buffer into a file, such -as @code{save-buffer} and @code{write-region}. You can specify a -different coding system for further file output from the buffer using -@code{set-buffer-file-coding-system} (@pxref{Text Coding}). - - You can insert any character Emacs supports into any Emacs buffer, -but most coding systems can only handle a subset of these characters. -Therefore, you can insert characters that cannot be encoded with the -coding system that will be used to save the buffer. For example, you -could start with an @acronym{ASCII} file and insert a few Latin-1 -characters into it, or you could edit a text file in Polish encoded in -@code{iso-8859-2} and add some Russian words to it. When you save -that buffer, Emacs cannot use the current value of -@code{buffer-file-coding-system}, because the characters you added -cannot be encoded by that coding system. - - When that happens, Emacs tries the most-preferred coding system (set -by @kbd{M-x prefer-coding-system} or @kbd{M-x -set-language-environment}), and if that coding system can safely -encode all of the characters in the buffer, Emacs uses it, and stores -its value in @code{buffer-file-coding-system}. Otherwise, Emacs -displays a list of coding systems suitable for encoding the buffer's -contents, and asks you to choose one of those coding systems. - - If you insert the unsuitable characters in a mail message, Emacs -behaves a bit differently. It additionally checks whether the -most-preferred coding system is recommended for use in MIME messages; -if not, Emacs tells you that the most-preferred coding system is not -recommended and prompts you for another coding system. This is so you -won't inadvertently send a message encoded in a way that your -recipient's mail software will have difficulty decoding. (You can -still use an unsuitable coding system if you type its name in response -to the question.) - -@vindex sendmail-coding-system - When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has -four different ways to determine the coding system to use for encoding -the message text. It tries the buffer's own value of -@code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise, -it uses the value of @code{sendmail-coding-system}, if that is -non-@code{nil}. The third way is to use the default coding system for -new files, which is controlled by your choice of language environment, -if that is non-@code{nil}. If all of these three values are @code{nil}, -Emacs encodes outgoing mail using the Latin-1 coding system. - -@node Text Coding -@section Specifying a Coding System for File Text - - In cases where Emacs does not automatically choose the right coding -system for a file's contents, you can use these commands to specify -one: - -@table @kbd -@item C-x @key{RET} f @var{coding} @key{RET} -Use coding system @var{coding} for saving or revisiting the visited -file in the current buffer. - -@item C-x @key{RET} c @var{coding} @key{RET} -Specify coding system @var{coding} for the immediately following -command. - -@item C-x @key{RET} r @var{coding} @key{RET} -Revisit the current file using the coding system @var{coding}. - -@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET} -Convert a region that was decoded using coding system @var{wrong}, -decoding it using coding system @var{right} instead. -@end table - -@kindex C-x RET f -@findex set-buffer-file-coding-system - The command @kbd{C-x @key{RET} f} -(@code{set-buffer-file-coding-system}) sets the file coding system for -the current buffer---in other words, it says which coding system to -use when saving or reverting the visited file. You specify which -coding system using the minibuffer. If you specify a coding system -that cannot handle all of the characters in the buffer, Emacs warns -you about the troublesome characters when you actually save the -buffer. - -@cindex specify end-of-line conversion - You can also use this command to specify the end-of-line conversion -(@pxref{Coding Systems, end-of-line conversion}) for encoding the -current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will -cause Emacs to save the current buffer's text with DOS-style CRLF line -endings. - -@kindex C-x RET c -@findex universal-coding-system-argument - Another way to specify the coding system for a file is when you visit -the file. First use the command @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}); this command uses the -minibuffer to read a coding system name. After you exit the minibuffer, -the specified coding system is used for @emph{the immediately following -command}. - - So if the immediately following command is @kbd{C-x C-f}, for example, -it reads the file using that coding system (and records the coding -system for when you later save the file). Or if the immediately following -command is @kbd{C-x C-w}, it writes the file using that coding system. -When you specify the coding system for saving in this way, instead -of with @kbd{C-x @key{RET} f}, there is no warning if the buffer -contains characters that the coding system cannot handle. - - Other file commands affected by a specified coding system include -@kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants -of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that -start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the -immediately following command does not use the coding system, then -@kbd{C-x @key{RET} c} ultimately has no effect. - - An easy way to visit a file with no conversion is with the @kbd{M-x -find-file-literally} command. @xref{Visiting}. - -@vindex default-buffer-file-coding-system - The variable @code{default-buffer-file-coding-system} specifies the -choice of coding system to use when you create a new file. It applies -when you find a new file, and when you create a buffer and then save it -in a file. Selecting a language environment typically sets this -variable to a good choice of default coding system for that language -environment. - -@kindex C-x RET r -@findex revert-buffer-with-coding-system - If you visit a file with a wrong coding system, you can correct this -with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}). -This visits the current file again, using a coding system you specify. - -@findex recode-region - If a piece of text has already been inserted into a buffer using the -wrong coding system, you can redo the decoding of it using @kbd{M-x -recode-region}. This prompts you for the proper coding system, then -for the wrong coding system that was actually used, and does the -conversion. It first encodes the region using the wrong coding system, -then decodes it again using the proper coding system. - -@node Communication Coding -@section Coding Systems for Interprocess Communication - - This section explains how to specify coding systems for use -in communication with other processes. - -@table @kbd -@item C-x @key{RET} x @var{coding} @key{RET} -Use coding system @var{coding} for transferring selections to and from -other window-based applications. - -@item C-x @key{RET} X @var{coding} @key{RET} -Use coding system @var{coding} for transferring @emph{one} -selection---the next one---to or from another window-based application. - -@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET} -Use coding systems @var{input-coding} and @var{output-coding} for -subprocess input and output in the current buffer. - -@item C-x @key{RET} c @var{coding} @key{RET} -Specify coding system @var{coding} for the immediately following -command. -@end table - -@kindex C-x RET x -@kindex C-x RET X -@findex set-selection-coding-system -@findex set-next-selection-coding-system - The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system}) -specifies the coding system for sending selected text to other windowing -applications, and for receiving the text of selections made in other -applications. This command applies to all subsequent selections, until -you override it by using the command again. The command @kbd{C-x -@key{RET} X} (@code{set-next-selection-coding-system}) specifies the -coding system for the next selection made in Emacs or read by Emacs. - -@kindex C-x RET p -@findex set-buffer-process-coding-system - The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system}) -specifies the coding system for input and output to a subprocess. This -command applies to the current buffer; normally, each subprocess has its -own buffer, and thus you can use this command to specify translation to -and from a particular subprocess by giving the command in the -corresponding buffer. - - You can also use @kbd{C-x @key{RET} c} just before the command that -runs or starts a subprocess, to specify the coding system to use for -communication with that subprocess. - - The default for translation of process input and output depends on the -current language environment. - -@vindex locale-coding-system -@cindex decoding non-@acronym{ASCII} keyboard input on X - The variable @code{locale-coding-system} specifies a coding system -to use when encoding and decoding system strings such as system error -messages and @code{format-time-string} formats and time stamps. That -coding system is also used for decoding non-@acronym{ASCII} keyboard input on X -Window systems. You should choose a coding system that is compatible -with the underlying system's text representation, which is normally -specified by one of the environment variables @env{LC_ALL}, -@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order -specified above, whose value is nonempty is the one that determines -the text representation.) - -@node File Name Coding -@section Coding Systems for File Names - -@table @kbd -@item C-x @key{RET} F @var{coding} @key{RET} -Use coding system @var{coding} for encoding and decoding file -@emph{names}. -@end table - -@vindex file-name-coding-system -@cindex file names with non-@acronym{ASCII} characters - The variable @code{file-name-coding-system} specifies a coding -system to use for encoding file names. It has no effect on reading -and writing the @emph{contents} of files. - -@findex set-file-name-coding-system -@kindex C-x @key{RET} F - If you set the variable to a coding system name (as a Lisp symbol or -a string), Emacs encodes file names using that coding system for all -file operations. This makes it possible to use non-@acronym{ASCII} -characters in file names---or, at least, those non-@acronym{ASCII} -characters which the specified coding system can encode. Use @kbd{C-x -@key{RET} F} (@code{set-file-name-coding-system}) to specify this -interactively. - - If @code{file-name-coding-system} is @code{nil}, Emacs uses a -default coding system determined by the selected language environment. -In the default language environment, any non-@acronym{ASCII} -characters in file names are not encoded specially; they appear in the -file system using the internal Emacs representation. - - @strong{Warning:} if you change @code{file-name-coding-system} (or the -language environment) in the middle of an Emacs session, problems can -result if you have already visited files whose names were encoded using -the earlier coding system and cannot be encoded (or are encoded -differently) under the new coding system. If you try to save one of -these buffers under the visited file name, saving may use the wrong file -name, or it may get an error. If such a problem happens, use @kbd{C-x -C-w} to specify a new file name for that buffer. - -@findex recode-file-name - If a mistake occurs when encoding a file name, use the command -@kbd{M-x recode-file-name} to change the file name's coding -system. This prompts for an existing file name, its old coding -system, and the coding system to which you wish to convert. - -@node Terminal Coding -@section Coding Systems for Terminal I/O - -@table @kbd -@item C-x @key{RET} k @var{coding} @key{RET} -Use coding system @var{coding} for keyboard input. - -@item C-x @key{RET} t @var{coding} @key{RET} -Use coding system @var{coding} for terminal output. -@end table - -@kindex C-x RET t -@findex set-terminal-coding-system - The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system}) -specifies the coding system for terminal output. If you specify a -character code for terminal output, all characters output to the -terminal are translated into that coding system. - - This feature is useful for certain character-only terminals built to -support specific languages or character sets---for example, European -terminals that support one of the ISO Latin character sets. You need to -specify the terminal coding system when using multibyte text, so that -Emacs knows which characters the terminal can actually handle. - - By default, output to the terminal is not translated at all, unless -Emacs can deduce the proper coding system from your terminal type or -your locale specification (@pxref{Language Environments}). - -@kindex C-x RET k -@findex set-keyboard-coding-system -@vindex keyboard-coding-system - The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}) -or the variable @code{keyboard-coding-system} specifies the coding -system for keyboard input. Character-code translation of keyboard -input is useful for terminals with keys that send non-@acronym{ASCII} -graphic characters---for example, some terminals designed for ISO -Latin-1 or subsets of it. - - By default, keyboard input is translated based on your system locale -setting. If your terminal does not really support the encoding -implied by your locale (for example, if you find it inserts a -non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set -@code{keyboard-coding-system} to @code{nil} to turn off encoding. -You can do this by putting - -@lisp -(set-keyboard-coding-system nil) -@end lisp - -@noindent -in your @file{~/.emacs} file. - - There is a similarity between using a coding system translation for -keyboard input, and using an input method: both define sequences of -keyboard input that translate into single characters. However, input -methods are designed to be convenient for interactive use by humans, and -the sequences that are translated are typically sequences of @acronym{ASCII} -printing characters. Coding systems typically translate sequences of -non-graphic characters. - -@node Fontsets -@section Fontsets -@cindex fontsets - - A font typically defines shapes for a single alphabet or script. -Therefore, displaying the entire range of scripts that Emacs supports -requires a collection of many fonts. In Emacs, such a collection is -called a @dfn{fontset}. A fontset is defined by a list of fonts, each -assigned to handle a range of character codes. - - Each fontset has a name, like a font. However, while fonts are -stored in the system and the available font names are defined by the -system, fontsets are defined within Emacs itself. Once you have -defined a fontset, you can use it within Emacs by specifying its name, -anywhere that you could use a single font. Of course, Emacs fontsets -can use only the fonts that the system supports; if certain characters -appear on the screen as hollow boxes, this means that the fontset in -use for them has no font for those characters.@footnote{The Emacs -installation instructions have information on additional font -support.} - - Emacs creates two fontsets automatically: the @dfn{standard fontset} -and the @dfn{startup fontset}. The standard fontset is most likely to -have fonts for a wide variety of non-@acronym{ASCII} characters; -however, this is not the default for Emacs to use. (By default, Emacs -tries to find a font that has bold and italic variants.) You can -specify use of the standard fontset with the @samp{-fn} option. For -example, - -@example -emacs -fn fontset-standard -@end example - -@noindent -You can also specify a fontset with the @samp{Font} resource (@pxref{X -Resources}). - - A fontset does not necessarily specify a font for every character -code. If a fontset specifies no font for a certain character, or if it -specifies a font that does not exist on your system, then it cannot -display that character properly. It will display that character as an -empty box instead. - -@node Defining Fontsets -@section Defining fontsets - -@vindex standard-fontset-spec -@cindex standard fontset - Emacs creates a standard fontset automatically according to the value -of @code{standard-fontset-spec}. This fontset's name is - -@example --*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard -@end example - -@noindent -or just @samp{fontset-standard} for short. - - Bold, italic, and bold-italic variants of the standard fontset are -created automatically. Their names have @samp{bold} instead of -@samp{medium}, or @samp{i} instead of @samp{r}, or both. - -@cindex startup fontset - If you specify a default @acronym{ASCII} font with the @samp{Font} resource or -the @samp{-fn} argument, Emacs generates a fontset from it -automatically. This is the @dfn{startup fontset} and its name is -@code{fontset-startup}. It does this by replacing the @var{foundry}, -@var{family}, @var{add_style}, and @var{average_width} fields of the -font name with @samp{*}, replacing @var{charset_registry} field with -@samp{fontset}, and replacing @var{charset_encoding} field with -@samp{startup}, then using the resulting string to specify a fontset. - - For instance, if you start Emacs this way, - -@example -emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1" -@end example - -@noindent -Emacs generates the following fontset and uses it for the initial X -window frame: - -@example --*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup -@end example - - With the X resource @samp{Emacs.Font}, you can specify a fontset name -just like an actual font name. But be careful not to specify a fontset -name in a wildcard resource like @samp{Emacs*Font}---that wildcard -specification matches various other resources, such as for menus, and -menus cannot handle fontsets. - - You can specify additional fontsets using X resources named -@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0. -The resource value should have this form: - -@smallexample -@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} -@end smallexample - -@noindent -@var{fontpattern} should have the form of a standard X font name, except -for the last two fields. They should have the form -@samp{fontset-@var{alias}}. - - The fontset has two names, one long and one short. The long name is -@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You -can refer to the fontset by either name. - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the -font to use for that character set. You can use this construct any -number of times in defining one fontset. - - For the other character sets, Emacs chooses a font based on -@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values -that describe the character set. For the @acronym{ASCII} character font, -@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not useful because it is -better to use the smaller font in its own size, which is what Emacs -does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as below: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@findex create-fontset-from-fontset-spec - The function that processes the fontset resource value to create the -fontset is called @code{create-fontset-from-fontset-spec}. You can also -call this function explicitly to create a fontset. - - @xref{Font X}, for more information about font naming in X. - -@node Undisplayable Characters -@section Undisplayable Characters - - There may be a some non-@acronym{ASCII} characters that your terminal cannot -display. Most text-only terminals support just a single character -set (use the variable @code{default-terminal-coding-system} -(@pxref{Terminal Coding}) to tell Emacs which one); characters which -can't be encoded in that coding system are displayed as @samp{?} by -default. - - Graphical displays can display a broader range of characters, but -you may not have fonts installed for all of them; characters that have -no font appear as a hollow box. - - If you use Latin-1 characters but your terminal can't display -Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences -instead, e.g.@: @samp{"o} for o-umlaut. Load the library -@file{iso-ascii} to do this. - -@vindex latin1-display - If your terminal can display Latin-1, you can display characters -from other European character sets using a mixture of equivalent -Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable -@code{latin1-display} to enable this. The mnemonic @acronym{ASCII} -sequences mostly correspond to those of the prefix input methods. - -@node Unibyte Mode -@section Unibyte Editing Mode - -@cindex European character sets -@cindex accented characters -@cindex ISO Latin character sets -@cindex Unibyte operation - The ISO 8859 Latin-@var{n} character sets define character codes in -the range 0240 to 0377 octal (160 to 255 decimal) to handle the -accented letters and punctuation needed by various European languages -(and some non-European ones). If you disable multibyte characters, -Emacs can still handle @emph{one} of these character codes at a time. -To specify @emph{which} of these codes to use, invoke @kbd{M-x -set-language-environment} and specify a suitable language environment -such as @samp{Latin-@var{n}}. - - For more information about unibyte operation, see @ref{Enabling -Multibyte}. Note particularly that you probably want to ensure that -your initialization files are read as unibyte if they contain -non-@acronym{ASCII} characters. - -@vindex unibyte-display-via-language-environment - Emacs can also display those characters, provided the terminal or font -in use supports them. This works automatically. Alternatively, on a -graphical display, Emacs can also display single-byte characters -through fontsets, in effect by displaying the equivalent multibyte -characters according to the current language environment. To request -this, set the variable @code{unibyte-display-via-language-environment} -to a non-@code{nil} value. - -@cindex @code{iso-ascii} library - If your terminal does not support display of the Latin-1 character -set, Emacs can display these characters as @acronym{ASCII} sequences which at -least give you a clear idea of what the characters are. To do this, -load the library @code{iso-ascii}. Similar libraries for other -Latin-@var{n} character sets could be implemented, but we don't have -them yet. - -@findex standard-display-8bit -@cindex 8-bit display - Normally non-ISO-8859 characters (decimal codes between 128 and 159 -inclusive) are displayed as octal escapes. You can change this for -non-standard ``extended'' versions of ISO-8859 character sets by using the -function @code{standard-display-8bit} in the @code{disp-table} library. - - There are two ways to input single-byte non-@acronym{ASCII} -characters: - -@itemize @bullet -@cindex 8-bit input -@item -You can use an input method for the selected language environment. -@xref{Input Methods}. When you use an input method in a unibyte buffer, -the non-@acronym{ASCII} character you specify with it is converted to unibyte. - -@item -If your keyboard can generate character codes 128 (decimal) and up, -representing non-@acronym{ASCII} characters, you can type those character codes -directly. - -On a graphical display, you should not need to do anything special to use -these keys; they should simply work. On a text-only terminal, you -should use the command @code{M-x set-keyboard-coding-system} or the -variable @code{keyboard-coding-system} to specify which coding system -your keyboard uses (@pxref{Terminal Coding}). Enabling this feature -will probably require you to use @kbd{ESC} to type Meta characters; -however, on a console terminal or in @code{xterm}, you can arrange for -Meta to be converted to @kbd{ESC} and still be able type 8-bit -characters present directly on the keyboard or using @kbd{Compose} or -@kbd{AltGr} keys. @xref{User Input}. - -@kindex C-x 8 -@cindex @code{iso-transl} library -@cindex compose character -@cindex dead character -@item -For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose -character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing -characters. @kbd{C-x 8} is good for insertion (in the minibuffer as -well as other buffers), for searching, and in any other context where -a key sequence is allowed. - -@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that -library is loaded, the @key{ALT} modifier key, if the keyboard has -one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together -with an accent character to modify the following letter. In addition, -if the keyboard has keys for the Latin-1 ``dead accent characters,'' -they too are defined to compose with the following character, once -@code{iso-transl} is loaded. - -Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations. -@end itemize - -@node Charsets -@section Charsets -@cindex charsets - - Emacs groups all supported characters into disjoint @dfn{charsets}. -Each character code belongs to one and only one charset. For -historical reasons, Emacs typically divides an 8-bit character code -for an extended version of @acronym{ASCII} into two charsets: -@acronym{ASCII}, which covers the codes 0 through 127, plus another -charset which covers the ``right-hand part'' (the codes 128 and up). -For instance, the characters of Latin-1 include the Emacs charset -@code{ascii} plus the Emacs charset @code{latin-iso8859-1}. - - Emacs characters belonging to different charsets may look the same, -but they are still different characters. For example, the letter -@samp{o} with acute accent in charset @code{latin-iso8859-1}, used for -Latin-1, is different from the letter @samp{o} with acute accent in -charset @code{latin-iso8859-2}, used for Latin-2. - -@findex list-charset-chars -@cindex characters in a certain charset -@findex describe-character-set - There are two commands for obtaining information about Emacs -charsets. The command @kbd{M-x list-charset-chars} prompts for a name -of a character set, and displays all the characters in that character -set. The command @kbd{M-x describe-character-set} prompts for a -charset name and displays information about that charset, including -its internal representation within Emacs. - - To find out which charset a character in the buffer belongs to, -put point before it and type @kbd{C-u C-x =}. - -@ignore - arch-tag: 310ba60d-31ef-4ce7-91f1-f282dd57b6b3 -@end ignore diff --git a/man/newsticker.texi b/man/newsticker.texi deleted file mode 100644 index 48d7f992667..00000000000 --- a/man/newsticker.texi +++ /dev/null @@ -1,290 +0,0 @@ -\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/man/org.texi b/man/org.texi deleted file mode 100644 index f3b13511571..00000000000 --- a/man/org.texi +++ /dev/null @@ -1,7931 +0,0 @@ -\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/man/pcl-cvs.texi b/man/pcl-cvs.texi deleted file mode 100644 index 93bd54eb456..00000000000 --- a/man/pcl-cvs.texi +++ /dev/null @@ -1,1443 +0,0 @@ -\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/man/pgg.texi b/man/pgg.texi deleted file mode 100644 index 6a175db4cb9..00000000000 --- a/man/pgg.texi +++ /dev/null @@ -1,498 +0,0 @@ -\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/man/picture-xtra.texi b/man/picture-xtra.texi deleted file mode 100644 index ad3b9f27cc5..00000000000 --- a/man/picture-xtra.texi +++ /dev/null @@ -1,291 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Picture Mode -@chapter Editing Pictures -@cindex pictures -@cindex making pictures out of text characters -@findex edit-picture - - To edit a picture made out of text characters (for example, a picture -of the division of a register into fields, as a comment in a program), -use the command @kbd{M-x edit-picture} to enter Picture mode. - - In Picture mode, editing is based on the @dfn{quarter-plane} model of -text, according to which the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the end -of a line does not exist in this model; the most you can say is where the -last nonblank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But Picture mode replaces -the most frequently-used commands with variants that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture mode -to do essentially the same thing but in a quarter-plane way. In addition, -Picture mode defines various keys starting with the @kbd{C-c} prefix to -run special picture editing commands. - - One of these keys, @kbd{C-c C-c}, is particularly important. Often a -picture is part of a larger file that is usually edited in some other -major mode. @kbd{M-x edit-picture} records the name of the previous -major mode so you can use the @kbd{C-c C-c} command -(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c C-c} -also deletes spaces from the ends of lines, unless given a numeric -argument. - - The special commands of Picture mode all work in other modes (provided -the @file{picture} library is loaded), but are not bound to keys except -in Picture mode. The descriptions below talk of moving ``one column'' -and so on, but all the picture mode commands handle numeric arguments as -their normal equivalents do. - -@vindex picture-mode-hook - Turning on Picture mode runs the hook @code{picture-mode-hook}. -Additional extensions to Picture mode can be found in -@file{artist.el}. - -@menu -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end menu - -@node Basic Picture -@section Basic Editing in Picture Mode - -@findex picture-forward-column -@findex picture-backward-column -@findex picture-move-down -@findex picture-move-up -@cindex editing in Picture mode - - Most keys do the same thing in Picture mode that they usually do, but -do it in a quarter-plane style. For example, @kbd{C-f} is rebound to -run @code{picture-forward-column}, a command which moves point one -column to the right, inserting a space if necessary so that the actual -end of the line makes no difference. @kbd{C-b} is rebound to run -@code{picture-backward-column}, which always moves point left one -column, converting a tab to multiple spaces if necessary. @kbd{C-n} and -@kbd{C-p} are rebound to run @code{picture-move-down} and -@code{picture-move-up}, which can either insert spaces or convert tabs -as necessary to make sure that point stays in exactly the same column. -@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last -nonblank character on the line. There is no need to change @kbd{C-a}, -as the choice of screen model does not affect beginnings of -lines. - -@findex picture-newline - Insertion of text is adapted to the quarter-plane screen model -through the use of Overwrite mode -@iftex -(@pxref{Minor Modes,,, emacs, the Emacs Manual}.) -@end iftex -@ifnottex -(@pxref{Minor Modes}.) -@end ifnottex -Self-inserting characters replace existing text, column by column, -rather than pushing existing text to the right. @key{RET} runs -@code{picture-newline}, which just moves to the beginning of the -following line so that new text will replace that line. - -@findex picture-backward-clear-column -@findex picture-clear-column -@findex picture-clear-line - In Picture mode, the commands that normally delete or kill text, -instead erase text (replacing it with spaces). @key{DEL} -(@code{picture-backward-clear-column}) replaces the preceding -character with a space rather than removing it; this moves point -backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next -character or characters with spaces, but does not move point. (If you -want to clear characters to spaces and move forward over them, use -@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the -contents of lines, but does not delete the newlines from the buffer. - -@findex picture-open-line - To do actual insertion, you must use special commands. @kbd{C-o} -(@code{picture-open-line}) creates a blank line after the current -line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes -sense in Picture mode, so it is not changed. @kbd{C-j} -(@code{picture-duplicate-line}) inserts another line with the same -contents below the current line. - -@kindex C-c C-d @r{(Picture mode)} - To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} -(which is defined as @code{delete-char}, as @kbd{C-d} is in other -modes), or one of the picture rectangle commands (@pxref{Rectangles in -Picture}). - -@node Insert in Picture -@section Controlling Motion after Insert - -@findex picture-movement-up -@findex picture-movement-down -@findex picture-movement-left -@findex picture-movement-right -@findex picture-movement-nw -@findex picture-movement-ne -@findex picture-movement-sw -@findex picture-movement-se -@kindex C-c < @r{(Picture mode)} -@kindex C-c > @r{(Picture mode)} -@kindex C-c ^ @r{(Picture mode)} -@kindex C-c . @r{(Picture mode)} -@kindex C-c ` @r{(Picture mode)} -@kindex C-c ' @r{(Picture mode)} -@kindex C-c / @r{(Picture mode)} -@kindex C-c \ @r{(Picture mode)} - Since ``self-inserting'' characters in Picture mode overwrite and move -point, there is no essential restriction on how point should be moved. -Normally point moves right, but you can specify any of the eight -orthogonal or diagonal directions for motion after a ``self-inserting'' -character. This is useful for drawing lines in the buffer. - -@table @kbd -@item C-c < -@itemx C-c @key{LEFT} -Move left after insertion (@code{picture-movement-left}). -@item C-c > -@itemx C-c @key{RIGHT} -Move right after insertion (@code{picture-movement-right}). -@item C-c ^ -@itemx C-c @key{UP} -Move up after insertion (@code{picture-movement-up}). -@item C-c . -@itemx C-c @key{DOWN} -Move down after insertion (@code{picture-movement-down}). -@item C-c ` -@itemx C-c @key{HOME} -Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). -@item C-c ' -@itemx C-c @key{PAGEUP} -Move up and right (``northeast'') after insertion -(@code{picture-movement-ne}). -@item C-c / -@itemx C-c @key{END} -Move down and left (``southwest'') after insertion -@*(@code{picture-movement-sw}). -@item C-c \ -@itemx C-c @key{PAGEDOWN} -Move down and right (``southeast'') after insertion -@*(@code{picture-movement-se}). -@end table - -@kindex C-c C-f @r{(Picture mode)} -@kindex C-c C-b @r{(Picture mode)} -@findex picture-motion -@findex picture-motion-reverse - Two motion commands move based on the current Picture insertion -direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the -same direction as motion after ``insertion'' currently does, while @kbd{C-c -C-b} (@code{picture-motion-reverse}) moves in the opposite direction. - -@node Tabs in Picture -@section Picture Mode Tabs - -@kindex M-TAB @r{(Picture mode)} -@findex picture-tab-search -@vindex picture-tab-chars - Two kinds of tab-like action are provided in Picture mode. Use -@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. -With no argument, it moves to a point underneath the next -``interesting'' character that follows whitespace in the previous -nonblank line. ``Next'' here means ``appearing at a horizontal position -greater than the one point starts out at.'' With an argument, as in -@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting -character in the current line. @kbd{M-@key{TAB}} does not change the -text; it only moves point. ``Interesting'' characters are defined by -the variable @code{picture-tab-chars}, which should define a set of -characters. The syntax for this variable is like the syntax used inside -of @samp{[@dots{}]} in a regular expression---but without the @samp{[} -and the @samp{]}. Its default value is @code{"!-~"}. - -@findex picture-tab - @key{TAB} itself runs @code{picture-tab}, which operates based on the -current tab stop settings; it is the Picture mode equivalent of -@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric -argument it clears the text that it moves over. - -@kindex C-c TAB @r{(Picture mode)} -@findex picture-set-tab-stops - The context-based and tab-stop-based forms of tabbing are brought -together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). -This command sets the tab stops to the positions which @kbd{M-@key{TAB}} -would consider significant in the current line. The use of this command, -together with @key{TAB}, can get the effect of context-based tabbing. But -@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. - - It may be convenient to prevent use of actual tab characters in -pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing -up the picture. You can do this by setting the variable -@code{indent-tabs-mode} to @code{nil}. - -@node Rectangles in Picture -@section Picture Mode Rectangle Commands -@cindex rectangles and Picture mode -@cindex Picture mode and rectangles - - Picture mode defines commands for working on rectangular pieces of -the text in ways that fit with the quarter-plane model. The standard -rectangle commands may also be useful. -@iftex -@xref{Rectangles,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Rectangles}. -@end ifnottex - -@table @kbd -@item C-c C-k -Clear out the region-rectangle with spaces -(@code{picture-clear-rectangle}). With argument, delete the text. -@item C-c C-w @var{r} -Similar, but save rectangle contents in register @var{r} first -(@code{picture-clear-rectangle-to-register}). -@item C-c C-y -Copy last killed rectangle into the buffer by overwriting, with upper -left corner at point (@code{picture-yank-rectangle}). With argument, -insert instead. -@item C-c C-x @var{r} -Similar, but use the rectangle in register @var{r} -(@code{picture-yank-rectangle-from-register}). -@end table - -@kindex C-c C-k @r{(Picture mode)} -@kindex C-c C-w @r{(Picture mode)} -@findex picture-clear-rectangle -@findex picture-clear-rectangle-to-register - The picture rectangle commands @kbd{C-c C-k} -(@code{picture-clear-rectangle}) and @kbd{C-c C-w} -(@code{picture-clear-rectangle-to-register}) differ from the standard -rectangle commands in that they normally clear the rectangle instead of -deleting it; this is analogous with the way @kbd{C-d} is changed in Picture -mode. - - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. -@kbd{C-c C-k} either with or without a numeric argument saves the -rectangle for @kbd{C-c C-y}. - -@kindex C-c C-y @r{(Picture mode)} -@kindex C-c C-x @r{(Picture mode)} -@findex picture-yank-rectangle -@findex picture-yank-rectangle-from-register - The Picture mode commands for yanking rectangles differ from the -standard ones in that they overwrite instead of inserting. This is -the same way that Picture mode insertion of other text differs from -other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts -(by overwriting) the rectangle that was most recently killed, while -@kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does -likewise for the rectangle found in a specified register. - -@ignore - arch-tag: 10e423ad-d896-42f2-a7e8-7018adeaf8c2 -@end ignore diff --git a/man/programs.texi b/man/programs.texi deleted file mode 100644 index 2472d7daabe..00000000000 --- a/man/programs.texi +++ /dev/null @@ -1,1773 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Programs, Building, Text, Top -@chapter Editing Programs -@cindex Lisp editing -@cindex C editing -@cindex program editing - - Emacs provides many features to facilitate editing programs. Some -of these features can - -@itemize @bullet -@item -Find or move over top-level definitions (@pxref{Defuns}). -@item -Apply the usual indentation conventions of the language -(@pxref{Program Indent}). -@item -Balance parentheses (@pxref{Parentheses}). -@item -Insert, kill or align comments (@pxref{Comments}). -@item -Highlight program syntax (@pxref{Font Lock}). -@end itemize - - This chapter describes these features and many more. - -@menu -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, and Pike modes. -* Asm Mode:: Asm mode and its special features. -@ifnottex -* Fortran:: Fortran mode and its special features. -@end ifnottex -@end menu - -@node Program Modes -@section Major Modes for Programming Languages -@cindex modes for programming languages - - Emacs has specialized major modes for various programming languages. -@xref{Major Modes}. A programming language major mode typically -specifies the syntax of expressions, the customary rules for -indentation, how to do syntax highlighting for the language, and how -to find the beginning of a function definition. It often customizes -or provides facilities for compiling and debugging programs as well. - - Ideally, Emacs should provide a major mode for each programming -language that you might want to edit; if it doesn't have a mode for -your favorite language, you can contribute one. But often the mode -for one language can serve for other syntactically similar languages. -The major mode for language @var{l} is called @code{@var{l}-mode}, -and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. -@xref{Choosing Modes}. - -@cindex Perl mode -@cindex Icon mode -@cindex Makefile mode -@cindex Tcl mode -@cindex CPerl mode -@cindex DSSSL mode -@cindex Octave mode -@cindex Metafont mode -@cindex Modula2 mode -@cindex Prolog mode -@cindex Python mode -@cindex Simula mode -@cindex VHDL mode -@cindex M4 mode -@cindex Shell-script mode -@cindex Delphi mode -@cindex PostScript mode -@cindex Conf mode -@cindex DNS mode - The existing programming language major modes include Lisp, Scheme (a -variant of Lisp) and the Scheme-based DSSSL expression language, Ada, -ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed -format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s -companion for font creation), Modula2, Objective-C, Octave, Pascal, -Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An -alternative mode for Perl is called CPerl mode. Modes are available for -the scripting languages of the common GNU and Unix shells, VMS DCL, and -MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for -editing makefiles, DNS master files, and various sorts of configuration -files. - -@kindex DEL @r{(programming modes)} -@findex c-electric-backspace - In most programming languages, indentation should vary from line to -line to illustrate the structure of the program. So the major modes -for programming languages arrange for @key{TAB} to update the -indentation of the current line. They also rebind @key{DEL} to treat -a tab as if it were the equivalent number of spaces; this lets you -delete one column of indentation without worrying whether the -whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a -tab character before point, in these modes. - - Separate manuals are available for the modes for Ada (@pxref{Top, , Ada -Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK -(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes -(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran -mode, see -@iftex -@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@ref{Fortran}. -@end ifnottex - - -@cindex mode hook -@vindex c-mode-hook -@vindex lisp-mode-hook -@vindex emacs-lisp-mode-hook -@vindex lisp-interaction-mode-hook -@vindex scheme-mode-hook - Turning on a major mode runs a normal hook called the @dfn{mode -hook}, which is the value of a Lisp variable. Each major mode has a -mode hook, and the hook's name is always made from the mode command's -name by adding @samp{-hook}. For example, turning on C mode runs the -hook @code{c-mode-hook}, while turning on Lisp mode runs the hook -@code{lisp-mode-hook}. The purpose of the mode hook is to give you a -place to set up customizations for that major mode. @xref{Hooks}. - -@node Defuns -@section Top-Level Definitions, or Defuns - - In Emacs, a major definition at the top level in the buffer, -something like a function, is called a @dfn{defun}. The name comes -from Lisp, but in Emacs we use it for all languages. - -@menu -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. -@end menu - -@node Left Margin Paren -@subsection Left Margin Convention - -@cindex open-parenthesis in leftmost column -@cindex ( in leftmost column - Emacs assumes by default that any opening delimiter found at the -left margin is the start of a top-level definition, or defun. -Therefore, @strong{don't put an opening delimiter at the left margin -unless it should have that significance}. For instance, never put an -open-parenthesis at the left margin in a Lisp file unless it is the -start of a top-level list. - - If you don't follow this convention, not only will you have trouble -when you explicitly use the commands for motion by defuns; other -features that use them will also give you trouble. This includes -the indentation commands (@pxref{Program Indent}) and Font Lock -mode (@pxref{Font Lock}). - - The most likely problem case is when you want an opening delimiter -at the start of a line inside a string. To avoid trouble, put an -escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some -other Lisp dialects) before the opening delimiter. This will not -affect the contents of the string, but will prevent that opening -delimiter from starting a defun. Here's an example: - -@example - (insert "Foo: -\(bar) -") -@end example - - To help you catch violations of this convention, Font Lock mode -highlights confusing opening delimiters (those that ought to be -quoted) in bold red. - -If you need to override this convention, you can so by setting this -user option: - -@defvar open-paren-in-column-0-is-defun-start -If this user option is set to @code{t} (the default), opening -parentheses or braces at column zero always start defuns. When it's -@code{nil}, defuns are found by searching for parens or braces at the -outermost level. -@end defvar - - Usually, you shouldn't need to set -@code{open-paren-in-column-0-is-defun-start} to @code{nil}. However, -if your buffer contains parentheses or braces in column zero which -don't start defuns and this confuses Emacs, it sometimes helps to set -the option to @code{nil}. Be aware, though, that this will make -scrolling and display in large buffers quite sluggish, and that -parentheses and braces must be correctly matched throughout the buffer -for it to work properly. - - In the earliest days, the original Emacs found defuns by moving -upward a level of parentheses or braces until there were no more -levels to go up. This always required scanning all the way back to -the beginning of the buffer, even for a small function. To speed up -the operation, we changed Emacs to assume that any opening delimiter -at the left margin is the start of a defun. This heuristic is nearly -always right, and avoids the need to scan back to the beginning of the -buffer. However, now that modern computers are so powerful, this -scanning is rarely slow enough to annoy, so we've provided a way to -disable the heuristic. - -@node Moving by Defuns -@subsection Moving by Defuns -@cindex defuns - - These commands move point or set up the region based on top-level -major definitions, also called @dfn{defuns}. - -@table @kbd -@item C-M-a -Move to beginning of current or preceding defun -(@code{beginning-of-defun}). -@item C-M-e -Move to end of current or following defun (@code{end-of-defun}). -@item C-M-h -Put region around whole current or following defun (@code{mark-defun}). -@end table - -@cindex move to beginning or end of function -@cindex function, move to beginning or end -@kindex C-M-a -@kindex C-M-e -@kindex C-M-h -@findex beginning-of-defun -@findex end-of-defun -@findex mark-defun - The commands to move to the beginning and end of the current defun -are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} -(@code{end-of-defun}). If you repeat one of these commands, or use a -positive numeric argument, each repetition moves to the next defun in -the direction of motion. - - @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward -@var{n} times to the next beginning of a defun. This is not exactly -the same place that @kbd{C-M-e} with argument @var{n} would move to; -the end of this defun is not usually exactly the same place as the -beginning of the following defun. (Whitespace, comments, and perhaps -declarations can separate them.) Likewise, @kbd{C-M-e} with a -negative argument moves back to an end of a defun, which is not quite -the same as @kbd{C-M-a} with a positive argument. - -@kindex C-M-h @r{(C mode)} -@findex c-mark-function - To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun}) -which puts point at the beginning and mark at the end of the current -defun. This is the easiest way to get ready to kill the defun in -order to move it to a different place in the file. If you use the -command while point is between defuns, it uses the following defun. -Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode -when the mark is active, extends the end of the region to include one -more defun each time. - - In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, -which is almost the same as @code{mark-defun}; the difference is that -it backs up over the argument declarations, function name and returned -data type so that the entire C function is inside the region. This is -an example of how major modes adjust the standard key bindings so that -they do their standard jobs in a way better fitting a particular -language. Other major modes may replace any or all of these key -bindings for that purpose. - -@node Imenu -@subsection Imenu -@cindex index of buffer definitions -@cindex buffer definitions index -@cindex tags - - The Imenu facility offers a way to find the major definitions in -a file by name. It is also useful in text formatter major modes, -where it treats each chapter, section, etc., as a definition. -(@xref{Tags}, for a more powerful feature that handles multiple files -together.) - -@findex imenu - If you type @kbd{M-x imenu}, it reads the name of a definition using -the minibuffer, then moves point to that definition. You can use -completion to specify the name; the command always displays the whole -list of valid names. - -@findex imenu-add-menubar-index - Alternatively, you can bind the command @code{imenu} to a mouse -click. Then it displays mouse menus for you to select a definition -name. You can also add the buffer's index to the menu bar by calling -@code{imenu-add-menubar-index}. If you want to have this menu bar -item available for all buffers in a certain major mode, you can do -this by adding @code{imenu-add-menubar-index} to its mode hook. But -if you have done that, you will have to wait a little while each time -you visit a file in that mode, while Emacs finds all the definitions -in that buffer. - -@vindex imenu-auto-rescan - When you change the contents of a buffer, if you add or delete -definitions, you can update the buffer's index based on the -new contents by invoking the @samp{*Rescan*} item in the menu. -Rescanning happens automatically if you set @code{imenu-auto-rescan} to -a non-@code{nil} value. There is no need to rescan because of small -changes in the text. - -@vindex imenu-sort-function - You can customize the way the menus are sorted by setting the -variable @code{imenu-sort-function}. By default, names are ordered as -they occur in the buffer; if you want alphabetic sorting, use the -symbol @code{imenu--sort-by-name} as the value. You can also -define your own comparison function by writing Lisp code. - - Imenu provides the information to guide Which Function mode -@ifnottex -(@pxref{Which Function}). -@end ifnottex -@iftex -(see below). -@end iftex -The Speedbar can also use it (@pxref{Speedbar}). - -@node Which Function -@subsection Which Function Mode -@cindex current function name in mode line - - Which Function mode is a minor mode that displays the current -function name in the mode line, updating it as you move around in a -buffer. - -@findex which-function-mode -@vindex which-func-modes - To either enable or disable Which Function mode, use the command -@kbd{M-x which-function-mode}. This command is global; it applies to -all buffers, both existing ones and those yet to be created. However, -it takes effect only in certain major modes, those listed in the value -of @code{which-func-modes}. If the value is @code{t}, then Which -Function mode applies to all major modes that know how to support -it---in other words, all the major modes that support Imenu. - -@node Program Indent -@section Indentation for Programs -@cindex indentation for programs - - The best way to keep a program properly indented is to use Emacs to -reindent it as you change it. Emacs has commands to indent properly -either a single line, a specified number of lines, or all of the lines -inside a single parenthetical grouping. - -@menu -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. -@end menu - -@cindex pretty-printer - Emacs also provides a Lisp pretty-printer in the library @code{pp}. -This program reformats a Lisp object with indentation chosen to look nice. - -@node Basic Indent -@subsection Basic Program Indentation Commands - - The basic indentation commands indent a single line according to the -usual conventions of the language you are editing. - -@need 1000 -@table @kbd -@item @key{TAB} -Adjust indentation of current line. -@item C-j -Insert a newline, then adjust indentation of following line -(@code{newline-and-indent}). -@end table - -@kindex TAB @r{(programming modes)} -@findex c-indent-command -@findex indent-line-function -@findex indent-for-tab-command - The basic indentation command is @key{TAB}, which gives the current line -the correct indentation as determined from the previous lines. The -function that @key{TAB} runs depends on the major mode; it is -@code{lisp-indent-line} -in Lisp mode, @code{c-indent-command} in C mode, etc. These functions -understand the syntax and conventions of different languages, but they all do -conceptually the same job: @key{TAB} in any programming-language major mode -inserts or deletes whitespace at the beginning of the current line, -independent of where point is in the line. If point was inside the -whitespace at the beginning of the line, @key{TAB} puts it at the end of -that whitespace; otherwise, @key{TAB} keeps point fixed with respect to -the characters around it. - - Use @kbd{C-q @key{TAB}} to insert a tab character at point. - -@kindex C-j -@findex newline-and-indent - When entering lines of new code, use @kbd{C-j} -(@code{newline-and-indent}), which inserts a newline and then adjusts -indentation after it. (It also deletes any trailing whitespace which -remains before the new newline.) Thus, @kbd{C-j} at the end of a line -creates a blank line with appropriate indentation. In programming -language modes, it is equivalent to @key{RET} @key{TAB}. - - @key{TAB} indents a line that starts within a parenthetical grouping -under the preceding line within the grouping, or the text after the -parenthesis. Therefore, if you manually give one of these lines a -nonstandard indentation, the lines below will tend to follow it. This -behavior is convenient in cases where you have overridden the standard -result of @key{TAB} because you find it unaesthetic for a particular -line. - - In some modes, an open-parenthesis, open-brace or other opening -delimiter at the left margin is assumed by Emacs (including the -indentation routines) to be the start of a function. This speeds up -indentation commands. If you will be editing text which contains -opening delimiters in column zero that aren't the beginning of a -functions, even inside strings or comments, you must set -@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin -Paren}, for more information on this. - - Normally, lines are indented with tabs and spaces. If you want Emacs -to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}). - -@node Multi-line Indent -@subsection Indenting Several Lines - - When you wish to reindent several lines of code which have been -altered or moved to a different level in the parenthesis structure, -you have several commands available. - -@table @kbd -@item C-M-q -Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}). -@item C-M-\ -Reindent all lines in the region (@code{indent-region}). -@item C-u @key{TAB} -Shift an entire parenthetical grouping rigidly sideways so that its -first line is properly indented. -@item M-x indent-code-rigidly -Shift all the lines in the region rigidly sideways, but do not alter -lines that start inside comments and strings. -@end table - -@kindex C-M-q -@findex indent-pp-sexp - You can reindent the contents of a single parenthetical grouping by -positioning point before the beginning of it and typing @kbd{C-M-q} -(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also -bound to other suitable commands in other modes). The indentation of -the line where the grouping starts is not changed; therefore this -changes only the relative indentation within the grouping, not its -overall indentation. To correct that as well, type @key{TAB} first. - - Another way to specify the range to be reindented is with the -region. The command @kbd{C-M-\} (@code{indent-region}) applies -@key{TAB} to every line whose first character is between point and -mark. - -@kindex C-u TAB - If you like the relative indentation within a grouping, but not the -indentation of its first line, you can type @kbd{C-u @key{TAB}} to -reindent the whole grouping as a rigid unit. (This works in Lisp -modes and C and related modes.) @key{TAB} with a numeric argument -reindents the current line as usual, then reindents by the same amount -all the lines in the parenthetical grouping starting on the current -line. It is clever, though, and does not alter lines that start -inside strings. Neither does it alter C preprocessor lines when in C -mode, but it does reindent any continuation lines that may be attached -to them. - -@findex indent-code-rigidly - You can also perform this operation on the region, using the command -@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the -region sideways, like @code{indent-rigidly} does (@pxref{Indentation -Commands}). It doesn't alter the indentation of lines that start -inside a string, unless the region also starts inside that string. -The prefix arg specifies the number of columns to indent. - -@node Lisp Indent -@subsection Customizing Lisp Indentation -@cindex customizing Lisp indentation - - The indentation pattern for a Lisp expression can depend on the function -called by the expression. For each Lisp function, you can choose among -several predefined patterns of indentation, or define an arbitrary one with -a Lisp program. - - The standard pattern of indentation is as follows: the second line of the -expression is indented under the first argument, if that is on the same -line as the beginning of the expression; otherwise, the second line is -indented underneath the function name. Each following line is indented -under the previous line whose nesting depth is the same. - -@vindex lisp-indent-offset - If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides -the usual indentation pattern for the second line of an expression, so that -such lines are always indented @code{lisp-indent-offset} more columns than -the containing list. - -@vindex lisp-body-indent - Certain functions override the standard pattern. Functions whose -names start with @code{def} treat the second lines as the start of -a @dfn{body}, by indenting the second line @code{lisp-body-indent} -additional columns beyond the open-parenthesis that starts the -expression. - -@cindex @code{lisp-indent-function} property - You can override the standard pattern in various ways for individual -functions, according to the @code{lisp-indent-function} property of -the function name. Normally you would use this for macro definitions -and specify it using the @code{declare} construct (@pxref{Defining -Macros,,, elisp, the Emacs Lisp Reference Manual}). - -@node C Indent -@subsection Commands for C Indentation - - Here are special features for indentation in C mode and related modes: - -@table @code -@item C-c C-q -@kindex C-c C-q @r{(C mode)} -@findex c-indent-defun -Reindent the current top-level function definition or aggregate type -declaration (@code{c-indent-defun}). - -@item C-M-q -@kindex C-M-q @r{(C mode)} -@findex c-indent-exp -Reindent each line in the balanced expression that follows point -(@code{c-indent-exp}). A prefix argument inhibits warning messages -about invalid syntax. - -@item @key{TAB} -@findex c-indent-command -Reindent the current line, and/or in some cases insert a tab character -(@code{c-indent-command}). - -@vindex c-tab-always-indent -If @code{c-tab-always-indent} is @code{t}, this command always reindents -the current line and does nothing else. This is the default. - -If that variable is @code{nil}, this command reindents the current line -only if point is at the left margin or in the line's indentation; -otherwise, it inserts a tab (or the equivalent number of spaces, -if @code{indent-tabs-mode} is @code{nil}). - -Any other value (not @code{nil} or @code{t}) means always reindent the -line, and also insert a tab if within a comment or a string. -@end table - - To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This -first selects the whole buffer as the region, then reindents that -region. - - To reindent the current block, use @kbd{C-M-u C-M-q}. This moves -to the front of the block and then reindents it all. - -@node Custom C Indent -@subsection Customizing C Indentation -@cindex style (for indentation) - - C mode and related modes use a flexible mechanism for customizing -indentation. C mode indents a source line in two steps: first it -classifies the line syntactically according to its contents and -context; second, it determines the indentation offset associated by -your selected @dfn{style} with the syntactic construct and adds this -onto the indentation of the @dfn{anchor statement}. - -@table @kbd -@item C-c . @key{RET} @var{style} @key{RET} -Select a predefined style @var{style} (@code{c-set-style}). -@end table - - A @dfn{style} is a named collection of customizations that can be -used in C mode and the related modes. @ref{Styles,,, ccmode, The CC -Mode Manual}, for a complete description. Emacs comes with several -predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, -@code{stroustrup}, @code{linux}, @code{python}, @code{java}, -@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these -styles are primarily intended for one language, but any of them can be -used with any of the languages supported by these modes. To find out -what a style looks like, select it and reindent some code, e.g., by -typing @key{C-M-q} at the start of a function definition. - -@kindex C-c . @r{(C mode)} -@findex c-set-style - To choose a style for the current buffer, use the command @w{@kbd{C-c -.}}. Specify a style name as an argument (case is not significant). -This command affects the current buffer only, and it affects only -future invocations of the indentation commands; it does not reindent -the code already in the buffer. To reindent the whole buffer in the -new style, you can type @kbd{C-x h C-M-\}. - -@vindex c-default-style - You can also set the variable @code{c-default-style} to specify the -default style for various major modes. Its value should be either the -style's name (a string) or an alist, in which each element specifies -one major mode and which indentation style to use for it. For -example, - -@example -(setq c-default-style - '((java-mode . "java") (awk-mode . "awk") (other . "gnu"))) -@end example - -@noindent -specifies explicit choices for Java and AWK modes, and the default -@samp{gnu} style for the other C-like modes. (These settings are -actually the defaults.) This variable takes effect when you select -one of the C-like major modes; thus, if you specify a new default -style for Java mode, you can make it take effect in an existing Java -mode buffer by typing @kbd{M-x java-mode} there. - - The @code{gnu} style specifies the formatting recommended by the GNU -Project for C; it is the default, so as to encourage use of our -recommended style. - - @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and -@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more -information on customizing indentation for C and related modes, -including how to override parts of an existing style and how to define -your own styles. - -@node Parentheses -@section Commands for Editing with Parentheses - -@findex check-parens -@cindex unbalanced parentheses and quotes - This section describes the commands and features that take advantage -of the parenthesis structure in a program, or help you keep it -balanced. - - When talking about these facilities, the term ``parenthesis'' also -includes braces, brackets, or whatever delimiters are defined to match -in pairs. The major mode controls which delimiters are significant, -through the syntax table (@pxref{Syntax}). In Lisp, only parentheses -count; in C, these commands apply to braces and brackets too. - - You can use @kbd{M-x check-parens} to find any unbalanced -parentheses and unbalanced string quotes in the buffer. - -@menu -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. -@end menu - -@node Expressions -@subsection Expressions with Balanced Parentheses - -@cindex sexp -@cindex expression -@cindex balanced expression - These commands deal with balanced expressions, also called -@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an -expression in Lisp.}. - -@table @kbd -@item C-M-f -Move forward over a balanced expression (@code{forward-sexp}). -@item C-M-b -Move backward over a balanced expression (@code{backward-sexp}). -@item C-M-k -Kill balanced expression forward (@code{kill-sexp}). -@item C-M-t -Transpose expressions (@code{transpose-sexps}). -@item C-M-@@ -@itemx C-M-@key{SPC} -Put mark after following expression (@code{mark-sexp}). -@end table - - Each programming language major mode customizes the definition of -balanced expressions to suit that language. Balanced expressions -typically include symbols, numbers, and string constants, as well as -any pair of matching delimiters and their contents. Some languages -have obscure forms of expression syntax that nobody has bothered to -implement in Emacs. - -@cindex Control-Meta - By convention, the keys for these commands are all Control-Meta -characters. They usually act on expressions just as the corresponding -Meta characters act on words. For instance, the command @kbd{C-M-b} -moves backward over a balanced expression, just as @kbd{M-b} moves -back over a word. - -@kindex C-M-f -@kindex C-M-b -@findex forward-sexp -@findex backward-sexp - To move forward over a balanced expression, use @kbd{C-M-f} -(@code{forward-sexp}). If the first significant character after point -is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or -@samp{@{} in C), @kbd{C-M-f} moves past the matching closing -delimiter. If the character begins a symbol, string, or number, -@kbd{C-M-f} moves over that. - - The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a -balanced expression. The detailed rules are like those above for -@kbd{C-M-f}, but with directions reversed. If there are prefix -characters (single-quote, backquote and comma, in Lisp) preceding the -expression, @kbd{C-M-b} moves back over them as well. The balanced -expression commands move across comments as if they were whitespace, -in most modes. - - @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the -specified number of times; with a negative argument, it moves in the -opposite direction. - -@cindex killing expressions -@kindex C-M-k -@findex kill-sexp - Killing a whole balanced expression can be done with @kbd{C-M-k} -(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} -would move over. - -@cindex transposition of expressions -@kindex C-M-t -@findex transpose-sexps - A somewhat random-sounding command which is nevertheless handy is -@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous -balanced expression across the next one. An argument serves as a -repeat count, moving the previous expression over that many following -ones. A negative argument drags the previous balanced expression -backwards across those before it (thus canceling out the effect of -@kbd{C-M-t} with a positive argument). An argument of zero, rather -than doing nothing, transposes the balanced expressions ending at or -after point and the mark. - -@kindex C-M-@@ -@kindex C-M-@key{SPC} -@findex mark-sexp - To set the region around the next balanced expression in the buffer, -use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place -that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like -@kbd{C-M-f}. In particular, a negative argument is useful for putting -the mark at the beginning of the previous balanced expression. The -alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you -repeat this command, or use it in Transient Mark mode when the mark is -active, it extends the end of the region by one sexp each time. - - In languages that use infix operators, such as C, it is not possible -to recognize all balanced expressions as such because there can be -multiple possibilities at a given position. For example, C mode does -not treat @samp{foo + bar} as a single expression, even though it -@emph{is} one C expression; instead, it recognizes @samp{foo} as one -expression and @samp{bar} as another, with the @samp{+} as punctuation -between them. Both @samp{foo + bar} and @samp{foo} are legitimate -choices for ``the expression following point'' when point is at the -@samp{f}, so the expression commands must perforce choose one or the -other to operate on. Note that @samp{(foo + bar)} is recognized as a -single expression in C mode, because of the parentheses. - -@node Moving by Parens -@subsection Moving in the Parenthesis Structure - -@cindex parenthetical groupings -@cindex parentheses, moving across -@cindex matching parenthesis and braces, moving to -@cindex braces, moving across -@cindex list commands - The Emacs commands for handling parenthetical groupings see nothing -except parentheses (or whatever characters must balance in the -language you are working with), and the escape characters that might -be used to quote those. They are mainly intended for editing -programs, but can be useful for editing any text that has parentheses. -They are sometimes called ``list'' commands because in Lisp these -groupings are lists. - -@table @kbd -@item C-M-n -Move forward over a parenthetical group (@code{forward-list}). -@item C-M-p -Move backward over a parenthetical group (@code{backward-list}). -@item C-M-u -Move up in parenthesis structure (@code{backward-up-list}). -@item C-M-d -Move down in parenthesis structure (@code{down-list}). -@end table - -@kindex C-M-n -@kindex C-M-p -@findex forward-list -@findex backward-list - The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and -@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n}) -parenthetical groupings, skipping blithely over any amount of text -that doesn't include meaningful parentheses (symbols, strings, etc.). - -@kindex C-M-u -@findex backward-up-list - @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the -parenthesis structure. To move @emph{up} one (or @var{n}) levels, use -@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up -past one unmatched opening delimiter. A positive argument serves as a -repeat count; a negative argument reverses the direction of motion, so -that the command moves forward and up one or more levels. - -@kindex C-M-d -@findex down-list - To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} -(@code{down-list}). In Lisp mode, where @samp{(} is the only opening -delimiter, this is nearly the same as searching for a @samp{(}. An -argument specifies the number of levels to go down. - -@node Matching -@subsection Automatic Display Of Matching Parentheses -@cindex matching parentheses -@cindex parentheses, displaying matches - - The Emacs parenthesis-matching feature is designed to show -automatically how parentheses (and other matching delimiters) match in -the text. Whenever you type a self-inserting character that is a -closing delimiter, the cursor moves momentarily to the location of the -matching opening delimiter, provided that is on the screen. If it is -not on the screen, Emacs displays some of the text near it in the echo -area. Either way, you can tell which grouping you are closing off. - - If the opening delimiter and closing delimiter are mismatched---such -as in @samp{[x)}---a warning message is displayed in the echo area. - -@vindex blink-matching-paren -@vindex blink-matching-paren-distance -@vindex blink-matching-delay - Three variables control parenthesis match display: - - @code{blink-matching-paren} turns the feature on or off: @code{nil} -disables it, but the default is @code{t} to enable match display. - - @code{blink-matching-delay} says how many seconds to leave the -cursor on the matching opening delimiter, before bringing it back to -the real location of point; the default is 1, but on some systems it -is useful to specify a fraction of a second. - - @code{blink-matching-paren-distance} specifies how many characters -back to search to find the matching opening delimiter. If the match -is not found in that distance, scanning stops, and nothing is displayed. -This is to prevent the scan for the matching delimiter from wasting -lots of time when there is no match. The default is 25600. - -@cindex Show Paren mode -@cindex highlighting matching parentheses -@findex show-paren-mode - Show Paren mode provides a more powerful kind of automatic matching. -Whenever point is after a closing delimiter, that delimiter and its -matching opening delimiter are both highlighted; otherwise, if point -is before an opening delimiter, the matching closing delimiter is -highlighted. (There is no need to highlight the opening delimiter in -that case, because the cursor appears on top of that character.) Use -the command @kbd{M-x show-paren-mode} to enable or disable this mode. - - Show Paren mode uses the faces @code{show-paren-match} and -@code{show-paren-mismatch} to highlight parentheses; you can customize -them to control how highlighting looks. @xref{Face Customization}. - -@node Comments -@section Manipulating Comments -@cindex comments - - Because comments are such an important part of programming, Emacs -provides special commands for editing and inserting comments. It can -also do spell checking on comments with Flyspell Prog mode -(@pxref{Spelling}). - -@menu -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. -@end menu - -@node Comment Commands -@subsection Comment Commands -@cindex indentation for comments -@cindex alignment for comments - - The comment commands in this table insert, kill and align comments. -They are described in this section and following sections. - -@table @asis -@item @kbd{M-;} -Insert or realign comment on current line; alternatively, comment or -uncomment the region (@code{comment-dwim}). -@item @kbd{C-u M-;} -Kill comment on current line (@code{comment-kill}). -@item @kbd{C-x ;} -Set comment column (@code{comment-set-column}). -@item @kbd{C-M-j} -@itemx @kbd{M-j} -Like @key{RET} followed by inserting and aligning a comment -(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. -@item @kbd{M-x comment-region} -@itemx @kbd{C-c C-c} (in C-like modes) -Add or remove comment delimiters on all the lines in the region. -@end table - -@kindex M-; -@findex comment-dwim - The command to create or align a comment is @kbd{M-;} -(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What -I Mean''; it indicates that this command can be used for many -different jobs relating to comments, depending on the situation where -you use it. - - If there is no comment already on the line, @kbd{M-;} inserts a new -comment, aligned at a specific column called the @dfn{comment column}. -The new comment begins with the string Emacs thinks comments should -start with (the value of @code{comment-start}; see below). Point is -after that string, so you can insert the text of the comment right -away. If the major mode has specified a string to terminate comments, -@kbd{M-;} inserts that after point, to keep the syntax valid. - - If the text of the line extends past the comment column, this -command aligns the comment start string to a suitable boundary -(usually, at least one space is inserted). - - You can also use @kbd{M-;} to align an existing comment. If a line -already contains the comment-start string, @kbd{M-;} realigns it to -the conventional alignment and moves point after it. (Exception: -comments starting in column 0 are not moved.) Even when an existing -comment is properly aligned, @kbd{M-;} is still useful for moving -directly to the start of the text inside the comment. - -@findex comment-kill -@kindex C-u M-; - @kbd{C-u M-;} kills any comment on the current line, along with the -whitespace before it. To reinsert the comment on another line, move -to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to -realign it. - - Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} -(@code{comment-dwim}) with a prefix argument. That command is -programmed so that when it receives a prefix argument it calls -@code{comment-kill}. However, @code{comment-kill} is a valid command -in its own right, and you can bind it directly to a key if you wish. - - @kbd{M-;} does two other jobs when used with an active region in -Transient Mark mode (@pxref{Transient Mark}). Then it either adds or -removes comment delimiters on each line of the region. (If every line -is a comment, it removes comment delimiters from each; otherwise, it -adds comment delimiters to each.) If you are not using Transient Mark -mode, then you should use the commands @code{comment-region} and -@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}), -or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}). -A prefix argument used in these circumstances specifies how many -comment delimiters to add or how many to delete. - - Some major modes have special rules for aligning certain kinds of -comments in certain contexts. For example, in Lisp code, comments which -start with two semicolons are indented as if they were lines of code, -instead of at the comment column. Comments which start with three -semicolons are supposed to start at the left margin and are often used -for sectioning purposes. Emacs understands -these conventions by indenting a double-semicolon comment using @key{TAB}, -and by not changing the indentation of a triple-semicolon comment at all. - -@example -;; This function is just an example. -;;; Here either two or three semicolons are appropriate. -(defun foo (x) -;;; And now, the first part of the function: - ;; The following line adds one. - (1+ x)) ; This line adds one. -@end example - - For C-like modes, you can configure the exact effect of @kbd{M-;} -more flexibly than for most buffers by setting the variables -@code{c-indent-comment-alist} and -@code{c-indent-comments-syntactically-p}. For example, on a line -ending in a closing brace, @kbd{M-;} puts the comment one space after -the brace rather than at @code{comment-column}. For full details see -@ref{Comment Commands,,, ccmode, The CC Mode Manual}. - -@node Multi-Line Comments -@subsection Multiple Lines of Comments - -@kindex C-M-j -@kindex M-j -@cindex blank lines in programs -@findex comment-indent-new-line - - If you are typing a comment and wish to continue it on another line, -you can use the command @kbd{C-M-j} or @kbd{M-j} -(@code{comment-indent-new-line}). If @code{comment-multi-line} -(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new -line within the comment. Otherwise it closes the comment and starts a -new comment on a new line. When Auto Fill mode is on, going past the -fill column while typing a comment causes the comment to be continued -in just this fashion. - -@kindex C-c C-c (C mode) -@findex comment-region - To turn existing lines into comment lines, use the @kbd{M-x -comment-region} command (or type @kbd{C-c C-c} in C-like modes). It -adds comment delimiters to the lines that start in the region, thus -commenting them out. With a negative argument, it does the -opposite---it deletes comment delimiters from the lines in the region. - - With a positive argument, @code{comment-region} duplicates the last -character of the comment start sequence it adds; the argument -specifies how many copies of the character to insert. Thus, in Lisp -mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. -Duplicating the comment delimiter is a way of calling attention to the -comment. It can also affect how the comment is aligned or indented. -In Lisp, for proper indentation, you should use an argument of two or -three, if between defuns; if within a defun, it must be three. - - You can configure C Mode such that when you type a @samp{/} at the -start of a line in a multi-line block comment, this closes the -comment. Enable the @code{comment-close-slash} clean-up for this. -@xref{Clean-ups,,, ccmode, The CC Mode Manual}. - -@node Options for Comments -@subsection Options Controlling Comments - -@vindex comment-column -@kindex C-x ; -@findex comment-set-column - The @dfn{comment column}, the column at which Emacs tries to place -comments, is stored in the variable @code{comment-column}. You can -set it to a number explicitly. Alternatively, the command @kbd{C-x ;} -(@code{comment-set-column}) sets the comment column to the column -point is at. @kbd{C-u C-x ;} sets the comment column to match the -last comment before point in the buffer, and then does a @kbd{M-;} to -align the current line's comment under the previous one. - - The variable @code{comment-column} is per-buffer: setting the variable -in the normal fashion affects only the current buffer, but there is a -default value which you can change with @code{setq-default}. -@xref{Locals}. Many major modes initialize this variable for the -current buffer. - -@vindex comment-start-skip - The comment commands recognize comments based on the regular -expression that is the value of the variable @code{comment-start-skip}. -Make sure this regexp does not match the null string. It may match more -than the comment starting delimiter in the strictest sense of the word; -for example, in C mode the value of the variable is -@c This stops M-q from breaking the line inside that @code. -@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces -after the @samp{/*} itself, and accepts C++ style comments also. -(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in -the string, which is needed to deny the first star its special meaning -in regexp syntax. @xref{Regexp Backslash}.) - -@vindex comment-start -@vindex comment-end - When a comment command makes a new comment, it inserts the value of -@code{comment-start} to begin it. The value of @code{comment-end} is -inserted after point, so that it will follow the text that you will -insert into the comment. When @code{comment-end} is non-empty, it -should start with a space. For example, in C mode, -@code{comment-start} has the value @w{@code{"/* "}} and -@code{comment-end} has the value @w{@code{" */"}}. - -@vindex comment-padding - The variable @code{comment-padding} specifies how many spaces -@code{comment-region} should insert on each line between the comment -delimiter and the line's original text. The default is 1, to insert -one space. @code{nil} means 0. Alternatively, @code{comment-padding} -can hold the actual string to insert. - -@vindex comment-multi-line - The variable @code{comment-multi-line} controls how @kbd{C-M-j} -(@code{indent-new-comment-line}) behaves when used inside a comment. -Specifically, when @code{comment-multi-line} is @code{nil}, the -command inserts a comment terminator, begins a new line, and finally -inserts a comment starter. Otherwise it does not insert the -terminator and starter, so it effectively continues the current -comment across multiple lines. In languages that allow multi-line -comments, the choice of value for this variable is a matter of taste. -The default for this variable depends on the major mode. - -@vindex comment-indent-function - The variable @code{comment-indent-function} should contain a function -that will be called to compute the alignment for a newly inserted -comment or for aligning an existing comment. It is set differently by -various major modes. The function is called with no arguments, but with -point at the beginning of the comment, or at the end of a line if a new -comment is to be inserted. It should return the column in which the -comment ought to start. For example, in Lisp mode, the indent hook -function bases its decision on how many semicolons begin an existing -comment, and on the code in the preceding lines. - -@node Documentation -@section Documentation Lookup - - Emacs provides several features you can use to look up the -documentation of functions, variables and commands that you plan to -use in your program. - -@menu -* Info Lookup:: Looking up library functions and commands - in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. -@end menu - -@node Info Lookup -@subsection Info Documentation Lookup - -@findex info-lookup-symbol -@findex info-lookup-file -@kindex C-h S - For many major modes, that apply to languages that have -documentation in Info, you can use @kbd{C-h S} -(@code{info-lookup-symbol}) to view the Info documentation for a -symbol used in the program. You specify the symbol with the -minibuffer; the default is the symbol appearing in the buffer at -point. For example, in C mode this looks for the symbol in the C -Library Manual. The command only works if the appropriate manual's -Info files are installed. - - The major mode determines where to look for documentation for the -symbol---which Info files to look in, and which indices to search. -You can also use @kbd{M-x info-lookup-file} to look for documentation -for a file name. - - If you use @kbd{C-h S} in a major mode that does not support it, -it asks you to specify the ``symbol help mode.'' You should enter -a command such as @code{c-mode} that would select a major -mode which @kbd{C-h S} does support. - -@node Man Page -@subsection Man Page Lookup - -@cindex manual page - On Unix, the main form of on-line documentation was the @dfn{manual -page} or @dfn{man page}. In the GNU operating system, we aim to -replace man pages with better-organized manuals that you can browse -with Info (@pxref{Misc Help}). This process is not finished, so it is -still useful to read manual pages. - -@findex manual-entry - You can read the man page for an operating system command, library -function, or system call, with the @kbd{M-x man} command. It -runs the @code{man} program to format the man page; if the system -permits, it runs @code{man} asynchronously, so that you can keep on -editing while the page is being formatted. (On MS-DOS and MS-Windows -3, you cannot edit while Emacs waits for @code{man} to finish.) The -result goes in a buffer named @samp{*Man @var{topic}*}. These buffers -use a special major mode, Man mode, that facilitates scrolling and -jumping to other manual pages. For details, type @kbd{C-h m} while in -a man page buffer. - -@cindex sections of manual pages - Each man page belongs to one of ten or more @dfn{sections}, each -named by a digit or by a digit and a letter. Sometimes there are -multiple man pages with the same name in different sections. To read -a man page from a specific section, type -@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} -when @kbd{M-x manual-entry} prompts for the topic. For example, to -read the man page for the C library function @code{chmod} (as opposed -to a command of the same name), type @kbd{M-x manual-entry @key{RET} -chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in -section @samp{2}.) - -@vindex Man-switches - If you do not specify a section, the results depend on how the -@code{man} program works on your system. Some of them display only -the first man page they find. Others display all man pages that have -the specified name, so you can move between them with the @kbd{M-n} -and @kbd{M-p} keys@footnote{On some systems, the @code{man} program -accepts a @samp{-a} command-line option which tells it to display all -the man pages for the specified topic. If you want this behavior, you -can add this option to the value of the variable @code{Man-switches}.}. -The mode line shows how many manual pages are present in the Man buffer. - -@vindex Man-fontify-manpage-flag - By default, Emacs highlights the text in man pages. For a long man -page, highlighting can take substantial time. You can turn off -highlighting of man pages by setting the variable -@code{Man-fontify-manpage-flag} to @code{nil}. - -@findex Man-fontify-manpage - If you insert the text of a man page into an Emacs buffer in some -other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to -perform the same conversions that @kbd{M-x manual-entry} does. - -@findex woman -@cindex manual pages, on MS-DOS/MS-Windows - An alternative way of reading manual pages is the @kbd{M-x woman} -command@footnote{The name of the command, @code{woman}, is an acronym -for ``w/o (without) man,'' since it doesn't use the @code{man} -program.}. Unlike @kbd{M-x man}, it does not run any external -programs to format and display the man pages; instead it does the job -in Emacs Lisp, so it works on systems such as MS-Windows, where the -@code{man} program (and other programs it uses) are not generally -available. - - @kbd{M-x woman} prompts for a name of a manual page, and provides -completion based on the list of manual pages that are installed on -your machine; the list of available manual pages is computed -automatically the first time you invoke @code{woman}. The word at -point in the current buffer is used to suggest the default for the -name the manual page. - - With a numeric argument, @kbd{M-x woman} recomputes the list of the -manual pages used for completion. This is useful if you add or delete -manual pages. - - If you type a name of a manual page and @kbd{M-x woman} finds that -several manual pages by the same name exist in different sections, it -pops up a window with possible candidates asking you to choose one of -them. - - For more information about setting up and using @kbd{M-x woman}, see -@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan -Manual}. - -@node Lisp Doc -@subsection Emacs Lisp Documentation Lookup - - As you edit Lisp code to be run in Emacs, you can use the commands -@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} -(@code{describe-variable}) to view documentation of functions and -variables that you want to use. These commands use the minibuffer to -read the name of a function or variable to document, and display the -documentation in a window. Their default arguments are based on the -code in the neighborhood of point. For @kbd{C-h f}, the default is -the function called in the innermost list containing point. @kbd{C-h -v} uses the symbol name around or adjacent to point as its default. - -@cindex Eldoc mode -@findex eldoc-mode - A more automatic but less powerful method is Eldoc mode. This minor -mode constantly displays in the echo area the argument list for the -function being called at point. (In other words, it finds the -function call that point is contained in, and displays the argument -list of that function.) If point is over a documented variable, it -shows the first line of the variable's docstring. Eldoc mode applies -in Emacs Lisp and Lisp Interaction modes, and perhaps a few others -that provide special support for looking up doc strings. Use the -command @kbd{M-x eldoc-mode} to enable or disable this feature. - -@node Hideshow -@section Hideshow minor mode - -@findex hs-minor-mode - Hideshow minor mode provides selective display of portions of a -program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} -to enable or disable this mode, or add @code{hs-minor-mode} to the -mode hook for certain major modes in order to enable it automatically -for those modes. - - Just what constitutes a block depends on the major mode. In C mode -or C++ mode, they are delimited by braces, while in Lisp mode and -similar modes they are delimited by parentheses. Multi-line comments -also count as blocks. - -@findex hs-hide-all -@findex hs-hide-block -@findex hs-show-all -@findex hs-show-block -@findex hs-show-region -@findex hs-hide-level -@findex hs-minor-mode -@kindex C-c @@ C-h -@kindex C-c @@ C-s -@kindex C-c @@ C-M-h -@kindex C-c @@ C-M-s -@kindex C-c @@ C-r -@kindex C-c @@ C-l -@kindex S-Mouse-2 -@table @kbd -@item C-c @@ C-h -Hide the current block (@code{hs-hide-block}). -@item C-c @@ C-s -Show the current block (@code{hs-show-block}). -@item C-c @@ C-c -Either hide or show the current block (@code{hs-toggle-hiding}). -@item S-Mouse-2 -Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). -@item C-c @@ C-M-h -Hide all top-level blocks (@code{hs-hide-all}). -@item C-c @@ C-M-s -Show everything in the buffer (@code{hs-show-all}). -@item C-c @@ C-l -Hide all blocks @var{n} levels below this block -(@code{hs-hide-level}). -@end table - -@vindex hs-hide-comments-when-hiding-all -@vindex hs-isearch-open -@vindex hs-special-modes-alist - These variables exist for customizing Hideshow mode. - -@table @code -@item hs-hide-comments-when-hiding-all -Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. - -@item hs-isearch-open -Specifies what kind of hidden blocks incremental search should make -visible. The value should be one of these four symbols: - -@table @code -@item code -Open only code blocks. -@item comment -Open only comments. -@item t -Open both code blocks and comments. -@item nil -Open neither code blocks nor comments. -@end table - -@item hs-special-modes-alist -A list of elements, each specifying how to initialize Hideshow -variables for one major mode. See the variable's documentation string -for more information. -@end table - -@node Symbol Completion -@section Completion for Symbol Names -@cindex completion (symbol names) - - In Emacs, completion is something you normally do in the minibuffer. -But one kind of completion is available in all buffers: completion for -symbol names. - -@kindex M-TAB - The character @kbd{M-@key{TAB}} runs a command to complete the -partial symbol before point against the set of meaningful symbol -names. This command inserts at point any additional characters that -it can determine from the partial name. - - If your window manager defines @kbd{M-@key{TAB}} to switch windows, -you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. -However, most window managers let you customize these shortcuts, and -we recommend that you change any that get in the way of use of Emacs. - - If the partial name in the buffer has multiple possible completions -that differ in the very next character, so that it is impossible to -complete even one more character, @kbd{M-@key{TAB}} displays a list of -all possible completions in another window. - -@cindex tags-based completion -@cindex Info index completion -@findex complete-symbol - In most programming language major modes, @kbd{M-@key{TAB}} runs the -command @code{complete-symbol}, which provides two kinds of completion. -Normally it does completion based on a tags table (@pxref{Tags}); with a -numeric argument (regardless of the value), it does completion based on -the names listed in the Info file indexes for your language. Thus, to -complete the name of a symbol defined in your own program, use -@kbd{M-@key{TAB}} with no argument; to complete the name of a standard -library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based -completion works only if there is an Info file for the standard library -functions of your language, and only if it is installed at your site. - -@cindex Lisp symbol completion -@cindex completion (Lisp symbols) -@findex lisp-complete-symbol - In Emacs-Lisp mode, the name space for completion normally consists of -nontrivial symbols present in Emacs---those that have function -definitions, values or properties. However, if there is an -open-parenthesis immediately before the beginning of the partial symbol, -only symbols with function definitions are considered as completions. -The command which implements this is @code{lisp-complete-symbol}. - - In Text mode and related modes, @kbd{M-@key{TAB}} completes words -based on the spell-checker's dictionary. @xref{Spelling}. - -@node Glasses -@section Glasses minor mode -@cindex Glasses mode -@cindex identifiers, making long ones readable -@cindex StudlyCaps, making them readable -@findex glasses-mode - - Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} -readable by altering the way they display. It knows two different -ways to do this: by displaying underscores between a lower-case letter -and the following capital letter, and by emboldening the capital -letters. It does not alter the buffer text, only the way they -display, so you can use it even on read-only buffers. You can use the -command @kbd{M-x glasses-mode} to enable or disable the mode in the -current buffer; you can also add @code{glasses-mode} to the mode hook -of the programming language major modes in which you normally want -to use Glasses mode. - -@node Misc for Programs -@section Other Features Useful for Editing Programs - - A number of Emacs commands that aren't designed specifically for -editing programs are useful for that nonetheless. - - The Emacs commands that operate on words, sentences and paragraphs -are useful for editing code. Most symbols names contain words -(@pxref{Words}); sentences can be found in strings and comments -(@pxref{Sentences}). Paragraphs in the strict sense can be found in -program code (in long comments), but the paragraph commands are useful -in other places too, because programming language major modes define -paragraphs to begin and end at blank lines (@pxref{Paragraphs}). -Judicious use of blank lines to make the program clearer will also -provide useful chunks of text for the paragraph commands to work on. -Auto Fill mode, if enabled in a programming language major mode, -indents the new lines which it creates. - - The selective display feature is useful for looking at the overall -structure of a function (@pxref{Selective Display}). This feature -hides the lines that are indented more than a specified amount. -Programming modes often support Outline minor mode (@pxref{Outline -Mode}). The Foldout package provides folding-editor features -(@pxref{Foldout}). - - The ``automatic typing'' features may be useful for writing programs. -@xref{Top,,Autotyping, autotype, Autotyping}. - -@node C Modes -@section C and Related Modes -@cindex C mode -@cindex Java mode -@cindex Pike mode -@cindex IDL mode -@cindex CORBA IDL mode -@cindex Objective C mode -@cindex C++ mode -@cindex AWK mode -@cindex mode, Java -@cindex mode, C -@cindex mode, C++ -@cindex mode, Objective C -@cindex mode, CORBA IDL -@cindex mode, Pike -@cindex mode, AWK - - This section gives a brief description of the special features -available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. -(These are called ``C mode and related modes.'') @xref{Top, , CC Mode, -ccmode, CC Mode}, for a more extensive description of these modes -and their special features. - -@menu -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. -@end menu - -@node Motion in C -@subsection C Mode Motion Commands - - This section describes commands for moving point, in C mode and -related modes. - -@table @code -@item M-x c-beginning-of-defun -@itemx M-x c-end-of-defun -@findex c-beginning-of-defun -@findex c-end-of-defun -Move point to the beginning or end of the current function or -top-level definition. These are found by searching for the least -enclosing braces. (By contrast, @code{beginning-of-defun} and -@code{end-of-defun} search for braces in column zero.) If you are -editing code where the opening brace of a function isn't placed in -column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to -these commands. @xref{Moving by Defuns}. - -@item C-c C-u -@kindex C-c C-u @r{(C mode)} -@findex c-up-conditional -Move point back to the containing preprocessor conditional, leaving the -mark behind. A prefix argument acts as a repeat count. With a negative -argument, move point forward to the end of the containing -preprocessor conditional. - -@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so -the function will stop at a @samp{#elif} when going backward, but not -when going forward. - -@item C-c C-p -@kindex C-c C-p @r{(C mode)} -@findex c-backward-conditional -Move point back over a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward. - -@item C-c C-n -@kindex C-c C-n @r{(C mode)} -@findex c-forward-conditional -Move point forward across a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move backward. - -@item M-a -@kindex M-a (C mode) -@findex c-beginning-of-statement -Move point to the beginning of the innermost C statement -(@code{c-beginning-of-statement}). If point is already at the beginning -of a statement, move to the beginning of the preceding statement. With -prefix argument @var{n}, move back @var{n} @minus{} 1 statements. - -In comments or in strings which span more than one line, this command -moves by sentences instead of statements. - -@item M-e -@kindex M-e (C mode) -@findex c-end-of-statement -Move point to the end of the innermost C statement or sentence; like -@kbd{M-a} except that it moves in the other direction -(@code{c-end-of-statement}). -@end table - -@node Electric C -@subsection Electric C Characters - - In C mode and related modes, certain printing characters are -@dfn{electric}---in addition to inserting themselves, they also -reindent the current line, and optionally also insert newlines. The -``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, -@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and -@kbd{)}. - - You might find electric indentation inconvenient if you are editing -chaotically indented code. If you are new to CC Mode, you might find -it disconcerting. You can toggle electric action with the command -@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line -after the mode name: - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(C mode)} -@findex c-toggle-electric-state -Toggle electric action (@code{c-toggle-electric-state}). With a -prefix argument, this command enables electric action if the argument -is positive, disables it if it is negative. -@end table - - Electric characters insert newlines only when, in addition to the -electric state, the @dfn{auto-newline} feature is enabled (indicated -by @samp{/la} in the mode line after the mode name). You can turn -this feature on or off with the command @kbd{C-c C-a}: - -@table @kbd -@item C-c C-a -@kindex C-c C-a @r{(C mode)} -@findex c-toggle-auto-newline -Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a -prefix argument, this command turns the auto-newline feature on if the -argument is positive, and off if it is negative. -@end table - - Usually the CC Mode style configures the exact circumstances in -which Emacs inserts auto-newlines. You can also configure this -directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. - -@node Hungry Delete -@subsection Hungry Delete Feature in C -@cindex hungry deletion (C Mode) - - If you want to delete an entire block of whitespace at point, you -can use @dfn{hungry deletion}. This deletes all the contiguous -whitespace either before point or after point in a single operation. -@dfn{Whitespace} here includes tabs and newlines, but not comments or -preprocessor commands. - -@table @kbd -@item C-c C-@key{DEL} -@itemx C-c @key{DEL} -@findex c-hungry-delete-backwards -@kindex C-c C-@key{DEL} (C Mode) -@kindex C-c @key{DEL} (C Mode) -@code{c-hungry-delete-backwards}---Delete the entire block of whitespace -preceding point. - -@item C-c C-d -@itemx C-c C-@key{DELETE} -@itemx C-c @key{DELETE} -@findex c-hungry-delete-forward -@kindex C-c C-d (C Mode) -@kindex C-c C-@key{DELETE} (C Mode) -@kindex C-c @key{DELETE} (C Mode) -@code{c-hungry-delete-forward}---Delete the entire block of whitespace -following point. -@end table - - As an alternative to the above commands, you can enable @dfn{hungry -delete mode}. When this feature is enabled (indicated by @samp{/h} in -the mode line after the mode name), a single @key{DEL} deletes all -preceding whitespace, not just one space, and a single @kbd{C-c C-d} -(but @emph{not} plain @key{DELETE}) deletes all following whitespace. - -@table @kbd -@item M-x c-toggle-hungry-state -@findex c-toggle-hungry-state -Toggle the hungry-delete feature -(@code{c-toggle-hungry-state})@footnote{This command had the binding -@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now -bound to @code{c-hungry-delete-forward}.}. With a prefix argument, -this command turns the hungry-delete feature on if the argument is -positive, and off if it is negative. -@end table - -@vindex c-hungry-delete-key - The variable @code{c-hungry-delete-key} controls whether the -hungry-delete feature is enabled. - -@node Other C Commands -@subsection Other Commands for C Mode - -@table @kbd -@item C-c C-w -@itemx M-x c-subword-mode -@findex c-subword-mode -Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word -commands recognize upper case letters in -@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by -the flag @samp{/w} on the mode line after the mode name -(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in -non-CC Mode buffers. - -In the GNU project, we recommend using underscores to separate words -within an identifier in C or C++, rather than using case distinctions. - -@item M-x c-context-line-break -@findex c-context-line-break -This command inserts a line break and indents the new line in a manner -appropriate to the context. In normal code, it does the work of -@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it -additionally inserts a @samp{\} at the line break, and within comments -it's like @kbd{M-j} (@code{c-indent-new-comment-line}). - -@code{c-context-line-break} isn't bound to a key by default, but it -needs a binding to be useful. The following code will bind it to -@kbd{C-j}. We use @code{c-initialization-hook} here to make sure -the keymap is loaded before we try to change it. - -@smallexample -(defun my-bind-clb () - (define-key c-mode-base-map "\C-j" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-bind-clb) -@end smallexample - -@item C-M-h -Put mark at the end of a function definition, and put point at the -beginning (@code{c-mark-function}). - -@item M-q -@kindex M-q @r{(C mode)} -@findex c-fill-paragraph -Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). -If any part of the current line is a comment or within a comment, this -command fills the comment or the paragraph of it that point is in, -preserving the comment indentation and comment delimiters. - -@item C-c C-e -@cindex macro expansion in C -@cindex expansion of C macros -@findex c-macro-expand -@kindex C-c C-e @r{(C mode)} -Run the C preprocessor on the text in the region, and show the result, -which includes the expansion of all the macro calls -(@code{c-macro-expand}). The buffer text before the region is also -included in preprocessing, for the sake of macros defined there, but the -output from this part isn't shown. - -When you are debugging C code that uses macros, sometimes it is hard to -figure out precisely how the macros expand. With this command, you -don't have to figure it out; you can see the expansions. - -@item C-c C-\ -@findex c-backslash-region -@kindex C-c C-\ @r{(C mode)} -Insert or align @samp{\} characters at the ends of the lines of the -region (@code{c-backslash-region}). This is useful after writing or -editing a C macro definition. - -If a line already ends in @samp{\}, this command adjusts the amount of -whitespace before it. Otherwise, it inserts a new @samp{\}. However, -the last line in the region is treated specially; no @samp{\} is -inserted on that line, and any @samp{\} there is deleted. - -@item M-x cpp-highlight-buffer -@cindex preprocessor highlighting -@findex cpp-highlight-buffer -Highlight parts of the text according to its preprocessor conditionals. -This command displays another buffer named @samp{*CPP Edit*}, which -serves as a graphic menu for selecting how to display particular kinds -of conditionals and their contents. After changing various settings, -click on @samp{[A]pply these settings} (or go to that buffer and type -@kbd{a}) to rehighlight the C mode buffer accordingly. - -@item C-c C-s -@findex c-show-syntactic-information -@kindex C-c C-s @r{(C mode)} -Display the syntactic information about the current source line -(@code{c-show-syntactic-information}). This information directs how -the line is indented. - -@item M-x cwarn-mode -@itemx M-x global-cwarn-mode -@findex cwarn-mode -@findex global-cwarn-mode -@vindex global-cwarn-mode -@cindex CWarn mode -@cindex suspicious constructions in C, C++ -CWarn minor mode highlights certain suspicious C and C++ constructions: - -@itemize @bullet{} -@item -Assignments inside expressions. -@item -Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} -(except after a @samp{do @dots{} while} statement); -@item -C++ functions with reference parameters. -@end itemize - -@noindent -You can enable the mode for one buffer with the command @kbd{M-x -cwarn-mode}, or for all suitable buffers with the command @kbd{M-x -global-cwarn-mode} or by customizing the variable -@code{global-cwarn-mode}. You must also enable Font Lock mode to make -it work. - -@item M-x hide-ifdef-mode -@findex hide-ifdef-mode -@cindex Hide-ifdef mode -Hide-ifdef minor mode hides selected code within @samp{#if} and -@samp{#ifdef} preprocessor blocks. See the documentation string of -@code{hide-ifdef-mode} for more information. - -@item M-x ff-find-related-file -@cindex related files -@findex ff-find-related-file -@vindex ff-related-file-alist -Find a file ``related'' in a special way to the file visited by the -current buffer. Typically this will be the header file corresponding -to a C/C++ source file, or vice versa. The variable -@code{ff-related-file-alist} specifies how to compute related file -names. -@end table - -@node Asm Mode -@section Asm Mode - -@cindex Asm mode -@cindex assembler mode -Asm mode is a major mode for editing files of assembler code. It -defines these commands: - -@table @kbd -@item @key{TAB} -@code{tab-to-tab-stop}. -@item C-j -Insert a newline and then indent using @code{tab-to-tab-stop}. -@item : -Insert a colon and then remove the indentation from before the label -preceding colon. Then do @code{tab-to-tab-stop}. -@item ; -Insert or align a comment. -@end table - - The variable @code{asm-comment-char} specifies which character -starts comments in assembler syntax. - -@ifnottex -@include fortran-xtra.texi -@end ifnottex - -@ignore - arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 -@end ignore diff --git a/man/rcirc.texi b/man/rcirc.texi deleted file mode 100644 index 6d5319cef4e..00000000000 --- a/man/rcirc.texi +++ /dev/null @@ -1,768 +0,0 @@ -\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/man/reftex.texi b/man/reftex.texi deleted file mode 100644 index a2c0a9689b2..00000000000 --- a/man/reftex.texi +++ /dev/null @@ -1,5898 +0,0 @@ -\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/man/regs.texi b/man/regs.texi deleted file mode 100644 index 475a3b7b1b5..00000000000 --- a/man/regs.texi +++ /dev/null @@ -1,330 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Registers, Display, CUA Bindings, Top -@chapter Registers -@cindex registers - - Emacs @dfn{registers} are compartments where you can save text, -rectangles, positions, and other things for later use. Once you save -text or a rectangle in a register, you can copy it into the buffer -once, or many times; you can move point to a position saved in a -register once, or many times. - -@findex view-register - Each register has a name, which consists of a single character. A -register can store a number, a piece of text, a rectangle, a position, -a window configuration, or a file name, but only one thing at any -given time. Whatever you store in a register remains there until you -store something else in that register. To see what a register @var{r} -contains, use @kbd{M-x view-register}. - -@table @kbd -@item M-x view-register @key{RET} @var{r} -Display a description of what register @var{r} contains. -@end table - - @dfn{Bookmarks} record files and positions in them, so you can -return to those positions when you look at the file again. -Bookmarks are similar enough in spirit to registers that they -seem to belong in this chapter. - -@menu -* Position: RegPos. Saving positions in registers. -* Text: RegText. Saving text in registers. -* Rectangle: RegRect. Saving rectangles in registers. -* Configurations: RegConfig. Saving window configurations in registers. -* Numbers: RegNumbers. Numbers in registers. -* Files: RegFiles. File names in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. -@end menu - -@node RegPos -@section Saving Positions in Registers -@cindex saving position in a register - - Saving a position records a place in a buffer so that you can move -back there later. Moving to a saved position switches to that buffer -and moves point to that place in it. - -@table @kbd -@item C-x r @key{SPC} @var{r} -Save position of point in register @var{r} (@code{point-to-register}). -@item C-x r j @var{r} -Jump to the position saved in register @var{r} (@code{jump-to-register}). -@end table - -@kindex C-x r SPC -@findex point-to-register - To save the current position of point in a register, choose a name -@var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r} -retains the position thus saved until you store something else in that -register. - -@kindex C-x r j -@findex jump-to-register - The command @kbd{C-x r j @var{r}} moves point to the position recorded -in register @var{r}. The register is not affected; it continues to -hold the same position. You can jump to the saved position any number -of times. - - If you use @kbd{C-x r j} to go to a saved position, but the buffer it -was saved from has been killed, @kbd{C-x r j} tries to create the buffer -again by visiting the same file. Of course, this works only for buffers -that were visiting files. - -@node RegText -@section Saving Text in Registers -@cindex saving text in a register - - When you want to insert a copy of the same piece of text several -times, it may be inconvenient to yank it from the kill ring, since each -subsequent kill moves that entry further down the ring. An alternative -is to store the text in a register and later retrieve it. - -@table @kbd -@item C-x r s @var{r} -Copy region into register @var{r} (@code{copy-to-register}). -@item C-x r i @var{r} -Insert text from register @var{r} (@code{insert-register}). -@item M-x append-to-register @key{RET} @var{r} -Append region to text in register @var{r}. -@item M-x prepend-to-register @key{RET} @var{r} -Prepend region to text in register @var{r}. -@end table - -@kindex C-x r s -@kindex C-x r i -@findex copy-to-register -@findex insert-register - @kbd{C-x r s @var{r}} stores a copy of the text of the region into -the register named @var{r}. @kbd{C-u C-x r s @var{r}}, the same -command with a numeric argument, deletes the text from the buffer as -well; you can think of this as ``moving'' the region text into the register. - -@findex append-to-register -@findex prepend-to-register - @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of -the text in the region to the text already stored in the register -named @var{r}. If invoked with a numeric argument, it deletes the -region after appending it to the register. The command -@code{prepend-to-register} is similar, except that it @emph{prepends} -the region text to the text in the register, rather than -@emph{appending} it. - - @kbd{C-x r i @var{r}} inserts in the buffer the text from register -@var{r}. Normally it leaves point before the text and places the mark -after, but with a numeric argument (@kbd{C-u}) it puts point after the -text and the mark before. - -@node RegRect -@section Saving Rectangles in Registers -@cindex saving rectangle in a register - - A register can contain a rectangle instead of linear text. The -rectangle is represented as a list of strings. @xref{Rectangles}, for -basic information on how to specify a rectangle in the buffer. - -@table @kbd -@findex copy-rectangle-to-register -@kindex C-x r r -@item C-x r r @var{r} -Copy the region-rectangle into register @var{r} -(@code{copy-rectangle-to-register}). With numeric argument, delete it as -well. -@item C-x r i @var{r} -Insert the rectangle stored in register @var{r} (if it contains a -rectangle) (@code{insert-register}). -@end table - - The @kbd{C-x r i @var{r}} command inserts a text string if the -register contains one, and inserts a rectangle if the register contains -one. - - See also the command @code{sort-columns}, which you can think of -as sorting a rectangle. @xref{Sorting}. - -@node RegConfig -@section Saving Window Configurations in Registers -@cindex saving window configuration in a register - -@findex window-configuration-to-register -@findex frame-configuration-to-register -@kindex C-x r w -@kindex C-x r f - You can save the window configuration of the selected frame in a -register, or even the configuration of all windows in all frames, and -restore the configuration later. - -@table @kbd -@item C-x r w @var{r} -Save the state of the selected frame's windows in register @var{r} -(@code{window-configuration-to-register}). -@item C-x r f @var{r} -Save the state of all frames, including all their windows, in register -@var{r} (@code{frame-configuration-to-register}). -@end table - - Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. -This is the same command used to restore a cursor position. When you -restore a frame configuration, any existing frames not included in the -configuration become invisible. If you wish to delete these frames -instead, use @kbd{C-u C-x r j @var{r}}. - -@node RegNumbers -@section Keeping Numbers in Registers -@cindex saving number in a register - - There are commands to store a number in a register, to insert -the number in the buffer in decimal, and to increment it. These commands -can be useful in keyboard macros (@pxref{Keyboard Macros}). - -@table @kbd -@item C-u @var{number} C-x r n @var{r} -@kindex C-x r n -@findex number-to-register -Store @var{number} into register @var{r} (@code{number-to-register}). -@item C-u @var{number} C-x r + @var{r} -@kindex C-x r + -@findex increment-register -Increment the number in register @var{r} by @var{number} -(@code{increment-register}). -@item C-x r i @var{r} -Insert the number from register @var{r} into the buffer. -@end table - - @kbd{C-x r i} is the same command used to insert any other sort of -register contents into the buffer. @kbd{C-x r +} with no numeric -argument increments the register value by 1; @kbd{C-x r n} with no -numeric argument stores zero in the register. - -@node RegFiles -@section Keeping File Names in Registers -@cindex saving file name in a register - - If you visit certain file names frequently, you can visit them more -conveniently if you put their names in registers. Here's the Lisp code -used to put a file name in a register: - -@smallexample -(set-register ?@var{r} '(file . @var{name})) -@end smallexample - -@need 3000 -@noindent -For example, - -@smallexample -(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) -@end smallexample - -@noindent -puts the file name shown in register @samp{z}. - - To visit the file whose name is in register @var{r}, type @kbd{C-x r j -@var{r}}. (This is the same command used to jump to a position or -restore a frame configuration.) - -@node Bookmarks -@section Bookmarks -@cindex bookmarks - - @dfn{Bookmarks} are somewhat like registers in that they record -positions you can jump to. Unlike registers, they have long names, and -they persist automatically from one Emacs session to the next. The -prototypical use of bookmarks is to record ``where you were reading'' in -various files. - -@table @kbd -@item C-x r m @key{RET} -Set the bookmark for the visited file, at point. - -@item C-x r m @var{bookmark} @key{RET} -@findex bookmark-set -Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). - -@item C-x r b @var{bookmark} @key{RET} -@findex bookmark-jump -Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). - -@item C-x r l -@findex list-bookmarks -List all bookmarks (@code{list-bookmarks}). - -@item M-x bookmark-save -@findex bookmark-save -Save all the current bookmark values in the default bookmark file. -@end table - -@kindex C-x r m -@findex bookmark-set -@kindex C-x r b -@findex bookmark-jump - The prototypical use for bookmarks is to record one current position -in each of several files. So the command @kbd{C-x r m}, which sets a -bookmark, uses the visited file name as the default for the bookmark -name. If you name each bookmark after the file it points to, then you -can conveniently revisit any of those files with @kbd{C-x r b}, and move -to the position of the bookmark at the same time. - -@kindex C-x r l - To display a list of all your bookmarks in a separate buffer, type -@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, -you can use it to edit your bookmark definitions or annotate the -bookmarks. Type @kbd{C-h m} in the bookmark buffer for more -information about its special editing commands. - - When you kill Emacs, Emacs offers to save your bookmark values in your -default bookmark file, @file{~/.emacs.bmk}, if you have changed any -bookmark values. You can also save the bookmarks at any time with the -@kbd{M-x bookmark-save} command. The bookmark commands load your -default bookmark file automatically. This saving and loading is how -bookmarks persist from one Emacs session to the next. - -@vindex bookmark-save-flag - If you set the variable @code{bookmark-save-flag} to 1, then each -command that sets a bookmark will also save your bookmarks; this way, -you don't lose any bookmark values even if Emacs crashes. (The value, -if a number, says how many bookmark modifications should go by between -saving.) - -@vindex bookmark-search-size - Bookmark position values are saved with surrounding context, so that -@code{bookmark-jump} can find the proper position even if the file is -modified slightly. The variable @code{bookmark-search-size} says how -many characters of context to record on each side of the bookmark's -position. - - Here are some additional commands for working with bookmarks: - -@table @kbd -@item M-x bookmark-load @key{RET} @var{filename} @key{RET} -@findex bookmark-load -Load a file named @var{filename} that contains a list of bookmark -values. You can use this command, as well as @code{bookmark-write}, to -work with other files of bookmark values in addition to your default -bookmark file. - -@item M-x bookmark-write @key{RET} @var{filename} @key{RET} -@findex bookmark-write -Save all the current bookmark values in the file @var{filename}. - -@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} -@findex bookmark-delete -Delete the bookmark named @var{bookmark}. - -@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert-location -Insert in the buffer the name of the file that bookmark @var{bookmark} -points to. - -@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert -Insert in the buffer the @emph{contents} of the file that bookmark -@var{bookmark} points to. -@end table - -@ignore - arch-tag: b00af991-ebc3-4b3a-8e82-a3ac81ff2e64 -@end ignore diff --git a/man/rmail.texi b/man/rmail.texi deleted file mode 100644 index 7c36a31ff18..00000000000 --- a/man/rmail.texi +++ /dev/null @@ -1,1430 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Rmail, Dired, Sending Mail, Top -@chapter Reading Mail with Rmail -@cindex Rmail -@cindex reading mail -@findex rmail -@findex rmail-mode -@vindex rmail-mode-hook - - Rmail is an Emacs subsystem for reading and disposing of mail that -you receive. Rmail stores mail messages in files called Rmail files -which use a special format. Reading the message in an Rmail file is -done in a special major mode, Rmail mode, which redefines most letters -to run commands for managing mail. -@menu -* Basic: Rmail Basics. Basic concepts of Rmail, and simple use. -* Scroll: Rmail Scrolling. Scrolling through a message. -* Motion: Rmail Motion. Moving to another message. -* Deletion: Rmail Deletion. Deleting and expunging messages. -* Inbox: Rmail Inbox. How mail gets into the Rmail file. -* Files: Rmail Files. Using multiple Rmail files. -* Output: Rmail Output. Copying message out to files. -* Labels: Rmail Labels. Classifying messages by labeling them. -* Attrs: Rmail Attributes. Certain standard labels, called attributes. -* Reply: Rmail Reply. Sending replies to messages you are viewing. -* Summary: Rmail Summary. Summaries show brief info on many messages. -* Sort: Rmail Sorting. Sorting messages in Rmail. -* Display: Rmail Display. How Rmail displays a message; customization. -* Coding: Rmail Coding. How Rmail handles decoding character sets. -* Editing: Rmail Editing. Editing message text and headers in Rmail. -* Digest: Rmail Digest. Extracting the messages from a digest message. -* Out of Rmail:: Converting an Rmail file to mailbox format. -* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes. -* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in - Various Formats -@end menu - -@node Rmail Basics -@section Basic Concepts of Rmail - -@cindex primary Rmail file -@vindex rmail-file-name - Using Rmail in the simplest fashion, you have one Rmail file -@file{~/RMAIL} in which all of your mail is saved. It is called your -@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary -Rmail file, merges new mail in from your inboxes, displays the first -message you haven't read yet, and lets you begin reading. The variable -@code{rmail-file-name} specifies the name of the primary Rmail file. - - Rmail uses narrowing to hide all but one message in the Rmail file. -The message that is shown is called the @dfn{current message}. Rmail -mode's special commands can do such things as delete the current -message, copy it into another file, send a reply, or move to another -message. You can also create multiple Rmail files and use Rmail to move -messages between them. - -@cindex message number - Within the Rmail file, messages are normally arranged sequentially in -order of receipt; you can specify other ways to sort them. Messages are -identified by consecutive integers which are their @dfn{message numbers}. -The number of the current message is displayed in Rmail's mode line, -followed by the total number of messages in the file. You can move to -a message by specifying its message number with the @kbd{j} key -(@pxref{Rmail Motion}). - -@kindex s @r{(Rmail)} -@findex rmail-expunge-and-save - Following the usual conventions of Emacs, changes in an Rmail file -become permanent only when you save the file. You can save it with -@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted -messages from the file first (@pxref{Rmail Deletion}). To save the -file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail -file after merging new mail from an inbox file (@pxref{Rmail Inbox}). - -@kindex q @r{(Rmail)} -@findex rmail-quit -@kindex b @r{(Rmail)} -@findex rmail-bury - You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges -and saves the Rmail file, then buries the Rmail buffer as well as its -summary buffer, if present (@pxref{Rmail Summary}). But there is no -need to ``exit'' formally. If you switch from Rmail to editing in -other buffers, and never switch back, you have exited. Just make sure -to save the Rmail file eventually (like any other file you have -changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save -Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the -Rmail buffer and its summary buffer without expunging and saving the -Rmail file. - -@node Rmail Scrolling -@section Scrolling Within a Message - - When Rmail displays a message that does not fit on the screen, you -must scroll through it to read the rest. You could do this with -@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so -frequent that it deserves to be easier. - -@table @kbd -@item @key{SPC} -Scroll forward (@code{scroll-up}). -@item @key{DEL} -Scroll backward (@code{scroll-down}). -@item . -Scroll to start of message (@code{rmail-beginning-of-message}). -@item / -Scroll to end of message (@code{rmail-end-of-message}). -@end table - -@kindex SPC @r{(Rmail)} -@kindex DEL @r{(Rmail)} - Since the most common thing to do while reading a message is to scroll -through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of -@kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down}) - -@kindex . @r{(Rmail)} -@kindex / @r{(Rmail)} -@findex rmail-beginning-of-message -@findex rmail-end-of-message - The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the -beginning of the selected message. This is not quite the same as @kbd{M-<}: -for one thing, it does not set the mark; for another, it resets the buffer -boundaries to the current message if you have changed them. Similarly, -the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end -of the selected message. - -@node Rmail Motion -@section Moving Among Messages - - The most basic thing to do with a message is to read it. The way to -do this in Rmail is to make the message current. The usual practice is -to move sequentially through the file, since this is the order of -receipt of messages. When you enter Rmail, you are positioned at the -first message that you have not yet made current (that is, the first one -that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move -forward to see the other new messages; move backward to re-examine old -messages. - -@table @kbd -@item n -Move to the next nondeleted message, skipping any intervening deleted -messages (@code{rmail-next-undeleted-message}). -@item p -Move to the previous nondeleted message -(@code{rmail-previous-undeleted-message}). -@item M-n -Move to the next message, including deleted messages -(@code{rmail-next-message}). -@item M-p -Move to the previous message, including deleted messages -(@code{rmail-previous-message}). -@item j -Move to the first message. With argument @var{n}, move to -message number @var{n} (@code{rmail-show-message}). -@item > -Move to the last message (@code{rmail-last-message}). -@item < -Move to the first message (@code{rmail-first-message}). - -@item M-s @var{regexp} @key{RET} -Move to the next message containing a match for @var{regexp} -(@code{rmail-search}). - -@item - M-s @var{regexp} @key{RET} -Move to the previous message containing a match for @var{regexp}. -@end table - -@kindex n @r{(Rmail)} -@kindex p @r{(Rmail)} -@kindex M-n @r{(Rmail)} -@kindex M-p @r{(Rmail)} -@findex rmail-next-undeleted-message -@findex rmail-previous-undeleted-message -@findex rmail-next-message -@findex rmail-previous-message - @kbd{n} and @kbd{p} are the usual way of moving among messages in -Rmail. They move through the messages sequentially, but skip over -deleted messages, which is usually what you want to do. Their command -definitions are named @code{rmail-next-undeleted-message} and -@code{rmail-previous-undeleted-message}. If you do not want to skip -deleted messages---for example, if you want to move to a message to -undelete it---use the variants @kbd{M-n} and @kbd{M-p} -(@code{rmail-next-message} and @code{rmail-previous-message}). A -numeric argument to any of these commands serves as a repeat -count. - - In Rmail, you can specify a numeric argument by typing just the -digits. You don't need to type @kbd{C-u} first. - -@kindex M-s @r{(Rmail)} -@findex rmail-search -@cindex searching in Rmail - The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of -search. The usual incremental search command @kbd{C-s} works in Rmail, -but it searches only within the current message. The purpose of -@kbd{M-s} is to search for another message. It reads a regular -expression (@pxref{Regexps}) nonincrementally, then searches starting at -the beginning of the following message for a match. It then selects -that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp -used the previous time. - - To search backward in the file for another message, give @kbd{M-s} a -negative argument. In Rmail you can do this with @kbd{- M-s}. - - It is also possible to search for a message based on labels. -@xref{Rmail Labels}. - -@kindex j @r{(Rmail)} -@kindex > @r{(Rmail)} -@kindex < @r{(Rmail)} -@findex rmail-show-message -@findex rmail-last-message -@findex rmail-first-message - To move to a message specified by absolute message number, use @kbd{j} -(@code{rmail-show-message}) with the message number as argument. With -no argument, @kbd{j} selects the first message. @kbd{<} -(@code{rmail-first-message}) also selects the first message. @kbd{>} -(@code{rmail-last-message}) selects the last message. - -@node Rmail Deletion -@section Deleting Messages - -@cindex deletion (Rmail) - When you no longer need to keep a message, you can @dfn{delete} it. This -flags it as ignorable, and some Rmail commands pretend it is no longer -present; but it still has its place in the Rmail file, and still has its -message number. - -@cindex expunging (Rmail) - @dfn{Expunging} the Rmail file actually removes the deleted messages. -The remaining messages are renumbered consecutively. Expunging is the only -action that changes the message number of any message, except for -undigestifying (@pxref{Rmail Digest}). - -@table @kbd -@item d -Delete the current message, and move to the next nondeleted message -(@code{rmail-delete-forward}). -@item C-d -Delete the current message, and move to the previous nondeleted -message (@code{rmail-delete-backward}). -@item u -Undelete the current message, or move back to a deleted message and -undelete it (@code{rmail-undelete-previous-message}). -@item x -Expunge the Rmail file (@code{rmail-expunge}). -@end table - -@kindex d @r{(Rmail)} -@kindex C-d @r{(Rmail)} -@findex rmail-delete-forward -@findex rmail-delete-backward - There are two Rmail commands for deleting messages. Both delete the -current message and select another message. @kbd{d} -(@code{rmail-delete-forward}) moves to the following message, skipping -messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward}) -moves to the previous nondeleted message. If there is no nondeleted -message to move to in the specified direction, the message that was just -deleted remains current. @kbd{d} with a numeric argument is -equivalent to @kbd{C-d}. - -@vindex rmail-delete-message-hook - Whenever Rmail deletes a message, it runs the hook -@code{rmail-delete-message-hook}. When the hook functions are invoked, -the message has been marked deleted, but it is still the current message -in the Rmail buffer. - -@cindex undeletion (Rmail) -@kindex x @r{(Rmail)} -@findex rmail-expunge -@kindex u @r{(Rmail)} -@findex rmail-undelete-previous-message - To make all the deleted messages finally vanish from the Rmail file, -type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still -@dfn{undelete} the deleted messages. The undeletion command, @kbd{u} -(@code{rmail-undelete-previous-message}), is designed to cancel the -effect of a @kbd{d} command in most cases. It undeletes the current -message if the current message is deleted. Otherwise it moves backward -to previous messages until a deleted message is found, and undeletes -that message. - - You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} -moves back to and undeletes the message that the @kbd{d} deleted. But -this does not work when the @kbd{d} skips a few already-deleted messages -that follow the message being deleted; then the @kbd{u} command -undeletes the last of the messages that were skipped. There is no clean -way to avoid this problem. However, by repeating the @kbd{u} command, -you can eventually get back to the message that you intend to -undelete. You can also select a particular deleted message with -the @kbd{M-p} command, then type @kbd{u} to undelete it. - - A deleted message has the @samp{deleted} attribute, and as a result -@samp{deleted} appears in the mode line when the current message is -deleted. In fact, deleting or undeleting a message is nothing more than -adding or removing this attribute. @xref{Rmail Attributes}. - -@node Rmail Inbox -@section Rmail Files and Inboxes -@cindex inbox file - - When you receive mail locally, the operating system places incoming -mail for you in a file that we call your @dfn{inbox}. When you start -up Rmail, it runs a C program called @code{movemail} to copy the new -messages from your local inbox into your primary Rmail file, which -also contains other messages saved from previous Rmail sessions. It -is in this file that you actually read the mail with Rmail. This -operation is called @dfn{getting new mail}. You can get new mail at -any time in Rmail by typing @kbd{g}. - -@vindex rmail-primary-inbox-list -@cindex @env{MAIL} environment variable - The variable @code{rmail-primary-inbox-list} contains a list of the -files which are inboxes for your primary Rmail file. If you don't set -this variable explicitly, it is initialized from the @env{MAIL} -environment variable, or, as a last resort, set to @code{nil}, which -means to use the default inbox. The default inbox file depends on -your operating system; often it is @file{/var/mail/@var{username}}, -@file{/usr/spool/mail/@var{username}}, or -@file{/usr/mail/@var{username}}. - - You can specify the inbox file(s) for any Rmail file with the -command @code{set-rmail-inbox-list}; see @ref{Rmail Files}. - - There are two reasons for having separate Rmail files and inboxes. - -@enumerate -@item -The inbox file format varies between operating systems and according to -the other mail software in use. Only one part of Rmail needs to know -about the alternatives, and it need only understand how to convert all -of them to Rmail's own format. - -@item -It is very cumbersome to access an inbox file without danger of losing -mail, because it is necessary to interlock with mail delivery. -Moreover, different operating systems use different interlocking -techniques. The strategy of moving mail out of the inbox once and for -all into a separate Rmail file avoids the need for interlocking in all -the rest of Rmail, since only Rmail operates on the Rmail file. -@end enumerate - - Rmail was written to use Babyl format as its internal format. Since -then, we have recognized that the usual inbox format on Unix and GNU -systems is adequate for the job, and we plan to change Rmail to use that -as its internal format. However, the Rmail file will still be separate -from the inbox file, even when their format is the same. - -@vindex rmail-preserve-inbox - When getting new mail, Rmail first copies the new mail from the -inbox file to the Rmail file; then it saves the Rmail file; then it -clears out the inbox file. This way, a system crash may cause -duplication of mail between the inbox and the Rmail file, but cannot -lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then -Rmail does not clear out the inbox file when it gets new mail. You -may wish to set this, for example, on a portable computer you use to -check your mail via POP while traveling, so that your mail will remain -on the server and you can save it later on your workstation. - - In some cases, Rmail copies the new mail from the inbox file -indirectly. First it runs the @code{movemail} program to move the mail -from the inbox to an intermediate file called -@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from -that file, saves the Rmail file, and only then deletes the intermediate -file. If there is a crash at the wrong time, this file continues to -exist, and Rmail will use it again the next time it gets new mail from -that inbox. - - If Rmail is unable to convert the data in -@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file -to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the -name unique) so that Rmail will not have trouble with the data again. -You should look at the file, find whatever message confuses Rmail -(probably one that includes the control-underscore character, octal code -037), and delete it. Then you can use @kbd{1 g} to get new mail from -the corrected file. - -@node Rmail Files -@section Multiple Rmail Files - - Rmail operates by default on your @dfn{primary Rmail file}, which is named -@file{~/RMAIL} and receives your incoming mail from your system inbox file. -But you can also have other Rmail files and edit them with Rmail. These -files can receive mail through their own inboxes, or you can move messages -into them with explicit Rmail commands (@pxref{Rmail Output}). - -@table @kbd -@item i @var{file} @key{RET} -Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}). - -@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET} -Specify inbox file names for current Rmail file to get mail from. - -@item g -Merge new mail from current Rmail file's inboxes -(@code{rmail-get-new-mail}). - -@item C-u g @var{file} @key{RET} -Merge new mail from inbox file @var{file}. -@end table - -@kindex i @r{(Rmail)} -@findex rmail-input - To run Rmail on a file other than your primary Rmail file, you can use -the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file -in Rmail mode. You can use @kbd{M-x rmail-input} even when not in -Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the -same thing. - - The file you read with @kbd{i} should normally be a valid Rmail file. -If it is not, Rmail tries to decompose it into a stream of messages in -various known formats. If it succeeds, it converts the whole file to an -Rmail file. If you specify a file name that doesn't exist, @kbd{i} -initializes a new buffer for creating a new Rmail file. - -@vindex rmail-secondary-file-directory -@vindex rmail-secondary-file-regexp - You can also select an Rmail file from a menu. In the Classify menu, -choose the Input Rmail File item; then choose the Rmail file you want. -The variables @code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that -match the regular expression). These variables also apply to choosing -a file for output (@pxref{Rmail Output}). - -@findex set-rmail-inbox-list - Each Rmail file can contain a list of inbox file names; you can specify -this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files} -@key{RET}}. The argument can contain any number of file names, separated -by commas. It can also be empty, which specifies that this file should -have no inboxes. Once you specify a list of inboxes in an Rmail file, -the Rmail file remembers it permanently until you specify a different list. - - As a special exception, if your primary Rmail file does not specify any -inbox files, it uses your standard system inbox. - -@kindex g @r{(Rmail)} -@findex rmail-get-new-mail - The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the -current Rmail file from its inboxes. If the Rmail file has no -inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also -merges new mail into your primary Rmail file. - - To merge mail from a file that is not the usual inbox, give the -@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file -name and merges mail from that file. The inbox file is not deleted or -changed in any way when @kbd{g} with an argument is used. This is, -therefore, a general way of merging one file of messages into another. - -@node Rmail Output -@section Copying Messages Out to Files - - These commands copy messages from an Rmail file into another file. - -@table @kbd -@item o @var{file} @key{RET} -Append a copy of the current message to the file @var{file}, using Rmail -file format by default (@code{rmail-output-to-rmail-file}). - -@item C-o @var{file} @key{RET} -Append a copy of the current message to the file @var{file}, using -system inbox file format by default (@code{rmail-output}). - -@item w @var{file} @key{RET} -Output just the message body to the file @var{file}, taking the default -file name from the message @samp{Subject} header. -@end table - -@kindex o @r{(Rmail)} -@findex rmail-output-to-rmail-file -@kindex C-o @r{(Rmail)} -@findex rmail-output - The commands @kbd{o} and @kbd{C-o} copy the current message into a -specified file. This file may be an Rmail file or it may be in system -inbox format; the output commands ascertain the file's format and write -the copied message in that format. - - The @kbd{o} and @kbd{C-o} commands differ in two ways: each has its -own separate default file name, and each specifies a choice of format to -use when the file does not already exist. The @kbd{o} command uses -Rmail format when it creates a new file, while @kbd{C-o} uses system -inbox format for a new file. The default file name for @kbd{o} is the -file name used last with @kbd{o}, and the default file name for -@kbd{C-o} is the file name used last with @kbd{C-o}. - - If the output file is an Rmail file currently visited in an Emacs buffer, -the output commands copy the message into that buffer. It is up to you -to save the buffer eventually in its file. - -@kindex w @r{(Rmail)} -@findex rmail-output-body-to-file - Sometimes you may receive a message whose body holds the contents of a -file. You can save the body to a file (excluding the message header) -with the @kbd{w} command (@code{rmail-output-body-to-file}). Often -these messages contain the intended file name in the @samp{Subject} -field, so the @kbd{w} command uses the @samp{Subject} field as the -default for the output file name. However, the file name is read using -the minibuffer, so you can specify a different name if you wish. - - You can also output a message to an Rmail file chosen with a menu. -In the Classify menu, choose the Output Rmail File menu item; then -choose the Rmail file you want. This outputs the current message to -that file, like the @kbd{o} command. The variables -@code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that -match the regular expression). - -@vindex rmail-delete-after-output - Copying a message with @kbd{o} or @kbd{C-o} gives the original copy -of the message the @samp{filed} attribute, so that @samp{filed} -appears in the mode line when such a message is current. @kbd{w} -gives it the @samp{stored} attribute. If you like to keep just a -single copy of every mail message, set the variable -@code{rmail-delete-after-output} to @code{t}; then the @kbd{o}, -@kbd{C-o} and @kbd{w} commands delete the original message after -copying it. (You can undelete the original afterward if you wish.) - - Copying messages into files in system inbox format uses the header -fields that are displayed in Rmail at the time. Thus, if you use the -@kbd{t} command to view the entire header and then copy the message, the -entire header is copied. @xref{Rmail Display}. - -@vindex rmail-output-file-alist - The variable @code{rmail-output-file-alist} lets you specify -intelligent defaults for the output file, based on the contents of the -current message. The value should be a list whose elements have this -form: - -@example -(@var{regexp} . @var{name-exp}) -@end example - -@noindent -If there's a match for @var{regexp} in the current message, then the -default file name for output is @var{name-exp}. If multiple elements -match the message, the first matching element decides the default file -name. The subexpression @var{name-exp} may be a string constant giving -the file name to use, or more generally it may be any Lisp expression -that returns a file name as a string. @code{rmail-output-file-alist} -applies to both @kbd{o} and @kbd{C-o}. - -@node Rmail Labels -@section Labels -@cindex label (Rmail) -@cindex attribute (Rmail) - - Each message can have various @dfn{labels} assigned to it as a means -of classification. Each label has a name; different names are different -labels. Any given label is either present or absent on a particular -message. A few label names have standard meanings and are given to -messages automatically by Rmail when appropriate; these special labels -are called @dfn{attributes}. -@ifnottex -(@xref{Rmail Attributes}.) -@end ifnottex -All other labels are assigned only by users. - -@table @kbd -@item a @var{label} @key{RET} -Assign the label @var{label} to the current message (@code{rmail-add-label}). -@item k @var{label} @key{RET} -Remove the label @var{label} from the current message (@code{rmail-kill-label}). -@item C-M-n @var{labels} @key{RET} -Move to the next message that has one of the labels @var{labels} -(@code{rmail-next-labeled-message}). -@item C-M-p @var{labels} @key{RET} -Move to the previous message that has one of the labels @var{labels} -(@code{rmail-previous-labeled-message}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Make a summary of all messages containing any of the labels @var{labels} -(@code{rmail-summary-by-labels}). -@end table - -@kindex a @r{(Rmail)} -@kindex k @r{(Rmail)} -@findex rmail-add-label -@findex rmail-kill-label - The @kbd{a} (@code{rmail-add-label}) and @kbd{k} -(@code{rmail-kill-label}) commands allow you to assign or remove any -label on the current message. If the @var{label} argument is empty, it -means to assign or remove the same label most recently assigned or -removed. - - Once you have given messages labels to classify them as you wish, there -are two ways to use the labels: in moving and in summaries. - -@kindex C-M-n @r{(Rmail)} -@kindex C-M-p @r{(Rmail)} -@findex rmail-next-labeled-message -@findex rmail-previous-labeled-message - The command @kbd{C-M-n @var{labels} @key{RET}} -(@code{rmail-next-labeled-message}) moves to the next message that has -one of the labels @var{labels}. The argument @var{labels} specifies one -or more label names, separated by commas. @kbd{C-M-p} -(@code{rmail-previous-labeled-message}) is similar, but moves backwards -to previous messages. A numeric argument to either command serves as a -repeat count. - - The command @kbd{C-M-l @var{labels} @key{RET}} -(@code{rmail-summary-by-labels}) displays a summary containing only the -messages that have at least one of a specified set of labels. The -argument @var{labels} is one or more label names, separated by commas. -@xref{Rmail Summary}, for information on summaries. - - If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or -@kbd{C-M-l} is empty, it means to use the last set of labels specified -for any of these commands. - -@node Rmail Attributes -@section Rmail Attributes - - Some labels such as @samp{deleted} and @samp{filed} have built-in -meanings, and Rmail assigns them to messages automatically at -appropriate times; these labels are called @dfn{attributes}. Here is -a list of Rmail attributes: - -@table @samp -@item unseen -Means the message has never been current. Assigned to messages when -they come from an inbox file, and removed when a message is made -current. When you start Rmail, it initially shows the first message -that has this attribute. -@item deleted -Means the message is deleted. Assigned by deletion commands and -removed by undeletion commands (@pxref{Rmail Deletion}). -@item filed -Means the message has been copied to some other file. Assigned by the -@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}). -@item stored -Assigned by the @kbd{w} file output command (@pxref{Rmail Output}). -@item answered -Means you have mailed an answer to the message. Assigned by the @kbd{r} -command (@code{rmail-reply}). @xref{Rmail Reply}. -@item forwarded -Means you have forwarded the message. Assigned by the @kbd{f} command -(@code{rmail-forward}). @xref{Rmail Reply}. -@item edited -Means you have edited the text of the message within Rmail. -@xref{Rmail Editing}. -@item resent -Means you have resent the message. Assigned by the command @kbd{M-x -rmail-resend}. @xref{Rmail Reply}. -@end table - - All other labels are assigned or removed only by users, and have no -standard meaning. - -@node Rmail Reply -@section Sending Replies - - Rmail has several commands that use Mail mode to send outgoing mail. -@xref{Sending Mail}, for information on using Mail mode, including -certain features meant to work with Rmail. What this section documents -are the special commands of Rmail for entering Mail mode. Note that the -usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5 -m}---also work normally in Rmail mode. - -@table @kbd -@item m -Send a message (@code{rmail-mail}). -@item c -Continue editing the already started outgoing message (@code{rmail-continue}). -@item r -Send a reply to the current Rmail message (@code{rmail-reply}). -@item f -Forward the current message to other users (@code{rmail-forward}). -@item C-u f -Resend the current message to other users (@code{rmail-resend}). -@item M-m -Try sending a bounced message a second time (@code{rmail-retry-failure}). -@end table - -@kindex r @r{(Rmail)} -@findex rmail-reply -@cindex reply to a message - The most common reason to send a message while in Rmail is to reply -to the message you are reading. To do this, type @kbd{r} -(@code{rmail-reply}). This displays the @samp{*mail*} buffer in -another window, much like @kbd{C-x 4 m}, but preinitializes the -@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and -@samp{References} header fields based on the message you are replying -to. The @samp{To} field starts out as the address of the person who -sent the message you received, and the @samp{CC} field starts out with -all the other recipients of that message. - -@vindex rmail-dont-reply-to-names - You can exclude certain recipients from being placed automatically in -the @samp{CC}, using the variable @code{rmail-dont-reply-to-names}. Its -value should be a regular expression (as a string); any recipient that -the regular expression matches, is excluded from the @samp{CC} field. -The default value matches your own name, and any name starting with -@samp{info-}. (Those names are excluded because there is a convention -of using them for large mailing lists to broadcast announcements.) - - To omit the @samp{CC} field completely for a particular reply, enter -the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}. -This means to reply only to the sender of the original message. - - Once the @samp{*mail*} buffer has been initialized, editing and -sending the mail goes as usual (@pxref{Sending Mail}). You can edit the -presupplied header fields if they are not what you want. You can also -use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c -C-y} which yanks in the message that you are replying to. You can -also switch to the Rmail buffer, select a different message there, switch -back, and yank the new current message. - -@kindex M-m @r{(Rmail)} -@findex rmail-retry-failure -@cindex retrying a failed message -@vindex rmail-retry-ignored-headers - Sometimes a message does not reach its destination. Mailers usually -send the failed message back to you, enclosed in a @dfn{failure -message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure}) -prepares to send the same message a second time: it sets up a -@samp{*mail*} buffer with the same text and header fields as before. If -you type @kbd{C-c C-c} right away, you send the message again exactly -the same as the first time. Alternatively, you can edit the text or -headers and then send it. The variable -@code{rmail-retry-ignored-headers}, in the same format as -@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which -headers are stripped from the failed message when retrying it. - -@kindex f @r{(Rmail)} -@findex rmail-forward -@cindex forwarding a message - Another frequent reason to send mail in Rmail is to @dfn{forward} the -current message to other users. @kbd{f} (@code{rmail-forward}) makes -this easy by preinitializing the @samp{*mail*} buffer with the current -message as the text, and a subject designating a forwarded message. All -you have to do is fill in the recipients and send. When you forward a -message, recipients get a message which is ``from'' you, and which has -the original message in its contents. - -@findex unforward-rmail-message - Forwarding a message encloses it between two delimiter lines. It also -modifies every line that starts with a dash, by inserting @w{@samp{- }} -at the start of the line. When you receive a forwarded message, if it -contains something besides ordinary text---for example, program source -code---you might find it useful to undo that transformation. You can do -this by selecting the forwarded message and typing @kbd{M-x -unforward-rmail-message}. This command extracts the original forwarded -message, deleting the inserted @w{@samp{- }} strings, and inserts it -into the Rmail file as a separate message immediately following the -current one. - -@findex rmail-resend - @dfn{Resending} is an alternative similar to forwarding; the -difference is that resending sends a message that is ``from'' the -original sender, just as it reached you---with a few added header fields -@samp{Resent-From} and @samp{Resent-To} to indicate that it came via -you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs -@code{rmail-forward}, which is programmed to invoke @code{rmail-resend} -if you provide a numeric argument.) - -@kindex m @r{(Rmail)} -@findex rmail-mail - The @kbd{m} (@code{rmail-mail}) command is used to start editing an -outgoing message that is not a reply. It leaves the header fields empty. -Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer -accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be -used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f} -can do. - -@kindex c @r{(Rmail)} -@findex rmail-continue - The @kbd{c} (@code{rmail-continue}) command resumes editing the -@samp{*mail*} buffer, to finish editing an outgoing message you were -already composing, or to alter a message you have sent. - -@vindex rmail-mail-new-frame - If you set the variable @code{rmail-mail-new-frame} to a -non-@code{nil} value, then all the Rmail commands to start sending a -message create a new frame to edit it in. This frame is deleted when -you send the message, or when you use the @samp{Cancel} item in the -@samp{Mail} menu. - - All the Rmail commands to send a message use the mail-composition -method that you have chosen (@pxref{Mail Methods}). - -@node Rmail Summary -@section Summaries -@cindex summary (Rmail) - - A @dfn{summary} is a buffer containing one line per message to give -you an overview of the mail in an Rmail file. Each line shows the -message number and date, the sender, the line count, the labels, and -the subject. Moving point in the summary buffer selects messages as -you move to their summary lines. Almost all Rmail commands are valid -in the summary buffer also; when used there, they apply to the message -described by the current line of the summary. - - A summary buffer applies to a single Rmail file only; if you are -editing multiple Rmail files, each one can have its own summary buffer. -The summary buffer name is made by appending @samp{-summary} to the -Rmail buffer's name. Normally only one summary buffer is displayed at a -time. - -@menu -* Rmail Make Summary:: Making various sorts of summaries. -* Rmail Summary Edit:: Manipulating messages from the summary. -@end menu - -@node Rmail Make Summary -@subsection Making Summaries - - Here are the commands to create a summary for the current Rmail file. -Once the Rmail file has a summary buffer, changes in the Rmail file -(such as deleting or expunging messages, and getting new mail) -automatically update the summary. - -@table @kbd -@item h -@itemx C-M-h -Summarize all messages (@code{rmail-summary}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Summarize messages that have one or more of the specified labels -(@code{rmail-summary-by-labels}). -@item C-M-r @var{rcpts} @key{RET} -Summarize messages that have one or more of the specified recipients -(@code{rmail-summary-by-recipients}). -@item C-M-t @var{topic} @key{RET} -Summarize messages that have a match for the specified regexp -@var{topic} in their subjects (@code{rmail-summary-by-topic}). -@item C-M-s @var{regexp} -Summarize messages whose headers and the subject line match the -specified regular expression @var{regexp} -(@code{rmail-summary-by-regexp}). -@end table - -@kindex h @r{(Rmail)} -@findex rmail-summary - The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer -for the current Rmail file with a summary of all the messages in the file. -It then displays and selects the summary buffer in another window. - -@kindex l @r{(Rmail)} -@kindex C-M-l @r{(Rmail)} -@findex rmail-summary-by-labels - @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes -a partial summary mentioning only the messages that have one or more of the -labels @var{labels}. @var{labels} should contain label names separated by -commas. - -@kindex C-M-r @r{(Rmail)} -@findex rmail-summary-by-recipients - @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) -makes a partial summary mentioning only the messages that have one or more -of the recipients @var{rcpts}. @var{rcpts} should contain mailing -addresses separated by commas. - -@kindex C-M-t @r{(Rmail)} -@findex rmail-summary-by-topic - @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic}) -makes a partial summary mentioning only the messages whose subjects have -a match for the regular expression @var{topic}. - -@kindex C-M-s @r{(Rmail)} -@findex rmail-summary-by-regexp - @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp}) -makes a partial summary which mentions only the messages whose headers -(including the date and the subject lines) match the regular -expression @var{regexp}. - - Note that there is only one summary buffer for any Rmail file; -making any kind of summary discards any previous summary. - -@vindex rmail-summary-window-size -@vindex rmail-summary-line-count-flag - The variable @code{rmail-summary-window-size} says how many lines to -use for the summary window. The variable -@code{rmail-summary-line-count-flag} controls whether the summary line -for a message should include the line count of the message. - -@node Rmail Summary Edit -@subsection Editing in Summaries - - You can use the Rmail summary buffer to do almost anything you can do -in the Rmail buffer itself. In fact, once you have a summary buffer, -there's no need to switch back to the Rmail buffer. - - You can select and display various messages in the Rmail buffer, from -the summary buffer, just by moving point in the summary buffer to -different lines. It doesn't matter what Emacs command you use to move -point; whichever line point is on at the end of the command, that -message is selected in the Rmail buffer. - - Almost all Rmail commands work in the summary buffer as well as in the -Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current -message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the -summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u} -serves as a repeat count. A negative argument reverses the meaning of -@kbd{d} and @kbd{C-d}.) @kbd{o} and @kbd{C-o} output the current -message to a file; @kbd{r} starts a reply to it. You can scroll the -current message while remaining in the summary buffer using @key{SPC} -and @key{DEL}. - - The Rmail commands to move between messages also work in the summary -buffer, but with a twist: they move through the set of messages included -in the summary. They also ensure the Rmail buffer appears on the screen -(unlike cursor motion commands, which update the contents of the Rmail -buffer but don't display it in a window unless it already appears). -Here is a list of these commands: - -@table @kbd -@item n -Move to next line, skipping lines saying `deleted', and select its -message. -@item p -Move to previous line, skipping lines saying `deleted', and select -its message. -@item M-n -Move to next line and select its message. -@item M-p -Move to previous line and select its message. -@item > -Move to the last line, and select its message. -@item < -Move to the first line, and select its message. -@item j -@itemx @key{RET} -Select the message on the current line (ensuring that the RMAIL buffer -appears on the screen). With argument @var{n}, select message number -@var{n} and move to its line in the summary buffer; this signals an -error if the message is not listed in the summary buffer. -@item M-s @var{pattern} @key{RET} -Search through messages for @var{pattern} starting with the current -message; select the message found, and move point in the summary buffer -to that message's line. -@end table - -@vindex rmail-redisplay-summary - Deletion, undeletion, and getting new mail, and even selection of a -different message all update the summary buffer when you do them in the -Rmail buffer. If the variable @code{rmail-redisplay-summary} is -non-@code{nil}, these actions also bring the summary buffer back onto -the screen. - -@kindex Q @r{(Rmail summary)} -@findex rmail-summary-wipe -@kindex q @r{(Rmail summary)} -@findex rmail-summary-quit - When you are finished using the summary, type @kbd{Q} -(@code{rmail-summary-wipe}) to delete the summary buffer's window. You -can also exit Rmail while in the summary: @kbd{q} -(@code{rmail-summary-quit}) deletes the summary window, then exits from -Rmail by saving the Rmail file and switching to another buffer. - -@node Rmail Sorting -@section Sorting the Rmail File - -@table @kbd -@item M-x rmail-sort-by-date -Sort messages of current Rmail file by date. - -@item M-x rmail-sort-by-subject -Sort messages of current Rmail file by subject. - -@item M-x rmail-sort-by-author -Sort messages of current Rmail file by author's name. - -@item M-x rmail-sort-by-recipient -Sort messages of current Rmail file by recipient's names. - -@item M-x rmail-sort-by-correspondent -Sort messages of current Rmail file by the name of the other -correspondent. - -@item M-x rmail-sort-by-lines -Sort messages of current Rmail file by size (number of lines). - -@item M-x rmail-sort-by-keywords @key{RET} @var{labels} @key{RET} -Sort messages of current Rmail file by labels. The argument -@var{labels} should be a comma-separated list of labels. The order of -these labels specifies the order of messages; messages with the first -label come first, messages with the second label come second, and so on. -Messages which have none of these labels come last. -@end table - - The Rmail sort commands perform a @emph{stable sort}: if there is no -reason to prefer either one of two messages, their order remains -unchanged. You can use this to sort by more than one criterion. For -example, if you use @code{rmail-sort-by-date} and then -@code{rmail-sort-by-author}, messages from the same author appear in -order by date. - - With a numeric argument, all these commands reverse the order of -comparison. This means they sort messages from newest to oldest, from -biggest to smallest, or in reverse alphabetical order. - -@node Rmail Display -@section Display of Messages - - Rmail reformats the header of each message before displaying it for -the first time. Reformatting hides uninteresting header fields to -reduce clutter. You can use the @kbd{t} command to show the entire -header or to repeat the header reformatting operation. - -@table @kbd -@item t -Toggle display of complete header (@code{rmail-toggle-header}). -@end table - -@vindex rmail-ignored-headers -@vindex rmail-nonignored-headers - Reformatting the header involves deleting most header fields, on the -grounds that they are not interesting. The variable -@code{rmail-ignored-headers} holds a regular expression that specifies -which header fields to hide in this way---if it matches the beginning -of a header field, that whole field is hidden. However, the variable -@code{rmail-nonignored-headers} provides a further override: a header -matching that regular expression is shown even if it matches -@code{rmail-ignored-headers} too. - -@kindex t @r{(Rmail)} -@findex rmail-toggle-header - Rmail saves the complete original header before reformatting; to see -it, use the @kbd{t} command (@code{rmail-toggle-header}). This -discards the reformatted headers of the current message and displays -it with the original header. Repeating @kbd{t} reformats the message -again, which shows only the interesting headers according to the -current values of those variable. Selecting the message again also -reformats it if necessary. - - One consequence of this is that if you edit the reformatted header -(using @kbd{e}; @pxref{Rmail Editing}), subsequent use of @kbd{t} will -discard your edits. On the other hand, if you use @kbd{e} after -@kbd{t}, to edit the original (unreformatted) header, those changes are -permanent. - - When the @kbd{t} command has a prefix argument, a positive argument -means to show the reformatted header, and a zero or negative argument -means to show the full header. - -@vindex rmail-highlighted-headers - When the terminal supports multiple fonts or colors, Rmail -highlights certain header fields that are especially interesting---by -default, the @samp{From} and @samp{Subject} fields. The variable -@code{rmail-highlighted-headers} holds a regular expression that -specifies the header fields to highlight; if it matches the beginning -of a header field, that whole field is highlighted. - - If you specify unusual colors for your text foreground and -background, the colors used for highlighting may not go well with -them. If so, specify different colors by setting the variable -@code{rmail-highlight-face} to a suitable face. To turn off -highlighting entirely in Rmail, set @code{rmail-highlighted-headers} -to @code{nil}. - - You can highlight and activate URLs in incoming messages by adding -the function @code{goto-address} to the hook -@code{rmail-show-message-hook}. Then you can browse these URLs by -clicking on them with @kbd{Mouse-2} (or @kbd{Mouse-1} quickly) or by -moving to one and typing @kbd{C-c @key{RET}}. @xref{Goto-address, -Activating URLs, Activating URLs}. - -@node Rmail Coding -@section Rmail and Coding Systems - -@cindex decoding mail messages (Rmail) - Rmail automatically decodes messages which contain non-@acronym{ASCII} -characters, just as Emacs does with files you visit and with subprocess -output. Rmail uses the standard @samp{charset=@var{charset}} header in -the message, if any, to determine how the message was encoded by the -sender. It maps @var{charset} into the corresponding Emacs coding -system (@pxref{Coding Systems}), and uses that coding system to decode -message text. If the message header doesn't have the @samp{charset} -specification, or if @var{charset} is not recognized, -Rmail chooses the coding system with the usual Emacs heuristics and -defaults (@pxref{Recognize Coding}). - -@cindex fixing incorrectly decoded mail messages - Occasionally, a message is decoded incorrectly, either because Emacs -guessed the wrong coding system in the absence of the @samp{charset} -specification, or because the specification was inaccurate. For -example, a misconfigured mailer could send a message with a -@samp{charset=iso-8859-1} header when the message is actually encoded -in @code{koi8-r}. When you see the message text garbled, or some of -its characters displayed as empty boxes, this may have happened. - -@findex rmail-redecode-body - You can correct the problem by decoding the message again using the -right coding system, if you can figure out or guess which one is -right. To do this, invoke the @kbd{M-x rmail-redecode-body} command. -It reads the name of a coding system, encodes the message body using -whichever coding system was used to decode it before, then redecodes -it using the coding system you specified. If you specified the right -coding system, the result should be readable. - - Decoding and encoding using the wrong coding system is lossless for -most encodings, in particular with 8-bit encodings such as iso-8859 or -koi8. So, if the initial attempt to redecode the message didn't -result in a legible text, you can try other coding systems until you -succeed. - - With some coding systems, notably those from the iso-2022 family, -information can be lost in decoding, so that encoding the message -again won't bring back the original incoming text. In such a case, -@code{rmail-redecode-body} cannot work. However, the problems that -call for use of @code{rmail-redecode-body} rarely occur with those -coding systems. So in practice the command works when you need it. - -@node Rmail Editing -@section Editing Within a Message - - Most of the usual Emacs commands are available in Rmail mode, though a -few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for -other purposes. However, the Rmail buffer is normally read only, and -most of the letters are redefined as Rmail commands. If you want to -edit the text of a message, you must use the Rmail command @kbd{e}. - -@table @kbd -@item e -Edit the current message as ordinary text. -@end table - -@kindex e @r{(Rmail)} -@findex rmail-edit-current-message - The @kbd{e} command (@code{rmail-edit-current-message}) switches from -Rmail mode into Rmail Edit mode, another major mode which is nearly the -same as Text mode. The mode line indicates this change. - - In Rmail Edit mode, letters insert themselves as usual and the Rmail -commands are not available. When you are finished editing the message and -are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to -Rmail mode. Alternatively, you can return to Rmail mode but cancel all the -editing that you have done, by typing @kbd{C-c C-]}. - -@vindex rmail-edit-mode-hook - Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then it -runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). It adds the -attribute @samp{edited} to the message. It also displays the full -headers of the message, so that you can edit the headers as well as the -body of the message, and your changes in the headers will be -permanent. - -@node Rmail Digest -@section Digest Messages -@cindex digest message -@cindex undigestify - - A @dfn{digest message} is a message which exists to contain and carry -several other messages. Digests are used on some moderated mailing -lists; all the messages that arrive for the list during a period of time -such as one day are put inside a single digest which is then sent to the -subscribers. Transmitting the single digest uses much less computer -time than transmitting the individual messages even though the total -size is the same, because the per-message overhead in network mail -transmission is considerable. - -@findex undigestify-rmail-message - When you receive a digest message, the most convenient way to read it is -to @dfn{undigestify} it: to turn it back into many individual messages. -Then you can read and delete the individual messages as it suits you. -To do this, select the digest message and type the command @kbd{M-x -undigestify-rmail-message}. This extracts the submessages as separate -Rmail messages, and inserts them following the digest. The digest -message itself is flagged as deleted. - -@node Out of Rmail -@section Converting an Rmail File to Inbox Format -@cindex Babyl format to Inbox format -@cindex converting Rmail file to mailbox format - -@findex unrmail - The command @kbd{M-x unrmail} converts a file in Rmail format to inbox -format (also known as the system mailbox, or mbox, format), so that -you can use it with other mail-editing tools. You must specify two -arguments, the name of the Rmail file and the name to use for the -converted file. @kbd{M-x unrmail} does not alter the Rmail file itself. - -@pindex b2m - @kbd{M-x unrmail} is useful if you can run Emacs on the machine -where the Rmail file resides, or can access the Rmail file remotely -(@pxref{Remote Files}) from a machine where Emacs is installed. If -accessing Rmail files from Emacs is impossible, you can use the -@command{b2m} program instead. @command{b2m} is part of the Emacs -distribution, it is installed into the same directory where all the -other auxiliary programs (@command{etags} etc.) are installed, and its -source is available in the Emacs source distribution, so that you -could copy the source to the target machine and compile it there. - - To convert a file @file{@var{babyl-file}} into @file{@var{mbox-file}}, -invoke @command{b2m} like this: - -@example - b2m < @var{babyl-file} > @var{mbox-file} -@end example - -@node Rmail Rot13 -@section Reading Rot13 Messages -@cindex rot13 code - - Mailing list messages that might offend some readers are sometimes -encoded in a simple code called @dfn{rot13}---so named because it -rotates the alphabet by 13 letters. This code is not for secrecy, as it -provides none; rather, it enables those who might be offended to avoid -seeing the real text of the message. - -@findex rot13-other-window - To view a buffer which uses the rot13 code, use the command @kbd{M-x -rot13-other-window}. This displays the current buffer in another window -which applies the code when displaying the text. - -@node Movemail -@section @code{movemail} program -@cindex @code{movemail} program - - When invoked for the first time, Rmail attempts to locate the -@code{movemail} program and determine its version. There are two -versions of @code{movemail} program: the native one, shipped with GNU -Emacs (the ``emacs version'') and the one included in GNU mailutils -(the ``mailutils version,'' @pxref{movemail,,,mailutils,GNU -mailutils}). They support the same command line syntax and the same -basic subset of options. However, the Mailutils version offers -additional features. - - The Emacs version of @code{movemail} is able to retrieve mail from -usual UNIX mailbox formats and from remote mailboxes using the POP3 -protocol. - - The Mailutils version is able to handle a wide set of mailbox -formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH} -mailboxes, etc. It is able to retrieve remote mail using POP3 or -IMAP4 protocol, and can retrieve mail from them using a TLS encrypted -channel. It also accepts mailbox argument in the @acronym{URL} form. -The detailed description of mailbox @acronym{URL}s can be found in -@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL} -is: - -@smallexample -@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name} -@end smallexample - -@noindent -where square brackets denote optional elements. - -@table @var -@item proto -Specifies the @dfn{mailbox protocol}, or @dfn{format} to -use. The exact semantics of the rest of @acronym{URL} elements depends -on the actual value of @var{proto} (see below). - -@item user -User name to access the remote mailbox. - -@item password -User password to access the remote mailbox. - -@item host-or-file-name -Hostname of the remote server for remote mailboxes or file name of a -local mailbox. -@end table - -@noindent -@var{Proto} can be one of: - -@table @code -@item mbox -Usual UNIX mailbox format. In this case, neither @var{user} nor -@var{pass} are used, and @var{host-or-file-name} denotes the file name of -the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. - -@item mh -A local mailbox in the @acronym{MH} format. @var{User} and -@var{pass} are not used. @var{Host-or-file-name} denotes the name of -@acronym{MH} folder, e.g., @code{mh://Mail/inbox}. - -@item maildir -A local mailbox in the @acronym{maildir} format. @var{User} and -@var{pass} are not used, and @var{host-or-file-name} denotes the name of -@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}. - -@item file -Any local mailbox format. Its actual format is detected automatically -by @code{movemail}. - -@item pop -A remote mailbox to be accessed via POP3 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; e.g., -@code{pop://smith:guessme@@remote.server.net}. - -@item imap -A remote mailbox to be accessed via IMAP4 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; -e.g., @code{imap://smith:guessme@@remote.server.net}. -@end table - - Alternatively, you can specify the file name of the mailbox to use. -This is equivalent to specifying the @samp{file} protocol: - -@smallexample -/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user} -@end smallexample - -@vindex rmail-movemail-program -@vindex rmail-movemail-search-path - The variable @code{rmail-movemail-program} controls which version of -@code{movemail} to use. If that is a string, it specifies the -absolute file name of the @code{movemail} executable. If it is -@code{nil}, Rmail searches for @code{movemail} in the directories -listed in @code{rmail-movemail-search-path} and @code{exec-path}, then -in @code{exec-directory}. - -@node Remote Mailboxes -@section Retrieving Mail from Remote Mailboxes -@pindex movemail - - Some sites use a method called POP for accessing users' inbox data -instead of storing the data in inbox files. The @code{Emacs -movemail} can work with POP if you compile it with the macro -@code{MAIL_USE_POP} defined. (You can achieve that by specifying -@samp{--with-pop} when you run @code{configure} during the -installation of Emacs.) - -The Mailutils @code{movemail} by default supports POP, unless it was -configured with @samp{--disable-pop} option. - -Both versions of @code{movemail} only work with POP3, not with older -versions of POP. - -@cindex @env{MAILHOST} environment variable -@cindex POP mailboxes - No matter which flavor of @code{movemail} you use, you can specify -POP inbox by using POP @dfn{URL} (@pxref{Movemail}). A POP -@acronym{URL} is a ``file name'' of the form -@samp{pop://@var{username}@@@var{hostname}}, where -@var{hostname} is the host name or IP address of the remote mail -server and @var{username} is the user name on that server. -Additionally, you may specify the password in the mailbox @acronym{URL}: -@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this -case, @var{password} takes preference over the one set by -@code{rmail-remote-password}. This is especially useful if you have -several remote mailboxes with different passwords. - - For backward compatibility, Rmail also supports two alternative ways -of specifying remote POP mailboxes. First, specifying an inbox name -in the form @samp{po:@var{username}:@var{hostname}} is equivalent to -@samp{pop://@var{username}@@@var{hostname}}. Alternatively, you may -set a ``file name'' of @samp{po:@var{username}} in the inbox list of -an Rmail file. @code{movemail} will handle such a name by opening a -connection to the POP server. In this case, the @env{MAILHOST} -environment variable specifies the machine on which to look for the -POP server. - -@cindex IMAP mailboxes - Another method for accessing remote mailboxes is IMAP. This method is -supported only by the Mailutils @code{movemail}. To specify an IMAP -mailbox in the inbox list, use the following mailbox @acronym{URL}: -@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The -@var{password} part is optional, as described above. - -@vindex rmail-remote-password -@vindex rmail-remote-password-required -@vindex rmail-pop-password -@vindex rmail-pop-password-required - Accessing a remote mailbox may require a password. Rmail uses the -following algorithm to retrieve it: - -@enumerate -@item -If the @var{password} is present in mailbox URL (see above), it is -used. -@item -If the variable @code{rmail-remote-password} is non-@code{nil}, its -value is used. -@item -Otherwise, if @code{rmail-remote-password-required} is non-@code{nil}, -then Rmail will ask you for the password to use. -@item -Otherwise, Rmail assumes no password is required. -@end enumerate - - For compatibility with previous versions, the variables -@code{rmail-pop-password} and @code{rmail-pop-password-required} may -be used instead of @code{rmail-remote-password} and -@code{rmail-remote-password-required}. - -@vindex rmail-movemail-flags - If you need to pass additional command-line flags to @code{movemail}, -set the variable @code{rmail-movemail-flags} a list of the flags you -wish to use. Do not use this variable to pass the @samp{-p} flag to -preserve your inbox contents; use @code{rmail-preserve-inbox} instead. - -@cindex Kerberos POP authentication - The @code{movemail} program installed at your site may support -Kerberos authentication. If it is -supported, it is used by default whenever you attempt to retrieve -POP mail when @code{rmail-pop-password} and -@code{rmail-pop-password-required} are unset. - -@cindex reverse order in POP inboxes - Some POP servers store messages in reverse order. If your server does -this, and you would rather read your mail in the order in which it was -received, you can tell @code{movemail} to reverse the order of -downloaded messages by adding the @samp{-r} flag to -@code{rmail-movemail-flags}. - -@cindex TLS encryption (Rmail) - Mailutils @code{movemail} supports TLS encryption. If you wish to -use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}. - -@node Other Mailbox Formats -@section Retrieving Mail from Local Mailboxes in Various Formats - - If your incoming mail is stored on a local machine in a format other -than UNIX mailbox, you will need the Mailutils @code{movemail} to -retrieve it. @xref{Movemail}, for the detailed description of -@code{movemail} versions. For example, to access mail from a inbox in -@code{maildir} format located in @file{/var/spool/mail/in}, you would -include the following in the Rmail inbox list: - -@smallexample -maildir://var/spool/mail/in -@end smallexample - -@ignore - arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23 -@end ignore diff --git a/man/sc.texi b/man/sc.texi deleted file mode 100644 index 5ac3b882ccd..00000000000 --- a/man/sc.texi +++ /dev/null @@ -1,2533 +0,0 @@ -\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/man/screen.texi b/man/screen.texi deleted file mode 100644 index 90ec645a26f..00000000000 --- a/man/screen.texi +++ /dev/null @@ -1,359 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Screen, User Input, Acknowledgments, Top -@chapter The Organization of the Screen -@cindex screen -@cindex parts of the screen - - On a text-only terminal, the Emacs display occupies the whole -screen. On a graphical display, such as on GNU/Linux using the X -Window System, Emacs creates its own windows to use. We use the term -@dfn{frame} to mean the entire text-only screen or an entire -system-level window used by Emacs. Emacs uses both kinds of frames, -in the same way, to display your editing. Emacs normally starts out -with just one frame, but you can create additional frames if you wish. -@xref{Frames}. - - When you start Emacs, the main central area of the frame, all except -for the top and bottom and sides, displays the text you are editing. -This area is called @dfn{the window}. At the top there is normally a -@dfn{menu bar} where you can access a series of menus; then there may -be a @dfn{tool bar}, a row of icons that perform editing commands if -you click on them. Below this, the window begins, often with a -@dfn{scroll bar} on one side. Below the window comes the last line of -the frame, a special @dfn{echo area} or @dfn{minibuffer window}, where -prompts appear and you enter information when Emacs asks for it. See -following sections for more information about these special lines. - - You can subdivide the window horizontally or vertically to make -multiple text windows, each of which can independently display some -file or text (@pxref{Windows}). In this manual, the word ``window'' -refers to the initial large window if not subdivided, or any one of -the multiple windows you have subdivided it into. - - At any time, one window is the @dfn{selected window}. On graphical -displays, the selected window normally shows a more prominent cursor -(usually solid and blinking) while other windows show a weaker cursor -(such as a hollow box). Text terminals have just one cursor, so it -always appears in the selected window. - - Most Emacs commands implicitly apply to the text in the selected -window; the text in unselected windows is mostly visible for -reference. However, mouse commands generally operate on whatever -window you click them in, whether selected or not. If you use -multiple frames on a graphical display, then giving the input focus to -a particular frame selects a window in that frame. - - Each window's last line is a @dfn{mode line}, which describes what -is going on in that window. It appears in different color and/or a ``3D'' -box if the terminal supports them; its contents normally begin with -@w{@samp{--:-- @ *scratch*}} when Emacs starts. The mode line -displays status information such as what buffer is being displayed -above it in the window, what major and minor modes are in use, and -whether the buffer contains unsaved changes. - -@menu -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. -@end menu - -@node Point -@section Point -@cindex point -@cindex cursor - - Within Emacs, the active cursor shows the location at which -editing commands will take effect. This location is called @dfn{point}. -Many Emacs commands move point through the text, so that you can edit at -different places in it. You can also place point by clicking mouse -button 1 (normally the left button). - - While the cursor appears to be @emph{on} a character, you should -think of point as @emph{between} two characters; it points @emph{before} -the character that appears under the cursor. For example, if your text -looks like @samp{frob} with the cursor over the @samp{b}, then point is -between the @samp{o} and the @samp{b}. If you insert the character -@samp{!} at that position, the result is @samp{fro!b}, with point -between the @samp{!} and the @samp{b}. Thus, the cursor remains over -the @samp{b}, as before. - - Sometimes people speak of ``the cursor'' when they mean ``point,'' or -speak of commands that move point as ``cursor motion'' commands. - - If you are editing several files in Emacs, each in its own buffer, -each buffer has its own point location. A buffer that is not -currently displayed remembers its point location in case you display -it again later. When Emacs displays multiple windows, each window has -its own point location. If the same buffer appears in more than one -window, each window has its own point position in that buffer, and (when -possible) its own cursor. - - A text-only terminal has just one cursor, in the selected window. -The other windows do not show a cursor, even though they do have their -own position of point. When Emacs updates the screen on a text-only -terminal, it has to put the cursor temporarily at the place the output -goes. This doesn't mean point is there, though. Once display -updating finishes, Emacs puts the cursor where point is. - - On graphical displays, Emacs shows a cursor in each window; the -selected window's cursor is solid and blinking, and the other cursors -are just hollow. Thus, the most prominent cursor always shows you the -selected window, on all kinds of terminals. - - @xref{Cursor Display}, for customizable variables that control display -of the cursor or cursors. - - The term ``point'' comes from the character @samp{.}, which was the -command in TECO (the language in which the original Emacs was written) -for accessing the value now called ``point.'' - -@node Echo Area -@section The Echo Area -@cindex echo area - - The line at the bottom of the frame (below the mode line) is the -@dfn{echo area}. It is used to display small amounts of text for -various purposes. - - @dfn{Echoing} means displaying the characters that you type. At the -command line, the operating system normally echoes all your input. -Emacs handles echoing differently. - - Single-character commands do not echo in Emacs, and multi-character -commands echo only if you pause while typing them. As soon as you pause -for more than a second in the middle of a command, Emacs echoes all the -characters of the command so far. This is to @dfn{prompt} you for the -rest of the command. Once echoing has started, the rest of the command -echoes immediately as you type it. This behavior is designed to give -confident users fast response, while giving hesitant users maximum -feedback. You can change this behavior by setting a variable -(@pxref{Display Custom}). - -@cindex error message in the echo area - If a command cannot do its job, it may display an @dfn{error -message} in the echo area. Error messages are accompanied by beeping -or by flashing the screen. The error also discards any input you have -typed ahead. - - Some commands display informative messages in the echo area. These -messages look much like error messages, but they are not announced -with a beep and do not throw away input. Sometimes the message tells -you what the command has done, when this is not obvious from looking -at the text being edited. Sometimes the sole purpose of a command is -to show you a message giving you specific information---for example, -@kbd{C-x =} (hold down @key{CTRL} and type @kbd{x}, then let go of -@key{CTRL} and type @kbd{=}) displays a message describing the -character position of point in the text and its current column in the -window. Commands that take a long time often display messages ending -in @samp{...} while they are working, and add @samp{done} at the end -when they are finished. They may also indicate progress with -percentages. - -@cindex @samp{*Messages*} buffer -@cindex saved echo area messages -@cindex messages saved from echo area - Echo-area informative messages are saved in an editor buffer named -@samp{*Messages*}. (We have not explained buffers yet; see -@ref{Buffers}, for more information about them.) If you miss a message -that appears briefly on the screen, you can switch to the -@samp{*Messages*} buffer to see it again. (Successive progress messages -are often collapsed into one in that buffer.) - -@vindex message-log-max - The size of @samp{*Messages*} is limited to a certain number of -lines. The variable @code{message-log-max} specifies how many lines. -Once the buffer has that many lines, adding lines at the end deletes lines -from the beginning, to keep the size constant. @xref{Variables}, for -how to set variables such as @code{message-log-max}. - - The echo area is also used to display the @dfn{minibuffer}, a window -where you can input arguments to commands, such as the name of a file -to be edited. When the minibuffer is in use, the echo area begins -with a prompt string that usually ends with a colon; also, the cursor -appears in that line because it is the selected window. You can -always get out of the minibuffer by typing @kbd{C-g}. -@xref{Minibuffer}. - -@node Mode Line -@section The Mode Line -@cindex mode line -@cindex top level -@c - - Each text window's last line is a @dfn{mode line}, which describes -what is going on in that window. The mode line starts and ends with -dashes. When there is only one text window, the mode line appears -right above the echo area; it is the next-to-last line in the frame. -On a text-only terminal, the mode line is in inverse video if the -terminal supports that; on a graphics display, the mode line has a 3D -box appearance to help it stand out. The mode line of the selected -window is highlighted if possible; see @ref{Optional Mode Line}, for -more information. - - Normally, the mode line looks like this: - -@example --@var{cs}:@var{ch}@var{R}-@var{fr} @var{buf} @var{pos} @var{line} (@var{major} @var{minor})------ -@end example - -@noindent -This gives information about the window and the buffer it displays: the -buffer's name, what major and minor modes are in use, whether the -buffer's text has been changed, and how far down the buffer you are -currently looking. - - @var{ch} contains two stars @samp{**} if the text in the buffer has -been edited (the buffer is ``modified''), or @samp{--} if the buffer has -not been edited. For a read-only buffer, it is @samp{%*} if the buffer -is modified, and @samp{%%} otherwise. - - @var{R} is @samp{@@} if the default-directory for the current buffer -is on a remote machine, or a hyphen otherwise. - - @var{fr} gives the selected frame name (@pxref{Frames}). It appears -only on text-only terminals. The initial frame's name is @samp{F1}. - - @var{buf} is the name of the window's @dfn{buffer}. Usually this is -the same as the name of a file you are editing. @xref{Buffers}. - - The buffer displayed in the selected window (the window with the -cursor) is the @dfn{current buffer}, where editing happens. When a -command's effect applies to ``the buffer,'' we mean it does those -things to the current buffer. - - @var{pos} tells you whether there is additional text above the top of -the window, or below the bottom. If your buffer is small and it is all -visible in the window, @var{pos} is @samp{All}. Otherwise, it is -@samp{Top} if you are looking at the beginning of the buffer, @samp{Bot} -if you are looking at the end of the buffer, or @samp{@var{nn}%}, where -@var{nn} is the percentage of the buffer above the top of the window. -With Size Indication mode, you can display the size of the buffer as -well. @xref{Optional Mode Line}. - - @var{line} is @samp{L} followed by the current line number of point. -This is present when Line Number mode is enabled (it normally is). -You can display the current column number too, by turning on Column -Number mode. It is not enabled by default because it is somewhat -slower. @xref{Optional Mode Line}. - - @var{major} is the name of the @dfn{major mode} in effect in the -buffer. A buffer can only be in one major mode at a time. The major -modes available include Fundamental mode (the least specialized), Text -mode, Lisp mode, C mode, Texinfo mode, and many others. @xref{Major -Modes}, for details of how the modes differ and how to select -them. - - Some major modes display additional information after the major mode -name. For example, Rmail buffers display the current message number and -the total number of messages. Compilation buffers and Shell buffers -display the status of the subprocess. - - @var{minor} is a list of some of the @dfn{minor modes} that are -turned on at the moment in the window's chosen buffer. For example, -@samp{Fill} means that Auto Fill mode is on. @samp{Abbrev} means that -Word Abbrev mode is on. @samp{Ovwrt} means that Overwrite mode is on. -@xref{Minor Modes}, for more information. - - @samp{Narrow} means that the buffer being displayed has editing -restricted to only a portion of its text. (This is not really a minor -mode, but is like one.) @xref{Narrowing}. @samp{Def} means that a -keyboard macro is being defined. @xref{Keyboard Macros}. - - In addition, if Emacs is inside a recursive editing level, square -brackets (@samp{[@dots{}]}) appear around the parentheses that -surround the modes. If Emacs is in one recursive editing level within -another, double square brackets appear, and so on. Since recursive -editing levels affect Emacs globally, not just one buffer, the square -brackets appear in every window's mode line or not in any of them. -@xref{Recursive Edit}.@refill - - @var{cs} states the coding system used for the file you are editing. -A dash indicates the default state of affairs: no code conversion, -except for end-of-line translation if the file contents call for that. -@samp{=} means no conversion whatsoever. Nontrivial code conversions -are represented by various letters---for example, @samp{1} refers to ISO -Latin-1. @xref{Coding Systems}, for more information. - - On a text-only terminal, @var{cs} includes two additional characters -which describe the coding system for keyboard input and the coding -system for terminal output. They come right before the coding system -used for the file you are editing. - - If you are using an input method, a string of the form -@samp{@var{i}>} is added to the beginning of @var{cs}; @var{i} -identifies the input method. (Some input methods show @samp{+} or -@samp{@@} instead of @samp{>}.) @xref{Input Methods}. - - When multibyte characters are not enabled, @var{cs} does not appear at -all. @xref{Enabling Multibyte}. - -@cindex end-of-line conversion, mode-line indication - The colon after @var{cs} changes to another string in some cases. -Emacs uses newline characters to separate lines in the buffer. Some -files use different conventions for separating lines: either -carriage-return linefeed (the MS-DOS convention) or just -carriage-return (the Macintosh convention). If the buffer's file uses -carriage-return linefeed, the colon changes to either a backslash -(@samp{\}) or @samp{(DOS)}, depending on the operating system. If the -file uses just carriage-return, the colon indicator changes to either -a forward slash (@samp{/}) or @samp{(Mac)}. On some systems, Emacs -displays @samp{(Unix)} instead of the colon for files that use newline -as the line separator. - - @xref{Optional Mode Line}, to add other handy information to the -mode line, such as the size of the buffer, the current column number -of point, and whether new mail for you has arrived. - - The mode line is mouse-sensitive; when you move the mouse across -various parts of it, Emacs displays help text to say what a click in -that place will do. @xref{Mode Line Mouse}. - -@node Menu Bar -@section The Menu Bar -@cindex menu bar - - Each Emacs frame normally has a @dfn{menu bar} at the top which you -can use to perform common operations. There's no need to list them -here, as you can more easily see them yourself. - -@kindex M-` -@kindex F10 -@findex tmm-menubar -@findex menu-bar-open - On a graphical display, you can use the mouse to choose a command -from the menu bar. A right-arrow at the end of the menu item means it -leads to a subsidiary menu; @samp{...} at the end means that the -command invoked will read arguments (further input from you) before it -actually does anything. - - You can also invoke the first menu bar item by pressing @key{F10} (to run -the command @code{menu-bar-open}). You can then navigate the menus with -the arrow keys. You select an item by pressing @key{RET} and cancel menu -navigation with @key{ESC}. - - To view the full command name and documentation for a menu item, type -@kbd{C-h k}, and then select the menu bar with the mouse in the usual -way (@pxref{Key Help}). - - On text-only terminals with no mouse, you can use the menu bar by -typing @kbd{M-`} or @key{F10} (these run the command -@code{tmm-menubar}). This lets you select a menu item with the -keyboard. A provisional choice appears in the echo area. You can use -the up and down arrow keys to move through the menu to different -items, and then you can type @key{RET} to select the item. - - Each menu item also has an assigned letter or digit which designates -that item; it is usually the initial of some word in the item's name. -This letter or digit is separated from the item name by @samp{=>}. You -can type the item's letter or digit to select the item. - - Some of the commands in the menu bar have ordinary key bindings as -well; one such binding is shown in parentheses after the item itself. - -@ignore - arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f -@end ignore diff --git a/man/search.texi b/man/search.texi deleted file mode 100644 index 1a8a6372ba2..00000000000 --- a/man/search.texi +++ /dev/null @@ -1,1361 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Search, Fixit, Display, Top -@chapter Searching and Replacement -@cindex searching -@cindex finding strings within text - - Like other editors, Emacs has commands for searching for occurrences of -a string. The principal search command is unusual in that it is -@dfn{incremental}; it begins to search before you have finished typing the -search string. There are also nonincremental search commands more like -those of other editors. - - Besides the usual @code{replace-string} command that finds all -occurrences of one string and replaces them with another, Emacs has a -more flexible replacement command called @code{query-replace}, which -asks interactively which occurrences to replace. There are also -commands to find and operate on all matches for a pattern. - - You can also search multiple files under control of a tags -table (@pxref{Tags Search}) or through the Dired @kbd{A} command -(@pxref{Operating on Files}), or ask the @code{grep} program to do it -(@pxref{Grep Searching}). - - -@menu -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. -@end menu - -@node Incremental Search -@section Incremental Search -@cindex incremental search -@cindex isearch - - An incremental search begins searching as soon as you type the first -character of the search string. As you type in the search string, Emacs -shows you where the string (as you have typed it so far) would be -found. When you have typed enough characters to identify the place you -want, you can stop. Depending on what you plan to do next, you may or -may not need to terminate the search explicitly with @key{RET}. - -@table @kbd -@item C-s -Incremental search forward (@code{isearch-forward}). -@item C-r -Incremental search backward (@code{isearch-backward}). -@end table - -@menu -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Non-ASCII Isearch:: How to search for non-ASCII characters. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Highlight Isearch:: Isearch highlights the other possible matches. -* Isearch Scroll:: Scrolling during an incremental search. -* Slow Isearch:: Incremental search features for slow terminals. -@end menu - -@node Basic Isearch -@subsection Basics of Incremental Search - -@kindex C-s -@findex isearch-forward - @kbd{C-s} starts a forward incremental search. It reads characters -from the keyboard, and moves point past the next occurrence of those -characters. If you type @kbd{C-s} and then @kbd{F}, that puts the -cursor after the first @samp{F} (the first following the starting point, since -this is a forward search). Then if you type an @kbd{O}, you will see -the cursor move to just after the first @samp{FO} (the @samp{F} in that -@samp{FO} may or may not be the first @samp{F}). After another -@kbd{O}, the cursor moves to just after the first @samp{FOO} after the place -where you started the search. At each step, the buffer text that -matches the search string is highlighted, if the terminal can do that; -the current search string is always displayed in the echo area. - - If you make a mistake in typing the search string, you can cancel -characters with @key{DEL}. Each @key{DEL} cancels the last character of -search string. This does not happen until Emacs is ready to read another -input character; first it must either find, or fail to find, the character -you want to erase. If you do not want to wait for this to happen, use -@kbd{C-g} as described below. - - When you are satisfied with the place you have reached, you can type -@key{RET}, which stops searching, leaving the cursor where the search -brought it. Also, any command not specially meaningful in searches -stops the searching and is then executed. Thus, typing @kbd{C-a} -would exit the search and then move to the beginning of the line. -@key{RET} is necessary only if the next command you want to type is a -printing character, @key{DEL}, @key{RET}, or another character that is -special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, -@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some other -meta-characters). - - When you exit the incremental search, it sets the mark where point -@emph{was} before the search. That is convenient for moving back -there. In Transient Mark mode, incremental search sets the mark -without activating it, and does so only if the mark is not already -active. - -@node Repeat Isearch -@subsection Repeating Incremental Search - - Sometimes you search for @samp{FOO} and find one, but not the one you -expected to find. There was a second @samp{FOO} that you forgot -about, before the one you were aiming for. In this event, type -another @kbd{C-s} to move to the next occurrence of the search string. -You can repeat this any number of times. If you overshoot, you can -cancel some @kbd{C-s} characters with @key{DEL}. - - After you exit a search, you can search for the same string again by -typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes -incremental search, and the second @kbd{C-s} means ``search again.'' - - If a search is failing and you ask to repeat it by typing another -@kbd{C-s}, it starts again from the beginning of the buffer. -Repeating a failing reverse search with @kbd{C-r} starts again from -the end. This is called @dfn{wrapping around}, and @samp{Wrapped} -appears in the search prompt once this has happened. If you keep on -going past the original starting point of the search, it changes to -@samp{Overwrapped}, which means that you are revisiting matches that -you have already seen. - - To reuse earlier search strings, use the @dfn{search ring}. The -commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search -string to reuse. These commands leave the selected search ring element -in the minibuffer, where you can edit it. To edit the current search -string in the minibuffer without replacing it with items from the -search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r} -to terminate editing the string and search for it. - - You can change to searching backwards with @kbd{C-r}. For instance, -if you are searching forward but you realize you were looking for -something above the starting point, you can do this. Repeated -@kbd{C-r} keeps looking for more occurrences backwards. A @kbd{C-s} -starts going forwards again. @kbd{C-r} in a search can be canceled -with @key{DEL}. - -@kindex C-r -@findex isearch-backward - If you know initially that you want to search backwards, you can use -@kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} -as a key runs a command (@code{isearch-backward}) to search backward. -A backward search finds matches that end before the starting point, -just as a forward search finds matches that begin after it. - -@node Error in Isearch -@subsection Errors in Incremental Search - - If your string is not found at all, the echo area says @samp{Failing -I-Search}. The cursor is after the place where Emacs found as much of your -string as it could. Thus, if you search for @samp{FOOT}, and there is no -@samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}. -At this point there are several things you can do. If your string was -mistyped, you can rub some of it out and correct it. If you like the place -you have found, you can type @key{RET} or some other Emacs command to -remain there. Or you can type @kbd{C-g}, which -removes from the search string the characters that could not be found (the -@samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in -@samp{FOOT}). A second @kbd{C-g} at that point cancels the search -entirely, returning point to where it was when the search started. - -@cindex quitting (in search) - The @kbd{C-g} ``quit'' character does special things during searches; -just what it does depends on the status of the search. If the search has -found what you specified and is waiting for input, @kbd{C-g} cancels the -entire search. The cursor moves back to where you started the search. If -@kbd{C-g} is typed when there are characters in the search string that have -not been found---because Emacs is still searching for them, or because it -has failed to find them---then the search string characters which have not -been found are discarded from the search string. With them gone, the -search is now successful and waiting for more input, so a second @kbd{C-g} -will cancel the entire search. - -@node Special Isearch -@subsection Special Input for Incremental Search - - An upper-case letter in the search string makes the search -case-sensitive. If you delete the upper-case character from the search -string, it ceases to have this effect. @xref{Search Case}. - - To search for a newline, type @kbd{C-j}. To search for another -control character, such as control-S or carriage return, you must quote -it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous -to its use for insertion (@pxref{Inserting Text}): it causes the -following character to be treated the way any ``ordinary'' character is -treated in the same context. You can also specify a character by its -octal code: enter @kbd{C-q} followed by a sequence of octal digits. - - @kbd{M-%} typed in incremental search invokes @code{query-replace} -or @code{query-replace-regexp} (depending on search mode) with the -current search string used as the string to replace. @xref{Query -Replace}. - - Entering @key{RET} when the search string is empty launches -nonincremental search (@pxref{Nonincremental Search}). - -@vindex isearch-mode-map - To customize the special characters that incremental search understands, -alter their bindings in the keymap @code{isearch-mode-map}. For a list -of bindings, look at the documentation of @code{isearch-mode} with -@kbd{C-h f isearch-mode @key{RET}}. - -@node Non-ASCII Isearch -@subsection Isearch for Non-@acronym{ASCII} Characters -@cindex searching for non-@acronym{ASCII} characters -@cindex input method, during incremental search - - To enter non-@acronym{ASCII} characters in an incremental search, -you can use @kbd{C-q} (see the previous section), but it is easier to -use an input method (@pxref{Input Methods}). If an input method is -enabled in the current buffer when you start the search, you can use -it in the search string also. Emacs indicates that by including the -input method mnemonic in its prompt, like this: - -@example -I-search [@var{im}]: -@end example - -@noindent -@findex isearch-toggle-input-method -@findex isearch-toggle-specified-input-method -where @var{im} is the mnemonic of the active input method. - - You can toggle (enable or disable) the input method while you type -the search string with @kbd{C-\} (@code{isearch-toggle-input-method}). -You can turn on a certain (non-default) input method with @kbd{C-^} -(@code{isearch-toggle-specified-input-method}), which prompts for the -name of the input method. The input method you enable during -incremental search remains enabled in the current buffer afterwards. - -@node Isearch Yank -@subsection Isearch Yanking - - The characters @kbd{C-w} and @kbd{C-y} can be used in incremental -search to grab text from the buffer into the search string. This -makes it convenient to search for another occurrence of text at point. -@kbd{C-w} copies the character or word after point as part of the -search string, advancing point over it. (The decision, whether to -copy a character or a word, is heuristic.) Another @kbd{C-s} to -repeat the search will then search for a string including that -character or word. - - @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the -current line into the search string. If point is already at the end -of a line, it grabs the entire next line. Both @kbd{C-y} and -@kbd{C-w} convert the text they copy to lower case if the search is -currently not case-sensitive; this is so the search remains -case-insensitive. - - @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one -character at a time: @kbd{C-M-w} deletes the last character from the -search string and @kbd{C-M-y} copies the character after point to the -end of the search string. An alternative method to add the character -after point into the search string is to enter the minibuffer by -@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the -minibuffer. - - The character @kbd{M-y} copies text from the kill ring into the search -string. It uses the same text that @kbd{C-y} as a command would yank. -@kbd{Mouse-2} in the echo area does the same. -@xref{Yanking}. - -@node Highlight Isearch -@subsection Lazy Search Highlighting -@cindex lazy search highlighting -@vindex isearch-lazy-highlight - - When you pause for a little while during incremental search, it -highlights all other possible matches for the search string. This -makes it easier to anticipate where you can get to by typing @kbd{C-s} -or @kbd{C-r} to repeat the search. The short delay before highlighting -other matches helps indicate which match is the current one. -If you don't like this feature, you can turn it off by setting -@code{isearch-lazy-highlight} to @code{nil}. - -@cindex faces for highlighting search matches - You can control how this highlighting looks by customizing the faces -@code{isearch} (used for the current match) and @code{lazy-highlight} -(for all the other matches). - -@node Isearch Scroll -@subsection Scrolling During Incremental Search - - You can enable the use of vertical scrolling during incremental -search (without exiting the search) by setting the customizable -variable @code{isearch-allow-scroll} to a non-@code{nil} value. This -applies to using the vertical scroll-bar and to certain keyboard -commands such as @kbd{@key{PRIOR}} (@code{scroll-down}), -@kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter}). -You must run these commands via their key sequences to stay in the -search---typing @kbd{M-x} will terminate the search. You can give -prefix arguments to these commands in the usual way. - - This feature won't let you scroll the current match out of visibility, -however. - - The feature also affects some other commands, such as @kbd{C-x 2} -(@code{split-window-vertically}) and @kbd{C-x ^} -(@code{enlarge-window}) which don't exactly scroll but do affect where -the text appears on the screen. In general, it applies to any command -whose name has a non-@code{nil} @code{isearch-scroll} property. So you -can control which commands are affected by changing these properties. - - For example, to make @kbd{C-h l} usable within an incremental search -in all future Emacs sessions, use @kbd{C-h c} to find what command it -runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.) -Then you can put the following line in your @file{.emacs} file -(@pxref{Init File}): - -@example -(put 'view-lossage 'isearch-scroll t) -@end example - -@noindent -This feature can be applied to any command that doesn't permanently -change point, the buffer contents, the match data, the current buffer, -or the selected window and frame. The command must not itself attempt -an incremental search. - -@node Slow Isearch -@subsection Slow Terminal Incremental Search - - Incremental search on a slow terminal uses a modified style of display -that is designed to take less time. Instead of redisplaying the buffer at -each place the search gets to, it creates a new single-line window and uses -that to display the line that the search has found. The single-line window -comes into play as soon as point moves outside of the text that is already -on the screen. - - When you terminate the search, the single-line window is removed. -Emacs then redisplays the window in which the search was done, to show -its new position of point. - -@vindex search-slow-speed - The slow terminal style of display is used when the terminal baud rate is -less than or equal to the value of the variable @code{search-slow-speed}, -initially 1200. See also the discussion of the variable @code{baud-rate} -(@pxref{baud-rate,, Customization of Display}). - -@vindex search-slow-window-lines - The number of lines to use in slow terminal search display is controlled -by the variable @code{search-slow-window-lines}. Its normal value is 1. - -@node Nonincremental Search -@section Nonincremental Search -@cindex nonincremental search - - Emacs also has conventional nonincremental search commands, which require -you to type the entire search string before searching begins. - -@table @kbd -@item C-s @key{RET} @var{string} @key{RET} -Search for @var{string}. -@item C-r @key{RET} @var{string} @key{RET} -Search backward for @var{string}. -@end table - - To do a nonincremental search, first type @kbd{C-s @key{RET}}. This -enters the minibuffer to read the search string; terminate the string -with @key{RET}, and then the search takes place. If the string is not -found, the search command signals an error. - - When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental -search as usual. That command is specially programmed to invoke -nonincremental search, @code{search-forward}, if the string you -specify is empty. (Such an empty argument would otherwise be -useless.) But it does not call @code{search-forward} right away. First -it checks the next input character to see if is @kbd{C-w}, -which specifies a word search. -@ifnottex -@xref{Word Search}. -@end ifnottex -@kbd{C-r @key{RET}} does likewise, for a reverse incremental search. - -@findex search-forward -@findex search-backward - Forward and backward nonincremental searches are implemented by the -commands @code{search-forward} and @code{search-backward}. These -commands may be bound to keys in the usual manner. The feature that you -can get to them via the incremental search commands exists for -historical reasons, and to avoid the need to find separate key sequences -for them. - -@node Word Search -@section Word Search -@cindex word search - - Word search searches for a sequence of words without regard to how the -words are separated. More precisely, you type a string of many words, -using single spaces to separate them, and the string can be found even -if there are multiple spaces, newlines, or other punctuation characters -between these words. - - Word search is useful for editing a printed document made with a text -formatter. If you edit while looking at the printed, formatted version, -you can't tell where the line breaks are in the source file. With word -search, you can search without having to know them. - -@table @kbd -@item C-s @key{RET} C-w @var{words} @key{RET} -Search for @var{words}, ignoring details of punctuation. -@item C-r @key{RET} C-w @var{words} @key{RET} -Search backward for @var{words}, ignoring details of punctuation. -@end table - - Word search as a special case of nonincremental search is invoked -with @kbd{C-s @key{RET} C-w}. This is followed by the search string, -which must always be terminated with @key{RET}. Being nonincremental, -this search does not start until the argument is terminated. It works -by constructing a regular expression and searching for that; see -@ref{Regexp Search}. - - Use @kbd{C-r @key{RET} C-w} to do backward word search. - - You can also invoke word search with @kbd{C-s M-e C-w} or @kbd{C-r -M-e C-w} followed by the search string and terminated with @key{RET}, -@kbd{C-s} or @kbd{C-r}. This puts word search into incremental mode -where you can use all keys available for incremental search. However, -when you type more words in incremental word search, it will fail -until you type complete words. - -@findex word-search-forward -@findex word-search-backward - Forward and backward word searches are implemented by the commands -@code{word-search-forward} and @code{word-search-backward}. These -commands may be bound to keys in the usual manner. They are available -via the incremental search commands both for historical reasons and -to avoid the need to find separate key sequences for them. - -@node Regexp Search -@section Regular Expression Search -@cindex regular expression -@cindex regexp - - A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern -that denotes a class of alternative strings to match, possibly -infinitely many. GNU Emacs provides both incremental and -nonincremental ways to search for a match for a regexp. The syntax of -regular expressions is explained in the following section. - -@kindex C-M-s -@findex isearch-forward-regexp -@kindex C-M-r -@findex isearch-backward-regexp - Incremental search for a regexp is done by typing @kbd{C-M-s} -(@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a -prefix argument (whose value does not matter), or by typing @kbd{M-r} -within a forward incremental search. This command reads a -search string incrementally just like @kbd{C-s}, but it treats the -search string as a regexp rather than looking for an exact match -against the text in the buffer. Each time you add text to the search -string, you make the regexp longer, and the new regexp is searched -for. To search backward for a regexp, use @kbd{C-M-r} -(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, -or @kbd{M-r} within a backward incremental search. - - All of the control characters that do special things within an -ordinary incremental search have the same function in incremental regexp -search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the -search retrieves the last incremental search regexp used; that is to -say, incremental regexp and non-regexp searches have independent -defaults. They also have separate search rings that you can access with -@kbd{M-p} and @kbd{M-n}. - -@vindex search-whitespace-regexp - If you type @key{SPC} in incremental regexp search, it matches any -sequence of whitespace characters, including newlines. If you want to -match just a space, type @kbd{C-q @key{SPC}}. You can control what a -bare space matches by setting the variable -@code{search-whitespace-regexp} to the desired regexp. - - In some cases, adding characters to the regexp in an incremental regexp -search can make the cursor move back and start again. For example, if -you have searched for @samp{foo} and you add @samp{\|bar}, the cursor -backs up in case the first @samp{bar} precedes the first @samp{foo}. - - Forward and backward regexp search are not symmetrical, because -regexp matching in Emacs always operates forward, starting with the -beginning of the regexp. Thus, forward regexp search scans forward, -trying a forward match at each possible starting position. Backward -regexp search scans backward, trying a forward match at each possible -starting position. These search methods are not mirror images. - -@findex re-search-forward -@findex re-search-backward - Nonincremental search for a regexp is done by the functions -@code{re-search-forward} and @code{re-search-backward}. You can invoke -these with @kbd{M-x}, or bind them to keys, or invoke them by way of -incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r -@key{RET}}. - - If you use the incremental regexp search commands with a prefix -argument, they perform ordinary string search, like -@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental -Search}. - -@node Regexps -@section Syntax of Regular Expressions -@cindex syntax of regexps - - This manual describes regular expression features that users -typically want to use. There are additional features that are -mainly used in Lisp programs; see @ref{Regular Expressions,,, -elisp, The Emacs Lisp Reference Manual}. - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character is a simple regular expression which matches that same -character and nothing else. The special characters are @samp{$}, -@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, and -@samp{\}. The character @samp{]} is special if it ends a character -alternative (see later). The character @samp{-} is special inside a -character alternative. Any other character appearing in a regular -expression is ordinary, unless a @samp{\} precedes it. (When you use -regular expressions in a Lisp program, each @samp{\} must be doubled, -see the example near the end of this section.) - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{ff}.) Likewise, @samp{o} is a regular expression that matches -only @samp{o}. (When case distinctions are being ignored, these regexps -also match @samp{F} and @samp{O}, but we consider this a generalization -of ``the same string,'' rather than an exception.) - - Any two regular expressions @var{a} and @var{b} can be concatenated. The -result is a regular expression which matches a string if @var{a} matches -some amount of the beginning of that string and @var{b} matches the rest of -the string.@refill - - As a simple example, we can concatenate the regular expressions @samp{f} -and @samp{o} to get the regular expression @samp{fo}, which matches only -the string @samp{fo}. Still trivial. To do something nontrivial, you -need to use one of the special characters. Here is a list of them. - -@table @asis -@item @kbd{.}@: @r{(Period)} -is a special character that matches any single character except a newline. -Using concatenation, we can make regular expressions like @samp{a.b}, which -matches any three-character string that begins with @samp{a} and ends with -@samp{b}.@refill - -@item @kbd{*} -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively as many times as -possible. Thus, @samp{o*} matches any number of @samp{o}s (including no -@samp{o}s). - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -The matcher processes a @samp{*} construct by matching, immediately, -as many repetitions as can be found. Then it continues with the rest -of the pattern. If that fails, backtracking occurs, discarding some -of the matches of the @samp{*}-modified construct in case that makes -it possible to match the rest of the pattern. For example, in matching -@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first -tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. -With this choice, the rest of the regexp matches successfully.@refill - -@item @kbd{+} -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. So, for example, @samp{ca+r} -matches the strings @samp{car} and @samp{caaaar} but not the string -@samp{cr}, whereas @samp{ca*r} matches all three strings. - -@item @kbd{?} -is a postfix operator, similar to @samp{*} except that it can match the -preceding expression either once or not at all. For example, -@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. - -@item @kbd{*?}, @kbd{+?}, @kbd{??} -@cindex non-greedy regexp matching -are non-greedy variants of the operators above. The normal operators -@samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as -much as they can, as long as the overall regexp can still match. With -a following @samp{?}, they are non-greedy: they will match as little -as possible. - -Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a} -and the string @samp{abbbb}; but if you try to match them both against -the text @samp{abbb}, @samp{ab*} will match it all (the longest valid -match), while @samp{ab*?} will match just @samp{a} (the shortest -valid match). - -Non-greedy operators match the shortest possible string starting at a -given starting point; in a forward search, though, the earliest -possible starting point for match is always the one chosen. Thus, if -you search for @samp{a.*?$} against the text @samp{abbab} followed by -a newline, it matches the whole string. Since it @emph{can} match -starting at the first @samp{a}, it does. - -@item @kbd{\@{@var{n}\@}} -is a postfix operator that specifies repetition @var{n} times---that -is, the preceding regular expression must match exactly @var{n} times -in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} -and nothing else. - -@item @kbd{\@{@var{n},@var{m}\@}} -is a postfix operator that specifies repetition between @var{n} and -@var{m} times---that is, the preceding regular expression must match -at least @var{n} times, but no more than @var{m} times. If @var{m} is -omitted, then there is no upper limit, but the preceding regular -expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is -equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to -@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. - -@item @kbd{[ @dots{} ]} -is a @dfn{character set}, which begins with @samp{[} and is terminated -by @samp{]}. In the simplest case, the characters between the two -brackets are what this set can match. - -Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and -@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s -(including the empty string), from which it follows that @samp{c[ad]*r} -matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. - -You can also include character ranges in a character set, by writing the -starting and ending characters with a @samp{-} between them. Thus, -@samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be -intermixed freely with individual characters, as in @samp{[a-z$%.]}, -which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or -period. - -Note that the usual regexp special characters are not special inside a -character set. A completely different set of special characters exists -inside character sets: @samp{]}, @samp{-} and @samp{^}. - -To include a @samp{]} in a character set, you must make it the first -character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To -include a @samp{-}, write @samp{-} as the first or last character of the -set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} -and @samp{-}. - -To include @samp{^} in a set, put it anywhere but at the beginning of -the set. (At the beginning, it complements the set---see below.) - -When you use a range in case-insensitive search, you should write both -ends of the range in upper case, or both in lower case, or both should -be non-letters. The behavior of a mixed-case range such as @samp{A-z} -is somewhat ill-defined, and it may change in future Emacs versions. - -@item @kbd{[^ @dots{} ]} -@samp{[^} begins a @dfn{complemented character set}, which matches any -character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches -all characters @emph{except} @acronym{ASCII} letters and digits. - -@samp{^} is not special in a character set unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character set can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -@item @kbd{^} -is a special character that matches the empty string, but only at the -beginning of a line in the text being matched. Otherwise it fails to -match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at -the beginning of a line. - -For historical compatibility reasons, @samp{^} can be used with this -meaning only at the beginning of the regular expression, or after -@samp{\(} or @samp{\|}. - -@item @kbd{$} -is similar to @samp{^} but matches only at the end of a line. Thus, -@samp{x+$} matches a string of one @samp{x} or more at the end of a line. - -For historical compatibility reasons, @samp{$} can be used with this -meaning only at the end of the regular expression, or before @samp{\)} -or @samp{\|}. - -@item @kbd{\} -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -See the following section for the special constructs that begin -with @samp{\}. -@end table - - Note: for historical compatibility, special characters are treated as -ordinary ones if they are in contexts where their special meanings make no -sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is -no preceding expression on which the @samp{*} can act. It is poor practice -to depend on this behavior; it is better to quote the special character anyway, -regardless of where it appears. - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -@node Regexp Backslash -@section Backslash in Regular Expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: two-character -sequences starting with @samp{\} that have special meanings. The -second character in the sequence is always an ordinary character when -used on its own. Here is a table of @samp{\} constructs. - -@table @kbd -@item \| -specifies an alternative. Two regular expressions @var{a} and @var{b} -with @samp{\|} in between form an expression that matches some text if -either @var{a} matches it or @var{b} matches it. It works by trying to -match @var{a}, and if that fails, by trying to match @var{b}. - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -Full backtracking capability exists to handle multiple uses of @samp{\|}. - -@item \( @dots{} \) -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. -Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{bananana}, etc., with any (zero or more) number of @samp{na} -strings.@refill - -@item -To record a matched substring for future reference. -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that is assigned as a -second meaning to the same @samp{\( @dots{} \)} construct. In practice -there is usually no conflict between the two meanings; when there is -a conflict, you can use a ``shy'' group. - -@item \(?: @dots{} \) -@cindex shy group, in regexp -specifies a ``shy'' group that does not record the matched substring; -you can't refer back to it with @samp{\@var{d}}. This is useful -in mechanically combining regular expressions, so that you -can add groups for syntactic purposes without interfering with -the numbering of the groups that are meant to be referred to. - -@item \@var{d} -@cindex back reference, in regexp -matches the same text that matched the @var{d}th occurrence of a -@samp{\( @dots{} \)} construct. This is called a @dfn{back -reference}. - -After the end of a @samp{\( @dots{} \)} construct, the matcher remembers -the beginning and end of the text matched by that construct. Then, -later on in the regular expression, you can use @samp{\} followed by the -digit @var{d} to mean ``match the same text matched the @var{d}th time -by the @samp{\( @dots{} \)} construct.'' - -The strings matching the first nine @samp{\( @dots{} \)} constructs -appearing in a regular expression are assigned numbers 1 through 9 in -the order that the open-parentheses appear in the regular expression. -So you can use @samp{\1} through @samp{\9} to refer to the text matched -by the corresponding @samp{\( @dots{} \)} constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a particular @samp{\( @dots{} \)} construct matches more than once -(which can easily happen if it is followed by @samp{*}), only the last -match is recorded. - -@item \` -matches the empty string, but only at the beginning of the string or -buffer (or its accessible portion) being matched against. - -@item \' -matches the empty string, but only at the end of the string or buffer -(or its accessible portion) being matched against. - -@item \= -matches the empty string, but only at point. - -@item \b -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@samp{\b} matches at the beginning or end of the buffer -regardless of what text appears next to it. - -@item \B -matches the empty string, but @emph{not} at the beginning or -end of a word. - -@item \< -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer only if a -word-constituent character follows. - -@item \> -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer only if the contents end with a -word-constituent character. - -@item \w -matches any word-constituent character. The syntax table -determines which characters these are. @xref{Syntax}. - -@item \W -matches any character that is not a word-constituent. - -@item \_< -matches the empty string, but only at the beginning of a symbol. -A symbol is a sequence of one or more symbol-constituent characters. -A symbol-constituent character is a character whose syntax is either -@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the -buffer only if a symbol-constituent character follows. - -@item \_> -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer only if the contents end with a -symbol-constituent character. - -@item \s@var{c} -matches any character whose syntax is @var{c}. Here @var{c} is a -character that designates a particular syntax class: thus, @samp{w} -for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} -for ordinary punctuation, etc. @xref{Syntax}. - -@item \S@var{c} -matches any character whose syntax is not @var{c}. - -@cindex categories of characters -@cindex characters which belong to a specific language -@findex describe-categories -@item \c@var{c} -matches any character that belongs to the category @var{c}. For -example, @samp{\cc} matches Chinese characters, @samp{\cg} matches -Greek characters, etc. For the description of the known categories, -type @kbd{M-x describe-categories @key{RET}}. - -@item \C@var{c} -matches any character that does @emph{not} belong to category -@var{c}. -@end table - - The constructs that pertain to words and syntax are controlled by the -setting of the syntax table (@pxref{Syntax}). - -@node Regexp Example -@section Regular Expression Example - - Here is a complicated regexp---a simplified version of the regexp -that Emacs uses, by default, to recognize the end of a sentence -together with any whitespace that follows. We show its Lisp syntax to -distinguish the spaces from the tab characters. In Lisp syntax, the -string constant begins and ends with a double-quote. @samp{\"} stands -for a double-quote as part of the regexp, @samp{\\} for a backslash as -part of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline. - -@example -"[.?!][]\"')]*\\($\\| $\\|\t\\| \\)[ \t\n]*" -@end example - -@noindent -This contains four parts in succession: a character set matching -period, @samp{?}, or @samp{!}; a character set matching -close-brackets, quotes, or parentheses, repeated zero or more times; a -set of alternatives within backslash-parentheses that matches either -end-of-line, a space at the end of a line, a tab, or two spaces; and a -character set matching whitespace characters, repeated any number of -times. - - To enter the same regexp in incremental search, you would type -@key{TAB} to enter a tab, and @kbd{C-j} to enter a newline. You would -also type single backslashes as themselves, instead of doubling them -for Lisp syntax. In commands that use ordinary minibuffer input to -read a regexp, you would quote the @kbd{C-j} by preceding it with a -@kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer. - -@node Search Case -@section Searching and Case - - Incremental searches in Emacs normally ignore the case of the text -they are searching through, if you specify the text in lower case. -Thus, if you specify searching for @samp{foo}, then @samp{Foo} and -@samp{foo} are also considered a match. Regexps, and in particular -character sets, are included: @samp{[ab]} would match @samp{a} or -@samp{A} or @samp{b} or @samp{B}.@refill - - An upper-case letter anywhere in the incremental search string makes -the search case-sensitive. Thus, searching for @samp{Foo} does not find -@samp{foo} or @samp{FOO}. This applies to regular expression search as -well as to string search. The effect ceases if you delete the -upper-case letter from the search string. - - Typing @kbd{M-c} within an incremental search toggles the case -sensitivity of that search. The effect does not extend beyond the -current incremental search to the next one, but it does override the -effect of including an upper-case letter in the current search. - -@vindex case-fold-search -@vindex default-case-fold-search - If you set the variable @code{case-fold-search} to @code{nil}, then -all letters must match exactly, including case. This is a per-buffer -variable; altering the variable affects only the current buffer, but -there is a default value in @code{default-case-fold-search} that you -can also set. @xref{Locals}. This variable applies to nonincremental -searches also, including those performed by the replace commands -(@pxref{Replace}) and the minibuffer history matching commands -(@pxref{Minibuffer History}). - - Several related variables control case-sensitivity of searching and -matching for specific commands or activities. For instance, -@code{tags-case-fold-search} controls case sensitivity for -@code{find-tag}. To find these variables, do @kbd{M-x -apropos-variable @key{RET} case-fold-search @key{RET}}. - -@node Replace -@section Replacement Commands -@cindex replacement -@cindex search-and-replace commands -@cindex string substitution -@cindex global substitution - - Global search-and-replace operations are not needed often in Emacs, -but they are available. In addition to the simple @kbd{M-x -replace-string} command which replaces all occurrences, -there is @kbd{M-%} (@code{query-replace}), which presents each occurrence -of the pattern and asks you whether to replace it. - - The replace commands normally operate on the text from point to the -end of the buffer; however, in Transient Mark mode (@pxref{Transient -Mark}), when the mark is active, they operate on the region. The -basic replace commands replace one string (or regexp) with one -replacement string. It is possible to perform several replacements in -parallel using the command @code{expand-region-abbrevs} -(@pxref{Expanding Abbrevs}). - -@menu -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. -@end menu - -@node Unconditional Replace, Regexp Replace, Replace, Replace -@subsection Unconditional Replacement -@findex replace-string - -@table @kbd -@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} -Replace every occurrence of @var{string} with @var{newstring}. -@end table - - To replace every instance of @samp{foo} after point with @samp{bar}, -use the command @kbd{M-x replace-string} with the two arguments -@samp{foo} and @samp{bar}. Replacement happens only in the text after -point, so if you want to cover the whole buffer you must go to the -beginning first. All occurrences up to the end of the buffer are -replaced; to limit replacement to part of the buffer, narrow to that -part of the buffer before doing the replacement (@pxref{Narrowing}). -In Transient Mark mode, when the region is active, replacement is -limited to the region (@pxref{Transient Mark}). - - When @code{replace-string} exits, it leaves point at the last -occurrence replaced. It sets the mark to the prior position of point -(where the @code{replace-string} command was issued); use @kbd{C-u -C-@key{SPC}} to move back there. - - A numeric argument restricts replacement to matches that are surrounded -by word boundaries. The argument's value doesn't matter. - - @xref{Replacement and Case}, for details about case-sensitivity in -replace commands. - - What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa? You can do it this way: - -@example -M-x replace-string @key{RET} x @key{RET} @@TEMP@@ @key{RET} -M-< M-x replace-string @key{RET} y @key{RET} x @key{RET} -M-< M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET} -@end example - -@noindent -This works provided the string @samp{@@TEMP@@} does not appear -in your text. - -@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace -@subsection Regexp Replacement -@findex replace-regexp - - The @kbd{M-x replace-string} command replaces exact matches for a -single string. The similar command @kbd{M-x replace-regexp} replaces -any match for a specified pattern. - -@table @kbd -@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace every match for @var{regexp} with @var{newstring}. -@end table - -@cindex back reference, in regexp replacement - In @code{replace-regexp}, the @var{newstring} need not be constant: -it can refer to all or part of what is matched by the @var{regexp}. -@samp{\&} in @var{newstring} stands for the entire match being -replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a -digit, stands for whatever matched the @var{d}th parenthesized -grouping in @var{regexp}. (This is called a ``back reference.'') -@samp{\#} refers to the count of replacements already made in this -command, as a decimal number. In the first replacement, @samp{\#} -stands for @samp{0}; in the second, for @samp{1}; and so on. For -example, - -@example -M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} -@end example - -@noindent -replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} -with @samp{cddr-safe}. - -@example -M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} -@end example - -@noindent -performs the inverse transformation. To include a @samp{\} in the -text to replace with, you must enter @samp{\\}. - - If you want to enter part of the replacement string by hand each -time, use @samp{\?} in the replacement string. Each replacement will -ask you to edit the replacement string in the minibuffer, putting -point where the @samp{\?} was. - - The remainder of this subsection is intended for specialized tasks -and requires knowledge of Lisp. Most readers can skip it. - - You can use Lisp expressions to calculate parts of the -replacement string. To do this, write @samp{\,} followed by the -expression in the replacement string. Each replacement calculates the -value of the expression and converts it to text without quoting (if -it's a string, this means using the string's contents), and uses it in -the replacement string in place of the expression itself. If the -expression is a symbol, one space in the replacement string after the -symbol name goes with the symbol name, so the value replaces them -both. - - Inside such an expression, you can use some special sequences. -@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire -match as a string, and to a submatch as a string. @var{n} may be -multiple digits, and the value of @samp{\@var{n}} is @code{nil} if -subexpression @var{n} did not match. You can also use @samp{\#&} and -@samp{\#@var{n}} to refer to those matches as numbers (this is valid -when the match or submatch has the form of a numeral). @samp{\#} here -too stands for the number of already-completed replacements. - - Repeating our example to exchange @samp{x} and @samp{y}, we can thus -do it also this way: - -@example -M-x replace-regexp @key{RET} \(x\)\|y @key{RET} -\,(if \1 "y" "x") @key{RET} -@end example - - For computing replacement strings for @samp{\,}, the @code{format} -function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). For example, to add consecutively numbered -strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are -already occupied), you can use - -@example -M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} -\,(format "%-72sABC%05d" \& \#) @key{RET} -@end example - -@node Replacement and Case, Query Replace, Regexp Replace, Replace -@subsection Replace Commands and Case - - If the first argument of a replace command is all lower case, the -command ignores case while searching for occurrences to -replace---provided @code{case-fold-search} is non-@code{nil}. If -@code{case-fold-search} is set to @code{nil}, case is always significant -in all searches. - -@vindex case-replace - In addition, when the @var{newstring} argument is all or partly lower -case, replacement commands try to preserve the case pattern of each -occurrence. Thus, the command - -@example -M-x replace-string @key{RET} foo @key{RET} bar @key{RET} -@end example - -@noindent -replaces a lower case @samp{foo} with a lower case @samp{bar}, an -all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with -@samp{Bar}. (These three alternatives---lower case, all caps, and -capitalized, are the only ones that @code{replace-string} can -distinguish.) - - If upper-case letters are used in the replacement string, they remain -upper case every time that text is inserted. If upper-case letters are -used in the first argument, the second argument is always substituted -exactly as given, with no case conversion. Likewise, if either -@code{case-replace} or @code{case-fold-search} is set to @code{nil}, -replacement is done without case conversion. - -@node Query Replace,, Replacement and Case, Replace -@subsection Query Replace -@cindex query replace - -@table @kbd -@item M-% @var{string} @key{RET} @var{newstring} @key{RET} -@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} -Replace some occurrences of @var{string} with @var{newstring}. -@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} -@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace some matches for @var{regexp} with @var{newstring}. -@end table - -@kindex M-% -@findex query-replace - If you want to change only some of the occurrences of @samp{foo} to -@samp{bar}, not all of them, then you cannot use an ordinary -@code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}). -This command finds occurrences of @samp{foo} one by one, displays each -occurrence and asks you whether to replace it. Aside from querying, -@code{query-replace} works just like @code{replace-string}. It -preserves case, like @code{replace-string}, provided -@code{case-replace} is non-@code{nil}, as it normally is -(@pxref{Replacement and Case}). A numeric argument means consider -only occurrences that are bounded by word-delimiter characters. - -@kindex C-M-% -@findex query-replace-regexp - @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). -It works like @code{replace-regexp} except that it queries -like @code{query-replace}. - -@cindex faces for highlighting query replace - These commands highlight the current match using the face -@code{query-replace}. They highlight other matches using -@code{lazy-highlight} just like incremental search (@pxref{Incremental -Search}). - - The characters you can type when you are shown a match for the string -or regexp are: - -@ignore @c Not worth it. -@kindex SPC @r{(query-replace)} -@kindex DEL @r{(query-replace)} -@kindex , @r{(query-replace)} -@kindex RET @r{(query-replace)} -@kindex . @r{(query-replace)} -@kindex ! @r{(query-replace)} -@kindex ^ @r{(query-replace)} -@kindex C-r @r{(query-replace)} -@kindex C-w @r{(query-replace)} -@kindex C-l @r{(query-replace)} -@end ignore - -@c WideCommands -@table @kbd -@item @key{SPC} -to replace the occurrence with @var{newstring}. - -@item @key{DEL} -to skip to the next occurrence without replacing this one. - -@item , @r{(Comma)} -to replace this occurrence and display the result. You are then asked -for another input character to say what to do next. Since the -replacement has already been made, @key{DEL} and @key{SPC} are -equivalent in this situation; both move to the next occurrence. - -You can type @kbd{C-r} at this point (see below) to alter the replaced -text. You can also type @kbd{C-x u} to undo the replacement; this exits -the @code{query-replace}, so if you want to do further replacement you -must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart -(@pxref{Repetition}). - -@item @key{RET} -to exit without doing any more replacements. - -@item .@: @r{(Period)} -to replace this occurrence and then exit without searching for more -occurrences. - -@item ! -to replace all remaining occurrences without asking again. - -@item ^ -to go back to the position of the previous occurrence (or what used to -be an occurrence), in case you changed it by mistake or want to -reexamine it. - -@item C-r -to enter a recursive editing level, in case the occurrence needs to be -edited rather than just replaced with @var{newstring}. When you are -done, exit the recursive editing level with @kbd{C-M-c} to proceed to -the next occurrence. @xref{Recursive Edit}. - -@item C-w -to delete the occurrence, and then enter a recursive editing level as in -@kbd{C-r}. Use the recursive edit to insert text to replace the deleted -occurrence of @var{string}. When done, exit the recursive editing level -with @kbd{C-M-c} to proceed to the next occurrence. - -@item e -to edit the replacement string in the minibuffer. When you exit the -minibuffer by typing @key{RET}, the minibuffer contents replace the -current occurrence of the pattern. They also become the new -replacement string for any further occurrences. - -@item C-l -to redisplay the screen. Then you must type another character to -specify what to do with this occurrence. - -@item C-h -to display a message summarizing these options. Then you must type -another character to specify what to do with this occurrence. -@end table - - Some other characters are aliases for the ones listed above: @kbd{y}, -@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and -@key{RET}. - - Aside from this, any other character exits the @code{query-replace}, -and is then reread as part of a key sequence. Thus, if you type -@kbd{C-k}, it exits the @code{query-replace} and then kills to end of -line. - - To restart a @code{query-replace} once it is exited, use @kbd{C-x -@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it -used the minibuffer to read its arguments. @xref{Repetition, C-x ESC -ESC}. - - @xref{Operating on Files}, for the Dired @kbd{Q} command which -performs query replace on selected files. See also @ref{Transforming -File Names}, for Dired commands to rename, copy, or link files by -replacing regexp matches in file names. - -@node Other Repeating Search -@section Other Search-and-Loop Commands - - Here are some other commands that find matches for a regular -expression. They all ignore case in matching, if the pattern contains -no upper-case letters and @code{case-fold-search} is non-@code{nil}. -Aside from @code{occur} and its variants, all operate on the text from -point to the end of the buffer, or on the active region in Transient -Mark mode. - -@findex list-matching-lines -@findex occur -@findex multi-occur -@findex multi-occur-in-matching-buffers -@findex how-many -@findex delete-non-matching-lines -@findex delete-matching-lines -@findex flush-lines -@findex keep-lines - -@table @kbd -@item M-x occur @key{RET} @var{regexp} @key{RET} -Display a list showing each line in the buffer that contains a match -for @var{regexp}. To limit the search to part of the buffer, narrow -to that part (@pxref{Narrowing}). A numeric argument @var{n} -specifies that @var{n} lines of context are to be displayed before and -after each matching line. Currently, @code{occur} can not correctly -handle multiline matches. - -@kindex RET @r{(Occur mode)} -@kindex o @r{(Occur mode)} -@kindex C-o @r{(Occur mode)} -The buffer @samp{*Occur*} containing the output serves as a menu for -finding the occurrences in their original context. Click -@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position -point there and type @key{RET}; this switches to the buffer that was -searched and moves point to the original of the chosen occurrence. -@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} -does not select it. - -After using @kbd{M-x occur}, you can use @code{next-error} to visit -the occurrences found, one by one. @ref{Compilation Mode}. - -@item M-x list-matching-lines -Synonym for @kbd{M-x occur}. - -@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET} -This function is just like @code{occur}, except it is able to search -through multiple buffers. It asks you to specify the buffer names one by one. - -@item M-x multi-occur-in-matching-buffers @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET} -This function is similar to @code{multi-occur}, except the buffers to -search are specified by a regular expression that matches visited -file names. With a prefix argument, it uses the regular expression to match -buffer names instead. - -@item M-x how-many @key{RET} @var{regexp} @key{RET} -Print the number of matches for @var{regexp} that exist in the buffer -after point. In Transient Mark mode, if the region is active, the -command operates on the region instead. - -@item M-x flush-lines @key{RET} @var{regexp} @key{RET} -This command deletes each line that contains a match for @var{regexp}, -operating on the text after point; it deletes the current line -if it contains a match starting after point. In Transient Mark mode, -if the region is active, the command operates on the region instead; -it deletes a line partially contained in the region if it contains a -match entirely contained in the region. - -If a match is split across lines, @code{flush-lines} deletes all those -lines. It deletes the lines before starting to look for the next -match; hence, it ignores a match starting on the same line at which -another match ended. - -@item M-x keep-lines @key{RET} @var{regexp} @key{RET} -This command deletes each line that @emph{does not} contain a match for -@var{regexp}, operating on the text after point; if point is not at the -beginning of a line, it always keeps the current line. In Transient -Mark mode, if the region is active, the command operates on the region -instead; it never deletes lines that are only partially contained in -the region (a newline that ends a line counts as part of that line). - -If a match is split across lines, this command keeps all those lines. -@end table - -@ignore - arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e -@end ignore diff --git a/man/sending.texi b/man/sending.texi deleted file mode 100644 index 5d6a7c83f3e..00000000000 --- a/man/sending.texi +++ /dev/null @@ -1,724 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Sending Mail -@chapter Sending Mail -@cindex sending mail -@cindex mail -@cindex message - - To send a message in Emacs, you start by typing a command (@kbd{C-x m}) -to select and initialize the @samp{*mail*} buffer. Then you edit the text -and headers of the message in this buffer, and type another command -(@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message. - -@table @kbd -@item C-x m -Begin composing a message to send (@code{compose-mail}). -@item C-x 4 m -Likewise, but display the message in another window -(@code{compose-mail-other-window}). -@item C-x 5 m -Likewise, but make a new frame (@code{compose-mail-other-frame}). -@item C-c C-s -In Mail mode, send the message (@code{mail-send}). -@item C-c C-c -Send the message and bury the mail buffer (@code{mail-send-and-exit}). -@end table - -@kindex C-x m -@findex compose-mail -@kindex C-x 4 m -@findex compose-mail-other-window -@kindex C-x 5 m -@findex compose-mail-other-frame - The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named -@samp{*mail*} and initializes it with the skeleton of an outgoing -message. @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the -@samp{*mail*} buffer in a different window, leaving the previous current -buffer visible. @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates -a new frame to select the @samp{*mail*} buffer. - - Because the mail-composition buffer is an ordinary Emacs buffer, you can -switch to other buffers while in the middle of composing mail, and switch -back later (or never). If you use the @kbd{C-x m} command again when you -have been composing another message but have not sent it, you are asked to -confirm before the old message is erased. If you answer @kbd{n}, the -@samp{*mail*} buffer remains selected with its old contents, so you can -finish the old message and send it. @kbd{C-u C-x m} is another way to do -this. Sending the message marks the @samp{*mail*} buffer ``unmodified,'' -which avoids the need for confirmation when @kbd{C-x m} is next used. - - If you are composing a message in the @samp{*mail*} buffer and want to -send another message before finishing the first, rename the -@samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc -Buffer}). Then you can use @kbd{C-x m} or its variants described above -to make a new @samp{*mail*} buffer. Once you've done that, you can work -with each mail buffer independently. - -@vindex mail-default-directory - The variable @code{mail-default-directory} controls the default -directory for mail buffers, and also says where to put their auto-save -files. - -@ignore -@c Commented out because it is not user-oriented; -@c it doesn't say how to do some job. -- rms. -@cindex directory servers -@cindex LDAP -@cindex PH/QI -@cindex names and addresses -There is an interface to directory servers using various protocols such -as LDAP or the CCSO white pages directory system (PH/QI), described in a -separate manual. It may be useful for looking up names and addresses. -@xref{Top,,EUDC, eudc, EUDC Manual}. -@end ignore - -@menu -* Format: Mail Format. Format of the mail being composed. -* Headers: Mail Headers. Details of permitted mail header fields. -* Aliases: Mail Aliases. Abbreviating and grouping mail addresses. -* Mode: Mail Mode. Special commands for editing mail being composed. -* Amuse: Mail Amusements. Distracting the NSA; adding fortune messages. -* Methods: Mail Methods. Using alternative mail-composition methods. -@end menu - -@node Mail Format -@section The Format of the Mail Buffer - - In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header -fields} which say who sent it, when, to whom, why, and so on. Some -header fields, such as @samp{Date} and @samp{Sender}, are created -automatically when you send the message. Others, such as the recipient -names, must be specified by you in order to send the message properly. - - In the mail buffer, you can insert and edit header fields using -ordinary editing commands. Mail mode provides a commands to help you -edit some header fields, and some are preinitialized in the buffer -automatically when appropriate. - - The line in the buffer that says - -@example ---text follows this line-- -@end example - -@noindent -is a special delimiter that separates the headers you have specified from -the text. Whatever follows this line is the text of the message; the -headers precede it. The delimiter line itself does not appear in the -message actually sent. The text used for the delimiter line is controlled -by the variable @code{mail-header-separator}. - - Here is an example of what the headers and text in the mail buffer -might look like. - -@example -To: gnu@@gnu.org -CC: lungfish@@spam.org, byob@@spam.org -Subject: The Emacs Manual ---Text follows this line-- -Please ignore this message. -@end example - -@node Mail Headers -@section Mail Header Fields -@cindex headers (of mail message) - - A header field in the mail buffer starts with a field name at the -beginning of a line, terminated by a colon. Upper and lower case are -equivalent in field names (and in mailing addresses also). After the -colon and optional whitespace comes the contents of the field. - - You can use any name you like for a header field, but normally people -use only standard field names with accepted meanings. Here is a table -of fields commonly used in outgoing messages. - -@table @samp -@item To -This field contains the mailing addresses to which the message is -addressed. If you list more than one address, use commas, not spaces, -to separate them. - -@item Subject -The contents of the @samp{Subject} field should be a piece of text -that says what the message is about. The reason @samp{Subject} fields -are useful is that most mail-reading programs can provide a summary of -messages, listing the subject of each message but not its text. - -@item CC -This field contains additional mailing addresses to send the message to, -like @samp{To} except that these readers should not regard the message -as directed at them. - -@item BCC -This field contains additional mailing addresses to send the message to, -which should not appear in the header of the message actually sent. -Copies sent this way are called @dfn{blind carbon copies}. - -@vindex mail-self-blind -@cindex copy of every outgoing message -To send a blind carbon copy of every outgoing message to yourself, set -the variable @code{mail-self-blind} to @code{t}. To send a blind carbon -copy of every message to some other @var{address}, set the variable -@code{mail-default-headers} to @code{"Bcc: @var{address}\n"}. - -@item FCC -This field contains the name of one file and directs Emacs to append a -copy of the message to that file when you send the message. If the file -is in Rmail format, Emacs writes the message in Rmail format; otherwise, -Emacs writes the message in system mail file format. To specify -more than one file, use several @samp{FCC} fields, with one file -name in each field. - -@vindex mail-archive-file-name -To put a fixed file name in the @samp{FCC} field each time you start -editing an outgoing message, set the variable -@code{mail-archive-file-name} to that file name. Unless you remove the -@samp{FCC} field before sending, the message will be written into that -file when it is sent. - -@item From -Use the @samp{From} field to say who you are, when the account you are -using to send the mail is not your own. The contents of the @samp{From} -field should be a valid mailing address, since replies will normally go -there. If you don't specify the @samp{From} field yourself, Emacs uses -the value of @code{user-mail-address} as the default. - -@item Reply-to -Use this field to direct replies to a different address. Most -mail-reading programs (including Rmail) automatically send replies to -the @samp{Reply-to} address in preference to the @samp{From} address. -By adding a @samp{Reply-to} field to your header, you can work around -any problems your @samp{From} address may cause for replies. - -@cindex @env{REPLYTO} environment variable -@vindex mail-default-reply-to -To put a fixed @samp{Reply-to} address into every outgoing message, set -the variable @code{mail-default-reply-to} to that address (as a string). -Then @code{mail} initializes the message with a @samp{Reply-to} field as -specified. You can delete or alter that header field before you send -the message, if you wish. When Emacs starts up, if the environment -variable @env{REPLYTO} is set, @code{mail-default-reply-to} is -initialized from that environment variable. - -@item In-reply-to -This field contains a piece of text describing the message you are -replying to. Some mail systems can use this information to correlate -related pieces of mail. Normally this field is filled in by Rmail -when you reply to a message in Rmail, and you never need to -think about it (@pxref{Rmail}). - -@item References -This field lists the message IDs of related previous messages. Rmail -sets up this field automatically when you reply to a message. -@end table - - The @samp{To}, @samp{CC}, and @samp{BCC} header fields can appear -any number of times, and each such header field can contain multiple -addresses, separated by commas. This way, you can specify any number -of places to send the message. These fields can also have -continuation lines: one or more lines starting with whitespace, -following the starting line of the field, are considered part of the -field. Here's an example of a @samp{To} field with a continuation -line: - -@example -@group -To: foo@@here.net, this@@there.net, - me@@gnu.cambridge.mass.usa.earth.spiral3281 -@end group -@end example - -@vindex mail-from-style - When you send the message, if you didn't write a @samp{From} field -yourself, Emacs puts in one for you. The variable -@code{mail-from-style} controls the format: - -@table @code -@item nil -Use just the email address, as in @samp{king@@grassland.com}. -@item parens -Use both email address and full name, as in:@* -@samp{king@@grassland.com (Elvis Parsley)}. -@item angles -Use both email address and full name, as in:@* -@samp{Elvis Parsley }. -@item system-default -Allow the system to insert the @samp{From} field. -@end table - -@vindex mail-default-headers - You can direct Emacs to insert certain default headers into the -outgoing message by setting the variable @code{mail-default-headers} -to a string. Then @code{C-x m} inserts this string into the message -headers. If the default header fields are not appropriate for a -particular message, edit them as appropriate before sending the -message. - -@node Mail Aliases -@section Mail Aliases -@cindex mail aliases -@cindex @file{.mailrc} file -@cindex mailrc file - - You can define @dfn{mail aliases} in a file named @file{~/.mailrc}. -These are short mnemonic names which stand for mail addresses or groups of -mail addresses. Like many other mail programs, Emacs expands aliases -when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and -@samp{Reply-to} fields, plus their @samp{Resent-} variants. - - To define an alias in @file{~/.mailrc}, write a line in the following -format: - -@example -alias @var{shortaddress} @var{fulladdresses} -@end example - -@noindent -Here @var{fulladdresses} stands for one or more mail addresses for -@var{shortaddress} to expand into. Separate multiple addresses with -spaces; if an address contains a space, quote the whole address with a -pair of double-quotes. - -For instance, to make @code{maingnu} stand for -@code{gnu@@gnu.org} plus a local address of your own, put in -this line:@refill - -@example -alias maingnu gnu@@gnu.org local-gnu -@end example - -@noindent -Addresses specified in this way should use doublequotes around an -entire address when the address contains spaces. But you need not -include doublequotes around parts of the address, such as the person's -full name. Emacs puts them in if they are needed. For example, - -@example -alias chief-torturer "George W. Bush " -@end example - -@noindent -is correct in @samp{.mailrc}. Emacs will insert the address as -@samp{"George W. Bush" }. - - Emacs also recognizes ``include'' commands in @samp{.mailrc} files. -They look like this: - -@example -source @var{filename} -@end example - -@noindent -The file @file{~/.mailrc} is used primarily by other mail-reading -programs; it can contain various other commands. Emacs ignores -everything in it except for alias definitions and include commands. - -@findex define-mail-alias - Another way to define a mail alias, within Emacs alone, is with the -@code{define-mail-alias} command. It prompts for the alias and then the -full address. You can use it to define aliases in your @file{.emacs} -file, like this: - -@example -(define-mail-alias "maingnu" "gnu@@gnu.org") -@end example - -@vindex mail-aliases - @code{define-mail-alias} records aliases by adding them to a -variable named @code{mail-aliases}. If you are comfortable with -manipulating Lisp lists, you can set @code{mail-aliases} directly. The -initial value of @code{mail-aliases} is @code{t}, which means that -Emacs should read @file{.mailrc} to get the proper value. - -@vindex mail-personal-alias-file - You can specify a different file name to use instead of -@file{~/.mailrc} by setting the variable -@code{mail-personal-alias-file}. - -@findex expand-mail-aliases - Normally, Emacs expands aliases when you send the message. You do not -need to expand mail aliases before sending the message, but you can -expand them if you want to see where the mail will actually go. To do -this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail -aliases currently present in the mail headers that hold addresses. - - If you like, you can have mail aliases expand as abbrevs, as soon as -you type them in (@pxref{Abbrevs}). To enable this feature, execute the -following: - -@example -(add-hook 'mail-mode-hook 'mail-abbrevs-setup) -@end example - -@noindent -@findex define-mail-abbrev -@vindex mail-abbrevs -This can go in your @file{.emacs} file. @xref{Hooks}. If you use this -feature, you must use @code{define-mail-abbrev} instead of -@code{define-mail-alias}; the latter does not work with this package. -Note that the mail abbreviation package uses the variable -@code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias -names are converted to lower case. - -@kindex C-c C-a @r{(Mail mode)} -@findex mail-interactive-insert-alias - The mail abbreviation package also provides the @kbd{C-c C-a} -(@code{mail-interactive-insert-alias}) command, which reads an alias -name (with completion) and inserts its definition at point. This is -useful when editing the message text itself or a header field such as -@samp{Subject} in which Emacs does not normally expand aliases. - - Note that abbrevs expand only if you insert a word-separator character -afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause -expansion as well. Here's how to do that: - -@smallexample -(add-hook 'mail-mode-hook - (lambda () - (define-key - mail-mode-map [remap next-line] 'mail-abbrev-next-line) - (define-key - mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer))) -@end smallexample - -@node Mail Mode -@section Mail Mode -@cindex Mail mode -@cindex mode, Mail - - The major mode used in the mail buffer is Mail mode, which is much -like Text mode except that various special commands are provided on the -@kbd{C-c} prefix. These commands all have to do specifically with -editing or sending the message. In addition, Mail mode defines the -character @samp{%} as a word separator; this is helpful for using the -word commands to edit mail addresses. - - Mail mode is normally used in buffers set up automatically by the -@code{mail} command and related commands. However, you can also switch -to Mail mode in a file-visiting buffer. This is a useful thing to do if -you have saved the text of a draft message in a file. - -@menu -* Mail Sending:: Commands to send the message. -* Header Editing:: Commands to move to header fields and edit them. -* Citing Mail:: Copying all or part of a message you are replying to. -* Mail Mode Misc:: Spell checking, signatures, etc. -@end menu - -@node Mail Sending -@subsection Mail Sending - - Mail mode has two commands for sending the message you have been -editing: - -@table @kbd -@item C-c C-s -Send the message, and leave the mail buffer selected (@code{mail-send}). -@item C-c C-c -Send the message, and select some other buffer (@code{mail-send-and-exit}). -@end table - -@kindex C-c C-s @r{(Mail mode)} -@kindex C-c C-c @r{(Mail mode)} -@findex mail-send -@findex mail-send-and-exit - @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail -buffer unmodified, but leaves that buffer selected so that you can -modify the message (perhaps with new recipients) and send it again. -@kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the -window or switches to another buffer. It puts the mail buffer at the -lowest priority for reselection by default, since you are finished with -using it. This is the usual way to send the message. - - In a file-visiting buffer, sending the message does not clear the -modified flag, because only saving the file should do that. Also, you -don't get a warning if you try to send the same message twice. - -@c This is indexed in mule.texi, node "Recognize Coding". -@c @vindex sendmail-coding-system - When you send a message that contains non-@acronym{ASCII} characters, they need -to be encoded with a coding system (@pxref{Coding Systems}). Usually -the coding system is specified automatically by your chosen language -environment (@pxref{Language Environments}). You can explicitly specify -the coding system for outgoing mail by setting the variable -@code{sendmail-coding-system} (@pxref{Recognize Coding}). - - If the coding system thus determined does not handle the characters in -a particular message, Emacs asks you to select the coding system to use, -showing a list of possible coding systems. - -@cindex SMTP -@cindex Feedmail -@cindex Sendmail -@vindex send-mail-function - The variable @code{send-mail-function} controls how the default mail -user agent sends mail. It should be set to a function. The default -is @code{sendmail-send-it}, which delivers mail using the Sendmail -installation on the local host. To send mail through a SMTP server, -set it to @code{smtpmail-send-it} and set up the Emacs SMTP library -(@pxref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}). A -third option is @code{feedmail-send-it}, see the commentary section of -the @file{feedmail.el} package for more information. - -@node Header Editing -@subsection Mail Header Editing - - Mail mode provides special commands to move to particular header -fields and to complete addresses in headers. - -@table @kbd -@item C-c C-f C-t -Move to the @samp{To} header field, creating one if there is none -(@code{mail-to}). -@item C-c C-f C-s -Move to the @samp{Subject} header field, creating one if there is -none (@code{mail-subject}). -@item C-c C-f C-c -Move to the @samp{CC} header field, creating one if there is none -(@code{mail-cc}). -@item C-c C-f C-b -Move to the @samp{BCC} header field, creating one if there is none -(@code{mail-bcc}). -@item C-c C-f C-f -Move to the @samp{FCC} header field, creating one if there is none -(@code{mail-fcc}). -@item M-@key{TAB} -Complete a mailing address (@code{mail-complete}). -@end table - -@kindex C-c C-f C-t @r{(Mail mode)} -@findex mail-to -@kindex C-c C-f C-s @r{(Mail mode)} -@findex mail-subject -@kindex C-c C-f C-c @r{(Mail mode)} -@findex mail-cc -@kindex C-c C-f C-b @r{(Mail mode)} -@findex mail-bcc -@kindex C-c C-f C-f @r{(Mail mode)} -@findex mail-fcc - There are five commands to move point to particular header fields, all -based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They -are listed in the table above. If the field in question does not exist, -these commands create one. We provide special motion commands for these -particular fields because they are the fields users most often want to -edit. - -@findex mail-complete -@kindex M-TAB @r{(Mail mode)} - While editing a header field that contains mailing addresses, such -as @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing -address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It -inserts the full name corresponding to the address, if it can -determine the full name. The variable @code{mail-complete-style} -controls whether to insert the full name, and what style to use, as in -@code{mail-from-style} (@pxref{Mail Headers}). (If your window -manager defines @kbd{M-@key{TAB}} to switch windows, you can type -@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) - - For completion purposes, the valid mailing addresses are taken to be -the local users' names plus your personal mail aliases. You can -specify additional sources of valid addresses; see the customization -group @samp{mailalias} to see the variables for customizing this -feature (@pxref{Customization Groups}). - - If you type @kbd{M-@key{TAB}} in the body of the message, -@code{mail-complete} invokes @code{ispell-complete-word}, as in Text -mode. - -@node Citing Mail -@subsection Citing Mail -@cindex citing mail - - Mail mode also has commands for yanking or @dfn{citing} all or part of -a message that you are replying to. These commands are active only when -you started sending a message using an Rmail command. - -@table @kbd -@item C-c C-y -Yank the selected message from Rmail (@code{mail-yank-original}). -@item C-c C-r -Yank the region from the Rmail buffer (@code{mail-yank-region}). -@item C-c C-q -Fill each paragraph cited from another message -(@code{mail-fill-yanked-message}). -@end table - -@kindex C-c C-y @r{(Mail mode)} -@findex mail-yank-original - When mail sending is invoked from the Rmail mail reader using an Rmail -command, @kbd{C-c C-y} can be used inside the mail buffer to insert -the text of the message you are replying to. Normally it indents each line -of that message three spaces and eliminates most header fields. A numeric -argument specifies the number of spaces to indent. An argument of just -@kbd{C-u} says not to indent at all and not to eliminate anything. -@kbd{C-c C-y} always uses the current message from the Rmail buffer, -so you can insert several old messages by selecting one in Rmail, -switching to @samp{*mail*} and yanking it, then switching back to -Rmail to select another. - -@vindex mail-yank-prefix - You can specify the text for @kbd{C-c C-y} to insert at the beginning -of each line: set @code{mail-yank-prefix} to the desired string. (A -value of @code{nil} means to use indentation; this is the default.) -However, @kbd{C-u C-c C-y} never adds anything at the beginning of the -inserted lines, regardless of the value of @code{mail-yank-prefix}. - -@kindex C-c C-r @r{(Mail mode)} -@findex mail-yank-region - To yank just a part of an incoming message, set the region in Rmail to -the part you want; then go to the @samp{*Mail*} message and type -@kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is -indented or prefixed according to @code{mail-yank-prefix}. - -@kindex C-c C-q @r{(Mail mode)} -@findex mail-fill-yanked-message - After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q} -(@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked -old message or messages. One use of @kbd{C-c C-q} fills all such -paragraphs, each one individually. To fill a single paragraph of the -quoted message, use @kbd{M-q}. If filling does not automatically -handle the type of citation prefix you use, try setting the fill prefix -explicitly. @xref{Filling}. - -@node Mail Mode Misc -@subsection Mail Mode Miscellany - -@table @kbd -@item C-c C-t -Move to the beginning of the message body text (@code{mail-text}). -@item C-c C-w -Insert the file @file{~/.signature} at the end of the message text -(@code{mail-signature}). -@item C-c C-i @var{file} @key{RET} -Insert the contents of @var{file} at the end of the outgoing message -(@code{mail-attach-file}). -@item M-x ispell-message -Perform spelling correction on the message text, but not on citations from -other messages. -@end table - -@kindex C-c C-t @r{(Mail mode)} -@findex mail-text - @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header -separator line---that is, to the beginning of the message body text. - -@kindex C-c C-w @r{(Mail mode)} -@findex mail-signature -@vindex mail-signature - @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text at -the end of the message to say more about who you are. The text comes -from the file @file{~/.signature} in your home directory. To insert -your signature automatically, set the variable @code{mail-signature} to -@code{t}; after that, starting a mail message automatically inserts the -contents of your @file{~/.signature} file. If you want to omit your -signature from a particular message, delete it from the buffer before -you send the message. - - You can also set @code{mail-signature} to a string; then that string -is inserted automatically as your signature when you start editing a -message to send. If you set it to some other Lisp expression, the -expression is evaluated each time, and its value (which should be a -string) specifies the signature. - -@findex ispell-message - You can do spelling correction on the message text you have written -with the command @kbd{M-x ispell-message}. If you have yanked an -incoming message into the outgoing draft, this command skips what was -yanked, but it checks the text that you yourself inserted. (It looks -for indentation or @code{mail-yank-prefix} to distinguish the cited -lines from your input.) @xref{Spelling}. - -@kindex C-c C-i @r{(Mail mode)} -@findex mail-attach-file - To include a file in the outgoing message, you can use @kbd{C-x i}, -the usual command to insert a file in the current buffer. But it is -often more convenient to use a special command, @kbd{C-c C-i} -(@code{mail-attach-file}). This command inserts the file contents at -the end of the buffer, after your signature if any, with a delimiter -line that includes the file name. Note that this is not a MIME -attachment. - -@vindex mail-mode-hook -@vindex mail-setup-hook - Turning on Mail mode (which @kbd{C-x m} does automatically) runs the -normal hooks @code{text-mode-hook} and @code{mail-mode-hook}. -Initializing a new outgoing message runs the normal hook -@code{mail-setup-hook}; if you want to add special fields to your mail -header or make other changes to the appearance of the mail buffer, use -that hook. @xref{Hooks}. - - The main difference between these hooks is just when they are -invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs -as soon as the @samp{*mail*} buffer is created. Then the -@code{mail-setup} function inserts the default contents of the buffer. -After these default contents are inserted, @code{mail-setup-hook} runs. - -@node Mail Amusements -@section Mail Amusements - -@findex spook -@cindex NSA - @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing -mail message. The keywords are chosen from a list of words that suggest -you are discussing something subversive. - - The idea behind this feature is the suspicion that the -NSA@footnote{The US National Security Agency.} snoops on -all electronic mail messages that contain keywords suggesting they might -find them interesting. (The NSA says they don't, but that's what they -@emph{would} say.) The idea is that if lots of people add suspicious -words to their messages, the NSA will get so busy with spurious input -that they will have to give up reading it all. - - Here's how to insert spook keywords automatically whenever you start -entering an outgoing message: - -@example -(add-hook 'mail-setup-hook 'spook) -@end example - - Whether or not this confuses the NSA, it at least amuses people. - -@findex fortune-to-signature -@cindex fortune cookies - You can use the @code{fortune} program to put a ``fortune cookie'' -message into outgoing mail. To do this, add -@code{fortune-to-signature} to @code{mail-setup-hook}: - -@example -(add-hook 'mail-setup-hook 'fortune-to-signature) -@end example - -@node Mail Methods -@section Mail-Composition Methods -@cindex mail-composition methods - -@cindex MH mail interface -@cindex Message mode for sending mail - In this chapter we have described the usual Emacs mode for editing -and sending mail---Mail mode. Emacs has alternative facilities for -editing and sending mail, including -MH-E and Message mode, not documented in this manual. -@xref{Top,,MH-E,mh-e, The Emacs Interface to MH}. @xref{Top,,Message,message, -Message Manual}. You can choose any of them as your preferred method. -The commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use -whichever agent you have specified, as do various other Emacs commands -and facilities that send mail. - -@vindex mail-user-agent - To specify your mail-composition method, customize the variable -@code{mail-user-agent}. Currently legitimate values include -@code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent}, -@code{message-user-agent} and @code{gnus-user-agent}. - - If you select a different mail-composition method, the information -in this chapter about the @samp{*mail*} buffer and Mail mode does not -apply; the other methods use a different format of text in a different -buffer, and their commands are different as well. - -@ignore - arch-tag: d8a3dfc3-5d87-45c5-a7f2-69871b8e4fd6 -@end ignore diff --git a/man/ses.texi b/man/ses.texi deleted file mode 100644 index 089e13a9cc0..00000000000 --- a/man/ses.texi +++ /dev/null @@ -1,982 +0,0 @@ -\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/man/sieve.texi b/man/sieve.texi deleted file mode 100644 index 4b7a95be952..00000000000 --- a/man/sieve.texi +++ /dev/null @@ -1,369 +0,0 @@ -\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/man/smtpmail.texi b/man/smtpmail.texi deleted file mode 100644 index 644cd061b74..00000000000 --- a/man/smtpmail.texi +++ /dev/null @@ -1,427 +0,0 @@ -\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/man/speedbar.texi b/man/speedbar.texi deleted file mode 100644 index 2a05993f569..00000000000 --- a/man/speedbar.texi +++ /dev/null @@ -1,1261 +0,0 @@ -\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/man/texinfo.tex b/man/texinfo.tex deleted file mode 100644 index fe6285b3bc5..00000000000 --- a/man/texinfo.tex +++ /dev/null @@ -1,8662 +0,0 @@ -% 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/man/text.texi b/man/text.texi deleted file mode 100644 index 3a0e091ea40..00000000000 --- a/man/text.texi +++ /dev/null @@ -1,2901 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Text, Programs, Indentation, Top -@chapter Commands for Human Languages -@cindex text -@cindex manipulating text - - The term @dfn{text} has two widespread meanings in our area of the -computer field. One is data that is a sequence of characters. Any file -that you edit with Emacs is text, in this sense of the word. The other -meaning is more restrictive: a sequence of characters in a human language -for humans to read (possibly after processing by a text formatter), as -opposed to a program or binary data. This chapter is concerned with -editing text in the narrower sense. - - Human languages have syntactic/stylistic conventions that can be -supported or used to advantage by editor commands: conventions involving -words, sentences, paragraphs, and capital letters. This chapter -describes Emacs commands for all of these things. There are also -commands for @dfn{filling}, which means rearranging the lines of a -paragraph to be approximately equal in length. The commands for moving -over and killing words, sentences and paragraphs, while intended -primarily for editing text, are also often useful for editing programs. - - Emacs has several major modes for editing human-language text. If the -file contains text pure and simple, use Text mode, which customizes -Emacs in small ways for the syntactic conventions of text. Outline mode -provides special commands for operating on text with an outline -structure. -@iftex -@xref{Outline Mode}. -@end iftex - - For text which contains embedded commands for text formatters, Emacs -has other major modes, each for a particular formatter. Thus, for -input to @TeX{}, you would use @TeX{} -@iftex -mode (@pxref{TeX Mode,,@TeX{} Mode}). -@end iftex -@ifnottex -mode. -@end ifnottex -For input to groff or nroff, use Nroff mode. - - Instead of using a text formatter, you can edit formatted text in -WYSIWYG style (``what you see is what you get''), with Enriched mode. -Then the formatting appears on the screen in Emacs while you edit. -@iftex -@xref{Formatted Text}. -@end iftex - -@cindex ASCII art - If you need to edit pictures made out of text characters (commonly -referred to as ``ASCII art''), use @kbd{M-x edit-picture} to enter -Picture mode, a special major mode for editing such pictures. -@iftex -@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Picture Mode}. -@end ifnottex - - -@cindex skeletons -@cindex templates -@cindex autotyping -@cindex automatic typing - The ``automatic typing'' features may be useful when writing text. -@inforef{Top,, autotype}. - -@menu -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* TeX Mode:: Editing input to the formatter TeX. -* HTML Mode:: Editing HTML, SGML, and XML files. -* Nroff Mode:: Editing input to the formatter nroff. -* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. -* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. -@end menu - -@node Words -@section Words -@cindex words -@cindex Meta commands and words - - Emacs has commands for moving over or operating on words. By convention, -the keys for them are all Meta characters. - -@table @kbd -@item M-f -Move forward over a word (@code{forward-word}). -@item M-b -Move backward over a word (@code{backward-word}). -@item M-d -Kill up to the end of a word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of a word (@code{backward-kill-word}). -@item M-@@ -Mark the end of the next word (@code{mark-word}). -@item M-t -Transpose two words or drag a word across others -(@code{transpose-words}). -@end table - - Notice how these keys form a series that parallels the character-based -@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is -cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}. - -@kindex M-f -@kindex M-b -@findex forward-word -@findex backward-word - The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b} -(@code{backward-word}) move forward and backward over words. These -Meta characters are thus analogous to the corresponding control -characters, @kbd{C-f} and @kbd{C-b}, which move over single characters -in the text. The analogy extends to numeric arguments, which serve as -repeat counts. @kbd{M-f} with a negative argument moves backward, and -@kbd{M-b} with a negative argument moves forward. Forward motion -stops right after the last letter of the word, while backward motion -stops right before the first letter. - -@kindex M-d -@findex kill-word - @kbd{M-d} (@code{kill-word}) kills the word after point. To be -precise, it kills everything from point to the place @kbd{M-f} would -move to. Thus, if point is in the middle of a word, @kbd{M-d} kills -just the part after point. If some punctuation comes between point and the -next word, it is killed along with the word. (If you wish to kill only the -next word but not the punctuation before it, simply do @kbd{M-f} to get -the end, and kill the word backwards with @kbd{M-@key{DEL}}.) -@kbd{M-d} takes arguments just like @kbd{M-f}. - -@findex backward-kill-word -@kindex M-DEL - @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before -point. It kills everything from point back to where @kbd{M-b} would -move to. For instance, if point is after the space in @w{@samp{FOO, -BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just -@samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead -of @kbd{M-@key{DEL}}. - -@c Don't index M-t and transpose-words here, they are indexed in -@c fixit.texi, in the node "Transpose". -@c @kindex M-t -@c @findex transpose-words - @kbd{M-t} (@code{transpose-words}) exchanges the word before or -containing point with the following word. The delimiter characters between -the words do not move. For example, @w{@samp{FOO, BAR}} transposes into -@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for -more on transposition. - -@kindex M-@@ -@findex mark-word - To operate on the next @var{n} words with an operation which applies -between point and mark, you can either set the mark at point and then move -over the words, or you can use the command @kbd{M-@@} (@code{mark-word}) -which does not move point, but sets the mark where @kbd{M-f} would move -to. @kbd{M-@@} accepts a numeric argument that says how many words to -scan for the place to put the mark. In Transient Mark mode, this command -activates the mark. - - The word commands' understanding of word boundaries is controlled -by the syntax table. Any character can, for example, be declared to -be a word delimiter. @xref{Syntax}. - -@node Sentences -@section Sentences -@cindex sentences -@cindex manipulating sentences - - The Emacs commands for manipulating sentences and paragraphs are mostly -on Meta keys, so as to be like the word-handling commands. - -@table @kbd -@item M-a -Move back to the beginning of the sentence (@code{backward-sentence}). -@item M-e -Move forward to the end of the sentence (@code{forward-sentence}). -@item M-k -Kill forward to the end of the sentence (@code{kill-sentence}). -@item C-x @key{DEL} -Kill back to the beginning of the sentence (@code{backward-kill-sentence}). -@end table - -@kindex M-a -@kindex M-e -@findex backward-sentence -@findex forward-sentence - The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and -@code{forward-sentence}) move to the beginning and end of the current -sentence, respectively. They were chosen to resemble @kbd{C-a} and -@kbd{C-e}, which move to the beginning and end of a line. Unlike -them, @kbd{M-a} and @kbd{M-e} move over successive sentences if -repeated. - - Moving backward over a sentence places point just before the first -character of the sentence; moving forward places point right after the -punctuation that ends the sentence. Neither one moves over the -whitespace at the sentence boundary. - -@kindex M-k -@kindex C-x DEL -@findex kill-sentence -@findex backward-kill-sentence - Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go -with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command -@kbd{M-k} (@code{kill-sentence}) which kills from point to the end of -the sentence. With minus one as an argument it kills back to the -beginning of the sentence. Larger arguments serve as a repeat count. -There is also a command, @kbd{C-x @key{DEL}} -(@code{backward-kill-sentence}), for killing back to the beginning of a -sentence. This command is useful when you change your mind in the -middle of composing text. - - The sentence commands assume that you follow the American typist's -convention of putting two spaces at the end of a sentence; they consider -a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!} -followed by the end of a line or two spaces, with any number of -@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between. -A sentence also begins or ends wherever a paragraph begins or ends. -It is useful to follow this convention, because it makes a distinction -between periods that end a sentence and periods that indicate -abbreviations; that enables the Emacs sentence commands to distinguish, -too. These commands do not stop for periods that indicate abbreviations. - -@vindex sentence-end-double-space - If you want to use just one space between sentences, you can set the -variable @code{sentence-end-double-space} to @code{nil} to make the -sentence commands stop for single spaces. However, this mode has a -drawback: there is no way to distinguish between periods that end -sentences and those that indicate abbreviations. For convenient and -reliable editing, we therefore recommend you follow the two-space -convention. The variable @code{sentence-end-double-space} also -affects filling (@pxref{Fill Commands}) in related ways. - -@vindex sentence-end - The variable @code{sentence-end} controls how to recognize the end -of a sentence. If non-@code{nil}, it is a regexp that matches the -last few characters of a sentence, together with the whitespace -following the sentence. If the value is @code{nil}, the default, then -Emacs computes the regexp according to various criteria such as the -value of @code{sentence-end-double-space}. @xref{Regexp Example}, for -a detailed explanation of one of the regular expressions Emacs uses -for this purpose. - -@vindex sentence-end-without-period - Some languages do not use periods to indicate the end of a sentence. -For example, sentences in Thai end with a double space but without a -period. Set the variable @code{sentence-end-without-period} to -@code{t} in such cases. - -@node Paragraphs -@section Paragraphs -@cindex paragraphs -@cindex manipulating paragraphs -@kindex M-@{ -@kindex M-@} -@findex backward-paragraph -@findex forward-paragraph - - The Emacs commands for manipulating paragraphs are also on Meta keys. - -@table @kbd -@item M-@{ -Move back to previous paragraph beginning (@code{backward-paragraph}). -@item M-@} -Move forward to next paragraph end (@code{forward-paragraph}). -@item M-h -Put point and mark around this or next paragraph (@code{mark-paragraph}). -@end table - - @kbd{M-@{} moves to the beginning of the current or previous -paragraph, while @kbd{M-@}} moves to the end of the current or next -paragraph. Blank lines and text-formatter command lines separate -paragraphs and are not considered part of any paragraph. If there is -a blank line before the paragraph, @kbd{M-@{} moves to the blank line, -because that is convenient in practice. - - In Text mode, an indented line is not a paragraph break. If you -want indented lines to have this effect, use Paragraph-Indent Text -mode instead. @xref{Text Mode}. - - In major modes for programs, paragraphs begin and end only at blank -lines. This makes the paragraph commands useful, even though there -are no paragraphs as such in a program. - - When you have set a fill prefix, then paragraphs are delimited by -all lines which don't start with the fill prefix. @xref{Filling}. - -@kindex M-h -@findex mark-paragraph - When you wish to operate on a paragraph, you can use the command -@kbd{M-h} (@code{mark-paragraph}) to set the region around it. Thus, -for example, @kbd{M-h C-w} kills the paragraph around or after point. -The @kbd{M-h} command puts point at the beginning and mark at the end of -the paragraph point was in. In Transient Mark mode, it activates the -mark. If point is between paragraphs (in a run of blank lines, or at a -boundary), the paragraph following point is surrounded by point and -mark. If there are blank lines preceding the first line of the -paragraph, one of these blank lines is included in the region. - -@vindex paragraph-start -@vindex paragraph-separate - The precise definition of a paragraph boundary is controlled by the -variables @code{paragraph-separate} and @code{paragraph-start}. The -value of @code{paragraph-start} is a regexp that should match any line -that either starts or separates paragraphs. The value of -@code{paragraph-separate} is another regexp that should match only lines -that separate paragraphs without being part of any paragraph (for -example, blank lines). Lines that start a new paragraph and are -contained in it must match only @code{paragraph-start}, not -@code{paragraph-separate}. Each regular expression must match at the -left margin. For example, in Fundamental mode, @code{paragraph-start} -is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is -@w{@code{"[ \t\f]*$"}}. - - Normally it is desirable for page boundaries to separate paragraphs. -The default values of these variables recognize the usual separator for -pages. - -@node Pages -@section Pages - -@cindex pages -@cindex formfeed - Files are often thought of as divided into @dfn{pages} by the -@dfn{formfeed} character (@acronym{ASCII} control-L, octal code 014). -When you print hardcopy for a file, this character forces a page break; -thus, each page of the file goes on a separate page on paper. Most Emacs -commands treat the page-separator character just like any other -character: you can insert it with @kbd{C-q C-l}, and delete it with -@key{DEL}. Thus, you are free to paginate your file or not. However, -since pages are often meaningful divisions of the file, Emacs provides -commands to move over them and operate on them. - -@table @kbd -@item C-x [ -Move point to previous page boundary (@code{backward-page}). -@item C-x ] -Move point to next page boundary (@code{forward-page}). -@item C-x C-p -Put point and mark around this page (or another page) (@code{mark-page}). -@item C-x l -Count the lines in this page (@code{count-lines-page}). -@end table - -@kindex C-x [ -@kindex C-x ] -@findex forward-page -@findex backward-page - The @kbd{C-x [} (@code{backward-page}) command moves point to immediately -after the previous page delimiter. If point is already right after a page -delimiter, it skips that one and stops at the previous one. A numeric -argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page}) -command moves forward past the next page delimiter. - -@kindex C-x C-p -@findex mark-page - The @kbd{C-x C-p} command (@code{mark-page}) puts point at the -beginning of the current page and the mark at the end. The page -delimiter at the end is included (the mark follows it). The page -delimiter at the front is excluded (point follows it). In Transient -Mark mode, this command activates the mark. - - @kbd{C-x C-p C-w} is a handy way to kill a page to move it -elsewhere. If you move to another page delimiter with @kbd{C-x [} and -@kbd{C-x ]}, then yank the killed page, all the pages will be properly -delimited once again. The reason @kbd{C-x C-p} includes only the -following page delimiter in the region is to ensure that. - - A numeric argument to @kbd{C-x C-p} is used to specify which page to go -to, relative to the current one. Zero means the current page. One means -the next page, and @minus{}1 means the previous one. - -@kindex C-x l -@findex count-lines-page - The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding -where to break a page in two. It displays in the echo area the total number -of lines in the current page, and then divides it up into those preceding -the current line and those following, as in - -@example -Page has 96 (72+25) lines -@end example - -@noindent - Notice that the sum is off by one; this is correct if point is not at the -beginning of a line. - -@vindex page-delimiter - The variable @code{page-delimiter} controls where pages begin. Its -value is a regexp that matches the beginning of a line that separates -pages. The normal value of this variable is @code{"^\f"}, which -matches a formfeed character at the beginning of a line. - -@node Filling -@section Filling Text -@cindex filling text - - @dfn{Filling} text means breaking it up into lines that fit a -specified width. Emacs does filling in two ways. In Auto Fill mode, -inserting text with self-inserting characters also automatically fills -it. There are also explicit fill commands that you can use when editing -text leaves it unfilled. When you edit formatted text, you can specify -a style of filling for each portion of the text (@pxref{Formatted -Text}). - -@menu -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented - or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. -* Refill:: Keeping paragraphs filled. -* Longlines:: Editing text with very long lines. -@end menu - -@node Auto Fill -@subsection Auto Fill Mode -@cindex Auto Fill mode -@cindex mode, Auto Fill - - @dfn{Auto Fill} mode is a minor mode in which lines are broken -automatically when they become too wide. Breaking happens only when -you type a @key{SPC} or @key{RET}. - -@table @kbd -@item M-x auto-fill-mode -Enable or disable Auto Fill mode. -@item @key{SPC} -@itemx @key{RET} -In Auto Fill mode, break lines when appropriate. -@end table - -@findex auto-fill-mode - @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off -if it was on. With a positive numeric argument it always turns Auto -Fill mode on, and with a negative argument always turns it off. You can -see when Auto Fill mode is in effect by the presence of the word -@samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is -a minor mode which is enabled or disabled for each buffer individually. -@xref{Minor Modes}. - - In Auto Fill mode, lines are broken automatically at spaces when they -get longer than the desired width. Line breaking and rearrangement -takes place only when you type @key{SPC} or @key{RET}. If you wish to -insert a space or newline without permitting line-breaking, type -@kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a -control-J). Also, @kbd{C-o} inserts a newline without line breaking. - - Auto Fill mode works well with programming-language modes, because it -indents new lines with @key{TAB}. If a line ending in a comment gets -too long, the text of the comment is split into two comment lines. -Optionally, new comment delimiters are inserted at the end of the first -line and the beginning of the second so that each line is a separate -comment; the variable @code{comment-multi-line} controls the choice -(@pxref{Comments}). - - Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as -well as for explicit fill commands. It takes a fill prefix -automatically from the second or first line of a paragraph. - - Auto Fill mode does not refill entire paragraphs; it can break lines but -cannot merge lines. So editing in the middle of a paragraph can result in -a paragraph that is not correctly filled. The easiest way to make the -paragraph properly filled again is usually with the explicit fill commands. -@ifnottex -@xref{Fill Commands}. -@end ifnottex - - Many users like Auto Fill mode and want to use it in all text files. -The section on init files says how to arrange this permanently for yourself. -@xref{Init File}. - -@node Fill Commands -@subsection Explicit Fill Commands - -@table @kbd -@item M-q -Fill current paragraph (@code{fill-paragraph}). -@item C-x f -Set the fill column (@code{set-fill-column}). -@item M-x fill-region -Fill each paragraph in the region (@code{fill-region}). -@item M-x fill-region-as-paragraph -Fill the region, considering it as one paragraph. -@item M-s -Center a line. -@end table - -@kindex M-q -@findex fill-paragraph - To refill a paragraph, use the command @kbd{M-q} -(@code{fill-paragraph}). This operates on the paragraph that point is -inside, or the one after point if point is between paragraphs. -Refilling works by removing all the line-breaks, then inserting new ones -where necessary. - -@findex fill-region - To refill many paragraphs, use @kbd{M-x fill-region}, which -finds the paragraphs in the region and fills each of them. - -@findex fill-region-as-paragraph - @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h} -for finding paragraph boundaries (@pxref{Paragraphs}). For more -control, you can use @kbd{M-x fill-region-as-paragraph}, which refills -everything between point and mark as a single paragraph. This command -deletes any blank lines within the region, so separate blocks of text -end up combined into one block. - -@cindex justification - A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text -as well as filling it. This means that extra spaces are inserted to -make the right margin line up exactly at the fill column. To remove -the extra spaces, use @kbd{M-q} with no argument. (Likewise for -@code{fill-region}.) Another way to control justification, and choose -other styles of filling, is with the @code{justification} text -property; see @ref{Format Justification}. - -@kindex M-s @r{(Text mode)} -@cindex centering -@findex center-line - The command @kbd{M-s} (@code{center-line}) centers the current line -within the current fill column. With an argument @var{n}, it centers -@var{n} lines individually and moves past them. This binding is -made by Text mode and is available only in that and related modes -(@pxref{Text Mode}). - -@vindex fill-column -@kindex C-x f -@findex set-fill-column - The maximum line width for filling is in the variable -@code{fill-column}. Altering the value of @code{fill-column} makes it -local to the current buffer; until that time, the default value is in -effect. The default is initially 70. @xref{Locals}. The easiest way -to set @code{fill-column} is to use the command @kbd{C-x f} -(@code{set-fill-column}). With a numeric argument, it uses that as the -new fill column. With just @kbd{C-u} as argument, it sets -@code{fill-column} to the current horizontal position of point. - - Emacs commands normally consider a period followed by two spaces or by -a newline as the end of a sentence; a period followed by just one space -indicates an abbreviation and not the end of a sentence. To preserve -the distinction between these two ways of using a period, the fill -commands do not break a line after a period followed by just one space. - - If the variable @code{sentence-end-double-space} is @code{nil}, the -fill commands expect and leave just one space at the end of a sentence. -Ordinarily this variable is @code{t}, so the fill commands insist on -two spaces for the end of a sentence, as explained above. @xref{Sentences}. - -@vindex colon-double-space - If the variable @code{colon-double-space} is non-@code{nil}, the -fill commands put two spaces after a colon. - -@vindex fill-nobreak-predicate - The variable @code{fill-nobreak-predicate} is a hook (an abnormal -hook, @pxref{Hooks}) specifying additional conditions where -line-breaking is not allowed. Each function is called with no -arguments, with point at a place where Emacs is considering breaking -the line. If a function returns a non-@code{nil} value, then that's -a bad place to break the line. Two standard functions you can use are -@code{fill-single-word-nobreak-p} (don't break after the first word of -a sentence or before the last) and @code{fill-french-nobreak-p} (don't -break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). - -@node Fill Prefix -@subsection The Fill Prefix - -@cindex fill prefix - To fill a paragraph in which each line starts with a special marker -(which might be a few spaces, giving an indented paragraph), you can use -the @dfn{fill prefix} feature. The fill prefix is a string that Emacs -expects every line to start with, and which is not included in filling. -You can specify a fill prefix explicitly; Emacs can also deduce the -fill prefix automatically (@pxref{Adaptive Fill}). - -@table @kbd -@item C-x . -Set the fill prefix (@code{set-fill-prefix}). -@item M-q -Fill a paragraph using current fill prefix (@code{fill-paragraph}). -@item M-x fill-individual-paragraphs -Fill the region, considering each change of indentation as starting a -new paragraph. -@item M-x fill-nonuniform-paragraphs -Fill the region, considering only paragraph-separator lines as starting -a new paragraph. -@end table - -@kindex C-x . -@findex set-fill-prefix - To specify a fill prefix for the current buffer, move to a line that -starts with the desired prefix, put point at the end of the prefix, -and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period -after the @kbd{C-x}.) To turn off the fill prefix, specify an empty -prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line. - - When a fill prefix is in effect, the fill commands remove the fill -prefix from each line of the paragraph before filling and insert it on -each line after filling. (The beginning of the first line of the -paragraph is left unchanged, since often that is intentionally -different.) Auto Fill mode also inserts the fill prefix automatically -when it makes a new line. The @kbd{C-o} command inserts the fill -prefix on new lines it creates, when you use it at the beginning of a -line (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes -the prefix (if it occurs) after the newline that it deletes -(@pxref{Indentation}). - - For example, if @code{fill-column} is 40 and you set the fill prefix -to @samp{;; }, then @kbd{M-q} in the following text - -@example -;; This is an -;; example of a paragraph -;; inside a Lisp-style comment. -@end example - -@noindent -produces this: - -@example -;; This is an example of a paragraph -;; inside a Lisp-style comment. -@end example - - Lines that do not start with the fill prefix are considered to start -paragraphs, both in @kbd{M-q} and the paragraph commands; this gives -good results for paragraphs with hanging indentation (every line -indented except the first one). Lines which are blank or indented once -the prefix is removed also separate or start paragraphs; this is what -you want if you are writing multi-paragraph comments with a comment -delimiter on each line. - -@findex fill-individual-paragraphs - You can use @kbd{M-x fill-individual-paragraphs} to set the fill -prefix for each paragraph automatically. This command divides the -region into paragraphs, treating every change in the amount of -indentation as the start of a new paragraph, and fills each of these -paragraphs. Thus, all the lines in one ``paragraph'' have the same -amount of indentation. That indentation serves as the fill prefix for -that paragraph. - -@findex fill-nonuniform-paragraphs - @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides -the region into paragraphs in a different way. It considers only -paragraph-separating lines (as defined by @code{paragraph-separate}) as -starting a new paragraph. Since this means that the lines of one -paragraph may have different amounts of indentation, the fill prefix -used is the smallest amount of indentation of any of the lines of the -paragraph. This gives good results with styles that indent a paragraph's -first line more or less that the rest of the paragraph. - -@vindex fill-prefix - The fill prefix is stored in the variable @code{fill-prefix}. Its value -is a string, or @code{nil} when there is no fill prefix. This is a -per-buffer variable; altering the variable affects only the current buffer, -but there is a default value which you can change as well. @xref{Locals}. - - The @code{indentation} text property provides another way to control -the amount of indentation paragraphs receive. @xref{Format Indentation}. - -@node Adaptive Fill -@subsection Adaptive Filling - -@cindex adaptive filling - The fill commands can deduce the proper fill prefix for a paragraph -automatically in certain cases: either whitespace or certain punctuation -characters at the beginning of a line are propagated to all lines of the -paragraph. - - If the paragraph has two or more lines, the fill prefix is taken from -the paragraph's second line, but only if it appears on the first line as -well. - - If a paragraph has just one line, fill commands @emph{may} take a -prefix from that line. The decision is complicated because there are -three reasonable things to do in such a case: - -@itemize @bullet -@item -Use the first line's prefix on all the lines of the paragraph. - -@item -Indent subsequent lines with whitespace, so that they line up under the -text that follows the prefix on the first line, but don't actually copy -the prefix from the first line. - -@item -Don't do anything special with the second and following lines. -@end itemize - - All three of these styles of formatting are commonly used. So the -fill commands try to determine what you would like, based on the prefix -that appears and on the major mode. Here is how. - -@vindex adaptive-fill-first-line-regexp - If the prefix found on the first line matches -@code{adaptive-fill-first-line-regexp}, or if it appears to be a -comment-starting sequence (this depends on the major mode), then the -prefix found is used for filling the paragraph, provided it would not -act as a paragraph starter on subsequent lines. - - Otherwise, the prefix found is converted to an equivalent number of -spaces, and those spaces are used as the fill prefix for the rest of the -lines, provided they would not act as a paragraph starter on subsequent -lines. - - In Text mode, and other modes where only blank lines and page -delimiters separate paragraphs, the prefix chosen by adaptive filling -never acts as a paragraph starter, so it can always be used for filling. - -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp - The variable @code{adaptive-fill-regexp} determines what kinds of line -beginnings can serve as a fill prefix: any characters at the start of -the line that match this regular expression are used. If you set the -variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is -never chosen automatically. - -@vindex adaptive-fill-function - You can specify more complex ways of choosing a fill prefix -automatically by setting the variable @code{adaptive-fill-function} to a -function. This function is called with point after the left margin of a -line, and it should return the appropriate fill prefix based on that -line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets -a chance to find a prefix. - -@node Refill -@subsection Refill Mode -@cindex refilling text, word processor style -@cindex modes, Refill -@cindex Refill minor mode - - Refill minor mode provides support for keeping paragraphs filled as -you type or modify them in other ways. It provides an effect similar -to typical word processor behavior. This works by running a -paragraph-filling command at suitable times. - - To toggle the use of Refill mode in the current buffer, type -@kbd{M-x refill-mode}. When you are typing text, only characters -which normally trigger auto filling, like the space character, will -trigger refilling. This is to avoid making it too slow. Apart from -self-inserting characters, other commands which modify the text cause -refilling. - - The current implementation is preliminary and not robust. You can -get better ``line wrapping'' behavior using Longlines mode. -@xref{Longlines}. However, Longlines mode has an important -side-effect: the newlines that it inserts for you are not saved to -disk, so the files that you make with Longlines mode will appear to be -completely unfilled if you edit them without Longlines mode. - -@node Longlines -@subsection Long Lines Mode -@cindex refilling text, word processor style -@cindex modes, Long Lines -@cindex word wrap -@cindex Long Lines minor mode - - Long Lines mode is a minor mode for @dfn{word wrapping}; it lets you -edit ``unfilled'' text files, which Emacs would normally display as a -bunch of extremely long lines. Many text editors, such as those built -into many web browsers, normally do word wrapping. - -@findex longlines-mode - To enable Long Lines mode, type @kbd{M-x longlines-mode}. If the -text is full of long lines, this will ``wrap'' them -immediately---i.e., break up to fit in the window. As you edit the -text, Long Lines mode automatically re-wraps lines by inserting or -deleting @dfn{soft newlines} as necessary (@pxref{Hard and Soft -Newlines}.) These soft newlines won't show up when you save the -buffer into a file, or when you copy the text into the kill ring, -clipboard, or a register. - -@findex longlines-auto-wrap - Word wrapping is @emph{not} the same as ordinary filling -(@pxref{Fill Commands}). It does not contract multiple spaces into a -single space, recognize fill prefixes (@pxref{Fill Prefix}), or -perform adaptive filling (@pxref{Adaptive Fill}). The reason for this -is that a wrapped line is still, conceptually, a single line. Each -soft newline is equivalent to exactly one space in that long line, and -vice versa. However, you can still call filling functions such as -@kbd{M-q}, and these will work as expected, inserting soft newlines -that won't show up on disk or when the text is copied. You can even -rely entirely on the normal fill commands by turning off automatic -line wrapping, with @kbd{C-u M-x longlines-auto-wrap}. To turn -automatic line wrapping back on, type @kbd{M-x longlines-auto-wrap}. - -@findex longlines-show-hard-newlines - Type @kbd{RET} to insert a hard newline, one which automatic -refilling will not remove. If you want to see where all the hard -newlines are, type @kbd{M-x longlines-show-hard-newlines}. This will -mark each hard newline with a special symbol. The same command with a -prefix argument turns this display off. - - Long Lines mode does not change normal text files that are already -filled, since the existing newlines are considered hard newlines. -Before Long Lines can do anything, you need to transform each -paragraph into a long line. One way is to set @code{fill-column} to a -large number (e.g., @kbd{C-u 9999 C-x f}), re-fill all the paragraphs, -and then set @code{fill-column} back to its original value. - -@node Case -@section Case Conversion Commands -@cindex case conversion - - Emacs has commands for converting either a single word or any arbitrary -range of text to upper case or to lower case. - -@table @kbd -@item M-l -Convert following word to lower case (@code{downcase-word}). -@item M-u -Convert following word to upper case (@code{upcase-word}). -@item M-c -Capitalize the following word (@code{capitalize-word}). -@item C-x C-l -Convert region to lower case (@code{downcase-region}). -@item C-x C-u -Convert region to upper case (@code{upcase-region}). -@end table - -@kindex M-l -@kindex M-u -@kindex M-c -@cindex words, case conversion -@cindex converting text to upper or lower case -@cindex capitalizing words -@findex downcase-word -@findex upcase-word -@findex capitalize-word - The word conversion commands are the most useful. @kbd{M-l} -(@code{downcase-word}) converts the word after point to lower case, moving -past it. Thus, repeating @kbd{M-l} converts successive words. -@kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while -@kbd{M-c} (@code{capitalize-word}) puts the first letter of the word -into upper case and the rest into lower case. All these commands convert -several words at once if given an argument. They are especially convenient -for converting a large amount of text from all upper case to mixed case, -because you can move through the text using @kbd{M-l}, @kbd{M-u} or -@kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead -to skip a word. - - When given a negative argument, the word case conversion commands apply -to the appropriate number of words before point, but do not move point. -This is convenient when you have just typed a word in the wrong case: you -can give the case conversion command and continue typing. - - If a word case conversion command is given in the middle of a word, -it applies only to the part of the word which follows point. (This is -comparable to what @kbd{M-d} (@code{kill-word}) does.) With a -negative argument, case conversion applies only to the part of the -word before point. - -@kindex C-x C-l -@kindex C-x C-u -@findex downcase-region -@findex upcase-region - The other case conversion commands are @kbd{C-x C-u} -(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which -convert everything between point and mark to the specified case. Point and -mark do not move. - - The region case conversion commands @code{upcase-region} and -@code{downcase-region} are normally disabled. This means that they ask -for confirmation if you try to use them. When you confirm, you may -enable the command, which means it will not ask for confirmation again. -@xref{Disabling}. - -@node Text Mode -@section Text Mode -@cindex Text mode -@cindex mode, Text -@findex text-mode - - When you edit files of text in a human language, it's more convenient -to use Text mode rather than Fundamental mode. To enter Text mode, type -@kbd{M-x text-mode}. - - In Text mode, only blank lines and page delimiters separate -paragraphs. As a result, paragraphs can be indented, and adaptive -filling determines what indentation to use when filling a paragraph. -@xref{Adaptive Fill}. - -@kindex TAB @r{(Text mode)} - Text mode defines @key{TAB} to run @code{indent-relative} -(@pxref{Indentation}), so that you can conveniently indent a line like -the previous line. - - Text mode turns off the features concerned with comments except when -you explicitly invoke them. It changes the syntax table so that -single-quotes are considered part of words. However, if a word starts -with single-quotes, these are treated as a prefix for purposes such as -capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into -@samp{'Hello'}, as expected. - -@cindex Paragraph-Indent Text mode -@cindex mode, Paragraph-Indent Text -@findex paragraph-indent-text-mode -@findex paragraph-indent-minor-mode - If you indent the first lines of paragraphs, then you should use -Paragraph-Indent Text mode rather than Text mode. In this mode, you -do not need to have blank lines between paragraphs, because the -first-line indentation is sufficient to start a paragraph; however -paragraphs in which every line is indented are not supported. Use -@kbd{M-x paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x -paragraph-indent-minor-mode} to enable an equivalent minor mode in -situations where you can't change the major mode---in mail -composition, for instance. - -@kindex M-TAB @r{(Text mode)} - Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} -as the command @code{ispell-complete-word}, which performs completion -of the partial word in the buffer before point, using the spelling -dictionary as the space of possible words. @xref{Spelling}. If your -window manager defines @kbd{M-@key{TAB}} to switch windows, you can -type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}. - -@vindex text-mode-hook - Entering Text mode runs the hook @code{text-mode-hook}. Other major -modes related to Text mode also run this hook, followed by hooks of -their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{} -mode, Outline mode, and Mail mode. Hook functions on -@code{text-mode-hook} can look at the value of @code{major-mode} to see -which of these modes is actually being entered. @xref{Hooks}. - -@ifnottex - Emacs provides two other modes for editing text that is to be passed -through a text formatter to produce fancy formatted printed output. -@xref{Nroff Mode}, for editing input to the formatter nroff. -@xref{TeX Mode,,@TeX{} Mode}, for editing input to the formatter TeX. - - Another mode is used for editing outlines. It allows you to view the -text at various levels of detail. You can view either the outline -headings alone or both headings and text; you can also hide some of the -headings at lower levels from view to make the high level structure more -visible. @xref{Outline Mode}. -@end ifnottex - -@node Outline Mode -@section Outline Mode -@cindex Outline mode -@cindex mode, Outline -@cindex invisible lines - -@findex outline-mode -@findex outline-minor-mode -@vindex outline-minor-mode-prefix - Outline mode is a major mode much like Text mode but intended for -editing outlines. It allows you to make parts of the text temporarily -invisible so that you can see the outline structure. Type @kbd{M-x -outline-mode} to switch to Outline mode as the major mode of the current -buffer. - - When Outline mode makes a line invisible, the line does not appear -on the screen. The screen appears exactly as if the invisible line -were deleted, except that an ellipsis (three periods in a row) appears -at the end of the previous visible line. (Multiple consecutive -invisible lines produce just one ellipsis.) - - Editing commands that operate on lines, such as @kbd{C-n} and -@kbd{C-p}, treat the text of the invisible line as part of the previous -visible line. Killing the ellipsis at the end of a visible line -really kills all the following invisible lines. - - Outline minor mode provides the same commands as the major mode, -Outline mode, but you can use it in conjunction with other major modes. -Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in -the current buffer. You can also specify this in the text of a file, -with a file local variable of the form @samp{mode: outline-minor} -(@pxref{File Variables}). - -@kindex C-c @@ @r{(Outline minor mode)} - The major mode, Outline mode, provides special key bindings on the -@kbd{C-c} prefix. Outline minor mode provides similar bindings with -@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the -major mode's special commands. (The variable -@code{outline-minor-mode-prefix} controls the prefix used.) - -@vindex outline-mode-hook - Entering Outline mode runs the hook @code{text-mode-hook} followed by -the hook @code{outline-mode-hook} (@pxref{Hooks}). - -@menu -* Format: Outline Format. What the text of an outline looks like. -* Motion: Outline Motion. Special commands for moving through - outlines. -* Visibility: Outline Visibility. Commands to control what is visible. -* Views: Outline Views. Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. -@end menu - -@node Outline Format -@subsection Format of Outlines - -@cindex heading lines (Outline mode) -@cindex body lines (Outline mode) - Outline mode assumes that the lines in the buffer are of two types: -@dfn{heading lines} and @dfn{body lines}. A heading line represents a -topic in the outline. Heading lines start with one or more stars; the -number of stars determines the depth of the heading in the outline -structure. Thus, a heading line with one star is a major topic; all the -heading lines with two stars between it and the next one-star heading -are its subtopics; and so on. Any line that is not a heading line is a -body line. Body lines belong with the preceding heading line. Here is -an example: - -@example -* Food -This is the body, -which says something about the topic of food. - -** Delicious Food -This is the body of the second-level header. - -** Distasteful Food -This could have -a body too, with -several lines. - -*** Dormitory Food - -* Shelter -Another first-level topic with its header line. -@end example - - A heading line together with all following body lines is called -collectively an @dfn{entry}. A heading line together with all following -deeper heading lines and their body lines is called a @dfn{subtree}. - -@vindex outline-regexp - You can customize the criterion for distinguishing heading lines by -setting the variable @code{outline-regexp}. (The recommended ways to -do this are in a major mode function or with a file local variable.) -Any line whose beginning has a match for this regexp is considered a -heading line. Matches that start within a line (not at the left -margin) do not count. - - The length of the matching text determines the level of the heading; -longer matches make a more deeply nested level. Thus, for example, if -a text formatter has commands @samp{@@chapter}, @samp{@@section} and -@samp{@@subsection} to divide the document into chapters and sections, -you could make those lines count as heading lines by setting -@code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note -the trick: the two words @samp{chapter} and @samp{section} are equally -long, but by defining the regexp to match only @samp{chap} we ensure -that the length of the text matched on a chapter heading is shorter, -so that Outline mode will know that sections are contained in -chapters. This works as long as no other command starts with -@samp{@@chap}. - -@vindex outline-level - You can explicitly specify a rule for calculating the level of a -heading line by setting the variable @code{outline-level}. The value -of @code{outline-level} should be a function that takes no arguments -and returns the level of the current heading. The recommended ways to -set this variable are in a major mode command or with a file local -variable. - -@node Outline Motion -@subsection Outline Motion Commands - - Outline mode provides special motion commands that move backward and -forward to heading lines. - -@table @kbd -@item C-c C-n -Move point to the next visible heading line -(@code{outline-next-visible-heading}). -@item C-c C-p -Move point to the previous visible heading line -(@code{outline-previous-visible-heading}). -@item C-c C-f -Move point to the next visible heading line at the same level -as the one point is on (@code{outline-forward-same-level}). -@item C-c C-b -Move point to the previous visible heading line at the same level -(@code{outline-backward-same-level}). -@item C-c C-u -Move point up to a lower-level (more inclusive) visible heading line -(@code{outline-up-heading}). -@end table - -@findex outline-next-visible-heading -@findex outline-previous-visible-heading -@kindex C-c C-n @r{(Outline mode)} -@kindex C-c C-p @r{(Outline mode)} - @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next -heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves -similarly backward. Both accept numeric arguments as repeat counts. The -names emphasize that invisible headings are skipped, but this is not really -a special feature. All editing commands that look for lines ignore the -invisible lines automatically. - -@findex outline-up-heading -@findex outline-forward-same-level -@findex outline-backward-same-level -@kindex C-c C-f @r{(Outline mode)} -@kindex C-c C-b @r{(Outline mode)} -@kindex C-c C-u @r{(Outline mode)} - More powerful motion commands understand the level structure of headings. -@kbd{C-c C-f} (@code{outline-forward-same-level}) and -@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one -heading line to another visible heading at the same depth in -the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves -backward to another heading that is less deeply nested. - -@node Outline Visibility -@subsection Outline Visibility Commands - - The other special commands of outline mode are used to make lines visible -or invisible. Their names all start with @code{hide} or @code{show}. -Most of them fall into pairs of opposites. They are not undoable; instead, -you can undo right past them. Making lines visible or invisible is simply -not recorded by the undo mechanism. - - Many of these commands act on the ``current'' heading line. If -point is on a heading line, that is the current heading line; if point -is on a body line, the current heading line is the nearest preceding -header line. - -@table @kbd -@item C-c C-c -Make the current heading line's body invisible (@code{hide-entry}). -@item C-c C-e -Make the current heading line's body visible (@code{show-entry}). -@item C-c C-d -Make everything under the current heading invisible, not including the -heading itself (@code{hide-subtree}). -@item C-c C-s -Make everything under the current heading visible, including body, -subheadings, and their bodies (@code{show-subtree}). -@item C-c C-l -Make the body of the current heading line, and of all its subheadings, -invisible (@code{hide-leaves}). -@item C-c C-k -Make all subheadings of the current heading line, at all levels, -visible (@code{show-branches}). -@item C-c C-i -Make immediate subheadings (one level down) of the current heading -line visible (@code{show-children}). -@item C-c C-t -Make all body lines in the buffer invisible (@code{hide-body}). -@item C-c C-a -Make all lines in the buffer visible (@code{show-all}). -@item C-c C-q -Hide everything except the top @var{n} levels of heading lines -(@code{hide-sublevels}). -@item C-c C-o -Hide everything except for the heading or body that point is in, plus -the headings leading up from there to the top level of the outline -(@code{hide-other}). -@end table - -@findex hide-entry -@findex show-entry -@kindex C-c C-c @r{(Outline mode)} -@kindex C-c C-e @r{(Outline mode)} - Two commands that are exact opposites are @kbd{C-c C-c} -(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They apply -to the body lines directly following the current heading line. -Subheadings and their bodies are not affected. - -@findex hide-subtree -@findex show-subtree -@kindex C-c C-s @r{(Outline mode)} -@kindex C-c C-d @r{(Outline mode)} -@cindex subtree (Outline mode) - Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) -and @kbd{C-c C-s} (@code{show-subtree}). Both apply to the current -heading line's @dfn{subtree}: its body, all its subheadings, both -direct and indirect, and all of their bodies. In other words, the -subtree contains everything following the current heading line, up to -and not including the next heading of the same or higher rank. - -@findex hide-leaves -@findex show-branches -@kindex C-c C-l @r{(Outline mode)} -@kindex C-c C-k @r{(Outline mode)} - Intermediate between a visible subtree and an invisible one is having -all the subheadings visible but none of the body. There are two -commands for doing this, depending on whether you want to hide the -bodies or make the subheadings visible. They are @kbd{C-c C-l} -(@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}). - -@kindex C-c C-i @r{(Outline mode)} -@findex show-children - A little weaker than @code{show-branches} is @kbd{C-c C-i} -(@code{show-children}). It makes just the direct subheadings -visible---those one level down. Deeper subheadings remain invisible, if -they were invisible. - -@findex hide-body -@findex show-all -@kindex C-c C-t @r{(Outline mode)} -@kindex C-c C-a @r{(Outline mode)} - Two commands have a blanket effect on the whole file. @kbd{C-c C-t} -(@code{hide-body}) makes all body lines invisible, so that you see just -the outline structure (as a special exception, it will not hide lines -at the top of the file, preceding the first header line, even though -these are technically body lines). @kbd{C-c C-a} (@code{show-all}) -makes all lines visible. These commands can be thought of as a pair -of opposites even though @kbd{C-c C-a} applies to more than just body -lines. - -@findex hide-sublevels -@kindex C-c C-q @r{(Outline mode)} - The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the -top level headings. With a numeric argument @var{n}, it hides everything -except the top @var{n} levels of heading lines. - -@findex hide-other -@kindex C-c C-o @r{(Outline mode)} - The command @kbd{C-c C-o} (@code{hide-other}) hides everything except -the heading and body text that point is in, plus its parents (the headers -leading up from there to top level in the outline) and the top level -headings. - -@findex reveal-mode - When incremental search finds text that is hidden by Outline mode, -it makes that part of the buffer visible. If you exit the search -at that position, the text remains visible. You can also -automatically make text visible as you navigate in it by using -@kbd{M-x reveal-mode}. - -@node Outline Views -@subsection Viewing One Outline in Multiple Views - -@cindex multiple views of outline -@cindex views of an outline -@cindex outline with multiple views -@cindex indirect buffers and outlines - You can display two views of a single outline at the same time, in -different windows. To do this, you must create an indirect buffer using -@kbd{M-x make-indirect-buffer}. The first argument of this command is -the existing outline buffer name, and its second argument is the name to -use for the new indirect buffer. @xref{Indirect Buffers}. - - Once the indirect buffer exists, you can display it in a window in the -normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline -mode commands to show and hide parts of the text operate on each buffer -independently; as a result, each buffer can have its own view. If you -want more than two views on the same outline, create additional indirect -buffers. - -@node Foldout -@subsection Folding Editing - -@cindex folding editing - The Foldout package extends Outline mode and Outline minor mode with -``folding'' commands. The idea of folding is that you zoom in on a -nested portion of the outline, while hiding its relatives at higher -levels. - - Consider an Outline mode buffer with all the text and subheadings under -level-1 headings hidden. To look at what is hidden under one of these -headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose -the body, or @kbd{C-c C-i} to expose the child (level-2) headings. - -@kindex C-c C-z -@findex foldout-zoom-subtree - With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}). -This exposes the body and child subheadings, and narrows the buffer so -that only the @w{level-1} heading, the body and the level-2 headings are -visible. Now to look under one of the level-2 headings, position the -cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body -and its level-3 child subheadings and narrows the buffer again. Zooming -in on successive subheadings can be done as much as you like. A string -in the mode line shows how deep you've gone. - - When zooming in on a heading, to see only the child subheadings specify -a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children -can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2 -C-c C-z} exposes two levels of child subheadings. Alternatively, the -body can be specified with a negative argument: @kbd{M-- C-c C-z}. The -whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x -show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}. - - While you're zoomed in, you can still use Outline mode's exposure and -hiding functions without disturbing Foldout. Also, since the buffer is -narrowed, ``global'' editing actions will only affect text under the -zoomed-in heading. This is useful for restricting changes to a -particular chapter or section of your document. - -@kindex C-c C-x -@findex foldout-exit-fold - To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}). -This hides all the text and subheadings under the top-level heading and -returns you to the previous view of the buffer. Specifying a numeric -argument exits that many levels of folds. Specifying a zero argument -exits all folds. - - To cancel the narrowing of a fold without hiding the text and -subheadings, specify a negative argument. For example, @kbd{M--2 C-c -C-x} exits two folds and leaves the text and subheadings exposed. - - Foldout mode also provides mouse commands for entering and exiting -folds, and for showing and hiding text: - -@table @asis -@item @kbd{C-M-Mouse-1} zooms in on the heading clicked on -@itemize @asis -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-2} exposes text under the heading clicked on -@itemize @asis -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold -@itemize @asis -@item -single click: hide subtree. -@item -double click: exit fold and hide text. -@item -triple click: exit fold without hiding text. -@item -quad click: exit all folds and hide text. -@end itemize -@end table - -@vindex foldout-mouse-modifiers - You can specify different modifier keys (instead of -@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if -you have already loaded the @file{foldout.el} library, you must reload -it in order for this to take effect. - - To use the Foldout package, you can type @kbd{M-x load-library -@key{RET} foldout @key{RET}}; or you can arrange for to do that -automatically by putting this in your @file{.emacs} file: - -@example -(eval-after-load "outline" '(require 'foldout)) -@end example - -@node TeX Mode -@section @TeX{} Mode -@cindex @TeX{} mode -@cindex La@TeX{} mode -@cindex Sli@TeX{} mode -@cindex Doc@TeX{} mode -@cindex mode, @TeX{} -@cindex mode, La@TeX{} -@cindex mode, Sli@TeX{} -@cindex mode, Doc@TeX{} -@findex tex-mode -@findex plain-tex-mode -@findex latex-mode -@findex slitex-mode -@findex doctex-mode - - @TeX{} is a powerful text formatter written by Donald Knuth; it is -also free software, like GNU Emacs. La@TeX{} is a simplified input -format for @TeX{}, implemented by @TeX{} macros; it comes with @TeX{}. -Sli@TeX{} is a special form of La@TeX{}.@footnote{Sli@TeX{} is -obsoleted by the @samp{slides} document class and other alternative -packages in recent La@TeX{} versions.} Doc@TeX{} (@file{.dtx}) is a -special file format in which the La@TeX{} sources are written, -combining sources with documentation. - - Emacs has a special @TeX{} mode for editing @TeX{} input files. -It provides facilities for checking the balance of delimiters and for -invoking @TeX{} on all or part of the file. - -@vindex tex-default-mode - @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode, -Sli@TeX{} mode, and Doc@TeX{} mode (these distinct major modes differ -only slightly). They are designed for editing the four different -formats. The command @kbd{M-x tex-mode} looks at the contents of the -buffer to determine whether the contents appear to be either La@TeX{} -input, Sli@TeX{}, or Doc@TeX{} input; if so, it selects the -appropriate mode. If the file contents do not appear to be La@TeX{}, -Sli@TeX{} or Doc@TeX{}, it selects Plain @TeX{} mode. If the contents -are insufficient to determine this, the variable -@code{tex-default-mode} controls which mode is used. - - When @kbd{M-x tex-mode} does not guess right, you can use the commands -@kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, @kbd{M-x slitex-mode}, -and @kbd{doctex-mode} to select explicitly the particular variants of -@TeX{} mode. - -@menu -* Editing: TeX Editing. Special commands for editing in TeX mode. -* LaTeX: LaTeX Editing. Additional commands for LaTeX input files. -* Printing: TeX Print. Commands for printing part of a file with TeX. -* Misc: TeX Misc. Customization of TeX mode, and related features. -@end menu - -@node TeX Editing -@subsection @TeX{} Editing Commands - - Here are the special commands provided in @TeX{} mode for editing the -text of the file. - -@table @kbd -@item " -Insert, according to context, either @samp{``} or @samp{"} or -@samp{''} (@code{tex-insert-quote}). -@item C-j -Insert a paragraph break (two newlines) and check the previous -paragraph for unbalanced braces or dollar signs -(@code{tex-terminate-paragraph}). -@item M-x tex-validate-region -Check each paragraph in the region for unbalanced braces or dollar signs. -@item C-c @{ -Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}). -@item C-c @} -Move forward past the next unmatched close brace (@code{up-list}). -@end table - -@findex tex-insert-quote -@kindex " @r{(@TeX{} mode)} - In @TeX{}, the character @samp{"} is not normally used; we use -@samp{``} to start a quotation and @samp{''} to end one. To make -editing easier under this formatting convention, @TeX{} mode overrides -the normal meaning of the key @kbd{"} with a command that inserts a pair -of single-quotes or backquotes (@code{tex-insert-quote}). To be -precise, this command inserts @samp{``} after whitespace or an open -brace, @samp{"} after a backslash, and @samp{''} after any other -character. - - If you need the character @samp{"} itself in unusual contexts, use -@kbd{C-q} to insert it. Also, @kbd{"} with a numeric argument always -inserts that number of @samp{"} characters. You can turn off the -feature of @kbd{"} expansion by eliminating that binding in the local -map (@pxref{Key Bindings}). - - In @TeX{} mode, @samp{$} has a special syntax code which attempts to -understand the way @TeX{} math mode delimiters match. When you insert a -@samp{$} that is meant to exit math mode, the position of the matching -@samp{$} that entered math mode is displayed for a second. This is the -same feature that displays the open brace that matches a close brace that -is inserted. However, there is no way to tell whether a @samp{$} enters -math mode or leaves it; so when you insert a @samp{$} that enters math -mode, the previous @samp{$} position is shown as if it were a match, even -though they are actually unrelated. - -@findex tex-insert-braces -@kindex C-c @{ @r{(@TeX{} mode)} -@findex up-list -@kindex C-c @} @r{(@TeX{} mode)} - @TeX{} uses braces as delimiters that must match. Some users prefer -to keep braces balanced at all times, rather than inserting them -singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of -braces. It leaves point between the two braces so you can insert the -text that belongs inside. Afterward, use the command @kbd{C-c @}} -(@code{up-list}) to move forward past the close brace. - -@findex tex-validate-region -@findex tex-terminate-paragraph -@kindex C-j @r{(@TeX{} mode)} - There are two commands for checking the matching of braces. @kbd{C-j} -(@code{tex-terminate-paragraph}) checks the paragraph before point, and -inserts two newlines to start a new paragraph. It outputs a message in -the echo area if any mismatch is found. @kbd{M-x tex-validate-region} -checks a region, paragraph by paragraph. The errors are listed in the -@samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in -that buffer to go to a particular mismatch. - - Note that Emacs commands count square brackets and parentheses in -@TeX{} mode, not just braces. This is not strictly correct for the -purpose of checking @TeX{} syntax. However, parentheses and square -brackets are likely to be used in text as matching delimiters and it is -useful for the various motion commands and automatic match display to -work with them. - -@node LaTeX Editing -@subsection La@TeX{} Editing Commands - - La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra -features not applicable to plain @TeX{}. - -@table @kbd -@item C-c C-o -Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position -point on a line between them (@code{tex-latex-block}). -@item C-c C-e -Close the innermost La@TeX{} block not yet closed -(@code{tex-close-latex-block}). -@end table - -@findex tex-latex-block -@kindex C-c C-o @r{(La@TeX{} mode)} -@vindex latex-block-names - In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to -group blocks of text. To insert a @samp{\begin} and a matching -@samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c -C-o} (@code{tex-latex-block}). A blank line is inserted between the -two, and point is left there. You can use completion when you enter the -block type; to specify additional block type names beyond the standard -list, set the variable @code{latex-block-names}. For example, here's -how to add @samp{theorem}, @samp{corollary}, and @samp{proof}: - -@example -(setq latex-block-names '("theorem" "corollary" "proof")) -@end example - -@findex tex-close-latex-block -@kindex C-c C-e @r{(La@TeX{} mode)} - In La@TeX{} input, @samp{\begin} and @samp{\end} commands must -balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to -insert automatically a matching @samp{\end} to match the last unmatched -@samp{\begin}. It indents the @samp{\end} to match the corresponding -@samp{\begin}. It inserts a newline after @samp{\end} if point is at -the beginning of a line. - -@node TeX Print -@subsection @TeX{} Printing Commands - - You can invoke @TeX{} as an inferior of Emacs on either the entire -contents of the buffer or just a region at a time. Running @TeX{} in -this way on just one chapter is a good way to see what your changes -look like without taking the time to format the entire file. - -@table @kbd -@item C-c C-r -Invoke @TeX{} on the current region, together with the buffer's header -(@code{tex-region}). -@item C-c C-b -Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). -@item C-c @key{TAB} -Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). -@item C-c C-f -Invoke @TeX{} on the current file (@code{tex-file}). -@item C-c C-l -Recenter the window showing output from the inferior @TeX{} so that -the last line can be seen (@code{tex-recenter-output-buffer}). -@item C-c C-k -Kill the @TeX{} subprocess (@code{tex-kill-job}). -@item C-c C-p -Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c -C-f} command (@code{tex-print}). -@item C-c C-v -Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c -C-f} command (@code{tex-view}). -@item C-c C-q -Show the printer queue (@code{tex-show-print-queue}). -@item C-c C-c -Invoke some other compilation command on the entire current buffer -(@code{tex-compile}). -@end table - -@findex tex-buffer -@kindex C-c C-b @r{(@TeX{} mode)} -@findex tex-print -@kindex C-c C-p @r{(@TeX{} mode)} -@findex tex-view -@kindex C-c C-v @r{(@TeX{} mode)} -@findex tex-show-print-queue -@kindex C-c C-q @r{(@TeX{} mode)} - You can pass the current buffer through an inferior @TeX{} by means of -@kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a -temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}). -Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to -view the progress of your output towards being printed. If your terminal -has the ability to display @TeX{} output files, you can preview the -output on the terminal with @kbd{C-c C-v} (@code{tex-view}). - -@cindex @env{TEXINPUTS} environment variable -@vindex tex-directory - You can specify the directory to use for running @TeX{} by setting the -variable @code{tex-directory}. @code{"."} is the default value. If -your environment variable @env{TEXINPUTS} contains relative directory -names, or if your files contains @samp{\input} commands with relative -file names, then @code{tex-directory} @emph{must} be @code{"."} or you -will get the wrong results. Otherwise, it is safe to specify some other -directory, such as @code{"/tmp"}. - -@vindex tex-run-command -@vindex latex-run-command -@vindex slitex-run-command -@vindex tex-dvi-print-command -@vindex tex-dvi-view-command -@vindex tex-show-queue-command - If you want to specify which shell commands are used in the inferior @TeX{}, -you can do so by setting the values of the variables @code{tex-run-command}, -@code{latex-run-command}, @code{slitex-run-command}, -@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and -@code{tex-show-queue-command}. The default values may -(or may not) be appropriate for your system. - - Normally, the file name given to these commands comes at the end of -the command string; for example, @samp{latex @var{filename}}. In some -cases, however, the file name needs to be embedded in the command; an -example is when you need to provide the file name as an argument to one -command whose output is piped to another. You can specify where to put -the file name with @samp{*} in the command string. For example, - -@example -(setq tex-dvi-print-command "dvips -f * | lpr") -@end example - -@findex tex-kill-job -@kindex C-c C-k @r{(@TeX{} mode)} -@findex tex-recenter-output-buffer -@kindex C-c C-l @r{(@TeX{} mode)} - The terminal output from @TeX{}, including any error messages, appears -in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can -switch to this buffer and feed it input (this works as in Shell mode; -@pxref{Interactive Shell}). Without switching to this buffer you can -scroll it so that its last line is visible by typing @kbd{C-c -C-l}. - - Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if -you see that its output is no longer useful. Using @kbd{C-c C-b} or -@kbd{C-c C-r} also kills any @TeX{} process still running. - -@findex tex-region -@kindex C-c C-r @r{(@TeX{} mode)} - You can also pass an arbitrary region through an inferior @TeX{} by typing -@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files -of @TeX{} input contain commands at the beginning to set parameters and -define macros, without which no later part of the file will format -correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a -part of the file as containing essential commands; it is included before -the specified region as part of the input to @TeX{}. The designated part -of the file is called the @dfn{header}. - -@cindex header (@TeX{} mode) - To indicate the bounds of the header in Plain @TeX{} mode, you insert two -special strings in the file. Insert @samp{%**start of header} before the -header, and @samp{%**end of header} after it. Each string must appear -entirely on one line, but there may be other text on the line before or -after. The lines containing the two strings are included in the header. -If @samp{%**start of header} does not appear within the first 100 lines of -the buffer, @kbd{C-c C-r} assumes that there is no header. - - In La@TeX{} mode, the header begins with @samp{\documentclass} or -@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These -are commands that La@TeX{} requires you to use in any case, so nothing -special needs to be done to identify the header. - -@findex tex-file -@kindex C-c C-f @r{(@TeX{} mode)} - The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their -work in a temporary directory, and do not have available any of the auxiliary -files needed by @TeX{} for cross-references; these commands are generally -not suitable for running the final copy in which all of the cross-references -need to be correct. - - When you want the auxiliary files for cross references, use @kbd{C-c -C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file, -in that file's directory. Before running @TeX{}, it offers to save any -modified buffers. Generally, you need to use (@code{tex-file}) twice to -get the cross-references right. - -@vindex tex-start-options - The value of the variable @code{tex-start-options} specifies -options for the @TeX{} run. - -@vindex tex-start-commands - The value of the variable @code{tex-start-commands} specifies @TeX{} -commands for starting @TeX{}. The default value causes @TeX{} to run -in nonstop mode. To run @TeX{} interactively, set the variable to -@code{""}. - -@vindex tex-main-file - Large @TeX{} documents are often split into several files---one main -file, plus subfiles. Running @TeX{} on a subfile typically does not -work; you have to run it on the main file. In order to make -@code{tex-file} useful when you are editing a subfile, you can set the -variable @code{tex-main-file} to the name of the main file. Then -@code{tex-file} runs @TeX{} on that file. - - The most convenient way to use @code{tex-main-file} is to specify it -in a local variable list in each of the subfiles. @xref{File -Variables}. - -@findex tex-bibtex-file -@kindex C-c TAB @r{(@TeX{} mode)} -@vindex tex-bibtex-command - For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary -file for the current buffer's file. Bib@TeX{} looks up bibliographic -citations in a data base and prepares the cited references for the -bibliography section. The command @kbd{C-c @key{TAB}} -(@code{tex-bibtex-file}) runs the shell command -(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the -current buffer's file. Generally, you need to do @kbd{C-c C-f} -(@code{tex-file}) once to generate the @samp{.aux} file, then do -@kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f} -(@code{tex-file}) twice more to get the cross-references correct. - -@findex tex-compile -@kindex C-c C-c @r{(@TeX{} mode)} - To invoke some other compilation program on the current @TeX{} -buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows -how to pass arguments to many common programs, including -@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can -select your desired compilation program using the standard completion -keys (@pxref{Completion}). - -@node TeX Misc -@subsection @TeX{} Mode Miscellany - -@vindex tex-shell-hook -@vindex tex-mode-hook -@vindex latex-mode-hook -@vindex slitex-mode-hook -@vindex plain-tex-mode-hook - Entering any variant of @TeX{} mode runs the hooks -@code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either -@code{plain-tex-mode-hook}, @code{latex-mode-hook}, or -@code{slitex-mode-hook}, whichever is appropriate. Starting the -@TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}. - -@findex iso-iso2tex -@findex iso-tex2iso -@findex iso-iso2gtex -@findex iso-gtex2iso -@cindex Latin-1 @TeX{} encoding -@cindex @TeX{} encoding - The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x -iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert -between Latin-1 encoded files and @TeX{}-encoded equivalents. -@ignore -@c Too cryptic to be useful, too cryptic for me to make it better -- rms. - They -are included by default in the @code{format-alist} variable, so they -can be used with @kbd{M-x format-find-file}, for instance. -@end ignore - -@ignore @c Not worth documenting if it is only for Czech -- rms. -@findex tildify-buffer -@findex tildify-region -@cindex ties, @TeX{}, inserting -@cindex hard spaces, @TeX{}, inserting - The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region} -insert @samp{~} (@dfn{tie}) characters where they are conventionally -required. This is set up for Czech---customize the group -@samp{tildify} for other languages or for other sorts of markup. -@end ignore - -@cindex Ref@TeX{} package -@cindex references, La@TeX{} -@cindex La@TeX{} references - For managing all kinds of references for La@TeX{}, you can use -Ref@TeX{}. @inforef{Top,, reftex}. - -@node HTML Mode -@section SGML, XML, and HTML Modes - - The major modes for SGML and HTML include indentation support and -commands to operate on tags. This section describes the special -commands of these modes. (HTML mode is a slightly customized variant -of SGML mode.) - -@table @kbd -@item C-c C-n -@kindex C-c C-n @r{(SGML mode)} -@findex sgml-name-char -Interactively specify a special character and insert the SGML -@samp{&}-command for that character. - -@item C-c C-t -@kindex C-c C-t @r{(SGML mode)} -@findex sgml-tag -Interactively specify a tag and its attributes (@code{sgml-tag}). -This command asks you for a tag name and for the attribute values, -then inserts both the opening tag and the closing tag, leaving point -between them. - -With a prefix argument @var{n}, the command puts the tag around the -@var{n} words already present in the buffer after point. With -@minus{}1 as argument, it puts the tag around the region. (In -Transient Mark mode, it does this whenever a region is active.) - -@item C-c C-a -@kindex C-c C-a @r{(SGML mode)} -@findex sgml-attributes -Interactively insert attribute values for the current tag -(@code{sgml-attributes}). - -@item C-c C-f -@kindex C-c C-f @r{(SGML mode)} -@findex sgml-skip-tag-forward -Skip across a balanced tag group (which extends from an opening tag -through its corresponding closing tag) (@code{sgml-skip-tag-forward}). -A numeric argument acts as a repeat count. - -@item C-c C-b -@kindex C-c C-b @r{(SGML mode)} -@findex sgml-skip-tag-backward -Skip backward across a balanced tag group (which extends from an -opening tag through its corresponding closing tag) -(@code{sgml-skip-tag-forward}). A numeric argument acts as a repeat -count. - -@item C-c C-d -@kindex C-c C-d @r{(SGML mode)} -@findex sgml-delete-tag -Delete the tag at or after point, and delete the matching tag too -(@code{sgml-delete-tag}). If the tag at or after point is an opening -tag, delete the closing tag too; if it is a closing tag, delete the -opening tag too. - -@item C-c ? @var{tag} @key{RET} -@kindex C-c ? @r{(SGML mode)} -@findex sgml-tag-help -Display a description of the meaning of tag @var{tag} -(@code{sgml-tag-help}). If the argument @var{tag} is empty, describe -the tag at point. - -@item C-c / -@kindex C-c / @r{(SGML mode)} -@findex sgml-close-tag -Insert a close tag for the innermost unterminated tag -(@code{sgml-close-tag}). If called from within a tag or a comment, -close this element instead of inserting a close tag. - -@item C-c 8 -@kindex C-c 8 @r{(SGML mode)} -@findex sgml-name-8bit-mode -Toggle a minor mode in which Latin-1 characters insert the -corresponding SGML commands that stand for them, instead of the -characters themselves (@code{sgml-name-8bit-mode}). - -@item C-c C-v -@kindex C-c C-v @r{(SGML mode)} -@findex sgml-validate -Run a shell command (which you must specify) to validate the current -buffer as SGML (@code{sgml-validate}). - -@item C-c TAB -@kindex C-c TAB @r{(SGML mode)} -@findex sgml-tags-invisible -Toggle the visibility of existing tags in the buffer. This can be -used as a cheap preview. -@end table - -@vindex sgml-xml-mode - SGML mode and HTML mode support XML also. In XML, every opening tag -must have an explicit closing tag. When @code{sgml-xml-mode} is -non-@code{nil}, SGML mode and HTML mode always insert explicit -closing tags. When you visit a file, these modes determine from the -file contents whether it is XML or not, and set @code{sgml-xml-mode} -accordingly, so that they do the right thing for the file in either -case. - -@node Nroff Mode -@section Nroff Mode - -@cindex nroff -@findex nroff-mode - Nroff mode is a mode like Text mode but modified to handle nroff commands -present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It -differs from Text mode in only a few ways. All nroff command lines are -considered paragraph separators, so that filling will never garble the -nroff commands. Pages are separated by @samp{.bp} commands. Comments -start with backslash-doublequote. Also, three special commands are -provided that are not in Text mode: - -@findex forward-text-line -@findex backward-text-line -@findex count-text-lines -@kindex M-n @r{(Nroff mode)} -@kindex M-p @r{(Nroff mode)} -@kindex M-? @r{(Nroff mode)} -@table @kbd -@item M-n -Move to the beginning of the next line that isn't an nroff command -(@code{forward-text-line}). An argument is a repeat count. -@item M-p -Like @kbd{M-n} but move up (@code{backward-text-line}). -@item M-? -Displays in the echo area the number of text lines (lines that are not -nroff commands) in the region (@code{count-text-lines}). -@end table - -@findex electric-nroff-mode - The other feature of Nroff mode is that you can turn on Electric Nroff -mode. This is a minor mode that you can turn on or off with @kbd{M-x -electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each -time you use @key{RET} to end a line that contains an nroff command that -opens a kind of grouping, the matching nroff command to close that -grouping is automatically inserted on the following line. For example, -if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}}, -this inserts the matching command @samp{.)b} on a new line following -point. - - If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}), -heading lines are lines of the form @samp{.H} followed by a number (the -header level). - -@vindex nroff-mode-hook - Entering Nroff mode runs the hook @code{text-mode-hook}, followed by -the hook @code{nroff-mode-hook} (@pxref{Hooks}). - -@node Formatted Text -@section Editing Formatted Text - -@cindex Enriched mode -@cindex mode, Enriched -@cindex formatted text -@cindex WYSIWYG -@cindex word processing - @dfn{Enriched mode} is a minor mode for editing files that contain -formatted text in WYSIWYG fashion, as in a word processor. Currently, -formatted text in Enriched mode can specify fonts, colors, underlining, -margins, and types of filling and justification. In the future, we plan -to implement other formatting features as well. - - Enriched mode is a minor mode (@pxref{Minor Modes}). It is -typically used in conjunction with Text mode (@pxref{Text Mode}), but -you can also use it with other major modes such as Outline mode and -Paragraph-Indent Text mode. - -@cindex text/enriched MIME format - Potentially, Emacs can store formatted text files in various file -formats. Currently, only one format is implemented: @dfn{text/enriched} -format, which is defined by the MIME protocol. @xref{Format -Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual}, -for details of how Emacs recognizes and converts file formats. - - The Emacs distribution contains a formatted text file that can serve as -an example. Its name is @file{etc/enriched.doc}. It contains samples -illustrating all the features described in this section. It also -contains a list of ideas for future enhancements. - -@menu -* Requesting Formatted Text:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Faces: Format Faces. Bold, italic, underline, etc. -* Color: Format Colors. Changing the color of text. -* Indent: Format Indentation. Changing the left and right margins. -* Justification: Format Justification. - Centering, setting text flush with the - left or right margin, etc. -* Other: Format Properties. The "special" text properties submenu. -* Forcing Enriched Mode:: How to force use of Enriched mode. -@end menu - -@node Requesting Formatted Text -@subsection Requesting to Edit Formatted Text - - Whenever you visit a file that Emacs saved in the text/enriched -format, Emacs automatically converts the formatting information in the -file into Emacs's own internal format (known as @dfn{text -properties}), and turns on Enriched mode. - -@findex enriched-mode - To create a new file of formatted text, first visit the nonexistent -file, then type @kbd{M-x enriched-mode} before you start inserting text. -This command turns on Enriched mode. Do this before you begin inserting -text, to ensure that the text you insert is handled properly. - - More generally, the command @code{enriched-mode} turns Enriched mode -on if it was off, and off if it was on. With a prefix argument, this -command turns Enriched mode on if the argument is positive, and turns -the mode off otherwise. - - When you save a buffer while Enriched mode is enabled in it, Emacs -automatically converts the text to text/enriched format while writing it -into the file. When you visit the file again, Emacs will automatically -recognize the format, reconvert the text, and turn on Enriched mode -again. - -@vindex enriched-translations - You can add annotations for saving additional text properties, which -Emacs normally does not save, by adding to @code{enriched-translations}. -Note that the text/enriched standard requires any non-standard -annotations to have names starting with @samp{x-}, as in -@samp{x-read-only}. This ensures that they will not conflict with -standard annotations that may be added later. - - @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual}, -for more information about text properties. - -@node Hard and Soft Newlines -@subsection Hard and Soft Newlines -@cindex hard newline -@cindex soft newline -@cindex newlines, hard and soft - -@cindex use-hard-newlines - In formatted text, Emacs distinguishes between two different kinds of -newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable -or disable this feature separately in any buffer with the command -@code{use-hard-newlines}.) - - Hard newlines are used to separate paragraphs, or items in a list, or -anywhere that there should always be a line break regardless of the -margins. The @key{RET} command (@code{newline}) and @kbd{C-o} -(@code{open-line}) insert hard newlines. - - Soft newlines are used to make text fit between the margins. All the -fill commands, including Auto Fill, insert soft newlines---and they -delete only soft newlines. - - Although hard and soft newlines look the same, it is important to bear -the difference in mind. Do not use @key{RET} to break lines in the -middle of filled paragraphs, or else you will get hard newlines that are -barriers to further filling. Instead, let Auto Fill mode break lines, -so that if the text or the margins change, Emacs can refill the lines -properly. @xref{Auto Fill}. - - On the other hand, in tables and lists, where the lines should always -remain as you type them, you can use @key{RET} to end lines. For these -lines, you may also want to set the justification style to -@code{unfilled}. @xref{Format Justification}. - -@node Editing Format Info -@subsection Editing Format Information - - There are two ways to alter the formatting information for a formatted -text file: with keyboard commands, and with the mouse. - - The easiest way to add properties to your document is with the Text -Properties menu. You can get to this menu in two ways: from the Edit -menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse), -or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle -mouse button). There are also keyboard commands described in the -following section. - - Most of the items in the Text Properties menu lead to other submenus. -These are described in the sections that follow. Some items run -commands directly: - -@table @code -@findex facemenu-remove-face-props -@item Remove Face Properties -Delete from the region all face and color text properties -(@code{facemenu-remove-face-props}). - -@findex facemenu-remove-all -@item Remove Text Properties -Delete @emph{all} text properties from the region -(@code{facemenu-remove-all}). - -@findex describe-text-properties -@cindex text properties of characters -@cindex overlays at character position -@cindex widgets at buffer position -@cindex buttons at buffer position -@item Describe Properties -List all the text properties, widgets, buttons, and overlays of the -character following point (@code{describe-text-properties}). - -@item Display Faces -Display a list of all the defined faces (@code{list-faces-display}). - -@item Display Colors -Display a list of all the defined colors (@code{list-colors-display}). -@end table - -@node Format Faces -@subsection Faces in Formatted Text - - The Faces submenu lists various Emacs faces including @code{bold}, -@code{italic}, and @code{underline} (@pxref{Faces}). These menu items -operate on the region if it is active and nonempty. Otherwise, they -specify to use that face for an immediately following self-inserting -character. Instead of the menu, you can use these keyboard commands: - -@table @kbd -@kindex M-o d @r{(Enriched mode)} -@findex facemenu-set-default -@item M-o d -Remove all @code{face} properties from the region (which includes -specified colors), or force the following inserted character to have no -@code{face} property (@code{facemenu-set-default}). -@kindex M-o b @r{(Enriched mode)} -@findex facemenu-set-bold -@item M-o b -Add the face @code{bold} to the region or to the following inserted -character (@code{facemenu-set-bold}). -@kindex M-o i @r{(Enriched mode)} -@findex facemenu-set-italic -@item M-o i -Add the face @code{italic} to the region or to the following inserted -character (@code{facemenu-set-italic}). -@kindex M-o l @r{(Enriched mode)} -@findex facemenu-set-bold-italic -@item M-o l -Add the face @code{bold-italic} to the region or to the following -inserted character (@code{facemenu-set-bold-italic}). -@kindex M-o u @r{(Enriched mode)} -@findex facemenu-set-underline -@item M-o u -Add the face @code{underline} to the region or to the following inserted -character (@code{facemenu-set-underline}). -@kindex M-o o @r{(Enriched mode)} -@findex facemenu-set-face -@item M-o o @var{face} @key{RET} -Add the face @var{face} to the region or to the following inserted -character (@code{facemenu-set-face}). -@end table - - With a prefix argument, all these commands apply to an immediately -following self-inserting character, disregarding the region. - - A self-inserting character normally inherits the @code{face} -property (and most other text properties) from the preceding character -in the buffer. If you use the above commands to specify face for the -next self-inserting character, or the next section's commands to -specify a foreground or background color for it, then it does not -inherit the @code{face} property from the preceding character; instead -it uses whatever you specified. It will still inherit other text -properties, though. - - Strictly speaking, these commands apply only to the first following -self-inserting character that you type. But if you insert additional -characters after it, they will inherit from the first one. So it -appears that these commands apply to all of them. - - Enriched mode defines two additional faces: @code{excerpt} and -@code{fixed}. These correspond to codes used in the text/enriched file -format. - - The @code{excerpt} face is intended for quotations. This face is the -same as @code{italic} unless you customize it (@pxref{Face Customization}). - - The @code{fixed} face means, ``Use a fixed-width font for this part -of the text.'' Applying the @code{fixed} face to a part of the text -will cause that part of the text to appear in a fixed-width font, even -if the default font is variable-width. This applies to Emacs and to -other systems that display text/enriched format. So if you -specifically want a certain part of the text to use a fixed-width -font, you should specify the @code{fixed} face for that part. - - By default, the @code{fixed} face looks the same as @code{bold}. -This is an attempt to distinguish it from @code{default}. You may -wish to customize @code{fixed} to some other fixed-width medium font. -@xref{Face Customization}. - - If your terminal cannot display different faces, you will not be -able to see them, but you can still edit documents containing faces, -and even add faces and colors to documents. The faces you specify -will be visible when the file is viewed on a terminal that can display -them. - -@node Format Colors -@subsection Colors in Formatted Text - - You can specify foreground and background colors for portions of the -text. There is a menu for specifying the foreground color and a menu -for specifying the background color. Each color menu lists all the -colors that you have used in Enriched mode in the current Emacs session. - - If you specify a color with a prefix argument---or, in Transient -Mark mode, if the region is not active---then it applies to any -immediately following self-inserting input. Otherwise, the command -applies to the region. - - Each color menu contains one additional item: @samp{Other}. You can use -this item to specify a color that is not listed in the menu; it reads -the color name with the minibuffer. To display a list of available colors -and their names, use the @samp{Display Colors} menu item in the Text -Properties menu (@pxref{Editing Format Info}). - - Any color that you specify in this way, or that is mentioned in a -formatted text file that you read in, is added to the corresponding -color menu for the duration of the Emacs session. - -@findex facemenu-set-foreground -@findex facemenu-set-background - There are no predefined key bindings for specifying colors, but you can do so -with the extended commands @kbd{M-x facemenu-set-foreground} and -@kbd{M-x facemenu-set-background}. Both of these commands read the name -of the color with the minibuffer. - -@node Format Indentation -@subsection Indentation in Formatted Text - - When editing formatted text, you can specify different amounts of -indentation for the right or left margin of an entire paragraph or a -part of a paragraph. The margins you specify automatically affect the -Emacs fill commands (@pxref{Filling}) and line-breaking commands. - - The Indentation submenu provides a convenient interface for specifying -these properties. The submenu contains four items: - -@table @code -@kindex C-x TAB @r{(Enriched mode)} -@findex increase-left-margin -@item Indent More -Indent the region by 4 columns (@code{increase-left-margin}). In -Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if -you supply a numeric argument, that says how many columns to add to the -margin (a negative argument reduces the number of columns). - -@item Indent Less -Remove 4 columns of indentation from the region. - -@item Indent Right More -Make the text narrower by indenting 4 columns at the right margin. - -@item Indent Right Less -Remove 4 columns of indentation from the right margin. -@end table - - You can use these commands repeatedly to increase or decrease the -indentation. - - The most common way to use them is to change the indentation of an -entire paragraph. For other uses, the effects of refilling can be -hard to predict, except in some special cases like the one described -next. - - The most common other use is to format paragraphs with @dfn{hanging -indents}, which means that the first line is indented less than -subsequent lines. To set up a hanging indent, increase the -indentation of the region starting after the first word of the -paragraph and running until the end of the paragraph. - - Indenting the first line of a paragraph is easier. Set the margin for -the whole paragraph where you want it to be for the body of the -paragraph, then indent the first line by inserting extra spaces or tabs. - -@vindex standard-indent - The variable @code{standard-indent} specifies how many columns these -commands should add to or subtract from the indentation. The default -value is 4. The overall default right margin for Enriched mode is -controlled by the variable @code{fill-column}, as usual. - -@kindex C-c [ @r{(Enriched mode)} -@kindex C-c ] @r{(Enriched mode)} -@findex set-left-margin -@findex set-right-margin - There are also two commands for setting the left or right margin of -the region absolutely: @code{set-left-margin} and -@code{set-right-margin}. Enriched mode binds these commands to -@kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the -margin width either with a numeric argument or in the minibuffer. - - Sometimes, as a result of editing, the filling of a paragraph becomes -messed up---parts of the paragraph may extend past the left or right -margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to -refill the paragraph. - - The fill prefix, if any, works in addition to the specified paragraph -indentation: @kbd{C-x .} does not include the specified indentation's -whitespace in the new value for the fill prefix, and the fill commands -look for the fill prefix after the indentation on each line. @xref{Fill -Prefix}. - -@node Format Justification -@subsection Justification in Formatted Text - - When editing formatted text, you can specify various styles of -justification for a paragraph. The style you specify automatically -affects the Emacs fill commands. - - The Justification submenu provides a convenient interface for specifying -the style. The submenu contains five items: - -@table @code -@item Left -This is the most common style of justification (at least for English). -Lines are aligned at the left margin but left uneven at the right. - -@item Right -This aligns each line with the right margin. Spaces and tabs are added -on the left, if necessary, to make lines line up on the right. - -@item Full -This justifies the text, aligning both edges of each line. Justified -text looks very nice in a printed book, where the spaces can all be -adjusted equally, but it does not look as nice with a fixed-width font -on the screen. Perhaps a future version of Emacs will be able to adjust -the width of spaces in a line to achieve elegant justification. - -@item Center -This centers every line between the current margins. - -@item Unfilled -This turns off filling entirely. Each line will remain as you wrote it; -the fill and auto-fill functions will have no effect on text which has -this setting. You can, however, still indent the left margin. In -unfilled regions, all newlines are treated as hard newlines (@pxref{Hard -and Soft Newlines}) . -@end table - - In Enriched mode, you can also specify justification from the keyboard -using the @kbd{M-j} prefix character: - -@table @kbd -@kindex M-j l @r{(Enriched mode)} -@findex set-justification-left -@item M-j l -Make the region left-filled (@code{set-justification-left}). -@kindex M-j r @r{(Enriched mode)} -@findex set-justification-right -@item M-j r -Make the region right-filled (@code{set-justification-right}). -@kindex M-j b @r{(Enriched mode)} -@findex set-justification-full -@item M-j b -Make the region fully justified (@code{set-justification-full}). -@kindex M-j c @r{(Enriched mode)} -@kindex M-S @r{(Enriched mode)} -@findex set-justification-center -@item M-j c -@itemx M-S -Make the region centered (@code{set-justification-center}). -@kindex M-j u @r{(Enriched mode)} -@findex set-justification-none -@item M-j u -Make the region unfilled (@code{set-justification-none}). -@end table - - Justification styles apply to entire paragraphs. All the -justification-changing commands operate on the paragraph containing -point, or, if the region is active, on all paragraphs which overlap the -region. - -@vindex default-justification - The default justification style is specified by the variable -@code{default-justification}. Its value should be one of the symbols -@code{left}, @code{right}, @code{full}, @code{center}, or @code{none}. -This is a per-buffer variable. Setting the variable directly affects -only the current buffer. However, customizing it in a Custom buffer -sets (as always) the default value for buffers that do not override it. -@xref{Locals}, and @ref{Easy Customization}. - -@node Format Properties -@subsection Setting Other Text Properties - - The Special Properties menu lets you add or remove three other useful text -properties: @code{read-only}, @code{invisible} and @code{intangible}. -The @code{intangible} property disallows moving point within the text, -the @code{invisible} text property hides text from display, and the -@code{read-only} property disallows alteration of the text. - - Each of these special properties has a menu item to add it to the -region. The last menu item, @samp{Remove Special}, removes all of these -special properties from the text in the region. - - Currently, the @code{invisible} and @code{intangible} properties are -@emph{not} saved in the text/enriched format. The @code{read-only} -property is saved, but it is not a standard part of the text/enriched -format, so other editors may not respect it. - -@node Forcing Enriched Mode -@subsection Forcing Enriched Mode - - Normally, Emacs knows when you are editing formatted text because it -recognizes the special annotations used in the file that you visited. -However, sometimes you must take special actions to convert file -contents or turn on Enriched mode: - -@itemize @bullet -@item -When you visit a file that was created with some other editor, Emacs may -not recognize the file as being in the text/enriched format. In this -case, when you visit the file you will see the formatting commands -rather than the formatted text. Type @kbd{M-x format-decode-buffer} to -translate it. This also automatically turns on Enriched mode. - -@item -When you @emph{insert} a file into a buffer, rather than visiting it, -Emacs does the necessary conversions on the text which you insert, but -it does not enable Enriched mode. If you wish to do that, type @kbd{M-x -enriched-mode}. -@end itemize - - The command @code{format-decode-buffer} translates text in various -formats into Emacs's internal format. It asks you to specify the format -to translate from; however, normally you can type just @key{RET}, which -tells Emacs to guess the format. - -@findex format-find-file - If you wish to look at a text/enriched file in its raw form, as a -sequence of characters rather than as formatted text, use the @kbd{M-x -find-file-literally} command. This visits a file, like -@code{find-file}, but does not do format conversion. It also inhibits -character code conversion (@pxref{Coding Systems}) and automatic -uncompression (@pxref{Compressed Files}). To disable format conversion -but allow character code conversion and/or automatic uncompression if -appropriate, use @code{format-find-file} with suitable arguments. - -@node Text Based Tables -@section Editing Text-based Tables -@cindex table mode -@cindex text-based tables - - Table mode provides an easy and intuitive way to create and edit WYSIWYG -text-based tables. Here is an example of such a table: - -@smallexample -@group -+-----------------+--------------------------------+-----------------+ -| Command | Description | Key Binding | -+-----------------+--------------------------------+-----------------+ -| forward-char |Move point right N characters | C-f | -| |(left if N is negative). | | -| | | | -| |On reaching end of buffer, stop | | -| |and signal error. | | -+-----------------+--------------------------------+-----------------+ -| backward-char |Move point left N characters | C-b | -| |(right if N is negative). | | -| | | | -| |On attempt to pass beginning or | | -| |end of buffer, stop and signal | | -| |error. | | -+-----------------+--------------------------------+-----------------+ -@end group -@end smallexample - - Table mode allows the contents of the table such as this one to be -easily manipulated by inserting or deleting characters inside a cell. -A cell is effectively a localized rectangular edit region and edits to -a cell do not affect the contents of the surrounding cells. If the -contents do not fit into a cell, then the cell is automatically -expanded in the vertical and/or horizontal directions and the rest of -the table is restructured and reformatted in accordance with the -growth of the cell. - -@menu -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Row Commands:: Manipulating rows of table cell. -* Column Commands:: Manipulating columns of table cell. -* Fixed Width Mode:: Fixing cell width. -* Table Conversion:: Converting between plain text and tables. -* Measuring Tables:: Analyzing table dimension. -* Table Misc:: Table miscellany. -@end menu - -@node Table Definition -@subsection What is a Text-based Table? - - Keep the following examples of valid tables in mind as a reference -while you read this section: - -@example - +--+----+---+ +-+ +--+-----+ - | | | | | | | | | - +--+----+---+ +-+ | +--+--+ - | | | | | | | | - +--+----+---+ +--+--+ | - | | | - +-----+--+ -@end example - - A table consists of a rectangular frame whose inside is divided into -cells. Each cell must be at least one character wide and one -character high, not counting its border lines. A cell can be -subdivided into multiple rectangular cells, but cells cannot overlap. - - The table frame and cell border lines are made of three special -characters. These variables specify those characters: - -@table @code -@vindex table-cell-vertical-char -@item table-cell-vertical-char -Holds the character used for vertical lines. The default value is -@samp{|}. - -@vindex table-cell-horizontal-char -@item table-cell-horizontal-char -Holds the character used for horizontal lines. The default value is -@samp{-}. - -@vindex table-cell-intersection-char -@item table-cell-intersection-char -Holds the character used at where horizontal line and vertical line -meet. The default value is @samp{+}. -@end table - -@noindent -Based on this definition, the following five tables are examples of invalid -tables: - -@example - +-----+ +-----+ +--+ +-++--+ ++ - | | | | | | | || | ++ - | +-+ | | | | | | || | - | | | | +--+ | +--+--+ +-++--+ - | +-+ | | | | | | | +-++--+ - | | | | | | | | | || | - +-----+ +--+--+ +--+--+ +-++--+ - a b c d e -@end example - -From left to right: - -@enumerate a -@item -Overlapped cells or non-rectangular cells are not allowed. -@item -Same as a. -@item -The border must be rectangular. -@item -Cells must have a minimum width/height of one character. -@item -Same as d. -@end enumerate - -@node Table Creation -@subsection How to Create a Table? -@cindex create a text-based table -@cindex table creation - -@findex table-insert - The command to create a table is @code{table-insert}. When called -interactively, it asks for the number of columns, number of rows, cell -width and cell height. The number of columns is the number of cells -horizontally side by side. The number of rows is the number of cells -vertically within the table's height. The cell width is a number of -characters that each cell holds, left to right. The cell height is a -number of lines each cell holds. The cell width and the cell height -can be either an integer (when the value is constant across the table) -or a series of integer, separated by spaces or commas, where each -number corresponds to the next cell within a row from left to right, -or the next cell within a column from top to bottom. - -@node Table Recognition -@subsection Table Recognition -@cindex table recognition - -@findex table-recognize -@findex table-unrecognize - Table mode maintains special text properties in the buffer to allow -editing in a convenient fashion. When a buffer with tables is saved -to its file, these text properties are lost, so when you visit this -file again later, Emacs does not see a table, but just formatted text. -To resurrect the table text properties, issue the @kbd{M-x -table-recognize} command. It scans the current buffer, recognizes -valid table cells, and attaches appropriate text properties to allow -for table editing. The converse command, @code{table-unrecognize}, is -used to remove the special text properties and convert the buffer back -to plain text. - - Special commands exist to enable or disable tables within a region, -enable or disable individual tables, and enable/disable individual -cells. These commands are: - -@table @kbd -@findex table-recognize-region -@item M-x table-recognize-region -Recognize tables within the current region and activate them. -@findex table-unrecognize-region -@item M-x table-unrecognize-region -Deactivate tables within the current region. -@findex table-recognize-table -@item M-x table-recognize-table -Recognize the table under point and activate it. -@findex table-unrecognize-table -@item M-x table-unrecognize-table -Deactivate the table under point. -@findex table-recognize-cell -@item M-x table-recognize-cell -Recognize the cell under point and activate it. -@findex table-unrecognize-cell -@item M-x table-unrecognize-cell -Deactivate the cell under point. -@end table - - For another way of converting text into tables, see @ref{Table -Conversion}. - -@node Cell Commands -@subsection Commands for Table Cells - -@findex table-forward-cell -@findex table-backward-cell - The commands @code{table-forward-cell} and -@code{table-backward-cell} move point from the current cell to an -adjacent cell forward and backward respectively. The order of the -cells is cyclic: when point is in the last cell of a table, typing -@kbd{M-x table-forward-cell} moves to the first cell in the table. -Likewise @kbd{M-x table-backward-cell} from the first cell in a table -moves to the last cell. - -@findex table-span-cell - The command @code{table-span-cell} merges the current cell with the -adjacent cell in a specified direction---right, left, above or below. -You specify the direction with the minibuffer. It does not allow -merges which don't result in a legitimate cell layout. - -@findex table-split-cell -@cindex text-based tables, split a cell -@cindex split table cell - The command @code{table-split-cell} splits the current cell -vertically or horizontally. This command is a wrapper to the -direction specific commands @code{table-split-cell-vertically} and -@code{table-split-cell-horizontally}. You specify the direction with -a minibuffer argument. - -@findex table-split-cell-vertically - The command @code{table-split-cell-vertically} splits the current -cell vertically and creates a pair of cells above and below where -point is located. The content in the original cell is split as well. - -@findex table-split-cell-horizontally - The command @code{table-split-cell-horizontally} splits the current -cell horizontally and creates a pair of cells right and left of where -point is located. If the cell being split is not empty, this asks you -how to handle the cell contents. The three options are: @code{split}, -@code{left}, or @code{right}. @code{split} splits the contents at -point literally, while the @code{left} and @code{right} options move -the entire contents into the left or right cell respectively. - -@cindex enlarge a table cell -@cindex shrink a table cell - The next four commands enlarge or shrink a cell. They use numeric -arguments (@pxref{Arguments}) to specify how many columns or rows to -enlarge or shrink a particular table. - -@table @kbd -@findex table-heighten-cell -@item M-x table-heighten-cell -Enlarge the current cell vertically. -@findex table-shorten-cell -@item M-x table-shorten-cell -Shrink the current cell vertically. -@findex table-widen-cell -@item M-x table-widen-cell -Enlarge the current cell horizontally. -@findex table-narrow-cell -@item M-x table-narrow-cell -Shrink the current cell horizontally. -@end table - -@node Cell Justification -@subsection Cell Justification -@cindex cell text justification - - You can specify text justification for each cell. The justification -is remembered independently for each cell and the subsequent editing -of cell contents is subject to the specified justification. - -@findex table-justify - The command @code{table-justify} ask you to specify what to justify: -a cell, a column, or a row. If you select cell justification, this -command sets the justification only for the current cell. Selecting -column or row justification sets the justification for all the cells -within a column or row respectively. The command then ask you which -kind of justification to apply: @code{left}, @code{center}, -@code{right}, @code{top}, @code{middle}, @code{bottom}, or -@code{none}. Horizontal justification and vertical justification are -specified independently. The options @code{left}, @code{center}, and -@code{right} specify horizontal justification while the options -@code{top}, @code{middle}, @code{bottom}, and @code{none} specify -vertical justification. The vertical justification @code{none} -effectively removes vertical justification. Horizontal justification -must be one of @code{left}, @code{center}, or @code{right}. - -@vindex table-detect-cell-alignment - Justification information is stored in the buffer as a part of text -property. Therefore, this information is ephemeral and does not -survive through the loss of the buffer (closing the buffer and -revisiting the buffer erase any previous text properties). To -countermand for this, the command @code{table-recognize} and other -recognition commands (@pxref{Table Recognition}) are equipped with a -convenience feature (turned on by default). During table recognition, -the contents of a cell are examined to determine which justification -was originally applied to the cell and then applies this justification -to the cell. This is a speculative algorithm and is therefore not -perfect, however, the justification is deduced correctly most of the -time. To disable this feature, customize the variable -@code{table-detect-cell-alignment} and set it to @code{nil}. - -@node Row Commands -@subsection Commands for Table Rows -@cindex table row commands - -@cindex insert row in table -@findex table-insert-row - The command @code{table-insert-row} inserts a row of cells before -the current row in a table. The current row where point is located is -pushed down after the newly inserted row. A numeric prefix argument -specifies the number of rows to insert. Note that in order to insert -rows @emph{after} the last row at the bottom of a table, you must -place point below the table---that is, outside the table---prior to -invoking this command. - -@cindex delete row in table -@findex table-delete-row - The command @code{table-delete-row} deletes a row of cells at point. -A numeric prefix argument specifies the number of rows to delete. - -@node Column Commands -@subsection Commands for Table Columns -@cindex table column commands - -@cindex insert column in table -@findex table-insert-column - The command @code{table-insert-column} inserts a column of cells to -the left of the current row in a table. This pushes the current -column to the right. To insert a column to the right side of the -rightmost column, place point to the right of the rightmost column, -which is outside of the table, prior to invoking this command. A -numeric prefix argument specifies the number of columns to insert. - -@cindex delete column in table - A command @code{table-delete-column} deletes a column of cells at -point. A numeric prefix argument specifies the number of columns to -delete. - -@node Fixed Width Mode -@subsection Fix Width of Cells -@cindex fix width of table cells - -@findex table-fixed-width-mode - The command @code{table-fixed-width-mode} toggles fixed width mode -on and off. When fixed width mode is turned on, editing inside a -cell never changes the cell width; when it is off, the cell width -expands automatically in order to prevent a word from being folded -into multiple lines. By default, fixed width mode is disabled. - -@node Table Conversion -@subsection Conversion Between Plain Text and Tables -@cindex text to table -@cindex table to text - -@findex table-capture - The command @code{table-capture} captures plain text in a region and -turns it into a table. Unlike @code{table-recognize} (@pxref{Table -Recognition}), the original text does not have a table appearance but -may hold a logical table structure. For example, some elements -separated by known patterns form a two dimensional structure which can -be turned into a table. - - Here's an example of data that @code{table-capture} can operate on. -The numbers are horizontally separated by a comma and vertically -separated by a newline character. - -@example -1, 2, 3, 4 -5, 6, 7, 8 -, 9, 10 -@end example - -@noindent -Invoking @kbd{M-x table-capture} on that text produces this table: - -@example -+-----+-----+-----+-----+ -|1 |2 |3 |4 | -+-----+-----+-----+-----+ -|5 |6 |7 |8 | -+-----+-----+-----+-----+ -| |9 |10 | | -+-----+-----+-----+-----+ -@end example - -@noindent -The conversion uses @samp{,} for the column delimiter and newline for -a row delimiter, cells are left justified, and minimum cell width is -5. - -@findex table-release - The command @code{table-release} does the opposite of -@code{table-capture}. It releases a table by removing the table frame -and cell borders. This leaves the table contents as plain text. One -of the useful applications of @code{table-capture} and -@code{table-release} is to edit a text in layout. Look at the -following three paragraphs (the latter two are indented with header -lines): - -@example -@samp{table-capture} is a powerful command, but mastering its -power requires some practice. Here are some things it can do: - -Parse Cell Items By using column delimiter regular - expression and raw delimiter regular - expression, it parses the specified text - area and extracts cell items from - non-table text and then forms a table out - of them. - -Capture Text Area When no delimiters are specified it - creates a single cell table. The text in - the specified region is placed in that - cell. -@end example - -@noindent -Applying @code{table-capture} to a region containing the above three -paragraphs, with empty strings for column delimiter regexp and row -delimiter regexp, creates a table with a single cell like the -following one. - -@c The first line's right-hand frame in the following two examples -@c sticks out to accommodate for the removal of @samp in the -@c produced output!! -@smallexample -@group -+-----------------------------------------------------------------+ -|@samp{table-capture} is a powerful command, but mastering its | -|power requires some practice. Here are some things it can do: | -| | -|Parse Cell Items By using column delimiter regular | -| expression and raw delimiter regular | -| expression, it parses the specified text | -| area and extracts cell items from | -| non-table text and then forms a table out | -| of them. | -| | -|Capture Text Area When no delimiters are specified it | -| creates a single cell table. The text in | -| the specified region is placed in that | -| cell. | -+-----------------------------------------------------------------+ -@end group -@end smallexample - -@noindent -By splitting the cell appropriately we now have a table consisting of -paragraphs occupying its own cell. Each cell can now be edited -independently without affecting the layout of other cells. - -@smallexample -+-----------------------------------------------------------------+ -|@samp{table-capture} is a powerful command, but mastering its | -|power requires some practice. Here are some things it can do: | -+---------------------+-------------------------------------------+ -|Parse Cell Items |By using column delimiter regular | -| |expression and raw delimiter regular | -| |expression, it parses the specified text | -| |area and extracts cell items from | -| |non-table text and then forms a table out | -| |of them. | -+---------------------+-------------------------------------------+ -|Capture Text Area |When no delimiters are specified it | -| |creates a single cell table. The text in | -| |the specified region is placed in that | -| |cell. | -+---------------------+-------------------------------------------+ -@end smallexample - -@noindent -By applying @code{table-release}, which does the opposite process, the -contents become once again plain text. @code{table-release} works as -a companion command to @code{table-capture}. - -@node Measuring Tables -@subsection Analyzing Table Dimensions -@cindex table dimensions - -@findex table-query-dimension - The command @code{table-query-dimension} analyzes a table structure -and reports information regarding its dimensions. In case of the -above example table, the @code{table-query-dimension} command displays -in echo area: - -@smallexample -Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5 -@end smallexample - -@noindent -This indicates that the current cell is 21 character wide and 6 lines -high, the entire table is 67 characters wide and 16 lines high. The -table has 2 columns and 3 rows. It has a total of 5 cells, since the -first row has a spanned cell. - -@node Table Misc -@subsection Table Miscellany - -@cindex insert string into table cells -@findex table-insert-sequence - The command @code{table-insert-sequence} inserts a string into each -cell. Each string is a part of a sequence i.e.@: a series of -increasing integer numbers. - -@cindex table in language format -@cindex table for HTML and LaTeX -@findex table-generate-source - The command @code{table-generate-source} generates a table formatted -for a specific markup language. It asks for a language (which must be -one of @code{html}, @code{latex}, or @code{cals}), a destination -buffer where to put the result, and the table caption (a string), and -then inserts the generated table in the proper syntax into the -destination buffer. The default destination buffer is -@code{table.@var{lang}}, where @var{lang} is the language you -specified. - -@ignore - arch-tag: 8db54ed8-2036-49ca-b0df-23811d03dc70 -@end ignore diff --git a/man/tramp.texi b/man/tramp.texi deleted file mode 100644 index b53bc59d506..00000000000 --- a/man/tramp.texi +++ /dev/null @@ -1,3297 +0,0 @@ -\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/man/trampver.texi b/man/trampver.texi deleted file mode 100644 index 4ed196a80f0..00000000000 --- a/man/trampver.texi +++ /dev/null @@ -1,62 +0,0 @@ -@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/man/trouble.texi b/man/trouble.texi deleted file mode 100644 index ea494445a4e..00000000000 --- a/man/trouble.texi +++ /dev/null @@ -1,1066 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Dealing with Common Problems - - If you type an Emacs command you did not intend, the results are often -mysterious. This chapter tells what you can do to cancel your mistake or -recover from a mysterious situation. Emacs bugs and system crashes are -also considered. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Quitting, Lossage, Customization, Top -@section Quitting and Aborting -@cindex quitting - -@table @kbd -@item C-g -@itemx C-@key{BREAK} @r{(MS-DOS only)} -Quit: cancel running or partially typed command. -@item C-] -Abort innermost recursive editing level and cancel the command which -invoked it (@code{abort-recursive-edit}). -@item @key{ESC} @key{ESC} @key{ESC} -Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). -@item M-x top-level -Abort all recursive editing levels that are currently executing. -@item C-x u -Cancel a previously made change in the buffer contents (@code{undo}). -@end table - - There are two ways of canceling a command before it has finished: -@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or -@kbd{M-x top-level}. Quitting cancels a partially typed command, or -one which is still running. Aborting exits a recursive editing level -and cancels the command that invoked the recursive edit. -(@xref{Recursive Edit}.) - -@cindex quitting -@kindex C-g - Quitting with @kbd{C-g} is the way to get rid of a partially typed -command, or a numeric argument that you don't want. It also stops a -running command in the middle in a relatively safe way, so you can use -it if you accidentally give a command which takes a long time. In -particular, it is safe to quit out of a kill command; either your text -will @emph{all} still be in the buffer, or it will @emph{all} be in -the kill ring, or maybe both. Quitting an incremental search does -special things, documented under searching; it may take two successive -@kbd{C-g} characters to get out of a search (@pxref{Incremental -Search}). - - On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character -like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to -recognize @kbd{C-g} while a command is running, between interactions -with the user. By contrast, it @emph{is} feasible to recognize -@kbd{C-@key{BREAK}} at all times. -@iftex -@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{MS-DOS Keyboard}. -@end ifnottex - - -@findex keyboard-quit - @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} -the instant @kbd{C-g} is typed; Emacs Lisp checks this variable -frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only -actually executed as a command if you type it while Emacs is waiting for -input. In that case, the command it runs is @code{keyboard-quit}. - - On a text terminal, if you quit with @kbd{C-g} a second time before -the first @kbd{C-g} is recognized, you activate the ``emergency -escape'' feature and return to the shell. @xref{Emergency Escape}. - -@cindex NFS and quitting - There are some situations where you cannot quit. When Emacs is -waiting for the operating system to do something, quitting is -impossible unless special pains are taken for the particular system -call within Emacs where the waiting occurs. We have done this for the -system calls that users are likely to want to quit from, but it's -possible you will a case not handled. In one very common -case---waiting for file input or output using NFS---Emacs itself knows -how to quit, but many NFS implementations simply do not allow user -programs to stop waiting for NFS when the NFS server is hung. - -@cindex aborting recursive edit -@findex abort-recursive-edit -@kindex C-] - Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get -out of a recursive editing level and cancel the command which invoked -it. Quitting with @kbd{C-g} does not do this, and could not do this, -because it is used to cancel a partially typed command @emph{within} the -recursive editing level. Both operations are useful. For example, if -you are in a recursive edit and type @kbd{C-u 8} to enter a numeric -argument, you can cancel that argument with @kbd{C-g} and remain in the -recursive edit. - -@findex keyboard-escape-quit -@kindex ESC ESC ESC - The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} -(@code{keyboard-escape-quit}) can either quit or abort. (We defined -it this way because @key{ESC} means ``get out'' in many PC programs.) -It can cancel a prefix argument, clear a selected region, or get out -of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer -or a recursive edit, like @kbd{C-]}. It can also get out of splitting -the frame into multiple windows, as with @kbd{C-x 1}. One thing it -cannot do, however, is stop a command that is running. That's because -it executes as an ordinary command, and Emacs doesn't notice it until -it is ready for the next command. - -@findex top-level - The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]} -commands to get you out of all the levels of recursive edits that you -are in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x -top-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-x -top-level} are like all other commands, and unlike @kbd{C-g}, in that -they take effect only when Emacs is ready for a command. @kbd{C-]} is -an ordinary key and has its meaning only because of its binding in the -keymap. @xref{Recursive Edit}. - - @kbd{C-x u} (@code{undo}) is not strictly speaking a way of canceling -a command, but you can think of it as canceling a command that already -finished executing. @xref{Undo}, for more information -about the undo facility. - -@node Lossage, Bugs, Quitting, Top -@section Dealing with Emacs Trouble - - This section describes various conditions in which Emacs fails to work -normally, and how to recognize them and correct them. For a list of -additional problems you might encounter, see @ref{Bugs and problems, , -Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS} -in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type -@kbd{C-h C-e} to read the @file{PROBLEMS} file. - -@menu -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: Emergency escape--- - What to do if Emacs stops responding. -* Total Frustration:: When you are at your wits' end. -@end menu - -@node DEL Does Not Delete -@subsection If @key{DEL} Fails to Delete -@cindex @key{DEL} vs @key{BACKSPACE} -@cindex @key{BACKSPACE} vs @key{DEL} -@cindex usual erasure key - - Every keyboard has a large key, a little ways above the @key{RET} or -@key{ENTER} key, which you normally use outside Emacs to erase the -last character that you typed. We call this key @dfn{the usual -erasure key}. In Emacs, it is supposed to be equivalent to @key{DEL}, -and when Emacs is properly configured for your terminal, it translates -that key into the character @key{DEL}. - - When Emacs starts up on a graphical display, it determines -automatically which key should be @key{DEL}. In some unusual cases -Emacs gets the wrong information from the system. If the usual -erasure key deletes forwards instead of backwards, that is probably -what happened---Emacs ought to be treating the @key{DELETE} key as -@key{DEL}, but it isn't. - - On a graphical display, if the usual erasure key is labeled -@key{BACKSPACE} and there is a @key{DELETE} key elsewhere, but the -@key{DELETE} key deletes backward instead of forward, that too -suggests Emacs got the wrong information---but in the opposite sense. -It ought to be treating the @key{BACKSPACE} key as @key{DEL}, and -treating @key{DELETE} differently, but it isn't. - - On a text-only terminal, if you find the usual erasure key prompts -for a Help command, like @kbd{Control-h}, instead of deleting a -character, it means that key is actually sending the @key{BS} -character. Emacs ought to be treating @key{BS} as @key{DEL}, but it -isn't. - - In all of those cases, the immediate remedy is the same: use the -command @kbd{M-x normal-erase-is-backspace-mode}. This toggles -between the two modes that Emacs supports for handling @key{DEL}, so -if Emacs starts in the wrong mode, this should switch to the right -mode. On a text-only terminal, if you want to ask for help when -@key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also -work, if it sends character code 127. - -@findex normal-erase-is-backspace-mode - To fix the problem automatically for every Emacs session, you can -put one of the following lines into your @file{.emacs} file -(@pxref{Init File}). For the first case above, where @key{DELETE} -deletes forwards instead of backwards, use this line to make -@key{DELETE} act as @key{DEL} (resulting in behavior compatible -with Emacs 20 and previous versions): - -@lisp -(normal-erase-is-backspace-mode 0) -@end lisp - -@noindent -For the other two cases, where @key{BACKSPACE} ought to act as -@key{DEL}, use this line: - -@lisp -(normal-erase-is-backspace-mode 1) -@end lisp - -@vindex normal-erase-is-backspace - Another way to fix the problem for every Emacs session is to -customize the variable @code{normal-erase-is-backspace}: the value -@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is -@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy -Customization}. - - On a graphical display, it can also happen that the usual erasure key -is labeled @key{BACKSPACE}, there is a @key{DELETE} key elsewhere, and -both keys delete forward. This probably means that someone has -redefined your @key{BACKSPACE} key as a @key{DELETE} key. With X, -this is typically done with a command to the @code{xmodmap} program -when you start the server or log in. The most likely motive for this -customization was to support old versions of Emacs, so we recommend -you simply remove it now. - -@node Stuck Recursive -@subsection Recursive Editing Levels - - Recursive editing levels are important and useful features of Emacs, but -they can seem like malfunctions if you do not understand them. - - If the mode line has square brackets @samp{[@dots{}]} around the parentheses -that contain the names of the major and minor modes, you have entered a -recursive editing level. If you did not do this on purpose, or if you -don't understand what that means, you should just get out of the recursive -editing level. To do so, type @kbd{M-x top-level}. This is called getting -back to top level. @xref{Recursive Edit}. - -@node Screen Garbled -@subsection Garbage on the Screen - - If the text on a text terminal looks wrong, the first thing to do is -see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay -the entire screen. If the screen appears correct after this, the -problem was entirely in the previous screen update. (Otherwise, see -the following section.) - - Display updating problems often result from an incorrect terminfo -entry for the terminal you are using. The file @file{etc/TERMS} in -the Emacs distribution gives the fixes for known problems of this -sort. @file{INSTALL} contains general advice for these problems in -one of its sections. To investigate the possibility that you have -this sort of problem, try Emacs on another terminal made by a -different manufacturer. If problems happen frequently on one kind of -terminal but not another kind, it is likely to be a bad terminfo entry, -though it could also be due to a bug in Emacs that appears for -terminals that have or that lack specific features. - -@node Text Garbled -@subsection Garbage in the Text - - If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to -see what commands you typed to produce the observed results. Then try -undoing the changes step by step using @kbd{C-x u}, until it gets back -to a state you consider correct. - - If a large portion of text appears to be missing at the beginning or -end of the buffer, check for the word @samp{Narrow} in the mode line. -If it appears, the text you don't see is probably still present, but -temporarily off-limits. To make it accessible again, type @kbd{C-x n -w}. @xref{Narrowing}. - -@node Memory Full -@subsection Running out of Memory -@cindex memory full -@cindex out of memory - - If you get the error message @samp{Virtual memory exceeded}, save -your modified buffers with @kbd{C-x s}. This method of saving them -has the smallest need for additional memory. Emacs keeps a reserve of -memory which it makes available when this error happens; that should -be enough to enable @kbd{C-x s} to complete its work. When the -reserve has been used, @samp{!MEM FULL!} appears at the beginning of -the mode line, indicating there is no more reserve. - - Once you have saved your modified buffers, you can exit this Emacs -session and start another, or you can use @kbd{M-x kill-some-buffers} -to free space in the current Emacs job. If this frees up sufficient -space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} -will disappear from the mode line. That means you can safely go on -editing in the same Emacs session. - - Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run -out of memory, because the buffer menu needs a fair amount of memory -itself, and the reserve supply may not be enough. - -@node After a Crash -@subsection Recovery After a Crash - - If Emacs or the computer crashes, you can recover the files you were -editing at the time of the crash from their auto-save files. To do -this, start Emacs again and type the command @kbd{M-x recover-session}. - - This command initially displays a buffer which lists interrupted -session files, each with its date. You must choose which session to -recover from. Typically the one you want is the most recent one. Move -point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} considers each of the files that you -were editing during that session; for each such file, it asks whether -to recover that file. If you answer @kbd{y} for a file, it shows the -dates of that file and its auto-save file, then asks once again -whether to recover that file. For the second question, you must -confirm with @kbd{yes}. If you do, Emacs visits the file but gets the -text from the auto-save file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - - As a last resort, if you had buffers with content which were not -associated with any files, or if the autosave was not recent enough to -have recorded important changes, you can use the -@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to -retrieve them from a core dump--provided that a core dump was saved, -and that the Emacs executable was not stripped of its debugging -symbols. - - As soon as you get the core dump, rename it to another name such as -@file{core.emacs}, so that another crash won't overwrite it. - - To use this script, run @code{gdb} with the file name of your Emacs -executable and the file name of the core dump, e.g. @samp{gdb -/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the -recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. -Then type the command @code{ybuffer-list} to see which buffers are -available. For each buffer, it lists a buffer number. To save a -buffer, use @code{ysave-buffer}; you specify the buffer number, and -the file name to write that buffer into. You should use a file name -which does not already exist; if the file does exist, the script does -not make a backup of its old contents. - -@node Emergency Escape -@subsection Emergency Escape - - On text-only terminals, the @dfn{emergency escape} feature suspends -Emacs immediately if you type @kbd{C-g} a second time before Emacs can -actually respond to the first one by quitting. This is so you can -always get out of GNU Emacs no matter how badly it might be hung. -When things are working properly, Emacs recognizes and handles the -first @kbd{C-g} so fast that the second one won't trigger emergency -escape. However, if some problem prevents Emacs from handling the -first @kbd{C-g} properly, then the second one will get you back to the -shell. - - When you resume Emacs after a suspension caused by emergency escape, -it asks two questions before going back to what it had been doing: - -@example -Auto-save? (y or n) -Abort (and dump core)? (y or n) -@end example - -@noindent -Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. - - Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of -all modified buffers in which auto-saving is enabled. Saying @kbd{n} -skips this. - - Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to -crash, dumping core. This is to enable a wizard to figure out why -Emacs was failing to quit in the first place. Execution does not -continue after a core dump. - - If you answer this question @kbd{n}, Emacs execution resumes. With -luck, Emacs will ultimately do the requested quit. If not, each -subsequent @kbd{C-g} invokes emergency escape again. - - If Emacs is not really hung, just slow, you may invoke the double -@kbd{C-g} feature without really meaning to. Then just resume and -answer @kbd{n} to both questions, and you will get back to the former -state. The quit you requested will happen by and by. - - Emergency escape is active only for text terminals. On graphical -displays, you can use the mouse to kill Emacs or switch to another -program. - - On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause -emergency escape---but there are cases where it won't work, when -system call hangs or when Emacs is stuck in a tight loop in C code. - -@node Total Frustration -@subsection Help for Total Frustration -@cindex Eliza -@cindex doctor - - If using Emacs (or something else) becomes terribly frustrating and none -of the techniques described above solve the problem, Emacs can still help -you. - - First, if the Emacs you are using is not responding to commands, type -@kbd{C-g C-g} to get out of it and then start a new one. - -@findex doctor - Second, type @kbd{M-x doctor @key{RET}}. - - The Emacs psychotherapist will help you feel better. Each time you -say something to the psychotherapist, you must end it by typing -@key{RET} @key{RET}. This indicates you are finished typing. - -@node Bugs, Contributing, Lossage, Top -@section Reporting Bugs - -@cindex bugs - Sometimes you will encounter a bug in Emacs. Although we cannot -promise we can or will fix the bug, and we might not even agree that it -is a bug, we want to hear about problems you encounter. Often we agree -they are bugs and want to fix them. - - To make it possible for us to fix a bug, you must report it. In order -to do so effectively, you must know when and how to do it. - - Before reporting a bug, it is a good idea to see if it is already -known. You can find the list of known problems in the file -@file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-e} to read -it. Some additional user-level problems can be found in @ref{Bugs and -problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your -problem in these two documents might provide you with a solution or a -work-around, or give you additional information about related issues. - -@menu -* Criteria: Bug Criteria. Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. -@end menu - -@node Bug Criteria -@subsection When Is There a Bug - - If Emacs accesses an invalid memory location (``segmentation -fault''), or exits with an operating system error message that -indicates a problem in the program (as opposed to something like -``disk full''), then it is certainly a bug. - - If Emacs updates the display in a way that does not correspond to what is -in the buffer, then it is certainly a bug. If a command seems to do the -wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a -case of incorrect display updating. - - Taking forever to complete a command can be a bug, but you must make -certain that it was really Emacs's fault. Some commands simply take a -long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l} -to see whether the input Emacs received was what you intended to type; -if the input was such that you @emph{know} it should have been processed -quickly, report a bug. If you don't know whether the command should -take a long time, find out by looking in the manual or by asking for -assistance. - - If a command you are familiar with causes an Emacs error message in a -case where its usual definition ought to be reasonable, it is probably a -bug. - - If a command does the wrong thing, that is a bug. But be sure you know -for certain what it ought to have done. If you aren't familiar with the -command, or don't know for certain how the command is supposed to work, -then it might actually be working right. Rather than jumping to -conclusions, show the problem to someone who knows for certain. - - Finally, a command's intended definition may not be the best -possible definition for editing with. This is a very important sort -of problem, but it is also a matter of judgment. Also, it is easy to -come to such a conclusion out of ignorance of some of the existing -features. It is probably best not to complain about such a problem -until you have checked the documentation in the usual ways, feel -confident that you understand it, and know for certain that what you -want is not available. Ask other Emacs users, too. If you are not -sure what the command is supposed to do after a careful reading of the -manual, check the index and glossary for any terms that may be -unclear. - - If after careful rereading of the manual you still do not understand -what the command should do, that indicates a bug in the manual, which -you should report. The manual's job is to make everything clear to -people who are not Emacs experts---including you. It is just as -important to report documentation bugs as program bugs. - - If the on-line documentation string of a function or variable disagrees -with the manual, one of them must be wrong; that is a bug. - -@node Understanding Bug Reporting -@subsection Understanding Bug Reporting - -@findex emacs-version - When you decide that there is a bug, it is important to report it and to -report it in a way which is useful. What is most useful is an exact -description of what commands you type, starting with the shell command to -run Emacs, until the problem happens. - - The most important principle in reporting a bug is to report -@emph{facts}. Hypotheses and verbal descriptions are no substitute for -the detailed raw data. Reporting the facts is straightforward, but many -people strain to posit explanations and report them instead of the -facts. If the explanations are based on guesses about how Emacs is -implemented, they will be useless; meanwhile, lacking the facts, we will -have no real information about the bug. - - For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh -@key{RET}}, visiting a file which (you know) happens to be rather -large, and Emacs displays @samp{I feel pretty today}. The best way to -report the bug is with a sentence like the preceding one, because it -gives all the facts. - - A bad way would be to assume that the problem is due to the size of -the file and say, ``I visited a large file, and Emacs displayed @samp{I -feel pretty today}.'' This is what we mean by ``guessing -explanations.'' The problem is just as likely to be due to the fact -that there is a @samp{z} in the file name. If this is so, then when we -got your report, we would try out the problem with some ``large file,'' -probably with no @samp{z} in its name, and not see any problem. There -is no way in the world that we could guess that we should try visiting a -file with a @samp{z} in its name. - - Alternatively, the problem might be due to the fact that the file starts -with exactly 25 spaces. For this reason, you should make sure that you -inform us of the exact contents of any file that is needed to reproduce the -bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} -command previously? This is why we ask you to give the exact sequence of -characters you typed since starting the Emacs session. - - You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless -you @emph{know} that it makes no difference which visiting command is used. -Similarly, rather than saying ``if I have three characters on the line,'' -say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is -the way you entered the text. - - So please don't guess any explanations when you report a bug. If you -want to actually @emph{debug} the problem, and report explanations that -are more than guesses, that is useful---but please include the facts as -well. - -@node Checklist -@subsection Checklist for Bug Reports - -@cindex reporting bugs - The best way to send a bug report is to mail it electronically to the -Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to -@email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta -release. (If you want to suggest a change as an improvement, use the -same address.) - - If you'd like to read the bug reports, you can find them on the -newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a -spectator you should not criticize anything about what you see there. -The purpose of bug reports is to give information to the Emacs -maintainers. Spectators are welcome only as long as they do not -interfere with this. In particular, some bug reports contain fairly -large amounts of data; spectators should not complain about this. - - Please do not post bug reports using netnews; mail is more reliable -than netnews about reporting your correct address, which we may need -in order to ask you for more information. If your data is more than -500,000 bytes, please don't include it directly in the bug report; -instead, offer to send it on request, or make it available by ftp and -say where. - -@findex report-emacs-bug - A convenient way to send a bug report for Emacs is to use the command -@kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending -Mail}) and automatically inserts @emph{some} of the essential -information. However, it cannot supply all the necessary information; -you should still read and follow the guidelines below, so you can enter -the other crucial information by hand before you send the message. - - To enable maintainers to investigate a bug, your report -should include all these things: - -@itemize @bullet -@item -The version number of Emacs. Without this, we won't know whether there -is any point in looking for the bug in the current version of GNU -Emacs. - -You can get the version number by typing @kbd{M-x emacs-version -@key{RET}}. If that command does not work, you probably have something -other than GNU Emacs, so you will have to report the bug somewhere -else. - -@item -The type of machine you are using, and the operating system name and -version number. @kbd{M-x emacs-version @key{RET}} provides this -information too. Copy its output from the @samp{*Messages*} buffer, so -that you get it all and get it accurately. - -@item -The operands given to the @code{configure} command when Emacs was -installed. - -@item -A complete list of any modifications you have made to the Emacs source. -(We may not have time to investigate the bug unless it happens in an -unmodified Emacs. But if you've made modifications and you don't tell -us, you are sending us on a wild goose chase.) - -Be precise about these changes. A description in English is not -enough---send a context diff for them. - -Adding files of your own, or porting to another machine, is a -modification of the source. - -@item -Details of any other deviations from the standard procedure for installing -GNU Emacs. - -@item -The complete text of any files needed to reproduce the bug. - - If you can tell us a way to cause the problem without visiting any files, -please do so. This makes it much easier to debug. If you do need files, -make sure you arrange for us to see their exact contents. For example, it -can matter whether there are spaces at the ends of lines, or a -newline after the last line in the buffer (nothing ought to care whether -the last line is terminated, but try telling the bugs that). - -@item -The precise commands we need to type to reproduce the bug. - -@findex open-dribble-file -@cindex dribble file -@cindex logging keystrokes -The easy way to record the input to Emacs precisely is to write a -dribble file. To start the file, execute the Lisp expression - -@example -(open-dribble-file "~/dribble") -@end example - -@noindent -using @kbd{M-:} or from the @samp{*scratch*} buffer just after -starting Emacs. From then on, Emacs copies all your input to the -specified dribble file until the Emacs process is killed. - -@item -@findex open-termscript -@cindex termscript file -@cindex @env{TERM} environment variable -For possible display bugs, the terminal type (the value of environment -variable @env{TERM}), the complete termcap entry for the terminal from -@file{/etc/termcap} (since that file is not identical on all machines), -and the output that Emacs actually sent to the terminal. - -The way to collect the terminal output is to execute the Lisp expression - -@example -(open-termscript "~/termscript") -@end example - -@noindent -using @kbd{M-:} or from the @samp{*scratch*} buffer just after -starting Emacs. From then on, Emacs copies all terminal output to the -specified termscript file as well, until the Emacs process is killed. -If the problem happens when Emacs starts up, put this expression into -your @file{.emacs} file so that the termscript file will be open when -Emacs displays the screen for the first time. - -Be warned: it is often difficult, and sometimes impossible, to fix a -terminal-dependent bug without access to a terminal of the type that -stimulates the bug. - -@item -If non-@acronym{ASCII} text or internationalization is relevant, the locale that -was current when you started Emacs. On GNU/Linux and Unix systems, or -if you use a Posix-style shell such as Bash, you can use this shell -command to view the relevant values: - -@smallexample -echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ - LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG -@end smallexample - -Alternatively, use the @command{locale} command, if your system has it, -to display your locale settings. - -You can use the @kbd{M-!} command to execute these commands from -Emacs, and then copy the output from the @samp{*Messages*} buffer into -the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL -@key{RET}} will display the value of @code{LC_ALL} in the echo area, and -you can copy its output from the @samp{*Messages*} buffer. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``The Emacs process gets a fatal signal,'' or, -``The resulting text is as follows, which I think is wrong.'' - -Of course, if the bug is that Emacs gets a fatal signal, then one can't -miss it. But if the bug is incorrect text, the maintainer might fail to -notice what is wrong. Why leave it to chance? - -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of the source is out of sync, or you have encountered a bug in the -C library on your system. (This has happened!) Your copy might crash -and the copy here might not. If you @emph{said} to expect a crash, then -when Emacs here fails to crash, we would know that the bug was not -happening. If you don't say to expect a crash, then we would not know -whether the bug was happening---we would not be able to draw any -conclusion from our observations. - -@item -If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual -fails to describe the actual behavior of Emacs, or that the text is -confusing, copy in the text from the online manual which you think is -at fault. If the section is small, just the section name is enough. - -@item -If the manifestation of the bug is an Emacs error message, it is -important to report the precise text of the error message, and a -backtrace showing how the Lisp program in Emacs arrived at the error. - -To get the error message text accurately, copy it from the -@samp{*Messages*} buffer into the bug report. Copy all of it, not just -part. - -@findex toggle-debug-on-error -@pindex Edebug -To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} -before the error happens (that is to say, you must give that command -and then make the bug happen). This causes the error to start the Lisp -debugger, which shows you a backtrace. Copy the text of the -debugger's backtrace into the bug report. @xref{Debugger,, The Lisp -Debugger, elisp, the Emacs Lisp Reference Manual}, for information on -debugging Emacs Lisp programs with the Edebug package. - -This use of the debugger is possible only if you know how to make the -bug happen again. If you can't make it happen again, at least copy -the whole error message. - -@item -Check whether any programs you have loaded into the Lisp world, -including your @file{.emacs} file, set any variables that may affect the -functioning of Emacs. Also, see whether the problem happens in a -freshly started Emacs without loading your @file{.emacs} file (start -Emacs with the @code{-q} switch to prevent loading the init file). If -the problem does @emph{not} occur then, you must report the precise -contents of any programs that you must load into the Lisp world in order -to cause the problem to occur. - -@item -If the problem does depend on an init file or other Lisp programs that -are not part of the standard Emacs system, then you should make sure it -is not a bug in those programs by complaining to their maintainers -first. After they verify that they are using Emacs in a way that is -supposed to work, they should report the bug. - -@item -If you wish to mention something in the GNU Emacs source, show the line -of code with a few lines of context. Don't just give a line number. - -The line numbers in the development sources don't match those in your -sources. It would take extra work for the maintainers to determine what -code is in your version at a given line number, and we could not be -certain. - -@item -Additional information from a C debugger such as GDB might enable -someone to find a problem on a machine which he does not have available. -If you don't know how to use GDB, please read the GDB manual---it is not -very long, and using GDB is easy. You can find the GDB distribution, -including the GDB manual in online form, in most of the same places you -can find the Emacs distribution. To run Emacs under GDB, you should -switch to the @file{src} subdirectory in which Emacs was compiled, then -do @samp{gdb emacs}. It is important for the directory @file{src} to be -current so that GDB will read the @file{.gdbinit} file in this -directory. - -However, you need to think when you collect the additional information -if you want it to show what causes the bug. - -@cindex backtrace for bug reports -For example, many people send just a backtrace, but that is not very -useful by itself. A simple backtrace with arguments often conveys -little about what is happening inside GNU Emacs, because most of the -arguments listed in the backtrace are pointers to Lisp objects. The -numeric values of these pointers have no significance whatever; all that -matters is the contents of the objects they point to (and most of the -contents are themselves pointers). - -@findex debug_print -To provide useful information, you need to show the values of Lisp -objects in Lisp notation. Do this for each variable which is a Lisp -object, in several stack frames near the bottom of the stack. Look at -the source to see which variables are Lisp objects, because the debugger -thinks of them as integers. - -To show a variable's value in Lisp syntax, first print its value, then -use the user-defined GDB command @code{pr} to print the Lisp object in -Lisp syntax. (If you must use another debugger, call the function -@code{debug_print} with the object as an argument.) The @code{pr} -command is defined by the file @file{.gdbinit}, and it works only if you -are debugging a running process (not with a core dump). - -To make Lisp errors stop Emacs and return to GDB, put a breakpoint at -@code{Fsignal}. - -For a short listing of Lisp functions running, type the GDB -command @code{xbacktrace}. - -The file @file{.gdbinit} defines several other commands that are useful -for examining the data types and contents of Lisp objects. Their names -begin with @samp{x}. These commands work at a lower level than -@code{pr}, and are less convenient, but they may work even when -@code{pr} does not, such as when debugging a core dump or when Emacs has -had a fatal signal. - -@cindex debugging Emacs, tricks and techniques -More detailed advice and other useful techniques for debugging Emacs -are available in the file @file{etc/DEBUG} in the Emacs distribution. -That file also includes instructions for investigating problems -whereby Emacs stops responding (many people assume that Emacs is -``hung,'' whereas in fact it might be in an infinite loop). - -To find the file @file{etc/DEBUG} in your Emacs installation, use the -directory name stored in the variable @code{data-directory}. -@end itemize - -Here are some things that are not necessary in a bug report: - -@itemize @bullet -@item -A description of the envelope of the bug---this is not necessary for a -reproducible bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time-consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -You might as well save time by not searching for additional examples. -It is better to send the bug report right away, go back to editing, -and find another bug to report. - -Of course, if you can find a simpler example to report @emph{instead} of -the original one, that is a convenience. Errors in the output will be -easier to spot, running under the debugger will take less time, etc. - -However, simplification is not vital; if you can't do this or don't have -time to try, please report the bug with your original test case. - -@item -A core dump file. - -Debugging the core dump might be useful, but it can only be done on -your machine, with your Emacs executable. Therefore, sending the core -dump file to the Emacs maintainers won't be useful. Above all, don't -include the core file in an email bug report! Such a large message -can be extremely inconvenient. - -@item -A system-call trace of Emacs execution. - -System-call traces are very useful for certain special kinds of -debugging, but in most cases they give little useful information. It is -therefore strange that many people seem to think that @emph{the} way to -report information about a crash is to send a system-call trace. Perhaps -this is a habit formed from experience debugging programs that don't -have source code or debugging symbols. - -In most programs, a backtrace is normally far, far more informative than -a system-call trace. Even in Emacs, a simple backtrace is generally -more informative, though to give full information you should supplement -the backtrace by displaying variable values and printing them as Lisp -objects with @code{pr} (see above). - -@item -A patch for the bug. - -A patch for the bug is useful if it is a good one. But don't omit the -other information that a bug report needs, such as the test case, on the -assumption that a patch is sufficient. We might see problems with your -patch and decide to fix the problem another way, or we might not -understand it at all. And if we can't understand what bug you are -trying to fix, or why your patch should be an improvement, we mustn't -install it. - -@ifnottex -@xref{Sending Patches}, for guidelines on how to make it easy for us to -understand and install your patches. -@end ifnottex - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even experts can't guess right about -such things without first using the debugger to find the facts. -@end itemize - -@node Sending Patches -@subsection Sending Patches for GNU Emacs - -@cindex sending patches for GNU Emacs -@cindex patches, sending - If you would like to write bug fixes or improvements for GNU Emacs, -that is very helpful. When you send your changes, please follow these -guidelines to make it easy for the maintainers to use them. If you -don't follow these guidelines, your information might still be useful, -but using it will take extra work. Maintaining GNU Emacs is a lot of -work in the best of circumstances, and we can't keep up unless you do -your best to help. - -@itemize @bullet -@item -Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a bug fix, just include a copy of the -bug report, and explain why the change fixes the bug. - -(Referring to a bug report is not as good as including it, because then -we will have to look it up, and we have probably already deleted it if -we've already fixed the bug.) - -@item -Always include a proper bug report for the problem you think you have -fixed. We need to convince ourselves that the change is right before -installing it. Even if it is correct, we might have trouble -understanding it if we don't have a way to reproduce the problem. - -@item -Include all the comments that are appropriate to help people reading the -source in the future understand why this change was needed. - -@item -Don't mix together changes made for different reasons. -Send them @emph{individually}. - -If you make two changes for separate reasons, then we might not want to -install them both. We might want to install just one. If you send them -all jumbled together in a single set of diffs, we have to do extra work -to disentangle them---to figure out which parts of the change serve -which purpose. If we don't have time for this, we might have to ignore -your changes entirely. - -If you send each change as soon as you have written it, with its own -explanation, then two changes never get tangled up, and we can consider -each one properly without any extra work to disentangle them. - -@item -Send each change as soon as that change is finished. Sometimes people -think they are helping us by accumulating many changes to send them all -together. As explained above, this is absolutely the worst thing you -could do. - -Since you should send each change separately, you might as well send it -right away. That gives us the option of installing it immediately if it -is important. - -@item -Use @samp{diff -c} to make your diffs. Diffs without context are hard -to install reliably. More than that, they are hard to study; we must -always study a patch to decide whether we want to install it. Unidiff -format is better than contextless diffs, but not as easy to read as -@samp{-c} format. - -If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when -making diffs of C code. This shows the name of the function that each -change occurs in. - -@item -Avoid any ambiguity as to which is the old version and which is the new. -Please make the old version the first argument to diff, and the new -version the second argument. And please give one version or the other a -name that indicates whether it is the old version or your new changed -one. - -@item -Write the change log entries for your changes. This is both to save us -the extra work of writing them, and to help explain your changes so we -can understand them. - -The purpose of the change log is to show people where to find what was -changed. So you need to be specific about what functions you changed; -in large functions, it's often helpful to indicate where within the -function the change was. - -On the other hand, once you have shown people where to find the change, -you need not explain its purpose in the change log. Thus, if you add a -new function, all you need to say about it is that it is new. If you -feel that the purpose needs explaining, it probably does---but put the -explanation in comments in the code. It will be more useful there. - -Please read the @file{ChangeLog} files in the @file{src} and -@file{lisp} directories to see what sorts of information to put in, -and to learn the style that we use. @xref{Change Log}. - -@item -When you write the fix, keep in mind that we can't install a change that -would break other systems. Please think about what effect your change -will have if compiled on another type of system. - -Sometimes people send fixes that @emph{might} be an improvement in -general---but it is hard to be sure of this. It's hard to install -such changes because we have to study them very carefully. Of course, -a good explanation of the reasoning by which you concluded the change -was correct can help convince us. - -The safest changes are changes to the configuration files for a -particular machine. These are safe because they can't create new bugs -on other machines. - -Please help us keep up with the workload by designing the patch in a -form that is clearly safe to install. -@end itemize - -@node Contributing, Service, Bugs, Top -@section Contributing to Emacs Development - -If you would like to help pretest Emacs releases to assure they work -well, or if you would like to work on improving Emacs, please contact -the maintainers at @email{emacs-devel@@gnu.org}. A pretester -should be prepared to investigate bugs as well as report them. If you'd -like to work on improving Emacs, please ask for suggested projects or -suggest your own ideas. - -If you have already written an improvement, please tell us about it. If -you have not yet started work, it is useful to contact -@email{emacs-devel@@gnu.org} before you start; it might be -possible to suggest ways to make your extension fit in better with the -rest of Emacs. - -The development version of Emacs can be downloaded from the CVS -repository where it is actively maintained by a group of developers. -See the Emacs project page -@url{http://savannah.gnu.org/projects/emacs/} for details. - -@node Service, Copying, Contributing, Top -@section How To Get Help with GNU Emacs - -If you need help installing, using or changing GNU Emacs, there are two -ways to find it: - -@itemize @bullet -@item -Send a message to the mailing list -@email{help-gnu-emacs@@gnu.org}, or post your request on -newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup -interconnect, so it does not matter which one you use.) - -@item -Look in the service directory for someone who might help you for a fee. -The service directory is found in the file named @file{etc/SERVICE} in the -Emacs distribution. -@end itemize - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c -@end ignore diff --git a/man/url.texi b/man/url.texi deleted file mode 100644 index 0fc6b08acdc..00000000000 --- a/man/url.texi +++ /dev/null @@ -1,1202 +0,0 @@ -\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/man/vc-xtra.texi b/man/vc-xtra.texi deleted file mode 100644 index 6ec69d60896..00000000000 --- a/man/vc-xtra.texi +++ /dev/null @@ -1,32 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included in emacs-xtra.texi when producing the printed -@c version. -@iftex -@node Advanced VC Usage -@section Advanced VC Usage - - Commonly used features of Emacs' version control (VC) support are -described in the main Emacs manual (@pxref{Version Control,,,emacs, -the Emacs Manual}). This chapter describes more advanced VC usage. - -@menu -* VC Dired Mode:: Listing files managed by version control. -* VC Dired Commands:: Commands to use in a VC Dired buffer. -* Remote Repositories:: Efficient access to remote CVS servers. -* Snapshots:: Sets of file versions treated as a unit. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end menu -@end iftex - -@iftex -@include vc1-xtra.texi -@include vc2-xtra.texi -@end iftex - -@ignore - arch-tag: 11a18d0e-1baf-49da-8e38-f61195ae4dc3 -@end ignore diff --git a/man/vc1-xtra.texi b/man/vc1-xtra.texi deleted file mode 100644 index 6d5df78848c..00000000000 --- a/man/vc1-xtra.texi +++ /dev/null @@ -1,151 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in vc-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node VC Dired Mode -@subsection Dired under VC - -@cindex PCL-CVS -@pindex cvs -@cindex CVS Dired Mode - The VC Dired Mode described here works with all the version control -systems that VC supports. Another more powerful facility, designed -specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS, -pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. - -@kindex C-x v d -@findex vc-directory - When you are working on a large program, it is often useful to find -out which files have changed within an entire directory tree, or to view -the status of all files under version control at once, and to perform -version control operations on collections of files. You can use the -command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing -that includes only files relevant for version control. - -@vindex vc-dired-terse-display - @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks -much like an ordinary Dired buffer -@iftex -(@pxref{Dired,,,emacs, the Emacs Manual}); -@end iftex -@ifnottex -(@pxref{Dired}); -@end ifnottex -however, normally it shows only the noteworthy files (those locked or -not up-to-date). This is called @dfn{terse display}. If you set the -variable @code{vc-dired-terse-display} to @code{nil}, then VC Dired -shows all relevant files---those managed under version control, plus -all subdirectories (@dfn{full display}). The command @kbd{v t} in a -VC Dired buffer toggles between terse display and full display -(@pxref{VC Dired Commands}). - -@vindex vc-dired-recurse - By default, VC Dired produces a recursive listing of noteworthy or -relevant files at or below the given directory. You can change this by -setting the variable @code{vc-dired-recurse} to @code{nil}; then VC -Dired shows only the files in the given directory. - - The line for an individual file shows the version control state in the -place of the hard link count, owner, group, and size of the file. If -the file is unmodified, in sync with the master file, the version -control state shown is blank. Otherwise it consists of text in -parentheses. Under RCS and SCCS, the name of the user locking the file -is shown; under CVS, an abbreviated version of the @samp{cvs status} -output is used. Here is an example using RCS: - -@smallexample -@group - /home/jim/project: - - -rw-r--r-- (jim) Apr 2 23:39 file1 - -r--r--r-- Apr 5 20:21 file2 -@end group -@end smallexample - -@noindent -The files @samp{file1} and @samp{file2} are under version control, -@samp{file1} is locked by user jim, and @samp{file2} is unlocked. - - Here is an example using CVS: - -@smallexample -@group - /home/joe/develop: - - -rw-r--r-- (modified) Aug 2 1997 file1.c - -rw-r--r-- Apr 4 20:09 file2.c - -rw-r--r-- (merge) Sep 13 1996 file3.c -@end group -@end smallexample - - Here @samp{file1.c} is modified with respect to the repository, and -@samp{file2.c} is not. @samp{file3.c} is modified, but other changes -have also been checked in to the repository---you need to merge them -with the work file before you can check it in. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local - In the above, if the repository were on a remote machine, VC would -only contact it when the variable @code{vc-stay-local} (or -@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is -because access to the repository may be slow, or you may be working -offline and not have access to the repository at all. As a -consequence, VC would not be able to tell you that @samp{file3.c} is -in the ``merge'' state; you would learn that only when you try to -check-in your modified copy of the file, or use a command such as -@kbd{C-x v m}. - - In practice, this is not a problem because CVS handles this case -consistently whenever it arises. In VC, you'll simply get prompted to -merge the remote changes into your work file first. The benefits of -less network communication usually outweigh the disadvantage of not -seeing remote changes immediately. - -@vindex vc-directory-exclusion-list - When VC Dired displays subdirectories (in the ``full'' display mode), -it omits some that should never contain any files under version control. -By default, this includes Version Control subdirectories such as -@samp{RCS} and @samp{CVS}; you can customize this by setting the -variable @code{vc-directory-exclusion-list}. - - You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in -ordinary Dired, that allows you to specify additional switches for the -@samp{ls} command. - -@node VC Dired Commands -@subsection VC Dired Commands - - All the usual Dired commands work normally in VC Dired mode, except -for @kbd{v}, which is redefined as the version control prefix. You can -invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by -typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply -to the file name on the current line. - - The command @kbd{v v} (@code{vc-next-action}) operates on all the -marked files, so that you can lock or check in several files at once. -If it operates on more than one file, it handles each file according to -its current state; thus, it might lock one file, but check in another -file. This could be confusing; it is up to you to avoid confusing -behavior by marking a set of files that are in a similar state. If no -files are marked, @kbd{v v} operates on the file in the current line. - - If any files call for check-in, @kbd{v v} reads a single log entry, -then uses it for all the files being checked in. This is convenient for -registering or checking in several files at once, as part of the same -change. - -@findex vc-dired-toggle-terse-mode -@findex vc-dired-mark-locked - You can toggle between terse display (only locked files, or files not -up-to-date) and full display at any time by typing @kbd{v t} -(@code{vc-dired-toggle-terse-mode}). There is also a special command -@kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently -locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l -t k} is another way to delete from the buffer all files except those -currently locked. - -@ignore - arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263 -@end ignore diff --git a/man/vc2-xtra.texi b/man/vc2-xtra.texi deleted file mode 100644 index 83f28088726..00000000000 --- a/man/vc2-xtra.texi +++ /dev/null @@ -1,789 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in vc-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Remote Repositories -@subsection Remote Repositories -@cindex remote repositories (CVS) - - A common way of using CVS is to set up a central CVS repository on -some Internet host, then have each developer check out a personal -working copy of the files on his local machine. Committing changes to -the repository, and picking up changes from other users into one's own -working area, then works by direct interactions with the CVS server. - - One difficulty is that access to the CVS server is often slow, and -that developers might need to work off-line as well. VC is designed -to reduce the amount of network interaction necessary. - -@menu -* Version Backups:: Keeping local copies of repository versions. -* Local Version Control:: Using another version system for local editing. -@end menu - -@node Version Backups -@subsubsection Version Backups -@cindex version backups - -@cindex automatic version backups - When VC sees that the CVS repository for a file is on a remote -machine, it automatically makes local backups of unmodified versions -of the file---@dfn{automatic version backups}. This means that you -can compare the file to the repository version (@kbd{C-x v =}), or -revert to that version (@kbd{C-x v u}), without any network -interactions. - - The local copy of the unmodified file is called a @dfn{version -backup} to indicate that it corresponds exactly to a version that is -stored in the repository. Note that version backups are not the same -as ordinary Emacs backup files -@iftex -(@pxref{Backup,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Backup}). -@end ifnottex -But they follow a similar naming convention. - - For a file that comes from a remote CVS repository, VC makes a -version backup whenever you save the first changes to the file, and -removes it after you have committed your modified version to the -repository. You can disable the making of automatic version backups by -setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). - -@cindex manual version backups - The name of the automatic version backup for version @var{version} -of file @var{file} is @code{@var{file}.~@var{version}.~}. This is -almost the same as the name used by @kbd{C-x v ~} -@iftex -(@pxref{Old Versions,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Old Versions}), -@end ifnottex -the only difference being the additional dot (@samp{.}) after the -version number. This similarity is intentional, because both kinds of -files store the same kind of information. The file made by @kbd{C-x v -~} acts as a @dfn{manual version backup}. - - All the VC commands that operate on old versions of a file can use -both kinds of version backups. For instance, @kbd{C-x v ~} uses -either an automatic or a manual version backup, if possible, to get -the contents of the version you request. Likewise, @kbd{C-x v =} and -@kbd{C-x v u} use either an automatic or a manual version backup, if -one of them exists, to get the contents of a version to compare or -revert to. If you changed a file outside of Emacs, so that no -automatic version backup was created for the previous text, you can -create a manual backup of that version using @kbd{C-x v ~}, and thus -obtain the benefit of the local copy for Emacs commands. - - The only difference in Emacs's handling of manual and automatic -version backups, once they exist, is that Emacs deletes automatic -version backups when you commit to the repository. By contrast, -manual version backups remain until you delete them. - -@node Local Version Control -@subsubsection Local Version Control -@cindex local version control -@cindex local back end (version control) - -When you make many changes to a file that comes from a remote -repository, it can be convenient to have version control on your local -machine as well. You can then record intermediate versions, revert to -a previous state, etc., before you actually commit your changes to the -remote server. - -VC lets you do this by putting a file under a second, local version -control system, so that the file is effectively registered in two -systems at the same time. For the description here, we will assume -that the remote system is CVS, and you use RCS locally, although the -mechanism works with any combination of version control systems -(@dfn{back ends}). - -To make it work with other back ends, you must make sure that the -``more local'' back end comes before the ``more remote'' back end in -the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By -default, this variable is set up so that you can use remote CVS and -local RCS as described here. - -To start using local RCS for a file that comes from a remote CVS -server, you must @emph{register the file in RCS}, by typing @kbd{C-u -C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a -prefix argument, and specify RCS as the back end.) - -You can do this at any time; it does not matter whether you have -already modified the file with respect to the version in the CVS -repository. If possible, VC tries to make the RCS master start with -the unmodified repository version, then checks in any local changes -as a new version. This works if you have not made any changes yet, or -if the unmodified repository version exists locally as a version -backup (@pxref{Version Backups}). If the unmodified version is not -available locally, the RCS master starts with the modified version; -the only drawback to this is that you cannot compare your changes -locally to what is stored in the repository. - -The version number of the RCS master is derived from the current CVS -version, starting a branch from it. For example, if the current CVS -version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in -the RCS master will be identical to version 1.23 under CVS; your first -changes are checked in as 1.23.1.1. (If the unmodified file is not -available locally, VC will check in the modified file twice, both as -1.23 and 1.23.1.1, to make the revision numbers consistent.) - -If you do not use locking under CVS (the default), locking is also -disabled for RCS, so that editing under RCS works exactly as under -CVS. - -When you are done with local editing, you can commit the final version -back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. -This initializes the log entry buffer -@iftex -(@pxref{Log Buffer,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Log Buffer}) -@end ifnottex -to contain all the log entries you have recorded in the RCS master; -you can edit them as you wish, and then commit in CVS by typing -@kbd{C-c C-c}. If the commit is successful, VC removes the RCS -master, so that the file is once again registered under CVS only. -(The RCS master is not actually deleted, just renamed by appending -@samp{~} to the name, so that you can refer to it later if you wish.) - -While using local RCS, you can pick up recent changes from the CVS -repository into your local file, or commit some of your changes back -to CVS, without terminating local RCS version control. To do this, -switch to the CVS back end temporarily, with the @kbd{C-x v b} command: - -@table @kbd -@item C-x v b -Switch to another back end that the current file is registered -under (@code{vc-switch-backend}). - -@item C-u C-x v b @var{backend} @key{RET} -Switch to @var{backend} for the current file. -@end table - -@kindex C-x v b -@findex vc-switch-backend -@kbd{C-x v b} does not change the buffer contents, or any files; it -only changes VC's perspective on how to handle the file. Any -subsequent VC commands for that file will operate on the back end that -is currently selected. - -If the current file is registered in more than one back end, typing -@kbd{C-x v b} ``cycles'' through all of these back ends. With a -prefix argument, it asks for the back end to use in the minibuffer. - -Thus, if you are using local RCS, and you want to pick up some recent -changes in the file from remote CVS, first visit the file, then type -@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m -@key{RET}} to merge the news -@iftex -(@pxref{Merging,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Merging}). -@end ifnottex -You can then switch back to RCS by typing @kbd{C-x v b} again, and -continue to edit locally. - -But if you do this, the revision numbers in the RCS master no longer -correspond to those of CVS. Technically, this is not a problem, but -it can become difficult to keep track of what is in the CVS repository -and what is not. So we suggest that you return from time to time to -CVS-only operation, by committing your local changes back to the -repository using @kbd{C-u C-x v v cvs @key{RET}}. - -@node Snapshots -@subsection Snapshots -@cindex snapshots and version control - - A @dfn{snapshot} is a named set of file versions (one for each -registered file) that you can treat as a unit. One important kind of -snapshot is a @dfn{release}, a (theoretically) stable version of the -system that is ready for distribution to users. - -@menu -* Making Snapshots:: The snapshot facilities. -* Snapshot Caveats:: Things to be careful of when using snapshots. -@end menu - -@node Making Snapshots -@subsubsection Making and Using Snapshots - - There are two basic commands for snapshots; one makes a -snapshot with a given name, the other retrieves a named snapshot. - -@table @code -@kindex C-x v s -@findex vc-create-snapshot -@item C-x v s @var{name} @key{RET} -Define the last saved versions of every registered file in or under the -current directory as a snapshot named @var{name} -(@code{vc-create-snapshot}). - -@kindex C-x v r -@findex vc-retrieve-snapshot -@item C-x v r @var{name} @key{RET} -For all registered files at or below the current directory level, select -whatever versions correspond to the snapshot @var{name} -(@code{vc-retrieve-snapshot}). - -This command reports an error if any files are locked at or below the -current directory, without changing anything; this is to avoid -overwriting work in progress. -@end table - - A snapshot uses a very small amount of resources---just enough to record -the list of file names and which version belongs to the snapshot. Thus, -you need not hesitate to create snapshots whenever they are useful. - - You can give a snapshot name as an argument to @kbd{C-x v =} or -@kbd{C-x v ~} -@iftex -(@pxref{Old Versions,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Old Versions}). -@end ifnottex -Thus, you can use it to compare a snapshot against the current files, -or two snapshots against each other, or a snapshot against a named -version. - -@node Snapshot Caveats -@subsubsection Snapshot Caveats - -@cindex named configurations (RCS) - VC's snapshot facilities are modeled on RCS's named-configuration -support. They use RCS's native facilities for this, so -snapshots made using RCS through VC are visible even when you bypass VC. - - With CVS, Meta-CVS, and Subversion, VC also uses the native -mechanism provided by that back end to make snapshots and retrieve them -(@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion). - -@c worded verbosely to avoid overfull hbox. - For SCCS, VC implements snapshots itself. The files it uses contain -name/file/version-number triples. These snapshots are visible only -through VC. - - There is no support for VC snapshots using GNU Arch yet. - - A snapshot is a set of checked-in versions. So make sure that all the -files are checked in and not locked when you make a snapshot. - - File renaming and deletion can create some difficulties with snapshots. -This is not a VC-specific problem, but a general design issue in version -control systems that no one has solved very well yet. - - If you rename a registered file, you need to rename its master along -with it (the command @code{vc-rename-file} does this automatically). If -you are using SCCS, you must also update the records of the snapshot, to -mention the file by its new name (@code{vc-rename-file} does this, -too). An old snapshot that refers to a master file that no longer -exists under the recorded name is invalid; VC can no longer retrieve -it. It would be beyond the scope of this manual to explain enough about -RCS and SCCS to explain how to update the snapshots by hand. - - Using @code{vc-rename-file} makes the snapshot remain valid for -retrieval, but it does not solve all problems. For example, some of the -files in your program probably refer to others by name. At the very -least, the makefile probably mentions the file that you renamed. If you -retrieve an old snapshot, the renamed file is retrieved under its new -name, which is not the name that the makefile expects. So the program -won't really work as retrieved. - -@node Miscellaneous VC -@subsection Miscellaneous Commands and Features of VC - - This section explains the less-frequently-used features of VC. - -@menu -* Change Logs and VC:: Generating a change log file from log entries. -* Renaming and VC:: A command to rename both the source and master - file correctly. -* Version Headers:: Inserting version control headers into working files. -@end menu - -@node Change Logs and VC -@subsubsection Change Logs and VC - - If you use RCS or CVS for a program and also maintain a change log -file for it -@iftex -(@pxref{Change Log,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Change Log}), -@end ifnottex -you can generate change log entries automatically from the version -control log entries: - -@table @kbd -@item C-x v a -@kindex C-x v a -@findex vc-update-change-log -Visit the current directory's change log file and, for registered files -in that directory, create new entries for versions checked in since the -most recent entry in the change log file. -(@code{vc-update-change-log}). - -This command works with RCS or CVS only, not with any of the other -back ends. - -@item C-u C-x v a -As above, but only find entries for the current buffer's file. - -@item M-1 C-x v a -As above, but find entries for all the currently visited files that are -maintained with version control. This works only with RCS, and it puts -all entries in the log for the default directory, which may not be -appropriate. -@end table - - For example, suppose the first line of @file{ChangeLog} is dated -1999-04-10, and that the only check-in since then was by Nathaniel -Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log -messages that start with `#'.}. Then @kbd{C-x v a} visits -@file{ChangeLog} and inserts text like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-22 Nathaniel Bowditch - - * rcs2log: Ignore log messages that start with `#'. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - -@noindent -You can then edit the new change log entry further as you wish. - - Some of the new change log entries may duplicate what's already in -ChangeLog. You will have to remove these duplicates by hand. - - Normally, the log entry for file @file{foo} is displayed as @samp{* -foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted -if the text of the log entry starts with @w{@samp{(@var{functionname}): -}}. For example, if the log entry for @file{vc.el} is -@samp{(vc-do-command): Check call-process status.}, then the text in -@file{ChangeLog} looks like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-06 Nathaniel Bowditch - - * vc.el (vc-do-command): Check call-process status. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - When @kbd{C-x v a} adds several change log entries at once, it groups -related log entries together if they all are checked in by the same -author at nearly the same time. If the log entries for several such -files all have the same text, it coalesces them into a single entry. -For example, suppose the most recent check-ins have the following log -entries: - -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} -@end flushleft - -@noindent -They appear like this in @file{ChangeLog}: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch - - * vc.texinfo: Fix expansion typos. - - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - Normally, @kbd{C-x v a} separates log entries by a blank line, but you -can mark several related log entries to be clumped together (without an -intervening blank line) by starting the text of each related log entry -with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label -itself is not copied to @file{ChangeLog}. For example, suppose the log -entries are: - -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} -@end flushleft - -@noindent -Then the text in @file{ChangeLog} looks like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch - - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - A log entry whose text begins with @samp{#} is not copied to -@file{ChangeLog}. For example, if you merely fix some misspellings in -comments, you can log the change with an entry beginning with @samp{#} -to avoid putting such trivia into @file{ChangeLog}. - -@node Renaming and VC -@subsubsection Renaming VC Work Files and Master Files - -@findex vc-rename-file - When you rename a registered file, you must also rename its master -file correspondingly to get proper results. Use @code{vc-rename-file} -to rename the source file as you specify, and rename its master file -accordingly. It also updates any snapshots (@pxref{Snapshots}) that -mention the file, so that they use the new name; despite this, the -snapshot thus modified may not completely work (@pxref{Snapshot -Caveats}). - - Some back ends do not provide an explicit rename operation to their -repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} -on the original and renamed buffers and provide the necessary edit -log. - - You cannot use @code{vc-rename-file} on a file that is locked by -someone else. - -@node Version Headers -@subsubsection Inserting Version Control Headers - - Sometimes it is convenient to put version identification strings -directly into working files. Certain special strings called -@dfn{version headers} are replaced in each successive version by the -number of that version, the name of the user who created it, and other -relevant information. All of the back ends that VC supports have such -a mechanism, except GNU Arch. - - VC does not normally use the information contained in these headers. -The exception is RCS---with RCS, version headers are sometimes more -reliable than the master file to determine which version of the file -you are editing. Note that in a multi-branch environment, version -headers are necessary to make VC behave correctly -@iftex -(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Multi-User Branching}). -@end ifnottex - - Searching for RCS version headers is controlled by the variable -@code{vc-consult-headers}. If it is non-@code{nil} (the default), -Emacs searches for headers to determine the version number you are -editing. Setting it to @code{nil} disables this feature. - - Note that although CVS uses the same kind of version headers as RCS -does, VC never searches for these headers if you are using CVS, -regardless of the above setting. - -@kindex C-x v h -@findex vc-insert-headers - You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to -insert a suitable header string. - -@table @kbd -@item C-x v h -Insert headers in a file for use with your version-control system. -@end table - -@vindex vc-@var{backend}-header - The default header string is @samp{@w{$}Id$} for RCS and -@samp{@w{%}W%} for SCCS. You can specify other headers to insert by -setting the variables @code{vc-@var{backend}-header} where -@var{backend} is @code{rcs} or @code{sccs}. - - Instead of a single string, you can specify a list of strings; then -each string in the list is inserted as a separate header on a line of -its own. - - It may be necessary to use apparently-superfluous backslashes when -writing the strings that you put in this variable. For instance, you -might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra -backslash prevents the string constant from being interpreted as a -header, if the Emacs Lisp file containing it is maintained with -version control. - -@vindex vc-comment-alist - Each header is inserted surrounded by tabs, inside comment delimiters, -on a new line at point. Normally the ordinary comment -start and comment end strings of the current mode are used, but for -certain modes, there are special comment delimiters for this purpose; -the variable @code{vc-comment-alist} specifies them. Each element of -this list has the form @code{(@var{mode} @var{starter} @var{ender})}. - -@vindex vc-static-header-alist - The variable @code{vc-static-header-alist} specifies further strings -to add based on the name of the buffer. Its value should be a list of -elements of the form @code{(@var{regexp} . @var{format})}. Whenever -@var{regexp} matches the buffer name, @var{format} is inserted as part -of the header. A header line is inserted for each element that matches -the buffer name, and for each string specified by -@code{vc-@var{backend}-header}. The header line is made by processing the -string from @code{vc-@var{backend}-header} with the format taken from the -element. The default value for @code{vc-static-header-alist} is as follows: - -@example -@group -(("\\.c$" . - "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ -#endif /* lint */\n")) -@end group -@end example - -@noindent -It specifies insertion of text of this form: - -@example -@group - -#ifndef lint -static char vcid[] = "@var{string}"; -#endif /* lint */ -@end group -@end example - -@noindent -Note that the text above starts with a blank line. - - If you use more than one version header in a file, put them close -together in the file. The mechanism in @code{revert-buffer} that -preserves markers may not handle markers positioned between two version -headers. - -@node Customizing VC -@subsection Customizing VC - -@vindex vc-handled-backends -The variable @code{vc-handled-backends} determines which version -control systems VC should handle. The default value is @code{(RCS CVS -SVN SCCS BZR GIT HG Arch MCVS)}, so it contains all the version systems -that are currently supported. If you want VC to ignore one or more of -these systems, exclude its name from the list. To disable VC entirely, -set this variable to @code{nil}. - -The order of systems in the list is significant: when you visit a file -registered in more than one system (@pxref{Local Version Control}), VC -uses the system that comes first in @code{vc-handled-backends} by -default. The order is also significant when you register a file for -the first time, see -@iftex -@ref{Registering,,,emacs, the Emacs Manual}, -@end iftex -@ifnottex -@ref{Registering}, -@end ifnottex -for details. - -@menu -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. -@end menu - -@node General VC Options -@subsubsection General Options - -@vindex vc-make-backup-files - Emacs normally does not save backup files for source files that are -maintained with version control. If you want to make backup files even -for files that use version control, set the variable -@code{vc-make-backup-files} to a non-@code{nil} value. - -@vindex vc-keep-workfiles - Normally the work file exists all the time, whether it is locked or -not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking -in a new version with @kbd{C-x v v} deletes the work file; but any -attempt to visit the file with Emacs creates it again. (With CVS, work -files are always kept.) - -@vindex vc-follow-symlinks - Editing a version-controlled file through a symbolic link can be -dangerous. It bypasses the version control system---you can edit the -file without locking it, and fail to check your changes in. Also, -your changes might overwrite those of another user. To protect against -this, VC checks each symbolic link that you visit, to see if it points -to a file under version control. - - The variable @code{vc-follow-symlinks} controls what to do when a -symbolic link points to a version-controlled file. If it is @code{nil}, -VC only displays a warning message. If it is @code{t}, VC automatically -follows the link, and visits the real file instead, telling you about -this in the echo area. If the value is @code{ask} (the default), VC -asks you each time whether to follow the link. - -@vindex vc-suppress-confirm - If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} -and @kbd{C-x v i} can save the current buffer without asking, and -@kbd{C-x v u} also operates without asking for confirmation. (This -variable does not affect @kbd{C-x v c}; that operation is so drastic -that it should always ask for confirmation.) - -@vindex vc-command-messages - VC mode does much of its work by running the shell commands for RCS, -CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC -displays messages to indicate which shell commands it runs, and -additional messages when the commands finish. - -@vindex vc-path - You can specify additional directories to search for version control -programs by setting the variable @code{vc-path}. These directories -are searched before the usual search path. It is rarely necessary to -set this variable, because VC normally finds the proper files -automatically. - -@node RCS and SCCS -@subsubsection Options for RCS and SCCS - -@cindex non-strict locking (RCS) -@cindex locking, non-strict (RCS) - By default, RCS uses locking to coordinate the activities of several -users, but there is a mode called @dfn{non-strict locking} in which -you can check-in changes without locking the file first. Use -@samp{rcs -U} to switch to non-strict locking for a particular file, -see the @code{rcs} manual page for details. - - When deducing the version control state of an RCS file, VC first -looks for an RCS version header string in the file (@pxref{Version -Headers}). If there is no header string, VC normally looks at the -file permissions of the work file; this is fast. But there might be -situations when the file permissions cannot be trusted. In this case -the master file has to be consulted, which is rather expensive. Also -the master file can only tell you @emph{if} there's any lock on the -file, but not whether your work file really contains that locked -version. - -@vindex vc-consult-headers - You can tell VC not to use version headers to determine the file -status by setting @code{vc-consult-headers} to @code{nil}. VC then -always uses the file permissions (if it is supposed to trust them), or -else checks the master file. - -@vindex vc-mistrust-permissions - You can specify the criterion for whether to trust the file -permissions by setting the variable @code{vc-mistrust-permissions}. -Its value can be @code{t} (always mistrust the file permissions and -check the master file), @code{nil} (always trust the file -permissions), or a function of one argument which makes the decision. -The argument is the directory name of the @file{RCS} subdirectory. A -non-@code{nil} value from the function says to mistrust the file -permissions. If you find that the file permissions of work files are -changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. -Then VC always checks the master file to determine the file's status. - - VC determines the version control state of files under SCCS much as -with RCS. It does not consider SCCS version headers, though. Thus, -the variable @code{vc-mistrust-permissions} affects SCCS use, but -@code{vc-consult-headers} does not. - -@node CVS Options -@subsubsection Options specific for CVS - -@cindex locking (CVS) - By default, CVS does not use locking to coordinate the activities of -several users; anyone can change a work file at any time. However, -there are ways to restrict this, resulting in behavior that resembles -locking. - -@cindex CVSREAD environment variable (CVS) - For one thing, you can set the @env{CVSREAD} environment variable -(the value you use makes no difference). If this variable is defined, -CVS makes your work files read-only by default. In Emacs, you must -type @kbd{C-x v v} to make the file writable, so that editing works -in fact similar as if locking was used. Note however, that no actual -locking is performed, so several users can make their files writable -at the same time. When setting @env{CVSREAD} for the first time, make -sure to check out all your modules anew, so that the file protections -are set correctly. - -@cindex cvs watch feature -@cindex watching files (CVS) - Another way to achieve something similar to locking is to use the -@dfn{watch} feature of CVS. If a file is being watched, CVS makes it -read-only by default, and you must also use @kbd{C-x v v} in Emacs to -make it writable. VC calls @code{cvs edit} to make the file writable, -and CVS takes care to notify other developers of the fact that you -intend to change the file. See the CVS documentation for details on -using the watch feature. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local -@cindex remote repositories (CVS) - When a file's repository is on a remote machine, VC tries to keep -network interactions to a minimum. This is controlled by the variable -@code{vc-cvs-stay-local}. There is another variable, -@code{vc-stay-local}, which enables the feature also for other back -ends that support it, including CVS. In the following, we will talk -only about @code{vc-cvs-stay-local}, but everything applies to -@code{vc-stay-local} as well. - -If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses -only the entry in the local CVS subdirectory to determine the file's -state (and possibly information returned by previous CVS commands). -One consequence of this is that when you have modified a file, and -somebody else has already checked in other changes to the file, you -are not notified of it until you actually try to commit. (But you can -try to pick up any recent changes from the repository first, using -@kbd{C-x v m @key{RET}}, -@iftex -@pxref{Merging,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -@pxref{Merging}). -@end ifnottex - - When @code{vc-cvs-stay-local} is @code{t}, VC also makes local -version backups, so that simple diff and revert operations are -completely local (@pxref{Version Backups}). - - On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, -then VC queries the remote repository @emph{before} it decides what to -do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local -repositories. It also does not make any version backups. - - You can also set @code{vc-cvs-stay-local} to a regular expression -that is matched against the repository host name; VC then stays local -only for repositories from hosts that match the pattern. - -@vindex vc-cvs-global-switches - You can specify additional command line options to pass to all CVS -operations in the variable @code{vc-cvs-global-switches}. These -switches are inserted immediately after the @code{cvs} command, before -the name of the operation to invoke. - -@ignore - arch-tag: 140b8629-4339-4b5e-9e50-72453e51615e -@end ignore diff --git a/man/vip.texi b/man/vip.texi deleted file mode 100644 index a3f4a447f82..00000000000 --- a/man/vip.texi +++ /dev/null @@ -1,1958 +0,0 @@ -\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/man/viper.texi b/man/viper.texi deleted file mode 100644 index 55c97f18c9c..00000000000 --- a/man/viper.texi +++ /dev/null @@ -1,4579 +0,0 @@ -% -*-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