diff options
Diffstat (limited to 'doc/misc')
62 files changed, 11044 insertions, 6305 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 6c9557cb0e..917ebf0d67 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,31 +1,190 @@ +2011-05-18 Teodor Zlatanov <[email protected]> + + * gnus.texi (Gnus Registry Setup): Rename from "Setup". + (Store custom flags and keywords): Mention + `gnus-registry-user-format-function-M' and + `gnus-registry-user-format-function-M2'. + +2011-05-17 Paul Eggert <[email protected]> + + * texinfo.tex: Sync from gnulib, version 2011-05-11.16. + +2011-05-17 Glenn Morris <[email protected]> + + * gnus.texi (Face): Fix typo. + +2011-05-14 Glenn Morris <[email protected]> + + * dired-x.texi (Omitting Examples): Minor addition. + +2011-05-10 Jim Meyering <[email protected]> + + * ede.texi: Fix typo "or or -> or". + +2011-05-03 Peter Münster <[email protected]> (tiny change) + + * gnus.texi (Summary Buffer Lines): + gnus-summary-user-date-format-alist does not exist. + (Sorting the Summary Buffer): More about sorting threads. + +2011-04-25 Michael Albinus <[email protected]> + + * trampver.texi: Update release number. + +2011-04-14 Michael Albinus <[email protected]> + + * tramp.texi (Frequently Asked Questions): New item for disabling + Tramp in other packages. + +2011-04-14 Teodor Zlatanov <[email protected]> + + * gnus.texi (nnmairix caveats, Setup, Registry Article Refer Method) + (Fancy splitting to parent, Store arbitrary data): Updated + gnus-registry docs. + +2011-04-13 Juanma Barranquero <[email protected]> + + * ede.texi: Fix typos. + +2011-04-12 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Window Layout): @itemize @code doesn't exist. + It's @table @code. + +2011-03-19 Antoine Levitt <[email protected]> + + * gnus.texi (Listing Groups): Document gnus-group-list-ticked + +2011-03-17 Jay Belanger <[email protected]> + + * calc.texi (Logarithmic Units): Update the function names. + +2011-03-15 Lars Magne Ingebrigtsen <[email protected]> + + * message.texi (Various Commands): Document format specs in the + ellipsis. + +2011-03-15 Antoine Levitt <[email protected]> + + * message.texi (Insertion Variables): Document message-cite-style. + +2011-03-14 Michael Albinus <[email protected]> + + * tramp.texi (Remote processes): New subsection "Running shell on + a remote host". + +2011-03-12 Teodor Zlatanov <[email protected]> + + * auth.texi (Help for developers): Update docs to explain that the + :save-function will only run the first time. + +2011-03-12 Glenn Morris <[email protected]> + + * Makefile.in (emacs-faq.html): Fix some more cross-refs. + (emacs-faq.text): New target. + (clean): Add emacs-faq. + 2011-03-12 Michael Albinus <[email protected]> + Sync with Tramp 2.2.1. + * trampver.texi: Update release number. +2011-03-11 Glenn Morris <[email protected]> + + * Makefile.in (HTML_TARGETS): New. + (clean): Delete $HTML_TARGETS. + (emacs-faq.html): New, for use with the gnu.org Emacs webpage. + +2011-03-08 Teodor Zlatanov <[email protected]> + + * auth.texi (Help for developers): Show example of using + `auth-source-search' with prompts and :save-function. + 2011-03-07 Chong Yidong <[email protected]> * Version 23.3 released. -2011-02-23 Glenn Morris <[email protected]> +2011-03-07 Antoine Levitt <[email protected]> - * dbus.texi (Type Conversion): Grammar fix. + * message.texi (Message Buffers): Update default value of + message-generate-new-buffers. - * dired-x.texi (Features, Local Variables): Fix typos. - (Features): Minor rephrasing. +2011-03-06 Jay Belanger <[email protected]> -2011-02-19 Glenn Morris <[email protected]> + * calc.texi (Logarithmic Units): Rename calc-logunits-dblevel + and calc-logunits-nplevel to calc-dblevel and calc-nplevel, + respectively. + (Musical Notes): New section. + (Customizing Calc): Mention the customizable variable + calc-note-threshold. - * edt.texi, erc.texi, gnus.texi, idlwave.texi, mh-e.texi: - Standardize some Emacs/XEmacs terminology. +2011-03-03 Glenn Morris <[email protected]> + + * url.texi (Dealing with HTTP documents): Remove reference to + function url-decode-text-part; never seems to have existed. (Bug#6038) + (Configuration): Update url-configuration-directory description. + +2011-03-02 Glenn Morris <[email protected]> + + * dired-x.texi (Multiple Dired Directories): Remove mentions + of dired-default-directory-alist and dired-default-directory. + Move dired-smart-shell-command here... + (Miscellaneous Commands): ... from here. + +2011-03-02 Paul Eggert <[email protected]> + + * texinfo.tex: Update to version 2011-02-24.09. + +2011-03-02 Glenn Morris <[email protected]> + + * dired-x.texi (Omitting Variables): Refer to add-dir-local-variable + instead of the obsoleted dired-omit-here-always. -2011-02-19 Michael Albinus <[email protected]> +2011-02-28 Michael Albinus <[email protected]> + + * tramp.texi (Frequently Asked Questions): Add Emacs 24 to + supported systems. + +2011-02-28 Glenn Morris <[email protected]> + + * dbus.texi (Type Conversion): Grammar fix. + +2011-02-23 Michael Albinus <[email protected]> * tramp.texi: Use consistently "Emacs" (instead of "GNU Emacs") and "Debian GNU/Linux". * trampver.texi [xemacs]: Set emacsothername to "Emacs". -2011-02-18 Eli Zaretskii <[email protected]> +2011-02-23 Glenn Morris <[email protected]> + + * dired-x.texi (Features): Minor rephrasing. + (Local Variables): Fix typos. + + * edt.texi, erc.texi, gnus.texi, idlwave.texi, mh-e.texi: + Standardize some Emacs/XEmacs terminology. + + * dired-x.texi (Features): Don't advertise obsolete local variables. + Simplify layout. + (Omitting Variables): Update local variables example. + (Local Variables): Say this is obsolete. Fix description of + dired-enable-local-variables possible values. + +2011-02-22 Teodor Zlatanov <[email protected]> + + * auth.texi (Help for users): Mention ~/.netrc is also searched by + default now. + +2011-02-21 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (Article Date): Clarify gnus-article-update-date-headers. + +2011-02-20 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (Window Layout): Document layout names. + +2011-02-19 Eli Zaretskii <[email protected]> * ada-mode.texi: Sync @dircategory with ../../info/dir. * auth.texi: Sync @dircategory with ../../info/dir. @@ -75,7 +234,28 @@ * widget.texi: Sync @dircategory with ../../info/dir. * woman.texi: Sync @dircategory with ../../info/dir. -2011-02-14 Glenn Morris <[email protected]> +2011-02-19 Glenn Morris <[email protected]> + + * dired-x.texi (Technical Details): No longer redefines dired-add-entry, + dired-initial-position, dired-clean-up-after-deletion, + dired-read-shell-command, or dired-find-buffer-nocreate. + +2011-02-18 Glenn Morris <[email protected]> + + * dired-x.texi (Optional Installation File At Point): Simplify. + +2011-02-17 Teodor Zlatanov <[email protected]> + + * auth.texi (Help for users): Use :port instead of :protocol for all + auth-source docs. + (GnuPG and EasyPG Assistant Configuration): Mention the default now is + to have two files in `auth-sources'. + +2011-02-16 Glenn Morris <[email protected]> + + * dired-x.texi: Use emacsver.texi to get Emacs version. + * Makefile.in ($(infodir)/dired-x, dired-x.dvi, dired-x.pdf): + Depend on emacsver.texi. * dired-x.texi: Drop meaningless version number. (Introduction): Remove old info. @@ -83,68 +263,896 @@ Remove incorrect info about loaddefs.el. (Bugs): Just refer to M-x report-emacs-bug. + * dired-x.texi (Multiple Dired Directories): Update for rename of + default-directory-alist. + (Miscellaneous Commands): No longer mention very old VM version 4. + +2011-02-15 Paul Eggert <[email protected]> + + Merge from gnulib. + * texinfo.tex: Update to version 2011-02-14.11. + +2011-02-14 Teodor Zlatanov <[email protected]> + + * auth.texi (Help for users): + Login collection is "Login" and not "login". + +2011-02-13 Michael Albinus <[email protected]> + + * tramp.texi (History): Remove IMAP support. + (External methods, Frequently Asked Questions): Remove `imap' and + `imaps' methods. + (Password handling): Remove IMAP entries for ~/.authinfo.gpg. + + * trampver.texi: Remove default value of `emacsimap'. + +2011-02-13 Glenn Morris <[email protected]> + + * ada-mode.texi, dired-x.texi, ebrowse.texi, ediff.texi, eudc.texi: + * idlwave.texi, reftex.texi, sc.texi, speedbar.texi: Add @top. + 2011-02-12 Glenn Morris <[email protected]> * sc.texi (Getting Connected): Remove old index entries. -2011-02-12 Ulrich Mueller <[email protected]> +2011-02-12 Ulrich Mueller <[email protected]> * url.texi: Remove duplicate @dircategory (Bug#7942). -2011-02-03 Michael Albinus <[email protected]> +2011-02-11 Teodor Zlatanov <[email protected]> + + * auth.texi (Overview, Help for users, Help for developers): + Update docs. + (Help for users): Talk about spaces. + +2011-02-09 Paul Eggert <[email protected]> + + * texinfo.tex: Update to version 2011-02-07.16. + +2011-02-07 Michael Albinus <[email protected]> + + * dbus.texi (Bus names): Adapt descriptions for + dbus-list-activatable-names and dbus-list-known-names. + +2011-02-07 Jay Belanger <[email protected]> + + * calc.texi (Logarithmic Units): New section. + +2011-02-05 Teodor Zlatanov <[email protected]> + + * gnus-overrides.texi: Renamed from overrides.texi and all the relevant + manuals use it now. + + * Makefile.in (nowebhack): Fixed to use -D flag instead of overrides. + +2011-02-05 Katsumi Yamaoka <[email protected]> + + * overrides.texi: Remove. + + * sieve.texi, sasl.texi, pgg.texi, message.texi, gnus.texi: + * emacs-mime.texi, auth.texi, Makefile.in: Revert last changes. + +2011-02-05 Michael Albinus <[email protected]> * tramp.texi (Frequently Asked Questions): Mention problems with WinSSHD. -2011-01-03 Eduard Wiebe <[email protected]> + * trampver.texi: Update release number. + +2011-02-05 Era Eriksson <[email protected]> (tiny change) + + * tramp.texi: + Replace "delimet" with "delimit" globally. + Replace "explicite" with "explicit" globally. + Replace "instead of" with "instead" where there was nothing after "of". + Audit use of comma before interrogative pronoun, "that", or "which". + Minor word order, spelling, wording changes. + +2011-02-04 Teodor Zlatanov <[email protected]> + + * overrides.texi: New file to set or clear WEBHACKDEVEL. + + * sieve.texi: Use WEBHACKDEVEL. + + * sasl.texi: Use WEBHACKDEVEL. + + * pgg.texi: Use WEBHACKDEVEL. + + * message.texi: Use WEBHACKDEVEL. + + * gnus.texi: Use WEBHACKDEVEL. + + * emacs-mime.texi: Use WEBHACKDEVEL. + + * auth.texi: Use WEBHACKDEVEL. + + * Makefile.in (webhack, nowebhack): Hacks to produce for-the-web + manuals. + +2011-02-04 Lars Ingebrigtsen <[email protected]> + + * gnus.texi: Add DEVEL header (suggested by Andreas Schwab). + +2011-02-03 Paul Eggert <[email protected]> + + * texinfo.tex: Update to version 2011-02-01.10 from gnulib, + which in turn is copied from ftp://tug.org/tex/. + +2011-02-03 Glenn Morris <[email protected]> + + * faq.texi (Contacting the FSF): Mainly just refer to the web-site. + (Binding combinations of modifiers and function keys): + Let's assume people reading this are not using Emacs 18. + +2011-02-03 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (Article Date): Remove mention of gnus-stop-date-timer, + since it's run automatically. + +2011-02-01 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (Customizing Articles): Fix typo. + +2011-01-31 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (Customizing Articles): Document the new way of customizing + the date headers(s). + +2011-01-30 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (Client-Side IMAP Splitting): Add a complete nnimap fancy + splitting example. + +2011-01-29 Eli Zaretskii <[email protected]> + + * makefile.w32-in (MAKEINFO): Remove options, leave only program name. + (MAKEINFO_OPTS): New variable. + (ENVADD, $(infodir)/emacs): Use $(MAKEINFO_OPTS). + ($(infodir)/info, $(infodir)/ccmode, $(infodir)/ada-mode) + ($(infodir)/pcl-cvs, $(infodir)/eshell, $(infodir)/cl) + ($(infodir)/dbus, $(infodir)/dired-x, $(infodir)/ediff) + ($(infodir)/flymake, $(infodir)/forms, $(infodir)/gnus) + ($(infodir)/message, $(infodir)/emacs-mime, $(infodir)/sieve) + ($(infodir)/pgg, $(infodir)/mh-e, $(infodir)/reftex) + ($(infodir)/remember, $(infodir)/sasl, $(infodir)/sc) + ($(infodir)/vip, $(infodir)/viper, $(infodir)/widget) + ($(infodir)/efaq, $(infodir)/autotype, $(infodir)/calc) + ($(infodir)/idlwave, $(infodir)/eudc, $(infodir)/ebrowse) + ($(infodir)/woman, $(infodir)/speedbar, $(infodir)/tramp) + ($(infodir)/ses, $(infodir)/smtpmail, $(infodir)/org) + ($(infodir)/url, $(infodir)/newsticker, $(infodir)/nxml-mode) + ($(infodir)/rcirc, $(infodir)/erc, $(infodir)/ert) + ($(infodir)/epa, $(infodir)/mairix-el, $(infodir)/auth) + ($(infodir)/eieio, $(infodir)/ede, $(infodir)/semantic) + ($(infodir)/edt): Use $(MAKEINFO_OPTS). + +2011-01-26 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (Article Date): Document gnus-article-update-lapsed-header. + +2011-01-24 Teodor Zlatanov <[email protected]> + + * message.texi (IDNA): Explain what it is. + +2011-01-24 Lars Ingebrigtsen <[email protected]> + + * gnus.texi (The Empty Backend): Document nnnil (bug #7653). + +2011-01-23 Werner Lemberg <[email protected]> + + * Makefile.in (MAKEINFO): Now controlled by `configure'. + (MAKEINFO_OPTS): New variable. Use it where appropriate. + (ENVADD): Updated. + +2011-01-18 Glenn Morris <[email protected]> + + * ert.texi: Relicense under GFDL 1.3+, and standardize license notice. + +2011-01-14 Eduard Wiebe <[email protected]> * nxml-mode.texi (Introduction): Fix file name typos. -2010-12-02 Glenn Morris <[email protected]> +2011-01-13 Christian Ohler <[email protected]> + + * ert.texi: New file. + + * Makefile.in: + * makefile.w32-in: Add ert.texi. + +2011-01-10 Jan Moringen <[email protected]> + + * dbus.texi (Receiving Method Calls): New function + dbus-register-service. Rearrange node. + +2011-01-07 Paul Eggert <[email protected]> + + * texinfo.tex: Update to version 2010-12-23.17 from gnulib, + which in turn is copied from ftp://tug.org/tex/. + +2011-01-04 Jan Moringen <[email protected]> + + * dbus.texi (Receiving Method Calls): Describe new optional + parameter dont-register-service of dbus-register-{method,property}. + +2010-12-17 Daiki Ueno <[email protected]> + + * epa.texi (Encrypting/decrypting *.gpg files): Mention + epa-file-select-keys. + +2010-12-16 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Archived Messages): Remove outdated text. + +2010-12-16 Teodor Zlatanov <[email protected]> + + * gnus.texi (Foreign Groups): Added clarification of foreign groups. + +2010-12-15 Andrew Cohen <[email protected]> + + * gnus.texi (The hyrex Engine): Say that this engine is obsolete. + +2010-12-14 Andrew Cohen <[email protected]> + + * gnus.texi (The swish++ Engine): Add customizable parameters + descriptions. + (The swish-e Engine): Ditto. + +2010-12-14 Michael Albinus <[email protected]> + + * tramp.texi (Inline methods): Add "ksu" method. + (Remote processes): Add example with remote `default-directory'. + +2010-12-14 Glenn Morris <[email protected]> + + * faq.texi (Expanding aliases when sending mail): + Now build-mail-aliases is interactive. + +2010-12-13 Andrew Cohen <[email protected]> + + * gnus.texi: First pass at adding (rough) nnir documentation. + +2010-12-13 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Filtering New Groups): + Mention gnus-auto-subscribed-categories. + (The First Time): Remove, since default-subscribed-newsgroups has been + removed. + +2010-12-13 Glenn Morris <[email protected]> * cl.texi (For Clauses): Small fixes for frames and windows. -2010-11-23 Glenn Morris <[email protected]> +2010-12-11 Carsten Dominik <[email protected]> + + * org.texi (Using capture): Document using prefix arguments for + finalizing capture. + (Agenda commands): Document prefix argument for the bulk scatter + command. + (Beamer class export): Document that also overlay arguments can be + passed to the column environment. + (Template elements): Document the new entry type. + +2010-12-11 Puneeth Chaganti <[email protected]> + + * org.texi (Include files): Document :minlevel. + +2010-12-11 Julien Danjou <[email protected]> + + * org.texi (Categories): Document category icons. + +2010-12-11 Eric Schulte <[email protected]> + + * org.texi (noweb): Fix typo. + +2010-12-06 Tassilo Horn <[email protected]> + + * gnus.texi (Server Commands): Point to the rest of the server + commands. + +2010-12-04 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Paging the Article): Note the reverse meanings of `C-u C-u + g'. + +2010-12-02 Julien Danjou <[email protected]> + + * gnus.texi (Archived Messages): Remove gnus-outgoing-message-group. + +2010-11-28 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Customizing the IMAP Connection): Note the new defaults. + (Direct Functions): Note the STARTTLS upgrade. + +2010-11-27 Glenn Morris <[email protected]> James Clark <[email protected]> * nxml-mode.texi (Introduction): New section. -2010-11-10 Glenn Morris <[email protected]> +2010-11-21 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Server Commands): Document gnus-server-show-server. + +2010-11-20 Michael Albinus <[email protected]> + + Sync with Tramp 2.2.0. + + * trampver.texi: Update release number. + +2010-11-19 Jay Belanger <[email protected]> + + * calc.texi (TeX and LaTeX Language Modes, Predefined Units): + Mention that the TeX specific units won't use the `tex' prefix + in TeX mode. + +2010-11-18 Katsumi Yamaoka <[email protected]> + + * gnus.texi (Misc Article): Document gnus-inhibit-images. + +2010-11-17 Glenn Morris <[email protected]> * edt.texi: Remove information about Emacs 19. -2010-11-05 Michael Albinus <[email protected]> +2010-11-17 Michael Albinus <[email protected]> * trampver.texi: Update release number. -2010-11-03 Jay Belanger <[email protected]> +2010-11-12 Katsumi Yamaoka <[email protected]> + + * gnus.texi (Article Washing): Fix typo. + +2010-11-11 Noorul Islam <[email protected]> + + * org.texi: Fix typo. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Using capture): Explain that refiling is + sensitive to cursor position. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Images and tables): Add cross reference to link section. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi: Document the <c> cookie. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi: multi-line header arguments :PROPERTIES: :ID: + b77c8857-6c76-4ea9-8a61-ddc2648d96c4 :END:. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (CSS support): Document :HTML_CONTAINER_CLASS: property. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Project alist): Mention that this is a property list. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Setting up the staging area): Document that + file names remain visible when encrypting the MobileOrg files. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Setting up the staging area): Document which + versions are needed for encryption. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi (noweb): Update :noweb documentation to + reflect the new "tangle" argument. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi (Batch execution): Improve tangling script in + documentation. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Handling links): + (In-buffer settings): Document inlining images on startup. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Setting up the staging area): Document use of + crypt password. + +2010-11-11 David Maus <[email protected]> + + * org.texi (Template expansion): Add date related link type escapes. + +2010-11-11 David Maus <[email protected]> + + * org.texi (Template expansion): Add mew in table for link type + escapes. + +2010-11-11 David Maus <[email protected]> + + * org.texi (Template expansion): Fix typo in link type escapes. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi (Structure of code blocks): Another documentation tweak. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi (Structure of code blocks): Documentation tweak. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi (Structure of code blocks): + Update documentation to mention inline code block syntax. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi (comments): Improve wording. + +2010-11-11 Eric Schulte <[email protected]> + + * org.texi (comments): Document the new :comments header arguments. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Installation): Remove the special + installation instructions for XEmacs. + +2010-11-11 Jambunathan K <[email protected]> (tiny change) + + * org.texi (Easy Templates): New section. Documents quick + insertion of empty structural elements. + +2010-11-11 Noorul Islam <[email protected]> + + * org.texi: Fix doc. + +2010-11-11 Jambunathan K <[email protected]> (tiny change) + + * org.texi (The date/time prompt): Document specification + of time ranges. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Internal links): Document the changes in + internal links. + +2010-11-11 Carsten Dominik <[email protected]> + + * org.texi (Agenda commands): Document the limitation for + the filter preset - it can only be used for an entire agenda + view, not in an individual block in a block agenda. + +2010-11-11 Eric S Fraga <[email protected]> + + * org.texi (iCalendar export): Document alarm creation. + +2010-11-10 Michael Albinus <[email protected]> + + * dbus.texi (Type Conversion): Introduce `:unix-fd' type mapping. + +2010-11-09 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Article Washing): Document gnus-article-treat-non-ascii. + +2010-11-09 Jay Belanger <[email protected]> * calc.texi: Use emacsver.texi to determine Emacs version. -2010-10-30 Glenn Morris <[email protected]> +2010-11-04 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Customizing the IMAP Connection): Remove nnir mention, + since that works by default. + +2010-11-03 Kan-Ru Chen <[email protected]> (tiny change) + + * gnus.texi (Customizing the IMAP Connection): Document + `nnimap-expunge' and remove `nnimap-expunge-inbox' from example. + +2010-11-04 Michael Albinus <[email protected]> + + * tramp.texi (Remote shell setup): New item "Interactive shell + prompt". Reported by Christian Millour <[email protected]>. + (Remote shell setup, Remote processes): Use @code{} for + environment variables. + +2010-11-03 Glenn Morris <[email protected]> + + * ediff.texi (Quick Help Commands, Miscellaneous): + * gnus.texi (Agent Variables, Configuring nnmairix): Spelling fix. + +2010-10-31 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Paging the Article): Document C-u g/C-u C-u g. + +2010-10-31 Glenn Morris <[email protected]> * mh-e.texi (Preface, From Bill Wohler): Change 23 to past tense. -2010-10-29 Glenn Morris <[email protected]> +2010-10-31 Glenn Morris <[email protected]> * cc-mode.texi: Remove reference to defunct viewcvs URL. -2010-10-22 Juanma Barranquero <[email protected]> +2010-10-29 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Client-Side IMAP Splitting): Mention + nnimap-unsplittable-articles. + +2010-10-29 Julien Danjou <[email protected]> + + * gnus.texi (Finding the News): Remove references to obsoletes + variables `gnus-nntp-server' and `gnus-secondary-servers'. + +2010-10-29 Eli Zaretskii <[email protected]> + + * makefile.w32-in (MAKEINFO): Add -I$(emacsdir). + (ENVADD): Remove extra -I$(emacsdir), included in $(MAKEINFO). + ($(infodir)/efaq): Remove -I$(emacsdir), included in $(MAKEINFO). + ($(infodir)/calc, calc.dvi): Depend on $(emacsdir)/emacsver.texi. + +2010-10-28 Glenn Morris <[email protected]> + + * Makefile.in (MAKEINFO, ENVADD): Add $emacsdir to include path. + (($(infodir)/calc, calc.dvi, calc.pdf): Depend on emacsver.texi. + ($(infodir)/efaq): Remove -I option now in $MAKEINFO. + +2010-10-25 Daiki Ueno <[email protected]> + + * epa.texi (Mail-mode integration): Add alternative key bindings + for epa-mail commands; escape comma. + Don't use the word "PGP", since it is a non-free program. + +2010-10-24 Jay Belanger <[email protected]> + + * calc.texi: Use emacsver.texi to determine Emacs version. + +2010-10-24 Juanma Barranquero <[email protected]> * gnus.texi (Group Parameters, Buttons): Fix typos. +2010-10-22 Tassilo Horn <[email protected]> + + * gnus.texi (Subscription Commands): Mention that you can also + subscribe to new groups via the Server buffer, which is probably more + convenient when subscribing to many groups. + +2010-10-21 Julien Danjou <[email protected]> + + * message.texi (Message Headers): Allow message-default-headers to be a + function. + +2010-10-21 Lars Magne Ingebrigtsen <[email protected]> + + * gnus-news.texi: Mention new archive defaults. + +2010-10-21 Katsumi Yamaoka <[email protected]> + + * gnus.texi (RSS): Remove nnrss-wash-html-in-text-plain-parts. + +2010-10-20 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (HTML): Document the function value of + gnus-blocked-images. + (Article Washing): shr and gnus-w3m, not the direct function names. + +2010-10-20 Julien Danjou <[email protected]> + + * emacs-mime.texi (Flowed text): Add a note about mml-enable-flowed + variable. + +2010-10-19 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Customizing the IMAP Connection): The port strings are + strings. + (Document Groups): Mention git. + +2010-10-18 Lars Magne Ingebrigtsen <[email protected]> + + * gnus-coding.texi (Gnus Maintainance Guide): Update to mention Emacs + bzr/Gnus git sync. + +2010-10-15 Eli Zaretskii <[email protected]> + + * auth.texi (GnuPG and EasyPG Assistant Configuration): Fix last + change. + +2010-10-13 Lars Magne Ingebrigtsen <[email protected]> + + * auth.texi (GnuPG and EasyPG Assistant Configuration): Fix up the + @item syntax for in-Emacs makeinfo. + +2010-10-13 Teodor Zlatanov <[email protected]> + + * auth.texi (GnuPG and EasyPG Assistant Configuration): Fix syntax and + trim sentence. + +2010-10-12 Daiki Ueno <[email protected]> + + * epa.texi (Caching Passphrases): + * auth.texi (GnuPG and EasyPG Assistant Configuration): Clarify + some configurations require to set up gpg-agent. + +2010-10-11 Glenn Morris <[email protected]> + + * Makefile.in (.texi.dvi): Remove unnecessary suffix rule. + +2010-10-09 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Spam Package Introduction): Mention `$'. + +2010-10-09 Eli Zaretskii <[email protected]> + + * makefile.w32-in (emacsdir): New variable. + ($(infodir)/efaq, faq.dvi): Depend on emacsver.texi. + (ENVADD, $(infodir)/efaq): Add -I$(emacsdir). + +2010-10-09 Glenn Morris <[email protected]> + + * Makefile.in (mostlyclean): Delete *.toc. + + * Makefile.in: Use $< in rules. + + * Makefile.in (maintainer-clean): Remove harmless, long-standing error. + + * Makefile.in ($(infodir)): Delete rule. + (mkinfodir): New. Use it in all the info rules, rather than depending + on infodir. + +2010-10-09 Glenn Morris <[email protected]> + + * gnus.texi (Article Washing): Fix previous change. + + * Makefile.in (emacsdir): New variable. + ($(infodir)/efaq): Pass -I $(emacsdir) to makeinfo. + Depend on emacsver.texi. + + * faq.texi (VER): Replace with EMACSVER from emacsver.texi. + + * Makefile.in (.PHONY): Declare info, dvi, pdf and the clean rules. + +2010-10-08 Julien Danjou <[email protected]> + + * gnus.texi: Add mm-shr. + +2010-10-08 Ludovic Courtès <[email protected]> + + * gnus.texi (Finding the Parent, The Gnus Registry) + (Registry Article Refer Method): Update docs for nnregistry.el. + +2010-10-08 Daiki Ueno <[email protected]> + + * auth.texi (Help for users) + (GnuPG and EasyPG Assistant Configuration): Update docs. + 2010-10-08 Glenn Morris <[email protected]> * cl.texi (Organization, Installation, Old CL Compatibility): Deprecate cl-compat for new code. - -2010-10-07 Glenn Morris <[email protected]> + (Usage, Installation): Remove outdated information. * eudc.texi (CCSO PH/QI, LDAP Requirements): Remove old information. +2010-10-07 Katsumi Yamaoka <[email protected]> + + * gnus.texi (Gravatars): Document gnus-gravatar-too-ugly. + +2010-10-06 Julien Danjou <[email protected]> + + * sieve.texi (Manage Sieve API): Document sieve-manage-authenticate. + + * message.texi (PGP Compatibility): Remove reference to gpg-2comp, + broken link. + + * gnus-faq.texi (FAQ 8-3): Remove references to my.gnus.org. + + * gnus.texi (Comparing Mail Back Ends): Remove broken link and allusion + to ReiserFS. + + * gnus-faq.texi (FAQ 5-5): Fix Flyspell URL. + (FAQ 7-1): Fix getmail URL. + +2010-10-06 Daiki Ueno <[email protected]> + + * epa.texi (Caching Passphrases): New section. + 2010-10-06 Glenn Morris <[email protected]> - * cl.texi (Usage, Installation): Remove outdated information. + * Makefile.in (SHELL): Set it. + (info): Move the mkdir dependency to the individual info files. + (mostlyclean): Tidy up. + (clean): Only delete the specific dvi and pdf files. + (maintainer-clean): Be more restrictive in what we delete. + ($(infodir)): Add parallel build workaround. + +2010-10-04 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Misc Article): Document gnus-widen-article-window. + +2010-10-03 Julien Danjou <[email protected]> + + * emacs-mime.texi (Display Customization): Update + mm-inline-large-images documentation and add documentation for + mm-inline-large-images-proportion. + +2010-10-03 Michael Albinus <[email protected]> + + * tramp.texi (Frequently Asked Questions): Mention + remote-file-name-inhibit-cache. + +2010-10-02 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Splitting Mail): Fix @xref syntax. + (Splitting Mail): Really fix the @ref syntax. + +2010-10-01 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Splitting Mail): Mention the new fancy splitting + function. + (Article Hiding): Add google banner example. Suggested by Benjamin + Xu. + +2010-09-30 Teodor Zlatanov <[email protected]> + + * gnus.texi (Spam Package Configuration Examples, SpamOracle): Remove + nnimap-split-rule from examples. + +2010-09-30 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Mail Source Specifiers): Remove webmail.el mentions. + (NNTP): Document nntp-server-list-active-group. Suggested by Barry + Fishman. + (Client-Side IMAP Splitting): Add nnimap-split-fancy. + +2010-09-30 Julien Danjou <[email protected]> + + * gnus.texi (Gravatars): Fix documentation about + gnu-gravatar-properties. + +2010-09-29 Daiki Ueno <[email protected]> + + * epa.texi (Bug Reports): New section. + +2010-09-29 Glenn Morris <[email protected]> + + * Makefile.in (top_srcdir): Remove unused variable. + +2010-09-29 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Using IMAP): Remove the @acronyms from the headings. + (Client-Side IMAP Splitting): Document 'default. + +2010-09-27 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Customizing the IMAP Connection): Document + nnimap-fetch-partial-articles. + +2010-09-26 Lars Magne Ingebrigtsen <[email protected]> + + * gnus-news.texi: Mention nnimap-inbox. + + * gnus.texi (Picons): Document gnus-picon-inhibit-top-level-domains. + +2010-09-26 Julien Danjou <[email protected]> + + * gnus.texi (Oort Gnus): Remove mention of ssl.el. + +2010-09-26 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Security): Remove gpg.el mention. + +2010-09-26 Andreas Seltenreich <[email protected]> + + * gnus.texi (Browse Foreign Server): New variable + gnus-browse-subscribe-newsgroup-method. + + * gnus-news.texi: Mention it. + +2010-09-26 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (NoCeM): Removed. + (Startup Variables): No jingle. + +2010-09-25 Ulrich Mueller <[email protected]> + + * woman.texi (Interface Options): xz compression is now supported. + +2010-09-25 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Article Commands): Document gnus-fetch-partial-articles. + (Unavailable Servers): Document gnus-server-copy-server. + (Using IMAP): Document the new nnimap. + +2010-09-25 Julien Danjou <[email protected]> + + * gnus.texi (Customizing Articles): Remove gnus-treat-translate. + +2010-09-24 Glenn Morris <[email protected]> + + * url.texi (Disk Caching): Tweak previous change. + +2010-09-24 Julien Danjou <[email protected]> + + * url.texi (Disk Caching): Mention url-cache-expire-time, + url-cache-expired, and url-fetch-from-cache. + +2010-09-24 Julien Danjou <[email protected]> + + * gnus.texi: Add Gravatars. + +2010-09-23 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Startup Variables): Mention gnus-use-backend-marks. + +2010-09-21 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Expunging mailboxes): Update name of the expunging + command. + +2010-09-20 Katsumi Yamaoka <[email protected]> + + * emacs-mime.texi (rfc2047): Update description for + rfc2047-encode-parameter. + +2010-09-13 Michael Albinus <[email protected]> + + * tramp.texi (Inline methods): Remove "ssh1_old", "ssh2_old" and + "fish" methods. + (External methods): Remove "scp1_old" and "scp2_old" methods. + +2010-09-09 Michael Albinus <[email protected]> + + * tramp.texi: Remove Japanese manual. Fix typo. + + * trampver.texi: Update release number. Remove japanesemanual. + +2010-09-09 Glenn Morris <[email protected]> + + * org.texi: Restore clobbered changes (copyright years, untabify). + +2010-09-04 Julien Danjou <[email protected]> (tiny change) + + * gnus.texi (Adaptive Scoring): Fix typo. + +2010-09-03 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Article Display): Document gnus-html-show-images. + +2010-09-02 Jan Djärv <[email protected]> + + * cl.texi (Basic Setf): Remove x-get-cut-buffer and x-get-cutbuffer. + +2010-09-01 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (HTML): Document gnus-max-image-proportion. + +2010-08-31 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (HTML): Document gnus-blocked-images. + + * message.texi (Wide Reply): Document message-prune-recipient-rules. + +2010-08-30 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Summary Mail Commands): Note that only the addresses from + the first message are used for wide replies. + (Changing Servers): Remove documentation on gnus-change-server and + friends, since it's been removed. + +2010-08-29 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Drafts): Mention B DEL. + +2010-08-29 Tim Landscheidt <[email protected]> (tiny change) + + * gnus.texi (Delayed Articles): Mention that the Date header is the + original one, even if you delay. + +2010-08-29 Lars Magne Ingebrigtsen <[email protected]> + + * gnus.texi (Asynchronous Fetching): Document + gnus-async-post-fetch-function. + (HTML): Made into its own section. 2010-08-26 Michael Albinus <[email protected]> @@ -165,14 +1173,97 @@ * trampver.texi: Update release number. -2010-08-01 Juanma Barranquero <[email protected]> +2010-08-23 Michael Albinus <[email protected]> + + * dbus.texi (Alternative Buses): New chapter. + +2010-08-12 Stefan Monnier <[email protected]> + + * cl.texi (Mapping over Sequences): Rename mapc => cl-mapc. + +2010-08-09 Jay Belanger <[email protected]> + + * calc.texi (Customizing Calc): Rearrange description of new + variables to match the presentation of other variables. + +2010-08-08 Juanma Barranquero <[email protected]> * org.texi (Footnotes, Tables in HTML export): Fix typos. -2010-07-23 Chong Yidong <[email protected]> +2010-08-08 Jay Belanger <[email protected]> + + * calc.texi (Making Selections, Selecting Subformulas) + (Customizing Calc): Mention how to use faces to emphasize selected + sub-formulas. + +2010-08-05 Michael Albinus <[email protected]> + + * tramp.texi (External packages): File attributes cache flushing + for asynchronous processes. + +2010-08-01 Alan Mackenzie <[email protected]> + + Enhance the manual for the latest Java Mode. + + * cc-mode.texi (Syntactic Symbols): New symbols annotation-top-cont and + annotation-var-cont. + (Java Symbols): Page renamed from Anonymous Class Symbol. Document the + two new symbols. + +2010-07-28 Michael Albinus <[email protected]> + + * tramp.texi (Traces and Profiles): Describe verbose level 9. + +2010-07-27 Chong Yidong <[email protected]> * nxml-mode.texi (Limitations): Remove obsolete discussion (Bug#6708). +2010-07-19 Juanma Barranquero <[email protected]> + + * org.texi: Fix typo in previous change (2010-07-19T09:47:[email protected]). + +2010-07-19 Carsten Dominik <[email protected]> + + * org.texi: Add macros to get plain quotes in PDF output. + List additional contributors. + (Capture): New section, replaces the section about remember. + (Working With Source Code): New chapter, focused on documenting Org + Babel. + (Code evaluation security): New section. + (MobileOrg): Document DropBox support. + (TaskJuggler export): Document taskjuggler and Gantt chart support. + (Special symbols): Show how to display UTF8 characters for entities. + (Global TODO list): Clarify the use of the "M" key and the differences + to the "m" key. + (RSS Feeds): Mention Atom feeds as well. + (Setting tags): Remove paragraph about + `org-complete-tags-always-offer-all-agenda-tags'. + +2010-07-17 Michael Albinus <[email protected]> + + * tramp.texi (Inline methods): Remove remark about doubled "-t" + argument. + (Frequently Asked Questions): Recommend "sshx" and "scpx" for + echoing shells. + +2010-07-10 Michael Albinus <[email protected]> + + * tramp.texi (Inline methods): Remove "kludgy" phrase. + (Filename Syntax): Describe port numbers. + +2010-07-09 Michael Albinus <[email protected]> + + * dbus.texi (Top): Introduce Index. Emphasize "nil" whereever + forgotten. + (Type Conversion): Precise conversion of natural numbers. + (Errors and Events): Add "debugging" to concept index. Add variable + `dbus-debug'. + +2010-07-04 Michael Albinus <[email protected]> + + * dbus.texi (Receiving Method Calls): Add optional argument + EMITS-SIGNAL to `dbus-register-property'. + 2010-06-27 Alex Schroeder <[email protected]> * nxml-mode.texi (Commands for locating a schema): Fix typo. @@ -203,44 +1294,151 @@ * idlwave.texi (Load-Path Shadows): * org.texi (Handling links): Fix typos. -2010-05-07 Chong Yidong <[email protected]> +2010-06-07 Teodor Zlatanov <[email protected]> - * Version 23.2 released. + * gnus.texi (Interactive): Explain effect of gnus-expert-user better. + +2010-05-26 Michael Albinus <[email protected]> -2010-05-03 Štěpán Němec <[email protected]> (tiny change) + * eshell.texi (Built-ins): Describe, how to disable a built-in command + by an alias. (Bug#6226) + +2010-05-16 Jay Belanger <[email protected]> + + * calc.texi (Manipulating Vectors): Mention that vectors can + be used to determine bins for `calc-histogram'. + +2010-05-13 Jay Belanger <[email protected]> + + * calc.texi: Remove "\turnoffactive" commands throughout. + +2010-05-08 Štěpán Němec <[email protected]> (tiny change) * url.texi (HTTP language/coding, Customization): * message.texi (Header Commands, Responses): * cl.texi (Argument Lists): Fix typos. -2010-04-18 Chong Yidong <[email protected]> +2010-05-08 Chong Yidong <[email protected]> - * ede.texi (EDE Mode): Refer to init file rather than `.emacs'. Note - that Development menu is always available. + * ede.texi (EDE Mode): Refer to init file rather than `.emacs'. + Note that Development menu is always available. (Creating a project): Fix terminology. (Add/Remove files): Fix typo. -2010-04-17 Teodor Zlatanov <[email protected]> +2010-05-07 Chong Yidong <[email protected]> + + * Version 23.2 released. + +2010-05-01 Daniel E. Doherty <[email protected]> (tiny change) + + * calc.texi (Tutorial): Use "^{\prime}" to indicate primes. + +2010-05-01 Michael Albinus <[email protected]> + + * tramp.texi (Inline methods, Default Method): + Mention `tramp-inline-compress-start-size'. + +2010-04-18 Teodor Zlatanov <[email protected]> * gnus.texi (Gnus Versions, Oort Gnus): Mention the Git repo instead of the CVS repo. Put the Git repo in the news section. - * gnus-coding.texi (Gnus Maintainance Guide): Fixed title typo. + * gnus-coding.texi (Gnus Maintainance Guide): Fix title typo. Removed some mentions of CVS. Mention the new Git repo. -2010-04-15 Andreas Seltenreich <[email protected]> +2010-04-18 Andreas Seltenreich <[email protected]> * gnus.texi (Score File Format): Fix typo. Reported by Štěpán Němec. (Mail Group Commands): Add index entry. -2010-04-15 Glenn Morris <[email protected]> +2010-04-18 Glenn Morris <[email protected]> * info.texi (Search Index): Mention Emacs's Info-virtual-index. -2010-03-14 Michael Albinus <[email protected]> +2010-04-18 Jay Belanger <[email protected]> + + * calc.texi (Radix modes): Mention that the option prefix will + turn on twos-complement mode. + (Inverse and Hyperbolic Flags): Mention the Option flag. + +2010-04-15 Carsten Dominik <[email protected]> + + * org.texi (LaTeX and PDF export): Add a footnote about xetex. + (LaTeX/PDF export commands): Rename and Move section. + (Sectioning structure): Update. + (References): New use case for field coordinates. + (The export dispatcher): Rename from ASCII export. + (Setting up the staging area): Document the availability of + encryption for MobileOrg. + (Images and tables): Document how to reference labels. + (Index entries): New section. + (Generating an index): New section. + (Column width and alignment): Document that <N> now + means a fixed width, not a maximum width. + (Publishing options): Document the :email option. + (Beamer class export): Fix bug in the BEAMER example. + (Refiling notes): Document refile logging. + (In-buffer settings): Document refile logging keywords. + (Drawers): Document `C-c C-z' command. + (Agenda commands): Mention the alternative key `C-c C-z'. + (Special properties): Document the BLOCKED property. + (The spreadsheet): Mention the formula editor. + (References): Document field coordinates. + (Publishing action): Correct the documentation for the + publishing function. + (The date/time prompt): Document that we accept dates + like month/day/year. + (Cooperation): Document the changes in table.el support. + (Faces for TODO keywords, Faces for TODO keywords) + (Priorities): Document the easy colors. + (Visibility cycling): Document the new double prefix + arg for `org-reveal'. + (Cooperation): Remember.el is part of Emacs. + (Clean view): Mention that `wrap-prefix' is also set by + org-indent-mode. + (Agenda commands): Add information about prefix args to + scheduling and deadline commands. + (Search view): Point to the docstring of + `org-search-view' for more details. + (Agenda commands): Document that `>' prompts for a date. + (Setting tags): Document variable + org-complete-tags-always-offer-all-agenda-tags. + (Column attributes): Cross-reference special properties. + +2010-04-10 Michael Albinus <[email protected]> + + Synchronize with Tramp repository. + + * tramp.texi (Auto-save and Backup): Remove reference to Emacs 21. + (Frequently Asked Questions): Adapt supported (X)Emacs versions. Adapt + supported MS Windows versions. Remove obsolete URL. Use the $() + syntax, texi2dvi reports errors with the backquotes. + + * trampver.texi: Update release number. + +2010-04-01 Teodor Zlatanov <[email protected]> + + * gnus.texi (Finding the News): Add pointers to the Server buffer + because it's essential. + +2010-03-31 Katsumi Yamaoka <[email protected]> + + * gnus.texi (MIME Commands): Update description of + gnus-article-browse-html-article. + +2010-03-27 Teodor Zlatanov <[email protected]> + + * auth.texi (Secret Service API): Add TODO node. + (Help for users): Explain the new source options for `auth-sources'. + +2010-03-24 Michael Albinus <[email protected]> * trampver.texi: Update release number. +2010-03-10 Chong Yidong <[email protected]> + + * Branch for 23.2. + 2010-03-03 Chong Yidong <[email protected]> * faq.texi (Escape sequences in shell output): Note that ansi-color is @@ -280,7 +1478,7 @@ 2010-01-17 Michael Albinus <[email protected]> * tramp.texi (Frequently Asked Questions): Add GNU Emacs 23 and - SXEmacs 22 to the supported systems. New item for hung ssh sessions. + SXEmacs 22 to the supported systems. New item for hung ssh sessions. 2010-01-17 Glenn Morris <[email protected]> @@ -709,7 +1907,7 @@ (Agenda commands): Document new bulk commands. (Plain lists): Document new behavior of `org-cycle-include-plain-lists'. - Hyphenation only in TeX. + Hyphenation only in TeX. (Clocking work time): Document the key to update effort estimates. (Clocking work time): Document the clock time display. @@ -1776,7 +2974,7 @@ 2008-06-15 Reiner Steib <[email protected]> * gnus.texi (Mail Source Customization): Correct values of - `mail-source-delete-incoming'. Reported by Tassilo Horn. + `mail-source-delete-incoming'. Reported by Tassilo Horn. (Oort Gnus): Fix version comment for mml-dnd-protocol-alist. 2008-06-14 Reiner Steib <[email protected]> @@ -2415,10 +3613,6 @@ * gnus-news.texi, gnus-coding.texi, sasl.texi: New files. -2007-10-28 Emanuele Giaquinta <[email protected]> (tiny change) - - * gnus-faq.texi ([5.12]): Remove reference to discontinued service. - 2007-10-28 Reiner Steib <[email protected]> * gnus.texi (Sorting the Summary Buffer): Remove @@ -3954,19 +5148,6 @@ * org.texi (Progress logging): New section. -2006-05-29 Stefan Monnier <[email protected]> - - * viper.texi (Viper Specials): - * gnus.texi (Example Setup): - * faq.texi (Backspace invokes help): - * dired-x.texi (Optional Installation Dired Jump): - * calc.texi (Defining Simple Commands): Use ;; instead of ;;; to better - follow coding conventions. - -2006-05-18 Reiner Steib <[email protected]> - - * gnus.texi (Saving Articles): Clarify gnus-summary-save-article-mail. - 2006-06-06 Carsten Dominik <[email protected]> * org.texi (ASCII export): Document indentation adaptation. @@ -4014,6 +5195,15 @@ * org.texi: Small typo fixes. +2006-05-29 Stefan Monnier <[email protected]> + + * viper.texi (Viper Specials): + * gnus.texi (Example Setup): + * faq.texi (Backspace invokes help): + * dired-x.texi (Optional Installation Dired Jump): + * calc.texi (Defining Simple Commands): Use ;; instead of ;;; to better + follow coding conventions. + 2006-05-29 Michael Albinus <[email protected]> * tramp.texi (Frequently Asked Questions): Disable zsh zle. @@ -4570,10 +5760,6 @@ * gnus.texi (Article Washing): Additions. -2006-01-08 Alex Schroeder <[email protected]> - - * pgg.texi (Caching passphrase): Rewording. - 2006-01-13 Carsten Dominik <[email protected]> * org.texi (Agenda commands): Document tags command. @@ -4811,7 +5997,7 @@ * org.texi (FAQ): Document `org-table-tab-jumps-over-hlines'. (Agenda): Document commands `org-cycle-agenda-files' and - `org-agenda-file-to-front' + `org-agenda-file-to-front'. (Built-in table editor): Document `org-table-sort-lines'. (HTML formatting): Export of hand-formatted lists. @@ -6400,7 +7586,7 @@ 2000-12-14 Dave Love <[email protected]> - * Makefile.in (mostlyclean): Remove gnustmp.* + * Makefile.in (mostlyclean): Remove gnustmp.*. (gnus.dvi): Change rule to remove @latex stuff. 2000-10-19 Eric M. Ludlam <[email protected]> @@ -6811,12 +7997,9 @@ ;; Local Variables: ;; coding: utf-8 -;; fill-column: 79 -;; add-log-time-zone-rule: t ;; End: - Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, - 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. + Copyright (C) 1993-1999, 2001-2011 Free Software Foundation, Inc. This file is part of GNU Emacs. @@ -6832,5 +8015,3 @@ You should have received a copy of the GNU General Public License along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. - -;; arch-tag: 08b2903e-900c-4c72-a4a9-e76416a80803 diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 9e93be4e13..28a949f81e 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -1,7 +1,6 @@ #### Makefile for documentation other than the Emacs manual. -# Copyright (C) 1994, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -# 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +# Copyright (C) 1994, 1996-2011 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -18,23 +17,31 @@ # You should have received a copy of the GNU General Public License # along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. +SHELL = /bin/sh # Where to find the source code. $(srcdir) will be the man-aux # 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. +# Note the other doc Makefiles do not use VPATH anymore, instead +# they set infodir to an absolute path. Not doing that here in +# case INFO_TARGETS gets too long for some feeble shells. +# (cf src/Makefile.in's passing of $lisp to make-docfile) VPATH=@srcdir@ ## Where the output files go. ## Note that the setfilename command in the .texi files assumes this. infodir=../../info +## Directory with emacsver.texi. +## Currently only used by efaq and calc. +emacsdir = $(srcdir)/../emacs # The makeinfo program is part of the Texinfo distribution. # Use --force so that it generates output even if there are errors. -MAKEINFO = makeinfo --force +MAKEINFO = @MAKEINFO@ +MAKEINFO_OPTS = --force -I$(emacsdir) # Also add new entries to INFO_FILES in the top-level Makefile.in. INFO_TARGETS = \ @@ -54,6 +61,7 @@ INFO_TARGETS = \ $(infodir)/emacs-mime \ $(infodir)/epa \ $(infodir)/erc \ + $(infodir)/ert \ $(infodir)/eshell \ $(infodir)/eudc \ $(infodir)/efaq \ @@ -104,6 +112,7 @@ DVI_TARGETS = \ emacs-mime.dvi \ epa.dvi \ erc.dvi \ + ert.dvi \ eshell.dvi \ eudc.dvi \ faq.dvi \ @@ -154,6 +163,7 @@ PDF_TARGETS = \ emacs-mime.pdf \ epa.pdf \ erc.pdf \ + ert.pdf \ eshell.pdf \ eudc.pdf \ faq.pdf \ @@ -187,21 +197,23 @@ PDF_TARGETS = \ widget.pdf \ woman.pdf +HTML_TARGETS = emacs-faq.html + TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - $(TEXI2DVI) $< +ENVADD = TEXINPUTS="$(srcdir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" -ENVADD = TEXINPUTS="$(srcdir):$(TEXINPUTS)" MAKEINFO="$(MAKEINFO) -I$(srcdir)" +mkinfodir = @cd ${srcdir}; test -d ${infodir} || mkdir ${infodir} || test -d ${infodir} +.PHONY: info dvi pdf -info: $(infodir) $(INFO_TARGETS) +info: $(INFO_TARGETS) -$(infodir): - mkdir $@ +# please modify this for all the web manual targets +webhack: clean + $(MAKE) pdf MAKEINFO_OPTS="-DWEBHACKDEVEL $(MAKEINFO_OPTS)" dvi: $(DVI_TARGETS) @@ -215,183 +227,222 @@ pdf: $(PDF_TARGETS) ## "short" target names for convenience, to just rebuild one manual. ada-mode : $(infodir)/ada-mode $(infodir)/ada-mode: ada-mode.texi - cd $(srcdir); $(MAKEINFO) ada-mode.texi -ada-mode.dvi: ada-mode.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/ada-mode.texi -ada-mode.pdf: ada-mode.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/ada-mode.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +ada-mode.dvi: ${srcdir}/ada-mode.texi + $(ENVADD) $(TEXI2DVI) $< +ada-mode.pdf: ${srcdir}/ada-mode.texi + $(ENVADD) $(TEXI2PDF) $< auth : $(infodir)/auth $(infodir)/auth: auth.texi - cd $(srcdir); $(MAKEINFO) auth.texi -auth.dvi: auth.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/auth.texi -auth.pdf: auth.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/auth.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +auth.dvi: ${srcdir}/auth.texi + $(ENVADD) $(TEXI2DVI) $< +auth.pdf: ${srcdir}/auth.texi + $(ENVADD) $(TEXI2PDF) $< autotype : $(infodir)/autotype $(infodir)/autotype: autotype.texi - cd $(srcdir); $(MAKEINFO) autotype.texi -autotype.dvi: autotype.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/autotype.texi -autotype.pdf: autotype.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/autotype.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +autotype.dvi: ${srcdir}/autotype.texi + $(ENVADD) $(TEXI2DVI) $< +autotype.pdf: ${srcdir}/autotype.texi + $(ENVADD) $(TEXI2PDF) $< calc : $(infodir)/calc -$(infodir)/calc: calc.texi - cd $(srcdir); $(MAKEINFO) calc.texi -calc.dvi: calc.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/calc.texi -calc.pdf: calc.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/calc.texi +$(infodir)/calc: calc.texi $(emacsdir)/emacsver.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +calc.dvi: ${srcdir}/calc.texi $(emacsdir)/emacsver.texi + $(ENVADD) $(TEXI2DVI) $< +calc.pdf: ${srcdir}/calc.texi $(emacsdir)/emacsver.texi + $(ENVADD) $(TEXI2PDF) $< ccmode : $(infodir)/ccmode $(infodir)/ccmode: cc-mode.texi - cd $(srcdir); $(MAKEINFO) cc-mode.texi -cc-mode.dvi: cc-mode.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/cc-mode.texi -cc-mode.pdf: cc-mode.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/cc-mode.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +cc-mode.dvi: ${srcdir}/cc-mode.texi + $(ENVADD) $(TEXI2DVI) $< +cc-mode.pdf: ${srcdir}/cc-mode.texi + $(ENVADD) $(TEXI2PDF) $< cl : $(infodir)/cl $(infodir)/cl: cl.texi - cd $(srcdir); $(MAKEINFO) cl.texi -cl.dvi: cl.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/cl.texi -cl.pdf: cl.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/cl.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +cl.dvi: ${srcdir}/cl.texi + $(ENVADD) $(TEXI2DVI) $< +cl.pdf: ${srcdir}/cl.texi + $(ENVADD) $(TEXI2PDF) $< dbus : $(infodir)/dbus $(infodir)/dbus: dbus.texi - cd $(srcdir); $(MAKEINFO) dbus.texi -dbus.dvi: dbus.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/dbus.texi -dbus.pdf: dbus.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/dbus.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +dbus.dvi: ${srcdir}/dbus.texi + $(ENVADD) $(TEXI2DVI) $< +dbus.pdf: ${srcdir}/dbus.texi + $(ENVADD) $(TEXI2PDF) $< dired-x : $(infodir)/dired-x -$(infodir)/dired-x: dired-x.texi - cd $(srcdir); $(MAKEINFO) dired-x.texi -dired-x.dvi: dired-x.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/dired-x.texi -dired-x.pdf: dired-x.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/dired-x.texi +$(infodir)/dired-x: dired-x.texi $(emacsdir)/emacsver.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +dired-x.dvi: ${srcdir}/dired-x.texi $(emacsdir)/emacsver.texi + $(ENVADD) $(TEXI2DVI) $< +dired-x.pdf: ${srcdir}/dired-x.texi $(emacsdir)/emacsver.texi + $(ENVADD) $(TEXI2PDF) $< ebrowse : $(infodir)/ebrowse $(infodir)/ebrowse: ebrowse.texi - cd $(srcdir); $(MAKEINFO) ebrowse.texi -ebrowse.dvi: ebrowse.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/ebrowse.texi -ebrowse.pdf: ebrowse.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/ebrowse.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +ebrowse.dvi: ${srcdir}/ebrowse.texi + $(ENVADD) $(TEXI2DVI) $< +ebrowse.pdf: ${srcdir}/ebrowse.texi + $(ENVADD) $(TEXI2PDF) $< ede : $(infodir)/ede $(infodir)/ede: ede.texi - cd $(srcdir); $(MAKEINFO) ede.texi -ede.dvi: ede.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/ede.texi -ede.pdf: ede.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/ede.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +ede.dvi: ${srcdir}/ede.texi + $(ENVADD) $(TEXI2DVI) $< +ede.pdf: ${srcdir}/ede.texi + $(ENVADD) $(TEXI2PDF) $< ediff : $(infodir)/ediff $(infodir)/ediff: ediff.texi - cd $(srcdir); $(MAKEINFO) ediff.texi -ediff.dvi: ediff.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi -ediff.pdf: ediff.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/ediff.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +ediff.dvi: ${srcdir}/ediff.texi + $(ENVADD) $(TEXI2DVI) $< +ediff.pdf: ${srcdir}/ediff.texi + $(ENVADD) $(TEXI2PDF) $< edt : $(infodir)/edt $(infodir)/edt: edt.texi - cd $(srcdir); $(MAKEINFO) edt.texi -edt.dvi: edt.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/edt.texi -edt.pdf: edt.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/edt.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +edt.dvi: ${srcdir}/edt.texi + $(ENVADD) $(TEXI2DVI) $< +edt.pdf: ${srcdir}/edt.texi + $(ENVADD) $(TEXI2PDF) $< eieio : $(infodir)/eieio $(infodir)/eieio: eieio.texi - cd $(srcdir); $(MAKEINFO) eieio.texi -eieio.dvi: eieio.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/eieio.texi -eieio.pdf: eieio.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/eieio.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +eieio.dvi: ${srcdir}/eieio.texi + $(ENVADD) $(TEXI2DVI) $< +eieio.pdf: ${srcdir}/eieio.texi + $(ENVADD) $(TEXI2PDF) $< emacs-mime : $(infodir)/emacs-mime $(infodir)/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 -emacs-mime.pdf: emacs-mime.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-mime.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) --enable-encoding $< +emacs-mime.dvi: ${srcdir}/emacs-mime.texi + $(ENVADD) $(TEXI2DVI) $< +emacs-mime.pdf: ${srcdir}/emacs-mime.texi + $(ENVADD) $(TEXI2PDF) $< epa : $(infodir)/epa $(infodir)/epa: epa.texi - cd $(srcdir); $(MAKEINFO) epa.texi -epa.dvi: epa.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/epa.texi -epa.pdf: epa.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/epa.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +epa.dvi: ${srcdir}/epa.texi + $(ENVADD) $(TEXI2DVI) $< +epa.pdf: ${srcdir}/epa.texi + $(ENVADD) $(TEXI2PDF) $< erc : $(infodir)/erc $(infodir)/erc: erc.texi - cd $(srcdir); $(MAKEINFO) erc.texi -erc.dvi: erc.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/erc.texi -erc.pdf: erc.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/erc.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +erc.dvi: ${srcdir}/erc.texi + $(ENVADD) $(TEXI2DVI) $< +erc.pdf: ${srcdir}/erc.texi + $(ENVADD) $(TEXI2PDF) $< + +ert : $(infodir)/ert +$(infodir)/ert: ert.texi $(infodir) + cd $(srcdir); $(MAKEINFO) ert.texi +ert.dvi: ert.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ert.texi +ert.pdf: ert.texi + $(ENVADD) $(TEXI2PDF) ${srcdir}/ert.texi eshell : $(infodir)/eshell $(infodir)/eshell: eshell.texi - cd $(srcdir); $(MAKEINFO) eshell.texi -eshell.dvi: eshell.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi -eshell.pdf: eshell.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/eshell.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +eshell.dvi: ${srcdir}/eshell.texi + $(ENVADD) $(TEXI2DVI) $< +eshell.pdf: ${srcdir}/eshell.texi + $(ENVADD) $(TEXI2PDF) $< eudc : $(infodir)/eudc $(infodir)/eudc: eudc.texi - cd $(srcdir); $(MAKEINFO) eudc.texi -eudc.dvi: eudc.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/eudc.texi -eudc.pdf: eudc.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/eudc.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +eudc.dvi: ${srcdir}/eudc.texi + $(ENVADD) $(TEXI2DVI) $< +eudc.pdf: ${srcdir}/eudc.texi + $(ENVADD) $(TEXI2PDF) $< efaq : $(infodir)/efaq -$(infodir)/efaq: faq.texi - cd $(srcdir); $(MAKEINFO) faq.texi -faq.dvi: faq.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/faq.texi -faq.pdf: faq.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/faq.texi +$(infodir)/efaq: faq.texi $(emacsdir)/emacsver.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +faq.dvi: ${srcdir}/faq.texi $(emacsdir)/emacsver.texi + $(ENVADD) $(TEXI2DVI) $< +faq.pdf: ${srcdir}/faq.texi $(emacsdir)/emacsver.texi + $(ENVADD) $(TEXI2PDF) $< +## This is the name used on the Emacs web-page. +## sed fixes up links to point to split version of the manual. +emacs-faq.html: ${srcdir}/faq.texi $(emacsdir)/emacsver.texi + $(MAKEINFO) $(MAKEINFO_OPTS) --no-split \ + --css-ref='/layout.css' --html -o $@ $< + sed -i -e 's|a href="\([a-z]*\)\.html#\([^"]*\)"|a href="manual/html_node/\1/\2.html"|g' \ + -e 's|/Top\.html|/|g' $@ +emacs-faq.text: ${srcdir}/faq.texi $(emacsdir)/emacsver.texi + $(MAKEINFO) $(MAKEINFO_OPTS) --plaintext -o $@ $< flymake : $(infodir)/flymake $(infodir)/flymake: flymake.texi - cd $(srcdir); $(MAKEINFO) flymake.texi -flymake.dvi: flymake.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/flymake.texi -flymake.pdf: flymake.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/flymake.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +flymake.dvi: ${srcdir}/flymake.texi + $(ENVADD) $(TEXI2DVI) $< +flymake.pdf: ${srcdir}/flymake.texi + $(ENVADD) $(TEXI2PDF) $< forms : $(infodir)/forms $(infodir)/forms: forms.texi - cd $(srcdir); $(MAKEINFO) forms.texi -forms.dvi: forms.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/forms.texi -forms.pdf: forms.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/forms.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +forms.dvi: ${srcdir}/forms.texi + $(ENVADD) $(TEXI2DVI) $< +forms.pdf: ${srcdir}/forms.texi + $(ENVADD) $(TEXI2PDF) $< # gnus/message/emacs-mime/sieve/pgg are part of Gnus: gnus : $(infodir)/gnus $(infodir)/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 + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +gnus.dvi: ${srcdir}/gnus.texi gnus-faq.texi + sed -e '/@iflatex/,/@end iflatex/d' $< > gnustmp.texi $(ENVADD) $(TEXI2DVI) gnustmp.texi cp gnustmp.dvi $*.dvi rm gnustmp.* -gnus.pdf: gnus.texi gnus-faq.texi - sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi +gnus.pdf: ${srcdir}/gnus.texi gnus-faq.texi + sed -e '/@iflatex/,/@end iflatex/d' $< > gnustmp.texi $(ENVADD) $(TEXI2PDF) gnustmp.texi cp gnustmp.pdf $@ rm gnustmp.* @@ -400,229 +451,259 @@ gnus.pdf: gnus.texi gnus-faq.texi # names clash on DOS 8+3 filesystems idlwave : $(infodir)/idlwave $(infodir)/idlwave: idlwave.texi - cd $(srcdir); $(MAKEINFO) --no-split idlwave.texi -idlwave.dvi: idlwave.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/idlwave.texi -idlwave.pdf: idlwave.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/idlwave.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) --no-split $< +idlwave.dvi: ${srcdir}/idlwave.texi + $(ENVADD) $(TEXI2DVI) $< +idlwave.pdf: ${srcdir}/idlwave.texi + $(ENVADD) $(TEXI2PDF) $< # 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 : $(infodir)/info # circular! $(infodir)/info: info.texi - cd $(srcdir); $(MAKEINFO) --no-split info.texi -o $@ -info.dvi: info.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/info.texi -info.pdf: info.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/info.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) --no-split $< -o $@ +info.dvi: ${srcdir}/info.texi + $(ENVADD) $(TEXI2DVI) $< +info.pdf: ${srcdir}/info.texi + $(ENVADD) $(TEXI2PDF) $< mairix-el : $(infodir)/mairix-el $(infodir)/mairix-el: mairix-el.texi - cd $(srcdir); $(MAKEINFO) mairix-el.texi -mairix-el.dvi: mairix-el.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/mairix-el.texi -mairix-el.pdf: mairix-el.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/mairix-el.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +mairix-el.dvi: ${srcdir}/mairix-el.texi + $(ENVADD) $(TEXI2DVI) $< +mairix-el.pdf: ${srcdir}/mairix-el.texi + $(ENVADD) $(TEXI2PDF) $< message : $(infodir)/message $(infodir)/message: message.texi - cd $(srcdir); $(MAKEINFO) message.texi -message.dvi: message.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/message.texi -message.pdf: message.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/message.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +message.dvi: ${srcdir}/message.texi + $(ENVADD) $(TEXI2DVI) $< +message.pdf: ${srcdir}/message.texi + $(ENVADD) $(TEXI2PDF) $< mh-e : $(infodir)/mh-e $(infodir)/mh-e: mh-e.texi - cd $(srcdir); $(MAKEINFO) mh-e.texi -mh-e.dvi: mh-e.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/mh-e.texi -mh-e.pdf: mh-e.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/mh-e.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +mh-e.dvi: ${srcdir}/mh-e.texi + $(ENVADD) $(TEXI2DVI) $< +mh-e.pdf: ${srcdir}/mh-e.texi + $(ENVADD) $(TEXI2PDF) $< newsticker : $(infodir)/newsticker $(infodir)/newsticker: newsticker.texi - cd $(srcdir); $(MAKEINFO) newsticker.texi -newsticker.dvi: newsticker.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi -newsticker.pdf: newsticker.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/newsticker.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +newsticker.dvi: ${srcdir}/newsticker.texi + $(ENVADD) $(TEXI2DVI) $< +newsticker.pdf: ${srcdir}/newsticker.texi + $(ENVADD) $(TEXI2PDF) $< nxml-mode : $(infodir)/nxml-mode $(infodir)/nxml-mode: nxml-mode.texi - cd $(srcdir); $(MAKEINFO) nxml-mode.texi -nxml-mode.dvi: nxml-mode.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/nxml-mode.texi -nxml-mode.pdf: nxml-mode.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/nxml-mode.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +nxml-mode.dvi: ${srcdir}/nxml-mode.texi + $(ENVADD) $(TEXI2DVI) $< +nxml-mode.pdf: ${srcdir}/nxml-mode.texi + $(ENVADD) $(TEXI2PDF) $< org : $(infodir)/org $(infodir)/org: org.texi - cd $(srcdir); $(MAKEINFO) org.texi -org.dvi: org.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/org.texi -org.pdf: org.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/org.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +org.dvi: ${srcdir}/org.texi + $(ENVADD) $(TEXI2DVI) $< +org.pdf: ${srcdir}/org.texi + $(ENVADD) $(TEXI2PDF) $< pcl-cvs : $(infodir)/pcl-cvs $(infodir)/pcl-cvs: pcl-cvs.texi - cd $(srcdir); $(MAKEINFO) pcl-cvs.texi -pcl-cvs.dvi: pcl-cvs.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi -pcl-cvs.pdf: pcl-cvs.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/pcl-cvs.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +pcl-cvs.dvi: ${srcdir}/pcl-cvs.texi + $(ENVADD) $(TEXI2DVI) $< +pcl-cvs.pdf: ${srcdir}/pcl-cvs.texi + $(ENVADD) $(TEXI2PDF) $< pgg : $(infodir)/pgg $(infodir)/pgg: pgg.texi - cd $(srcdir); $(MAKEINFO) pgg.texi -pgg.dvi: pgg.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/pgg.texi -pgg.pdf: pgg.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/pgg.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +pgg.dvi: ${srcdir}/pgg.texi + $(ENVADD) $(TEXI2DVI) $< +pgg.pdf: ${srcdir}/pgg.texi + $(ENVADD) $(TEXI2PDF) $< rcirc : $(infodir)/rcirc $(infodir)/rcirc: rcirc.texi - cd $(srcdir); $(MAKEINFO) rcirc.texi -rcirc.dvi: rcirc.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/rcirc.texi -rcirc.pdf: rcirc.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/rcirc.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +rcirc.dvi: ${srcdir}/rcirc.texi + $(ENVADD) $(TEXI2DVI) $< +rcirc.pdf: ${srcdir}/rcirc.texi + $(ENVADD) $(TEXI2PDF) $< reftex : $(infodir)/reftex $(infodir)/reftex: reftex.texi - cd $(srcdir); $(MAKEINFO) reftex.texi -reftex.dvi: reftex.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/reftex.texi -reftex.pdf: reftex.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/reftex.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +reftex.dvi: ${srcdir}/reftex.texi + $(ENVADD) $(TEXI2DVI) $< +reftex.pdf: ${srcdir}/reftex.texi + $(ENVADD) $(TEXI2PDF) $< remember : $(infodir)/remember $(infodir)/remember: remember.texi - cd $(srcdir); $(MAKEINFO) remember.texi -remember.dvi: remember.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/remember.texi -remember.pdf: remember.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/remember.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +remember.dvi: ${srcdir}/remember.texi + $(ENVADD) $(TEXI2DVI) $< +remember.pdf: ${srcdir}/remember.texi + $(ENVADD) $(TEXI2PDF) $< sasl : $(infodir)/sasl $(infodir)/sasl: sasl.texi - cd $(srcdir); $(MAKEINFO) sasl.texi -sasl.dvi: sasl.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/sasl.texi -sasl.pdf: sasl.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/sasl.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +sasl.dvi: ${srcdir}/sasl.texi + $(ENVADD) $(TEXI2DVI) $< +sasl.pdf: ${srcdir}/sasl.texi + $(ENVADD) $(TEXI2PDF) $< sc : $(infodir)/sc $(infodir)/sc: sc.texi - cd $(srcdir); $(MAKEINFO) sc.texi -sc.dvi: sc.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi -sc.pdf: sc.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/sc.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +sc.dvi: ${srcdir}/sc.texi + $(ENVADD) $(TEXI2DVI) $< +sc.pdf: ${srcdir}/sc.texi + $(ENVADD) $(TEXI2PDF) $< semantic : $(infodir)/semantic $(infodir)/semantic: semantic.texi sem-user.texi - cd $(srcdir); $(MAKEINFO) semantic.texi -semantic.dvi: semantic.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/semantic.texi -semantic.pdf: semantic.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/semantic.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +semantic.dvi: ${srcdir}/semantic.texi sem-user.texi + $(ENVADD) $(TEXI2DVI) $< +semantic.pdf: ${srcdir}/semantic.texi sem-user.texi + $(ENVADD) $(TEXI2PDF) $< ses : $(infodir)/ses $(infodir)/ses: ses.texi - cd $(srcdir); $(MAKEINFO) ses.texi -ses.dvi: ses.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/ses.texi -ses.pdf: ses.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/ses.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +ses.dvi: ${srcdir}/ses.texi + $(ENVADD) $(TEXI2DVI) $< +ses.pdf: ${srcdir}/ses.texi + $(ENVADD) $(TEXI2PDF) $< sieve : $(infodir)/sieve $(infodir)/sieve: sieve.texi - cd $(srcdir); $(MAKEINFO) sieve.texi -sieve.dvi: sieve.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/sieve.texi -sieve.pdf: sieve.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/sieve.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +sieve.dvi: ${srcdir}/sieve.texi + $(ENVADD) $(TEXI2DVI) $< +sieve.pdf: ${srcdir}/sieve.texi + $(ENVADD) $(TEXI2PDF) $< smtpmail : $(infodir)/smtpmail $(infodir)/smtpmail: smtpmail.texi - cd $(srcdir); $(MAKEINFO) smtpmail.texi -smtpmail.dvi: smtpmail.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/smtpmail.texi -smtpmail.pdf: smtpmail.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/smtpmail.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +smtpmail.dvi: ${srcdir}/smtpmail.texi + $(ENVADD) $(TEXI2DVI) $< +smtpmail.pdf: ${srcdir}/smtpmail.texi + $(ENVADD) $(TEXI2PDF) $< speedbar : $(infodir)/speedbar $(infodir)/speedbar: speedbar.texi - cd $(srcdir); $(MAKEINFO) speedbar.texi -speedbar.dvi: speedbar.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/speedbar.texi -speedbar.pdf: speedbar.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/speedbar.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +speedbar.dvi: ${srcdir}/speedbar.texi + $(ENVADD) $(TEXI2DVI) $< +speedbar.pdf: ${srcdir}/speedbar.texi + $(ENVADD) $(TEXI2PDF) $< tramp : $(infodir)/tramp $(infodir)/tramp: tramp.texi trampver.texi - cd $(srcdir); $(MAKEINFO) -D emacs tramp.texi -tramp.dvi: tramp.texi trampver.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/tramp.texi -tramp.pdf: tramp.texi trampver.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/tramp.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) -D emacs $< +tramp.dvi: ${srcdir}/tramp.texi trampver.texi + $(ENVADD) $(TEXI2DVI) $< +tramp.pdf: ${srcdir}/tramp.texi trampver.texi + $(ENVADD) $(TEXI2PDF) $< url : $(infodir)/url $(infodir)/url: url.texi - cd $(srcdir); $(MAKEINFO) url.texi -url.dvi: url.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/url.texi -url.pdf: url.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/url.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +url.dvi: ${srcdir}/url.texi + $(ENVADD) $(TEXI2DVI) $< +url.pdf: ${srcdir}/url.texi + $(ENVADD) $(TEXI2PDF) $< vip : $(infodir)/vip $(infodir)/vip: vip.texi - cd $(srcdir); $(MAKEINFO) vip.texi -vip.dvi: vip.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/vip.texi -vip.pdf: vip.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/vip.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +vip.dvi: ${srcdir}/vip.texi + $(ENVADD) $(TEXI2DVI) $< +vip.pdf: ${srcdir}/vip.texi + $(ENVADD) $(TEXI2PDF) $< viper : $(infodir)/viper $(infodir)/viper: viper.texi - cd $(srcdir); $(MAKEINFO) viper.texi -viper.dvi: viper.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/viper.texi -viper.pdf: viper.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/viper.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +viper.dvi: ${srcdir}/viper.texi + $(ENVADD) $(TEXI2DVI) $< +viper.pdf: ${srcdir}/viper.texi + $(ENVADD) $(TEXI2PDF) $< widget : $(infodir)/widget $(infodir)/widget: widget.texi - cd $(srcdir); $(MAKEINFO) widget.texi -widget.dvi: widget.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/widget.texi -widget.pdf: widget.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/widget.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +widget.dvi: ${srcdir}/widget.texi + $(ENVADD) $(TEXI2DVI) $< +widget.pdf: ${srcdir}/widget.texi + $(ENVADD) $(TEXI2PDF) $< woman : $(infodir)/woman $(infodir)/woman: woman.texi - cd $(srcdir); $(MAKEINFO) woman.texi -woman.dvi: woman.texi - $(ENVADD) $(TEXI2DVI) ${srcdir}/woman.texi -woman.pdf: woman.texi - $(ENVADD) $(TEXI2PDF) ${srcdir}/woman.texi + $(mkinfodir) + cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $< +woman.dvi: ${srcdir}/woman.texi + $(ENVADD) $(TEXI2DVI) $< +woman.pdf: ${srcdir}/woman.texi + $(ENVADD) $(TEXI2PDF) $< + +.PHONY: mostlyclean clean distclean maintainer-clean mostlyclean: - rm -f *.log *.cp *.fn *.ky *.op *.ops *.pg *.vr core *.tp \ - *.tps *.core gnustmp.* - rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc + rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ + *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f gnustmp.* clean: mostlyclean - rm -f *.dvi *.pdf + rm -f $(DVI_TARGETS) $(PDF_TARGETS) $(HTML_TARGETS) emacs-faq.text distclean: clean # rm -f Makefile +## infodir is relative to srcdir. maintainer-clean: distclean - for file in $(INFO_TARGETS); do rm -f $${file}*; done - + cd $(srcdir); for file in $(INFO_TARGETS); do \ + rm -f $${file} $${file}-[1-9] $${file}-[1-9][0-9]; \ + done ### Makefile ends here diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi index 9f4fd44f46..66cdb20011 100644 --- a/doc/misc/ada-mode.texi +++ b/doc/misc/ada-mode.texi @@ -3,8 +3,7 @@ @settitle Ada Mode @copying -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -40,6 +39,7 @@ developing GNU and promoting software freedom.'' @contents @node Top, Overview, (dir), (dir) +@top Ada Mode @ifnottex @insertcopying @@ -1524,7 +1524,3 @@ autofill the current comment. @printindex fn @bye - -@ignore - arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e -@end ignore diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index 5c555e81a7..a16da92343 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -1,13 +1,16 @@ \input texinfo @c -*-texinfo-*- + +@include gnus-overrides.texi + @setfilename ../../info/auth @settitle Emacs auth-source Library @value{VERSION} -@set VERSION 0.2 +@set VERSION 0.3 @copying This file describes the Emacs auth-source library. -Copyright @copyright{} 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2008-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -35,7 +38,12 @@ license to the document, as described in section 6 of the license. @end direntry @titlepage +@ifset WEBHACKDEVEL +@title Emacs auth-source Library (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title Emacs auth-source Library +@end ifclear @author by Ted Zlatanov @page @vskip 0pt plus 1filll @@ -57,7 +65,9 @@ It is a way for multiple applications to share a single configuration @menu * Overview:: Overview of the auth-source library. * Help for users:: +* Secret Service API:: * Help for developers:: +* GnuPG and EasyPG Assistant Configuration:: * Index:: * Function Index:: * Variable Index:: @@ -68,15 +78,19 @@ It is a way for multiple applications to share a single configuration @chapter Overview The auth-source library is simply a way for Emacs and Gnus, among -others, to find the answer to the old burning question ``I have a -server name and a port, what are my user name and password?'' +others, to answer the old burning question ``What are my user name and +password?'' + +(This is different from the old question about burning ``Where is the +fire extinguisher, please?''.) + +The auth-source library supports more than just the user name or the +password (known as the secret). -The auth-source library actually supports more than just the user name -(known as the login) or the password, but only those two are in use -today in Emacs or Gnus. Similarly, the auth-source library can in -theory support multiple storage formats, but currently it only -understands the classic ``netrc'' format, examples of which you can -see later in this document. +Similarly, the auth-source library supports multiple storage backend, +currently either the classic ``netrc'' backend, examples of which you +can see later in this document, or the Secret Service API. This is +done with EIEIO-based backends and you can write your own if you want. @node Help for users @chapter Help for users @@ -86,27 +100,42 @@ see later in this document. machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} @end example -The machine is the server (either a DNS name or an IP address). +The @code{machine} is the server (either a DNS name or an IP address). +It's known as @var{:host} in @code{auth-source-search} queries. You +can also use @code{host}. + +The @code{port} is the connection port or protocol. It's known as +@var{:port} in @code{auth-source-search} queries. + +The @code{user} is the user name. It's known as @var{:user} in +@code{auth-source-search} queries. You can also use @code{login} and +@code{account}. + +Spaces are always OK as far as auth-source is concerned (but other +programs may not like them). Just put the data in quotes, escaping +quotes as you'd expect with @code{\}. -The port is optional. If it's missing, auth-source will assume any -port is OK. Actually the port is a protocol name or a port number so -you can have separate entries for port @var{143} and for protocol -@var{imap} if you fancy that. Anyway, you can just omit the port if -you don't need it. +All these are optional. You could just say (but we don't recommend +it, we're just showing that it's possible) -The login and password are simply your login credentials to the server. +@example +password @var{mypassword} +@end example + +to use the same password everywhere. Again, @emph{DO NOT DO THIS} or +you will be pwned as the kids say. ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc}; nowadays @code{.authinfo} seems to be more popular and the auth-source -library encourages this confusion by making it the default, as you'll -see later. +library encourages this confusion by accepting both, as you'll see +later. -If you have problems with the port, set @code{auth-source-debug} to -@code{t} and see what port the library is checking in the -@code{*Messages*} buffer. Ditto for any other problems, your first -step is always to see what's being checked. The second step, of -course, is to write a blog entry about it and wait for the answer in -the comments. +If you have problems with the search, set @code{auth-source-debug} to +@code{'trivia} and see what host, port, and user the library is +checking in the @code{*Messages*} buffer. Ditto for any other +problems, your first step is always to see what's being checked. The +second step, of course, is to write a blog entry about it and wait for +the answer in the comments. You can customize the variable @code{auth-sources}. The following may be needed if you are using an older version of Emacs or if the @@ -120,40 +149,45 @@ auth-source library is not loaded for some other reason. @defvar auth-sources The @code{auth-sources} variable tells the auth-source library where -your netrc files live for a particular host and protocol. While you -can get fancy, the default and simplest configuration is: +your netrc files or Secret Service API collection items live for a +particular host and protocol. While you can get fancy, the default +and simplest configuration is: @lisp -(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) +;;; old default: required :host and :port, not needed anymore +(setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t))) +;;; mostly equivalent (see below about fallbacks) but shorter: +(setq auth-sources '((:source "~/.authinfo.gpg"))) +;;; even shorter and the @emph{default}: +(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc")) +;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API}) +(setq auth-sources '("secrets:Login")) @end lisp -This says ``for any host and any protocol, use just that one file.'' -Sweet simplicity. In fact, this is already the default, so unless you -want to move your netrc file, it will just work if you have that -file. You may not, though, so make sure it exists. - By adding multiple entries to @code{auth-sources} with a particular host or protocol, you can have specific netrc files for that host or protocol. Usually this is unnecessary but may make sense if you have shared netrc files or some other unusual setup (90% of Emacs users have unusual setups and the remaining 10% are @emph{really} unusual). +Here's a mixed example using two sources: + +@lisp +(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") + "~/.authinfo.gpg")) +@end lisp + @end defvar If you don't customize @code{auth-sources}, you'll have to live with the defaults: any host and any port are looked up in the netrc -file @code{~/.authinfo.gpg}. This is an encrypted file if and only if -you set up EPA, which is strongly recommended. +file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file +(@pxref{GnuPG and EasyPG Assistant Configuration}). -@lisp -(require 'epa-file) -(epa-file-enable) -;;; VERY important if you want symmetric encryption -;;; irrelevant if you don't -(setq epa-file-cache-passphrase-for-symmetric-encryption t) -@end lisp +If that fails, the unencrypted netrc files @code{~/.authinfo} and +@code{~/.netrc} will be used. -The simplest working netrc line example is one without a port. +The typical netrc line example is without a port. @example machine YOURMACHINE login YOU password YOURPASSWORD @@ -190,44 +224,156 @@ don't use a port entry, you match any Tramp method, as explained earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup. +@node Secret Service API +@chapter Secret Service API + +TODO: how does it work generally, how does secrets.el work, some examples. + @node Help for developers @chapter Help for developers -The auth-source library only has one function for external use. +The auth-source library lets you control logging output easily. -@defun auth-source-user-or-password mode host port +@defvar auth-source-debug +Set this variable to 'trivia to see lots of output in *Messages*, or +set it to a function that behaves like @code{message} to do your own +logging. +@end defvar + +The auth-source library only has a few functions for external use. -Retrieve appropriate authentication tokens, determined by @var{mode}, -for host @var{host} and @var{port}. If @code{auth-source-debug} is t, -debugging messages will be printed. Set @code{auth-source-debug} to a -function to use that function for logging. The parameters passed will -be the same that the @code{message} function takes, that is, a string -formatting spec and optional parameters. +@defun auth-source-search SPEC -If @var{mode} is a list of strings, the function will return a list of -strings or @code{nil} objects (thus you can avoid parsing the netrc -file more than once). If it's a string, the function will return a -string or a @code{nil} object. Currently only the modes ``login'' and -``password'' are recognized but more may be added in the future. +TODO: how to include docstring? -@var{host} is a string containing the host name. +@end defun -@var{port} contains the protocol name (e.g. ``imap'') or -a port number. It must be a string, corresponding to the port in the -user's netrc files. +Let's take a look at an example of using @code{auth-source-search} +from Gnus' @code{nnimap.el}. @example -;; IMAP example -(setq auth (auth-source-user-or-password - '("login" "password") - "anyhostnamehere" - "imap")) -(nth 0 auth) ; the login name -(nth 1 auth) ; the password +(defun nnimap-credentials (address ports) + (let* ((auth-source-creation-prompts + '((user . "IMAP user at %h: ") + (secret . "IMAP password for %u@@%h: "))) + (found (nth 0 (auth-source-search :max 1 + :host address + :port ports + :require '(:user :secret) + :create t)))) + (if found + (list (plist-get found :user) + (let ((secret (plist-get found :secret))) + (if (functionp secret) + (funcall secret) + secret)) + (plist-get found :save-function)) + nil))) @end example +This call requires the user and password (secret) to be in the +results. It also requests that an entry be created if it doesn't +exist already. While the created entry is being assembled, the shown +prompts will be used to interact with the user. The caller can also +pass data in @code{auth-source-creation-defaults} to supply defaults +for any of the prompts. + +Note that the password needs to be evaluated if it's a function. It's +wrapped in a function to provide some security. + +Later, after a successful login, @code{nnimal.el} calls the +@code{:save-function} like so: + +@example +(when (functionp (nth 2 credentials)) + (funcall (nth 2 credentials))) +@end example + +This will work whether the @code{:save-function} was provided or not. +@code{:save-function} will be provided only when a new entry was +created, so this effectively says ``after a successful login, save the +authentication information we just used, if it was newly created.'' + +After the first time it's called, the @code{:save-function} will not +run again (but it will log something if you have set +@code{auth-source-debug} to @code{'trivia}). This is so it won't ask +the same question again, which is annoying. This is so it won't ask +the same question again, which is annoying. This is so it won't ask +the same question again, which is annoying. + +So the responsibility of the API user that specified @code{:create t} +is to call the @code{:save-function} if it's provided. + +@defun auth-source-delete SPEC + +TODO: how to include docstring? + +@end defun + +@defun auth-source-forget SPEC + +TODO: how to include docstring? + +@end defun + +@defun auth-source-forget+ SPEC + +TODO: how to include docstring? + @end defun +@node GnuPG and EasyPG Assistant Configuration +@appendix GnuPG and EasyPG Assistant Configuration + +If you don't customize @code{auth-sources}, the auth-source library +reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file. Then +it will check @code{~/.authinfo} but it's not recommended to use such +an unencrypted file. + +In Emacs 23 or later there is an option @code{auto-encryption-mode} to +automatically decrypt @code{*.gpg} files. It is enabled by default. +If you are using earlier versions of Emacs, you will need: + +@lisp +(require 'epa-file) +(epa-file-enable) +@end lisp + +If you want your GnuPG passwords to be cached, set up @code{gpg-agent} +or EasyPG Assitant +(@pxref{Caching Passphrases, , Caching Passphrases, epa}). + +To quick start, here are some questions: + +@enumerate +@item +Do you use GnuPG version 2 instead of GnuPG version 1? +@item +Do you use symmetric encryption rather than public key encryption? +@item +Do you want to use gpg-agent? +@end enumerate + +Here are configurations depending on your answers: + +@multitable {111} {222} {333} {configuration configuration configuration} +@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration +@item Yes @tab Yes @tab Yes @tab Set up gpg-agent. +@item Yes @tab Yes @tab No @tab You can't, without gpg-agent. +@item Yes @tab No @tab Yes @tab Set up gpg-agent. +@item Yes @tab No @tab No @tab You can't, without gpg-agent. +@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. +@item No @tab Yes @tab No @tab Set up elisp passphrase cache. +@item No @tab No @tab Yes @tab Set up gpg-agent. +@item No @tab No @tab No @tab You can't, without gpg-agent. +@end multitable + +To set up gpg-agent, follow the instruction in GnuPG manual +(@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}). + +To set up elisp passphrase cache, set +@code{epa-file-cache-passphrase-for-symmetric-encryption}. + @node Index @chapter Index @printindex cp @@ -243,7 +389,3 @@ user's netrc files. @bye @c End: - -@ignore - arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 -@end ignore diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index 7f9dd0daa0..2e66c78a3c 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -10,8 +10,7 @@ @c @cindex autotypist @copying -Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004, 2005, -2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1994-1995, 1999, 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -664,7 +663,3 @@ of the expansion possibilities. @printindex vr @bye - -@ignore - arch-tag: 54001b27-5ef8-4a9d-a199-905d650fafba -@end ignore diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index 0a595d90b8..f732eff569 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -7,6 +7,8 @@ @setchapternewpage odd @comment %**end of header (This is for running Texinfo on a region.) +@include emacsver.texi + @c The following macros are used for conditional output for single lines. @c @texline foo @c `foo' will appear only in TeX output @@ -76,7 +78,6 @@ @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 @@ -89,11 +90,11 @@ This file documents Calc, the GNU Emacs calculator. @end ifinfo @ifnotinfo -This file documents Calc, the GNU Emacs calculator, included with GNU Emacs 23.3. +This file documents Calc, the GNU Emacs calculator, included with +GNU Emacs @value{EMACSVER}. @end ifnotinfo -Copyright @copyright{} 1990, 1991, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1990-1991, 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1804,7 +1805,6 @@ or, in large mathematical notation, @end example @end ifnottex @tex -\turnoffactive \beforedisplay $$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$ \afterdisplay @@ -3358,7 +3358,6 @@ Suppose we had the following set of equations: @end group @end ifnottex @tex -\turnoffactive \beforedisplayh $$ \openup1\jot \tabskip=0pt plus1fil \halign to\displaywidth{\tabskip=0pt @@ -3385,7 +3384,6 @@ This can be cast into the matrix equation, @end group @end ifnottex @tex -\turnoffactive \beforedisplay $$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 } \times @@ -3457,7 +3455,6 @@ in terms of @expr{a} and @expr{b}. @end group @end ifnottex @tex -\turnoffactive \beforedisplay $$ \eqalign{ x &+ a y = 6 \cr x &+ b y = 10} @@ -3483,7 +3480,6 @@ on the left by the transpose of @expr{A}: @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 @@ -3506,7 +3502,6 @@ system: @end group @end ifnottex @tex -\turnoffactive \beforedisplayh $$ \openup1\jot \tabskip=0pt plus1fil \halign to\displaywidth{\tabskip=0pt @@ -3778,7 +3773,6 @@ 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} $$ @@ -3820,7 +3814,6 @@ 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$.) @@ -3874,7 +3867,6 @@ b = (sum(y) - m sum(x)) / N @end example @end ifnottex @tex -\turnoffactive \beforedisplay $$ b = {\sum y - m \sum x \over N} $$ \afterdisplay @@ -5223,7 +5215,6 @@ down to the formula, @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 @@ -5245,7 +5236,6 @@ h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ... @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)) $$ @@ -5686,7 +5676,6 @@ 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 @@ -5704,7 +5693,6 @@ 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 @@ -6234,7 +6222,7 @@ new_x = x - f(x)/f'(x) @end ifnottex @tex \beforedisplay -$$ x_{\rm new} = x - {f(x) \over f'(x)} $$ +$$ x_{\rm new} = x - {f(x) \over f^{\prime}(x)} $$ \afterdisplay @end tex @@ -6336,7 +6324,6 @@ 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 @@ -6875,7 +6862,6 @@ get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum. @end example @end ifnottex @tex -\turnoffactive \beforedisplay $$ \eqalign{ x &+ a y = 6 \cr x &+ b y = 10} @@ -6939,7 +6925,6 @@ which we can solve using Calc's @samp{/} command. @end example @end ifnottex @tex -\turnoffactive \beforedisplayh $$ \openup1\jot \tabskip=0pt plus1fil \halign to\displaywidth{\tabskip=0pt @@ -7074,7 +7059,6 @@ the first job is to form the matrix that describes the problem. @end example @end ifnottex @tex -\turnoffactive \beforedisplay $$ m \times x + b \times 1 = y $$ \afterdisplay @@ -7865,7 +7849,6 @@ So the result when we take the modulo after every step is, @end example @end ifnottex @tex -\turnoffactive \beforedisplay $$ 3 (3 a + b - 511 m) + c - 511 n $$ \afterdisplay @@ -7881,7 +7864,6 @@ the distributive law yields @end example @end ifnottex @tex -\turnoffactive \beforedisplay $$ 9 a + 3 b + c - 511\times3 m - 511 n $$ \afterdisplay @@ -7899,9 +7881,8 @@ term. So we can take it out to get an equivalent formula with @end example @end ifnottex @tex -\turnoffactive \beforedisplay -$$ 9 a + 3 b + c - 511 n' $$ +$$ 9 a + 3 b + c - 511 n^{\prime} $$ \afterdisplay @end tex @@ -12167,7 +12148,7 @@ 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 +file name is @file{~/.emacs.d/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}. @@ -12289,15 +12270,21 @@ 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 +@kindex O +@pindex calc-option +The @kbd{O} key (@code{calc-option}) sets another flag, the +@dfn{Option Flag}, which also can alter the subsequent Calc command in +various ways. + +The Inverse, Hyperbolic and Option 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}, @kbd{H} or @kbd{O} (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). + +Another Calc prefix flag, @kbd{K} (keep-arguments), is discussed elsewhere. @xref{Keep Arguments}. @node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings @@ -13175,12 +13162,13 @@ in the current radix. (Larger integers will still be displayed in their entirety.) @cindex Two's complements -With the binary, octal and hexadecimal display modes, Calc can -display @expr{w}-bit integers using two's complement notation. This -option is selected with the key sequences @kbd{C-u d 2}, @kbd{C-u d 8} -and @kbd{C-u d 6}, respectively, and a negative word size might be -appropriate (@pxref{Binary Functions}). In two's complement -notation, the integers in the (nearly) symmetric interval from +Calc can display @expr{w}-bit integers using two's complement +notation, although this is most useful with the binary, octal and +hexadecimal display modes. This option is selected by using the +@kbd{O} option prefix before setting the display radix, and a negative word +size might be appropriate (@pxref{Binary Functions}). In two's +complement notation, the integers in the (nearly) symmetric interval +from @texline @math{-2^{w-1}} @infoline @expr{-2^(w-1)} to @@ -14133,6 +14121,10 @@ but @texline @math{\sin(2 + x)}. @infoline @expr{sin(2 + x)}. +The @TeX{} specific unit names (@pxref{Predefined Units}) will not use +the @samp{tex} prefix; the unit name for a @TeX{} point will be +@samp{pt} instead of @samp{texpt}, for example. + 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 @@ -14401,7 +14393,6 @@ $$ \sin\left( a^2 \over b_i \right) $$ @end group @end example @tex -\turnoffactive $$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$ @end tex @sp 1 @@ -14427,7 +14418,6 @@ $$ [|a|, \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 @@ -14460,7 +14450,6 @@ First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}: @end group @end example @tex -\turnoffactive $$ 2 + 3 \to 5 $$ $$ 5 $$ @end tex @@ -14475,7 +14464,6 @@ First with standard @code{\to}, then with @samp{\let\to\Rightarrow}: @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}}] $$} @@ -14492,7 +14480,6 @@ Matrices normally, then changing @code{\matrix} to @code{\pmatrix}: @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 @@ -16006,7 +15993,7 @@ No line breaking (@kbd{d b}). 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}). +Record modes in @file{~/.emacs.d/calc.el} (@kbd{m R}; @pxref{General Mode Commands}). @item Local Record modes in Embedded buffer (@kbd{m R}). @@ -17928,7 +17915,6 @@ ddb(cost, salv, life, per) = --------, book = cost - depreciation so far @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 $$ @@ -18584,7 +18570,6 @@ 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. @@ -20051,6 +20036,20 @@ 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.) +If no prefix is given, then you will be prompted for a vector which +will be used to determine the bins. (If a positive integer is given at +this prompt, it will be still treated as if it were given as a +prefix.) Each bin will consist of the interval of numbers closest to +the corresponding number of this new vector; if the vector +@expr{[a, b, c, ...]} is entered at the prompt, the bins will be +@expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of +this command will be a vector counting how many elements of the +original vector are in each bin. + +The result will then be a vector with the same length as this new vector; +each element of the new vector will be replaced by the number of +elements of the original vector which are closest to it. + @kindex H v H @kindex H V H With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack. @@ -20552,7 +20551,6 @@ 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 @@ -20586,7 +20584,6 @@ 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 @@ -20596,7 +20593,6 @@ 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 @@ -20629,7 +20625,6 @@ 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 @@ -20643,7 +20638,6 @@ 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 @@ -20655,7 +20649,6 @@ 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 @@ -20678,7 +20671,6 @@ 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 @@ -20705,7 +20697,6 @@ 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 @@ -20770,7 +20761,6 @@ 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} @@ -20798,7 +20788,6 @@ 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 @@ -21530,7 +21519,11 @@ to @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 +to a dot. (If the customizable variable +@code{calc-highlight-selections-with-faces} is non-nil, then the characters +not part of the sub-formula are de-emphasized by using a less +noticeable face instead of using dots. @pxref{Displaying Selections}.) +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 @@ -21743,6 +21736,9 @@ of the hierarchy simply by pointing to it with the cursor. @noindent @kindex j d @pindex calc-show-selections +@vindex calc-highlight-selections-with-faces +@vindex calc-selected-face +@vindex calc-nonselected-face 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 @@ -21757,6 +21753,13 @@ by @samp{#} signs: . . . . 2 x + 1 @end group @end smallexample +If the customizable variable +@code{calc-highlight-selections-with-faces} is non-nil, then the +non-selected portion of the formula will be de-emphasized by using a +less noticeable face (@code{calc-nonselected-face}) instead of dots +and the selected sub-formula will be highlighted by using a more +noticeable face (@code{calc-selected-face}) instead of @samp{#} +signs. (@pxref{Customizing Calc}.) @node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas @subsection Operating on Selections @@ -24354,8 +24357,6 @@ For example, suppose the data matrix @end example @end ifnottex @tex -\turnoffactive -\turnoffactive \beforedisplay $$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr 5 & 7 & 9 & 11 & 13 } @@ -24415,7 +24416,6 @@ 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 @@ -24606,7 +24606,6 @@ 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 @@ -25381,7 +25380,6 @@ 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 @@ -27677,6 +27675,8 @@ begin with the @kbd{u} prefix key. * The Units Table:: * Predefined Units:: * User-Defined Units:: +* Logarithmic Units:: +* Musical Notes:: @end menu @node Basic Operations on Units, The Units Table, Units, Units @@ -27995,6 +27995,14 @@ 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). +When Calc is using the @TeX{} or La@TeX{} language mode (@pxref{TeX +and LaTeX Language Modes}), the @TeX{} specific unit names will not +use the @samp{tex} prefix; the unit name for a @TeX{} point will be +@samp{pt} instead of @samp{texpt}, for example. To avoid conflicts, +the unit names for pint and parsec will simply be @samp{pint} and +@samp{parsec} instead of @samp{pt} and @samp{pc}. + + 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 @@ -28030,7 +28038,7 @@ really is unitless.) @c Describe angular units, luminosity vs. steradians problem. -@node User-Defined Units, , Predefined Units, Units +@node User-Defined Units, Logarithmic Units, Predefined Units, Units @section User-Defined Units @noindent @@ -28108,12 +28116,321 @@ possible to create user-defined temperature 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 +@code{calc-settings-file}, typically @file{~/.emacs.d/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 Logarithmic Units, Musical Notes, User-Defined Units, Units +@section Logarithmic Units + +The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic +units which are manipulated differently than standard units. Calc +provides commands to work with these logarithmic units. + +Decibels and nepers are used to measure power quantities as well as +field quantities (quantities whose squares are proportional to power); +these two types of quantities are handled slightly different from each +other. By default the Calc commands work as if power quantities are +being used; with the @kbd{H} prefix the Calc commands work as if field +quantities are being used. + +The decibel level of a power +@infoline @math{P1}, +@texline @math{P_1}, +relative to a reference power +@infoline @math{P0}, +@texline @math{P_0}, +is defined to be +@infoline @math{10 log10(P1/P0) dB}. +@texline @math{10 \log_{10}(P_{1}/P_{0}) {\rm dB}}. +(The factor of 10 is because a decibel, as its name implies, is +one-tenth of a bel. The bel, named after Alexander Graham Bell, was +considered to be too large of a unit and was effectively replaced by +the decibel.) If @math{F} is a field quantity with power +@math{P=k F^2}, then a reference quantity of +@infoline @math{F0} +@texline @math{F_0} +would correspond to a power of +@infoline @math{P0=k F0^2}. +@texline @math{P_{0}=kF_{0}^2}. +If +@infoline @math{P1=k F1^2}, +@texline @math{P_{1}=kF_{1}^2}, +then + +@ifnottex +@example +10 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0). +@end example +@end ifnottex +@tex +$$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20 +\log_{10}(F_1/F_0)$$ +@end tex + +@noindent +In order to get the same decibel level regardless of whether a field +quantity or the corresponding power quantity is used, the decibel +level of a field quantity +@infoline @math{F1}, +@texline @math{F_1}, +relative to a reference +@infoline @math{F0}, +@texline @math{F_0}, +is defined as +@infoline @math{20 log10(F1/F0) dB}. +@texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}. +For example, the decibel value of a sound pressure level of +@infoline @math{60 uPa} +@texline @math{60 \mu{\rm Pa}} +relative to +@infoline @math{20 uPa} +@texline @math{20 \mu{\rm Pa}} +(the threshhold of human hearing) is +@infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB}, +@texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}}, +which is about +@infoline @math{9.54 dB}. +@texline @math{9.54 {\rm dB}}. +Note that in taking the ratio, the original units cancel and so these +logarithmic units are dimensionless. + +Nepers (named after John Napier, who is credited with inventing the +logarithm) are similar to bels except they use natural logarithms instead +of common logarithms. The neper level of a power +@infoline @math{P1}, +@texline @math{P_1}, +relative to a reference power +@infoline @math{P0}, +@texline @math{P_0}, +is +@infoline @math{(1/2) ln(P1/P0) Np}. +@texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}. +The neper level of a field +@infoline @math{F1}, +@texline @math{F_1}, +relative to a reference field +@infoline @math{F0}, +@texline @math{F_0}, +is +@infoline @math{ln(F1/F0) Np}. +@texline @math{\ln(F_1/F_0) {\rm Np}}. + +@vindex calc-lu-power-reference +@vindex calc-lu-field-reference +For power quantities, Calc uses +@infoline @math{1 mW} +@texline @math{1 {\rm mW}} +as the default reference quantity; this default can be changed by changing +the value of the customizable variable +@code{calc-lu-power-reference} (@pxref{Customizing Calc}). +For field quantities, Calc uses +@infoline @math{20 uPa} +@texline @math{20 \mu{\rm Pa}} +as the default reference quantity; this is the value used in acoustics +which is where decibels are commonly encountered. This default can be +changed by changing the value of the customizable variable +@code{calc-lu-field-reference} (@pxref{Customizing Calc}). A +non-default reference quantity will be read from the stack if the +capital @kbd{O} prefix is used. + +@kindex l q +@pindex calc-lu-quant +@tindex lupquant +@tindex lufquant +The @kbd{l q} (@code{calc-lu-quant}) [@code{lupquant}] +command computes the power quantity corresponding to a given number of +logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the +reference level will be read from the top of the stack. (In an +algebraic formula, @code{lupquant} can be given an optional second +argument which will be used for the reference level.) For example, +@code{20 dB @key{RET} l q} will return @code{100 mW}; +@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}. +The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but +computes field quantities instead of power quantities. + +@kindex l d +@pindex calc-db +@tindex dbpower +@tindex dbfield +@kindex l n +@pindex calc-np +@tindex nppower +@tindex npfield +The @kbd{l d} (@code{calc-db}) [@code{dbpower}] command will compute +the decibel level of a power quantity using the default reference +level; @kbd{H l d} [@code{dbfield}] will compute the decibel level of +a field quantity. The commands @kbd{l n} (@code{calc-np}) +[@code{nppower}] and @kbd{H l n} [@code{npfield}] will similarly +compute neper levels. With the capital @kbd{O} prefix these commands +will read a reference level from the stack; in an algebraic formula +the reference level can be given as an optional second argument. + +@kindex l + +@pindex calc-lu-plus +@tindex lupadd +@tindex lufadd +@kindex l - +@pindex calc-lu-minus +@tindex lupsub +@tindex lufsub +@kindex l * +@pindex calc-lu-times +@tindex lupmul +@tindex lufmul +@kindex l / +@pindex calc-lu-divide +@tindex lupdiv +@tindex lufdiv +The sum of two power or field quantities doesn't correspond to the sum +of the corresponding decibel or neper levels. If the powers +corresponding to decibel levels +@infoline @math{D1} +@texline @math{D_1} +and +@infoline @math{D2} +@texline @math{D_2} +are added, the corresponding decibel level ``sum'' will be + +@ifnottex +@example + 10 log10(10^(D1/10) + 10^(D2/10)) dB. +@end example +@end ifnottex +@tex +$$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$ +@end tex + +@noindent +When field quantities are combined, it often means the corresponding +powers are added and so the above formula might be used. In +acoustics, for example, the sound pressure level is a field quantity +and so the decibels are often defined using the field formula, but the +sound pressure levels are combined as the sound power levels, and so +the above formula should be used. If two field quantities themselves +are added, the new decibel level will be + +@ifnottex +@example + 20 log10(10^(D1/20) + 10^(D2/20)) dB. +@end example +@end ifnottex +@tex +$$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$ +@end tex + +@noindent +If the power corresponding to @math{D} dB is multiplied by a number @math{N}, +then the corresponding decibel level will be + +@ifnottex +@example + D + 10 log10(N) dB, +@end example +@end ifnottex +@tex +$$ D + 10 \log_{10}(N) {\rm dB},$$ +@end tex + +@noindent +if a field quantity is multiplied by @math{N} the corresponding decibel level +will be + +@ifnottex +@example + D + 20 log10(N) dB. +@end example +@end ifnottex +@tex +$$ D + 20 \log_{10}(N) {\rm dB}.$$ +@end tex + +@noindent +There are similar formulas for combining nepers. The @kbd{l +} +(@code{calc-lu-plus}) [@code{lupadd}] command will ``add'' two +logarithmic unit power levels this way; with the @kbd{H} prefix, +@kbd{H l +} [@code{lufadd}] will add logarithmic unit field levels. +Similarly, logarithmic units can be ``subtracted'' with @kbd{l -} +(@code{calc-lu-minus}) [@code{lupsub}] or @kbd{H l -} [@code{lufsub}]. +The @kbd{l *} (@code{calc-lu-times}) [@code{lupmul}] and @kbd{H l *} +[@code{lufmul}] commands will ``multiply'' a logarithmic unit by a +number; the @kbd{l /} (@code{calc-lu-divide}) [@code{lupdiv}] and +@kbd{H l /} [@code{lufdiv}] commands will ``divide'' a logarithmic +unit by a number. Note that the reference quantities don't play a role +in this arithmetic. + +@node Musical Notes, , Logarithmic Units, Units +@section Musical Notes + +Calc can convert between musical notes and their associated +frequencies. Notes can be given using either scientific pitch +notation or midi numbers. Since these note systems are basically +logarithmic scales, Calc uses the @kbd{l} prefix for functions +operating on notes. + +Scientific pitch notation refers to a note by giving a letter +A through G, possibly followed by a flat or sharp) with a subscript +indicating an octave number. Each octave starts with C and ends with +B and +@c increasing each note by a semitone will result +@c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E}, +@c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B} +@c flat and @expr{B}. +the octave numbered 0 was chosen to correspond to the lowest +audible frequency. Using this system, middle C (about 261.625 Hz) +corresponds to the note @expr{C} in octave 4 and is denoted +@expr{C_4}. Any frequency can be described by giving a note plus an +offset in cents (where a cent is a ratio of frequencies so that a +semitone consists of 100 cents). + +The midi note number system assigns numbers to notes so that +@expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9} +corresponds to the midi note number 127. A midi controller can have +up to 128 keys and each midi note number from 0 to 127 corresponds to +a possible key. + +@kindex l s +@pindex calc-spn +@tindex spn +The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either +a frequency or a midi number to scientific pitch notation. For +example, @code{500 Hz} gets converted to +@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}. + + +@kindex l m +@pindex calc-midi +@tindex midi +The @kbd{l m} (@code{calc-midi}) [@code{midi}] command converts either +a frequency or a note given in scientific pitch notation to the +corresponding midi number. For example, @code{C_6} gets converted to 84 +and @code{440 Hz} to 69. + +@kindex l f +@pindex calc-freq +@tindex freq +The @kbd{l f} (@code{calc-freq}) [@code{freq}] command converts either +either a midi number or a note given in scientific pitch notation to +the corresponding frequency. For example, @code{Asharp_2 + 30 cents} +gets converted to @code{118.578040134 Hz} and @code{55} to +@code{195.99771799 Hz}. + +Since the frequencies of notes are not usually given exactly (and are +typically irrational), the customizable variable +@code{calc-note-threshold} determines how close (in cents) a frequency +needs to be to a note to be recognized as that note +(@pxref{Customizing Calc}). This variable has a default value of +@code{1}. For example, middle @var{C} is approximately +@expr{261.625565302 Hz}; this frequency is often shortened to +@expr{261.625 Hz}. Without @code{calc-note-threshold} (or a value of +@expr{0}), Calc would convert @code{261.625 Hz} to scientific pitch +notation @code{B_3 + 99.9962592773 cents}; with the default value of +@code{1}, Calc converts @code{261.625 Hz} to @code{C_4}. + + + @node Store and Recall, Graphics, Units, Top @chapter Storing and Recalling @@ -28509,7 +28826,7 @@ names rather than prompting for the variable name. @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 +the variable @code{calc-settings-file}, typically @file{~/.emacs.d/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 @@ -30862,7 +31179,7 @@ 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}) +by the variable @code{calc-settings-file}, typically @file{~/.emacs.d/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 @@ -31122,7 +31439,7 @@ 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, +@code{calc-settings-file}, typically @file{~/.emacs.d/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 @@ -31855,7 +32172,7 @@ step of @code{myfact} could have been written 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. +@file{~/.emacs.d/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, @@ -34933,7 +35250,7 @@ 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 +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. @@ -34956,7 +35273,9 @@ If @code{calc-settings-file} is not your user init file (typically @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"}. +The default value for this variable is @code{"~/.emacs.d/calc.el"} +unless the file @file{~/.calc.el} exists, in which case the default +value will be @code{"~/.calc.el"}. @end defvar @defvar calc-gnuplot-name @@ -35217,6 +35536,45 @@ should also be added to @code{calc-embedded-announce-formula-alist} and @code{calc-embedded-open-close-plain-alist}. @end defvar +@defvar calc-lu-power-reference +@defvarx calc-lu-field-reference +See @ref{Logarithmic Units}.@* +The variables @code{calc-lu-power-reference} and +@code{calc-lu-field-reference} are unit expressions (written as +strings) which Calc will use as reference quantities for logarithmic +units. + +The default value of @code{calc-lu-power-reference} is @code{"mW"} +and the default value of @code{calc-lu-field-reference} is +@code{"20 uPa"}. +@end defvar + +@defvar calc-note-threshold +See @ref{Musical Notes}.@* +The variable @code{calc-note-threshold} is a number (written as a +string) which determines how close (in cents) a frequency needs to be +to a note to be recognized as that note. + +The default value of @code{calc-note-threshold} is 1. +@end defvar + +@defvar calc-highlight-selections-with-faces +@defvarx calc-selected-face +@defvarx calc-nonselected-face +See @ref{Displaying Selections}.@* +The variable @code{calc-highlight-selections-with-faces} +determines how selected sub-formulas are distinguished. +If @code{calc-highlight-selections-with-faces} is nil, then +a selected sub-formula is distinguished either by changing every +character not part of the sub-formula with a dot or by changing every +character in the sub-formula with a @samp{#} sign. +If @code{calc-highlight-selections-with-faces} is t, +then a selected sub-formula is distinguished either by displaying the +non-selected portion of the formula with @code{calc-nonselected-face} +or by displaying the selected sub-formula with +@code{calc-nonselected-face}. +@end defvar + @defvar calc-multiplication-has-precedence The variable @code{calc-multiplication-has-precedence} determines whether multiplication has precedence over division in algebraic @@ -35459,6 +35817,7 @@ keystrokes are not listed in this summary. @r{ @: M @: @: @:calc-more-recursion-depth@:} @r{ @: I M @: @: @:calc-less-recursion-depth@:} @r{ a@: N @: @: 5 @:evalvn@:(a)} +@r{ @: O @:command @: 32 @:@:Option} @r{ @: P @: @: @:@:pi} @r{ @: I P @: @: @:@:gamma} @r{ @: H P @: @: @:@:e} @@ -35847,6 +36206,31 @@ keystrokes are not listed in this summary. @r{ v x@: I k T @: @: @:ltpt@:(x,v)} @c +@r{ a b@: l + @: @: @:lupadd@:(a,b)} +@r{ a b@: H l + @: @: @:lufadd@:(a,b)} +@r{ a b@: l - @: @: @:lupsub@:(a,b)} +@r{ a b@: H l - @: @: @:lufsub@:(a,b)} +@r{ a b@: l * @: @: @:lupmul@:(a,b)} +@r{ a b@: H l * @: @: @:lufmul@:(a,b)} +@r{ a b@: l / @: @: @:lupdiv@:(a,b)} +@r{ a b@: H l / @: @: @:lufdiv@:(a,b)} +@r{ a@: l d @: @: @:dbpower@:(a)} +@r{ a b@: O l d @: @: @:dbpower@:(a,b)} +@r{ a@: H l d @: @: @:dbfield@:(a)} +@r{ a b@: O H l d @: @: @:dbfield@:(a,b)} +@r{ a@: l n @: @: @:nppower@:(a)} +@r{ a b@: O l n @: @: @:nppower@:(a,b)} +@r{ a@: H l n @: @: @:npfield@:(a)} +@r{ a b@: O H l n @: @: @:npfield@:(a,b)} +@r{ a@: l q @: @: @:lupquant@:(a)} +@r{ a b@: O l q @: @: @:lupquant@:(a,b)} +@r{ a@: H l q @: @: @:lufquant@:(a)} +@r{ a b@: O H l q @: @: @:lufquant@:(a,b)} +@r{ a@: l s @: @: @:spn@:(a)} +@r{ a@: l m @: @: @:midi@:(a)} +@r{ a@: l f @: @: @:freq@:(a)} + +@c @r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} @r{ @: m d @: @: @:calc-degrees-mode@:} @r{ @: m e @: @: @:calc-embedded-preserve-modes@:} @@ -36569,8 +36953,3 @@ the corresponding full Lisp name is derived by adding a prefix of @printindex fn @bye - - -@ignore - arch-tag: 77a71809-fa4d-40be-b2cc-da3e8fb137c0 -@end ignore diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 4b56e07226..9ae9abd5e1 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -159,9 +159,7 @@ CC Mode @copying This manual is for CC Mode in Emacs. -Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 -Free Software Foundation, Inc. +Copyright @copyright{} 1995-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -312,19 +310,19 @@ Indentation Engine Basics 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:: +* 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:: +* Java Symbols:: +* Statement Block Symbols:: +* K&R Symbols:: Customizing Indentation @@ -3971,6 +3969,9 @@ The first line in a ``topmost'' definition. @ref{Function Symbols}. 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 annotation-top-cont +Topmost definition continuation lines where all previous items are +annotations. @ref{Java Symbols}. @item member-init-intro First line in a member initialization list. @ref{Class Symbols}. @item member-init-cont @@ -3999,6 +4000,9 @@ with an open brace. @ref{Brace List Symbols}. A statement. @ref{Function Symbols}. @item statement-cont A continuation of a statement. @ref{Function Symbols}. +@item annotation-var-cont +A continuation of a statement where all previous items are +annotations. @ref{Java Symbols}. @item statement-block-intro The first line in a new statement block. @ref{Conditional Construct Symbols}. @@ -4112,23 +4116,23 @@ 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}. +Java. @ref{Java Symbols}. @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:: +* 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:: +* Java Symbols:: +* Statement Block Symbols:: +* K&R Symbols:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -4233,7 +4237,7 @@ Hitting @kbd{C-c C-s} on line 5 shows the following analysis: @noindent The primary syntactic symbol for this line is @code{access-label} as -this a label keyword that specifies access protection in C++. However, +this is 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}. @@ -4740,7 +4744,7 @@ 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 +@node Objective-C Method Symbols, Java Symbols, Multiline Macro Symbols, Syntactic Symbols @comment node-name, next, previous, up @subsection Objective-C Method Symbols @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -4767,34 +4771,45 @@ 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 +@node Java Symbols, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols @comment node-name, next, previous, up -@subsection Anonymous Class Symbol (Java) +@subsection Java Symbols @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: @} + 1: @@Test + 2: public void watch(Observable o) @{ + 3: @@NonNull + 4: Observer obs = new Observer() @{ + 5: public void update(Observable o, Object arg) @{ + 6: history.addElement(arg); + 7: @} + 8: @}; + 9: o.addObserver(obs); + 10: @} @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 +Lines 5 and 8 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. +@ssindex annotation-top-cont +@ssindex annotation-var-cont +Line 2 is assigned the @code{annotation-top-cont} syntax, due to it being a +continuation of a topmost introduction with an annotation symbol preceding +the current line. Similarly, line 4 is assigned the @code{annotation-var-cont} +syntax due to it being a continuation of a variable declaration where preceding +the declaration is an annotation. + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols +@node Statement Block Symbols, K&R Symbols, Java Symbols, Syntactic Symbols @comment node-name, next, previous, up @subsection Statement Block Symbols @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -6997,4 +7012,3 @@ Since most @ccmode{} variables are prepended with the string @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @bye - diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 6bdc494a1a..afe7c94f44 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -5,8 +5,7 @@ @copying This file documents the GNU Emacs Common Lisp emulation package. -Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1017,10 +1016,10 @@ 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 +global-key-binding x-get-secondary-selection +keymap-parent x-get-selection +local-key-binding +mark mark-marker @end smallexample @@ -3740,10 +3739,10 @@ 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 +@defun cl-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}, +collected into a list. The return value of @code{cl-mapc} is @var{seq}, the first sequence. This function is more general than the Emacs primitive @code{mapc}. @end defun diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index b34a25b64f..e6fb00d348 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -5,8 +5,11 @@ @c @setchapternewpage odd @c %**end of header +@syncodeindex vr cp +@syncodeindex fn cp + @copying -Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -50,7 +53,10 @@ another. An overview of D-Bus can be found at * Asynchronous Methods:: Calling methods non-blocking. * Receiving Method Calls:: Offering own methods. * Signals:: Sending and receiving signals. +* Alternative Buses:: Alternative buses. * Errors and Events:: Errors and events. +* Index:: Index including concepts, functions, variables. + * GNU Free Documentation License:: The license for this documentation. @end menu @@ -126,14 +132,24 @@ There are several basic functions which inspect the buses for registered names. Internally they use the basic interface @samp{org.freedesktop.DBus}, which is supported by all objects of a bus. -@defun dbus-list-activatable-names -This function returns the D-Bus service names, which can be activated. -An activatable service is described in a service registration file. -Under GNU/Linux, such files are located at -@file{/usr/share/dbus-1/services/}. +@defun dbus-list-activatable-names &optional bus +This function returns the D-Bus service names, which can be activated +for @var{bus}. It must be either the symbol @code{:system} (the +default) or the symbol @code{:session}. An activatable service is +described in a service registration file. Under GNU/Linux, such files +are located at @file{/usr/share/dbus-1/system-services/} (for the +@code{:system} bus) or @file{/usr/share/dbus-1/services/}. An +activatable service is not necessarily registered at @var{bus} at already. The result is a list of strings, which is @code{nil} when there are no -activatable service names at all. +activatable service names at all. Example: + +@lisp +;; Check, whether the document viewer can be accessed via D-Bus. +(member "org.gnome.evince.Daemon" + (dbus-list-activatable-names :session)) +@end lisp + @end defun @defun dbus-list-names bus @@ -148,7 +164,7 @@ strings like @samp{org.freedesktop.DBus}. Names starting with @end defun @defun dbus-list-known-names bus -Retrieves all services which correspond to a known name in @var{bus}. +Retrieves all registered services which correspond to a known name in @var{bus}. A service has a known name if it doesn't start with @samp{:}. The result is a list of strings, which is @code{nil} when there are no known names at all. @@ -418,7 +434,8 @@ Example: @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig" @end lisp -If @var{object} has no @var{attribute}, the function returns nil. +If @var{object} has no @var{attribute}, the function returns +@code{nil}. @end defun @@ -669,7 +686,7 @@ A @var{property} value can be retrieved by the function @defun dbus-get-property bus service path interface property This function returns the value of @var{property} of @var{interface}. It will be checked at @var{bus}, @var{service}, @var{path}. The -result can be any valid D-Bus value, or nil if there is no +result can be any valid D-Bus value, or @code{nil} if there is no @var{property}. Example: @lisp @@ -863,12 +880,12 @@ Lisp function call. The following mapping to D-Bus types is applied, when the corresponding D-Bus message is created: @example -@multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN} +@multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN} @item Lisp type @tab @tab D-Bus type @item @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN -@item number @tab @expansion{} @tab DBUS_TYPE_UINT32 -@item integer @tab @expansion{} @tab DBUS_TYPE_INT32 +@item natural number @tab @expansion{} @tab DBUS_TYPE_UINT32 +@item negative integer @tab @expansion{} @tab DBUS_TYPE_INT32 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE @item string @tab @expansion{} @tab DBUS_TYPE_STRING @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY @@ -883,25 +900,26 @@ symbol can be prepended to the corresponding Lisp object. Basic D-Bus types are represented by the type symbols @code{:byte}, @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, -@code{:string}, @code{:object-path} and @code{:signature}. +@code{:string}, @code{:object-path}, @code{:signature} and +@code{:unix-fd}. @noindent Example: @lisp -(dbus-call-method @dots{} @var{NUMBER} @var{STRING}) +(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING}) @end lisp is equivalent to @lisp -(dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING}) +(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING}) @end lisp but different to @lisp -(dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING}) +(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING}) @end lisp The value for a byte D-Bus type can be any integer in the range 0 @@ -994,17 +1012,18 @@ Output parameters of D-Bus methods and signals are mapped to Lisp objects. @example -@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}} +@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float} @item D-Bus type @tab @tab Lisp type @item @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} -@item DBUS_TYPE_BYTE @tab @expansion{} @tab number -@item DBUS_TYPE_UINT16 @tab @expansion{} @tab number -@item DBUS_TYPE_INT16 @tab @expansion{} @tab number -@item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float -@item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float -@item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float -@item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float +@item DBUS_TYPE_BYTE @tab @expansion{} @tab natural number +@item DBUS_TYPE_UINT16 @tab @expansion{} @tab natural number +@item DBUS_TYPE_INT16 @tab @expansion{} @tab integer +@item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number or float +@item DBUS_TYPE_UNIX_FD @tab @expansion{} @tab natural number or float +@item DBUS_TYPE_INT32 @tab @expansion{} @tab integer or float +@item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number or float +@item DBUS_TYPE_INT64 @tab @expansion{} @tab integer or float @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float @item DBUS_TYPE_STRING @tab @expansion{} @tab string @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string @@ -1017,9 +1036,9 @@ objects. @end example A float object in case of @code{DBUS_TYPE_UINT32}, -@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and -@code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the -Emacs number size range. +@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64}, +@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when +the C value exceeds the Emacs number size range. The resulting list of the last 4 D-Bus compound types contains as elements the elements of the D-Bus container, mapped according to the @@ -1030,7 +1049,7 @@ The signal @code{PropertyModified}, discussed as example in (@var{BOOL} stands here for either @code{nil} or @code{t}): @lisp -(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) +(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) @end lisp @defun dbus-byte-array-to-string byte-array @@ -1234,9 +1253,73 @@ message has been arrived, and @var{handler} is called. Example: @cindex method calls, returning @cindex returning method calls -Emacs can also offer own methods, which can be called by other -applications. These methods could be an implementation of an -interface of a well known service, like @samp{org.freedesktop.TextEditor}. +In order to register methods on the D-Bus, Emacs has to request a well +known name on the D-Bus under which it will be available for other +clients. Names on the D-Bus can be registered and unregistered using +the following functions: + +@defun dbus-register-service bus service &rest flags +Register the known name @var{service} on D-Bus @var{bus}. + +@var{bus} is either the symbol @code{:system} or the symbol +@code{:session}. + +@var{service} is the service name to be registered on the D-Bus. It +must be a known name. + +@var{flags} is a subset of the following keywords: + +@itemize +@item @code{:allow-replacement}: Allow another service to become the primary +owner if requested. + +@item @code{:replace-existing}: Request to replace the current primary owner. + +@item @code{:do-not-queue}: If we can not become the primary owner do not +place us in the queue. +@end itemize + +One of the following keywords is returned: + +@itemize + +@item @code{:primary-owner}: We have become the primary owner of the name +@var{service}. + +@item @code{:in-queue}: We could not become the primary owner and +have been placed in the queue. + +@item @code{:exists}: We already are in the queue. + +@item @code{:already-owner}: We already are the primary +owner. +@end itemize +@end defun + +@defun dbus-unregister-service bus service +Unregister all objects from D-Bus @var{bus}, registered by Emacs for +@var{service}. + +@var{bus} is either the symbol @code{:system} or the symbol +@code{:session}. + +@var{service} is the D-Bus service name of the D-Bus. It must be a +known name. Emacs releases its association to @var{service} from +D-Bus. + +One of the following keywords is returned: + +@itemize +@item @code{:released}: We successfully released the name @var{service}. +@item @code{:non-existent}: The name @var{service} does not exist on the bus. +@item @code{:not-owner}: We are not an owner of the name @var{service}. +@end itemize +@end defun + +When a name has been chosen, Emacs can offer own methods, which can be +called by other applications. These methods could be an +implementation of an interface of a well known service, like +@samp{org.freedesktop.TextEditor}. It could be also an implementation of an own interface. In this case, the service name must be @samp{org.gnu.Emacs}. The object path shall @@ -1255,7 +1338,7 @@ paths, used by offered methods or signals, shall start with this string. @end deffn -@defun dbus-register-method bus service path interface method handler +@defun dbus-register-method bus service path interface method handler dont-register-service With this function, an application registers @var{method} on the D-Bus @var{bus}. @@ -1263,10 +1346,11 @@ With this function, an application registers @var{method} on the D-Bus @code{:session}. @var{service} is the D-Bus service name of the D-Bus object -@var{method} is registered for. It must be a known name. +@var{method} is registered for. It must be a known name (See +discussion of @var{dont-register-service} below). -@var{path} is the D-Bus object path @var{service} is -registered. +@var{path} is the D-Bus object path @var{service} is registered (See +discussion of @var{dont-register-service} below). @var{interface} is the interface offered by @var{service}. It must provide @var{method}. @@ -1285,6 +1369,13 @@ returning a list containing the object. In case @var{handler} shall return a reply message with an empty argument list, @var{handler} must return the symbol @code{:ignore}. +When @var{dont-register-service} is non-@code{nil}, the known name +@var{service} is not registered. This means that other D-Bus clients +have no way of noticing the newly registered method. When interfaces +are constructed incrementally by adding single methods or properties +at a time, @var{dont-register-service} can be used to prevent other +clients from discovering the still incomplete interface. + The default D-Bus timeout when waiting for a message reply is 25 seconds. This value could be even smaller, depending on the calling client. Therefore, @var{handler} shall not last longer than @@ -1359,7 +1450,7 @@ The test runs then @end example @end defun -@defun dbus-register-property bus service path interface property access value +@defun dbus-register-property bus service path interface property access value &optional emits-signal dont-register-service With this function, an application declares a @var{property} on the D-Bus @var{bus}. @@ -1369,8 +1460,8 @@ With this function, an application declares a @var{property} on the D-Bus @var{service} is the D-Bus service name of the D-Bus. It must be a known name. -@var{path} is the D-Bus object path @var{service} is -registered. +@var{path} is the D-Bus object path @var{service} is registered (See +discussion of @var{dont-register-service} below). @var{interface} is the name of the interface used at @var{path}, @var{property} is the name of the property of @var{interface}. @@ -1387,7 +1478,19 @@ only way to change their values. Properties with access type The interface @samp{org.freedesktop.DBus.Properties} is added to @var{path}, including a default handler for the @samp{Get}, -@samp{GetAll} and @samp{Set} methods of this interface. Example: +@samp{GetAll} and @samp{Set} methods of this interface. When +@var{emits-signal} is non-@code{nil}, the signal +@samp{PropertiesChanged} is sent when the property is changed by +@code{dbus-set-property}. + +When @var{dont-register-service} is non-@code{nil}, the known name +@var{service} is not registered. This means that other D-Bus clients +have no way of noticing the newly registered method. When interfaces +are constructed incrementally by adding single methods or properties +at a time, @var{dont-register-service} can be used to prevent other +clients from discovering the still incomplete interface. + +@noindent Example: @lisp (dbus-register-property @@ -1399,7 +1502,7 @@ The interface @samp{org.freedesktop.DBus.Properties} is added to (dbus-register-property :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version" :readwrite emacs-version) + "org.freedesktop.TextEditor" "version" :readwrite emacs-version t) @result{} ((:session "org.freedesktop.TextEditor" "version") ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) @@ -1461,18 +1564,6 @@ registered for the respective service, Emacs releases its association to the service from D-Bus. @end defun -@defun dbus-unregister-service bus service -Unregister all objects from D-Bus @var{bus}, registered by Emacs for -@var{service}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus. It must be a -known name. Emacs releases its association to @var{service} from -D-Bus. -@end defun - @node Signals @chapter Sending and receiving signals. @@ -1568,11 +1659,68 @@ which objects the GNU/Linux @code{hal} daemon adds. @end defun +@node Alternative Buses +@chapter Alternative buses. +@cindex bus names +@cindex UNIX domain socket + +Until now, we have spoken about the system and the session buses, +which are the default buses to be connected to. However, it is +possible to connect to any bus, from which the address is known. This +is a UNIX domain socket. Everywhere, where a @var{bus} is mentioned +as argument of a function (the symbol @code{:system} or the symbol +@code{:session}), this address can be used instead. The connection to +this bus must be initialized first. + +@defun dbus-init-bus bus +Establish the connection to D-Bus @var{bus}. + +@var{bus} can be either the symbol @code{:system} or the symbol +@code{:session}, or it can be a string denoting the address of the +corresponding bus. For the system and session busses, this function +is called when loading @file{dbus.el}, there is no need to call it +again. + +Example: You open another session bus in a terminal window on your host: + +@example +# eval `dbus-launch --auto-syntax` +# echo $DBUS_SESSION_BUS_ADDRESS + +@print{} unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e +@end example + +In Emacs, you can access to this bus via its address: + +@lisp +(setq my-bus + "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e") + +@result{} "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e" + +(dbus-init-bus my-bus) + +@result{} nil + +(dbus-get-unique-name my-bus) + +@result{} ":1.0" +@end lisp +@end defun + + @node Errors and Events @chapter Errors and events. +@cindex debugging @cindex errors @cindex events +The internal actions can be traced by running in a debug mode. + +@defvar dbus-debug +If this variable is non-@code{nil}, D-Bus specific debug messages are raised. +@end defvar + Input parameters of @code{dbus-call-method}, @code{dbus-call-method-non-blocking}, @code{dbus-call-method-asynchronously}, and @@ -1587,8 +1735,7 @@ appended to the @code{dbus-error}. @defspec dbus-ignore-errors forms@dots{} This executes @var{forms} exactly like a @code{progn}, except that @code{dbus-error} errors are ignored during the @var{forms}. These -errors can be made visible when variable @code{dbus-debug} is set to -@code{t}. +errors can be made visible when @code{dbus-debug} is set to @code{t}. @end defspec Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc @@ -1636,12 +1783,12 @@ The result is either the symbol @code{:system} or the symbol @code{:session}. @defun dbus-event-message-type event Returns the message type of the corresponding D-Bus message. The -result is a number. +result is a natural number. @end defun @defun dbus-event-serial-number event Returns the serial number of the corresponding D-Bus message. -The result is a number. +The result is a natural number. @end defun @defun dbus-event-service-name event @@ -1691,12 +1838,14 @@ D-Bus applications running. Therefore, they shall check carefully, whether a given D-Bus error is related to them. +@node Index +@unnumbered Index + +@printindex cp + + @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi @bye - -@ignore - arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8 -@end ignore diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 2a49390041..99530e6356 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -10,6 +10,8 @@ @setfilename ../../info/dired-x @settitle Dired Extra User's Manual +@include emacsver.texi + @iftex @finalout @end iftex @@ -17,8 +19,8 @@ @comment %**end of header (This is for running Texinfo on a region.) @copying -Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1994-1995, 1999, 2001-2011 +Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -68,6 +70,7 @@ developing GNU and promoting software freedom.'' @ifnottex @node Top +@top Dired Extra @noindent This documents the ``extra'' features for GNU Emacs's Dired Mode that are @@ -79,7 +82,7 @@ provided by the file @file{dired-x.el}. Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de> @item -For @file{dired-x.el} as distributed with GNU Emacs 23. +For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. @end itemize @@ -126,39 +129,24 @@ original @file{dired-x.el}). @section Features @cindex Features -Some features provided by Dired Extra +Some features provided by Dired Extra: @enumerate @item -Omitting uninteresting files from Dired listing. -@itemize @bullet -@xref{Omitting Files in Dired}. -@end itemize +Omitting uninteresting files from Dired listing +(@pxref{Omitting Files in Dired}). @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 +Guessing shell commands in Dired buffers +(@pxref{Shell Command Guessing}). @item -Running Dired commands in non-Dired buffers. -@itemize @bullet -@xref{Virtual Dired}. -@end itemize +Running Dired command in non-Dired buffers +(@pxref{Virtual Dired}). @item -Finding a file mentioned in a buffer. -@itemize @bullet -@xref{Find File At Point}. -@end itemize +Finding a file mentioned in a buffer +(@pxref{Find File At Point}). @item -Commands using file marking. -@itemize @bullet -@xref{Advanced Mark Commands}. -@end itemize +Commands using file marking +(@pxref{Advanced Mark Commands}). @end enumerate @noindent @@ -171,30 +159,19 @@ respectively (@pxref{Find File At Point}). @node Technical Details, , Features, Introduction @section Technical Details -@cindex Redefined functions +@cindex Modified 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} -@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 +When @file{dired-x.el} is loaded, some standard Dired functions from +@file{dired.el} and @file{dired-aux.el} offer additional features. +@code{dired-add-entry} obeys Dired Omit mode (@pxref{Omitting Files in +Dired}), if it is active. @code{dired-find-buffer-nocreate} and +@code{dired-initial-position} respect the value of +@code{dired-find-subdir} (@pxref{Miscellaneous Commands}). +@code{dired-clean-up-after-deletion} respects the value of +@code{dired-clean-up-buffers-too}. @code{dired-read-shell-command} uses +@code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to +offer a smarter default command. @node Installation, Omitting Files in Dired, Introduction, Top @chapter Installation @@ -261,22 +238,9 @@ for these functions. In your @file{.emacs} file put @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 +@code{dired-x-hands-off-my-keys}. To do this, either set it +@emph{before} @file{dired-x.el} is loaded, or use @kbd{M-x customize-variable}, +or call @code{dired-x-bind-find-file} after changing the value. @example (add-hook 'dired-load-hook @@ -372,28 +336,17 @@ 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 +To enable omitting automatically only in certain directories you can add +a directory local setting +(@pxref{Directory Variables,,,emacs,The Gnu Emacs manual}) for Dired mode @example -Local Variables: -dired-omit-mode: t -End: +((dired-mode . ((dired-omit-mode . t)))) @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 +to a @file{.dir-locals.el} file in that directory. You can use the +command @code{add-dir-local-variable} to do this. @vindex dired-omit-files @item dired-omit-files @@ -499,7 +452,9 @@ then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). +in the @code{dired-load-hook} (@pxref{Installation}). (Of course, a +better way to achieve this particular goal is simply to omit @samp{-a} from +@code{dired-listing-switches}.) @end itemize @@ -511,7 +466,6 @@ Loading @file{dired-x.el} will install Dired Omit by putting call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} in your @code{dired-mode-hook}. -@c FIXME does the standard dir-locals mechanism obsolete this? @node Local Variables, Shell Command Guessing, Omitting Files in Dired, Top @chapter Local Variables for Dired Directories @@ -519,10 +473,15 @@ in your @code{dired-mode-hook}. @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}. +This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs +directory local variables mechanism (@pxref{Directory +Variables,,,emacs,The Gnu Emacs manual}) replaces it. For an example of +the new mechanims, @pxref{Omitting Variables}. + +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 @@ -572,12 +531,10 @@ into the Dired buffer and run @code{hack-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. +Controls the use of local-variables lists in Dired. This variable +temporarily overrides the value of @code{enable-local-variables} when +the Dired Local Variables are hacked. It takes the same values as that +variable. A value of @code{nil} means to ignore any Dired Local Variables. @end table @node Shell Command Guessing, Virtual Dired, Local Variables, Top @@ -912,24 +869,12 @@ 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 +@findex dired-smart-shell-command +@findex shell-command +@kindex M-! +The command @code{dired-smart-shell-command}, bound to @kbd{M-!} in +Dired buffers, is like @code{shell-command}, but it runs with +@code{default-directory} bound to the current Dired directory. @node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top @section Find File At Point @@ -1038,12 +983,6 @@ 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 @@ -1076,13 +1015,12 @@ 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. +read-only. 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. +@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. @vindex dired-bind-vm If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound @@ -1173,7 +1111,3 @@ enhancement, then please use @kbd{M-x report-emacs-bug} to report it. @printindex vr @bye - -@ignore - arch-tag: 201727aa-9318-4c74-a0d7-4f51c550c4de -@end ignore diff --git a/doc/misc/doclicense.texi b/doc/misc/doclicense.texi index d3ae2f92b2..a511ffcd5a 100644 --- a/doc/misc/doclicense.texi +++ b/doc/misc/doclicense.texi @@ -505,7 +505,3 @@ to permit their use in free software. @c Local Variables: @c ispell-local-pdict: "ispell-dict" @c End: - -@ignore - arch-tag: c1679162-1d8a-4f02-bc52-2e71765f0165 -@end ignore diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi index 58b04dc7b8..19ee970548 100644 --- a/doc/misc/ebrowse.texi +++ b/doc/misc/ebrowse.texi @@ -10,8 +10,7 @@ @copying This file documents Ebrowse, a C++ class browser for GNU Emacs. -Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2000-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -47,6 +46,7 @@ developing GNU and promoting software freedom.'' @ifnottex @node Top, Overview, (dir), (dir) +@top Ebrowse You can browse C++ class hierarchies from within Emacs by using Ebrowse. @@ -1451,7 +1451,3 @@ in on with the command @kbd{C-c C-m m}. @printindex cp @bye - -@ignore - arch-tag: 52fe78ac-a1c4-48e7-815e-0a31acfad4bf -@end ignore diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 57dc01d9fe..13b640a09f 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -5,8 +5,7 @@ @copying This file describes EDE, the Emacs Development Environment. -Copyright @copyright{} 1998, 1999, 2000, 2001, 2004, 2005, 2008, 2009, -2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1998-2001, 2004-2005, 2008-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -242,7 +241,7 @@ To add the current file to an existing target, type @kbd{C-c . a} You can add a file to more than one target; this is OK. To remove the current file from a target, type @kbd{C-c . d} -(@code{ede-remove-file}), or or use the @samp{Remove File} menu item +(@code{ede-remove-file}), or use the @samp{Remove File} menu item in the @samp{Target Options} submenu. If the file belongs to multiple targets, this command prompts for each target it could be removed from. @@ -2124,7 +2123,7 @@ Results in --add-missing being passed to automake. @end deffn @deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accomodate @var{THIS}. +Flush the configure file (current buffer) to accommodate @var{THIS}. By flushing, remove any cruft that may be in the file. Subsequent calls to @dfn{ede-proj-tweak-autoconf} can restore items removed by flush. @end deffn @@ -2175,7 +2174,7 @@ These are removed with make clean. @end deffn @deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accomodate @var{THIS}. +Tweak the configure file (current buffer) to accommodate @var{THIS}. @end deffn @deffn Method ede-proj-compilers :AFTER obj @@ -2685,7 +2684,7 @@ Bonus: Return a cons cell: (COMPILED . UPTODATE). @end deffn @deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accomodate @var{THIS}. +Flush the configure file (current buffer) to accommodate @var{THIS}. @end deffn @deffn Method ede-buffer-mine :AFTER this buffer @@ -2698,7 +2697,7 @@ Return the variable name for @var{THIS}'s sources. @end deffn @deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accomodate @var{THIS}. +Tweak the configure file (current buffer) to accommodate @var{THIS}. @end deffn @deffn Method ede-update-version-in-source :AFTER this version @@ -2778,7 +2777,7 @@ Create or update the autoload target. @end deffn @deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accomodate @var{THIS}. +Flush the configure file (current buffer) to accommodate @var{THIS}. @end deffn @deffn Method ede-buffer-mine :AFTER this buffer @@ -2797,7 +2796,7 @@ Argument @var{THIS} is the target which needs to insert an info file. @end deffn @deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accomodate @var{THIS}. +Tweak the configure file (current buffer) to accommodate @var{THIS}. @end deffn @deffn Method ede-update-version-in-source :AFTER this version @@ -3009,7 +3008,7 @@ The preferred interpreter for this code. @subsubsection Specialized Methods @deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accomodate @var{THIS}. +Tweak the configure file (current buffer) to accommodate @var{THIS}. @end deffn @@ -3537,7 +3536,7 @@ For example, C code uses .o on unix, and Emacs Lisp uses .elc. @subsubsection Specialized Methods @deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accomodate @var{THIS}. +Flush the configure file (current buffer) to accommodate @var{THIS}. @end deffn @deffn Method ede-proj-makefile-insert-rules :AFTER this @@ -3559,7 +3558,7 @@ Retrieves the slot @code{sourcetype} from an object of class @code{ede-compilati @end deffn @deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accomodate @var{THIS}. +Tweak the configure file (current buffer) to accommodate @var{THIS}. @end deffn @@ -3791,7 +3790,3 @@ For example, C code uses .o on unix, and Emacs Lisp uses .elc. @end table @bye - -@ignore - arch-tag: c9bfdc6e-e6e9-4e87-97f7-d8348342fbf4 -@end ignore diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 8774fae506..3ba0796e63 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -25,8 +25,7 @@ This file documents Ediff, a comprehensive visual interface to Unix diff and patch utilities. -Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -64,6 +63,7 @@ developing GNU and promoting software freedom.'' @contents @node Top, Introduction, (dir), (dir) +@top Ediff @insertcopying @@ -759,7 +759,7 @@ 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 +(Some poor souls leave so many active Ediff sessions around that they lose track of them completely... The `R' command is designed to save these people from the recently discovered Ediff Proficiency Syndrome.) @@ -2315,7 +2315,7 @@ 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. +This is because it is all too easy to lose a 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. @@ -2541,7 +2541,3 @@ Eli Zaretskii (eliz at is.elta.co.il) @printindex cp @bye - -@ignore - arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46 -@end ignore diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi index 68c2db7336..8f9f8fc03a 100644 --- a/doc/misc/edt.texi +++ b/doc/misc/edt.texi @@ -5,8 +5,7 @@ @copying This file documents the EDT emulation package for Emacs. -Copyright @copyright{} 1986, 1992, 1994, 1995, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 1986, 1992, 1994-1995, 1999-2011 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index f36efff3a0..8ee40288fe 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -11,7 +11,7 @@ @copying This manual documents EIEIO, an object framework for Emacs Lisp. -Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1906,7 +1906,3 @@ Allow method overloading of method-like functions in Emacs. @contents @bye - -@ignore - arch-tag: 7225b7c7-2462-4563-99e7-836a20172178 -@end ignore diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 6121f1afd7..a9d80d868b 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -1,5 +1,7 @@ \input texinfo +@include gnus-overrides.texi + @setfilename ../../info/emacs-mime @settitle Emacs MIME Manual @synindex fn cp @@ -9,8 +11,7 @@ @copying This file documents the Emacs MIME interface functionality. -Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, -2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1998-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -39,7 +40,12 @@ developing GNU and promoting software freedom.'' @setchapternewpage odd @titlepage +@ifset WEBHACKDEVEL +@title Emacs MIME Manual (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title Emacs MIME Manual +@end ifclear @author by Lars Magne Ingebrigtsen @page @@ -374,12 +380,18 @@ message as follows: @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 +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 +@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. +their size. If you set this variable to @code{resize}, the image will +be displayed resized to fit in the window, if Emacs has the ability to +resize images. + +@item mm-inline-large-images-proportion +@vindex mm-inline-images-max-proportion +The proportion used when resizing large images. @item mm-inline-override-types @vindex mm-inline-override-types @@ -394,7 +406,7 @@ 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}, +renderers are selected by the symbols @code{gnus-article-html}, @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 @@ -1034,6 +1046,10 @@ flowed text, the default is to wrap after 66 characters. If hard newline characters are not present in the buffer, no flow encoding occurs. +You can customize the value of the @code{mml-enable-flowed} variable +to enable or disable the flowed encoding usage when newline +characteres are present in the buffer. + 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 @@ -1469,21 +1485,9 @@ 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 +Encode a parameter in the RFC2047-like style. This is a substitution +for the @code{rfc2231-encode-string} function, that is the standard but +many mailers don't support it. @xref{rfc2231}. @end table @@ -1889,7 +1893,3 @@ Documentation of the text/plain format parameter for flowed text. @c mode: texinfo @c coding: iso-8859-1 @c End: - -@ignore - arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d -@end ignore diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi index e6402fb83f..b4137a7dac 100644 --- a/doc/misc/epa.texi +++ b/doc/misc/epa.texi @@ -9,7 +9,7 @@ @copying This file describes EasyPG Assistant @value{VERSION}. -Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -65,7 +65,9 @@ called EasyPG Library. @menu * Overview:: * Quick start:: -* Commands:: +* Commands:: +* Caching Passphrases:: +* Bug Reports:: @end menu @node Overview @@ -304,14 +306,14 @@ Encrypt marked files. @section Mail-mode integration EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help -user compose inline PGP messages. Inline PGP is a traditional style -of sending signed/encrypted emails by embedding raw OpenPGP blobs -inside a message body, not using modern MIME format. +user compose inline OpenPGP messages. Inline OpenPGP is a traditional +style of sending signed/encrypted emails by embedding raw OpenPGP +blobs inside a message body, not using modern MIME format. -NOTE: Inline PGP is not recommended and you should consider to use +NOTE: Inline OpenPGP is not recommended and you should consider to use PGP/MIME. See @uref{http://josefsson.org/inline-openpgp-considered-harmful.html, -Inline PGP in E-mail is bad, Mm'kay?}. +Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}. @noindent Once @code{epa-mail-mode} is enabled, the following keys are assigned. @@ -319,22 +321,26 @@ You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customize interface. Try @kbd{M-x customize-variable epa-global-mail-mode}. @table @kbd -@item C-c C-e d +@item C-c C-e C-d and C-c C-e d +@kindex @kbd{C-c C-e C-d} @kindex @kbd{C-c C-e d} @findex epa-mail-decrypt Decrypt OpenPGP armors in the current buffer. -@item C-c C-e v +@item C-c C-e C-v and C-c C-e v +@kindex @kbd{C-c C-e C-v} @kindex @kbd{C-c C-e v} @findex epa-mail-verify Verify OpenPGP cleartext signed messages in the current buffer. -@item C-c C-e s +@item C-c C-e C-s and C-c C-e s +@kindex @kbd{C-c C-e C-s} @kindex @kbd{C-c C-e s} @findex epa-mail-sign Compose a signed message from the current buffer. -@item C-c C-e e +@item C-c C-e C-e and C-c C-e e +@kindex @kbd{C-c C-e C-e} @kindex @kbd{C-c C-e e} @findex epa-mail-encrypt Compose an encrypted message from the current buffer. @@ -347,16 +353,21 @@ key in the recipient list, use @samp{encrypt-to} option in @node Encrypting/decrypting *.gpg files @section Encrypting/decrypting *.gpg files -By default, every file whose extension is @samp{.gpg} will be treated -as encrypted. That is, when you attempt to open such a file which -already exists, the decrypted text is inserted in the buffer rather -than encrypted one. On the other hand, when you attempt to save the -buffer to a file whose extension is @samp{.gpg}, encrypted data is -written. +By default, every file whose name ends with @samp{.gpg} will be +treated as encrypted. That is, when you open such a file, the +decrypted text is inserted in the buffer rather than encrypted one. +Similarly, when you save the buffer to a @samp{foo.gpg} file, +encrypted data is written. -If you want to temporarily disable this behavior, use @kbd{M-x -epa-file-disable}, and then to enable this behavior use @kbd{M-x -epa-file-enable}. +The file name pattern for encrypted files can be controlled by +@var{epa-file-name-regexp}. + +@defvar epa-file-name-regexp +Regexp which matches filenames treated as encrypted. +@end defvar + +You can disable this behavior with @kbd{M-x epa-file-disable}, and +then get it back with @kbd{M-x epa-file-enable}. @deffn Command epa-file-disable Disable automatic encryption/decryption of *.gpg files. @@ -367,23 +378,48 @@ Enable automatic encryption/decryption of *.gpg files. @end deffn @noindent -@code{epa-file} will let you select recipients. If you want to -suppress this question, it might be a good idea to put the following -line on the first line of the text being encrypted. +By default, @code{epa-file} will try to use symmetric encryption, aka +password-based encryption. If you want to use public key encryption +instead, do @kbd{M-x epa-file-select-keys}, which will pops up the key +selection dialog. + +@deffn Command epa-file-select-keys +Select recipient keys to encrypt the currently visiting file with +public key encryption. +@end deffn + +You can also change the default behavior with the variable +@var{epa-file-select-keys}. + +@defvar epa-file-select-keys +Control whether or not to pop up the key selection dialog. +@end defvar + +For frequently visited files, it might be a good idea to tell Emacs +which encryption method should be used through @xref{File Variables, , +, emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local +variable for this. @vindex epa-file-encrypt-to +For example, if you want an Elisp file should be encrypted with a +public key associated with an email address @samp{ueno@@unixuser.org}, +add the following line to the beginning of the file. + @cartouche @lisp ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*- @end lisp @end cartouche -The file name extension of encrypted files can be controlled by -@var{epa-file-name-regexp}. +Instead, if you want the file always (regardless of the value of the +@code{epa-file-select-keys} variable) encrypted with symmetric +encryption, change the line as follows. -@defvar epa-file-name-regexp -Regexp which matches filenames treated as encrypted. -@end defvar +@cartouche +@lisp +;; -*- epa-file-encrypt-to: nil -*- +@end lisp +@end cartouche Other variables which control the automatic encryption/decryption behavior are below. @@ -398,10 +434,65 @@ If non-@code{nil}, disable auto-saving when opening an encrypted file. The default value is @code{t}. @end defvar +@node Caching Passphrases +@chapter Caching Passphrases + +Typing passphrases is an irritating task if you frequently open and +close the same file. GnuPG and EasyPG Assistant provide mechanisms to +remember your passphrases. However, the configuration is a bit +confusing since it depends on your GnuPG installation (GnuPG version 1 or +GnuPG version 2), encryption method (symmetric or public key), and whether or +not you want to use gpg-agent. Here are some questions: + +@enumerate +@item Do you use GnuPG version 2 instead of GnuPG version 1? +@item Do you use symmetric encryption rather than public key encryption? +@item Do you want to use gpg-agent? +@end enumerate + +Here are configurations depending on your answers: + +@multitable {111} {222} {333} {configuration configuration configuration} +@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration +@item Yes @tab Yes @tab Yes @tab Set up gpg-agent. +@item Yes @tab Yes @tab No @tab You can't, without gpg-agent. +@item Yes @tab No @tab Yes @tab Set up gpg-agent. +@item Yes @tab No @tab No @tab You can't, without gpg-agent. +@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. +@item No @tab Yes @tab No @tab Set up elisp passphrase cache. +@item No @tab No @tab Yes @tab Set up gpg-agent. +@item No @tab No @tab No @tab You can't, without gpg-agent. +@end multitable + +To set up gpg-agent, follow the instruction in GnuPG manual. +@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}. + +To set up elisp passphrase cache, set +@code{epa-file-cache-passphrase-for-symmetric-encryption}. +@xref{Encrypting/decrypting *.gpg files}. + +@node Bug Reports +@chapter Bug Reports + +Bugs and problems with EasyPG Assistant are actively worked on by the +Emacs development team. Feature requests and suggestions are also +more than welcome. Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, , +Bugs, emacs, Reporting Bugs}. + +When submitting a bug report, please try to describe in excruciating +detail the steps required to reproduce the problem. Also try to +collect necessary information to fix the bug, such as: + +@itemize @bullet +@item the GnuPG version. Send the output of @samp{gpg --version}. +@item the GnuPG configuration. Send the contents of @file{~/.gnupg/gpg.conf}. +@end itemize + +Before reporting the bug, you should set @code{epg-debug} in the +@file{~/.emacs} file and repeat the bug. Then, include the contents +of the @samp{ *epg-debug*} buffer. Note that the first letter of the +buffer name is a whitespace. + @bye @c End: - -@ignore - arch-tag: 7404e246-7d4c-4db4-9332-c1293a455a4f -@end ignore diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index aa7cb893fd..b46748a08f 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -8,7 +8,7 @@ @copying This manual is for ERC version 5.3. -Copyright @copyright{} 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2005-2011 Free Software Foundation, Inc. @quotation @@ -1061,7 +1061,3 @@ We switched to using git for our version control system. @printindex cp @bye - -@ignore - arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e -@end ignore diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi new file mode 100644 index 0000000000..978cac6992 --- /dev/null +++ b/doc/misc/ert.texi @@ -0,0 +1,841 @@ +\input texinfo +@c %**start of header +@setfilename ../../info/ert +@settitle Emacs Lisp Regression Testing +@c %**end of header + +@dircategory Emacs +@direntry +* ERT: (ert). Emacs Lisp Regression Testing. +@end direntry + +@copying +Copyright @copyright{} 2008, 2010-2011 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License'' +in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@node Top, Introduction, (dir), (dir) +@top ERT: Emacs Lisp Regression Testing + +ERT is a tool for automated testing in Emacs Lisp. Its main features +are facilities for defining tests, running them and reporting the +results, and for debugging test failures interactively. + +ERT is similar to tools for other environments such as JUnit, but has +unique features that take advantage of the dynamic and interactive +nature of Emacs. Despite its name, it works well both for test-driven +development (see +@url{http://en.wikipedia.org/wiki/Test-driven_development}) and for +traditional software development methods. + +@menu +* Introduction:: A simple example of an ERT test. +* How to Run Tests:: Run tests in your Emacs or from the command line. +* How to Write Tests:: How to add tests to your Emacs Lisp code. +* How to Debug Tests:: What to do if a test fails. +* Extending ERT:: ERT is extensible in several ways. +* Other Testing Concepts:: Features not in ERT. + +@detailmenu + --- The Detailed Node Listing --- + +How to Run Tests + +* Running Tests Interactively:: Run tests in your current Emacs. +* Running Tests in Batch Mode:: Run tests in emacs -Q. +* Test Selectors:: Choose which tests to run. + +How to Write Tests + +* The @code{should} Macro:: A powerful way to express assertions. +* Expected Failures:: Tests for known bugs. +* Tests and Their Environment:: Don't depend on customizations; no side effects. +* Useful Techniques:: Some examples. + +How to Debug Tests + +* Understanding Explanations:: How ERT gives details on why an assertion failed. +* Interactive Debugging:: Tools available in the ERT results buffer. + +Extending ERT + +* Defining Explanation Functions:: Teach ERT about more predicates. +* Low-Level Functions for Working with Tests:: Use ERT's data for your purposes. + +Other Testing Concepts + +* Mocks and Stubs:: Stubbing out code that is irrelevant to the test. +* Fixtures and Test Suites:: How ERT differs from tools for other languages. + +@end detailmenu +@end menu + +@node Introduction, How to Run Tests, Top, Top +@chapter Introduction + +ERT allows you to define @emph{tests} in addition to functions, +macros, variables, and the other usual Lisp constructs. Tests are +simply Lisp code --- code that invokes other code and checks whether +it behaves as expected. + +ERT keeps track of the tests that are defined and provides convenient +commands to run them to verify whether the definitions that are +currently loaded in Emacs pass the tests. + +Some Lisp files have comments like the following (adapted from the +package @code{pp.el}): + +@lisp +;; (pp-to-string '(quote quote)) ; expected: "'quote" +;; (pp-to-string '((quote a) (quote b))) ; expected: "('a 'b)\n" +;; (pp-to-string '('a 'b)) ; same as above +@end lisp + +The code contained in these comments can be evaluated from time to +time to compare the output with the expected output. ERT formalizes +this and introduces a common convention, which simplifies Emacs +development, since programmers no longer have to manually find and +evaluate such comments. + +An ERT test definition equivalent to the above comments is this: + +@lisp +(ert-deftest pp-test-quote () + "Tests the rendering of `quote' symbols in `pp-to-string'." + (should (equal (pp-to-string '(quote quote)) "'quote")) + (should (equal (pp-to-string '((quote a) (quote b))) "('a 'b)\n")) + (should (equal (pp-to-string '('a 'b)) "('a 'b)\n"))) +@end lisp + +If you know @code{defun}, the syntax of @code{ert-deftest} should look +familiar: This example defines a test named @code{pp-test-quote} that +will pass if the three calls to @code{equal} all return true +(non-nil). + +@code{should} is a macro with the same meaning as @code{assert} but +better error reporting. @xref{The @code{should} Macro}. + +Each test should have a name that describes what functionality the +test tests. Test names can be chosen arbitrarily --- they are in a +namespace separate from functions and variables --- but should follow +the usual Emacs Lisp convention of having a prefix that indicates +which package they belong to. Test names are displayed by ERT when +reporting failures and can be used when selecting which tests to run. + +The empty parentheses @code{()} in the first line don't currently have +any meaning and are reserved for future extension. They also make +@code{ert-deftest}'s syntax more similar to @code{defun}. + +The docstring describes what feature this test tests. When running +tests interactively, the first line of the docstring is displayed for +tests that fail, so it is good if the first line makes sense on its +own. + +The body of a test can be arbitrary Lisp code. It should have as few +side effects as possible; each test should be written to clean up +after itself, leaving Emacs in the same state as it was before the +test. Tests should clean up even if they fail. @xref{Tests and Their +Environment}. + + +@node How to Run Tests, How to Write Tests, Introduction, Top +@chapter How to Run Tests + +You can run tests either in the Emacs you are working in, or on the +command line in a separate Emacs process in batch mode (i.e., with no +user interface). The former mode is convenient during interactive +development, the latter is useful to make sure that tests pass +independently of your customizations, allows tests to be invoked from +makefiles and scripts to be written that run tests in several +different Emacs versions. + +@menu +* Running Tests Interactively:: Run tests in your current Emacs. +* Running Tests in Batch Mode:: Run tests in emacs -Q. +* Test Selectors:: Choose which tests to run. +@end menu + + +@node Running Tests Interactively, Running Tests in Batch Mode, How to Run Tests, How to Run Tests +@section Running Tests Interactively + +You can run the tests that are currently defined in your Emacs with +the command @kbd{@kbd{M-x} ert @kbd{RET} t @kbd{RET}}. ERT will pop +up a new buffer, the ERT results buffer, showing the results of the +tests run. It looks like this: + +@example +Selector: t +Passed: 31 +Failed: 2 (2 unexpected) +Total: 33/33 + +Started at: 2008-09-11 08:39:25-0700 +Finished. +Finished at: 2008-09-11 08:39:27-0700 + +FF............................... + +F addition-test + (ert-test-failed + ((should + (= + (+ 1 2) + 4)) + :form + (= 3 4) + :value nil)) + +F list-test + (ert-test-failed + ((should + (equal + (list 'a 'b 'c) + '(a b d))) + :form + (equal + (a b c) + (a b d)) + :value nil :explanation + (list-elt 2 + (different-atoms c d)))) +@end example + +At the top, there is a summary of the results: We ran all tests in the +current Emacs (@code{Selector: t}), 31 of them passed, and 2 failed +unexpectedly. @xref{Expected Failures}, for an explanation of the +term @emph{unexpected} in this context. + +The line of dots and @code{F}s is a progress bar where each character +represents one test; it fills while the tests are running. A dot +means that the test passed, an @code{F} means that it failed. Below +the progress bar, ERT shows details about each test that had an +unexpected result. In the example above, there are two failures, both +due to failed @code{should} forms. @xref{Understanding Explanations}, +for more details. + +In the ERT results buffer, @kbd{TAB} and @kbd{S-TAB} cycle between +buttons. Each name of a function or macro in this buffer is a button; +moving point to it and typing @kbd{RET} jumps to its definition. + +Pressing @kbd{r} re-runs the test near point on its own. Pressing +@kbd{d} re-runs it with the debugger enabled. @kbd{.} jumps to the +definition of the test near point (@kbd{RET} has the same effect if +point is on the name of the test). On a failed test, @kbd{b} shows +the backtrace of the failure. + +@kbd{l} shows the list of @code{should} forms executed in the test. +If any messages were generated (with the Lisp function @code{message}) +in a test or any of the code that it invoked, @kbd{m} will show them. + +By default, long expressions in the failure details are abbreviated +using @code{print-length} and @code{print-level}. Pressing @kbd{L} +while point is on a test failure will increase the limits to show more +of the expression. + + +@node Running Tests in Batch Mode, Test Selectors, Running Tests Interactively, How to Run Tests +@section Running Tests in Batch Mode + +ERT supports automated invocations from the command line or from +scripts or makefiles. There are two functions for this purpose, +@code{ert-run-tests-batch} and @code{ert-run-tests-batch-and-exit}. +They can be used like this: + +@example +emacs -batch -L /path/to/ert -l ert.el -l my-tests.el -f ert-run-tests-batch-and-exit +@end example + +This command will start up Emacs in batch mode, load ERT, load +@code{my-tests.el}, and run all tests defined in it. It will exit +with a zero exit status if all tests passed, or nonzero if any tests +failed or if anything else went wrong. It will also print progress +messages and error diagnostics to standard output. + +You may need additional @code{-L} flags to ensure that +@code{my-tests.el} and all the files that it requires are on your +@code{load-path}. + + +@node Test Selectors, , Running Tests in Batch Mode, How to Run Tests +@section Test Selectors + +Functions like @code{ert} accept a @emph{test selector}, a Lisp +expression specifying a set of tests. Test selector syntax is similar +to Common Lisp's type specifier syntax: + +@itemize +@item @code{nil} selects no tests. +@item @code{t} selects all tests. +@item @code{:new} selects all tests that have not been run yet. +@item @code{:failed} and @code{:passed} select tests according to their most recent result. +@item @code{:expected}, @code{:unexpected} select tests according to their most recent result. +@item A string selects all tests that have a name that matches the string, a regexp. +@item A test selects that test. +@item A symbol selects the test that the symbol names. +@item @code{(member TESTS...)} selects TESTS, a list of tests or symbols naming tests. +@item @code{(eql TEST)} selects TEST, a test or a symbol naming a test. +@item @code{(and SELECTORS...)} selects the tests that match all SELECTORS. +@item @code{(or SELECTORS...)} selects the tests that match any SELECTOR. +@item @code{(not SELECTOR)} selects all tests that do not match SELECTOR. +@item @code{(tag TAG)} selects all tests that have TAG on their tags list. +@item @code{(satisfies PREDICATE)} Selects all tests that satisfy PREDICATE. +@end itemize + +Selectors that are frequently useful when selecting tests to run +include @code{t} to run all tests that are currently defined in Emacs, +@code{"^foo-"} to run all tests in package @code{foo} --- this assumes +that package @code{foo} uses the prefix @code{foo-} for its test names +---, result-based selectors such as @code{(or :new :unexpected)} to +run all tests that have either not run yet or that had an unexpected +result in the last run, and tag-based selectors such as @code{(not +(tag :causes-redisplay))} to run all tests that are not tagged +@code{:causes-redisplay}. + + +@node How to Write Tests, How to Debug Tests, How to Run Tests, Top +@chapter How to Write Tests + +ERT lets you define tests in the same way you define functions. You +can type @code{ert-deftest} forms in a buffer and evaluate them there +with @code{eval-defun} or @code{compile-defun}, or you can save the +file and load it, optionally byte-compiling it first. + +Just like @code{find-function} is only able to find where a function +was defined if the function was loaded from a file, ERT is only able +to find where a test was defined if the test was loaded from a file. + + +@menu +* The @code{should} Macro:: A powerful way to express assertions. +* Expected Failures:: Tests for known bugs. +* Tests and Their Environment:: Don't depend on customizations; no side effects. +* Useful Techniques:: Some examples. +@end menu + +@node The @code{should} Macro, Expected Failures, How to Write Tests, How to Write Tests +@section The @code{should} Macro + +Test bodies can include arbitrary code; but to be useful, they need to +have checks whether the code being tested (or @emph{code under test}) +does what it is supposed to do. The macro @code{should} is similar to +@code{assert} from the cl package, but analyzes its argument form and +records information that ERT can display to help debugging. + +This test definition + +@lisp +(ert-deftest addition-test () + (should (= (+ 1 2) 4))) +@end lisp + +will produce this output when run via @kbd{M-x ert}: + +@example +F addition-test + (ert-test-failed + ((should + (= + (+ 1 2) + 4)) + :form + (= 3 4) + :value nil)) +@end example + +In this example, @code{should} recorded the fact that (= (+ 1 2) 4) +reduced to (= 3 4) before it reduced to nil. When debugging why the +test failed, it helps to know that the function @code{+} returned 3 +here. ERT records the return value for any predicate called directly +within @code{should}. + +In addition to @code{should}, ERT provides @code{should-not}, which +checks that the predicate returns nil, and @code{should-error}, which +checks that the form called within it signals an error. An example +use of @code{should-error}: + +@lisp +(ert-deftest test-divide-by-zero () + (should-error (/ 1 0) + :type 'arith-error)) +@end lisp + +This checks that dividing one by zero signals an error of type +@code{arith-error}. The @code{:type} argument to @code{should-error} +is optional; if absent, any type of error is accepted. +@code{should-error} returns an error description of the error that was +signalled, to allow additional checks to be made. The error +description has the format @code{(ERROR-SYMBOL . DATA)}. + +There is no @code{should-not-error} macro since tests that signal an +error fail anyway, so @code{should-not-error} is effectively the +default. + +@xref{Understanding Explanations}, for more details on what +@code{should} reports. + + +@node Expected Failures, Tests and Their Environment, The @code{should} Macro, How to Write Tests +@section Expected Failures + +Some bugs are complicated to fix or not very important and are left as +@emph{known bugs}. If there is a test case that triggers the bug and +fails, ERT will alert you of this failure every time you run all +tests. For known bugs, this alert is a distraction. The way to +suppress it is to add @code{:expected-result :failed} to the test +definition: + +@lisp +(ert-deftest future-bug () + "Test `time-forward' with negative arguments. +Since this functionality isn't implemented yet, the test is known to fail." + :expected-result :failed + (time-forward -1)) +@end lisp + +ERT will still display a small @code{f} in the progress bar as a +reminder that there is a known bug, and will count the test as failed, +but it will be quiet about it otherwise. + +An alternative to marking the test as a known failure this way is to +delete the test. This is a good idea if there is no intent to fix it, +i.e., if the behavior that was formerly considered a bug has become an +accepted feature. + +In general, however, it can be useful to keep tests that are known to +fail. If someone wants to fix the bug, they will have a very good +starting point: an automated test case that reproduces the bug. This +makes it much easier to fix the bug, demonstrate that it is fixed, and +prevent future regressions. + +ERT displays the same kind of alerts for tests that pass unexpectedly +that it displays for unexpected failures. This way, if you make code +changes that happen to fix a bug that you weren't aware of, you will +know to remove the @code{:expected-result} clause of that test and +close the corresponding bug report, if any. + +Since @code{:expected-result} evaluates its argument when the test is +loaded, tests can be marked as known failures only on certain Emacs +versions, specific architectures, etc.: + +@lisp +(ert-deftest foo () + "A test that is expected to fail on Emacs 23 but succeed elsewhere." + :expected-result (if (string-match "GNU Emacs 23[.]" (emacs-version)) + :failed + :passed) + ...) +@end lisp + + +@node Tests and Their Environment, Useful Techniques, Expected Failures, How to Write Tests +@section Tests and Their Environment + +The outcome of running a test should not depend on the current state +of the environment, and each test should leave its environment in the +same state it found it in. In particular, a test should not depend on +any Emacs customization variables or hooks, and if it has to make any +changes to Emacs' state or state external to Emacs such as the file +system, it should undo these changes before it returns, regardless of +whether it passed or failed. + +Tests should not depend on the environment because any such +dependencies can make the test brittle or lead to failures that occur +only under certain circumstances and are hard to reproduce. Of +course, the code under test may have settings that affect its +behavior. In that case, it is best to make the test @code{let}-bind +all such settings variables to set up a specific configuration for the +duration of the test. The test can also set up a number of different +configurations and run the code under test with each. + +Tests that have side effects on their environment should restore it to +its original state because any side effects that persist after the +test can disrupt the workflow of the programmer running the tests. If +the code under test has side effects on Emacs' current state, such as +on the current buffer or window configuration, the test should create +a temporary buffer for the code to manipulate (using +@code{with-temp-buffer}), or save and restore the window configuration +(using @code{save-window-excursion}), respectively. For aspects of +the state that can not be preserved with such macros, cleanup should +be performed with @code{unwind-protect}, to ensure that the cleanup +occurs even if the test fails. + +An exception to this are messages that the code under test prints with +@code{message} and similar logging; tests should not bother restoring +the @code{*Message*} buffer to its original state. + +The above guidelines imply that tests should avoid calling highly +customizable commands such as @code{find-file}, except, of course, if +such commands are what they want to test. The exact behavior of +@code{find-file} depends on many settings such as +@code{find-file-wildcards}, @code{enable-local-variables}, and +@code{auto-mode-alist}. It is difficult to write a meaningful test if +its behavior can be affected by so many external factors. Also, +@code{find-file} has side effects that are hard to predict and thus +hard to undo: It may create a new buffer or may reuse an existing +buffer if one is already visiting the requested file; and it runs +@code{find-file-hook}, which can have arbitrary side effects. + +Instead, it is better to use lower-level mechanisms with simple and +predictable semantics like @code{with-temp-buffer}, @code{insert} or +@code{insert-file-contents-literally}, and activating the desired mode +by calling the corresponding function directly --- after binding the +hook variables to nil. This avoids the above problems. + + +@node Useful Techniques, , Tests and Their Environment, How to Write Tests +@section Useful Techniques when Writing Tests + +Testing simple functions that have no side effects and no dependencies +on their environment is easy. Such tests often look like this: + +@lisp +(ert-deftest ert-test-mismatch () + (should (eql (ert--mismatch "" "") nil)) + (should (eql (ert--mismatch "" "a") 0)) + (should (eql (ert--mismatch "a" "a") nil)) + (should (eql (ert--mismatch "ab" "a") 1)) + (should (eql (ert--mismatch "Aa" "aA") 0)) + (should (eql (ert--mismatch '(a b c) '(a b d)) 2))) +@end lisp + +This test calls the function @code{ert--mismatch} several times with +various combinations of arguments and compares the return value to the +expected return value. (Some programmers prefer @code{(should (eql +EXPECTED ACTUAL))} over the @code{(should (eql ACTUAL EXPECTED))} +shown here. ERT works either way.) + +Here's a more complicated test: + +@lisp +(ert-deftest ert-test-record-backtrace () + (let ((test (make-ert-test :body (lambda () (ert-fail "foo"))))) + (let ((result (ert-run-test test))) + (should (ert-test-failed-p result)) + (with-temp-buffer + (ert--print-backtrace (ert-test-failed-backtrace result)) + (goto-char (point-min)) + (end-of-line) + (let ((first-line (buffer-substring-no-properties (point-min) (point)))) + (should (equal first-line " signal(ert-test-failed (\"foo\"))"))))))) +@end lisp + +This test creates a test object using @code{make-ert-test} whose body +will immediately signal failure. It then runs that test and asserts +that it fails. Then, it creates a temporary buffer and invokes +@code{ert--print-backtrace} to print the backtrace of the failed test +to the current buffer. Finally, it extracts the first line from the +buffer and asserts that it matches what we expect. It uses +@code{buffer-substring-no-properties} and @code{equal} to ignore text +properties; for a test that takes properties into account, +@code{buffer-substring} and @code{ert-equal-including-properties} +could be used instead. + +The reason why this test only checks the first line of the backtrace +is that the remainder of the backtrace is dependent on ERT's internals +as well as whether the code is running interpreted or compiled. By +looking only at the first line, the test checks a useful property +--- that the backtrace correctly captures the call to @code{signal} that +results from the call to @code{ert-fail} --- without being brittle. + +This example also shows that writing tests is much easier if the code +under test was structured with testing in mind. + +For example, if @code{ert-run-test} accepted only symbols that name +tests rather than test objects, the test would need a name for the +failing test, which would have to be a temporary symbol generated with +@code{make-symbol}, to avoid side effects on Emacs' state. Choosing +the right interface for @code{ert-run-tests} allows the test to be +simpler. + +Similarly, if @code{ert--print-backtrace} printed the backtrace to a +buffer with a fixed name rather than the current buffer, it would be +much harder for the test to undo the side effect. Of course, some +code somewhere needs to pick the buffer name. But that logic is +independent of the logic that prints backtraces, and keeping them in +separate functions allows us to test them independently. + +A lot of code that you will encounter in Emacs was not written with +testing in mind. Sometimes, the easiest way to write tests for such +code is to restructure the code slightly to provide better interfaces +for testing. Usually, this makes the interfaces easier to use as +well. + + +@node How to Debug Tests, Extending ERT, How to Write Tests, Top +@chapter How to Debug Tests + +This section describes how to use ERT's features to understand why +a test failed. + + +@menu +* Understanding Explanations:: How ERT gives details on why an assertion failed. +* Interactive Debugging:: Tools available in the ERT results buffer. +@end menu + + +@node Understanding Explanations, Interactive Debugging, How to Debug Tests, How to Debug Tests +@section Understanding Explanations + +Failed @code{should} forms are reported like this: + +@example +F addition-test + (ert-test-failed + ((should + (= + (+ 1 2) + 4)) + :form + (= 3 4) + :value nil)) +@end example + +ERT shows what the @code{should} expression looked like and what +values its subexpressions had: The source code of the assertion was +@code{(should (= (+ 1 2) 4))}, which applied the function @code{=} to +the arguments @code{3} and @code{4}, resulting in the value +@code{nil}. In this case, the test is wrong; it should expect 3 +rather than 4. + +If a predicate like @code{equal} is used with @code{should}, ERT +provides a so-called @emph{explanation}: + +@example +F list-test + (ert-test-failed + ((should + (equal + (list 'a 'b 'c) + '(a b d))) + :form + (equal + (a b c) + (a b d)) + :value nil :explanation + (list-elt 2 + (different-atoms c d)))) +@end example + +In this case, the function @code{equal} was applied to the arguments +@code{(a b c)} and @code{(a b d)}. ERT's explanation shows that +the item at index 2 differs between the two lists; in one list, it is +the atom c, in the other, it is the atom d. + +In simple examples like the above, the explanation is unnecessary. +But in cases where the difference is not immediately apparent, it can +save time: + +@example +F test1 + (ert-test-failed + ((should + (equal x y)) + :form + (equal a a) + :value nil :explanation + (different-symbols-with-the-same-name a a))) +@end example + +ERT only provides explanations for predicates that have an explanation +function registered. @xref{Defining Explanation Functions}. + + +@node Interactive Debugging, , Understanding Explanations, How to Debug Tests +@section Interactive Debugging + +Debugging failed tests works essentially the same way as debugging any +other problems with Lisp code. Here are a few tricks specific to +tests: + +@itemize +@item Re-run the failed test a few times to see if it fails in the same way +each time. It's good to find out whether the behavior is +deterministic before spending any time looking for a cause. In the +ERT results buffer, @kbd{r} re-runs the selected test. + +@item Use @kbd{.} to jump to the source code of the test to find out what +exactly it does. Perhaps the test is broken rather than the code +under test. + +@item If the test contains a series of @code{should} forms and you can't +tell which one failed, use @kbd{l}, which shows you the list of all +@code{should} forms executed during the test before it failed. + +@item Use @kbd{b} to view the backtrace. You can also use @kbd{d} to re-run +the test with debugging enabled, this will enter the debugger and show +the backtrace as well; but the top few frames shown there will not be +relevant to you since they are ERT's own debugger hook. @kbd{b} +strips them out, so it is more convenient. + +@item If the test or the code under testing prints messages using +@code{message}, use @kbd{m} to see what messages it printed before it +failed. This can be useful to figure out how far it got. + +@item You can instrument tests for debugging the same way you instrument +@code{defun}s for debugging --- go to the source code of the test and +type @kbd{@kbd{C-u} @kbd{C-M-x}}. Then, go back to the ERT buffer and +re-run the test with @kbd{r} or @kbd{d}. + +@item If you have been editing and rearranging tests, it is possible that +ERT remembers an old test that you have since renamed or removed --- +renamings or removals of definitions in the source code leave around a +stray definition under the old name in the running process, this is a +common problem in Lisp. In such a situation, hit @kbd{D} to let ERT +forget about the obsolete test. +@end itemize + + +@node Extending ERT, Other Testing Concepts, How to Debug Tests, Top +@chapter Extending ERT + +There are several ways to add functionality to ERT. + +@menu +* Defining Explanation Functions:: Teach ERT about more predicates. +* Low-Level Functions for Working with Tests:: Use ERT's data for your purposes. +@end menu + + +@node Defining Explanation Functions, Low-Level Functions for Working with Tests, Extending ERT, Extending ERT +@section Defining Explanation Functions + +The explanation function for a predicate is a function that takes the +same arguments as the predicate and returns an @emph{explanation}. +The explanation should explain why the predicate, when invoked with +the arguments given to the explanation function, returns the value +that it returns. The explanation can be any object but should have a +comprehensible printed representation. If the return value of the +predicate needs no explanation for a given list of arguments, the +explanation function should return nil. + +To associate an explanation function with a predicate, add the +property @code{ert-explainer} to the symbol that names the predicate. +The value of the property should be the symbol that names the +explanation function. + + +@node Low-Level Functions for Working with Tests, , Defining Explanation Functions, Extending ERT +@section Low-Level Functions for Working with Tests + +Both @code{ert-run-tests-interactively} and @code{ert-run-tests-batch} +are implemented on top of the lower-level test handling code in the +sections named ``Facilities for running a single test'', ``Test +selectors'', and ``Facilities for running a whole set of tests''. + +If you want to write code that works with ERT tests, you should take a +look at this lower-level code. Symbols that start with @code{ert--} +are internal to ERT, those that start with @code{ert-} but not +@code{ert--} are meant to be usable by other code. But there is no +mature API yet. + +Contributions to ERT are welcome. + + +@node Other Testing Concepts, , Extending ERT, Top +@chapter Other Testing Concepts + +For information on mocks, stubs, fixtures, or test suites, see below. + + +@menu +* Mocks and Stubs:: Stubbing out code that is irrelevant to the test. +* Fixtures and Test Suites:: How ERT differs from tools for other languages. +@end menu + +@node Mocks and Stubs, Fixtures and Test Suites, Other Testing Concepts, Other Testing Concepts +@section Other Tools for Emacs Lisp + +Stubbing out functions or using so-called @emph{mocks} can make it +easier to write tests. See +@url{http://en.wikipedia.org/wiki/Mock_object} for an explanation of +the corresponding concepts in object-oriented languages. + +ERT does not have built-in support for mocks or stubs. The package +@code{el-mock} (see @url{http://www.emacswiki.org/emacs/el-mock.el}) +offers mocks for Emacs Lisp and can be used in conjunction with ERT. + + +@node Fixtures and Test Suites, , Mocks and Stubs, Other Testing Concepts +@section Fixtures and Test Suites + +In many ways, ERT is similar to frameworks for other languages like +SUnit or JUnit. However, two features commonly found in such +frameworks are notably absent from ERT: fixtures and test suites. + +Fixtures, as used e.g. in SUnit or JUnit, are mainly used to provide +an environment for a set of tests, and consist of set-up and tear-down +functions. + +While fixtures are a useful syntactic simplification in other +languages, this does not apply to Lisp, where higher-order functions +and `unwind-protect' are available. One way to implement and use a +fixture in ERT is + +@lisp +(defun my-fixture (body) + (unwind-protect + (progn [set up] + (funcall body)) + [tear down])) + +(ert-deftest my-test () + (my-fixture + (lambda () + [test code]))) +@end lisp + +(Another way would be a @code{with-my-fixture} macro.) This solves +the set-up and tear-down part, and additionally allows any test +to use any combination of fixtures, so it is more flexible than what +other tools typically allow. + +If the test needs access to the environment the fixture sets up, the +fixture can be modified to pass arguments to the body. + +These are well-known Lisp techniques. Special syntax for them could +be added but would provide only a minor simplification. + +(If you are interested in such syntax, note that splitting set-up and +tear-down into separate functions, like *Unit tools usually do, makes +it impossible to establish dynamic `let' bindings as part of the +fixture. So, blindly imitating the way fixtures are implemented in +other languages would be counter-productive in Lisp.) + +The purpose of test suites is to group related tests together. + +The most common use of this is to run just the tests for one +particular module. Since symbol prefixes are the usual way of +separating module namespaces in Emacs Lisp, test selectors already +solve this by allowing regexp matching on test names; e.g., the +selector "^ert-" selects ERT's self-tests. + +Other uses include grouping tests by their expected execution time to +run quick tests during interactive development and slow tests less +frequently. This can be achieved with the @code{:tag} argument to +@code{ert-deftest} and @code{tag} test selectors. + +@bye + +@c LocalWords: ERT Hagelberg Ohler JUnit namespace docstring ERT's +@c LocalWords: backtrace makefiles workflow backtraces API SUnit +@c LocalWords: subexpressions diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 25ba50d616..0ae6a0e7fa 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -8,8 +8,7 @@ @copying This manual is for Eshell, the Emacs shell. -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -369,6 +368,17 @@ eshell/ls is a compiled Lisp function in `em-ls.el' /bin/ls @end example +If you want to discard a given built-in command, you could declare an +alias, @ref{Aliases}. Eample: + +@example +~ $ which sudo +eshell/sudo is a compiled Lisp function in `em-unix.el' +~ $ alias sudo '*sudo $*' +~ $ which sudo +sudo is an alias, defined as "*sudo $*" +@end example + Some of the built-in commands have a special behaviour in Eshell: @table @code @@ -1004,7 +1014,3 @@ Since it keeps the cursor up where the command was invoked. @printindex ky @bye - -@ignore - arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01 -@end ignore diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index cf40bcce73..a68eda5002 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -12,8 +12,7 @@ EUDC is the Emacs Unified Directory Client, a common interface to directory servers using various protocols such as LDAP or the CCSO white pages directory system (PH/QI) -Copyright @copyright{} 1998, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1998, 2000-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -51,6 +50,7 @@ developing GNU and promoting software freedom.'' @ifnottex @node Top, Overview, (dir), (dir) +@top Emacs Unified Directory Client @comment node-name, next, previous, up @insertcopying diff --git a/doc/misc/faq.texi b/doc/misc/faq.texi index ae2d0867fd..7528abca58 100644 --- a/doc/misc/faq.texi +++ b/doc/misc/faq.texi @@ -4,16 +4,14 @@ @settitle GNU Emacs FAQ @c %**end of header -@c This is used in many places -@set VER 23.3.50 +@include emacsver.texi @c This file is maintained by Romain Francoise <[email protected]>. @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, 2008, -2009, 2010, 2011 Free Software Foundation, Inc.@* +Copyright @copyright{} 2001-2011 Free Software Foundation, Inc.@* Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 Reuven M. Lerner@* Copyright @copyright{} 1992, 1993 Steven Byrnes@* @@ -67,7 +65,7 @@ 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. -This is the version of the FAQ distributed with Emacs @value{VER}, and +This is the version of the FAQ distributed with Emacs @value{EMACSVER}, and mainly describes that version. Although there is some information on older versions, details about very old releases (now only of historical interest) have been removed. If you are interested in this, consult @@ -504,36 +502,13 @@ contain information in either the message header unsubscribe. @node Contacting the FSF -@section What is the current address of the FSF? -@cindex Snail mail address of the FSF -@cindex Postal address of the FSF +@section How do I contact the FSF? @cindex Contracting the FSF @cindex Free Software Foundation, contacting For up-to-date information, see @uref{http://www.fsf.org/about/contact.html, the FSF contact web-page}. - -@table @asis - -@item E-mail -info@@fsf.org - -@item Telephone -+1-617-542-5942 - -@item Fax -+1-617-542-2652 - -@item World Wide Web -@uref{http://www.fsf.org/} - -@item Postal address -Free Software Foundation@* -51 Franklin Street, Fifth Floor@* -Boston, MA 02110-1301@* -USA@* - -@end table +You can send general correspondence to @email{info@@fsf.org}. @cindex Ordering GNU software For details on how to order items directly from the FSF, see the @@ -1010,7 +985,7 @@ conventions}). @cindex Repository, Emacs @cindex Bazaar repository, Emacs -Emacs @value{VER} is the current version as of this writing. A version +Emacs @value{EMACSVER} is the current version as of this writing. A version number with two components (e.g. @samp{22.1}) indicates a released version; three components indicate a development version (e.g. @samp{23.0.50} is what will eventually become @samp{23.1}). @@ -1067,11 +1042,11 @@ Emacs now supports using both X displays and ttys in the same session @item Emacs can be started as a daemon in the background. -@cindex NeXTSTEP port +@cindex NeXTstep port @cindex GNUstep port @cindex Mac OS X Cocoa @item -There is a new NeXTSTEP port of Emacs. This supports GNUstep and Mac OS +There is a new NeXTstep port of Emacs. This supports GNUstep and Mac OS X (via the Cocoa libraries). The Carbon port of Emacs, which supported Mac OS X in Emacs 22, has been removed. @@ -3897,9 +3872,9 @@ command. @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 Emacs documentation): +You can represent modified function keys in vector format by adding +prefixes to the function key symbol. For example (from the Emacs +documentation): @lisp (global-set-key [?\C-x right] 'forward-page) @@ -4300,12 +4275,12 @@ file. Normally, Emacs expands aliases when you send the message. To expand them before this, use @kbd{M-x expand-mail-aliases}. -@c FIXME there should be an interactive rebuild command for this. @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-: (build-mail-aliases) @key{RET}} to -make Emacs reread @file{~/.mailrc}. +Emacs normally only reads the @file{.mailrc} file once per session, when +you start to compose your first mail message. If you edit the file +after this, you can use @kbd{M-x build-mail-aliases} to make Emacs +reread it. Prior to Emacs 24.1, this is not an interactive command, so +you must instead type @kbd{M-: (build-mail-aliases) @key{RET}}. @item If you like, you can expand mail aliases as abbrevs, as soon as you @@ -4479,7 +4454,3 @@ to the end of the @file{*Newsgroup*} buffer. @printindex cp @bye - -@ignore - arch-tag: fee0d62d-06cf-43d8-ac21-123408eaf10f -@end ignore diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 75a660f040..74cf3d630d 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -11,7 +11,7 @@ This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), which is a universal on-the-fly syntax checker for GNU Emacs. -Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2004-2011 Free Software Foundation, Inc. @quotation @@ -749,7 +749,3 @@ It just kills all the active syntax check processes before calling @printindex cp @bye - -@ignore - arch-tag: 9f0db077-5598-49ab-90b9-8df9248a63ec -@end ignore diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi index 1ac00e6ace..17c1d7feaf 100644 --- a/doc/misc/forms.texi +++ b/doc/misc/forms.texi @@ -18,8 +18,7 @@ @copying This file documents Forms mode, a form-editing major mode for GNU Emacs. -Copyright @copyright{} 1989, 1997, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1997, 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -976,7 +975,3 @@ Software Foundation. Thanks, Richard! @printindex cp @bye - -@ignore - arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed -@end ignore diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index 666a99fc48..ab9c0232d3 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -7,7 +7,7 @@ @syncodeindex pg cp @copying -Copyright @copyright{} 2004, 2005, 2007, 2008, 2009, 2010, 2011 Free Software +Copyright @copyright{} 2004-2005, 2007-2011 Free Software Foundation, Inc. @quotation @@ -288,14 +288,21 @@ Emacs repository might have been lost. With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus -CVS semi-automatically. These bug fixes are installed on the stable -branch and on the trunk. Basically the idea is that the gateway will -cause all common files in Emacs and Gnus v5-10 to be identical except -when there's a very good reason (e.g., the Gnus version string in Emacs -says @samp{5.11}, but the v5-10 version string remains @samp{5.10.x}). -Furthermore, all changes in these files in either Emacs or the v5-10 -branch will be installed into the Gnus CVS trunk, again except where -there's a good reason. +CVS semi-automatically. + +After Emacs moved to bzr and Gnus moved to git, Katsumi Yamaoka has +taken over the chore of keeping Emacs and Gnus in sync. In general, +changes made to one repository will usually be replicated in the other +within a few days. + +Basically the idea is that the gateway will cause all common files in +Emacs and Gnus v5-13 to be identical except when there's a very good +reason (e.g., the Gnus version string in Emacs says @samp{5.11}, but +the v5-13 version string remains @samp{5.13.x}). Furthermore, all +changes in these files in either Emacs or the v5-13 branch will be +installed into the Gnus git trunk, again except where there's a good +reason. + @c (typically so far the only exception has been that the changes @c already exist in the trunk in modified form). Because of this, when the next major version of Gnus will be included in @@ -311,9 +318,9 @@ If it's a file which is thought of as being outside of Gnus (e.g., the new @file{encrypt.el}), you should probably make the change in the Emacs tree, and it will show up in the Gnus tree a few days later. -If you don't have Emacs CVS access (or it's inconvenient), you can +If you don't have Emacs bzr access (or it's inconvenient), you can change such a file in the v5-10 branch, and it should propagate to Emacs -CVS -- however, it will get some extra scrutiny (by Miles) to see if the +bzr -- however, it will get some extra scrutiny (by Miles) to see if the changes are possibly controversial and need discussion on the mailing list. Many changes are obvious bug-fixes however, so often there won't be any problem. @@ -321,12 +328,12 @@ be any problem. @item If it's to a Gnus file, and it's important enough that it should be part of Emacs and the v5-10 branch, then you can make the change on the v5-10 -branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days +branch, and it will go into Emacs bzr and the Gnus git trunk (a few days later). The most prominent examples for such changes are bug-fixed including improvements on the documentation. If you know that there will be conflicts (perhaps because the affected -source code is different in v5-10 and the Gnus CVS trunk), then you can +source code is different in v5-10 and the Gnus git trunk), then you can install your change in both places, and when I try to sync them, there will be a conflict -- however, since in most such cases there would be a conflict @emph{anyway}, it's often easier for me to resolve it simply if @@ -338,9 +345,6 @@ For general Gnus development changes, of course you just make the change on the Gnus Git trunk and it goes into Emacs a few years later... :-) -With the new Git repository, we'll probably set up something to -automatically synchronize with Emacs when possible. CVS was much less -powerful for this kind of synchronization. @end itemize Of course in any case, if you just can't wait for me to sync your @@ -387,7 +391,3 @@ changed. @c mode: texinfo @c coding: iso-8859-1 @c End: - -@ignore - arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931 -@end ignore diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index d224d36fcd..e8e89ed2a3 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1,11 +1,7 @@ @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, 2008, -@c 2009, 2010, 2011 Free Software Foundation, Inc. -@c -@c Do not modify this file, it was generated from gnus-faq.xml, available from -@c <URL:http://my.gnus.org/FAQ/>. +@c Copyright (C) 1995, 2001-2011 Free Software Foundation, Inc. @c @setfilename gnus-faq.info @settitle Frequently Asked Questions @@ -40,20 +36,9 @@ @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)}. +@email{ding@@gnus.org, ding list}. @node FAQ - Changes @subheading Changes @@ -98,8 +83,6 @@ 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 @@ -107,7 +90,7 @@ 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. +misprints are the Gnus team's fault, sorry. @node FAQ 1 - Installation FAQ @subsection Installation FAQ @@ -1042,8 +1025,7 @@ 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} +faces. @node FAQ 4-12 @subsubheading Question 4.12 @@ -1414,7 +1396,7 @@ 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}. +@uref{http://www-sop.inria.fr/members/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 @@ -1987,7 +1969,7 @@ 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}. +and @uref{http://pyropus.ca/software/getmail/, 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 @@ -2141,12 +2123,8 @@ Which websites should I know? @subsubheading Answer -The two most important ones are the +The most important one is 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. @@ -2331,7 +2309,3 @@ NUA is an acronym for News User Agent, it's the program you use to read and write Usenet news. @end table - -@ignore -arch-tag: 64dc5692-edb4-4848-a965-7aa0181acbb8 -@end ignore diff --git a/doc/misc/gnus-news.el b/doc/misc/gnus-news.el index 5939773805..485e7ce464 100644 --- a/doc/misc/gnus-news.el +++ b/doc/misc/gnus-news.el @@ -1,5 +1,5 @@ ;;; gnus-news.el --- a hack to create GNUS-NEWS from texinfo source -;; Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +;; Copyright (C) 2004-2011 Free Software Foundation, Inc. ;; Author: Reiner Steib <[email protected]> ;; Keywords: tools @@ -26,8 +26,7 @@ (defvar gnus-news-header-disclaimer "GNUS NEWS -- history of user-visible changes. -Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, - 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright (C) 1999-2011 Free Software Foundation, Inc. See the end of the file for license conditions. Please send Gnus bug reports to [email protected]. @@ -113,5 +112,4 @@ paragraph-separate: \"[ ]*$\"\nend:\n") (insert gnus-news-trailer) (write-region (point-min) (point-max) outfile)))) -;; arch-tag: e23cdd27-eafd-4ba0-816f-98f5edb0dc29 ;;; gnus-news.el ends here diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi index 4e4480689a..62c1663508 100644 --- a/doc/misc/gnus-news.texi +++ b/doc/misc/gnus-news.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2011 Free Software Foundation, Inc. @c Permission is granted to anyone to make or distribute verbatim copies @c of this document as received, in any medium, provided that the @@ -18,6 +18,17 @@ @itemize @bullet +@item Supported Emacs versions +The following Emacs versions are supported by No Gnus: +@itemize @bullet + +@item Emacs 22 and up +@item XEmacs 21.4 +@item XEmacs 21.5 +@item SXEmacs + +@end itemize + @item Installation changes @itemize @bullet @@ -55,6 +66,13 @@ remove-installed-shadows}. @itemize @bullet +@item New version of @code{nnimap} + +@code{nnimap} has been reimplemented in a mostly-compatible way. See +the Gnus manual for a description of the new interface. In +particular, @code{nnimap-inbox} and the client side split method has +changed. + @item Gnus includes the Emacs Lisp @acronym{SASL} library. This provides a clean @acronym{API} to @acronym{SASL} mechanisms from @@ -87,6 +105,12 @@ EasyPG is included in Emacs 23 and available separately as well. @c ************************ @itemize @bullet + +@item +Symbols like @code{gcc-self} now has the same presedence rules in +@code{gnus-parameters} as other ``real'' variables: The last match +wins instead of the first match. + @item Old intermediate incoming mail files (@file{Incoming*}) are deleted after a couple of days, not immediately. @xref{Mail Source @@ -100,6 +124,9 @@ Customization}. @itemize @bullet +@item There's now only one variable that determines how @acronym{HTML} +is rendered: @code{mm-text-html-renderer}. + @item Gnus now supports sticky article buffers. Those are article buffers that are not reused when you select another article. @xref{Sticky Articles}. @@ -197,6 +224,9 @@ that are accessible from the article buffer. @item Changes in Message mode @itemize @bullet +@item Gnus now defaults to saving all outgoing messages in per-month +nnfolder archives. + @item Gnus now supports the ``hashcash'' client puzzle anti-spam mechanism. Use @code{(setq message-generate-hashcash t)} to enable. @xref{Hashcash}. @@ -230,6 +260,16 @@ of the "Whomever writes:" line. You need to set @code{message-insert-formatted-citation-line} as well. @end itemize +@item Changes in Browse Server mode + +@itemize @bullet +@item Gnus' sophisticated subscription methods are now available in +Browse Server buffers as well using the variable +@code{gnus-browse-subscribe-newsgroup-method}. + +@end itemize + + @item Changes in back ends @itemize @bullet @@ -320,12 +360,12 @@ be unchanged except that the marks will be removed when copying or moving articles to a group that has not turned auto-expire on. @xref{Expiring Mail}. +@item NoCeM support has been removed. + +@item Carpal mode has been removed. + @end itemize @end itemize @c gnus-news.texi ends here. - -@ignore - arch-tag: 872c7569-4340-4d73-9d1d-7826d9f94a51 -@end ignore diff --git a/doc/misc/gnus-overrides.texi b/doc/misc/gnus-overrides.texi new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/doc/misc/gnus-overrides.texi diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index a3b5ddde4a..a6b79237f0 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -1,5 +1,7 @@ \input texinfo +@include gnus-overrides.texi + @setfilename ../../info/gnus @settitle Gnus Manual @syncodeindex fn cp @@ -9,8 +11,7 @@ @documentencoding ISO-8859-1 @copying -Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -330,7 +331,12 @@ developing GNU and promoting software freedom.'' @titlepage +@ifset WEBHACKDEVEL +@title Gnus Manual (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title Gnus Manual +@end ifclear @author by Lars Magne Ingebrigtsen @page @@ -407,6 +413,7 @@ This manual corresponds to Gnus v5.13 * Composing Messages:: Information on sending mail and news. * Select Methods:: Gnus reads all messages from various select methods. * Scoring:: Assigning values to articles. +* Searching:: Mail and News search engines. * Various:: General purpose settings. * The End:: Farewell and goodbye. * Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History, Internals. @@ -428,7 +435,6 @@ Other related manuals 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. @@ -589,7 +595,7 @@ Article Treatment * 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 Display:: Display various stuff---X-Face, Picons, Smileys, Gravatars * Article Signature:: What is a signature? * Article Miscellanea:: Various other stuff. @@ -629,10 +635,10 @@ Select Methods * Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. +* Using IMAP:: Reading mail from @acronym{IMAP}. * 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. +* Other Sources:: Reading directories, files. * 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. @@ -695,43 +701,24 @@ 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. +* The Empty Backend:: The backend that never has any news. 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 @@ -806,6 +793,21 @@ Advanced Scoring * Advanced Scoring Examples:: What they look like. * Advanced Scoring Tips:: Getting the most out of it. +Searching + +* nnir:: Searching with various engines. +* nnmairix:: Searching with Mairix. + +nnir + +* What is nnir?:: What does nnir do. +* Basic Usage:: How to perform simple searches. +* Setting up nnir:: How to set up nnir. + +Setting up nnir + +* Associating Engines:: How to associate engines. + Various * Process/Prefix:: A convention used by many treatment commands. @@ -817,9 +819,7 @@ Various * 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. @@ -849,6 +849,7 @@ Image Enhancements * Smileys:: Show all those happy faces the way they were meant to be shown. * Picons:: How to display pictures of what you're reading. +* Gravatars:: Display the avatar of people you read. * XVarious:: Other XEmacsy Gnusey variables. Thwarting Email Spam @@ -980,7 +981,6 @@ 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? @@ -996,6 +996,15 @@ terminology section (@pxref{Terminology}). @section Finding the News @cindex finding news +First of all, you should know that there is a special buffer called +@code{*Server*} that lists all the servers Gnus knows about. You can +press @kbd{^} from the Group buffer to see it. In the Server buffer, +you can press @kbd{RET} on a defined server to see all the groups it +serves (subscribed or not!). You can also add or delete servers, edit +a foreign server's definition, agentize or de-agentize a server, and +do many other neat things. @xref{Server Buffer}. +@xref{Foreign Groups}. @xref{Agent Basics}. + @vindex gnus-select-method @c @head The @code{gnus-select-method} variable says where Gnus should look for @@ -1032,22 +1041,6 @@ Gnus will see whether @code{gnus-nntpserver-file} 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 @@ -1080,31 +1073,6 @@ several Gnus installations, but may slow down things a bit when fetching new articles. @xref{NNTP marks}, for more information. -@node The First Time -@section The First Time -@cindex first time usage - -If no startup files exist (@pxref{Startup Files}), Gnus will try to -determine what groups should be subscribed by default. - -@vindex gnus-default-subscribed-newsgroups -If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus -will subscribe you to just those groups in that list, leaving the rest -killed. Your system administrator should have set this variable to -something useful. - -Since she hasn't, Gnus will just subscribe you to a few arbitrarily -picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined -here as @dfn{whatever Lars thinks you should read}.) - -You'll also be subscribed to the Gnus documentation group, which should -help you with most common problems. - -If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just -use the normal functions for handling new groups, and not do anything -special. - - @node The Server is Down @section The Server is Down @cindex server errors @@ -1286,7 +1254,7 @@ parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe} topic parameter that looks like @example -"nnslashdot" +"nnml" @end example will mean that all groups that match that regex will be subscribed under @@ -1349,11 +1317,18 @@ 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{nnfolder}, @code{nnmbox}, @code{nnmh}, @code{nnimap}, and +@code{nnmaildir}) subscribed. If you don't like that, just set this +variable to @code{nil}. + +@vindex gnus-auto-subscribed-categories +As if that wasn't enough, @code{gnus-auto-subscribed-categories} also +allows you to specify that new groups should be subcribed based on the +category their select methods belong to. The default is @samp{(mail +post-mail)}, meaning that all new groups from mail-like backends +should be subscribed automatically. + +New groups that match these variables are subscribed using @code{gnus-subscribe-options-newsgroup-method}. @@ -1376,31 +1351,11 @@ 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. +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 @@ -1659,14 +1614,11 @@ of doing your job. Note that this variable is used before @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}. +@item gnus-use-backend-marks +@vindex gnus-use-backend-marks +If non-@code{nil}, Gnus will store article marks both in the +@file{.newsrc.eld} file and in the backends. This will slow down +group operation some. @end table @@ -1731,7 +1683,6 @@ long as Gnus is active. * Exiting Gnus:: Stop reading news and get some work done. * Group Topics:: A folding group mode divided into topics. * Non-ASCII Group Names:: Accessing groups of non-English names. -* Searching:: Mail search engines. * Misc Group Stuff:: Other stuff that you can to do. @end menu @@ -2018,8 +1969,7 @@ 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. +It will not be called when @code{gnus-visual} is @code{nil}. @node Group Maneuvering @@ -2247,6 +2197,12 @@ selected. @section Subscription Commands @cindex subscription +The following commands allow for managing your subscriptions in the +Group buffer. If you want to subscribe to many groups, it's probably +more convenient to go to the @ref{Server Buffer}, and choose the +server there using @kbd{RET} or @kbd{SPC}. Then you'll have the +commands listed in @ref{Browse Foreign Server} at hand. + @table @kbd @item S t @@ -2445,6 +2401,9 @@ one with the best 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. +This variable can also be a function. In that case, that function will +be called and the result will be used as value. + @vindex gnus-group-list-inactive-groups If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active @@ -2560,6 +2519,15 @@ the command to be executed. @section Foreign Groups @cindex foreign groups +If you recall how to subscribe to servers (@pxref{Finding the News}) +you will remember that @code{gnus-secondary-select-methods} and +@code{gnus-select-method} let you write a definition in Emacs Lisp of +what servers you want to see when you start up. The alternate +approach is to use foreign servers and groups. ``Foreign'' here means +they are not coming from the select methods. All foreign server +configuration and subscriptions are stored only in the +@file{~/.newsrc.eld} file. + 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 @@ -2633,27 +2601,6 @@ for a directory name (@code{gnus-group-make-directory-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 @@ -3373,6 +3320,11 @@ List all groups with cached articles (@code{gnus-group-list-cached}). @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-ticked +List all groups with ticked articles (@code{gnus-group-list-ticked}). + @item A / @kindex A / (Group) @findex gnus-group-list-limit @@ -3655,8 +3607,12 @@ Enter the current group (@code{gnus-browse-select-group}). @item u @kindex u (Browse) @findex gnus-browse-unsubscribe-current-group +@vindex gnus-browse-subscribe-newsgroup-method Unsubscribe to the current group, or, as will be the case here, -subscribe to it (@code{gnus-browse-unsubscribe-current-group}). +subscribe to it (@code{gnus-browse-unsubscribe-current-group}). You +can affect the way the new group is entered into the Group buffer +using the variable @code{gnus-browse-subscribe-newsgroup-method}. See +@pxref{Subscription Methods} for available options. @item l @itemx q @@ -4362,713 +4318,6 @@ names should be the same in both groups. Otherwise the Newsgroups header will be displayed incorrectly in the article buffer. -@node Searching -@section Searching - -@menu -* nnir:: Searching on IMAP, with swish, namazu, etc. -* nnmairix:: Searching maildir, MH or mbox with Mairix. -@end menu - -@cindex Searching - -FIXME: This node is a stub. - -FIXME: Add a brief overview of Gnus search capabilities. A brief -comparison of nnir, nnmairix, contrib/gnus-namazu would be nice -as well. - -FIXME: Explain difference to @ref{Searching for Articles}, add reference -and back-reference. - -@node nnir -@subsection nnir - -FIXME: As a first step, convert the commentary of @file{nnir} to texi. -@cindex nnir - -@node nnmairix -@subsection nnmairix - -@cindex mairix -@cindex nnmairix -This paragraph describes how to set up mairix and the back end -@code{nnmairix} for indexing and searching your mail from within -Gnus. Additionally, you can create permanent ``smart'' groups which are -bound to mairix searches and are automatically updated. - -@menu -* About mairix:: About the mairix mail search engine -* nnmairix requirements:: What you will need for using nnmairix -* What nnmairix does:: What does nnmairix actually do? -* Setting up mairix:: Set up your mairix installation -* Configuring nnmairix:: Set up the nnmairix back end -* nnmairix keyboard shortcuts:: List of available keyboard shortcuts -* Propagating marks:: How to propagate marks from nnmairix groups -* nnmairix tips and tricks:: Some tips, tricks and examples -* nnmairix caveats:: Some more stuff you might want to know -@end menu - -@c FIXME: The markup in this section might need improvement. -@c E.g. adding @samp, @var, @file, @command, etc. -@c Cf. (info "(texinfo)Indicating") - -@node About mairix -@subsubsection About mairix - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can -be found at -@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} - -Though mairix might not be as flexible as other search tools like -swish++ or namazu, which you can use via the @code{nnir} back end, it -has the prime advantage of being incredibly fast. On current systems, it -can easily search through headers and message bodies of thousands and -thousands of mails in well under a second. Building the database -necessary for searching might take a minute or two, but only has to be -done once fully. Afterwards, the updates are done incrementally and -therefore are really fast, too. Additionally, mairix is very easy to set -up. - -For maximum speed though, mairix should be used with mails stored in -@code{Maildir} or @code{MH} format (this includes the @code{nnml} back -end), although it also works with mbox. Mairix presents the search -results by populating a @emph{virtual} maildir/MH folder with symlinks -which point to the ``real'' message files (if mbox is used, copies are -made). Since mairix already presents search results in such a virtual -mail folder, it is very well suited for using it as an external program -for creating @emph{smart} mail folders, which represent certain mail -searches. This is similar to a Kiboze group (@pxref{Kibozed Groups}), -but much faster. - -@node nnmairix requirements -@subsubsection nnmairix requirements - -Mairix searches local mail---that means, mairix absolutely must have -direct access to your mail folders. If your mail resides on another -server (e.g. an @acronym{IMAP} server) and you happen to have shell -access, @code{nnmairix} supports running mairix remotely, e.g. via ssh. - -Additionally, @code{nnmairix} only supports the following Gnus back -ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use -one of these back ends for using @code{nnmairix}. Other back ends, like -@code{nnmbox}, @code{nnfolder} or @code{nnmh}, won't work. - -If you absolutely must use mbox and still want to use @code{nnmairix}, -you can set up a local @acronym{IMAP} server, which you then access via -@code{nnimap}. This is a rather massive setup for accessing some mbox -files, so just change to MH or Maildir already... However, if you're -really, really passionate about using mbox, you might want to look into -the package @file{mairix.el}, which comes with Emacs 23. - -@node What nnmairix does -@subsubsection What nnmairix does - -The back end @code{nnmairix} enables you to call mairix from within Gnus, -either to query mairix with a search term or to update the -database. While visiting a message in the summary buffer, you can use -several pre-defined shortcuts for calling mairix, e.g. to quickly -search for all mails from the sender of the current message or to -display the whole thread associated with the message, even if the -mails are in different folders. - -Additionally, you can create permanent @code{nnmairix} groups which are bound -to certain mairix searches. This way, you can easily create a group -containing mails from a certain sender, with a certain subject line or -even for one specific thread based on the Message-ID. If you check for -new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they -automatically update themselves by calling mairix. - -You might ask why you need @code{nnmairix} at all, since mairix already -creates the group, populates it with links to the mails so that you can -then access it with Gnus, right? Well, this @emph{might} work, but often -does not---at least not without problems. Most probably you will get -strange article counts, and sometimes you might see mails which Gnus -claims have already been canceled and are inaccessible. This is due to -the fact that Gnus isn't really amused when things are happening behind -its back. Another problem can be the mail back end itself, e.g. if you -use mairix with an @acronym{IMAP} server (I had Dovecot complaining -about corrupt index files when mairix changed the contents of the search -group). Using @code{nnmairix} should circumvent these problems. - -@code{nnmairix} is not really a mail back end---it's actually more like -a wrapper, sitting between a ``real'' mail back end where mairix stores -the searches and the Gnus front end. You can choose between three -different mail back ends for the mairix folders: @code{nnml}, -@code{nnmaildir} or @code{nnimap}. @code{nnmairix} will call the mairix -binary so that the search results are stored in folders named -@code{zz_mairix-<NAME>-<NUMBER>} on this mail back end, but it will -present these folders in the Gnus front end only with @code{<NAME>}. -You can use an existing mail back end where you already store your mail, -but if you're uncomfortable with @code{nnmairix} creating new mail -groups alongside your other mail, you can also create e.g. a new -@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then -make sure those servers do not accidentally receive your new mail -(@pxref{nnmairix caveats}). A special case exists if you want to use -mairix remotely on an IMAP server with @code{nnimap}---here the mairix -folders and your other mail must be on the same @code{nnimap} back end. - -@node Setting up mairix -@subsubsection Setting up mairix - -First: create a backup of your mail folders (@pxref{nnmairix caveats}). - -Setting up mairix is easy: simply create a @file{.mairixrc} file with -(at least) the following entries: - -@example -# Your Maildir/MH base folder -base=~/Maildir -@end example - -This is the base folder for your mails. All the following directories -are relative to this base folder. If you want to use @code{nnmairix} -with @code{nnimap}, this base directory has to point to the mail -directory where the @acronym{IMAP} server stores the mail folders! - -@example -maildir= ... your maildir folders which should be indexed ... -mh= ... your nnml/mh folders which should be indexed ... -mbox = ... your mbox files which should be indexed ... -@end example - -This specifies all your mail folders and mbox files (relative to the -base directory!) you want to index with mairix. Note that the -@code{nnml} back end saves mails in MH format, so you have to put those -directories in the @code{mh} line. See the example at the end of this -section and mairixrc's man-page for further details. - -@example -omit=zz_mairix-* -@end example - -@vindex nnmairix-group-prefix -This should make sure that you don't accidentally index the mairix -search results. You can change the prefix of these folders with the -variable @code{nnmairix-group-prefix}. - -@example -mformat= ... 'maildir' or 'mh' ... -database= ... location of database file ... -@end example - -The @code{format} setting specifies the output format for the mairix -search folder. Set this to @code{mh} if you want to access search results -with @code{nnml}. Otherwise choose @code{maildir}. - -To summarize, here is my shortened @file{.mairixrc} file as an example: - -@example -base=~/Maildir -maildir=.personal:.work:.logcheck:.sent -mh=../Mail/nnml/*... -mbox=../mboxmail/mailarchive_year* -mformat=maildir -omit=zz_mairix-* -database=~/.mairixdatabase -@end example - -In this case, the base directory is @file{~/Maildir}, where all my Maildir -folders are stored. As you can see, the folders are separated by -colons. If you wonder why every folder begins with a dot: this is -because I use Dovecot as @acronym{IMAP} server, which again uses -@code{Maildir++} folders. For testing nnmairix, I also have some -@code{nnml} mail, which is saved in @file{~/Mail/nnml}. Since this has -to be specified relative to the @code{base} directory, the @code{../Mail} -notation is needed. Note that the line ends in @code{*...}, which means -to recursively scan all files under this directory. Without the three -dots, the wildcard @code{*} will not work recursively. I also have some -old mbox files with archived mail lying around in @file{~/mboxmail}. -The other lines should be obvious. - -See the man page for @code{mairixrc} for details and further options, -especially regarding wildcard usage, which may be a little different -than you are used to. - -Now simply call @code{mairix} to create the index for the first time. -Note that this may take a few minutes, but every following index will do -the updates incrementally and hence is very fast. - -@node Configuring nnmairix -@subsubsection Configuring nnmairix - -In group mode, type @kbd{G b c} -(@code{nnmairix-create-server-and-default-group}). This will ask you for all -necessary information and create a @code{nnmairix} server as a foreign -server. You will have to specify the following: - -@itemize @bullet - -@item -The @strong{name} of the @code{nnmairix} server---choose whatever you -want. - -@item -The name of the @strong{back end server} where mairix should store its -searches. This must be a full server name, like @code{nnml:mymail}. -Just hit @kbd{TAB} to see the available servers. Currently, servers -which are accessed through @code{nnmaildir}, @code{nnimap} and -@code{nnml} are supported. As explained above, for locally stored -mails, this can be an existing server where you store your mails. -However, you can also create e.g. a new @code{nnmaildir} or @code{nnml} -server exclusively for @code{nnmairix} in your secondary select methods -(@pxref{Finding the News}). If you use a secondary @code{nnml} server -just for mairix, make sure that you explicitly set the server variable -@code{nnml-get-new-mail} to @code{nil}, or you might loose mail -(@pxref{nnmairix caveats}). If you want to use mairix remotely on an -@acronym{IMAP} server, you have to choose the corresponding -@code{nnimap} server here. - -@item -@vindex nnmairix-mairix-search-options -The @strong{command} to call the mairix binary. This will usually just -be @code{mairix}, but you can also choose something like @code{ssh -SERVER mairix} if you want to call mairix remotely, e.g. on your -@acronym{IMAP} server. If you want to add some default options to -mairix, you could do this here, but better use the variable -@code{nnmairix-mairix-search-options} instead. - -@item -The name of the @strong{default search group}. This will be the group -where all temporary mairix searches are stored, i.e. all searches which -are not bound to permanent @code{nnmairix} groups. Choose whatever you -like. - -@item -If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be -asked if you work with @strong{Maildir++}, i.e. with hidden maildir -folders (=beginning with a dot). For example, you have to answer -@samp{yes} here if you work with the Dovecot @acronym{IMAP} -server. Otherwise, you should answer @samp{no} here. - -@end itemize - -@node nnmairix keyboard shortcuts -@subsubsection nnmairix keyboard shortcuts - -In group mode: - -@table @kbd - -@item G b c -@kindex G b c (Group) -@findex nnmairix-create-server-and-default-group -Creates @code{nnmairix} server and default search group for this server -(@code{nnmairix-create-server-and-default-group}). You should have done -this by now (@pxref{Configuring nnmairix}). - -@item G b s -@kindex G b s (Group) -@findex nnmairix-search -Prompts for query which is then sent to the mairix binary. Search -results are put into the default search group which is automatically -displayed (@code{nnmairix-search}). - -@item G b m -@kindex G b m (Group) -@findex nnmairix-widget-search -Allows you to create a mairix search or a permanent group more -comfortably using graphical widgets, similar to a customization -group. Just try it to see how it works (@code{nnmairix-widget-search}). - -@item G b i -@kindex G b i (Group) -@findex nnmairix-search-interactive -Another command for creating a mairix query more comfortably, but uses -only the minibuffer (@code{nnmairix-search-interactive}). - -@item G b g -@kindex G b g (Group) -@findex nnmairix-create-search-group -Creates a permanent group which is associated with a search query -(@code{nnmairix-create-search-group}). The @code{nnmairix} back end -automatically calls mairix when you update this group with @kbd{g} or -@kbd{M-g}. - -@item G b q -@kindex G b q (Group) -@findex nnmairix-group-change-query-this-group -Changes the search query for the @code{nnmairix} group under cursor -(@code{nnmairix-group-change-query-this-group}). - -@item G b t -@kindex G b t (Group) -@findex nnmairix-group-toggle-threads-this-group -Toggles the 'threads' parameter for the @code{nnmairix} group under cursor, -i.e. if you want see the whole threads of the found messages -(@code{nnmairix-group-toggle-threads-this-group}). - -@item G b u -@kindex G b u (Group) -@findex nnmairix-update-database -@vindex nnmairix-mairix-update-options -Calls mairix binary for updating the database -(@code{nnmairix-update-database}). The default parameters are @code{-F} -and @code{-Q} for making this as fast as possible (see variable -@code{nnmairix-mairix-update-options} for defining these default -options). - -@item G b r -@kindex G b r (Group) -@findex nnmairix-group-toggle-readmarks-this-group -Keep articles in this @code{nnmairix} group always read or unread, or leave the -marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}). - -@item G b d -@kindex G b d (Group) -@findex nnmairix-group-delete-recreate-this-group -Recreate @code{nnmairix} group on the ``real'' mail back end -(@code{nnmairix-group-delete-recreate-this-group}). You can do this if -you always get wrong article counts with a @code{nnmairix} group. - -@item G b a -@kindex G b a (Group) -@findex nnmairix-group-toggle-allowfast-this-group -Toggles the @code{allow-fast} parameters for group under cursor -(@code{nnmairix-group-toggle-allowfast-this-group}). The default -behavior of @code{nnmairix} is to do a mairix search every time you -update or enter the group. With the @code{allow-fast} parameter set, -mairix will only be called when you explicitly update the group, but not -upon entering. This makes entering the group faster, but it may also -lead to dangling symlinks if something changed between updating and -entering the group which is not yet in the mairix database. - -@item G b p -@kindex G b p (Group) -@findex nnmairix-group-toggle-propmarks-this-group -Toggle marks propagation for this group -(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating -marks}). - -@item G b o -@kindex G b o (Group) -@findex nnmairix-propagate-marks -Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when -@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}. - -@end table - -In summary mode: - -@table @kbd - -@item $ m -@kindex $ m (Summary) -@findex nnmairix-widget-search-from-this-article -Allows you to create a mairix query or group based on the current -message using graphical widgets (same as @code{nnmairix-widget-search}) -(@code{nnmairix-widget-search-from-this-article}). - -@item $ g -@kindex $ g (Summary) -@findex nnmairix-create-search-group-from-message -Interactively creates a new search group with query based on the current -message, but uses the minibuffer instead of graphical widgets -(@code{nnmairix-create-search-group-from-message}). - -@item $ t -@kindex $ t (Summary) -@findex nnmairix-search-thread-this-article -Searches thread for the current article -(@code{nnmairix-search-thread-this-article}). This is effectively a -shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the -current article and enabled threads. - -@item $ f -@kindex $ f (Summary) -@findex nnmairix-search-from-this-article -Searches all messages from sender of the current article -(@code{nnmairix-search-from-this-article}). This is a shortcut for -calling @code{nnmairix-search} with @samp{f:From}. - -@item $ o -@kindex $ o (Summary) -@findex nnmairix-goto-original-article -(Only in @code{nnmairix} groups!) Tries determine the group this article -originally came from and displays the article in this group, so that -e.g. replying to this article the correct posting styles/group -parameters are applied (@code{nnmairix-goto-original-article}). This -function will use the registry if available, but can also parse the -article file name as a fallback method. - -@item $ u -@kindex $ u (Summary) -@findex nnmairix-remove-tick-mark-original-article -Remove possibly existing tick mark from original article -(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix -tips and tricks}). - -@end table - -@node Propagating marks -@subsubsection Propagating marks - -First of: you really need a patched mairix binary for using the marks -propagation feature efficiently. Otherwise, you would have to update -the mairix database all the time. You can get the patch at - -@uref{http://www.randomsample.de/mairix-maildir-patch.tar} - -You need the mairix v0.21 source code for this patch; everything else -is explained in the accompanied readme file. If you don't want to use -marks propagation, you don't have to apply these patches, but they also -fix some annoyances regarding changing maildir flags, so it might still -be useful to you. - -With the patched mairix binary, you can use @code{nnmairix} as an -alternative to mail splitting (@pxref{Fancy Mail Splitting}). For -example, instead of splitting all mails from @samp{david@@foobar.com} -into a group, you can simply create a search group with the query -@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are -all about: simply put everything in one mail folder and dynamically -create searches instead of splitting. This is more flexible, since you -can dynamically change your folders any time you want to. This also -implies that you will usually read your mails in the @code{nnmairix} -groups instead of your ``real'' mail groups. - -There is one problem, though: say you got a new mail from -@samp{david@@foobar.com}; it will now show up in two groups, the -``real'' group (your INBOX, for example) and in the @code{nnmairix} -search group (provided you have updated the mairix database). Now you -enter the @code{nnmairix} group and read the mail. The mail will be -marked as read, but only in the @code{nnmairix} group---in the ``real'' -mail group it will be still shown as unread. - -You could now catch up the mail group (@pxref{Group Data}), but this is -tedious and error prone, since you may overlook mails you don't have -created @code{nnmairix} groups for. Of course, you could first use -@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard -shortcuts}) and then read the mail in the original group, but that's -even more cumbersome. - -Clearly, the easiest way would be if marks could somehow be -automatically set for the original article. This is exactly what -@emph{marks propagation} is about. - -Marks propagation is deactivated by default. You can activate it for a -certain @code{nnmairix} group with -@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b -p}). This function will warn you if you try to use it with your default -search group; the reason is that the default search group is used for -temporary searches, and it's easy to accidentally propagate marks from -this group. However, you can ignore this warning if you really want to. - -With marks propagation enabled, all the marks you set in a @code{nnmairix} -group should now be propagated to the original article. For example, -you can now tick an article (by default with @kbd{!}) and this mark should -magically be set for the original article, too. - -A few more remarks which you may or may not want to know: - -@vindex nnmairix-propagate-marks-upon-close -Marks will not be set immediately, but only upon closing a group. This -not only makes marks propagation faster, it also avoids problems with -dangling symlinks when dealing with maildir files (since changing flags -will change the file name). You can also control when to propagate marks -via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for -details). - -Obviously, @code{nnmairix} will have to look up the original group for every -article you want to set marks for. If available, @code{nnmairix} will first use -the registry for determining the original group. The registry is very -fast, hence you should really, really enable the registry when using -marks propagation. If you don't have to worry about RAM and disc space, -set @code{gnus-registry-max-entries} to a large enough value; to be on -the safe side, choose roughly the amount of mails you index with mairix. - -@vindex nnmairix-only-use-registry -If you don't want to use the registry or the registry hasn't seen the -original article yet, @code{nnmairix} will use an additional mairix -search for determining the file name of the article. This, of course, is -way slower than the registry---if you set hundreds or even thousands of -marks this way, it might take some time. You can avoid this situation by -setting @code{nnmairix-only-use-registry} to t. - -Maybe you also want to propagate marks the other way round, i.e. if you -tick an article in a "real" mail group, you'd like to have the same -article in a @code{nnmairix} group ticked, too. For several good -reasons, this can only be done efficiently if you use maildir. To -immediately contradict myself, let me mention that it WON'T work with -@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and -not in the file name. Therefore, propagating marks to @code{nnmairix} -groups will usually only work if you use an IMAP server which uses -maildir as its file format. - -@vindex nnmairix-propagate-marks-to-nnmairix-groups -If you work with this setup, just set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what -happens. If you don't like what you see, just set it to @code{nil} again. One -problem might be that you get a wrong number of unread articles; this -usually happens when you delete or expire articles in the original -groups. When this happens, you can recreate the @code{nnmairix} group on the -back end using @kbd{G b d}. - -@node nnmairix tips and tricks -@subsubsection nnmairix tips and tricks - -@itemize -@item -Checking Mail - -@findex nnmairix-update-groups -I put all my important mail groups at group level 1. The mairix groups -have group level 5, so they do not get checked at start up (@pxref{Group -Levels}). - -I use the following to check for mails: - -@lisp -(defun my-check-mail-mairix-update (level) - (interactive "P") - ;; if no prefix given, set level=1 - (gnus-group-get-new-news (or level 1)) - (nnmairix-update-groups "mairixsearch" t t) - (gnus-group-list-groups)) - -(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update) -@end lisp - -Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix} -server. See the doc string for @code{nnmairix-update-groups} for -details. - -@item -Example: search group for ticked articles - -For example, you can create a group for all ticked articles, where the -articles always stay unread: - -Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use -@samp{F:f} as query and do not include threads. - -Now activate marks propagation for this group by using @kbd{G b p}. Then -activate the always-unread feature by using @kbd{G b r} twice. - -So far so good---but how do you remove the tick marks in the @code{nnmairix} -group? There are two options: You may simply use -@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove -tick marks from the original article. The other possibility is to set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above -comments about this option. If it works for you, the tick marks should -also exist in the @code{nnmairix} group and you can remove them as usual, -e.g. by marking an article as read. - -When you have removed a tick mark from the original article, this -article should vanish from the @code{nnmairix} group after you have updated the -mairix database and updated the group. Fortunately, there is a function -for doing exactly that: @code{nnmairix-update-groups}. See the previous code -snippet and the doc string for details. - -@item -Dealing with auto-subscription of mail groups - -As described before, all @code{nnmairix} groups are in fact stored on -the mail back end in the form @samp{zz_mairix-<NAME>-<NUMBER>}. You can -see them when you enter the back end server in the server buffer. You -should not subscribe these groups! Unfortunately, these groups will -usually get @emph{auto-subscribed} when you use @code{nnmaildir} or -@code{nnml}, i.e. you will suddenly see groups of the form -@samp{zz_mairix*} pop up in your group buffer. If this happens to you, -simply kill these groups with C-k. For avoiding this, turn off -auto-subscription completely by setting the variable -@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New -Groups}), or if you like to keep this feature use the following kludge -for turning it off for all groups beginning with @samp{zz_}: - -@lisp -(setq gnus-auto-subscribed-groups - "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*") -@end lisp - -@end itemize - -@node nnmairix caveats -@subsubsection nnmairix caveats - -@itemize -@item -You can create a secondary @code{nnml} server just for nnmairix, but then -you have to explicitly set the corresponding server variable -@code{nnml-get-new-mail} to @code{nil}. Otherwise, new mail might get -put into this secondary server (and would never show up again). Here's -an example server definition: - -@lisp -(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil)) -@end lisp - -(The @code{nnmaildir} back end also has a server variabe -@code{get-new-mail}, but its default value is @code{nil}, so you don't -have to explicitly set it if you use a @code{nnmaildir} server just for -mairix.) - -@item -If you use the Gnus registry: don't use the registry with -@code{nnmairix} groups (put them in -@code{gnus-registry-unfollowed-groups}). Be @emph{extra careful} if -you use @code{gnus-registry-split-fancy-with-parent}; mails which are -split into @code{nnmairix} groups are usually gone for good as soon as -you check the group for new mail (yes, it has happened to me...). - -@item -Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix} -groups (you shouldn't be able to, anyway). - -@item -If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize -@code{nnmairix} groups (though I have no idea what happens if you do). - -@item -mairix does only support us-ascii characters. - -@item -@code{nnmairix} uses a rather brute force method to force Gnus to -completely reread the group on the mail back end after mairix was -called---it simply deletes and re-creates the group on the mail -back end. So far, this has worked for me without any problems, and I -don't see how @code{nnmairix} could delete other mail groups than its -own, but anyway: you really should have a backup of your mail -folders. - -@item -All necessary information is stored in the group parameters -(@pxref{Group Parameters}). This has the advantage that no active file -is needed, but also implies that when you kill a @code{nnmairix} group, -it is gone for good. - -@item -@findex nnmairix-purge-old-groups -If you create and kill a lot of @code{nnmairix} groups, the -``zz_mairix-*'' groups will accumulate on the mail back end server. To -delete old groups which are no longer needed, call -@code{nnmairix-purge-old-groups}. Note that this assumes that you don't -save any ``real'' mail in folders of the form -@code{zz_mairix-<NAME>-<NUMBER>}. You can change the prefix of -@code{nnmairix} groups by changing the variable -@code{nnmairix-group-prefix}. - -@item -The following only applies if you @emph{don't} use the mentioned patch -for mairix (@pxref{Propagating marks}): - -A problem can occur when using @code{nnmairix} with maildir folders and -comes with the fact that maildir stores mail flags like @samp{Seen} or -@samp{Replied} by appending chars @samp{S} and @samp{R} to the message -file name, respectively. This implies that currently you would have to -update the mairix database not only when new mail arrives, but also when -mail flags are changing. The same applies to new mails which are indexed -while they are still in the @samp{new} folder but then get moved to -@samp{cur} when Gnus has seen the mail. If you don't update the database -after this has happened, a mairix query can lead to symlinks pointing to -non-existing files. In Gnus, these messages will usually appear with -``(none)'' entries in the header and can't be accessed. If this happens -to you, using @kbd{G b u} and updating the group will usually fix this. - -@end itemize - @node Misc Group Stuff @section Misc Group Stuff @@ -5249,37 +4498,6 @@ 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} @@ -6034,6 +5252,11 @@ threads. This variable can also be a number. In that case, center the window at the given number of lines from the top. +@item gnus-summary-stop-at-end-of-message +@vindex gnus-summary-stop-at-end-of-message +If non-@code{nil}, don't go to the next article when hitting +@kbd{SPC}, and you're at the end of the article. + @end table @@ -6239,9 +5462,10 @@ Scroll the current article one line backward @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. +given a prefix, show a completely ``raw'' article, just the way it +came from the server. If given a prefix twice (i.e., @kbd{C-u C-u +g'}), fetch the current article, but don't run any of the article +treatment functions. @cindex charset, view article with different charset If given a numerical prefix, you can do semi-manual charset stuff. @@ -6341,7 +5565,8 @@ present, that's used instead. @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. +the process/prefix convention, but only uses the headers from the +first article to determine the recipients. @item S v @kindex S v (Summary) @@ -6405,8 +5630,6 @@ 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, @@ -6744,6 +5967,12 @@ Presumably, you want to use the demon for sending due delayed articles. Just don't forget to set that up :-) @end table +When delaying an article with @kbd{C-c C-j}, Message mode will +automatically add a @code{"Date"} header with the current time. In +many cases you probably want the @code{"Date"} header to reflect the +time the message is sent instead. To do this, you have to delete +@code{Date} from @code{message-draft-headers}. + @node Marking Articles @section Marking Articles @@ -6852,10 +6081,6 @@ Marked as read by a catchup (@code{gnus-catchup-mark}). @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 @@ -7826,7 +7051,7 @@ 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. +web-based 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 @@ -8115,7 +7340,9 @@ predicate functions include @code{gnus-thread-sort-by-number}, 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. +normally done by looking only at the roots of each thread. Exceptions +to this rule are @code{gnus-thread-sort-by-most-recent-number} and +@code{gnus-thread-sort-by-most-recent-date}. If you use more than one function, the primary sort key should be the last function in the list. You should probably always include @@ -8262,6 +7489,16 @@ 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-async-post-fetch-function +@findex gnus-html-prefetch-images +After an article has been prefetched, this +@code{gnus-async-post-fetch-function} will be called. The buffer will +be narrowed to the region of the article that was fetched. A useful +value would be @code{gnus-html-prefetch-images}, which will prefetch +and store images referenced in the article, so that you don't have to +wait for them to be fetched when you read the article. This is useful +for @acronym{HTML} messages that have external images. + @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 @@ -9266,7 +8503,8 @@ these articles easier. * 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 Display:: Display various stuff: + X-Face, Picons, Gravatars, Smileys. * Article Signature:: What is a signature? * Article Miscellanea:: Various other stuff. @end menu @@ -9527,6 +8765,14 @@ signature should be removed, or other symbol, meaning that the corresponding regular expression in @code{gnus-article-banner-alist} is used. +For instance: + +@lisp +(setq gnus-article-banner-alist + ((googleGroups . + "^\n*--~--~---------\\(.+\n\\)+"))) +@end lisp + 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}. @@ -9730,6 +8976,17 @@ 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 U +@kindex W U (Summary) +@findex gnus-article-treat-non-ascii +@cindex Unicode +@cindex Non-@acronym{ASCII} +Translate many non-@acronym{ASCII} characters into their +@acronym{ASCII} equivalents (@code{gnus-article-treat-non-ascii}). +This is mostly useful if you're on a terminal that has a limited font +and does't show accented characters, ``advanced'' punctuation, and the +like. For instance, @samp{�} is tranlated into @samp{>>}, and so on. + @item W Y f @kindex W Y f (Summary) @findex gnus-article-outlook-deuglify-article @@ -9845,15 +9102,18 @@ 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: +@acronym{HTML}. Pre-defined functions you can use include: @table @code +@item shr +Use Gnus simple html renderer. + +@item gnus-w3m +Use Gnus rendered based on w3m. + @item w3 Use Emacs/W3. @@ -10118,18 +9378,6 @@ string is invalid. 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 @@ -10202,14 +9450,6 @@ Related variables and functions include @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 @@ -10266,26 +9506,21 @@ 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 +Date: 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. +This line is updated continually by default. The frequency (in +seconds) is controlled by the @code{gnus-article-update-date-headers} +variable. -If you want to have this line updated continually, you can put +If you wish to switch updating off, say: +@vindex gnus-article-update-date-headers @lisp -(gnus-start-date-timer) +(setq gnus-article-update-date-headers nil) @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. +in your @file{~/.gnus.el} file. @item W T o @kindex W T o (Summary) @@ -10307,6 +9542,7 @@ preferred format automatically. @cindex picons @cindex x-face @cindex smileys +@cindex gravatars These commands add various frivolous display gimmicks to the article buffer in Emacs versions that support them. @@ -10323,6 +9559,9 @@ 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}). +Gravatars reside on-line and are fetched from +@uref{http://www.gravatar.com/} (@pxref{Gravatars}). + All these functions are toggles---if the elements already exist, they'll be removed. @@ -10361,12 +9600,31 @@ Piconify all mail headers (i. e., @code{Cc}, @code{To}) Piconify all news headers (i. e., @code{Newsgroups} and @code{Followup-To}) (@code{gnus-treat-newsgroups-picon}). +@item W D g +@kindex W D g (Summary) +@findex gnus-treat-from-gravatar +Gravatarify the @code{From} header (@code{gnus-treat-from-gravatar}). + +@item W D h +@kindex W D h (Summary) +@findex gnus-treat-mail-gravatar +Gravatarify all mail headers (i. e., @code{Cc}, @code{To}) +(@code{gnus-treat-from-gravatar}). + @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}). +@item W D W +@kindex W D W (Summary) +@findex gnus-html-show-images +If you're reading an @acronym{HTML} article rendered with +@code{gnus-article-html}, then you can insert any blocked images in +the buffer with this command. +(@code{gnus-html-show-images}). + @end table @@ -10506,17 +9764,24 @@ the same manner: @kindex K H (Summary) @findex gnus-article-browse-html-article View @samp{text/html} parts of the current article with a WWW browser. -The message header is added to the beginning of every html part unless -the prefix argument is given. +Inline images embedded in a message using the @code{cid} scheme, as they +are generally considered to be safe, will be processed properly. The +message header is added to the beginning of every @acronym{HTML} part +unless the prefix argument is given. -Warning: Spammers use links to images in HTML articles to verify whether -you have read the message. As this command passes the @acronym{HTML} -content to the browser without eliminating these ``web bugs'' you should -only use it for mails from trusted senders. +Warning: Spammers use links to images (using the @code{http} scheme) in +@acronym{HTML} articles to verify whether you have read the message. As +this command passes the @acronym{HTML} content to the browser without +eliminating these ``web bugs'' you should only use it for mails from +trusted senders. If you always want to display @acronym{HTML} parts in the browser, set @code{mm-text-html-renderer} to @code{nil}. +This command creates temporary files to pass @acronym{HTML} contents +including images if any to the browser, and deletes them when exiting +the group (if you want). + @item K b @kindex K b (Summary) Make all the @acronym{MIME} parts have buttons in front of them. This is @@ -10831,6 +10096,16 @@ Generate and print a PostScript image of the article buffer be run just before printing the buffer. An alternative way to print article is to use Muttprint (@pxref{Saving Articles}). +@item A C +@vindex gnus-fetch-partial-articles +@findex gnus-summary-show-complete-article +If @code{<backend>-fetch-partial-articles} is non-@code{nil}, Gnus will +fetch partial articles, if the backend it fetches them from supports +it. Currently only @code{nnimap} does. If you're looking at a +partial article, and want to see the complete article instead, then +the @kbd{A C} command (@code{gnus-summary-show-complete-article}) will +do so. + @end table @@ -11008,9 +10283,12 @@ 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. +group. @code{nnmh} does not support this at all. +Fortunately, the special @code{nnregistry} back end is able to locate +articles in any groups, regardless of their back end (@pxref{Registry +Article Refer Method, fetching by @code{Message-ID} using the +registry}). @node Alternative Approaches @section Alternative Approaches @@ -11554,18 +10832,6 @@ sieve. @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 @@ -11891,8 +11157,7 @@ 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}). +heinous crime. Remember: Cross-posting is kinda ok, but posting the same article separately to several groups is not. Massive cross-posting (aka. @@ -12023,7 +11288,7 @@ To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to install an OpenPGP implementation such as GnuPG. The Lisp interface to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG, epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg, -PGG Manual}), Mailcrypt, and gpg.el are also supported. +PGG Manual}), and Mailcrypt are also supported. @item To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6 @@ -12062,7 +11327,7 @@ public-key matching the @samp{From:} header as the recipient; @vindex mml1991-use Symbol indicating elisp interface to OpenPGP implementation for @acronym{PGP} messages. The default is @code{epg}, but @code{pgg}, -@code{mailcrypt}, and @code{gpg} are also supported although +and @code{mailcrypt} are also supported although deprecated. By default, Gnus uses the first available interface in this order. @@ -12070,7 +11335,7 @@ this order. @vindex mml2015-use Symbol indicating elisp interface to OpenPGP implementation for @acronym{PGP/MIME} messages. The default is @code{epg}, but -@code{pgg}, @code{mailcrypt}, and @code{gpg} are also supported +@code{pgg}, and @code{mailcrypt} are also supported although deprecated. By default, Gnus uses the first available interface in this order. @@ -12170,6 +11435,7 @@ tell Gnus otherwise. @menu * Hiding Headers:: Deciding what headers should be displayed. * Using MIME:: Pushing articles through @acronym{MIME} before reading them. +* HTML:: Reading @acronym{HTML} messages. * Customizing Articles:: Tailoring the look of the articles. * Article Keymap:: Keystrokes available in the article buffer. * Misc Article:: Other stuff. @@ -12466,6 +11732,75 @@ Any similarity to real events and people is purely coincidental. Ahem. Also @pxref{MIME Commands}. +@node HTML +@section @acronym{HTML} +@cindex @acronym{HTML} + +If you have @code{w3m} installed on your system, Gnus can display +@acronym{HTML} articles in the article buffer. There are many Gnus +add-ons for doing this, using various approaches, but there's one +(sort of) built-in method that's used by default. + +For a complete overview, consult @xref{Display Customization, +,Display Customization, emacs-mime, The Emacs MIME Manual}. This +section only describes the default method. + +@table @code +@item mm-text-html-renderer +@vindex mm-text-html-renderer +If set to @code{gnus-article-html}, Gnus will use the built-in method, +that's based on @code{w3m}. + +@item gnus-blocked-images +@vindex gnus-blocked-images +External images that have @acronym{URL}s that match this regexp won't +be fetched and displayed. For instance, do block all @acronym{URL}s +that have the string ``ads'' in them, do the following: + +@lisp +(setq gnus-blocked-images "ads") +@end lisp + +This can also be a function to be evaluated. If so, it will be +called with the group name as the parameter. The default value is +@code{gnus-block-private-groups}, which will return @samp{"."} for +anything that isn't a newsgroup. This means that no external images +will be fetched as a result of reading mail, so that nobody can use +web bugs (and the like) to track whether you've read email. + +Also @pxref{Misc Article} for @code{gnus-inhibit-images}. + +@item gnus-html-cache-directory +@vindex gnus-html-cache-directory +Gnus will download and cache images according to how +@code{gnus-blocked-images} is set. These images will be stored in +this directory. + +@item gnus-html-cache-size +@vindex gnus-html-cache-size +When @code{gnus-html-cache-size} bytes have been used in that +directory, the oldest files will be deleted. The default is 500MB. + +@item gnus-html-frame-width +@vindex gnus-html-frame-width +The width to use when rendering HTML. The default is 70. + +@item gnus-max-image-proportion +@vindex gnus-max-image-proportion +How big pictures displayed are in relation to the window they're in. +A value of 0.7 (the default) means that they are allowed to take up +70% of the width and height of the window. If they are larger than +this, and Emacs supports it, then the images will be rescaled down to +fit these criteria. + +@end table + +To use this, make sure that you have @code{w3m} and @code{curl} +installed. If you have, then Gnus should display @acronym{HTML} +automatically. + + + @node Customizing Articles @section Customizing Articles @cindex article customization @@ -12551,16 +11886,12 @@ controlling variable is a predicate list, as described above. @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-date @vindex gnus-treat-from-picon @vindex gnus-treat-mail-picon @vindex gnus-treat-newsgroups-picon +@vindex gnus-treat-from-gravatar +@vindex gnus-treat-mail-gravatar @vindex gnus-treat-display-smileys @vindex gnus-treat-body-boundary @vindex gnus-treat-display-x-face @@ -12579,7 +11910,6 @@ controlling variable is a predicate list, as described above. @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 @@ -12611,13 +11941,39 @@ possible but those listed are probably sufficient for most people. @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) +@item gnus-treat-date (head) + +This will transform/add date headers according to the +@code{gnus-article-date-headers} variable. This is a list of Date +headers to display. The formats available are: + +@table @code +@item ut +Universal time, aka GMT, aka ZULU. + +@item local +The user's local time zone. + +@item english +A semi-readable English sentence. + +@item lapsed +The time elapsed since the message was posted. + +@item combined-lapsed +Both the original date header and a (shortened) elapsed time. + +@item original +The original date header. + +@item iso8601 +ISO8601 format, i.e., ``2010-11-23T22:05:21''. + +@item user-defined +A format done according to the @code{gnus-article-time-format} +variable. + +@end table @xref{Article Date}. @@ -12627,6 +11983,11 @@ possible but those listed are probably sufficient for most people. @xref{Picons}. +@item gnus-treat-from-gravatar (head) +@item gnus-treat-mail-gravatar (head) + +@xref{Gravatars}. + @item gnus-treat-display-smileys (t, integer) @item gnus-treat-body-boundary (head) @@ -12681,8 +12042,6 @@ is controlled by @code{gnus-body-boundary-delimiter}. @vindex gnus-treat-play-sounds @item gnus-treat-play-sounds -@vindex gnus-treat-translate -@item gnus-treat-translate @item gnus-treat-ansi-sequences (t) @vindex gnus-treat-x-pgp-sig @item gnus-treat-x-pgp-sig (head) @@ -12812,6 +12171,11 @@ 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. +@item gnus-widen-article-window +@cindex gnus-widen-article-window +If non-@code{nil}, selecting the article buffer with the @kbd{h} +command will ``widen'' the article window to take the entire frame. + @vindex gnus-article-decode-hook @item gnus-article-decode-hook @cindex @acronym{MIME} @@ -12906,6 +12270,15 @@ for how to compose such messages. This requires @uref{http://www.gnu.org/software/libidn/, GNU Libidn}, and this variable is only enabled if you have installed it. +@vindex gnus-inhibit-images +@item gnus-inhibit-images +If this is non-@code{nil}, inhibit displaying of images inline in the +article body. It is effective to images that are in articles as +@acronym{MIME} parts, and images in @acronym{HTML} articles rendered +when @code{mm-text-html-renderer} (@pxref{Display Customization, +,Display Customization, emacs-mime, The Emacs MIME Manual}) is +@code{shr} or @code{gnus-w3m}. + @end table @@ -13276,9 +12649,6 @@ messages in one file per month: (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 @@ -13290,27 +12660,7 @@ 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. @@ -13405,14 +12755,20 @@ 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. +The attribute value can be a string, 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. + +In the case of a string value, if the @code{match} is a regular +expression, a @samp{gnus-match-substitute-replacement} is proceed on +the value to replace the positional parameters @samp{\@var{n}} by the +corresponding parenthetical matches (see @xref{Replacing the Text that +Matched, , Text Replacement, elisp, The Emacs Lisp Reference Manual}.) @vindex message-reply-headers @@ -13543,6 +12899,9 @@ 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. +Finally, if you want to delete a draft, use the normal @kbd{B DEL} +command (@pxref{Mail Group Commands}). + @node Rejected Articles @section Rejected Articles @@ -13670,10 +13029,10 @@ The different methods all have their peculiarities, of course. @menu * Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. +* Using IMAP:: Reading mail from @acronym{IMAP}. * 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. +* Other Sources:: Reading directories, files. * 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. @@ -13785,6 +13144,11 @@ Add a new server (@code{gnus-server-add-server}). @findex gnus-server-edit-server Edit a server (@code{gnus-server-edit-server}). +@item S +@kindex S (Server) +@findex gnus-server-show-server +Show the definition of a server (@code{gnus-server-show-server}). + @item SPACE @kindex SPACE (Server) @findex gnus-server-read-server @@ -13840,6 +13204,9 @@ hence getting a correct total article count. @end table +Some more commands for closing, disabling, and re-opening servers are +listed in @ref{Unavailable Servers}. + @node Example Methods @subsection Example Methods @@ -14085,6 +13452,14 @@ Close the connections to all servers in the buffer Remove all marks to whether Gnus was denied connection from any servers (@code{gnus-server-remove-denials}). +@item c +@kindex c (Server) +@findex gnus-server-copy-server +Copy a server and give it a new name +(@code{gnus-server-copy-server}). This can be useful if you have a +complex method definition, and want to use the same definition towards +a different (physical) server. + @item L @kindex L (Server) @findex gnus-server-offline-server @@ -14356,6 +13731,12 @@ inhibit Gnus to add a @code{Message-ID} header, you could say: Note that not all servers support the recommended ID. This works for INN versions 2.3.0 and later, for instance. +@item nntp-server-list-active-group +If @code{nil}, then always use @samp{GROUP} instead of @samp{LIST +ACTIVE}. This is usually slower, but on misconfigured servers that +don't update their active files often, this can help. + + @end table @menu @@ -14379,7 +13760,12 @@ functions is also affected by commonly understood variables @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. +remote system. If both Emacs and the server supports it, the +connection will be upgraded to an encrypted @acronym{STARTTLS} +connection automatically. + +@item network-only +The same as the above, but don't do automatic @acronym{STARTTLS} upgrades. @findex nntp-open-tls-stream @item nntp-open-tls-stream @@ -14749,6 +14135,156 @@ there. @end table +@node Using IMAP +@section Using IMAP +@cindex imap + +The most popular mail backend is probably @code{nnimap}, which +provides access to @acronym{IMAP} servers. @acronym{IMAP} servers +store mail remotely, so the client doesn't store anything locally. +This means that it's a convenient choice when you're reading your mail +from different locations, or with different user agents. + +@menu +* Connecting to an IMAP Server:: Getting started with @acronym{IMAP}. +* Customizing the IMAP Connection:: Variables for @acronym{IMAP} connection. +* Client-Side IMAP Splitting:: Put mail in the correct mail box. +@end menu + + +@node Connecting to an IMAP Server +@subsection Connecting to an IMAP Server + +Connecting to an @acronym{IMAP} can be very easy. Type @kbd{B} in the +group buffer, or (if your primary interest is reading email), say +something like: + +@example +(setq gnus-select-method + '(nnimap "imap.gmail.com")) +@end example + +You'll be prompted for a user name and password. If you grow tired of +that, then add the following to your @file{~/.authinfo} file: + +@example +machine imap.gmail.com login <username> password <password> port imap +@end example + +That should basically be it for most users. + + +@node Customizing the IMAP Connection +@subsection Customizing the IMAP Connection + +Here's an example method that's more complex: + +@example +(nnimap "imap.gmail.com" + (nnimap-inbox "INBOX") + (nnimap-split-methods default) + (nnimap-expunge t) + (nnimap-stream ssl)) +@end example + +@table @code +@item nnimap-address +The address of the server, like @samp{imap.gmail.com}. + +@item nnimap-server-port +If the server uses a non-standard port, that can be specified here. A +typical port would be @code{"imap"} or @code{"imaps"}. + +@item nnimap-stream +How @code{nnimap} should connect to the server. Possible values are: + +@table @code +@item undecided +This is the default, and this first tries the @code{ssl} setting, and +then tries the @code{network} setting. + +@item ssl +This uses standard @acronym{TLS}/@acronym{SSL} connections. + +@item network +Non-encrypted and unsafe straight socket connection, but will upgrade +to encrypted @acronym{STARTTLS} if both Emacs and the server +supports it. + +@item starttls +Encrypted @acronym{STARTTLS} over the normal @acronym{IMAP} port. + +@item shell +If you need to tunnel via other systems to connect to the server, you +can use this option, and customize @code{nnimap-shell-program} to be +what you need. + +@end table + +@item nnimap-authenticator +Some @acronym{IMAP} servers allow anonymous logins. In that case, +this should be set to @code{anonymous}. + +@item nnimap-expunge +If non-@code{nil}, expunge articles after deleting them. This is always done +if the server supports UID EXPUNGE, but it's not done by default on +servers that doesn't support that command. + +@item nnimap-streaming +Virtually all @code{IMAP} server support fast streaming of data. If +you have problems connecting to the server, try setting this to @code{nil}. + +@item nnimap-fetch-partial-articles +If non-@code{nil}, fetch partial articles from the server. If set to +a string, then it's interpreted as a regexp, and parts that have +matching types will be fetched. For instance, @samp{"text/"} will +fetch all textual parts, while leaving the rest on the server. + +@end table + + +@node Client-Side IMAP Splitting +@subsection Client-Side IMAP Splitting + +Many people prefer to do the sorting/splitting of mail into their mail +boxes on the @acronym{IMAP} server. That way they don't have to +download the mail they're not all that interested in. + +If you do want to do client-side mail splitting, then the following +variables are relevant: + +@table @code +@item nnimap-inbox +This is the @acronym{IMAP} mail box that will be scanned for new mail. + +@item nnimap-split-methods +Uses the same syntax as @code{nnmail-split-methods} (@pxref{Splitting +Mail}), except the symbol @code{default}, which means that it should +use the value of the @code{nnmail-split-methods} variable. + +@item nnimap-split-fancy +Uses the same syntax as @code{nnmail-split-fancy}. + +@item nnimap-unsplittable-articles +List of flag symbols to ignore when doing splitting. That is, +articles that have these flags won't be considered when splitting. +The default is @samp{(%Deleted %Seen)}. + +@end table + +Here's a complete example @code{nnimap} backend with a client-side +``fancy'' splitting method: + +@example +(nnimap "imap.example.com" + (nnimap-inbox "INBOX") + (nnimap-split-methods + (| ("MailScanner-SpamCheck" "spam" "spam.detected") + (to "foo@@bar.com" "foo") + "undecided"))) +@end example + + @node Getting Mail @section Getting Mail @cindex reading mail @@ -14933,6 +14469,9 @@ 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. +This variable can also be a fancy split method. For the syntax, +see @ref{Fancy Mail Splitting}. + 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 @@ -15307,10 +14846,7 @@ 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}. +@acronym{IMAP} mailbox. @xref{Using IMAP}, for more information. Keywords: @@ -15402,45 +14938,6 @@ An example @acronym{IMAP} mail source: :fetchflag "\\Seen") @end lisp -@item webmail -Get mail from a webmail server, such as @uref{http://www.hotmail.com/}, -@uref{http://webmail.netscape.com/}, @uref{http://www.netaddress.com/}, -@uref{http://mail.yahoo.com/}. - -NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is -required for url "4.0pre.46". - -WARNING: Mails may be lost. NO WARRANTY. - -Keywords: - -@table @code -@item :subtype -The type of the webmail server. The default is @code{hotmail}. The -alternatives are @code{netscape}, @code{netaddress}, @code{my-deja}. - -@item :user -The user name to give to the webmail server. The default is the login -name. - -@item :password -The password to give to the webmail server. If not specified, the user is -prompted. - -@item :dontexpunge -If non-@code{nil}, only fetch unread articles and don't move them to -trash folder after finishing the fetch. - -@end table - -An example webmail source: - -@lisp -(webmail :subtype 'hotmail - :user "user-name" - :password "secret") -@end lisp - @item group Get the actual mail source from the @code{mail-source} group parameter, @xref{Group Parameters}. @@ -15779,7 +15276,7 @@ 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}). +(@pxref{Client-Side IMAP Splitting}). @item (! @var{func} @var{split}) If the split is a list, and the first element is @code{!}, then @@ -16543,6 +16040,7 @@ Spool}). @end menu + @node Unix Mail Box @subsubsection Unix Mail Box @cindex nnmbox @@ -17258,13 +16756,12 @@ 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} +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 +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, a non-block-structured file system. Since maildirs don't require locking for delivery, the maildirs you use @@ -17334,9 +16831,6 @@ 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 @@ -17479,159 +16973,6 @@ Format string URL to fetch an article by @code{Message-ID}. @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 @@ -17718,15 +17059,6 @@ 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 @@ -17824,739 +17156,6 @@ Put that in your @file{.emacs} file, and hitting links in W3-rendered follow the link. -@node IMAP -@section IMAP -@cindex nnimap -@cindex @acronym{IMAP} - -@acronym{IMAP} is a network protocol for reading mail (or news, or @dots{}), -think of it as a modernized @acronym{NNTP}. Connecting to a @acronym{IMAP} -server is much similar to connecting to a news server, you just -specify the network address of the server. - -@acronym{IMAP} has two properties. First, @acronym{IMAP} can do -everything that @acronym{POP} can, it can hence be viewed as a -@acronym{POP++}. Secondly, @acronym{IMAP} is a mail storage protocol, -similar to @acronym{NNTP} being a news storage protocol---however, -@acronym{IMAP} offers more features than @acronym{NNTP} because news -is more or less read-only whereas mail is read-write. - -If you want to use @acronym{IMAP} as a @acronym{POP++}, use an imap -entry in @code{mail-sources}. With this, Gnus will fetch mails from -the @acronym{IMAP} server and store them on the local disk. This is -not the usage described in this section---@xref{Mail Sources}. - -If you want to use @acronym{IMAP} as a mail storage protocol, use an nnimap -entry in @code{gnus-secondary-select-methods}. With this, Gnus will -manipulate mails stored on the @acronym{IMAP} server. This is the kind of -usage explained in this section. - -A server configuration in @file{~/.gnus.el} with a few @acronym{IMAP} -servers might look something like the following. (Note that for -@acronym{TLS}/@acronym{SSL}, you need external programs and libraries, -see below.) - -@lisp -(setq gnus-secondary-select-methods - '((nnimap "simpleserver") ; @r{no special configuration} - ; @r{perhaps a ssh port forwarded server:} - (nnimap "dolk" - (nnimap-address "localhost") - (nnimap-server-port 1430)) - ; @r{a UW server running on localhost} - (nnimap "barbar" - (nnimap-server-port 143) - (nnimap-address "localhost") - (nnimap-list-pattern ("INBOX" "mail/*"))) - ; @r{anonymous public cyrus server:} - (nnimap "cyrus.andrew.cmu.edu" - (nnimap-authenticator anonymous) - (nnimap-list-pattern "archive.*") - (nnimap-stream network)) - ; @r{a ssl server on a non-standard port:} - (nnimap "vic20" - (nnimap-address "vic20.somewhere.com") - (nnimap-server-port 9930) - (nnimap-stream ssl)))) -@end lisp - -After defining the new server, you can subscribe to groups on the -server using normal Gnus commands such as @kbd{U} in the Group Buffer -(@pxref{Subscription Commands}) or via the Server Buffer -(@pxref{Server Buffer}). - -The following variables can be used to create a virtual @code{nnimap} -server: - -@table @code - -@item nnimap-address -@vindex nnimap-address - -The address of the remote @acronym{IMAP} server. Defaults to the virtual -server name if not specified. - -@item nnimap-server-port -@vindex nnimap-server-port -Port on server to contact. Defaults to port 143, or 993 for @acronym{TLS}/@acronym{SSL}. - -Note that this should be an integer, example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-server-port 4711)) -@end lisp - -@item nnimap-list-pattern -@vindex nnimap-list-pattern -String or list of strings of mailboxes to limit available groups to. -This is used when the server has very many mailboxes and you're only -interested in a few---some servers export your home directory via -@acronym{IMAP}, you'll probably want to limit the mailboxes to those in -@file{~/Mail/*} then. - -The string can also be a cons of REFERENCE and the string as above, what -REFERENCE is used for is server specific, but on the University of -Washington server it's a directory that will be concatenated with the -mailbox. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" - ("~friend/Mail/" . "list/*")))) -@end lisp - -@item nnimap-stream -@vindex nnimap-stream -The type of stream used to connect to your server. By default, nnimap -will detect and automatically use all of the below, with the exception -of @acronym{TLS}/@acronym{SSL}. (@acronym{IMAP} over -@acronym{TLS}/@acronym{SSL} is being replaced by STARTTLS, which can -be automatically detected, but it's not widely deployed yet.) - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-stream ssl)) -@end lisp - -Please note that the value of @code{nnimap-stream} is a symbol! - -@itemize @bullet -@item -@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the -@samp{gsasl} or @samp{imtest} program. -@item -@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program. -@item -@dfn{starttls:} Connect via the STARTTLS extension (similar to -@acronym{TLS}/@acronym{SSL}). Requires the external library @samp{starttls.el} and program -@samp{starttls}. -@item -@dfn{tls:} Connect through @acronym{TLS}. Requires GNUTLS (the program -@samp{gnutls-cli}). -@item -@dfn{ssl:} Connect through @acronym{SSL}. Requires OpenSSL (the program -@samp{openssl}) or SSLeay (@samp{s_client}). -@item -@dfn{shell:} Use a shell command to start @acronym{IMAP} connection. -@item -@dfn{network:} Plain, TCP/IP network connection. -@end itemize - -@vindex imap-kerberos4-program -The @samp{imtest} program is shipped with Cyrus IMAPD. If you're -using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version -1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type} -to make @code{imap.el} use a pty instead of a pipe when communicating -with @samp{imtest}. You will then suffer from a line length -restrictions on @acronym{IMAP} commands, which might make Gnus seem to hang -indefinitely if you have many articles in a mailbox. The variable -@code{imap-kerberos4-program} contain parameters to pass to the imtest -program. - -For @acronym{TLS} connection, the @code{gnutls-cli} program from GNUTLS is -needed. It is available from -@uref{http://www.gnu.org/software/gnutls/}. - -@vindex imap-gssapi-program -This parameter specifies a list of command lines that invoke a GSSAPI -authenticated @acronym{IMAP} stream in a subshell. They are tried -sequentially until a connection is made, or the list has been -exhausted. By default, @samp{gsasl} from GNU SASL, available from -@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest} -program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are -tried. - -@vindex imap-ssl-program -For @acronym{SSL} connections, the OpenSSL program is available from -@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay, -and nnimap support it too---although the most recent versions of -SSLeay, 0.9.x, are known to have serious bugs making it -useless. Earlier versions, especially 0.8.x, of SSLeay are known to -work. The variable @code{imap-ssl-program} contain parameters to pass -to OpenSSL/SSLeay. - -@vindex imap-shell-program -@vindex imap-shell-host -For @acronym{IMAP} connections using the @code{shell} stream, the -variable @code{imap-shell-program} specify what program to call. Make -sure nothing is interfering with the output of the program, e.g., don't -forget to redirect the error output to the void. - -@item nnimap-authenticator -@vindex nnimap-authenticator - -The authenticator used to connect to the server. By default, nnimap -will use the most secure authenticator your server is capable of. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-authenticator anonymous)) -@end lisp - -Please note that the value of @code{nnimap-authenticator} is a symbol! - -@itemize @bullet -@item -@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires -external program @code{gsasl} or @code{imtest}. -@item -@dfn{kerberos4:} Kerberos 4 authentication. Requires external program -@code{imtest}. -@item -@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires -external library @code{digest-md5.el}. -@item -@dfn{cram-md5:} Encrypted username/password via CRAM-MD5. -@item -@dfn{login:} Plain-text username/password via LOGIN. -@item -@dfn{anonymous:} Login as ``anonymous'', supplying your email address as password. -@end itemize - -@item nnimap-expunge-on-close -@cindex expunging -@vindex nnimap-expunge-on-close -Unlike Parmenides the @acronym{IMAP} designers have decided things that -don't exist actually do exist. More specifically, @acronym{IMAP} has -this concept of marking articles @code{Deleted} which doesn't actually -delete them, and this (marking them @code{Deleted}, that is) is what -nnimap does when you delete an article in Gnus (with @kbd{B DEL} or -similar). - -Since the articles aren't really removed when we mark them with the -@code{Deleted} flag we'll need a way to actually delete them. Feel like -running in circles yet? - -Traditionally, nnimap has removed all articles marked as @code{Deleted} -when closing a mailbox but this is now configurable by this server -variable. - -The possible options are: - -@table @code - -@item always -The default behavior, delete all articles marked as ``Deleted'' when -closing a mailbox. -@item never -Never actually delete articles. Currently there is no way of showing -the articles marked for deletion in nnimap, but other @acronym{IMAP} clients -may allow you to do this. If you ever want to run the EXPUNGE command -manually, @xref{Expunging mailboxes}. -@item ask -When closing mailboxes, nnimap will ask if you wish to expunge deleted -articles or not. - -@end table - -@item nnimap-importantize-dormant -@vindex nnimap-importantize-dormant - -If non-@code{nil} (the default), marks dormant articles as ticked (as -well), for other @acronym{IMAP} clients. Within Gnus, dormant articles will -naturally still (only) be marked as dormant. This is to make dormant -articles stand out, just like ticked articles, in other @acronym{IMAP} -clients. (In other words, Gnus has two ``Tick'' marks and @acronym{IMAP} -has only one.) - -Probably the only reason for frobbing this would be if you're trying -enable per-user persistent dormant flags, using something like: - -@lisp -(setcdr (assq 'dormant nnimap-mark-to-flag-alist) - (format "gnus-dormant-%s" (user-login-name))) -(setcdr (assq 'dormant nnimap-mark-to-predicate-alist) - (format "KEYWORD gnus-dormant-%s" (user-login-name))) -@end lisp - -In this case, you would not want the per-user dormant flag showing up -as ticked for other users. - -@item nnimap-expunge-search-string -@cindex expunging -@vindex nnimap-expunge-search-string -@cindex expiring @acronym{IMAP} mail - -This variable contain the @acronym{IMAP} search command sent to server when -searching for articles eligible for expiring. The default is -@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by -UID set and the second @code{%s} is replaced by a date. - -Probably the only useful value to change this to is -@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in -messages instead of the internal article date. See section 6.4.4 of -RFC 2060 for more information on valid strings. - -However, if @code{nnimap-search-uids-not-since-is-evil} -is true, this variable has no effect since the search logic -is reversed, as described below. - -@item nnimap-authinfo-file -@vindex nnimap-authinfo-file - -A file containing credentials used to log in on servers. The format is -(almost) the same as the @code{ftp} @file{~/.netrc} file. See the -variable @code{nntp-authinfo-file} for exact syntax; also see -@ref{NNTP}. An example of an .authinfo line for an IMAP server, is: - -@example -machine students.uio.no login larsi password geheimnis port imap -@end example - -Note that it should be @code{port imap}, or @code{port 143}, if you -use a @code{nnimap-stream} of @code{tls} or @code{ssl}, even if the -actual port number used is port 993 for secured IMAP. For -convenience, Gnus will accept @code{port imaps} as a synonym of -@code{port imap}. - -@item nnimap-need-unselect-to-notice-new-mail -@vindex nnimap-need-unselect-to-notice-new-mail - -Unselect mailboxes before looking for new mail in them. Some servers -seem to need this under some circumstances; it was reported that -Courier 1.7.1 did. - -@item nnimap-nov-is-evil -@vindex nnimap-nov-is-evil -@cindex Courier @acronym{IMAP} server -@cindex @acronym{NOV} - -Never generate or use a local @acronym{NOV} database. Defaults to the -value of @code{gnus-agent}. - -Using a @acronym{NOV} database usually makes header fetching much -faster, but it uses the @code{UID SEARCH UID} command, which is very -slow on some servers (notably some versions of Courier). Since the Gnus -Agent caches the information in the @acronym{NOV} database without using -the slow command, this variable defaults to true if the Agent is in use, -and false otherwise. - -@item nnimap-search-uids-not-since-is-evil -@vindex nnimap-search-uids-not-since-is-evil -@cindex Courier @acronym{IMAP} server -@cindex expiring @acronym{IMAP} mail - -Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE -@var{date}} command, which is slow on some @acronym{IMAP} servers -(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE -@var{date}} and prune the list of expirable articles within Gnus. - -When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a -list of expirable articles and asks the IMAP server questions like ``Of -these articles, which ones are older than a week?'' While this seems -like a perfectly reasonable question, some IMAP servers take a long time -to answer it, since they seemingly go looking into every old article to -see if it is one of the expirable ones. Curiously, the question ``Of -@emph{all} articles, which ones are newer than a week?'' seems to be -much faster to answer, so setting this variable causes Gnus to ask this -question and figure out the answer to the real question itself. - -This problem can really sneak up on you: when you first configure Gnus, -everything works fine, but once you accumulate a couple thousand -messages, you start cursing Gnus for being so slow. On the other hand, -if you get a lot of email within a week, setting this variable will -cause a lot of network traffic between Gnus and the IMAP server. - -@item nnimap-logout-timeout -@vindex nnimap-logout-timeout - -There is a case where a connection to a @acronym{IMAP} server is unable -to close, when connecting to the server via a certain kind of network, -e.g. @acronym{VPN}. In that case, it will be observed that a connection -between Emacs and the local network looks alive even if the server has -closed a connection for some reason (typically, a timeout). -Consequently, Emacs continues waiting for a response from the server for -the @code{LOGOUT} command that Emacs sent, or hangs in other words. If -you are in such a network, setting this variable to a number of seconds -will be helpful. If it is set, a hung connection will be closed -forcibly, after this number of seconds from the time Emacs sends the -@code{LOGOUT} command. It should not be too small value but too large -value will be inconvenient too. Perhaps the value 1.0 will be a good -candidate but it might be worth trying some other values. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-logout-timeout 1.0)) -@end lisp - -@end table - -@menu -* Splitting in IMAP:: Splitting mail with nnimap. -* Expiring in IMAP:: Expiring mail with nnimap. -* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. -* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. -* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus. -* Debugging IMAP:: What to do when things don't work. -@end menu - - - -@node Splitting in IMAP -@subsection Splitting in IMAP -@cindex splitting imap mail - -Splitting is something Gnus users have loved and used for years, and now -the rest of the world is catching up. Yeah, dream on, not many -@acronym{IMAP} servers have server side splitting and those that have -splitting seem to use some non-standard protocol. This means that -@acronym{IMAP} support for Gnus has to do its own splitting. - -And it does. - -(Incidentally, people seem to have been dreaming on, and Sieve has -gaining a market share and is supported by several IMAP servers. -Fortunately, Gnus support it too, @xref{Sieve Commands}.) - -Here are the variables of interest: - -@table @code - -@item nnimap-split-crosspost -@cindex splitting, crosspost -@cindex crosspost -@vindex nnimap-split-crosspost - -If non-@code{nil}, do crossposting if several split methods match the -mail. If @code{nil}, the first match in @code{nnimap-split-rule} -found will be used. - -Nnmail equivalent: @code{nnmail-crosspost}. - -@item nnimap-split-inbox -@cindex splitting, inbox -@cindex inbox -@vindex nnimap-split-inbox - -A string or a list of strings that gives the name(s) of @acronym{IMAP} -mailboxes to split from. Defaults to @code{nil}, which means that -splitting is disabled! - -@lisp -(setq nnimap-split-inbox - '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) -@end lisp - -No nnmail equivalent. - -@item nnimap-split-rule -@cindex splitting, rules -@vindex nnimap-split-rule - -New mail found in @code{nnimap-split-inbox} will be split according to -this variable. - -This variable contains a list of lists, where the first element in the -sublist gives the name of the @acronym{IMAP} mailbox to move articles -matching the regexp in the second element in the sublist. Got that? -Neither did I, we need examples. - -@lisp -(setq nnimap-split-rule - '(("INBOX.nnimap" - "^Sender: owner-nnimap@@vic20.globalcom.se") - ("INBOX.junk" "^Subject:.*MAKE MONEY") - ("INBOX.private" ""))) -@end lisp - -This will put all articles from the nnimap mailing list into mailbox -INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line -into INBOX.junk and everything else in INBOX.private. - -The first string may contain @samp{\\1} forms, like the ones used by -replace-match to insert sub-expressions from the matched text. For -instance: - -@lisp -("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@") -@end lisp - -The first element can also be the symbol @code{junk} to indicate that -matching messages should simply be deleted. Use with care. - -The second element can also be a function. In that case, it will be -called with the first element of the rule as the argument, in a buffer -containing the headers of the article. It should return a -non-@code{nil} value if it thinks that the mail belongs in that group. - -Nnmail users might recollect that the last regexp had to be empty to -match all articles (like in the example above). This is not required in -nnimap. Articles not matching any of the regexps will not be moved out -of your inbox. (This might affect performance if you keep lots of -unread articles in your inbox, since the splitting code would go over -them every time you fetch new mail.) - -These rules are processed from the beginning of the alist toward the -end. The first rule to make a match will ``win'', unless you have -crossposting enabled. In that case, all matching rules will ``win''. - -This variable can also have a function as its value, the function will -be called with the headers narrowed and should return a group where it -thinks the article should be split to. See @code{nnimap-split-fancy}. - -The splitting code tries to create mailboxes if it needs to. - -To allow for different split rules on different virtual servers, and -even different split rules in different inboxes on the same server, -the syntax of this variable have been extended along the lines of: - -@lisp -(setq nnimap-split-rule - '(("my1server" (".*" (("ding" "ding@@gnus.org") - ("junk" "From:.*Simon")))) - ("my2server" ("INBOX" nnimap-split-fancy)) - ("my[34]server" (".*" (("private" "To:.*Simon") - ("junk" my-junk-func)))))) -@end lisp - -The virtual server name is in fact a regexp, so that the same rules -may apply to several servers. In the example, the servers -@code{my3server} and @code{my4server} both use the same rules. -Similarly, the inbox string is also a regexp. The actual splitting -rules are as before, either a function, or a list with group/regexp or -group/function elements. - -Nnmail equivalent: @code{nnmail-split-methods}. - -@item nnimap-split-predicate -@cindex splitting -@vindex nnimap-split-predicate - -Mail matching this predicate in @code{nnimap-split-inbox} will be -split, it is a string and the default is @samp{UNSEEN UNDELETED}. - -This might be useful if you use another @acronym{IMAP} client to read mail in -your inbox but would like Gnus to split all articles in the inbox -regardless of readedness. Then you might change this to -@samp{UNDELETED}. - -@item nnimap-split-fancy -@cindex splitting, fancy -@findex nnimap-split-fancy -@vindex nnimap-split-fancy - -It's possible to set @code{nnimap-split-rule} to -@code{nnmail-split-fancy} if you want to use fancy -splitting. @xref{Fancy Mail Splitting}. - -However, to be able to have different fancy split rules for nnmail and -nnimap back ends you can set @code{nnimap-split-rule} to -@code{nnimap-split-fancy} and define the nnimap specific fancy split -rule in @code{nnimap-split-fancy}. - -Example: - -@lisp -(setq nnimap-split-rule 'nnimap-split-fancy - nnimap-split-fancy ...) -@end lisp - -Nnmail equivalent: @code{nnmail-split-fancy}. - -@item nnimap-split-download-body -@findex nnimap-split-download-body -@vindex nnimap-split-download-body - -Set to non-@code{nil} to download entire articles during splitting. -This is generally not required, and will slow things down -considerably. You may need it if you want to use an advanced -splitting function that analyzes the body to split the article. - -@end table - -@node Expiring in IMAP -@subsection Expiring in IMAP -@cindex expiring @acronym{IMAP} mail - -Even though @code{nnimap} is not a proper @code{nnmail} derived back -end, it supports most features in regular expiring (@pxref{Expiring -Mail}). Unlike splitting in @acronym{IMAP} (@pxref{Splitting in -IMAP}) it does not clone the @code{nnmail} variables (i.e., creating -@var{nnimap-expiry-wait}) but reuse the @code{nnmail} variables. What -follows below are the variables used by the @code{nnimap} expiry -process. - -A note on how the expire mark is stored on the @acronym{IMAP} server is -appropriate here as well. The expire mark is translated into a -@code{imap} client specific mark, @code{gnus-expire}, and stored on the -message. This means that likely only Gnus will understand and treat -the @code{gnus-expire} mark properly, although other clients may allow -you to view client specific flags on the message. It also means that -your server must support permanent storage of client specific flags on -messages. Most do, fortunately. - -If expiring @acronym{IMAP} mail seems very slow, try setting the server -variable @code{nnimap-search-uids-not-since-is-evil}. - -@table @code - -@item nnmail-expiry-wait -@item nnmail-expiry-wait-function - -These variables are fully supported. The expire value can be a -number, the symbol @code{immediate} or @code{never}. - -@item nnmail-expiry-target - -This variable is supported, and internally implemented by calling the -@code{nnmail} functions that handle this. It contains an optimization -that if the destination is a @acronym{IMAP} group on the same server, the -article is copied instead of appended (that is, uploaded again). - -@end table - -@node Editing IMAP ACLs -@subsection Editing IMAP ACLs -@cindex editing imap acls -@cindex Access Control Lists -@cindex Editing @acronym{IMAP} ACLs -@kindex G l (Group) -@findex gnus-group-nnimap-edit-acl - -ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for -limiting (or enabling) other users access to your mail boxes. Not all -@acronym{IMAP} servers support this, this function will give an error if it -doesn't. - -To edit an ACL for a mailbox, type @kbd{G l} -(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with an ACL -editing window with detailed instructions. - -Some possible uses: - -@itemize @bullet -@item -Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags) -on your mailing list mailboxes enables other users on the same server to -follow the list without subscribing to it. -@item -At least with the Cyrus server, you are required to give the user -``anyone'' posting ("p") capabilities to have ``plussing'' work (that is, -mail sent to user+mailbox@@domain ending up in the @acronym{IMAP} mailbox -INBOX.mailbox). -@end itemize - -@node Expunging mailboxes -@subsection Expunging mailboxes -@cindex expunging - -@cindex expunge -@cindex manual expunging -@kindex G x (Group) -@findex gnus-group-nnimap-expunge - -If you're using the @code{never} setting of @code{nnimap-expunge-on-close}, -you may want the option of expunging all deleted articles in a mailbox -manually. This is exactly what @kbd{G x} does. - -Currently there is no way of showing deleted articles, you can just -delete them. - -@node A note on namespaces -@subsection A note on namespaces -@cindex IMAP namespace -@cindex namespaces - -The @acronym{IMAP} protocol has a concept called namespaces, described -by the following text in the RFC2060: - -@display -5.1.2. Mailbox Namespace Naming Convention - - By convention, the first hierarchical element of any mailbox name - which begins with "#" identifies the "namespace" of the remainder of - the name. This makes it possible to disambiguate between different - types of mailbox stores, each of which have their own namespaces. - - For example, implementations which offer access to USENET - newsgroups MAY use the "#news" namespace to partition the USENET - newsgroup namespace from that of other mailboxes. Thus, the - comp.mail.misc newsgroup would have an mailbox name of - "#news.comp.mail.misc", and the name "comp.mail.misc" could refer - to a different object (e.g. a user's private mailbox). -@end display - -While there is nothing in this text that warrants concern for the -@acronym{IMAP} implementation in Gnus, some servers use namespace -prefixes in a way that does not work with how Gnus uses mailbox names. - -Specifically, University of Washington's @acronym{IMAP} server uses -mailbox names like @code{#driver.mbx/read-mail} which are valid only -in the @sc{create} and @sc{append} commands. After the mailbox is -created (or a messages is appended to a mailbox), it must be accessed -without the namespace prefix, i.e. @code{read-mail}. Since Gnus do -not make it possible for the user to guarantee that user entered -mailbox names will only be used with the CREATE and APPEND commands, -you should simply not use the namespace prefixed mailbox names in -Gnus. - -See the UoW IMAPD documentation for the @code{#driver.*/} prefix -for more information on how to use the prefixes. They are a power -tool and should be used only if you are sure what the effects are. - -@node Debugging IMAP -@subsection Debugging IMAP -@cindex IMAP debugging -@cindex protocol dump (IMAP) - -@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or -@acronym{POP3}. Implementation bugs are not unlikely, and we do our -best to fix them right away. If you encounter odd behavior, chances -are that either the server or Gnus is buggy. - -If you are familiar with network protocols in general, you will -probably be able to extract some clues from the protocol dump of the -exchanges between Gnus and the server. Even if you are not familiar -with network protocols, when you include the protocol dump in -@acronym{IMAP}-related bug reports you are helping us with data -critical to solving the problem. Therefore, we strongly encourage you -to include the protocol dump when reporting IMAP bugs in Gnus. - - -@vindex imap-log -Because the protocol dump, when enabled, generates lots of data, it is -disabled by default. You can enable it by setting @code{imap-log} as -follows: - -@lisp -(setq imap-log t) -@end lisp - -This instructs the @code{imap.el} package to log any exchanges with -the server. The log is stored in the buffer @samp{*imap-log*}. Look -for error messages, which sometimes are tagged with the keyword -@code{BAD}---but when submitting a bug, make sure to include all the -data. - @node Other Sources @section Other Sources @@ -18568,8 +17167,8 @@ newsgroups. * 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. +* The Empty Backend:: The backend that never has any news. @end menu @@ -18710,6 +17309,10 @@ A @acronym{MIME} digest of messages. @item lanl-gov-announce Announcement messages from LANL Gov Announce. +@cindex git commit messages +@item git +@code{git} commit messages. + @cindex forwarded messages @item rfc822-forward A message forwarded according to RFC822. @@ -18936,289 +17539,6 @@ 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 @@ -19296,6 +17616,22 @@ So, to use this, simply say something like: @end lisp +@node The Empty Backend +@subsection The Empty Backend +@cindex nnnil + +@code{nnnil} is a backend that can be used as a placeholder if you +have to specify a backend somewhere, but don't really want to. The +classical example is if you don't want to have a primary select +methods, but want to only use secondary ones: + +@lisp +(setq gnus-select-method '(nnnil "")) +(setq gnus-secondary-select-methods + '((nnimap "foo") + (nnml ""))) +@end lisp + @node Combined Groups @section Combined Groups @@ -19305,7 +17641,6 @@ groups. @menu * Virtual Groups:: Combining articles from many groups. -* Kibozed Groups:: Looking through parts of the newsfeed for articles. @end menu @@ -19395,58 +17730,6 @@ 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 @@ -20933,7 +19216,7 @@ 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 +However, all articles parsed prior to losing the connection will be available while unplugged). The default is 10M so it is unusual to see any cycling. @@ -22002,7 +20285,7 @@ is @file{ADAPT}. @vindex gnus-adaptive-pretty-print Adaptive score files can get huge and are not meant to be edited by human hands. If @code{gnus-adaptive-pretty-print} is @code{nil} (the -deafult) those files will not be written in a human readable way. +default) those files will not be written in a human readable way. @vindex gnus-score-exact-adapt-limit When doing adaptive scoring, substring or fuzzy matching would probably @@ -22776,6 +21059,1072 @@ 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. +@node Searching +@chapter Searching +@cindex searching + +FIXME: Add a brief overview of Gnus search capabilities. A brief +comparison of nnir, nnmairix, contrib/gnus-namazu would be nice +as well. + +This chapter describes tools for searching groups and servers for +articles matching a query and then retrieving those articles. Gnus +provides a simpler mechanism for searching through articles in a summary buffer +to find those matching a pattern. @xref{Searching for Articles}. + +@menu +* nnir:: Searching with various engines. +* nnmairix:: Searching with Mairix. +@end menu + +@node nnir +@section nnir +@cindex nnir + +This section describes how to use @code{nnir} to search for articles +within gnus. + +@menu +* What is nnir?:: What does @code{nnir} do? +* Basic Usage:: How to perform simple searches. +* Setting up nnir:: How to set up @code{nnir}. +@end menu + +@node What is nnir? +@subsection What is nnir? + +@code{nnir} is a Gnus interface to a number of tools for searching +through mail and news repositories. Different backends (like +@code{nnimap} and @code{nntp}) work with different tools (called +@dfn{engines} in @code{nnir} lingo), but all use the same basic search +interface. + +The @code{nnimap} and @code{gmane} search engines should work with no +configuration. Other engines require a local index that needs to be +created and maintained outside of Gnus. + + +@node Basic Usage +@subsection Basic Usage + +In the group buffer typing @kbd{G G} will search the group on the +current line by calling @code{gnus-group-make-nnir-group}. This prompts +for a query string, creates an ephemeral @code{nnir} group containing +the articles that match this query, and takes you to a summary buffer +showing these articles. Articles may then be read, moved and deleted +using the usual commands. + +The @code{nnir} group made in this way is an @code{ephemeral} group, and +some changes are not permanent: aside from reading, moving, and +deleting, you can't act on the original article. But there is an +alternative: you can @emph{warp} to the original group for the article +on the current line with @kbd{A W}, aka +@code{gnus-warp-to-article}. Even better, the function +@code{gnus-summary-refer-thread}, bound by default in summary buffers to +@kbd{A T}, will first warp to the original group before it works its +magic and includes all the articles in the thread. From here you can +read, move and delete articles, but also copy them, alter article marks, +whatever. Go nuts. + +You say you want to search more than just the group on the current line? +No problem: just process-mark the groups you want to search. You want +even more? Calling for an nnir search with the cursor on a topic heading +will search all the groups under that heading. + +Still not enough? OK, in the server buffer +@code{gnus-group-make-nnir-group} (now bound to @kbd{G}) will search all +groups from the server on the current line. Too much? Want to ignore +certain groups when searching, like spam groups? Just customize +@code{nnir-ignored-newsgroups}. + +One more thing: individual search engines may have special search +features. You can access these special features by giving a prefix-arg +to @code{gnus-group-make-nnir-group}. If you are searching multiple +groups with different search engines you will be prompted for the +special search features for each engine separately. + + +@node Setting up nnir +@subsection Setting up nnir + +To set up nnir you may need to do some prep work. Firstly, you may need +to configure the search engines you plan to use. Some of them, like +@code{imap} and @code{gmane}, need no special configuration. Others, +like @code{namazu} and @code{swish}, require configuration as described +below. Secondly, you need to associate a search engine with a server or +a backend. + +If you just want to use the @code{imap} engine to search @code{nnimap} +servers, and the @code{gmane} engine to search @code{gmane} then you +don't have to do anything. But you might want to read the details of the +query language anyway. + +@menu +* Associating Engines:: How to associate engines. +* The imap Engine:: Imap configuration and usage. +* The gmane Engine:: Gmane configuration and usage. +* The swish++ Engine:: Swish++ configuration and usage. +* The swish-e Engine:: Swish-e configuration and usage. +* The namazu Engine:: Namazu configuration and usage. +* The hyrex Engine:: Hyrex configuration and usage. +* Customizations:: User customizable settings. +@end menu + +@node Associating Engines +@subsubsection Associating Engines + + +When searching a group, @code{nnir} needs to know which search engine to +use. You can configure a given server to use a particular engine by +setting the server variable @code{nnir-search-engine} to the engine +name. For example to use the @code{namazu} engine to search the server +named @code{home} you can use + +@lisp +(setq gnus-secondary-select-methods + '((nnml "home" + (nnimap-address "localhost") + (nnir-search-engine namazu)))) +@end lisp + +Alternatively you might want to use a particular engine for all servers +with a given backend. For example, you might want to use the @code{imap} +engine for all servers using the @code{nnimap} backend. In this case you +can customize the variable @code{nnir-method-default-engines}. This is +an alist of pairs of the form @code{(backend . engine)}. By default this +variable is set to use the @code{imap} engine for all servers using the +@code{nnimap} backend, and the @code{gmane} backend for @code{nntp} +servers. (Don't worry, the @code{gmane} search engine won't actually try +to search non-gmane @code{nntp} servers.) But if you wanted to use +@code{namazu} for all your servers with an @code{nnimap} backend you +could change this to + +@lisp +'((nnimap . namazu) + (nntp . gmane)) +@end lisp + +@node The imap Engine +@subsubsection The imap Engine + +The @code{imap} engine requires no configuration. + +Queries using the @code{imap} engine follow a simple query language. +The search is always case-insensitive and supports the following +features (inspired by the Google search input language): + +@table @samp + +@item Boolean query operators +AND, OR, and NOT are supported, and parentheses can be used to control +operator precedence, e.g. (emacs OR xemacs) AND linux. Note that +operators must be written with all capital letters to be +recognised. Also preceding a term with a - sign is equivalent to NOT +term. + +@item Automatic AND queries +If you specify multiple words then they will be treated as an AND +expression intended to match all components. + +@item Phrase searches +If you wrap your query in double-quotes then it will be treated as a +literal string. + +@end table + +By default the whole message will be searched. The query can be limited +to a specific part of a message by using a prefix-arg. After inputting +the query this will prompt (with completion) for a message part. +Choices include ``Whole message'', ``Subject'', ``From'', and +``To''. Any unrecognized input is interpreted as a header name. For +example, typing @kbd{Message-ID} in response to this prompt will limit +the query to the Message-ID header. + +Finally selecting ``Imap'' will interpret the query as a raw +@acronym{IMAP} search query. The format of such queries can be found in +RFC3501. + +If you don't like the default of searching whole messages you can +customize @code{nnir-imap-default-search-key}. For example to use +@acronym{IMAP} queries by default + +@lisp +(setq nnir-imap-default-search-key "Imap") +@end lisp + +@node The gmane Engine +@subsubsection The gmane Engine + +The @code{gmane} engine requires no configuration. + +Gmane queries follow a simple query language: + +@table @samp +@item Boolean query operators +AND, OR, NOT (or AND NOT), and XOR are supported, and brackets can be +used to control operator precedence, e.g. (emacs OR xemacs) AND linux. +Note that operators must be written with all capital letters to be +recognised. + +@item Required and excluded terms ++ and - can be used to require or exclude terms, e.g. football -american + +@item Unicode handling +The search engine converts all text to utf-8, so searching should work +in any language. + +@item Stopwords +Common English words (like 'the' and 'a') are ignored by default. You +can override this by prefixing such words with a + (e.g. +the) or +enclosing the word in quotes (e.g. "the"). + +@end table + +The query can be limited to articles by a specific author using a +prefix-arg. After inputting the query this will prompt for an author +name (or part of a name) to match. + +@node The swish++ Engine +@subsubsection The swish++ Engine + +FIXEM: Say something more here. + +Documentation for swish++ may be found at the swish++ sourceforge page: +@uref{http://swishplusplus.sourceforge.net} + +@table @code + +@item nnir-swish++-program +The name of the swish++ executable. Defaults to @code{search} + +@item nnir-swish++-additional-switches +A list of strings to be given as additional arguments to +swish++. @code{nil} by default. + +@item nnir-swish++-remove-prefix +The prefix to remove from each file name returned by swish++ in order +to get a group name. By default this is @code{$HOME/Mail}. + +@end table + +@node The swish-e Engine +@subsubsection The swish-e Engine + +FIXEM: Say something more here. + +Documentation for swish-e may be found at the swish-e homepage +@uref{http://swish-e.org} + +@table @code + +@item nnir-swish-e-program +The name of the swish-e search program. Defaults to @code{swish-e}. + +@item nnir-swish-e-additional-switches +A list of strings to be given as additional arguments to +swish-e. @code{nil} by default. + +@item nnir-swish-e-remove-prefix +The prefix to remove from each file name returned by swish-e in order +to get a group name. By default this is @code{$HOME/Mail}. + +@end table + +@node The namazu Engine +@subsubsection The namazu Engine + +Using the namazu engine requires creating and maintaining index files. +One directory should contain all the index files, and nnir must be told +where to find them by setting the @code{nnir-namazu-index-directory} +variable. + +To work correctly the @code{nnir-namazu-remove-prefix} variable must +also be correct. This is the prefix to remove from each file name +returned by Namazu in order to get a proper group name (albeit with `/' +instead of `.'). + +For example, suppose that Namazu returns file names such as +@samp{/home/john/Mail/mail/misc/42}. For this example, use the +following setting: @code{(setq nnir-namazu-remove-prefix +"/home/john/Mail/")} Note the trailing slash. Removing this prefix from +the directory gives @samp{mail/misc/42}. @code{nnir} knows to remove +the @samp{/42} and to replace @samp{/} with @samp{.} to arrive at the +correct group name @samp{mail.misc}. + +Extra switches may be passed to the namazu search command by setting the +variable @code{nnir-namazu-additional-switches}. It is particularly +important not to pass any any switches to namazu that will change the +output format. Good switches to use include `--sort', `--ascending', +`--early' and `--late'. Refer to the Namazu documentation for further +information on valid switches. + +Mail must first be indexed with the `mknmz' program. Read the documentation +for namazu to create a configuration file. Here is an example: + +@cartouche +@example + package conf; # Don't remove this line! + + # Paths which will not be indexed. Don't use `^' or `$' anchors. + $EXCLUDE_PATH = "spam|sent"; + + # Header fields which should be searchable. case-insensitive + $REMAIN_HEADER = "from|date|message-id|subject"; + + # Searchable fields. case-insensitive + $SEARCH_FIELD = "from|date|message-id|subject"; + + # The max length of a word. + $WORD_LENG_MAX = 128; + + # The max length of a field. + $MAX_FIELD_LENGTH = 256; +@end example +@end cartouche + +For this example, mail is stored in the directories @samp{~/Mail/mail/}, +@samp{~/Mail/lists/} and @samp{~/Mail/archive/}, so to index them go to +the index directory set in @code{nnir-namazu-index-directory} and issue +the following command: + +@example +mknmz --mailnews ~/Mail/archive/ ~/Mail/mail/ ~/Mail/lists/ +@end example + +For maximum searching efficiency you might want to have a cron job run +this command periodically, say every four hours. + +@node The hyrex Engine +@subsubsection The hyrex Engine +This engine is obsolete. + +@node Customizations +@subsubsection Custimozations + +@table @code + +@item nnir-method-default-engines +Alist of server backend - search engine pairs. The default associations +are +@example +(nnimap . imap) +(nntp . gmane) +@end example + +@item nnir-ignored-newsgroups +A regexp to match newsgroups in the active file that should be skipped +when searching all groups on a server. + +@item nnir-summary-line-format +The format specification to be used for lines in an nnir summary buffer. +All the items from `gnus-summary-line-format' are available, along with +three items unique to nnir summary buffers: + +@example +%Z Search retrieval score value (integer) +%G Article original full group name (string) +%g Article original short group name (string) +@end example + +If nil (the default) this will use @code{gnus-summary-line-format}. + +@item nnir-retrieve-headers-override-function +If non-nil, a function that retrieves article headers rather than using +the gnus built-in function. This function takes an article list and +group as arguments and populates the `nntp-server-buffer' with the +retrieved headers. It should then return either 'nov or 'headers +indicating the retrieved header format. Failure to retrieve headers +should return @code{nil} + +If this variable is nil, or if the provided function returns nil for a +search result, @code{gnus-retrieve-headers} will be called instead." + + +@end table + + +@node nnmairix +@section nnmairix + +@cindex mairix +@cindex nnmairix +This paragraph describes how to set up mairix and the back end +@code{nnmairix} for indexing and searching your mail from within +Gnus. Additionally, you can create permanent ``smart'' groups which are +bound to mairix searches and are automatically updated. + +@menu +* About mairix:: About the mairix mail search engine +* nnmairix requirements:: What you will need for using nnmairix +* What nnmairix does:: What does nnmairix actually do? +* Setting up mairix:: Set up your mairix installation +* Configuring nnmairix:: Set up the nnmairix back end +* nnmairix keyboard shortcuts:: List of available keyboard shortcuts +* Propagating marks:: How to propagate marks from nnmairix groups +* nnmairix tips and tricks:: Some tips, tricks and examples +* nnmairix caveats:: Some more stuff you might want to know +@end menu + +@c FIXME: The markup in this section might need improvement. +@c E.g. adding @samp, @var, @file, @command, etc. +@c Cf. (info "(texinfo)Indicating") + +@node About mairix +@subsection About mairix + +Mairix is a tool for indexing and searching words in locally stored +mail. It was written by Richard Curnow and is licensed under the +GPL. Mairix comes with most popular GNU/Linux distributions, but it also +runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can +be found at +@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} + +Though mairix might not be as flexible as other search tools like +swish++ or namazu, which you can use via the @code{nnir} back end, it +has the prime advantage of being incredibly fast. On current systems, it +can easily search through headers and message bodies of thousands and +thousands of mails in well under a second. Building the database +necessary for searching might take a minute or two, but only has to be +done once fully. Afterwards, the updates are done incrementally and +therefore are really fast, too. Additionally, mairix is very easy to set +up. + +For maximum speed though, mairix should be used with mails stored in +@code{Maildir} or @code{MH} format (this includes the @code{nnml} back +end), although it also works with mbox. Mairix presents the search +results by populating a @emph{virtual} maildir/MH folder with symlinks +which point to the ``real'' message files (if mbox is used, copies are +made). Since mairix already presents search results in such a virtual +mail folder, it is very well suited for using it as an external program +for creating @emph{smart} mail folders, which represent certain mail +searches. + +@node nnmairix requirements +@subsection nnmairix requirements + +Mairix searches local mail---that means, mairix absolutely must have +direct access to your mail folders. If your mail resides on another +server (e.g. an @acronym{IMAP} server) and you happen to have shell +access, @code{nnmairix} supports running mairix remotely, e.g. via ssh. + +Additionally, @code{nnmairix} only supports the following Gnus back +ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use +one of these back ends for using @code{nnmairix}. Other back ends, like +@code{nnmbox}, @code{nnfolder} or @code{nnmh}, won't work. + +If you absolutely must use mbox and still want to use @code{nnmairix}, +you can set up a local @acronym{IMAP} server, which you then access via +@code{nnimap}. This is a rather massive setup for accessing some mbox +files, so just change to MH or Maildir already... However, if you're +really, really passionate about using mbox, you might want to look into +the package @file{mairix.el}, which comes with Emacs 23. + +@node What nnmairix does +@subsection What nnmairix does + +The back end @code{nnmairix} enables you to call mairix from within Gnus, +either to query mairix with a search term or to update the +database. While visiting a message in the summary buffer, you can use +several pre-defined shortcuts for calling mairix, e.g. to quickly +search for all mails from the sender of the current message or to +display the whole thread associated with the message, even if the +mails are in different folders. + +Additionally, you can create permanent @code{nnmairix} groups which are bound +to certain mairix searches. This way, you can easily create a group +containing mails from a certain sender, with a certain subject line or +even for one specific thread based on the Message-ID. If you check for +new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they +automatically update themselves by calling mairix. + +You might ask why you need @code{nnmairix} at all, since mairix already +creates the group, populates it with links to the mails so that you can +then access it with Gnus, right? Well, this @emph{might} work, but often +does not---at least not without problems. Most probably you will get +strange article counts, and sometimes you might see mails which Gnus +claims have already been canceled and are inaccessible. This is due to +the fact that Gnus isn't really amused when things are happening behind +its back. Another problem can be the mail back end itself, e.g. if you +use mairix with an @acronym{IMAP} server (I had Dovecot complaining +about corrupt index files when mairix changed the contents of the search +group). Using @code{nnmairix} should circumvent these problems. + +@code{nnmairix} is not really a mail back end---it's actually more like +a wrapper, sitting between a ``real'' mail back end where mairix stores +the searches and the Gnus front end. You can choose between three +different mail back ends for the mairix folders: @code{nnml}, +@code{nnmaildir} or @code{nnimap}. @code{nnmairix} will call the mairix +binary so that the search results are stored in folders named +@code{zz_mairix-<NAME>-<NUMBER>} on this mail back end, but it will +present these folders in the Gnus front end only with @code{<NAME>}. +You can use an existing mail back end where you already store your mail, +but if you're uncomfortable with @code{nnmairix} creating new mail +groups alongside your other mail, you can also create e.g. a new +@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then +make sure those servers do not accidentally receive your new mail +(@pxref{nnmairix caveats}). A special case exists if you want to use +mairix remotely on an IMAP server with @code{nnimap}---here the mairix +folders and your other mail must be on the same @code{nnimap} back end. + +@node Setting up mairix +@subsection Setting up mairix + +First: create a backup of your mail folders (@pxref{nnmairix caveats}). + +Setting up mairix is easy: simply create a @file{.mairixrc} file with +(at least) the following entries: + +@example +# Your Maildir/MH base folder +base=~/Maildir +@end example + +This is the base folder for your mails. All the following directories +are relative to this base folder. If you want to use @code{nnmairix} +with @code{nnimap}, this base directory has to point to the mail +directory where the @acronym{IMAP} server stores the mail folders! + +@example +maildir= ... your maildir folders which should be indexed ... +mh= ... your nnml/mh folders which should be indexed ... +mbox = ... your mbox files which should be indexed ... +@end example + +This specifies all your mail folders and mbox files (relative to the +base directory!) you want to index with mairix. Note that the +@code{nnml} back end saves mails in MH format, so you have to put those +directories in the @code{mh} line. See the example at the end of this +section and mairixrc's man-page for further details. + +@example +omit=zz_mairix-* +@end example + +@vindex nnmairix-group-prefix +This should make sure that you don't accidentally index the mairix +search results. You can change the prefix of these folders with the +variable @code{nnmairix-group-prefix}. + +@example +mformat= ... 'maildir' or 'mh' ... +database= ... location of database file ... +@end example + +The @code{format} setting specifies the output format for the mairix +search folder. Set this to @code{mh} if you want to access search results +with @code{nnml}. Otherwise choose @code{maildir}. + +To summarize, here is my shortened @file{.mairixrc} file as an example: + +@example +base=~/Maildir +maildir=.personal:.work:.logcheck:.sent +mh=../Mail/nnml/*... +mbox=../mboxmail/mailarchive_year* +mformat=maildir +omit=zz_mairix-* +database=~/.mairixdatabase +@end example + +In this case, the base directory is @file{~/Maildir}, where all my Maildir +folders are stored. As you can see, the folders are separated by +colons. If you wonder why every folder begins with a dot: this is +because I use Dovecot as @acronym{IMAP} server, which again uses +@code{Maildir++} folders. For testing nnmairix, I also have some +@code{nnml} mail, which is saved in @file{~/Mail/nnml}. Since this has +to be specified relative to the @code{base} directory, the @code{../Mail} +notation is needed. Note that the line ends in @code{*...}, which means +to recursively scan all files under this directory. Without the three +dots, the wildcard @code{*} will not work recursively. I also have some +old mbox files with archived mail lying around in @file{~/mboxmail}. +The other lines should be obvious. + +See the man page for @code{mairixrc} for details and further options, +especially regarding wildcard usage, which may be a little different +than you are used to. + +Now simply call @code{mairix} to create the index for the first time. +Note that this may take a few minutes, but every following index will do +the updates incrementally and hence is very fast. + +@node Configuring nnmairix +@subsection Configuring nnmairix + +In group mode, type @kbd{G b c} +(@code{nnmairix-create-server-and-default-group}). This will ask you for all +necessary information and create a @code{nnmairix} server as a foreign +server. You will have to specify the following: + +@itemize @bullet + +@item +The @strong{name} of the @code{nnmairix} server---choose whatever you +want. + +@item +The name of the @strong{back end server} where mairix should store its +searches. This must be a full server name, like @code{nnml:mymail}. +Just hit @kbd{TAB} to see the available servers. Currently, servers +which are accessed through @code{nnmaildir}, @code{nnimap} and +@code{nnml} are supported. As explained above, for locally stored +mails, this can be an existing server where you store your mails. +However, you can also create e.g. a new @code{nnmaildir} or @code{nnml} +server exclusively for @code{nnmairix} in your secondary select methods +(@pxref{Finding the News}). If you use a secondary @code{nnml} server +just for mairix, make sure that you explicitly set the server variable +@code{nnml-get-new-mail} to @code{nil}, or you might lose mail +(@pxref{nnmairix caveats}). If you want to use mairix remotely on an +@acronym{IMAP} server, you have to choose the corresponding +@code{nnimap} server here. + +@item +@vindex nnmairix-mairix-search-options +The @strong{command} to call the mairix binary. This will usually just +be @code{mairix}, but you can also choose something like @code{ssh +SERVER mairix} if you want to call mairix remotely, e.g. on your +@acronym{IMAP} server. If you want to add some default options to +mairix, you could do this here, but better use the variable +@code{nnmairix-mairix-search-options} instead. + +@item +The name of the @strong{default search group}. This will be the group +where all temporary mairix searches are stored, i.e. all searches which +are not bound to permanent @code{nnmairix} groups. Choose whatever you +like. + +@item +If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be +asked if you work with @strong{Maildir++}, i.e. with hidden maildir +folders (=beginning with a dot). For example, you have to answer +@samp{yes} here if you work with the Dovecot @acronym{IMAP} +server. Otherwise, you should answer @samp{no} here. + +@end itemize + +@node nnmairix keyboard shortcuts +@subsection nnmairix keyboard shortcuts + +In group mode: + +@table @kbd + +@item G b c +@kindex G b c (Group) +@findex nnmairix-create-server-and-default-group +Creates @code{nnmairix} server and default search group for this server +(@code{nnmairix-create-server-and-default-group}). You should have done +this by now (@pxref{Configuring nnmairix}). + +@item G b s +@kindex G b s (Group) +@findex nnmairix-search +Prompts for query which is then sent to the mairix binary. Search +results are put into the default search group which is automatically +displayed (@code{nnmairix-search}). + +@item G b m +@kindex G b m (Group) +@findex nnmairix-widget-search +Allows you to create a mairix search or a permanent group more +comfortably using graphical widgets, similar to a customization +group. Just try it to see how it works (@code{nnmairix-widget-search}). + +@item G b i +@kindex G b i (Group) +@findex nnmairix-search-interactive +Another command for creating a mairix query more comfortably, but uses +only the minibuffer (@code{nnmairix-search-interactive}). + +@item G b g +@kindex G b g (Group) +@findex nnmairix-create-search-group +Creates a permanent group which is associated with a search query +(@code{nnmairix-create-search-group}). The @code{nnmairix} back end +automatically calls mairix when you update this group with @kbd{g} or +@kbd{M-g}. + +@item G b q +@kindex G b q (Group) +@findex nnmairix-group-change-query-this-group +Changes the search query for the @code{nnmairix} group under cursor +(@code{nnmairix-group-change-query-this-group}). + +@item G b t +@kindex G b t (Group) +@findex nnmairix-group-toggle-threads-this-group +Toggles the 'threads' parameter for the @code{nnmairix} group under cursor, +i.e. if you want see the whole threads of the found messages +(@code{nnmairix-group-toggle-threads-this-group}). + +@item G b u +@kindex G b u (Group) +@findex nnmairix-update-database +@vindex nnmairix-mairix-update-options +Calls mairix binary for updating the database +(@code{nnmairix-update-database}). The default parameters are @code{-F} +and @code{-Q} for making this as fast as possible (see variable +@code{nnmairix-mairix-update-options} for defining these default +options). + +@item G b r +@kindex G b r (Group) +@findex nnmairix-group-toggle-readmarks-this-group +Keep articles in this @code{nnmairix} group always read or unread, or leave the +marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}). + +@item G b d +@kindex G b d (Group) +@findex nnmairix-group-delete-recreate-this-group +Recreate @code{nnmairix} group on the ``real'' mail back end +(@code{nnmairix-group-delete-recreate-this-group}). You can do this if +you always get wrong article counts with a @code{nnmairix} group. + +@item G b a +@kindex G b a (Group) +@findex nnmairix-group-toggle-allowfast-this-group +Toggles the @code{allow-fast} parameters for group under cursor +(@code{nnmairix-group-toggle-allowfast-this-group}). The default +behavior of @code{nnmairix} is to do a mairix search every time you +update or enter the group. With the @code{allow-fast} parameter set, +mairix will only be called when you explicitly update the group, but not +upon entering. This makes entering the group faster, but it may also +lead to dangling symlinks if something changed between updating and +entering the group which is not yet in the mairix database. + +@item G b p +@kindex G b p (Group) +@findex nnmairix-group-toggle-propmarks-this-group +Toggle marks propagation for this group +(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating +marks}). + +@item G b o +@kindex G b o (Group) +@findex nnmairix-propagate-marks +Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when +@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}. + +@end table + +In summary mode: + +@table @kbd + +@item $ m +@kindex $ m (Summary) +@findex nnmairix-widget-search-from-this-article +Allows you to create a mairix query or group based on the current +message using graphical widgets (same as @code{nnmairix-widget-search}) +(@code{nnmairix-widget-search-from-this-article}). + +@item $ g +@kindex $ g (Summary) +@findex nnmairix-create-search-group-from-message +Interactively creates a new search group with query based on the current +message, but uses the minibuffer instead of graphical widgets +(@code{nnmairix-create-search-group-from-message}). + +@item $ t +@kindex $ t (Summary) +@findex nnmairix-search-thread-this-article +Searches thread for the current article +(@code{nnmairix-search-thread-this-article}). This is effectively a +shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the +current article and enabled threads. + +@item $ f +@kindex $ f (Summary) +@findex nnmairix-search-from-this-article +Searches all messages from sender of the current article +(@code{nnmairix-search-from-this-article}). This is a shortcut for +calling @code{nnmairix-search} with @samp{f:From}. + +@item $ o +@kindex $ o (Summary) +@findex nnmairix-goto-original-article +(Only in @code{nnmairix} groups!) Tries determine the group this article +originally came from and displays the article in this group, so that +e.g. replying to this article the correct posting styles/group +parameters are applied (@code{nnmairix-goto-original-article}). This +function will use the registry if available, but can also parse the +article file name as a fallback method. + +@item $ u +@kindex $ u (Summary) +@findex nnmairix-remove-tick-mark-original-article +Remove possibly existing tick mark from original article +(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix +tips and tricks}). + +@end table + +@node Propagating marks +@subsection Propagating marks + +First of: you really need a patched mairix binary for using the marks +propagation feature efficiently. Otherwise, you would have to update +the mairix database all the time. You can get the patch at + +@uref{http://www.randomsample.de/mairix-maildir-patch.tar} + +You need the mairix v0.21 source code for this patch; everything else +is explained in the accompanied readme file. If you don't want to use +marks propagation, you don't have to apply these patches, but they also +fix some annoyances regarding changing maildir flags, so it might still +be useful to you. + +With the patched mairix binary, you can use @code{nnmairix} as an +alternative to mail splitting (@pxref{Fancy Mail Splitting}). For +example, instead of splitting all mails from @samp{david@@foobar.com} +into a group, you can simply create a search group with the query +@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are +all about: simply put everything in one mail folder and dynamically +create searches instead of splitting. This is more flexible, since you +can dynamically change your folders any time you want to. This also +implies that you will usually read your mails in the @code{nnmairix} +groups instead of your ``real'' mail groups. + +There is one problem, though: say you got a new mail from +@samp{david@@foobar.com}; it will now show up in two groups, the +``real'' group (your INBOX, for example) and in the @code{nnmairix} +search group (provided you have updated the mairix database). Now you +enter the @code{nnmairix} group and read the mail. The mail will be +marked as read, but only in the @code{nnmairix} group---in the ``real'' +mail group it will be still shown as unread. + +You could now catch up the mail group (@pxref{Group Data}), but this is +tedious and error prone, since you may overlook mails you don't have +created @code{nnmairix} groups for. Of course, you could first use +@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard +shortcuts}) and then read the mail in the original group, but that's +even more cumbersome. + +Clearly, the easiest way would be if marks could somehow be +automatically set for the original article. This is exactly what +@emph{marks propagation} is about. + +Marks propagation is deactivated by default. You can activate it for a +certain @code{nnmairix} group with +@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b +p}). This function will warn you if you try to use it with your default +search group; the reason is that the default search group is used for +temporary searches, and it's easy to accidentally propagate marks from +this group. However, you can ignore this warning if you really want to. + +With marks propagation enabled, all the marks you set in a @code{nnmairix} +group should now be propagated to the original article. For example, +you can now tick an article (by default with @kbd{!}) and this mark should +magically be set for the original article, too. + +A few more remarks which you may or may not want to know: + +@vindex nnmairix-propagate-marks-upon-close +Marks will not be set immediately, but only upon closing a group. This +not only makes marks propagation faster, it also avoids problems with +dangling symlinks when dealing with maildir files (since changing flags +will change the file name). You can also control when to propagate marks +via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for +details). + +Obviously, @code{nnmairix} will have to look up the original group for every +article you want to set marks for. If available, @code{nnmairix} will first use +the registry for determining the original group. The registry is very +fast, hence you should really, really enable the registry when using +marks propagation. If you don't have to worry about RAM and disc space, +set @code{gnus-registry-max-entries} to a large enough value; to be on +the safe side, choose roughly the amount of mails you index with mairix. + +@vindex nnmairix-only-use-registry +If you don't want to use the registry or the registry hasn't seen the +original article yet, @code{nnmairix} will use an additional mairix +search for determining the file name of the article. This, of course, is +way slower than the registry---if you set hundreds or even thousands of +marks this way, it might take some time. You can avoid this situation by +setting @code{nnmairix-only-use-registry} to t. + +Maybe you also want to propagate marks the other way round, i.e. if you +tick an article in a "real" mail group, you'd like to have the same +article in a @code{nnmairix} group ticked, too. For several good +reasons, this can only be done efficiently if you use maildir. To +immediately contradict myself, let me mention that it WON'T work with +@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and +not in the file name. Therefore, propagating marks to @code{nnmairix} +groups will usually only work if you use an IMAP server which uses +maildir as its file format. + +@vindex nnmairix-propagate-marks-to-nnmairix-groups +If you work with this setup, just set +@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what +happens. If you don't like what you see, just set it to @code{nil} again. One +problem might be that you get a wrong number of unread articles; this +usually happens when you delete or expire articles in the original +groups. When this happens, you can recreate the @code{nnmairix} group on the +back end using @kbd{G b d}. + +@node nnmairix tips and tricks +@subsection nnmairix tips and tricks + +@itemize +@item +Checking Mail + +@findex nnmairix-update-groups +I put all my important mail groups at group level 1. The mairix groups +have group level 5, so they do not get checked at start up (@pxref{Group +Levels}). + +I use the following to check for mails: + +@lisp +(defun my-check-mail-mairix-update (level) + (interactive "P") + ;; if no prefix given, set level=1 + (gnus-group-get-new-news (or level 1)) + (nnmairix-update-groups "mairixsearch" t t) + (gnus-group-list-groups)) + +(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update) +@end lisp + +Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix} +server. See the doc string for @code{nnmairix-update-groups} for +details. + +@item +Example: search group for ticked articles + +For example, you can create a group for all ticked articles, where the +articles always stay unread: + +Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use +@samp{F:f} as query and do not include threads. + +Now activate marks propagation for this group by using @kbd{G b p}. Then +activate the always-unread feature by using @kbd{G b r} twice. + +So far so good---but how do you remove the tick marks in the @code{nnmairix} +group? There are two options: You may simply use +@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove +tick marks from the original article. The other possibility is to set +@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above +comments about this option. If it works for you, the tick marks should +also exist in the @code{nnmairix} group and you can remove them as usual, +e.g. by marking an article as read. + +When you have removed a tick mark from the original article, this +article should vanish from the @code{nnmairix} group after you have updated the +mairix database and updated the group. Fortunately, there is a function +for doing exactly that: @code{nnmairix-update-groups}. See the previous code +snippet and the doc string for details. + +@item +Dealing with auto-subscription of mail groups + +As described before, all @code{nnmairix} groups are in fact stored on +the mail back end in the form @samp{zz_mairix-<NAME>-<NUMBER>}. You can +see them when you enter the back end server in the server buffer. You +should not subscribe these groups! Unfortunately, these groups will +usually get @emph{auto-subscribed} when you use @code{nnmaildir} or +@code{nnml}, i.e. you will suddenly see groups of the form +@samp{zz_mairix*} pop up in your group buffer. If this happens to you, +simply kill these groups with C-k. For avoiding this, turn off +auto-subscription completely by setting the variable +@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New +Groups}), or if you like to keep this feature use the following kludge +for turning it off for all groups beginning with @samp{zz_}: + +@lisp +(setq gnus-auto-subscribed-groups + "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*") +@end lisp + +@end itemize + +@node nnmairix caveats +@subsection nnmairix caveats + +@itemize +@item +You can create a secondary @code{nnml} server just for nnmairix, but then +you have to explicitly set the corresponding server variable +@code{nnml-get-new-mail} to @code{nil}. Otherwise, new mail might get +put into this secondary server (and would never show up again). Here's +an example server definition: + +@lisp +(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil)) +@end lisp + +(The @code{nnmaildir} back end also has a server variabe +@code{get-new-mail}, but its default value is @code{nil}, so you don't +have to explicitly set it if you use a @code{nnmaildir} server just for +mairix.) + +@item +If you use the Gnus registry: don't use the registry with +@code{nnmairix} groups (put them in +@code{gnus-registry-unfollowed-groups}; this is the default). Be +@emph{extra careful} if you use +@code{gnus-registry-split-fancy-with-parent}; mails which are split +into @code{nnmairix} groups are usually gone for good as soon as you +check the group for new mail (yes, it has happened to me...). + +@item +Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix} +groups (you shouldn't be able to, anyway). + +@item +If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize +@code{nnmairix} groups (though I have no idea what happens if you do). + +@item +mairix does only support us-ascii characters. + +@item +@code{nnmairix} uses a rather brute force method to force Gnus to +completely reread the group on the mail back end after mairix was +called---it simply deletes and re-creates the group on the mail +back end. So far, this has worked for me without any problems, and I +don't see how @code{nnmairix} could delete other mail groups than its +own, but anyway: you really should have a backup of your mail +folders. + +@item +All necessary information is stored in the group parameters +(@pxref{Group Parameters}). This has the advantage that no active file +is needed, but also implies that when you kill a @code{nnmairix} group, +it is gone for good. + +@item +@findex nnmairix-purge-old-groups +If you create and kill a lot of @code{nnmairix} groups, the +``zz_mairix-*'' groups will accumulate on the mail back end server. To +delete old groups which are no longer needed, call +@code{nnmairix-purge-old-groups}. Note that this assumes that you don't +save any ``real'' mail in folders of the form +@code{zz_mairix-<NAME>-<NUMBER>}. You can change the prefix of +@code{nnmairix} groups by changing the variable +@code{nnmairix-group-prefix}. + +@item +The following only applies if you @emph{don't} use the mentioned patch +for mairix (@pxref{Propagating marks}): + +A problem can occur when using @code{nnmairix} with maildir folders and +comes with the fact that maildir stores mail flags like @samp{Seen} or +@samp{Replied} by appending chars @samp{S} and @samp{R} to the message +file name, respectively. This implies that currently you would have to +update the mairix database not only when new mail arrives, but also when +mail flags are changing. The same applies to new mails which are indexed +while they are still in the @samp{new} folder but then get moved to +@samp{cur} when Gnus has seen the mail. If you don't update the database +after this has happened, a mairix query can lead to symlinks pointing to +non-existing files. In Gnus, these messages will usually appear with +``(none)'' entries in the header and can't be accessed. If this happens +to you, using @kbd{G b u} and updating the group will usually fix this. + +@end itemize + @iftex @iflatex @chapter Message @@ -22804,9 +22153,7 @@ four days, Gnus will decay the scores four times, for instance. * 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. @@ -22890,8 +22237,11 @@ 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. +questions by Gnus. It will simply assume you know what you're doing, +no matter how strange. For example, quitting Gnus, exiting a group +without an update, catching up with a group, deleting expired +articles, and replying by mail to a news message will not require +confirmation. @item gnus-interactive-catchup @vindex gnus-interactive-catchup @@ -23263,8 +22613,7 @@ glitches. Use at your own peril. 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)))) +((group (vertical 1.0 (group 1.0 point))) (article (vertical 1.0 (summary 0.25 point) (article 1.0)))) @end lisp @@ -23302,7 +22651,6 @@ 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 @@ -23313,20 +22661,16 @@ 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}. +be used as a split. 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)) + (group 1.0)) (vertical 1.0 (summary 0.25 point) - (summary-carpal 4) (article 1.0)))) @end lisp @@ -23490,6 +22834,81 @@ 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 Window Configuration Names + +Here's a list of most of the currently known window configurations, +and when they're used: + +@table @code +@item group +The group buffer. + +@item summary +Entering a group and showing only the summary. + +@item article +Selecting an article. + +@item server +The server buffer. + +@item browse +Browsing groups from the server buffer. + +@item message +Composing a (new) message. + +@item only-article +Showing only the article buffer. + +@item edit-article +Editing an article. + +@item edit-form +Editing group parameters and the like. + +@item edit-score +Editing a server definition. + +@item post +Composing a news message. + +@item reply +Replying or following up an article without yanking the text. + +@item forward +Forwarding a message. + +@item reply-yank +Replying or following up an article with yanking the text. + +@item mail-bound +Bouncing a message. + +@item pipe +Sending an article to an external process. + +@item bug +Sending a bug report. + +@item score-trace +Displaying the score trace. + +@item score-words +Displaying the score words. + +@item split-trace +Displaying the split trace. + +@item compose-bounce +Composing a bounce message. + +@item mml-preview +Previewing a @acronym{MIME} part. + +@end table + + @subsection Example Window Configurations @itemize @bullet @@ -23703,62 +23122,6 @@ 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 are 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 @@ -23822,13 +23185,12 @@ your @file{~/.gnus.el} file: (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-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 @@ -23847,152 +23209,6 @@ is a sure-fire way of getting booted off any respectable system. So behave. -@node NoCeM -@section NoCeM -@cindex nocem -@cindex spam - -@dfn{Spamming} is posting the same article lots and lots of times. -Spamming is bad. Spamming is evil. - -Spamming is usually canceled within a day or so by various anti-spamming -agencies. These agencies usually also send out @dfn{NoCeM} messages. -NoCeM is pronounced ``no see-'em'', and means what the name -implies---these are messages that make the offending articles, like, go -away. - -What use are these NoCeM messages if the articles are canceled anyway? -Some sites do not honor cancel messages and some sites just honor cancels -from a select few people. Then you may wish to make use of the NoCeM -messages, which are distributed in the newsgroups -@samp{news.lists.filters}, @samp{alt.nocem.misc}, etc. - -Gnus can read and parse the messages in this group automatically, and -this will make spam disappear. - -There are some variables to customize, of course: - -@table @code -@item gnus-use-nocem -@vindex gnus-use-nocem -Set this variable to @code{t} to set the ball rolling. It is @code{nil} -by default. - -You can also set this variable to a positive number as a group level. -In that case, Gnus scans NoCeM messages when checking new news if this -value is not exceeding a group level that you specify as the prefix -argument to some commands, e.g. @code{gnus}, -@code{gnus-group-get-new-news}, etc. Otherwise, Gnus does not scan -NoCeM messages if you specify a group level that is smaller than this -value to those commands. For example, if you use 1 or 2 on the mail -groups and the levels on the news groups remain the default, 3 is the -best choice. - -@item gnus-nocem-groups -@vindex gnus-nocem-groups -Gnus will look for NoCeM messages in the groups in this list. The -default is -@lisp -("news.lists.filters" "alt.nocem.misc") -@end lisp - -@item gnus-nocem-issuers -@vindex gnus-nocem-issuers -There are many people issuing NoCeM messages. This list says what -people you want to listen to. The default is: - -@lisp -("Adri Verhoef" - "alba-nocem@@albasani.net" - "bleachbot@@httrack.com" - "news@@arcor-online.net" - "news@@uni-berlin.de" - "nocem@@arcor.de" - "pgpmoose@@killfile.org" - "xjsppl@@gmx.de") -@end lisp - -Known despammers that you can put in this list are listed at@* -@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}. - -You do not have to heed NoCeM messages from all these people---just the -ones you want to listen to. You also don't have to accept all NoCeM -messages from the people you like. Each NoCeM message has a @dfn{type} -header that gives the message a (more or less, usually less) rigorous -definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf}, -@samp{binary}, and @samp{troll}. To specify this, you have to use -@code{(@var{issuer} @var{conditions} @dots{})} elements in the list. -Each condition is either a string (which is a regexp that matches types -you want to use) or a list on the form @code{(not @var{string})}, where -@var{string} is a regexp that matches types you don't want to use. - -For instance, if you want all NoCeM messages from Chris Lewis except his -@samp{troll} messages, you'd say: - -@lisp -("clewis@@ferret.ocunix.on.ca" ".*" (not "troll")) -@end lisp - -On the other hand, if you just want nothing but his @samp{spam} and -@samp{spew} messages, you'd say: - -@lisp -("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam") -@end lisp - -The specs are applied left-to-right. - - -@item gnus-nocem-verifyer -@vindex gnus-nocem-verifyer -@findex gnus-nocem-epg-verify -@findex pgg-verify -This should be a function for verifying that the NoCeM issuer is who she -says she is. This variable defaults to @code{gnus-nocem-epg-verify} if -EasyPG is available, otherwise defaults to @code{pgg-verify}. The -function should return non-@code{nil} if the verification is successful, -otherwise (including the case the NoCeM message was not signed) should -return @code{nil}. If this is too slow and you don't care for -verification (which may be dangerous), you can set this variable to -@code{nil}. - -Formerly the default was @code{mc-verify}, which is a Mailcrypt -function. While you can still use it, you can change it into -@code{gnus-nocem-epg-verify} or @code{pgg-verify} running with GnuPG if -you are willing to add the @acronym{PGP} public keys to GnuPG's keyring. - -@item gnus-nocem-directory -@vindex gnus-nocem-directory -This is where Gnus will store its NoCeM cache files. The default is@* -@file{~/News/NoCeM/}. - -@item gnus-nocem-expiry-wait -@vindex gnus-nocem-expiry-wait -The number of days before removing old NoCeM entries from the cache. -The default is 15. If you make it shorter Gnus will be faster, but you -might then see old spam. - -@item gnus-nocem-check-from -@vindex gnus-nocem-check-from -Non-@code{nil} means check for valid issuers in message bodies. -Otherwise don't bother fetching articles unless their author matches a -valid issuer; that is much faster if you are selective about the -issuers. - -@item gnus-nocem-check-article-limit -@vindex gnus-nocem-check-article-limit -If non-@code{nil}, the maximum number of articles to check in any NoCeM -group. @code{nil} means no restriction. NoCeM groups can be huge and -very slow to process. - -@end table - -Using NoCeM could potentially be a memory hog. If you have many living -(i. e., subscribed or unsubscribed groups), your Emacs process will grow -big. If this is a problem, you should kill off all (or most) of your -unsubscribed groups (@pxref{Subscription Commands}). - - @node Undo @section Undo @cindex undo @@ -24126,6 +23342,7 @@ stuff, so Gnus has taken advantage of that. * 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. +* Gravatars:: Display the avatar of people you read. * XVarious:: Other XEmacsy Gnusey variables. @end menu @@ -24284,7 +23501,7 @@ specifications. The @code{gnus-face-properties-alist} variable affects the appearance of displayed Face images. @xref{X-Face}. -Viewing an @code{Face} header requires an Emacs that is able to display +Viewing a @code{Face} header requires an Emacs that is able to display PNG images. @c Maybe add this: @c (if (featurep 'xemacs) @@ -24452,8 +23669,59 @@ want to add @samp{"unknown"} to this list. Ordered list of suffixes on picon file names to try. Defaults to @code{("xpm" "gif" "xbm")} minus those not built-in your Emacs. +@item gnus-picon-inhibit-top-level-domains +@vindex gnus-picon-inhibit-top-level-domains +If non-@code{nil} (which is the default), don't display picons for +things like @samp{.net} and @samp{.de}, which aren't usually very +interesting. + +@end table + +@node Gravatars +@subsection Gravatars + +@iftex +@iflatex +\include{gravatars} +@end iflatex +@end iftex + +A gravatar is an image registered to an e-mail address. + +You can submit yours on-line at @uref{http://www.gravatar.com}. + +The following variables offer control over how things are displayed. + +@table @code + +@item gnus-gravatar-size +@vindex gnus-gravatar-size +The size in pixels of gravatars. Gravatars are always square, so one +number for the size is enough. + +@item gnus-gravatar-properties +@vindex gnus-gravatar-properties +List of image properties applied to Gravatar images. + +@item gnus-gravatar-too-ugly +@vindex gnus-gravatar-too-ugly +Regexp that matches mail addresses or names of people of which avatars +should not be displayed, or @code{nil}. It default to the value of +@code{gnus-article-x-face-too-ugly} (@pxref{X-Face}). + @end table +If you want to see them in the From field, set: +@lisp +(setq gnus-treat-from-gravatar 'head) +@end lisp + +If you want to see them in the Cc and To fields, set: + +@lisp +(setq gnus-treat-mail-gravatar 'head) +@end lisp + @node XVarious @subsection Various XEmacs Variables @@ -24789,7 +24057,7 @@ call the external tools during splitting. Example fancy split method: Note that with the nnimap back end, message bodies will not be downloaded by default. You need to set @code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Splitting in IMAP}). +(@pxref{Client-Side IMAP Splitting}). 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 @@ -24983,12 +24251,14 @@ yourself, so that the message is processed as spam when you exit the group: @table @kbd -@item M-d +@item $ +@itemx M-d @itemx M s x @itemx S x -@kindex M-d -@kindex S x -@kindex M s x +@kindex $ (Summary) +@kindex M-d (Summary) +@kindex S x (Summary) +@kindex M s x (Summary) @findex gnus-summary-mark-as-spam @findex gnus-summary-mark-as-spam Mark current article as spam, showing it with the @samp{$} mark @@ -25071,14 +24341,14 @@ the value @samp{spam} means @samp{nnimap+your-server:spam}. The value @vindex nnimap-split-download-body Note for IMAP users: if you use the @code{spam-check-bogofilter}, @code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, -you should also set the variable @code{nnimap-split-download-body} -to @code{t}. These spam back ends are most useful when they can -``scan'' the full message body. By default, the nnimap back end only -retrieves the message headers; @code{nnimap-split-download-body} tells -it to retrieve the message bodies as well. We don't set this by -default because it will slow @acronym{IMAP} down, and that is not an -appropriate decision to make on behalf of the user. @xref{Splitting -in IMAP}. +you should also set the variable @code{nnimap-split-download-body} to +@code{t}. These spam back ends are most useful when they can ``scan'' +the full message body. By default, the nnimap back end only retrieves +the message headers; @code{nnimap-split-download-body} tells it to +retrieve the message bodies as well. We don't set this by default +because it will slow @acronym{IMAP} down, and that is not an +appropriate decision to make on behalf of the user. @xref{Client-Side +IMAP Splitting}. 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 @@ -25363,8 +24633,8 @@ From Ted Zlatanov <tzz@@lifelogs.com>. 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!} + ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual} nnimap-split-fancy '(| ;; @r{trace references to parents and put in their group} (: gnus-registry-split-fancy-with-parent) @@ -26086,8 +25356,8 @@ messages stay in @samp{INBOX}: @example (setq spam-use-spamoracle t spam-split-group "Junk" + ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual} nnimap-split-inbox '("INBOX") - nnimap-split-rule 'nnimap-split-fancy nnimap-split-fancy '(| (: spam-split) "INBOX")) @end example @@ -26613,6 +25883,13 @@ the sender in addition to the Message-ID. Several strategies are available. @item +Refer to messages by ID + +Commands like @code{gnus-summary-refer-parent-article} can take +advantage of the registry to jump to the referred article, regardless +of the group the message is in. + +@item Store custom flags and keywords The registry can store custom flags and keywords for a message. For @@ -26629,20 +25906,20 @@ of all messages matching a particular set of criteria. @end enumerate @menu -* Setup:: +* Gnus Registry Setup:: * Fancy splitting to parent:: +* Registry Article Refer Method:: * Store custom flags and keywords:: * Store arbitrary data:: @end menu -@node Setup -@subsection Setup +@node Gnus Registry Setup +@subsection Gnus Registry Setup Fortunately, setting up the Gnus registry is pretty easy: @lisp -(setq gnus-registry-max-entries 2500 - gnus-registry-use-long-group-names t) +(setq gnus-registry-max-entries 2500) (gnus-registry-initialize) @end lisp @@ -26664,16 +25941,16 @@ what they do before you copy them blindly). ("spam" t) ("train" t)) gnus-registry-max-entries 500000 - gnus-registry-use-long-group-names t + ;; this is the default gnus-registry-track-extra '(sender subject)) @end lisp -They say: keep a lot of messages around, use long group names, track -messages by sender and subject (not just parent Message-ID), and when -the registry splits incoming mail, use a majority rule to decide where -messages should go if there's more than one possibility. In addition, -the registry should ignore messages in groups that match ``nntp'', -``nnrss'', ``spam'', or ``train.'' +They say: keep a lot of messages around, track messages by sender and +subject (not just parent Message-ID), and when the registry splits +incoming mail, use a majority rule to decide where messages should go +if there's more than one possibility. In addition, the registry +should ignore messages in groups that match ``nntp'', ``nnrss'', +``spam'', or ``train.'' You are doubtless impressed by all this, but you ask: ``I am a Gnus user, I customize to live. Give me more.'' Here you go, these are @@ -26683,19 +25960,9 @@ the general settings. The groups that will not be followed by @code{gnus-registry-split-fancy-with-parent}. They will still be remembered by the registry. This is a list of regular expressions. -@end defvar - -@defvar gnus-registry-ignored-groups -The groups that will not be remembered by the registry. This is a -list of regular expressions, also available through Group/Topic -customization (so you can ignore or keep a specific group or a whole -topic). -@end defvar - -@defvar gnus-registry-use-long-group-names -Whether the registry will use long group names. It's recommended to -set this to @code{t}, although everything works if you don't. Future -functionality will require it. +By default any group name that ends with ``delayed'', ``drafts'', +``queue'', or ``INBOX'', belongs to the nnmairix backend, or contains +the word ``archive'' is not followed. @end defvar @defvar gnus-registry-max-entries @@ -26703,10 +25970,52 @@ The number (an integer or @code{nil} for unlimited) of entries the registry will keep. @end defvar +@defvar gnus-registry-max-pruned-entries +The maximum number (an integer or @code{nil} for unlimited) of entries +the registry will keep after pruning. +@end defvar + @defvar gnus-registry-cache-file -The file where the registry will be stored between Gnus sessions. +The file where the registry will be stored between Gnus sessions. By +default the file name is @code{.gnus.registry.eioio} in the same +directory as your @code{.newsrc.eld}. @end defvar +@node Registry Article Refer Method +@subsection Fetching by @code{Message-ID} Using the Registry + +The registry knows how to map each @code{Message-ID} to the group it's +in. This can be leveraged to enhance the ``article refer method'', +the thing that tells Gnus how to look up an article given its +Message-ID (@pxref{Finding the Parent}). + +@vindex nnregistry +@vindex gnus-refer-article-method + +The @code{nnregistry} refer method does exactly that. It has the +advantage that an article may be found regardless of the group it's +in---provided its @code{Message-ID} is known to the registry. It can +be enabled by augmenting the start-up file with something along these +lines: + +@example +;; Keep enough entries to have a good hit rate when referring to an +;; article using the registry. Use long group names so that Gnus +;; knows where the article is. +(setq gnus-registry-max-entries 2500) + +(gnus-registry-initialize) + +(setq gnus-refer-article-method + '(current + (nnregistry) + (nnweb "gmane" (nnweb-type gmane)))) +@end example + +The example above instructs Gnus to first look up the article in the +current group, or, alternatively, using the registry, and finally, if +all else fails, using Gmane. + @node Fancy splitting to parent @subsection Fancy splitting to parent @@ -26739,9 +26048,8 @@ following variables. @defvar gnus-registry-track-extra This is a list of symbols, so it's best to change it from the -Customize interface. By default it's @code{nil}, but you may want to -track @code{subject} and @code{sender} as well when splitting by parent. -It may work for you. It can be annoying if your mail flow is large and +Customize interface. By default it's @code{(subject sender)}, which +may work for you. It can be annoying if your mail flow is large and people don't stick to the same groups. @end defvar @@ -26749,7 +26057,8 @@ people don't stick to the same groups. This is a symbol, so it's best to change it from the Customize interface. By default it's @code{nil}, but you may want to set it to @code{majority} or @code{first} to split by sender or subject based on -the majority of matches or on the first found. +the majority of matches or on the first found. I find @code{majority} +works best. @end defvar @node Store custom flags and keywords @@ -26777,6 +26086,21 @@ Call this function to mark an article with a custom registry mark. It will offer the available marks for completion. @end defun +You can use @code{defalias} to install a summary line formatting +function that will show the registry marks. There are two flavors of +this function, either showing the marks as single characters, using +their @code{:char} property, or showing the marks as full strings. + +@lisp +;; show the marks as single characters (see the :char property in +;; `gnus-registry-marks'): +;; (defalias 'gnus-user-format-function-M 'gnus-registry-user-format-function-M) + +;; show the marks by name (see `gnus-registry-marks'): +;; (defalias 'gnus-user-format-function-M 'gnus-registry-user-format-function-M2) +@end lisp + + @node Store arbitrary data @subsection Store arbitrary data @@ -26784,17 +26108,12 @@ The registry has a simple API that uses a Message-ID as the key to store arbitrary data (as long as it can be converted to a list for storage). -@defun gnus-registry-store-extra-entry (id key value) -Store @code{value} in the extra data key @code{key} for message -@code{id}. -@end defun - -@defun gnus-registry-delete-extra-entry (id key) -Delete the extra data key @code{key} for message @code{id}. +@defun gnus-registry-set-id-key (id key value) +Store @code{value} under @code{key} for message @code{id}. @end defun -@defun gnus-registry-fetch-extra (id key) -Get the extra data key @code{key} for message @code{id}. +@defun gnus-registry-get-id-key (id key) +Get the data under @code{key} for message @code{id}. @end defun @defvar gnus-registry-extra-entries-precious @@ -27406,7 +26725,7 @@ wrong show. Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. @item -Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, webmail.el, +Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.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. @@ -27792,10 +27111,6 @@ 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}). @@ -27841,10 +27156,6 @@ Buttons}). 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 @@ -27940,8 +27251,7 @@ 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}). +Gnus has a new back end (@code{nnsoup}) to create/read SOUP packets. @item The Gnus cache is much faster. @@ -28000,13 +27310,6 @@ Mail can be re-scanned by a daemonic process (@pxref{Daemons}). @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 @@ -28522,9 +27825,7 @@ The revised Gnus @acronym{FAQ} is included in the manual, @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. +@acronym{NNTP} via @file{tls.el} and GNUTLS. @item Improved anti-spam features. @@ -29502,11 +28803,9 @@ Gnus not to use @acronym{NOV}. As the variables for the other back ends, there are @code{nndiary-nov-is-evil}, @code{nndir-nov-is-evil}, @code{nnfolder-nov-is-evil}, @code{nnimap-nov-is-evil}, -@code{nnml-nov-is-evil}, @code{nnspool-nov-is-evil}, and -@code{nnwarchive-nov-is-evil}. Note that a non-@code{nil} value for -@code{gnus-nov-is-evil} overrides all those variables.@footnote{Although -the back ends @code{nnkiboze}, @code{nnslashdot}, @code{nnultimate}, and -@code{nnwfm} don't have their own nn*-nov-is-evil.} +@code{nnml-nov-is-evil}, and @code{nnspool-nov-is-evil}. Note that a +non-@code{nil} value for @code{gnus-nov-is-evil} overrides all those +variables. @end table @@ -30104,7 +29403,7 @@ group and article numbers are when fetching articles by on successful article retrieval. -@item (nnchoke-request-group GROUP &optional SERVER FAST) +@item (nnchoke-request-group GROUP &optional SERVER FAST INFO) Get data on @var{group}. This function also has the side effect of making @var{group} the current group. @@ -30112,6 +29411,9 @@ making @var{group} the current group. If @var{fast}, don't bother to return useful data, just make @var{group} the current group. +If @var{info}, it allows the backend to update the group info +structure. + Here's an example of some result data and a definition of the same: @example @@ -31300,11 +30602,11 @@ that means: (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: +On the other hand, if the manual says ``set @code{gnus-nntp-server-file} to +@samp{/etc/nntpserver}'', that means: @lisp -(setq gnus-nntp-server "nntp.ifi.uio.no") +(setq gnus-nntp-server-file "/etc/nntpserver") @end lisp So be careful not to mix up strings (the latter) with symbols (the @@ -31337,7 +30639,3 @@ former). The manual is unambiguous, but it can be confusing. @c mode: texinfo @c coding: iso-8859-1 @c End: - -@ignore - arch-tag: c9fa47e7-78ca-4681-bda9-9fef45d1c819 -@end ignore diff --git a/doc/misc/gpl.texi b/doc/misc/gpl.texi index 5b416d3cb4..1908d1f8f9 100644 --- a/doc/misc/gpl.texi +++ b/doc/misc/gpl.texi @@ -715,7 +715,3 @@ library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. - -@ignore - arch-tag: 0c4a2556-f87e-464f-9b1d-efd920fcaf67 -@end ignore diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 54088cef21..8e17230191 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -22,8 +22,7 @@ Emacs, and interacting with an IDL shell run as a subprocess. This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE @value{VERSION}. -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -58,6 +57,7 @@ developing GNU and promoting software freedom.'' @ifnottex @node Top, Introduction, (dir), (dir) +@top IDLWAVE IDLWAVE is a package which supports editing source code written in the Interactive Data Language (IDL), and running IDL as an inferior shell. @@ -4295,7 +4295,3 @@ IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}. @printindex cp @bye - -@ignore - arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492 -@end ignore diff --git a/doc/misc/info.texi b/doc/misc/info.texi index 03b9b64a39..68390a2f0c 100644 --- a/doc/misc/info.texi +++ b/doc/misc/info.texi @@ -14,8 +14,7 @@ This file describes how to use Info, the on-line, menu-driven GNU documentation system. -Copyright @copyright{} 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, -2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 1989, 1992, 1996-2011 Free Software Foundation, Inc. @quotation @@ -1508,7 +1507,3 @@ topics discussed in this document. @printindex cp @bye - -@ignore - arch-tag: 965c1638-01d6-4156-9227-b10418b9d8e8 -@end ignore diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index ff5cd922ea..d64f316cb7 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -6,7 +6,7 @@ @documentencoding ISO-8859-1 @copying -Copyright @copyright{} 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2008-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -349,7 +349,3 @@ And that's it! @bye - -@ignore - arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9 -@end ignore diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in index 942847976e..1e497fe309 100644 --- a/doc/misc/makefile.w32-in +++ b/doc/misc/makefile.w32-in @@ -1,7 +1,6 @@ #### -*- Makefile -*- for documentation other than the Emacs manual. -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 -# Free Software Foundation, Inc. +# Copyright (C) 2003-2011 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -27,8 +26,13 @@ srcdir=. infodir = $(srcdir)/../../info +## Directory with emacsver.texi. +## Currently only used by efaq; could be added to MAKEINFO. +emacsdir = $(srcdir)/../emacs + # The makeinfo program is part of the Texinfo distribution. -MAKEINFO = makeinfo --force +MAKEINFO = makeinfo +MAKEINFO_OPTS = --force -I$(emacsdir) MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat INFO_TARGETS = $(infodir)/ccmode \ $(infodir)/cl $(infodir)/dbus $(infodir)/dired-x \ @@ -43,7 +47,8 @@ INFO_TARGETS = $(infodir)/ccmode \ $(infodir)/org $(infodir)/url $(infodir)/speedbar \ $(infodir)/tramp $(infodir)/ses $(infodir)/smtpmail \ $(infodir)/flymake $(infodir)/newsticker $(infodir)/rcirc \ - $(infodir)/erc $(infodir)/remember $(infodir)/nxml-mode \ + $(infodir)/erc $(infodir)/ert \ + $(infodir)/remember $(infodir)/nxml-mode \ $(infodir)/epa $(infodir)/mairix-el $(infodir)/sasl \ $(infodir)/auth $(infodir)/eieio $(infodir)/ede \ $(infodir)/semantic $(infodir)/edt @@ -54,7 +59,8 @@ DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \ ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \ pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \ speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \ - newsticker.dvi rcirc.dvi erc.dvi remember.dvi nxml-mode.dvi \ + newsticker.dvi rcirc.dvi erc.dvi ert.dvi \ + remember.dvi nxml-mode.dvi \ epa.dvi mairix-el.dvi sasl.dvi auth.dvi eieio.dvi ede.dvi \ semantic.dvi edt.dvi INFOSOURCES = info.texi @@ -66,7 +72,7 @@ INFOSOURCES = info.texi TEXI2DVI = texi2dvi ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C + "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C info: $(INFO_TARGETS) @@ -88,65 +94,65 @@ $(infodir)/dir: # texi filename, contrary to GNU standards. $(infodir)/info: $(INFOSOURCES) - $(MAKEINFO) --no-split -o $@ info.texi + $(MAKEINFO) $(MAKEINFO_OPTS) --no-split -o $@ info.texi info.dvi: $(INFOSOURCES) $(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi $(infodir)/ccmode: cc-mode.texi - $(MAKEINFO) cc-mode.texi + $(MAKEINFO) $(MAKEINFO_OPTS) 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 + $(MAKEINFO) $(MAKEINFO_OPTS) 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 + $(MAKEINFO) $(MAKEINFO_OPTS) pcl-cvs.texi pcl-cvs.dvi: pcl-cvs.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/pcl-cvs.texi $(infodir)/eshell: eshell.texi - $(MAKEINFO) eshell.texi + $(MAKEINFO) $(MAKEINFO_OPTS) eshell.texi eshell.dvi: eshell.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/eshell.texi $(infodir)/cl: cl.texi - $(MAKEINFO) cl.texi + $(MAKEINFO) $(MAKEINFO_OPTS) cl.texi cl.dvi: cl.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/cl.texi $(infodir)/dbus: dbus.texi - $(MAKEINFO) dbus.texi + $(MAKEINFO) $(MAKEINFO_OPTS) dbus.texi dbus.dvi: dbus.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/dbus.texi $(infodir)/dired-x: dired-x.texi - $(MAKEINFO) dired-x.texi + $(MAKEINFO) $(MAKEINFO_OPTS) dired-x.texi dired-x.dvi: dired-x.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/dired-x.texi $(infodir)/ediff: ediff.texi - $(MAKEINFO) ediff.texi + $(MAKEINFO) $(MAKEINFO_OPTS) ediff.texi ediff.dvi: ediff.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ediff.texi $(infodir)/flymake: flymake.texi - $(MAKEINFO) flymake.texi + $(MAKEINFO) $(MAKEINFO_OPTS) flymake.texi flymake.dvi: flymake.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/flymake.texi $(infodir)/forms: forms.texi - $(MAKEINFO) forms.texi + $(MAKEINFO) $(MAKEINFO_OPTS) 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 + $(MAKEINFO) $(MAKEINFO_OPTS) gnus.texi gnus.dvi: gnus.texi sed -e "/@iflatex/,/@end iflatex/d" $(srcdir)/gnus.texi > gnustmp.texi $(ENVADD) $(TEXI2DVI) gnustmp.texi @@ -154,185 +160,190 @@ gnus.dvi: gnus.texi rm gnustmp.* # $(infodir)/message: message.texi - $(MAKEINFO) message.texi + $(MAKEINFO) $(MAKEINFO_OPTS) message.texi message.dvi: message.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/message.texi # $(infodir)/emacs-mime: emacs-mime.texi - $(MAKEINFO) --enable-encoding emacs-mime.texi + $(MAKEINFO) $(MAKEINFO_OPTS) --enable-encoding emacs-mime.texi emacs-mime.dvi: emacs-mime.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-mime.texi # $(infodir)/sieve: sieve.texi - $(MAKEINFO) sieve.texi + $(MAKEINFO) $(MAKEINFO_OPTS) sieve.texi sieve.dvi: sieve.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/sieve.texi # $(infodir)/pgg: pgg.texi - $(MAKEINFO) pgg.texi + $(MAKEINFO) $(MAKEINFO_OPTS) pgg.texi pgg.dvi: pgg.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/pgg.texi $(infodir)/mh-e: mh-e.texi - $(MAKEINFO) mh-e.texi + $(MAKEINFO) $(MAKEINFO_OPTS) mh-e.texi mh-e.dvi: mh-e.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/mh-e.texi $(infodir)/reftex: reftex.texi - $(MAKEINFO) reftex.texi + $(MAKEINFO) $(MAKEINFO_OPTS) reftex.texi reftex.dvi: reftex.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/reftex.texi $(infodir)/remember: remember.texi - $(MAKEINFO) remember.texi + $(MAKEINFO) $(MAKEINFO_OPTS) remember.texi remember.dvi: remember.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/remember.texi $(infodir)/sasl: sasl.texi - $(MAKEINFO) sasl.texi + $(MAKEINFO) $(MAKEINFO_OPTS) sasl.texi sasl.dvi: sasl.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/sasl.texi $(infodir)/sc: sc.texi - $(MAKEINFO) sc.texi + $(MAKEINFO) $(MAKEINFO_OPTS) sc.texi sc.dvi: sc.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/sc.texi $(infodir)/vip: vip.texi - $(MAKEINFO) vip.texi + $(MAKEINFO) $(MAKEINFO_OPTS) vip.texi vip.dvi: vip.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/vip.texi $(infodir)/viper: viper.texi - $(MAKEINFO) viper.texi + $(MAKEINFO) $(MAKEINFO_OPTS) viper.texi viper.dvi: viper.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/viper.texi $(infodir)/widget: widget.texi - $(MAKEINFO) widget.texi + $(MAKEINFO) $(MAKEINFO_OPTS) widget.texi widget.dvi: widget.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/widget.texi -$(infodir)/efaq: faq.texi - $(MAKEINFO) faq.texi -faq.dvi: faq.texi +$(infodir)/efaq: faq.texi $(emacsdir)/emacsver.texi + $(MAKEINFO) $(MAKEINFO_OPTS) faq.texi +faq.dvi: faq.texi $(emacsdir)/emacsver.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/faq.texi $(infodir)/autotype: autotype.texi - $(MAKEINFO) autotype.texi + $(MAKEINFO) $(MAKEINFO_OPTS) autotype.texi autotype.dvi: autotype.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/autotype.texi -$(infodir)/calc: calc.texi - $(MAKEINFO) calc.texi +$(infodir)/calc: calc.texi $(emacsdir)/emacsver.texi + $(MAKEINFO) $(MAKEINFO_OPTS) calc.texi -calc.dvi: calc.texi +calc.dvi: calc.texi $(emacsdir)/emacsver.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 + $(MAKEINFO) $(MAKEINFO_OPTS) --no-split idlwave.texi idlwave.dvi: idlwave.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/idlwave.texi $(infodir)/eudc: eudc.texi - $(MAKEINFO) eudc.texi + $(MAKEINFO) $(MAKEINFO_OPTS) eudc.texi eudc.dvi: eudc.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/eudc.texi $(infodir)/ebrowse: ebrowse.texi - $(MAKEINFO) ebrowse.texi + $(MAKEINFO) $(MAKEINFO_OPTS) ebrowse.texi ebrowse.dvi: ebrowse.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ebrowse.texi $(infodir)/woman: woman.texi - $(MAKEINFO) woman.texi + $(MAKEINFO) $(MAKEINFO_OPTS) woman.texi woman.dvi: woman.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/woman.texi $(infodir)/speedbar: speedbar.texi - $(MAKEINFO) speedbar.texi + $(MAKEINFO) $(MAKEINFO_OPTS) speedbar.texi speedbar.dvi: speedbar.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/speedbar.texi $(infodir)/tramp: tramp.texi - $(MAKEINFO) tramp.texi + $(MAKEINFO) $(MAKEINFO_OPTS) tramp.texi tramp.dvi: tramp.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/tramp.texi $(infodir)/ses: ses.texi - $(MAKEINFO) ses.texi + $(MAKEINFO) $(MAKEINFO_OPTS) ses.texi ses.dvi: ses.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ses.texi $(infodir)/smtpmail: smtpmail.texi - $(MAKEINFO) smtpmail.texi + $(MAKEINFO) $(MAKEINFO_OPTS) smtpmail.texi smtpmail.dvi: smtpmail.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/smtpmail.texi $(infodir)/org: org.texi - $(MAKEINFO) org.texi + $(MAKEINFO) $(MAKEINFO_OPTS) org.texi org.dvi: org.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/org.texi $(infodir)/url: url.texi - $(MAKEINFO) url.texi + $(MAKEINFO) $(MAKEINFO_OPTS) url.texi url.dvi: url.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/url.texi $(infodir)/newsticker: newsticker.texi - $(MAKEINFO) newsticker.texi + $(MAKEINFO) $(MAKEINFO_OPTS) newsticker.texi newsticker.dvi: newsticker.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi $(infodir)/nxml-mode: nxml-mode.texi - $(MAKEINFO) nxml-mode.texi + $(MAKEINFO) $(MAKEINFO_OPTS) nxml-mode.texi nxml-mod.dvi: nxml-mode.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/nxml-mode.texi $(infodir)/rcirc: rcirc.texi - $(MAKEINFO) rcirc.texi + $(MAKEINFO) $(MAKEINFO_OPTS) rcirc.texi rcirc.dvi: rcirc.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/rcirc.texi $(infodir)/erc: erc.texi - $(MAKEINFO) erc.texi + $(MAKEINFO) $(MAKEINFO_OPTS) erc.texi erc.dvi: erc.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/erc.texi +$(infodir)/ert: ert.texi + $(MAKEINFO) $(MAKEINFO_OPTS) ert.texi +ert.dvi: ert.texi + $(ENVADD) $(TEXI2DVI) $(srcdir)/ert.texi + $(infodir)/epa: epa.texi - $(MAKEINFO) epa.texi + $(MAKEINFO) $(MAKEINFO_OPTS) epa.texi epa.dvi: epa.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/epa.texi $(infodir)/mairix-el: mairix-el.texi - $(MAKEINFO) mairix-el.texi + $(MAKEINFO) $(MAKEINFO_OPTS) mairix-el.texi mairix-el.dvi: mairix-el.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/mairix-el.texi $(infodir)/auth: auth.texi - $(MAKEINFO) auth.texi + $(MAKEINFO) $(MAKEINFO_OPTS) auth.texi auth.dvi: auth.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/auth.texi $(infodir)/eieio: eieio.texi - $(MAKEINFO) eieio.texi + $(MAKEINFO) $(MAKEINFO_OPTS) eieio.texi eieio.dvi: eieio.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/eieio.texi $(infodir)/ede: ede.texi - $(MAKEINFO) ede.texi + $(MAKEINFO) $(MAKEINFO_OPTS) ede.texi ede.dvi: ede.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ede.texi $(infodir)/semantic: semantic.texi - $(MAKEINFO) semantic.texi + $(MAKEINFO) $(MAKEINFO_OPTS) semantic.texi semantic.dvi: semantic.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/semantic.texi $(infodir)/edt: edt.texi - $(MAKEINFO) edt.texi + $(MAKEINFO) $(MAKEINFO_OPTS) edt.texi edt.dvi: edt.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/edt.texi @@ -358,7 +369,7 @@ clean: mostlyclean $(infodir)/url* $(infodir)/org* \ $(infodir)/flymake* $(infodir)/newsticker* \ $(infodir)/sieve* $(infodir)/pgg* \ - $(infodir)/erc* $(infodir)/rcirc* \ + $(infodir)/erc* $(infodir)/ert* $(infodir)/rcirc* \ $(infodir)/remember* $(infodir)/nxml-mode* \ $(infodir)/epa* $(infodir)/sasl* \ $(infodir)/mairix-el* $(infodir)/auth* \ diff --git a/doc/misc/message.texi b/doc/misc/message.texi index cc17433326..48d0028e45 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -1,5 +1,7 @@ \input texinfo @c -*-texinfo-*- +@include gnus-overrides.texi + @setfilename ../../info/message @settitle Message Manual @synindex fn cp @@ -8,8 +10,7 @@ @copying This file documents Message, the Emacs message composition mode. -Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1996-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -35,7 +36,12 @@ developing GNU and promoting software freedom.'' @end iftex @titlepage +@ifset WEBHACKDEVEL +@title Message Manual (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title Message Manual +@end ifclear @author by Lars Magne Ingebrigtsen @page @@ -182,6 +188,37 @@ Addresses that match the @code{message-dont-reply-to-names} regular expression (or list of regular expressions) will be removed from the @code{Cc} header. A value of @code{nil} means exclude your name only. +@vindex message-prune-recipient-rules +@code{message-prune-recipient-rules} is used to prune the addresses +used when doing a wide reply. It's meant to be used to remove +duplicate addresses and the like. It's a list of lists, where the +first element is a regexp to match the address to trigger the rule, +and the second is a regexp that will be expanded based on the first, +to match addresses to be pruned. + +It's complicated to explain, but it's easy to use. + +For instance, if you get an email from @samp{foo@@example.org}, but +@samp{foo@@zot.example.org} is also in the @code{Cc} list, then your +wide reply will go out to both these addresses, since they are unique. + +To avoid this, do something like the following: + +@lisp +(setq message-prune-recipient-rules + '(("^\\([^@@]+\\)@@\\(.*\\)" "\\1@@.*[.]\\2"))) +@end lisp + +If, for instance, you want all wide replies that involve messages from +@samp{cvs@@example.org} to go to that address, and nowhere else (i.e., +remove all other recipients if @samp{cvs@@example.org} is in the +recipient list: + +@lisp +(setq message-prune-recipient-rules + '(("cvs@@example.org" "."))) +@end lisp + @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 @@ -855,6 +892,10 @@ Manual}). @cindex internationalized domain names @cindex non-ascii domain names +@acronym{IDNA} is a standard way to encode non-@acronym{ASCII} domain +names into a readable @acronym{ASCII} string. The details can be +found in RFC 3490. + 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}, @@ -1059,11 +1100,11 @@ the passphrase prompt. @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 +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}. +pgg, PGG Manual}), is included, but Mailcrypt is also supported. +@xref{PGP Compatibility}. @cindex gpg-agent Message internally calls GnuPG (the @command{gpg} command) to perform @@ -1118,11 +1159,8 @@ 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. +@code{pgg-default-scheme} to @code{pgp}). 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 @@ -1164,6 +1202,10 @@ 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{[...]}). +This is a format-spec string, and you can use @samp{%l} to say how +many lines were removed, and @samp{%c} to say how many characters were +removed. + @item C-c M-k @kindex C-c M-k @findex message-kill-address @@ -1422,8 +1464,10 @@ Allegedly. @item message-default-headers @vindex message-default-headers -This string is inserted at the end of the headers in all message -buffers. +Header lines to be inserted in outgoing messages before you edit the +message, so you can edit or delete their lines. If set to a string, it +is directly inserted. If set to a function, it is called and its +result is inserted. @item message-subject-re-regexp @vindex message-subject-re-regexp @@ -1645,7 +1689,8 @@ the problem will actually occur. @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. +in several parts. If it is @code{nil} (which is the default), the +size is unlimited. @end table @@ -1889,6 +1934,25 @@ posting a prepared news message. @section Insertion Variables @table @code +@item message-cite-style +@vindex message-cite-style +The overall style to be used when replying to messages. This controls +things like where the reply should be put relative to the original, +how the citation is formatted, where the signature goes, etc. + +Value is either @code{nil} (no variable overrides) or a let-style list +of pairs @code{(VARIABLE VALUE)} to override default values. + +See @code{gnus-posting-styles} to set this variable for specific +groups. Presets to impersonate popular mail agents are available in the +@code{message-cite-style-*} variables. + +@item message-cite-reply-position +@vindex message-cite-reply-position +Where the reply should be positioned. Available styles are +@code{traditional} to reply inline, @code{above} for top-posting, and +@code{below} for bottom-posting + @item message-ignored-cited-headers @vindex message-ignored-cited-headers All headers that match this regexp will be removed from yanked @@ -2257,8 +2321,7 @@ created. @item unique @item t -Create the new buffer with the name generated in the Message way. This -is the default. +Create the new buffer with the name generated in the Message way. @item unsent Similar to @code{unique} but the buffer name begins with "*unsent ". @@ -2274,7 +2337,7 @@ 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}. +The default value is @code{unsent}. @item message-max-buffers @vindex message-max-buffers @@ -2441,7 +2504,3 @@ basis of the new @code{Cc} header, except if this header is @bye @c End: - -@ignore - arch-tag: 16ab76af-a281-4e34-aed6-5624569f7601 -@end ignore diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 1759470199..43d7bc7455 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -24,8 +24,7 @@ This is version @value{VERSION}@value{EDITION} of @cite{The MH-E Manual}, last updated @value{UPDATED}. -Copyright @copyright{} 1995, 2001, 2002, 2003, 2005, 2006, 2007, 2008, - 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995, 2001-2003, 2005-2011 Free Software Foundation, Inc. @c This dual license has been agreed upon by the FSF. diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi index f01fe23a6e..c7d8224597 100644 --- a/doc/misc/newsticker.texi +++ b/doc/misc/newsticker.texi @@ -13,7 +13,7 @@ This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). @noindent -Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2004-2011 Free Software Foundation, Inc. @quotation @@ -315,7 +315,3 @@ Byte-compiling newsticker.el is recommended. @bye - -@ignore - arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0 -@end ignore diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi index 9ed8bcf88d..2760344041 100644 --- a/doc/misc/nxml-mode.texi +++ b/doc/misc/nxml-mode.texi @@ -8,7 +8,7 @@ This manual documents nxml-mode, an Emacs major mode for editing XML with RELAX NG support. -Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/org.texi b/doc/misc/org.texi index b42de909d0..a0ec20c403 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -1,10 +1,16 @@ + \input texinfo @c %**start of header @setfilename ../../info/org @settitle The Org Manual -@set VERSION 6.33x -@set DATE November 2009 +@set VERSION 7.4 +@set DATE December 2010 + +@c Use proper quote and backtick for code sections in PDF output +@c Cf. Texinfo manual 14.2 +@set txicodequoteundirected +@set txicodequotebacktick @c Version and Contact Info @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} @@ -15,22 +21,236 @@ @c %**end of header @finalout -@c Macro definitions + +@c ----------------------------------------------------------------------------- + +@c Macro definitions for commands and keys +@c ======================================= + +@c The behavior of the key/command macros will depend on the flag cmdnames +@c When set, commands names are shown. When clear, they are not shown. + +@set cmdnames + +@c Below we define the following macros for Org key tables: + +@c orgkey{key} A key item +@c orgcmd{key,cmd} Key with command name +@c xorgcmd{key,cmmand} Key with command name as @itemx +@c orgcmdnki{key,cmd} Like orgcmd, but do not index the key +@c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key +@c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or" +@c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but +@c different functions, so format as @itemx +@c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short" +@c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx +@c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands + +@c a key but no command +@c Inserts: @item key +@macro orgkey{key} +@kindex \key\ +@item @kbd{\key\} +@end macro + +@macro xorgkey{key} +@kindex \key\ +@itemx @kbd{\key\} +@end macro + +@c one key with a command +@c Inserts: @item KEY COMMAND +@macro orgcmd{key,command} +@ifset cmdnames +@kindex \key\ +@findex \command\ @iftex -@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} +@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key\ +@item @kbd{\key\} +@end ifclear +@end macro + +@c One key with one command, formatted using @itemx +@c Inserts: @itemx KEY COMMAND +@macro xorgcmd{key,command} +@ifset cmdnames +@kindex \key\ +@findex \command\ +@iftex +@itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key\ +@itemx @kbd{\key\} +@end ifclear +@end macro + +@c one key with a command, bit do not index the key +@c Inserts: @item KEY COMMAND +@macro orgcmdnki{key,command} +@ifset cmdnames +@findex \command\ +@iftex +@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@item @kbd{\key\} +@end ifclear +@end macro + +@c one key with a command, and special text to replace key in item +@c Inserts: @item TEXT COMMAND +@macro orgcmdtkc{text,key,command} +@ifset cmdnames +@kindex \key\ +@findex \command\ +@iftex +@item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key\ +@item @kbd{\text\} +@end ifclear +@end macro + +@c two keys with one command +@c Inserts: @item KEY1 or KEY2 COMMAND +@macro orgcmdkkc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} @end iftex -@macro Ie {} -I.e., +@ifnottex +@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} +@end ifclear +@end macro + +@c Two keys with one command name, but different functions, so format as +@c @itemx +@c Inserts: @item KEY1 +@c @itemx KEY2 COMMAND +@macro orgcmdkxkc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@item @kbd{\key1\} +@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key1\} +@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} +@itemx @kbd{\key2\} +@end ifclear @end macro -@macro ie {} -i.e., + +@c Same as previous, but use "or short" +@c Inserts: @item KEY1 or short KEY2 COMMAND +@macro orgcmdkskc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} +@end ifclear @end macro -@macro Eg {} -E.g., + +@c Same as previous, but use @itemx +@c Inserts: @itemx KEY1 or short KEY2 COMMAND +@macro xorgcmdkskc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} +@end ifclear @end macro -@macro eg {} -e.g., + +@c two keys with two commands +@c Inserts: @item KEY1 COMMAND1 +@c @itemx KEY2 COMMAND2 +@macro orgcmdkkcc{key1,key2,command1,command2} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command1\ +@findex \command2\ +@iftex +@item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\} +@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\} +@end iftex +@ifnottex +@item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\}) +@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} +@itemx @kbd{\key2\} +@end ifclear @end macro +@c ----------------------------------------------------------------------------- + +@iftex +@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} +@end iftex @c Subheadings inside a table. @macro tsubheading{text} @@ -45,7 +265,7 @@ e.g., @copying This manual is for Org version @value{VERSION}. -Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation +Copyright @copyright{} 2004-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -68,7 +288,7 @@ license to the document, as described in section 6 of the license. @dircategory Emacs editing modes @direntry -* Org Mode: (org). Outline-based notes management and organizer. +* Org Mode: (org). Outline-based notes management and organizer @end direntry @titlepage @@ -76,6 +296,7 @@ license to the document, as described in section 6 of the license. @subtitle Release @value{VERSION} @author by Carsten Dominik +with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye @c The following two commands start the copyright page. @page @@ -107,12 +328,14 @@ license to the document, as described in section 6 of the license. * Markup:: Prepare text for rich export * Exporting:: Sharing and publishing of notes * Publishing:: Create a web site of linked Org files +* Working With Source Code:: Export, evaluate, and tangle code blocks * Miscellaneous:: All the rest which did not fit elsewhere * Hacking:: How to hack your way around * MobileOrg:: Viewing and capture on a mobile device * History and Acknowledgments:: How Org came into being * Main Index:: An index of Org's concepts and features * Key Index:: Key bindings and where they are described +* Command and Function Index:: Command names and some internal functions * Variable Index:: Variables mentioned in the manual @detailmenu @@ -126,7 +349,7 @@ Introduction * Feedback:: Bug reports, ideas, patches etc. * Conventions:: Type-setting conventions in the manual -Document Structure +Document structure * Outlines:: Org is based on Outline mode * Headlines:: How to typeset Org tree headlines @@ -175,7 +398,7 @@ Internal links * Radio targets:: Make targets trigger links in plain text -TODO Items +TODO items * TODO basics:: Marking and displaying TODO entries * TODO extensions:: Workflow and assignments @@ -206,10 +429,10 @@ Tags * Setting tags:: How to assign tags to a headline * Tag searches:: Searching for combinations of tags -Properties and Columns +Properties and columns * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features +* Special properties:: Access to other Org-mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -226,19 +449,19 @@ Defining columns * Scope of column definitions:: Where defined, where valid? * Column attributes:: Appearance and content of a column -Dates and Times +Dates and times * Timestamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps * Deadlines and scheduling:: Planning your work * Clocking work time:: Tracking how long you spend on a task -* Resolving idle time:: Resolving time if you've been idle * Effort estimates:: Planning work effort in advance * Relative timer:: Notes with a running timer +* Countdown timer:: Starting a countdown timer for a task Creating timestamps -* The date/time prompt:: How Org mode helps you entering date and time +* The date/time prompt:: How Org-mode helps you entering date and time * Custom time format:: Making dates look different Deadlines and scheduling @@ -246,27 +469,38 @@ Deadlines and scheduling * Inserting deadline/schedule:: Planning items * Repeated tasks:: Items that show up again and again +Clocking work time + +* Clocking commands:: Starting and stopping a clock +* The clock table:: Detailed reports +* Resolving idle time:: Resolving time when you've been idle + Capture - Refile - Archive -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks * RSS Feeds:: Getting input from RSS feeds * Protocols:: External (e.g. Browser) access to Emacs and Org * Refiling notes:: Moving a tree from one place to another * Archiving:: What to do with finished projects -Remember +Capture + +* Setting up capture:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types -* Setting up Remember for Org:: 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 +Capture templates + +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context Archiving * Moving subtrees:: Moving a tree to an archive file -* Internal archiving:: Switch off a tree but keep i in the file +* Internal archiving:: Switch off a tree but keep it in the file -Agenda Views +Agenda views * Agenda files:: Files being searched for agenda information * Agenda dispatcher:: Keyboard access to agenda views @@ -304,6 +538,7 @@ Markup for rich export * Images and tables:: Tables and Images will be included * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document +* Index entries:: Making an index * Macro replacement:: Use macros to create complex output * Embedded LaTeX:: LaTeX can be freely used inside Org documents @@ -320,7 +555,7 @@ Structural markup elements * Horizontal rules:: Make a line * Comment lines:: What will *not* be exported -Embedded La@TeX{} +Embedded @LaTeX{} * Special symbols:: Greek letters and other symbols * Subscripts and superscripts:: Simple syntax for raising/lowering text @@ -333,10 +568,11 @@ Exporting * Selective export:: Using tags to select and exclude trees * Export options:: Per-file export settings * The export dispatcher:: How to access exporter commands -* ASCII export:: Exporting to plain ASCII +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO * iCalendar export:: Exporting in iCalendar format @@ -344,21 +580,23 @@ Exporting HTML export * HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode +* Quoting HTML tags:: Using direct HTML in Org-mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output +* Math formatting in HTML export:: Beautiful math also on the web * Text areas in HTML export:: An alternative way to show an example * CSS support:: Changing the appearance of the output -* Javascript support:: Info and Folding in a web browser +* JavaScript support:: Info and Folding in a web browser -La@TeX{} and PDF export +@LaTeX{} and PDF export * LaTeX/PDF export commands:: Which key invokes which commands -* Quoting LaTeX code:: Incorporating literal La@TeX{} code -* Sectioning structure:: Changing sectioning in La@TeX{} output -* Tables in LaTeX export:: Options for exporting tables to La@TeX{} -* Images in LaTeX export:: How to insert figures into La@TeX{} output +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal @LaTeX{} code +* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} +* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Beamer class export:: Turning the file into a presentation DocBook export @@ -384,17 +622,72 @@ Configuration * 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 +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages Sample configuration * Simple example:: One-component publishing * Complex example:: A multi-component publishing example +Working with source code + +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line + +Header arguments + +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments + +Using header arguments + +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values +* Header arguments in function calls:: The most specific level + +Specific header arguments + +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will + be collected and handled +* file:: Specify a path for file output +* dir:: Specify the default (possibly remote) + directory for code block execution +* exports:: Export code and/or results +* tangle:: Toggle tangling and specify file name +* comments:: Toggle insertion of comments in tangled + code files +* no-expand:: Turn off variable assignment and noweb + expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables +* shebang:: Make tangled files executable +* eval:: Limit evaluation of specific code blocks + Miscellaneous * Completion:: M-TAB knows what you need -* Speed keys:: Electic commands at the beginning of a headline +* Easy Templates:: Quick insertion of structural elements +* Speed keys:: Electric commands at the beginning of a headline +* Code evaluation security:: Org mode files evaluate inline code * Customization:: Adapting Org to your taste * In-buffer settings:: Overview of the #+KEYWORDS * The very busy C-c C-c key:: When in doubt, press C-c C-c @@ -413,7 +706,7 @@ Hacking * Add-on packages:: Available extensions * Adding hyperlink types:: New custom link types * Context-sensitive commands:: How to add functionality to such commands -* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs +* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views * Extracting agenda information:: Postprocessing of agenda information @@ -470,40 +763,39 @@ structured ASCII file, as HTML, or (TODO and agenda items only) as an iCalendar file. It can also serve as a publishing tool for a set of linked web pages. -An important design aspect that distinguishes Org from, for example, -Planner/Muse is that it encourages you to store every piece of information -only once. In Planner, you have project pages, day pages and possibly -other files, duplicating some information such as tasks. In Org, -you only have notes files. In your notes you mark entries as tasks, and -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. +As a project planning environment, Org works by adding metadata to outline +nodes. Based on this data, specific entries can be extracted in queries and +create dynamic @i{agenda views}. + +Org mode contains the Org Babel environment which allows you to work with +embedded source code blocks in a file, to facilitate code evaluation, +documentation, and tangling. + +Org's automatic, context-sensitive table editor with spreadsheet +capabilities can be integrated into any major mode by activating the +minor Orgtbl mode. Using a translation step, it can be used to maintain +tables in arbitrary file types, for example in @LaTeX{}. The structure +editing and list creation capabilities can be used outside Org with +the minor Orgstruct mode. Org keeps simple things simple. When first fired up, it should feel like a straightforward, easy to use outliner. Complexity is not imposed, but a large amount of functionality is available when you need -it. Org is a toolbox and can be used in different ways, for -example as: +it. Org is a toolbox and can be used in different ways and for different +ends, for example: @example @r{@bullet{} an outline extension with visibility cycling and structure editing} @r{@bullet{} an ASCII system and table editor for taking structured notes} -@r{@bullet{} an ASCII table editor with spreadsheet-like capabilities} @r{@bullet{} a TODO list editor} @r{@bullet{} a full agenda and planner with deadlines and work scheduling} @pindex GTD, Getting Things Done -@r{@bullet{} an environment to implement David Allen's GTD system} -@r{@bullet{} a basic database application} -@r{@bullet{} a simple hypertext system, with HTML and La@TeX{} export} +@r{@bullet{} an environment in which to implement David Allen's GTD system} +@r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export} @r{@bullet{} a publishing tool to create a set of interlinked webpages} +@r{@bullet{} an environment for literate programming} @end example -Org's automatic, context-sensitive table editor with spreadsheet -capabilities can be integrated into any major mode by activating the -minor Orgtbl mode. Using a translation step, it can be used to maintain -tables in arbitrary file types, for example in La@TeX{}. The structure -editing and list creation capabilities can be used outside Org with -the minor Orgstruct mode. @cindex FAQ There is a website for Org which provides links to the newest @@ -545,18 +837,6 @@ step for this directory: (setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) @end example -@sp 2 -@cartouche -XEmacs users now need to install the file @file{noutline.el} from -the @file{xemacs} sub-directory of the Org distribution. Use the -command: - -@example - make install-noutline -@end example -@end cartouche -@sp 2 - @noindent Now byte-compile the Lisp files with the shell command: @example @@ -600,14 +880,6 @@ Do not forget to activate Org as described in the following section. @cindex global key bindings @cindex key bindings, global -@iftex -@b{Important:} @i{If you use copy-and-paste to copy Lisp code from the -PDF documentation as viewed by some PDF viewers to your @file{.emacs} file, the -single-quote character comes out incorrectly and the code will not work. -You need to fix the single-quotes by hand, or copy from Info -documentation.} -@end iftex - Add the following lines to your @file{.emacs} file. The last three lines define @emph{global} keys for the commands @command{org-store-link}, @command{org-agenda}, and @command{org-iswitchb}---please choose suitable @@ -630,9 +902,9 @@ active. You can do this with either one of the following two lines (add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only @end lisp -@cindex Org mode, turning on +@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 +into Org-mode. As an alternative, make the first line of a file look like this: @example @@ -640,7 +912,7 @@ MY PROJECTS -*- mode: org; -*- @end example @vindex org-insert-mode-line-in-empty-file -@noindent which will select Org mode for this buffer no matter what +@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}. @@ -665,10 +937,15 @@ active region by using the mouse to select a region, or pressing If you find problems with Org, or if you have questions, remarks, or ideas about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. If you are not a member of the mailing list, your mail will be passed to the -list after a moderator has approved it. - -For bug reports, please provide as much information as possible, including -the version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org +list after a moderator has approved it@footnote{Please consider subscribing +to the mailing list, in order to minimize the work the mailing list +moderators have to do.}. + +For bug reports, please first try to reproduce the bug with the latest +version of Org available---if you are running an outdated version, it is +quite possible that the bug has been fixed already. If the bug persists, +prepare a report and provide as much information as possible, including the +version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org (@kbd{M-x org-version @key{RET}}), as well as the Org related setup in @file{.emacs}. The easiest way to do this is to use the command @example @@ -687,7 +964,7 @@ about: @item What did you expect to happen? @item What happened instead? @end enumerate -@noindent Thank you for helping to improve this mode. +@noindent Thank you for helping to improve this program. @subsubheading How to create a useful backtrace @@ -742,8 +1019,20 @@ User-defined properties are capitalized; built-in properties with special meaning are written with all capitals. @end table +The manual lists both the keys and the corresponding commands for accessing +functionality. Org mode often uses the same key for different functions, +depending on context. The command that is bound to such keys has a generic +name, like @code{org-metaright}. In the manual we will, wherever possible, +give the function that is internally called by the generic command. For +example, in the chapter on document structure, @kbd{M-@key{right}} will be +listed to call @code{org-do-demote}, while in the chapter on tables, it will +be listed to call org-table-move-column-right. + +If you prefer, you can compile the manual without the command names by +unsetting the flag @code{cmdnames} in @file{org.texi}. + @node Document Structure, Tables, Introduction, Top -@chapter Document Structure +@chapter Document structure @cindex document structure @cindex structure of document @@ -783,11 +1072,14 @@ command, @command{org-cycle}, which is bound to the @key{TAB} key. @cindex headlines @cindex outline tree @vindex org-special-ctrl-a/e +@vindex org-special-ctrl-k +@vindex org-ctrl-k-protect-subtree -Headlines define the structure of an outline tree. The headlines in -Org start with one or more stars, on the left margin@footnote{See -the variable @code{org-special-ctrl-a/e} to configure special behavior -of @kbd{C-a} and @kbd{C-e} in headlines.}. For example: +Headlines define the structure of an outline tree. The headlines in Org +start with one or more stars, on the left margin@footnote{See the variables +@code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and +@code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a}, +@kbd{C-e}, and @kbd{C-k} in headlines.}. For example: @example * Top level headline @@ -828,9 +1120,8 @@ Org uses just two commands, bound to @key{TAB} and @cindex folded, subtree visibility state @cindex children, subtree visibility state @cindex subtree, subtree visibility state -@table @kbd -@kindex @key{TAB} -@item @key{TAB} +@table @asis +@orgcmd{@key{TAB},org-cycle} @emph{Subtree cycling}: Rotate current subtree among the states @example @@ -852,8 +1143,7 @@ argument (@kbd{C-u @key{TAB}}), global cycling is invoked. @cindex overview, global visibility state @cindex contents, global visibility state @cindex show all, global visibility state -@kindex S-@key{TAB} -@item S-@key{TAB} +@orgcmd{S-@key{TAB},org-global-cycle} @itemx C-u @key{TAB} @emph{Global cycling}: Rotate the entire buffer among the states @@ -867,18 +1157,18 @@ CONTENTS view up to headlines of level N will be shown. Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field. @cindex show all, command -@kindex C-u C-u C-u @key{TAB} -@item C-u C-u C-u @key{TAB} +@orgcmd{C-u C-u C-u @key{TAB},show-all} Show all, including drawers. -@kindex C-c C-r -@item C-c C-r +@orgcmd{C-c C-r,org-reveal} Reveal context around point, showing the current entry, the following heading and the hierarchy above. Useful for working near a location that has been exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command (@pxref{Agenda commands}). With a prefix argument show, on each -level, all sibling headings. -@kindex C-c C-x b -@item C-c C-x b +level, all sibling headings. With double prefix arg, also show the entire +subtree of the parent. +@orgcmd{C-c C-k,show-branches} +Expose all the headings of the subtree, CONTENT view for just one subtree. +@orgcmd{C-c C-x b,org-tree-to-indirect-buffer} Show the current subtree in an indirect buffer@footnote{The indirect buffer @ifinfo @@ -920,9 +1210,8 @@ Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties and Columns}) will get their visibility adapted accordingly. Allowed values for this property are @code{folded}, @code{children}, @code{content}, and @code{all}. -@table @kbd -@kindex C-u C-u @key{TAB} -@item C-u C-u @key{TAB} +@table @asis +@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility} Switch back to the startup visibility of the buffer, i.e. whatever is requested by startup options and @samp{VISIBILITY} properties in individual entries. @@ -935,24 +1224,18 @@ entries. @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 +@table @asis +@orgcmd{C-c C-n,outline-next-visible-heading} Next heading. -@kindex C-c C-p -@item C-c C-p +@orgcmd{C-c C-p,outline-previous-visible-heading} Previous heading. -@kindex C-c C-f -@item C-c C-f +@orgcmd{C-c C-f,org-forward-same-level} Next heading same level. -@kindex C-c C-b -@item C-c C-b +@orgcmd{C-c C-b,org-backward-same-level} Previous heading same level. -@kindex C-c C-u -@item C-c C-u +@orgcmd{C-c C-u,outline-up-heading} Backward to higher level heading. -@kindex C-c C-j -@item C-c C-j +@orgcmd{C-c C-j,org-goto} 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: @@ -987,9 +1270,8 @@ See also the variable @code{org-goto-interface}. @cindex sorting, of subtrees @cindex subtrees, cut and paste -@table @kbd -@kindex M-@key{RET} -@item M-@key{RET} +@table @asis +@orgcmd{M-@key{RET},org-insert-heading} @vindex org-M-RET-may-split-line 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 @@ -1004,62 +1286,48 @@ the content of that line is made the new heading. If the command is used at the end of a folded subtree (i.e. behind the ellipses at the end of a headline), then a headline like the current one will be inserted after the end of the subtree. -@kindex C-@key{RET} -@item C-@key{RET} +@orgcmd{C-@key{RET},org-insert-heading-respect-content} Just like @kbd{M-@key{RET}}, except when adding a new heading below the current heading, the new heading is placed after the body instead of before it. This command works from anywhere in the entry. -@kindex M-S-@key{RET} -@item M-S-@key{RET} +@orgcmd{M-S-@key{RET},org-insert-todo-heading} @vindex org-treat-insert-todo-heading-as-state-change Insert new TODO entry with same level as current heading. See also the variable @code{org-treat-insert-todo-heading-as-state-change}. -@kindex C-S-@key{RET} -@item C-S-@key{RET} +@orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content} Insert new TODO entry with same level as current heading. Like @kbd{C-@key{RET}}, the new headline will be inserted after the current subtree. -@kindex @key{TAB} -@item @key{TAB} @r{in new, empty entry} +@orgcmd{@key{TAB},org-cycle} In a new entry with no text yet, the first @key{TAB} demotes the entry to become a child of the previous one. The next @key{TAB} makes it a parent, and so on, all the way to top level. Yet another @key{TAB}, and you are back to the initial level. -@kindex M-@key{left} -@item M-@key{left} +@orgcmd{M-@key{left},org-do-promote} Promote current heading by one level. -@kindex M-@key{right} -@item M-@key{right} +@orgcmd{M-@key{right},org-do-demote} Demote current heading by one level. -@kindex M-S-@key{left} -@item M-S-@key{left} +@orgcmd{M-S-@key{left},org-promote-subtree} Promote the current subtree by one level. -@kindex M-S-@key{right} -@item M-S-@key{right} +@orgcmd{M-S-@key{right},org-demote-subtree} Demote the current subtree by one level. -@kindex M-S-@key{up} -@item M-S-@key{up} +@orgcmd{M-S-@key{up},org-move-subtree-up} Move subtree up (swap with previous subtree of same level). -@kindex M-S-@key{down} -@item M-S-@key{down} +@orgcmd{M-S-@key{down},org-move-subtree-down} Move subtree down (swap with next subtree of same level). -@kindex C-c C-x C-w -@item C-c C-x C-w +@orgcmd{C-c C-x C-w,org-cut-subtree} Kill subtree, i.e. remove it from buffer but save in kill ring. With a numeric prefix argument N, kill N sequential subtrees. -@kindex C-c C-x M-w -@item C-c C-x M-w +@orgcmd{C-c C-x M-w,org-copy-subtree} Copy subtree to kill ring. With a numeric prefix argument N, copy the N sequential subtrees. -@kindex C-c C-x C-y -@item C-c C-x C-y +@orgcmd{C-c C-x C-y,org-paste-subtree} Yank subtree from kill ring. This does modify the level of the subtree to make sure the tree fits in nicely at the yank position. The yank level can also be specified with a numeric prefix argument, or by yanking after a headline marker like @samp{****}. -@kindex C-y -@item C-y +@orgcmd{C-y,org-yank} @vindex org-yank-adjusted-subtrees @vindex org-yank-folded-subtrees Depending on the variables @code{org-yank-adjusted-subtrees} and @@ -1072,19 +1340,16 @@ previously visible. Any prefix argument to this command will force a normal force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a yank, it will yank previous kill items plainly, without adjustment and folding. -@kindex C-c C-x c -@item C-c C-x c +@orgcmd{C-c C-x c,org-clone-subtree-with-time-shift} Clone a subtree by making a number of sibling copies of it. You will be prompted for the number of copies to make, and you can also specify if any timestamps in the entry should be shifted. This can be useful, for example, to create a number of tasks related to a series of lectures to prepare. For more details, see the docstring of the command @code{org-clone-subtree-with-time-shift}. -@kindex C-c C-w -@item C-c C-w +@orgcmd{C-c C-w,org-refile} Refile entry or region to a different location. @xref{Refiling notes}. -@kindex C-c ^ -@item C-c ^ +@orgcmd{C-c ^,org-sort-entries-or-items} 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 @@ -1095,14 +1360,11 @@ of a property. Reverse sorting is possible as well. You can also supply your own function to extract the sorting key. With a @kbd{C-u} prefix, sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes, duplicate entries will also be removed. -@kindex C-x n s -@item C-x n s +@orgcmd{C-x n s,org-narrow-to-subtree} Narrow buffer to current subtree. -@kindex C-x n w -@item C-x n w +@orgcmd{C-x n w,widen} Widen buffer to remove narrowing. -@kindex C-c * -@item C-c * +@orgcmd{C-c *,org-toggle-heading} Turn a normal line or plain list item into a headline (so that it becomes a subheading at its location). Also turn a headline into a normal line by removing the stars. If there is an active region, turn all lines in the @@ -1134,7 +1396,7 @@ functionality. @vindex org-show-following-heading @vindex org-show-siblings @vindex org-show-entry-below -An important feature of Org mode is the ability to construct @emph{sparse +An important feature of Org-mode is the ability to construct @emph{sparse trees} for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it@footnote{See also the @@ -1143,15 +1405,13 @@ variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, control on how much context is shown around each match.}. Just try it out and you will see immediately how it works. -Org mode contains several commands creating such trees, all these +Org-mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: -@table @kbd -@kindex C-c / -@item C-c / +@table @asis +@orgcmd{C-c /,org-sparse-tree} This prompts for an extra key to select a sparse-tree creating command. -@kindex C-c / r -@item C-c / r +@orgcmd{C-c / r,org-occur} @vindex org-remove-highlights-with-change 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 @@ -1202,9 +1462,9 @@ part of the document and print the resulting file. @cindex ordered lists Within an entry of the outline tree, hand-formatted lists can provide -additional structure. They also provide a way to create lists of -checkboxes (@pxref{Checkboxes}). Org supports editing such lists, -and the HTML exporter (@pxref{Exporting}) parses and formats them. +additional structure. They also provide a way to create lists of checkboxes +(@pxref{Checkboxes}). Org supports editing such lists, and every exporter +(@pxref{Exporting}) can parse and format them. Org knows ordered lists, unordered lists, and description lists. @itemize @bullet @@ -1217,24 +1477,39 @@ visually indistinguishable from true headlines. In short: even though @samp{*} is supported, it may be better to not use it for plain list items.} as bullets. @item +@vindex org-plain-list-ordered-item-terminator @emph{Ordered} list items start with a numeral followed by either a period or -a right parenthesis, such as @samp{1.} or @samp{1)}. +a right parenthesis@footnote{You can filter out any of them by configuring +@code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or +@samp{1)}. If you want a list to start with a different value (e.g. 20), start +the text of the item with @code{[@@20]}@footnote{If there's a checkbox in the +item, the cookie must be put @emph{before} the checkbox.}. Those constructs +can be used in any item of the list in order to enforce a particular +numbering. @item @emph{Description} list items are unordered list items, and contain the separator @samp{ :: } to separate the description @emph{term} from the description. @end itemize -@vindex org-empty-line-terminates-plain-lists 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: +list. + +@vindex org-list-ending-method +@vindex org-list-end-regexp +@vindex org-empty-line-terminates-plain-lists +Two methods@footnote{To disable either of them, configure +@code{org-list-ending-method}.} are provided to terminate lists. A list ends +before the next line that is indented like the bullet/number or less, or it +ends before two blank lines@footnote{See also +@code{org-empty-line-terminates-plain-lists}.}. In both cases, all levels of +the list are closed@footnote{So you cannot have a sublist, some text and then +another sublist while still in the same top-level list item. This used to be +possible, but it was only supported in the HTML exporter and difficult to +manage with automatic indentation.}. For finer control, you can end lists +with any pattern set in @code{org-list-end-regexp}. Here is an example: @example @group @@ -1245,8 +1520,8 @@ Here is an example: + 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. + - on DVD only But in the end, no individual scenes matter but the film as a whole. Important actors in this film are: - @b{Elijah Wood} :: He plays Frodo @@ -1261,46 +1536,54 @@ XEmacs, you should use Kyle E. Jones' @file{filladapt.el}. To turn this on, put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting them properly (@pxref{Exporting}). Since indentation is what governs the structure of these lists, many structural constructs like @code{#+BEGIN_...} -blocks can be indented to signal that they should be part of a list item. +blocks can be indented to signal that they should be considered as a list +item. -The following commands act on items when the cursor is in the first line -of an item (the line with the bullet or number). +@vindex org-list-demote-modify-bullet +If you find that using a different bullet for a sub-list (than that used for +the current list-level) improves readability, customize the variable +@code{org-list-demote-modify-bullet}. -@table @kbd -@kindex @key{TAB} -@item @key{TAB} +@vindex org-list-automatic-rules +The following commands act on items when the cursor is in the first line of +an item (the line with the bullet or number). Some of them imply the +application of automatic rules to keep list structure intact. If some of +these actions get in your way, configure @code{org-list-automatic-rules} +to disable them individually. + +@table @asis +@orgcmd{@key{TAB},org-cycle} @vindex org-cycle-include-plain-lists Items can be folded just like headline levels. Normally this works only if the cursor is on a plain list item. For more details, see the variable -@code{org-cycle-include-plain-lists}. to @code{integrate}, plain list items -will be treated like low-level. The level of an item is then given by the +@code{org-cycle-include-plain-lists}. If this variable is set to +@code{integrate}, plain list items will be treated like low-level +headlines. The level of an item is then given by the indentation of the bullet/number. Items are always subordinate to real headlines, however; the hierarchies remain completely separated. - -If @code{org-cycle-include-plain-lists} has not been set, @key{TAB} -fixes the indentation of the current line in a heuristic way. -@kindex M-@key{RET} -@item M-@key{RET} +@orgcmd{M-@key{RET},org-insert-heading} @vindex org-M-RET-may-split-line +@vindex org-list-automatic-rules Insert new item at current level. With a prefix argument, force a new heading (@pxref{Structure editing}). If this command is used in the middle of a line, the line is @emph{split} and the rest of the line becomes the new item@footnote{If you do not want the line to be split, customize the variable -@code{org-M-RET-may-split-line}.}. If this command is executed in the -@emph{whitespace before a bullet or number}, the new item is created -@emph{before} the current item. If the command is executed in the white -space before the text that is part of an item but does not contain the -bullet, a bullet is added to the current line. +@code{org-M-RET-may-split-line}.}. If this command is executed @emph{before +an item's body}, 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. + +As a new item cannot be inserted in a structural construct (like an example +or source code block) within a list, Org will instead insert it right before +the structure, or return an error. @kindex M-S-@key{RET} @item M-S-@key{RET} Insert a new item with a checkbox (@pxref{Checkboxes}). -@kindex @key{TAB} -@item @key{TAB} @r{in new, empty item} +@orgcmd{@key{TAB},org-cycle} In a new item with no text yet, the first @key{TAB} demotes the item to -become a child of the previous one. The next @key{TAB} makes it a parent, -and so on, all the way to the left margin. Yet another @key{TAB}, and you -are back to the initial level. -@kindex S-@key{up} +become a child of the previous one. Subsequent @key{TAB}s move the item to +meaningful levels in the list and eventually get it back to its initial +position. @kindex S-@key{down} @item S-@key{up} @itemx S-@key{down} @@ -1317,30 +1600,45 @@ similar effect. 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-@key{left} +@kindex M-@key{right} +@item M-@key{left} +@itemx M-@key{right} +Decrease/increase the indentation of an item, leaving children alone. @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. +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. + +As a special case, using this command on the very first item of a list will +move the whole list. This behavior can be disabled by configuring +@code{org-list-automatic-rules}. The global indentation of a list has no +influence on the text @emph{after} the list. @kindex C-c C-c @item C-c C-c If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the -state of the checkbox. If not, this command makes sure that all the -items on this list level use the same bullet. Furthermore, if this is -an ordered list, make sure the numbering is OK. +state of the checkbox. Also, makes sure that all the +items on this list level use the same bullet and that the numbering of list +items (if applicable) is correct. @kindex C-c - +@vindex org-plain-list-ordered-item-terminator +@vindex org-list-automatic-rules @item C-c - Cycle the entire list level through the different itemize/enumerate bullets -(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). With a numeric prefix -argument N, select the Nth bullet from this list. If there is an active -region when calling this, all lines will be converted to list items. If the -first line already was a list item, any item markers will be removed from the -list. Finally, even without an active region, a normal line will be +(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them, +depending on @code{org-plain-list-ordered-item-terminator}, the type of list, +and its position@footnote{See @code{bullet} rule in +@code{org-list-automatic-rules} for more information.}. With a numeric +prefix argument N, select the Nth bullet from this list. If there is an +active region when calling this, all lines will be converted to list items. +If the first line already was a list item, any item markers will be removed +from the list. Finally, even without an active region, a normal line will be converted into a list item. @kindex C-c * @item C-c * @@ -1367,7 +1665,7 @@ numerically, alphabetically, by time, or by custom function. @vindex org-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}. +normally don't want to see it. For this, Org-mode has @emph{drawers}. Drawers need to be configured with the variable @code{org-drawers}@footnote{You can define drawers on a per-file basis with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers @@ -1385,10 +1683,17 @@ look like this: 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 the @code{PROPERTIES} drawer for +press @key{TAB} there. Org-mode uses the @code{PROPERTIES} drawer for storing properties (@pxref{Properties and Columns}), and you can also arrange for state change notes (@pxref{Tracking TODO state changes}) and clock times -(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. +(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you +want to store a quick note in the LOGBOOK drawer, in a similar way to state changes, use + +@table @kbd +@kindex C-c C-z +@item C-c C-z +Add a time-stamped note to the LOGBOOK drawer. +@end table @node Blocks, Footnotes, Drawers, Document Structure @section Blocks @@ -1413,13 +1718,13 @@ or on a per-file basis by using @section Footnotes @cindex footnotes -Org mode supports the creation of footnotes. In contrast to the -@file{footnote.el} package, Org mode's footnotes are designed for work on a +Org-mode supports the creation of footnotes. In contrast to the +@file{footnote.el} package, Org-mode's footnotes are designed for work on a larger document, not only for one-off documents like emails. The basic syntax is similar to the one used by @file{footnote.el}, i.e. a footnote is defined in a paragraph that is started by a footnote marker in square brackets in column 0, no indentation allowed. If you need a paragraph break -inside a footnote, use the La@TeX{} idiom @samp{\par}. The footnote reference +inside a footnote, use the @LaTeX{} idiom @samp{\par}. The footnote reference is simply the marker in square brackets, inside text. For example: @example @@ -1428,10 +1733,10 @@ The Org homepage[fn:1] now looks a lot better than it used to. [fn:1] The link is: http://orgmode.org @end example -Org mode extends the number-based syntax to @emph{named} footnotes and +Org-mode extends the number-based syntax to @emph{named} footnotes and optional inline definition. Using plain numbers as markers (as @file{footnote.el} does) is supported for backward compatibility, but not -encouraged because of possible conflicts with La@TeX{} snippets (@pxref{Embedded +encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded LaTeX}). Here are the valid references: @table @code @@ -1443,7 +1748,7 @@ snippet. A named footnote reference, where @code{name} is a unique label word, or, for simplicity of automatic creation, a number. @item [fn:: This is the inline definition of this footnote] -A La@TeX{}-like anonymous footnote where the definition is given directly at the +A @LaTeX{}-like anonymous footnote where the definition is given directly at the reference point. @item [fn:name: a definition] An inline definition of a footnote, which also specifies a name for the note. @@ -1454,7 +1759,7 @@ Since Org allows multiple references to the same note, you can then use @vindex org-footnote-auto-label Footnote labels can be created automatically, or you can create names yourself. This is handled by the variable @code{org-footnote-auto-label} and its -corresponding @code{#+STARTUP} keywords, see the docstring of that variable +corresponding @code{#+STARTUP} keywords. See the docstring of that variable for details. @noindent The following command handles footnotes: @@ -1522,7 +1827,7 @@ you can use the usual commands to follow these links. @cindex Orgstruct mode @cindex minor mode for structure editing -If you like the intuitive way the Org mode structure editing and list +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 @code{orgstruct-mode} makes this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or @@ -1537,7 +1842,7 @@ When this mode is active and the cursor is on a line that looks to Org like a headline or 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. When you use +lines, Orgstruct mode lurks silently in the shadows. When you use @code{orgstruct++-mode}, Org will also export indentation and autofill settings into that mode, and detect item context after the first line of an item. @@ -1548,8 +1853,7 @@ item. @cindex editing tables Org comes with a fast and intuitive table editor. Spreadsheet-like -calculations are supported in connection with the Emacs @file{calc} -package +calculations are supported using the Emacs @file{calc} package @ifinfo (@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). @end ifinfo @@ -1614,8 +1918,7 @@ unpredictable for you, configure the variables @table @kbd @tsubheading{Creation and conversion} -@kindex C-c | -@item C-c | +@orgcmd{C-c |,org-table-create-or-convert-from-region} Convert the active region to table. If every line contains at least one TAB character, the function assumes that the material is tab separated. If every line contains a comma, comma-separated values (CSV) are assumed. @@ -1629,74 +1932,55 @@ 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 +@orgcmd{C-c C-c,org-table-align} Re-align the table without moving the cursor. @c -@kindex @key{TAB} -@item @key{TAB} +@orgcmd{<TAB>,org-table-next-field} Re-align the table, move to the next field. Creates a new row if necessary. @c -@kindex S-@key{TAB} -@item S-@key{TAB} +@orgcmd{S-@key{TAB},org-table-previous-field} Re-align, move to previous field. @c -@kindex @key{RET} -@item @key{RET} +@orgcmd{@key{RET},org-table-next-row} 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. @c -@kindex M-a -@item M-a +@orgcmd{M-a,org-table-beginning-of-field} Move to beginning of the current table field, or on to the previous field. -@kindex M-e -@item M-e +@orgcmd{M-e,org-table-end-of-field} Move to end of the current table field, or on to the next field. @tsubheading{Column and row editing} -@kindex M-@key{left} -@kindex M-@key{right} -@item M-@key{left} -@itemx M-@key{right} +@orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right} Move the current column left/right. @c -@kindex M-S-@key{left} -@item M-S-@key{left} +@orgcmd{M-S-@key{left},org-table-delete-column} Kill the current column. @c -@kindex M-S-@key{right} -@item M-S-@key{right} +@orgcmd{M-S-@key{right},org-table-insert-column} 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} +@orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down} Move the current row up/down. @c -@kindex M-S-@key{up} -@item M-S-@key{up} +@orgcmd{M-S-@key{up},org-table-kill-row} Kill the current row or horizontal line. @c -@kindex M-S-@key{down} -@item M-S-@key{down} +@orgcmd{M-S-@key{down},org-table-insert-row} Insert a new row above the current row. With a prefix argument, the line is created below the current one. @c -@kindex C-c - -@item C-c - +@orgcmd{C-c -,org-table-insert-hline} Insert a horizontal line below current row. With a prefix argument, the line is created above the current line. @c -@kindex C-c @key{RET} -@item C-c @key{RET} +@orgcmd{C-c @key{RET},org-table-hline-and-move} Insert a horizontal line below current row, and move the cursor into the row below that line. @c -@kindex C-c ^ -@item C-c ^ +@orgcmd{C-c ^,org-table-sort-lines} 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 @@ -1708,35 +1992,30 @@ included into the sorting. The command prompts for the sorting type argument, alphabetic sorting will be case-sensitive. @tsubheading{Regions} -@kindex C-c C-x M-w -@item C-c C-x M-w +@orgcmd{C-c C-x M-w,org-table-copy-region} Copy a rectangular region from a table to a special clipboard. Point and mark determine edge fields of the rectangle. If there is no active region, copy just the current field. The process ignores horizontal separator lines. @c -@kindex C-c C-x C-w -@item C-c C-x C-w +@orgcmd{C-c C-x C-w,org-table-cut-region} 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 +@orgcmd{C-c C-x C-y,org-table-paste-rectangle} Paste a rectangular region into a table. The upper left corner ends up in the current field. All involved fields will be overwritten. If the rectangle does not fit into the present table, the table is enlarged as needed. The process ignores horizontal separator lines. @c -@kindex M-@key{RET} -@itemx M-@kbd{RET} -Wrap several fields in a column like a paragraph. If there is an active -region, and both point and mark are in the same column, the text in the -column is wrapped to minimum width for the given number of lines. A numeric -prefix argument may be used to change the number of desired lines. If there -is no region, the current field is split at the cursor position and the text -fragment to the right of the cursor is prepended to the field one line -down. If there is no region, but you specify a prefix argument, the current -field is made blank, and the content is appended to the field above. +@orgcmd{M-@key{RET},org-table-wrap-region} +Split the current field at the cursor position and move the rest to the line +below. If there is an active region, and both point and mark are in the same +column, the text in the column is wrapped to minimum width for the given +number of lines. A numeric prefix argument may be used to change the number +of desired lines. If there is no region, but you specify a prefix argument, +the current field is made blank, and the content is appended to the field +above. @tsubheading{Calculations} @cindex formula, in tables @@ -1744,14 +2023,12 @@ field is made blank, and the content is appended to the field above. @cindex region, active @cindex active region @cindex transient mark mode -@kindex C-c + -@item C-c + +@orgcmd{C-c +,org-table-sum} 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} +@orgcmd{S-@key{RET},org-table-copy-down} @vindex org-table-copy-increment 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. @@ -1762,8 +2039,7 @@ increment. This key is also used by shift-selection and related modes (@pxref{Conflicts}). @tsubheading{Miscellaneous} -@kindex C-c ` -@item C-c ` +@orgcmd{C-c `,org-table-edit-field} Edit the current field in a separate window. This is useful for fields that are not fully visible (@pxref{Column width and alignment}). When called with a @kbd{C-u} prefix, just make the full field visible, so that it can be @@ -1777,12 +2053,13 @@ 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 | +@orgcmd{C-c |,org-table-create-or-convert-from-region} Tables can also be imported by pasting tabular text into the Org buffer, selecting the pasted text with @kbd{C-x C-x} and then using the @kbd{C-c |} command (see above under @i{Creation and conversion}). @c @item M-x org-table-export +@findex org-table-export @vindex org-table-export-default-format Export the table, by default as a TAB-separated file. Use for data exchange with, for example, spreadsheet or database programs. The format @@ -1815,13 +2092,13 @@ The width of columns is automatically determined by the table editor. And also the alignment of a column is determined automatically from the fraction of number-like versus non-number fields in the column. -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{<N>} 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. +Sometimes a single field or a few fields need to carry more text, leading to +inconveniently wide columns. Or maybe you want to make a table with several +columns having a fixed width, regardless of content. To set@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{<N>} 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 this value. @example @group @@ -1837,7 +2114,7 @@ value. @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. +Note that the full text is still in the buffer but is hidden. 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 @@ -1858,9 +2135,13 @@ on a per-file basis with: @end example If you would like to overrule the automatic alignment of number-rich columns -to the right and of string-rich column to the left, you and use @samp{<r>} or -@samp{<l>} in a similar fashion. You may also combine alignment and field -width like this: @samp{<l10>}. +to the right and of string-rich column to the left, you can use @samp{<r>}, +@samp{c}@footnote{Centering does not work inside Emacs, but it does have an +effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may +also combine alignment and field width like this: @samp{<l10>}. + +Lines which only contain these formatting cookies will be removed +automatically when exporting the document. @node Column groups, Orgtbl mode, Column width and alignment, Tables @section Column groups @@ -1878,18 +2159,18 @@ a group of its own. Boundaries between column groups will upon export be marked with vertical lines. Here is an example: @example -| | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | -|---+----+-----+-----+-----+---------+------------| -| / | <> | < | | > | < | > | -| # | 1 | 1 | 1 | 1 | 1 | 1 | -| # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | -| # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | -|---+----+-----+-----+-----+---------+------------| -#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))) +| 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: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1))) @end example It is also sufficient to just insert the column group starters after -every vertical line you'd like to have: +every vertical line you would like to have: @example | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | @@ -1914,7 +2195,7 @@ example in mail mode, use 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 +construct @LaTeX{} tables with the underlying ease and power of Orgtbl mode, including spreadsheet capabilities. For details, see @ref{Tables in arbitrary syntax}. @@ -1926,11 +2207,13 @@ Orgtbl mode, including spreadsheet capabilities. For details, see The table editor makes use of the Emacs @file{calc} package to implement spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to -derive fields from other fields. While fully featured, Org's -implementation is not identical to other spreadsheets. For example, -Org knows the concept of a @emph{column formula} that will be -applied to all non-header fields in a column without having to copy the -formula to each relevant field. +derive fields from other fields. While fully featured, Org's implementation +is not identical to other spreadsheets. For example, Org knows the concept +of a @emph{column formula} that will be applied to all non-header fields in a +column without having to copy the formula to each relevant field. There is +also a formula debugger, and a formula editor with features for highlighting +fields in the table corresponding to the references at the point in the +formula, moving these references by arrow keys @menu * References:: How to refer to another field or range @@ -2038,6 +2321,28 @@ 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 Field coordinates in formulas +@cindex field coordinates +@cindex coordinates, of field +@cindex row, of field coordinates +@cindex column, of field coordinates + +For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to +get the row or column number of the field where the formula result goes. +The traditional Lisp formula equivalents are @code{org-table-current-dline} +and @code{org-table-current-column}. Examples: + +@example +if(@@# % 2, $#, string("")) @r{column number on odd lines only} +$3 = remote(FOO, @@@@#$2) @r{copy column 2 from table FOO into} + @r{column 3 of the current table} +@end example + +@noindent For the second example, table FOO must have at least as many rows +as the current table. Inefficient@footnote{The computation time scales as +O(N^2) because table FOO is parsed for each field to be copied.} for large +number of rows. + @subsubheading Named references @cindex named references @cindex references, named @@ -2127,8 +2432,11 @@ 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} +p20 @r{set the internal Calc calculation precision to 20 digits} +n3 s3 e2 f4 @r{Normal, scientific, engineering, or fixed} + @r{format of the result of Calc passed back to Org.} + @r{Calc formatting is unlimited in precision as} + @r{long as the Calc calculation precision is greater.} 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} @@ -2138,8 +2446,16 @@ L @r{literal} @end example @noindent -In addition, you may provide a @code{printf} format specifier to -reformat the final result. A few examples: +Unless you use large integer numbers or high-precision-calculation +and -display for floating point numbers you may alternatively provide a +@code{printf} format specifier to reformat the Calc result after it has been +passed back to Org instead of letting Calc already do the +formatting@footnote{The @code{printf} reformatting is limited in precision +because the value passed to it is converted into an @code{integer} or +@code{double}. The @code{integer} is limited in size by truncating the +signed value to 32 bits. The @code{double} is limited in precision to 64 +bits overall which leaves approximately 16 significant decimal digits.}. +A few examples: @example $1+$2 @r{Sum of first and second field} @@ -2152,7 +2468,7 @@ 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} +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 @@ -2165,24 +2481,23 @@ if($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty} @subsection Emacs Lisp forms as formulas @cindex Lisp forms, as table formulas -It is also possible to write a formula in Emacs Lisp; this can be useful -for string manipulation and control structures, if Calc's -functionality is not enough. If a formula starts with a single-quote -followed by an opening parenthesis, then it is evaluated as a Lisp form. -The evaluation should return either a string or a number. Just as with -@file{calc} formulas, you can specify modes and a printf format after a -semicolon. With Emacs Lisp forms, you need to be conscious about the way -field references are interpolated into the form. By default, a -reference will be interpolated as a Lisp string (in double-quotes) -containing the field. If you provide the @samp{N} mode switch, all -referenced elements will be numbers (non-number fields will be zero) and -interpolated as Lisp numbers, without quotes. If you provide the -@samp{L} flag, all fields will be interpolated literally, without quotes. -I.e., if you want a reference to be interpreted as a string by the Lisp -form, enclose the reference operator itself in double-quotes, like -@code{"$3"}. Ranges are inserted as space-separated fields, so you can -embed them in list or vector syntax. A few examples, note how the -@samp{N} mode is used when we do computations in Lisp. +It is also possible to write a formula in Emacs Lisp; this can be useful for +string manipulation and control structures, if Calc's functionality is not +enough. If a formula starts with a single-quote followed by an opening +parenthesis, then it is evaluated as a Lisp form. The evaluation should +return either a string or a number. Just as with @file{calc} formulas, you +can specify modes and a printf format after a semicolon. With Emacs Lisp +forms, you need to be conscious about the way field references are +interpolated into the form. By default, a reference will be interpolated as +a Lisp string (in double-quotes) containing the field. If you provide the +@samp{N} mode switch, all referenced elements will be numbers (non-number +fields will be zero) and interpolated as Lisp numbers, without quotes. If +you provide the @samp{L} flag, all fields will be interpolated literally, +without quotes. I.e., if you want a reference to be interpreted as a string +by the Lisp form, enclose the reference operator itself in double-quotes, +like @code{"$3"}. Ranges are inserted as space-separated fields, so you can ++embed them in list or vector syntax. Here are 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} @@ -2206,7 +2521,7 @@ evaluated, and the current field replaced with the result. @cindex #+TBLFM 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 +directly below the table. If you type 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 @@ -2220,8 +2535,7 @@ 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 = +@orgcmd{C-u C-c =,org-table-eval-formula} 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. @@ -2254,8 +2568,7 @@ Instead of typing an equation into the field, you may also use the following command: @table @kbd -@kindex C-c = -@item C-c = +@orgcmd{C-c =,org-table-eval-formula} 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 @@ -2278,32 +2591,29 @@ if possible. If you prefer to only work with the internal format (like @code{org-table-use-standard-references}. @table @kbd -@kindex C-c = -@kindex C-u C-c = -@item C-c = -@itemx C-u C-c = +@orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula} 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 = +@orgcmd{C-u C-u C-c =,org-table-eval-formula} 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 ? +@orgcmd{C-c ?,org-table-field-info} 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 @} +@findex org-table-toggle-coordinate-overlays @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}. +Toggle the display of row and column numbers for a table, using overlays +(@command{org-table-toggle-coordinate-overlays}). These are updated each +time the table is aligned; you can force it with @kbd{C-c C-c}. @kindex C-c @{ +@findex org-table-toggle-formula-debugger @item C-c @{ -Toggle the formula debugger on and off. See below. -@kindex C-c ' -@item C-c ' +Toggle the formula debugger on and off +(@command{org-table-toggle-formula-debugger}). See below. +@orgcmd{C-c ',org-table-edit-formulas} 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. @@ -2311,46 +2621,40 @@ While inside the special buffer, Org will automatically highlight any field or range reference at the cursor position. You may edit, remove and add formulas, and use the following commands: @table @kbd -@kindex C-c C-c -@kindex C-x C-s -@item C-c C-c -@itemx C-x C-s +@orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish} 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 +@orgcmd{C-c C-q,org-table-fedit-abort} Exit the formula editor without installing changes. -@kindex C-c C-r -@item C-c C-r +@orgcmd{C-c C-r,org-table-fedit-toggle-ref-type} Toggle all references in the formula editor between standard (like @code{B3}) and internal (like @code{@@3$2}). -@kindex @key{TAB} -@item @key{TAB} +@orgcmd{@key{TAB},org-table-fedit-lisp-indent} 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} +@orgcmd{M-@key{TAB},lisp-complete-symbol} 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} +@findex org-table-fedit-ref-up +@findex org-table-fedit-ref-down +@findex org-table-fedit-ref-left +@findex org-table-fedit-ref-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} +@orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down} Move the test line for column formulas in the Org buffer up and down. -@kindex M-@key{up} -@kindex M-@key{down} -@item M-@key{up}/@key{down} +@orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up} Scroll the window displaying the table. @kindex C-c @} +@findex org-table-toggle-coordinate-overlays @item C-c @} Turn the coordinate grid in the table on and off. @end table @@ -2390,8 +2694,7 @@ 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 * +@orgcmd{C-c *,org-table-recalculate} Recalculate the current row by first applying the stored column formulas from left to right, and all field formulas in the current row. @c @@ -2402,13 +2705,17 @@ from left to right, and all field formulas in the current row. 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 +@orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate} 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. +@item M-x org-table-recalculate-buffer-tables +@findex org-table-recalculate-buffer-tables +Recompute all tables in the current buffer. +@item M-x org-table-iterate-buffer-tables +@findex org-table-iterate-buffer-tables +Iterate all tables in the current buffer, in order to converge table-to-table +dependencies. @end table @node Advanced features, , Updating the table, The spreadsheet @@ -2418,8 +2725,7 @@ 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-# +@orgcmd{C-#,org-table-rotate-recalc-marks} Rotate the calculation mark in first column through the states @samp{ }, @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region, change all marks in the region. @@ -2516,7 +2822,7 @@ functions. @node Org-Plot, , The spreadsheet, Tables @section Org-Plot @cindex graph, in tables -@cindex plot tables using gnuplot +@cindex plot tables using Gnuplot @cindex #+PLOT Org-Plot can produce 2D and 3D graphs of information stored in org tables @@ -2575,8 +2881,8 @@ Defaults to @code{lines}. If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}. @item labels -List of labels to be used for the deps (defaults to the column headers if -they exist). +List of labels to be used for the @code{deps} (defaults to the column headers +if they exist). @item line Specify an entire line to be inserted in the Gnuplot script. @@ -2682,23 +2988,13 @@ text before the first headline is usually not exported, so the first such target should be after the first headline, or in the line directly before the first headline.}. -If no dedicated target exists, Org will search for the words in the link. In -the above example the search would be for @samp{my target}. Links starting -with a star like @samp{*My Target} restrict the search to -headlines@footnote{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.}. 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 - +If no dedicated target exists, Org will search for a headline that is exactly +the link text but may also include a TODO keyword and tags@footnote{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.}. In non-Org files, the search will look for the words in the +link text. In the above example the search would be for @samp{my target}. Following a link pushes a mark onto Org's own mark ring. You can return to the previous position with @kbd{C-c &}. Using this command @@ -2752,14 +3048,18 @@ the colon. The following list shows examples for each link type. @example http://www.astro.uva.nl/~dominik @r{on the web} +doi:10.1000/182 @r{DOI for an electronic resource} file:/home/dominik/images/jupiter.jpg @r{file, absolute path} /home/dominik/images/jupiter.jpg @r{same as above} file:papers/last.pdf @r{file, relative path} ./papers/last.pdf @r{same as above} +file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine} +/myself@@some.where:papers/last.pdf @r{same as above} file:sometextfile::NNN @r{file with line number to jump to} file:projects.org @r{another Org file} file:projects.org::some words @r{text search in Org file} file:projects.org::*task title @r{heading search in Org file} +docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} news:comp.emacs @r{Usenet link} mailto:adent@@galaxy.net @r{Mail link} @@ -2776,6 +3076,7 @@ gnus:group @r{Gnus group link} gnus:group#id @r{Gnus article link} bbdb:R.*Stallman @r{BBDB link (with regexp)} irc:/irc.com/#emacs/bob @r{IRC link} +info:org:External%20links @r{Info node link (with encoded space)} shell:ls *.org @r{A shell command} elisp:org-agenda @r{Interactive Elisp command} elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} @@ -2811,9 +3112,8 @@ Org provides methods to create a link in the correct syntax, to insert it into an Org file, and to follow the link. @table @kbd -@kindex C-c l +@orgcmd{C-c l,org-store-link} @cindex storing links -@item C-c l Store a link to the current location. This is a @emph{global} command (you must create the key binding yourself) which can be used in any buffer to create a link. The link will be stored for later insertion into an Org @@ -2869,11 +3169,10 @@ When the cursor is in an agenda view, the created link points to the entry referenced by the current line. @c -@kindex C-c C-l +@orgcmd{C-c C-l,org-insert-link} @cindex link completion @cindex completion, of links @cindex inserting links -@item C-c C-l @vindex org-keep-stored-link-after-insertion Insert a link@footnote{ Note that you don't have to use this command to insert a link. Links in Org are plain text, and you can type or paste them @@ -2903,10 +3202,9 @@ calling a special function @code{org-PREFIX-complete-link}.} For example, if you type @kbd{file @key{RET}}, file name completion (alternative access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb @key{RET}} you can complete contact names. -@kindex C-u C-c C-l +@orgkey 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 @@ -2916,14 +3214,12 @@ 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)} +@item C-c C-l @ @r{(with cursor on existing link)} When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the link and description parts of the link. @c @cindex following links -@kindex C-c C-o -@kindex RET -@item C-c C-o @r{or} @key{RET} +@orgcmd{C-c C-o,org-open-at-point} @vindex org-file-apps 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 @@ -2939,13 +3235,17 @@ visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid opening in Emacs, use a @kbd{C-u C-u} prefix.@* If the cursor is on a headline, but not on a link, offer all links in the headline and entry text. +@orgkey @key{RET} +@vindex org-return-follows-link +When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow +the link at point. @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, @kbd{mouse-1} will also follow a link. +would. Under Emacs 22 and later, @kbd{mouse-1} will also follow a link. @c @kindex mouse-3 @item mouse-3 @@ -2954,28 +3254,36 @@ 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 +@orgcmd{C-c C-x C-v,org-toggle-inline-images} +@cindex inlining images +@cindex images, inlining +@vindex org-startup-with-inline-images +@cindex @code{inlineimages}, STARTUP keyword +@cindex @code{noinlineimages}, STARTUP keyword +Toggle the inline display of linked images. Normally this will only inline +images that have no description part in the link, i.e. images that will also +be inlined during export. When called with a prefix argument, also display +images that do have a link description. You can ask for inline images to be +displayed at startup by configuring the variable +@code{org-startup-with-inline-images}@footnote{with corresponding +@code{#+STARTUP} keywords @code{inlineimages} and @code{inlineimages}}. +@orgcmd{C-c %,org-mark-ring-push} @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 +@orgcmd{C-c &,org-mark-ring-goto} @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 +@orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link} @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 +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 @@ -3013,20 +3321,22 @@ abbreviated link looks like this @noindent @vindex org-link-abbrev-alist -where the tag is optional. The @i{linkword} must be a word; letter, numbers, -@samp{-}, and @samp{_} are allowed here. Abbreviations are resolved +where the tag is optional. +The @i{linkword} must be a word, starting with a letter, followed by +letters, numbers, @samp{-}, and @samp{_}. 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 +@smalllisp @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"))) + ("gmap" . "http://maps.google.com/maps?q=%s") + ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") + ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST"))) @end group -@end lisp +@end smalllisp 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 @@ -3035,8 +3345,11 @@ be called with the tag as the only argument to create the link. With the above setting, you could link to a specific bug with @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with -@code{[[google:OrgMode]]} and find out what the Org author is -doing besides Emacs hacking with @code{[[ads:Dominik,C]]}. +@code{[[google:OrgMode]]}, show the map location of the Free Software +Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office +@code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out +what the Org author is doing besides Emacs hacking with +@code{[[ads:Dominik,C]]}. If you need special abbreviations just for a single Org buffer, you can define them in the file with @@ -3075,6 +3388,7 @@ link, together with an explanation: [[file:~/code/main.c::255]] [[file:~/xx.org::My Target]] [[file:~/xx.org::*My Target]] +[[file:~/xx.org::#my-custom-id]] [[file:~/xx.org::/regexp/]] @end example @@ -3089,10 +3403,12 @@ link will become an HTML reference to the corresponding named anchor in the linked file. @item *My Target In an Org file, restrict search to headlines. +@item #my-custom-id +Link to a heading with a @code{CUSTOM_ID} property @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 +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. @@ -3128,10 +3444,10 @@ for Bib@TeX{} database files, and you can use the corresponding code as an implementation example. See the file @file{org-bibtex.el}. @node TODO Items, Tags, Hyperlinks, Top -@chapter TODO Items +@chapter TODO items @cindex TODO items -Org mode does not maintain TODO lists as separate documents@footnote{Of +Org-mode does not maintain TODO lists as separate documents@footnote{Of course, you can make a document that contains only long lists of TODO items, but this is not required.}. Instead, TODO items are an integral part of the notes file, because TODO items usually come up while taking notes! With Org @@ -3140,7 +3456,7 @@ information is not duplicated, and the entire context from which the TODO item emerged is always present. Of course, this technique for managing TODO items scatters them -throughout your notes file. Org mode compensates for this by providing +throughout your notes file. Org-mode compensates for this by providing methods to give you an overview of all the things that you have to do. @menu @@ -3166,9 +3482,8 @@ Any headline becomes a TODO item when it starts with the word The most important commands to work with TODO entries are: @table @kbd -@kindex C-c C-t +@orgcmd{C-c C-t,org-todo} @cindex cycling, of TODO states -@item C-c C-t Rotate the TODO state of the current item among @example @@ -3179,8 +3494,7 @@ Rotate the TODO state of the current item among The same rotation can also be done ``remotely'' from the timeline and agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). -@kindex C-u C-c C-t -@item C-u C-c C-t +@orgkey{C-u C-c C-t} Select a specific keyword using completion or (if it has been set up) the fast selection interface. For the latter, you need to assign keys to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for @@ -3188,37 +3502,32 @@ more information. @kindex S-@key{right} @kindex S-@key{left} +@item S-@key{right} @ @r{/} @ S-@key{left} @vindex org-treat-S-cursor-todo-selection-as-state-change -@item S-@key{right} -@itemx S-@key{left} Select the following/preceding TODO state, similar to cycling. Useful mostly if more than two TODO states are possible (@pxref{TODO extensions}). See also @ref{Conflicts}, for a discussion of the interaction with @code{shift-selection-mode}. See also the variable @code{org-treat-S-cursor-todo-selection-as-state-change}. -@kindex C-c C-v -@kindex C-c / t +@orgcmd{C-c / t,org-show-todo-key} @cindex sparse tree, for TODO -@item C-c C-v -@itemx C-c / t @vindex org-todo-keywords View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the -entire buffer, but shows all TODO items and the headings hierarchy above -them. With a prefix argument, search for a specific TODO. You will be -prompted for the keyword, and you can also give a list of keywords like -@code{KWD1|KWD2|...} to list entries that match any one of these keywords. -With numeric prefix argument N, show the tree for the Nth keyword in the -variable @code{org-todo-keywords}. With two prefix arguments, find all TODO -and DONE entries. -@kindex C-c a t -@item C-c a t -Show the global TODO list. Collects the TODO items from all agenda -files (@pxref{Agenda Views}) into a single buffer. The new buffer will -be in @code{agenda-mode}, which provides commands to examine and -manipulate the TODO entries from the new buffer (@pxref{Agenda -commands}). @xref{Global TODO list}, for more information. -@kindex S-M-@key{RET} -@item S-M-@key{RET} +entire buffer, but shows all TODO items (with not-DONE state) and the +headings hierarchy above them. With a prefix argument (or by using @kbd{C-c +/ T}), 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|...} to list +entries that match any one of these keywords. With numeric prefix argument +N, show the tree for the Nth keyword in the variable +@code{org-todo-keywords}. With two prefix arguments, find all TODO states, +both un-done and done. +@orgcmd{C-c a t,org-todo-list} +Show the global TODO list. Collects the TODO items (with not-DONE states) +from all agenda files (@pxref{Agenda Views}) into a single buffer. The new +buffer will be in @code{agenda-mode}, which provides commands to examine and +manipulate the TODO entries from the new buffer (@pxref{Agenda commands}). +@xref{Global TODO list}, for more information. +@orgcmd{S-M-@key{RET},org-insert-todo-heading} Insert a new TODO entry below the current one. @end table @@ -3233,7 +3542,7 @@ option @code{org-todo-state-tags-triggers} for details. @vindex org-todo-keywords By default, marked TODO entries have one of only two states: TODO and -DONE. Org mode allows you to classify TODO items in more complex ways +DONE. Org-mode allows you to classify TODO items in more complex ways with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With special setup, the TODO keyword system can work differently in different files. @@ -3258,7 +3567,7 @@ TODO items in particular (@pxref{Tags}). 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 +this variable only becomes effective after restarting Org-mode in a buffer.}: @lisp @@ -3301,7 +3610,7 @@ be set up like this: 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 +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 @@ -3309,10 +3618,10 @@ 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 +by using a numeric prefix to @kbd{C-c / t}. For example, to see all things +Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items from all agenda files into a single buffer, you would use the numeric prefix -argument as well when creating the global TODO list: @kbd{C-3 C-c t}. +argument as well when creating the global TODO list: @kbd{C-3 C-c a t}. @node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions @subsection Multiple keyword sets in one file @@ -3332,7 +3641,7 @@ like this: (sequence "|" "CANCELED"))) @end lisp -The keywords should all be different, this helps Org mode to keep track +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 @@ -3429,9 +3738,9 @@ 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 +known to Org-mode@footnote{Org-mode parses these lines only when +Org-mode is activated after visiting a file. @kbd{C-c C-c} with the +cursor in a line starting with @samp{#+} is simply restarting Org-mode for the current buffer.}. @node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions @@ -3441,7 +3750,7 @@ for the current buffer.}. @vindex org-todo @r{(face)} @vindex org-done @r{(face)} @vindex org-todo-keyword-faces -Org mode highlights TODO keywords with special faces: @code{org-todo} +Org-mode highlights TODO keywords with special faces: @code{org-todo} for keywords indicating that an item still has to be acted upon, and @code{org-done} for keywords indicating that an item is finished. If you are using more than 2 different states, you might want to use @@ -3451,15 +3760,16 @@ special faces for some of them. This can be done using the variable @lisp @group (setq org-todo-keyword-faces - '(("TODO" . org-warning) - ("DEFERRED" . shadow) - ("CANCELED" . (:foreground "blue" :weight bold)))) + '(("TODO" . org-warning) ("STARTED" . "yellow") + ("CANCELED" . (:foreground "blue" :weight bold)))) @end group @end lisp -While using a list with face properties as shown for CANCELED -@emph{should} work, this does not aways seem to be the case. If -necessary, define a special face and use that. +While using a list with face properties as shown for CANCELED @emph{should} +work, this does not aways seem to be the case. If necessary, define a +special face and use that. A string is interpreted as a color. The variable +@code{org-faces-easy-properties} determines if that color is interpreted as a +foreground or a background color. @node TODO dependencies, , Faces for TODO keywords, TODO extensions @subsection TODO dependencies @@ -3494,8 +3804,7 @@ example: @end example @table @kbd -@kindex C-c C-x o -@item C-c C-x o +@orgcmd{C-c C-x o,org-toggle-ordered-property} @vindex org-track-ordered-property-with-tag @cindex property, ORDERED Toggle the @code{ORDERED} property of the current entry. A property is used @@ -3503,8 +3812,7 @@ for this behavior because this should be local to the current entry, not inherited like a tag. However, if you would like to @i{track} the value of this property with a tag for better visibility, customize the variable @code{org-track-ordered-property-with-tag}. -@kindex C-u C-u C-u C-c C-t -@item C-u C-u C-u C-c C-t +@orgkey{C-u C-u C-u C-c C-t} Change TODO state, circumventing any state blocking. @end table @@ -3530,7 +3838,7 @@ module @file{org-depend.el}. @cindex progress logging @cindex logging, of progress -Org mode can automatically record a timestamp and possibly a note when +Org-mode can automatically record a timestamp and possibly a note when you mark a TODO item as DONE, or even each time you change the state of a TODO item. This system is highly configurable, settings can be on a per-keyword basis and can be localized to a file or even a subtree. For @@ -3548,7 +3856,7 @@ work time}. The most basic logging is to keep track of @emph{when} a certain TODO item was finished. This is achieved with@footnote{The corresponding -in-buffer setting is: @code{#+STARTUP: logdone}}. +in-buffer setting is: @code{#+STARTUP: logdone}} @lisp (setq org-log-done 'time) @@ -3594,7 +3902,7 @@ behavior---the recommended drawer for this is called @code{LOGBOOK}. You can also overrule the setting of this variable for a subtree by setting a @code{LOG_INTO_DRAWER} property. -Since it is normally too much to record a note for every state, Org mode +Since it is normally too much to record a note for every state, Org-mode expects configuration on a per-keyword basis for this. This is achieved by adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note) in parentheses after each keyword. For example, with the setting @@ -3608,7 +3916,7 @@ in parentheses after each keyword. For example, with the setting @vindex org-log-done you not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to -DONE@footnote{It is possible that Org mode will record two timestamps +DONE@footnote{It is possible that Org-mode will record two timestamps when you are using both @code{org-log-done} and state change logging. However, it will never prompt for two notes---if you have configured both, the state change recording note will take precedence and cancel @@ -3668,7 +3976,10 @@ The habit is a TODO, with a TODO keyword representing an open state. @item The property @code{STYLE} is set to the value @code{habit}. @item -The TODO has a scheduled date, with a @code{.+} style repeat interval. +The TODO has a scheduled date, usually with a @code{.+} style repeat +interval. A @code{++} style may be appropriate for habits with time +constraints, e.g., must be done on weekends, or a @code{+} style for an +unusual habit that can have a backlog, e.g., weekly reports. @item The TODO may also have minimum and maximum ranges specified by using the syntax @samp{.+2d/3d}, which says that you want to do the task at least every @@ -3724,7 +4035,7 @@ If the task was going to be overdue the next day. If the task was overdue on that day. @end table -In addition to coloring each day, the day is also marked with an asterix if +In addition to coloring each day, the day is also marked with an asterisk if the task was actually done that day, and an exclamation mark to show where the current day falls in the graph. @@ -3754,38 +4065,37 @@ which should only be done in certain contexts, for example. @section Priorities @cindex priorities -If you use Org mode extensively, you may end up enough TODO items that +If you use Org-mode extensively, you may end up with enough TODO items that it starts to make sense to prioritize them. Prioritizing can be done by -placing a @emph{priority cookie} into the headline of a TODO item, like -this +placing a @emph{priority cookie} into the headline of a TODO item, like this @example *** TODO [#A] Write letter to Sam Fortune @end example @noindent -By default, Org mode supports three priorities: @samp{A}, @samp{B}, and -@samp{C}. @samp{A} is the highest priority. An entry without a cookie -is treated as priority @samp{B}. Priorities make a difference only in -the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they have -no inherent meaning to Org mode. +@vindex org-priority-faces +By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and +@samp{C}. @samp{A} is the highest priority. An entry without a cookie is +treated just like priority @samp{B}. Priorities make a difference only for +sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they +have no inherent meaning to Org-mode. The cookies can be highlighted with +special faces by customizing the variable @code{org-priority-faces}. -Priorities can be attached to any outline tree entries; they do not need -to be TODO items. +Priorities can be attached to any outline node; they do not need to be TODO +items. @table @kbd -@kindex @kbd{C-c ,} @item @kbd{C-c ,} -Set the priority of the current headline. The command prompts for a -priority character @samp{A}, @samp{B} or @samp{C}. When you press -@key{SPC} instead, the priority cookie is removed from the headline. -The priorities can also be changed ``remotely'' from the timeline and -agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). +@kindex @kbd{C-c ,} +@findex org-priority +Set the priority of the current headline (@command{org-priority}). 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} +@orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down} @vindex org-priority-start-cycle-with-default Increase/decrease priority of current headline@footnote{See also the option @code{org-priority-start-cycle-with-default}.}. Note that these keys are @@ -3821,7 +4131,7 @@ with detailed subtasks on the tree@footnote{To keep subtasks out of the global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep the overview over the fraction of subtasks that are already completed, insert either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will -be updates each time the todo status of a child changes, or when pressing +be updated each time the TODO status of a child changes, or when pressing @kbd{C-c C-c} on the cookie. For example: @example @@ -3874,13 +4184,16 @@ large number of subtasks (@pxref{Checkboxes}). @section Checkboxes @cindex checkboxes -Every item in a plain list (@pxref{Plain lists}) can be made into a -checkbox by starting it with the string @samp{[ ]}. This feature is -similar to TODO items (@pxref{TODO Items}), but is more lightweight. -Checkboxes are not included into the global TODO list, so they are often -great to split a task into a number of simple steps. Or you can use -them in a shopping list. To toggle a checkbox, use @kbd{C-c C-c}, or -use the mouse (thanks to Piotr Zielinski's @file{org-mouse.el}). +@vindex org-list-automatic-rules +Every item in a plain list@footnote{With the exception of description +lists. But you can allow it by modifying @code{org-list-automatic-rules} +accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting +it with the string @samp{[ ]}. This feature is similar to TODO items +(@pxref{TODO Items}), but is more lightweight. Checkboxes are not included +into the global TODO list, so they are often great to split a task into a +number of simple steps. Or you can use them in a shopping list. To toggle a +checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's +@file{org-mouse.el}). Here is an example of a checkbox list. @@ -3932,13 +4245,11 @@ off a box while there are unchecked boxes above it. @noindent The following commands work with checkboxes: @table @kbd -@kindex C-c C-c -@item C-c C-c +@orgcmd{C-c C-c,org-toggle-checkbox} Toggle checkbox status or (with prefix arg) checkbox presence at point. With double 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 +@orgcmd{C-c C-x C-b,org-toggle-checkbox} Toggle checkbox status or (with prefix arg) checkbox presence at point. With double prefix argument, set it to @samp{[-]}, which is considered to be an intermediate state. @@ -3953,13 +4264,11 @@ 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} +@orgcmd{M-S-@key{RET},org-insert-todo-heading} 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 C-x o -@item C-c C-x o +@orgcmd{C-c C-x o,org-toggle-ordered-property} @vindex org-track-ordered-property-with-tag @cindex property, ORDERED Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must @@ -3968,8 +4277,7 @@ this should be local to the current entry, not inherited like a tag. However, if you would like to @i{track} the value of this property with a tag for better visibility, customize the variable @code{org-track-ordered-property-with-tag}. -@kindex C-c # -@item C-c # +@orgcmd{C-c #,org-update-statistics-cookies} Update the statistics cookie 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 @@ -3987,7 +4295,7 @@ entry twice (checkboxes with @kbd{C-c C-c}). @cindex sparse tree, tag based An excellent way to implement labels and contexts for cross-correlating -information is to assign @i{tags} to headlines. Org mode has extensive +information is to assign @i{tags} to headlines. Org-mode has extensive support for tags. @vindex org-tag-faces @@ -4063,19 +4371,17 @@ After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is also a special command for inserting tags: @table @kbd -@kindex C-c C-q -@item C-c C-q +@orgcmd{C-c C-q,org-set-tags-command} @cindex completion, of tags @vindex org-tags-column -Enter new tags for the current headline. Org mode will either offer +Enter new tags for the current headline. Org-mode will either offer completion or a special single-key interface for setting tags, see below. After pressing @key{RET}, the tags will be inserted and aligned to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all tags in the current buffer will be aligned to that column, just to make things look nice. TAGS are automatically realigned after promotion, demotion, and TODO state changes (@pxref{TODO basics}). -@kindex C-c C-c -@item C-c C-c +@orgcmd{C-c C-c,org-set-tags-command} When the cursor is in a headline, this does the same as @kbd{C-c C-q}. @end table @@ -4111,7 +4417,7 @@ by adding a STARTUP option line to that file: #+STARTUP: noptag @end example -By default Org mode uses the standard minibuffer completion facilities for +By default Org-mode uses the standard minibuffer completion facilities for entering tags. However, it also implements another, quicker, tag selection method called @emph{fast tag selection}. This allows you to select and deselect tags with just a single key press. For this to work well you should @@ -4242,18 +4548,13 @@ Once a system of tags has been set up, it can be used to collect related information into special lists. @table @kbd -@kindex C-c \ -@kindex C-c / m -@item C-c \ -@itemx C-c / m +@orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree} 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 +@orgcmd{C-c a m,org-tags-view} 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 +@orgcmd{C-c a M,org-tags-view} @vindex org-tags-match-list-sublevels Create a global list of tag matches from all agenda files, but check only TODO items and force checking subitems (see variable @@ -4270,11 +4571,11 @@ and properties. For a complete description with many examples, see @node Properties and Columns, Dates and Times, Tags, Top -@chapter Properties and Columns +@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 two main applications for properties in Org-mode. First, properties are like tags, but with a value. Second, you can use properties to implement (very basic) database capabilities in an Org buffer. For an example of the first application, imagine maintaining a file where @@ -4291,7 +4592,7 @@ Properties can be conveniently edited and viewed in column view @menu * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features +* Special properties:: Access to other Org-mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -4354,33 +4655,29 @@ Org files. The following commands help to work with properties: @table @kbd -@kindex M-@key{TAB} -@item M-@key{TAB} +@orgcmd{M-@key{TAB},org-complete} After an initial colon in a line, complete property keys. All keys used in the current file will be offered as possible completions. -@kindex C-c C-x p -@item C-c C-x p +@orgcmd{C-c C-x p,org-set-property} Set a property. This prompts for a property name and a value. If necessary, the property drawer is created as well. @item M-x org-insert-property-drawer +@findex 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 +@orgcmd{C-c C-c,org-property-action} With the cursor in a property drawer, this executes property commands. -@item C-c C-c s +@orgcmd{C-c C-c s,org-set-property} 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} +@orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value} Switch property at point to the next/previous allowed value. -@item C-c C-c d +@orgcmd{C-c C-c d,org-delete-property} Remove a property from the current entry. -@item C-c C-c D +@orgcmd{C-c C-c D,org-delete-property-globally} Globally remove a property, from all entries in the current file. -@item C-c C-c c +@orgcmd{C-c C-c c,org-compute-property-at-point} Compute the property at point, using the operator and scope from the nearest column format definition. @end table @@ -4389,7 +4686,7 @@ nearest column format definition. @section Special properties @cindex properties, special -Special properties provide an alternative access method to Org mode +Special properties provide an alternative access method to Org-mode features, like the TODO state or the priority of an entry, discussed in the previous chapters. This interface exists so that you can include these states in a column view (@pxref{Column view}), or to use them in @@ -4407,6 +4704,7 @@ used as keys in the properties drawer: @cindex property, special, TIMESTAMP @cindex property, special, TIMESTAMP_IA @cindex property, special, CLOCKSUM +@cindex property, special, BLOCKED @c guessing that ITEM is needed in this area; also, should this list be sorted? @cindex property, special, ITEM @example @@ -4422,6 +4720,7 @@ TIMESTAMP @r{The first keyword-less timestamp in the entry.} TIMESTAMP_IA @r{The first inactive timestamp in the entry.} CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}} @r{must be run first to compute the values.} +BLOCKED @r{"t" if task is currently blocked by children or siblings} ITEM @r{The content of the entry.} @end example @@ -4433,18 +4732,13 @@ ITEM @r{The content of the entry.} To create sparse trees and special lists with selection based on properties, the same commands are used as for tag searches (@pxref{Tag searches}). @table @kbd -@kindex C-c \ -@kindex C-c / m -@item C-c \ -@itemx C-c / m +@orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree} Create a sparse tree with all matching entries. 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 +@orgcmd{C-c a m,org-tags-view} Create a global list of tag/property matches from all agenda files. @xref{Matching tags and properties}. -@kindex C-c a M -@item C-c a M +@orgcmd{C-c a M,org-tags-view} @vindex org-tags-match-list-sublevels Create a global list of tag matches from all agenda files, but check only TODO items and force checking of subitems (see variable @@ -4458,12 +4752,11 @@ There is also a special command for creating sparse trees based on a single property: @table @kbd -@kindex C-c / p -@item C-c / p +@orgkey{C-c / p} Create a sparse tree based on the value of a property. This first prompts for the name of a property, and then for a value. A sparse tree is created with all entries that define this property with the given -value. If you enclose the value into curly braces, it is interpreted as +value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property values. @end table @@ -4473,18 +4766,20 @@ a regular expression and matched against the property values. @cindex inheritance, of properties @vindex org-use-property-inheritance -The outline structure of Org-mode documents lends itself for an +The outline structure of Org-mode documents lends itself to an inheritance model of properties: if the parent in a tree has a certain -property, the children can inherit this property. Org mode does not +property, the children can inherit this property. Org-mode does not turn this on by default, because it can slow down property searches significantly and is often not needed. However, if you find inheritance useful, you can turn it on by setting the variable @code{org-use-property-inheritance}. It may be set to @code{t} to make all properties inherited from the parent, to a list of properties that should be inherited, or to a regular expression that matches -inherited properties. +inherited properties. If a property has the value @samp{nil}, this is +interpreted as an explicit undefine of the property, so that inheritance +search will stop at this value and return @code{nil}. -Org mode has a few properties for which inheritance is hard-coded, at +Org-mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used: @cindex property, COLUMNS @@ -4515,7 +4810,7 @@ subtree (@pxref{Tracking TODO state changes}). A great way to view and edit properties in an outline tree is @emph{column view}. In column view, each outline node 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 +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 @@ -4591,15 +4886,15 @@ optional. The individual parts have the following meaning: @var{property} @r{The property that should be edited in this column.} @r{Special properties representing meta data are allowed here} @r{as well (@pxref{Special properties})} -(title) @r{The header text for the column. If omitted, the} - @r{property name is used.} +@var{title} @r{The header text for the column. If omitted, the property} + @r{name is used.} @{@var{summary-type}@} @r{The summary type. If specified, the column values for} @r{parent nodes are computed from the children.} @r{Supported summary types are:} @{+@} @r{Sum numbers in this column.} @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.} @{$@} @r{Currency, short for @samp{+;%.2f}.} - @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.} + @{:@} @r{Sum times, HH:MM, plain numbers are hours.} @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.} @{X/@} @r{Checkbox status, @samp{[n/m]}.} @{X%@} @r{Checkbox status, @samp{[n%]}.} @@ -4609,9 +4904,10 @@ optional. The individual parts have the following meaning: @{:min@} @r{Smallest time value in column.} @{:max@} @r{Largest time value.} @{:mean@} @r{Arithmetic mean of time values.} - @{@@min@} @r{Minimum age (in days/hours/mins/seconds).} - @{@@max@} @r{Maximum age (in days/hours/mins/seconds).} - @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).} + @{@@min@} @r{Minimum age (in days/hours/mins/seconds).} + @{@@max@} @r{Maximum age (in days/hours/mins/seconds).} + @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).} + @{est+@} @r{Add low-high estimates.} @end example @noindent @@ -4619,6 +4915,22 @@ Be aware that you can only have one summary type for any property you include. Subsequent columns referencing the same property will all display the same summary information. +The @code{est+} summary type requires further explanation. It is used for +combining estimates, expressed as low-high ranges. For example, instead +of estimating a particular task will take 5 days, you might estimate it as +5-6 days if you're fairly confident you know how much work is required, or +1-10 days if you don't really know what needs to be done. Both ranges +average at 5.5 days, but the first represents a more predictable delivery. + +When combining a set of such estimates, simply adding the lows and highs +produces an unrealistically wide result. Instead, @code{est+} adds the +statistical mean and variance of the sub-tasks, generating a final estimate +from the sum. For example, suppose you had ten tasks, each of which was +estimated at 0.5 to 2 days of work. Straight addition produces an estimate +of 5 to 20 days, representing what to expect if everything goes either +extremely well or extremely poorly. In contrast, @code{est+} estimates the +full job more realistically, at 10-15 days. + Here is an example for a complete columns definition, along with allowed values. @@ -4651,8 +4963,7 @@ in the subtree. @table @kbd @tsubheading{Turning column view on and off} -@kindex C-c C-x C-c -@item C-c C-x C-c +@orgcmd{C-c C-x C-c,org-columns} @vindex org-columns-default-format Turn on column view. If the cursor is before the first headline in the file, column view is turned on for the entire file, using the @code{#+COLUMNS} @@ -4663,14 +4974,11 @@ for the tree starting at the entry that contains the @code{:COLUMNS:} property. If no such property is found, the format is taken from the @code{#+COLUMNS} line or from the variable @code{org-columns-default-format}, and column view is established for the current entry and its subtree. -@kindex r -@item r +@orgcmd{r,org-columns-redo} Recreate the column view, to include recent changes made in the buffer. -@kindex g -@item g +@orgcmd{g,org-columns-redo} Same as @kbd{r}. -@kindex q -@item q +@orgcmd{q,org-columns-quit} Exit column view. @tsubheading{Editing values} @item @key{left} @key{right} @key{up} @key{down} @@ -4681,40 +4989,30 @@ Move through the column view from field to field. Switch to the next/previous allowed value of the field. For this, you have to have specified allowed values for a property. @item 1..9,0 -Directly select the nth allowed value, @kbd{0} selects the 10th value. -@kindex n -@kindex p -@itemx n / p +Directly select the Nth allowed value, @kbd{0} selects the 10th value. +@orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value} Same as @kbd{S-@key{left}/@key{right}} -@kindex e -@item e +@orgcmd{e,org-columns-edit-value} Edit the property at point. For the special properties, this will invoke the same interface that you normally use to change that property. For example, when editing a TAGS property, the tag completion or fast selection interface will pop up. -@kindex C-c C-c -@item C-c C-c +@orgcmd{C-c C-c,org-columns-set-tags-or-toggle} When there is a checkbox at point, toggle it. -@kindex v -@item v +@orgcmd{v,org-columns-show-value} 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 +@orgcmd{a,org-columns-edit-allowed} 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 < / > +@orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen} Make the column narrower/wider by one character. -@kindex S-M-@key{right} -@item S-M-@key{right} +@orgcmd{S-M-@key{right},org-columns-new} Insert a new column, to the left of the current column. -@kindex S-M-@key{left} -@item S-M-@key{left} +@orgcmd{S-M-@key{left},org-columns-delete} Delete the current column. @end table @@ -4770,20 +5068,16 @@ column view is @code{ITEM}. The following commands insert or update the dynamic block: @table @kbd -@kindex C-c C-x i -@item C-c C-x i +@orgcmd{C-c C-x i,org-insert-columns-dblock} Insert a dynamic block capturing a column view. You will be prompted for the scope or ID of the view. -@kindex C-c C-c -@item C-c C-c -@kindex C-c C-x C-u -@itemx C-c C-x C-u +@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} Update dynamic block at point. The cursor needs to be in the @code{#+BEGIN} line of the dynamic block. -@kindex C-u C-c C-x C-u -@item C-u C-c C-x C-u +@orgcmd{C-u C-c C-x C-u,org-update-all-dblocks} Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if -you have several clock table blocks in a buffer. +you have several clock table blocks, column-capturing blocks or other dynamic +blocks in a buffer. @end table You can add formulas to the column view table and you may add plotting @@ -4810,7 +5104,7 @@ features based on them. For more information see @ref{Using the property API}. @node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top -@chapter Dates and Times +@chapter Dates and times @cindex dates @cindex times @cindex timestamp @@ -4818,9 +5112,9 @@ property API}. To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and time -information is called a @emph{timestamp} in Org mode. This may be a +information is called a @emph{timestamp} in Org-mode. This may be a little confusing because timestamp is often used as indicating when -something was created or last changed. However, in Org mode this term +something was created or last changed. However, in Org-mode this term is used in a much wider sense. @menu @@ -4828,9 +5122,9 @@ is used in a much wider sense. * Creating timestamps:: Commands which insert timestamps * Deadlines and scheduling:: Planning your work * Clocking work time:: Tracking how long you spend on a task -* Resolving idle time:: Resolving time if you've been idle * Effort estimates:: Planning work effort in advance * Relative timer:: Notes with a running timer +* Countdown timer:: Starting a countdown timer for a task @end menu @@ -4845,7 +5139,7 @@ is used in a much wider sense. A timestamp is a specification of a date (possibly with a 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 inspired by the standard ISO 6801 date/time +12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 date/time format. To use an alternative format, see @ref{Custom time format}.}. A timestamp 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 @@ -4876,7 +5170,7 @@ following will show up in the agenda every Wednesday: @end example @item Diary-style sexp entries -For more complex date specifications, Org mode supports using the +For more complex date specifications, Org-mode supports using the special sexp diary entries implemented in the Emacs calendar/diary package. For example @@ -4915,20 +5209,18 @@ angular ones. These timestamps are inactive in the sense that they do @cindex creating timestamps @cindex timestamps, creating -For Org mode to recognize timestamps, they need to be in the specific +For Org-mode to recognize timestamps, they need to be in the specific format. All commands listed below produce timestamps in the correct format. @table @kbd -@kindex C-c . -@item C-c . +@orgcmd{C-c .,org-time-stamp} Prompt for a date and insert a corresponding timestamp. When the cursor is at an existing timestamp in the buffer, the command is used to modify this timestamp instead of inserting a new one. When this command is used twice in succession, a time range is inserted. @c -@kindex C-c ! -@item C-c ! +@orgcmd{C-c !,org-time-stamp-inactive} Like @kbd{C-c .}, but insert an inactive timestamp that will not cause an agenda entry. @c @@ -4941,32 +5233,23 @@ Like @kbd{C-c .} and @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 < +@orgcmd{C-c <,org-date-from-calendar} Insert a timestamp corresponding to the cursor date in the Calendar. @c -@kindex C-c > -@item C-c > +@orgcmd{C-c >,org-goto-calendar} Access the Emacs calendar for the current date. If there is a timestamp in the current line, go to the corresponding date instead. @c -@kindex C-c C-o -@item C-c C-o +@orgcmd{C-c C-o,org-open-at-point} Access the agenda for the date given by the timestamp 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} +@orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day} Change date at cursor by one day. These key bindings conflict with shift-selection and related modes (@pxref{Conflicts}). @c -@kindex S-@key{up} -@kindex S-@key{down} -@item S-@key{up} -@itemx S-@key{down} +@orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down} Change the item under the cursor in a timestamp. The cursor can be on a year, month, day, hour or minute. When the timestamp contains a time range like @samp{15:30-16:30}, modifying the first time will also shift the second, @@ -4976,9 +5259,8 @@ timestamp, these same keys modify the priority of an item. (@pxref{Priorities}). The key bindings also conflict with shift-selection and related modes (@pxref{Conflicts}). @c -@kindex C-c C-y +@orgcmd{C-c C-y,org-evaluate-time-range} @cindex evaluate time range -@item C-c C-y Evaluate a time range by computing the difference between start and end. With a prefix argument, insert result after the time range (in a table: into the following column). @@ -4986,7 +5268,7 @@ the following column). @menu -* The date/time prompt:: How Org mode helps you entering date and time +* The date/time prompt:: How Org-mode helps you entering date and time * Custom time format:: Making dates look different @end menu @@ -4996,17 +5278,17 @@ the following column). @cindex time, reading in minibuffer @vindex org-read-date-prefer-future -When Org mode prompts for a date/time, the default is shown in default +When Org-mode prompts for a date/time, the default is shown in default date/time format, and the prompt therefore seems to ask for a specific format. But it will in fact accept any string containing some date and/or time information, and it is really smart about interpreting your input. You can, for example, use @kbd{C-y} to paste a (possibly multi-line) string -copied from an email message. Org mode will find whatever information is in +copied from an email message. Org-mode will find whatever information is in there and derive anything you have not specified from the @emph{default date and time}. The default is usually the current date and time, but when modifying an existing timestamp, or when entering the second stamp of a range, it is taken from the stamp in the buffer. When filling in -information, Org mode assumes that most of the time you will want to enter a +information, Org-mode assumes that most of the time you will want to enter a date in the future: if you omit the month/year and the given day/month is @i{before} today, it will assume that you mean a future date@footnote{See the variable @code{org-read-date-prefer-future}. You may set that variable to @@ -5015,14 +5297,16 @@ tomorrow.}. If the date has been automatically shifted into the future, the time prompt will show this with @samp{(=>F).} For example, let's assume that today is @b{June 13, 2006}. Here is how -various inputs will be interpreted, the items filled in by Org mode are +various inputs will be interpreted, the items filled in by Org-mode are in @b{bold}. @example 3-2-5 --> 2003-02-05 +2/5/3 --> 2003-02-05 14 --> @b{2006}-@b{06}-14 12 --> @b{2006}-@b{07}-12 -Fri --> nearest Friday (defaultdate or later) +2/5 --> @b{2007}-02-05 +Fri --> nearest Friday (default date or later) sep 15 --> @b{2006}-09-15 feb 15 --> @b{2007}-02-15 sep 12 9 --> 2009-09-12 @@ -5039,7 +5323,7 @@ letter ([dwmy]) to indicate change in days, weeks, months, or years. With a single plus or minus, the date is always relative to today. With a double plus or minus, it is relative to the default date. If instead of a single letter, you use the abbreviation of day name, the date will be -the nth such day. E.g. +the Nth such day. E.g. @example +0 --> today @@ -5057,6 +5341,16 @@ 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}. +You can specify a time range by giving start and end times or by giving a +start time and a duration (in HH:MM format). Use `-' or `-@{@}-' as the separator +in the former case and use '+' as the separator in the latter case. E.g. + +@example +11am-1:15pm --> 11:00-13:15 +11am--1:15pm --> same as above +11am+2:15 --> same as above +@end example + @cindex calendar, for selecting date @vindex org-popup-calendar-for-date-prompt Parallel to the minibuffer prompt, a calendar is popped up@footnote{If @@ -5069,6 +5363,8 @@ from the minibuffer: @kindex < @kindex > +@kindex M-v +@kindex C-v @kindex mouse-1 @kindex S-@key{right} @kindex S-@key{left} @@ -5078,12 +5374,13 @@ from the minibuffer: @kindex M-S-@key{left} @kindex @key{RET} @example -> / < @r{Scroll calendar forward/backward by one month.} +@key{RET} @r{Choose date at cursor in calendar.} mouse-1 @r{Select date by clicking on it.} S-@key{right}/@key{left} @r{One day forward/backward.} S-@key{down}/@key{up} @r{One week forward/backward.} M-S-@key{right}/@key{left} @r{One month forward/backward.} -@key{RET} @r{Choose date in calendar.} +> / < @r{Scroll calendar forward/backward by one month.} +M-v / C-v @r{Scroll calendar forward/backward by 3 months.} @end example @vindex org-read-date-display-live @@ -5102,20 +5399,19 @@ minibuffer@footnote{If you find this distracting, turn the display of with @vindex org-display-custom-times @vindex org-time-stamp-custom-formats -Org mode uses the standard ISO notation for dates and times as it is +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 +@orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays} 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 +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: @@ -5131,7 +5427,7 @@ 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 timestamp contains a range of clock times or a repeater, these -will not be overlayed, but remain in the buffer as they were. +will not be overlaid, but remain in the buffer as they were. @item When you delete a timestamp character-by-character, it will only disappear from the buffer after @emph{all} (invisible) characters @@ -5183,8 +5479,8 @@ 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. +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. @@ -5192,23 +5488,23 @@ I.e. the task will automatically be forwarded until completed. @end example @noindent -@b{Important:} Scheduling an item in Org mode should @i{not} be +@b{Important:} Scheduling an item in Org-mode should @i{not} be understood in the same way that we understand @i{scheduling a meeting}. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by -Org users. In Org mode, @i{scheduling} means setting a date when you +Org users. In Org-mode, @i{scheduling} means setting a date when you want to start working on an action item. @end table You may use timestamps with repeaters in scheduling and deadline -entries. Org mode will issue early and late warnings based on the +entries. Org-mode will issue early and late warnings based on the assumption that the timestamp represents the @i{nearest instance} of the repeater. However, the use of diary sexp entries like @c @code{<%%(diary-float t 42)>} @c -in scheduling and deadline timestamps is limited. Org mode does not +in scheduling and deadline timestamps is limited. Org-mode does not know enough about the internals of each sexp function to issue early and late warnings. However, it will show the item on each day where the sexp entry matches. @@ -5226,8 +5522,7 @@ an item: @table @kbd @c -@kindex C-c C-d -@item C-c C-d +@orgcmd{C-c C-d,org-deadline} Insert @samp{DEADLINE} keyword along with a stamp. The insertion will happen in the line directly following the headline. When called with a prefix arg, an existing deadline will be removed from the entry. Depending on the @@ -5237,8 +5532,7 @@ and @code{nologredeadline}}, a note will be taken when changing an existing deadline. @c FIXME Any CLOSED timestamp will be removed.???????? @c -@kindex C-c C-s -@item C-c C-s +@orgcmd{C-c C-s,org-schedule} Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will happen in the line directly following the headline. Any CLOSED timestamp will be removed. When called with a prefix argument, remove the scheduling @@ -5248,18 +5542,16 @@ keywords @code{logredeadline}, @code{lognoteredeadline}, and @code{nologredeadline}}, a note will be taken when changing an existing scheduling time. @c -@kindex C-c C-x C-k +@orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action} @kindex k a @kindex k s -@item C-c C-x C-k Mark the current entry for agenda action. After you have marked the entry like this, you can open the agenda or the calendar to find an appropriate date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to schedule the marked item. @c -@kindex C-c / d +@orgcmd{C-c / d,org-check-deadlines} @cindex sparse tree, for deadlines -@item C-c / d @vindex org-deadline-warning-days Create a sparse tree with all deadlines that are either past-due, or which will become due within @code{org-deadline-warning-days}. @@ -5267,12 +5559,10 @@ With @kbd{C-u} prefix, show all deadlines in the file. With a numeric prefix, check that many days. For example, @kbd{C-1 C-c / d} shows all deadlines due tomorrow. @c -@kindex C-c / b -@item C-c / b +@orgcmd{C-c / b,org-check-before-date} Sparse tree for deadlines and scheduled items before a given date. @c -@kindex C-c / a -@item C-c / a +@orgcmd{C-c / a,org-check-after-date} Sparse tree for deadlines and scheduled items after a given date. @end table @@ -5281,7 +5571,7 @@ Sparse tree for deadlines and scheduled items after a given date. @cindex tasks, repeated @cindex repeated tasks -Some tasks need to be repeated again and again. Org mode helps to +Some tasks need to be repeated again and again. Org-mode helps to organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, or plain timestamp. In the following example @example @@ -5295,17 +5585,21 @@ from that time. If you need both a repeater and a special warning period in a deadline entry, the repeater should come first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}. -Deadlines and scheduled items produce entries in the agenda when they -are over-due, so it is important to be able to mark such an entry as -completed once you have done so. When you mark a DEADLINE or a SCHEDULE -with the TODO keyword DONE, it will no longer produce entries in the -agenda. The problem with this is, however, that then also the -@emph{next} instance of the repeated entry will not be active. Org mode -deals with this in the following way: When you try to mark such an entry -DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating -timestamp 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: +@vindex org-todo-repeat-to-state +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 timestamp by the repeater interval, and +immediately set the entry state back to TODO@footnote{In fact, the target +state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or +the variable @code{org-todo-repeat-to-state}. If neither of these is +specified, the target state defaults to the first state of the TODO state +sequence.}. In the example above, setting the state to DONE would actually +switch the date like this: @example ** TODO Pay the rent @@ -5327,11 +5621,11 @@ With the @samp{+1m} cookie, the date shift will always be exactly one month. So if you have not paid the rent for three months, marking this entry DONE will still keep it as an overdue deadline. Depending on the task, this may not be the best way to handle it. For example, if you -forgot to call you father for 3 weeks, it does not make sense to call +forgot to call your father for 3 weeks, it does not make sense to call him 3 times in a single day to make up for it. Finally, there are tasks like changing batteries which should always repeat a certain time -@i{after} the last time you did it. For these tasks, Org mode has -special repeaters markers with @samp{++} and @samp{.+}. For example: +@i{after} the last time you did it. For these tasks, Org-mode has +special repeaters @samp{++} and @samp{.+}. For example: @example ** TODO Call Father @@ -5354,10 +5648,12 @@ subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was created for this purpose, it is described in @ref{Structure editing}. -@node Clocking work time, Resolving idle time, Deadlines and scheduling, Dates and Times +@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times @section Clocking work time +@cindex clocking time +@cindex time clocking -Org mode allows you to clock the time you spend on specific tasks in a +Org-mode allows you to clock the time you spend 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 @@ -5376,9 +5672,17 @@ on this task while outside Emacs, use @code{(setq org-clock-persist t)}.} will be found (@pxref{Resolving idle time}) and you will be prompted about what to do with it. +@menu +* Clocking commands:: Starting and stopping a clock +* The clock table:: Detailed reports +* Resolving idle time:: Resolving time when you've been idle +@end menu + +@node Clocking commands, The clock table, Clocking work time, Clocking work time +@subsection Clocking commands + @table @kbd -@kindex C-c C-x C-i -@item C-c C-x C-i +@orgcmd{C-c C-x C-i,org-clock-in} @vindex org-clock-into-drawer Start the clock on the current item (clock-in). This inserts the CLOCK keyword together with a timestamp. If this is not the first clocking of @@ -5408,8 +5712,8 @@ show all time clocked on this tasks today (see also the variable @code{auto} which is the default@footnote{See also the variable @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the mode line entry will pop up a menu with clocking options. -@kindex C-c C-x C-o -@item C-c C-x C-o +@c +@orgcmd{C-c C-x C-o,org-clock-out} @vindex org-log-note-clock-out Stop the clock (clock-out). This inserts another timestamp at the same location where the clock was last started. It also directly computes @@ -5418,30 +5722,24 @@ HH:MM}. See the variable @code{org-log-note-clock-out} for the possibility to record an additional note together with the clock-out timestamp@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: lognoteclock-out}}. -@kindex C-c C-x C-e -@item C-c C-x C-e +@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate} Update the effort estimate for the current clock task. @kindex C-c C-y @kindex C-c C-c -@item C-c C-y @ @ @r{or}@ @ C-c C-c +@orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range} Recompute the time interval after changing one of the timestamps. This is only necessary if you edit the timestamps 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 +@orgcmd{C-c C-t,org-todo} 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 +@orgcmd{C-c C-x C-x,org-clock-cancel} Cancel the current clock. This is useful if a clock was started by mistake, or if you ended up working on something else. -@kindex C-c C-x C-j -@item C-c C-x C-j -Jump to the entry that contains the currently running clock. With a -@kbd{C-u} prefix arg, select the target task from a list of recently clocked -tasks. -@kindex C-c C-x C-d -@item C-c C-x C-d +@orgcmd{C-c C-x C-j,org-clock-goto} +Jump to the headline of the currently clocked in task. With a @kbd{C-u} +prefix arg, select the target task from a list of recently clocked tasks. +@orgcmd{C-c C-x C-d,org-clock-display} @vindex org-remove-highlights-with-change Display time summaries for each subtree in the current buffer. This puts overlays at the end of each headline, showing the total time @@ -5449,24 +5747,60 @@ 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 +@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 The clock table, Resolving idle time, Clocking commands, Clocking work time +@subsection The clock table +@cindex clocktable, dynamic block +@cindex report, of clocked time + +Org mode can produce quite complex reports based on the time clocking +information. Such a report is called a @emph{clock table}, because it is +formatted as one or several Org tables. + +@table @kbd +@orgcmd{C-c C-x C-r,org-clock-report} Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock report as an Org-mode table into the current file. When the cursor is at an existing clock table, just update it. When called with a prefix argument, jump to the first clock report in the current document and update it. +@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} +Update dynamic block at point. The cursor needs to be in the +@code{#+BEGIN} line of the dynamic block. +@orgkey{C-u C-c C-x C-u} +Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if +you have several clock table blocks in a buffer. +@orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift} +Shift the current @code{:block} interval and update the table. The cursor +needs to be in the @code{#+BEGIN: clocktable} line for this command. If +@code{:block} is @code{today}, it will be shifted to @code{today-1} etc. +@end table + + +Here is an example of the frame for a clock table as it is inserted into the +buffer with the @kbd{C-c C-x C-r} command: + @cindex #+BEGIN, clocktable @example #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file #+END: clocktable @end example @noindent -If such a block already exists at point, its content is replaced by the -new table. The @samp{BEGIN} line can specify options: +@vindex org-clocktable-defaults +The @samp{BEGIN} line and specify a number of options to define the scope, +structure, and formatting of the report. Defaults for all these options can +be configured in the variable @code{org-clocktable-defaults}. + +@noindent First there are options that determine which clock entries are to +be selected: @example :maxlevel @r{Maximum level depth to which times are listed in the table.} -:emphasize @r{When @code{t}, emphasize level one and level two items.} + @r{Clocks at deeper levels will be summed into the upper level.} :scope @r{The scope to consider. This can be any of the following:} nil @r{the current buffer or narrowed region} file @r{the full current buffer} @@ -5483,6 +5817,7 @@ new table. The @samp{BEGIN} line can specify options: 2007-12-31 @r{New year eve 2007} 2007-12 @r{December 2007} 2007-W50 @r{ISO-week 50 in 2007} + 2007-Q2 @r{2nd quarter in 2007} 2007 @r{the year 2007} today, yesterday, today-@var{N} @r{a relative day} thisweek, lastweek, thisweek-@var{N} @r{a relative week} @@ -5493,13 +5828,33 @@ new table. The @samp{BEGIN} line can specify options: :tend @r{A time string specifying when to stop considering times.} :step @r{@code{week} or @code{day}, to split the table into chunks.} @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.} +:stepskip0 @r{Do not show steps that have zero time.} +:fileskip0 @r{Do not show table sections from files which did not contribute.} +:tags @r{A tags match to select entries that should contribute}. +@end example + +Then there are options which determine the formatting of the table. There +options are interpreted by the function @code{org-clocktable-write-default}, +but you can specify your own function using the @code{:formatter} parameter. +@example +:emphasize @r{When @code{t}, emphasize level one and level two items.} :link @r{Link the item headlines in the table to their origins.} +:narrow @r{An integer to limit the width of the headline column in} + @r{the org table. If you write it like @samp{50!}, then the} + @r{headline will also be shortened in export.} +:indent @r{Indent each headline field according to its level.} +:tcolumns @r{Number of columns to be used for times. If this is smaller} + @r{than @code{:maxlevel}, lower levels will be lumped into one column.} +:level @r{Should a level number column be included?} +:compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}} + @r{All are overwritten except if there is an explicit @code{:narrow}} +:timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,} + @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.} :formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.} @r{As a special case, @samp{:formula %} adds a column with % time.} - @r{If you do not specify a formula here, any existing formula.} + @r{If you do not specify a formula here, any existing formula} @r{below the clock table will survive updates and be evaluated.} -:timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,} - @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.} +:formatter @r{A function to format clock data and insert it into the buffer.} @end example To get a clock summary of the current level 1 tree, for the current day, you could write @@ -5521,31 +5876,15 @@ A summary of the current subtree with % times would be #+BEGIN: clocktable :scope subtree :link t :formula % #+END: clocktable @end example -@kindex C-c C-c -@item C-c C-c -@kindex C-c C-x C-u -@itemx C-c C-x C-u -Update dynamic block at point. The cursor needs to be in the -@code{#+BEGIN} line of the dynamic block. -@kindex C-u C-c C-x C-u -@item C-u C-c C-x C-u -Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if -you have several clock table blocks in a buffer. -@kindex S-@key{left} -@kindex S-@key{right} -@item S-@key{left} -@itemx S-@key{right} -Shift the current @code{:block} interval and update the table. The cursor -needs to be in the @code{#+BEGIN: clocktable} line for this command. If -@code{:block} is @code{today}, it will be shifted to @code{today-1} etc. -@end table - -The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in -the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been -worked on or closed during a day. +A horizontally compact representation of everything clocked during last week +would be +@example +#+BEGIN: clocktable :scope agenda :block lastweek :compact t +#+END: clocktable +@end example -@node Resolving idle time, Effort estimates, Clocking work time, Dates and Times -@section Resolving idle time +@node Resolving idle time, , The clock table, Clocking work time +@subsection Resolving idle time @cindex resolve idle time @cindex idle, resolve, dangling @@ -5585,8 +5924,8 @@ use the shift key and press @kbd{S}. Remember that using shift will always leave you clocked out, no matter which option you choose. @item C To cancel the clock altogether, use @kbd{C}. Note that if instead of -cancelling you subtract the away time, and the resulting clock amount is less -than a minute, the clock will still be cancelled rather than clutter up the +canceling you subtract the away time, and the resulting clock amount is less +than a minute, the clock will still be canceled rather than clutter up the log with an empty entry. @end table @@ -5606,13 +5945,13 @@ If you restart Emacs and clock into any task, Org will notice that you have a dangling clock which was never clocked out from your last session. Using that clock's starting time as the beginning of the unaccounted-for period, Org will ask how you want to resolve that time. The logic and behavior is -identical to dealing with away time due to idleness, it's just happening due +identical to dealing with away time due to idleness; it's just happening due to a recovery event rather than a set amount of idle time. You can also check all the files visited by your Org agenda for dangling clocks at any time using @kbd{M-x org-resolve-clocks}. -@node Effort estimates, Relative timer, Resolving idle time, Dates and Times +@node Effort estimates, Relative timer, Clocking work time, Dates and Times @section Effort estimates @cindex effort estimates @@ -5628,13 +5967,11 @@ used with the variable @code{org-effort-property}.}. You can set the effort for an entry with the following commands: @table @kbd -@kindex C-c C-x e -@item C-c C-x e +@orgcmd{C-c C-x e,org-set-effort} Set the effort estimate for the current entry. With a numeric prefix -argument, set it to the NTH allowed value (see below). This command is also +argument, set it to the Nth allowed value (see below). This command is also accessible from the agenda with the @kbd{e} key. -@kindex C-c C-x C-e -@item C-c C-x C-e +@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate} Modify the effort estimate of the item currently being clocked. @end table @@ -5677,7 +6014,7 @@ with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have these estimates defined consistently, two or three key presses will narrow down the list to stuff that fits into an available time slot. -@node Relative timer, , Effort estimates, Dates and Times +@node Relative timer, Countdown timer, Effort estimates, Dates and Times @section Taking notes with a relative timer @cindex relative timer @@ -5686,194 +6023,356 @@ be useful to have access to times relative to a starting time. Org provides such a relative timer and make it easy to create timed notes. @table @kbd -@kindex C-c C-x . -@item C-c C-x . +@orgcmd{C-c C-x .,org-timer} Insert a relative time into the buffer. The first time you use this, the timer will be started. When called with a prefix argument, the timer is restarted. -@kindex C-c C-x - -@item C-c C-x - +@orgcmd{C-c C-x -,org-timer-item} Insert a description list item with the current relative time. With a prefix argument, first reset the timer to 0. -@kindex M-@key{RET} -@item M-@key{RET} +@orgcmd{M-@key{RET},org-insert-heading} Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert new timer items. +@c for key sequences with a comma, command name macros fail :( @kindex C-c C-x , @item C-c C-x , -Pause the timer, or continue it if it is already paused. +Pause the timer, or continue it if it is already paused +(@command{org-timer-pause-or-continue}). @c removed the sentence because it is redundant to the following item @kindex C-u C-c C-x , @item C-u C-c C-x , Stop the timer. After this, you can only start a new timer, not continue the old one. This command also removes the timer from the mode line. -@kindex C-c C-x 0 -@item C-c C-x 0 +@orgcmd{C-c C-x 0,org-timer-start} Reset the timer without inserting anything into the buffer. By default, the timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to specific starting offset. The user is prompted for the offset, with a default taken from a timer string at point, if any, So this can be used to restart taking notes after a break in the process. When called with a double -prefix argument @kbd{C-c C-u}, change all timer strings in the active region +prefix argument @kbd{C-u C-u}, change all timer strings in the active region by a certain amount. This can be used to fix timer strings if the timer was not started at exactly the right moment. @end table +@node Countdown timer, , Relative timer, Dates and Times +@section Countdown timer +@cindex Countdown timer +@kindex C-c C-x ; +@kindex ; + +Calling @code{org-timer-set-timer} from an Org-mode buffer runs a countdown +timer. Use @key{;} from agenda buffers, @key{C-c C-x ;} everwhere else. + +@code{org-timer-set-timer} prompts the user for a duration and displays a +countdown timer in the modeline. @code{org-timer-default-timer} sets the +default countdown value. Giving a prefix numeric argument overrides this +default value. + @node Capture - Refile - Archive, Agenda Views, Dates and Times, Top @chapter Capture - Refile - Archive @cindex capture An important part of any organization system is the ability to quickly capture new ideas and tasks, and to associate reference material with them. -Org uses the @file{remember.el} package to create tasks, and stores files +Org does this using a process called @i{capture}. It also can store files related to a task (@i{attachments}) in a special directory. Once in the system, tasks and projects need to be moved around. Moving completed project trees to an archive file keeps the system compact and fast. @menu -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks * RSS Feeds:: Getting input from RSS feeds * Protocols:: External (e.g. Browser) access to Emacs and Org * Refiling notes:: Moving a tree from one place to another * Archiving:: What to do with finished projects @end menu -@node Remember, Attachments, Capture - Refile - Archive, Capture - Refile - Archive -@section Remember -@cindex @file{remember.el} +@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive +@section Capture +@cindex capture -The Remember package by John Wiegley lets you store quick notes with little -interruption of your work flow. It is an excellent way to add new notes and -tasks to Org files. The @code{remember.el} package is part of Emacs 23, not -Emacs 22. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for -more information. +Org's method for capturing new items is heavily inspired by John Wiegley +excellent remember package. Up to version 6.36 Org used a special setup +for @file{remember.el}. @file{org-remember.el} is still part of Org-mode for +backward compatibility with existing setups. You can find the documentation +for org-remember at @url{http://orgmode.org/org-remember.pdf}. + +The new capturing setup described here is preferred and should be used by new +users. To convert your @code{org-remember-templates}, run the command +@example +@kbd{M-x org-capture-import-remember-templates @key{RET}} +@end example +@noindent and then customize the new variable with @kbd{M-x +customize-variable org-capture-templates}, check the result, and save the +customization. You can then use both remember and capture until +you are familiar with the new mechanism. -Org significantly expands the possibilities of Remember: you may define -templates for different note types, and associate target files and headlines -with specific templates. It also allows you to select the location where a -note should be stored interactively, on the fly. +Capture lets you quickly store notes with little interruption of your work +flow. The basic process of capturing is very similar to remember, but Org +does enhance it with templates and more. @menu -* Setting up Remember for Org:: 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 +* Setting up capture:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types @end menu -@node Setting up Remember for Org, Remember templates, Remember, Remember -@subsection Setting up Remember for Org +@node Setting up capture, Using capture, Capture, Capture +@subsection Setting up capture -The following customization will tell Remember to use Org files as -target, and to create annotations compatible with Org links. +The following customization sets a default target file for notes, and defines +a global key@footnote{Please select your own key, @kbd{C-c c} is only a +suggestion.} for capturing new material. +@vindex org-default-notes-file @example -(org-remember-insinuate) -(setq org-directory "~/path/to/my/orgfiles/") (setq org-default-notes-file (concat org-directory "/notes.org")) -(define-key global-map "\C-cr" 'org-remember) +(define-key global-map "\C-cc" 'org-capture) @end example -@noindent -The last line binds the command @code{org-remember} to a global -key@footnote{Please select your own key, @kbd{C-c r} is only a -suggestion.}. @code{org-remember} basically just calls Remember, -but it makes a few things easier: if there is an active region, it will -automatically copy the region into the Remember buffer. It also allows -to jump to the buffer and location where Remember notes are being -stored: just call @code{org-remember} with a prefix argument. If you -use two prefix arguments, Org jumps to the location where the last -remember note was stored. - -The Remember buffer will actually use @code{org-mode} as its major mode, so -that all editing features of Org mode are available. In addition to this, a -minor mode @code{org-remember-mode} is turned on, for the single purpose that -you can use its keymap @code{org-remember-mode-map} to overwrite some of -Org mode's key bindings. - -You can also call @code{org-remember} in a special way from the agenda, -using the @kbd{k r} key combination. With this access, any timestamps -inserted by the selected Remember template (see below) will default to -the cursor date in the agenda, rather than to the current date. - -@node Remember templates, Storing notes, Setting up Remember for Org, Remember -@subsection Remember templates -@cindex templates, for Remember - -In combination with Org, you can use templates to generate -different types of Remember notes. For example, if you would like -to use one template to create general TODO entries, another one for -journal entries, and a third one for collecting random ideas, you could -use: - -@example -(setq org-remember-templates - '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") - ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") - ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) -@end example - -@vindex org-remember-default-headline -@vindex org-directory -@noindent In these entries, the first string is just a name, and the -character specifies how to select the template. It is useful if the -character is also the first letter of the name. The next string specifies -the template. Two more (optional) strings give the file in which, and the -headline under which, the new note should be stored. The file (if not -present or @code{nil}) defaults to @code{org-default-notes-file}, the heading -to @code{org-remember-default-headline}. If the file name is not an absolute -path, it will be interpreted relative to @code{org-directory}. - -The heading can also be the symbols @code{top} or @code{bottom} to send notes -as level 1 entries to the beginning or end of the file, respectively. It may -also be the symbol @code{date-tree}. Then, a tree with year on level 1, -month on level 2 and day on level three will be build in the file, and the -entry will be filed into the tree under the current date@footnote{If the file -contains an entry with a @code{DATE_TREE} property, the entire date tree will -be build under that entry.} - -An optional sixth element specifies the contexts in which the user can select -the template. This element can be a list of major modes or a function. -@code{org-remember} will first check whether the function returns @code{t} or -if we are in any of the listed major modes, and exclude templates for which -this condition is not fulfilled. Templates that do not specify this element -at all, or that use @code{nil} or @code{t} as a value will always be -selectable. - -So for example: - -@example -(setq org-remember-templates - '(("Bug" ?b "* BUG %?\n %i\n %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode)) - ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" "X" my-check) - ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) -@end example +@node Using capture, Capture templates, Setting up capture, Capture +@subsection Using capture -@noindent -The first template will only be available when invoking @code{org-remember} -from an buffer in @code{emacs-lisp-mode}. The second template will only be -available when the function @code{my-check} returns @code{t}. The third -template will be proposed in any context. +@table @kbd +@orgcmd{C-c c,org-capture} +Call the command @code{org-capture}. Note that this keybinding is global and +not active by default - you need to install it. If you have templates +defined @pxref{Capture templates}, it will offer these templates for +selection or use a new Org outline node as the default template. It will +insert the template into the target file and switch to an indirect buffer +narrowed to this new node. You may then insert the information you want. + +@orgcmd{C-c C-c,org-capture-finalize} +Once you have finished entering information into the capture buffer, @kbd{C-c +C-c} will return you to the window configuration before the capture process, +so that you can resume your work without further distraction. When called +with a prefix arg, finalize and then jump to the captured item. + +@orgcmd{C-c C-w,org-capture-refile} +Finalize the capture process by refiling (@pxref{Refiling notes}) the note to +a different place. Please realize that this is a normal refiling command +that will be executed---so the cursor position at the moment you run this +command is important. If you have inserted a tree with a parent and +children, first move the cursor back to the parent. Any prefix argument +given to this command will be passed on to the @code{org-refile} command. + +@orgcmd{C-c C-k,org-capture-kill} +Abort the capture process and return to the previous state. + +@end table + +You can also call @code{org-capture} in a special way from the agenda, using +the @kbd{k c} key combination. With this access, any timestamps inserted by +the selected capture template will default to the cursor date in the agenda, +rather than to the current date. + +To find the locations of the last stored capture, use @code{org-capture} with +prefix commands: + +@table @kbd +@orgkey{C-u C-c c} +Visit the target location of a cpature template. You get to select the +template in the usual way. +@orgkey{C-u C-u C-c c} +Visit the last stored capture item in its buffer. +@end table + +@node Capture templates, , Using capture, Capture +@subsection Capture templates +@cindex templates, for Capture + +You can use templates for different types of capture items, and +for different target locations. The easiest way to create such templates is +through the customize interface. + +@table @kbd +@orgkey{C-c c C} +Customize the variable @code{org-capture-templates}. +@end table + +Before we give the formal description of template definitions, let's look at +an example. Say you would like to use one template to create general TODO +entries, and you want to put these entries under the heading @samp{Tasks} in +your file @file{~/org/gtd.org}. Also, a date tree in the file +@file{journal.org} should capture journal entries. A possible configuration +would look like: + +@example +(setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) +@end example -When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember -something, Org will prompt for a key to select the template (if you have -more than one template) and then prepare the buffer like +@noindent If you then press @kbd{C-c c t}, Org will prepare the template +for you like this: @example * TODO - [[file:@var{link to where you called remember}]] + [[file:@var{link to where you initiated capture}]] @end example @noindent -During expansion of the template, special @kbd{%}-escapes@footnote{If you -need one of these sequences literally, escape the @kbd{%} with a backslash.} -allow dynamic insertion of content: +During expansion of the template, @code{%a} has been replaced by a link to +the location from where you called the capture command. This can be +extremely useful for deriving tasks from emails, for example. You fill in +the task definition, press @code{C-c C-c} and Org returns you to the same +place where you started the capture process. + + +@menu +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context +@end menu + +@node Template elements, Template expansion, Capture templates, Capture templates +@subsubsection Template elements + +Now lets look at the elements of a template definition. Each entry in +@code{org-capture-templates} is a list with the following items: + +@table @var +@item keys +The keys that will select the template, as a string, characters +only, for example @code{"a"} for a template to be selected with a +single key, or @code{"bt"} for selection with two keys. When using +several keys, keys using the same prefix key must be sequential +in the list and preceded by a 2-element entry explaining the +prefix key, for example @example + ("b" "Templates for marking stuff to buy") +@end example +@noindent If you do not define a template for the @kbd{C} key, this key will +be used to open the customize buffer for this complex variable. + +@item description +A short string describing the template, which will be shown during +selection. + +@item type +The type of entry, a symbol. Valid values are: +@table @code +@item entry +An Org-mode node, with a headline. Will be filed as the child of the +target entry or as a top-level entry. The target file should be an Org-mode +file. +@item item +A plain list item, placed in the first plain list at the target +location. Again the target file should be an Org file. +@item checkitem +A checkbox item. This only differs from the plain list item by the +default template. +@item table-line +a new line in the first table at the target location. Where exactly the +line will be inserted depends on the properties @code{:prepend} and +@code{:table-line-pos} (see below). +@item plain +Text to be inserted as it is. +@end table + +@item target +@vindex org-default-notes-file +Specification of where the captured item should be placed. In Org-mode +files, targets usually define a node. Entries will become children of this +node. Other types will be added to the table or list in the body of this +node. Most target specifications contain a file name. If that file name is +the empty string, it defaults to @code{org-default-notes-file}. + +Valid values are: +@table @code +@item (file "path/to/file") +Text will be placed at the beginning or end of that file. + +@item (id "id of existing org entry") +Filing as child of this entry, or in the body of the entry. + +@item (file+headline "path/to/file" "node headline") +Fast configuration if the target heading is unique in the file. + +@item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...) +For non-unique headings, the full path is safer. + +@item (file+regexp "path/to/file" "regexp to find location") +Use a regular expression to position the cursor. + +@item (file+datetree "path/to/file") +Will create a heading in a date tree for today's date. + +@item (file+datetree+prompt "path/to/file") +Will create a heading in a date tree, but will prompt for the date. + +@item (file+function "path/to/file" function-finding-location) +A function to find the right location in the file. + +@item (clock) +File to the entry that is currently being clocked. + +@item (function function-finding-location) +Most general way, write your own function to find both +file and location. +@end table + +@item template +The template for creating the capture item. If you leave this empty, an +appropriate default template will be used. Otherwise this is a string with +escape codes, which will be replaced depending on time and context of the +capture call. The string with escapes may be loaded from a template file, +using the special syntax @code{(file "path/to/template")}. See below for +more details. + +@item properties +The rest of the entry is a property list of additional options. +Recognized properties are: +@table @code +@item :prepend +Normally new captured information will be appended at +the target location (last child, last table line, last list item...). +Setting this property will change that. + +@item :immediate-finish +When set, do not offer to edit the information, just +file it away immediately. This makes sense if the template only needs +information that can be added automatically. + +@item :empty-lines +Set this to the number of lines to insert +before and after the new item. Default 0, only common other value is 1. + +@item :clock-in +Start the clock in this item. + +@item :clock-resume +If starting the capture interrupted a clock, restart that clock when finished +with the capture. + +@item :unnarrowed +Do not narrow the target buffer, simply show the full buffer. Default is to +narrow it so that you only see the new material. + +@item :kill-buffer +If the target file was not yet visited when capture was invoked, kill the +buffer again after capture is completed. +@end table +@end table + +@node Template expansion, , Template elements, Capture templates +@subsubsection Template expansion + +In the template itself, special @kbd{%}-escapes@footnote{If you need one of +these sequences literally, escape the @kbd{%} with a backslash.} allow +dynamic insertion of content: + +@comment SJE: should these sentences terminate in period? +@smallexample %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.} @r{You may specify a default value and a completion table with} @r{%^@{prompt|default|completion2|completion3...@}} @r{The arrow keys access a prompt-specific history.} %a @r{annotation, normally the link created with @code{org-store-link}} %A @r{like @code{%a}, but prompt for the description part} -%i @r{initial content, the region when remember is called with C-u.} +%i @r{initial content, the region when capture is called while the} + @r{region is active.} @r{The entire text will be indented like @code{%i} itself.} %t @r{timestamp, date only} %T @r{timestamp with date and time} @@ -5885,124 +6384,58 @@ allow dynamic insertion of content: %x @r{Content of the X clipboard.} %^C @r{Interactive selection of which kill or clip to use.} %^L @r{Like @code{%^C}, but insert as link.} +%k @r{title of the currently clocked task} +%K @r{link to the currently clocked task} %^g @r{prompt for tags, with completion on tags in target file.} -%k @r{title of currently clocked task} -%K @r{link to currently clocked task} %^G @r{prompt for tags, with completion all tags in all agenda files.} %^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}} %:keyword @r{specific information for certain link types, see below} %[@var{file}] @r{insert the contents of the file given by @var{file}} %(@var{sexp}) @r{evaluate Elisp @var{sexp} and replace with the result} -%! @r{immediately store note after completing the template} - @r{(skipping the @kbd{C-c C-c} that normally triggers storing)} -%& @r{jump to target location immediately after storing note} -@end example +@end smallexample @noindent For specific link types, the following keywords will be defined@footnote{If you define your own link types (@pxref{Adding hyperlink types}), any property you store with -@code{org-store-link-props} can be accessed in remember templates in a +@code{org-store-link-props} can be accessed in capture templates in a similar way.}: @vindex org-from-is-user-regexp -@example +@smallexample Link type | Available keywords -------------------+---------------------------------------------- -bbdb | %:name %:company -bbdb | %::server %:port %:nick -vm, wl, mh, rmail | %:type %:subject %:message-id - | %:from %:fromname %:fromaddress - | %:to %:toname %:toaddress - | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}} -gnus | %:group, @r{for messages also all email fields} -w3, w3m | %:url -info | %:file %:node -calendar | %:date" -@end example +bbdb | %:name %:company +irc | %:server %:port %:nick +vm, wl, mh, mew, rmail | %:type %:subject %:message-id + | %:from %:fromname %:fromaddress + | %:to %:toname %:toaddress + | %:date @r{(message date header field)} + | %:date-timestamp @r{(date as active timestamp)} + | %:date-timestamp-inactive @r{(date as inactive timestamp)} + | %: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 smallexample @noindent To place the cursor after template expansion use: -@example +@smallexample %? @r{After completing the template, position cursor here.} -@end example - -@noindent -If you change your mind about which template to use, call -@code{org-remember} in the remember buffer. You may then select a new -template that will be filled with the previous context information. - -@node Storing notes, , Remember templates, Remember -@subsection Storing notes - -@vindex org-remember-clock-out-on-exit -When you are finished preparing a note with Remember, you have to press -@kbd{C-c C-c} to file the note away. If you have started the clock in the -Remember buffer, you will first be asked if you want to clock out -now@footnote{To avoid this query, configure the variable -@code{org-remember-clock-out-on-exit}.}. If you answer @kbd{n}, the clock -will continue to run after the note was filed away. - -The handler will then store the note in the file and under the headline -specified in the template, or it will use the default file and headline. -The window configuration will be restored, sending you back to the working -context before the call to Remember. To re-use the location found -during the last call to Remember, exit the Remember buffer with -@kbd{C-0 C-c C-c}, i.e. specify a zero prefix argument to @kbd{C-c C-c}. -Another special case is @kbd{C-2 C-c C-c} which files the note as a child of -the currently clocked item. - -@vindex org-remember-store-without-prompt -If you want to store the note directly to a different place, use -@kbd{C-1 C-c C-c} instead to exit Remember@footnote{Configure the -variable @code{org-remember-store-without-prompt} to make this behavior -the default.}. The handler will then first prompt for a target file---if -you press @key{RET}, the value specified for the template is used. -Then the command offers the headings tree of the selected file, with the -cursor position at the default headline (if you specified one in the -template). You can either immediately press @key{RET} to get the note -placed there. Or you can use the following keys to find a different -location: -@example -@key{TAB} @r{Cycle visibility.} -@key{down} / @key{up} @r{Next/previous visible headline.} -n / p @r{Next/previous visible headline.} -f / b @r{Next/previous headline same level.} -u @r{One level up.} -@c 0-9 @r{Digit argument.} -@end example -@noindent -Pressing @key{RET} or @key{left} or @key{right} -then leads to the following result. - -@vindex org-reverse-note-order -@multitable @columnfractions 0.2 0.15 0.65 -@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted} -@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last -@item @tab @tab depending on @code{org-reverse-note-order}. -@item @tab @key{left}/@key{right} @tab as same level, before/after current heading -@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning -@item @tab @tab depending on @code{org-reverse-note-order}. -@item not on headline @tab @key{RET} - @tab at cursor position, level taken from context. -@end multitable - -Before inserting the text into a tree, the function ensures that the text has -a headline, i.e. a first line that starts with a @samp{*}. If not, a -headline is constructed from the current date. If you have indented the text -of the note below the headline, the indentation will be adapted if inserting -the note into the tree requires demotion from level 1. +@end smallexample -@node Attachments, RSS Feeds, Remember, Capture - Refile - Archive +@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive @section Attachments @cindex attachments @vindex org-attach-directory It is often useful to associate reference material with an outline node/task. Small chunks of plain text can simply be stored in the subtree of a project. -Hyperlinks (@pxref{Hyperlinks}) can be used to establish associations with +Hyperlinks (@pxref{Hyperlinks}) can establish associations with files that live elsewhere on your computer or in the cloud, like emails or source code files belonging to a project. Another method is @i{attachments}, which are files located in a directory belonging to an outline node. Org @@ -6019,19 +6452,17 @@ choice to an entry. You can also make children inherit the attachment directory from a parent, so that an entire subtree uses the same attached directory. -@noindent The following commands deal with attachments. +@noindent The following commands deal with attachments: @table @kbd -@kindex C-c C-a -@item C-c C-a +@orgcmd{C-c C-a,org-attach} The dispatcher for commands related to the attachment system. After these -keys, a list of commands is displayed and you need to press an additional key +keys, a list of commands is displayed and you must press an additional key to select a command: @table @kbd -@kindex C-c C-a a -@item a +@orgcmdtkc{a,C-c C-a a,org-attach-attach} @vindex org-attach-method Select a file and move it into the task's attachment directory. The file will be copied, moved, or linked, depending on @code{org-attach-method}. @@ -6044,52 +6475,42 @@ Note that hard links are not supported on all systems. Attach a file using the copy/move/link method. Note that hard links are not supported on all systems. -@kindex C-c C-a n -@item n +@orgcmdtkc{n,C-c C-a n,org-attach-new} Create a new attachment as an Emacs buffer. -@kindex C-c C-a z -@item z +@orgcmdtkc{z,C-c C-a z,org-attach-sync} Synchronize the current task with its attachment directory, in case you added attachments yourself. -@kindex C-c C-a o -@item o +@orgcmdtkc{p,C-c C-a o,org-attach-open} @vindex org-file-apps -Open current task's attachment. If there are more than one, prompt for a +Open current task's attachment. If there is more than one, prompt for a file name first. Opening will follow the rules set by @code{org-file-apps}. For more details, see the information on following hyperlinks (@pxref{Handling links}). -@kindex C-c C-a O -@item O +@orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs} Also open the attachment, but force opening the file in Emacs. -@kindex C-c C-a f -@item f +@orgcmdtkc{f,C-c C-a f,org-attach-reveal} Open the current task's attachment directory. -@kindex C-c C-a F -@item F +@orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs} Also open the directory, but force using @command{dired} in Emacs. -@kindex C-c C-a d -@item d +@orgcmdtkc{d,C-c C-a d,org-attach-delete-one} Select and delete a single attachment. -@kindex C-c C-a D -@item D +@orgcmdtkc{D,C-c C-a D,org-attach-delete-all} Delete all of a task's attachments. A safer way is to open the directory in @command{dired} and delete from there. -@kindex C-c C-a s -@item C-c C-a s +@orgcmdtkc{s,C-c C-a s,org-attach-set-directory} @cindex property, ATTACH_DIR Set a specific directory as the entry's attachment directory. This works by putting the directory path into the @code{ATTACH_DIR} property. -@kindex C-c C-a i -@item C-c C-a i +@orgcmdtkc{i,C-c C-a i,org-attach-set-inherit} @cindex property, ATTACH_DIR_INHERIT Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the same directory for attachments as the parent does. @@ -6099,31 +6520,34 @@ same directory for attachments as the parent does. @node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive @section RSS feeds @cindex RSS feeds +@cindex Atom feeds -Org has the capability to add and change entries based on information found in -RSS feeds. You could use this to make a task out of each new podcast in a +Org can add and change entries based on information found in RSS feeds and +Atom feeds. You could use this to make a task out of each new podcast in a podcast feed. Or you could use a phone-based note-creating service on the -web to import tasks into Org. To access feeds, you need to configure the -variable @code{org-feed-alist}. The docstring of this variable has detailed +web to import tasks into Org. To access feeds, configure the variable +@code{org-feed-alist}. The docstring of this variable has detailed information. Here is just an example: @example (setq org-feed-alist - '(("ReQall" "http://www.reqall.com/user/feeds/rss/a1b2c3....." - "~/org/feeds.org" "ReQall Entries") + '(("Slashdot" + "http://rss.slashdot.org/Slashdot/slashdot" + "~/txt/org/feeds.org" "Slashdot Entries"))) @end example + @noindent -will configure that new items from the feed provided by @file{reqall.com} -will result in new entries in the file @file{~/org/feeds.org} under the -heading @samp{ReQall Entries}, whenever the following command is used: +will configure that new items from the feed provided by +@code{rss.slashdot.org} will result in new entries in the file +@file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever +the following command is used: @table @kbd -@kindex C-c C-x g +@orgcmd{C-c C-x g,org-feed-update-all} @item C-c C-x g Collect items from the feeds configured in @code{org-feed-alist} and act upon them. -@kindex C-c C-x G -@item C-c C-x G +@orgcmd{C-c C-x G,org-feed-goto-inbox} Prompt for a feed name and go to the inbox configured for this feed. @end table @@ -6136,8 +6560,8 @@ list of drawers in that file: #+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS @end example -For more information, see @file{org-feed.el} and the docstring of -@code{org-feed-alist}. +For more information, including how to read atom feeds, see +@file{org-feed.el} and the docstring of @code{org-feed-alist}. @node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive @section Protocols for external access @@ -6147,7 +6571,7 @@ For more information, see @file{org-feed.el} and the docstring of You can set up Org for handling protocol calls from outside applications that are passed to Emacs through the @file{emacsserver}. For example, you can configure bookmarks in your web browser to send a link to the current page to -Org and create a note from it using Remember (@pxref{Remember}). Or you +Org and create a note from it using capture (@pxref{Capture}). Or you could create a bookmark that will tell Emacs to open the local source file of a remote website you are looking at with the browser. See @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed @@ -6163,13 +6587,14 @@ right location, and then pasting the note is cumbersome. To simplify this process, you can use the following special command: @table @kbd -@kindex C-c C-w -@item C-c C-w +@orgcmd{C-c C-w,org-refile} @vindex org-reverse-note-order @vindex org-refile-targets @vindex org-refile-use-outline-path @vindex org-outline-path-complete-in-steps @vindex org-refile-allow-creating-parent-nodes +@vindex org-log-refile +@vindex org-refile-use-cache Refile the entry or region at point. This command offers possible locations for refiling the entry and lets you select one with completion. The item (or all items in the region) is filed below the target heading as a subitem. @@ -6183,14 +6608,23 @@ the variables @code{org-refile-use-outline-path} and @code{org-outline-path-complete-in-steps}. If you would like to be able to create new nodes as new parents for refiling on the fly, check the variable @code{org-refile-allow-creating-parent-nodes}. -@kindex C-u C-c C-w -@item C-u C-c C-w +When the variable @code{org-log-refile}@footnote{with corresponding +@code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile}, +and @code{nologrefile}} is set, a time stamp or a note will be +recorded when an entry has been refiled. +@orgkey{C-u C-c C-w} Use the refile interface to jump to a heading. -@kindex C-u C-u C-c C-w -@item C-u C-u C-c C-w +@orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored} Jump to the location where @code{org-refile} last moved a tree to. @item C-2 C-c C-w Refile as the child of the item currently being clocked. +@item C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w + +@orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear} + +Clear the target cache. Caching of refile targets can be turned on by +setting @code{org-refile-use-cache}. To make the command see new possible +targets, you have to clear the cache with this command. @end table @node Archiving, , Refiling notes, Capture - Refile - Archive @@ -6203,8 +6637,7 @@ agenda. Archiving is important to keep your working files compact and global searches like the construction of agenda views fast. @table @kbd -@kindex C-c C-x C-a -@item C-c C-x C-a +@orgcmd{C-c C-x C-a,org-archive-subtree-default} @vindex org-archive-default-command Archive the current entry using the command specified in the variable @code{org-archive-default-command}. @@ -6212,7 +6645,7 @@ Archive the current entry using the command specified in the variable @menu * Moving subtrees:: Moving a tree to an archive file -* Internal archiving:: Switch off a tree but keep i in the file +* Internal archiving:: Switch off a tree but keep it in the file @end menu @node Moving subtrees, Internal archiving, Archiving, Archiving @@ -6223,14 +6656,11 @@ The most common archiving action is to move a project tree to another file, the archive file. @table @kbd -@kindex C-c $ -@kindex C-c C-x C-s -@item C-c C-x C-s@ @r{or short} @ C-c $ +@orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree} @vindex org-archive-location Archive the subtree starting at the cursor position to the location given by @code{org-archive-location}. -@kindex C-u C-c C-x C-s -@item C-u C-c C-x C-s +@orgkey{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 @@ -6305,31 +6735,27 @@ Archived trees are not exported (@pxref{Exporting}), only the headline is. Configure the details using the variable @code{org-export-with-archived-trees}. @item -@vindex org-columns-skip-arrchived-trees +@vindex org-columns-skip-archived-trees Archived trees are excluded from column view unless the variable -@code{org-columns-skip-arrchived-trees} is configured to @code{nil}. +@code{org-columns-skip-archived-trees} is configured to @code{nil}. @end itemize -The following commands help managing the ARCHIVE tag: +The following commands help manage the ARCHIVE tag: @table @kbd -@kindex C-c C-x a -@item C-c C-x a +@orgcmd{C-c C-x a,org-toggle-archive-tag} Toggle the ARCHIVE tag for the current headline. When the tag is set, the headline changes to a shadowed face, and the subtree below it is hidden. -@kindex C-u C-c C-x a -@item C-u C-c C-x a +@orgkey{C-u C-c C-x a} Check if any direct children of the current headline should be archived. To do this, each subtree is checked for open TODO entries. If none are found, the command offers to set the ARCHIVE tag for the child. If the cursor is @emph{not} on a headline when this command is invoked, the level 1 trees will be checked. -@kindex C-@kbd{TAB} -@item C-@kbd{TAB} +@orgcmd{C-@kbd{TAB},org-force-cycle-archived} Cycle a tree even if it is tagged with ARCHIVE. -@kindex C-c C-x A -@item C-c C-x A +@orgcmd{C-c C-x A,org-archive-to-archive-sibling} Move the current entry to the @emph{Archive Sibling}. This is a sibling of the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The entry becomes a child of that sibling and in this way retains a lot of its @@ -6339,7 +6765,7 @@ outline. @node Agenda Views, Markup, Capture - Refile - Archive, Top -@chapter Agenda Views +@chapter Agenda views @cindex agenda views Due to the way Org works, TODO items, time-stamped items, and @@ -6422,18 +6848,15 @@ 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 [ +@orgcmd{C-c [,org-agenda-to-front} Add current file to the list of agenda files. The file is added to the front of the list. If it was already in the list, it is moved to the front. With a prefix argument, file is added/moved to the end. -@kindex C-c ] -@item C-c ] +@orgcmd{C-c ],org-remove-file} Remove current file from the list of agenda files. @kindex C-, -@kindex C-' -@item C-, -@itemx C-' +@orgcmd{C-',org-cycle-agenda-files} +@itemx C-, Cycle through agenda file list, visiting one file after the other. @kindex M-x org-iswitchb @item M-x org-iswitchb @@ -6453,16 +6876,14 @@ you may press @kbd{<} once or several times in the dispatcher extended period, use the following commands: @table @kbd -@kindex C-c C-x < -@item C-c C-x < +@orgcmd{C-c C-x <,org-agenda-set-restriction-lock} Permanently restrict the agenda to the current subtree. When with a prefix argument, or with the cursor before the first headline in a file, the agenda scope is set to the entire file. This restriction remains in effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<} or @kbd{>} in the agenda dispatcher. If there is a window displaying an agenda view, the new restriction takes effect immediately. -@kindex C-c C-x > -@item C-c C-x > +@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock} Remove the permanent restriction created by @kbd{C-c C-x <}. @end table @@ -6470,14 +6891,12 @@ Remove the permanent restriction created by @kbd{C-c C-x <}. When working with @file{speedbar.el}, you can use the following commands in the Speedbar frame: @table @kbd -@kindex < -@item < @r{in the speedbar frame} +@orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction} Permanently restrict the agenda to the item---either an Org file or a subtree in such a file---at the cursor in the Speedbar frame. If there is a window displaying an agenda view, the new restriction takes effect immediately. -@kindex > -@item > @r{in the speedbar frame} +@orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock} Lift the restriction. @end table @@ -6557,18 +6976,23 @@ 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 -@vindex org-agenda-ndays +@orgcmd{C-c a a,org-agenda-list} Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. With a numeric prefix@footnote{For backward compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be listed before the agenda. This feature is deprecated, use the dedicated TODO list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1 -C-c a a}) you may set the number of days to be displayed (see also the -variable @code{org-agenda-ndays}) +C-c a a}) you may set the number of days to be displayed. @end table +@vindex org-agenda-span +@vindex org-agenda-ndays +The default number of days displayed in the agenda is set by the variable +@code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This +variable can be set to any number of days you want to see by default in the +agenda, or to a span name, such a @code{day}, @code{week}, @code{month} or +@code{year}. + 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 @@ -6586,7 +7010,7 @@ anniversaries, lunar phases, sunrise/set, recurrent appointments Org. It can be very useful to combine output from Org with the diary. -In order to include entries from the Emacs diary into Org mode's +In order to include entries from the Emacs diary into Org-mode's agenda, you only need to customize the variable @lisp @@ -6595,7 +7019,7 @@ agenda, you only need to customize the variable @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 +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 @@ -6606,7 +7030,7 @@ between calendar and agenda. If you are using the diary only for sexp entries and holidays, it is faster to not use the above setting, but instead to copy or even move -the entries into an Org file. Org mode evaluates diary-style sexp +the entries into an Org file. Org-mode evaluates diary-style sexp entries, and does it faster because there is no overhead for first creating the diary display. Note that the sexp entries must start at the left margin, no whitespace is allowed before them. For example, @@ -6618,8 +7042,8 @@ will be made in the agenda: #+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 +%%(diary-anniversary 5 14 1956)@footnote{Note that the order of the arguments (month, day, year) depends on the setting of @code{calendar-date-style}.} Arthur Dent is %d years old +%%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old @end example @subsubheading Anniversaries from BBDB @@ -6636,7 +7060,7 @@ following to one your your agenda files: * Anniversaries :PROPERTIES: :CATEGORY: Anniv - :END + :END: %%(org-bbdb-anniversaries) @end example @@ -6679,22 +7103,20 @@ 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 +@orgcmd{C-c a t,org-todo-list} +Show the global TODO list. This collects the TODO items from all agenda +files (@pxref{Agenda Views}) into a single buffer. By default, this lists +items with a state the is not a DONE state. 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}). +@orgcmd{C-c a T,org-todo-list} @cindex TODO keyword matching @vindex org-todo-keywords -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 the boolean OR -operator. With a numeric prefix, the nth keyword in -@code{org-todo-keywords} is selected. +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}. You are +prompted for a keyword, and you may also specify several keywords by +separating them with @samp{|} as the 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, @@ -6716,13 +7138,15 @@ it more compact: @item @vindex org-agenda-todo-ignore-scheduled @vindex org-agenda-todo-ignore-deadlines +@vindex org-agenda-todo-ignore-timestamp @vindex org-agenda-todo-ignore-with-date Some people view a TODO item that has been @emph{scheduled} for execution or have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}. Configure the variables @code{org-agenda-todo-ignore-scheduled}, -@code{org-agenda-todo-ignore-deadlines}, and/or -@code{org-agenda-todo-ignore-with-date} to exclude such items from the -global TODO list. +@code{org-agenda-todo-ignore-deadlines}, +@code{org-agenda-todo-ignore-timestamp} and/or +@code{org-agenda-todo-ignore-with-date} to exclude such items from the global +TODO list. @item @vindex org-agenda-todo-list-sublevels TODO items may have sublevels to break up the task into subtasks. In @@ -6745,22 +7169,21 @@ syntax described here also applies when creating sparse trees with @kbd{C-c / m}. @table @kbd -@kindex C-c a m -@item C-c a m +@orgcmd{C-c a m,org-tags-view} 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 +@orgcmd{C-c a M,org-tags-view} @vindex org-tags-match-list-sublevels @vindex org-agenda-tags-todo-honor-ignore-options -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}). -To exclude scheduled/deadline items, see the variable -@code{org-agenda-tags-todo-honor-ignore-options}. Matching specific TODO -keywords together with a tags match is also possible, see @ref{Tag searches}. +Like @kbd{C-c a m}, but only select headlines that are also TODO items in a +not-DONE state and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items, +see the variable @code{org-agenda-tags-todo-honor-ignore-options}. 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 @@ -6865,7 +7288,7 @@ other properties will slow down the search. However, once you have paid the price by accessing one property, testing additional properties is cheap again. -You can configure Org mode to use property inheritance during a search, but +You can configure Org-mode to use property inheritance during a search, but beware that this can slow down searches considerably. See @ref{Property inheritance}, for details. @@ -6874,12 +7297,13 @@ different way to test TODO states in a search. For this, terminate the tags/property part of the search string (which may include several terms connected with @samp{|}) with a @samp{/} and then specify a Boolean expression just for TODO keywords. The syntax is then similar to that for -tags, but should be applied with care: for example, a positive -selection on several TODO keywords cannot meaningfully be combined with -boolean AND. However, @emph{negative selection} combined with AND can be -meaningful. To make sure that only lines are checked that actually have any -TODO keyword (resulting in a speed-up), use @kbd{C-c a M}, or equivalently -start the TODO part after the slash with @samp{!}. Examples: +tags, but should be applied with care: for example, a positive selection on +several TODO keywords cannot meaningfully be combined with boolean AND. +However, @emph{negative selection} combined with AND can be meaningful. To +make sure that only lines are checked that actually have any TODO keyword +(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO +part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will +not match TODO keywords in a DONE state. Examples: @table @samp @item work/WAITING @@ -6897,13 +7321,12 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or @cindex timeline, single file @cindex time-sorted view -The timeline summarizes all time-stamped items from a single Org mode +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 +@orgcmd{C-c a L,org-timeline} 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. @@ -6919,12 +7342,11 @@ The commands available in the timeline buffer are listed in @cindex text search @cindex searching, for text -This agenda view is a general text search facility for Org mode entries. +This agenda view is a general text search facility for Org-mode entries. It is particularly useful to find notes. @table @kbd -@kindex C-c a s -@item C-c a s +@orgcmd{C-c a s,org-search-view} This is a special search that lets you select entries by matching a substring or specific words using a boolean logic. @end table @@ -6936,7 +7358,9 @@ logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}} will search for note entries that contain the keywords @code{computer} and @code{wifi}, but not the keyword @code{ethernet}, and which are also not matched by the regular expression @code{8\.11[bg]}, meaning to -exclude both 8.11b and 8.11g. +exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on +word search, other @samp{+} characters are optional. For more details, see +the docstring of the command @code{org-search-view}. @vindex org-agenda-text-search-extra-files Note that in addition to the agenda files, this command will also search @@ -6949,12 +7373,11 @@ 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 +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 # +@orgcmd{C-c a #,org-agenda-list-stuck-projects} List projects that are stuck. @kindex C-c a ! @item C-c a ! @@ -6968,7 +7391,7 @@ work for you. The built-in default assumes that all your projects are level-2 headlines, and that a project is not stuck if it has at least one entry marked with a TODO keyword TODO or NEXT or NEXTACTION. -Let's assume that you, in your own way of using Org mode, identify +Let's assume that you, in your own way of using Org-mode, identify projects with a tag PROJECT, and that you use a TODO keyword MAYBE to indicate a project that should not be considered yet. Let's further assume that the TODO keyword DONE marks finished projects, and that NEXT @@ -6995,7 +7418,7 @@ will still be searched for stuck projects. @cindex presentation, of agenda items @vindex org-agenda-prefix-format -Before displaying items in an agenda view, Org mode visually prepares +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 @@ -7013,6 +7436,7 @@ associated with the item. @subsection Categories @cindex category +@cindex #+CATEGORY The category is a broad label assigned to each agenda item. By default, the category is simply derived from the file name, but you can also specify it with a special line in the buffer, like this@footnote{For @@ -7038,11 +7462,15 @@ special category you want to apply as the value. The display in the agenda buffer looks best if the category is not longer than 10 characters. +@noindent +You can set up icons for category by customizing the +@code{org-agenda-category-icon-alist} variable. + @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 +Org-mode checks each agenda item for a time-of-day specification. The time can be part of the timestamp 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 timestamps, like @@ -7054,7 +7482,7 @@ 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 +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: @@ -7140,40 +7568,26 @@ 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 +@orgcmd{n,org-agenda-next-line} Next line (same as @key{up} and @kbd{C-p}). -@kindex p -@item p +@orgcmd{p,org-agenda-previous-line} Previous line (same as @key{down} and @kbd{C-n}). @tsubheading{View/Go to Org file} -@kindex mouse-3 -@kindex @key{SPC} -@item mouse-3 -@itemx @key{SPC} +@orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up} Display the original location of the item in another window. With prefix arg, make sure that the entire entry is made visible in the outline, not only the heading. @c -@kindex L -@item L +@orgcmd{L,org-agenda-recenter} 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. +@orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto} +Go to the original location of the item in another window. @c -@kindex @key{RET} -@itemx @key{RET} +@orgcmd{@key{RET},org-agenda-switch-to} Go to the original location of the item and delete other windows. @c -@kindex F -@item F +@orgcmd{F,org-agenda-follow-mode} @vindex org-agenda-start-with-follow-mode Toggle Follow mode. In Follow mode, as you move the cursor through the agenda buffer, the other window always shows the corresponding @@ -7181,15 +7595,13 @@ 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 C-c C-x b -@item C-c C-x b +@orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer} Display the entire subtree of the current item in an indirect buffer. With a numeric prefix argument N, go up to level N and then take that tree. If N is negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the previously used indirect buffer. -@kindex C-c C-o -@item C-c C-o +@orgcmd{C-c C-o,org-agenda-open-link} Follow a link in the entry. This will offer a selection of any links in the text belonging to the referenced Org node. If there is only one link, it will be followed without a selection prompt. @@ -7200,16 +7612,20 @@ will be followed without a selection prompt. @item o Delete other windows. @c -@kindex v d -@kindex d -@kindex v w -@kindex w -@kindex v m -@kindex v y -@item v d @ @r{or short} @ d -@itemx v w @ @r{or short} @ w -@itemx v m -@itemx v y +@c @kindex v d +@c @kindex d +@c @kindex v w +@c @kindex w +@c @kindex v m +@c @kindex v y +@c @item v d @ @r{or short} @ d +@c @itemx v w @ @r{or short} @ w +@c @itemx v m +@c @itemx v y +@orgcmdkskc{v d,d,org-aganda-day-view} +@xorgcmdkskc{v w,w,org-aganda-day-view} +@xorgcmd{v m,org-agenda-month-view} +@xorgcmd{v y,org-agenda-month-year} Switch to day/week/month/year view. When switching to day or week view, this setting becomes the default for subsequent agenda commands. Since month and year views are slow to create, they do not become the default. @@ -7221,32 +7637,28 @@ argument as well. For example, @kbd{200712 w} will jump to week 12 in 2007. If such a year specification has only one or two digits, it will be mapped to the interval 1938-2037. @c -@kindex f -@item f -@vindex org-agenda-ndays -Go forward in time to display the following @code{org-agenda-ndays} days. +@orgcmd{f,org-agenda-later} +Go forward in time to display the following @code{org-agenda-current-span} 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. +With prefix arg, go forward that many times @code{org-agenda-current-span} days. @c -@kindex b -@item b +@orgcmd{b,org-agenda-earlier} Go backward in time to display earlier dates. @c -@kindex . -@item . +@orgcmd{.,org-agenda-goto-today} Go to today. @c -@kindex j -@item j +@orgcmd{j,org-agenda-goto-date} Prompt for a date and go there. @c -@kindex D -@item D +@orgcmd{J,org-agenda-clock-goto} +Go to the currently clocked-in task @i{in the agenda buffer}. +@c +@orgcmd{D,org-agenda-toggle-diary} Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}. @c -@kindex v l -@kindex l -@item v l @ @r{or short} @ l +@orgcmdkskc{v l,l,org-agenda-log-mode} +@kindex v L @vindex org-log-done @vindex org-agenda-log-mode-items Toggle Logbook mode. In Logbook mode, entries that were marked DONE while @@ -7256,35 +7668,31 @@ types that should be included in log mode using the variable @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show all possible logbook entries, including state changes. When called with two prefix args @kbd{C-u C-u}, show only logging information, nothing else. +@kbd{v L} is equivalent to @kbd{C-u v l}. @c -@kindex v [ -@kindex [ -@item v [ @ @r{or short} @ [ +@orgcmdkskc{v [,[,org-agenda-manipulate-query-add} Include inactive timestamps into the current view. Only for weekly/daily agenda and timeline views. @c -@kindex v a -@kindex v A -@item v a -@itemx v A +@orgcmd{v a,org-agenda-archives-mode} +@xorgcmd{v A,org-agenda-archives-mode 'files} Toggle Archives mode. In Archives mode, trees that are marked @code{ARCHIVED} are also scanned when producing the agenda. When you use the capital @kbd{A}, even all archive files are included. To exit archives mode, press @kbd{v a} again. @c -@kindex v R -@kindex R -@item v R @ @r{or short} @ R +@orgcmdkskc{v R,R,org-agenda-clockreport-mode} @vindex org-agenda-start-with-clockreport-mode Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will always show a table with the clocked times for the timespan and file scope covered by the current agenda view. The initial setting for this mode in new agenda buffers can be set with the variable -@code{org-agenda-start-with-clockreport-mode}. +@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument +when toggling this mode (i.e. @kbd{C-u R}), the clock table will not show +contributions from entries that are hidden by agenda filtering@footnote{Only +tags filtering will be respected here, effort filtering is ignored.}. @c -@kindex v E -@kindex E -@item v E @ @r{or short} @ E +@orgcmdkskc{v E,E,org-agenda-entry-text-mode} @vindex org-agenda-start-with-entry-text-mode @vindex org-agenda-entry-text-maxlines Toggle entry text mode. In entry text mode, a number of lines from the Org @@ -7293,33 +7701,26 @@ The maximum number of lines is given by the variable @code{org-agenda-entry-text-maxlines}. Calling this command with a numeric prefix argument will temporarily modify that number to the prefix value. @c -@kindex G -@item G +@orgcmd{G,org-agenda-toggle-time-grid} @vindex org-agenda-use-time-grid @vindex org-agenda-time-grid 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 +@orgcmd{r,org-agenda-rodo} Recreate the agenda buffer, for example to reflect the changes after modification of the timestamps of items with @kbd{S-@key{left}} and @kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix argument is interpreted to create a selective list for a specific TODO keyword. -@kindex g -@item g +@orgcmd{g,org-agenda-rodo} Same as @kbd{r}. @c -@kindex s -@kindex C-x C-s -@item s -@itemx C-x C-s +@orgcmdkskc{C-x C-s,s,org-save-all-org-buffers} Save all Org buffers in the current Emacs session, and also the locations of IDs. @c -@kindex C-c C-x C-c -@item C-c C-x C-c +@orgcmd{C-c C-x C-c,org-agenda-columns} @vindex org-columns-default-format Invoke column view (@pxref{Column view}) in the agenda buffer. The column view format is taken from the entry at point, or (if there is no entry at @@ -7328,8 +7729,7 @@ that entry would be in the original buffer (taken from a property, from a @code{#+COLUMNS} line, or from the default variable @code{org-columns-default-format}), will be used in the agenda. -@kindex C-c C-x > -@item C-c C-x > +@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock} Remove the restriction lock on the agenda, if it is currently restricted to a file or subtree (@pxref{Agenda files}). @@ -7339,18 +7739,19 @@ file or subtree (@pxref{Agenda files}). @cindex effort filtering, in agenda @cindex query editing, in agenda -@kindex / -@item / +@orgcmd{/,org-agenda-filter-by-tag} @vindex org-agenda-filter-preset Filter the current agenda view with respect to a tag and/or effort estimates. The difference between this and a custom agenda command is that filtering is very fast, so that you can switch quickly between different filters without -having to recreate the agenda@footnote{Custom commands can preset a filter by +having to recreate the agenda.@footnote{Custom commands can preset a filter by binding the variable @code{org-agenda-filter-preset} as an option. This filter will then be applied to the view and persist as a basic filter through -refreshes and more secondary filtering.} +refreshes and more secondary filtering. The filter is a global property of +the entire agenda view---in a block agenda, you should only set this in the +global options section, not in the section of an individual block.} -You will be prompted for a tag selection letter, SPC will mean any tag at +You will be prompted for a tag selection letter; @key{SPC} will mean any tag at all. Pressing @key{TAB} at that prompt will offer use completion to select a tag (including any tags that do not have a selection character). The command then hides all entries that do not contain or inherit this tag. When called @@ -7362,7 +7763,7 @@ Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also immediately use the @kbd{\} command. @vindex org-sort-agenda-noeffort-is-high -In order to filter for effort estimates, you should set-up allowed +In order to filter for effort estimates, you should set up allowed efforts globally, for example @lisp (setq org-global-properties @@ -7405,13 +7806,13 @@ Internet, and outside of business hours, with something like this: @end group @end lisp -@kindex \ -@item \ +@orgcmd{\,org-agenda-filter-by-tag-refine} Narrow the current agenda filter by an additional condition. When called with prefix arg, remove the entries that @emph{do} have the tag, or that do match the effort criterion. You can achieve the same effect by pressing @kbd{+} or @kbd{-} as the first key after the @kbd{/} command. +@c @kindex [ @kindex ] @kindex @{ @@ -7427,7 +7828,6 @@ negative search term which @i{must not} occur/match in the entry for it to be selected. @end table -@page @tsubheading{Remote editing} @cindex remote editing, from agenda @@ -7436,114 +7836,89 @@ Digit argument. @c @cindex undoing remote-editing events @cindex remote editing, undo -@kindex C-_ -@item C-_ +@orgcmd{C-_,org-agenda-undo} 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 +@orgcmd{t,org-agenda-todo} Change the TODO state of the item, both in the agenda and in the original org file. @c -@kindex C-S-@key{right} -@kindex C-S-@key{left} -@item C-S-@key{right}@r{/}@key{left} +@orgcmd{C-S-@key{right},org-agenda-todo-nextset} +@orgcmd{C-S-@key{left},org-agenda-todo-previousset} Switch to the next/previous set of TODO keywords. @c -@kindex C-k -@item C-k +@orgcmd{C-k,org-agenda-kill} @vindex org-agenda-confirm-kill Delete the current agenda item along with the entire subtree belonging to it in the original Org file. If the text to be deleted remotely is longer than one line, the kill needs to be confirmed by the user. See variable @code{org-agenda-confirm-kill}. @c -@kindex C-c C-w -@item C-c C-w +@orgcmd{C-c C-w,org-agenda-refile} Refile the entry at point. @c -@kindex C-c C-x C-a -@kindex a -@item C-c C-x C-a @ @r{or short} @ a +@orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation} @vindex org-archive-default-command Archive the subtree corresponding to the entry at point using the default archiving command set in @code{org-archive-default-command}. When using the @code{a} key, confirmation will be required. @c -@kindex C-c C-x a -@item C-c C-x a +@orgcmd{C-c C-x a,org-agenda-toggle-archive-tag} Toggle the ARCHIVE tag for the current headline. @c -@kindex C-c C-x A -@item C-c C-x A +@orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling} Move the subtree corresponding to the current entry to its @emph{archive sibling}. @c -@kindex $ -@kindex C-c C-x C-s -@item C-c C-x C-s @ @r{or short} @ $ +@orgcmdkskc{C-c C-x C-s,$,org-agenda-archive} Archive the subtree corresponding to the current headline. This means the entry will be moved to the configured archive location, most likely a different file. @c -@kindex T -@item T +@orgcmd{T,org-agenda-show-tags} @vindex org-agenda-show-inherited-tags Show all tags associated with the current item. This is useful if you have turned off @code{org-agenda-show-inherited-tags}, but still want to see all tags of a headline occasionally. @c -@kindex : -@item : +@orgcmd{:,org-agenda-set-tags} Set tags for the current headline. If there is an active region in the agenda, change a tag for all headings in the region. @c @kindex , @item , -Set the priority for the current item. Org mode prompts for the -priority character. If you reply with @key{SPC}, the priority cookie -is removed from the entry. +Set the priority for the current item (@command{org-agenda-priority}). +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 +@orgcmd{P,org-agenda-show-priority} Display weighted priority of current item. @c -@kindex + -@kindex S-@key{up} -@item + -@itemx S-@key{up} +@orgcmdkkc{+,S-@key{up},org-agenda-priority-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} +@orgcmdkkc{-,S-@key{down},org-agenda-priority-down} Decrease the priority of the current item. @c -@kindex z -@item z +@orgcmdkkc{z,C-c C-z,org-agenda-add-note} @vindex org-log-into-drawer -Add a note to the entry. This note will be recorded, and then files to the +Add a note to the entry. This note will be recorded, and then filed to the same location where state change notes are put. Depending on -@code{org-log-into-drawer}, this maybe inside a drawer. +@code{org-log-into-drawer}, this may be inside a drawer. @c -@kindex C-c C-a -@item C-c C-a +@orgcmd{C-c C-a,org-attach} Dispatcher for all command related to attachments. @c -@kindex C-c C-s -@item C-c C-s -Schedule this item +@orgcmd{C-c C-s,org-agenda-schedule} +Schedule this item. With prefix arg remove the scheduling timestamp @c -@kindex C-c C-d -@item C-c C-d -Set a deadline for this item. +@orgcmd{C-c C-d,org-agenda-deadline} +Set a deadline for this item. With prefix arg remove the deadline. @c -@kindex k -@item k +@orgcmd{k,org-agenda-action} Agenda actions, to set dates for selected items to the cursor date. This command also works in the calendar! The command prompts for an additional key: @@ -7552,14 +7927,13 @@ m @r{Mark the entry at point for action. You can also make entries} @r{in Org files with @kbd{C-c C-x C-k}.} d @r{Set the deadline of the marked entry to the date at point.} s @r{Schedule the marked entry at the date at point.} -r @r{Call @code{org-remember} with the cursor date as default date.} +r @r{Call @code{org-capture} with the cursor date as default date.} @end example @noindent Press @kbd{r} afterward to refresh the agenda and see the effect of the command. @c -@kindex S-@key{right} -@item S-@key{right} +@orgcmd{S-@key{right},org-agenda-do-date-later} Change the timestamp associated with the current line by one day into the future. With a numeric prefix argument, change it by that many days. For example, @kbd{3 6 5 S-@key{right}} will change it by a year. With a @@ -7569,56 +7943,48 @@ a double @kbd{C-u C-u} prefix, do the same for changing minutes. The stamp is changed in the original Org file, but the change is not directly reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer. @c -@kindex S-@key{left} -@item S-@key{left} +@orgcmd{S-@key{left},org-agenda-do-date-earlier} Change the timestamp associated with the current line by one day into the past. @c -@kindex > -@item > -Change the timestamp associated with the current line to today. -The key @kbd{>} has been chosen, because it is the same as @kbd{S-.} -on my keyboard. +@orgcmd{>,org-agenda-date-prompt} +Change the timestamp associated with the current line. The key @kbd{>} has +been chosen, because it is the same as @kbd{S-.} on my keyboard. @c -@kindex I -@item I +@orgcmd{I,org-agenda-clock-in} Start the clock on the current item. If a clock is running already, it is stopped first. @c -@kindex O -@item O +@orgcmd{O,org-agenda-clock-out} Stop the previously started clock. @c -@kindex X -@item X +@orgcmd{X,org-agenda-clock-cancel} Cancel the currently running clock. - -@kindex J -@item J +@c +@orgcmd{J,org-agenda-clock-goto} Jump to the running clock in another window. @tsubheading{Bulk remote editing selected entries} @cindex remote editing, bulk, from agenda -@kindex m -@item s -Mark the entry at point for bulk action. - -@kindex u -@item u +@orgcmd{m,org-agenda-bulk-mark} +Mark the entry at point for bulk action. With prefix arg, mark that many +successive entries. +@c +@orgcmd{u,org-agenda-bulk-unmark} Unmark entry for bulk action. - -@kindex U -@item U +@c +@orgcmd{U,org-agenda-bulk-remove-all-marks} Unmark all marked entries for bulk action. - -@kindex B -@item B +@c +@orgcmd{B,org-agenda-bulk-action} Bulk action: act on all marked entries in the agenda. This will prompt for -another key to select the action to be applied: +another key to select the action to be applied. The prefix arg to @kbd{B} +will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove +these special timestamps. @example r @r{Prompt for a single refile target and move all entries. The entries} - @r{will no longer be in the agenda, refresh (@kbd{g}) to bring them back.} + @r{will no longer be in the agenda; refresh (@kbd{g}) to bring them back.} $ @r{Archive all selected entries.} A @r{Archive entries by moving them to their respective archive siblings.} t @r{Change TODO state. This prompts for a single TODO keyword and} @@ -7629,23 +7995,24 @@ t @r{Change TODO state. This prompts for a single TODO keyword and} s @r{Schedule all items to a new date. To shift existing schedule dates} @r{by a fixed number of days, use something starting with double plus} @r{at the prompt, for example @samp{++8d} or @samp{++2w}.} +S @r{Reschedule randomly by N days. N will be prompted for. With prefix} + @r{arg (@kbd{C-u B S}), scatter only accross weekdays.} d @r{Set deadline to a specific date.} @end example @tsubheading{Calendar commands} @cindex calendar commands, from agenda -@kindex c -@item c + +@orgcmd{c,org-agenda-goto-calendar} 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 +@orgcmd{c,org-calendar-goto-agenda} +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 +@orgcmd{i,org-agenda-diary-entry} @vindex org-agenda-diary-file Insert a new entry into the diary, using the date at the cursor and (for block entries) the date at the mark. This will add to the Emacs diary @@ -7658,29 +8025,25 @@ If you configure @code{org-agenda-diary-file} to point to an Org-mode file, Org will create entries (in org-mode syntax) in that file instead. Most entries will be stored in a date-based outline tree that will later make it easy to archive appointments from previous months/years. The tree will be -build under an entry with a @code{DATE_TREE} property, or else with years as -top-level entries. Emacs will prompt you for the entry text - if you specify +built under an entry with a @code{DATE_TREE} property, or else with years as +top-level entries. Emacs will prompt you for the entry text---if you specify it, the entry will be created in @code{org-agenda-diary-file} without further interaction. If you directly press @key{RET} at the prompt without typing text, the target file will be shown in another window for you to finish the entry there. See also the @kbd{k r} command. @c -@kindex M -@item M +@orgcmd{M,org-agenda-phases-of-moon} Show the phases of the moon for the three months around current date. @c -@kindex S -@item S +@orgcmd{S,org-agenda-sunrise-sunset} Show sunrise and sunset times. The geographical location must be set with calendar variables, see the documentation for the Emacs calendar. @c -@kindex C -@item C +@orgcmd{C,org-agenda-convert-date} Convert the date at cursor into many other cultural and historic calendars. @c -@kindex H -@item H +@orgcmd{H,org-agenda-holidays} Show holidays for three months around the cursor date. @item M-x org-export-icalendar-combine-agenda-files @@ -7688,8 +8051,7 @@ Export a single iCalendar file containing entries from all agenda files. This is a globally available command, and also available in the agenda menu. @tsubheading{Exporting to a file} -@kindex C-x C-w -@item C-x C-w +@orgcmd{C-x C-w,org-write-agenda} @cindex exporting agenda views @cindex agenda views, exporting @vindex org-agenda-exporter-settings @@ -7702,13 +8064,11 @@ argument, immediately open the newly created file. Use the variable for @file{htmlize} to be used during export. @tsubheading{Quit and Exit} -@kindex q -@item q +@orgcmd{q,org-agenda-quit} Quit agenda, remove the agenda buffer. @c -@kindex x @cindex agenda files, removing buffers -@item x +@orgcmd{x,org-agenda-exit} 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. @@ -7838,7 +8198,7 @@ command @kbd{C-c a o} provides a similar view for office tasks. @cindex options, for custom agenda views @vindex org-agenda-custom-commands -Org mode contains a number of variables regulating agenda construction +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 @@ -7874,7 +8234,7 @@ 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 +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 @@ -7910,7 +8270,7 @@ yourself. @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 +version of some agenda views to carry around. Org-mode can export custom agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's @file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the ghostscript @file{ps2pdf} utility must be installed on the system. Selecting @@ -7918,8 +8278,7 @@ a PDF file with also create the postscript file.}, and iCalendar files. If you want to do this only occasionally, use the command @table @kbd -@kindex C-x C-w -@item C-x C-w +@orgcmd{C-x C-w,org-write-agenda} @cindex exporting agenda views @cindex agenda views, exporting @vindex org-agenda-exporter-settings @@ -7975,7 +8334,7 @@ or absolute. @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 +@file{.html}, Org-mode will use the @file{htmlize.el} package to convert the buffer to HTML and save it to this file name. If the extension is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce Postscript output. If the extension is @file{.ics}, iCalendar export is @@ -7989,8 +8348,7 @@ 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 +@orgcmd{C-c a e,org-store-agenda-views} Export all agenda views that have export file names associated with them. @end table @@ -8030,7 +8388,7 @@ or, if you need to modify some parameters@footnote{Quoting depends on the system you use, please check the FAQ for examples.} @example emacs -eval '(org-batch-store-agenda-views \ - org-agenda-ndays 30 \ + org-agenda-span month \ org-agenda-start-day "2007-11-01" \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ @@ -8057,8 +8415,7 @@ quite useful to use column view also from the agenda, where entries are collected by certain criteria. @table @kbd -@kindex C-c C-x C-c -@item C-c C-x C-c +@orgcmd{C-c C-x C-c,org-agenda-columns} Turn on column view in the agenda. @end table @@ -8085,7 +8442,7 @@ turning on column view in the agenda will visit all relevant agenda files and make sure that the computations of this property are up to date. This is also true for the special @code{CLOCKSUM} property. Org will then sum the values displayed in the agenda. In the daily/weekly agenda, the sums will -cover a single day, in all other views they cover the entire block. It is +cover a single day; in all other views they cover the entire block. It is vital to realize that the agenda may show the same entry @emph{twice} (for example as scheduled and as a deadline), and it may show two entries from the same hierarchy (for example a @emph{parent} and its @emph{child}). In these @@ -8108,8 +8465,8 @@ the agenda). When exporting Org-mode documents, the exporter tries to reflect the structure of the document as accurately as possible in the backend. Since -export targets like HTML, La@TeX{}, or DocBook allow much richer formatting, -Org mode has rules on how to prepare text for rich export. This section +export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting, +Org-mode has rules on how to prepare text for rich export. This section summarizes the markup rules used in an Org-mode buffer. @menu @@ -8117,6 +8474,7 @@ summarizes the markup rules used in an Org-mode buffer. * Images and tables:: Tables and Images will be included * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document +* Index entries:: Making an index * Macro replacement:: Use macros to create complex output * Embedded LaTeX:: LaTeX can be freely used inside Org documents @end menu @@ -8201,9 +8559,9 @@ the table of contents entirely, by configuring the variable @cindex text before first headline, markup rules @cindex #+TEXT -Org mode normally exports the text before the first headline, and even uses +Org-mode normally exports the text before the first headline, and even uses the first line as the document title. The text will be fully marked up. If -you need to include literal HTML, La@TeX{}, or DocBook code, use the special +you need to include literal HTML, @LaTeX{}, or DocBook code, use the special constructs described below in the sections for the individual exporters. @vindex org-export-skip-text-before-1st-heading @@ -8296,7 +8654,7 @@ different backends support this to varying degrees. You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text in the code and verbatim string is not processed for Org-mode specific -syntax, it is exported verbatim. +syntax; it is exported verbatim. @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements @subheading Horizontal rules @@ -8329,11 +8687,12 @@ Toggle the COMMENT keyword at the beginning of an entry. @cindex tables, markup rules @cindex #+CAPTION @cindex #+LABEL -Both the native Org mode tables (@pxref{Tables}) and tables formatted with -the @file{table.el} package will be exported properly. For Org mode tables, +Both the native Org-mode tables (@pxref{Tables}) and tables formatted with +the @file{table.el} package will be exported properly. For Org-mode tables, the lines before the first horizontal separator line will become table header lines. You can use the following lines somewhere before the table to assign -a caption and a label for cross references: +a caption and a label for cross references, and in the text you can refer to +the object with @code{\ref@{tab:basic-data@}}: @example #+CAPTION: This is the caption for the next table (or link) @@ -8343,12 +8702,12 @@ a caption and a label for cross references: @end example @cindex inlined images, markup rules -Some backends (HTML, La@TeX{}, and DocBook) allow you to directly include +Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include images into the exported document. Org does this, if a link to an image files does not have a description part, for example @code{[[./img/a.jpg]]}. If you wish to define a caption for the image and maybe a label for internal -cross references, you sure that the link is on a line by itself precede it -with: +cross references, make sure that the link is on a line by itself and precede +it with @code{#+CAPTION} and @code{#+LABEL} as follows: @example #+CAPTION: This is the caption for the next figure link (or table) @@ -8360,6 +8719,7 @@ You may also define additional attributes for the figure. As this is backend-specific, see the sections about the individual backends for more information. +@xref{Handling links,the discussion of image links}. @node Literal examples, Include files, Images and tables, Markup @section Literal examples @@ -8391,20 +8751,31 @@ Here is an example @cindex formatting source code, markup rules If the example is source code from a programming language, or any other text that can be marked up by font-lock in Emacs, you can ask for the example to -look like the fontified Emacs buffer@footnote{Currently this works for the -HTML backend, and requires the @file{htmlize.el} package version 1.34 or -later. It also works for LaTeX with the listings package, if you turn on the -option @code{org-export-latex-listings} and make sure that the listings -package is included by the LaTeX header.}. This is done with the @samp{src} -block, where you also need to specify the name of the major mode that should -be used to fontify the example: +look like the fontified Emacs buffer@footnote{This works automatically for +the HTML backend (it requires version 1.34 of the @file{htmlize.el} package, +which is distributed with Org). Fontified code chunks in LaTeX can be +achieved using either the listings or the +@url{http://code.google.com/p/minted, minted,} package. To use listings, turn +on the variable @code{org-export-latex-listings} and ensure that the listings +package is included by the LaTeX header (e.g. by configuring +@code{org-export-latex-packages-alist}). See the listings documentation for +configuration options, including obtaining colored output. For minted it is +necessary to install the program @url{http://pygments.org, pygments}, in +addition to setting @code{org-export-latex-minted}, ensuring that the minted +package is included by the LaTeX header, and ensuring that the +@code{-shell-escape} option is passed to @file{pdflatex} (see +@code{org-latex-to-pdf-process}). See the documentation of the variables +@code{org-export-latex-listings} and @code{org-export-latex-minted} for +further details.}. This is done with the @samp{src} block, where you also +need to specify the name of the major mode that should be used to fontify the +example: @cindex #+BEGIN_SRC @example #+BEGIN_SRC emacs-lisp -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) #+END_SRC @end example @@ -8450,8 +8821,8 @@ Edit the source code example at point in its native mode. This works by switching to a temporary buffer with the source code. You need to exit by pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*} or @samp{#} will get a comma prepended, to keep them from being interpreted -by Org as outline nodes or special comments. These commas will be striped -for editing with @kbd{C-c '}, and also for export.}, the edited version will +by Org as outline nodes or special comments. These commas will be stripped +for editing with @kbd{C-c '}, and also for export.}. The edited version will then replace the old version in the Org buffer. Fixed-width regions (where each line starts with a colon followed by a space) will be edited using @code{artist-mode}@footnote{You may select a different-mode with the @@ -8461,14 +8832,14 @@ fixed-width region. @kindex C-c l @item C-c l Calling @code{org-store-link} while editing a source code example in a -temporary buffer created with @kbd{C-c '} will prompt for a label, make sure +temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure that it is unique in the current buffer, and insert it with the proper formatting like @samp{(ref:label)} at the end of the current line. Then the label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}. @end table -@node Include files, Macro replacement, Literal examples, Markup +@node Include files, Index entries, Literal examples, Markup @section Include files @cindex include files, markup rules @@ -8482,12 +8853,14 @@ include your @file{.emacs} file, you could use: @noindent The optional second and third parameter are the markup (e.g. @samp{quote}, @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the -language for formatting the contents. The markup is optional, if it is not -given, the text will be assumed to be in Org mode format and will be +language for formatting the contents. The markup is optional; if it is not +given, the text will be assumed to be in Org-mode format and will be processed normally. The include line will also allow additional keyword parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the -first line and for each following line, as well as any options accepted by -the selected markup. For example, to include a file as an item, use +first line and for each following line, @code{:minlevel} in order to get +org-mode content demoted to a specified level, as well as any options +accepted by the selected markup. For example, to include a file as an item, +use @example #+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " " @@ -8499,8 +8872,25 @@ the selected markup. For example, to include a file as an item, use Visit the include file at point. @end table +@node Index entries, Macro replacement, Include files, Markup +@section Index entries +@cindex index entries, for publishing + +You can specify entries that will be used for generating an index during +publishing. This is done by lines starting with @code{#+INDEX}. An entry +the contains an exclamation mark will create a sub item. See @ref{Generating +an index} for more information. + +@example +* Curriculum Vitae +#+INDEX: CV +#+INDEX: Application!CV +@end example + + -@node Macro replacement, Embedded LaTeX, Include files, Markup + +@node Macro replacement, Embedded LaTeX, Index entries, Markup @section Macro replacement @cindex macro replacement, during export @cindex #+MACRO @@ -8526,23 +8916,19 @@ construct complex HTML code. @node Embedded LaTeX, , Macro replacement, Markup -@section Embedded La@TeX{} +@section Embedded @LaTeX{} @cindex @TeX{} interpretation -@cindex La@TeX{} interpretation - -Plain ASCII is normally sufficient for almost all note taking. One -exception, however, are scientific notes which need to be able to contain -mathematical symbols and the occasional formula. La@TeX{}@footnote{La@TeX{} -is a macro system based on Donald E. Knuth's @TeX{} system. Many of the -features described here as ``La@TeX{}'' are really from @TeX{}, but for -simplicity I am blurring this distinction.} is widely used to typeset -scientific documents. Org mode supports embedding La@TeX{} code into its -files, because many academics are used to reading La@TeX{} source code, and -because it can be readily processed into images for HTML production. - -It is not necessary to mark La@TeX{} macros and code in any special way. -If you observe a few conventions, Org mode knows how to find it and what -to do with it. +@cindex @LaTeX{} interpretation + +Plain ASCII is normally sufficient for almost all note taking. Exceptions +include scientific notes, which often require mathematical symbols and the +occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on +Donald E. Knuth's @TeX{} system. Many of the features described here as +``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this +distinction.} is widely used to typeset scientific documents. Org-mode +supports embedding @LaTeX{} code into its files, because many academics are +used to writing and reading @LaTeX{} source code, and because it can be +readily processed to produce pretty output for a number of export backends. @menu * Special symbols:: Greek letters and other symbols @@ -8557,48 +8943,61 @@ to do with it. @cindex math symbols @cindex special symbols @cindex @TeX{} macros -@cindex La@TeX{} fragments, markup rules +@cindex @LaTeX{} fragments, markup rules @cindex HTML entities -@cindex La@TeX{} entities +@cindex @LaTeX{} entities -You can use La@TeX{} macros to insert special symbols like @samp{\alpha} to +You can use @LaTeX{} 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 +and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{} +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 -@vindex org-html-entities +@vindex org-entities During export, these symbols will be transformed into the native format of the exporter backend. Strings like @code{\alpha} will be exported as -@code{α} in the HTML output, and as @code{$\alpha$} in the La@TeX{} +@code{α} in the HTML output, and as @code{$\alpha$} in the @LaTeX{} output. Similarly, @code{\nbsp} will become @code{ } in HTML and -@code{~} in La@TeX{}. If you need such a symbol inside a word, terminate it +@code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it like this: @samp{\Aacute@{@}stor}. A large number of entities is provided, with names taken from both HTML and -La@TeX{}, see the variable @code{org-html-entities} for the complete list. +@LaTeX{}; see the variable @code{org-entities} for the complete list. @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and @samp{...} are all converted into special commands creating hyphens of different lengths or a compact set of dots. +If you would like to see entities displayed as UTF8 characters, use the +following command@footnote{You can turn this on by default by setting the +variable @code{org-pretty-entities}, or on a per-file base with the +@code{#+STARTUP} option @code{entitiespretty}.}: + +@table @kbd +@kindex C-c C-x \ +@item C-c C-x \ +Toggle display of entities as UTF-8 characters. This does not change the +buffer content which remains plain ASCII, but it overlays the UTF-8 character +for display purposes only. +@end table + @node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX @subsection Subscripts and superscripts @cindex subscript @cindex superscript -Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super- +Just like in @LaTeX{}, @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 mass of 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 @@ -8614,39 +9013,49 @@ convention, or use, on a per-file basis: #+OPTIONS: ^:@{@} @end example +@noindent With this setting, @samp{a_b} will not be interpreted as a +subscript, but @samp{a_@{b@}} will. + +@table @kbd +@kindex C-c C-x \ +@item C-c C-x \ +In addition to showing entities as UTF-8 characters, this command will also +format sub- and superscripts in a WYSIWYM way. +@end table @node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX -@subsection La@TeX{} fragments -@cindex La@TeX{} fragments +@subsection @LaTeX{} fragments +@cindex @LaTeX{} fragments @vindex org-format-latex-header -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 +Going beyond symbols and sub- and superscripts, a full formula language is +needed. Org-mode can contain @LaTeX{} math fragments, and it supports ways +to process these for several export backends. When exporting to @LaTeX{}, +the code is obviously left as it is. When exporting to HTML, Org invokes the +@uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in +HTML export}) to process and display the math@footnote{If you plan to use +this regularly or on pages with significant page views, you should install +@file{MathJax} on your own +server in order to limit the load of our server.}. Finally, it can also +process the mathematical expressions into images@footnote{For this to work +you need to be on a system with a working @LaTeX{} 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}. +@url{http://sourceforge.net/projects/dvipng/}. The @LaTeX{} header that will +be used when processing a fragment can be configured with the variable +@code{org-format-latex-header}.} that can be displayed in a browser or in +DocBook documents. -La@TeX{} fragments don't need any special marking at all. The following -snippets will be identified as La@TeX{} source code: +@LaTeX{} fragments don't need any special marking at all. The following +snippets will be identified as @LaTeX{} 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. +Environments of any kind@footnote{When @file{MathJax} is used, only the +environment recognized by @file{MathJax} will be processed. When +@file{dvipng} is used to create images, any @LaTeX{} environments will be +handled.}. 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 +Text within the usual @LaTeX{} 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, @@ -8670,19 +9079,33 @@ either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. @vindex org-format-latex-options 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. +ones you do not wish to have interpreted by the @LaTeX{} converter. + +@vindex org-export-with-LaTeX-fragments +LaTeX processing can be configured with the variable +@code{org-export-with-LaTeX-fragments}. The default setting is @code{t} +which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and +LaTeX backends. You can also set this variable on a per-file basis using one +of these lines: + +@example +#+OPTIONS: LaTeX:t @r{Do the right thing automatically (MathJax)} +#+OPTIONS: LaTeX:dvipng @r{Force using dvipng images} +#+OPTIONS: LaTeX:nil @r{Do not process @LaTeX{} fragments at all} +#+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so} +@end example @node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX @subsection Previewing LaTeX fragments @cindex LaTeX fragments, preview -La@TeX{} fragments can be processed to produce preview images of the -typeset expressions: +If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to +produce 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 +Produce a preview image of the @LaTeX{} 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 @@ -8699,26 +9122,18 @@ some aspects of the preview. In particular, the @code{:scale} (and for HTML export, @code{:html-scale}) property can be used to adjust the size of the preview images. -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, , Previewing LaTeX fragments, Embedded LaTeX @subsection Using CDLa@TeX{} to enter math @cindex CDLa@TeX{} CDLa@TeX{} mode is a minor mode that is normally used in combination with a -major La@TeX{} mode like AUC@TeX{} in order to speed-up insertion of -environments and math templates. Inside Org mode, you can make use of +major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of +environments and math templates. Inside Org-mode, you can make use of some of the features of CDLa@TeX{} mode. You need to install @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. -Don't use CDLa@TeX{} mode itself under Org mode, but use the light -version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it +Don't use CDLa@TeX{} mode itself under Org-mode, but use the light +version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it on for the current buffer with @code{M-x org-cdlatex-mode}, or for all Org files with @@ -8735,7 +9150,7 @@ 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 +@LaTeX{} 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 @@ -8749,7 +9164,7 @@ To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. @kindex _ @kindex ^ @vindex cdlatex-simplify-sub-super-scripts -Pressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert these +Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} 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 @@ -8757,14 +9172,14 @@ macro, they are removed again (depending on the variable @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 +macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds after the backquote, a help window will pop up. @item @kindex ' Pressing the single-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 +1.5 seconds after the single-quote, a help window will pop up. Character +modification will work only inside @LaTeX{} fragments; outside the quote is normal. @end itemize @@ -8776,13 +9191,14 @@ Org-mode documents can be exported into a variety of other formats. For printing and sharing of notes, ASCII export produces a readable and simple version of an Org file. HTML export allows you to publish a notes file on the web, while the XOXO format provides a solid base for exchange with a -broad range of other applications. La@TeX{} export lets you use Org mode and -its structured editing functions to easily create La@TeX{} files. DocBook +broad range of other applications. @LaTeX{} export lets you use Org-mode and +its structured editing functions to easily create @LaTeX{} files. DocBook export makes it possible to convert Org files to many other formats using -DocBook tools. 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. +DocBook tools. For project management you can create gantt and resource +charts by using TaskJuggler export. To incorporate entries with associated +times like deadlines or appointments into a desktop calendar program like +iCal, Org-mode can also produce extracts in the iCalendar format. Currently +Org-mode only supports export, not import of these different formats. Org supports export of selected regions when @code{transient-mark-mode} is enabled (default in Emacs 23). @@ -8791,10 +9207,11 @@ enabled (default in Emacs 23). * Selective export:: Using tags to select and exclude trees * Export options:: Per-file export settings * The export dispatcher:: How to access exporter commands -* ASCII export:: Exporting to plain ASCII +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO * iCalendar export:: Exporting in iCalendar format @@ -8839,8 +9256,7 @@ In particular, note that you can place commonly-used (export) options in a separate file which can be included using @code{#+SETUPFILE}. @table @kbd -@kindex C-c C-e t -@item C-c C-e t +@orgcmd{C-c C-e t,org-insert-export-options-template} Insert template with export options, see example below. @end table @@ -8858,6 +9274,7 @@ Insert template with export options, see example below. @cindex #+LINK_HOME @cindex #+EXPORT_SELECT_TAGS @cindex #+EXPORT_EXCLUDE_TAGS +@cindex #+XSLT @cindex #+LATEX_HEADER @vindex user-full-name @vindex user-mail-address @@ -8865,7 +9282,7 @@ Insert template with export options, see example below. @example #+TITLE: the title to be shown (default is the buffer name) #+AUTHOR: the author (default taken from @code{user-full-name}) -#+DATE: a date, fixed, of a format string for @code{format-time-string} +#+DATE: a date, fixed, or a format string for @code{format-time-string} #+EMAIL: his/her email address (default from @code{user-mail-address}) #+DESCRIPTION: the page description, e.g. for the XHTML meta tag #+KEYWORDS: the page keywords, e.g. for the XHTML meta tag @@ -8880,12 +9297,13 @@ Insert template with export options, see example below. #+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@} #+EXPORT_SELECT_TAGS: Tags that select a tree for export #+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export +#+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file @end example @noindent The OPTIONS line is a compact@footnote{If you want to configure many options -this way, you can use several OPTIONS lines.} form to specify export settings. Here -you can: +this way, you can use several OPTIONS lines.} form to specify export +settings. Here you can: @cindex headline levels @cindex section-numbers @cindex table of contents @@ -8898,14 +9316,14 @@ you can: @cindex special strings @cindex emphasized text @cindex @TeX{} macros -@cindex La@TeX{} fragments +@cindex @LaTeX{} fragments @cindex author info, in export @cindex time info, in export @example H: @r{set the number of headline levels for export} num: @r{turn on/off section-numbers} toc: @r{turn on/off table of contents, or set level limit (integer)} -\n: @r{turn on/off line-break-preservation} +\n: @r{turn on/off line-break-preservation (DOES NOT WORK)} @@: @r{turn on/off quoted HTML tags} :: @r{turn on/off fixed-width sections} |: @r{turn on/off tables} @@ -8920,17 +9338,21 @@ tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}} <: @r{turn on/off inclusion of any time/date stamps like DEADLINES} *: @r{turn on/off emphasized text (bold, italic, underlined)} TeX: @r{turn on/off simple @TeX{} macros in plain text} -LaTeX: @r{turn on/off La@TeX{} fragments} +LaTeX: @r{configure export of @LaTeX{} fragments. Default @code{auto}} 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} +email: @r{turn on/off inclusion of author email into exported file} creator: @r{turn on/off inclusion of creator info into exported file} timestamp: @r{turn on/off inclusion creation time into exported file} d: @r{turn on/off inclusion of drawers} @end example @noindent -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. +These options take effect in both the HTML and @LaTeX{} export, except for +@code{TeX} and @code{LaTeX}, which are respectively @code{t} and @code{nil} +for the @LaTeX{} export. The default values for these and many other options +are given by a set of variables. For a list of such variables, the +corresponding OPTIONS keys and also the publishing keys (@pxref{Project +alist}), see the constant @code{org-export-plist-vars}. When exporting only a single subtree by selecting it with @kbd{C-c @@} before calling an export command, the subtree can overrule some of the file's export @@ -8938,7 +9360,7 @@ settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE}, @code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and @code{EXPORT_OPTIONS}. -@node The export dispatcher, ASCII export, Export options, Exporting +@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting @section The export dispatcher @cindex dispatcher, for export commands @@ -8949,8 +9371,7 @@ contains one outline tree, the first heading is used as document title and the subtrees are exported. @table @kbd -@kindex C-c C-e -@item C-c C-e +@orgcmd{C-c C-e,org-export} @vindex org-export-run-in-background Dispatcher for export and publishing commands. Displays a help-window listing the additional key(s) needed to launch an export or publishing @@ -8958,31 +9379,31 @@ command. The prefix arg is passed through to the exporter. A double prefix @kbd{C-u C-u} causes most commands to be executed in the background, in a separate Emacs process@footnote{To make this behavior the default, customize the variable @code{org-export-run-in-background}.}. -@kindex C-c C-e v -@item C-c C-e v +@orgcmd{C-c C-e v,org-export-visible} Like @kbd{C-c C-e}, but only export the text that is currently visible (i.e. not hidden by outline visibility). -@kindex C-u C-u C-c C-e -@item C-u C-u C-c C-e +@orgcmd{C-u C-u C-c C-e,org-export} @vindex org-export-run-in-background -Call an the exporter, but reverse the setting of +Call the exporter, but reverse the setting of @code{org-export-run-in-background}, i.e. request background processing if not set, or force processing in the current Emacs process if set. @end table -@node ASCII export, HTML export, The export dispatcher, Exporting -@section ASCII export +@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting +@section ASCII/Latin-1/UTF-8 export @cindex ASCII export +@cindex Latin-1 export +@cindex UTF-8 export ASCII export produces a simple and very readable version of an Org-mode -file. +file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file +with special characters and symbols available in these encodings. @cindex region, active @cindex active region @cindex transient-mark-mode @table @kbd -@kindex C-c C-e a -@item C-c C-e a +@orgcmd{C-c C-e a,org-export-as-ascii} @cindex property, EXPORT_FILE_NAME 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 @@ -8993,11 +9414,15 @@ current subtree, use @kbd{C-c @@}.}, the tree head will become the document title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME} property, that name will be used for the export. -@kindex C-c C-e A -@item C-c C-e A -Export to a temporary buffer, do not create a file. -@kindex C-c C-e v a -@item C-c C-e v a +@orgcmd{C-c C-e A,org-export-as-ascii-to-buffer} +Export to a temporary buffer. Do not create a file. +@orgcmd{C-c C-e n,org-export-as-latin1} +@xorgcmd{C-c C-e N,org-export-as-latin1-to-buffer} +Like the above commands, but use Latin-1 encoding. +@orgcmd{C-c C-e u,org-export-as-utf8} +@xorgcmd{C-c C-e U,org-export-as-utf8-to-buffer} +Like the above commands, but use UTF-8 encoding. +@item C-c C-e v a/n/u Export only the visible part of the document. @end table @@ -9025,23 +9450,24 @@ Links will be exported in a footnote-like style, with the descriptive part in the text and the link in a note before the next heading. See the variable @code{org-export-ascii-links-to-notes} for details and other options. -@node HTML export, LaTeX and PDF export, ASCII export, Exporting +@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting @section HTML export @cindex HTML export -Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive +Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive HTML formatting, in ways similar to John Gruber's @emph{markdown} language, but with additional support for tables. @menu * HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode +* Quoting HTML tags:: Using direct HTML in Org-mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output +* Math formatting in HTML export:: Beautiful math also on the web * Text areas in HTML export:: An alternative way to show an example * CSS support:: Changing the appearance of the output -* Javascript support:: Info and Folding in a web browser +* JavaScript support:: Info and Folding in a web browser @end menu @node HTML Export commands, Quoting HTML tags, HTML export, HTML export @@ -9051,8 +9477,7 @@ language, but with additional support for tables. @cindex active region @cindex transient-mark-mode @table @kbd -@kindex C-c C-e h -@item C-c C-e h +@orgcmd{C-c C-e h,org-export-as-html} @cindex property, EXPORT_FILE_NAME 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 @@ -9062,25 +9487,15 @@ exported. If the selected region is a single tree@footnote{To select the current subtree, use @kbd{C-c @@}.}, the tree head will become the document title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the export. -@kindex C-c C-e b -@item C-c C-e b +@orgcmd{C-c C-e b,org-export-as-html-and-open} Export as HTML file and immediately open it with a browser. -@kindex C-c C-e H -@item C-c C-e H -Export to a temporary buffer, do not create a file. -@kindex C-c C-e R -@item C-c C-e R +@orgcmd{C-c C-e H,org-export-as-html-to-buffer} +Export to a temporary buffer. Do not create a file. +@orgcmd{C-c C-e R,org-export-region-as-html} Export the active region to a temporary buffer. With a prefix argument, do not produce the file header and footer, but just the plain HTML section for the region. This is good for cut-and-paste operations. -@kindex C-c C-e v h -@kindex C-c C-e v b -@kindex C-c C-e v H -@kindex C-c C-e v R -@item C-c C-e v h -@item C-c C-e v b -@item C-c C-e v H -@item C-c C-e v R +@item C-c C-e v h/b/H/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 @@ -9174,7 +9589,7 @@ tables, place something like the following before the table: #+ATTR_HTML: border="2" rules="all" frame="all" @end example -@node Images in HTML export, Text areas in HTML export, Tables in HTML export, HTML export +@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export @subsection Images in HTML export @cindex images, inline in HTML @@ -9196,7 +9611,7 @@ will link to a high resolution version of the image, you could use: [[file:highres.jpg][file:thumb.jpg]] @end example -If you need to add attributes to an inlines image, use a @code{#+ATTR_HTML}. +If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}. In the example below we specify the @code{alt} and @code{title} attributes to support text viewers and accessibility, and align it to the right. @@ -9211,7 +9626,43 @@ support text viewers and accessibility, and align it to the right. @noindent and you could use @code{http} addresses just as well. -@node Text areas in HTML export, CSS support, Images in HTML export, HTML export +@node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export +@subsection Math formatting in HTML export +@cindex MathJax +@cindex dvipng + +@LaTeX{} math snippets (@pxref{LaTeX fragments}) can be displayed in two +different ways on HTML pages. The default is to use the +@uref{http://www.mathjax.org, MathJax system} which should work out of the +box with Org mode installation because @code{http://orgmode.org} serves +@file{MathJax} for Org-mode users for small applications and for testing +purposes. @b{If you plan to use this regularly or on pages with significant +page views, you should install@footnote{Installation instructions can be +found on the MathJax website, see +@uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on +your own server in order to limit the load of our server.} To configure +@file{MathJax}, use the variable @code{org-export-html-mathjax-options} or +insert something like the following into the buffer: + +@example +#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js" +@end example + +@noindent See the docstring of the variable +@code{org-export-html-mathjax-options} for the meaning of the parameters in +this line. + +If you prefer, you can also request that @LaTeX{} fragments are processed +into small images that will be inserted into the browser page. Before the +availability of MathJax, this was the default method for Org files. This +method requires that the @file{dvipng} program is available on your system. +You can still get this processing with + +@example +#+OPTIONS: LaTeX:dvipng +@end example + +@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export @subsection Text areas in HTML export @cindex text areas, in HTML @@ -9226,14 +9677,14 @@ respectively. For example @example #+BEGIN_EXAMPLE -t -w 40 -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) #+END_EXAMPLE @end example -@node CSS support, Javascript support, Text areas in HTML export, HTML export +@node CSS support, JavaScript support, Text areas in HTML export, HTML export @subsection CSS support @cindex CSS, for HTML export @cindex HTML export, CSS @@ -9288,7 +9739,7 @@ inclusion of these defaults off, customize @code{org-export-html-style-include-default}}. You may overwrite these settings, or add to them by using the variables @code{org-export-html-style} (for Org-wide settings) and @code{org-export-html-style-extra} (for more -granular settings, like file-local settings). To set the latter variable +fine-grained settings, like file-local settings). To set the latter variable individually for each file, you can use @cindex #+STYLE @@ -9301,11 +9752,16 @@ For longer style definitions, you can use several such lines. You could also directly write a @code{<style>} @code{</style>} section in this way, without referring to an external file. +In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:} +property to assign a class to the tree. In order to specify CSS styles for a +particular headline, you can use the id specified in a @code{:CUSTOM_ID:} +property. + @c FIXME: More about header and footer styles @c FIXME: Talk about links and targets. -@node Javascript support, , CSS support, HTML export -@subsection Javascript supported display of web pages +@node JavaScript support, , CSS support, HTML export +@subsection JavaScript supported display of web pages @cindex Rose, Sebastian Sebastian Rose has written a JavaScript program especially designed to @@ -9351,11 +9807,11 @@ sdepth: @r{Maximum headline level that will still become an independent} @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).} @r{If this is smaller than in @code{org-export-headline-levels}, each} @r{info/folding section can still contain child headlines.} -toc: @r{Should the table of content @emph{initially} be visible?} +toc: @r{Should the table of contents @emph{initially} be visible?} @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.} tdepth: @r{The depth of the table of contents. The defaults are taken from} @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.} -ftoc: @r{Does the css of the page specify a fixed position for the "toc"?} +ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?} @r{If yes, the toc will never be displayed as a section.} ltoc: @r{Should there be short contents (children) in each section?} @r{Make this @code{above} if the section should be above initial text.} @@ -9372,35 +9828,40 @@ You can choose default values for these options by customizing the variable pages, configure the variable @code{org-export-html-use-infojs}. @node LaTeX and PDF export, DocBook export, HTML export, Exporting -@section La@TeX{} and PDF export -@cindex La@TeX{} export +@section @LaTeX{} and PDF export +@cindex @LaTeX{} export @cindex PDF export @cindex Guerry, Bastien -Org mode contains a La@TeX{} exporter written by Bastien Guerry. With -further processing, this backend is also used to produce PDF output. Since -the La@TeX{} output uses @file{hyperref} to implement links and cross -references, the PDF output file will be fully linked. +Org-mode contains a @LaTeX{} exporter written by Bastien Guerry. With +further processing@footnote{The default LaTeX output is designed for +processing with pdftex or latex. It includes packages that are not +compatible with xetex and possibly luatex. See the variables +@code{org-export-latex-default-packages-alist} and +@code{org-export-latex-packages-alist}.}, this backend is also used to +produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to +implement links and cross references, the PDF output file will be fully +linked. @menu * LaTeX/PDF export commands:: Which key invokes which commands -* Quoting LaTeX code:: Incorporating literal La@TeX{} code -* Sectioning structure:: Changing sectioning in La@TeX{} output -* Tables in LaTeX export:: Options for exporting tables to La@TeX{} -* Images in LaTeX export:: How to insert figures into La@TeX{} output +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal @LaTeX{} code +* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} +* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Beamer class export:: Turning the file into a presentation @end menu -@node LaTeX/PDF export commands, Quoting LaTeX code, LaTeX and PDF export, LaTeX and PDF export -@subsection La@TeX{} export commands +@node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export +@subsection @LaTeX{} export commands @cindex region, active @cindex active region @cindex transient-mark-mode @table @kbd -@kindex C-c C-e l -@item C-c C-e l +@orgcmd{C-c C-e l,org-export-as-latex} @cindex property EXPORT_FILE_NAME -Export as La@TeX{} file @file{myfile.tex}. For an Org file +Export as @LaTeX{} file @file{myfile.tex}. For an Org file @file{myfile.org}, the ASCII file will be @file{myfile.tex}. The file will be overwritten without warning. If there is an active region@footnote{This requires @code{transient-mark-mode} be turned on.}, only the region will be @@ -9408,27 +9869,21 @@ exported. If the selected region is a single tree@footnote{To select the current subtree, use @kbd{C-c @@}.}, the tree head will become the document title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME} property, that name will be used for the export. -@kindex C-c C-e L -@item C-c C-e L -Export to a temporary buffer, do not create a file. -@kindex C-c C-e v l -@kindex C-c C-e v L -@item C-c C-e v l -@item C-c C-e v L +@orgcmd{C-c C-e L,org-export-as-latex-to-buffer} +Export to a temporary buffer. Do not create a file. +@item C-c C-e v l/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 +Convert the region to @LaTeX{} 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{} +Replace the active region (assumed to be in Org-mode syntax) by @LaTeX{} code. -@kindex C-c C-e p -@item C-c C-e p -Export as La@TeX{} and then process to PDF. -@kindex C-c C-e d -@item C-c C-e d -Export as La@TeX{} and then process to PDF, then open the resulting PDF file. +@orgcmd{C-c C-e p,org-export-as-pdf} +Export as @LaTeX{} and then process to PDF. +@orgcmd{C-c C-e d,org-export-as-pdf-and-open} +Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. @end table @cindex headline levels, for exporting @@ -9449,13 +9904,47 @@ with a numeric prefix argument. For example, @noindent creates two levels of headings and does the rest as items. -@node Quoting LaTeX code, Sectioning structure, LaTeX/PDF export commands, LaTeX and PDF export -@subsection Quoting La@TeX{} code +@node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export +@subsection Header and sectioning structure +@cindex @LaTeX{} class +@cindex @LaTeX{} sectioning structure +@cindex @LaTeX{} header +@cindex header, for LaTeX files +@cindex sectioning structure, for LaTeX export + +By default, the @LaTeX{} output uses the class @code{article}. + +@vindex org-export-latex-default-class +@vindex org-export-latex-classes +@vindex org-export-latex-default-packages-alist +@vindex org-export-latex-packages-alist +@cindex #+LATEX_HEADER +@cindex #+LATEX_CLASS +@cindex #+LATEX_CLASS_OPTIONS +@cindex property, LATEX_CLASS +@cindex property, LATEX_CLASS_OPTIONS +You can change this globally by setting a different value for +@code{org-export-latex-default-class} or locally by adding an option like +@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:} +property that applies when exporting a region containing only this (sub)tree. +The class must be listed in @code{org-export-latex-classes}. This variable +defines a header template for each class@footnote{Into which the values of +@code{org-export-latex-default-packages-alist} and +@code{org-export-latex-packages-alist} are spliced.}, and allows you to +define the sectioning structure for each class. You can also define your own +classes there. @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS} +property can specify the options for the @code{\documentclass} macro. You +can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the +header. See the docstring of @code{org-export-latex-classes} for more +information. + +@node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export +@subsection Quoting @LaTeX{} code -Embedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctly -inserted into the La@TeX{} file. This includes simple macros like +Embedded @LaTeX{} as described in @ref{Embedded LaTeX}, will be correctly +inserted into the @LaTeX{} file. This includes simple macros like @samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore, -you can add special code that should only be present in La@TeX{} export with +you can add special code that should only be present in @LaTeX{} export with the following constructs: @cindex #+LaTeX @@ -9473,35 +9962,17 @@ All lines between these markers are exported literally #+END_LaTeX @end example -@node Sectioning structure, Tables in LaTeX export, Quoting LaTeX code, LaTeX and PDF export -@subsection Sectioning structure -@cindex La@TeX{} class -@cindex La@TeX{} sectioning structure - -By default, the La@TeX{} output uses the class @code{article}. - -@vindex org-export-latex-default-class -@vindex org-export-latex-classes -@cindex #+LATEX_HEADER -@cindex #+LATEX_CLASS -@cindex property, LATEX_CLASS -You can change this globally by setting a different value for -@code{org-export-latex-default-class} or locally by adding an option like -@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:} -property that applies when exporting a region containing only this (sub)tree. -The class should be listed in @code{org-export-latex-classes}, where you can -also define the sectioning structure for each class, as well as defining -additional classes. You can also use @code{#+LATEX_HEADER: -\usepackage@{xyz@}} to add lines to the header. -@node Tables in LaTeX export, Images in LaTeX export, Sectioning structure, LaTeX and PDF export -@subsection Tables in La@TeX{} export -@cindex tables, in La@TeX{} export +@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export +@subsection Tables in @LaTeX{} export +@cindex tables, in @LaTeX{} export -For La@TeX{} export of a table, you can specify a label and a caption +For @LaTeX{} export of a table, you can specify a label and a caption (@pxref{Images and tables}). You can also use the @code{ATTR_LaTeX} line to -request a longtable environment for the table, so that it may span several -pages. Finally, you can set the alignment string: +request a @code{longtable} environment for the table, so that it may span +several pages, or provide the @code{multicolumn} keyword that will make the +table span the page in a multicolumn environment (@code{table*} environment). +Finally, you can set the alignment string: @cindex #+CAPTION @cindex #+LABEL @@ -9515,14 +9986,14 @@ pages. Finally, you can set the alignment string: @end example -@node Images in LaTeX export, , Tables in LaTeX export, LaTeX and PDF export -@subsection Images in La@TeX{} export -@cindex images, inline in La@TeX{} -@cindex inlining images in La@TeX{} +@node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export +@subsection Images in @LaTeX{} export +@cindex images, inline in @LaTeX{} +@cindex inlining images in @LaTeX{} Images that are linked to without a description part in the link, like @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF -output file resulting from La@TeX{} processing. Org will use an +output file resulting from @LaTeX{} processing. Org will use an @code{\includegraphics} macro to insert the image. If you have specified a caption and/or a label as described in @ref{Images and tables}, the figure will be wrapped into a @code{figure} environment and thus become a floating @@ -9532,12 +10003,12 @@ options that can be used in the optional argument of the @code{figure} environment, add something like @samp{placement=[h!]} to the Attributes. -If you'd like to let text flow around the image, add the word @samp{wrap} to -the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left -half of the page. To fine-tune, the @code{placement} field will be the -set of additional arguments needed by the @code{wrapfigure} environment. -Note that if you change the size of the image, you need to use compatible -settings for @code{\includegraphics} and @code{wrapfigure}. +If you would like to let text flow around the image, add the word @samp{wrap} +to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left +half of the page. To fine-tune, the @code{placement} field will be the set +of additional arguments needed by the @code{wrapfigure} environment. Note +that if you change the size of the image, you need to use compatible settings +for @code{\includegraphics} and @code{wrapfigure}. @cindex #+CAPTION @cindex #+LABEL @@ -9553,13 +10024,140 @@ settings for @code{\includegraphics} and @code{wrapfigure}. @end example If you need references to a label created in this way, write -@samp{\ref@{fig:SED-HR4049@}} just like in La@TeX{}. +@samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}. + +@node Beamer class export, , Images in LaTeX export, LaTeX and PDF export +@subsection Beamer class export + +The LaTeX class @file{beamer} allows production of high quality presentations +using LaTeX and pdf processing. Org-mode has special support for turning an +Org-mode file or tree into a @file{beamer} presentation. + +When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS: +beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is +@code{beamer}, a special export mode will turn the file or tree into a beamer +presentation. Any tree with not-too-deep level nesting should in principle be +exportable as a beamer presentation. By default, the top-level entries (or +the first level below the selected subtree heading) will be turned into +frames, and the outline structure below this level will become itemize lists. +You can also configure the variable @code{org-beamer-frame-level} to a +different level---then the hierarchy above frames will produce the sectioning +structure of the presentation. + +A template for useful in-buffer settings or properties can be inserted into +the buffer with @kbd{M-x org-insert-beamer-options-template}. Among other +things, this will install a column view format which is very handy for +editing special properties used by beamer. + +You can influence the structure of the presentation using the following +properties: + +@table @code +@item BEAMER_env +The environment that should be used to format this entry. Valid environments +are defined in the constant @code{org-beamer-environments-default}, and you +can define more in @code{org-beamer-environments-extra}. If this property is +set, the entry will also get a @code{:B_environment:} tag to make this +visible. This tag has no semantic meaning, it is only a visual aid. +@item BEAMER_envargs +The beamer-special arguments that should be used for the environment, like +@code{[t]} or @code{[<+->]} of @code{<2-3>}. If the @code{BEAMER_col} +property is also set, something like @code{C[t]} can be added here as well to +set an options argument for the implied @code{columns} environment. +@code{c[t]} or @code{c<2->} will set an options for the implied @code{column} +environment. +@item BEAMER_col +The width of a column that should start with this entry. If this property is +set, the entry will also get a @code{:BMCOL:} property to make this visible. +Also this tag is only a visual aid. When this is a plain number, it will be +interpreted as a fraction of @code{\textwidth}. Otherwise it will be assumed +that you have specified the units, like @samp{3cm}. The first such property +in a frame will start a @code{columns} environment to surround the columns. +This environment is closed when an entry has a @code{BEAMER_col} property +with value 0 or 1, or automatically at the end of the frame. +@item BEAMER_extra +Additional commands that should be inserted after the environment has been +opened. For example, when creating a frame, this can be used to specify +transitions. +@end table + +Frames will automatically receive a @code{fragile} option if they contain +source code that uses the verbatim environment. Special @file{beamer} +specific code can be inserted using @code{#+BEAMER:} and +@code{#+BEGIN_beamer...#+end_beamer} constructs, similar to other export +backends, but with the difference that @code{#+LaTeX:} stuff will be included +in the presentation as well. + +Outline nodes with @code{BEAMER_env} property value @samp{note} or +@samp{noteNH} will be formatted as beamer notes, i,e, they will be wrapped +into @code{\note@{...@}}. The former will include the heading as part of the +note text, the latter will ignore the heading of that node. To simplify note +generation, it is actually enough to mark the note with a @emph{tag} (either +@code{:B_note:} or @code{:B_noteNH:}) instead of creating the +@code{BEAMER_env} property. + +You can turn on a special minor mode @code{org-beamer-mode} for editing +support with + +@example +#+STARTUP: beamer +@end example + +@table @kbd +@orgcmd{C-c C-b,org-beamer-select-environment} +In @code{org-beamer-mode}, this key offers fast selection of a beamer +environment or the @code{BEAMER_col} property. +@end table + +Column view provides a great way to set the environment of a node and other +important parameters. Make sure you are using a COLUMN format that is geared +toward this special purpose. The command @kbd{M-x +org-insert-beamer-options-template} defines such a format. -@node DocBook export, Freemind export, LaTeX and PDF export, Exporting +Here is a simple example Org document that is intended for beamer export. + +@smallexample +#+LaTeX_CLASS: beamer +#+TITLE: Example Presentation +#+AUTHOR: Carsten Dominik +#+LaTeX_CLASS_OPTIONS: [presentation] +#+BEAMER_FRAME_LEVEL: 2 +#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@} +#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex) + +* This is the first structural section + +** Frame 1 \\ with a subtitle +*** Thanks to Eric Fraga :BMCOL:B_block: + :PROPERTIES: + :BEAMER_env: block + :BEAMER_envargs: C[t] + :BEAMER_col: 0.5 + :END: + for the first viable beamer setup in Org +*** Thanks to everyone else :BMCOL:B_block: + :PROPERTIES: + :BEAMER_col: 0.5 + :BEAMER_env: block + :BEAMER_envargs: <2-> + :END: + for contributing to the discussion +**** This will be formatted as a beamer note :B_note: +** Frame 2 \\ where we will not use columns +*** Request :B_block: + Please test this stuff! + :PROPERTIES: + :BEAMER_env: block + :END: +@end smallexample + +For more information, see the documentation on Worg. + +@node DocBook export, TaskJuggler export, LaTeX and PDF export, Exporting @section DocBook export @cindex DocBook export @cindex PDF export -@cindex Cui, Baoqui +@cindex Cui, Baoqiu Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is exported to DocBook format, it can be further processed to produce other @@ -9584,8 +10182,7 @@ Currently DocBook exporter only supports DocBook V5.0. @cindex active region @cindex transient-mark-mode @table @kbd -@kindex C-c C-e D -@item C-c C-e D +@orgcmd{C-c C-e D,org-export-as-docbook} @cindex property EXPORT_FILE_NAME Export as DocBook file. For an Org file, @file{myfile.org}, the DocBook XML file will be @file{myfile.xml}. The file will be overwritten without @@ -9595,8 +10192,7 @@ exported. If the selected region is a single tree@footnote{To select the current subtree, use @kbd{C-c @@}.}, the tree head will become the document title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the export. -@kindex C-c C-e V -@item C-c C-e V +@orgcmd{C-c C-e V,org-export-as-docbook-pdf-and-open} Export as DocBook file, process to PDF, then open the resulting PDF file. @vindex org-export-docbook-xslt-proc-command @@ -9606,8 +10202,14 @@ need to have XSLT processor and XSL-FO processor software installed on your system. Check variables @code{org-export-docbook-xslt-proc-command} and @code{org-export-docbook-xsl-fo-proc-command}. -@kindex C-c C-e v D -@item C-c C-e v D +@vindex org-export-docbook-xslt-stylesheet +The stylesheet argument @code{%s} in variable +@code{org-export-docbook-xslt-proc-command} is replaced by the value of +variable @code{org-export-docbook-xslt-stylesheet}, which needs to be set by +the user. You can also overrule this global setting on a per-file basis by +adding an in-buffer setting @code{#+XSLT:} to the Org file. + +@orgkey{C-c C-e v D} Export only the visible part of the document. @end table @@ -9642,7 +10244,7 @@ exported DocBook XML files invalid by not quoting DocBook code correctly. #+BEGIN_DOCBOOK <warning> <para>You should know what you are doing when quoting DocBook XML code - in your Org file. Invalid DocBook XML file may be generated by + in your Org file. Invalid DocBook XML may be generated by DocBook exporter if you are not careful!</para> </warning> #+END_DOCBOOK @@ -9693,21 +10295,21 @@ or @code{width}, can be specified in two ways: you can either customize variable @code{org-export-docbook-default-image-attributes} or use the @code{#+ATTR_DOCBOOK:} line. Attributes specified in variable @code{org-export-docbook-default-image-attributes} are applied to all inline -images in the Org file to be exported (unless they are overwritten by image +images in the Org file to be exported (unless they are overridden by image attributes specified in @code{#+ATTR_DOCBOOK:} lines). The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image -attributes or overwrite default image attributes for individual images. If +attributes or override default image attributes for individual images. If the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and variable @code{org-export-docbook-default-image-attributes}, the former -overwrites the latter. Here is an example about how image attributes can be +takes precedence. Here is an example about how image attributes can be set: @cindex #+CAPTION @cindex #+LABEL @cindex #+ATTR_DOCBOOK @example -#+CAPTION: The logo of Org mode +#+CAPTION: The logo of Org-mode #+LABEL: unicorn-svg #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" [[./img/org-mode-unicorn.svg]] @@ -9724,12 +10326,12 @@ more types to this list as long as DocBook supports them. @cindex Special characters in DocBook export @vindex org-export-docbook-doctype -@vindex org-html-entities +@vindex org-entities Special characters that are written in @TeX{}-like syntax, such as @code{\alpha}, @code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. These characters are rewritten to XML entities, like @code{α}, @code{Γ}, and @code{Ζ}, based on the list saved in variable -@code{org-html-entities}. As long as the generated DocBook file includes the +@code{org-entities}. As long as the generated DocBook file includes the corresponding entities, these special characters are recognized. You can customize variable @code{org-export-docbook-doctype} to include the @@ -9748,16 +10350,143 @@ special characters included in XHTML entities: " @end example -@node Freemind export, XOXO export, DocBook export, Exporting +@node TaskJuggler export, Freemind export, DocBook export, Exporting +@section TaskJuggler export +@cindex TaskJuggler export +@cindex Project management + +@uref{http://www.taskjuggler.org/, TaskJuggler} is a project management tool. +It provides an optimizing scheduler that computes your project time lines and +resource assignments based on the project outline and the constraints that +you have provided. + +The TaskJuggler exporter is a bit different from other exporters, such as the +HTML and LaTeX exporters for example, in that it does not export all the +nodes of a document or strictly follow the order of the nodes in the +document. + +Instead the TaskJuggler exporter looks for a tree that defines the tasks and +a optionally tree that defines the resources for this project. It then +creates a TaskJuggler file based on these trees and the attributes defined in +all the nodes. + +@subsection TaskJuggler export commands + +@table @kbd +@orgcmd{C-c C-e j,org-export-as-taskjuggler} +Export as TaskJuggler file. + +@orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open} +Export as TaskJuggler file and then open the file with TaskJugglerUI. +@end table + +@subsection Tasks + +@vindex org-export-taskjuggler-project-tag +Create your tasks as you usually do with Org-mode. Assign efforts to each +task using properties (it's easiest to do this in the column view). You +should end up with something similar to the example by Peter Jones in +@url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}. +Now mark the top node of your tasks with a tag named +@code{:taskjuggler_project:} (or whatever you customized +@code{org-export-taskjuggler-project-tag} to). You are now ready to export +the project plan with @kbd{C-c C-e J} which will export the project plan and +open a gantt chart in TaskJugglerUI. + +@subsection Resources + +@vindex org-export-taskjuggler-resource-tag +Next you can define resources and assign those to work on specific tasks. You +can group your resources hierarchically. Tag the top node of the resources +with @code{:taskjuggler_resource:} (or whatever you customized +@code{org-export-taskjuggler-resource-tag} to). You can optionally assign an +identifier (named @samp{resource_id}) to the resources (using the standard +Org properties commands, @pxref{Property syntax}) or you can let the exporter +generate identifiers automatically (the exporter picks the first word of the +headline as the identifier as long as it is unique---see the documentation of +@code{org-taskjuggler-get-unique-id}). Using that identifier you can then +allocate resources to tasks. This is again done with the @samp{allocate} +property on the tasks. Do this in column view or when on the task type +@kbd{C-c C-x p allocate @key{RET} <resource_id> @key{RET}}. + +Once the allocations are done you can again export to TaskJuggler and check +in the Resource Allocation Graph which person is working on what task at what +time. + +@subsection Export of properties + +The exporter also takes TODO state information into consideration, i.e. if a +task is marked as done it will have the corresponding attribute in +TaskJuggler (@samp{complete 100}). Also it will export any property on a task +resource or resource node which is known to TaskJuggler, such as +@samp{limits}, @samp{vacation}, @samp{shift}, @samp{booking}, +@samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or +@samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end}, +@samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible}, +@samp{scheduling}, etc for tasks. + +@subsection Dependencies + +The exporter will handle dependencies that are defined in the tasks either +with the @samp{ORDERED} attribute (@pxref{TODO dependencies}), with the +@samp{BLOCKER} attribute (see @file{org-depend.el}) or alternatively with a +@samp{depends} attribute. Both the @samp{BLOCKER} and the @samp{depends} +attribute can be either @samp{previous-sibling} or a reference to an +identifier (named @samp{task_id}) which is defined for another task in the +project. @samp{BLOCKER} and the @samp{depends} attribute can define multiple +dependencies separated by either space or comma. You can also specify +optional attributes on the dependency by simply appending it. The following +examples should illustrate this: + +@example +* Preparation + :PROPERTIES: + :task_id: preparation + :ORDERED: t + :END: +* Training material + :PROPERTIES: + :task_id: training_material + :ORDERED: t + :END: +** Markup Guidelines + :PROPERTIES: + :Effort: 2.0 + :END: +** Workflow Guidelines + :PROPERTIES: + :Effort: 2.0 + :END: +* Presentation + :PROPERTIES: + :Effort: 2.0 + :BLOCKER: training_material @{ gapduration 1d @} preparation + :END: +@end example + +@subsection Reports + +@vindex org-export-taskjuggler-default-reports +TaskJuggler can produce many kinds of reports (e.g. gantt chart, resource +allocation, etc). The user defines what kind of reports should be generated +for a project in the TaskJuggler file. The exporter will automatically insert +some default reports in the file. These defaults are defined in +@code{org-export-taskjuggler-default-reports}. They can be modified using +customize along with a number of other options. For a more complete list, see +@kbd{M-x customize-group @key{RET} org-export-taskjuggler @key{RET}}. + +For more information and examples see the Org-taskjuggler tutorial at +@uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.php}. + +@node Freemind export, XOXO export, TaskJuggler export, Exporting @section Freemind export @cindex Freemind export @cindex mind map -The freemind exporter was written by Lennart Borgman. +The Freemind exporter was written by Lennart Borgman. @table @kbd -@kindex C-c C-e m -@item C-c C-e m +@orgcmd{C-c C-e m,org-export-as-freemind} Export as Freemind mind map @file{myfile.mm}. @end table @@ -9765,16 +10494,14 @@ Export as Freemind mind map @file{myfile.mm}. @section XOXO export @cindex XOXO export -Org mode contains an exporter that produces XOXO-style output. +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 +@orgcmd{C-c C-e x,org-export-as-xoxo} Export as XOXO file @file{myfile.html}. -@kindex C-c C-e v -@item C-c C-e v x +@orgkey{C-c C-e v x} Export only the visible part of the document. @end table @@ -9786,10 +10513,11 @@ Export only the visible part of the document. @vindex org-icalendar-use-deadline @vindex org-icalendar-use-scheduled @vindex org-icalendar-categories -Some people use Org mode for keeping track of projects, but still prefer a +@vindex org-icalendar-alarm-time +Some people 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 show deadlines and other time-stamped items in Org -files in the calendar application. Org mode can export calendar information +files 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}. Plain timestamps are exported as VEVENT, @@ -9799,7 +10527,9 @@ to set the start and due dates for the TODO entry@footnote{See the variables @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}. As categories, it will use the tags locally defined in the heading, and the file/tree category@footnote{To add inherited tags or the TODO state, -configure the variable @code{org-icalendar-categories}.}. +configure the variable @code{org-icalendar-categories}.}. See the variable +@code{org-icalendar-alarm-time} for a way to assign alarms to entries with a +time. @vindex org-icalendar-store-UID @cindex property, ID @@ -9814,18 +10544,15 @@ In this way the UID remains unique, but a synchronization program can still figure out from which entry all the different instances originate. @table @kbd -@kindex C-c C-e i -@item C-c C-e i +@orgcmd{C-c C-e i,org-export-icalendar-this-file} 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 +@orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files} @vindex org-agenda-files 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 +@orgcmd{C-c C-e c,org-export-icalendar-combine-agenda-files} @vindex org-combined-agenda-icalendar-file Create a single large iCalendar file from all files in @code{org-agenda-files} and write it to the file given by @@ -9847,10 +10574,9 @@ and the description from the body (limited to How this calendar is best read and updated, depends on the application you are using. The FAQ covers this issue. -@node Publishing, Miscellaneous, Exporting, Top +@node Publishing, Working With Source Code, Exporting, Top @chapter Publishing @cindex publishing -@cindex O'Toole, David Org includes a publishing management system that allows you to configure automatic HTML conversion of @emph{projects} composed of interlinked org @@ -9883,7 +10609,8 @@ and many other properties of a 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 +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages @end menu @node Project alist, Sources and destinations, Configuration, Configuration @@ -9897,7 +10624,8 @@ 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 ...) + ("project-name" :property value :property value ...) + @r{i.e. a well-formed property list with alternating keys and values} @r{or} ("project-name" :components ("project-name" "project-name" ...)) @@ -9929,11 +10657,15 @@ publish to a webserver using a file name syntax appropriate for the Emacs @file{tramp} package. Or you can publish to a local directory and use external tools to upload your website (@pxref{Uploading files}). @item @code{:preparation-function} -@tab Function called before starting the publishing process, for example, to -run @code{make} for updating files to be published. +@tab Function or list of functions to be called before starting the +publishing process, for example, to run @code{make} for updating files to be +published. The project property list is scoped into this call as the +variable @code{project-plist}. @item @code{:completion-function} -@tab Function called after finishing the publishing process, for example, to -change permissions of the resulting files. +@tab Function or list of functions called after finishing the publishing +process, for example, to change permissions of the resulting files. The +project property list is scoped into this call as the variable +@code{project-plist}. @end multitable @noindent @@ -9958,6 +10690,9 @@ extension. @item @code{:include} @tab List of files to be included regardless of @code{:base-extension} and @code{:exclude}. + +@item @code{:recursive} +@tab Non-nil means, check base-directory recursively for files to publish. @end multitable @node Publishing action, Publishing options, Selecting files, Configuration @@ -9969,20 +10704,20 @@ possibly transformed in the process. The default transformation is to export Org files as HTML files, and this is done by the function @code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML export}). But you also can publish your content as PDF files using -@code{org-publish-org-to-pdf}. If you want to publish the Org file itself, -but with @i{archived}, @i{commented}, and @i{tag-excluded} trees removed, use -@code{org-publish-org-to-org} and set the parameters @code{:plain-source} -and/or @code{:htmlized-source}. This will produce @file{file.org} and -@file{file.org.html} in the publishing +@code{org-publish-org-to-pdf}, or as @code{ascii}, @code{latin1} or +@code{utf8} encoded files using the corresponding functions. If you want to +publish the Org file itself, but with @i{archived}, @i{commented}, and +@i{tag-excluded} trees removed, use @code{org-publish-org-to-org} and set the +parameters @code{:plain-source} and/or @code{:htmlized-source}. This will +produce @file{file.org} and @file{file.org.html} in the publishing directory@footnote{@file{file-source.org} and @file{file-source.org.html} if source and publishing directories are equal. Note that with this kind of setup, you need to add @code{:exclude "-source\\.org"} to the project -definition in @code{org-publish-project-alist} to avoid that the published -source files will be considered as new org files the next time the project is -published.}. Other files like images only -need to be copied to the publishing destination, for this you may use -@code{org-publish-attachment}. For non-Org files, you always need to -specify the publishing function: +definition in @code{org-publish-project-alist} to prevent the published +source files from being considered as new org files the next time the project +is published.}. Other files like images only need to be copied to the +publishing destination; for this you may use @code{org-publish-attachment}. +For non-Org files, you always need to specify the publishing function: @multitable @columnfractions 0.3 0.7 @item @code{:publishing-function} @@ -9994,17 +10729,18 @@ list of functions, which will all be called in turn. @tab Non-nil means, publish htmlized source. @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. +The function must accept three arguments: a property list containing at least +a @code{:publishing-directory} property, the name of the file to be +published, and the path to the publishing directory of the output file. It +should take the specified file, make the necessary transformation (if any) +and place the result into the destination folder. @node Publishing options, Publishing links, Publishing action, Configuration -@subsection Options for the HTML/La@TeX{} exporters +@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 +and @LaTeX{} exporters. In most cases, these properties correspond to user variables in Org. The table below lists these properties along with the variable they belong to. See the documentation string for the respective variable for details. @@ -10033,6 +10769,7 @@ respective variable for details. @vindex org-export-with-fixed-width @vindex org-export-with-timestamps @vindex org-export-author-info +@vindex org-export-email @vindex org-export-creator-info @vindex org-export-with-tables @vindex org-export-highlight-first-table-line @@ -10081,6 +10818,7 @@ respective variable for details. @item @code{:fixed-width} @tab @code{org-export-with-fixed-width} @item @code{:timestamps} @tab @code{org-export-with-timestamps} @item @code{:author-info} @tab @code{org-export-author-info} +@item @code{:email-info} @tab @code{org-export-email-info} @item @code{:creator-info} @tab @code{org-export-creator-info} @item @code{:tables} @tab @code{org-export-with-tables} @item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line} @@ -10107,9 +10845,9 @@ respective variable for details. @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 +both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and @code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the -La@TeX{} export. +@LaTeX{} export. @vindex org-publish-project-alist When a property is given a value in @code{org-publish-project-alist}, @@ -10117,7 +10855,7 @@ 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 +@node Publishing links, Sitemap, Publishing options, Configuration @subsection Links between published files @cindex links, publishing @@ -10154,31 +10892,61 @@ 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 +@node Sitemap, Generating an index, Publishing links, Configuration +@subsection Generating a sitemap +@cindex sitemap, of published pages -The following properties may be used to control publishing of an -index of files or a summary page for a given project. +The following properties may be used to control publishing of +a map of files for a given project. -@multitable @columnfractions 0.25 0.75 -@item @code{:auto-index} -@tab When non-nil, publish an index during @code{org-publish-current-project} +@multitable @columnfractions 0.35 0.65 +@item @code{:auto-sitemap} +@tab When non-nil, publish a sitemap during @code{org-publish-current-project} or @code{org-publish-all}. -@item @code{:index-filename} -@tab Filename for output of index. Defaults to @file{sitemap.org} (which +@item @code{:sitemap-filename} +@tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which becomes @file{sitemap.html}). -@item @code{:index-title} -@tab Title of index page. Defaults to name of file. +@item @code{:sitemap-title} +@tab Title of sitemap page. Defaults to name of file. -@item @code{:index-function} -@tab Plug-in function to use for generation of index. -Defaults to @code{org-publish-org-index}, which generates a plain list +@item @code{:sitemap-function} +@tab Plug-in function to use for generation of the sitemap. +Defaults to @code{org-publish-org-sitemap}, which generates a plain list of links to all files in the project. + +@item @code{:sitemap-sort-folders} +@tab Where folders should appear in the sitemap. Set this to @code{first} +(default) or @code{last} to display folders first or last, +respectively. Any other value will mix files and folders. + +@item @code{:sitemap-alphabetically} +@tab The site map is normally sorted alphabetically. Set this explicitly to +@code{nil} to turn off sorting. + +@item @code{:sitemap-ignore-case} +@tab Should sorting be case-sensitive? Default @code{nil}. + @end multitable +@node Generating an index, , Sitemap, Configuration +@subsection Generating an index +@cindex index, in a publishing project + +Org-mode can generate an index across the files of a publishing project. + +@multitable @columnfractions 0.25 0.75 +@item @code{:makeindex} +@tab When non-nil, generate in index in the file @file{theindex.org} and +publish it as @file{theindex.html}. +@end multitable + +The file will be create when first publishing a project with the +@code{:makeindex} set. The file only contains a statement @code{#+include: +"theindex.inc"}. You can then built around this include statement by adding +a title, style information etc. + @node Uploading files, Sample configuration, Configuration, Publishing @section Uploading files @cindex rsync @@ -10186,7 +10954,7 @@ of links to all files in the project. For those people already utilizing third party sync tools such as @command{rsync} or @command{unison}, it might be preferable not to use the built in -@i{remote} publishing facilities of Org mode which rely heavily on +@i{remote} publishing facilities of Org-mode which rely heavily on Tramp. Tramp, while very useful and powerful, tends not to be so efficient for multiple file transfer and has been known to cause problems under heavy usage. @@ -10253,7 +11021,7 @@ 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 +publishable images in @file{~/images}, you would link to an image with @c @example file:../images/myimage.png @@ -10299,17 +11067,13 @@ right place on the web server, and publishing images to it. Once properly configured, Org can publish with the following commands: @table @kbd -@kindex C-c C-e C -@item C-c C-e C +@orgcmd{C-c C-e X,org-publish} Prompt for a specific project and publish all files that belong to it. -@kindex C-c C-e P -@item C-c C-e P +@orgcmd{C-c C-e P,org-publish-current-project} Publish the project containing the current file. -@kindex C-c C-e F -@item C-c C-e F +@orgcmd{C-c C-e F,org-publish-current-file} Publish only the current file. -@kindex C-c C-e E -@item C-c C-e E +@orgcmd{C-c C-e E,org-publish-all} Publish every project. @end table @@ -10321,12 +11085,1405 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}. This may be necessary in particular if files include other files via @code{#+SETUPFILE:} or @code{#+INCLUDE:}. -@node Miscellaneous, Hacking, Publishing, Top +@comment node-name, next, previous, up +@comment Working With Source Code, Miscellaneous, Publishing, Top + +@node Working With Source Code, Miscellaneous, Publishing, Top +@chapter Working with source code +@cindex Schulte, Eric +@cindex Davison, Dan +@cindex source code, working with + +Source code can be included in Org-mode documents using a @samp{src} block, +e.g. + +@example +#+BEGIN_SRC emacs-lisp + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end example + +Org-mode provides a number of features for working with live source code, +including editing of code blocks in their native major-mode, evaluation of +code blocks, tangling of code blocks, and exporting code blocks and their +results in several formats. This functionality was contributed by Eric +Schulte and Dan Davison, and was originally named Org-babel. + +The following sections describe Org-mode's code block handling facilities. + +@menu +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line +@end menu + +@comment node-name, next, previous, up +@comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code + +@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code +@section Structure of code blocks +@cindex code block, structure +@cindex source code, block structure + +The structure of code blocks is as follows: + +@example +#+srcname: <name> +#+begin_src <language> <switches> <header arguments> + <body> +#+end_src +@end example + +code blocks can also be embedded in text as so called inline code blocks as + +@example +src_<language>@{<body>@} +@end example + +or + +@example +src_<language>[<header arguments>]@{<body>@} +@end example + +@table @code +@item <name> +This name is associated with the code block. This is similar to the +@samp{#+tblname} lines that can be used to name tables in Org-mode files. +Referencing the name of a code block makes it possible to evaluate the +block from other places in the file, other files, or from Org-mode table +formulas (see @ref{The spreadsheet}). +@item <language> +The language of the code in the block. +@item <switches> +Switches controlling exportation of the code block (see switches discussion in +@ref{Literal examples}) +@item <header arguments> +Optional header arguments control many aspects of evaluation, export and +tangling of code blocks. See the @ref{Header arguments} +section. Header arguments can also be set on a per-buffer or per-subtree +basis using properties. +@item <body> +The source code. +@end table + +@comment node-name, next, previous, up +@comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code + +@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code +@section Editing source code +@cindex code block, editing +@cindex source code, editing + +@kindex C-c ' +Use @kbd{C-c '} to edit the current code block. This brings up +a language major-mode edit buffer containing the body of the code +block. Saving this buffer will write the new contents back to the Org +buffer. Use @kbd{C-c '} again to exit. + +The @code{org-src-mode} minor mode will be active in the edit buffer. The +following variables can be used to configure the behavior of the edit +buffer. See also the customization group @code{org-edit-structure} for +further configuration options. + +@table @code +@item org-src-lang-modes +If an Emacs major-mode named @code{<lang>-mode} exists, where +@code{<lang>} is the language named in the header line of the code block, +then the edit buffer will be placed in that major-mode. This variable +can be used to map arbitrary language names to existing major modes. +@item org-src-window-setup +Controls the way Emacs windows are rearranged when the edit buffer is created. +@item org-src-preserve-indentation +This variable is especially useful for tangling languages such as +Python, in which whitespace indentation in the output is critical. +@item org-src-ask-before-returning-to-edit-buffer +By default, Org will ask before returning to an open edit buffer. Set +this variable to nil to switch without asking. +@end table + +@comment node-name, next, previous, up +@comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code + +@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code +@section Exporting code blocks +@cindex code block, exporting +@cindex source code, exporting + +It is possible to export the @emph{contents} of code blocks, the +@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For +most languages, the default exports the contents of code blocks. However, for +some languages (e.g. @code{ditaa}) the default exports the results of code +block evaluation. For information on exporting code block bodies, see +@ref{Literal examples}. + +The @code{:exports} header argument can be used to specify export +behavior: + +@subsubheading Header arguments: +@table @code +@item :exports code +The default in most languages. The body of the code block is exported, as +described in @ref{Literal examples}. +@item :exports results +The code block will be evaluated and the results will be placed in the +Org-mode buffer for export, either updating previous results of the code +block located anywhere in the buffer or, if no previous results exist, +placing the results immediately after the code block. The body of the code +block will not be exported. +@item :exports both +Both the code block and its results will be exported. +@item :exports none +Neither the code block nor its results will be exported. +@end table + +It is possible to inhibit the evaluation of code blocks during export. +Setting the @code{org-export-babel-evaluate} variable to @code{nil} will +ensure that no code blocks are evaluated as part of the export process. This +can be useful in situations where potentially untrusted Org-mode files are +exported in an automated fashion, for example when Org-mode is used as the +markup language for a wiki. + +@comment node-name, next, previous, up +@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code +@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code +@section Extracting source code +@cindex source code, extracting +@cindex code block, extracting source code + +Creating pure source code files by extracting code from source blocks is +referred to as ``tangling''---a term adopted from the literate programming +community. During ``tangling'' of code blocks their bodies are expanded +using @code{org-babel-expand-src-block} which can expand both variable and +``noweb'' style references (see @ref{Noweb reference syntax}). + +@subsubheading Header arguments +@table @code +@item :tangle no +The default. The code block is not included in the tangled output. +@item :tangle yes +Include the code block in the tangled output. The output file name is the +name of the org file with the extension @samp{.org} replaced by the extension +for the block language. +@item :tangle filename +Include the code block in the tangled output to file @samp{filename}. +@end table + +@kindex C-c C-v t +@subsubheading Functions +@table @code +@item org-babel-tangle +Tangle the current file. Bound to @kbd{C-c C-v t}. +@item org-babel-tangle-file +Choose a file to tangle. Bound to @kbd{C-c C-v f}. +@end table + +@subsubheading Hooks +@table @code +@item org-babel-post-tangle-hook +This hook is run from within code files tangled by @code{org-babel-tangle}. +Example applications could include post-processing, compilation or evaluation +of tangled code files. +@end table + +@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code +@section Evaluating code blocks +@cindex code block, evaluating +@cindex source code, evaluating + +Code blocks can be evaluated@footnote{Whenever code is evaluated there is a +potential for that code to do harm. Org-mode provides a number of safeguards +to ensure that it only evaluates code with explicit confirmation from the +user. For information on these safeguards (and on how to disable them) see +@ref{Code evaluation security}.} and the results placed in the Org-mode +buffer. By default, evaluation is only turned on for @code{emacs-lisp} code +blocks, however support exists for evaluating blocks in many languages. See +@ref{Languages} for a list of supported languages. See @ref{Structure of +code blocks} for information on the syntax used to define a code block. + +@kindex C-c C-c +There are a number of ways to evaluate code blocks. The simplest is to press +@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The +@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code +evaluation from the @kbd{C-c C-c} key binding.}. This will call the +@code{org-babel-execute-src-block} function to evaluate the block and insert +its results into the Org-mode buffer. + +It is also possible to evaluate named code blocks from anywhere in an +Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously +@code{#+function} or @code{#+lob}) lines can be used to remotely execute code +blocks located in the current Org-mode buffer or in the ``Library of Babel'' +(see @ref{Library of Babel}). These lines use the following syntax. + +@example +#+call: <name>(<arguments>) <header arguments> +#+function: <name>(<arguments>) <header arguments> +#+lob: <name>(<arguments>) <header arguments> +@end example + +@table @code +@item <name> +The name of the code block to be evaluated. +@item <arguments> +Arguments specified in this section will be passed to the code block. +@item <header arguments> +Header arguments can be placed after the function invocation. See +@ref{Header arguments} for more information on header arguments. +@end table + + +@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code +@section Library of Babel +@cindex babel, library of +@cindex source code, library +@cindex code block, library + +The ``Library of Babel'' is a library of code blocks +that can be called from any Org-mode file. The library is housed in an +Org-mode file located in the @samp{contrib} directory of Org-mode. +Org-mode users can deposit functions they believe to be generally +useful in the library. + +Code blocks defined in the ``Library of Babel'' can be called remotely as if +they were in the current Org-mode buffer (see @ref{Evaluating code blocks} +for information on the syntax of remote code block evaluation). + +@kindex C-c C-v i +Code blocks located in any Org-mode file can be loaded into the ``Library of +Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v +i}. + +@node Languages, Header arguments, Library of Babel, Working With Source Code +@section Languages +@cindex babel, languages +@cindex source code, languages +@cindex code block, languages + +Code blocks in the following languages are supported. + +@multitable @columnfractions 0.28 0.3 0.22 0.2 +@item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier} +@item Asymptote @tab asymptote @tab C @tab C +@item C++ @tab C++ @tab Clojure @tab clojure +@item CSS @tab css @tab ditaa @tab ditaa +@item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp +@item gnuplot @tab gnuplot @tab Haskell @tab haskell +@item LaTeX @tab latex @tab MATLAB @tab matlab +@item Mscgen @tab mscgen @tab Objective Caml @tab ocaml +@item Octave @tab octave @tab Oz @tab oz +@item Perl @tab perl @tab Python @tab python +@item R @tab R @tab Ruby @tab ruby +@item Sass @tab sass @tab GNU Screen @tab screen +@item shell @tab sh @tab SQL @tab sql +@item SQLite @tab sqlite +@end multitable + +Language-specific documentation is available for some languages. If +available, it can be found at +@uref{http://orgmode.org/worg/org-contrib/babel/languages}. + +The @code{org-babel-load-languages} controls which languages are enabled for +evaluation (by default only @code{emacs-lisp} is enabled). This variable can +be set using the customization interface or by adding code like the following +to your emacs configuration. + +@quotation +The following disables @code{emacs-lisp} evaluation and enables evaluation of +@code{R} code blocks. +@end quotation + +@lisp +(org-babel-do-load-languages + 'org-babel-load-languages + '((emacs-lisp . nil) + (R . t))) +@end lisp + +It is also possible to enable support for a language by loading the related +elisp file with @code{require}. + +@quotation +The following adds support for evaluating @code{clojure} code blocks. +@end quotation + +@lisp +(require 'ob-clojure) +@end lisp + +@node Header arguments, Results of evaluation, Languages, Working With Source Code +@section Header arguments +@cindex code block, header arguments +@cindex source code, block header arguments + +Code block functionality can be configured with header arguments. This +section provides an overview of the use of header arguments, and then +describes each header argument in detail. + +@menu +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments +@end menu + +@node Using header arguments, Specific header arguments, Header arguments, Header arguments +@subsection Using header arguments + +The values of header arguments can be set in six different ways, each more +specific (and having higher priority) than the last. +@menu +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values +* Header arguments in function calls:: The most specific level +@end menu + + +@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments +@subsubheading System-wide header arguments +@vindex org-babel-default-header-args +System-wide values of header arguments can be specified by customizing the +@code{org-babel-default-header-args} variable: + +@example +:session => "none" +:results => "replace" +:exports => "code" +:cache => "no" +:noweb => "no" +@end example + +@c @example +@c org-babel-default-header-args is a variable defined in `org-babel.el'. +@c Its value is +@c ((:session . "none") +@c (:results . "replace") +@c (:exports . "code") +@c (:cache . "no") +@c (:noweb . "no")) + + +@c Documentation: +@c Default arguments to use when evaluating a code block. +@c @end example + +For example, the following example could be used to set the default value of +@code{:noweb} header arguments to @code{yes}. This would have the effect of +expanding @code{:noweb} references by default when evaluating source code +blocks. + +@lisp +(setq org-babel-default-header-args +(cons '(:noweb . "yes") +(assq-delete-all :noweb org-babel-default-header-args))) +@end lisp + +@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments +@subsubheading Language-specific header arguments +Each language can define its own set of default header arguments. See the +language-specific documentation available online at +@uref{http://orgmode.org/worg/org-contrib/babel}. + +@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments +@subsubheading Buffer-wide header arguments +Buffer-wide header arguments may be specified through the use of a special +line placed anywhere in an Org-mode file. The line consists of the +@code{#+BABEL:} keyword followed by a series of header arguments which may be +specified using the standard header argument syntax. + +For example the following would set @code{session} to @code{*R*}, and +@code{results} to @code{silent} for every code block in the buffer, ensuring +that all execution took place in the same session, and no results would be +inserted into the buffer. + +@example +#+BABEL: :session *R* :results silent +@end example + +@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments +@subsubheading Header arguments in Org-mode properties + +Header arguments are also read from Org-mode properties (see @ref{Property +syntax}), which can be set on a buffer-wide or per-heading basis. An example +of setting a header argument for all code blocks in a buffer is + +@example +#+property: tangle yes +@end example + +When properties are used to set default header arguments, they are looked up +with inheritance, so the value of the @code{:cache} header argument will default +to @code{yes} in all code blocks in the subtree rooted at the following +heading: + +@example +* outline header +:PROPERTIES: +:cache: yes +:END: +@end example + +@kindex C-c C-x p +@vindex org-babel-default-header-args +Properties defined in this way override the properties set in +@code{org-babel-default-header-args}. It is convenient to use the +@code{org-set-property} function bound to @kbd{C-c C-x p} to set properties +in Org-mode documents. + +@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org-mode properties, Using header arguments +@subsubheading Code block specific header arguments + +The most common way to assign values to header arguments is at the +code block level. This can be done by listing a sequence of header +arguments and their values as part of the @code{#+begin_src} line. +Properties set in this way override both the values of +@code{org-babel-default-header-args} and header arguments specified as +properties. In the following example, the @code{:results} header argument +is set to @code{silent}, meaning the results of execution will not be +inserted in the buffer, and the @code{:exports} header argument is set to +@code{code}, meaning only the body of the code block will be +preserved on export to HTML or LaTeX. + +@example +#+source: factorial +#+begin_src haskell :results silent :exports code :var n=0 +fac 0 = 1 +fac n = n * fac (n-1) +#+end_src +@end example +Similarly, it is possible to set header arguments for inline code blocks: + +@example +src_haskell[:exports both]@{fac 5@} +@end example + +@node Header arguments in function calls, , Code block specific header arguments, Using header arguments +@comment node-name, next, previous, up +@subsubheading Header arguments in function calls + +At the most specific level, header arguments for ``Library of Babel'' or +function call lines can be set as shown below: + +@example +#+call: factorial(n=5) :exports results +@end example + +@node Specific header arguments, , Using header arguments, Header arguments +@subsection Specific header arguments +The following header arguments are defined: + +@menu +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will + be collected and handled +* file:: Specify a path for file output +* dir:: Specify the default (possibly remote) + directory for code block execution +* exports:: Export code and/or results +* tangle:: Toggle tangling and specify file name +* comments:: Toggle insertion of comments in tangled + code files +* no-expand:: Turn off variable assignment and noweb + expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables +* shebang:: Make tangled files executable +* eval:: Limit evaluation of specific code blocks +@end menu + +@node var, results, Specific header arguments, Specific header arguments +@subsubsection @code{:var} +The @code{:var} header argument is used to pass arguments to code blocks. +The specifics of how arguments are included in a code block vary by language; +these are addressed in the language-specific documentation. However, the +syntax used to specify arguments is the same across all languages. The +values passed to arguments can be literal values, values from org-mode tables +and literal example blocks, or the results of other code blocks. + +These values can be indexed in a manner similar to arrays---see the +``indexable variable values'' heading below. + +The following syntax is used to pass arguments to code blocks using the +@code{:var} header argument. + +@example +:var name=assign +@end example + +where @code{assign} can take one of the following forms + +@itemize @bullet +@item literal value +either a string @code{"string"} or a number @code{9}. +@item reference +a table name: + +@example +#+tblname: example-table +| 1 | +| 2 | +| 3 | +| 4 | + +#+source: table-length +#+begin_src emacs-lisp :var table=example-table +(length table) +#+end_src + +#+results: table-length +: 4 +@end example + +a code block name, as assigned by @code{#+srcname:}, followed by +parentheses: + +@example +#+begin_src emacs-lisp :var length=table-length() +(* 2 length) +#+end_src + +#+results: +: 8 +@end example + +In addition, an argument can be passed to the code block referenced +by @code{:var}. The argument is passed within the parentheses following the +code block name: + +@example +#+source: double +#+begin_src emacs-lisp :var input=8 +(* 2 input) +#+end_src + +#+results: double +: 16 + +#+source: squared +#+begin_src emacs-lisp :var input=double(input=1) +(* input input) +#+end_src + +#+results: squared +: 4 +@end example +@end itemize + +@subsubheading Alternate argument syntax +It is also possible to specify arguments in a potentially more natural way +using the @code{#+source:} line of a code block. As in the following +example arguments can be packed inside of parenthesis, separated by commas, +following the source name. + +@example +#+source: double(input=0, x=2) +#+begin_src emacs-lisp +(* 2 (+ input x)) +#+end_src +@end example + +@subsubheading Indexable variable values +It is possible to reference portions of variable values by ``indexing'' into +the variables. Indexes are 0 based with negative values counting back from +the end. If an index is separated by @code{,}s then each subsequent section +will index into the next deepest nesting or dimension of the value. The +following example assigns the last cell of the first row the table +@code{example-table} to the variable @code{data}: + +@example +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | + +#+begin_src emacs-lisp :var data=example-table[0,-1] + data +#+end_src + +#+results: +: a +@end example + +Ranges of variable values can be referenced using two integers separated by a +@code{:}, in which case the entire inclusive range is referenced. For +example the following assigns the middle three rows of @code{example-table} +to @code{data}. + +@example +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | +| 5 | 3 | + +#+begin_src emacs-lisp :var data=example-table[1:3] + data +#+end_src + +#+results: +| 2 | b | +| 3 | c | +| 4 | d | +@end example + +Additionally, an empty index, or the single character @code{*}, are both +interpreted to mean the entire range and as such are equivalent to +@code{0:-1}, as shown in the following example in which the entire first +column is referenced. + +@example +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | + +#+begin_src emacs-lisp :var data=example-table[,0] + data +#+end_src + +#+results: +| 1 | 2 | 3 | 4 | +@end example + +It is possible to index into the results of code blocks as well as tables. +Any number of dimensions can be indexed. Dimensions are separated from one +another by commas, as shown in the following example. + +@example +#+source: 3D +#+begin_src emacs-lisp + '(((1 2 3) (4 5 6) (7 8 9)) + ((10 11 12) (13 14 15) (16 17 18)) + ((19 20 21) (22 23 24) (25 26 27))) +#+end_src + +#+begin_src emacs-lisp :var data=3D[1,,1] + data +#+end_src + +#+results: +| 11 | 14 | 17 | +@end example + +@node results, file, var, Specific header arguments +@subsubsection @code{:results} + +There are three classes of @code{:results} header argument. Only one option +per class may be supplied per code block. + +@itemize @bullet +@item +@b{collection} header arguments specify how the results should be collected +from the code block +@item +@b{type} header arguments specify what type of result the code block will +return---which has implications for how they will be inserted into the +Org-mode buffer +@item +@b{handling} header arguments specify how the results of evaluating the code +block should be handled. +@end itemize + +@subsubheading Collection +The following options are mutually exclusive, and specify how the results +should be collected from the code block. + +@itemize @bullet +@item @code{value} +This is the default. The result is the value of the last statement in the +code block. This header argument places the evaluation in functional +mode. Note that in some languages, e.g., Python, use of this result type +requires that a @code{return} statement be included in the body of the source +code block. E.g., @code{:results value}. +@item @code{output} +The result is the collection of everything printed to STDOUT during the +execution of the code block. This header argument places the +evaluation in scripting mode. E.g., @code{:results output}. +@end itemize + +@subsubheading Type + +The following options are mutually exclusive and specify what type of results +the code block will return. By default, results are inserted as either a +table or scalar depending on their value. + +@itemize @bullet +@item @code{table}, @code{vector} +The results should be interpreted as an Org-mode table. If a single value is +returned, it will be converted into a table with one row and one column. +E.g., @code{:results value table}. +@item @code{list} +The results should be interpreted as an Org-mode list. If a single scalar +value is returned it will be converted into a list with only one element. +@item @code{scalar}, @code{verbatim} +The results should be interpreted literally---they will not be +converted into a table. The results will be inserted into the Org-mode +buffer as quoted text. E.g., @code{:results value verbatim}. +@item @code{file} +The results will be interpreted as the path to a file, and will be inserted +into the Org-mode buffer as a file link. E.g., @code{:results value file}. +@item @code{raw}, @code{org} +The results are interpreted as raw Org-mode code and are inserted directly +into the buffer. If the results look like a table they will be aligned as +such by Org-mode. E.g., @code{:results value raw}. +@item @code{html} +Results are assumed to be HTML and will be enclosed in a @code{begin_html} +block. E.g., @code{:results value html}. +@item @code{latex} +Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. +E.g., @code{:results value latex}. +@item @code{code} +Result are assumed to be parseable code and are enclosed in a code block. +E.g., @code{:results value code}. +@item @code{pp} +The result is converted to pretty-printed code and is enclosed in a code +block. This option currently supports Emacs Lisp, Python, and Ruby. E.g., +@code{:results value pp}. +@end itemize + +@subsubheading Handling +The following results options indicate what happens with the +results once they are collected. + +@itemize @bullet +@item @code{silent} +The results will be echoed in the minibuffer but will not be inserted into +the Org-mode buffer. E.g., @code{:results output silent}. +@item @code{replace} +The default value. Any existing results will be removed, and the new results +will be inserted into the Org-mode buffer in their place. E.g., +@code{:results output replace}. +@item @code{append} +If there are pre-existing results of the code block then the new results will +be appended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@item @code{prepend} +If there are pre-existing results of the code block then the new results will +be prepended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@end itemize + +@node file, dir, results, Specific header arguments +@subsubsection @code{:file} + +The header argument @code{:file} is used to specify a path for file output. +An Org-mode style @code{file:} link is inserted into the buffer as the result +(see @ref{Link format}). Common examples are graphical output from R, +gnuplot, ditaa and LaTeX code blocks. + +Note that for some languages, including R, gnuplot, LaTeX and ditaa, +graphical output is sent to the specified file without the file being +referenced explicitly in the code block. See the documentation for the +individual languages for details. In contrast, general purpose languages such +as Python and Ruby require that the code explicitly create output +corresponding to the path indicated by @code{:file}. + + +@node dir, exports, file, Specific header arguments +@subsubsection @code{:dir} and remote execution + +While the @code{:file} header argument can be used to specify the path to the +output file, @code{:dir} specifies the default directory during code block +execution. If it is absent, then the directory associated with the current +buffer is used. In other words, supplying @code{:dir path} temporarily has +the same effect as changing the current directory with @kbd{M-x cd path}, and +then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets +the value of the Emacs variable @code{default-directory}. + +When using @code{:dir}, you should supply a relative path for file output +(e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which +case that path will be interpreted relative to the default directory. + +In other words, if you want your plot to go into a folder called @file{Work} +in your home directory, you could use + +@example +#+begin_src R :file myplot.png :dir ~/Work +matplot(matrix(rnorm(100), 10), type="l") +#+end_src +@end example + +@subsubheading Remote execution +A directory on a remote machine can be specified using tramp file syntax, in +which case the code will be evaluated on the remote machine. An example is + +@example +#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: +plot(1:10, main=system("hostname", intern=TRUE)) +#+end_src +@end example + +Text results will be returned to the local Org-mode buffer as usual, and file +output will be created on the remote machine with relative paths interpreted +relative to the remote directory. An Org-mode link to the remote file will be +created. + +So, in the above example a plot will be created on the remote machine, +and a link of the following form will be inserted in the org buffer: + +@example +[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] +@end example + +Most of this functionality follows immediately from the fact that @code{:dir} +sets the value of the Emacs variable @code{default-directory}, thanks to +tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to +install tramp separately in order for these features to work correctly. + +@subsubheading Further points + +@itemize @bullet +@item +If @code{:dir} is used in conjunction with @code{:session}, although it will +determine the starting directory for a new session as expected, no attempt is +currently made to alter the directory associated with an existing session. +@item +@code{:dir} should typically not be used to create files during export with +@code{:exports results} or @code{:exports both}. The reason is that, in order +to retain portability of exported material between machines, during export +links inserted into the buffer will *not* be expanded against @code{default +directory}. Therefore, if @code{default-directory} is altered using +@code{:dir}, it is probable that the file will be created in a location to +which the link does not point. +@end itemize + +@node exports, tangle, dir, Specific header arguments +@subsubsection @code{:exports} + +The @code{:exports} header argument specifies what should be included in HTML +or LaTeX exports of the Org-mode file. + +@itemize @bullet +@item @code{code} +The default. The body of code is included into the exported file. E.g., +@code{:exports code}. +@item @code{results} +The result of evaluating the code is included in the exported file. E.g., +@code{:exports results}. +@item @code{both} +Both the code and results are included in the exported file. E.g., +@code{:exports both}. +@item @code{none} +Nothing is included in the exported file. E.g., @code{:exports none}. +@end itemize + +@node tangle, comments, exports, Specific header arguments +@subsubsection @code{:tangle} + +The @code{:tangle} header argument specifies whether or not the code +block should be included in tangled extraction of source code files. + +@itemize @bullet +@item @code{tangle} +The code block is exported to a source code file named after the +basename (name w/o extension) of the Org-mode file. E.g., @code{:tangle +yes}. +@item @code{no} +The default. The code block is not exported to a source code file. +E.g., @code{:tangle no}. +@item other +Any other string passed to the @code{:tangle} header argument is interpreted +as a file basename to which the block will be exported. E.g., @code{:tangle +basename}. +@end itemize + +@node comments, no-expand, tangle, Specific header arguments +@subsubsection @code{:comments} +By default code blocks are tangled to source-code files without any insertion +of comments beyond those which may already exist in the body of the code +block. The @code{:comments} header argument can be set as follows to control +the insertion of extra comments into the tangled code file. + +@itemize @bullet +@item @code{no} +The default. No extra comments are inserted during tangling. +@item @code{link} +The code block is wrapped in comments which contain pointers back to the +original Org file from which the code was tangled. +@item @code{yes} +A synonym for ``link'' to maintain backwards compatibility. +@item @code{org} +Include text from the org-mode file as a comment. + +The text is picked from the leading context of the tangled code and is +limited by the nearest headline or source block as the case may be. +@item @code{both} +Turns on both the ``link'' and ``org'' comment options. +@end itemize + +@node no-expand, session, comments, Specific header arguments +@subsubsection @code{:no-expand} + +By default, code blocks are expanded with @code{org-babel-expand-src-block} +during tangling. This has the effect of assigning values to variables +specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' +references (see @ref{Noweb reference syntax}) with their targets. The +@code{:no-expand} header argument can be used to turn off this behavior. + +@node session, noweb, no-expand, Specific header arguments +@subsubsection @code{:session} + +The @code{:session} header argument starts a session for an interpreted +language where state is preserved. + +By default, a session is not started. + +A string passed to the @code{:session} header argument will give the session +a name. This makes it possible to run concurrent sessions for each +interpreted language. + +@node noweb, cache, session, Specific header arguments +@subsubsection @code{:noweb} + +The @code{:noweb} header argument controls expansion of ``noweb'' style (see +@ref{Noweb reference syntax}) references in a code block. This header +argument can have one of three values: @code{yes} @code{no} or @code{tangle}. + +@itemize @bullet +@item @code{yes} +All ``noweb'' syntax references in the body of the code block will be +expanded before the block is evaluated, tangled or exported. +@item @code{no} +The default. No ``noweb'' syntax specific action is taken on evaluating +code blocks, However, noweb references will still be expanded during +tangling. +@item @code{tangle} +All ``noweb'' syntax references in the body of the code block will be +expanded before the block is tangled, however ``noweb'' references will not +be expanded when the block is evaluated or exported. +@end itemize + +@subsubheading Noweb prefix lines +Noweb insertions are now placed behind the line prefix of the +@code{<<reference>>}. +This behavior is illustrated in the following example. Because the +@code{<<example>>} noweb reference appears behind the SQL comment syntax, +each line of the expanded noweb reference will be commented. + +This code block: + +@example +-- <<example>> +@end example + + +expands to: + +@example +-- this is the +-- multi-line body of example +@end example + +Note that noweb replacement text that does not contain any newlines will not +be affected by this change, so it is still possible to use inline noweb +references. + +@node cache, hlines, noweb, Specific header arguments +@subsubsection @code{:cache} + +The @code{:cache} header argument controls the use of in-buffer caching of +the results of evaluating code blocks. It can be used to avoid re-evaluating +unchanged code blocks. This header argument can have one of two +values: @code{yes} or @code{no}. + +@itemize @bullet +@item @code{no} +The default. No caching takes place, and the code block will be evaluated +every time it is called. +@item @code{yes} +Every time the code block is run a SHA1 hash of the code and arguments +passed to the block will be generated. This hash is packed into the +@code{#+results:} line and will be checked on subsequent +executions of the code block. If the code block has not +changed since the last time it was evaluated, it will not be re-evaluated. +@end itemize + +@node hlines, colnames, cache, Specific header arguments +@subsubsection @code{:hlines} + +Tables are frequently represented with one or more horizontal lines, or +hlines. The @code{:hlines} argument to a code block accepts the +values @code{yes} or @code{no}, with a default value of @code{no}. + +@itemize @bullet +@item @code{no} +Strips horizontal lines from the input table. In most languages this is the +desired effect because an @code{hline} symbol is interpreted as an unbound +variable and raises an error. Setting @code{:hlines no} or relying on the +default value yields the following results. + +@example +#+tblname: many-cols +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | + +#+source: echo-table +#+begin_src python :var tab=many-cols + return tab +#+end_src + +#+results: echo-table +| a | b | c | +| d | e | f | +| g | h | i | +@end example + +@item @code{yes} +Leaves hlines in the table. Setting @code{:hlines yes} has this effect. + +@example +#+tblname: many-cols +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | + +#+source: echo-table +#+begin_src python :var tab=many-cols :hlines yes + return tab +#+end_src + +#+results: echo-table +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | +@end example +@end itemize + +@node colnames, rownames, hlines, Specific header arguments +@subsubsection @code{:colnames} + +The @code{:colnames} header argument accepts the values @code{yes}, +@code{no}, or @code{nil} for unassigned. The default value is @code{nil}. + +@itemize @bullet +@item @code{nil} +If an input table looks like it has column names +(because its second row is an hline), then the column +names will be removed from the table before +processing, then reapplied to the results. + +@example +#+tblname: less-cols +| a | +|---| +| b | +| c | + +#+srcname: echo-table-again +#+begin_src python :var tab=less-cols + return [[val + '*' for val in row] for row in tab] +#+end_src + +#+results: echo-table-again +| a | +|----| +| b* | +| c* | +@end example + +@item @code{no} +No column name pre-processing takes place + +@item @code{yes} +Column names are removed and reapplied as with @code{nil} even if the table +does not ``look like'' it has column names (i.e. the second row is not an +hline) +@end itemize + +@node rownames, shebang, colnames, Specific header arguments +@subsubsection @code{:rownames} + +The @code{:rownames} header argument can take on the values @code{yes} +or @code{no}, with a default value of @code{no}. + +@itemize @bullet +@item @code{no} +No row name pre-processing will take place. + +@item @code{yes} +The first column of the table is removed from the table before processing, +and is then reapplied to the results. + +@example +#+tblname: with-rownames +| one | 1 | 2 | 3 | 4 | 5 | +| two | 6 | 7 | 8 | 9 | 10 | + +#+srcname: echo-table-once-again +#+begin_src python :var tab=with-rownames :rownames yes + return [[val + 10 for val in row] for row in tab] +#+end_src + +#+results: echo-table-once-again +| one | 11 | 12 | 13 | 14 | 15 | +| two | 16 | 17 | 18 | 19 | 20 | +@end example +@end itemize + +@node shebang, eval, rownames, Specific header arguments +@subsubsection @code{:shebang} + +Setting the @code{:shebang} header argument to a string value +(e.g. @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the +first line of any tangled file holding the code block, and the file +permissions of the tangled file are set to make it executable. + +@node eval, , shebang, Specific header arguments +@subsubsection @code{:eval} +The @code{:eval} header argument can be used to limit the evaluation of +specific code blocks. @code{:eval} accepts two arguments ``never'' and +``query''. @code{:eval never} will ensure that a code block is never +evaluated, this can be useful for protecting against the evaluation of +dangerous code blocks. @code{:eval query} will require a query for every +execution of a code block regardless of the value of the +@code{org-confirm-babel-evaluate} variable. + +@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code +@section Results of evaluation +@cindex code block, results of evaluation +@cindex source code, results of evaluation + +The way in which results are handled depends on whether a session is invoked, +as well as on whether @code{:results value} or @code{:results output} is +used. The following table shows the possibilities: + +@multitable @columnfractions 0.26 0.33 0.41 +@item @tab @b{Non-session} @tab @b{Session} +@item @code{:results value} @tab value of last expression @tab value of last expression +@item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output +@end multitable + +Note: With @code{:results value}, the result in both @code{:session} and +non-session is returned to Org-mode as a table (a one- or two-dimensional +vector of strings or numbers) when appropriate. + +@subsection Non-session +@subsubsection @code{:results value} +This is the default. Internally, the value is obtained by wrapping the code +in a function definition in the external language, and evaluating that +function. Therefore, code should be written as if it were the body of such a +function. In particular, note that Python does not automatically return a +value from a function unless a @code{return} statement is present, and so a +@samp{return} statement will usually be required in Python. + +This is the only one of the four evaluation contexts in which the code is +automatically wrapped in a function definition. + +@subsubsection @code{:results output} +The code is passed to the interpreter as an external process, and the +contents of the standard output stream are returned as text. (In certain +languages this also contains the error output stream; this is an area for +future work.) + +@subsection Session +@subsubsection @code{:results value} +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the result of the last evaluation +performed by the interpreter. (This is obtained in a language-specific +manner: the value of the variable @code{_} in Python and Ruby, and the value +of @code{.Last.value} in R). + +@subsubsection @code{:results output} +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the concatenation of the sequence of +(text) output from the interactive interpreter. Notice that this is not +necessarily the same as what would be sent to @code{STDOUT} if the same code +were passed to a non-interactive interpreter running as an external +process. For example, compare the following two blocks: + +@example +#+begin_src python :results output + print "hello" + 2 + print "bye" +#+end_src + +#+resname: +: hello +: bye +@end example + +In non-session mode, the `2' is not printed and does not appear. +@example +#+begin_src python :results output :session + print "hello" + 2 + print "bye" +#+end_src + +#+resname: +: hello +: 2 +: bye +@end example + +But in @code{:session} mode, the interactive interpreter receives input `2' +and prints out its value, `2'. (Indeed, the other print statements are +unnecessary here). + +@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code +@section Noweb reference syntax +@cindex code block, noweb reference +@cindex syntax, noweb +@cindex source code, noweb reference + +The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate +Programming system allows named blocks of code to be referenced by using the +familiar Noweb syntax: + +@example +<<code-block-name>> +@end example + +When a code block is tangled or evaluated, whether or not ``noweb'' +references are expanded depends upon the value of the @code{:noweb} header +argument. If @code{:noweb yes}, then a Noweb reference is expanded before +evaluation. If @code{:noweb no}, the default, then the reference is not +expanded before evaluation. + +Note: the default value, @code{:noweb no}, was chosen to ensure that +correct code is not broken in a language, such as Ruby, where +@code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is not +syntactically valid in languages that you use, then please consider setting +the default value. + +@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code +@section Key bindings and useful functions +@cindex code block, key bindings + +Many common Org-mode key sequences are re-bound depending on +the context. + +Within a code block, the following key bindings +are active: + +@multitable @columnfractions 0.25 0.75 +@kindex C-c C-c +@item @kbd{C-c C-c} @tab org-babel-execute-src-block +@kindex C-c C-o +@item @kbd{C-c C-o} @tab org-babel-open-src-block-result +@kindex C-up +@item @kbd{C-@key{up}} @tab org-babel-load-in-session +@kindex M-down +@item @kbd{M-@key{down}} @tab org-babel-pop-to-session +@end multitable + +In an Org-mode buffer, the following key bindings are active: + +@multitable @columnfractions 0.45 0.55 +@kindex C-c C-v a +@kindex C-c C-v C-a +@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab org-babel-sha1-hash +@kindex C-c C-v b +@kindex C-c C-v C-b +@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab org-babel-execute-buffer +@kindex C-c C-v f +@kindex C-c C-v C-f +@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab org-babel-tangle-file +@kindex C-c C-v g +@item @kbd{C-c C-v g} @tab org-babel-goto-named-source-block +@kindex C-c C-v h +@item @kbd{C-c C-v h} @tab org-babel-describe-bindings +@kindex C-c C-v l +@kindex C-c C-v C-l +@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab org-babel-lob-ingest +@kindex C-c C-v p +@kindex C-c C-v C-p +@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab org-babel-expand-src-block +@kindex C-c C-v s +@kindex C-c C-v C-s +@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab org-babel-execute-subtree +@kindex C-c C-v t +@kindex C-c C-v C-t +@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab org-babel-tangle +@kindex C-c C-v z +@kindex C-c C-v C-z +@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab org-babel-switch-to-session +@end multitable + +@c When possible these keybindings were extended to work when the control key is +@c kept pressed, resulting in the following additional keybindings. + +@c @multitable @columnfractions 0.25 0.75 +@c @item @kbd{C-c C-v C-a} @tab org-babel-sha1-hash +@c @item @kbd{C-c C-v C-b} @tab org-babel-execute-buffer +@c @item @kbd{C-c C-v C-f} @tab org-babel-tangle-file +@c @item @kbd{C-c C-v C-l} @tab org-babel-lob-ingest +@c @item @kbd{C-c C-v C-p} @tab org-babel-expand-src-block +@c @item @kbd{C-c C-v C-s} @tab org-babel-execute-subtree +@c @item @kbd{C-c C-v C-t} @tab org-babel-tangle +@c @item @kbd{C-c C-v C-z} @tab org-babel-switch-to-session +@c @end multitable + +@node Batch execution, , Key bindings and useful functions, Working With Source Code +@section Batch execution +@cindex code block, batch execution +@cindex source code, batch execution + +It is possible to call functions from the command line. This shell +script calls @code{org-babel-tangle} on every one of its arguments. + +Be sure to adjust the paths to fit your system. + +@example +#!/bin/sh +# -*- mode: shell-script -*- +# +# tangle files with org-mode +# +DIR=`pwd` +FILES="" +ORGINSTALL="~/src/org/lisp/org-install.el" + +# wrap each argument in the code required to call tangle on it +for i in $@@; do + FILES="$FILES \"$i\"" +done + +emacs -Q --batch -l $ORGINSTALL \ +--eval "(progn +(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) +(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) +(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle) +(mapc (lambda (file) + (find-file (expand-file-name file \"$DIR\")) + (org-babel-tangle) + (kill-buffer)) '($FILES)))" 2>&1 |grep tangled +@end example + +@node Miscellaneous, Hacking, Working With Source Code, Top @chapter Miscellaneous @menu * Completion:: M-TAB knows what you need -* Speed keys:: Electic commands at the beginning of a headline +* Easy Templates:: Quick insertion of structural elements +* Speed keys:: Electric commands at the beginning of a headline +* Code evaluation security:: Org mode files evaluate inline code * Customization:: Adapting Org to your taste * In-buffer settings:: Overview of the #+KEYWORDS * The very busy C-c C-c key:: When in doubt, press C-c C-c @@ -10336,7 +12493,7 @@ This may be necessary in particular if files include other files via @end menu -@node Completion, Speed keys, Miscellaneous, Miscellaneous +@node Completion, Easy Templates, Miscellaneous, Miscellaneous @section Completion @cindex completion, of @TeX{} symbols @cindex completion, of TODO keywords @@ -10387,7 +12544,7 @@ buffer. 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 +@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 @@ -10398,7 +12555,46 @@ Elsewhere, complete dictionary words using Ispell. @end itemize @end table -@node Speed keys, Customization, Completion, Miscellaneous +@node Easy Templates, Speed keys, Completion, Miscellaneous +@section Easy Templates +@cindex template insertion +@cindex insertion, of templates + +Org-mode supports insertion of empty structural elements (like +@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key +strokes. This is achieved through a native template expansion mechanism. +Note that Emacs has several other template mechanisms which could be used in +a similar way, for example @file{yasnippet}. + +To insert a structural element, type a @samp{<}, followed by a template +selector and @kbd{@key{TAB}}. Completion takes effect only when the above +keystrokes are typed on a line by itself. + +The following template selectors are currently supported. + +@multitable @columnfractions 0.1 0.9 +@item @kbd{s} @tab @code{#+begin_src ... #+end_src} +@item @kbd{e} @tab @code{#+begin_example ... #+end_example} +@item @kbd{q} @tab @code{#+begin_quote ... #+end_quote} +@item @kbd{v} @tab @code{#+begin_verse ... #+end_verse} +@item @kbd{c} @tab @code{#+begin_center ... #+end_center} +@item @kbd{l} @tab @code{#+begin_latex ... #+end_latex} +@item @kbd{L} @tab @code{#+latex:} +@item @kbd{h} @tab @code{#+begin_html ... #+end_html} +@item @kbd{H} @tab @code{#+html:} +@item @kbd{a} @tab @code{#+begin_ascii ... #+end_ascii} +@item @kbd{A} @tab @code{#+ascii:} +@item @kbd{i} @tab @code{#+include:} line +@end multitable + +For example, on an empty line, typing "<e" and then pressing TAB, will expand +into a complete EXAMPLE template. + +You can install additional templates by customizing the variable +@code{org-structure-template-alist}. See the docstring of the variable for +additional details. + +@node Speed keys, Code evaluation security, Easy Templates, Miscellaneous @section Speed keys @cindex speed keys @vindex org-use-speed-commands @@ -10410,13 +12606,62 @@ beginning of a headline, i.e. before the first star. Configure the variable pre-defined list of commands, and you can add more such commands using the variable @code{org-speed-commands-user}. Speed keys do not only speed up navigation and other commands, but they also provide an alternative way to -execute commands bound to keys that are not or not easily available on a tty, +execute commands bound to keys that are not or not easily available on a TTY, or on a small mobile device with a limited keyboard. To see which commands are available, activate the feature and press @kbd{?} with the cursor at the beginning of a headline. -@node Customization, In-buffer settings, Speed keys, Miscellaneous +@node Code evaluation security, Customization, Speed keys, Miscellaneous +@section Code evaluation and security issues + +Org provides tools to work with the code snippets, including evaluating them. + +Running code on your machine always comes with a security risk. Badly +written or malicious code can be executed on purpose or by accident. Org has +default settings which will only evaluate such code if you give explicit +permission to do so, and as a casual user of these features you should leave +these precautions intact. + +For people who regularly work with such code, the confirmation prompts can +become annoying, and you might want to turn them off. This can be done, but +you must be aware of the risks that are involved. + +Code evaluation can happen under the following circumstances: + +@table @i +@item Source code blocks +Source code blocks can be evaluated during export, or when pressing @kbd{C-c +C-c} in the block. The most important thing to realize here is that Org mode +files which contain code snippets are, in a certain sense, like executable +files. So you should accept them and load them into Emacs only from trusted +sources---just like you would do with a program you install on your computer. + +Make sure you know what you are doing before customizing the variables +which take off the default security brakes. + +@defopt org-confirm-babel-evaluate +When set to t user is queried before code block evaluation +@end defopt + +@item Following @code{shell} and @code{elisp} links +Org has two link types that can directly evaluate code (@pxref{External +links}). These links can be problematic because the code to be evaluated is +not visible. + +@defopt org-confirm-shell-link-function +Function to queries user about shell link execution. +@end defopt +@defopt org-confirm-elisp-link-function +Functions to query user for Emacs Lisp link execution. +@end defopt + +@item Formulas in tables +Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated +either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter. +@end table + +@node Customization, In-buffer settings, Code evaluation security, Miscellaneous @section Customization @cindex customization @cindex options, for customization @@ -10435,7 +12680,7 @@ lines into the buffer (@pxref{In-buffer settings}). @cindex in-buffer settings @cindex special keywords -Org mode uses special lines in the buffer to define settings on a +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 @@ -10465,7 +12710,7 @@ applies. @vindex org-table-formula-constants @vindex org-table-formula Set file-local values for constants to be used in table formulas. This -line set the local variable @code{org-table-formula-constants-local}. +line sets the local variable @code{org-table-formula-constants-local}. The global version of this variable is @code{org-table-formula-constants}. @item #+FILETAGS: :tag1:tag2:tag3: @@ -10486,7 +12731,7 @@ These lines (several are allowed) specify link abbreviations. @vindex org-default-priority 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. +have a lower ASCII number than 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. @@ -10494,14 +12739,14 @@ buffer, most useful for specifying the allowed values of a property. @item #+SETUPFILE: file This line defines a file that holds more in-buffer setup. Normally this is entirely ignored. Only when the buffer is parsed for option-setting lines -(i.e. when starting Org mode for a file, when pressing @kbd{C-c C-c} in a +(i.e. when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a settings line, or when exporting), then the contents of this file are parsed as if they had been included in the buffer. In particular, the file can be -any other Org mode file with internal setup. You can visit the file the +any other Org-mode file with internal setup. You can visit the file the cursor is in the line with @kbd{C-c '}. @item #+STARTUP: @cindex #+STARTUP: -This line sets options to be used at startup of Org mode, when an +This line sets options to be used at startup of Org-mode, when an Org file is being visited. The first set of options deals with the initial visibility of the outline @@ -10541,6 +12786,18 @@ variable is @code{org-startup-align-all-tables}, with a default value align @r{align all tables} noalign @r{don't align tables on startup} @end example + +@vindex org-startup-with-inline-images +When visiting a file, inline images can be automatically displayed. The +corresponding variable is @code{org-startup-with-inline-images}, with a +default value @code{nil} to avoid delays when visiting a file. +@cindex @code{inlineimages}, STARTUP keyword +@cindex @code{noinlineimages}, STARTUP keyword +@example +inlineimages @r{show inline images} +noinlineimages @r{don't show inline images on startup} +@end example + @vindex org-log-done @vindex org-log-note-clock-out @vindex org-log-repeat @@ -10561,6 +12818,9 @@ configured using these options (see variables @code{org-log-done}, @cindex @code{logredeadline}, STARTUP keyword @cindex @code{lognoteredeadline}, STARTUP keyword @cindex @code{nologredeadline}, STARTUP keyword +@cindex @code{logrefile}, STARTUP keyword +@cindex @code{lognoterefile}, STARTUP keyword +@cindex @code{nologrefile}, STARTUP keyword @example logdone @r{record a timestamp when an item is marked DONE} lognotedone @r{record timestamp and a note when DONE} @@ -10576,6 +12836,9 @@ nologreschedule @r{do not record when a scheduling date changes} logredeadline @r{record a timestamp when deadline changes} lognoteredeadline @r{record a note when deadline changes} nologredeadline @r{do not record when a deadline date changes} +logrefile @r{record a timestamp when refiling} +lognoterefile @r{record a note when refiling} +nologrefile @r{do not record when refiling} @end example @vindex org-hide-leading-stars @vindex org-odd-levels-only @@ -10648,6 +12911,15 @@ To hide blocks on startup, use these keywords. The corresponding variable is hideblocks @r{Hide all begin/end blocks on startup} nohideblocks @r{Do not hide blocks on startup} @end example +@cindex org-pretty-entities +The display of entities as UTF-8 characters is governed by the variable +@code{org-pretty-entities} and the keywords +@cindex @code{entitiespretty}, STARTUP keyword +@cindex @code{entitiesplain}, STARTUP keyword +@example +entitiespretty @r{Show entities as UTF-8 characters where possible} +entitiesplain @r{Leave entities plain} +@end example @item #+TAGS: TAG1(c1) TAG2(c2) @vindex org-tag-alist These lines (several such lines are allowed) specify the valid tags in @@ -10656,8 +12928,8 @@ 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:, #+DATE:, -@itemx #+OPTIONS:, #+BIND: -@itemx #+DESCRIPTION:, #+KEYWORDS: +@itemx #+OPTIONS:, #+BIND:, #+XSLT:, +@itemx #+DESCRIPTION:, #+KEYWORDS:, @itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:, @itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS: These lines provide settings for exporting files. For more details see @@ -10695,10 +12967,7 @@ works even if the automatic table editor has been turned off. 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. +If the current buffer is a capture buffer, close the note and file it. With a prefix argument, file it, without further interaction, to the default location. @item @@ -10749,25 +13018,30 @@ more text | more text @end example @noindent -If you are using at least Emacs 23.1.50.3 and version 6.29 of Org, this kind -of view can be achieved dynamically at display time using -@code{org-indent-mode}. In this minor mode, all lines are prefixed for -display with the necessary amount of space. Also headlines are prefixed with -additional stars, so that the amount of indentation shifts by -two@footnote{See the variable @code{org-indent-indentation-per-level}.} -spaces per level. All headline stars but the last one are made invisible -using the @code{org-hide} face@footnote{Turning on @code{org-indent-mode} -sets @code{org-hide-leading-stars} to @code{t} and -@code{org-adapt-indentation} to @code{nil}.} - see below under @samp{2.} for -more information on how this works. You can turn on @code{org-indent-mode} -for all files by customizing the variable @code{org-startup-indented}, or you -can turn it on for individual files using + +If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash +with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can +be achieved dynamically at display time using @code{org-indent-mode}. In +this minor mode, all lines are prefixed for display with the necessary amount +of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix} +property, such that @code{visual-line-mode} (or purely setting +@code{word-wrap}) wraps long lines (including headlines) correctly indented. +}. Also headlines are prefixed with additional stars, so that the amount of +indentation shifts by two@footnote{See the variable +@code{org-indent-indentation-per-level}.} spaces per level. All headline +stars but the last one are made invisible using the @code{org-hide} +face@footnote{Turning on @code{org-indent-mode} sets +@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to +@code{nil}.} - see below under @samp{2.} for more information on how this +works. You can turn on @code{org-indent-mode} for all files by customizing +the variable @code{org-startup-indented}, or you can turn it on for +individual files using @example #+STARTUP: indent @end example -If you want a similar effect in earlier version of Emacs and/or Org, or if +If you want a similar effect in an earlier version of Emacs and/or Org, or if you want the indentation to be hard space characters so that the plain text file looks as similar as possible to the Emacs display, Org supports you in the following way: @@ -10859,16 +13133,16 @@ is really only fun with @kbd{S-@key{cursor}} keys, whereas on a tty you would rather use @kbd{C-c .} to re-insert the timestamp. @multitable @columnfractions 0.15 0.2 0.1 0.2 -@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} -@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab -@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} -@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab +@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} +@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab +@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} +@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}} -@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab -@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}} -@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab +@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab +@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}} +@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}} -@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab +@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}} @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab @@ -10924,11 +13198,11 @@ setup. See the installation instructions in the file @item @file{cdlatex.el} by Carsten Dominik @cindex @file{cdlatex.el} @cindex Dominik, Carsten -Org mode can make use of the CDLa@TeX{} package to efficiently enter -La@TeX{} fragments into Org files. See @ref{CDLaTeX mode}. +Org-mode can make use of the CDLa@TeX{} package to efficiently enter +@LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}. @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg @cindex @file{imenu.el} -Imenu allows menu access to an index of items in a file. Org mode +Imenu allows menu access to an index of items in a file. Org-mode supports Imenu---all you need to do to get the index is the following: @lisp (add-hook 'org-mode-hook @@ -10940,13 +13214,12 @@ the option @code{org-imenu-depth}. @item @file{remember.el} by John Wiegley @cindex @file{remember.el} @cindex Wiegley, John -Org cooperates with remember, see @ref{Remember}. -@file{Remember.el} is not part of Emacs, find it on the web. +Org used to use this package for capture, but no longer does. @item @file{speedbar.el} by Eric M. Ludlam @cindex @file{speedbar.el} @cindex Ludlam, Eric M. Speedbar is a package that creates a special frame displaying files and -index items in files. Org mode supports Speedbar and allows you to +index items in files. Org-mode supports Speedbar and allows you to drill into Org files directly from the Speedbar. It also allows you to restrict the scope of agenda commands to a file or a subtree by using the command @kbd{<} in the Speedbar frame. @@ -10957,40 +13230,36 @@ the command @kbd{<} in the Speedbar frame. @cindex @file{table.el} @cindex Ota, Takaaki -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. +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). +Org-mode will recognize these tables and export them properly. Because of +interference with other Org-mode functionality, you unfortunately cannot edit +these tables directly in the buffer. Instead, you need to use the command +@kbd{C-c '} to edit them, similar to source code snippets. @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. +@orgcmd{C-c ',org-edit-special} +Edit a @file{table.el} table. Works when the cursor is in a table.el table. @c -@kindex C-c ~ -@item C-c ~ +@orgcmd{C-c ~,org-table-create-with-table.el} Insert a @file{table.el} table. If there is already a table at point, this command converts it between the @file{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. +@file{table.el} is part of Emacs since Emacs 22. @item @file{footnote.el} by Steven L. Baur @cindex @file{footnote.el} @cindex Baur, Steven L. -Org mode recognizes numerical footnotes as provided by this package. -However, Org mode also has its own footnote support (@pxref{Footnotes}), +Org-mode recognizes numerical footnotes as provided by this package. +However, Org-mode also has its own footnote support (@pxref{Footnotes}), which makes using @file{footnote.el} unnecessary. @end table @node Conflicts, , Cooperation, Interaction -@subsection Packages that lead to conflicts with Org mode +@subsection Packages that lead to conflicts with Org-mode @table @asis @@ -11002,7 +13271,7 @@ This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change timestamps, TODO keywords, priorities, and item bullet types if the cursor is at such a location. By default, @kbd{S-@key{cursor}} commands outside special contexts don't do anything, but you can customize the variable -@code{org-support-shift-select}. Org mode then tries to accommodate shift +@code{org-support-shift-select}. Org-mode then tries to accommodate shift selection by (i) using it outside of the special contexts where special commands apply, and by (ii) extending an existing active region even if the cursor moves across a special context. @@ -11017,7 +13286,7 @@ region. In fact, Emacs 23 has this built-in in the form of @code{shift-selection-mode}, see previous paragraph. If you are using Emacs 23, you probably don't want to use another package for this purpose. However, if you prefer to leave these keys to a different package while working in -Org mode, configure the variable @code{org-replace-disputed-keys}. When set, +Org-mode, configure the variable @code{org-replace-disputed-keys}. When set, Org will move the following key bindings in Org files, and in the agenda buffer (but not during date selection). @@ -11035,7 +13304,7 @@ to have other replacement keys, look at the variable @item @file{yasnippet.el} @cindex @file{yasnippet.el} The way Org-mode binds the TAB key (binding to @code{[tab]} instead of -@code{"\t"}) overrules yasnippets' access to this key. The following code +@code{"\t"}) overrules YASnippet's access to this key. The following code fixed this problem: @lisp @@ -11048,7 +13317,18 @@ fixed this problem: @item @file{windmove.el} by Hovav Shacham @cindex @file{windmove.el} This package also uses the @kbd{S-<cursor>} keys, so everything written -in the paragraph above about CUA mode also applies here. +in the paragraph above about CUA mode also applies here. If you want make +the windmove function active in locations where Org-mode does not have +special functionality on @kbd{S-@key{cursor}}, add this to your +configuration: + +@lisp +;; Make windmove work in org-mode: +(add-hook 'org-shiftup-final-hook 'windmove-up) +(add-hook 'org-shiftleft-final-hook 'windmove-left) +(add-hook 'org-shiftdown-final-hook 'windmove-down) +(add-hook 'org-shiftright-final-hook 'windmove-right) +@end lisp @item @file{viper.el} by Michael Kifer @cindex @file{viper.el} @@ -11077,7 +13357,7 @@ Org. * Add-on packages:: Available extensions * Adding hyperlink types:: New custom link types * Context-sensitive commands:: How to add functionality to such commands -* Tables in arbitrary syntax:: Orgtbl for La@TeX{} and other programs +* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views * Extracting agenda information:: Postprocessing of agenda information @@ -11101,7 +13381,7 @@ maintained by the Worg project and can be found at A large number of add-on packages have been written by various authors. These packages are not part of Emacs, but they are distributed as contributed -packages with the separate release available at the Org mode home page at +packages with the separate release available at the Org-mode home page at @uref{http://orgmode.org}. The list of contributed packages, along with documentation about each package, is maintained by the Worg project at @uref{http://orgmode.org/worg/org-contrib/}. @@ -11206,7 +13486,7 @@ can also set the @code{:description} property to provide a default for the link description when the link is later inserted into an Org buffer with @kbd{C-c C-l}. -When is makes sense for your new link type, you may also define a function +When it makes sense for your new link type, you may also define a function @code{org-PREFIX-complete-link} that implements special (e.g. completion) support for inserting such a link with @kbd{C-c C-l}. Such a function should not accept any arguments, and return the full link with prefix. @@ -11224,8 +13504,10 @@ Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property. Add-ons can tap into this functionality by providing a function that detects special context for that add-on and executes functionality appropriate for the context. Here is an example from Dan Davison's @file{org-R.el} which -allows you to evaluate commands based on the @file{R} programming language. For -this package, special contexts are lines that start with @code{#+R:} or +allows you to evaluate commands based on the @file{R} programming language +@footnote{@file{org-R.el} has been replaced by the org-mode functionality +described in @ref{Working With Source Code} and is now obsolete.}. For this +package, special contexts are lines that start with @code{#+R:} or @code{#+RR:}. @lisp @@ -11255,12 +13537,11 @@ contexts. If the function finds it should do nothing locally, it returns @code{ 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 +specific languages, for example @LaTeX{}. 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 @@ -11268,10 +13549,10 @@ function to @i{translate} the table to the correct syntax, and to the burden of writing conversion functions on the user, but it allows for a very flexible system. -Bastien added the ability to do the same with lists. You can use Org's -facilities to edit and structure lists by turning @code{orgstruct-mode} -on, then locally exporting such lists in another format (HTML, La@TeX{} -or Texinfo.) +Bastien added the ability to do the same with lists, in Orgstruct mode. You +can use Org's facilities to edit and structure lists by turning +@code{orgstruct-mode} on, then locally exporting such lists in another format +(HTML, @LaTeX{} or Texinfo.) @menu @@ -11329,7 +13610,7 @@ additional columns. @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 +compilation of a C file or processing of a @LaTeX{} file. There are a number of different solutions: @itemize @bullet @@ -11340,7 +13621,7 @@ language. For example, in C mode you could wrap the table between @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{}. +in @LaTeX{}. @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 @@ -11350,14 +13631,14 @@ key. @end itemize @node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax -@subsection A La@TeX{} example of radio tables -@cindex La@TeX{}, and Orgtbl mode +@subsection A @LaTeX{} example of radio tables +@cindex @LaTeX{}, and Orgtbl mode -The best way to wrap the source table in La@TeX{} is to use the +The best way to wrap the source table in @LaTeX{} 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 +default this works only for @LaTeX{}, HTML, and Texinfo. Configure the variable @code{orgtbl-radio-tables} to install templates for other modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will be prompted for a table name, let's say we use @samp{salesfigures}. You @@ -11374,13 +13655,13 @@ will then get the following template: @end example @noindent -@vindex La@TeX{}-verbatim-environments +@vindex @LaTeX{}-verbatim-environments 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 +@code{orgtbl-to-latex} to convert the table into @LaTeX{} 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 +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 La@TeX{} mode. As shown in the +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 AUC@TeX{} with the font-latex library, a @@ -11430,7 +13711,7 @@ Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ \end@{comment@} @end example -The La@TeX{} translator function @code{orgtbl-to-latex} is already part of +The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of Orgtbl mode. It uses a @code{tabular} environment to typeset the table and marks horizontal lines with @code{\hline}. Furthermore, it interprets the following parameters (see also @pxref{Translator functions}): @@ -11494,7 +13775,7 @@ 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 +would like to use the @LaTeX{} translator, but wanted the line endings to be @samp{\\[2mm]} instead of the default @samp{\\}, you could just overrule the default with @@ -11503,7 +13784,7 @@ overrule the default with @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 +analogy with the @LaTeX{} 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 @@ -11532,21 +13813,23 @@ containing the formatted table. If you write a generally useful translator, please post it on @email{emacs-orgmode@@gnu.org} so that others can benefit from your work. -@node Radio lists, , Translator functions, Tables in arbitrary syntax +@node Radio lists, , Translator functions, Tables in arbitrary syntax @subsection Radio lists @cindex radio lists @cindex org-list-insert-radio-list -Sending and receiving radio lists works exactly the same way than sending and +Sending and receiving radio lists works exactly the same way as sending and receiving radio tables (@pxref{Radio tables}). As for radio tables, you can -insert radio lists templates in HTML, La@TeX{} and Texinfo modes by calling +insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling @code{org-list-insert-radio-list}. Here are the differences with radio tables: @itemize @minus @item -Use @code{ORGLST} instead of @code{ORGTBL}. +Orgstruct mode must be active. +@item +Use the @code{ORGLST} keyword instead of @code{ORGTBL}. @item The available translation functions for radio lists don't take parameters. @@ -11554,15 +13837,15 @@ parameters. @kbd{C-c C-c} will work when pressed on the first item of the list. @end itemize -Here is a La@TeX{} example. Let's say that you have this in your -La@TeX{} file: +Here is a @LaTeX{} example. Let's say that you have this in your +@LaTeX{} file: -@cindex #+ORGLIST +@cindex #+ORGLST @example % BEGIN RECEIVE ORGLST to-buy % END RECEIVE ORGLST to-buy \begin@{comment@} -#+ORGLIST: SEND to-buy orgtbl-to-latex +#+ORGLST: SEND to-buy org-list-to-latex - a new house - a new computer + a new keyboard @@ -11572,7 +13855,7 @@ La@TeX{} file: @end example Pressing `C-c C-c' on @code{a new house} and will insert the converted -La@TeX{} list between the two marker lines. +@LaTeX{} list between the two marker lines. @node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking @section Dynamic blocks @@ -11583,11 +13866,11 @@ 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 +Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name to the block and can also specify parameters for the function producing the content of the block. -#+BEGIN:dynamic block +@cindex #+BEGIN:dynamic block @example #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... @@ -11597,11 +13880,9 @@ the content of the block. Dynamic blocks are updated with the following commands @table @kbd -@kindex C-c C-x C-u -@item C-c C-x C-u +@orgcmd{C-c C-x C-u,org-dblock-update} Update dynamic block at point. -@kindex C-u C-c C-x C-u -@item C-u C-c C-x C-u +@orgkey{C-u C-c C-x C-u} Update all dynamic blocks in the current file. @end table @@ -11643,10 +13924,11 @@ written in a way such that it does nothing in buffers that are not in @section Special agenda views @cindex agenda views, user-defined -Org provides a special hook that can be used to narrow down the -selection made by any of the agenda views. You may specify a function -that is used at each match to verify if the match should indeed be part -of the agenda view, and if not, how much should be skipped. +Org provides a special hook that can be used to narrow down the selection +made by these agenda views: @code{todo}, @code{alltodo}, @code{tags}, @code{tags-todo}, +@code{tags-tree}. 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 @@ -11707,6 +13989,10 @@ Skip current entry if it has not been scheduled. 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-if 'todo '("TODO" "WAITING")) +Skip current entry if the TODO keyword is TODO or WAITING. +@item '(org-agenda-skip-entry-if 'todo 'done) +Skip current entry if the TODO keyword marks a DONE state. @item '(org-agenda-skip-entry-if 'timestamp) Skip current entry if it has any timestamp, may also be deadline or scheduled. @item '(org-agenda-skip-entry 'regexp "regular expression") @@ -11765,7 +14051,7 @@ 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-span month \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ | lpr @@ -11843,7 +14129,7 @@ properties. 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 +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 @@ -11900,6 +14186,15 @@ Treat the value of the property PROPERTY as a whitespace-separated list of values and check if VALUE is in this list. @end defun +@defopt org-property-allowed-value-functions +Hook for functions supplying allowed values for a specific property. +The functions must take a single argument, the name of the property, and +return a flat list of allowed values. If @samp{:ETC} is one of +the values, use the values as completion help, but allow also other values +to be entered. The functions must return @code{nil} if they are not +responsible for this property. +@end defopt + @node Using the mapping API, , Using the property API, Hacking @section Using the mapping API @cindex API, for mapping @@ -11971,12 +14266,12 @@ information about the entry, or in order to change metadata in the entry. Here are a couple of functions that might be handy: @defun org-todo &optional arg -Change the TODO state of the entry, see the docstring of the functions for +Change the TODO state of the entry. See the docstring of the functions for the many possible values for the argument ARG. @end defun @defun org-priority &optional action -Change the priority of the entry, see the docstring of this function for the +Change the priority of the entry. See the docstring of this function for the possible values for ACTION. @end defun @@ -12015,11 +14310,13 @@ The following example counts the number of entries with TODO keyword @cindex iPhone @cindex MobileOrg -@i{MobileOrg} is an application for the @i{iPhone/iPod Touch} series of -devices, developed by Richard Moreland. @i{MobileOrg} offers offline viewing -and capture support for an Org-mode system rooted on a ``real'' computer. It -does also allow you to record changes to existing entries. For information -about @i{MobileOrg}, see @uref{http://mobileorg.ncogni.to/}). +@uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the +@i{iPhone/iPod Touch} series of devices, developed by Richard Moreland. +@i{MobileOrg} offers offline viewing and capture support for an Org-mode +system rooted on a ``real'' computer. It does also allow you to record +changes to existing entries. Android users should check out +@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} +by Matt Jones. This appendix describes the support Org has for creating agenda views in a format that can be displayed by @i{MobileOrg}, and for integrating notes @@ -12027,9 +14324,9 @@ captured and changes made by @i{MobileOrg} into the main system. For changing tags and TODO states in MobileOrg, you should have set up the customization variables @code{org-todo-keywords} and @code{org-tags-alist} to -cover all important tags and todo keywords, even if individual files use only +cover all important tags and TODO keywords, even if individual files use only part of these. MobileOrg will also offer you states and tags set up with -in-buffer settings, but it will understand the logistics of todo state +in-buffer settings, but it will understand the logistics of TODO state @i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags (@pxref{Setting tags}) only for those set in these variables. @@ -12042,34 +14339,33 @@ in-buffer settings, but it will understand the logistics of todo state @node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg @section Setting up the staging area -Org-mode has commands to prepare a directory with files for @i{MobileOrg}, -and to read captured notes from there. If Emacs can directly write to the -WebDAV directory accessed by @i{MobileOrg}, just point to this directory -using the variable @code{org-mobile-directory}. Using the @file{tramp} -method, @code{org-mobile-directory} may point to a remote directory -accessible through, for example, -@file{ssh/scp}: +MobileOrg needs to interact with Emacs through a directory on a server. If you +are using a public server, you should consider to encrypt the files that are +uploaded to the server. This can be done with Org-mode 7.02 and with +@i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl} +installation on your system. To turn on encryption, set a password in +@i{MobileOrg} and, on the Emacs side, configure the variable +@code{org-mobile-use-encryption}@footnote{If you can safely store the +password in your Emacs setup, you might also want to configure +@code{org-mobile-encryption-password}. Please read the docstring of that +variable. Note that encryption will apply only to the contents of the +@file{.org} files. The file names themselves will remain visible.}. + +The easiest way to create that directory is to use a free +@uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use +Dropbox, or if your version of MobileOrg does not support it, you can use a +webdav server. For more information, check out the documentation of MobileOrg and also this +@uref{http://orgmode.org/worg/org-faq.php#mobileorg_webdav, FAQ entry}.}. +When MobileOrg first connects to your Dropbox, it will create a directory +@i{MobileOrg} inside the Dropbox. After the directory has been created, tell +Emacs about it: -@smallexample -(setq org-mobile-directory "/scpc:user@@remote.host:org/webdav/") -@end smallexample +@lisp +(setq org-mobile-directory "~/Dropbox/MobileOrg") +@end lisp -If Emacs cannot access the WebDAV directory directly using a @file{tramp} -method, or you prefer to maintain a local copy, you can use a local directory -for staging. Other means must then be used to keep this directory in sync -with the WebDAV directory. In the following example, files are staged in -@file{~/stage}, and Org-mode hooks take care of moving files to and from the -WebDAV directory using @file{scp}. - -@smallexample -(setq org-mobile-directory "~/stage/") -(add-hook 'org-mobile-post-push-hook - (lambda () (shell-command "scp -r ~/stage/* user@@wdhost:mobile/"))) -(add-hook 'org-mobile-pre-pull-hook - (lambda () (shell-command "scp user@@wdhost:mobile/mobileorg.org ~/stage/ "))) -(add-hook 'org-mobile-post-pull-hook - (lambda () (shell-command "scp ~/stage/mobileorg.org user@@wdhost:mobile/"))) -@end smallexample +Org-mode has commands to put files for @i{MobileOrg} into that directory, +and to read captured notes from there. @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg @section Pushing to MobileOrg @@ -12078,29 +14374,29 @@ This operation copies all files currently listed in @code{org-mobile-files} to the directory @code{org-mobile-directory}. By default this list contains all agenda files (as listed in @code{org-agenda-files}), but additional files can be included by customizing @code{org-mobiles-files}. File names will be -staged with path relative to @code{org-directory}, so all files should be -inside this directory. The push operation also creates (in the same -directory) a special Org file @file{agendas.org}. This file is an Org-mode -style outline, containing every custom agenda view defined by the user. -While creating the agendas, Org-mode will force@footnote{See the variable -@code{org-mobile-force-id-on-agenda-items}.} an ID property on all entries -referenced by the agendas, so that these entries can be uniquely identified -if @i{MobileOrg} flags them for further action. Finally, Org writes the file -@file{index.org}, containing links to all other files. If @i{MobileOrg} is -configured to request this file from the WebDAV server, all agendas and Org -files will be downloaded to the device. To speed up the download, MobileOrg -will only read files whose checksums@footnote{stored automatically in the -file @file{checksums.dat}} have changed. +staged with paths relative to @code{org-directory}, so all files should be +inside this directory. The push operation also creates a special Org file +@file{agendas.org} with all custom agenda view defined by the +user@footnote{While creating the agendas, Org-mode will force ID properties +on all referenced entries, so that these entries can be uniquely identified +if @i{MobileOrg} flags them for further action. If you do not want to get +these properties in so many entries, you can set the variable +@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then +rely on outline paths, in the hope that these will be unique enough.}. +Finally, Org writes the file @file{index.org}, containing links to all other +files. @i{MobileOrg} first reads this file from the server, and then +downloads all agendas and Org files listed in it. To speed up the download, +MobileOrg will only read files whose checksums@footnote{stored automatically +in the file @file{checksums.dat}} have changed. @node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg @section Pulling from MobileOrg -When @i{MobileOrg} synchronizes with the WebDAV server, it not only pulls the -Org files for viewing. It also appends captured entries and pointers to -flagged and changed entries to the file @file{mobileorg.org} on the server. -Org has a @emph{pull} operation that integrates this information into an -inbox file and operates on the pointers to flagged entries. Here is how it -works: +When @i{MobileOrg} synchronizes with the server, it not only pulls the Org +files for viewing. It also appends captured entries and pointers to flagged +and changed entries to the file @file{mobileorg.org} on the server. Org has +a @emph{pull} operation that integrates this information into an inbox file +and operates on the pointers to flagged entries. Here is how it works: @enumerate @item @@ -12132,47 +14428,41 @@ another window and also push it onto the kill ring. So you could use @kbd{? z C-y C-c C-c} to store that flagging note as a normal note in the entry. Pressing @kbd{?} twice in succession will offer to remove the @code{:FLAGGED:} tag along with the recorded flagging note (which is stored -in a property). In this way you indicate, that the intended processing for +in a property). In this way you indicate that the intended processing for this flagged entry is finished. @end table @end enumerate @kindex C-c a ? If you are not able to process all flagged entries directly, you can always -return to this agenda view using @kbd{C-c a ?}. Note, however, that there is -a subtle difference. The view created automatically by @kbd{M-x -org-mobile-pull RET} is guaranteed to search all files that have been -addressed by the last pull. This might include a file that is not currently -in your list of agenda files. If you later use @kbd{C-c a ?} to regenerate -the view, only the current agenda files will be searched. +return to this agenda view@footnote{Note, however, that there is a subtle +difference. The view created automatically by @kbd{M-x org-mobile-pull +@key{RET}} is guaranteed to search all files that have been addressed by the +last pull. This might include a file that is not currently in your list of +agenda files. If you later use @kbd{C-c a ?} to regenerate the view, only +the current agenda files will be searched.} using @kbd{C-c a ?}. @node History and Acknowledgments, Main Index, MobileOrg, Top -@appendix History and Acknowledgments -@cindex acknowledgements +@appendix History and acknowledgments +@cindex acknowledgments @cindex history @cindex thanks -Org was born in 2003, out of frustration over the user interface -of the Emacs Outline mode. I was trying to organize my notes and -projects, and using Emacs seemed to be the natural way to go. However, -having to remember eleven different commands with two or three keys per -command, only to hide and show parts of the outline tree, that seemed -entirely unacceptable to me. Also, when using outlines to take notes, I -constantly wanted 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{timestamps}, and @emph{table support}. These areas highlighted the two main -goals that Org still has today: to be a new, outline-based, -plain text mode with innovative and intuitive editing features, and to -incorporate project planning functionality directly into a notes file. - -A special thanks goes to @i{Bastien Guerry} who has not only written a large -number of extensions to Org (most of them integrated into the core by now), -but who has also helped in the development and maintenance of Org so much that he -should be considered the main co-contributor to this package. +Org was born in 2003, out of frustration over the user interface of the Emacs +Outline mode. I was trying to organize my notes and projects, and using +Emacs seemed to be the natural way to go. However, having to remember eleven +different commands with two or three keys per command, only to hide and show +parts of the outline tree, that seemed entirely unacceptable to me. Also, +when using outlines to take notes, I constantly wanted 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{timestamps}, and +@emph{table support}. These areas highlighted the two main goals that Org +still has today: to be 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 to @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug @@ -12183,6 +14473,38 @@ in shaping one or more aspects of Org. The list may not be complete, if I have forgotten someone, please accept my apologies and let me know. +Before I get to this list, a few special mentions are in order: + +@table @i +@item Bastien Guerry +Bastien has written a large number of extensions to Org (most of them +integrated into the core by now), including the LaTeX exporter and the plain +list parser. His support during the early days, when he basically acted as +co-maintainer, was central to the success of this project. Bastien also +invented Worg, helped establishing the Web presence of Org, and sponsors +hosting costs for the orgmode.org website. +@item Eric Schulte and Dan Davison +Eric and Dan are jointly responsible for the Org-babel system, which turns +Org into a multi-language environment for evaluating code and doing literate +programming and reproducible research. +@item John Wiegley +John has contributed a number of great ideas and patches directly to Org, +including the attachment system (@file{org-attach.el}), integration with +Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO +items, habit tracking (@file{org-habits.el}), and encryption +(@file{org-crypt.el}). Also, the capture system is really an extended copy +of his great @file{remember.el}. +@item Sebastian Rose +Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work +of an ignorant amateur. Sebastian has pushed this part of Org onto a much +higher level. He also wrote @file{org-info.js}, a Java script for displaying +webpages derived from Org using an Info-like or a folding interface with +single-key navigation. +@end table + +@noindent OK, now to the full list of contributions! Again, please let me +know what I am missing here! + @itemize @bullet @item @@ -12195,12 +14517,14 @@ Org-mode website. @item @i{Alex Bochannek} provided a patch for rounding timestamps. @item +@i{Jan Böcker} wrote @file{org-docview.el}. +@item @i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files. @item @i{Tom Breton} wrote @file{org-choose.el}. @item @i{Charles Cave}'s suggestion sparked the implementation of templates -for Remember. +for Remember, which are now templates for capture. @item @i{Pavel Chalmoviansky} influenced the agenda treatment of items with specified time. @@ -12213,8 +14537,6 @@ calculations and improved XEmacs compatibility, in particular by porting @item @i{Baoqiu Cui} contributed the DocBook exporter. @item -@i{Dan Davison} wrote (together with @i{Eric Schulte}) Org Babel. -@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. @@ -12225,8 +14547,12 @@ them. 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. +@i{Thomas S. Dye} contributed documentation on Worg and helped integrating +the Org-Babel documentation into the manual. +@item +@i{Christian Egli} converted the documentation into Texinfo format, inspired +the agenda, patched CSS formatting into the HTML exporter, and wrote +@file{org-taskjuggler.el}. @item @i{David Emery} provided a patch for custom CSS support in exported HTML agendas. @@ -12244,13 +14570,21 @@ around a match in a hidden outline tree. @item @i{Austin Frank} works as a mailing list moderator. @item +@i{Eric Fraga} drove the development of BEAMER export with ideas and +testing. +@item +@i{Barry Gidden} did proofreading the manual in preparation for the book +publication through Network Theory Ltd. +@item @i{Niels Giesen} had the idea to automatically archive DONE trees. @item -@i{Bastien Guerry} wrote the La@TeX{} exporter and @file{org-bibtex.el}, and -has been prolific with patches, ideas, and bug reports. +@i{Nicolas Goaziou} rewrote much of the plain list code. @item @i{Kai Grossjohann} pointed out key-binding conflicts with other packages. @item +@i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a +book. +@item @i{Bernt Hansen} has driven much of the support for auto-repeating tasks, task state change logging, and the clocktable. His clear explanations have been critical when we started to adopt the Git version control system. @@ -12263,14 +14597,20 @@ patches. @i{Scott Jaderholm} proposed footnotes, control over whitespace between folded entries, and column view for properties. @item +@i{Matt Jones} wrote @i{MobileOrg Android}. +@item @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}. @item -@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also +@i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also provided frequent feedback and some patches. @item @i{Matt Lundin} has proposed last-row references for table formulas and named invisible anchors. He has also worked a lot on the FAQ. @item +@i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org, +and is a prolific contributor on the mailing list with competent replies, +small fixes and patches. +@item @i{Jason F. McBrayer} suggested agenda export to CSV format. @item @i{Max Mikhanosha} came up with the idea of refiling. @@ -12293,6 +14633,9 @@ and being able to quickly restrict the agenda to a subtree. @i{Tim O'Callaghan} suggested in-file links, search options for general file links, and TAGS. @item +@i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text +version of the reference card. +@item @i{Takeshi Okano} translated the manual and David O'Toole's tutorial into Japanese. @item @@ -12317,10 +14660,6 @@ also acted as mailing list moderator for some time. @item @i{Kevin Rogers} contributed code to access VM files on remote hosts. @item -@i{Sebastian Rose} wrote @file{org-info.js}, a Java script for displaying -webpages derived from Org using an Info-like or a folding interface with -single-key navigation. -@item @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a conflict with @file{allout.el}. @item @@ -12333,8 +14672,7 @@ of feedback, developed and applied standards to the Org documentation. @i{Christian Schlauer} proposed angular brackets around links, among other things. @item -@i{Eric Schulte} wrote @file{org-plot.el} and (together with @i{Dan Davison}) -Org Babel, and contributed various patches, small features and modules. +@i{Paul Sexton} wrote @file{org-ctags.el}. @item Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s @file{organizer-mode.el}. @@ -12356,31 +14694,33 @@ tweaks and features. @i{Adam Spiers} asked for global linking commands, inspired the link extension system, added support for mairix, and proposed the mapping API. @item +@i{Ulf Stegemann} created the table to translate special symbols to HTML, +LaTeX, UTF-8, Latin-1 and ASCII. +@item @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content with links transformation to Org syntax. @item @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual chapter about publishing. @item +@i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and +enabled source code highlighling in Gnus. +@item +@i{Stefan Vollmar} organized a video-recorded talk at the +Max-Planck-Institute for Neurology. He also inspired the creation of a +concept index for HTML export. +@item @i{J@"urgen Vollmer} contributed code generating the table of contents in HTML output. @item +@i{Samuel Wales} has provided important feedback and bug reports. +@item @i{Chris Wallace} provided a patch implementing the @samp{QUOTE} keyword. @item @i{David Wainberg} suggested archiving, and improvements to the linking system. @item -@i{John Wiegley} wrote @file{emacs-wiki.el}, @file{planner.el}, and -@file{muse.el}, which have some overlap with Org. Initially the development -of Org was fully independent because I was not aware of the existence of -these packages. But with time I have occasionally looked at John's code and -learned a lot from it. John has also contributed a number of great ideas and -patches directly to Org, including the attachment system -(@file{org-attach.el}), integration with Apple Mail -(@file{org-mac-message.el}), hierarchical dependencies of TODO items, habit -tracking (@file{org-habits.el}) and support for pcomplete. -@item @i{Carsten Wimmer} suggested some changes and helped fix a bug in linking to Gnus. @item @@ -12393,17 +14733,22 @@ and contributed various ideas and code snippets. @node Main Index, Key Index, History and Acknowledgments, Top -@unnumbered Concept Index +@unnumbered Concept index @printindex cp -@node Key Index, Variable Index, Main Index, Top -@unnumbered Key Index +@node Key Index, Command and Function Index, Main Index, Top +@unnumbered Key index @printindex ky -@node Variable Index, , Key Index, Top -@unnumbered Variable Index +@node Command and Function Index, Variable Index, Key Index, Top +@unnumbered Command and function index + +@printindex fn + +@node Variable Index, , Command and Function Index, Top +@unnumbered Variable index This is not a complete index of variables and faces, only the ones that are mentioned in the manual. For a more complete list, use @kbd{M-x @@ -12413,14 +14758,11 @@ org-customize @key{RET}} and then click yourself through the tree. @bye -@ignore - arch-tag: 7893d1Fe-cc57-4d13-b5e5-f494a1CBC7ac -@end ignore - @c Local variables: -@c ispell-local-dictionary: "en_US-w_accents" -@c ispell-local-pdict: "./.aspell.org.pws" @c fill-column: 77 +@c indent-tabs-mode: nil +@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" +@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" @c End: diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index e466a3bec8..f12942da2d 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -6,8 +6,7 @@ @c %**end of header @copying -Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 1991-2011 Free Software Foundation, Inc. @quotation @@ -1432,7 +1431,3 @@ this manual. @printindex ky @bye - -@ignore - arch-tag: 5c7178ce-56fa-40b0-abd7-f4a09758b235 -@end ignore diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index daef19a01b..9cb7a637a0 100644 --- a/doc/misc/pgg.texi +++ b/doc/misc/pgg.texi @@ -1,4 +1,7 @@ \input texinfo @c -*-texinfo-*- + +@include gnus-overrides.texi + @setfilename ../../info/pgg @settitle PGG @value{VERSION} @@ -8,8 +11,7 @@ This file describes PGG @value{VERSION}, an Emacs interface to various PGP implementations. -Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2001, 2003-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -31,7 +33,12 @@ developing GNU and promoting software freedom.'' @end direntry @titlepage +@ifset WEBHACKDEVEL +@title PGG (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title PGG +@end ifclear @author by Daiki Ueno @page @@ -497,7 +504,3 @@ If non-@code{nil}, don't check the checksum of the packets. @bye @c End: - -@ignore - arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85 -@end ignore diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index c8c341534f..c2b6867c41 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -5,7 +5,7 @@ @c %**end of header @copying -Copyright @copyright{} 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2006-2011 Free Software Foundation, Inc. @quotation @@ -948,7 +948,3 @@ The real answer, therefore, is a @code{/reconnect} command: @printindex cp @bye - -@ignore - arch-tag: 2589e562-3843-4ffc-8c2f-477cbad57c01 -@end ignore diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index c5cb511c06..3944b71233 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -27,8 +27,7 @@ citations and indices for LaTeX documents with Emacs. This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for @b{Ref@TeX{}} @value{VERSION} -Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1997-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -80,6 +79,7 @@ developing GNU and promoting software freedom.'' @ifnottex @node Top,,,(dir) +@top RefTeX @b{Ref@TeX{}} is a package for managing Labels, References, Citations and index entries with GNU Emacs. @@ -5890,7 +5890,3 @@ released on 7 Jan 1997. @printindex cp @bye - -@ignore - arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43 -@end ignore diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi index bdaf4750d9..e67d6155bb 100644 --- a/doc/misc/remember.texi +++ b/doc/misc/remember.texi @@ -8,7 +8,7 @@ @copying This manual is for Remember Mode, version 1.9 -Copyright @copyright{} 2001, 2004, 2005, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2001, 2004-2005, 2007-2011 Free Software Foundation, Inc. @quotation @@ -403,7 +403,3 @@ consult @ref{Remember, , , org}. @printindex cp @bye - -@ignore - arch-tag: 5b980db0-20cc-4167-b845-52dc11d53b9f -@end ignore diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi index a75f2d80f6..a75b237519 100644 --- a/doc/misc/sasl.texi +++ b/doc/misc/sasl.texi @@ -1,4 +1,7 @@ \input texinfo @c -*-texinfo-*- + +@include gnus-overrides.texi + @setfilename ../../info/sasl @set VERSION 0.2 @@ -7,7 +10,7 @@ @copying This file describes the Emacs SASL library, version @value{VERSION}. -Copyright @copyright{} 2000, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2000, 2004-2011 Free Software Foundation, Inc. @quotation @@ -37,7 +40,12 @@ license to the document, as described in section 6 of the license. @titlepage +@ifset WEBHACKDEVEL +@title Emacs SASL Library @value{VERSION} (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title Emacs SASL Library @value{VERSION} +@end ifclear @author by Daiki Ueno @page @@ -267,7 +275,3 @@ At the first time @var{step} should be set to @code{nil}. @bye @c End: - -@ignore - arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875 -@end ignore diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index d4f45fb6b9..8853192af0 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi @@ -14,8 +14,7 @@ This document describes Supercite, an Emacs package for citing and attributing replies to mail and news messages. -Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -54,6 +53,7 @@ developing GNU and promoting software freedom.'' @ifnottex @node Top, Introduction, (dir), (dir) +@top Supercite @comment node-name, next, previous, up @insertcopying @@ -1939,7 +1939,3 @@ its @var{variable} name. @end iftex @printindex vr @bye - -@ignore - arch-tag: 0521847a-4680-44b6-ae6e-13ce20e18436 -@end ignore diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index f986c0fd45..b17f1ab7e9 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -1,7 +1,6 @@ @c This file is included by semantic.texi -@c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007, 2009, -@c 2010, 2011 Free Software Foundation, Inc. +@c Copyright (C) 1999-2005, 2007, 2009-2011 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this @c document under the terms of the GNU Free Documentation License, @@ -1330,7 +1329,3 @@ To add other kind of decorations on a tag, @code{NAME-highlight} must use @dfn{semantic-decorate-tag}, and other functions of the semantic decoration @var{api} found in this library. @end defun - -@ignore - arch-tag: 760dca58-7119-484e-8237-866cbaf36f79 -@end ignore diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi index 97f9bc21e8..f3f11d29f1 100644 --- a/doc/misc/semantic.texi +++ b/doc/misc/semantic.texi @@ -24,8 +24,7 @@ @copying This manual documents the Semantic library and utilities. -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007, -2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2005, 2007, 2009-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -622,7 +621,3 @@ Emacs Lisp. It is an LALR parser suitable for complex languages. @c LocalWords: subsubsection sw sym texi texinfo titlefont titlepage @c LocalWords: tok TOKEN's toplevel typemodifiers uml unset untar @c LocalWords: uref usedb var vskip xref yak - -@ignore - arch-tag: cbc6e78c-4ff1-410e-9fc7-936487e39bbf -@end ignore diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index 6a1cbe6203..d9739b9392 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -11,8 +11,7 @@ @copying This file documents SES: the Simple Emacs Spreadsheet. -Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2002-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -982,7 +981,3 @@ Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr} @include doclicense.texi @bye - -@ignore - arch-tag: 10a4ee1c-7ef4-4c06-8b7a-f975e39f0dec -@end ignore diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi index 139d0fa77d..64fd92f40c 100644 --- a/doc/misc/sieve.texi +++ b/doc/misc/sieve.texi @@ -1,4 +1,7 @@ \input texinfo @c -*-texinfo-*- + +@include gnus-overrides.texi + @setfilename ../../info/sieve @settitle Emacs Sieve Manual @synindex fn cp @@ -8,8 +11,7 @@ @copying This file documents the Emacs Sieve package, for server-side mail filtering. -Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, -2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -35,7 +37,12 @@ developing GNU and promoting software freedom.'' @setchapternewpage odd @titlepage +@ifset WEBHACKDEVEL +@title Emacs Sieve Manual (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title Emacs Sieve Manual +@end ifclear @author by Simon Josefsson @page @@ -264,10 +271,6 @@ 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}. @@ -356,7 +359,3 @@ A Protocol for Remotely Managing Sieve Scripts @bye @c End: - -@ignore - arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3 -@end ignore diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index 40dcf6bc92..1d4bbbff4a 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -3,7 +3,7 @@ @settitle Emacs SMTP Library @syncodeindex vr fn @copying -Copyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +Copyright @copyright{} 2003-2011 Free Software Foundation, Inc. @quotation @@ -415,7 +415,3 @@ cannot accept mail. @printindex fn @bye - -@ignore - arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f -@end ignore diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 3e0373d044..9dc47e4574 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -4,8 +4,7 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -41,6 +40,7 @@ developing GNU and promoting software freedom.'' @node Top, , , (dir)Top @comment node-name, next, previous, up +@top Speedbar Speedbar is a program for Emacs which can be used to summarize information related to the current buffer. Its original inspiration @@ -1253,7 +1253,3 @@ Two good values are @code{nil} and @code{statictag}. @bye @c LocalWords: speedbar's xref slowbar kbd subsubsection @c LocalWords: keybindings - -@ignore - arch-tag: e1fc85f0-1eeb-489f-a8d4-a2bfe711fa02 -@end ignore diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 91408263bc..fd22fd6856 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,11 +3,11 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2009-08-14.15} +\def\texinfoversion{2011-05-23.16} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -% 2007, 2008, 2009 Free Software Foundation, Inc. +% 2007, 2008, 2009, 2010, 2011 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 @@ -65,7 +65,6 @@ \everyjob{\message{[Texinfo version \texinfoversion]}% \catcode`+=\active \catcode`\_=\active} - \chardef\other=12 % We never want plain's \outer definition of \+ in Texinfo. @@ -93,14 +92,13 @@ \let\ptexnewwrite\newwrite \let\ptexnoindent=\noindent \let\ptexplus=+ +\let\ptexraggedright=\raggedright \let\ptexrbrace=\} \let\ptexslash=\/ \let\ptexstar=\* \let\ptext=\t \let\ptextop=\top -{\catcode`\'=\active -\global\let\ptexquoteright'}% Math-mode def from plain.tex. -\let\ptexraggedright=\raggedright +{\catcode`\'=\active \global\let\ptexquoteright'}% active in plain's math mode % If this character appears in an error message or help string, it % starts a new line in the output. @@ -120,8 +118,8 @@ \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\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 @@ -160,15 +158,18 @@ \def\spaceisspace{\catcode`\ =\spacecat} % sometimes characters are active, so we need control sequences. +\chardef\ampChar = `\& \chardef\colonChar = `\: \chardef\commaChar = `\, \chardef\dashChar = `\- \chardef\dotChar = `\. \chardef\exclamChar= `\! +\chardef\hashChar = `\# \chardef\lquoteChar= `\` \chardef\questChar = `\? \chardef\rquoteChar= `\' \chardef\semiChar = `\; +\chardef\slashChar = `\/ \chardef\underChar = `\_ % Ignore a token. @@ -199,36 +200,7 @@ % 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 - }% - }% -} +\def\finalout{\overfullrule=0pt } % Sometimes it is convenient to have everything in the transcript file % and nothing on the terminal. We don't just call \tracingall here, @@ -246,7 +218,7 @@ \tracingmacros2 \tracingrestores1 \showboxbreadth\maxdimen \showboxdepth\maxdimen - \ifx\eTeXversion\undefined\else % etex gives us more logging + \ifx\eTeXversion\thisisundefined\else % etex gives us more logging \tracingscantokens1 \tracingifs1 \tracinggroups1 @@ -267,7 +239,6 @@ \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 @@ -577,7 +548,7 @@ } \def\inenvironment#1{% \ifx#1\empty - out of any environment% + outside of any environment% \else in environment \expandafter\string#1% \fi @@ -589,7 +560,7 @@ \parseargdef\end{% \if 1\csname iscond.#1\endcsname \else - % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03 + % The general wording of \badenverr may not be ideal. \expandafter\checkenv\csname#1\endcsname \csname E#1\endcsname \endgroup @@ -599,85 +570,6 @@ \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 \ifmmode\imath \else\ptexi \fi - \else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi - \else \errmessage{@dotless can be used only with i or j}% - \fi\fi -} - -% The \TeX{} logo, as in plain, but resetting the spacing so that a -% period following counts as ending a sentence. (Idea found in latex.) -% -\edef\TeX{\TeX \spacefactor=1000 } - -% @LaTeX{} logo. Not quite the same results as the definition in -% latex.ltx, since we use a different font for the raised A; it's most -% convenient for us to use an explicitly smaller font, rather than using -% the \scriptstyle font (since we don't reset \scriptstyle and -% \scriptscriptstyle). -% -\def\LaTeX{% - L\kern-.36em - {\setbox0=\hbox{T}% - \vbox to \ht0{\hbox{\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 @@ -719,7 +611,7 @@ \else\ifx\temp\offword \plainnonfrenchspacing \else \errhelp = \EMsimple - \errmessage{Unknown @frenchspacing option `\temp', must be on/off}% + \errmessage{Unknown @frenchspacing option `\temp', must be on|off}% \fi\fi } @@ -801,15 +693,6 @@ where each line of input produces a line of output.} \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. @@ -873,7 +756,7 @@ where each line of input produces a line of output.} % @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'. +% class. WHICH is `l' or `r'. Not documented, written for gawk manual. % \newskip\inmarginspacing \inmarginspacing=1cm \def\strutdepth{\dp\strutbox} @@ -920,6 +803,36 @@ where each line of input produces a line of output.} \temp } +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). This command +% is not documented, not supported, and doesn't work. +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + % @include FILE -- \input text of FILE. % \def\include{\parseargusing\filenamecatcodes\includezzz} @@ -930,6 +843,7 @@ where each line of input produces a line of output.} \makevalueexpandable % we want to expand any @value in FILE. \turnoffactive % and allow special characters in the expansion \indexnofonts % Allow `@@' and other weird things in file names. + \wlog{texinfo.tex: doing @include of #1^^J}% \edef\temp{\noexpand\input #1 }% % % This trickery is to read FILE outside of a group, in case it makes @@ -1095,109 +1009,6 @@ where each line of input produces a line of output.} } -% @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 - % make the texinfo accent commands work in math mode - \let\"=\ddot - \let\'=\acute - \let\==\bar - \let\^=\hat - \let\`=\grave - \let\u=\breve - \let\v=\check - \let\~=\tilde - \let\dotaccent=\dot - $\finishmath -} -\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. - -% Some active characters (such as <) are spaced differently in math. -% We have to reset their definitions in case the @math was an argument -% to a command which sets the catcodes (such as @item or @section). -% -{ - \catcode`^ = \active - \catcode`< = \active - \catcode`> = \active - \catcode`+ = \active - \catcode`' = \active - \gdef\mathactive{% - \let^ = \ptexhat - \let< = \ptexless - \let> = \ptexgtr - \let+ = \ptexplus - \let' = \ptexquoteright - } -} - -% Some math mode symbols. -\def\bullet{$\ptexbullet$} -\def\geq{\ifmmode \ge\else $\ge$\fi} -\def\leq{\ifmmode \le\else $\le$\fi} -\def\minus{\ifmmode -\else $-$\fi} - -% @dots{} outputs an ellipsis using the current font. -% We do .5em per period so that it has the same spacing in the cm -% typewriter fonts as three actual period characters; on the other hand, -% in other typewriter fonts three periods are wider than 1.5em. So do -% whichever is larger. -% -\def\dots{% - \leavevmode - \setbox0=\hbox{...}% get width of three periods - \ifdim\wd0 > 1.5em - \dimen0 = \wd0 - \else - \dimen0 = 1.5em - \fi - \hbox to \dimen0{% - \hskip 0pt plus.25fil - .\hskip 0pt plus1fil - .\hskip 0pt plus1fil - .\hskip 0pt plus.5fil - }% -} - -% @enddots{} is an end-of-sentence ellipsis. -% -\def\enddots{% - \dots - \spacefactor=\endofsentencespacefactor -} - -% @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 @@ -1262,9 +1073,8 @@ where each line of input produces a line of output.} \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 +% can be set). So we test for \relax and 0 as well as being undefined. +\ifx\pdfoutput\thisisundefined \else \ifx\pdfoutput\relax \else @@ -1492,6 +1302,7 @@ output) for that.)} \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace % % Read toc silently, to get counts of subentries for \pdfoutline. + \def\partentry##1##2##3##4{}% ignore parts in the outlines \def\numchapentry##1##2##3##4{% \def\thischapnum{##2}% \def\thissecnum{0}% @@ -1695,7 +1506,7 @@ output) for that.)} % if we are producing pdf, and we have \pdffontattr, then define cmaps. % (\pdffontattr was introduced many years ago, but people still run % older pdftex's; it's easy to conditionalize, so we do.) -\ifpdf \ifx\pdffontattr\undefined \else +\ifpdf \ifx\pdffontattr\thisisundefined \else \begingroup \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap @@ -1962,7 +1773,7 @@ end % 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 +\ifx\fontprefix\thisisundefined \def\fontprefix{cm} \fi % Support font families that don't use the same naming scheme as CM. @@ -2105,8 +1916,8 @@ end \font\reducedsy=cmsy10 \def\reducedecsize{1000} -% reset the current fonts -\textfonts +\textleading = 13.2pt % line spacing for 11pt CM +\textfonts % reset the current fonts \rm } % end of 11pt text font size definitions @@ -2236,11 +2047,9 @@ end \font\reducedsy=cmsy9 \def\reducedecsize{0900} -% reduce space between paragraphs -\divide\parskip by 2 - -% reset the current fonts -\textfonts +\divide\parskip by 2 % reduce space between paragraphs +\textleading = 12pt % line spacing for 10pt CM +\textfonts % reset the current fonts \rm } % end of 10pt text font size definitions @@ -2249,12 +2058,13 @@ end % @fonttextsize 10 % (or 11) to redefine the text font size. pt is assumed. % -\def\xword{10} \def\xiword{11} +\def\xword{10} +\def\xwordpt{10pt} % \parseargdef\fonttextsize{% \def\textsizearg{#1}% - \wlog{doing @fonttextsize \textsizearg}% + %\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. @@ -2308,7 +2118,7 @@ end \let\tenttsl=\titlettsl \def\curfontsize{title}% \def\lsize{chap}\def\lllsize{subsec}% - \resetmathfonts \setleading{25pt}} + \resetmathfonts \setleading{27pt}} \def\titlefont#1{{\titlefonts\rmisbold #1}} \def\chapfonts{% \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl @@ -2436,12 +2246,14 @@ end % Markup style setup for left and right quotes. \defmarkupstylesetup\markupsetuplq{% - \expandafter\let\expandafter \temp \csname markupsetuplq\currentmarkupstyle\endcsname + \expandafter\let\expandafter \temp + \csname markupsetuplq\currentmarkupstyle\endcsname \ifx\temp\relax \markupsetuplqdefault \else \temp \fi } \defmarkupstylesetup\markupsetuprq{% - \expandafter\let\expandafter \temp \csname markupsetuprq\currentmarkupstyle\endcsname + \expandafter\let\expandafter \temp + \csname markupsetuprq\currentmarkupstyle\endcsname \ifx\temp\relax \markupsetuprqdefault \else \temp \fi } @@ -2460,22 +2272,26 @@ end \let\markupsetuplqcode \markupsetcodequoteleft \let\markupsetuprqcode \markupsetcodequoteright +% \let\markupsetuplqexample \markupsetcodequoteleft \let\markupsetuprqexample \markupsetcodequoteright +% +\let\markupsetuplqsamp \markupsetcodequoteleft +\let\markupsetuprqsamp \markupsetcodequoteright +% \let\markupsetuplqverb \markupsetcodequoteleft \let\markupsetuprqverb \markupsetcodequoteright +% \let\markupsetuplqverbatim \markupsetcodequoteleft \let\markupsetuprqverbatim \markupsetcodequoteright -\let\markupsetuplqsamp \markupsetnoligaturesquoteleft \let\markupsetuplqkbd \markupsetnoligaturesquoteleft -% 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. +% Allow an option to not use regular directed right quote/apostrophe +% (char 0x27), but instead the undirected quote from cmtt (char 0x0d). +% The undirected quote is ugly, so don't make it the default, but it +% works for pasting with more pdf viewers (at least evince), the +% lilypond developers report. xpdf does work with the regular 0x27. % \def\codequoteright{% \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax @@ -2499,33 +2315,76 @@ end \else \char'22 \fi } +% Commands to set the quote options. +% +\parseargdef\codequoteundirected{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETtxicodequoteundirected\endcsname + = t% + \else\ifx\temp\offword + \expandafter\let\csname SETtxicodequoteundirected\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @codequoteundirected value `\temp', must be on|off}% + \fi\fi +} +% +\parseargdef\codequotebacktick{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETtxicodequotebacktick\endcsname + = t% + \else\ifx\temp\offword + \expandafter\let\csname SETtxicodequotebacktick\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @codequotebacktick value `\temp', must be on|off}% + \fi\fi +} + % [Knuth] pp. 380,381,391, disable Spanish ligatures ?` and !` of \tt font. \def\noligaturesquoteleft{\relax\lq} % Count depth in font-changes, for error checks \newcount\fontdepth \fontdepth=0 -%% Add scribe-like font environments, plus @l for inline lisp (usually sans -%% serif) and @ii for TeX italic +% Font commands. -% \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} +% #1 is the font command (\sl or \it), #2 is the text to slant. +% If we are in a monospaced environment, however, 1) always use \ttsl, +% and 2) do not add an italic correction. +\def\dosmartslant#1#2{% + \ifusingtt + {{\ttsl #2}\let\next=\relax}% + {\def\next{{#1#2}\futurelet\next\smartitaliccorrection}}% + \next +} +\def\smartslanted{\dosmartslant\sl} +\def\smartitalic{\dosmartslant\it} -% like \smartslanted except unconditionally uses \ttsl. +% Output an italic correction unless \next (presumed to be the following +% character) is such as not to need one. +\def\smartitaliccorrection{% + \ifx\next,% + \else\ifx\next-% + \else\ifx\next.% + \else\ptexslash + \fi\fi\fi} + +% like \smartslanted except unconditionally uses \ttsl, and no ic. % @var is set to this for defun arguments. -\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx} +\def\ttslanted#1{{\ttsl #1}} % @cite is like \smartslanted except unconditionally use \sl. We never want % ttsl for book titles, do we? -\def\cite#1{{\sl #1}\futurelet\next\smartitalicx} +\def\cite#1{{\sl #1}\futurelet\next\smartitaliccorrection} \let\i=\smartitalic \let\slanted=\smartslanted -\def\var#1{{\setupmarkupstyle{var}\smartslanted{#1}}} +\def\var#1{\smartslanted{#1}} \let\dfn=\smartslanted \let\emph=\smartitalic @@ -2653,6 +2512,8 @@ end } } +\def\codex #1{\tclose{#1}\endgroup} + \def\realdash{-} \def\codedash{-\discretionary{}{}{}} \def\codeunder{% @@ -2666,7 +2527,6 @@ end \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 @@ -2686,63 +2546,18 @@ end \allowcodebreaksfalse \else \errhelp = \EMsimple - \errmessage{Unknown @allowcodebreaks option `\txiarg'}% + \errmessage{Unknown @allowcodebreaks option `\txiarg', must be true|false}% \fi\fi } -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. -\def\kbd#1{{\setupmarkupstyle{kbd}\def\look{#1}\expandafter\kbdfoo\look??\par}} - -% @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\setupmarkupstyle{kbd}\look}}\fi -\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi} - -% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. -\let\indicateurl=\code -\let\env=\code -\let\command=\code - -% @clicksequence{File @click{} Open ...} -\def\clicksequence#1{\begingroup #1\endgroup} - -% @clickstyle @arrow (by default) -\parseargdef\clickstyle{\def\click{#1}} -\def\click{\arrow} - % @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 +% itself. First (mandatory) arg is the url. +% (This \urefnobreak definition isn't used now, leaving it for a while +% for comparison.) +\def\urefnobreak#1{\dourefnobreak #1,,,\finish} +\def\dourefnobreak#1,#2,#3,#4\finish{\begingroup \unsepspaces \pdfurl{#1}% \setbox0 = \hbox{\ignorespaces #3}% @@ -2763,6 +2578,103 @@ end \endlink \endgroup} +% This \urefbreak definition is the active one. +\def\urefbreak{\begingroup \urefcatcodes \dourefbreak} +\let\uref=\urefbreak +\def\dourefbreak#1{\urefbreakfinish #1,,,\finish} +\def\urefbreakfinish#1,#2,#3,#4\finish{% doesn't work in @example + \unsepspaces + \pdfurl{#1}% + \setbox0 = \hbox{\ignorespaces #3}% + \ifdim\wd0 > 0pt + \unhbox0 % third arg given, show only that + \else + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \ifpdf + \unhbox0 % PDF: 2nd arg given, show only it + \else + \unhbox0\ (\urefcode{#1})% DVI: 2nd arg given, show both it and url + \fi + \else + \urefcode{#1}% only url given, so show it + \fi + \fi + \endlink +\endgroup} + +% Allow line breaks around only a few characters (only). +\def\urefcatcodes{% + \catcode\ampChar=\active \catcode\dotChar=\active + \catcode\hashChar=\active \catcode\questChar=\active + \catcode\slashChar=\active +} +{ + \urefcatcodes + % + \global\def\urefcode{\begingroup + \setupmarkupstyle{code}% + \urefcatcodes + \let&\urefcodeamp + \let.\urefcodedot + \let#\urefcodehash + \let?\urefcodequest + \let/\urefcodeslash + \codex + } + % + % By default, they are just regular characters. + \global\def&{\normalamp} + \global\def.{\normaldot} + \global\def#{\normalhash} + \global\def?{\normalquest} + \global\def/{\normalslash} +} + +% we put a little stretch before and after the breakable chars, to help +% line breaking of long url's. The unequal skips make look better in +% cmtt at least, especially for dots. +\def\urefprestretch{\urefprebreak \hskip0pt plus.13em } +\def\urefpoststretch{\urefpostbreak \hskip0pt plus.1em } +% +\def\urefcodeamp{\urefprestretch \&\urefpoststretch} +\def\urefcodedot{\urefprestretch .\urefpoststretch} +\def\urefcodehash{\urefprestretch \#\urefpoststretch} +\def\urefcodequest{\urefprestretch ?\urefpoststretch} +\def\urefcodeslash{\futurelet\next\urefcodeslashfinish} +{ + \catcode`\/=\active + \global\def\urefcodeslashfinish{% + \urefprestretch \slashChar + % Allow line break only after the final / in a sequence of + % slashes, to avoid line break between the slashes in http://. + \ifx\next/\else \urefpoststretch \fi + } +} + +% One more complication: by default we'll break after the special +% characters, but some people like to break before the special chars, so +% allow that. Also allow no breaking at all, for manual control. +% +\parseargdef\urefbreakstyle{% + \def\txiarg{#1}% + \ifx\txiarg\wordnone + \def\urefprebreak{\nobreak}\def\urefpostbreak{\nobreak} + \else\ifx\txiarg\wordbefore + \def\urefprebreak{\allowbreak}\def\urefpostbreak{\nobreak} + \else\ifx\txiarg\wordafter + \def\urefprebreak{\nobreak}\def\urefpostbreak{\allowbreak} + \else + \errhelp = \EMsimple + \errmessage{Unknown @urefbreakstyle setting `\txiarg'}% + \fi\fi\fi +} +\def\wordafter{after} +\def\wordbefore{before} +\def\wordnone{none} + +\urefbreakstyle after + % @url synonym for @uref, since that's how everyone uses it. % \let\url=\uref @@ -2784,6 +2696,51 @@ end \let\email=\uref \fi +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. +\def\kbd#1{{\setupmarkupstyle{kbd}\def\look{#1}\expandafter\kbdfoo\look??\par}} + +% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), +% `example' (@kbd uses ttsl only inside of @example and friends), +% or `code' (@kbd uses normal tty font always). +\parseargdef\kbdinputstyle{% + \def\txiarg{#1}% + \ifx\txiarg\worddistinct + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% + \else\ifx\txiarg\wordexample + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% + \else\ifx\txiarg\wordcode + \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% + \else + \errhelp = \EMsimple + \errmessage{Unknown @kbdinputstyle setting `\txiarg'}% + \fi\fi\fi +} +\def\worddistinct{distinct} +\def\wordexample{example} +\def\wordcode{code} + +% Default is `distinct'. +\kbdinputstyle distinct + +\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\setupmarkupstyle{kbd}\look}}\fi +\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi} + +% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. +\let\indicateurl=\code +\let\env=\code +\let\command=\code + +% @clicksequence{File @click{} Open ...} +\def\clicksequence#1{\begingroup #1\endgroup} + +% @clickstyle @arrow (by default) +\parseargdef\clickstyle{\def\click{#1}} +\def\click{\arrow} + % Typeset a dimension, e.g., `in' or `pt'. The only reason for the % argument is to make the input look right: @dmn{pt} instead of @dmn{}pt. % @@ -2819,8 +2776,188 @@ end \fi } +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math outputs its argument in math mode. +% +% One complication: _ usually means subscripts, but it could also mean +% an actual _ character, as in @math{@var{some_variable} + 1}. So make +% _ active, and distinguish by seeing if the current family is \slfam, +% which is what @var uses. +{ + \catcode`\_ = \active + \gdef\mathunderscore{% + \catcode`\_=\active + \def_{\ifnum\fam=\slfam \_\else\sb\fi}% + } +} +% Another complication: we want \\ (and @\) to output a math (or tt) \. +% FYI, plain.tex uses \\ as a temporary control sequence (for no +% particular reason), but this is not advertised and we don't care. +% +% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. +\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} +% +\def\math{% + \tex + \mathunderscore + \let\\ = \mathbackslash + \mathactive + % make the texinfo accent commands work in math mode + \let\"=\ddot + \let\'=\acute + \let\==\bar + \let\^=\hat + \let\`=\grave + \let\u=\breve + \let\v=\check + \let\~=\tilde + \let\dotaccent=\dot + $\finishmath +} +\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. + +% Some active characters (such as <) are spaced differently in math. +% We have to reset their definitions in case the @math was an argument +% to a command which sets the catcodes (such as @item or @section). +% +{ + \catcode`^ = \active + \catcode`< = \active + \catcode`> = \active + \catcode`+ = \active + \catcode`' = \active + \gdef\mathactive{% + \let^ = \ptexhat + \let< = \ptexless + \let> = \ptexgtr + \let+ = \ptexplus + \let' = \ptexquoteright + } +} + \message{glyphs,} +% and logos. + +% @@ prints an @. +\def\@{\char64 } + +% Used to generate quoted braces. Unless we're in typewriter, use +% \ecfont because the CM text fonts do not have braces, and we don't +% want to switch into math. +\def\mylbrace{{\ifmonospace\else\ecfont\fi \char123}} +\def\myrbrace{{\ifmonospace\else\ecfont\fi \char125}} +\let\{=\mylbrace +\let\}=\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\, = \ptexc +\let\dotaccent = \ptexdot +\def\ringaccent#1{{\accent23 #1}} +\let\tieaccent = \ptext +\let\ubaraccent = \ptexb +\let\udotaccent = \d + +% Other special characters: @questiondown @exclamdown @ordf @ordm +% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. +\def\questiondown{?`} +\def\exclamdown{!`} +\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} +\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} + +% Dotless i and dotless j, used for accents. +\def\imacro{i} +\def\jmacro{j} +\def\dotless#1{% + \def\temp{#1}% + \ifx\temp\imacro \ifmmode\imath \else\ptexi \fi + \else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi + \else \errmessage{@dotless can be used only with i or j}% + \fi\fi +} + +% The \TeX{} logo, as in plain, but resetting the spacing so that a +% period following counts as ending a sentence. (Idea found in latex.) +% +\edef\TeX{\TeX \spacefactor=1000 } + +% @LaTeX{} logo. Not quite the same results as the definition in +% latex.ltx, since we use a different font for the raised A; it's most +% convenient for us to use an explicitly smaller font, rather than using +% the \scriptstyle font (since we don't reset \scriptstyle and +% \scriptscriptstyle). +% +\def\LaTeX{% + L\kern-.36em + {\setbox0=\hbox{T}% + \vbox to \ht0{\hbox{% + \ifx\textnominalsize\xwordpt + % for 10pt running text, \lllsize (8pt) is too small for the A in LaTeX. + % Revert to plain's \scriptsize, which is 7pt. + \count255=\the\fam $\fam\count255 \scriptstyle A$% + \else + % For 11pt, we can use our lllsize. + \selectfonts\lllsize A% + \fi + }% + \vss + }}% + \kern-.15em + \TeX +} + +% Some math mode symbols. +\def\bullet{$\ptexbullet$} +\def\geq{\ifmmode \ge\else $\ge$\fi} +\def\leq{\ifmmode \le\else $\le$\fi} +\def\minus{\ifmmode -\else $-$\fi} + +% @dots{} outputs an ellipsis using the current font. +% We do .5em per period so that it has the same spacing in the cm +% typewriter fonts as three actual period characters; on the other hand, +% in other typewriter fonts three periods are wider than 1.5em. So do +% whichever is larger. +% +\def\dots{% + \leavevmode + \setbox0=\hbox{...}% get width of three periods + \ifdim\wd0 > 1.5em + \dimen0 = \wd0 + \else + \dimen0 = 1.5em + \fi + \hbox to \dimen0{% + \hskip 0pt plus.25fil + .\hskip 0pt plus1fil + .\hskip 0pt plus1fil + .\hskip 0pt plus.5fil + }% +} + +% @enddots{} is an end-of-sentence ellipsis. +% +\def\enddots{% + \dots + \spacefactor=\endofsentencespacefactor +} % @point{}, @result{}, @expansion{}, @print{}, @equiv{}. % @@ -2991,7 +3128,7 @@ end % 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 +\ifx\Orb\thisisundefined \def\Orb{\mathhexbox20D} \fi @@ -3019,8 +3156,9 @@ end \newif\ifsetshortcontentsaftertitlepage \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue -\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% - \endgroup\page\hbox{}\page} +\parseargdef\shorttitlepage{% + \begingroup \hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} \envdef\titlepage{% % Open one extra group, as we want to close it in the middle of \Etitlepage. @@ -3080,7 +3218,7 @@ end \finishedtitlepagetrue } -%%% Macros to be used within @titlepage: +% Macros to be used within @titlepage: \let\subtitlerm=\tenrm \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} @@ -3113,7 +3251,7 @@ end } -%%% Set up page headings and footings. +% Set up page headings and footings. \let\thispage=\folio @@ -3207,10 +3345,14 @@ end \def\headings #1 {\csname HEADINGS#1\endcsname} -\def\HEADINGSoff{% -\global\evenheadline={\hfil} \global\evenfootline={\hfil} -\global\oddheadline={\hfil} \global\oddfootline={\hfil}} -\HEADINGSoff +\def\headingsoff{% non-global headings elimination + \evenheadline={\hfil}\evenfootline={\hfil}% + \oddheadline={\hfil}\oddfootline={\hfil}% +} + +\def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting +\HEADINGSoff % it's the default + % When we turn headings on, set the page number to 1. % For double-sided printing, put current file name in lower left corner, % chapter name on inside top of right hand pages, document @@ -3261,7 +3403,7 @@ end % 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 +\ifx\today\thisisundefined \def\today{% \number\day\space \ifcase\month @@ -3322,7 +3464,7 @@ end \begingroup \advance\leftskip by-\tableindent \advance\hsize by\tableindent - \advance\rightskip by0pt plus1fil + \advance\rightskip by0pt plus1fil\relax \leavevmode\unhbox0\par \endgroup % @@ -3808,9 +3950,9 @@ end \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. +% 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 @@ -4134,11 +4276,14 @@ end \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 + % Need these unexpandable (because we define \tt as a dummy) + % definitions when @{ or @} appear in index entry text. Also, more + % complicated, when \tex is in effect and \{ is a \delimiter again. + % We can't use \lbracecmd and \rbracecmd because texindex assumes + % braces and backslashes are used only as delimiters. Perhaps we + % should define @lbrace and @rbrace commands a la @comma. + \def\{{{\tt\char123}}% + \def\}{{\tt\char125}}% % % I don't entirely understand this, but when an index entry is % generated from a macro call, the \endinput which \scanmacro inserts @@ -4191,7 +4336,7 @@ end \def\commondummies{% % % \definedummyword defines \#1 as \string\#1\space, thus effectively - % preventing its expansion. This is used only for control% words, + % 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. @@ -4210,6 +4355,7 @@ end \commondummiesnofonts % \definedummyletter\_% + \definedummyletter\-% % % Non-English letters. \definedummyword\AA @@ -4246,20 +4392,24 @@ end \definedummyword\TeX % % Assorted special characters. + \definedummyword\arrow \definedummyword\bullet \definedummyword\comma \definedummyword\copyright \definedummyword\registeredsymbol \definedummyword\dots \definedummyword\enddots + \definedummyword\entrybreak \definedummyword\equiv \definedummyword\error \definedummyword\euro + \definedummyword\expansion + \definedummyword\geq \definedummyword\guillemetleft \definedummyword\guillemetright \definedummyword\guilsinglleft \definedummyword\guilsinglright - \definedummyword\expansion + \definedummyword\leq \definedummyword\minus \definedummyword\ogonek \definedummyword\pounds @@ -4316,7 +4466,9 @@ end \definedummyword\b \definedummyword\i \definedummyword\r + \definedummyword\sansserif \definedummyword\sc + \definedummyword\slanted \definedummyword\t % % Commands that take arguments. @@ -4325,10 +4477,12 @@ end \definedummyword\code \definedummyword\command \definedummyword\dfn + \definedummyword\dmn \definedummyword\email \definedummyword\emph \definedummyword\env \definedummyword\file + \definedummyword\indicateurl \definedummyword\kbd \definedummyword\key \definedummyword\math @@ -4356,7 +4510,7 @@ end \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. + % All control words become @asis by default; overrides below. \let\definedummyword\definedummyaccent % \commondummiesnofonts @@ -4368,8 +4522,14 @@ end % \def\ { }% \def\@{@}% - % how to handle braces? \def\_{\normalunderscore}% + \def\-{}% @- shouldn't affect sorting + % + % Unfortunately, texindex is not prepared to handle braces in the + % content at all. So for index sorting, we map @{ and @} to strings + % starting with |, since that ASCII character is between ASCII { and }. + \def\{{|a}% + \def\}{|b}% % % Non-English letters. \def\AA{AA}% @@ -4397,6 +4557,7 @@ end % % Assorted special characters. % (The following {} will end up in the sort string, but that's ok.) + \def\arrow{->}% \def\bullet{bullet}% \def\comma{,}% \def\copyright{copyright}% @@ -4406,10 +4567,12 @@ end \def\error{error}% \def\euro{euro}% \def\expansion{==>}% + \def\geq{>=}% \def\guillemetleft{<<}% \def\guillemetright{>>}% \def\guilsinglleft{<}% \def\guilsinglright{>}% + \def\leq{<=}% \def\minus{-}% \def\point{.}% \def\pounds{pounds}% @@ -4424,6 +4587,9 @@ end \def\result{=>}% \def\textdegree{o}% % + \expandafter\ifx\csname SETtxiindexlquoteignore\endcsname\relax + \else \indexlquoteignore \fi + % % We need to get rid of all macros, leaving only the arguments (if present). % Of course this is not nearly correct, but it is the best we can do for now. % makeinfo does not expand macros in the argument to @deffn, which ends up @@ -4437,6 +4603,11 @@ end \macrolist } +% Undocumented (for FSFS 2nd ed.): @set txiindexlquoteignore makes us +% ignore left quotes in the sort term. +{\catcode`\`=\active + \gdef\indexlquoteignore{\let`=\empty}} + \let\indexbackslash=0 %overridden during \printindex. \let\SETmarginindex=\relax % put index entries in margin (undocumented)? @@ -4694,7 +4865,6 @@ end % But this freezes the catcodes in the argument, and can cause problems to % @code, which sets - active. This problem was fixed by a kludge--- % ``-'' was active throughout whole index, but this isn't really right. -% % The right solution is to prevent \entry from swallowing the whole text. % --kasal, 21nov03 \def\entry{% @@ -4731,10 +4901,17 @@ end % columns. \vskip 0pt plus1pt % + % When reading the text of entry, convert explicit line breaks + % from @* into spaces. The user might give these in long section + % titles, for instance. + \def\*{\unskip\space\ignorespaces}% + \def\entrybreak{\hfil\break}% + % % Swallow the left brace of the text (first parameter): \afterassignment\doentry \let\temp = } +\def\entrybreak{\unskip\space\ignorespaces}% \def\doentry{% \bgroup % Instead of the swallowed brace. \noindent @@ -4967,7 +5144,22 @@ end \message{sectioning,} % Chapters, sections, etc. -% \unnumberedno is an oxymoron, of course. But we count the unnumbered +% Let's start with @part. +\outer\parseargdef\part{\partzzz{#1}} +\def\partzzz#1{% + \chapoddpage + \null + \vskip.3\vsize % move it down on the page a bit + \begingroup + \noindent \titlefonts\rmisbold #1\par % the text + \let\lastnode=\empty % no node to associate with + \writetocentry{part}{#1}{}% but put it in the toc + \headingsoff % no headline or footline on the part page + \chapoddpage + \endgroup +} + +% \unnumberedno is an oxymoron. But we count the unnumbered % sections so that we can refer to them unambiguously in the pdf % outlines by their "section number". We avoid collisions with chapter % numbers by starting them at 10000. (If a document ever has 10000 @@ -5046,8 +5238,8 @@ end \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 +% To achieve this, remember the "biggest" unnum. sec. we are currently in: +\chardef\unnlevel = \maxseclevel % % Trace whether the current chapter is an appendix or not: % \chapheadtype is "N" or "A", unnumbered chapters are ignored. @@ -5072,8 +5264,8 @@ end % The heading type: \def\headtype{#1}% \if \headtype U% - \ifnum \absseclevel < \unmlevel - \chardef\unmlevel = \absseclevel + \ifnum \absseclevel < \unnlevel + \chardef\unnlevel = \absseclevel \fi \else % Check for appendix sections: @@ -5085,10 +5277,10 @@ end \fi\fi \fi % Check for numbered within unnumbered: - \ifnum \absseclevel > \unmlevel + \ifnum \absseclevel > \unnlevel \def\headtype{U}% \else - \chardef\unmlevel = 3 + \chardef\unnlevel = 3 \fi \fi % Now print the heading: @@ -5174,7 +5366,8 @@ end \global\let\subsubsection = \appendixsubsubsec } -\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +% normally unnmhead0 calls unnumberedzzz: +\outer\parseargdef\unnumbered{\unnmhead0{#1}} \def\unnumberedzzz#1{% \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 \global\advance\unnumberedno by 1 @@ -5218,40 +5411,47 @@ end \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 +% normally calls appendixsectionzzz: +\outer\parseargdef\appendixsection{\apphead1{#1}} \def\appendixsectionzzz#1{% \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% } \let\appendixsec\appendixsection -\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz +% normally calls unnumberedseczzz: +\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} \def\unnumberedseczzz#1{% \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% } % Subsections. -\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz +% +% normally calls numberedsubseczzz: +\outer\parseargdef\numberedsubsec{\numhead2{#1}} \def\numberedsubseczzz#1{% \global\subsubsecno=0 \global\advance\subsecno by 1 \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% } -\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz +% normally calls appendixsubseczzz: +\outer\parseargdef\appendixsubsec{\apphead2{#1}} \def\appendixsubseczzz#1{% \global\subsubsecno=0 \global\advance\subsecno by 1 \sectionheading{#1}{subsec}{Yappendix}% {\appendixletter.\the\secno.\the\subsecno}% } -\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +% normally calls unnumberedsubseczzz: +\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} \def\unnumberedsubseczzz#1{% \global\subsubsecno=0 \global\advance\subsecno by 1 \sectionheading{#1}{subsec}{Ynothing}% @@ -5259,21 +5459,25 @@ end } % Subsubsections. -\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz +% +% normally numberedsubsubseczzz: +\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} \def\numberedsubsubseczzz#1{% \global\advance\subsubsecno by 1 \sectionheading{#1}{subsubsec}{Ynumbered}% {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% } -\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz +% normally appendixsubsubseczzz: +\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} \def\appendixsubsubseczzz#1{% \global\advance\subsubsecno by 1 \sectionheading{#1}{subsubsec}{Yappendix}% {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% } -\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +% normally unnumberedsubsubseczzz: +\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} \def\unnumberedsubsubseczzz#1{% \global\advance\subsubsecno by 1 \sectionheading{#1}{subsubsec}{Ynothing}% @@ -5323,14 +5527,13 @@ end % (including whitespace, linebreaking, etc. around it), % given all the information in convenient, parsed form. -%%% Args are the skip and penalty (usually negative) +% 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 +% Define plain chapter starts, and page on/off switching for it. \def\chapbreak{\dobreak \chapheadingskip {-4000}} \def\chappager{\par\vfill\supereject} % Because \domark is called before \chapoddpage, the filler page will @@ -5340,9 +5543,8 @@ end \chappager \ifodd\pageno \else \begingroup - \evenheadline={\hfil}\evenfootline={\hfil}% - \oddheadline={\hfil}\oddfootline={\hfil}% - \hbox to 0pt{}% + \headingsoff + \null \chappager \endgroup \fi @@ -5534,6 +5736,8 @@ end % \def\sectionheading#1#2#3#4{% {% + \checkenv{}% should not be in an environment. + % % Switch to the right set of fonts. \csname #2fonts\endcsname \rmisbold % @@ -5785,6 +5989,7 @@ end \def\summarycontents{% \startcontents{\putwordShortTOC}% % + \let\partentry = \shortpartentry \let\numchapentry = \shortchapentry \let\appentry = \shortchapentry \let\unnchapentry = \shortunnchapentry @@ -5840,6 +6045,19 @@ end % The last argument is the page number. % The arguments in between are the chapter number, section number, ... +% Parts, in the main contents. Replace the part number, which doesn't +% exist, with an empty box. Let's hope all the numbers have the same width. +% Also ignore the page number, which is conventionally not printed. +\def\numeralbox{\setbox0=\hbox{8}\hbox to \wd0{\hfil}} +\def\partentry#1#2#3#4{\dochapentry{\numeralbox\labelspace#1}{}} +% +% Parts, in the short toc. +\def\shortpartentry#1#2#3#4{% + \penalty-300 + \vskip.5\baselineskip plus.15\baselineskip minus.1\baselineskip + \shortchapentry{{\bf #1}}{\numeralbox}{}{}% +} + % Chapters, in the main contents. \def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} % @@ -5929,9 +6147,9 @@ end \message{environments,} % @foo ... @end foo. -% @tex ... @end tex escapes into raw Tex temporarily. +% @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. +% But \@ or @@ will get a plain @ character. \envdef\tex{% \setupmarkupstyle{tex}% @@ -5948,6 +6166,10 @@ end \catcode`\'=\other \escapechar=`\\ % + % ' is active in math mode (mathcode"8000). So reset it, and all our + % other math active characters (just in case), to plain's definitions. + \mathactive + % \let\b=\ptexb \let\bullet=\ptexbullet \let\c=\ptexc @@ -6150,41 +6372,42 @@ end } % 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} +% Let's do it in one command. #1 is the env name, #2 the definition. +\def\makedispenvdef#1#2{% + \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2}% + \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2}% \expandafter\let\csname E#1\endcsname \afterenvbreak \expandafter\let\csname Esmall#1\endcsname \afterenvbreak } -% Define two synonyms: -\def\maketwodispenvs #1#2#3{ - \makedispenv{#1}{#3} - \makedispenv{#2}{#3} +% Define two environment synonyms (#1 and #2) for an environment. +\def\maketwodispenvdef#1#2#3{% + \makedispenvdef{#1}{#3}% + \makedispenvdef{#2}{#3}% } - -% @lisp: indented, narrowed, typewriter font; @example: same as @lisp. +% +% @lisp: indented, narrowed, typewriter font; +% @example: same as @lisp. % % @smallexample and @smalllisp: use smaller fonts. % Originally contributed by Pavel@xerox. % -\maketwodispenvs {lisp}{example}{% +\maketwodispenvdef{lisp}{example}{% \nonfillstart \tt\setupmarkupstyle{example}% \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. - \gobble % eat return + \gobble % eat return } % @display/@smalldisplay: same as @lisp except keep current font. % -\makedispenv {display}{% +\makedispenvdef{display}{% \nonfillstart \gobble } % @format/@smallformat: same as @display except don't narrow margins. % -\makedispenv{format}{% +\makedispenvdef{format}{% \let\nonarrowing = t% \nonfillstart \gobble @@ -6203,7 +6426,7 @@ end \envdef\flushright{% \let\nonarrowing = t% \nonfillstart - \advance\leftskip by 0pt plus 1fill + \advance\leftskip by 0pt plus 1fill\relax \gobble } \let\Eflushright = \afterenvbreak @@ -6238,6 +6461,8 @@ end % we're doing normal filling. So, when using \aboveenvbreak and % \afterenvbreak, temporarily make \parskip 0. % +\makedispenvdef{quotation}{\quotationstart} +% \def\quotationstart{% {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip \parindent=0pt @@ -6253,28 +6478,18 @@ end \parsearg\quotationlabel } -\envdef\quotation{% - \setnormaldispenv - \quotationstart -} - -\envdef\smallquotation{% - \setsmalldispenv - \quotationstart -} -\let\Esmallquotation = \Equotation - % We have retained a nonzero parskip for the environment, since we're % doing normal filling. % \def\Equotation{% \par - \ifx\quotationauthor\undefined\else + \ifx\quotationauthor\thisisundefined\else % indent a bit. \leftline{\kern 2\leftskip \sl ---\quotationauthor}% \fi {\parskip=0pt \afterenvbreak}% } +\def\Esmallquotation{\Equotation} % If we're given an argument, typeset it in bold with a colon after. \def\quotationlabel#1{% @@ -6331,21 +6546,28 @@ end % Setup for the @verbatim environment % -% Real tab expansion +% Real tab expansion. \newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount % -\def\starttabbox{\setbox0=\hbox\bgroup} +% We typeset each line of the verbatim in an \hbox, so we can handle +% tabs. The \global is in case the verbatim line starts with an accent, +% or some other command that starts with a begin-group. Otherwise, the +% entire \verbbox would disappear at the corresponding end-group, before +% it is typeset. Meanwhile, we can't have nested verbatim commands +% (can we?), so the \global won't be overwriting itself. +\newbox\verbbox +\def\starttabbox{\global\setbox\verbbox=\hbox\bgroup} % \begingroup \catcode`\^^I=\active \gdef\tabexpand{% \catcode`\^^I=\active \def^^I{\leavevmode\egroup - \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 + \dimen\verbbox=\wd\verbbox % the width so far, or since the previous tab + \divide\dimen\verbbox by\tabw + \multiply\dimen\verbbox by\tabw % compute previous multiple of \tabw + \advance\dimen\verbbox by\tabw % advance to next multiple of \tabw + \wd\verbbox=\dimen\verbbox \box\verbbox \starttabbox }% } \endgroup @@ -6354,15 +6576,16 @@ end \def\setupverbatim{% \let\nonarrowing = t% \nonfillstart - % Easiest (and conventionally used) font for verbatim - \tt - \def\par{\leavevmode\egroup\box0\endgraf}% + \tt % easiest (and conventionally used) font for verbatim + % The \leavevmode here is for blank lines. Otherwise, we would + % never \starttabox and the \egroup would end verbatim mode. + \def\par{\leavevmode\egroup\box\verbbox\endgraf}% \tabexpand \setupmarkupstyle{verbatim}% % Respect line breaks, % print special symbols as themselves, and - % make each space count - % must do in this order: + % make each space count. + % Must do in this order: \obeylines \uncatcodespecials \sepspaces \everypar{\starttabbox}% } @@ -6419,6 +6642,7 @@ end \makevalueexpandable \setupverbatim \indexnofonts % Allow `@@' and other weird things in file names. + \wlog{texinfo.tex: doing @verbatiminclude of #1^^J}% \input #1 \afterenvbreak }% @@ -6468,7 +6692,7 @@ end % 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 + % As a further refinement, we avoid "club" headers by signalling % with penalty of 10003 after the very first @deffn in the % sequence (see above), and penalty of 10002 after any following % @def command. @@ -6505,7 +6729,7 @@ end #1#2 \endheader % common ending: \interlinepenalty = 10000 - \advance\rightskip by 0pt plus 1fil + \advance\rightskip by 0pt plus 1fil\relax \endgraf \nobreak\vskip -\parskip \penalty\defunpenalty % signal to \startdefun and \dodefunx @@ -6535,13 +6759,36 @@ end \def\domakedefun#1#2#3{% \envdef#1{% \startdefun + \doingtypefnfalse % distinguish typed functions from all else \parseargusing\activeparens{\printdefunline#3}% }% \def#2{\dodefunx#1}% \def#3% } -%%% Untyped functions: +\newif\ifdoingtypefn % doing typed function? +\newif\ifrettypeownline % typeset return type on its own line? + +% @deftypefnnewline on|off says whether the return type of typed functions +% are printed on their own line. This affects @deftypefn, @deftypefun, +% @deftypeop, and @deftypemethod. +% +\parseargdef\deftypefnnewline{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETtxideftypefnnl\endcsname + = \empty + \else\ifx\temp\offword + \expandafter\let\csname SETtxideftypefnnl\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @txideftypefnnl value `\temp', + must be on|off}% + \fi\fi +} + +% Untyped functions: % @deffn category name args \makedefun{deffn}{\deffngeneral{}} @@ -6560,7 +6807,7 @@ end \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% } -%%% Typed functions: +% Typed functions: % @deftypefn category type name args \makedefun{deftypefn}{\deftypefngeneral{}} @@ -6575,10 +6822,11 @@ end % \def\deftypefngeneral#1#2 #3 #4 #5\endheader{% \dosubind{fn}{\code{#4}}{#1}% + \doingtypefntrue \defname{#2}{#3}{#4}\defunargs{#5\unskip}% } -%%% Typed variables: +% Typed variables: % @deftypevr category type var args \makedefun{deftypevr}{\deftypecvgeneral{}} @@ -6596,7 +6844,7 @@ end \defname{#2}{#3}{#4}\defunargs{#5\unskip}% } -%%% Untyped variables: +% Untyped variables: % @defvr category var args \makedefun{defvr}#1 {\deftypevrheader{#1} {} } @@ -6607,7 +6855,8 @@ end % \defcvof {category of}class var args \def\defcvof#1#2 {\deftypecvof{#1}#2 {} } -%%% Type: +% Types: + % @deftp category name args \makedefun{deftp}#1 #2 #3\endheader{% \doind{tp}{\code{#2}}% @@ -6635,25 +6884,49 @@ end % We are followed by (but not passed) the arguments, if any. % \def\defname#1#2#3{% + \par % Get the values of \leftskip and \rightskip as they were outside the @def... \advance\leftskip by -\defbodyindent % - % How we'll format the type name. Putting it in brackets helps + % Determine if we are typesetting the return type of a typed function + % on a line by itself. + \rettypeownlinefalse + \ifdoingtypefn % doing a typed function specifically? + % then check user option for putting return type on its own line: + \expandafter\ifx\csname SETtxideftypefnnl\endcsname\relax \else + \rettypeownlinetrue + \fi + \fi + % + % How we'll format the category name. Putting it in brackets helps % distinguish it from the body text that may end up on the next line % just below it. \def\temp{#1}% \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} % - % Figure out line sizes for the paragraph shape. + % Figure out line sizes for the paragraph shape. We'll always have at + % least two. + \tempnum = 2 + % % The first line needs space for \box0; but if \rightskip is nonzero, % we need only space for the part of \box0 which exceeds it: \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip + % + % If doing a return type on its own line, we'll have another line. + \ifrettypeownline + \advance\tempnum by 1 + \def\maybeshapeline{0in \hsize}% + \else + \def\maybeshapeline{}% + \fi + % % The continuations: \dimen2=\hsize \advance\dimen2 by -\defargsindent - % (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. + % The final paragraph shape: + \parshape \tempnum 0in \dimen0 \maybeshapeline \defargsindent \dimen2 + % + % Put the category name at the right margin. \noindent \hbox to 0pt{% \hfil\box0 \kern-\hsize @@ -6675,8 +6948,16 @@ end % . 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 + \def\temp{#2}% text of the return type + \ifx\temp\empty\else + \tclose{\temp}% typeset the return type + \ifrettypeownline + % put return type on its own line; prohibit line break following: + \hfil\vadjust{\nobreak}\break + \else + \space % type on same line, so just followed by a space + \fi + \fi % no return type #3% output function name }% {\rm\enskip}% hskip 0.5 em of \tenrm @@ -6794,7 +7075,7 @@ end % 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 +\ifx\eTeXversion\thisisundefined \newwrite\macscribble \def\scantokens#1{% \toks0={#1}% @@ -6805,25 +7086,30 @@ end } \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\scanmacro#1{\begingroup + \newlinechar`\^^M + \let\xeatspaces\eatspaces + % + % Undo catcode changes of \startcontents and \doprintindex + % When called from @insertcopying or (short)caption, we need active + % backslash to get it printed correctly. Previously, we had + % \catcode`\\=\other instead. We'll see whether a problem appears + % with macro expansion. --kasal, 19aug04 + \catcode`\@=0 \catcode`\\=\active \escapechar=`\@ + % + % ... and for \example: + \spaceisspace + % + % The \empty here causes a following catcode 5 newline to be eaten as + % part of reading whitespace after a control sequence. It does not + % eat a catcode 13 newline. There's no good way to handle the two + % cases (untried: maybe e-TeX's \everyeof could help, though plain TeX + % would then have different behavior). See the Macro Details node in + % the manual for the workaround we recommend for macros and + % line-oriented commands. + % + \scantokens{#1\empty}% +\endgroup} \def\scanexp#1{% \edef\temp{\noexpand\scanmacro{#1}}% @@ -6877,17 +7163,18 @@ end % 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 \. - +% (as in normal texinfo). It is necessary to change the definition of \ +% to recognize macro arguments; this is the job of \mbodybackslash. +% % Non-ASCII encodings make 8-bit characters active, so un-activate % them to avoid their expansion. Must do this non-globally, to % confine the change to the current group. - +% % It's necessary to have hard CRs when the macro is executed. This is -% done by making ^^M (\endlinechar) catcode 12 when reading the macro +% done by making ^^M (\endlinechar) catcode 12 when reading the macro % body, and then making it the \newlinechar in \scanmacro. - -\def\scanctxt{% +% +\def\scanctxt{% used as subroutine \catcode`\"=\other \catcode`\+=\other \catcode`\<=\other @@ -6900,13 +7187,13 @@ end \ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi } -\def\scanargctxt{% +\def\scanargctxt{% used for copying and captions, not macros. \scanctxt \catcode`\\=\other \catcode`\^^M=\other } -\def\macrobodyctxt{% +\def\macrobodyctxt{% used for @macro definitions \scanctxt \catcode`\{=\other \catcode`\}=\other @@ -6914,30 +7201,48 @@ end \usembodybackslash } -\def\macroargctxt{% +\def\macroargctxt{% used when scanning invocations \scanctxt - \catcode`\\=\other + \catcode`\\=0 } +% why catcode 0 for \ in the above? To recognize \\ \{ \} as "escapes" +% for the single characters \ { }. Thus, we end up with the "commands" +% that would be written @\ @{ @} in a Texinfo document. +% +% We already have @{ and @}. For @\, we define it here, and only for +% this purpose, to produce a typewriter backslash (so, the @\ that we +% define for @math can't be used with @macro calls): +% +\def\\{\normalbackslash}% +% +% We would like to do this for \, too, since that is what makeinfo does. +% But it is not possible, because Texinfo already has a command @, for a +% cedilla accent. Documents must use @comma{} instead. +% +% \anythingelse will almost certainly be an error of some kind. + % \mbodybackslash is the definition of \ in @macro bodies. % It maps \foo\ => \csname macarg.foo\endcsname => #N % where N is the macro parameter number. % We define \csname macarg.\endcsname to be \realbackslash, so % \\ in macro replacement text gets you a backslash. - +% {\catcode`@=0 @catcode`@\=@active @gdef@usembodybackslash{@let\=@mbodybackslash} @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} } \expandafter\def\csname macarg.\endcsname{\realbackslash} +\def\margbackslash#1{\char`\#1 } + \def\macro{\recursivefalse\parsearg\macroxxx} \def\rmacro{\recursivetrue\parsearg\macroxxx} \def\macroxxx#1{% - \getargs{#1}% now \macname is the macname and \argl the arglist + \getargs{#1}% now \macname is the macname and \argl the arglist \ifx\argl\empty % no arguments - \paramno=0% + \paramno=0 \else \expandafter\parsemargdef \argl;% \fi @@ -6986,28 +7291,32 @@ end % 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\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. +% 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 +% 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\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% + \advance\paramno by 1 \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname {\xeatspaces{\hash\the\paramno}}% \edef\paramlist{\paramlist\hash\the\paramno,}% @@ -7015,7 +7324,7 @@ end % 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% @@ -7026,6 +7335,7 @@ end % 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 @@ -7089,7 +7399,8 @@ end % \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) +% as an argument (by \parsebrace or \parsearg). +% \def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} \def\braceorlinexxx{% \ifx\nchar\bgroup\else @@ -7099,7 +7410,8 @@ end % @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. +% sign. Make them active and then expand them all to nothing. +% \def\alias{\parseargusing\obeyspaces\aliasxxx} \def\aliasxxx #1{\aliasyyy#1\relax} \def\aliasyyy #1=#2\relax{% @@ -7120,7 +7432,8 @@ end % @inforef is relatively simple. \def\inforef #1{\inforefzzz #1,,,,**} -\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, +\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 @@ -7181,11 +7494,32 @@ end \toks0 = \expandafter{\lastsection}% \immediate \writexrdef{title}{\the\toks0 }% \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. - \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout + \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, at \shipout }% \fi } +% @xrefautosectiontitle on|off says whether @section(ing) names are used +% automatically in xrefs, if the third arg is not explicitly specified. +% This was provided as a "secret" @set xref-automatic-section-title +% variable, now it's official. +% +\parseargdef\xrefautomaticsectiontitle{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETxref-automatic-section-title\endcsname + = \empty + \else\ifx\temp\offword + \expandafter\let\csname SETxref-automatic-section-title\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @xrefautomaticsectiontitle value `\temp', + must be on|off}% + \fi\fi +} + + % @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is % the node name, #2 the name of the Info cross-reference, #3 the printed % node name, #4 the name of the Info file, #5 the name of the printed @@ -7202,7 +7536,7 @@ end \setbox0=\hbox{\printedrefname\unskip}% \ifdim \wd0 = 0pt % No printed node name was explicitly given. - \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax + \expandafter\ifx\csname SETxref-automatic-section-title\endcsname \relax % Use the node name inside the square brackets. \def\printedrefname{\ignorespaces #1}% \else @@ -7357,7 +7691,8 @@ end \angleleft un\-de\-fined\angleright \iflinks \ifhavexrefs - \message{\linenumber Undefined cross reference `#1'.}% + {\toks0 = {#1}% avoid expansion of possibly-complex value + \message{\linenumber Undefined cross reference `\the\toks0'.}}% \else \ifwarnedxrefs\else \global\warnedxrefstrue @@ -7671,7 +8006,7 @@ end it from ftp://tug.org/tex/epsf.tex.} % \def\image#1{% - \ifx\epsfbox\undefined + \ifx\epsfbox\thisiundefined \ifwarnednoepsf \else \errhelp = \noepsfhelp \errmessage{epsf.tex not found, images will be ignored}% @@ -7687,7 +8022,7 @@ end % #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. +% #6 is just the usual extra ignored arg for parsing stuff. \newif\ifimagevmode \def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup \catcode`\^^M = 5 % in case we're inside an example @@ -8136,7 +8471,7 @@ directory should work if nowhere else does.} % % Latin1 (ISO-8859-1) character definitions. \def\latonechardefs{% - \gdef^^a0{~} + \gdef^^a0{\tie} \gdef^^a1{\exclamdown} \gdef^^a2{\missingcharmsg{CENT SIGN}} \gdef^^a3{{\pounds}} @@ -8166,7 +8501,7 @@ directory should work if nowhere else does.} \gdef^^b9{$^1$} \gdef^^ba{\ordm} % - \gdef^^bb{\guilletright} + \gdef^^bb{\guillemetright} \gdef^^bc{$1\over4$} \gdef^^bd{$1\over2$} \gdef^^be{$3\over4$} @@ -8258,7 +8593,7 @@ directory should work if nowhere else does.} % Latin2 (ISO-8859-2) character definitions. \def\lattwochardefs{% - \gdef^^a0{~} + \gdef^^a0{\tie} \gdef^^a1{\ogonek{A}} \gdef^^a2{\u{}} \gdef^^a3{\L} @@ -8339,8 +8674,8 @@ directory should work if nowhere else does.} \gdef^^ea{\ogonek{e}} \gdef^^eb{\"e} \gdef^^ec{\v e} - \gdef^^ed{\'\i} - \gdef^^ee{\^\i} + \gdef^^ed{\'{\dotless{i}}} + \gdef^^ee{\^{\dotless{i}}} \gdef^^ef{\v d} % \gdef^^f0{\dh} @@ -8431,7 +8766,7 @@ directory should work if nowhere else does.} \gdef\DeclareUnicodeCharacter#1#2{% \countUTFz = "#1\relax - \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% + %\wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% \begingroup \parseXMLCharref \def\UTFviiiTwoOctets##1##2{% @@ -8899,8 +9234,8 @@ directory should work if nowhere else does.} % Prevent underfull vbox error messages. \vbadness = 10000 -% Don't be so finicky about underfull hboxes, either. -\hbadness = 2000 +% Don't be very finicky about underfull hboxes, either. +\hbadness = 6666 % Following George Bush, get rid of widows and orphans. \widowpenalty=10000 @@ -9107,28 +9442,21 @@ directory should work if nowhere else does.} \message{and turning on texinfo input format.} +\def^^L{\par} % remove \outer, so ^L can appear in an @comment + % DEL is a comment character, in case @c does not suffice. \catcode`\^^? = 14 % Define macros to output various characters with catcode for normal text. -\catcode`\"=\other -\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 +\catcode`\"=\other \def\normaldoublequote{"} +\catcode`\$=\other \def\normaldollar{$}%$ font-lock fix +\catcode`\+=\other \def\normalplus{+} +\catcode`\<=\other \def\normalless{<} +\catcode`\>=\other \def\normalgreater{>} +\catcode`\^=\other \def\normalcaret{^} +\catcode`\_=\other \def\normalunderscore{_} +\catcode`\|=\other \def\normalverticalbar{|} +\catcode`\~=\other \def\normaltilde{~} % This macro is used to make a character print one way in \tt % (where it can probably be output as-is), and another way in other fonts, @@ -9221,16 +9549,16 @@ directory should work if nowhere else does.} % the literal character `\'. % @def@normalturnoffactive{% - @let\=@normalbackslash @let"=@normaldoublequote - @let~=@normaltilde + @let$=@normaldollar %$ font-lock fix + @let+=@normalplus + @let<=@normalless + @let>=@normalgreater + @let\=@normalbackslash @let^=@normalcaret @let_=@normalunderscore @let|=@normalverticalbar - @let<=@normalless - @let>=@normalgreater - @let+=@normalplus - @let$=@normaldollar %$ font-lock fix + @let~=@normaltilde @markupsetuplqdefault @markupsetuprqdefault @unsepspaces @@ -9262,10 +9590,16 @@ directory should work if nowhere else does.} % Say @foo, not \foo, in error messages. @escapechar = `@@ +% These (along with & and #) are made active for url-breaking, so need +% active definitions as the normal characters. +@def@normaldot{.} +@def@normalquest{?} +@def@normalslash{/} + % These look ok in all fonts, so just make them not special. -@catcode`@& = @other -@catcode`@# = @other -@catcode`@% = @other +@catcode`@& = @other @def@normalamp{&} +@catcode`@# = @other @def@normalhash{#} +@catcode`@% = @other @def@normalpercent{%} @c Finally, make ` and ' active, so that txicodequoteundirected and @c txicodequotebacktick work right in, e.g., @w{@code{`foo'}}. If we diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 542e649aea..2663d2df0f 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -37,8 +37,7 @@ @end macro @copying -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -105,11 +104,6 @@ If you're using the other Emacs flavor, you should read the @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 @@ -171,7 +165,6 @@ 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 @@ -449,9 +442,6 @@ Support of gateways exists since April 2007. @ifset emacsgvfs GVFS integration started in February 2009. @end ifset -@ifset emacsimap -Storing files into IMAP mailboxes has been added in September 2009. -@end ifset In December 2001, @value{tramp} has been added to the XEmacs package repository. Being part of the Emacs repository happened in June 2002, @@ -624,10 +614,6 @@ 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 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 @@ -705,6 +691,14 @@ 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{ksu} +@cindex method ksu +@cindex ksu method +@cindex Kerberos (with ksu method) + +This is another method from the Kerberos suite. It behaves like @option{su}. + + @item @option{plink} @cindex method plink @cindex plink method @@ -736,19 +730,6 @@ expects PuTTY session names, calling @samp{plink -load @var{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 @@ -808,10 +789,6 @@ 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 @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 @@ -975,7 +952,7 @@ anyway. @cindex method ftp @cindex ftp method -This is not a native @value{tramp} method. Instead of, it forwards all +This is not a native @value{tramp} method. Instead, it forwards all requests to @value{ftppackagename}. @ifset xemacs This works only for unified filenames, see @ref{Issues}. @@ -990,20 +967,20 @@ 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 +far, it is tested against 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 +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. +Since authorization is done on share level, you will always be +prompted for a password if you access another share on the same host. This can be suppressed by @ref{Password handling}. -MS Windows uses for authorization both a user name and a domain name. +For authorization, MS Windows uses 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 @@ -1027,33 +1004,10 @@ methods, where in such a case the local user name is taken. The @option{smb} method supports the @samp{-p} argument. @strong{Please note:} If @value{emacsname} runs locally under MS -Windows, this method isn't available. Instead of, you can use UNC +Windows, this method isn't available. Instead, 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. - - -@ifset emacsimap -@item @option{imap} -@cindex method imap -@cindex method imaps -@cindex imap method -@cindex imaps method - -Accessing an IMAP mailbox is intended to save files there as encrypted -message. It could be used in case there are no other remote file -storages available. - -@value{tramp} supports both @option{imap} and @option{imaps} methods. -The latter one accesses the IMAP server over ssl. - -Both methods support the port number specification. - -Note, that special handling is needed for declaring a passphrase for -encryption / decryption of the messages (@pxref{Using an -authentication file}). - -@end ifset @end table @@ -1067,7 +1021,7 @@ authentication file}). The connection methods described in this section are based on GVFS @uref{http://en.wikipedia.org/wiki/GVFS}. Via GVFS, the remote filesystem is mounted locally through FUSE. @value{tramp} uses -internally this local mounted directory. +this local mounted directory internally. The communication with GVFS is implemented via D-Bus messages. Therefore, your @value{emacsname} must have D-Bus integration, @@ -1092,7 +1046,7 @@ Both methods support the port number specification as discussed above. @cindex obex method OBEX is an FTP-like access protocol for simple devices, like cell -phones. Until now @value{tramp} supports only OBEX over Bluetooth. +phones. For the time being, @value{tramp} only supports OBEX over Bluetooth. @item @option{synce} @@ -1101,11 +1055,11 @@ phones. Until now @value{tramp} supports only OBEX over Bluetooth. The @option{synce} method allows communication with Windows Mobile devices. Beside GVFS for mounting remote files and directories via -FUSE, it needs also the SYNCE-GVFS plugin. +FUSE, it also needs the SYNCE-GVFS plugin. @end table @defopt tramp-gvfs-methods -This customer option, a list, defines the external methods, which +This customer option, a list, defines the external methods which shall be used with GVFS. Per default, these are @option{dav}, @option{davs}, @option{obex} and @option{synce}. Other possible values are @option{ftp}, @option{sftp} and @option{smb}. @@ -1124,10 +1078,10 @@ 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 +A gateway method must always come along with a method which supports port setting. This is because @value{tramp} targets the accompanied method to @file{localhost#random_port}, from where the firewall or -proxy server is accessed to. +proxy server is accessed. Gateway methods support user name and password declarations. These are used to authenticate towards the corresponding firewall or proxy @@ -1644,18 +1598,6 @@ The port can be any @value{tramp} method (@pxref{Inline methods}, @pxref{External methods}), to match only this method. When you omit the port, you match all @value{tramp} methods. -@ifset emacsimap -A special case are @option{imap}-like methods. Authentication with -the IMAP server is performed via @file{imap.el}, there is no special -need from @value{tramp} point of view. An additional passphrase, used -for symmetric encryption and decryption of the stored messages, should -be given with the special port indication @option{tramp-imap}: - -@example -machine melancholia port tramp-imap login daniel password ultrageheim -@end example -@end ifset - @anchor{Caching passwords} @subsection Caching passwords @@ -1730,7 +1672,7 @@ multiple hops (@pxref{Multi-hops}). When @value{tramp} detects a changed operating system version on a remote host (via the command @command{uname -sr}), it flushes all connection related information for this host, and opens the -connection, again. +connection again. @node Remote Programs @@ -1786,7 +1728,7 @@ as: @end lisp Another possibility is to reuse the path settings of your remote -account, when you log in. Usually, these settings are overwritten, +account when you log in. Usually, these settings are overwritten, because they might not be useful for @value{tramp}. The place holder @code{tramp-own-remote-path} preserves these settings. You can activate it via @@ -1969,7 +1911,7 @@ 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 +@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. @@ -1996,6 +1938,38 @@ 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? + +@item Interactive shell prompt + +@value{tramp} redefines the shell prompt in order to parse the shell's +output robustly. When calling an interactive shell by @kbd{M-x +shell}, this doesn't look nice. + +You can redefine the shell prompt by checking the environment variable +@code{INSIDE_EMACS}, which is set by @value{tramp}, in your startup +script @file{~/.emacs_SHELLNAME}. @code{SHELLNAME} might be the string +@code{bash} or similar, in case of doubt you could set it the +environment variable @code{ESHELL} in your @file{.emacs}: + +@lisp +(setenv "ESHELL" "bash") +@end lisp + +Your file @file{~/.emacs_SHELLNAME} could contain code like + +@example +# Reset the prompt for remote Tramp shells. +if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then + PS1="[\u@@\h \w]$ " +fi +@end example + +@ifinfo +@ifset emacs +@xref{Interactive Shell, , , @value{emacsdir}}. +@end ifset +@end ifinfo + @end table @@ -2414,8 +2388,8 @@ 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. +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 @@ -2455,8 +2429,8 @@ Example: A remote directory might have changed its contents out of @value{emacsname} control, for example by creation or deletion of -files by other processes. Therefore, during filename completion the -remote directory contents is reread regularly in order to detect such +files by other processes. Therefore, during filename completion, the +remote directory contents are reread regularly in order to detect such changes, which would be invisible otherwise (@pxref{Connection caching}). @defopt tramp-completion-reread-directory-timeout @@ -2478,6 +2452,15 @@ remote file names. It does not work for the @option{ftp} and @option{smb} methods. Association of a pty, as specified in @code{start-file-process}, is not supported. +@code{process-file} and @code{start-file-process} work on the remote +host when the variable @code{default-directory} is remote: + +@lisp +(let ((default-directory "/ssh:remote.host:")) + (start-file-process "grep" (get-buffer-create "*grep*") + "/bin/sh" "-c" "grep -e tramp *")) +@end lisp + @ifset emacsgvfs If the remote host is mounted via GVFS (see @ref{GVFS based methods}), the remote filesystem is mounted locally. Therefore, there are no @@ -2520,7 +2503,7 @@ Adding an entry can be performed via @code{add-to-list}: 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{HISTORY} environment variable, you can customize @code{tramp-remote-process-environment}, or you can apply the following code in your @file{.emacs}: @@ -2539,7 +2522,7 @@ integrate them as well. @xref{Bug Reports}. If you want to run a remote program, which shall connect the X11 server you are using with your local host, you can set the -@var{$DISPLAY} environment variable on the remote host: +@code{DISPLAY} environment variable on the remote host: @lisp (add-to-list 'tramp-remote-process-environment @@ -2557,7 +2540,28 @@ Another trick might be that you put @code{ForwardX11 yes} or that host. -@subsection Running shell-command on a remote host +@subsection Running @code{shell} on a remote host +@cindex shell + +Calling @code{M-x shell} in a buffer related to a remote host runs the +local shell as defined in @option{shell-file-name}. This might be +also a valid path name for a shell to be applied on the remote host, +but it will fail at least when your local and remote hosts belong to +different system types, like @samp{windows-nt} and @samp{gnu/linux}. + +You must set the variable @option{explicit-shell-file-name} to the +shell path name on the remote host, in order to start that shell on +the remote host. + +@ifset emacs +Starting with Emacs 24 this won't be necessary, if you call +@code{shell} interactively. You will be asked for the remote shell +path, if you are on a remote buffer, and if +@option{explicit-shell-file-name} is equal to @code{nil}. +@end ifset + + +@subsection Running @code{shell-command} on a remote host @cindex shell-command @code{shell-command} allows to execute commands in a shell, either @@ -2573,13 +2577,13 @@ You will see the buffer @file{*Async Shell Command*}, containing the continuous output of the @command{tail} command. -@subsection Running eshell on a remote host +@subsection Running @code{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: +After you have started @code{M-x eshell}, you could perform commands +like this: @example @b{~ $} cd @trampfn{sudo, , , /etc} @key{RET} @@ -2757,13 +2761,13 @@ There is also a Savannah project page. @item Which systems does it work on? -The package has been used successfully on Emacs 22, Emacs 23, XEmacs -21 (starting with 21.4), and SXEmacs 22. +The package has been used successfully on Emacs 22, Emacs 23, Emacs +24, XEmacs 21 (starting with 21.4), and SXEmacs 22. The package was intended to work on Unix, and it really expects a -Unix-like system on the remote end (except the @option{smb} and -@option{imap} methods), but some people seemed to have some success -getting it to work on MS Windows XP/Vista/7 @value{emacsname}. +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 XP/Vista/7 @value{emacsname}. @item @@ -2780,7 +2784,10 @@ Use an external method, like @option{scpc}. Use caching. This is already enabled by default. Information about the remote host as well as the remote files are cached for reuse. The information about remote hosts is kept in the file specified in -@code{tramp-persistency-file-name}. Keep this file. +@code{tramp-persistency-file-name}. Keep this file. If you are +confident that files on remote hosts are not changed out of +@value{emacsname}' control, set @code{remote-file-name-inhibit-cache} +to @code{nil}. Disable version control. If you access remote files which are not under version control, a lot of check operations can be avoided by @@ -2805,12 +2812,11 @@ When @value{tramp} does not connect to the remote host, there are three 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 +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. @@ -2875,7 +2881,6 @@ checksum. (when (file-remote-p default-directory) (set (make-local-variable 'file-precious-flag) t)))) @end lisp - @end itemize @@ -2885,7 +2890,7 @@ checksum. When your network connection is down, @command{ssh} sessions might hang. @value{tramp} cannot detect it safely, because it still sees a running @command{ssh} process. Timeouts cannot be used as well, -because it cannot be predicted, how long a remote command will last, +because it cannot be predicted how long a remote command will last, for example when copying very large files. Therefore, you must configure the @command{ssh} process to die @@ -3095,7 +3100,7 @@ You can define default methods and user names for hosts, 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 +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, , ,}}. @@ -3127,7 +3132,7 @@ Lisp: @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 +are. The disadvantage is that you cannot edit the file name, because environment variables are not expanded during editing in the minibuffer. @@ -3299,7 +3304,7 @@ You need to load @file{bbdb}: 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: +specify a method together with the user name when needed. Example: @example @kbd{M-x bbdb-create-ftp-site @key{RET}} @@ -3316,7 +3321,7 @@ pressing the key @key{F}. @end enumerate -I would like to thank all @value{tramp} users, who have contributed to +I would like to thank all @value{tramp} users who have contributed to the different recipes! @@ -3339,7 +3344,7 @@ On the remote host, you start the Emacs Server: (server-start) @end lisp -Make sure, that the result of @code{(system-name)} can be resolved on +Make sure that the result of @code{(system-name)} can be resolved on your local host; otherwise you might use a hard coded IP address. The resulting file @file{~/.emacs.d/server/server} must be copied to @@ -3370,14 +3375,43 @@ export EDITOR=/path/to/emacsclient.sh @item -How can I disable @value{tramp}? +There are packages which call @value{tramp} although I haven't entered +a remote file name ever. I dislike it, how could I disable it? -Shame on you, why did you read until now? +In general, @value{tramp} functions are used only when +you apply remote file name syntax. However, some packages enable +@value{tramp} on their own. @itemize @minus +@item +@file{ido.el} + +You could disable @value{tramp} file name completion: + +@lisp +(custom-set-variables + '(ido-enable-tramp-completion nil)) +@end lisp + +@item +@file{rlogin.el} + +You could disable remote directory tracking mode: + +@lisp +(rlogin-directory-tracking-mode -1) +@end lisp +@end itemize + @item +How can I disable @value{tramp} at all? + +Shame on you, why did you read until now? + +@itemize @minus @ifset emacs +@item If you just want to have @value{ftppackagename} as default remote files access package, you should apply the following code: @@ -3473,7 +3507,7 @@ its complete cache keeping attributes for all files of the remote host it has seen so far. This is a performance degradation, because the lost file attributes -must be recomputed, when needed again. In cases the caller of +must be recomputed when needed again. In cases the caller of @code{process-file} knows that there are no file attribute changes, it shall let-bind the variable @code{process-file-side-effects} to @code{nil}. @value{tramp} wouldn't flush the file attributes cache then. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 6e0674c4cb..6a245f9c28 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -2,14 +2,13 @@ @c texi/trampver.texi. Generated from trampver.texi.in by configure. @c This is part of the Emacs manual. -@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, -@c 2011 Free Software Foundation, Inc. +@c Copyright (C) 2003-2011 Free Software Foundation, Inc. @c See file doclicense.texi for copying conditions. @c In the Tramp CVS, the version number is auto-frobbed from @c configure.ac, so you should edit that file and run @c "autoconf && ./configure" to change the version number. -@set trampver 2.1.21-pre +@set trampver 2.2.2-pre @c Other flags from configuration @set instprefix /usr/local @@ -29,11 +28,6 @@ @set emacsgw @end ifclear -@c Whether or not describe IMAP support. -@ifclear noemacsimap -@set emacsimap -@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 @@ -56,7 +50,6 @@ @set emacsothername XEmacs @set emacsotherdir xemacs @set emacsotherfilename tramp-xemacs.html -@set japanesemanual tramp_ja-emacs.html @end ifset @c XEmacs counterparts. @@ -73,5 +66,4 @@ @set emacsothername Emacs @set emacsotherdir emacs @set emacsotherfilename tramp-emacs.html -@set japanesemanual tramp_ja-xemacs.html @end ifset diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 7e65e5c867..42594457ab 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -20,8 +20,7 @@ @copying This file documents the Emacs Lisp URL loading package. -Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002, -2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1993-1999, 2002, 2004-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -117,7 +116,10 @@ The meaning of the @var{path} component depends on the service. @cindex @file{~/.url} @cindex configuration files The directory in which URL configuration files, the cache etc., -reside. Default @file{~/.url}. +reside. The old default was @file{~/.url}, and this directory +is still used if it exists. The new default is a @file{url/} +directory in @code{user-emacs-directory}, which is normally +@file{~/.emacs.d}. @end defvar @node Parsed URLs @@ -384,20 +386,7 @@ Currently this is just the raw header contents. 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{<meta>} elements. -@end defun +emacs-mime, The Emacs MIME Manual}. @node file/ftp @section file and ftp @@ -730,14 +719,6 @@ 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. @@ -767,6 +748,22 @@ more likely to conflict with other files. @end smallexample @end defun +@defun url-cache-expired +This function returns non-nil if a cache entry has expired (or is absent). +The arguments are a URL and optional expiration delay in seconds +(default @var{url-cache-expire-time}). +@end defun + +@defopt url-cache-expire-time +This variable is the default number of seconds to use for the +expire-time argument of the function @code{url-cache-expired}. +@end defopt + +@defun url-fetch-from-cache +This function takes a URL as its argument and returns a buffer +containing the data cached for that URL. +@end defun + @c Fixme: never actually used currently? @c @defopt url-standalone-mode @c @cindex Relying on cache @@ -1185,7 +1182,3 @@ Connect directly. @printindex cp @bye - -@ignore - arch-tag: c96be356-7e2d-4196-bcda-b13246c5c3f0 -@end ignore diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi index 539f6fe2c3..03ca65882e 100644 --- a/doc/misc/vip.texi +++ b/doc/misc/vip.texi @@ -3,8 +3,7 @@ @settitle VIP @copying -Copyright @copyright{} 1987, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1987, 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1946,7 +1945,3 @@ file. @printindex cp @bye - -@ignore - arch-tag: 7c5d17b9-1d21-4261-a88a-b9fdbbf1020b -@end ignore diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 0482f78ba1..1f0dffee5b 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -7,8 +7,7 @@ @setfilename ../../info/viper @copying -Copyright @copyright{} 1995, 1996, 1997, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-1997, 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -4558,7 +4557,3 @@ zapman@@cc.gatech.edu (Jason Zapman II), @printindex cp @bye - -@ignore - arch-tag: f53e866a-15cf-4b1e-aead-77da9da1e864 -@end ignore diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi index ac111870f3..c4f5317e5a 100644 --- a/doc/misc/widget.texi +++ b/doc/misc/widget.texi @@ -8,8 +8,7 @@ @c %**end of header @copying -Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2000-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1829,7 +1828,3 @@ variables, and widgets described in this manual. @printindex cp @bye - -@ignore - arch-tag: 2b427731-4c61-4e72-85de-5ccec9c623f0 -@end ignore diff --git a/doc/misc/woman.texi b/doc/misc/woman.texi index 975a9c408f..c869d1a46c 100644 --- a/doc/misc/woman.texi +++ b/doc/misc/woman.texi @@ -18,8 +18,7 @@ This file documents WoMan: A program to browse Unix manual pages `W.O. (without) man'. -Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, -2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2001-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1121,8 +1120,8 @@ A regular match expression used to match compressed man file extensions for which decompressors are available and handled by auto-compression mode. It should begin with @code{\\.} and end with @code{\\'} and @emph{must not} be optional. The default value is -@code{"\\.\\(g?z\\|bz2\\)\\'"}, which matches the @code{gzip} and -@code{bzip2} compression extensions. +@code{"\\.\\(g?z\\|bz2\\|xz\\)\\'"}, which matches the @code{gzip}, +@code{bzip2}, and @code{xz} compression extensions. @emph{Do not change this unless you are sure you know what you are doing!} @@ -1430,7 +1429,3 @@ Eli Zaretskii, @email{eliz@@is.elta.co.il} @printindex cp @bye - -@ignore - arch-tag: a1a6b715-396f-4378-9b94-0b2ca0aa5028 -@end ignore |