diff options
| author | Ken Raeburn <raeburn@raeburn.org> | 2015-11-01 01:42:21 -0400 |
|---|---|---|
| committer | Ken Raeburn <raeburn@raeburn.org> | 2015-11-01 01:42:21 -0400 |
| commit | 39372e1a1032521be74575bb06f95a3898fbae30 (patch) | |
| tree | 754bd242a23d2358ea116126fcb0a629947bd9ec /doc | |
| parent | 6a3121904d76e3b2f63007341d48c5c1af55de80 (diff) | |
| parent | e11aaee266da52937a3a031cb108fe13f68958c3 (diff) | |
| download | emacs-39372e1a1032521be74575bb06f95a3898fbae30.tar.gz | |
merge from trunk
Diffstat (limited to 'doc')
211 files changed, 29734 insertions, 14901 deletions
diff --git a/doc/emacs/.gitignore b/doc/emacs/.gitignore deleted file mode 100644 index 3ff56b474dd..00000000000 --- a/doc/emacs/.gitignore +++ /dev/null @@ -1,23 +0,0 @@ -*.aux -*.cp -*.cps -*.dvi -*.fn -*.fns -*.ky -*.kys -*.log -*.op -*.ops -*.pdf -*.pg -*.pgs -*.ps -*.tmp -*.toc -*.tp -*.tps -*.vr -*.vrs -Makefile -makefile diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog.1 index f94db60f25f..469fdc39cea 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog.1 @@ -1,3 +1,946 @@ +2015-03-29 Dani Moncayo <dmoncayo@gmail.com> + + * files.texi (Diff Mode): Doc fix. + +2015-03-18 Eli Zaretskii <eliz@gnu.org> + + * misc.texi (Term Mode): + * programs.texi (Basic Indent, Custom C Indent): + * mini.texi (Minibuffer History): + * text.texi (Org Mode): + * display.texi (View Mode): Use @kbd where @key was mistakenly + used. (Bug#20135) + +2015-03-18 Eli Zaretskii <eliz@gnu.org> + + * basic.texi (Moving Point): Improve indexing for HOME and END. + + * cmdargs.texi (General Variables): Improve indexing for + environment variables. + + * msdog.texi (Windows HOME): + * msdog-xtra.texi (MS-DOS File Names): Remove markup from HOME in + the index entries. (Bug#20105) + +2015-02-26 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (Windows Files): Document characters invalid in + Windows file names. (Bug#19463) + + * custom.texi (Customization Groups): Update the looks of the + Customize Group buffer. + + * programs.texi (Hungry Delete): Fix a typo: "C-d" instead of + "C-c C-d" in hungry-delete mode. + +2015-02-26 Eli Zaretskii <eliz@gnu.org> + + * mule.texi (Language Environments): Work around refill bug in + makeinfo 4.x. (Bug#19697) + +2015-01-28 Eli Zaretskii <eliz@gnu.org> + + * cmdargs.texi (Action Arguments): Clarify into which buffer + '--insert' inserts. (Bug#19694) + + * programs.texi (Custom C Indent): Fix a typo. (Bug#19647) + +2015-01-27 Ivan Shmakov <ivan@siamics.net> + + * files.texi (File Archives): Document "I" for tar-new-entry. + (Bug#19274) + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/emacs.info, emacs.html): + Use them. + +2014-12-27 Eli Zaretskii <eliz@gnu.org> + + * buffers.texi (Kill Buffer): Improve indexing. + +2014-12-24 Stephen Leake <stephen_leake@stephe-leake.org> + + * trouble.texi: Move user-level information from CONTRIBUTE here. + +2014-12-14 Alan Mackenzie <acm@muc.de> + + * display.texi (Scrolling): fast-but-imprecise-scrolling. + Describe new variable. + +2014-12-14 Cameron Desautels <camdez@gmail.com> + + * custom.texi (Saving Customizations): Mention + `custom-prompt-customize-unsaved-options'. + +2014-12-08 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * misc.texi (Network Security): Mention the new protocol-level + `high' NSM checks. + +2014-12-08 Eric S. Raymond <esr@snark.thyrsus.com> + + * maintaining.texi: Suopport fo Arch has been moved to obosolete, + remove references that imply otherwise. + +2014-11-29 Paul Eggert <eggert@cs.ucla.edu> + + Lessen focus on ChangeLog files, as opposed to change log entries. + * maintaining.texi (Change Log): Mention that ChangeLog files may + be copied to or from a version control system. + * trouble.texi (Sending Patches): Point to the commit messages. + +2014-11-29 Eli Zaretskii <eliz@gnu.org> + + * maintaining.texi (Switching Branches): Mention "C-x v r". + Correct commands for switching branches in various VCSs. + +2014-11-27 Tassilo Horn <tsdh@gnu.org> + + * misc.texi (DocView Slicing): Describe how to slice with the + mouse. Fix command mentioned by slice by BoundingBox paragraph. + (Bug#18040) + +2014-11-25 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * misc.texi (Network Security): Use "untrustworthy" instead of + "unsafe". + +2014-11-24 Eli Zaretskii <eliz@gnu.org> + + * misc.texi (Network Security): Improve wording and indexing of + last change. + +2014-11-24 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * misc.texi (Gnus Summary Buffer): Move the Network Security + Manager stuff here from the lispref manual. + +2014-11-21 Eli Zaretskii <eliz@gnu.org> + + * maintaining.texi (Version Control Systems): Move "@end itemize" + past the last @item. + +2014-11-21 H. Dieter Wilhelm <dieter@duenenhof-wilhelm.de> + + * maintaining.texi (Version Control Systems): Fix a typo. + +2014-11-20 Eric S. Raymond <esr@snark.thyrsus.com> + + * maintaining.texi: Document SRC support. + +2014-11-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (top_srcdir, version): New, set by configure. + (doc-emacsver): New rule. + (bootstrap-clean, maintainer-clean): Delete emacsver.texi. + (emacsver.texi.in): Rename from emacsver.texi. + +2014-11-09 Juri Linkov <juri@jurta.org> + + * search.texi (Other Repeating Search): Add documentation for + multi-isearch-files and multi-isearch-files-regexp. (Bug#13592) + +2014-11-09 Glenn Morris <rgm@gnu.org> + + * Makefile.in (version): Remove variable. + (clean): No longer delete dist tarfile. + (dist): Remove rule; replace with code in admin.el. + +2014-11-03 Glenn Morris <rgm@gnu.org> + + * programs.texi (Misc for Programs): Fix typo. + +2014-10-30 Eli Zaretskii <eliz@gnu.org> + + * frames.texi (Scroll Bars): Improve indexing of faces. + + * killing.texi (Secondary Selection): Improve indexing of faces. + + * search.texi (Basic Isearch, Query Replace): Improve indexing of faces. + + * display.texi (Standard Faces, Text Display) + (Useless Whitespace): Improve indexing of faces. + + * frames.texi (Frame Commands): Document and index + 'frame-resize-pixelwise'. + + * windows.texi (Split Window): Document and index + 'window-resize-pixelwise'. + +2014-10-22 Tassilo Horn <tsdh@gnu.org> + + * misc.texi (Document View): Adapt to latest doc-view changes wrt + viewing the document's plain text contents. + +2014-10-20 Glenn Morris <rgm@gnu.org> + + * Merge in all changes up to 24.4 release. + +2014-10-13 Glenn Morris <rgm@gnu.org> + + * Makefile.in (dist): Update for new output variables. + +2014-10-12 Paul Eggert <eggert@cs.ucla.edu> + + * macos.texi (Mac OS / GNUstep, Mac / GNUstep Basics) + (Mac / GNUstep Customization): Mac OS X 10.6 or later now required. + +2014-10-09 Glenn Morris <rgm@gnu.org> + + * package.texi (Package Menu): The package list was changed to not + say "unsigned" any more. + +2014-10-05 Glenn Morris <rgm@gnu.org> + + * misc.texi (Sorting): + * search.texi (Query Replace): Markup fixes. + +2014-10-04 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Scroll Bars): Describe use of horizontal scroll bars. + +2014-10-04 Glenn Morris <rgm@gnu.org> + + * cmdargs.texi (Misc X): + * display.texi (Optional Mode Line): + * misc.texi (emacsclient Options): + * vc1-xtra.texi (VC Delete/Rename): Small fixes re @var usage. + + * killing.texi (Rectangles): Copyedits re rectangle-mark-mode. + (CUA Bindings): Mention rectangle-mark-mode. + +2014-10-03 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Frame Commands): + * cmdargs.texi (Window Size X): Mention the use of + `frame-resize-pixelwise' to make frames truly fullscreen or maximized. + +2014-10-02 Glenn Morris <rgm@gnu.org> + + * package.texi (Package Installation): Mention etc/package-keyring.gpg. + +2014-09-29 Eli Zaretskii <eliz@gnu.org> + + * emacsver.texi (EMACSVER): Bump to 20.0.50. + +2014-09-15 Daniel Colascione <dancol@dancol.org> + + * regs.texi (Text Registers): Update end-user documentation + to reflect `insert-register' interface change. + +2014-08-07 Reuben Thomas <rrt@sc3d.org> + + * programs.texi (Program Modes): Don't advertise VMS DCL support + any more. + +2014-08-07 Reuben Thomas <rrt@sc3d.org> + + Refer to MS-DOS using the same name everywhere. + + * Makefile.in (EMACSSOURCES): ``MS-DOG'', ``MSDOG'' and ``msdog'' + become ``MS-DOS''; ``msdog'' in filenames becomes ``msdos''. + * emacs-xtra.texi: ditto. + * emacs.texi: ditto. + * makefile.w32-in: ditto. + * msdog-xtra.texi: ditto, and rename file. + * msdog.texi: ditto, and rename file. + +2014-07-21 Glenn Morris <rgm@gnu.org> + + * emacs.texi (Intro): Workaround makeinfo 4 @acronym bug. (Bug#18040) + +2014-07-09 Juri Linkov <juri@jurta.org> + + * search.texi (Regexp Search): Update lax space matching that is + not active in regexp search by default now. (Bug#17901) + +2014-07-03 Glenn Morris <rgm@gnu.org> + + * help.texi (Misc Help): + * trouble.texi (Checklist): "Online" help doesn't mean what it + used to any more. + +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with pattern rule. + (${buildinfodir}): New rule. + ($(buildinfodir)/emacs.info): Use order-only prereq for output dir. + Use $<. + (emacs.dvi, emacs.pdf, emacs.html, emacs-xtra.dvi, emacs-xtra.pdf): + Use $<. + (%.ps): New rule. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-08 Glenn Morris <rgm@gnu.org> + + * entering.texi (Entering Emacs): Small fix re initial-buffer-choice. + * misc.texi (emacsclient Options): Copyedit. + + * buffers.texi (Uniquify): Copyedits. + * files.texi (Visiting): Update for uniquify changes. + + * dired.texi (Marks vs Flags): + * rmail.texi (Rmail Scrolling): Markup fixes re SPC. + + * help.texi (Help, Misc Help): Copyedits. + + * screen.texi (Menu Bar): Copyedits. + * msdog.texi (Windows Keyboard): F10 menus are now a general feature. + + * frames.texi (Frame Commands): Copyedits re M-F10, F11. + * cmdargs.texi (Window Size X): Copyedits. + + * ack.texi (Acknowledgments): + * emacs.texi (Acknowledgments): Updates. + +2014-06-08 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): + * emacs.texi (Acknowledgments): Updates. + + * programs.texi (Prettifying Symbols): Remove node. + (Misc for Programs): Mention more briefly here. + * emacs.texi (Top): Update menu. + + * package.texi (Package Menu, Package Installation): + Mention signed packages. + (Package Installation): Mention package-pinned-packages. + +2014-06-02 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): Remove some obsolete items. + * misc.texi [iftex]: Update chapter summary. + (Emulation): Remove section. + + * macos.texi (Mac / GNUstep Customization): Mention ns custom group. + (Customization options specific to Mac OS / GNUstep): Remove section. + + * abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function. + +2014-05-26 Eli Zaretskii <eliz@gnu.org> + + * frames.texi (Fonts): Clarify which frames are affected by + setting font from the menu and in default-frame-alist. + (Bug#17532) + +2014-05-14 Eli Zaretskii <eliz@gnu.org> + + * mule.texi (Language Environments): Remove unused @anchor. (Bug#17479) + +2014-05-04 Eli Zaretskii <eliz@gnu.org> + + * trouble.texi (Lossage, DEL Does Not Delete, Stuck Recursive) + (Screen Garbled, Text Garbled, After a Crash, Emergency Escape) + (Bug Criteria, Understanding Bug Reporting, Checklist, Service): + Improve indexing. + +2014-05-04 Leo Liu <sdl.web@gmail.com> + + * cal-xtra.texi (Non-Gregorian Diary): Document new features for + Chinese calendar and diary. + +2014-04-30 Eli Zaretskii <eliz@gnu.org> + + * trouble.texi (Quitting, DEL Does Not Delete, Emergency Escape) + (Bug Criteria): Fix usage of @kbd and @key. (Bug#17362) + + * text.texi (Words, Pages, Foldout, HTML Mode): Fix usage of @kbd + and @key. + + * search.texi (Special Isearch, Regexp Search): Fix usage of @kbd + and @key. + + * screen.texi (Echo Area, Menu Bar): Fix usage of @kbd and @key. + + * rmail.texi (Rmail Scrolling): Fix usage of @kbd and @key. + + * programs.texi (Hungry Delete, Other C Commands): Fix usage of + @kbd and @key. + + * picture-xtra.texi (Insert in Picture): Fix usage of @kbd and + @key. + + * mule.texi (Unibyte Mode, Bidirectional Editing): Fix usage of + @kbd and @key. + + * msdog.texi (Windows Keyboard, Windows Processes): Fix usage of + @kbd and @key. + + * msdog-xtra.texi (MS-DOS Keyboard, MS-DOS Printing) + (MS-DOS Processes): Fix usage of @kbd and @key. + + * misc.texi (Shell Ring, Printing Package): Fix usage of @kbd and + @key. + + * mini.texi (Completion Commands, Minibuffer History): Fix usage + of @kbd and @key. + + * kmacro.texi (Keyboard Macro Step-Edit): Fix usage of @kbd and + @key. + + * killing.texi (Deletion, Rectangles, CUA Bindings): Fix usage of + @kbd and @key. + + * indent.texi (Indentation Commands): Fix usage of @kbd and @key. + + * help.texi (Help Mode, Misc Help): Fix usage of @kbd and @key. + + * glossary.texi (Glossary): Fix usage of @kbd and @key. + + * frames.texi (Speedbar): Fix usage of @kbd and @key. + + * files.texi (Misc File Ops, File Name Cache, File Conveniences) + (Filesets): Fix usage of @kbd and @key. + + * display.texi (View Mode): Fix usage of @kbd and @key. + + * dired.texi (Image-Dired): Fix usage of @kbd and @key. + + * custom.texi (Modifier Keys, Function Keys, Named ASCII Chars) + (Init Syntax): Fix usage of @kbd and @key. + + * commands.texi (User Input): Fix usage of @kbd and @key. + + * calendar.texi (Counting Days, General Calendar): Fix usage of + @kbd and @key. + + * building.texi (Threads Buffer): Fix usage of @kbd and @key. + + * buffers.texi (Select Buffer, Icomplete): Fix usage of @kbd and + @key. + + * basic.texi (Inserting Text, Erasing, Arguments): Fix usage of + @kbd and @key. + + * anti.texi (Antinews): Fix usage of @kbd and @key. + + * sending.texi (Mail Signature): Document signature variables used + by Message mode. (Bug#17308) + +2014-04-22 Eli Zaretskii <eliz@gnu.org> + + * buffers.texi (Uniquify): Clarify the default uniquification. + + * indent.texi (Tab Stops): Improve wording. + + * cmdargs.texi (General Variables): Improve docs of + EMACSLOADPATH. Index all the environment variables. + (Misc Variables): Index all the environment variables. + +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + Do not fail merely because the info directory does not exist, + but do fail if it exists and can't be cleaned. + +2014-04-16 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Cursor Display): Explain better how to customize + 'blink-cursor-blinks'. + +2014-04-07 Glenn Morris <rgm@gnu.org> + + * trouble.texi (Checklist): Dribble files may contain passwords. + + * files.texi (Backup Names): + * arevert-xtra.texi (Supporting additional buffers): + Update for default values of some -function vars no longer being nil. + (Supporting additional buffers): + Update for buffer-stale-function also applying to file-buffers. + +2014-03-28 Glenn Morris <rgm@gnu.org> + + * custom.texi (Terminal Init): Mention term-file-aliases. + +2014-03-26 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): Remove reference to obsolete file. + +2014-03-22 Glenn Morris <rgm@gnu.org> + + * help.texi (Help Files): Update C-h g description. + +2014-03-16 Dmitry Gutov <dgutov@yandex.ru> + + * programs.texi (Matching): Update the missed spot. (Bug#17008) + +2014-03-15 Dmitry Gutov <dgutov@yandex.ru> + + * programs.texi (Matching): Update WRT to the new + `blink-matching-paren' behavior. + +2014-03-13 Paul Eggert <eggert@cs.ucla.edu> + + * mule.texi (International, Language Environments): + Update the list of language environments to what Emacs currently + supports. Add the full list to the index. Suggest C-h L for + details rather than trying to give very brief details here. + +2014-03-12 Glenn Morris <rgm@gnu.org> + + * cmdargs.texi (General Variables): Don't mention INCPATH, + from the obsolete complete.el. + +2014-03-12 Paul Eggert <eggert@cs.ucla.edu> + + * mule.texi (International Chars): Adjust C-u C-x = description. + Change it to match Emacs's current behavior. Also, change the + example to use ê instead of À, as the isolated grave accent in the + latter's decomposition listing was confusingly transliterated to + left single quote in the PDF version of the manual. + +2014-03-12 Glenn Morris <rgm@gnu.org> + + * misc.texi (Saving Emacs Sessions): Be briefer about desktop's + handling of frames. + + * indent.texi (Indent Convenience): Mention electric-indent-local-mode. + +2014-03-02 Xue Fuqiao <xfq@gnu.org> + + * mark.texi (Mark): + * killing.texi (Rectangles): Document `rectangle-mark-mode'. + +2014-03-01 Glenn Morris <rgm@gnu.org> + + * search.texi (Query Replace): Mention search-invisible. + * text.texi (Outline Visibility): Mention search-invisible + also affects query-replace. + +2014-02-28 Xue Fuqiao <xfq@gnu.org> + + * emacs.texi (Top): + * programs.texi (Programs, Prettifying Symbols): + Document `prettify-symbols-mode' and `global-prettify-symbols-mode'. + + * misc.texi (Saving Emacs Sessions): + Document some new desktop user options. + +2014-02-27 Xue Fuqiao <xfq@gnu.org> + + * programs.texi (Basic Indent, Other C Commands): + Fix the description of RET and `C-j'. + + * indent.texi (Indentation Commands): Move the description of + `C-j' from here... + * basic.texi (Inserting Text): ... to here. + +2014-02-25 Glenn Morris <rgm@gnu.org> + + * custom.texi (Terminal Init): + Replace term-setup-hook with tty-setup-hook. + +2014-02-23 Glenn Morris <rgm@gnu.org> + + * rmail.texi (Rmail Inbox): Mention rmail-mbox-format. + +2014-02-20 Glenn Morris <rgm@gnu.org> + + * search.texi (Special Isearch): Mention invisible text. + * text.texi (Outline Visibility): Mention `M-s i' in isearch. + +2014-02-18 Glenn Morris <rgm@gnu.org> + + * trouble.texi (Contributing) [WWW_GNU_ORG]: Link to + gnu.org version of etc/CONTRIBUTE in html output. + + * misc.texi (Saving Emacs Sessions): Mention desktop-auto-save-timeout. + +2014-02-17 Stefan Monnier <monnier@iro.umontreal.ca> + + * programs.texi (Matching): Fix typo. + + * killing.texi (CUA Bindings): Document the new relationship between + cua-mode and delete-selection mode. + (CUA Bindings): Mention that rectangle mode can be used on its own. + +2014-02-14 Glenn Morris <rgm@gnu.org> + + * regs.texi (Configuration Registers): Update C-x r f binding. + +2014-02-12 Glenn Morris <rgm@gnu.org> + + * mini.texi (Completion Options): No longer mention icomplete, + which has its own section now. + * modes.texi (Minor Modes): Update Icomplete xref. + + * help.texi (Package Keywords): Mention describe-package buttons. + + * package.texi (Package Menu): Mention package-menu-filter. + +2014-02-11 Lars Ingebrigtsen <larsi@gnus.org> + + * text.texi (Editing Format Info): Use @samp for menus (bug#13736). + +2014-02-09 Lars Ingebrigtsen <larsi@gnus.org> + + * dired.texi (Hiding Subdirectories): Mention the node for + deleting subdirectories (bug#11743). + +2014-02-09 Glenn Morris <rgm@gnu.org> + + * programs.texi (MixedCase Words): Rename node from "Glasses". + Move Subword mode here from "Other C Commands" node. + (Misc for Programs): Mention Superword mode. + * emacs.texi: Update menu. + +2014-02-08 Lars Ingebrigtsen <larsi@gnus.org> + + * regs.texi (File Registers): Clarify metasyntactical variables + (bug#13565). + + * search.texi (Search Case): Rearrange text slightly to make it + obvious that `M-c' also toggles sensitivity if `case-fold-search' + is nil (bug#14726). + + * frames.texi (Mouse Commands): Clarify `mouse-yank-at-click' + (bug#16376). + +2014-02-07 Glenn Morris <rgm@gnu.org> + + * display.texi (Highlight Interactively): + Mention hi-lock-auto-select-face. + + * anti.texi (Antinews): Fix typo. + + * ack.texi (Acknowledgments): No longer mention obsolete files. + +2014-02-02 Glenn Morris <rgm@gnu.org> + + * regs.texi (Registers): Mention previewing. + +2014-01-29 Glenn Morris <rgm@gnu.org> + + * killing.texi (Deletion): Mention cycle-spacing. + +2014-01-28 Glenn Morris <rgm@gnu.org> + + * text.texi (Fill Commands): Mention fill-single-char-nobreak-p. + + * indent.texi (Tab Stops): Updates for new tab-stop behavior. + +2014-01-27 Glenn Morris <rgm@gnu.org> + + * dired.texi (Misc Dired Features): Copyedits for hide-details. + + * buffers.texi (List Buffers): Tiny edit. + + * calendar.texi (Time Intervals): Update for files in ~/.emacs.d/. + +2014-01-26 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): + * programs.texi (Program Modes): + Update for delphi.el -> opascal.el renaming. + + * misc.texi (Sorting): Add findex for reverse-region. + + * killing.texi (Deletion): Mention delete-duplicate-lines. + +2014-01-24 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): No longer mention obsolete xesam.el, + terminal.el. + + * files.texi (Interlocking): Copyedit. + +2014-01-23 Glenn Morris <rgm@gnu.org> + + * building.texi (Lisp Eval): Update prefix argument behavior + of eval-expression, eval-last-sexp. + +2014-01-17 Bastien Guerry <bzg@gnu.org> + + * building.texi (Commands of GUD): Fix keybinding for `gud-break'. + +2014-01-15 Glenn Morris <rgm@gnu.org> + + * files.texi (File Conveniences): + * misc.texi (EWW): Copyedits. + +2014-01-10 Glenn Morris <rgm@gnu.org> + + * emacs.texi (Distrib): Add donate URL. Add anchor. + +2014-01-10 Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * dired.texi (Misc Dired Features): Document `dired-hide-details-mode', + `dired-hide-details-hide-symlink-targets', and + `dired-hide-details-hide-information-lines'. + +2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * emacs.texi: Add EWW. + * misc.texi (EWW): Document EWW. + +2014-01-09 Glenn Morris <rgm@gnu.org> + + * trouble.texi (Service): Refer to online service directory + rather than etc/SERVICE. + +2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * building.texi (Lisp Libraries): Document `load-prefer-newer'. + + * files.texi (File Conveniences): Document `image-next-frame', + `image-previous-frame', `image-goto-frame', + `image-increase-speed', `image-decrease-speed', + `image-reverse-speed', and `image-reset-speed'. + +2014-01-07 Bastien Guerry <bzg@gnu.org> + + * buffers.texi (Buffers): Fix display of @math content by using + nested braces. (Bug#16389) + +2014-01-07 Chong Yidong <cyd@gnu.org> + + * search.texi (Special Isearch): Document C-x 8 RET in isearch. + (Word Search): Document incremental word search changes. + (Isearch Yank): Document M-s C-e with a prefix argument. + +2014-01-07 Glenn Morris <rgm@gnu.org> + + * cal-xtra.texi (Calendar Customizing): + Mention calendar-day-header-array. + +2013-12-28 Glenn Morris <rgm@gnu.org> + + * trouble.texi (Understanding Bug Reporting): Brevity. + +2013-12-27 Jarek Czekalski <jarekczek@poczta.onet.pl> + + * mini.texi (Completion Options): Add a link to Shell Options. + * misc.texi (Shell Mode): Move documentation of + shell-completion-fignore from Shell Mode to Shell Options. + +2013-12-26 João Távora <joaotavora@gmail.com> + + * emacs.texi (Matching): Describe new features of Electric Pair mode. + +2013-12-25 Chong Yidong <cyd@gnu.org> + + * glossary.texi (Glossary): Define MULE in modern terms. + +2013-12-25 Xue Fuqiao <xfq.free@gmail.com> + + * files.texi (Diff Mode): Add an index. + +2013-12-24 Xue Fuqiao <xfq.free@gmail.com> + + * trouble.texi (Understanding Bug Reporting): Minor update. + (Checklist): Fix a cross-reference. + +2013-12-23 Xue Fuqiao <xfq.free@gmail.com> + + * regs.texi (Bookmarks): Document `bookmark-default-file'. + + * misc.texi (Shell Mode): Add a cross-reference. + + * building.texi (Lisp Eval): Add an index. + +2013-12-22 Glenn Morris <rgm@gnu.org> + + * entering.texi (Entering Emacs): Typo fix. + + * calendar.texi (General Calendar): + * rmail.texi (Rmail Scrolling): Use itemx where appropriate. + +2013-12-22 Eli Zaretskii <eliz@gnu.org> + + * regs.texi (Keyboard Macro Registers): Fix last change. + +2013-12-22 Xue Fuqiao <xfq.free@gmail.com> + + * search.texi (Special Isearch, Query Replace): Document negative + argument of replacement commands. + (Symbol Search): Document `isearch-forward-symbol-at-point'. + + * files.texi (File Conveniences): Document `image-next-file' and + `image-previous-file'. + + * display.texi (Optional Mode Line): Fix an index. + + * regs.texi (File Registers): Document `kmacro-to-register'. + + * indent.texi (Tab Stops): Mention recent changes about `tab-stop-list'. + + * frames.texi (Scroll Bars): + Document `scroll-bar-adjust-thumb-portion'. + +2013-12-21 Chong Yidong <cyd@gnu.org> + + * indent.texi (Indentation Commands): Document C-x TAB changes. + +2013-12-20 Tassilo Horn <tsdh@gnu.org> + + * calendar.texi, display.texi, help.texi, rmail.texi: + Document `S-SPC' as alternative to scrolling down with `DEL'. + + * frames.texi: Document `toggle-frame-maximized' and + `toggle-frame-fullscreen' with their respective keys. + + * buffers.texi: Document buffer name uniquification changes. + + * indent.texi: Document that `electric-indent-mode' is enabled by + default. + + * display.texi (Cursor Display): Document `blink-cursor-blinks'. + + * buffers.texi: Update list-buffers "screenshot" to show Messages + as major-mode. + + * entering.texi: Document `initial-buffer-choice' changes. + + * misc.texi (emacsclient Options): + Document `initial-buffer-choice' changes. + + * help.texi: Document that `?' now also shows subcommands of + prefix keys. + +2013-12-17 Chong Yidong <cyd@gnu.org> + + * killing.texi (Appending Kills): Note that append-next-kill can + prepend the kill. + +2013-12-12 Eli Zaretskii <eliz@gnu.org> + + * mule.texi (File Name Coding): Document file-name encoding + peculiarities on MS-Windows. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * emacs.texi: Sync direntry with info/dir version. + +2013-12-08 Juanma Barranquero <lekktu@gmail.com> + + * msdog.texi (Windows Keyboard): Fix typo. + +2013-11-30 Glenn Morris <rgm@gnu.org> + + * Makefile.in (distclean): Remove Makefile. + +2013-11-29 Stefan Monnier <monnier@iro.umontreal.ca> + + * buffers.texi (Icomplete): Rename from Iswitchb and + rewrite accordingly. + +2013-11-23 Glenn Morris <rgm@gnu.org> + + * cmdargs.texi (General Variables): + Empty elements in EMACSLOADPATH now mean the default load-path. + +2013-11-21 Glenn Morris <rgm@gnu.org> + + * cmdargs.texi (Action Arguments): Use path-separator with -L. + +2013-11-04 Glenn Morris <rgm@gnu.org> + + * cmdargs.texi (Action Arguments): Mention that `-L :...' appends. + +2013-11-02 Glenn Morris <rgm@gnu.org> + + * cmdargs.texi (Action Arguments): Clarify `-L' a bit. + +2013-10-23 Glenn Morris <rgm@gnu.org> + + * files.texi, glossary.texi, killing.texi, search.texi, sending.texi: + Nuke @refill. + + * Makefile.in (install-dvi, install-html, install-pdf) + (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) + (uninstall-pdf): Quote entities that might contain whitespace. + +2013-10-20 Xue Fuqiao <xfq.free@gmail.com> + + * custom.texi (Init Syntax, Terminal Init, Terminal Init): + Remove @refill. + +2013-10-13 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): Comment out old alpha stuff. + +2013-10-13 Xue Fuqiao <xfq.free@gmail.com> + + * calendar.texi (Special Diary Entries): Remove @refill. + +2013-10-13 Glenn Morris <rgm@gnu.org> + + * display.texi (Text Scale): Update text-scale-adjust details. + + * ack.texi (Acknowledgments): + * emacs.texi (Acknowledgments): Use accented form of some names. + +2013-10-08 Eli Zaretskii <eliz@gnu.org> + + * ack.texi (Acknowledgments): Fix spelling of Hrvoje Nikšić's + name. (Bug#15557) + + Support menus on text-mode terminals. + * screen.texi (Menu Bar): Adapt to TTY menus. + + * frames.texi (Frames): Mention menu support on text terminals. + + * files.texi (Visiting): Mention the "File" menu-bar menu. + + * display.texi (Standard Faces): Mention TTY faces for menus. + +2013-10-06 Xue Fuqiao <xfq.free@gmail.com> + + * cal-xtra.texi (Calendar Customizing, Diary Display): Remove @refill. + +2013-09-29 Xue Fuqiao <xfq.free@gmail.com> + + * fortran-xtra.texi (Fortran Abbrev): Remove @refill. + +2013-09-26 Xue Fuqiao <xfq.free@gmail.com> + + * dired.texi (Flagging Many Files): Use @emph instead of @strong. + + * emacs.texi (Intro): Minor cleanup. + +2013-09-22 Xue Fuqiao <xfq.free@gmail.com> + + * fixit.texi (Transpose, Fixing Case): Remove @refill. + +2013-09-21 Xue Fuqiao <xfq.free@gmail.com> + + * maintaining.texi (VC Directory Commands): Add keybinding for + vc-log-incoming in vc-dir. + (Log Buffer): Use @emph instead of @strong. + +2013-09-12 Xue Fuqiao <xfq.free@gmail.com> + + * text.texi (Enriched Justification): Explain values of default-justification. + +2013-09-04 Xue Fuqiao <xfq.free@gmail.com> + + * maintaining.texi (VC Ignore): Mention `vc-ignore' with prefix argument. + +2013-08-31 Ulrich Müller <ulm@gentoo.org> + + * xresources.texi (Motif Resources): + Rename from LessTif Resources. Update xrefs. (Bug#15145) + * emacs.texi: Update menu. + +2013-08-28 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, + for portability to hosts where /bin/sh has problems. + 2013-08-17 Xue Fuqiao <xfq.free@gmail.com> * text.texi (Enriched Justification): Minor fixes. @@ -23,8 +966,8 @@ (emacs.ps, emacs-xtra.ps): Remove explicit rules. (emacs.html): Use HTML_OPTS. (clean): Use DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS. - (.PHONY): install-dvi, install-html, install-pdf, install-ps - ,install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, + (.PHONY): install-dvi, install-html, install-pdf, install-ps, + install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, uninstall-ps, and uninstall-doc. (install-dvi, install-html, install-pdf, install-ps, install-doc) (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) @@ -346,8 +1289,8 @@ * misc.texi (Terminal emulator): Document Term mode faces. - * mini.texi (Basic Minibuffer): New node. Document - minibuffer-electric-default-mode. + * mini.texi (Basic Minibuffer): New node. + Document minibuffer-electric-default-mode. * display.texi (Visual Line Mode): Fix index entry. @@ -524,6 +1467,11 @@ * trouble.texi (Crashing): Document addr2line. +2012-09-19 Tassilo Horn <tsdh@gnu.org> + + * misc.texi (DocView Slicing): Document new slice from + BoundingBox feature. + 2012-09-19 Chong Yidong <cyd@gnu.org> * killing.texi (Yanking): Minor clarification (Bug#12469). @@ -1011,7 +1959,7 @@ \\`info- no longer handled specially. Update for rmail-enable-mime-composing. Don't mention 'm' for replies. - Don't mention rmail-mail-new-frame and cancelling, since it does + Don't mention rmail-mail-new-frame and canceling, since it does not work for Message at the moment. * cal-xtra.texi: Copyedits. @@ -2209,7 +3157,7 @@ 2011-05-22 Chong Yidong <cyd@stupidchicken.com> - * mule.texi (Specify Coding, Text Coding, Communication Coding): + * mule.texi (Specify Coding, Text Coding, Communication Coding) (File Name Coding, Terminal Coding): Add command names (Bug#8312). 2011-05-18 Glenn Morris <rgm@gnu.org> @@ -2402,7 +3350,7 @@ * Makefile.in (MAKEINFO): Now controlled by `configure'. (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): Updated. + (ENVADD): Update. 2011-01-18 Glenn Morris <rgm@gnu.org> @@ -2881,9 +3829,9 @@ 2010-03-27 Nick Roberts <nickrob@snap.net.nz> - doc/emacs/building.texi: Describe restored GDB/MI functionality + * building.texi: Describe restored GDB/MI functionality removed by 2009-12-29T07:15:34Z!nickrob@snap.net.nz. - doc/emacs/emacs.texi: Update node names for building.texi. + * emacs.texi: Update node names for building.texi. 2010-03-24 Glenn Morris <rgm@gnu.org> @@ -4700,7 +5648,7 @@ 2008-05-02 Eric S. Raymond <esr@snark.thyrsus.com> - * emacs/buffers.texi, emacs/files.texi (Version-control): + * buffers.texi, files.texi (Version-control): vc-toggle-read-only is no longer a good idea... 2008-04-29 Glenn Morris <rgm@gnu.org> @@ -4847,10 +5795,6 @@ * maintaining.texi (Tags): Fix last change. -2008-02-02 Michael Albinus <michael.albinus@gmx.de> - - * tramp.texi: Use new FSF's Back-Cover Text. - 2008-01-31 Nick Roberts <nickrob@snap.net.nz> * trouble.texi (Checklist): Direct users to emacs-devel@gnu.org. @@ -4893,8 +5837,6 @@ * search.texi (Query Replace): Make exp of query-replace more self-contained, and clarify. - * cc-mode.texi (Getting Started): Change @ref to @pxref. - 2007-12-15 Richard Stallman <rms@gnu.org> * files.texi (Auto Save): Clarify definition of auto-saving. @@ -5446,6 +6388,11 @@ * frames.texi (Secondary Selection): Window clicked does not matter when mouse-yank-at-point is non-nil. +2007-01-27 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (ls in Lisp): Document ls-lisp-format-time-list and + ls-lisp-use-localized-time-format. + 2007-01-16 Glenn Morris <rgm@gnu.org> * abbrevs.texi (Editing Abbrevs): Describe how to disable a @@ -5773,6 +6720,11 @@ Change "Library Public License" to "Lesser Public License" throughout. Use "yyyy" to represent year. +2006-09-12 Paul Eggert <eggert@cs.ucla.edu> + + * misc.texi (Interactive Shell): EMACS is now set + to Emacs's absolute file name, not to "t". + 2006-09-12 Reiner Steib <Reiner.Steib@gmx.de> * files.texi (Visiting): Add index entry "open file". @@ -6534,8 +7486,6 @@ * sending.texi (Mail Sending): pxref to Top needs five args. - * texinfo.tex: Update to current version (2006-03-21.13). - 2006-03-31 Richard Stallman <rms@gnu.org> * emacs.texi (Top): Update subnode menu. @@ -8295,7 +9245,7 @@ * text.texi (Format Faces): Replace old M-g key prefix with M-o. - * emacs.texi (Acknowledgments): Updated. + * emacs.texi (Acknowledgments): Update. * anti.texi: Total rewrite. @@ -9402,20 +10352,20 @@ * frames.texi (Dialog Boxes): Add use-file-dialog. -2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org> +2003-11-22 Martin Stjernholm <mast@lysator.liu.se> * ack.texi: Note that Alan Mackenzie contributed the AWK support in CC Mode. 2003-11-02 Jesper Harder <harder@ifa.au.dk> (tiny change) - * man/ack.texi, man/basic.texi, man/cmdargs.texi: - * man/commands.texi, man/custom.texi, man/display.texi: - * man/emacs.texi, man/files.texi: - * man/frames.texi, man/glossary.texi, man/killing.texi: - * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi: - * man/mule.texi, man/rmail.texi, man/search.texi: - * man/sending.texi, man/text.texi, man/trouble.texi: + * ack.texi, basic.texi, cmdargs.texi: + * commands.texi, custom.texi, display.texi: + * emacs.texi, files.texi: + * frames.texi, glossary.texi, killing.texi: + * macos.texi, mark.texi, misc.texi, msdog.texi: + * mule.texi, rmail.texi, search.texi: + * sending.texi, text.texi, trouble.texi: Replace @sc{ascii} and ASCII with @acronym{ASCII}. 2003-11-01 Alan Mackenzie <acm@muc.de> @@ -9949,7 +10899,7 @@ 1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. + * texindex.c: If USG, include sys/types.h and sys/fcntl.h. 1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) @@ -9969,7 +10919,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1993-1999, 2001-2013 Free Software Foundation, Inc. + Copyright (C) 1993-1999, 2001-2015 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 7aeead4e2f6..7630780be6c 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1994, 1996-2013 Free Software Foundation, Inc. +# Copyright (C) 1994, 1996-2015 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -17,17 +17,18 @@ # 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 +SHELL = @SHELL@ # NB If you add any more configure variables, # update the sed rules in the dist target below. # Where to find the source code. $(srcdir) will be the doc/emacs subdirectory -# of the source tree. This is set by configure's `--srcdir' option. +# of the source tree. This is set by configure's '--srcdir' option. srcdir=@srcdir@ -# Only for make dist. -version=@version@ +top_srcdir = @top_srcdir@ + +version = @version@ ## Where the output files go. ## Note that the setfilename command in the .texi files assumes this. @@ -54,12 +55,11 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. # --no-split is only needed because of MS-DOS. # For a possible alternative, see # http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg01182.html -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -73,8 +73,15 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ +ENVADD = $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = emacs.dvi emacs-xtra.dvi @@ -87,12 +94,13 @@ EMACS_XTRA= \ $(srcdir)/arevert-xtra.texi \ $(srcdir)/cal-xtra.texi \ $(srcdir)/dired-xtra.texi \ + ${srcdir}/docstyle.texi \ $(srcdir)/picture-xtra.texi \ $(srcdir)/emerge-xtra.texi \ $(srcdir)/vc-xtra.texi \ $(srcdir)/vc1-xtra.texi \ $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi + $(srcdir)/msdos-xtra.texi EMACSSOURCES= \ ${srcdir}/emacs.texi \ @@ -136,54 +144,65 @@ EMACSSOURCES= \ ${srcdir}/xresources.texi \ ${srcdir}/anti.texi \ ${srcdir}/macos.texi \ - ${srcdir}/msdog.texi \ + ${srcdir}/msdos.texi \ ${srcdir}/gnu.texi \ ${srcdir}/glossary.texi \ ${srcdir}/ack.texi \ ${srcdir}/kmacro.texi \ $(EMACS_XTRA) -## This seems pointless. The info/ directory exists in both the -## repository and the release tarfiles. -mkinfodir = @${MKDIR_P} ${buildinfodir} +## Disable implicit rules. +%.texi: ; .PHONY: info dvi html pdf ps -.SUFFIXES: .ps .dvi - -.dvi.ps: - $(DVIPS) -o $@ $< - -info: $(buildinfodir)/emacs$(INFO_EXT) +info: $(buildinfodir)/emacs.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) +## The info/ directory exists in release tarfiles but not the repository. +${buildinfodir}: + ${MKDIR_P} $@ + # Note that all the Info targets build the Info files in srcdir. # There is no provision for Info files to exist in the build directory. # In a distribution of Emacs, the Info files should be up to date. -# Note: "<" is not portable in ordinary make rules. -$(buildinfodir)/emacs$(INFO_EXT): ${EMACSSOURCES} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs.texi +$(buildinfodir)/emacs.info: ${EMACSSOURCES} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< emacs.dvi: ${EMACSSOURCES} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi + $(ENVADD) $(TEXI2DVI) $< emacs.pdf: ${EMACSSOURCES} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs.texi + $(ENVADD) $(TEXI2PDF) $< emacs.html: ${EMACSSOURCES} - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< emacs-xtra.dvi: $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi + $(ENVADD) $(TEXI2DVI) $< emacs-xtra.pdf: $(EMACS_XTRA) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-xtra.texi + $(ENVADD) $(TEXI2PDF) $< + +%.ps: %.dvi + $(DVIPS) -o $@ $< + +.PHONY: doc-emacsver + +# If configure were to just generate emacsver.texi from emacsver.texi.in +# in the normal way, the timestamp of emacsver.texi would always be +# newer than that of the info files, which are prebuilt in release tarfiles. +# So we use this rule, and move-if-change, to avoid that. +doc-emacsver: + sed 's/[@]version@/${version}/' \ + ${srcdir}/emacsver.texi.in > emacsver.texi.$$$$ && \ + ${top_srcdir}/build-aux/move-if-change emacsver.texi.$$$$ \ + ${srcdir}/emacsver.texi -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean ## Temp files. mostlyclean: @@ -193,57 +212,38 @@ mostlyclean: ## Products not in the release tarfiles. clean: mostlyclean rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f emacs-manual-${version}.tar* distclean: clean + rm -f Makefile ## In the standalone tarfile, the clean rule runs this. infoclean: - -cd $(buildinfodir) && rm -f emacs$(INFO_EXT) emacs$(INFO_EXT)-[1-9] emacs$(INFO_EXT)-[1-9][0-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -## Make a standalone tarfile of the Emacs manual sources. -## The [c] is a dumb way to prevent configure expanding it. -dist: - rm -rf emacs-manual-${version} - mkdir emacs-manual-${version} - cp ${srcdir}/*.texi ${texinfodir}/texinfo.tex \ - ${srcdir}/ChangeLog* emacs-manual-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - ${srcdir}/Makefile.in > emacs-manual-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-manual-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-manual-${version}.tar emacs-manual-${version} - rm -rf emacs-manual-${version} + rm -f \ + $(buildinfodir)/emacs.info \ + $(buildinfodir)/emacs.info-[1-9] \ + $(buildinfodir)/emacs.info-[1-9][0-9] +bootstrap-clean maintainer-clean: distclean infoclean + rm -f ${srcdir}/emacsver.texi .PHONY: install-dvi install-html install-pdf install-ps install-doc install-dvi: dvi - umask 022; $(MKDIR_P) $(DESTDIR)$(dvidir) - $(INSTALL_DATA) $(DVI_TARGETS) $(DESTDIR)$(dvidir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" + $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" install-html: html - umask 022; $(MKDIR_P) $(DESTDIR)$(htmldir) - $(INSTALL_DATA) $(HTML_TARGETS) $(DESTDIR)$(htmldir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" + $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" install-pdf: pdf - umask 022;$(MKDIR_P) $(DESTDIR)$(pdfdir) - $(INSTALL_DATA) $(PDF_TARGETS) $(DESTDIR)$(pdfdir) + umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" + $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" install-ps: ps - umask 022; $(MKDIR_P) $(DESTDIR)$(psdir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} $(DESTDIR)$(psdir); \ + $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ [ -n "${GZIP_PROG}" ] || continue; \ - rm -f $(DESTDIR)$(psdir)/$${file}.gz; \ - ${GZIP_PROG} -9n $(DESTDIR)$(psdir)/$${file}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ + ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ done ## Top-level Makefile installs the info pages. @@ -254,20 +254,20 @@ install-doc: install-dvi install-html install-pdf install-ps uninstall-dvi: for file in $(DVI_TARGETS); do \ - rm -f $(DESTDIR)$(dvidir)/$${file}; \ + rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ done uninstall-html: for file in $(HTML_TARGETS); do \ - rm -f $(DESTDIR)$(htmldir)/$${file}; \ + rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ done uninstall-ps: ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ for file in $(PS_TARGETS); do \ - rm -f $(DESTDIR)$(psdir)/$${file}$${ext}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ done uninstall-pdf: for file in $(PDF_TARGETS); do \ - rm -f $(DESTDIR)$(pdfdir)/$${file}; \ + rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ done uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index cc16a5f7762..23d7e28f4e3 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Abbrevs @@ -20,7 +20,7 @@ to expand the letters in the buffer before point by looking for other words in the buffer that start with those letters. @xref{Dynamic Abbrevs}. - ``Hippie'' expansion generalizes abbreviation expansion. + A third kind, @dfn{hippie expansion}, generalizes abbreviation expansion. @xref{Hippie Expand, , Hippie Expansion, autotype, Features for Automatic Typing}. @@ -206,8 +206,9 @@ to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled. - Expanding any abbrev runs @code{abbrev-expand-functions}, a special -hook. Functions in this special hook can make arbitrary changes to + The function @code{expand-abbrev} performs the expansion by calling +the function that @code{abbrev-expand-function} specifies. By +changing this function you can make arbitrary changes to the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp Reference Manual}. @@ -249,10 +250,10 @@ keeps track of this to help you see which abbrevs you actually use, so that you can eliminate those that you don't use often. The string at the end of the line is the expansion. - Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs + Some abbrevs are marked with @samp{(sys)}. These @dfn{system abbrevs} (@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are pre-defined by various modes, and are not saved to your abbrev file. -To disable a ``system'' abbrev, define an abbrev of the same name that +To disable a system abbrev, define an abbrev of the same name that expands to itself, and save it to your abbrev file. @findex edit-abbrevs diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 47e5be88ce1..eebab8acaa8 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1994-1997, 1999-2013 Free Software Foundation, Inc. +@c Copyright (C) 1994-1997, 1999-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @node Acknowledgments @@ -15,7 +15,7 @@ We thank them for their generosity as well. This list is intended to mention every contributor of a major package or feature we currently distribute; if you know of someone we have omitted, -please report that as a manual bug. More comprehensive information is +please make a bug report. More comprehensive information is available in the @file{ChangeLog} files, summarized in the file @file{etc/AUTHORS} in the distribution. @@ -51,12 +51,12 @@ files. @item Michael Albinus wrote @file{dbus.el}, a package that implements the D-Bus message bus protocol; @file{zeroconf.el}, a mode for browsing -Avahi services; @file{xesam.el}, a Xesam-based search engine -interface; and @file{secrets.el}, an interface to keyring daemons for -storing confidential data. He and Kai Großjohann wrote the Tramp package, which -provides transparent remote file editing using rcp, ssh, ftp, and -other network protocols. He and Daniel Pittman wrote -@file{tramp-cache.el}. +Avahi services; @file{secrets.el}, an interface to keyring daemons for +storing confidential data; and @file{filenotify.el} and the associated +low-level interface routines, for watching file status changes. +He and Kai Großjohann wrote the Tramp package, which provides +transparent remote file editing using ssh, ftp, and other network +protocols. He and Daniel Pittman wrote @file{tramp-cache.el}. @item Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the @@ -88,7 +88,8 @@ moving the mouse in particular patterns. @item Juanma Barranquero wrote @file{emacs-lock.el} (based on the original version by Tom Wurgler), which makes it harder to exit with valuable -buffers unsaved. He also made many other contributions to other +buffers unsaved; and @file{frameset.el}, for saving and restoring the +frame/window setup. He also made many other contributions to other areas, including MS Windows support. @item @@ -104,7 +105,7 @@ footnotes in email messages; and @file{gnus-audio.el} and @item Alexander L. Belikoff, Sergey Berezin, Sacha Chua, David Edmondson, Noah Friedman, Andreas Fuchs, Mario Lang, Ben Mesander, Lawrence -Mitchell, Gergely Nagy, Michael Olson, Per Persson, Jorgen Schaefer, +Mitchell, Gergely Nagy, Michael Olson, Per Persson, Jorgen Schäfer, Alex Schroeder, and Tom Tromey wrote ERC, an advanced Internet Relay Chat client (for more information, see the file @file{CREDITS} in the ERC distribution). @@ -122,8 +123,8 @@ by Oliver Seidel), a package for maintaining @file{TODO} list files. Anna M. Bigatti wrote @file{cal-html.el}, which produces HTML calendars. @item -Ray Blaak and Simon South wrote @file{delphi.el}, a mode for editing -Delphi (Object Pascal) source code. +Ray Blaak and Simon South wrote @file{opascal.el}, a mode for editing +Object Pascal source code. @item Martin Blais, Stefan Merten, and David Goodger wrote @file{rst.el}, a @@ -154,7 +155,7 @@ directory changes in shell buffers; @file{filecache.el}, which records which directories your files are in; @file{locate.el}, which interfaces to the @code{locate} command; @file{find-lisp.el}, an Emacs Lisp emulation of the @command{find} program; @file{net-utils.el}; and -the ``generic mode'' feature. +the generic mode feature. @item Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs; and @@ -195,7 +196,8 @@ for editing IDL and WAVE CL. Bob Chassell wrote @file{texnfo-upd.el}, @file{texinfo.el}, and @file{makeinfo.el}, modes and utilities for working with Texinfo files; and @file{page-ext.el}, commands for extended page handling. He also -wrote the ``Introduction to programming in Emacs Lisp'' manual. +wrote the Emacs Lisp introduction. @xref{Top,,,eintr, Introduction to +Programming in Emacs Lisp}. @item Jihyun Cho wrote @file{hanja-util.el} and @file{hangul.el}, utilities @@ -203,7 +205,9 @@ for Korean Hanja. @item Andrew Choi and Yamamoto Mitsuharu wrote the Carbon support, used -prior to Emacs 23 for Mac OS. +prior to Emacs 23 for Mac OS@. Yamamoto Mitsuharu continued to +contribute to Mac OS support in the newer Nextstep port; and also +improved support for multi-monitor displays. @item Chong Yidong was the Emacs co-maintainer from Emacs 23 to 24.3. He made many @@ -244,10 +248,10 @@ for compiled Emacs Lisp code. @item Mathias Dahl wrote @file{image-dired.el}, a package for viewing image -files as ``thumbnails''. +files as thumbnails. @item -Julien Danjou wrote an implementation of ``Desktop Notifications'' +Julien Danjou wrote an implementation of desktop notifications (@file{notifications.el}, and related packages for ERC and Gnus); and @file{color.el}, a library for general color manipulation. He also made various contributions to Gnus. @@ -276,7 +280,7 @@ over maintainership. Benjamin Andresen, Thomas Baumann, Joel Boehland, Jan Böc Borgman, Baoqiu Cui, Dan Davison, Christian Egli, Eric S. Fraga, Daniel German, Chris Gray, Konrad Hinsen, Tassilo Horn, Philip Jackson, Martyn Jago, Thorsten Jolitz, Jambunathan K, Tokuya Kameshima, Sergey Litvinov, David Maus, Ross Patterson, Juan Pechiar, Sebastian Rose, Eric Schulte, Paul Sexton, Ulf Stegemann, Andy Stewart, Christopher Suckling, David O'Toole, John Wiegley, Zhang Weize, -Piotr Zielinski, and others also wrote various Org mode components. +Piotr Zieliński, and others also wrote various Org mode components. For more information, @pxref{History and Acknowledgments,,, org, The Org Manual}. @item @@ -303,8 +307,7 @@ to VC and the calendar. @item Stephen Eglen wrote @file{mspools.el}, which tells you which Procmail -folders have mail waiting in them; and @file{iswitchb.el}, a feature -for incremental reading and completion of buffer names. +folders have mail waiting in them. @item Torbjörn Einarsson wrote @file{f90.el}, a mode for Fortran 90 files. @@ -347,11 +350,14 @@ mail messages; and @file{saveplace.el}, for preserving point's location in files between editing sessions. @item -Gary Foster wrote @file{crisp.el}, the emulation for CRiSP and Brief -editors; and @file{scroll-all.el}, a mode for scrolling several buffers +Gary Foster wrote @file{scroll-all.el}, a mode for scrolling several buffers together. @item +Romain Francoise contributed ACL (Access Control List) support, +for preserving extended file attributes on backup and copy. + +@item Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, @file{type-break.el}, which reminds you to take periodic breaks from typing, and @code{eldoc-mode}, a mode to show the defined parameters or @@ -512,13 +518,14 @@ Emacs, including: @file{dns.el} for Domain Name Service lookups; @file{time-date.el} for general date and time handling. He also wrote @file{network-stream.el}, for opening network processes; @file{url-queue.el}, for controlling parallel downloads of URLs; -and implemented libxml2 support. +and implemented libxml2 support. He also wrote @file{eww.el}, +an Emacs Lisp web browser; and implemented native zlib decompression. Components of Gnus have also been written by: Nagy Andras, David Blacka, Scott Byer, Ludovic Courtès, Julien Danjou, Kevin Greiner, Kai Großjohann, Joe Hildebrand, Paul Jarc, Simon Josefsson, Sascha Lüdecke, David Moore, Jim Radford, Benjamin Rutt, Raymond Scholz, -Thomas Steffen, Reiner Steib, Didier Verna, Ilja Weis, Katsumi -Yamaoka, Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the +Thomas Steffen, Reiner Steib, Jan Tatarik, Didier Verna, Ilja Weis, +Katsumi Yamaoka, Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the Gnus Manual}). @item @@ -538,11 +545,11 @@ diary entries to and from the iCalendar format; @file{bubbles.el}, a puzzle game. @item -Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game. +Kyle Jones wrote @file{life.el}, a package to play Conway's Game of Life. @item Terry Jones wrote @file{shadow.el}, a package for finding potential -load-path problems when some Lisp file ``shadows'' another. +load-path problems when some Lisp file shadows another. @item Simon Josefsson wrote @file{dns-mode.el}, an editing mode for Domain @@ -594,7 +601,7 @@ buffers. @item Michael Kifer wrote @code{ediff}, an interactive interface to the @command{diff}, @command{patch}, and @command{merge} programs; and -Viper, another emulator of the VI editor. +Viper, an emulator of the VI editor. @item Richard King wrote the first version of @file{userlock.el} and @@ -698,7 +705,11 @@ directory-local variables; and the @code{info-finder} feature that creates a virtual Info manual of package keywords. @item -Károly Lőrentey wrote the ``multi-terminal'' code, which allows +Leo Liu wrote @file{pcmpl-x.el}, providing completion for +miscellaneous external tools; and revamped support for Octave in Emacs 24.4. + +@item +Károly Lőrentey wrote the multi-terminal code, which allows Emacs to run on graphical and text terminals simultaneously. @item @@ -716,7 +727,7 @@ Autoconf files; @file{cfengine.el}, a mode for editing Cfengine files; @file{elide-head.el}, a package for eliding boilerplate text from file headers; @file{hl-line.el}, a minor mode for highlighting the line in the current window on which point is; @file{cap-words.el}, a minor mode -for motion in ``CapitalizedWordIdentifiers''; @file{latin1-disp.el}, a +for motion in @code{CapitalizedWordIdentifiers}; @file{latin1-disp.el}, a package that lets you display ISO 8859 characters on Latin-1 terminals by setting up appropriate display tables; the version of @file{python.el} used prior to Emacs 24.3; @file{smiley.el}, a @@ -812,14 +823,13 @@ command with its arguments. @item Richard Mlynarik wrote @file{cl-indent.el}, a package for indenting -Common Lisp code; @file{ebuff-menu.el}, an ``electric'' browser for +Common Lisp code; @file{ebuff-menu.el}, an electric browser for buffer listings; @file{ehelp.el}, bindings for browsing help screens; -@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, -used in mail messages and news articles; and @file{terminal.el}, a -terminal emulator for Emacs subprocesses. +and @file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, +used in mail messages and news articles. @item -Gerd Moellmann was the Emacs maintainer from the beginning of Emacs 21 +Gerd Möllmann was the Emacs maintainer from the beginning of Emacs 21 development until the release of 21.1. He wrote the new display engine used from Emacs 21 onwards, and the asynchronous timers facility. He also wrote @code{ebrowse}, the C@t{++} browser; @@ -829,7 +839,8 @@ facility. He also wrote @code{ebrowse}, the C@t{++} browser; and @file{rx.el}, a regular expression constructor. @item -Stefan Monnier was the Emacs (co-)maintainer from Emacs 23 onwards. He added +Stefan Monnier was the Emacs (co-)maintainer from Emacs 23 until +late in the development of 25.1. He added support for Arch and Subversion to VC, re-wrote much of the Emacs server to use the built-in networking primitives, and re-wrote the abbrev and minibuffer completion code for Emacs 23. He also wrote @code{PCL-CVS}, @@ -839,12 +850,12 @@ text; @file{smerge-mode.el}, a minor mode for resolving @code{diff3} conflicts; @file{diff-mode.el}, a mode for viewing and editing context diffs; @file{css-mode.el} for Cascading Style Sheets; @file{bibtex-style.el} for Bib@TeX{} Style files; @file{mpc.el}, a -client for the ``Music Player Daemon''; @file{smie.el}, a generic +client for the Music Player Daemon (MPD); @file{smie.el}, a generic indentation engine; and @file{pcase.el}, implementing ML-style pattern matching. In Emacs 24, he integrated the lexical binding code, cleaned up the CL namespace (making it acceptable to use CL -functions at runtime), and added generalized variables to core Emacs -Lisp. +functions at runtime), added generalized variables to core Emacs +Lisp, and implemented a new lightweight advice mechanism. @item Morioka Tomohiko wrote several packages for MIME support in Gnus and @@ -874,9 +885,6 @@ Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor mode for selectively displaying blocks of text. @item -Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. - -@item Dan Nicolaescu added support for running Emacs as a daemon. He also wrote @file{romanian.el}, support for editing Romanian text; @file{iris-ansi.el}, support for running Emacs on SGI's @code{xwsh} @@ -884,7 +892,7 @@ and @code{winterm} terminal emulators; and @file{vc-dir.el}, displaying the status of version-controlled directories. @item -Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer +Hrvoje Nikšić wrote @file{savehist.el}, for saving the minibuffer history between Emacs sessions. @item @@ -924,7 +932,7 @@ Jeff Peck wrote @file{sun.el}, key bindings for sunterm keys. @item Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of -the ``Towers of Hanoi'' puzzle. +the Towers of Hanoi puzzle. @item William M. Perry wrote @file{mailcap.el} (with Lars Magne @@ -979,7 +987,7 @@ minor mode for displaying a ruler in the header line; and structures. @item -Francesco A. Potorti wrote @file{cmacexp.el}, providing a command which +Francesco A. Potortì wrote @file{cmacexp.el}, providing a command which runs the C preprocessor on a region of a file and displays the results. He also expanded and redesigned the @code{etags} program. @@ -997,7 +1005,7 @@ source code version control systems, with Paul Eggert; @file{gud.el}, a package for running source-level debuggers like GDB and SDB in Emacs; @file{asm-mode.el}, a mode for editing assembly language code; @file{AT386.el}, terminal support package for IBM's AT keyboards; -@file{cookie1.el}, support for ``fortune-cookie'' programs like +@file{cookie1.el}, support for fortune-cookie programs like @file{yow.el} and @file{spook.el}; @file{finder.el}, a package for finding Emacs Lisp packages by keyword and topic; @file{keyswap.el}, code to swap the @key{BS} and @key{DEL} keys; @file{loadhist.el}, @@ -1027,10 +1035,8 @@ Alex Rezinsky wrote @file{which-func.el}, a mode that shows the name of the current function in the mode line. @item -Rob Riepel wrote @file{tpu-edt.el} and its associated files, providing -an emulation of the VMS TPU text editor emulating the VMS EDT editor, -and @file{vt-control.el}, providing some control functions for the DEC -VT line of terminals. +Rob Riepel wrote @file{vt-control.el}, providing some control +functions for the DEC VT line of terminals. @item Nick Roberts wrote @file{t-mouse.el}, for mouse support in text @@ -1050,7 +1056,8 @@ Guillermo J. Rozas wrote @file{scheme.el}, a mode for editing Scheme and DSSSL code. @item -Martin Rudalics implemented improved display-buffer handling in Emacs 24. +Martin Rudalics implemented improved display-buffer handling in Emacs 24; +and implemented pixel-wise resizing of windows and frames. @item Ivar Rummelhoff wrote @file{winner.el}, which records recent window @@ -1073,9 +1080,6 @@ James B. Salem and Brewster Kahle wrote @file{completion.el}, providing dynamic word completion. @item -Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor. - -@item Holger Schauer wrote @file{fortune.el}, a package for using fortune in message signatures. @@ -1100,9 +1104,6 @@ Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played against Emacs; and @file{mpuz.el}, a multiplication puzzle. @item -Rainer Schoepf contributed to Alpha and OSF1 support. - -@item Jan Schormann wrote @file{solitaire.el}, an implementation of the Solitaire game. @@ -1178,7 +1179,7 @@ selecting regions to follow many other systems. @item Richard Stallman invented Emacs. He is the original author of GNU Emacs, and has been Emacs maintainer over several non-contiguous -periods. In addition to much of the ``core'' Emacs code, he has +periods. In addition to much of the core Emacs code, he has written @file{easymenu.el}, a facility for defining Emacs menus; @file{image-mode.el}, support for visiting image files; @file{menu-bar.el}, the Emacs menu bar support code; @@ -1186,24 +1187,23 @@ written @file{easymenu.el}, a facility for defining Emacs menus; color; and also co-authored portions of CC mode. @item -Sam Steingold wrote @file{gulp.el}, a facility for asking package -maintainers for updated versions of their packages via e-mail, and -@file{midnight.el}, a package for running a command every midnight. +Sam Steingold wrote @file{midnight.el}, a package for running a +command every midnight. @item Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for browsing indices made from buffer contents. @item -Peter Stephenson wrote @file{vcursor.el}, which implements a ``virtual -cursor'' that you can move with the keyboard and use for copying text. +Peter Stephenson wrote @file{vcursor.el}, which implements a virtual +cursor that you can move with the keyboard and use for copying text. @item Ken Stevens wrote @file{ispell.el}, a spell-checker interface. @item Kim F. Storm made many improvements to the Emacs display engine, -process support, and networking support. He also wrote +process support, and networking support. He also wrote @file{bindat.el}, a package for encoding and decoding binary data; CUA mode, which allows Emacs to emulate the standard CUA key bindings; @file{ido.el}, a package for selecting buffers and files @@ -1232,7 +1232,7 @@ the keyboard. @item Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing -image files as ``thumbnails''. +image files as thumbnails. @item Spencer Thomas wrote the original @file{dabbrev.el}, providing a command @@ -1276,7 +1276,7 @@ for Gnus; and @file{timezone.el}, providing functions for dealing with time zones. @item -Neil W. Van Dyke wrote @file{webjump.el}, a ``hot links'' package. +Neil W. Van Dyke wrote @file{webjump.el}, a Web hotlist package. @item Didier Verna wrote @file{rect.el}, a package of functions for @@ -1375,7 +1375,7 @@ manual pages without the @code{man} command. @item Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU linker scripts, and contributed subword handling and style -``guessing'' in CC mode. +guessing in CC mode. @item Jonathan Yavner wrote @file{testcover.el}, a package for keeping track @@ -1405,7 +1405,8 @@ zone out in front of Emacs. Eli Zaretskii made many standard Emacs features work on MS-DOS and Microsoft Windows. He also wrote @file{tty-colors.el}, which implements transparent mapping of X colors to tty colors; and -@file{rxvt.el}. He implemented support for bidirectional text. +@file{rxvt.el}. He implemented support for bidirectional text, +and also menus on text-mode terminals. @item Jamie Zawinski wrote much of the support for faces and X selections. diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi index 7e2b1324ac9..d702ff78b7c 100644 --- a/doc/emacs/anti.texi +++ b/doc/emacs/anti.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2005-2013 Free Software Foundation, Inc. +@c Copyright (C) 2005-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Antinews @@ -17,17 +17,17 @@ Support for displaying and editing ``bidirectional'' text has been removed. Text is now always displayed on the screen in a single consistent direction---left to right---regardless of the underlying script. Similarly, @kbd{C-f} and @kbd{C-b} always move the text -cursor to the right and left respectively. Also, @key{right} and -@key{left} are now equivalent to @kbd{C-f} and @kbd{C-b}, as you might +cursor to the right and left respectively. Also, @key{RIGHT} and +@key{LEFT} are now equivalent to @kbd{C-f} and @kbd{C-b}, as you might expect, rather than moving forward or backward based on the underlying ``paragraph direction''. -Users of ``right-to-left'' languages, like Arabic and Hebrew, may +Users of right-to-left languages, like Arabic and Hebrew, may adapt by reading and/or editing text in left-to-right order. @item The Emacs Lisp package manager has been removed. Instead of using a -``user interface'' (@kbd{M-x list-packages}), additional Lisp packages +user interface (@kbd{M-x list-packages}), additional Lisp packages must now be installed by hand, which is the most flexible and ``Lispy'' method anyway. Typically, this just involves editing your init file to add the package installation directory to the load path @@ -36,7 +36,7 @@ and/or README file for details. @item The option @code{delete-active-region} has been deleted. When the -region is active, typing @key{DEL} or @key{delete} no longer deletes +region is active, typing @key{DEL} or @key{Delete} no longer deletes the text in the region; it deletes a single character instead. @item @@ -89,7 +89,7 @@ scroll bars. Emacs no longer refers to GTK+ to set the default @item Setting the option @code{delete-by-moving-to-trash} to a -non-@code{nil} now causes all file deletions to use the system trash, +non-@code{nil} value now causes all file deletions to use the system trash, even temporary files created by Lisp programs; furthermore, the @kbd{M-x delete-file} and @kbd{M-x delete-directory} commands no longer accept prefix arguments to force true deletion. diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index f3b21c491d2..69431c65983 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @@ -17,13 +17,13 @@ of buffers for which it is implemented (listed in the menu below). Like file buffers, non-file buffers should normally not revert while you are working on them, or while they contain information that might get lost after reverting. Therefore, they do not revert if they are -``modified''. This can get tricky, because deciding when a non-file +modified. This can get tricky, because deciding when a non-file buffer should be marked modified is usually more difficult than for file buffers. Another tricky detail is that, for efficiency reasons, Auto Revert often does not try to detect all possible changes in the buffer, only -changes that are ``major'' or easy to detect. Hence, enabling +changes that are major or easy to detect. Hence, enabling auto-reverting for a non-file buffer does not always guarantee that all information in the buffer is up-to-date, and does not necessarily make manual reverts useless. @@ -47,9 +47,10 @@ explained in the corresponding sections. @subsection Auto Reverting the Buffer Menu If auto-reverting of non-file buffers is enabled, the Buffer Menu -automatically reverts every @code{auto-revert-interval} seconds, -whether there is a need for it or not. (It would probably take longer -to check whether there is a need than to actually revert.) +(@pxref{Several Buffers}) automatically reverts every +@code{auto-revert-interval} seconds, whether there is a need for it or +not. (It would probably take longer to check whether there is a need +than to actually revert.) If the Buffer Menu inappropriately gets marked modified, just revert it manually using @kbd{g} and auto-reverting will resume. However, if @@ -103,15 +104,15 @@ arguments to list only some of the files. @file{*Find*} and This section is intended for Elisp programmers who would like to add support for auto-reverting new types of buffers. -To support auto-reverting the buffer must first of all have a +To support auto-reverting the buffer must first of all have a suitable @code{revert-buffer-function}. @xref{Definition of revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. -In addition, it @emph{must} have a @code{buffer-stale-function}. +In addition, it must have a suitable @code{buffer-stale-function}. @c FIXME only defvar in all of doc/emacs! @defvar buffer-stale-function -The value of this variable is a function to check whether a non-file +The value of this variable is a function to check whether a buffer needs reverting. This should be a function with one optional argument @var{noconfirm}. The function should return non-@code{nil} if the buffer should be reverted. The buffer is current when this @@ -132,7 +133,7 @@ If you just want to automatically auto-revert every @code{auto-revert-interval} seconds (like the Buffer Menu), use: @example -(set (make-local-variable 'buffer-stale-function) +(setq-local buffer-stale-function #'(lambda (&optional noconfirm) 'fast)) @end example @@ -149,7 +150,7 @@ also be useful if the function is consulted for purposes other than auto-reverting. @end defvar -Once the buffer has a @code{revert-buffer-function} and a +Once the buffer has a suitable @code{revert-buffer-function} and @code{buffer-stale-function}, several problems usually remain. The buffer will only auto-revert if it is marked unmodified. Hence, diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index a840f912656..e5d34c62a57 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -1,5 +1,6 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Basic @@ -40,14 +41,20 @@ forward, so that point remains just after the inserted text. @xref{Point}. @kindex RET +@kindex C-j @cindex newline +@c @findex electric-indent-just-newline To end a line and start a new one, type @key{RET} (@code{newline}). (The @key{RET} key may be labeled @key{Return} or @key{Enter} on your keyboard, but we refer to it as @key{RET} in this manual.) This -command inserts a newline character into the buffer. If point is at -the end of the line, the effect is to create a new blank line after -it; if point is in the middle of a line, the line is split at that -position. +command inserts a newline character into the buffer, then indents +(@pxref{Indentation}) according to the major mode. If point is at the end +of the line, the effect is to create a new blank line after it and +indent the new line; if point is in the middle of a line, the line is +split at that position. To turn off the auto-indentation, you can +either disable Electric Indent mode (@pxref{Indent Convenience}) or +type @kbd{C-j}, which inserts just a newline, without any +auto-indentation. As we explain later in this manual, you can change the way Emacs handles text insertion by turning on @dfn{minor modes}. For instance, @@ -61,7 +68,7 @@ instead of shoving it to the right. @xref{Minor Modes}. @findex quoted-insert Only graphic characters can be inserted by typing the associated key; other keys act as editing commands and do not insert themselves. -For instance, @kbd{DEL} runs the command @code{delete-backward-char} +For instance, @key{DEL} runs the command @code{delete-backward-char} by default (some modes bind it to a different command); it does not insert a literal @samp{DEL} character (@acronym{ASCII} character code 127). @@ -98,10 +105,22 @@ the letters @kbd{a} to @kbd{f} serve as part of a character code, just like digits. Case is ignored. @findex insert-char -@kindex C-x 8 RET +@kindex C-x 8 @cindex Unicode characters, inserting @cindex insert Unicode character @cindex characters, inserting by name or code-point +@cindex curly quotes +@cindex curved quotes + A few common Unicode characters can be inserted via a command +starting with @kbd{C-x 8}. For example, @kbd{C-x 8 [} inserts @t{‘} +which is Unicode code-point @code{U+2018} LEFT SINGLE QUOTATION MARK, +sometimes called a left single ``curved quote'' or ``curly quote''. +Similarly, @kbd{C-x 8 ]}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the +curved quotes @t{’}, @t{“} and @t{”}, respectively. Also, a working +Alt key acts like @kbd{C-x 8}; e.g., @kbd{A-[} acts like @kbd{C-x 8 [} +and inserts @t{‘}. To see which characters have @kbd{C-x 8} +shorthands, type @kbd{C-x 8 C-h}. + Alternatively, you can use the command @kbd{C-x 8 @key{RET}} (@code{insert-char}). This prompts for the Unicode name or code-point of a character, using the minibuffer. If you enter a name, the @@ -110,15 +129,26 @@ code-point, it should be as a hexadecimal number (the convention for Unicode), or a number with a specified radix, e.g., @code{#o23072} (octal); @xref{Integer Basics,,, elisp, The Emacs Lisp Reference Manual}. The command then inserts the corresponding character into -the buffer. For example, both of the following insert the infinity -sign (Unicode code-point @code{U+221E}): +the buffer. + + In some contexts, if you type a quotation using grave accent and +apostrophe @t{`like this'}, it is converted to a form @t{‘like this’} +using single quotation marks. Similarly, typing a quotation @t{``like +this''} using double grave accent and apostrophe converts it to a form +@t{“like this”} using double quotation marks. @xref{Quotation Marks}. + + For example, the following all insert the same character: @example -@kbd{C-x 8 @key{RET} infinity @key{RET}} -@kbd{C-x 8 @key{RET} 221e @key{RET}} +@kbd{C-x 8 @key{RET} left single quotation mark @key{RET}} +@kbd{C-x 8 @key{RET} left sin @key{TAB} @key{RET}} +@kbd{C-x 8 @key{RET} 2018 @key{RET}} +@kbd{C-x 8 [} +@kbd{A-[} @r{(if the Alt key works)} +@kbd{`} @r{(in Electric Quote mode)} @end example - A numeric argument to @kbd{C-q} or @kbd{C-x 8 @key{RET}} specifies + A numeric argument to @kbd{C-q} or @kbd{C-x 8 ...} specifies how many copies of the character to insert (@pxref{Arguments}). @node Moving Point @@ -133,8 +163,8 @@ how many copies of the character to insert (@pxref{Arguments}). point (@pxref{Point}). The keyboard commands @kbd{C-f}, @kbd{C-b}, @kbd{C-n}, and @kbd{C-p} move point to the right, left, down, and up, respectively. You can also move point using the @dfn{arrow keys} -present on most keyboards: @kbd{@key{right}}, @kbd{@key{left}}, -@kbd{@key{down}}, and @kbd{@key{up}}; however, many Emacs users find +present on most keyboards: @key{RIGHT}, @key{LEFT}, +@key{DOWN}, and @key{UP}; however, many Emacs users find that it is slower to use the arrow keys than the control keys, because you need to move your hand to the area of the keyboard where those keys are located. @@ -150,7 +180,7 @@ keyboard commands that move point in more sophisticated ways. @findex forward-char Move forward one character (@code{forward-char}). -@item @key{right} +@item @key{RIGHT} @kindex RIGHT @findex right-char @vindex visual-order-cursor-movement @@ -170,7 +200,7 @@ away, depending on the surrounding bidirectional context. @findex backward-char Move backward one character (@code{backward-char}). -@item @key{left} +@item @key{LEFT} @kindex LEFT @findex left-char This command (@code{left-char}) behaves like @kbd{C-b}, except it @@ -181,7 +211,7 @@ left of the current screen position, moving to the previous or next screen line as appropriate. @item C-n -@itemx @key{down} +@itemx @key{DOWN} @kindex C-n @kindex DOWN @findex next-line @@ -190,7 +220,7 @@ to keep the horizontal position unchanged, so if you start in the middle of one line, you move to the middle of the next. @item C-p -@itemx @key{up} +@itemx @key{UP} @kindex C-p @kindex UP @findex previous-line @@ -200,14 +230,14 @@ preserves position within the line, like @kbd{C-n}. @item C-a @itemx @key{Home} @kindex C-a -@kindex HOME +@kindex HOME key @findex move-beginning-of-line Move to the beginning of the line (@code{move-beginning-of-line}). @item C-e @itemx @key{End} @kindex C-e -@kindex END +@kindex END key @findex move-end-of-line Move to the end of the line (@code{move-end-of-line}). @@ -216,8 +246,8 @@ Move to the end of the line (@code{move-end-of-line}). @findex forward-word Move forward one word (@code{forward-word}). -@item C-@key{right} -@itemx M-@key{right} +@item C-@key{RIGHT} +@itemx M-@key{RIGHT} @kindex C-RIGHT @kindex M-RIGHT @findex right-word @@ -230,12 +260,12 @@ right-to-left. @xref{Bidirectional Editing}. @findex backward-word Move backward one word (@code{backward-word}). -@item C-@key{left} -@itemx M-@key{left} +@item C-@key{LEFT} +@itemx M-@key{LEFT} @kindex C-LEFT @kindex M-LEFT @findex left-word -This command (@code{left-word}) behaves like @kbd{M-f}, except it +This command (@code{left-word}) behaves like @kbd{M-b}, except it moves @emph{forward} by one word if the current paragraph is right-to-left. @xref{Bidirectional Editing}. @@ -360,7 +390,7 @@ moves down into it. @table @kbd @item @key{DEL} -@itemx @key{Backspace} +@itemx @key{BACKSPACE} Delete the character before point, or the region if it is active (@code{delete-backward-char}). @@ -388,20 +418,20 @@ the preceding newline, joining this line to the previous one. If, however, the region is active, @kbd{@key{DEL}} instead deletes the text in the region. @xref{Mark}, for a description of the region. - On most keyboards, @key{DEL} is labeled @key{Backspace}, but we + On most keyboards, @key{DEL} is labeled @key{BACKSPACE}, but we refer to it as @key{DEL} in this manual. (Do not confuse @key{DEL} with the @key{Delete} key; we will discuss @key{Delete} momentarily.) On some text terminals, Emacs may not recognize the @key{DEL} key properly. @xref{DEL Does Not Delete}, if you encounter this problem. - The @key{delete} (@code{delete-forward-char}) command deletes in the -``opposite direction'': it deletes the character after point, i.e., the + The @key{Delete} (@code{delete-forward-char}) command deletes in the +opposite direction: it deletes the character after point, i.e., the character under the cursor. If point was at the end of a line, this joins the following line onto this one. Like @kbd{@key{DEL}}, it deletes the text in the region if the region is active (@pxref{Mark}). @kbd{C-d} (@code{delete-char}) deletes the character after point, -similar to @key{delete}, but regardless of whether the region is +similar to @key{Delete}, but regardless of whether the region is active. @xref{Deletion}, for more detailed information about the above @@ -717,7 +747,7 @@ M-5 C-n moves down five lines. The keys @kbd{M-1}, @kbd{M-2}, and so on, as well as @kbd{M--}, are bound to commands (@code{digit-argument} and @code{negative-argument}) that set up an argument for the next -command. @kbd{Meta--} without digits normally means @minus{}1. +command. @kbd{M--} without digits normally means @minus{}1. If you enter more than one digit, you need not hold down the @key{META} key for the second and subsequent digits. Thus, to move @@ -733,7 +763,7 @@ down one line, as you might expect---the @samp{0} is treated as part of the prefix argument. (What if you do want to insert five copies of @samp{0}? Type @kbd{M-5 -C-u 0}. Here, @kbd{C-u} ``terminates'' the prefix argument, so that +C-u 0}. Here, @kbd{C-u} terminates the prefix argument, so that the next keystroke begins the command that you want to execute. Note that this meaning of @kbd{C-u} applies only to this case. For the usual role of @kbd{C-u}, see below.) @@ -751,7 +781,7 @@ multiplies the argument for the next command by four. @kbd{C-u C-u} multiplies it by sixteen. Thus, @kbd{C-u C-u C-f} moves forward sixteen characters. Other useful combinations are @kbd{C-u C-n}, @kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u -C-u C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four +C-u C-o} (make sixteen blank lines), and @kbd{C-u C-k} (kill four lines). You can use a numeric argument before a self-inserting character to diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 2d3ff5b05d8..5a4d1abfc39 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Buffers @@ -43,15 +43,15 @@ variables}---variables that can have a different value in each buffer. A buffer's size cannot be larger than some maximum, which is defined by the largest buffer position representable by @dfn{Emacs integers}. This is because Emacs tracks buffer positions using that data type. -For typical 64-bit machines, this maximum buffer size is @math{2^61 - -2} bytes, or about 2 EiB@. For typical 32-bit machines, the maximum is -usually @math{2^29 - 2} bytes, or about 512 MiB@. Buffer sizes are +For typical 64-bit machines, this maximum buffer size is @math{2^{61} - 2} +bytes, or about 2 EiB@. For typical 32-bit machines, the maximum is +usually @math{2^{29} - 2} bytes, or about 512 MiB@. Buffer sizes are also limited by the amount of memory in the system. @menu * Select Buffer:: Creating a new buffer or reselecting an old one. * List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onlyness; copying text. +* Misc Buffer:: Renaming; changing read-only status; copying text. * Kill Buffer:: Killing buffers you no longer need. * Several Buffers:: How to go through the list of all buffers and operate variously on several of them. @@ -94,7 +94,7 @@ now displayed in any window. While entering the buffer name, you can use the usual completion and history commands (@pxref{Minibuffer}). Note that @kbd{C-x b}, and -related commands, use ``permissive completion with confirmation'' for +related commands, use @dfn{permissive completion with confirmation} for minibuffer completion: if you type @key{RET} immediately after completing up to a nonexistent buffer name, Emacs prints @samp{[Confirm]} and you must type a second @key{RET} to submit that @@ -174,13 +174,13 @@ List the existing buffers (@code{list-buffers}). @kindex C-x C-b @findex list-buffers To display a list of existing buffers, type @kbd{C-x C-b}. Each -line in the list shows one buffer's name, major mode and visited file. +line in the list shows one buffer's name, size, major mode and visited file. The buffers are listed in the order that they were current; the buffers that were current most recently come first. @samp{.} in the first field of a line indicates that the buffer is current. @samp{%} indicates a read-only buffer. @samp{*} indicates -that the buffer is ``modified''. If several buffers are modified, it +that the buffer is modified. If several buffers are modified, it may be time to save some with @kbd{C-x s} (@pxref{Save Commands}). Here is an example of a buffer list: @@ -194,7 +194,7 @@ CRM Buffer Size Mode File % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS *scratch* 191 Lisp Interaction - * *Messages* 1554 Fundamental + * *Messages* 1554 Messages @end smallexample @noindent @@ -226,10 +226,10 @@ Scroll through buffer @var{buffer}. @xref{View Mode}. @cindex read-only buffer A buffer can be @dfn{read-only}, which means that commands to change its contents are not allowed. The mode line indicates read-only -buffers with @samp{%%} or @samp{%*} near the left margin. Read-only -buffers are usually made by subsystems such as Dired and Rmail that -have special commands to operate on the text; also by visiting a file -whose access control says you cannot write it. +buffers with @samp{%%} or @samp{%*} near the left margin. @xref{Mode +Line}. Read-only buffers are usually made by subsystems such as Dired +and Rmail that have special commands to operate on the text; also by +visiting a file whose access control says you cannot write it. @findex read-only-mode @vindex view-read-only @@ -269,11 +269,16 @@ can also be used to copy text from one buffer to another. @section Killing Buffers @cindex killing buffers +@cindex close buffer +@cindex close file If you continue an Emacs session for a while, you may accumulate a large number of buffers. You may then find it convenient to @dfn{kill} -the buffers you no longer need. On most operating systems, killing a -buffer releases its space back to the operating system so that other -programs can use it. Here are some commands for killing buffers: +the buffers you no longer need. (Some other editors call this +operation @dfn{close}, and talk about ``closing the buffer'' or +``closing the file'' visited in the buffer.) On most operating +systems, killing a buffer releases its space back to the operating +system so that other programs can use it. Here are some commands for +killing buffers: @table @kbd @item C-x k @var{bufname} @key{RET} @@ -344,7 +349,7 @@ the Customization buffer to set the variable @code{midnight-mode} to @table @kbd @item M-x buffer-menu Begin editing a buffer listing all Emacs buffers. -@item M-x buffer-menu-other-window. +@item M-x buffer-menu-other-window Similar, but do it in another window. @end table @@ -515,7 +520,7 @@ the @var{n}-th column (@code{tabulated-list-sort}). @findex Buffer-menu-toggle-files-only @kindex T @r{(Buffer Menu)} Delete, or reinsert, lines for non-file buffers -@code{Buffer-menu-toggle-files-only}). This command toggles the +(@code{Buffer-menu-toggle-files-only}). This command toggles the inclusion of such buffers in the buffer list. @end table @@ -598,7 +603,7 @@ convenient to switch between buffers. @menu * Uniquify:: Making buffer names unique with directory parts. -* Iswitchb:: Switching between buffers with substrings. +* Icomplete:: Fast minibuffer selection. * Buffer Menus:: Configurable buffer menu. @end menu @@ -608,32 +613,36 @@ convenient to switch between buffers. @cindex unique buffer names @cindex directories in buffer names When several buffers visit identically-named files, Emacs must give -the buffers distinct names. The usual method for making buffer names -unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer -names (all but one of them). +the buffers distinct names. The default method adds a suffix based on +the names of the directories that contain the files. For example, if +you visit files @file{/foo/bar/mumble/name} and +@file{/baz/quux/mumble/name} at the same time, their buffers will be +named @samp{name<bar/mumble>} and @samp{name<quux/mumble>}, respectively. +Emacs adds as many directory parts as are needed to make a unique name. @vindex uniquify-buffer-name-style - Other methods work by adding parts of each file's directory to the -buffer name. To select one, load the library @file{uniquify} (e.g., -using @code{(require 'uniquify)}), and customize the variable -@code{uniquify-buffer-name-style} (@pxref{Easy Customization}). - - To begin with, the @code{forward} naming method includes part of the -file's directory name at the beginning of the buffer name; using this -method, buffers visiting the files @file{/u/rms/tmp/Makefile} and + You can choose from several different styles for constructing unique +buffer names, by customizing the option @code{uniquify-buffer-name-style}. + + The @code{forward} naming method includes part of the file's +directory name at the beginning of the buffer name; using this method, +buffers visiting the files @file{/u/rms/tmp/Makefile} and @file{/usr/projects/zaphod/Makefile} would be named -@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead -of @samp{Makefile} and @samp{Makefile<2>}). +@samp{tmp/Makefile} and @samp{zaphod/Makefile}. In contrast, the @code{post-forward} naming method would call the -buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the +buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}. The default +method @code{post-forward-angle-brackets} is like @code{post-forward}, +except that it encloses the unique path in angle brackets. The @code{reverse} naming method would call them @samp{Makefile\tmp} and @samp{Makefile\zaphod}. The nontrivial difference between @code{post-forward} and @code{reverse} occurs when just one directory name is not enough to distinguish two files; then @code{reverse} puts the directory names in reverse order, so that @file{/top/middle/file} becomes @samp{file\middle\top}, while @code{post-forward} puts them in -forward order after the file name, as in @samp{file|top/middle}. +forward order after the file name, as in @samp{file|top/middle}. If +@code{uniquify-buffer-name-style} is set to @code{nil}, the buffer +names simply get @samp{<2>}, @samp{<3>}, etc.@: appended. Which rule to follow for putting the directory names in the buffer name is not very important if you are going to @emph{look} at the @@ -641,39 +650,32 @@ buffer names before you type one. But as an experienced user, if you know the rule, you won't have to look. And then you may find that one rule or another is easier for you to remember and apply quickly. -@node Iswitchb -@subsection Switching Between Buffers using Substrings - -@findex iswitchb-mode -@cindex Iswitchb mode -@cindex mode, Iswitchb -@kindex C-x b @r{(Iswitchb mode)} -@kindex C-x 4 b @r{(Iswitchb mode)} -@kindex C-x 5 b @r{(Iswitchb mode)} -@kindex C-x 4 C-o @r{(Iswitchb mode)} - - Iswitchb global minor mode provides convenient switching between -buffers using substrings of their names. It replaces the normal -definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x -4 C-o} with alternative commands that are somewhat ``smarter''. - - When one of these commands prompts you for a buffer name, you can -type in just a substring of the name you want to choose. As you enter -the substring, Iswitchb mode continuously displays a list of buffers -that match the substring you have typed. - - At any time, you can type @key{RET} to select the first buffer in -the list. So the way to select a particular buffer is to make it the -first in the list. There are two ways to do this. You can type more -of the buffer name and thus narrow down the list, excluding unwanted -buffers above the desired one. Alternatively, you can use @kbd{C-s} -and @kbd{C-r} to rotate the list until the desired buffer is first. +@node Icomplete +@subsection Fast minibuffer selection - @key{TAB} while entering the buffer name performs completion on the -string you have entered, based on the displayed list of buffers. +@findex icomplete-mode +@cindex Icomplete mode - To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize -the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy + Icomplete global minor mode provides a convenient way to quickly select an +element among the possible completions in a minibuffer. When enabled, typing +in the minibuffer continuously displays a list of possible completions that +match the string you have typed. + + At any time, you can type @kbd{C-j} to select the first completion in +the list. So the way to select a particular completion is to make it the +first in the list. There are two ways to do this. You can type more +of the completion name and thus narrow down the list, excluding unwanted +completions above the desired one. Alternatively, you can use @kbd{C-.} +and @kbd{C-,} to rotate the list until the desired buffer is first. + + @kbd{M-@key{TAB}} will select the first completion in the list, like +@kbd{C-j} but without exiting the minibuffer, so you can edit it +further. This is typically used when entering a file name, where +@kbd{M-@key{TAB}} can be used a few times to descend in the hierarchy +of directories. + + To enable Icomplete mode, type @kbd{M-x icomplete-mode}, or customize +the variable @code{icomplete-mode} to @code{t} (@pxref{Easy Customization}). @node Buffer Menus diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 1072d49ea20..fbef9feb5a6 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Building @@ -322,7 +322,7 @@ nohup @var{command}; sleep 1 @end example @ifnottex - On the MS-DOS ``operating system'', asynchronous subprocesses are + On MS-DOS, asynchronous subprocesses are not supported, so @kbd{M-x compile} runs the compilation command synchronously (i.e., you must wait until the command finishes before you can do anything else in Emacs). @xref{MS-DOS}. @@ -334,7 +334,7 @@ you can do anything else in Emacs). @xref{MS-DOS}. Just as you can run a compiler from Emacs and then visit the lines with compilation errors, you can also run @command{grep} and then visit the lines on which matches were found. This works by treating -the matches reported by @command{grep} as if they were ``errors''. +the matches reported by @command{grep} as if they were errors. The output buffer uses Grep mode, which is a variant of Compilation mode (@pxref{Compilation Mode}). @@ -618,12 +618,12 @@ associated with an identifier when the program is not executing. selecting stack frames, and stepping through the program. @table @kbd -@item C-x @key{SPC} -@kindex C-x SPC +@item C-x C-a C-b +@kindex C-x C-a C-b Set a breakpoint on the source line that point is on. @end table - @kbd{C-x @key{SPC}} (@code{gud-break}), when called in a source + @kbd{C-x C-a C-b} (@code{gud-break}), when called in a source buffer, sets a debugger breakpoint on the current source line. This command is available only after starting GUD@. If you call it in a buffer that is not associated with any debugger subprocess, it signals @@ -800,12 +800,12 @@ the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to @table @samp @item %f The name of the current source file. If the current buffer is the GUD -buffer, then the ``current source file'' is the file that the program +buffer, then the current source file is the file that the program stopped in. @item %l The number of the current source line. If the current buffer is the GUD -buffer, then the ``current source line'' is the line that the program +buffer, then the current source line is the line that the program stopped in. @item %e @@ -848,7 +848,7 @@ GUD}). You must use this if you want to debug multiple programs within one Emacs session, as that is currently unsupported by @kbd{M-x gdb}. - Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is + Internally, @kbd{M-x gdb} informs GDB that its screen size is unlimited; for correct operation, you must not change GDB's screen height and width values during the debugging session. @@ -893,8 +893,8 @@ displays the following frame layout: @findex gdb-restore-windows @findex gdb-many-windows - If you ever change the window layout, you can restore the ``many -windows'' layout by typing @kbd{M-x gdb-restore-windows}. To toggle + If you ever change the window layout, you can restore the many-windows +layout by typing @kbd{M-x gdb-restore-windows}. To toggle between the many windows layout and a simple layout with just the GUD interaction buffer and a source file, type @kbd{M-x gdb-many-windows}. @@ -947,7 +947,7 @@ of the window. Disabled breakpoints are indicated with @samp{b}. (The margin is only displayed if a breakpoint is present.) A solid arrow in the left fringe of a source buffer indicates the -line of the innermost frame where the debugged program has stopped. A +line of the innermost frame where the debugged program has stopped. A hollow arrow indicates the current execution line of a higher-level frame. If you drag the arrow in the fringe with @kbd{Mouse-1}, that causes execution to advance to the line where you release the button. @@ -1005,7 +1005,7 @@ non-@code{nil}, the GDB Threads buffer is the one shown by default. The GDB Threads buffer displays a summary of the threads in the debugged program. @xref{Threads, Threads, Debugging programs with multiple threads, gdb, The GNU debugger}. To select a thread, move -point there and type @key{RET} (@code{gdb-select-thread}), or click on +point there and press @key{RET} (@code{gdb-select-thread}), or click on it with @kbd{Mouse-2}. This also displays the associated source buffer, and updates the contents of the other GDB buffers. @@ -1138,7 +1138,7 @@ size for these data items. When @code{gdb-many-windows} is non-@code{nil}, the locals buffer shares its window with the registers buffer, just like breakpoints and -threads buffers. To switch from one to the other, click with +threads buffers. To switch from one to the other, click with @kbd{Mouse-1} on the relevant button in the header line. @node Watch Expressions @@ -1348,6 +1348,7 @@ not from an existing Emacs buffer. @findex load @findex load-library +@vindex load-prefer-newer @cindex load path for Emacs Lisp If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path} (defined below), you can load it by typing @kbd{M-x load-library}, @@ -1356,15 +1357,18 @@ command prompts for a @dfn{library name} rather than a file name; it searches through each directory in the Emacs Lisp load path, trying to find a file matching that library name. If the library name is @samp{@var{foo}}, it tries looking for files named -@file{@var{foo}.elc}, @file{@var{foo}.el}, and lastly just -@file{@var{foo}}; the first one found is loaded. This command prefers -@file{.elc} files over @file{.el} files because compiled files load -and run faster. If it finds that @file{@var{lib}.el} is newer than -@file{@var{lib}.elc}, it issues a warning, in case someone made +@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. The +default behavior is to load the first file found. This command +prefers @file{.elc} files over @file{.el} files because compiled files +load and run faster. If it finds that @file{@var{lib}.el} is newer +than @file{@var{lib}.elc}, it issues a warning, in case someone made changes to the @file{.el} file and forgot to recompile it, but loads the @file{.elc} file anyway. (Due to this behavior, you can save unfinished edits to Emacs Lisp source files, and not recompile until -your changes are ready for use.) +your changes are ready for use.) If you set the option +@code{load-prefer-newer} to a non-@code{nil} value, however, then +rather than the procedure described above, Emacs loads whichever +version of the file is newest. Emacs Lisp programs usually load Emacs Lisp files using the @code{load} function. This is similar to @code{load-library}, but is @@ -1422,6 +1426,7 @@ Emacs to crash. Set the variable @code{load-dangerous-libraries} to @section Evaluating Emacs Lisp Expressions @cindex Emacs Lisp mode @cindex mode, Emacs Lisp +@cindex evaluation, Emacs Lisp @findex emacs-lisp-mode Emacs Lisp mode is the major mode for editing Emacs Lisp. Its mode @@ -1452,8 +1457,8 @@ Evaluate all the Emacs Lisp expressions in the buffer. @end table @ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu +@c This uses 'colon' instead of a literal ':' because Info cannot +@c cope with a ':' in a menu. @kindex M-@key{colon} @end ifinfo @ifnotinfo @@ -1471,13 +1476,17 @@ expression.) The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Emacs Lisp expression preceding point in the buffer, and displays the value in the echo area. When the result of an evaluation is an -integer, you can type @kbd{C-x C-e} a second time to display the value -of the integer result in additional formats (octal, hexadecimal, and -character). +integer, it is displayed together with the value in other formats +(octal, hexadecimal, and character). If @kbd{M-:} or @kbd{C-x C-e} is given a prefix argument, it inserts the value into the current buffer at point, rather than displaying it -in the echo area. The argument's value does not matter. +in the echo area. If the prefix argument is zero, any integer output +is inserted together with its value in other formats (octal, +hexadecimal, and character). Such a prefix argument also prevents +abbreviation of the output according to the variables +@code{eval-expression-print-level} and @code{eval-expression-print-length} +(see below). @kindex C-M-x @r{(Emacs Lisp mode)} @findex eval-defun @@ -1511,9 +1520,11 @@ eval-buffer} is similar but evaluates the entire buffer. The options @code{eval-expression-print-level} and @code{eval-expression-print-length} control the maximum depth and length of lists to print in the result of the evaluation commands -before abbreviating them. @code{eval-expression-debug-on-error} -controls whether evaluation errors invoke the debugger when these -commands are used; its default is @code{t}. +before abbreviating them. Supplying a zero prefix argument to +@code{eval-expression} or @code{eval-last-sexp} causes lists to be +printed in full. @code{eval-expression-debug-on-error} controls +whether evaluation errors invoke the debugger when these commands are +used; its default is @code{t}. @node Lisp Interaction @section Lisp Interaction Buffers @@ -1538,7 +1549,7 @@ mode are the same as in Emacs Lisp mode. At startup, the @file{*scratch*} buffer contains a short message, in the form of a Lisp comment, that explains what it is for. This message is controlled by the variable @code{initial-scratch-message}, -which should be either a string, or @code{nil} (which means to +which should be either a documentation string, or @code{nil} (which means to suppress the message). @findex ielm diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index 5c964bbb369..3b5b3c58a65 100644 --- a/doc/emacs/cal-xtra.texi +++ b/doc/emacs/cal-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -*- coding: utf-8 -*- -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @@ -43,9 +43,12 @@ customize the variables @code{calendar-intermonth-header} and @code{calendar-intermonth-text} as described in their documentation. @vindex calendar-month-header +@vindex calendar-day-header-array The variable @code{calendar-month-header} controls the text that appears above each month in the calendar. By default, it shows the -month and year. +month and year. The variable @code{calendar-day-header-array} +controls the text that appears above each day's column in every month. +By default, it shows the first two letters of each day's name. @vindex calendar-holiday-marker @vindex diary-entry-marker @@ -68,7 +71,7 @@ the calendar). Starting the calendar runs the normal hook @code{calendar-initial-window-hook}. Recomputation of the calendar display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again.@refill +@kbd{q} command and reenter it, the hook runs again. @vindex calendar-today-visible-hook @findex calendar-star-date @@ -140,7 +143,7 @@ all) of the variables @code{calendar-bahai-all-holidays-flag}, Each of the holiday variables is a list of @dfn{holiday forms}, each form describing a holiday (or sometimes a list of holidays). Here is a table of the possible kinds of holiday form. Day numbers and month -numbers count starting from 1, but ``dayname'' numbers count Sunday as +numbers count starting from 1, but @dfn{dayname} numbers count Sunday as 0. The argument @var{string} is always the description of the holiday, as a string. @@ -191,14 +194,14 @@ can do this as follows: Many holidays occur on a specific day of the week, at a specific time of month. Here is a holiday form describing Hurricane Supplication Day, -celebrated in the Virgin Islands on the fourth Monday in August: +celebrated in the Virgin Islands on the fourth Monday in July: @smallexample -(holiday-float 8 1 4 "Hurricane Supplication Day") +(holiday-float 7 1 4 "Hurricane Supplication Day") @end smallexample @noindent -Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, +Here the 7 specifies July, the 1 specifies Monday (Sunday is 0, Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in the month (1 specifies the first occurrence, 2 the second occurrence, @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and @@ -514,7 +517,7 @@ the fourth pattern. @subsection Diary Entries Using non-Gregorian Calendars As well as entries based on the standard Gregorian calendar, your -diary can have entries based on Bahá'í, Hebrew, or Islamic dates. +diary can have entries based on Bahá'í, Chinese, Hebrew, or Islamic dates. Recognition of such entries can be time-consuming, however, and since most people don't use them, you must explicitly enable their use. If you want the diary to recognize Hebrew-date diary entries, for example, @@ -528,22 +531,27 @@ you must do this: @findex diary-islamic-mark-entries @findex diary-bahai-list-entries @findex diary-bahai-mark-entries +@findex diary-chinese-list-entries +@findex diary-chinese-mark-entries @smallexample (add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) (add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) @end smallexample @noindent -Similarly, for Islamic and Bahá'í entries, add -@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or -@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}. +Similarly, for Islamic, Bahá'í and Chinese entries, add +@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, +@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}, +or @code{diary-chinese-list-entries} and @code{diary-chinese-mark-entries}. @vindex diary-bahai-entry-symbol +@vindex diary-chinese-entry-symbol @vindex diary-hebrew-entry-symbol @vindex diary-islamic-entry-symbol These diary entries have the same formats as Gregorian-date diary entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) -must precede a Bahá'í date, @code{diary-hebrew-entry-symbol} (default +must precede a Bahá'í date, @code{diary-chinese-entry-symbol} (default +@samp{C}) a Chinese date, @code{diary-hebrew-entry-symbol} (default @samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default @samp{I}) an Islamic date. Moreover, non-Gregorian month names may not be abbreviated (because the first three letters are often not unique). @@ -570,7 +578,7 @@ nonmarking if preceded by @code{diary-nonmarking-symbol} (default Here is a table of commands used in the calendar to create diary entries that match the selected date and other dates that are similar in -the Bahá'í, Hebrew, or Islamic calendars: +the Bahá'í, Chinese, Hebrew, or Islamic calendars: @table @kbd @item i h d @@ -591,6 +599,14 @@ the Bahá'í, Hebrew, or Islamic calendars: @code{diary-bahai-insert-monthly-entry} @item i B y @code{diary-bahai-insert-yearly-entry} +@item i C d +@code{diary-chinese-insert-entry} +@item i C m +@code{diary-chinese-insert-monthly-entry} +@item i C y +@code{diary-chinese-insert-yearly-entry} +@item i C a +@code{diary-chinese-insert-anniversary-entry} @end table @findex diary-hebrew-insert-entry @@ -602,6 +618,11 @@ the Bahá'í, Hebrew, or Islamic calendars: @findex diary-bahai-insert-entry @findex diary-bahai-insert-monthly-entry @findex diary-bahai-insert-yearly-entry +@findex diary-chinese-insert-entry +@findex diary-chinese-insert-monthly-entry +@findex diary-chinese-insert-yearly-entry +@findex diary-chinese-insert-anniversary-entry + These commands work much like the corresponding commands for ordinary diary entries: they apply to the date that point is on in the calendar window, and what they do is insert just the date portion of a diary @@ -631,7 +652,7 @@ example, to sort the entries by the dates they apply to. Ordinarily, the fancy diary buffer does not show days for which there are no diary entries, even if that day is a holiday. If you want such days to be shown in the fancy diary buffer, set the variable -@code{diary-list-include-blanks} to @code{t}.@refill +@code{diary-list-include-blanks} to @code{t}. The fancy diary buffer enables View mode @iftex @@ -819,7 +840,7 @@ Renew medication (5th time) @noindent in the fancy diary display on September 7, 2012. - There is an ``early reminder'' diary sexp that includes its entry in the + There is an early-reminder diary sexp that includes its entry in the diary not only on the date of occurrence, but also on earlier dates. For example, if you want a reminder a week before your anniversary, you can use diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi index 88f46984207..bc13d4ba296 100644 --- a/doc/emacs/calendar.texi +++ b/doc/emacs/calendar.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -*- coding: utf-8 -*- -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Calendar/Diary @@ -57,7 +57,7 @@ For more advanced topics, Calendar mode provides commands to move through the calendar in logical units of time such as days, weeks, months, and years. If you move outside the three months originally displayed, the calendar -display ``scrolls'' automatically through time to make the selected +display scrolls automatically through time to make the selected date visible. Moving to a date lets you view its holidays or diary entries, or convert it to other calendars; moving by long time periods is also useful simply to scroll the calendar. @@ -177,10 +177,13 @@ repeat count indicating how many weeks, months, or years to move backward or forward. @vindex calendar-week-start-day +@vindex calendar-weekend-days @cindex weeks, which day they start on @cindex calendar, first day of week By default, weeks begin on Sunday. To make them begin on Monday -instead, set the variable @code{calendar-week-start-day} to 1. +instead, set the variable @code{calendar-week-start-day} to 1. To +change which day headers are highlighted as weekend days, set the +variable @code{calendar-weekend-days}. @node Specified Dates @subsection Specified Dates @@ -206,7 +209,7 @@ Move point to today's date (@code{calendar-goto-today}). @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day of the month, and then moves to that date. Because the calendar includes all dates from the beginning of the current era, you must type the year in its -entirety; that is, type @samp{1990}, not @samp{90}. +entirety; that is, type @samp{2010}, not @samp{10}. @kindex g D @r{(Calendar mode)} @findex calendar-goto-day-of-year @@ -266,7 +269,7 @@ contents one month backwards in time. @kindex M-v @r{(Calendar mode)} @findex calendar-scroll-right-three-months The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire -``screenful''---three months---in analogy with the usual meaning of +screenful---three months---in analogy with the usual meaning of these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes earlier dates visible. These commands take a numeric argument as a repeat count; in particular, since @kbd{C-u} multiplies the next command @@ -288,7 +291,7 @@ Display the number of days in the current region @kindex M-= @r{(Calendar mode)} @findex calendar-count-days-region To determine the number of days in a range, set the mark on one -date using @kbd{C-SPC}, move point to another date, and type @kbd{M-=} +date using @kbd{C-@key{SPC}}, move point to another date, and type @kbd{M-=} (@code{calendar-count-days-region}). The numbers of days shown is @emph{inclusive}; that is, it includes the days specified by mark and point. @@ -301,9 +304,10 @@ point. Display day-in-year (@code{calendar-print-day-of-year}). @item C-c C-l Regenerate the calendar window (@code{calendar-redraw}). -@item SPC +@item @key{SPC} Scroll the next window up (@code{scroll-other-window}). -@item DEL +@item @key{DEL} +@itemx S-@key{SPC} Scroll the next window down (@code{scroll-other-window-down}). @item q Exit from calendar (@code{calendar-exit}). @@ -326,8 +330,8 @@ date. non-Calendar-mode editing commands.) @kindex SPC @r{(Calendar mode)} - In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window}) -and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other + In Calendar mode, you can use @key{SPC} (@code{scroll-other-window}) +and @key{DEL} (@code{scroll-other-window-down}) to scroll the other window (if there is one) up or down, respectively. This is handy when you display a list of holidays or diary entries in another window. @@ -378,7 +382,7 @@ between years will not work. If the variable @code{cal-html-print-day-number-flag} is non-@code{nil}, then the monthly calendars show the day-of-the-year -number. The variable @code{cal-html-year-index-cols} specifies the +number. The variable @code{cal-html-year-index-cols} specifies the number of columns in the yearly index page. @cindex calendar and @LaTeX{} @@ -428,8 +432,8 @@ Generate a Filofax-style calendar for one year (@code{cal-tex-cursor-filofax-year}). @end table - Some of these commands print the calendar sideways (in ``landscape -mode''), so it can be wider than it is long. Some of them use Filofax + Some of these commands print the calendar sideways (in landscape +mode), so it can be wider than it is long. Some of them use Filofax paper size (3.75in x 6.75in). All of these commands accept a prefix argument, which specifies how many days, weeks, months or years to print (starting always with the selected one). @@ -627,8 +631,8 @@ for all users in a @file{default.el} file. @xref{Init File}. These calendar commands display the dates and times of the phases of the moon (new moon, first quarter, full moon, last quarter). This -feature is useful for debugging problems that ``depend on the phase of -the moon''. +feature is useful for debugging problems that depend on the phase of +the moon. @table @kbd @item M @@ -661,7 +665,7 @@ See the discussion in the previous section. @xref{Sunrise/Sunset}. @cindex Gregorian calendar The Emacs calendar displayed is @emph{always} the Gregorian calendar, -sometimes called the ``new style'' calendar, which is used in most of +sometimes called the New Style calendar, which is used in most of the world today. However, this calendar did not exist before the sixteenth century and was not widely used before the eighteenth century; it did not fully displace the Julian calendar and gain universal @@ -755,13 +759,13 @@ official calendar of Iran will be at that time. into solar years. The years go in cycles of sixty, each year containing either twelve months in an ordinary year or thirteen months in a leap year; each month has either 29 or 30 days. Years, ordinary months, and -days are named by combining one of ten ``celestial stems'' with one of -twelve ``terrestrial branches'' for a total of sixty names that are +days are named by combining one of ten @dfn{celestial stems} with one of +twelve @dfn{terrestrial branches} for a total of sixty names that are repeated in a cycle of sixty. @cindex Bahá'í calendar The Bahá'í calendar system is based on a solar cycle of 19 months with -19 days each. The four remaining ``intercalary'' days are placed +19 days each. The four remaining intercalary days are placed between the 18th and 19th months. @node To Other Calendar @@ -826,7 +830,7 @@ Display Mayan date for selected day (@code{calendar-mayan-print-date}). Otherwise, move point to the date you want to convert, then type the appropriate command starting with @kbd{p} from the table above. The prefix @kbd{p} is a mnemonic for ``print'', since Emacs ``prints'' the -equivalent date in the echo area. @kbd{p o} displays the +equivalent date in the echo area. @kbd{p o} displays the date in all forms known to Emacs. You can also use @kbd{Mouse-3} and then choose @kbd{Other calendars} from the menu that appears. This displays the equivalent forms of the date in all the calendars Emacs @@ -904,7 +908,7 @@ Islamic, or French names. @findex calendar-hebrew-list-yahrzeits @cindex yahrzeits One common issue concerning the Hebrew calendar is the computation -of the anniversary of a date of death, called a ``yahrzeit''. The Emacs +of the anniversary of a date of death, called a @dfn{yahrzeit}. The Emacs calendar includes a facility for such calculations. If you are in the calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for a range of years and then displays a list of the yahrzeit dates for those @@ -918,46 +922,95 @@ years, and then displays the list of yahrzeit dates. The Emacs diary keeps track of appointments or other events on a daily basis, in conjunction with the calendar. To use the diary feature, you -must first create a @dfn{diary file} containing a list of events and +must first create a diary file containing a list of events and their dates. Then Emacs can automatically pick out and display the events for today, for the immediate future, or for any specified date. - The name of the diary file is specified by the variable -@code{diary-file}; @file{~/diary} is the default. Here's an example -showing what that file looks like: + Although you probably will start by creating a diary manually, Emacs +provides a number of commands to let you view, add, and change diary +entries. + +@menu +* Format of Diary File:: Entering events in your diary. +* Displaying the Diary:: Viewing diary entries and associated calendar dates. +* Date Formats:: Various ways you can specify dates. +* Adding to Diary:: Commands to create diary entries. +* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. +@end menu + +@node Format of Diary File +@subsection The Diary File +@cindex diary file + +@vindex diary-file + Your @dfn{diary file} is a file that records events associated with +particular dates. The name of the diary file is specified by the +variable @code{diary-file}. The default is @file{~/.emacs.d/diary}, +though for compatibility with older versions Emacs will use +@file{~/diary} if it exists. +@ignore +@c I don't think this is relevant any more. The utility doesn't seem +@c to be part of the default install on GNU/Linux machines these days. +@c When I tried it with my basic diary file, it just died with an error. +The @code{calendar} utility program supports a subset of the format +allowed by the Emacs diary facilities, so you can use that utility to +view the diary file, with reasonable results aside from the entries it +cannot understand. +@end ignore + + Each entry in the diary file describes one event and consists of one +or more lines. An entry always begins with a date specification at the +left margin. The rest of the entry is simply text to describe the +event. If the entry has more than one line, then the lines after the +first must begin with whitespace to indicate they continue a previous +entry. Lines that do not begin with valid dates and do not continue a +preceding entry are ignored. Here's an example: @example -12/22/2012 Twentieth wedding anniversary!! -&1/1. Happy New Year! +12/22/2015 Twentieth wedding anniversary! 10/22 Ruth's birthday. * 21, *: Payday Tuesday--weekly meeting with grad students at 10am Supowit, Shen, Bitner, and Kapoor to attend. 1/13/89 Friday the thirteenth!! -&thu 4pm squash game with Lloyd. +thu 4pm squash game with Lloyd. mar 16 Dad's birthday -April 15, 2013 Income tax due. -&* 15 time cards due. +April 15, 2016 Income tax due. +* 15 time cards due. @end example @noindent -This format is essentially the same as the one used by the separate -@command{calendar} utility that is present on some Unix systems. This -example uses extra spaces to align the event descriptions of most of -the entries. Such formatting is purely a matter of taste. +This example uses extra spaces to align the event descriptions of most +of the entries. Such formatting is purely a matter of taste. - Although you probably will start by creating a diary manually, Emacs -provides a number of commands to let you view, add, and change diary -entries. + You can also use a format where the first line of a diary entry +consists only of the date or day name (with no following blanks or +punctuation). For example: -@menu -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. -@end menu +@example +02/11/2012 + Bill B. visits Princeton today + 2pm Cognitive Studies Committee meeting + 2:30-5:30 Liz at Lawrenceville + 4:00pm Dentist appt + 7:30pm Dinner at George's + 8:00-10:00pm concert +@end example + +@noindent +This entry will have a different appearance if you use the simple diary +display +@iftex +(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{Diary Display}). +@end ifnottex +The simple diary display omits the date line at the beginning; only the +continuation lines appear. This style of entry looks neater when you +display just a single day's entries, but can cause confusion if you ask +for more than one day's entries. @node Displaying the Diary @subsection Displaying the Diary @@ -989,9 +1042,9 @@ Mail yourself email reminders about upcoming diary entries. @kindex d @r{(Calendar mode)} @findex diary-view-entries @vindex calendar-view-diary-initially-flag - Displaying the diary entries with @kbd{d} shows in a separate window + Displaying the diary entries with @kbd{d} shows in a separate buffer the diary entries for the selected date in the calendar. The mode line -of the new window shows the date of the diary entries. Holidays are +of the new buffer shows the date of the diary entries. Holidays are shown either in the buffer or in the mode line, depending on the display method you choose @iftex @@ -1031,6 +1084,15 @@ turns off holiday marks (@pxref{Holidays}). If the variable @code{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or updating the calendar marks diary dates automatically. +@vindex diary-nonmarking-symbol + To prevent an individual diary entry from being marked in the +calendar, insert the string that @code{diary-nonmarking-symbol} +specifies (the default is @samp{&}) at the beginning of the entry, +before the date. This has no effect on display of the entry in the +diary buffer; it only affects marks on dates in the calendar. +Nonmarking entries can be useful for generic entries that would +otherwise mark many different dates. + @kindex s @r{(Calendar mode)} @findex diary-show-all-entries To see the full diary file, rather than just some of the entries, use @@ -1060,65 +1122,6 @@ diary-mail-entries}. A prefix argument specifies how many days (starting with today) to check; otherwise, the variable @code{diary-mail-days} says how many days. -@node Format of Diary File -@subsection The Diary File -@cindex diary file - -@vindex diary-file - Your @dfn{diary file} is a file that records events associated with -particular dates. The name of the diary file is specified by the -variable @code{diary-file}; @file{~/diary} is the default. The -@code{calendar} utility program supports a subset of the format allowed -by the Emacs diary facilities, so you can use that utility to view the -diary file, with reasonable results aside from the entries it cannot -understand. - - Each entry in the diary file describes one event and consists of one -or more lines. An entry always begins with a date specification at the -left margin. The rest of the entry is simply text to describe the -event. If the entry has more than one line, then the lines after the -first must begin with whitespace to indicate they continue a previous -entry. Lines that do not begin with valid dates and do not continue a -preceding entry are ignored. - - You can also use a format where the first line of a diary entry -consists only of the date or day name (with no following blanks or -punctuation). For example: - -@example -02/11/2012 - Bill B. visits Princeton today - 2pm Cognitive Studies Committee meeting - 2:30-5:30 Liz at Lawrenceville - 4:00pm Dentist appt - 7:30pm Dinner at George's - 8:00-10:00pm concert -@end example - -@noindent -This entry will have a different appearance if you use the simple diary -display -@iftex -(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Diary Display}). -@end ifnottex -The simple diary display omits the date line at the beginning; only the -continuation lines appear. This style of entry looks neater when you -display just a single day's entries, but can cause confusion if you ask -for more than one day's entries. - -@vindex diary-nonmarking-symbol - You can inhibit the marking of certain diary entries in the calendar -window; to do this, insert the string that -@code{diary-nonmarking-symbol} specifies (default @samp{&}) at the -beginning of the entry, before the date. This -has no effect on display of the entry in the diary window; it only -affects marks on dates in the calendar window. Nonmarking entries are -especially useful for generic entries that would otherwise mark many -different dates. - @node Date Formats @subsection Date Formats @@ -1270,12 +1273,12 @@ entry. The entry looks like this: @findex diary-anniversary @example -%%(diary-anniversary 10 31 1948) Arthur's birthday +%%(diary-anniversary 10 31 1988) Arthur's birthday @end example @noindent -This entry applies to October 31 in any year after 1948; @samp{10 31 -1948} specifies the date. (If you are using the European or ISO +This entry applies to October 31 in any year after 1988; @samp{10 31 +1988} specifies the date. (If you are using the European or ISO calendar style, the input order of month, day and year is different.) The reason this expression requires a beginning year is that advanced diary functions can use it to calculate the number of elapsed years. @@ -1347,7 +1350,7 @@ mean ``second'', @minus{}2 would mean ``second-to-last'', and so on). The month can be a single month or a list of months. Thus you could change the 11 above to @samp{'(1 2 3)} and have the entry apply to the last Thursday of January, February, and March. If the month is @code{t}, the -entry applies to all months of the year.@refill +entry applies to all months of the year. Each of the standard sexp diary entries takes an optional parameter specifying the name of a face or a single-character string to use when @@ -1460,11 +1463,11 @@ variable @code{diary-outlook-formats}. Other mail clients can set @c FIXME the name of the RFC is hardly very relevant. @cindex iCalendar support The icalendar package allows you to transfer data between your Emacs -diary file and iCalendar files, which are defined in ``RFC +diary file and iCalendar files, which are defined in @cite{RFC 2445---Internet Calendaring and Scheduling Core Object Specification -(iCalendar)'' (as well as the earlier vCalendar format). +(iCalendar)} (as well as the earlier vCalendar format). -@c Importing works for ``ordinary'' (i.e., non-recurring) events, but +@c Importing works for ordinary (i.e., non-recurring) events, but @c (at present) may not work correctly (if at all) for recurring events. @c Exporting of diary files into iCalendar files should work correctly @c for most diary entries. This feature is a work in progress, so the @@ -1598,11 +1601,11 @@ timeclock-change}. Once you've collected data from a number of time intervals, you can use @kbd{M-x timeclock-workday-remaining} to see how much time is left to work today (assuming a typical average of 8 hours a day), and @kbd{M-x -timeclock-when-to-leave} which will calculate when you're ``done''. +timeclock-when-to-leave} which will calculate when you're done. @vindex timeclock-modeline-display @findex timeclock-modeline-display - If you want Emacs to display the amount of time ``left'' of your + If you want Emacs to display the amount of time left of your workday in the mode line, either customize the @code{timeclock-modeline-display} variable and set its value to @code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. @@ -1615,11 +1618,11 @@ you. You can, however, customize the value of the variable then, only an explicit @kbd{M-x timeclock-out} or @kbd{M-x timeclock-change} will tell Emacs that the current interval is over. -@cindex @file{.timelog} file +@cindex @file{timelog} file @vindex timeclock-file @findex timeclock-reread-log The timeclock functions work by accumulating the data in a file -called @file{.timelog} in your home directory. You can specify a +called @file{~/.emacs.d/timelog}. You can specify a different name for this file by customizing the variable @code{timeclock-file}. If you edit the timeclock file manually, or if you change the value of any of timeclock's customizable variables, you diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 3dc64fdd127..fcaf87f1709 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Emacs Invocation @@ -10,6 +10,7 @@ @cindex switches (command line) @cindex startup (command line arguments) @cindex invocation (command line arguments) +@c FIXME: Document '--smid'? --xfq Emacs supports command line arguments to request various actions when invoking Emacs. These are for compatibility with other editors @@ -135,7 +136,14 @@ visited. @opindex -L @itemx --directory=@var{dir} @opindex --directory -Add directory @var{dir} to the variable @code{load-path}. +Prepend directory @var{dir} to the variable @code{load-path}. +If you specify multiple @samp{-L} options, Emacs preserves the +relative order; i.e., using @samp{-L /foo -L /bar} results in +a @code{load-path} of the form @code{("/foo" "/bar" @dots{})}. +If @var{dir} begins with @samp{:}, Emacs removes the @samp{:} and +appends (rather than prepends) the remainder to @code{load-path}. +(On MS Windows, use @samp{;} instead of @samp{:}; i.e., use +the value of @code{path-separator}.) @item -f @var{function} @opindex -f @@ -157,9 +165,12 @@ Evaluate Lisp expression @var{expression}. @item --insert=@var{file} @opindex --insert @cindex insert file contents, command-line argument -Insert the contents of @var{file} into the @file{*scratch*} buffer -(@pxref{Lisp Interaction}). This is like what @kbd{M-x insert-file} -does (@pxref{Misc File Ops}). +Insert the contents of @var{file} into the buffer that is current when +this command-line argument is processed. Usually, this is the +@file{*scratch*} buffer (@pxref{Lisp Interaction}), but if arguments +earlier on the command line visit files or switch buffers, that might +be a different buffer. The effect of this command-line argument is +like what @kbd{M-x insert-file} does (@pxref{Misc File Ops}). @item --kill @opindex --kill @@ -431,47 +442,66 @@ special meanings in Emacs. Most of these variables are also used by some other programs. Emacs does not require any of these environment variables to be set, but it uses their values if they are set. +@c This used to be @vtable, but that enters the variables alone into +@c the Variable Index, which in some cases, like HOME, might be +@c confused with keys by that name, and other cases, like NAME, +@c might be confused with general-purpose phrases. @table @env @item CDPATH +@vindex CDPATH, environment variable Used by the @code{cd} command to search for the directory you specify, when you specify a relative directory name. @item DBUS_SESSION_BUS_ADDRESS +@vindex DBUS_SESSION_BUS_ADDRESS, environment variable Used by D-Bus when Emacs is compiled with it. Usually, there is no need to change it. Setting it to a dummy address, like @samp{unix:path=/dev/null}, suppresses connections to the D-Bus session bus as well as autolaunching the D-Bus session bus if not running yet. @item EMACSDATA +@vindex EMACSDATA, environment variable Directory for the architecture-independent files that come with Emacs. This is used to initialize the variable @code{data-directory}. @item EMACSDOC +#vindex EMACSDOC, environment variable Directory for the documentation string file, which is used to initialize the Lisp variable @code{doc-directory}. @item EMACSLOADPATH -A colon-separated list of directories@footnote{ Here and below, +#vindex EMACSLOADPATH, environment variable +A colon-separated list of directories@footnote{Here and below, whenever we say ``colon-separated list of directories'', it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, the directories are separated by semi-colons instead, since DOS/Windows -file names might include a colon after a drive letter.} to search for -Emacs Lisp files. If set, it overrides the usual initial value of the -@code{load-path} variable (@pxref{Lisp Libraries}). +file names might include a colon after a drive letter.} to search for +Emacs Lisp files. If set, it modifies the usual initial value of the +@code{load-path} variable (@pxref{Lisp Libraries}). An empty element +stands for the default value of @code{load-path}; e.g., using +@samp{EMACSLOADPATH="/tmp:"} adds @file{/tmp} to the front of +the default @code{load-path}. To specify an empty element in the +middle of the list, use 2 colons in a row, as in +@samp{EMACSLOADPATH="/tmp::/foo"}. @item EMACSPATH +@vindex EMACSPATH, environment variable A colon-separated list of directories to search for executable files. If set, Emacs uses this in addition to @env{PATH} (see below) when initializing the variable @code{exec-path} (@pxref{Shell}). @item EMAIL +@vindex EMAIL, environment variable @vindex user-mail-address@r{, initialization} Your email address; used to initialize the Lisp variable @code{user-mail-address}, which the Emacs mail interface puts into the @samp{From} header of outgoing messages (@pxref{Mail Headers}). @item ESHELL +@vindex ESHELL, environment variable Used for shell-mode to override the @env{SHELL} environment variable (@pxref{Interactive Shell}). @item HISTFILE +@vindex HISTFILE, environment variable The name of the file that shell commands are saved in between logins. This variable defaults to @file{~/.bash_history} if you use Bash, to @file{~/.sh_history} if you use ksh, and to @file{~/.history} otherwise. @item HOME +@vindex HOME, environment variable The location of your files in the directory tree; used for expansion of file names starting with a tilde (@file{~}). On MS-DOS, it defaults to the directory from which Emacs was started, with @@ -483,20 +513,33 @@ where @var{username} is your user name), though for backwards compatibility @file{C:/} will be used instead if a @file{.emacs} file is found there. @item HOSTNAME +@vindex HOSTNAME, environment variable The name of the machine that Emacs is running on. +@c complete.el is obsolete since 24.1. +@ignore @item INCPATH A colon-separated list of directories. Used by the @code{complete} package to search for files. +@end ignore @item INFOPATH +@vindex INFOPATH, environment variable A colon-separated list of directories in which to search for Info files. @item LC_ALL +@vindex LC_ALL, environment variable @itemx LC_COLLATE +@vindex LC_COLLATE, environment variable @itemx LC_CTYPE +@vindex LC_CTYPE, environment variable @itemx LC_MESSAGES +@vindex LC_MESSAGES, environment variable @itemx LC_MONETARY +@vindex LC_MONETARY, environment variable @itemx LC_NUMERIC +@vindex LC_NUMERIC, environment variable @itemx LC_TIME +@vindex LC_TIME, environment variable @itemx LANG +@vindex LANG, environment variable The user's preferred locale. The locale has six categories, specified by the environment variables @env{LC_COLLATE} for sorting, @env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system @@ -518,70 +561,89 @@ matched against entries in @code{locale-language-names}, @code{locale-preferred-coding-systems}, to select a default language environment and coding system. @xref{Language Environments}. @item LOGNAME +@vindex LOGNAME, environment variable The user's login name. See also @env{USER}. @item MAIL +@vindex MAIL, environment variable The name of your system mail inbox. @ifnottex @item MH +@vindex MH, environment variable Name of setup file for the mh system. @xref{Top,,MH-E,mh-e, The Emacs Interface to MH}. @end ifnottex @item NAME +@vindex NAME, environment variable Your real-world name. This is used to initialize the variable @code{user-full-name} (@pxref{Mail Headers}). @item NNTPSERVER +@vindex NNTPSERVER, environment variable The name of the news server. Used by the mh and Gnus packages. @item ORGANIZATION +@vindex ORGANIZATION, environment variable The name of the organization to which you belong. Used for setting the -`Organization:' header in your posts from the Gnus package. +@samp{Organization:} header in your posts from the Gnus package. @item PATH +@vindex PATH, environment variable A colon-separated list of directories containing executable files. This is used to initialize the variable @code{exec-path} (@pxref{Shell}). @item PWD +@vindex PWD, environment variable If set, this should be the default directory when Emacs was started. @item REPLYTO +@vindex REPLYTO, environment variable If set, this specifies an initial value for the variable @code{mail-default-reply-to} (@pxref{Mail Headers}). @item SAVEDIR +@vindex SAVEDIR, environment variable The name of a directory in which news articles are saved by default. Used by the Gnus package. @item SHELL +@vindex SHELL, environment variable The name of an interpreter used to parse and execute programs run from inside Emacs. @item SMTPSERVER +@vindex SMTPSERVER, environment variable The name of the outgoing mail server. This is used to initialize the variable @code{smtpmail-smtp-server} (@pxref{Mail Sending}). @cindex background mode, on @command{xterm} @item TERM +@vindex TERM, environment variable The type of the terminal that Emacs is using. This variable must be set unless Emacs is run in batch mode. On MS-DOS, it defaults to @samp{internal}, which specifies a built-in terminal emulation that handles the machine's own display. @item TERMCAP +@vindex TERMCAP, environment variable The name of the termcap library file describing how to program the terminal specified by @env{TERM}. This defaults to @file{/etc/termcap}. @item TMPDIR +@vindex TMPDIR, environment variable @itemx TMP +@vindex TMP, environment variable @itemx TEMP +@vindex TEMP, environment variable These environment variables are used to initialize the variable @code{temporary-file-directory}, which specifies a directory in which to put temporary files (@pxref{Backup}). Emacs tries to use @env{TMPDIR} first. If that is unset, Emacs normally falls back on @file{/tmp}, but on MS-Windows and MS-DOS it instead falls back on @env{TMP}, then @env{TEMP}, and finally @file{c:/temp}. - @item TZ +@vindex TZ, environment variable This specifies the current time zone and possibly also daylight saving time information. On MS-DOS, if @env{TZ} is not set in the environment when Emacs starts, Emacs defines a default value as appropriate for the country code returned by DOS@. On MS-Windows, Emacs does not use @env{TZ} at all. @item USER +@vindex USER, environment variable The user's login name. See also @env{LOGNAME}. On MS-DOS, this defaults to @samp{root}. @item VERSION_CONTROL +@vindex VERSION_CONTROL, environment variable Used to initialize the @code{version-control} variable (@pxref{Backup Names}). @end table @@ -591,7 +653,7 @@ Names}). These variables are used only on particular configurations: -@table @env +@vtable @env @item COMSPEC On MS-DOS and MS-Windows, the name of the command interpreter to use when invoking batch files and commands internal to the shell. On MS-DOS @@ -643,7 +705,7 @@ rather than hard-coding an absolute path. This allows multiple versions of Emacs to share the same environment variable settings, and it allows you to move the Emacs installation directory, without changing any environment or registry settings. -@end table +@end vtable @node MS-Windows Registry @appendixsubsec The MS-Windows System Registry @@ -746,7 +808,7 @@ Use @var{font} as the default font. @end table When passing a font name to Emacs on the command line, you may need to -``quote'' it, by enclosing it in quotation marks, if it contains +quote it, by enclosing it in quotation marks, if it contains characters that the shell treats specially (e.g., spaces). For example: @@ -885,30 +947,33 @@ the initial frame. @itemx --fullscreen @opindex --fullscreen @cindex fullscreen, command-line argument -Specify that width and height shall be the size of the screen. Normally -no window manager decorations are shown. +Specify that width and height should be that of the screen. Normally +no window manager decorations are shown. (After starting Emacs, +you can toggle this state using @key{F11}, @code{toggle-frame-fullscreen}.) @item -mm @opindex -mm @itemx --maximized @opindex --maximized @cindex maximized, command-line argument -Specify that the Emacs frame shall be maximized. This normally +Specify that the Emacs frame should be maximized. This normally means that the frame has window manager decorations. +(After starting Emacs, you can toggle this state using @kbd{M-F10}, +@code{toggle-frame-maximized}.) @item -fh @opindex -fh @itemx --fullheight @opindex --fullheight @cindex fullheight, command-line argument -Specify that the height shall be the height of the screen. +Specify that the height should be the height of the screen. @item -fw @opindex -fw @itemx --fullwidth @opindex --fullwidth @cindex fullwidth, command-line argument -Specify that the width shall be the width of the screen. +Specify that the width should be the width of the screen. @end table @noindent @@ -968,10 +1033,10 @@ size with no tool bar, use an X resource to specify ``no tool bar'' (@pxref{Table of Resources}); then Emacs will already know there's no tool bar when it processes the specified geometry. - When using one of @samp{--fullscreen}, @samp{--maximized}, @samp{--fullwidth} -or @samp{--fullheight} there may be some space around the frame -anyway. That is because Emacs rounds the sizes so they are an -even number of character heights and widths. + When using one of @samp{--fullscreen}, @samp{--maximized}, +@samp{--fullwidth} or @samp{--fullheight}, some window managers require +you to set the variable @code{frame-resize-pixelwise} to a non-@code{nil} +value to make a frame appear truly maximized or full-screen. Some window managers have options that can make them ignore both program-specified and user-specified positions. If these are set, @@ -1050,7 +1115,7 @@ for the initial Emacs frame. @opindex --iconic @itemx --iconic @cindex start iconified, command-line argument -Start Emacs in an iconified (``minimized'') state. +Start Emacs in an iconified state. @item -nbi @opindex -nbi @@ -1060,9 +1125,9 @@ Start Emacs in an iconified (``minimized'') state. Disable the use of the Emacs icon. @end table - Most window managers allow you to ``iconify'' (or ``minimize'') an + Most window managers allow you to iconify (or ``minimize'') an Emacs frame, hiding it from sight. Some window managers replace -iconified windows with tiny ``icons'', while others remove them +iconified windows with tiny icons, while others remove them entirely from sight. The @samp{-iconic} option tells Emacs to begin running in an iconified state, rather than showing a frame right away. The text frame doesn't appear until you deiconify (or ``un-minimize'') @@ -1087,8 +1152,8 @@ rectangle containing the frame's title. @c Enable horizontal scroll bars. Since horizontal scroll bars @c are not yet implemented, this actually does nothing. -@item --parent-id @var{ID} -Open Emacs as a client X window via the XEmbed protocol, with @var{ID} +@item --parent-id @var{id} +Open Emacs as a client X window via the XEmbed protocol, with @var{id} as the parent X window id. Currently, this option is mainly useful for developers. diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi index 1c0746a9dd0..98e12531253 100644 --- a/doc/emacs/commands.texi +++ b/doc/emacs/commands.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @@ -35,42 +35,42 @@ Therefore, this manual mainly documents how to edit with the keyboard. @samp{3}, @samp{=}, and the space character (denoted as @key{SPC}), are entered by typing the corresponding key. @dfn{Control characters}, such as @key{RET}, @key{TAB}, @key{DEL}, @key{ESC}, -@key{F1}, @key{Home}, and @key{left}, are also entered this way, as +@key{F1}, @key{Home}, and @key{LEFT}, are also entered this way, as are certain characters found on non-English keyboards (@pxref{International}). @cindex modifier keys @cindex Control @cindex C- -@cindex Meta +@cindex META @cindex M- Emacs also recognizes control characters that are entered using @dfn{modifier keys}. Two commonly-used modifier keys are -@key{Control} (usually labeled @key{Ctrl}), and @key{Meta} (usually -labeled @key{Alt})@footnote{We refer to @key{Alt} as @key{Meta} for +@key{Control} (usually labeled @key{Ctrl}), and @key{META} (usually +labeled @key{Alt})@footnote{We refer to @key{Alt} as @key{META} for historical reasons.}. For example, @kbd{Control-a} is entered by holding down the @key{Ctrl} key while pressing @kbd{a}; we will refer -to this as @kbd{C-a} for short. Similarly @kbd{Meta-a}, or @kbd{M-a} +to this as @kbd{C-a} for short. Similarly @kbd{@key{META}-a}, or @kbd{M-a} for short, is entered by holding down the @key{Alt} key and pressing @kbd{a}. Modifier keys can also be applied to non-alphanumerical -characters, e.g., @kbd{C-@key{F1}} or @kbd{M-@key{left}}. +characters, e.g., @kbd{C-@key{F1}} or @kbd{M-@key{LEFT}}. -@cindex @key{ESC} replacing @key{Meta} key +@cindex @key{ESC} replacing @key{META} key You can also type Meta characters using two-character sequences starting with @key{ESC}. Thus, you can enter @kbd{M-a} by typing @kbd{@key{ESC} a}. You can enter @kbd{C-M-a} by typing @kbd{@key{ESC} -C-a}. Unlike @key{Meta}, @key{ESC} is entered as a separate +C-a}. Unlike @key{META}, @key{ESC} is entered as a separate character. You don't hold down @key{ESC} while typing the next character; instead, press @key{ESC} and release it, then enter the next character. This feature is useful on certain text terminals -where the @key{Meta} key does not function reliably. +where the @key{META} key does not function reliably. @cindex keys stolen by window manager @cindex window manager, keys stolen by On graphical displays, the window manager might block some keyboard inputs, including @kbd{M-@key{TAB}}, @kbd{M-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}. If you have this problem, you can either customize -your window manager to not block those keys, or ``rebind'' the +your window manager to not block those keys, or rebind the affected Emacs commands (@pxref{Customization}). @cindex input event diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index f3e07fd8ba0..76c7261767a 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1,5 +1,6 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Customization @@ -28,7 +29,7 @@ Reference Manual}. to decide what to do; by setting variables, you can control their functioning. * Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine keys". + By changing them, you can redefine keys. * Init File:: How to write common customizations in the initialization file. @end menu @@ -82,14 +83,12 @@ top-level @code{Emacs} group. It looks like this, in part: @c @page @smallexample @group -To apply changes, use the Save or Set buttons. -For details, see [Saving Customizations] in the [Emacs manual]. +For help, see [Easy Customization] in the [Emacs manual]. ________________________________________ [ Search ] Operate on all settings in this buffer: - [ Set for current session ] [ Save for future sessions ] - [ Undo edits ] [ Reset to saved ] [ Erase customizations ] [ Exit ] + [ Revert... ] [ Apply ] [ Apply and Save ] Emacs group: Customization of the One True Editor. @@ -97,7 +96,6 @@ Emacs group: Customization of the One True Editor. See also [Manual]. [Editing] : Basic text editing facilities. - [Convenience] : Convenience features for faster editing. @var{more second-level groups} @@ -405,6 +403,16 @@ customizations in your initialization file. This is because saving customizations from such a session would wipe out all the other customizations you might have on your initialization file. + Please note that any customizations you have not chosen to save for +future sessions will be lost when you terminate Emacs. If you'd like +to be prompted about unsaved customizations at termination time, add +the following to your initialization file: + +@example +(add-hook 'kill-emacs-query-functions + 'custom-prompt-customize-unsaved-options) +@end example + @node Face Customization @subsection Customizing Faces @cindex customizing faces @@ -573,7 +581,7 @@ directory specified by the variable @code{custom-theme-directory} which are distributed with Emacs, which customize Emacs's faces to fit various color schemes. (Note, however, that Custom themes need not be restricted to this purpose; they can be used to customize variables -too). +too.) @vindex custom-theme-load-path If you want Emacs to look for Custom themes in some other directory, @@ -721,7 +729,7 @@ maximum length of the kill ring (@pxref{Earlier Kills}); if you give @code{kill-ring-max} a string value, commands such as @kbd{C-y} (@code{yank}) will signal an error. On the other hand, some variables don't care about type; for instance, if a variable has one effect for -@code{nil} values and another effect for ``non-@code{nil}'' values, +@code{nil} values and another effect for non-@code{nil} values, then any value that is not the symbol @code{nil} induces the second effect, regardless of its type (by convention, we usually use the value @code{t}---a symbol which stands for ``true''---to specify a @@ -766,22 +774,22 @@ C-h v fill-column @key{RET} displays something like this: @example -fill-column is a variable defined in `C source code'. -fill-column's value is 70 +fill-column is a variable defined in ‘C source code’. +Its value is 70 -Automatically becomes buffer-local when set. -This variable is safe as a file local variable if its value -satisfies the predicate `integerp'. + Automatically becomes buffer-local when set. + This variable is safe as a file local variable if its value + satisfies the predicate ‘integerp’. Documentation: Column beyond which automatic line-wrapping should happen. -Interactively, you can set the local value with C-x f. +Interactively, you can set the buffer local value using C-x f. You can customize this variable. @end example @noindent -The line that says ``You can customize the variable'' indicates that +The line that says @samp{You can customize the variable} indicates that this variable is a user option. @kbd{C-h v} is not restricted to user options; it allows non-customizable variables too. @@ -1149,7 +1157,7 @@ the list. Here is an example: # End: @end example - Some ``variable names'' have special meanings in a local variables + Some names have special meanings in a local variables list: @itemize @@ -1754,7 +1762,7 @@ and @kbd{C-c p} in Texinfo mode: alphabetical characters are case-insensitive. In other words, @kbd{C-A} does the same thing as @kbd{C-a}, and @kbd{M-A} does the same thing as @kbd{M-a}. This concerns only alphabetical characters, -and does not apply to ``shifted'' versions of other keys; for +and does not apply to shifted versions of other keys; for instance, @kbd{C-@@} is not the same as @kbd{C-2}. A @key{Control}-modified alphabetical character is always considered @@ -1766,20 +1774,20 @@ historical. characters case-sensitive when you customize Emacs. For instance, you could make @kbd{M-a} and @kbd{M-A} run different commands. - Although only the @key{Control} and @key{Meta} modifier keys are + Although only the @key{Control} and @key{META} modifier keys are commonly used, Emacs supports three other modifier keys. These are called @key{Super}, @key{Hyper} and @key{Alt}. Few terminals provide ways to use these modifiers; the key labeled @key{Alt} on most -keyboards usually issues the @key{Meta} modifier, not @key{Alt}. The +keyboards usually issues the @key{META} modifier, not @key{Alt}. The standard key bindings in Emacs do not include any characters with these modifiers. However, you can customize Emacs to assign meanings to them. The modifier bits are labeled as @samp{s-}, @samp{H-} and @samp{A-} respectively. Even if your keyboard lacks these additional modifier keys, you can -enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to -the next character, @kbd{C-x @@ s} adds the ``super'' flag, and -@kbd{C-x @@ a} adds the ``alt'' flag. For instance, @kbd{C-x @@ h +enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the Hyper flag to +the next character, @kbd{C-x @@ s} adds the Super flag, and +@kbd{C-x @@ a} adds the Alt flag. For instance, @kbd{C-x @@ h C-a} is a way to enter @kbd{Hyper-Control-a}. (Unfortunately, there is no way to add two modifiers by using @kbd{C-x @@} twice for the same character, because the first one goes to work on the @kbd{C-x}.) @@ -1795,10 +1803,10 @@ the corresponding Lisp symbol. Here are the conventional Lisp names for common function keys: @table @asis -@item @code{left}, @code{up}, @code{right}, @code{down} +@item @code{LEFT}, @code{UP}, @code{RIGHT}, @code{DOWN} Cursor arrow keys. -@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} +@item @code{Begin}, @code{End}, @code{Home}, @code{next}, @code{prior} Other cursor repositioning keys. @item @code{select}, @code{print}, @code{execute}, @code{backtab} @@ -1829,7 +1837,7 @@ key. @xref{Init Rebinding}, for examples of binding function keys. @cindex keypad - Many keyboards have a ``numeric keypad'' on the right hand side. + Many keyboards have a numeric keypad on the right hand side. The numeric keys in the keypad double up as cursor motion keys, toggled by a key labeled @samp{Num Lock}. By default, Emacs translates these keys to the corresponding keys in the main keyboard. @@ -1859,13 +1867,13 @@ prefix arguments. started out as names for certain @acronym{ASCII} control characters, used so often that they have special keys of their own. For instance, @key{TAB} was another name for @kbd{C-i}. Later, users found it -convenient to distinguish in Emacs between these keys and the ``same'' -control characters typed with the @key{CTRL} key. Therefore, on most +convenient to distinguish in Emacs between these keys and the corresponding +control characters typed with the @key{Ctrl} key. Therefore, on most modern terminals, they are no longer the same: @key{TAB} is different from @kbd{C-i}. Emacs can distinguish these two kinds of input if the keyboard does. -It treats the ``special'' keys as function keys named @code{tab}, +It treats the special keys as function keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and @code{delete}. These function keys translate automatically into the corresponding @acronym{ASCII} characters @emph{if} they have no @@ -1875,7 +1883,7 @@ need to pay attention to the distinction unless they care to. If you do not want to distinguish between (for example) @key{TAB} and @kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} (octal code 011). If you do want to distinguish, make one binding for -this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. +this @acronym{ASCII} character, and another for the function key @code{tab}. With an ordinary @acronym{ASCII} terminal, there is no way to distinguish between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), @@ -1930,7 +1938,7 @@ single click definition has run when the first click was received. This constrains what you can do with double clicks, but user interface designers say that this constraint ought to be followed in any case. A double click should do something similar to the single click, only -``more so''. The command for the double-click event should perform the +more so. The command for the double-click event should perform the extra work for the double click. If a double-click event has no binding, it changes to the @@ -1977,8 +1985,8 @@ or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. A frame includes areas that don't show text from the buffer, such as the mode line and the scroll bar. You can tell whether a mouse button -comes from a special area of the screen by means of dummy ``prefix -keys''. For example, if you click the mouse in the mode line, you get +comes from a special area of the screen by means of dummy prefix +keys. For example, if you click the mouse in the mode line, you get the prefix key @code{mode-line} before the ordinary mouse-button symbol. Thus, here is how to define the command for clicking the first button in a mode line to run @code{scroll-up-command}: @@ -2187,8 +2195,8 @@ sequences are mandatory. @samp{\C-} can be used as a prefix for a control character, as in @samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for -a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for -@kbd{Control-Meta-A}.@refill +a Meta character, as in @samp{\M-a} for @kbd{@key{META}-A} or +@samp{\M-\C-a} for @kbd{@key{Ctrl}-@key{META}-A}. @xref{Init Non-ASCII}, for information about including non-@acronym{ASCII} in your init file. @@ -2206,10 +2214,10 @@ require one and some contexts require the other. keys which send non-@acronym{ASCII} characters. @item True: -@code{t} stands for `true'. +@code{t} stands for ``true''. @item False: -@code{nil} stands for `false'. +@code{nil} stands for ``false''. @item Other Lisp objects: @cindex Lisp object syntax @@ -2240,8 +2248,8 @@ line. (setq c-tab-always-indent nil) @end example -Here we have a variable whose value is normally @code{t} for `true' -and the alternative is @code{nil} for `false'. +Here we have a variable whose value is normally @code{t} for ``true'' +and the alternative is @code{nil} for ``false''. @item Make searches case sensitive by default (in all buffers that do not @@ -2433,9 +2441,7 @@ You can also simply disregard the errors that occur if the function is not defined. @example -(condition case () - (set-face-background 'region "grey75") - (error nil)) +(ignore-errors (set-face-background 'region "grey75")) @end example A @code{setq} on a variable which does not exist is generally @@ -2445,13 +2451,17 @@ harmless, so those do not need a conditional. @node Terminal Init @subsection Terminal-specific Initialization +@vindex term-file-aliases Each terminal type can have a Lisp library to be loaded into Emacs when it is run on that type of terminal. For a terminal type named -@var{termtype}, the library is called @file{term/@var{termtype}} and it is +@var{termtype}, the library is called @file{term/@var{termtype}}. +(If there is an entry of the form @code{(@var{termtype} . @var{alias})} +in the @code{term-file-aliases} association list, Emacs uses +@var{alias} in place of @var{termtype}.) The library is found by searching the directories @code{load-path} as usual and trying the suffixes @samp{.elc} and @samp{.el}. Normally it appears in the subdirectory @file{term} of the directory where most Emacs libraries are -kept.@refill +kept. The usual purpose of the terminal-specific library is to map the escape sequences used by the terminal's function keys onto more @@ -2466,7 +2476,7 @@ function keys that Termcap does not specify. before the first hyphen is significant in choosing the library name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use the library @file{term/aaa}. The code in the library can use -@code{(getenv "TERM")} to find the full terminal type name.@refill +@code{(getenv "TERM")} to find the full terminal type name. @vindex term-file-prefix The library's name is constructed by concatenating the value of the @@ -2474,8 +2484,8 @@ variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} file can prevent the loading of the terminal-specific library by setting @code{term-file-prefix} to @code{nil}. -@vindex term-setup-hook - Emacs runs the hook @code{term-setup-hook} at the end of +@vindex tty-setup-hook + Emacs runs the hook @code{tty-setup-hook} at the end of initialization, after both your @file{.emacs} file and any terminal-specific library have been read in. Add hook functions to this hook if you wish to override part of any of the terminal-specific diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi index e0fec06ab1a..2b9ddae2654 100644 --- a/doc/emacs/dired-xtra.texi +++ b/doc/emacs/dired-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index f4ca6c30a5a..e7e49445b54 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Dired @@ -14,7 +14,7 @@ optionally some of its subdirectories as well. You can use the normal Emacs commands to move around in this buffer, and special Dired commands to operate on the listed files. - The Dired buffer is ``read-only'', and inserting text in it is not + The Dired buffer is read-only, and inserting text in it is not allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are redefined for special Dired commands. Some Dired commands @dfn{mark} or @dfn{flag} the @dfn{current file} (that is, the file on the current @@ -281,9 +281,9 @@ say they are backup files---that is, files whose names end in the backup files for deletion: all but the oldest few and newest few backups of any one file. Normally, the number of newest versions kept for each file is given by the variable @code{dired-kept-versions} -(@strong{not} @code{kept-new-versions}; that applies only when -saving). The number of oldest versions to keep is given by the -variable @code{kept-old-versions}. +(@emph{not} @code{kept-new-versions}; that applies only when saving). +The number of oldest versions to keep is given by the variable +@code{kept-old-versions}. Period with a positive numeric argument, as in @kbd{C-u 3 .}, specifies the number of newest versions to keep, overriding @@ -376,7 +376,7 @@ for @file{..} and typing @kbd{f} there. @end table @node Marks vs Flags -@section Dired Marks vs. Flags +@section Dired Marks vs.@: Flags @cindex marking many files (in Dired) Instead of flagging a file with @samp{D}, you can @dfn{mark} the @@ -522,7 +522,7 @@ flags on all the files that have no marks, while unflagging all those that already have @samp{D} flags: @example -* c D t * c SPC D * c t SPC +* c D t * c @key{SPC} D * c t @key{SPC} @end example This assumes that no files were already marked with @samp{t}. @@ -722,7 +722,17 @@ suitable guess made using the variables @code{lpr-command} and @cindex compressing files (in Dired) @item Z Compress the specified files (@code{dired-do-compress}). If the file -appears to be a compressed file already, uncompress it instead. +appears to be a compressed file already, uncompress it instead. Each +marked file is compressed into its own archive. + +@findex dired-do-compress-to +@kindex c @r{(Dired)} +@cindex compressing files (in Dired) +@item c +Compress the specified files (@code{dired-do-compress-to}) into a +single archive anywhere on the file system. The compression algorithm +is determined by the extension of the archive, see +@code{dired-compress-files-alist}. @findex epa-dired-do-decrypt @kindex :d @r{(Dired)} @@ -924,7 +934,7 @@ from the name of the old file. The four regular-expression substitution commands effectively perform a search-and-replace on the selected file names. They read two arguments: a regular expression @var{from}, and a substitution -pattern @var{to}; they match each ``old'' file name against +pattern @var{to}; they match each old file name against @var{from}, and then replace the matching part with @var{to}. You can use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or part of what the pattern matched in the old file name, as in @@ -1108,7 +1118,8 @@ can use hiding to temporarily exclude subdirectories from operations without having to remove the Dired marks on files in those subdirectories. -@xref{Dired Updating}, for how to insert or delete a subdirectory listing. +@xref{Subdirectories in Dired}, for how to insert a subdirectory +listing, and @pxref{Dired Updating} for how delete it. @node Dired Updating @section Updating the Dired Buffer @@ -1261,7 +1272,7 @@ and erases all flags and marks. @findex wdired-change-to-wdired-mode Wdired is a special mode that allows you to perform file operations by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands -for ``writable''.) To enter Wdired mode, type @kbd{C-x C-q} +for ``writable''). To enter Wdired mode, type @kbd{C-x C-q} (@code{dired-toggle-read-only}) while in a Dired buffer. Alternatively, use the @samp{Immediate / Edit File Names} menu item. @@ -1306,24 +1317,24 @@ buffer containing image-dired, corresponding to the marked files. You can also enter Image-Dired directly by typing @kbd{M-x image-dired}. This prompts for a directory; specify one that has image files. This creates thumbnails for all the images in that -directory, and displays them all in the ``thumbnail buffer''. This +directory, and displays them all in the thumbnail buffer. This takes a long time if the directory contains many image files, and it asks for confirmation if the number of image files exceeds @code{image-dired-show-all-from-dir-max-files}. - With point in the thumbnail buffer, you can type @kbd{RET} + With point in the thumbnail buffer, you can type @key{RET} (@code{image-dired-display-thumbnail-original-image}) to display a sized version of it in another window. This sizes the image to fit the window. Use the arrow keys to move around in the buffer. For -easy browsing, use @kbd{SPC} +easy browsing, use @key{SPC} (@code{image-dired-display-next-thumbnail-original}) to advance and -display the next image. Typing @kbd{DEL} +display the next image. Typing @key{DEL} (@code{image-dired-display-previous-thumbnail-original}) backs up to the previous thumbnail and displays that instead. @vindex image-dired-external-viewer To view and the image in its original size, either provide a prefix -argument (@kbd{C-u}) before pressing @kbd{RET}, or type +argument (@kbd{C-u}) before pressing @key{RET}, or type @kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to display the image in an external viewer. You must first configure @code{image-dired-external-viewer}. @@ -1347,9 +1358,9 @@ with a certain tag, you can use @kbd{C-t d} to view them. You can also tag a file directly from the thumbnail buffer by typing @kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also -a special ``tag'' called ``comment'' for each file (it is not a tag in +a special tag called ``comment'' for each file (it is not a tag in the exact same sense as the other tags, it is handled slightly -different). That is used to enter a comment or description about the +differently). That is used to enter a comment or description about the image. You comment a file from the thumbnail buffer by typing @kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add a comment from Dired (@code{image-dired-dired-comment-files}). @@ -1374,7 +1385,7 @@ the directory already exists. @findex dired-do-isearch @findex dired-do-isearch-regexp The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a -``multi-file'' incremental search on the marked files. If a search +multi-file incremental search on the marked files. If a search fails at the end of a file, typing @kbd{C-s} advances to the next marked file and repeats the search; at the end of the last marked file, the search wraps around to the first marked file. The command @@ -1382,7 +1393,7 @@ file, the search wraps around to the first marked file. The command a regular expression search. @xref{Repeat Isearch}, for information about search repetition. -@cindex Adding to the kill ring in Dired. +@cindex adding to the kill ring in Dired @kindex w @r{(Dired)} @findex dired-copy-filename-as-kill The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the @@ -1403,6 +1414,19 @@ names into arguments for other Emacs commands. It also displays what it added to the kill ring, so you can use it to display the list of currently marked files in the echo area. +@kindex ( @r{(Dired)} +@findex dired-hide-details-mode +@vindex dired-hide-details-hide-symlink-targets +@vindex dired-hide-details-hide-information-lines +@cindex hiding details in Dired + The command @kbd{(} (@code{dired-hide-details-mode}) toggles whether +details, such as ownership or file permissions, are visible in the +current Dired buffer. By default, it also hides the targets of +symbolic links, and all lines other than the header line and +file/directory listings. To change this, customize the options +@code{dired-hide-details-hide-symlink-targets} and +@code{dired-hide-details-hide-information-lines}, respectively. + @cindex Dired and version control If the directory you are visiting is under version control (@pxref{Version Control}), then the normal VC diff and log commands @@ -1411,21 +1435,21 @@ will operate on the selected files. @findex dired-compare-directories The command @kbd{M-x dired-compare-directories} is used to compare the current Dired buffer with another directory. It marks all the files -that are ``different'' between the two directories. It puts these marks +that differ between the two directories. It puts these marks in all Dired buffers where these files are listed, which of course includes the current buffer. The default comparison method (used if you type @key{RET} at the -prompt) is to compare just the file names---each file name that does -not appear in the other directory is ``different''. You can specify +prompt) is to compare just the file names---file names differ if +they do not appear in the other directory. You can specify more stringent comparisons by entering a Lisp expression, which can refer to the variables @code{size1} and @code{size2}, the respective file sizes; @code{mtime1} and @code{mtime2}, the last modification times in seconds, as floating point numbers; and @code{fa1} and @code{fa2}, the respective file attribute lists (as returned by the function @code{file-attributes}). This expression is evaluated for -each pair of like-named files, and if the expression's value is -non-@code{nil}, those files are considered ``different''. +each pair of like-named files, and files differ if the expression's +value is non-@code{nil}. For instance, the sequence @code{M-x dired-compare-directories @key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this @@ -1434,7 +1458,7 @@ directory than in this one. It also marks files with no counterpart, in both directories, as always. @cindex drag and drop, Dired - On the X Window System, Emacs supports the ``drag and drop'' + On the X Window System, Emacs supports the drag and drop protocol. You can drag a file object from another program, and drop it onto a Dired buffer; this either moves, copies, or creates a link to the file in that directory. Precisely which action is taken is diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index aa9977a52e5..a722ec4841b 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -1,5 +1,6 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @@ -47,18 +48,18 @@ the text is displayed. displays only a portion of it. @dfn{Scrolling} commands change which portion of the buffer is displayed. - Scrolling ``forward'' or ``up'' advances the portion of the buffer + Scrolling forward or up advances the portion of the buffer displayed in the window; equivalently, it moves the buffer text -upwards relative to the window. Scrolling ``backward'' or ``down'' +upwards relative to the window. Scrolling backward or down displays an earlier portion of the buffer, and moves the text downwards relative to the window. - In Emacs, scrolling ``up'' or ``down'' refers to the direction that + In Emacs, scrolling up or down refers to the direction that the text moves in the window, @emph{not} the direction that the window moves relative to the text. This terminology was adopted by Emacs before the modern meaning of ``scrolling up'' and ``scrolling down'' became widespread. Hence, the strange result that @key{PageDown} -scrolls ``up'' in the Emacs sense. +scrolls up in the Emacs sense. The portion of a buffer displayed in a window always contains point. If you move point past the bottom or top of the window, scrolling @@ -127,6 +128,19 @@ the mouse wheel (@pxref{Mouse Commands}); in general, it affects any command that has a non-@code{nil} @code{scroll-command} property. @xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}. +@vindex fast-but-imprecise-scrolling + Sometimes, particularly when you hold down keys such as @kbd{C-v} +and @kbd{M-v}, activating keyboard auto-repeat, Emacs fails to keep up +with the rapid rate of scrolling requested; the display doesn't update +and Emacs can become unresponsive to input for quite a long time. You +can counter this sluggishness by setting the variable +@code{fast-but-imprecise-scrolling} to a non-@code{nil} value. This +instructs the scrolling commands not to fontify (@pxref{Font Lock}) +any unfontified text they scroll over, instead to assume it has the +default face. This can cause Emacs to scroll to somewhat wrong buffer +positions when the faces in use are not all the same size, even with +single (i.e., without auto-repeat) scrolling operations. + @vindex scroll-up @vindex scroll-down @findex scroll-up-line @@ -428,8 +442,8 @@ it. @xref{Disabling}. screenfuls. It provides commands for scrolling through the buffer conveniently but not for changing it. Apart from the usual Emacs cursor motion commands, you can type @key{SPC} to scroll forward one -windowful, @key{DEL} to scroll backward, and @kbd{s} to start an -incremental search. +windowful, @kbd{S-@key{SPC}} or @key{DEL} to scroll backward, and @kbd{s} to +start an incremental search. @kindex q @r{(View mode)} @kindex e @r{(View mode)} @@ -455,7 +469,7 @@ and visits it with View mode enabled. @cindex synchronizing windows @dfn{Follow mode} is a minor mode that makes two windows, both -showing the same buffer, scroll as a single tall ``virtual window''. +showing the same buffer, scroll as a single tall virtual window. To use Follow mode, go to a frame with just one window, split it into two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x follow-mode}. From then on, you can edit the buffer in either of the @@ -578,6 +592,7 @@ Parameters}. @node Standard Faces @section Standard Faces +@cindex standard faces Here are the standard faces for specifying text appearance. You can apply them to specific text when you want the effects they produce. @@ -598,8 +613,10 @@ This face underlines text. This face forces use of a fixed-width font. It's reasonable to customize this face to use a different fixed-width font, if you like, but you should not make it a variable-width font. +@cindex variable-pitch face @item variable-pitch This face forces use of a variable-width font. +@cindex shadow face @item shadow This face is used for making the text less noticeable than the surrounding ordinary text. Usually this can be achieved by using shades of gray in @@ -621,7 +638,7 @@ This face is used to highlight the current Isearch match This face is used to highlight the current Query Replace match (@pxref{Replace}). @item lazy-highlight -This face is used to highlight ``lazy matches'' for Isearch and Query +This face is used to highlight lazy matches for Isearch and Query Replace (matches other than the current one). @item region This face is used for displaying an active region (@pxref{Mark}). @@ -638,7 +655,7 @@ Whitespace}). The face for displaying control characters and escape sequences (@pxref{Text Display}). @item nobreak-space -The face for displaying ``no-break'' space characters (@pxref{Text +The face for displaying no-break space characters (@pxref{Text Display}). @end table @@ -647,25 +664,34 @@ frame: @table @code @item mode-line +@cindex mode-line face +@cindex faces for mode lines This face is used for the mode line of the currently selected window, and for menu bars when toolkit menus are not used. By default, it's -drawn with shadows for a ``raised'' effect on graphical displays, and +drawn with shadows for a raised effect on graphical displays, and drawn as the inverse of the default face on non-windowed terminals. @item mode-line-inactive +@cindex mode-line-inactive face Like @code{mode-line}, but used for mode lines of the windows other than the selected one (if @code{mode-line-in-non-selected-windows} is non-@code{nil}). This face inherits from @code{mode-line}, so changes in that face affect mode lines in all windows. @item mode-line-highlight -Like @code{highlight}, but used for portions of text on mode lines. +@cindex mode-line-highlight face +Like @code{highlight}, but used for mouse-sensitive portions of text +on mode lines. Such portions of text typically pop up tooltips +(@pxref{Tooltips}) when the mouse pointer hovers above them. @item mode-line-buffer-id +@cindex mode-line-buffer-id face This face is used for buffer identification parts in the mode line. @item header-line +@cindex header-line face Similar to @code{mode-line} for a window's header line, which appears at the top of a window just as the mode line appears at the bottom. Most windows do not have a header line---only some special modes, such Info mode, create one. @item vertical-border +@cindex vertical-border face This face is used for the vertical divider between windows on text terminals. @item minibuffer-prompt @@ -674,8 +700,9 @@ terminals. This face is used for the prompt strings displayed in the minibuffer. By default, Emacs automatically adds this face to the value of @code{minibuffer-prompt-properties}, which is a list of text -properties used to display the prompt text. (This variable takes -effect when you enter the minibuffer.) +properties (@pxref{Text Properties,,, elisp, the Emacs Lisp Reference +Manual}) used to display the prompt text. (This variable takes effect +when you enter the minibuffer.) @item fringe @cindex @code{fringe} face The face for the fringes to the left and right of windows on graphic @@ -710,6 +737,17 @@ This face determines the color of tool bar icons. @xref{Tool Bars}. @cindex customization of @code{menu} face This face determines the colors and font of Emacs's menus. @xref{Menu Bars}. +@item tty-menu-enabled-face +@cindex faces for text-mode menus +@cindex TTY menu faces +This face is used to display enabled menu items on text-mode +terminals. +@item tty-menu-disabled-face +This face is used to display disabled menu items on text-mode +terminals. +@item tty-menu-selected-face +This face is used to display on text-mode terminals the menu item that +would be selected if you click a mouse or press @key{RET}. @end table @node Text Scale @@ -732,9 +770,9 @@ determine which action to take. @kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face height by three steps. Each step scales the text height by a factor of 1.2; to change this factor, customize the variable -@code{text-scale-mode-step}. As an exception, a numeric argument of 0 +@code{text-scale-mode-step}. A numeric argument of 0 to the @code{text-scale-adjust} command restores the default height, -similar to typing @kbd{C-x C-0}. +the same as typing @kbd{C-x C-0}. @cindex increase buffer face height @findex text-scale-increase @@ -817,7 +855,6 @@ and the default level otherwise, use the value '((c-mode . 1) (c++-mode . 1))) @end example -@vindex font-lock-beginning-of-syntax-function @cindex incorrect fontification @cindex parenthesis in column zero and fontification @cindex brace in column zero and fontification @@ -830,19 +867,6 @@ any string or comment. Therefore, you should avoid placing an open-parenthesis or open-brace in the leftmost column, if it is inside a string or comment. @xref{Left Margin Paren}, for details. -@cindex slow display during scrolling - The variable @code{font-lock-beginning-of-syntax-function}, which is -always buffer-local, specifies how Font Lock mode can find a position -guaranteed to be outside any comment or string. In modes which use -the leftmost column parenthesis convention, the default value of the -variable is @code{beginning-of-defun}---that tells Font Lock mode to -use the convention. If you set this variable to @code{nil}, Font Lock -no longer relies on the convention. This avoids incorrect results, -but the price is that, in some cases, fontification for a changed text -must rescan buffer text from the beginning of the buffer. This can -considerably slow down redisplay while scrolling, particularly if you -are close to the end of a large buffer. - @findex font-lock-add-keywords Font Lock highlighting patterns already exist for most modes, but you may want to fontify additional patterns. You can use the function @@ -917,6 +941,12 @@ highlighting, Hi Lock provides several of its own and these are pre-loaded into a list of default values. While being prompted for a face use @kbd{M-n} and @kbd{M-p} to cycle through them. +@vindex hi-lock-auto-select-face +Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil} +value causes this command (and other Hi Lock commands that read faces) +to automatically choose the next face from the default list without +prompting. + You can use this command multiple times, specifying various regular expressions to highlight in different ways. @@ -965,8 +995,8 @@ initial lower-case letters will become case insensitive. @findex highlight-symbol-at-point @cindex symbol, highlighting @cindex highlighting symbol at point -Highlight the symbol found near point without prompting, using the next -available face automatically (@code{highlight-symbol-at-point}). +Highlight the symbol found near point, using the next available face +(@code{highlight-symbol-at-point}). @item M-s h w @itemx C-x w b @@ -1030,17 +1060,18 @@ variable @code{fringe-mode}. The most common use of the fringes is to indicate a continuation line (@pxref{Continuation Lines}). When one line of text is split into multiple screen lines, the left fringe shows a curving arrow for -each screen line except the first, indicating that ``this is not the -real beginning''. The right fringe shows a curving arrow for each -screen line except the last, indicating that ``this is not the real -end''. If the line's direction is right-to-left (@pxref{Bidirectional +each screen line except the first, indicating that this is not the +real beginning. The right fringe shows a curving arrow for each +screen line except the last, indicating that this is not the real +end. If the line's direction is right-to-left (@pxref{Bidirectional Editing}), the meanings of the curving arrows in the fringes are swapped. - The fringes indicate line truncation with short horizontal arrows -meaning ``there's more text on this line which is scrolled -horizontally out of view''. Clicking the mouse on one of the arrows -scrolls the display horizontally in the direction of the arrow. + The fringes indicate line truncation (@pxref{Line Truncation}) with +short horizontal arrows meaning there's more text on this line which +is scrolled horizontally out of view. Clicking the mouse on one of +the arrows scrolls the display horizontally in the direction of the +arrow. The fringes can also indicate other things, such as buffer boundaries (@pxref{Displaying Boundaries}), and where a program you @@ -1068,13 +1099,14 @@ how the buffer boundaries and window scrolling is indicated in the fringes. If the value is @code{left} or @code{right}, both angle and arrow bitmaps are displayed in the left or right fringe, respectively. - If value is an alist, each element @code{(@var{indicator} . -@var{position})} specifies the position of one of the indicators. -The @var{indicator} must be one of @code{top}, @code{bottom}, -@code{up}, @code{down}, or @code{t} which specifies the default -position for the indicators not present in the alist. -The @var{position} is one of @code{left}, @code{right}, or @code{nil} -which specifies not to show this indicator. + If value is an alist (@pxref{Association Lists,,, elisp, the Emacs +Lisp Reference Manual}), each element @code{(@var{indicator} . +@var{position})} specifies the position of one of the indicators. The +@var{indicator} must be one of @code{top}, @code{bottom}, @code{up}, +@code{down}, or @code{t} which specifies the default position for the +indicators not present in the alist. The @var{position} is one of +@code{left}, @code{right}, or @code{nil} which specifies not to show +this indicator. For example, @code{((top . left) (t . right))} places the top angle bitmap in left fringe, the bottom angle bitmap in right fringe, and @@ -1093,14 +1125,15 @@ empty lines at the end of a buffer, without realizing it. In most cases, this @dfn{trailing whitespace} has no effect, but sometimes it can be a nuisance. +@cindex trailing-whitespace face You can make trailing whitespace at the end of a line visible by setting the buffer-local variable @code{show-trailing-whitespace} to @code{t}. Then Emacs displays trailing whitespace, using the face @code{trailing-whitespace}. This feature does not apply when point is at the end of the line -containing the whitespace. Strictly speaking, that is ``trailing -whitespace'' nonetheless, but displaying it specially in that case +containing the whitespace. Strictly speaking, that is trailing +whitespace nonetheless, but displaying it specially in that case looks ugly while you are typing in new text. In this special case, the location of point is enough to show you that the spaces are present. @@ -1132,7 +1165,7 @@ indicate-empty-lines t)}. @findex whitespace-mode @vindex whitespace-style Whitespace mode is a buffer-local minor mode that lets you -``visualize'' many kinds of whitespace in the buffer, by either +visualize many kinds of whitespace in the buffer, by either drawing the whitespace characters with a special face or displaying them as special glyphs. To toggle this mode, type @kbd{M-x whitespace-mode}. The kinds of whitespace visualized are determined @@ -1158,7 +1191,7 @@ Highlight space and non-breaking space characters. @item lines @vindex whitespace-line-column -Highlight lines longer than 80 lines. To change the column limit, +Highlight lines longer than 80 columns. To change the column limit, customize the variable @code{whitespace-line-column}. @item newline @@ -1228,11 +1261,11 @@ Size Indication mode. The size will be displayed immediately following the buffer percentage like this: @example -@var{POS} of @var{SIZE} +@var{pos} of @var{size} @end example @noindent -Here @var{SIZE} is the human readable representation of the number of +Here @var{size} is the human readable representation of the number of characters in the buffer, which means that @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. @@ -1312,9 +1345,9 @@ the mail indicator prominent. Use @code{display-time-mail-file} to specify the mail file to check, or set @code{display-time-mail-directory} to specify the directory to check for incoming mail (any nonempty regular file in the directory is -considered as ``newly arrived mail''). +considered to be newly arrived mail). -@cindex mail (on mode line) +@cindex battery status (on mode line) @findex display-battery-mode @vindex display-battery-mode @vindex battery-mode-line-format @@ -1401,6 +1434,8 @@ as octal escape sequences instead of caret escape sequences. @cindex non-breaking space @cindex non-breaking hyphen @cindex soft hyphen +@cindex escape-glyph face +@cindex nobreak-space face Some non-@acronym{ASCII} characters have the same appearance as an @acronym{ASCII} space or hyphen (minus) character. Such characters can cause problems if they are entered into a buffer without your @@ -1432,6 +1467,15 @@ customizing the variable @code{glyphless-char-display-control}. @xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs Lisp Reference Manual}, for details. +@cindex curly quotes +@cindex curved quotes +@cindex escape-glyph face + If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are +known to look just like @acronym{ASCII} characters, they are shown +with the @code{escape-glyph} face. Curved quotes that cannot be +displayed are shown as their @acronym{ASCII} approximations @samp{`}, +@samp{'}, and @samp{"} with the @code{escape-glyph} face. + @node Cursor Display @section Displaying the Cursor @cindex text cursor @@ -1439,8 +1483,8 @@ Lisp Reference Manual}, for details. @vindex visible-cursor On a text terminal, the cursor's appearance is controlled by the terminal, largely out of the control of Emacs. Some terminals offer -two different cursors: a ``visible'' static cursor, and a ``very -visible'' blinking cursor. By default, Emacs uses the very visible +two different cursors: a visible static cursor, and a very +visible blinking cursor. By default, Emacs uses the very visible cursor, and switches to it when you start or resume Emacs. If the variable @code{visible-cursor} is @code{nil} when Emacs starts or resumes, it uses the normal cursor. @@ -1462,21 +1506,34 @@ pixels tall), or @code{nil} (no cursor at all). @findex blink-cursor-mode @cindex cursor, blinking @cindex blinking cursor +@vindex blink-cursor-mode +@vindex blink-cursor-blinks @vindex blink-cursor-alist - To disable cursor blinking, change the variable -@code{blink-cursor-mode} to @code{nil} (@pxref{Easy Customization}), -or add the line @code{(blink-cursor-mode 0)} to your init file. -Alternatively, you can change how the cursor looks when it ``blinks -off'' by customizing the list variable @code{blink-cursor-alist}. -Each element in the list should have the form @code{(@var{on-type} -. @var{off-type})}; this means that if the cursor is displayed as -@var{on-type} when it blinks on (where @var{on-type} is one of the -cursor types described above), then it is displayed as @var{off-type} -when it blinks off. + By default, the cursor stops blinking after 10 blinks, if Emacs does +not get any input during that time; any input event restarts the +count. You can customize the variable @code{blink-cursor-blinks} to +control that: its value says how many times to blink without input +before stopping. Setting that variable to a zero or negative value +will make the cursor blink forever. To disable cursor blinking +altogether, change the variable @code{blink-cursor-mode} to @code{nil} +(@pxref{Easy Customization}), or add the line + +@lisp + (blink-cursor-mode 0) +@end lisp + +@noindent +to your init file. Alternatively, you can change how the cursor +looks when it blinks off by customizing the list variable +@code{blink-cursor-alist}. Each element in the list should have the +form @code{(@var{on-type} . @var{off-type})}; this means that if the +cursor is displayed as @var{on-type} when it blinks on (where +@var{on-type} is one of the cursor types described above), then it is +displayed as @var{off-type} when it blinks off. @vindex x-stretch-cursor @cindex wide block cursor - Some characters, such as tab characters, are ``extra wide''. When + Some characters, such as tab characters, are extra wide. When the cursor is positioned over such a character, it is normally drawn with the default character width. You can make the cursor stretch to cover wide characters, by changing the variable @@ -1601,14 +1658,14 @@ there is something to echo. @xref{Echo Area}. On graphical displays, Emacs displays the mouse pointer as an hourglass if Emacs is busy. To disable this feature, set the variable @code{display-hourglass} to @code{nil}. The variable -@code{hourglass-delay} determines the number of seconds of ``busy -time'' before the hourglass is shown; the default is 1. +@code{hourglass-delay} determines the number of seconds of busy +time before the hourglass is shown; the default is 1. @vindex make-pointer-invisible If the mouse pointer lies inside an Emacs frame, Emacs makes it invisible each time you type a character to insert text, to prevent it from obscuring the text. (To be precise, the hiding occurs when you -type a ``self-inserting'' character. @xref{Inserting Text}.) Moving +type a self-inserting character. @xref{Inserting Text}.) Moving the mouse pointer makes it visible again. To disable this feature, set the variable @code{make-pointer-invisible} to @code{nil}. diff --git a/doc/emacs/docstyle.texi b/doc/emacs/docstyle.texi new file mode 100644 index 00000000000..dfd14306b39 --- /dev/null +++ b/doc/emacs/docstyle.texi @@ -0,0 +1,10 @@ +@c Emacs documentation style settings +@documentencoding UTF-8 +@c These two require Texinfo 5.0 or later, so we use the older +@c equivalent @set variables supported in 4.11 and hence +@ignore +@codequotebacktick on +@codequoteundirected on +@end ignore +@set txicodequoteundirected +@set txicodequotebacktick diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi index f67ed3d5cad..3490c08d275 100644 --- a/doc/emacs/emacs-xtra.texi +++ b/doc/emacs/emacs-xtra.texi @@ -1,7 +1,8 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/emacs-xtra +@setfilename ../../info/emacs-xtra.info @settitle Specialized Emacs Features +@include docstyle.texi @c Merge all functions, variables, and keys into the concept index. @syncodeindex fn cp @syncodeindex vr cp @@ -11,13 +12,13 @@ @copying This manual describes specialized features of Emacs. -Copyright @copyright{} 2004--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2015 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,'' +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''. @@ -26,8 +27,6 @@ modify this GNU manual.'' @end quotation @end copying -@documentencoding UTF-8 - @dircategory Emacs @direntry * Emacs-Xtra: (emacs-xtra). Specialized Emacs features. @@ -120,7 +119,7 @@ the Emacs manual. @include fortran-xtra.texi -@include msdog-xtra.texi +@include msdos-xtra.texi @lowersections @end iftex diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 8a518b82abb..27bb77d5cac 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -1,7 +1,8 @@ \input texinfo @c -*- coding: utf-8 -*- -@setfilename ../../info/emacs +@setfilename ../../info/emacs.info @settitle GNU Emacs Manual +@include docstyle.texi @c The edition number appears in more than one place in this file @c I don't really know what it means... @@ -26,14 +27,14 @@ This is the @cite{GNU Emacs Manual}, @end ifnottex updated for Emacs version @value{EMACSVER}. -Copyright @copyright{} 1985--1987, 1993--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1985--1987, 1993--2015 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being ``The GNU Manifesto,'' ``Distribution'' and -``GNU GENERAL PUBLIC LICENSE,'' with the Front-Cover texts being ``A GNU +``GNU GENERAL PUBLIC LICENSE,'' with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' @@ -44,11 +45,9 @@ developing GNU and promoting software freedom.'' @end quotation @end copying -@documentencoding UTF-8 - @dircategory Emacs @direntry -* Emacs: (emacs). The extensible self-documenting text editor. +* Emacs: (emacs). The extensible self-documenting text editor. @end direntry @c in general, keep the following line commented out, unless doing a @@ -94,7 +93,7 @@ developing GNU and promoting software freedom.'' Published by the Free Software Foundation @* 51 Franklin Street, Fifth Floor @* Boston, MA 02110-1301 USA @* -ISBN 978-0-9831592-4-7 +ISBN 978-0-9831592-5-4 @sp 2 Cover art by Etienne Suvasa; cover design by Matt Lee. @@ -115,6 +114,7 @@ display editor. This manual describes how to edit with Emacs and some of the ways to customize it; it corresponds to GNU Emacs version @value{EMACSVER}. +@c See 'manual-html-mono' and 'manual-html-node' in admin/admin.el. @ifset WWW_GNU_ORG @html The homepage for GNU Emacs is at @@ -160,7 +160,7 @@ Fundamental Editing Commands * Help:: Commands for asking Emacs about its commands. Important Text-Changing Commands -* Mark:: The mark: how to delimit a "region" of text. +* Mark:: The mark: how to delimit a region of text. * Killing:: Killing (cutting) and yanking (copying) text. * Registers:: Saving a text string or a location in the buffer. * Display:: Controlling what text is displayed. @@ -172,7 +172,7 @@ Major Structures of Emacs * Files:: All about handling files. * Buffers:: Multiple buffers; editing several files at once. * Windows:: Viewing multiple pieces of text in one frame. -* Frames:: Using multiple "windows" on your display. +* Frames:: Using multiple windows on your display. * International:: Using non-@acronym{ASCII} character sets. Advanced Features @@ -188,7 +188,9 @@ Advanced Features * Sending Mail:: Sending mail in Emacs. * Rmail:: Reading mail in Emacs. * Gnus:: A flexible mail and news reader. +* Network Security:: Managing the network security. * Document View:: Viewing PDF, PS and DVI files. +* EWW:: A web browser in Emacs. * Shell:: Executing shell commands from Emacs. * Emacs Server:: Using Emacs as an editing server. * Printing:: Printing hardcopies of buffers or regions. @@ -198,8 +200,7 @@ Advanced Features @end ifnottex * Editing Binary Files:: Editing binary files with Hexl mode. * Saving Emacs Sessions:: Saving Emacs state from one session to the next. -* Recursive Edit:: Performing edits while "within another command". -* Emulation:: Emulating some other editors with Emacs. +* Recursive Edit:: Performing edits while within another command. * Hyperlinking:: Following links in buffers. * Amusements:: Various games and hacks. * Packages:: Installing additional features. @@ -237,9 +238,9 @@ Indexes (each index contains a large menu) * Concept Index:: An item for each concept. @c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In +@c be correctly identified by 'texinfo-multiple-files-update'. In @c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. +@c value of 'texinfo-master-menu-header'. See texnfo-upd.el. @detailmenu --- The Detailed Node Listing --- @@ -300,7 +301,7 @@ Help * Language Help:: Help relating to international language support. * Misc Help:: Other help commands. * Help Files:: Commands to display auxiliary help files. -* Help Echo:: Help on active text and tooltips ("balloon help"). +* Help Echo:: Help on active text and tooltips. The Mark and the Region @@ -336,7 +337,7 @@ Yanking * Earlier Kills:: Yanking something killed some time ago. * Appending Kills:: Several kills in a row all yank together. -"Cut and Paste" Operations on Graphical Displays +Cut and Paste Operations on Graphical Displays * Clipboard:: How Emacs uses the system clipboard. * Primary Selection:: The temporarily selected text selection. @@ -344,13 +345,14 @@ Yanking Registers -* Position Registers:: Saving positions in registers. -* Text Registers:: Saving text in registers. -* Rectangle Registers:: Saving rectangles in registers. -* Configuration Registers:: Saving window configurations in registers. -* Number Registers:: Numbers in registers. -* File Registers:: File names in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. +* Position Registers:: Saving positions in registers. +* Text Registers:: Saving text in registers. +* Rectangle Registers:: Saving rectangles in registers. +* Configuration Registers:: Saving window configurations in registers. +* Number Registers:: Numbers in registers. +* File Registers:: File names in registers. +* Keyboard Macro Registers:: Keyboard macros in registers. +* Bookmarks:: Bookmarks are like registers, but persistent. Controlling the Display @@ -462,7 +464,7 @@ Saving Files * Customize Save:: Customizing the saving of files. * Interlocking:: How Emacs protects against simultaneous editing of one file by two users. -* File Shadowing:: Copying files to "shadows" automatically. +* File Shadowing:: Copying files to shadows automatically. * Time Stamps:: Emacs can update time stamps on saved files. Backup Files @@ -490,7 +492,7 @@ Using Multiple Buffers * Select Buffer:: Creating a new buffer or reselecting an old one. * List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onlyness; copying text. +* Misc Buffer:: Renaming; changing read-only status; copying text. * Kill Buffer:: Killing buffers you no longer need. * Several Buffers:: How to go through the list of all buffers and operate variously on several of them. @@ -501,7 +503,7 @@ Using Multiple Buffers Convenience Features and Customization of Buffer Handling * Uniquify:: Making buffer names unique with directory parts. -* Iswitchb:: Switching between buffers with substrings. +* Icomplete:: Fast minibuffer selection. * Buffer Menus:: Configurable buffer menu. Multiple Windows @@ -595,7 +597,7 @@ Commands for Human Languages * TeX Mode:: Editing TeX and LaTeX files. * HTML Mode:: Editing HTML and SGML files. * Nroff Mode:: Editing input to the nroff formatter. -* Enriched Text:: Editing text "enriched" with fonts, colors, etc. +* Enriched Text:: Editing text enriched with fonts, colors, etc. * Text Based Tables:: Commands for editing text-based tables. * Two-Column:: Splitting text columns into separate windows. @@ -636,7 +638,7 @@ Enriched Text * Enriched Indentation:: Changing the left and right margins. * Enriched Justification:: Centering, setting text flush with the left or right margin, etc. -* Enriched Properties:: The "special" text properties submenu. +* Enriched Properties:: The ``Special text properties'' submenu. @c The automatic texinfo menu update inserts some duplicate items here @c (faces, colors, indentation, justification, properties), because @@ -665,7 +667,7 @@ Editing Programs * Documentation:: Getting documentation of functions you plan to call. * Hideshow:: Displaying blocks selectively. * Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. +* MixedCase Words:: Dealing with identifiersLikeThis. * Semantic:: Suite of editing tools based on source code parsing. * Misc for Programs:: Other Emacs features useful for editing programs. * C Modes:: Special commands of C, C++, Objective-C, @@ -829,7 +831,7 @@ VC Directory Mode Version Control Branches * Switching Branches:: How to get to another existing branch. -* VC Pull:: Updating the contents of a branch. +* Pulling / Pushing:: Receiving/sending changes from/to elsewhere. * Merging:: Transferring changes between branches. * Creating Branches:: How to start a new branch. @@ -893,7 +895,7 @@ Editing Pictures * Basic Picture:: Basic concepts and simple commands of Picture Mode. * Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. + after self-inserting characters. * Tabs in Picture:: Various features for tab stops and indentation. * Rectangles in Picture:: Clearing and superimposing rectangles. @end ifnottex @@ -959,8 +961,8 @@ Conversion To and From Other Calendars The Diary -* Displaying the Diary:: Viewing diary entries and associated calendar dates. * Format of Diary File:: Entering events in your diary. +* Displaying the Diary:: Viewing diary entries and associated calendar dates. * Date Formats:: Various ways you can specify dates. * Adding to Diary:: Commands to create diary entries. * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. @@ -1090,7 +1092,7 @@ Customization to decide what to do; by setting variables, you can control their functioning. * Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine" keys. + By changing them, you can redefine keys. * Init File:: How to write common customizations in the initialization file. @@ -1146,7 +1148,7 @@ The Emacs Initialization File Dealing with Emacs Trouble * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. +* Stuck Recursive:: '[...]' in mode line around the parentheses. * Screen Garbled:: Garbage on the screen. * Text Garbled:: Garbage in the text. * Memory Full:: How to cope when you run out of memory. @@ -1189,7 +1191,7 @@ X Options and Resources * Resources:: Using X resources with Emacs (in general). * Table of Resources:: Table of specific X resources that affect Emacs. * Lucid Resources:: X resources for Lucid menus. -* LessTif Resources:: X resources for LessTif and Motif menus. +* Motif Resources:: X resources for Motif and LessTif menus. * GTK resources:: Resources for GTK widgets. GTK resources @@ -1336,9 +1338,12 @@ If you find GNU Emacs useful, please @strong{send a donation} to the Free Software Foundation to support our work. Donations to the Free Software Foundation are tax deductible in the US@. If you use GNU Emacs at your workplace, please suggest that the company make a donation. -For more information on how you can help, see +To donate, see @url{https://my.fsf.org/donate/}. +For other ways in which you can help, see @url{http://www.gnu.org/help/help.html}. +@c The command view-order-manuals uses this anchor. +@anchor{Printed Books} We also sell hardcopy versions of this manual and @cite{An Introduction to Programming in Emacs Lisp}, by Robert J. Chassell. You can visit our online store at @url{http://shop.fsf.org/}. @@ -1360,12 +1365,14 @@ USA @node Acknowledgments @unnumberedsec Acknowledgments +@c It's hard to update this fairly. +@c I wonder if it would be better to drop it in favor of AUTHORS? Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas Abrahamsson, Jay K. Adams, Alon Albert, Michael Albinus, Nagy Andras, Benjamin Andresen, Ralf Angeli, Dmitry Antipov, Joe Arceneaux, Emil Åström, Miles Bader, David Bakhash, Juanma Barranquero, Eli Barzilay, Thomas Baumann, Steven L. Baur, Jay Belanger, Alexander L. Belikoff, -Thomas Bellman, Scott Bender, Boaz Ben-Zvi, Sergey Berezin, Karl +Thomas Bellman, Scott Bender, Boaz Ben-Zvi, Sergey Berezin, Stephen Berman, Karl Berry, Anna M. Bigatti, Ray Blaak, Martin Blais, Jim Blandy, Johan Bockgård, Jan Böcker, Joel Boehland, Lennart Borgman, Per Bothner, Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel Briot, Kevin @@ -1385,13 +1392,13 @@ Eglen, Christian Egli, Torbjörn Einarsson, Tsugutomo Enami, David Engster, Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick Farnbach, Oscar Figueiredo, Fred Fish, Steve Fisk, Karl Fogel, Gary Foster, Eric S. Fraga, Romain Francoise, Noah Friedman, Andreas -Fuchs, Shigeru Fukaya, Hallvard Furuseth, Keith Gabryelski, Peter S. +Fuchs, Shigeru Fukaya, Xue Fuqiao, Hallvard Furuseth, Keith Gabryelski, Peter S. Galbraith, Kevin Gallagher, Fabián E. Gallina, Kevin Gallo, Juan León Lahoz García, Howard Gayle, Daniel German, Stephen Gildea, Julien Gilles, David Gillespie, Bob Glickstein, Deepak Goel, David De La Harpe Golden, Boris Goldowsky, David Goodger, Chris Gray, Kevin Greiner, Michelangelo Grigni, Odd Gripenstam, Kai Großjohann, Michael Gschwind, Bastien Guerry, Henry -Guillaume, Doug Gwyn, Bruno Haible, Ken'ichi Handa, Lars Hansen, Chris +Guillaume, Dmitry Gutov, Doug Gwyn, Bruno Haible, Ken'ichi Handa, Lars Hansen, Chris Hanson, Jesper Harder, Alexandru Harsanyi, K. Shane Hartman, John Heidemann, Jon K. Hellan, Magnus Henoch, Markus Heritsch, Dirk Herrmann, Karl Heuer, Manabu Higashida, Konrad Hinsen, Anders Holst, @@ -1409,25 +1416,25 @@ Ryszard Kubiak, Igor Kuzmin, David Kågedal, Daniel LaLiberte, Karl Landstrom, Mario Lang, Aaron Larson, James R. Larus, Vinicius Jose Latorre, Werner Lemberg, Frederic Lepied, Peter Liljenberg, Christian Limpach, Lars Lindberg, Chris Lindblad, Anders Lindgren, Thomas Link, -Juri Linkov, Francis Litterio, Sergey Litvinov, Emilio C. Lopes, +Juri Linkov, Francis Litterio, Sergey Litvinov, Leo Liu, Emilio C. Lopes, Martin Lorentzon, Dave Love, Eric Ludlam, Károly Lőrentey, Sascha Lüdecke, Greg McGary, Roland McGrath, Michael McNamara, Alan Mackenzie, Christopher J. Madsen, Neil M. Mager, Ken Manheimer, Bill Mann, Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin, Yukihiro Matsumoto, Tomohiro Matsuyama, David Maus, Thomas May, Will Mengarini, David Megginson, Stefan Merten, Ben A. Mesander, Wayne Mesard, Brad -Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Moellmann, Stefan +Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Möllmann, Dani Moncayo, Stefan Monnier, Keith Moore, Jan Moringen, Morioka Tomohiko, Glenn Morris, Don Morrison, Diane Murray, Riccardo Murri, Sen Nagata, Erik Naggum, Gergely Nagy, Nobuyoshi Nakada, Thomas Neumann, Mike Newton, Thien-Thi Nguyen, -Jurgen Nickelsen, Dan Nicolaescu, Hrvoje Niksic, Jeff Norden, +Jurgen Nickelsen, Dan Nicolaescu, Hrvoje Nikšić, Jeff Norden, Andrew Norman, Edward O'Connor, Kentaro Ohkouchi, Christian Ohler, Kenichi Okada, Alexandre Oliva, Bob Olson, Michael Olson, Takaaki Ota, Pieter E. J. Pareit, Ross Patterson, David Pearson, Juan Pechiar, Jeff Peck, Damon Anton Permezel, Tom Perrine, William M. Perry, Per Persson, Jens Petersen, Daniel Pfeiffer, Justus Piater, Richard L. Pieri, Fred Pierresteguy, François Pinard, Daniel Pittman, Christian -Plaunt, Alexander Pohoyda, David Ponce, Francesco A. Potorti, +Plaunt, Alexander Pohoyda, David Ponce, Francesco A. Potortì, Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko Rahamaa, Ashwin Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, David Reitter, Alex Rezinsky, Rob Riepel, Lara Rios, Adrian Robert, Nick @@ -1435,10 +1442,10 @@ Roberts, Roland B. Roberts, John Robinson, Denis B. Roegel, Danny Roozendaal, Sebastian Rose, William Rosenblatt, Markus Rost, Guillermo J. Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, Wolfgang Rupprecht, Benjamin Rutt, Kevin Ryde, James B. Salem, Masahiko Sato, -Timo Savola, Jorgen Schaefer, Holger Schauer, William Schelter, Ralph +Timo Savola, Jorgen Schäfer, Holger Schauer, William Schelter, Ralph Schleicher, Gregor Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebelen, Jan Schormann, Alex Schroeder, Stefan Schoef, -Rainer Schoepf, Raymond Scholz, Eric Schulte, Andreas Schwab, Randal +Rainer Schöpf, Raymond Scholz, Eric Schulte, Andreas Schwab, Randal Schwartz, Oliver Seidel, Manuel Serrano, Paul Sexton, Hovav Shacham, Stanislav Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Tibor Šimko, Espen Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, @@ -1447,7 +1454,7 @@ South, Andre Spiegel, Michael Staats, Thomas Steffen, Ulf Stegemann, Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken Stevens, Andy Stewart, Jonathan Stigelman, Martin Stjernholm, Kim F. Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto -Takahashi, Steven Tamm, Luc Teirlinck, Jean-Philippe Theberge, Jens +Takahashi, Steven Tamm, Jan Tatarik, Luc Teirlinck, Jean-Philippe Theberge, Jens T. Berger Thielemann, Spencer Thomas, Jim Thompson, Toru Tomabechi, David O'Toole, Markus Triska, Tom Tromey, Enami Tsugutomo, Eli Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil @@ -1460,7 +1467,7 @@ Wohler, Steven A. Wood, Dale R. Worley, Francis J. Wright, Felix S. T. Wu, Tom Wurgler, Yamamoto Mitsuharu, Katsumi Yamaoka, Masatake Yamato, Jonathan Yavner, Ryan Yeske, Ilya Zakharevich, Milan Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Andrew Zhilin, -Shenghuo Zhu, Piotr Zielinski, Ian T. Zimmermann, Reto Zimmermann, +Shenghuo Zhu, Piotr Zieliński, Ian T. Zimmermann, Reto Zimmermann, Neal Ziring, Teodor Zlatanov, and Detlev Zundel. @end iftex @@ -1469,7 +1476,16 @@ Neal Ziring, Teodor Zlatanov, and Detlev Zundel. You are reading about GNU Emacs, the GNU incarnation of the advanced, self-documenting, customizable, extensible editor Emacs. -(The `G' in `GNU' is not silent.) +(The @samp{G} in +@c Workaround makeinfo 4 bug. +@c http://lists.gnu.org/archive/html/bug-texinfo/2004-08/msg00009.html +@iftex +@acronym{GNU, @acronym{GNU}'s Not Unix} +@end iftex +@ifnottex +@acronym{GNU, GNU's Not Unix} +@end ifnottex +is not silent.) We call Emacs @dfn{advanced} because it can do much more than simple insertion and deletion of text. It can control subprocesses, indent @@ -1558,8 +1574,8 @@ Lisp programming. @include anti.texi @include macos.texi -@c Includes msdog-xtra. -@include msdog.texi +@c Includes msdos-xtra. +@include msdos.texi @include gnu.texi @include glossary.texi @ifnottex diff --git a/doc/emacs/emacsver.texi b/doc/emacs/emacsver.texi deleted file mode 100644 index 408d6612d58..00000000000 --- a/doc/emacs/emacsver.texi +++ /dev/null @@ -1,4 +0,0 @@ -@c It would be nicer to generate this using configure and @version@. -@c However, that would mean emacsver.texi would always be newer -@c then the info files in release tarfiles. -@set EMACSVER 24.3.50 diff --git a/doc/emacs/emacsver.texi.in b/doc/emacs/emacsver.texi.in new file mode 100644 index 00000000000..fa685125301 --- /dev/null +++ b/doc/emacs/emacsver.texi.in @@ -0,0 +1,2 @@ +@c configure generates emacsver.texi from emacsver.texi.in via a Makefile rule +@set EMACSVER @version@ diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi index 74775e51261..836b27c5002 100644 --- a/doc/emacs/emerge-xtra.texi +++ b/doc/emacs/emerge-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @@ -151,7 +151,7 @@ input. The mode line indicates Auto Advance mode with @samp{A}. If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands skip over differences in states ``prefer-A'' and ``prefer-B'' (@pxref{State of Difference}). Thus you see only differences for -which neither version is presumed ``correct''. The mode line +which neither version is presumed correct. The mode line indicates Skip Prefers mode with @samp{S}. This mode is only relevant when there is an ancestor. @@ -183,7 +183,7 @@ produces this state; the mode line indicates it with @samp{B}. The difference is showing the A or the B state by default, because you haven't made a choice. All differences start in the default-A state (and thus the merge buffer is a copy of the A buffer), except those for -which one alternative is ``preferred'' (see below). +which one alternative is preferred (see below). When you select a difference, its state changes from default-A or default-B to plain A or B@. Thus, the selected difference never has diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi index bb89e6ffd8b..8b8a9189626 100644 --- a/doc/emacs/entering.texi +++ b/doc/emacs/entering.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @@ -74,11 +74,19 @@ up before reading @file{site-start.el}. @xref{Init File}, for information about @file{site-start.el}.} You can also force Emacs to display a file or directory at startup -by setting the variable @code{initial-buffer-choice} to a -non-@code{nil} value. (In that case, even if you specify one or more -files on the command line, Emacs opens but does not display them.) -The value of @code{initial-buffer-choice} should be the name of -the desired file or directory. +by setting the variable @code{initial-buffer-choice} to a string +naming that file or directory. The value of +@code{initial-buffer-choice} may also be a function (of no arguments) +that should return a buffer which is then displayed. +@ignore +@c I do not think this should be mentioned. AFAICS it is just a dodge +@c around inhibit-startup-screen not being settable on a site-wide basis. +@code{initial-buffer-choice} may also be @code{t} in which case the +@file{*scratch*} buffer will be shown. +@end ignore +If @code{initial-buffer-choice} is non-@code{nil}, then if you specify +any files on the command line, Emacs still visits them, but does not +display them initially. @node Exiting @section Exiting Emacs @@ -92,7 +100,7 @@ the desired file or directory. Kill Emacs (@code{save-buffers-kill-terminal}). @item C-z On a text terminal, suspend Emacs; on a graphical display, -``minimize'' the selected frame (@code{suspend-emacs}). +iconify (or ``minimize'') the selected frame (@code{suspend-emacs}). @end table @kindex C-x C-c @@ -108,7 +116,7 @@ subprocesses are still running, since killing Emacs will also kill the subprocesses (@pxref{Shell}). @kbd{C-x C-c} behaves specially if you are using Emacs as a server. -If you type it from a ``client frame'', it closes the client +If you type it from a client frame, it closes the client connection. @xref{Emacs Server}. Emacs can, optionally, record certain session information when you diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index bff0926f347..5752d02fe85 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Files @@ -55,8 +55,8 @@ the file name, using the minibuffer (@pxref{Minibuffer File}). history commands (@pxref{Minibuffer}). Note that file name completion ignores file names whose extensions appear in the variable @code{completion-ignored-extensions} (@pxref{Completion Options}). -Note also that most commands use ``permissive completion with -confirmation'' for reading file names: you are allowed to submit a +Note also that most commands use permissive completion with +confirmation for reading file names: you are allowed to submit a nonexistent file name, but if you type @key{RET} immediately after completing up to a nonexistent file name, Emacs prints @samp{[Confirm]} and you must type a second @key{RET} to confirm. @@ -96,9 +96,9 @@ minibuffer, with a directory omitted, specifies the file @file{/u/rms/gnu/new/foo}. When typing a file name into the minibuffer, you can make use of a -couple of shortcuts: a double slash is interpreted as ``ignore -everything before the second slash in the pair'', and @samp{~/} is -interpreted as your home directory. @xref{Minibuffer File}. +couple of shortcuts: a double slash ignores everything before the +second slash in the pair, and @samp{~/} is your home directory. +@xref{Minibuffer File}. @cindex environment variables in file names @cindex expansion of environment variables @@ -171,9 +171,9 @@ the mode line (@pxref{Mode Line}). Emacs normally constructs the buffer name from the file name, omitting the directory name. For example, a file named @file{/usr/rms/emacs.tex} is visited in a buffer named @samp{emacs.tex}. If there is already a buffer with that name, -Emacs constructs a unique name; the normal method is to append -@samp{<2>}, @samp{<3>}, and so on, but you can select other methods. -@xref{Uniquify}. +Emacs constructs a unique name; the normal method is to add a suffix +based on the directory name (e.g., @samp{<rms>}, @samp{<tmp>}, +and so on), but you can select other methods. @xref{Uniquify}. @cindex creating files To create a new file, just visit it using the same command, @kbd{C-x @@ -232,7 +232,7 @@ after the directory part; this is convenient if you made a slight error in typing the name. @vindex find-file-run-dired - If you ``visit'' a file that is actually a directory, Emacs invokes + If you visit a file that is actually a directory, Emacs invokes Dired, the Emacs directory browser. @xref{Dired}. You can disable this behavior by setting the variable @code{find-file-run-dired} to @code{nil}; in that case, it is an error to try to visit a directory. @@ -274,18 +274,22 @@ new frame, or selects any existing frame showing the specified file. On graphical displays, there are two additional methods for visiting files. Firstly, when Emacs is built with a suitable GUI toolkit, commands invoked with the mouse (by clicking on the menu bar or tool -bar) use the toolkit's standard ``File Selection'' dialog instead of +bar) use the toolkit's standard file selection dialog instead of prompting for the file name in the minibuffer. On GNU/Linux and Unix platforms, Emacs does this when built with GTK, LessTif, and Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. For information on how to customize this, see @ref{Dialog Boxes}. - Secondly, Emacs supports ``drag and drop'': dropping a file into an + Secondly, Emacs supports drag and drop: dropping a file into an ordinary Emacs window visits the file using that window. As an exception, dropping a file into a window displaying a Dired buffer moves or copies the file into the displayed directory. For details, see @ref{Drag and Drop}, and @ref{Misc Dired Features}. + On text-mode terminals and on graphical displays when Emacs was +built without a GUI toolkit, you can visit files via the menu-bar +@samp{File} menu, which has a @samp{Visit New File} item. + Each time you visit a file, Emacs automatically scans its contents to detect what character encoding and end-of-line convention it uses, and converts these to Emacs's internal encoding and end-of-line @@ -336,7 +340,7 @@ that was visited in the buffer. * Customize Save:: Customizing the saving of files. * Interlocking:: How Emacs protects against simultaneous editing of one file by two users. -* Shadowing: File Shadowing. Copying files to "shadows" automatically. +* Shadowing: File Shadowing. Copying files to ``shadows'' automatically. * Time Stamps:: Emacs can update time stamps on saved files. @end menu @@ -425,7 +429,7 @@ by mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}), which clears out the indication that the buffer is modified. If you do this, none of the save commands will believe that the buffer needs to be saved. (@samp{~} is often used as a -mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.) +mathematical symbol for ``not''; thus @kbd{M-~} is ``not'', metafied.) Alternatively, you can cancel all the changes made since the file was visited or saved, by reading the text from the file again. This is called @dfn{reverting}. @xref{Reverting}. (You could also undo all @@ -439,7 +443,7 @@ minibuffer. Then it marks the buffer as visiting that file name, and changes the buffer name correspondingly. @code{set-visited-file-name} does not save the buffer in the newly visited file; it just alters the records inside Emacs in case you do save later. It also marks the -buffer as ``modified'' so that @kbd{C-x C-s} in that buffer +buffer as modified so that @kbd{C-x C-s} in that buffer @emph{will} save. @kindex C-x C-w @@ -590,8 +594,8 @@ directory. Emacs creates the directory, if necessary, to make the backup. @vindex make-backup-file-name-function - If you define the variable @code{make-backup-file-name-function} to -a suitable Lisp function, that overrides the usual way Emacs + If you set the variable @code{make-backup-file-name-function} to +a suitable Lisp function, you can override the usual way Emacs constructs backup file names. @node Backup Deletion @@ -748,9 +752,10 @@ file. @cindex locking files When you make the first modification in an Emacs buffer that is visiting a file, Emacs records that the file is @dfn{locked} by you. -(It does this by creating a specially-named symbolic link or regular -file with special contents in the same directory.) Emacs removes the -lock when you save the changes. The idea is that the file is locked +(It does this by creating a specially-named symbolic link@footnote{If +your file system does not support symbolic links, a regular file is +used.} with special contents in the same directory.) Emacs removes the lock +when you save the changes. The idea is that the file is locked whenever an Emacs buffer visiting it has unsaved changes. @vindex create-lockfiles @@ -897,7 +902,7 @@ way that, if the file was edited only slightly, you will be at approximately the same part of the text as before. But if you have made major changes, point may end up in a totally different location. - Reverting marks the buffer as ``not modified''. It also clears the + Reverting marks the buffer as not modified. It also clears the buffer's undo history (@pxref{Undo}). Thus, the reversion cannot be undone---if you change your mind yet again, you can't use the undo commands to bring the reverted changes back. @@ -1085,7 +1090,7 @@ of data with the command @kbd{M-x recover-file @key{RET} @var{file} restores the contents from its auto-save file @file{#@var{file}#}. You can then save with @kbd{C-x C-s} to put the recovered text into @var{file} itself. For example, to recover file @file{foo.c} from its -auto-save file @file{#foo.c#}, do:@refill +auto-save file @file{#foo.c#}, do: @example M-x recover-file @key{RET} foo.c @key{RET} @@ -1162,7 +1167,7 @@ implies the effect of @code{find-file-existing-other-name}. @cindex directory name abbreviation @vindex directory-abbrev-alist Sometimes, a directory is ordinarily accessed through a symbolic -link, and you may want Emacs to preferentially show its ``linked'' +link, and you may want Emacs to preferentially show its linked name. To do this, customize @code{directory-abbrev-alist}. Each element in this list should have the form @code{(@var{from} . @var{to})}, which means to replace @var{from} with @var{to} whenever @@ -1267,7 +1272,7 @@ minibuffer, and displays the differences between the two files in a buffer named @file{*diff*}. This works by running the @command{diff} program, using options taken from the variable @code{diff-switches}. The value of @code{diff-switches} should be a string; the default is -@code{"-c"} to specify a context diff. +@code{"-u"} to specify a unified context diff. @c Note that the actual name of the info file is diffutils.info, @c but it adds a dir entry for diff too. @c On older systems, only "info diff" works, not "info diffutils". @@ -1320,7 +1325,7 @@ prefix argument turns that off. You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor mode for editing output from the @command{diff3} program. This is typically the result of a failed merge from a version control system -``update'' outside VC, due to conflicting changes to a file. Smerge +update outside VC, due to conflicting changes to a file. Smerge mode provides commands to resolve conflicts by selecting specific changes. @@ -1359,11 +1364,11 @@ contents of the hunk. read-only, you need to make it writable first. @xref{Misc Buffer}.) Whenever you change a hunk, Diff mode attempts to automatically correct the line numbers in the hunk headers, to ensure that the patch -remains ``correct''. To disable automatic line number correction, +remains correct. To disable automatic line number correction, change the variable @code{diff-update-on-the-fly} to @code{nil}. - Diff mode treats each hunk as an ``error message'', similar to -Compilation mode. Thus, you can use commands such as @kbd{C-x '} to + Diff mode treats each hunk as an error message, similar to +Compilation mode. Thus, you can use commands such as @kbd{C-x `} to visit the corresponding source locations. @xref{Compilation Mode}. In addition, Diff mode provides the following commands to navigate, @@ -1415,6 +1420,7 @@ In a multi-file patch, kill the current file part. @item C-c C-a @findex diff-apply-hunk +@cindex patches, applying Apply this hunk to its target file (@code{diff-apply-hunk}). With a prefix argument of @kbd{C-u}, revert this hunk. @@ -1470,9 +1476,9 @@ unified format to context format. When the mark is active, convert only the text within the region. @item C-c C-w -@findex diff-refine-hunk -Refine the current hunk so that it disregards changes in whitespace -(@code{diff-refine-hunk}). +@findex diff-ignore-whitespace-hunk +Re-diff the current hunk, disregarding changes in whitespace +(@code{diff-ignore-whitespace-hunk}). @item C-x 4 A @findex diff-add-change-log-entries-other-window @@ -1563,10 +1569,11 @@ old meaning of the name @var{new} to be lost. If @var{old} and @var{new} are on different file systems, the file @var{old} is copied and deleted. If the argument @var{new} is just a directory name, the real new name is in that directory, with the same non-directory -component as @var{old}. For example, @kbd{M-x rename-file RET ~/foo -RET /tmp RET} renames @file{~/foo} to @file{/tmp/foo}. The same rule -applies to all the remaining commands in this section. All of them -ask for confirmation when the new file name already exists, too. +component as @var{old}. For example, @kbd{M-x rename-file @key{RET} +~/foo @key{RET} /tmp @key{RET}} renames @file{~/foo} to +@file{/tmp/foo}. The same rule applies to all the remaining commands +in this section. All of them ask for confirmation when the new file +name already exists, too. @ifnottex If a file is under version control (@pxref{Version Control}), you @@ -1578,7 +1585,7 @@ rename-file}. @xref{VC Delete/Rename}. @cindex hard links (creation) @kbd{M-x add-name-to-file} adds an additional name to an existing file without removing its old name. The new name is created as a -``hard link'' to the existing file. The new name must belong on the +hard link to the existing file. The new name must belong on the same file system that the file is on. On MS-Windows, this command works only if the file resides in an NTFS file system. On MS-DOS, it works by copying the file. @@ -1605,7 +1612,7 @@ mark (@pxref{Mark Ring}). @findex insert-file-literally @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, -except the file is inserted ``literally'': it is treated as a sequence +except the file is inserted literally: it is treated as a sequence of @acronym{ASCII} characters with no special encoding or conversion, similar to the @kbd{M-x find-file-literally} command (@pxref{Visiting}). @@ -1682,6 +1689,13 @@ likewise. @kbd{v} extracts a file into a buffer in View mode another window, so you could edit the file and operate on the archive simultaneously. + The @kbd{I} key adds a new (regular) file to the archive. The file +is initially empty, but can readily be edited using the commands +above. The command inserts the new file before the current one, so +that using it on the topmost line of the Tar buffer makes the new file +the first one in the archive, and using it at the end of the buffer +makes it the last one. + @kbd{d} marks a file for deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} renames a file within the archive. @@ -1731,7 +1745,8 @@ owner, are supported only for some of the archive formats. and repack archives. However, you don't need these programs to look at the archive table of contents, only to extract or manipulate the subfiles in the archive. Details of the program names and their -options can be set in the @samp{Archive} Customize group. +options can be set in the @samp{Archive} Customize group +(@pxref{Customization Groups}). @node Remote Files @section Remote Files @@ -1881,11 +1896,11 @@ then specifying @file{/tmp/foo*bar} will visit only @findex file-cache-minibuffer-complete You can use the @dfn{file name cache} to make it easy to locate a file by name, without having to remember exactly where it is located. -When typing a file name in the minibuffer, @kbd{C-@key{tab}} +When typing a file name in the minibuffer, @kbd{C-@key{TAB}} (@code{file-cache-minibuffer-complete}) completes it using the file -name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the +name cache. If you repeat @kbd{C-@key{TAB}}, that cycles through the possible completions of what you had originally typed. (However, note -that the @kbd{C-@key{tab}} character cannot be typed on most text +that the @kbd{C-@key{TAB}} character cannot be typed on most text terminals.) The file name cache does not fill up automatically. Instead, you @@ -1931,6 +1946,7 @@ opened files. @kbd{M-x recentf-save-list} saves the current @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} edits it. +@c FIXME partial-completion-mode (complete.el) is obsolete. The @kbd{M-x ffap} command generalizes @code{find-file} with more powerful heuristic defaults (@pxref{FFAP}), often based on the text at point. Partial Completion mode offers other features extending @@ -1939,10 +1955,9 @@ point. Partial Completion mode offers other features extending @findex image-mode @findex image-toggle-display -@findex image-toggle-animation +@findex image-next-file +@findex image-previous-file @cindex images, viewing -@cindex image animation -@cindex animated images Visiting image files automatically selects Image mode. In this major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display}) to toggle between displaying the file as an image in the Emacs buffer, @@ -1951,10 +1966,33 @@ Displaying the file as an image works only if Emacs is compiled with support for displaying such images. If the displayed image is wider or taller than the frame, the usual point motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts of the image to be -displayed. If the image can be animated, the command @kbd{RET} +displayed. You can press @kbd{n} (@code{image-next-file}) and @kbd{p} +(@code{image-previous-file}) to visit the next image file and the +previous image file in the same directory, respectively. + +@findex image-toggle-animation +@findex image-next-frame +@findex image-previous-frame +@findex image-goto-frame +@findex image-increase-speed +@findex image-decrease-speed +@findex image-reset-speed +@findex image-reverse-speed +@vindex image-animate-loop +@cindex image animation +@cindex animated images + If the image can be animated, the command @key{RET} (@code{image-toggle-animation}) starts or stops the animation. Animation plays once, unless the option @code{image-animate-loop} is -non-@code{nil}. +non-@code{nil}. With @kbd{f} (@code{image-next-frame}) and @kbd{b} +(@code{image-previous-frame}) you can step through the individual +frames. Both commands accept a numeric prefix to step through several +frames at once. You can go to a specific frame with @kbd{F} +(@code{image-goto-frame}). Frames are indexed from 1. Typing @kbd{a ++} (@code{image-increase-speed}) increases the speed of the animation, +@kbd{a -} (@code{image-decrease-speed}) decreases it, and @kbd{a r} +(@code{image-reverse-speed}) reverses it. The command @kbd{a 0} +(@code{image-reset-speed}) resets the speed to the original value. @cindex ImageMagick support @vindex imagemagick-enabled-types @@ -1970,7 +2008,7 @@ enable ImageMagick for all possible image types, change @code{imagemagick-types-inhibit} lists the image types which should never be rendered using ImageMagick, regardless of the value of @code{imagemagick-enabled-types} (the default list includes types like -@code{C} and @code{HTML}, which ImageMagick can render as an ``image'' +@code{C} and @code{HTML}, which ImageMagick can render as an image but Emacs should not). To disable ImageMagick entirely, change @code{imagemagick-types-inhibit} to @code{t}. @@ -1996,7 +2034,7 @@ adds a @samp{Filesets} menu to the menu bar. @findex filesets-remove-buffer The simplest way to define a fileset is by adding files to it one at a time. To add a file to fileset @var{name}, visit the file and type -@kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If +@kbd{M-x filesets-add-buffer @key{RET} @var{name} @key{RET}}. If there is no fileset @var{name}, this creates a new one, which initially contains only the current file. The command @kbd{M-x filesets-remove-buffer} removes the current file from a fileset. @@ -2017,7 +2055,7 @@ files in a fileset, and @kbd{M-x filesets-close} to close them. Use a fileset. These commands are also available from the @samp{Filesets} menu, where each existing fileset is represented by a submenu. - @xref{Version Control}, for a different concept of ``filesets'': + @xref{Version Control}, for a different concept of filesets: groups of files bundled together for version control operations. Filesets of that type are unnamed, and do not persist across Emacs sessions. diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index b6eb1ed11a2..993f0dce1cc 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Fixit @@ -78,6 +78,7 @@ the undo command. previous undo commands, use @kbd{M-x undo-only}. This is like @code{undo}, but will not redo changes you have just undone. +@c What about @kbd{M-x revert-buffer}? --xfq If you notice that a buffer has been modified accidentally, the easiest way to recover is to type @kbd{C-/} repeatedly until the stars disappear from the front of the mode line (@pxref{Mode Line}). @@ -190,7 +191,7 @@ point forward across three other characters. It would change @samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word before point backward across four words. @kbd{C-u - C-M-t} would cancel -the effect of plain @kbd{C-M-t}.@refill +the effect of plain @kbd{C-M-t}. A numeric argument of zero is assigned a special meaning (because otherwise a command with a repeat count of zero would do nothing): to @@ -216,7 +217,7 @@ Convert last word to lower case with capital initial. the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a special feature when used with a negative argument: they do not move the cursor. As soon as you see you have mistyped the last word, you can simply -case-convert it and go on typing. @xref{Case}.@refill +case-convert it and go on typing. @xref{Case}. @node Spelling @section Checking and Correcting Spelling @@ -285,7 +286,7 @@ messages. @xref{Sending Mail}. When one of these commands encounters what appears to be an incorrect word, it asks you what to do. It usually displays a list of -numbered ``near-misses''---words that are close to the incorrect word. +numbered @dfn{near-misses}---words that are close to the incorrect word. Then you must type a single-character response. Here are the valid responses: @@ -330,7 +331,7 @@ file. @item l @var{word} @key{RET} Look in the dictionary for words that match @var{word}. These words -become the new list of ``near-misses''; you can select one of them as +become the new list of near-misses; you can select one of them as the replacement by typing a digit. You can use @samp{*} in @var{word} as a wildcard. @@ -403,10 +404,17 @@ mode in the current buffer. To enable Flyspell mode in all text mode buffers, add @code{flyspell-mode} to @code{text-mode-hook}. @xref{Hooks}. +@findex flyspell-correct-word +@findex flyspell-auto-correct-word +@findex flyspell-correct-word-before-point When Flyspell mode highlights a word as misspelled, you can click on -it with @kbd{Mouse-2} to display a menu of possible corrections and -actions. You can also correct the word by editing it manually in any -way you like. +it with @kbd{Mouse-2} (@code{flyspell-correct-word}) to display a menu +of possible corrections and actions. In addition, @kbd{C-.} or +@kbd{@key{ESC}-@key{TAB}} (@code{flyspell-auto-correct-word}) will +propose various successive corrections for the word at point, and +@kbd{C-c $} (@code{flyspell-correct-word-before-point}) will pop up a +menu of possible corrections. Of course, you can always correct the +misspelled word by editing it manually in any way you like. @findex flyspell-prog-mode Flyspell Prog mode works just like ordinary Flyspell mode, except diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi index da618fc4841..870bfcd2169 100644 --- a/doc/emacs/fortran-xtra.texi +++ b/doc/emacs/fortran-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @@ -13,9 +13,9 @@ @cindex Fortran 77 and Fortran 90, 95, 2003, 2008 @findex f90-mode @findex fortran-mode - Fortran mode is meant for editing ``fixed form'' (and also ``tab -format'') source code (normally Fortran 77). For editing more modern -``free form'' source code (Fortran 90, 95, 2003, 2008), use F90 mode + Fortran mode is meant for editing fixed form (and also tab +format) source code (normally Fortran 77). For editing more modern +free-form source code (Fortran 90, 95, 2003, 2008), use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode for the extensions @samp{.f90}, @samp{.f95}, @samp{.f03} and @samp{.f08}. @@ -70,7 +70,7 @@ command runs the hook @code{fortran-mode-hook}. @subsection Motion Commands In addition to the normal commands for moving by and operating on -``defuns'' (Fortran subprograms---functions and subroutines, as well +defuns (Fortran subprograms---functions and subroutines, as well as modules for F90 mode, using the commands @code{fortran-end-of-subprogram} and @code{fortran-beginning-of-subprogram}), Fortran mode provides special commands to move by statements and other program units. @@ -207,8 +207,8 @@ the Fortran standard counts from 1.) The variable @code{fortran-continuation-string} specifies what character to put in column 5. A line that starts with a tab character followed by any digit except @samp{0} is also a continuation line. We call this style of -continuation @dfn{tab format}. (Fortran 90 introduced ``free form'', -with another style of continuation lines). +continuation @dfn{tab format}. (Fortran 90 introduced free-form +continuation lines.) @vindex indent-tabs-mode @r{(Fortran mode)} @vindex fortran-analyze-depth @@ -499,7 +499,7 @@ will confuse font-lock.) @table @kbd @item C-c C-r -Display a ``column ruler'' momentarily above the current line +Display a column ruler momentarily above the current line (@code{fortran-column-ruler}). @item C-c C-w Split the current window horizontally temporarily so that it is @@ -575,7 +575,7 @@ yourself. To use them, you must turn on Abbrev mode. semicolon. For example, one built-in Fortran abbrev is @samp{;c} for @samp{continue}. If you insert @samp{;c} and then insert a punctuation character such as a space or a newline, the @samp{;c} expands automatically -to @samp{continue}, provided Abbrev mode is enabled.@refill +to @samp{continue}, provided Abbrev mode is enabled. Type @samp{;?} or @samp{;C-h} to display a list of all the built-in Fortran abbrevs and what they stand for. diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 5365bdc6e03..95b721fa739 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Frames @@ -7,7 +7,7 @@ @cindex frames When Emacs is started on a graphical display, e.g., on the X Window -System, it occupies a graphical system-level ``window''. In this +System, it occupies a graphical system-level display region. In this manual, we call this a @dfn{frame}, reserving the word ``window'' for the part of the frame used for displaying a buffer. A frame initially contains one window, but it can be subdivided into multiple windows @@ -28,7 +28,7 @@ displays (@pxref{Exiting}). To close just the selected frame, type This chapter describes Emacs features specific to graphical displays (particularly mouse commands), and features for managing multiple frames. On text terminals, many of these features are unavailable. -However, it is still possible to create multiple ``frames'' on text +However, it is still possible to create multiple frames on text terminals; such frames are displayed one at a time, filling the entire terminal screen (@pxref{Non-Window Terminals}). It is also possible to use the mouse on some text terminals (@pxref{Text-Only Mouse}, for @@ -39,7 +39,7 @@ doing so on GNU and Unix systems; and @ifnottex @pxref{MS-DOS Mouse}, @end ifnottex -for doing so on MS-DOS). +for doing so on MS-DOS). Menus are supported on all text terminals. @menu * Mouse Commands:: Moving, cutting, and pasting, with the mouse. @@ -54,6 +54,7 @@ for doing so on MS-DOS). * Multiple Displays:: How one Emacs instance can talk to several displays. * Frame Parameters:: Changing the colors and other modes of frames. * Scroll Bars:: How to enable and disable scroll bars; how to use them. +* Window Dividers:: Window separators that can be dragged with the mouse. * Drag and Drop:: Using drag and drop to open files and insert text. * Menu Bars:: Enabling and disabling the menu bar. * Tool Bars:: Enabling and disabling the tool bar. @@ -109,7 +110,7 @@ the window and sets the cursor position. @cindex mouse, dragging @findex mouse-set-region - Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch + Holding down @kbd{Mouse-1} and dragging the mouse over a stretch of text activates the region around that text (@code{mouse-set-region}), placing the mark where you started holding down the mouse button, and point where you release it (@pxref{Mark}). @@ -136,7 +137,7 @@ the position where you clicked and inserts the contents of the primary selection (@code{mouse-yank-primary}). @xref{Primary Selection}. This behavior is consistent with other X applications. Alternatively, you can rebind @kbd{Mouse-2} to @code{mouse-yank-at-click}, which -performs a yank at point. +performs a yank at the position you click. @vindex mouse-yank-at-point If you change the variable @code{mouse-yank-at-point} to a @@ -216,7 +217,7 @@ also copied to the kill ring. @item Double-Mouse-1 Select the text around the word which you click on. -Double-clicking on a character with ``symbol'' syntax (such as +Double-clicking on a character with symbol syntax (such as underscore, in C mode) selects the symbol surrounding that character. Double-clicking on a character with open- or close-parenthesis syntax selects the parenthetical grouping which that character starts or @@ -328,6 +329,7 @@ instead of running the @code{mouse-save-then-kill} command, rebind @kbd{Mouse-3} by adding the following line to your init file (@pxref{Init Rebinding}): +@c FIXME: `mouse-popup-menubar-stuff' is obsolete since 23.1. @smallexample (global-set-key [mouse-3] 'mouse-popup-menubar-stuff) @end smallexample @@ -376,6 +378,9 @@ position (@pxref{Split Window}). between two side-by-side mode lines, you can move the vertical boundary to the left or right. + Note that resizing windows is affected by the value of +@code{window-resize-pixelwise}, see @ref{Split Window}. + @node Creating Frames @section Creating Frames @cindex creating frames @@ -384,7 +389,7 @@ boundary to the left or right. The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}. Whereas each @kbd{C-x 4} command pops up a buffer in a different window in the selected frame (@pxref{Pop Up Window}), the @kbd{C-x 5} commands use a -different frame. If an existing visible or iconified (``minimized'') +different frame. If an existing visible or iconified (a.k.a.@: ``minimized'') frame already displays the requested buffer, that frame is raised and deiconified (``un-minimized''); otherwise, a new frame is created on the current display terminal. @@ -408,8 +413,8 @@ Select a Dired buffer for directory @var{directory} in another frame. This runs @code{dired-other-frame}. @xref{Dired}. @item C-x 5 m Start composing a mail message in another frame. This runs -@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. -@xref{Sending Mail}. +@code{compose-mail-other-frame}. It is the other-frame variant of +@kbd{C-x m}. @xref{Sending Mail}. @item C-x 5 . Find a tag in the current tag table in another frame. This runs @code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. @@ -440,7 +445,7 @@ error if there is only one frame. @item C-z @kindex C-z @r{(X windows)} @findex suspend-frame -Minimize (or ``iconify) the selected Emacs frame +Minimize (or iconify) the selected Emacs frame (@code{suspend-frame}). @xref{Exiting}. @item C-x 5 o @@ -453,13 +458,35 @@ cycles through all the frames on your terminal. @kindex C-x 5 1 @findex delete-other-frames Delete all frames on the current terminal, except the selected one. + +@item M-<F10> +@kindex M-<F10> +@findex toggle-frame-maximized +Toggle the maximization state of the current frame. When a frame is +maximized, it fills the screen. + +@item <F11> +@kindex <F11> +@findex toggle-frame-fullscreen +Toggle full-screen mode for the current frame. (The difference +between full-screen and maximized is normally that the former +hides window manager decorations, giving slightly more screen space to +Emacs itself.) @end table +@vindex frame-resize-pixelwise + Note that with some window managers you may have to customize the +variable @code{frame-resize-pixelwise} to a non-@code{nil} value in +order to make a frame truly maximized or full-screen. This +variable, when set to a non-@code{nil} value, in general allows +resizing frames at pixel resolution, rather than in integral multiples +of lines and columns. + The @kbd{C-x 5 0} (@code{delete-frame}) command deletes the selected frame. However, it will refuse to delete the last frame in an Emacs session, to prevent you from losing the ability to interact with the Emacs session. Note that when Emacs is run as a daemon (@pxref{Emacs -Server}), there is always a ``virtual frame'' that remains after all +Server}), there is always a virtual frame that remains after all the ordinary, interactive frames are deleted. In this case, @kbd{C-x 5 0} can delete the last interactive frame; you can use @command{emacsclient} to reconnect to the Emacs session. @@ -484,13 +511,14 @@ the mouse cursor to the chosen frame. @cindex fonts By default, Emacs displays text on graphical displays using a -12-point monospace font. There are several different ways to specify +10-point monospace font. There are several different ways to specify a different font: @itemize @item -Click on @samp{Set Default Font} in the @samp{Options} menu. To save -this for future sessions, click on @samp{Save Options} in the +Click on @samp{Set Default Font} in the @samp{Options} menu. This +makes the selected font the default on all existing graphical frames. +To save this for future sessions, click on @samp{Save Options} in the @samp{Options} menu. @item @@ -503,6 +531,10 @@ Add a line to your init file, modifying the variable '(font . "DejaVu Sans Mono-10")) @end example +@noindent +This makes the font the default on all graphical frames created after +restarting Emacs with that init file. + @cindex X defaults file @cindex X resources file @item @@ -534,7 +566,7 @@ command can be helpful. It describes the character at point, and names the font that it's rendered in. @cindex fontconfig - On X, there are four different ways to express a ``font name''. The + On X, there are four different ways to express a font name. The first is to use a @dfn{Fontconfig pattern}. Fontconfig patterns have the following form: @@ -543,7 +575,7 @@ the following form: @end example @noindent -Within this format, any of the elements in braces may be omitted. +Within this format, any of the elements in brackets may be omitted. Here, @var{fontname} is the @dfn{family name} of the font, such as @samp{Monospace} or @samp{DejaVu Sans Mono}; @var{fontsize} is the @dfn{point size} of the font (one @dfn{printer's point} is about 1/72 @@ -673,7 +705,10 @@ The font width---normally @samp{normal}, @samp{condensed}, other values. @item style An optional additional style name. Usually it is empty---most XLFDs -have two hyphens in a row at this point. +have two hyphens in a row at this point. The style name can also +specify a two-letter ISO-639 language name, like @samp{ja} or +@samp{ko}; some fonts that support CJK scripts have that spelled out +in the style name part. @item pixels The font height, in pixels. @item height @@ -704,8 +739,8 @@ have. Normally you should use @samp{iso8859} for @var{registry} and @samp{1} for @var{encoding}. @end table - The fourth and final method of specifying a font is to use a ``font -nickname''. Certain fonts have shorter nicknames, which you can use + The fourth and final method of specifying a font is to use a font +nickname. Certain fonts have shorter nicknames, which you can use instead of a normal font specification. For instance, @samp{6x13} is equivalent to @@ -792,8 +827,8 @@ When a file or directory is expanded, the @samp{[+]} changes to hiding its contents. You navigate through the speedbar using the keyboard, too. Typing -@kbd{RET} while point is on a line in the speedbar is equivalent to -clicking the item on the current line, and @kbd{SPC} expands or +@key{RET} while point is on a line in the speedbar is equivalent to +clicking the item on the current line, and @key{SPC} expands or contracts the item. @kbd{U} displays the parent directory of the current directory. To copy, delete, or rename the file on the current line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a @@ -881,10 +916,11 @@ those are drawn by the toolkit and not directly by Emacs. @section Scroll Bars @cindex Scroll Bar mode @cindex mode, Scroll Bar +@cindex Vertical Scroll Bar - On graphical displays, there is a @dfn{scroll bar} on the side of -each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's up and -down buttons scrolls the window by one line at a time. Clicking + On graphical displays, there is a @dfn{vertical scroll bar} on the +side of each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's +up and down buttons scrolls the window by one line at a time. Clicking @kbd{Mouse-1} above or below the scroll bar's inner box scrolls the window by nearly the entire height of the window, like @kbd{M-v} and @kbd{C-v} respectively (@pxref{Moving Point}). Dragging the inner box @@ -898,28 +934,104 @@ in the scroll bar lets you drag the inner box up and down. @findex scroll-bar-mode @findex toggle-scroll-bar - To toggle the use of scroll bars, type @kbd{M-x scroll-bar-mode}. -This command applies to all frames, including frames yet to be -created. To toggle scroll bars for just the selected frame, use the -command @kbd{M-x toggle-scroll-bar}. + To toggle the use of vertical scroll bars, type @kbd{M-x +scroll-bar-mode}. This command applies to all frames, including frames +yet to be created. To toggle vertical scroll bars for just the selected +frame, use the command @kbd{M-x toggle-scroll-bar}. @vindex scroll-bar-mode - To control the use of scroll bars at startup, customize the variable -@code{scroll-bar-mode}. Its value should be either @code{right} (put -scroll bars on the right side of windows), @code{left} (put them on -the left), or @code{nil} (disable scroll bars). By default, Emacs -puts scroll bars on the right if it was compiled with GTK+ support on -the X Window System, and on MS-Windows or Mac OS; Emacs puts scroll -bars on the left if compiled on the X Window System without GTK+ -support (following the old convention for X applications). + To control the use of vertical scroll bars at startup, customize the +variable @code{scroll-bar-mode}. Its value should be either +@code{right} (put scroll bars on the right side of windows), @code{left} +(put them on the left), or @code{nil} (disable vertical scroll bars). +By default, Emacs puts scroll bars on the right if it was compiled with +GTK+ support on the X Window System, and on MS-Windows or Mac OS; Emacs +puts scroll bars on the left if compiled on the X Window System without +GTK+ support (following the old convention for X applications). @vindex scroll-bar-width -@cindex width of the scroll bar +@cindex width of the vertical scroll bar You can also use the X resource @samp{verticalScrollBars} to enable or disable the scroll bars (@pxref{Resources}). To control the scroll bar width, change the @code{scroll-bar-width} frame parameter (@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). +@vindex scroll-bar-adjust-thumb-portion +@cindex overscrolling +If you're using Emacs on X (with GTK+ or Motif), you can customize the +variable @code{scroll-bar-adjust-thumb-portion} to control +@dfn{overscrolling} of the scroll bar, i.e., dragging the thumb down even +when the end of the buffer is visible. If its value is +non-@code{nil}, the scroll bar can be dragged downwards even if the +end of the buffer is shown; if @code{nil}, the thumb will be at the +bottom when the end of the buffer is shown. You can not over-scroll +when the entire buffer is visible. + +@cindex scroll-bar face + The visual appearance of the scroll bars is controlled by the +@code{scroll-bar} face. + +@cindex Horizontal Scroll Bar +@cindex Horizontal Scroll Bar mode + On graphical displays with toolkit support, Emacs may also supply a +@dfn{horizontal scroll bar} on the bottom of each window. Clicking +@kbd{Mouse-1} on the that scroll bar's left and right buttons scrolls +the window horizontally by one column at a time. Clicking @kbd{Mouse-1} +on the left or right of the scroll bar's inner box scrolls the window by +four columns. Dragging the inner box scrolls the window continuously. + + Note that such horizontal scrolling can make the window's position of +point disappear on the left or the right. Typing a character to insert +text or moving point with a keyboard command will usually bring it back +into view. + +@findex horizontal-scroll-bar-mode + To toggle the use of horizontal scroll bars, type @kbd{M-x +horizontal-scroll-bar-mode}. This command applies to all frames, +including frames yet to be created. To toggle horizontal scroll bars +for just the selected frame, use the command @kbd{M-x +toggle-horizontal-scroll-bar}. + +@vindex horizontal-scroll-bar-mode + To control the use of horizontal scroll bars at startup, customize the +variable @code{horizontal-scroll-bar-mode}. + +@vindex scroll-bar-height +@cindex height of the horizontal scroll bar + You can also use the X resource @samp{horizontalScrollBars} to enable +or disable horizontal scroll bars (@pxref{Resources}). To control the +scroll bar height, change the @code{scroll-bar-height} frame parameter +(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). + +@node Window Dividers +@section Window Dividers +@cindex Window Divider mode +@cindex mode, Window Divider + + On graphical displays, you can use @dfn{window dividers} in order to +separate windows visually. Window dividers are bars that can be dragged +with the mouse, thus allowing to easily resize adjacent windows. + +@findex window-divider-mode + To toggle the display of window dividers, use the command @kbd{M-x +window-divider-mode}. + +@vindex window-divider-default-places + To customize where dividers should appear, use the option +@code{window-divider-default-places}. Its value should be either +@code{bottom-only} (to show dividers only on the bottom of windows), +@code{right-only} (to show dividers only on the right of windows), or +@code{t} (to show them on the bottom and on the right). + +@vindex window-divider-default-bottom-width +@vindex window-divider-default-right-width + To adjust the width of window dividers displayed by this mode +customize the options @code{window-divider-default-bottom-width} and +@code{window-divider-default-right-width}. + + For more details about window dividers see @ref{Window Dividers,, +Window Dividers, elisp, The Emacs Lisp Reference Manual}. + @node Drag and Drop @section Drag and Drop @cindex drag and drop @@ -1027,8 +1139,8 @@ suppressed all dialog boxes with the variable @code{use-dialog-box}. @vindex x-gtk-file-dialog-help-text @cindex hidden files, in GTK+ file chooser @cindex help text, in GTK+ file chooser - When Emacs is compiled with GTK+ support, it uses the GTK+ ``file -chooser'' dialog. Emacs adds an additional toggle button to this + When Emacs is compiled with GTK+ support, it uses the GTK+ file +chooser dialog. Emacs adds an additional toggle button to this dialog, which you can use to enable or disable the display of hidden files (files starting with a dot) in that dialog. If you want this toggle to be activated by default, change the variable diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index e4693a5293f..e66cd79e740 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Glossary @@ -26,10 +26,10 @@ When the mark is active, we call the region an active region. @item Alt Alt is the name of a modifier bit that a keyboard input character may -have. To make a character Alt, type it while holding down the @key{ALT} -key. Such characters are given names that start with @kbd{Alt-} +have. To make a character Alt, type it while holding down the @key{Alt} +key. Such characters are given names that start with @kbd{@key{Alt}-} (usually written @kbd{A-} for short). (Note that many terminals have a -key labeled @key{ALT} that is really a @key{META} key.) @xref{User +key labeled @key{Alt} that is really a @key{META} key.) @xref{User Input, Alt}. @item Argument @@ -60,7 +60,7 @@ be preserved if the buffer is lost due to a system error or user error. @item Autoloading Emacs can automatically load Lisp libraries when a Lisp program requests a -function from those libraries. This is called `autoloading'. +function from those libraries. This is called ``autoloading''. @xref{Lisp Libraries}. @item Backtrace @@ -100,7 +100,7 @@ A base buffer is a buffer whose text is shared by an indirect buffer Some human languages, such as English, are written from left to right. Others, such as Arabic, are written from right to left. Emacs supports both of these forms, as well as any mixture of them---this -is `bidirectional text'. @xref{Bidirectional Editing}. +is ``bidirectional text''. @xref{Bidirectional Editing}. @item Bind To bind a key sequence means to give it a binding (q.v.). @@ -135,7 +135,7 @@ X}). Borders are not the same as fringes (q.v.). @item Buffer The buffer is the basic editing unit; one buffer corresponds to one text being edited. You normally have several buffers, but at any time you are -editing only one, the `current buffer', though several can be visible +editing only one, the current buffer, though several can be visible when you are using multiple windows or frames (q.v.). Most buffers are visiting (q.v.@:) some file. @xref{Buffers}. @@ -256,7 +256,7 @@ abbreviation for a name into the entire name. Completion is done for minibuffer (q.v.@:) arguments when the set of possible valid inputs is known; for example, on command names, buffer names, and file names. Completion usually occurs when @key{TAB}, @key{SPC} or -@key{RET} is typed. @xref{Completion}.@refill +@key{RET} is typed. @xref{Completion}. @anchor{Glossary---Continuation Line} @item Continuation Line @@ -265,12 +265,12 @@ normally (but see @ref{Glossary---Truncation}) takes up more than one screen line when displayed. We say that the text line is continued, and all screen lines used for it after the first are called continuation lines. @xref{Continuation Lines}. A related Emacs feature is -`filling' (q.v.). +filling (q.v.). @item Control Character A control character is a character that you type by holding down the -@key{CTRL} key. Some control characters also have their own keys, so -that you can type them without using @key{CTRL}. For example, +@key{Ctrl} key. Some control characters also have their own keys, so +that you can type them without using @key{Ctrl}. For example, @key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control characters. @xref{User Input}. @@ -284,8 +284,8 @@ around to empower users and encourage them to cooperate. The particular form of copyleft used by the GNU project is called the GNU General Public License. @xref{Copying}. -@item @key{CTRL} -The @key{CTRL} or ``control'' key is what you hold down +@item @key{Ctrl} +The @key{Ctrl} or control key is what you hold down in order to enter a control character (q.v.). @xref{Glossary---C-}. @item Current Buffer @@ -310,8 +310,8 @@ between defuns, the current defun is the one that follows point. The cursor is the rectangle on the screen which indicates the position (called point; q.v.@:) at which insertion and deletion takes place. The cursor is on or under the character that follows point. Often -people speak of `the cursor' when, strictly speaking, they mean -`point'. @xref{Point,Cursor}. +people speak of ``the cursor'' when, strictly speaking, they mean +``point''. @xref{Point,Cursor}. @item Customization Customization is making minor changes in the way Emacs works, to @@ -351,12 +351,12 @@ it is interpreted relative to the current buffer's default directory. @item Defun A defun is a major definition at the top level in a program. The name -`defun' comes from Lisp, where most such definitions use the construct +``defun'' comes from Lisp, where most such definitions use the construct @code{defun}. @xref{Defuns}. @item @key{DEL} @key{DEL} is a character that runs the command to delete one character -of text before the cursor. It is typically either the @key{DELETE} +of text before the cursor. It is typically either the @key{Delete} key or the @key{BACKSPACE} key, whichever one is easy to type. @xref{Erasing,DEL}. @@ -367,8 +367,8 @@ Deletion means erasing text without copying it into the kill ring @anchor{Glossary---Deletion of Files} @item Deletion of Files Deleting a file means erasing it from the file system. -(Note that some systems use the concept of a ``trash can'', or ``recycle -bin'', to allow you to ``undelete'' files.) +(Note that some systems use the concept of a trash can, or recycle +bin, to allow you to undelete files.) @xref{Misc File Ops,Misc File Ops,Miscellaneous File Operations}. @item Deletion of Messages @@ -405,7 +405,7 @@ confirmation. The usual reason for disabling a command is that it is confusing for beginning users. @xref{Disabling}. @item Down Event -Short for `button down event' (q.v.). +Short for ``button down event'' (q.v.). @item Drag Event A drag event is the kind of input event (q.v.@:) generated when you @@ -598,7 +598,7 @@ correspond to any character. @xref{Function Keys}. @item Global Global means ``independent of the current environment; in effect throughout Emacs''. It is the opposite of local (q.v.). Particular -examples of the use of `global' appear below. +examples of the use of ``global'' appear below. @item Global Abbrev A global definition of an abbrev (q.v.@:) is effective in all major @@ -687,7 +687,7 @@ changing any of its code. @xref{Hooks}. @item Hyper Hyper is the name of a modifier bit that a keyboard input character may have. To make a character Hyper, type it while holding down the -@key{HYPER} key. Such characters are given names that start with +@key{Hyper} key. Such characters are given names that start with @kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input}. @item Iff @@ -824,8 +824,8 @@ lists. @xref{Moving by Parens}. @item Local Local means ``in effect only in a particular context''; the relevant kind of context is a particular function execution, a particular -buffer, or a particular major mode. It is the opposite of `global' -(q.v.). Specific uses of `local' in Emacs terminology appear below. +buffer, or a particular major mode. It is the opposite of ``global'' +(q.v.). Specific uses of ``local'' in Emacs terminology appear below. @item Local Abbrev A local abbrev definition is effective only if a particular major mode @@ -842,13 +842,13 @@ A local value of a variable (q.v.@:) applies to only one buffer. @xref{Locals}. @item @kbd{M-} -@kbd{M-} in the name of a character is an abbreviation for @key{META}, +@kbd{M-} in the name of a character is an abbreviation for @key{Meta}, one of the modifier keys that can accompany any character. @xref{User Input,M-}. @item @kbd{M-C-} @kbd{M-C-} in the name of a character is an abbreviation for -Control-Meta; it means the same thing as `@kbd{C-M-}' (q.v.). +Control-Meta; it means the same thing as @kbd{C-M-} (q.v.). @item @kbd{M-x} @kbd{M-x} is the key sequence that is used to call an Emacs command by @@ -900,16 +900,16 @@ a keyboard interface to navigate it. @xref{Menu Bars}. @item Meta Meta is the name of a modifier bit which you can use in a command -character. To enter a meta character, you hold down the @key{META} +character. To enter a meta character, you hold down the @key{Meta} key while typing the character. We refer to such characters with names that start with @kbd{Meta-} (usually written @kbd{M-} for -short). For example, @kbd{M-<} is typed by holding down @key{META} +short). For example, @kbd{M-<} is typed by holding down @key{Meta} and at the same time typing @kbd{<} (which itself is done, on most terminals, by holding down @key{SHIFT} and typing @kbd{,}). @xref{User Input,Meta}. -On some terminals, the @key{META} key is actually labeled @key{ALT} -or @key{EDIT}. +On some terminals, the @key{Meta} key is actually labeled @key{Alt} +or @key{Edit}. @item Meta Character A Meta character is one whose character code includes the Meta bit. @@ -953,9 +953,15 @@ another. The usual way to move text is by killing (q.v.@:) it and then yanking (q.v.@:) it. @xref{Killing}. @item MULE -MULE refers to the Emacs features for editing multilingual -non-@acronym{ASCII} text using multibyte characters (q.v.). -@xref{International}. +@cindex MULE +Prior to Emacs 23, @acronym{MULE} was the name of a software package +which provided a @dfn{MULtilingual Enhancement} to Emacs, by adding +support for multiple character sets (q.v.). @acronym{MULE} was later +integrated into Emacs, and much of it was replaced when Emacs gained +internal Unicode support in version 23. + +Some parts of Emacs that deal with character set support still use the +@acronym{MULE} name. @xref{International}. @item Multibyte Character A multibyte character is a character that takes up several bytes in a @@ -1070,7 +1076,7 @@ command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. Quoting means depriving a character of its usual special significance. The most common kind of quoting in Emacs is with @kbd{C-q}. What constitutes special significance depends on the context and on -convention. For example, an ``ordinary'' character as an Emacs command +convention. For example, an ordinary character as an Emacs command inserts itself; so in this context, a special character is any character that does not normally insert itself (such as @key{DEL}, for example), and quoting it makes it insert itself as if it were not special. Not @@ -1115,7 +1121,7 @@ Many commands operate on the text of the region. @xref{Mark,Region}. @item Register Registers are named slots in which text, buffer positions, or rectangles can be saved for later use. @xref{Registers}. A related -Emacs feature is `bookmarks' (q.v.). +Emacs feature is bookmarks (q.v.). @anchor{Glossary---Regular Expression} @item Regular Expression @@ -1227,15 +1233,15 @@ Emacs has commands for moving by or killing by sentences. @anchor{Glossary---Server} @item Server -Within Emacs, you can start a `server' process, which listens for -connections from `clients'. This offers a faster alternative to +Within Emacs, you can start a ``server'' process, which listens for +connections from ``clients''. This offers a faster alternative to starting several Emacs instances. @xref{Emacs Server}, and @ref{Glossary---Daemon}. @c This is only covered in the lispref, not the user manual. @ignore @item Session Manager -Some window systems (q.v.@:) provide a tool called a `session manager'. +Some window systems (q.v.@:) provide a tool called a ``session manager''. This offers the ability to save your windows when you log off, and restore them after you log in again. @end ignore @@ -1244,7 +1250,7 @@ and restore them after you log in again. A sexp (short for ``s-expression'') is the basic syntactic unit of Lisp in its textual form: either a list, or Lisp atom. Sexps are also the balanced expressions (q.v.@:) of the Lisp language; this is why -the commands for editing balanced expressions have `sexp' in their +the commands for editing balanced expressions have @samp{sexp} in their name. @xref{Expressions,Sexps}. @item Simultaneous Editing @@ -1321,7 +1327,7 @@ Emacs does not make a termscript file unless you tell it to. @xref{Bugs}. @item Text -`Text' has two meanings (@pxref{Text}): +``Text'' has two meanings (@pxref{Text}): @itemize @bullet @item @@ -1414,7 +1420,7 @@ that you can customize Emacs by setting it to a new value. @item Variable A variable is an object in Lisp that can store an arbitrary value. Emacs uses some variables for internal purposes, and has others (known -as `user options'; q.v.@:) just so that you can set their values to +as ``user options''; q.v.@:) just so that you can set their values to control the behavior of Emacs. The variables used in Emacs that you are likely to be interested in are listed in the Variables Index in this manual (@pxref{Variable Index}). @xref{Variables}, for @@ -1442,7 +1448,7 @@ Emacs divides a frame (q.v.@:) into one or more windows, each of which can display the contents of one buffer (q.v.@:) at any time. @xref{Screen}, for basic information on how Emacs uses the screen. @xref{Windows}, for commands to control the use of windows. Some -other editors use the term ``window'' for what we call a `frame' +other editors use the term ``window'' for what we call a ``frame'' (q.v.@:) in Emacs. @item Window System diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi index 1e829a3244f..3c23b9c6048 100644 --- a/doc/emacs/gnu.texi +++ b/doc/emacs/gnu.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1985-1987, 1993, 1995, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993, 1995, 2001-2015 Free Software @c Foundation, Inc. @c @c Permission is granted to anyone to make or distribute verbatim copies @@ -83,7 +83,7 @@ memory, because they are the easiest machines to make it run on. The extra effort to make it run on smaller machines will be left to someone who wants to use it on them. -To avoid horrible confusion, please pronounce the `G' in the word `GNU' +To avoid horrible confusion, please pronounce the ``G'' in the word ``GNU'' when it is the name of this project. @unnumberedsec Why I Must Write GNU diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index e41d68a5f51..a9c63b91785 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Help @@ -55,11 +55,12 @@ This displays the available Emacs packages based on keywords. @xref{Package Keywords}. @end table - @kbd{C-h} or @key{F1} means ``help'' in various other contexts as + @kbd{C-h} or @key{F1} mean ``help'' in various other contexts as well. For instance, you can type them after a prefix key to view a -list of the keys that can follow the prefix key. (A few prefix keys -don't support @kbd{C-h} in this way, because they define other -meanings for it, but they all support @key{F1} for help.) +list of the keys that can follow the prefix key. (You can also use +@kbd{?} in this context. A few prefix keys don't support @kbd{C-h} +or @kbd{?} in this way, because they define other meanings for those +inputs, but they all support @key{F1}.) @menu * Help Summary:: Brief list of all Help commands. @@ -71,7 +72,7 @@ meanings for it, but they all support @key{F1} for help.) * Language Help:: Help relating to international language support. * Misc Help:: Other help commands. * Help Files:: Commands to display auxiliary help files. -* Help Echo:: Help on active text and tooltips ("balloon help"). +* Help Echo:: Help on active text and tooltips (``balloon help''). @end menu @iftex @@ -121,14 +122,15 @@ Display the name and documentation of the command that @var{key} runs Display a description of your last 300 keystrokes (@code{view-lossage}). @item C-h m -Display documentation of the current major mode (@code{describe-mode}). +Display documentation of the current major mode and minor modes +(@code{describe-mode}). @item C-h n Display news of recent Emacs changes (@code{view-emacs-news}). @item C-h p Find packages by topic keyword (@code{finder-by-keyword}). This lists packages using a package menu buffer. @xref{Packages}. @item C-h P @var{package} @key{RET} -Display documentation about the package named @var{package} +Display documentation about the specified package (@code{describe-package}). @item C-h r Display the Emacs manual in Info (@code{info-emacs-manual}). @@ -357,8 +359,11 @@ view, describe, default. @end quotation @vindex apropos-do-all - If the variable @code{apropos-do-all} is non-@code{nil}, the apropos -commands always behave as if they had been given a prefix argument. + If the variable @code{apropos-do-all} is non-@code{nil}, most +apropos commands behave as if they had been given a prefix argument. +There is one exception: @code{apropos-variable} without a prefix +argument will always search for all variables, no matter what the +value of @code{apropos-do-all} is. @vindex apropos-sort-by-scores @cindex apropos search results, order by score @@ -376,8 +381,9 @@ alphabetical order, change the variable @section Help Mode Commands Help buffers provide the same commands as View mode (@pxref{View -Mode}); for instance, @key{SPC} scrolls forward, and @key{DEL} scrolls -backward. A few special commands are also provided: +Mode}); for instance, @key{SPC} scrolls forward, and @key{DEL} or +@kbd{S-@key{SPC}} scrolls backward. A few special commands are also +provided: @table @kbd @item @key{RET} @@ -456,7 +462,9 @@ buffer (@pxref{Package Menu}). @kindex C-h P @kbd{C-h P} (@code{describe-package}) prompts for the name of a package, and displays a help buffer describing the attributes of the -package and the features that it implements. +package and the features that it implements. The buffer lists the +keywords that relate to the package in the form of buttons. Click on +a button to see other packages related to that keyword. @node Language Help @section Help for International Language Support @@ -486,8 +494,7 @@ currently in use. @xref{Coding Systems}. @kindex C-h i @findex info @cindex Info -@cindex manuals, on-line -@cindex on-line manuals +@cindex manuals, included @kbd{C-h i} (@code{info}) runs the Info program, which browses structured documentation files. The entire Emacs manual is available within Info, along with many other manuals for the GNU system. Type @@ -549,11 +556,13 @@ Emacs Lisp Reference Manual}). @findex describe-prefix-bindings You can get a list of subcommands for a particular prefix key by -typing @kbd{C-h} (@code{describe-prefix-bindings}) after the prefix -key. (There are a few prefix keys for which this does not -work---those that provide their own bindings for @kbd{C-h}. One of -these is @key{ESC}, because @kbd{@key{ESC} C-h} is actually -@kbd{C-M-h}, which marks a defun.) +typing @kbd{C-h}, @kbd{?}, or @key{F1} +(@code{describe-prefix-bindings}) after the prefix key. (There are a +few prefix keys for which not all of these keys work---those that +provide their own bindings for that key. One of these prefix keys +is @key{ESC}, because @kbd{@key{ESC} C-h} is actually @kbd{C-M-h}, +which marks a defun. However, @kbd{@key{ESC} @key{F1}} and +@kbd{@key{ESC} ?} work fine.) @node Help Files @section Help Files @@ -599,12 +608,13 @@ Display information about where to get external packages @item C-h C-f Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). @item C-h g -Display information about the GNU Project (@code{describe-gnu-project}). +Visit a @uref{http://www.gnu.org} page with information about the GNU +Project (@code{describe-gnu-project}). @item C-h C-m Display information about ordering printed copies of Emacs manuals (@code{view-order-manuals}). @item C-h C-n -Display the ``news'' file, which lists the new features in this +Display the news, which lists the new features in this version of Emacs (@code{view-emacs-news}). @item C-h C-o Display how to order or download the latest version of @@ -624,7 +634,8 @@ Emacs (@code{describe-no-warranty}). @cindex tooltips @cindex balloon help - In Emacs, stretches of ``active text'' (text that does something +@cindex active text + In Emacs, stretches of @dfn{active text} (text that does something special in response to mouse clicks or @key{RET}) often have associated help text. This includes hyperlinks in Emacs buffers, as well as parts of the mode line. On graphical displays, as well as diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi index 72ec68812ce..76dfa55211d 100644 --- a/doc/emacs/indent.texi +++ b/doc/emacs/indent.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Indentation @@ -35,7 +35,7 @@ mode and related major modes, @key{TAB} normally inserts some combination of space and tab characters to advance point to the next tab stop (@pxref{Tab Stops}). For this purpose, the position of the first non-whitespace character on the preceding line is treated as an -additional tab stop, so you can use @key{TAB} to ``align'' point with +additional tab stop, so you can use @key{TAB} to align point with the preceding line. If the region is active (@pxref{Using Region}), @key{TAB} acts specially: it indents each line in the region so that its first non-whitespace character is aligned with the preceding line. @@ -64,11 +64,6 @@ Emacs provides a variety of commands to perform indentation in other ways. @table @kbd -@item C-j -@kindex C-j -@findex newline-and-indent -Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). - @item C-M-o @kindex C-M-o @findex split-line @@ -103,7 +98,7 @@ argument, in which case do nothing. @kindex M-^ @findex delete-indentation Merge the previous and the current line (@code{delete-indentation}). -This ``joins'' the two lines cleanly, by replacing any indentation at +This joins the two lines cleanly, by replacing any indentation at the front of the current line, together with the line boundary, with a single space. @@ -127,14 +122,26 @@ that column number. @kindex C-x TAB @findex indent-rigidly @cindex remove indentation -Shift each line in the region by a fixed distance, to the right or -left (@code{indent-rigidly}). The distance to move is determined by -the numeric argument (positive to move rightward, negative to move -leftward). - -This command can be used to remove all indentation from the lines in -the region, by invoking it with a large negative argument, -e.g., @kbd{C-u -1000 C-x @key{TAB}}. +This command is used to change the indentation of all lines that begin +in the region, moving the affected lines as a rigid unit. + +If called with no argument, the command activates a transient mode for +adjusting the indentation of the affected lines interactively. While +this transient mode is active, typing @key{LEFT} or @key{RIGHT} +indents leftward and rightward, respectively, by one space. You can +also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to indent leftward +or rightward to the next tab stop (@pxref{Tab Stops}). Typing any +other key disables the transient mode, and resumes normal editing. + +If called with a prefix argument @var{n}, this command indents the +lines forward by @var{n} spaces (without enabling the transient mode). +Negative values of @var{n} indent backward, so you can remove all +indentation from the lines in the region using a large negative +argument, like this: + +@smallexample +C-u -999 C-x @key{TAB} +@end smallexample @end table @node Tab Stops @@ -145,10 +152,12 @@ e.g., @kbd{C-u -1000 C-x @key{TAB}}. Emacs defines certain column numbers to be @dfn{tab stops}. These are used as stopping points by @key{TAB} when inserting whitespace in Text mode and related modes (@pxref{Indentation}), and by commands -like @kbd{M-i} (@pxref{Indentation Commands}). By default, tab stops -are located every 8 columns. These positions are stored in the -variable @code{tab-stop-list}, whose value is a list of column numbers -in increasing order. +like @kbd{M-i} (@pxref{Indentation Commands}). The variable +@code{tab-stop-list} controls these positions. The default value is +@code{nil}, which means a tab stop every 8 columns. The value can +also be a list of zero-based column numbers (in increasing order) at +which to place tab stops. Emacs extends the list forever by repeating +the difference between the last and next-to-last elements. @findex edit-tab-stops @kindex C-c C-c @r{(Edit Tab Stops)} @@ -167,10 +176,14 @@ To install changes, type C-c C-c @noindent The first line contains a colon at each tab stop. The numbers on the next two lines are present just to indicate where the colons are. +If the value of @code{tab-stop-list} is @code{nil}, as it is by default, +no colons are displayed initially. You can edit this buffer to specify different tab stops by placing colons on the desired columns. The buffer uses Overwrite mode -(@pxref{Minor Modes}). When you are done, type @kbd{C-c C-c} to make +(@pxref{Minor Modes}). Remember that Emacs will extend the list of +tab stops forever by repeating the difference between the last two +explicit stops that you place. When you are done, type @kbd{C-c C-c} to make the new tab stops take effect. Normally, the new tab stop settings apply to all buffers. However, if you have made the @code{tab-stop-list} variable local to the buffer where you called @@ -185,7 +198,7 @@ are always displayed as empty spaces extending to the next @dfn{display tab stop}. @xref{Text Display}. @node Just Spaces -@section Tabs vs. Spaces +@section Tabs vs.@: Spaces @vindex tab-width Normally, indentation commands insert (or remove) an optimal mix of @@ -236,5 +249,7 @@ indentation; otherwise, it inserts a tab character. @cindex mode, Electric Indent @findex electric-indent-mode Electric Indent mode is a global minor mode that automatically -indents the line after every @key{RET} you type. To toggle this minor -mode, type @kbd{M-x electric-indent-mode}. +indents the line after every @key{RET} you type. This mode is enabled +by default. To toggle this minor mode, type @kbd{M-x +electric-indent-mode}. To toggle the mode in a single buffer, +use @kbd{M-x electric-indent-local-mode}. diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index cb33327faa1..d453647b0c5 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @@ -78,7 +78,7 @@ erase just one character or only whitespace. @table @kbd @item @key{DEL} -@itemx @key{Backspace} +@itemx @key{BACKSPACE} Delete the previous character, or the text in the region if it is active (@code{delete-backward-char}). @@ -105,16 +105,15 @@ indentation following it (@code{delete-indentation}). (@code{delete-backward-char}), @key{delete} (@code{delete-forward-char}), and @kbd{C-d} (@code{delete-char}). @xref{Erasing}. With a numeric argument, they delete the specified -number of characters. If the numeric argument is omitted or one, they -delete all the text in the region if it is active (@pxref{Using -Region}). +number of characters. If the numeric argument is omitted or one, +@key{DEL} and @key{delete} delete all the text in the region if it is +active (@pxref{Using Region}). -@c FIXME: `cycle-spacing' should be documented, too. (Maybe not in -@c this node, tho.) --xfq @kindex M-\ @findex delete-horizontal-space @kindex M-SPC @findex just-one-space +@findex cycle-spacing The other delete commands are those that delete only whitespace characters: spaces, tabs and newlines. @kbd{M-\} (@code{delete-horizontal-space}) deletes all the spaces and tab @@ -125,7 +124,11 @@ point, regardless of the number of spaces that existed previously (even if there were none before). With a numeric argument @var{n}, it leaves @var{n} spaces before point if @var{n} is positive; if @var{n} is negative, it deletes newlines in addition to spaces and tabs, -leaving @var{-n} spaces before point. +leaving @var{-n} spaces before point. The command @code{cycle-spacing} +acts like a more flexible version of @code{just-one-space}. It +does different things if you call it repeatedly in succession. +The first call acts like @code{just-one-space}, the next removes +all whitespace, and a third call restores the original whitespace. @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after the current line. If the current line is blank, it deletes all @@ -136,6 +139,17 @@ the current line). On a solitary blank line, it deletes that line. previous line, by deleting a newline and all surrounding spaces, usually leaving a single space. @xref{Indentation,M-^}. +@c Not really sure where to put this... +@findex delete-duplicate-lines + The command @code{delete-duplicate-lines} searches the region for +identical lines, and removes all but one copy of each. Normally it +keeps the first instance of each repeated line, but with a @kbd{C-u} +prefix argument it keeps the last. With a @kbd{C-u C-u} prefix +argument, it only searches for adjacent identical lines. This is a +more efficient mode of operation, useful when the lines have already +been sorted. With a @kbd{C-u C-u C-u} prefix argument, it retains +repeated blank lines. + @node Killing by Lines @subsection Killing by Lines @@ -344,34 +358,34 @@ So, to recover the text of the next-to-the-last kill, first use with the previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another @kbd{M-y}. - You can understand @kbd{M-y} in terms of a ``last yank'' pointer which -points at an entry in the kill ring. Each time you kill, the ``last -yank'' pointer moves to the newly made entry at the front of the ring. -@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. -@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the + You can understand @kbd{M-y} in terms of a last-yank pointer which +points at an entry in the kill ring. Each time you kill, the last-yank +pointer moves to the newly made entry at the front of the ring. +@kbd{C-y} yanks the entry which the last-yank pointer points to. +@kbd{M-y} moves the last-yank pointer to a different entry, and the text in the buffer changes to match. Enough @kbd{M-y} commands can move the pointer to any entry in the ring, so you can get any entry into the buffer. Eventually the pointer reaches the end of the ring; the next @kbd{M-y} loops back around to the first entry again. - @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does + @kbd{M-y} moves the last-yank pointer around the ring, but it does not change the order of the entries in the ring, which always runs from the most recent kill at the front to the oldest one still remembered. @kbd{M-y} can take a numeric argument, which tells it how many entries -to advance the ``last yank'' pointer by. A negative argument moves the +to advance the last-yank pointer by. A negative argument moves the pointer toward the front of the ring; from the front of the ring, it -moves ``around'' to the last entry and continues forward from there. +moves around to the last entry and continues forward from there. Once the text you are looking for is brought into the buffer, you can stop doing @kbd{M-y} commands and it will stay there. It's just a copy of the kill ring entry, so editing it in the buffer does not change -what's in the ring. As long as no new killing is done, the ``last -yank'' pointer remains at the same place in the kill ring, so repeating +what's in the ring. As long as no new killing is done, the last-yank +pointer remains at the same place in the kill ring, so repeating @kbd{C-y} will yank another copy of the same previous kill. When you call @kbd{C-y} with a numeric argument, that also sets the -``last yank'' pointer to the entry that it yanks. +last-yank pointer to the entry that it yanks. @node Appending Kills @subsection Appending Kills @@ -417,13 +431,15 @@ killed it. @kindex C-M-w @findex append-next-kill If a kill command is separated from the last kill command by other -commands (not just numeric arguments), it starts a new entry on the kill -ring. But you can force it to append by first typing the command -@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} -tells the following command, if it is a kill command, to append the text -it kills to the last killed text, instead of starting a new entry. With -@kbd{C-M-w}, you can kill several separated pieces of text and -accumulate them to be yanked back in one place.@refill +commands (not just numeric arguments), it starts a new entry on the +kill ring. But you can force it to combine with the last killed text, +by typing @kbd{C-M-w} (@code{append-next-kill}) right beforehand. The +@kbd{C-M-w} tells its following command, if it is a kill command, to +treat the kill as part of the sequence of previous kills. As usual, +the kill is appended to the previous killed text if the command kills +forward, and prepended if the command kills backward. In this way, +you can kill several separated pieces of text and accumulate them to +be yanked back in one place. A kill command following @kbd{M-w} (@code{kill-ring-save}) does not append to the text that @kbd{M-w} copied into the kill ring. @@ -530,9 +546,9 @@ containing the last stretch of text selected in an X application (usually by dragging the mouse). Typically, this text can be inserted into other X applications by @kbd{mouse-2} clicks. The primary selection is separate from the clipboard. Its contents are more -``fragile''; they are overwritten each time you select text with the -mouse, whereas the clipboard is only overwritten by explicit ``cut'' -or ``copy'' commands. +fragile; they are overwritten each time you select text with the +mouse, whereas the clipboard is only overwritten by explicit cut +or copy commands. Under X, whenever the region is active (@pxref{Mark}), the text in the region is saved in the primary selection. This applies regardless @@ -572,6 +588,7 @@ you can access it using the following Emacs commands: @table @kbd @findex mouse-set-secondary @kindex M-Drag-Mouse-1 +@cindex secondary-selection face @item M-Drag-Mouse-1 Set the secondary selection, with one end at the place where you press down the button, and the other end at the place where you release it @@ -710,9 +727,9 @@ rectangle, depending on the command that uses them. @table @kbd @item C-x r k Kill the text of the region-rectangle, saving its contents as the -``last killed rectangle'' (@code{kill-rectangle}). +last killed rectangle (@code{kill-rectangle}). @item C-x r M-w -Save the text of the region-rectangle as the ``last killed rectangle'' +Save the text of the region-rectangle as the last killed rectangle (@code{copy-rectangle-as-kill}). @item C-x r d Delete the text of the region-rectangle (@code{delete-rectangle}). @@ -738,6 +755,10 @@ Replace rectangle contents with @var{string} on each line (@code{string-rectangle}). @item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} Insert @var{string} on each line of the rectangle. +@item C-x @key{SPC} +Toggle Rectangle Mark mode (@code{rectangle-mark-mode}). +When this mode is active, the region-rectangle is highlighted and can +be shrunk/grown, and the standard kill and yank commands operate on it. @end table The rectangle operations fall into two classes: commands to erase or @@ -755,7 +776,7 @@ region-rectangle is like erasing the specified text on each line of the rectangle; if there is any following text on the line, it moves backwards to fill the gap. - ``Killing'' a rectangle is not killing in the usual sense; the + Killing a rectangle is not killing in the usual sense; the rectangle is not stored in the kill ring, but in a special place that only records the most recent rectangle killed. This is because yanking a rectangle is so different from yanking linear text that @@ -765,8 +786,8 @@ for rectangles. @kindex C-x r M-w @findex copy-rectangle-as-kill @kbd{C-x r M-w} (@code{copy-rectangle-as-kill}) is the equivalent of -@kbd{M-w} for rectangles: it records the rectangle as the ``last -killed rectangle'', without deleting the text from the buffer. +@kbd{M-w} for rectangles: it records the rectangle as the last +killed rectangle, without deleting the text from the buffer. @kindex C-x r y @findex yank-rectangle @@ -823,6 +844,15 @@ rectangle shifts right. @code{string-rectangle}, but inserts the string on each line, shifting the original text to the right. +@findex rectangle-mark-mode + The command @kbd{C-x @key{SPC}} (@code{rectangle-mark-mode}) toggles +whether the region-rectangle or the standard region is highlighted +(first activating the region if necessary). When this mode is enabled, +commands that resize the region (@kbd{C-f}, @kbd{C-n} etc.)@: do +so in a rectangular fashion, and killing and yanking operate on the +rectangle. @xref{Killing}. The mode persists only as long as the +region is active. + @node CUA Bindings @section CUA Bindings @findex cua-mode @@ -850,18 +880,23 @@ the prefix key twice, e.g., @kbd{C-x C-x C-f}. while retaining the other features of CUA mode described below, set the variable @code{cua-enable-cua-keys} to @code{nil}. - In CUA mode, typed text replaces the active region as in -Delete-Selection mode (@pxref{Mouse Commands}). + CUA mode by default activates Delete-Selection mode (@pxref{Mouse Commands}) +so that typed text replaces the active region. To use CUA without this +behavior, set the variable @code{cua-delete-selection} to @code{nil}. @cindex rectangle highlighting CUA mode provides enhanced rectangle support with visible -rectangle highlighting. Use @kbd{C-RET} to start a rectangle, +rectangle highlighting. Use @kbd{C-@key{RET}} to start a rectangle, extend it using the movement commands, and cut or copy it using -@kbd{C-x} or @kbd{C-c}. @kbd{RET} moves the cursor to the next +@kbd{C-x} or @kbd{C-c}. @key{RET} moves the cursor to the next (clockwise) corner of the rectangle, so you can easily expand it in any direction. Normal text you type is inserted to the left or right of each line in the rectangle (on the same side as the cursor). + You can use this rectangle support without activating CUA by calling the +@code{cua-rectangle-mark-mode} command. But see also the standard +@code{rectangle-mark-mode}. @xref{Rectangles}. + With CUA you can easily copy text and rectangles into and out of registers by providing a one-digit numeric prefix to the kill, copy, and yank commands, e.g., @kbd{C-1 C-c} copies the region into register @@ -869,7 +904,7 @@ and yank commands, e.g., @kbd{C-1 C-c} copies the region into register @cindex global mark CUA mode also has a global mark feature which allows easy moving and -copying of text between buffers. Use @kbd{C-S-SPC} to toggle the +copying of text between buffers. Use @kbd{C-S-@key{SPC}} to toggle the global mark on and off. When the global mark is on, all text that you kill or copy is automatically inserted at the global mark, and text you type is inserted at the global mark rather than at the current diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi index aa4d10ef324..2cbcc8b3d54 100644 --- a/doc/emacs/kmacro.texi +++ b/doc/emacs/kmacro.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Keyboard Macros @@ -194,9 +194,9 @@ C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d @end example @noindent -will rotate the keyboard macro ring to the ``second previous'' macro, +will rotate the keyboard macro ring to the second-previous macro, execute the resulting head macro three times, rotate back to the -original head macro, execute that once, rotate to the ``previous'' +original head macro, execute that once, rotate to the previous macro, execute that, and finally delete it from the macro ring. @findex kmacro-end-or-call-macro-repeat @@ -224,8 +224,8 @@ immediately by repeating just @kbd{C-n} and @kbd{C-p} until the desired macro is at the head of the ring. To execute the new macro ring head immediately, just type @kbd{C-k}. - Note that Emacs treats the head of the macro ring as the ``last -defined keyboard macro''. For instance, @key{F4} will execute that + Note that Emacs treats the head of the macro ring as the last +defined keyboard macro. For instance, @key{F4} will execute that macro, and @kbd{C-x C-k n} will give it a name. @vindex kmacro-ring-max @@ -506,7 +506,7 @@ keyboard input that you would use to invoke the macro---@kbd{C-x e} or @findex kmacro-step-edit-macro @kindex C-x C-k SPC You can interactively replay and edit the last keyboard -macro, one command at a time, by typing @kbd{C-x C-k SPC} +macro, one command at a time, by typing @kbd{C-x C-k @key{SPC}} (@code{kmacro-step-edit-macro}). Unless you quit the macro using @kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the macro ring. @@ -518,15 +518,15 @@ options. These actions are available: @itemize @bullet{} @item -@kbd{SPC} and @kbd{y} execute the current command, and advance to the +@key{SPC} and @kbd{y} execute the current command, and advance to the next command in the keyboard macro. @item -@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command. +@kbd{n}, @kbd{d}, and @key{DEL} skip and delete the current command. @item @kbd{f} skips the current command in this execution of the keyboard macro, but doesn't delete it from the macro. @item -@kbd{@key{TAB}} executes the current command, as well as all similar +@key{TAB} executes the current command, as well as all similar commands immediately following the current command; for example, @key{TAB} may be used to insert a sequence of characters (corresponding to a sequence of @code{self-insert-command} commands). @@ -542,31 +542,31 @@ with the edited macro. @kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; discarding any changes made to the keyboard macro. @item -@kbd{i KEY... C-j} reads and executes a series of key sequences (not +@kbd{i @var{key}@dots{} C-j} reads and executes a series of key sequences (not including the final @kbd{C-j}), and inserts them before the current command in the keyboard macro, without advancing over the current command. @item -@kbd{I KEY...} reads one key sequence, executes it, and inserts it +@kbd{I @var{key}@dots{}} reads one key sequence, executes it, and inserts it before the current command in the keyboard macro, without advancing over the current command. @item -@kbd{r KEY... C-j} reads and executes a series of key sequences (not +@kbd{r @var{key}@dots{} C-j} reads and executes a series of key sequences (not including the final @kbd{C-j}), and replaces the current command in the keyboard macro with them, advancing over the inserted key sequences. @item -@kbd{R KEY...} reads one key sequence, executes it, and replaces the +@kbd{R @var{key}@dots{}} reads one key sequence, executes it, and replaces the current command in the keyboard macro with that key sequence, advancing over the inserted key sequence. @item -@kbd{a KEY... C-j} executes the current command, then reads and +@kbd{a @var{key}@dots{} C-j} executes the current command, then reads and executes a series of key sequences (not including the final @kbd{C-j}), and inserts them after the current command in the keyboard macro; it then advances over the current command and the inserted key sequences. @item -@kbd{A KEY... C-j} executes the rest of the commands in the keyboard +@kbd{A @var{key}@dots{} C-j} executes the rest of the commands in the keyboard macro, then reads and executes a series of key sequences (not including the final @kbd{C-j}), and appends them at the end of the keyboard macro; it then terminates the step-editing and replaces the diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index 3faa2c88b2d..c9ae559f984 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node M-x diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index 50a7ea2c335..c04682586ce 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2000-2013 Free Software Foundation, Inc. +@c Copyright (C) 2000-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Mac OS / GNUstep @appendix Emacs and Mac OS / GNUstep @@ -12,7 +12,7 @@ the GNUstep libraries on GNU/Linux or other operating systems, or on Mac OS X with native window system support. On Mac OS X, Emacs can be built either without window system support, with X11, or with the Cocoa interface; this section only applies to the Cocoa build. This -does not support versions of Mac OS X earlier than 10.4. +does not support versions of Mac OS X earlier than 10.6. For various historical and technical reasons, Emacs uses the term @samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for @@ -66,7 +66,7 @@ file names. On GNUstep, in an X-windows environment you need to use @kbd{Cmd-c} instead of one of the @kbd{C-w} or @kbd{M-w} commands to transfer text to the X primary selection; otherwise, Emacs will use the -``clipboard'' selection. Likewise, @kbd{Cmd-y} (instead of @kbd{C-y}) +clipboard selection. Likewise, @kbd{Cmd-y} (instead of @kbd{C-y}) yanks from the X primary selection instead of the kill-ring or clipboard. @@ -84,15 +84,16 @@ set, which often causes the subprocesses it launches to behave differently than they would when launched from the shell. For the PATH and MANPATH variables, a system-wide method -of setting PATH is recommended on Mac OS X 10.5 and later, using the +of setting PATH is recommended on Mac OS X, using the @file{/etc/paths} files and the @file{/etc/paths.d} directory. @node Mac / GNUstep Customization @section Mac / GNUstep Customization -Emacs can be customized in several ways in addition to the standard -customization buffers and the Options menu. - +There are a few customization options that are specific to the +Nextstep port. For example, they affect things such as the modifier +keys and the fullscreen behavior. To see all such options, use +@kbd{M-x customize-group @key{RET} ns @key{RET}}. @subsection Font and Color Panels @@ -116,25 +117,23 @@ close the altered one. Useful in this context is the listing of all faces obtained by @kbd{M-x list-faces-display}. -@subsection Customization options specific to Mac OS / GNUstep - -The following customization options are specific to the Nextstep port. +@cindex Core Text, on Mac OS X +In Mac OS X, Emacs uses a Core Text based font backend +by default. If you prefer the older font style, enter the following +at the command-line before starting Emacs: -@table @code -@item ns-auto-hide-menu-bar -Non-nil means the menu-bar is hidden by default, but appears if you -move the mouse pointer over it. (Requires Mac OS X 10.6 or later.) - -@end table +@example +% defaults write org.gnu.Emacs FontBackend ns +@end example @node Mac / GNUstep Events @section Windowing System Events under Mac OS / GNUstep Nextstep applications receive a number of special events which have -no X equivalent. These are sent as specially defined ``keys'', which +no X equivalent. These are sent as specially defined key events, which do not correspond to any sequence of keystrokes. Under Emacs, these -``key'' events can be bound to functions just like ordinary +key events can be bound to functions just like ordinary keystrokes. Here is a list of these events. @table @key @@ -191,7 +190,7 @@ font are stored in the variables @code{ns-input-font} and @item ns-power-off This event occurs when the user logs out and Emacs is still running, or when -`Quit Emacs' is chosen from the application menu. +``Quit Emacs'' is chosen from the application menu. The default behavior is to save all file-visiting buffers. @end table diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 553375442d5..a571ea7ed67 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Maintaining @@ -8,7 +8,7 @@ This chapter describes Emacs features for maintaining large programs. If you are maintaining a large Lisp program, then in addition to the features described here, you may find -the @file{ERT} (``Emacs Lisp Regression Testing'') library useful +the Emacs Lisp Regression Testing (ERT) library useful (@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}). @menu @@ -31,11 +31,11 @@ versions of a source file, storing information such as the creation time of each version, who made it, and a description of what was changed. - The Emacs version control interface is called @dfn{VC}@. VC commands -work with several different version control systems; currently, it -supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, + The Emacs version control interface is called @dfn{VC}@. VC +commands work with several different version control systems; +currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS, -Arch, RCS, and Bazaar. +RCS, and Bazaar. VC is enabled automatically whenever you visit a file governed by a version control system. To disable VC entirely, set the customizable @@ -163,14 +163,6 @@ similar to CVS but without its problems (e.g., it supports atomic commits of filesets, and versioning of directories, symbolic links, meta-data, renames, copies, and deletes). -@cindex GNU Arch -@cindex Arch -@item -GNU Arch is one of the earliest @dfn{decentralized} version control -systems (the other being Monotone). @xref{VCS Concepts}, for a -description of decentralized version control systems. It is no longer -under active development, and has been deprecated in favor of Bazaar. - @cindex git @item Git is a decentralized version control system originally invented by @@ -191,6 +183,18 @@ exception of repository sync operations. Bazaar (bzr) is a decentralized version control system that supports both repository-based and decentralized versioning. VC supports most basic editing operations under Bazaar. + +@cindex SRC +@cindex src +@item +SRC (src) is RCS, reloaded - a specialized version-control system +designed for single-file projects worked on by only one person. It +allows multiple files with independent version-control histories to +exist in one directory, and is thus particularly well suited for +maintaining small documents, scripts, and dotfiles. While it uses RCS +for revision storage, it presents a modern user interface featuring +lockless operation and integer sequential version numbers. VC +supports almost all SRC operations. @end itemize @node VCS Concepts @@ -268,8 +272,8 @@ number and severity of conflicts that actually occur. SCCS always uses locking. RCS is lock-based by default but can be told to operate in a merging style. CVS and Subversion are merge-based by default but can be told to operate in a locking mode. -Decentralized version control systems, such as GNU Arch, Git, and -Mercurial, are exclusively merging-based. +Decentralized version control systems, such as Git and Mercurial, are +exclusively merging-based. VC mode supports both locking and merging version control. The terms ``commit'' and ``update'' are used in newer version control @@ -391,7 +395,7 @@ instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. to the master repository. On a graphical display, you can move the mouse over this mode line -indicator to pop up a ``tool-tip'', which displays a more verbose +indicator to pop up a tool-tip, which displays a more verbose description of the version control status. Pressing @kbd{Mouse-1} over the indicator pops up a menu of VC commands, identical to @samp{Tools / Version Control} on the menu bar. @@ -437,14 +441,14 @@ VC fileset. @findex vc-next-action @kindex C-x v v The principal VC command is a multi-purpose command, @kbd{C-x v v} -(@code{vc-next-action}), which performs the ``most appropriate'' +(@code{vc-next-action}), which performs the most appropriate action on the current VC fileset: either registering it with a version control system, or committing it, or unlocking it, or merging changes into it. The precise actions are described in detail in the following subsections. You can use @kbd{C-x v v} either in a file-visiting buffer or in a VC Directory buffer. - Note that VC filesets are distinct from the ``named filesets'' used + Note that VC filesets are distinct from the named filesets used for viewing and visiting files in functional groups (@pxref{Filesets}). Unlike named filesets, VC filesets are not named and don't persist across sessions. @@ -465,8 +469,8 @@ and don't persist across sessions. @item If there is more than one file in the VC fileset and the files have inconsistent version control statuses, signal an error. (Note, -however, that a fileset is allowed to include both ``newly-added'' -files and ``modified'' files; @pxref{Registering}.) +however, that a fileset is allowed to include both newly-added +files and modified files; @pxref{Registering}.) @item If none of the files in the VC fileset are registered with a version @@ -487,10 +491,10 @@ commit. @xref{Log Buffer}. If committing to a shared repository, the commit may fail if the repository that has been changed since your last update. In that case, you must perform an update before trying again. On a -decentralized version control system, use @kbd{C-x v +} (@pxref{VC -Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version -control system, type @kbd{C-x v v} again to merge in the repository -changes. +decentralized version control system, use @kbd{C-x v +} +(@pxref{Pulling / Pushing}) or @kbd{C-x v m} (@pxref{Merging}). +On a centralized version control system, type @kbd{C-x v v} again to +merge in the repository changes. @item Finally, if you are using a centralized version control system, check @@ -498,7 +502,7 @@ if each work file in the VC fileset is up-to-date. If any file has been changed in the repository, offer to update it. @end itemize - These rules also apply when you use RCS in its ``non-locking'' mode, + These rules also apply when you use RCS in its non-locking mode, except that changes are not automatically merged from the repository. Nothing informs you if another user has committed changes in the same file since you began editing it; when you commit your revision, his @@ -543,7 +547,7 @@ the lock and make the file read-only again. @item If each file is locked by another user, ask whether you want to -``steal the lock''. If you say yes, the file becomes locked by you, +steal the lock. If you say yes, the file becomes locked by you, and a warning message is sent to the user who had formerly locked the file. @end itemize @@ -578,11 +582,11 @@ If the fileset is unmodified (and unlocked), this checks the specified revision into the working tree. You can also specify a revision on another branch by giving its revision or branch ID (@pxref{Switching Branches}). An empty argument (i.e., @kbd{C-u C-x v v @key{RET}}) -checks out the latest (``head'') revision on the current branch. +checks out the latest (head) revision on the current branch. -This signals an error on a decentralized version control system. +This is silently ignored on a decentralized version control system. Those systems do not let you specify your own revision IDs, nor do -they use the concept of ``checking out'' individual files. +they use the concept of checking out individual files. @end itemize @node Log Buffer @@ -599,6 +603,7 @@ the buffer and commit the change, together with your log entry. @cindex Log Edit mode @cindex mode, Log Edit @vindex vc-log-mode-hook +@c FIXME: Mention log-edit-mode-hook here? --xfq The major mode for the @file{*vc-log*} buffer is Log Edit mode, a variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode, Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} @@ -629,7 +634,7 @@ support it, the header is treated as part of the log entry. @findex log-edit-show-files @kindex C-c C-d @r{(Log Edit mode)} @findex log-edit-show-diff - While in the @file{*vc-log*} buffer, the ``current VC fileset'' is + While in the @file{*vc-log*} buffer, the current VC fileset is considered to be the fileset that will be committed if you type @w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset, type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff @@ -652,7 +657,7 @@ opposite way of working---generating ChangeLog entries from the Log Edit buffer. @end ifnottex - To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that + To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that buffer. You can switch buffers and do other editing. As long as you don't try to make another commit, the entry you were editing remains in the @file{*vc-log*} buffer, and you can go back to that buffer at @@ -705,7 +710,7 @@ under, it prompts for a repository type, creates a new repository, and registers the file into that repository. On most version control systems, registering a file with @kbd{C-x v -i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the +i} or @kbd{C-x v v} adds it to the working tree but not to the repository. Such files are labeled as @samp{added} in the VC Directory buffer, and show a revision ID of @samp{@@@@} in the mode line. To make the registration take effect in the repository, you @@ -819,8 +824,8 @@ window. @kindex C-x v g Many version control systems allow you to view files @dfn{annotated} with per-line revision information, by typing @kbd{C-x v g} -(@code{vc-annotate}). This creates a new buffer (the ``annotate -buffer'') displaying the file's text, with each line colored to show +(@code{vc-annotate}). This creates a new ``annotate'' buffer +displaying the file's text, with each line colored to show how old it is. Red text is new, blue is old, and intermediate colors indicate intermediate ages. By default, the color is scaled over the full range of ages, such that the oldest changes are blue, and the @@ -831,7 +836,7 @@ arguments using the minibuffer: the revision to display and annotate (instead of the current file contents), and the time span in days the color range should cover. - From the annotate buffer, these and other color scaling options are + From the ``annotate'' buffer, these and other color scaling options are available from the @samp{VC-Annotate} menu. In this buffer, you can also use the following keys to browse the annotations of past revisions, view diffs, or view log entries: @@ -896,11 +901,11 @@ Display the change history for the current repository (@code{vc-print-root-log}). @item C-x v I -Display the changes that a pull operation will retrieve +Display the changes that a ``pull'' operation will retrieve (@code{vc-log-incoming}). @item C-x v O -Display the changes that will be sent by the next push operation +Display the changes that will be sent by the next ``push'' operation (@code{vc-log-outgoing}). @end table @@ -936,13 +941,13 @@ revision at point. A second @key{RET} hides it again. On a decentralized version control system, the @kbd{C-x v I} (@code{vc-log-incoming}) command displays a log buffer showing the changes that will be applied, the next time you run the version -control system's ``pull'' command to get new revisions from another -repository (@pxref{VC Pull}). This other repository is the default +control system's pull command to get new revisions from another +repository (@pxref{Pulling / Pushing}). This other repository is the default one from which changes are pulled, as defined by the version control system; with a prefix argument, @code{vc-log-incoming} prompts for a specific repository. Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows the changes that will be sent to -another repository, the next time you run the ``push'' command; with a +another repository, the next time you run the push command; with a prefix argument, it prompts for a specific destination repository. In the @file{*vc-change-log*} buffer, you can use the following keys @@ -1013,8 +1018,6 @@ Revert the work file(s) in the current VC fileset to the last revision (@code{vc-revert}). @end table -@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific. - @kindex C-x v u @findex vc-revert @vindex vc-revert-show-diff @@ -1043,12 +1046,14 @@ Ignore a file under current version control system. (@code{vc-ignore}). @kindex C-x v G @findex vc-ignore - Many source trees contain some files that do not need to be versioned, -such as editor backups, object or bytecode files, and built programs. -You can simply not add them, but then they’ll always crop up as -unknown files. You can also tell the version control system to ignore -these files by adding them to the ignore file at the top of the tree. -@kbd{C-x v G} (@code{vc-ignore}) can help you do this. + Many source trees contain some files that do not need to be +versioned, such as editor backups, object or bytecode files, and built +programs. You can simply not add them, but then they'll always crop +up as unknown files. You can also tell the version control system to +ignore these files by adding them to the ignore file at the top of the +tree. @kbd{C-x v G} (@code{vc-ignore}) can help you do this. When +called with a prefix argument, you can remove a file from the ignored +file list. @node VC Directory Mode @subsection VC Directory Mode @@ -1099,7 +1104,7 @@ PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}. The VC Directory buffer contains a list of version-controlled files and their version control statuses. It lists files in the current directory (the one specified when you called @kbd{C-x v d}) and its -subdirectories, but only those with a ``noteworthy'' status. Files +subdirectories, but only those with a noteworthy status. Files that are up-to-date (i.e., the same as in the repository) are omitted. If all the files in a subdirectory are up-to-date, the subdirectory is not listed either. As an exception, if a file has @@ -1164,7 +1169,7 @@ directories that are used internally by version control systems. @subsubsection VC Directory Commands Emacs provides several commands for navigating the VC Directory -buffer, and for ``marking'' files as belonging to the current VC +buffer, and for marking files as belonging to the current VC fileset. @table @kbd @@ -1240,7 +1245,7 @@ Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}). The VC Directory buffer also defines some single-key shortcuts for VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l}, -@kbd{i}, @kbd{D}, @kbd{L}, @kbd{G} and @kbd{v}. +@kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I} and @kbd{v}. For example, you can commit a set of edited files by opening a VC Directory buffer, where the files are listed with the @samp{edited} @@ -1286,8 +1291,8 @@ bring them back at a later time). One use of version control is to support multiple independent lines of development, which are called @dfn{branches}. Amongst other -things, branches can be used for maintaining separate ``stable'' and -``development'' versions of a program, and for developing unrelated +things, branches can be used for maintaining separate stable and +development versions of a program, and for developing unrelated features in isolation from one another. VC's support for branch operations is currently fairly limited. For @@ -1300,7 +1305,7 @@ different branches. @menu * Switching Branches:: How to get to another existing branch. -* VC Pull:: Updating the contents of a branch. +* Pulling / Pushing:: Receiving/sending changes from/to elsewhere. * Merging:: Transferring changes between branches. * Creating Branches:: How to start a new branch. @end menu @@ -1314,11 +1319,18 @@ implemented, and these differences cannot be entirely concealed by VC. On some decentralized version control systems, including Bazaar and Mercurial in its normal mode of operation, each branch has its own working directory tree, so switching between branches just involves -switching directories. On Git, switching between branches is done -using the @command{git branch} command, which changes the contents of -the working tree itself. - - On centralized version control systems, you can switch between +switching directories. On Git, branches are normally @dfn{co-located} +in the same directory, and switching between branches is done using +the @command{git checkout} command, which changes the contents of the +working tree to match the branch you switch to. Bazaar also supports +co-located branches, in which case the @command{bzr switch} command +will switch branches in the current directory. With Subversion, you +switch to another branch using the @command{svn switch} command. + + The VC command to switch to another branch in the current directory +is @kbd{C-x v r @var{branch-name} @key{RET}} (@code{vc-retrieve-tag}). + + On centralized version control systems, you can also switch between branches by typing @kbd{C-u C-x v v} in an up-to-date work file (@pxref{Advanced C-x v v}), and entering the revision ID for a revision on another branch. On CVS, for instance, revisions on the @@ -1337,8 +1349,8 @@ unlocks (write-protects) the working tree. branch until you switch away; for instance, any VC filesets that you commit will be committed to that specific branch. -@node VC Pull -@subsubsection Pulling Changes into a Branch +@node Pulling / Pushing +@subsubsection Pulling/Pushing Changes into/from a Branch @table @kbd @item C-x v + @@ -1347,6 +1359,11 @@ by ``pulling in'' changes from another location. On a centralized version control system, update the current VC fileset. + +@item C-x v P +On a decentralized version control system, ``push'' changes from the +current branch to another location. This concept does not exist +for centralized version control systems. @end table @kindex C-x v + @@ -1376,6 +1393,21 @@ Log}. On a centralized version control system like CVS, @kbd{C-x v +} updates the current VC fileset from the repository. +@kindex C-x v P +@findex vc-push + On a decentralized version control system, the command @kbd{C-x v P} +(@code{vc-push}) sends changes from your current branch to another location. +With a prefix argument, the command prompts for the exact +version control command to use, which lets you specify where to push +changes. Otherwise, it pushes to a default location determined +by the version control system. + + Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing}) +to view a log buffer of the changes to be sent. @xref{VC Change Log}. + +This command is currently supported only by Bazaar, Git, and Mercurial. +It signals an error for centralized version control systems. + @node Merging @subsubsection Merging Branches @cindex merging changes @@ -1464,9 +1496,11 @@ different revision with @kbd{C-u C-x v v}. @cindex change log Many software projects keep a @dfn{change log}. This is a file, normally named @file{ChangeLog}, containing a chronological record of -when and how the program was changed. Sometimes, there are several -change log files, each recording the changes in one directory or -directory tree. +when and how the program was changed. Sometimes, these files are +automatically generated from the change log entries stored in version +control systems, or are used to generate these change log entries. +Sometimes, there are several change log files, each recording the +changes in one directory or directory tree. @menu * Change Log Commands:: Commands for editing change log files. @@ -1556,7 +1590,7 @@ dated in May 1993, with two items and one item respectively. @smallexample 1993-05-25 Richard Stallman <rms@@gnu.org> - * man.el: Rename symbols `man-*' to `Man-*'. + * man.el: Rename symbols 'man-*' to 'Man-*'. (manual-entry): Make prompt string clearer. * simple.el (blink-matching-paren-distance): @@ -2373,11 +2407,11 @@ information about the project. A project may contain one or more @dfn{targets}. A target can be an object file, executable program, or some other type of file, which is -``built'' from one or more of the files in the project. +built from one or more of the files in the project. To add a new @dfn{target} to a project, type @kbd{C-c . t} (@code{M-x ede-new-target}). This command also asks if you wish to -``add'' the current file to that target, which means that the target +add the current file to that target, which means that the target is to be built from that file. After you have defined a target, you can add more files to it by typing @kbd{C-c . a} (@code{ede-add-file}). diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in deleted file mode 100644 index e289c46784d..00000000000 --- a/doc/emacs/makefile.w32-in +++ /dev/null @@ -1,153 +0,0 @@ -#### -*- Makefile -*- for the Emacs Manual - -# Copyright (C) 2003-2013 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. - - -# Where to find the source code. The source code for Emacs's C kernel is -# expected to be in $(srcdir)/src, and the source code for Emacs's -# utility programs is expected to be in $(srcdir)/lib-src. This is -# set by the configure script's `--srcdir' option. -srcdir=. - -infodir = $(srcdir)/../../info - -# The makeinfo program is part of the Texinfo distribution. -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat -INFO_EXT=.info -INFO_OPTS=--no-split -INFO_TARGETS = $(infodir)/emacs$(INFO_EXT) -DVI_TARGETS = emacs.dvi -INFOSOURCES = info.texi - -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - texi2dvi $< - -TEXI2DVI = texi2dvi -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - -EMACS_XTRA=\ - $(srcdir)/arevert-xtra.texi \ - $(srcdir)/cal-xtra.texi \ - $(srcdir)/dired-xtra.texi \ - $(srcdir)/picture-xtra.texi \ - $(srcdir)/emerge-xtra.texi \ - $(srcdir)/vc-xtra.texi \ - $(srcdir)/vc1-xtra.texi \ - $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi - -EMACSSOURCES= \ - $(srcdir)/emacs.texi \ - $(srcdir)/emacsver.texi \ - $(srcdir)/doclicense.texi \ - $(srcdir)/screen.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/entering.texi \ - $(srcdir)/basic.texi \ - $(srcdir)/mini.texi \ - $(srcdir)/m-x.texi \ - $(srcdir)/help.texi \ - $(srcdir)/mark.texi \ - $(srcdir)/killing.texi \ - $(srcdir)/regs.texi \ - $(srcdir)/display.texi \ - $(srcdir)/search.texi \ - $(srcdir)/fixit.texi \ - $(srcdir)/files.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/mule.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/indent.texi \ - $(srcdir)/text.texi \ - $(srcdir)/programs.texi \ - $(srcdir)/building.texi \ - $(srcdir)/maintaining.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/sending.texi \ - $(srcdir)/rmail.texi \ - $(srcdir)/dired.texi \ - $(srcdir)/calendar.texi \ - $(srcdir)/misc.texi \ - $(srcdir)/package.texi \ - $(srcdir)/custom.texi \ - $(srcdir)/trouble.texi \ - $(srcdir)/cmdargs.texi \ - $(srcdir)/xresources.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/macos.texi \ - $(srcdir)/msdog.texi \ - $(srcdir)/gnu.texi \ - $(srcdir)/glossary.texi \ - $(srcdir)/ack.texi \ - $(srcdir)/kmacro.texi \ - $(EMACS_XTRA) - -info: $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -# Note that all the Info targets build the Info files -# in srcdir. There is no provision for Info files -# to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -$(infodir)/dir: - $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -$(infodir)/emacs$(INFO_EXT): $(EMACSSOURCES) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ emacs.texi - -emacs.dvi: $(EMACSSOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi - -emacs.html: $(EMACSSOURCES) - $(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ emacs.texi - -emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* - -## FIXME $(infodir)/emacs* deletes too much, eg emacs-mime. -clean: mostlyclean - - $(DEL) *.dvi - - $(DEL) $(infodir)/emacs* - - $(DEL_TREE) emacs.html - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc -# Don't delete these, because they are outside the current directory. -# for file in $(INFO_TARGETS); do rm -f $${file}*; done - - -# Formerly this directory had texindex.c and getopt.c in it -# and this makefile built them to make texindex. -# That caused trouble because this is run entirely in the source directory. -# Since we expect to get texi2dvi from elsewhere, -# it is ok to expect texindex from elsewhere also. diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi index 05b2a5be3a4..09c766be504 100644 --- a/doc/emacs/mark.texi +++ b/doc/emacs/mark.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Mark @@ -43,6 +43,9 @@ Ordinarily, only the selected window highlights its region; however, if the variable @code{highlight-nonselected-windows} is non-@code{nil}, each window highlights its own region. + There is another kind of region: the rectangular region. +@xref{Rectangles}. + @menu * Setting Mark:: Commands to set the mark. * Marking Objects:: Commands to put region around textual units. @@ -102,7 +105,7 @@ region also automatically deactivate the mark, like @kbd{C-x C-u} in the above example. Instead of setting the mark in order to operate on a region, you can -also use it to ``remember'' a position in the buffer (by typing +also use it to remember a position in the buffer (by typing @kbd{C-@key{SPC} C-@key{SPC}}), and later jump back there (by typing @kbd{C-u C-@key{SPC}}). @xref{Mark Ring}, for details. @@ -130,7 +133,7 @@ detailed description of these mouse commands. @cindex shift-selection Finally, you can set the mark by holding down the shift key while -typing certain cursor motion commands (such as @kbd{S-@key{right}}, +typing certain cursor motion commands (such as @kbd{S-@key{RIGHT}}, @kbd{S-C-f}, @kbd{S-C-n}, etc.). This is called @dfn{shift-selection}. It sets the mark at point before moving point, but only if there is no active mark set via shift-selection. The mark set by mouse commands @@ -272,7 +275,7 @@ active. If you change the value to @code{kill}, these commands behavior. Such commands usually have the word @code{region} in their names, like @kbd{C-w} (@code{kill-region}) and @code{C-x C-u} (@code{upcase-region}). If the mark is inactive, they operate on the -``inactive region''---that is, on the text between point and the +@dfn{inactive region}---that is, on the text between point and the position at which the mark was last set (@pxref{Mark Ring}). To disable this behavior, change the variable @code{mark-even-if-inactive} to @code{nil}. Then these commands will diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index f3fab686ed9..2493fdadf37 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -1,5 +1,6 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Minibuffer @@ -37,7 +38,7 @@ how it will be used. The prompt is highlighted using the The simplest way to enter a minibuffer argument is to type the text, then @key{RET} to submit the argument and exit the minibuffer. Alternatively, you can type @kbd{C-g} to exit the minibuffer by -cancelling the command asking for the argument (@pxref{Quitting}). +canceling the command asking for the argument (@pxref{Quitting}). @cindex default argument Sometimes, the prompt shows a @dfn{default argument}, inside @@ -108,8 +109,8 @@ Find file: /u2/emacs/src//etc/termcap @cindex double slash in file name @cindex slashes repeated in file name @findex file-name-shadow-mode -Emacs interprets a double slash as ``ignore everything before the -second slash in the pair''. In the example above, +A double slash causes Emacs to ignore everything before the +second slash in the pair. In the example above, @file{/u2/emacs/src/} is ignored, so the argument you supplied is @file{/etc/termcap}. The ignored part of the file name is dimmed if the terminal allows it. (To disable this dimming, turn off File Name @@ -357,12 +358,12 @@ While in the completion list buffer, this chooses the completion at point (@code{choose-completion}). @findex next-completion -@item @key{Right} +@item @key{RIGHT} While in the completion list buffer, this moves point to the following completion alternative (@code{next-completion}). @findex previous-completion -@item @key{Left} +@item @key{LEFT} While in the completion list buffer, this moves point to the previous completion alternative (@code{previous-completion}). @end table @@ -435,10 +436,10 @@ This behavior is used by most commands that read file names, like @cindex completion style Completion commands work by narrowing a large list of possible -completion alternatives to a smaller subset that ``matches'' what you +completion alternatives to a smaller subset that matches what you have typed in the minibuffer. In @ref{Completion Example}, we gave a simple example of such matching. The procedure of determining what -constitutes a ``match'' is quite intricate. Emacs attempts to offer +constitutes a match is quite intricate. Emacs attempts to offer plausible completions under most circumstances. Emacs performs completion using one or more @dfn{completion @@ -545,11 +546,14 @@ ignored as a completion alternative. Any element ending in a slash @code{".o"}, @code{".elc"}, and @code{"~"}. For example, if a directory contains @samp{foo.c} and @samp{foo.elc}, @samp{foo} completes to @samp{foo.c}. However, if @emph{all} possible -completions end in ``ignored'' strings, they are not ignored: in the +completions end in otherwise-ignored strings, they are not ignored: in the previous example, @samp{foo.e} completes to @samp{foo.elc}. Emacs disregards @code{completion-ignored-extensions} when showing completion alternatives in the completion list. + Shell completion is an extended version of filename completion, +@pxref{Shell Options}. + @vindex completion-auto-help If @code{completion-auto-help} is set to @code{nil}, the completion commands never display the completion list buffer; you must type @@ -561,7 +565,7 @@ completion list buffer. @vindex completion-cycle-threshold If @code{completion-cycle-threshold} is non-@code{nil}, completion -commands can ``cycle'' through completion alternatives. Normally, if +commands can cycle through completion alternatives. Normally, if there is more than one completion alternative for the text in the minibuffer, a completion command completes up to the longest common substring. If you change @code{completion-cycle-threshold} to @@ -572,13 +576,6 @@ in a cyclic manner. If you give @code{completion-cycle-threshold} a numeric value @var{n}, completion commands switch to this cycling behavior only when there are @var{n} or fewer alternatives. -@cindex Icomplete mode -@findex icomplete-mode - Icomplete mode presents a constantly-updated display that tells you -what completions are available for the text you've entered so far. The -command to enable or disable this minor mode is @kbd{M-x -icomplete-mode}. - @node Minibuffer History @section Minibuffer History @cindex minibuffer history @@ -591,11 +588,11 @@ argument into the minibuffer: @table @kbd @item M-p -@itemx @key{Up} +@itemx @key{UP} Move to the previous item in the minibuffer history, an earlier argument (@code{previous-history-element}). @item M-n -@itemx @key{Down} +@itemx @key{DOWN} Move to the next item in the minibuffer history (@code{next-history-element}). @item M-r @var{regexp} @key{RET} @@ -612,11 +609,11 @@ Move to a later item in the minibuffer history that matches @kindex DOWN @r{(minibuffer history)} @findex next-history-element @findex previous-history-element - While in the minibuffer, @kbd{M-p} or @key{Up} + While in the minibuffer, @kbd{M-p} or @key{UP} (@code{previous-history-element}) moves through the minibuffer history list, one item at a time. Each @kbd{M-p} fetches an earlier item from the history list into the minibuffer, replacing its existing contents. -Typing @kbd{M-n} or @key{Down} (@code{next-history-element}) moves +Typing @kbd{M-n} or @key{DOWN} (@code{next-history-element}) moves through the minibuffer history list in the opposite direction, fetching later entries into the minibuffer. @@ -624,9 +621,9 @@ fetching later entries into the minibuffer. entries in the minibuffer history (e.g., if you haven't previously typed @kbd{M-p}), Emacs tries fetching from a list of default arguments: values that you are likely to enter. You can think of this -as moving through the ``future history'' list. +as moving through the ``future history''. - If you edit the text inserted by the @kbd{M-p} or @key{M-n} + If you edit the text inserted by the @kbd{M-p} or @kbd{M-n} minibuffer history commands, this does not change its entry in the history list. However, the edited argument does go at the end of the history list when you submit it. @@ -758,12 +755,12 @@ input is ignored. @node Yes or No Prompts @section Yes or No Prompts - An Emacs command may require you to answer a ``yes or no'' question + An Emacs command may require you to answer a yes-or-no question during the course of its execution. Such queries come in two main varieties. @cindex y or n prompt - For the first type of ``yes or no'' query, the prompt ends with + For the first type of yes-or-no query, the prompt ends with @samp{(y or n)}. Such a query does not actually use the minibuffer; the prompt appears in the echo area, and you answer by typing either @samp{y} or @samp{n}, which immediately delivers the response. For @@ -772,7 +769,7 @@ buffer, and enter the name of an existing file, Emacs issues a prompt like this: @smallexample -File `foo.el' exists; overwrite? (y or n) +File ‘foo.el’ exists; overwrite? (y or n) @end smallexample @noindent @@ -787,7 +784,7 @@ window; and @kbd{C-M-S-v} scrolls backward in the next window. Typing (@pxref{Quitting}). @cindex yes or no prompt - The second type of ``yes or no'' query is typically employed if + The second type of yes-or-no query is typically employed if giving the wrong answer would have serious consequences; it uses the minibuffer, and features a prompt ending with @samp{(yes or no)}. For example, if you invoke @kbd{C-x k} (@code{kill-buffer}) on a diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 73c1c85e2f8..7fad8268d06 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -1,18 +1,17 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @chapter Miscellaneous Commands This chapter contains several brief topics that do not fit anywhere -else: viewing ``document files'', reading Usenet news, running shell -commands and shell subprocesses, using a single shared Emacs for -utilities that expect to run an editor as a subprocess, printing -hardcopy, sorting text, narrowing display to part of the buffer, -editing binary files, saving an Emacs session for later resumption, -following hyperlinks, browsing images, emulating other editors, and -various diversions and amusements. +else: reading Usenet news, viewing PDFs and other such documents, web +browsing, running shell commands and shell subprocesses, using a +single shared Emacs for utilities that expect to run an editor as a +subprocess, printing, sorting text, editing binary files, saving an +Emacs session for later resumption, recursive editing level, following +hyperlinks, and various diversions and amusements. @end iftex @@ -250,6 +249,126 @@ Search forward for articles containing a match for @var{regexp}. Exit the summary buffer and return to the group buffer. @end table + +@node Network Security +@section Network Security +@cindex network security manager +@cindex NSM +@cindex encryption +@cindex SSL +@cindex TLS +@cindex STARTTLS + +Whenever Emacs establishes any network connection, it passes the +established connection to the @dfn{Network Security Manager} +(@acronym{NSM}). @acronym{NSM} is responsible for enforcing the +network security under your control. + +@vindex network-security-level +The @code{network-security-level} variable determines the security +level that @acronym{NSM} enforces. If its value is @code{low}, no +security checks are performed. + +If this variable is @code{medium} (which is the default), a number of +checks will be performed. If as result @acronym{NSM} determines that +the network connection might not be trustworthy, it will make you +aware of that, and will ask you what to do about the network +connection. + +You can decide to register a permanent security exception for an +unverified connection, a temporary exception, or refuse the connection +entirely. + +Below is a list of the checks done on the @code{medium} level. + +@table @asis + +@item unable to verify a @acronym{TLS} certificate +If the connection is a @acronym{TLS}, @acronym{SSL} or +@acronym{STARTTLS} connection, @acronym{NSM} will check whether +the certificate used to establish the identity of the server we're +connecting to can be verified. + +While an invalid certificate is often the cause for concern (there +could be a Man-in-the-Middle hijacking your network connection and +stealing your password), there may be valid reasons for going ahead +with the connection anyway. For instance, the server may be using a +self-signed certificate, or the certificate may have expired. It's up +to you to determine whether it's acceptable to continue with the +connection. + +@item a self-signed certificate has changed +If you've previously accepted a self-signed certificate, but it has +now changed, that could mean that the server has just changed the +certificate, but it might also mean that the network connection has +been hijacked. + +@item previously encrypted connection now unencrypted +If the connection is unencrypted, but it was encrypted in previous +sessions, this might mean that there is a proxy between you and the +server that strips away @acronym{STARTTLS} announcements, leaving the +connection unencrypted. This is usually very suspicious. + +@item talking to an unencrypted service when sending a password +When connecting to an @acronym{IMAP} or @acronym{POP3} server, these +should usually be encrypted, because it's common to send passwords +over these connections. Similarly, if you're sending email via +@acronym{SMTP} that requires a password, you usually want that +connection to be encrypted. If the connection isn't encrypted, +@acronym{NSM} will warn you. + +@end table + +If @code{network-security-level} is @code{high}, the following checks +will be made, in addition to the above: + +@table @asis +@item a validated certificate changes the public key +Servers change their keys occasionally, and that is normally nothing +to be concerned about. However, if you are worried that your network +connections are being hijacked by agencies who have access to pliable +Certificate Authorities which issue new certificates for third-party +services, you may want to keep track of these changes. + +@item Diffie-Hellman low prime bits +When doing the public key exchange, the number of prime bits +should be high to ensure that the channel can't be eavesdropped on by +third parties. If this number is too low, you will be warned. + +@item @acronym{RC4} stream cipher +The @acronym{RC4} stream cipher is believed to be of low quality and +may allow eavesdropping by third parties. + +@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3} +The protocols older than @acronym{TLS1.0} are believed to be +vulnerable to a variety of attacks, and you may want to avoid using +these if what you're doing requires higher security. +@end table + +Finally, if @code{network-security-level} is @code{paranoid}, you will +also be notified the first time @acronym{NSM} sees any new +certificate. This will allow you to inspect all the certificates from +all the connections that Emacs makes. + +The following additional variables can be used to control details of +@acronym{NSM} operation: + +@table @code +@item nsm-settings-file +@vindex nsm-settings-file +This is the file where @acronym{NSM} stores details about connections. +It defaults to @file{~/.emacs.d/network-security.data}. + +@item nsm-save-host-names +@vindex nsm-save-host-names +By default, host names will not be saved for non-@code{STARTTLS} +connections. Instead a host/port hash is used to identify connections. +This means that one can't casually read the settings file to see what +servers the user has connected to. If this variable is @code{t}, +@acronym{NSM} will also save host names in the nsm-settings-file. +@end table + + @node Document View @section Document Viewing @cindex DVI file @@ -267,9 +386,10 @@ Exit the summary buffer and return to the group buffer. OpenDocument, and Microsoft Office documents. It provides features such as slicing, zooming, and searching inside documents. It works by converting the document to a set of images using the @command{gs} -(GhostScript) command and other external tools @footnote{@code{gs} is -a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} is -needed. For OpenDocument and Microsoft Office documents, the +(GhostScript) or @command{mudraw}/@command{pdfdraw} (MuPDF) commands +and other external tools @footnote{For PostScript files, GhostScript +is a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} +is needed. For OpenDocument and Microsoft Office documents, the @code{unoconv} tool is needed.}, and displaying those images. @findex doc-view-toggle-display @@ -288,6 +408,17 @@ mode or DocView minor mode, repeating @kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView and the underlying file contents. +@findex doc-view-open-text + When you visit a file which would normally be handled by DocView +mode but some requirement is not met (e.g., you operate in a terminal +frame or emacs has no PNG support), you are queried if you want to +view the document's contents as plain text. If you confirm, the +buffer is put in text mode and DocView minor mode is activated. Thus, +by typing @kbd{C-c C-c} you switch to the fallback mode. With another +@kbd{C-c C-c} you return to DocView mode. The plain text contents can +also be displayed from within DocView mode by typing @kbd{C-c C-t} +(@code{doc-view-open-text}). + You can explicitly enable DocView mode with the command @code{M-x doc-view-mode}. You can toggle DocView minor mode with @code{M-x doc-view-minor-mode}. @@ -408,12 +539,14 @@ and the slice's width and height. A more convenient graphical way to specify the slice is with @kbd{s m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to -select the slice. -@c ??? How does this work? +select the slice. Simply press and hold the left mouse button at the +upper-left corner of the region you want to have in the slice, then +move the mouse pointer to the lower-right corner and release the +button. The most convenient way is to set the optimal slice by using BoundingBox information automatically determined from the document by -typing @kbd{s b} (@code{doc-view-set-slice-using-mouse}). +typing @kbd{s b} (@code{doc-view-set-slice-from-bounding-box}). @findex doc-view-reset-slice To cancel the selected slice, type @kbd{s r} @@ -439,6 +572,18 @@ associated with the current buffer, type @kbd{K} (@code{doc-view-kill-proc-and-buffer}) kills the converter process and the DocView buffer. +@node EWW +@section Web Browsing with EWW + +@findex eww +@findex eww-open-file + @dfn{EWW}, the Emacs Web Wowser, is a web browser package for Emacs. +It allows browsing URLs within an Emacs buffer. The command @kbd{M-x +eww} will open a URL or search the web. You can open a file +using the command @kbd{M-x eww-open-file}. You can use EWW as the +web browser for @code{browse-url}, @pxref{Browse-URL}. For full +details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}. + @node Shell @section Running Shell Commands from Emacs @cindex subshell @@ -642,15 +787,10 @@ also change the coding system for a running subshell by typing Coding}. @cindex @env{INSIDE_EMACS} environment variable -@cindex @env{EMACS} environment variable Emacs sets the environment variable @env{INSIDE_EMACS} in the subshell to @samp{@var{version},comint}, where @var{version} is the Emacs version (e.g., @samp{24.1}). Programs can check this variable -to determine whether they are running inside an Emacs subshell. (It -also sets the @env{EMACS} environment variable to @code{t}, if that -environment variable is not already defined. However, this -environment variable is deprecated; programs that use it should switch -to using @env{INSIDE_EMACS} instead.) +to determine whether they are running inside an Emacs subshell. @node Shell Mode @subsection Shell Mode @@ -677,20 +817,13 @@ in the shell buffer to submit the current line as input. @item @key{TAB} @kindex TAB @r{(Shell mode)} @findex completion-at-point +@cindex shell completion Complete the command name or file name before point in the shell buffer (@code{completion-at-point}). This uses the usual Emacs completion rules (@pxref{Completion}), with the completion alternatives being file names, environment variable names, the shell command history, and history references (@pxref{History References}). - -@vindex shell-completion-fignore -@vindex comint-completion-fignore -The variable @code{shell-completion-fignore} specifies a list of file -name extensions to ignore in Shell mode completion. The default -setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to -ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other -related Comint modes use the variable @code{comint-completion-fignore} -instead. +For options controlling the completion, @pxref{Shell Options}. @item M-? @kindex M-? @r{(Shell mode)} @@ -810,8 +943,8 @@ echoing. This is useful when a shell command runs a program that asks for a password. Please note that Emacs will not echo passwords by default. If you -really want them to be echoed, evaluate the following Lisp -expression: +really want them to be echoed, evaluate (@pxref{Lisp Eval}) the +following Lisp expression: @example (remove-hook 'comint-output-filter-functions @@ -994,8 +1127,8 @@ can reexecute several successive commands by typing @kbd{C-c C-x @key{RET}} over and over. The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) -copies an individual argument from a previous command, like @kbd{ESC -.} in Bash. The simplest use copies the last argument from the +copies an individual argument from a previous command, like +@kbd{@key{ESC} .} in Bash. The simplest use copies the last argument from the previous shell command. With a prefix argument @var{n}, it copies the @var{n}th argument instead. Repeating @kbd{C-c .} copies from an earlier shell command instead, always using the same value of @var{n} @@ -1179,6 +1312,20 @@ the possible completions whenever completion is not exact. If you set @code{shell-completion-execonly} to @code{nil}, it considers nonexecutable files as well. +@vindex shell-completion-fignore +@vindex comint-completion-fignore +The variable @code{shell-completion-fignore} specifies a list of file +name extensions to ignore in Shell mode completion. The default +setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to +ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other +related Comint modes use the variable @code{comint-completion-fignore} +instead. + +@findex shell-dynamic-complete-command +Some implementation details of the shell command completion may also be found +in the lisp documentation of the @code{shell-dynamic-complete-command} +function. + @findex shell-pushd-tohome @findex shell-pushd-dextract @findex shell-pushd-dunique @@ -1274,7 +1421,7 @@ char mode. @table @kbd @item C-c C-c -Send a literal @key{C-c} to the sub-shell. +Send a literal @kbd{C-c} to the sub-shell. @item C-c @var{char} This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For @@ -1339,8 +1486,8 @@ this buffer just like it does with a terminal in ordinary Term mode. most common speed is 9600 bits per second. You can change the speed interactively by clicking on the mode line. - A serial port can be configured even more by clicking on ``8N1'' in -the mode line. By default, a serial port is configured as ``8N1'', + A serial port can be configured even more by clicking on @samp{8N1} in +the mode line. By default, a serial port is configured as @samp{8N1}, which means that each byte consists of 8 data bits, No parity check bit, and 1 stopbit. @@ -1401,7 +1548,7 @@ variable to @samp{emacsclient +%d %s}.} @vindex server-name You can run multiple Emacs servers on the same machine by giving -each one a unique ``server name'', using the variable +each one a unique @dfn{server name}, using the variable @code{server-name}. For example, @kbd{M-x set-variable @key{RET} server-name @key{RET} foo @key{RET}} sets the server name to @samp{foo}. The @code{emacsclient} program can specify a server by @@ -1458,7 +1605,7 @@ still use Emacs to edit the file. @kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file and sends a message back to the @command{emacsclient} program, telling it to exit. Programs that use @env{EDITOR} usually wait for the -``editor''---in this case @command{emacsclient}---to exit before doing +editor---in this case @command{emacsclient}---to exit before doing something else. You can also call @command{emacsclient} with multiple file name @@ -1478,7 +1625,7 @@ create it. However, if you set @code{server-kill-new-buffers} to @code{nil}, then a different criterion is used: finishing with a server buffer kills it if the file name matches the regular expression @code{server-temp-file-regexp}. This is set up to distinguish certain -``temporary'' files. +temporary files. Each @kbd{C-x #} checks for other pending external requests to edit various files, and selects the next such file. You can switch to a @@ -1528,6 +1675,7 @@ precedence. @cindex client frame @item -c +@itemx --create-frame Create a new graphical @dfn{client frame}, instead of using an existing Emacs frame. See below for the special behavior of @kbd{C-x C-c} in a client frame. If Emacs cannot create a new graphical frame @@ -1542,9 +1690,9 @@ option, like the @samp{-t} option, creates a new frame in the server's current text terminal. @xref{Windows Startup}. If you omit a filename argument while supplying the @samp{-c} option, -the new frame displays the @file{*scratch*} buffer by default. If -@code{initial-buffer-choice} is a string (@pxref{Entering Emacs}), the -new frame displays that file or directory instead. +the new frame displays the @file{*scratch*} buffer by default. You +can customize this behavior with the variable @code{initial-buffer-choice} +(@pxref{Entering Emacs}). @item -F @var{alist} @itemx --frame-parameters=@var{alist} @@ -1568,8 +1716,8 @@ evaluate, @emph{not} as a list of files to visit. @cindex @env{EMACS_SERVER_FILE} environment variable Specify a @dfn{server file} for connecting to an Emacs server via TCP. -An Emacs server usually uses an operating system feature called a -``local socket'' to listen for connections. Some operating systems, +An Emacs server usually uses a +local socket to listen for connections. Some operating systems, such as Microsoft Windows, do not support local sockets; in that case, the server communicates with @command{emacsclient} via TCP. @@ -1592,9 +1740,9 @@ all server buffers are finished. You can take as long as you like to edit the server buffers within Emacs, and they are @emph{not} killed when you type @kbd{C-x #} in them. -@item --parent-id @var{ID} +@item --parent-id @var{id} Open an @command{emacsclient} frame as a client frame in the parent X -window with id @var{ID}, via the XEmbed protocol. Currently, this +window with id @var{id}, via the XEmbed protocol. Currently, this option is mainly useful for developers. @item -q @@ -1663,7 +1811,7 @@ print hardcopies from Dired (@pxref{Operating on Files}) and the diary (@pxref{Displaying the Diary}). You can also ``print'' an Emacs buffer to HTML with the command @kbd{M-x htmlfontify-buffer}, which converts the current buffer to a HTML file, replacing Emacs faces with -CSS-based markup. Furthermore, Org mode allows you to ``print'' Org +CSS-based markup. Furthermore, Org mode allows you to print Org files to a variety of formats, such as PDF (@pxref{Org Mode}). @table @kbd @@ -1836,7 +1984,7 @@ additional paper sizes by changing the variable @vindex ps-landscape-mode The variable @code{ps-landscape-mode} specifies the orientation of printing on the page. The default is @code{nil}, which stands for -``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' +portrait mode. Any non-@code{nil} value specifies landscape mode. @vindex ps-number-of-columns @@ -1899,11 +2047,11 @@ used. init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. This function replaces the usual printing commands in the menu bar with a @samp{Printing} submenu that contains various printing options. -You can also type @kbd{M-x pr-interface RET}; this creates a +You can also type @kbd{M-x pr-interface @key{RET}}; this creates a @file{*Printing Interface*} buffer, similar to a customization buffer, where you can set the printing options. After selecting what and how to print, you start the print job using the @samp{Print} button (click -@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For +@kbd{Mouse-2} on it, or move point over it and type @key{RET}). For further information on the various options, use the @samp{Interface Help} button. @@ -1917,9 +2065,9 @@ They divide the text of the region into many @dfn{sort records}, identify a @dfn{sort key} for each record, and then reorder the records into the order determined by the sort keys. The records are ordered so that their keys are in alphabetical order, or, for numeric sorting, in -numeric order. In alphabetic sorting, all upper-case letters `A' through -`Z' come before lower-case `a', in accord with the @acronym{ASCII} character -sequence. +numeric order. In alphabetic sorting, all upper-case letters @samp{A} +through @samp{Z} come before lower-case @samp{a}, in accordance with the +@acronym{ASCII} character sequence. The various sort commands differ in how they divide the text into sort records and in which part of each record is used as the sort key. Most of @@ -1972,12 +2120,14 @@ to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or @item M-x sort-columns Like @kbd{M-x sort-fields} except that the text within each line -used for comparison comes from a fixed range of columns. See below -for an explanation. +used for comparison comes from a fixed range of columns. With a +prefix argument, sort in reverse order. See below for more details +on this command. +@findex reverse-region @item M-x reverse-region Reverse the order of the lines in the region. This is useful for -sorting into descending order by fields or columns, since those sort +sorting into descending order by fields, since those sort commands do not have a feature for doing that. @end table @@ -2082,10 +2232,10 @@ Insert a byte with a code typed in octal. Insert a byte with a code typed in hex. @item C-x [ -Move to the beginning of a 1k-byte ``page''. +Move to the beginning of a 1k-byte page. @item C-x ] -Move to the end of a 1k-byte ``page''. +Move to the end of a 1k-byte page. @item M-g Move to an address specified in hex. @@ -2112,10 +2262,15 @@ hexl-@key{RET}} for details. @cindex reload files @cindex desktop +@vindex desktop-restore-frames Use the desktop library to save the state of Emacs from one session to another. Once you save the Emacs @dfn{desktop}---the buffers, their file names, major modes, buffer positions, and so on---then -subsequent Emacs sessions reload the saved desktop. +subsequent Emacs sessions reload the saved desktop. By default, +the desktop also tries to save the frame and window configuration. +To disable this, set @code{desktop-restore-frames} to @code{nil}. +(See that variable's documentation for some related options +that you can customize to fine-tune this behavior.) @findex desktop-save @vindex desktop-save-mode @@ -2130,6 +2285,12 @@ sessions, or add this line in your init file (@pxref{Init File}): (desktop-save-mode 1) @end example +@vindex desktop-auto-save-timeout +@noindent +When @code{desktop-save-mode} is active and the desktop file exists, +Emacs auto-saves it every @code{desktop-auto-save-timeout} +seconds, if that is non-@code{nil} and non-zero. + @findex desktop-change-dir @findex desktop-revert @vindex desktop-path @@ -2155,7 +2316,7 @@ usually turned on. However, this may be slow if there are a lot of buffers in the desktop. You can specify the maximum number of buffers to restore immediately with the variable @code{desktop-restore-eager}; the -remaining buffers are restored ``lazily'', when Emacs is idle. +remaining buffers are restored lazily, when Emacs is idle. @findex desktop-clear @vindex desktop-globals-to-clear @@ -2230,7 +2391,7 @@ stack overflow) from time to time. So remember to exit or abort the recursive edit when you no longer need it. In general, we try to minimize the use of recursive editing levels in -GNU Emacs. This is because they constrain you to ``go back'' in a +GNU Emacs. This is because they constrain you to go back in a particular order---from the innermost level toward the top level. When possible, we present different activities in separate buffers so that you can switch between them as you please. Some commands switch to a @@ -2238,17 +2399,17 @@ new major mode which provides a command to switch back. These approaches give you more flexibility to go back to unfinished tasks in the order you choose. +@ignore +@c Apart from edt and viper, this is all obsolete. +@c (Can't believe we were saying "most other editors" into 2014!) +@c There seems no point having a node just for those, which both have +@c their own manuals. @node Emulation @section Emulation @cindex emulating other editors @cindex other editors @cindex EDT @cindex vi -@cindex PC key bindings -@cindex scrolling all windows -@cindex PC selection -@cindex Motif key bindings -@cindex Macintosh key bindings @cindex WordStar GNU Emacs can be programmed to emulate (more or less) most other @@ -2288,7 +2449,7 @@ buffers or major modes while in EDT emulation. @item vi (Berkeley editor) @findex viper-mode -Viper is the newest emulator for vi. It implements several levels of +Viper is an emulator for vi. It implements several levels of emulation; level 1 is closest to vi itself, while level 5 departs somewhat from strict emulation to take advantage of the capabilities of Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you @@ -2299,8 +2460,8 @@ Viper, viper}. @findex vi-mode @kbd{M-x vi-mode} enters a major mode that replaces the previously established major mode. All of the vi commands that, in real vi, enter -``input'' mode are programmed instead to return to the previous major -mode. Thus, ordinary Emacs serves as vi's ``input'' mode. +input mode are programmed instead to return to the previous major +mode. Thus, ordinary Emacs serves as vi's input mode. Because vi emulation works through major modes, it does not work to switch buffers during emulation. Return to normal Emacs first. @@ -2311,7 +2472,7 @@ to the @code{vi-mode} command. @item vi (alternate emulator) @findex vip-mode @kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi -more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator +more thoroughly than @kbd{M-x vi-mode}. Input mode in this emulator is changed from ordinary Emacs so you can use @key{ESC} to go back to emulated vi command mode. To get from emulated vi command mode back to ordinary Emacs, type @kbd{C-z}. @@ -2329,6 +2490,8 @@ not use it. @kbd{M-x wordstar-mode} provides a major mode with WordStar-like key bindings. @end table +@end ignore + @node Hyperlinking @section Hyperlinking and Navigation Features @@ -2526,7 +2689,7 @@ character. Keep dissociwords out of your documentation, if you want it to be well userenced and properbose. @findex dunnet - @kbd{M-x dunnet} runs an text-based adventure game. + @kbd{M-x dunnet} runs a text-based adventure game. @findex gomoku @cindex Go Moku @@ -2541,7 +2704,7 @@ bored, try an argument of 9. Sit back and watch. @findex life @cindex Life - @kbd{M-x life} runs Conway's ``Life'' cellular automaton. + @kbd{M-x life} runs Conway's Game of Life cellular automaton. @findex landmark @cindex landmark game diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi index 6b7073e3f0a..4abbb59e89d 100644 --- a/doc/emacs/modes.texi +++ b/doc/emacs/modes.texi @@ -1,5 +1,6 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Modes @@ -200,6 +201,12 @@ Auto Save mode saves the buffer contents periodically to reduce the amount of work you can lose in case of a crash. @xref{Auto Save}. @item +Electric Quote mode automatically converts quotation marks. For +example, it requotes text typed @t{`like this'} to text @t{‘like +this’}. You can control what kind of text it operates in, and you can +disable it entirely in individual buffers. @xref{Quotation Marks}. + +@item Enriched mode enables editing and saving of formatted text. @xref{Enriched Text}. @@ -245,7 +252,7 @@ In Binary Overwrite mode, digits after @kbd{C-q} specify an octal character code, as usual. @item -Visual Line mode performs ``word wrapping'', causing long lines to be +Visual Line mode performs word wrapping, causing long lines to be wrapped at word boundaries. @xref{Visual Line Mode}. @end itemize @@ -263,8 +270,7 @@ in the region, if the region is active. @xref{Using Region}. @item Icomplete mode displays an indication of available completions when -you are in the minibuffer and completion is active. @xref{Completion -Options}. +you are in the minibuffer and completion is active. @xref{Icomplete}. @item Line Number mode enables display of the current line number in the @@ -430,7 +436,8 @@ compares the text at the start of the buffer to the variable @code{magic-mode-alist}, described above, except that is consulted only after @code{auto-mode-alist}. By default, @code{magic-fallback-mode-alist} contains forms that check for image -files, HTML/XML/SGML files, and PostScript files. +files, HTML/XML/SGML files, PostScript files, and Unix style Conf +files. @findex normal-mode If you have changed the major mode of a buffer, you can return to @@ -445,6 +452,6 @@ the file's @samp{-*-} line or local variables list (if any). a new major mode if the new file name implies a mode (@pxref{Saving}). (@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) However, this does not happen if the buffer contents specify a major -mode, and certain ``special'' major modes do not allow the mode to +mode, and certain special major modes do not allow the mode to change. You can turn off this mode-changing feature by setting @code{change-major-mode-with-file-name} to @code{nil}. diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdos-xtra.texi index cb19f89dd91..c8e266915f0 100644 --- a/doc/emacs/msdog-xtra.texi +++ b/doc/emacs/msdos-xtra.texi @@ -1,24 +1,23 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @c printed version) or in the main Emacs manual (for the on-line version). @node MS-DOS @section Emacs and MS-DOS -@cindex MS-DOG @cindex MS-DOS peculiarities This section briefly describes the peculiarities of using Emacs on -the MS-DOS ``operating system'' (also known as ``MS-DOG''). +MS-DOS. @iftex Information about Emacs and Microsoft's current operating system -Windows (also known as ``Losedows'') is in the main Emacs manual +Windows is in the main Emacs manual (@pxref{Microsoft Windows,,, emacs, the Emacs Manual}). @end iftex @ifnottex Information about peculiarities common to MS-DOS and Microsoft's -current operating systems Windows (also known as ``Losedows'') is in +current operating systems Windows is in @ref{Microsoft Windows}. @end ifnottex @@ -53,13 +52,13 @@ about Emacs's special handling of text files under MS-DOS (and Windows). The key that is called @key{DEL} in Emacs (because that's how it is designated on most workstations) is known as @key{BS} (backspace) on a PC@. That is why the PC-specific terminal initialization remaps the -@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act +@key{BS} key to act as @key{DEL}; the @key{Delete} key is remapped to act as @kbd{C-d} for the same reasons. @kindex C-g @r{(MS-DOS)} -@kindex C-BREAK @r{(MS-DOS)} +@kindex C-Break @r{(MS-DOS)} @cindex quitting on MS-DOS - Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit + Emacs built for MS-DOS recognizes @kbd{C-@key{Break}} as a quit character, just like @kbd{C-g}. This is because Emacs cannot detect that you have typed @kbd{C-g} until it is ready for more input. As a consequence, you cannot use @kbd{C-g} to stop a running command @@ -69,7 +68,7 @@ consequence, you cannot use @kbd{C-g} to stop a running command @ifnottex (@pxref{Quitting}). @end ifnottex -By contrast, @kbd{C-@key{BREAK}} @emph{is} detected as soon as you +By contrast, @kbd{C-@key{Break}} @emph{is} detected as soon as you type it (as @kbd{C-g} is on other systems), so it can be used to stop a running command and for emergency escape @iftex @@ -84,17 +83,17 @@ a running command and for emergency escape @cindex Super (under MS-DOS) @vindex dos-super-key @vindex dos-hyper-key - The PC keyboard maps use the left @key{ALT} key as the @key{META} key. + The PC keyboard maps use the left @key{Alt} key as the @key{META} key. You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: -choose either the right @key{CTRL} key or the right @key{ALT} key by +choose either the right @key{Ctrl} key or the right @key{Alt} key by setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 or 2 respectively. If neither @code{dos-super-key} nor -@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is +@code{dos-hyper-key} is 1, then by default the right @key{Alt} key is also mapped to the @key{META} key. However, if the MS-DOS international keyboard support program @file{KEYB.COM} is installed, Emacs will -@emph{not} map the right @key{ALT} to @key{META}, since it is used for +@emph{not} map the right @key{Alt} to @key{META}, since it is used for accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard -layouts; in this case, you may only use the left @key{ALT} as @key{META} +layouts; in this case, you may only use the left @key{Alt} as @key{META} key. @kindex C-j @r{(MS-DOS)} @@ -352,7 +351,7 @@ long file name support, set the environment variable @env{LFN} to DOS programs to access long file names, so Emacs built for MS-DOS will only see their short 8+3 aliases. -@cindex @env{HOME} directory under MS-DOS +@cindex HOME directory under MS-DOS MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends that the directory where it is installed is the value of the @env{HOME} environment variable. That is, if your Emacs binary, @@ -398,11 +397,11 @@ though they are connected to a Windows machine that uses a different encoding for the same locale. For example, in the Latin-1 locale, DOS uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and MULE}. When you print to such printers from Windows, you can use the -@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before -@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS -codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET -M-x lpr-region RET} will print the region while converting it to the -codepage 850 encoding. +@kbd{C-x @key{RET} c} (@code{universal-coding-system-argument}) command +before @kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS +codepage that you specify. For example, +@kbd{C-x @key{RET} c cp850-dos @key{RET} M-x lpr-region @key{RET}} +will print the region while converting it to the codepage 850 encoding. @vindex dos-printer @vindex dos-ps-printer @@ -597,7 +596,7 @@ work in MS-DOS by sending the output to one of the printer ports. program terminates and does not try to read keyboard input. If the program does not terminate on its own, you will be unable to terminate it, because MS-DOS provides no general way to terminate a process. -Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these +Pressing @kbd{C-c} or @kbd{C-@key{Break}} might sometimes help in these cases. Accessing files on other machines is not supported on MS-DOS@. Other diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdos.texi index 0f01958b51c..f1cdb26a0eb 100644 --- a/doc/emacs/msdog.texi +++ b/doc/emacs/msdos.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Microsoft Windows @@ -9,7 +9,7 @@ This section describes peculiarities of using Emacs on Microsoft Windows. Some of these peculiarities are also relevant to Microsoft's -older MS-DOS ``operating system'' (also known as ``MS-DOG''). +older MS-DOS operating system. However, Emacs features that are relevant @emph{only} to MS-DOS are described in a separate @iftex @@ -249,7 +249,42 @@ removable and remote volumes, where this could potentially slow down Dired and other related features. The value of @code{nil} means never issue those system calls. Non-@code{nil} values are more useful on NTFS volumes, which support hard links and file security, than on FAT, -FAT32, and XFAT volumes. +FAT32, and exFAT volumes. + +@cindex file names, invalid characters on MS-Windows + Unlike Unix, MS-Windows file systems restrict the set of characters +that can be used in a file name. The following characters are not +allowed: + +@itemize @bullet +@item +Shell redirection symbols @samp{<}, @samp{>}, and @samp{|}. + +@item +Colon @samp{:} (except after the drive letter). + +@item +Forward slash @samp{/} and backslash @samp{\} (except as directory +separators). + +@item +Wildcard characters @samp{*} and @samp{?}. + +@item +Control characters whose codepoints are 1 through 31 decimal. In +particular, newlines in file names are not allowed. + +@item +The null character, whose codepoint is zero (this limitation exists on +Unix filesystems as well). +@end itemize + +@noindent +In addition, referencing any file whose name matches a DOS character +device, such as @file{NUL} or @file{LPT1} or @file{PRN} or @file{CON}, +with or without any file-name extension, will always resolve to those +character devices, in any directory. Therefore, only use such file +names when you want to use the corresponding character device. @node ls in Lisp @section Emulation of @code{ls} on MS-Windows @@ -390,7 +425,7 @@ names, which might cause misalignment of columns in Dired display. @node Windows HOME @section HOME and Startup Directories on MS-Windows -@cindex @code{HOME} directory on MS-Windows +@cindex HOME directory on MS-Windows The Windows equivalent of @code{HOME} is the @dfn{user-specific application data directory}. The actual location depends on the @@ -458,13 +493,6 @@ before Microsoft was founded.) Examples of conflicts include You can redefine some of them with meanings more like the MS-Windows meanings by enabling CUA Mode (@pxref{CUA Bindings}). -@kindex F10 @r{(MS-Windows)} -@cindex menu bar access using keyboard @r{(MS-Windows)} - The @key{F10} key on Windows activates the menu bar in a way that -makes it possible to use the menus without a mouse. In this mode, the -arrow keys traverse the menus, @key{RET} selects a highlighted menu -item, and @key{ESC} closes the menu. - @iftex @inforef{Windows Keyboard, , emacs}, for information about additional Windows-specific variables in this category. @@ -479,10 +507,10 @@ the variable @code{w32-alt-is-meta} to a @code{nil} value. @findex w32-register-hot-key @findex w32-unregister-hot-key MS-Windows reserves certain key combinations, such as -@kbd{Alt-@key{TAB}}, for its own use. These key combinations are +@kbd{@key{Alt}-@key{TAB}}, for its own use. These key combinations are intercepted by the system before Emacs can see them. You can use the @code{w32-register-hot-key} function to allow a key sequence to be -seen by Emacs instead of being grabbed by Windows. This functions +seen by Emacs instead of being grabbed by Windows. This function registers a key sequence as a @dfn{hot key}, overriding the special meaning of that key sequence for Windows. (MS-Windows is told that the key sequence is a hot key only when one of the Emacs windows has @@ -491,7 +519,7 @@ other Windows applications.) The argument to @code{w32-register-hot-key} must be a single key, with or without modifiers, in vector form that would be acceptable to -@code{define-key}. The meta modifier is interpreted as the @key{ALT} +@code{define-key}. The meta modifier is interpreted as the @key{Alt} key if @code{w32-alt-is-meta} is @code{t} (the default), and the hyper modifier is always interpreted as the Windows key (usually labeled with @key{start} and the Windows logo). If the function succeeds in @@ -499,10 +527,10 @@ registering the key sequence, it returns the hotkey ID, a number; otherwise it returns @code{nil}. @kindex M-TAB@r{, (MS-Windows)} -@cindex @kbd{M-@key{TAB}} vs @kbd{Alt-@key{TAB}} (MS-Windows) -@cindex @kbd{Alt-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows) +@cindex @kbd{M-@key{TAB}} vs @kbd{@key{Alt}-@key{TAB}} (MS-Windows) +@cindex @kbd{@key{Alt}-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows) For example, @code{(w32-register-hot-key [M-tab])} lets you use -@kbd{M-TAB} normally in Emacs; for instance, to complete the word or +@kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the word or symbol at point at top level, or to complete the current search string against previously sought strings during incremental search. @@ -558,14 +586,14 @@ produces the symbol @code{scroll}. @cindex Windows system menu @cindex @code{Alt} key invokes menu (Windows) Emacs compiled as a native Windows application normally turns off -the Windows feature that tapping the @key{ALT} key invokes the Windows -menu. The reason is that the @key{ALT} serves as @key{META} in Emacs. +the Windows feature that tapping the @key{Alt} key invokes the Windows +menu. The reason is that the @key{Alt} serves as @key{META} in Emacs. When using Emacs, users often press the @key{META} key temporarily and then change their minds; if this has the effect of bringing up the Windows menu, it alters the meaning of subsequent commands. Many users find this frustrating. - You can re-enable Windows's default handling of tapping the @key{ALT} + You can re-enable Windows's default handling of tapping the @key{Alt} key by setting @code{w32-pass-alt-to-system} to a non-@code{nil} value. @@ -595,7 +623,7 @@ the combination of the right @key{Alt} and left @key{Ctrl} keys pressed together, is recognized as the @key{AltGr} key. The default is @code{t}, which means these keys produce @code{AltGr}; setting it to @code{nil} causes @key{AltGr} or the equivalent key combination to -be interpreted as the combination of @key{CTRL} and @key{META} +be interpreted as the combination of @key{Ctrl} and @key{META} modifiers. @end ifnottex @@ -674,7 +702,7 @@ subprocesses). If you have to reboot Windows 9X in this situation, do not use the @code{Shutdown} command on the @code{Start} menu; that usually hangs the -system. Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose +system. Instead, type @kbd{@key{Ctrl}-@key{Alt}-@key{DEL}} and then choose @code{Shutdown}. That usually works, although it may take a few minutes to do its job. @@ -993,5 +1021,5 @@ click-to-focus policy. @end ifnottex @ifnottex -@include msdog-xtra.texi +@include msdos-xtra.texi @end ifnottex diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index ebddc46be94..88bbccd5b11 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -1,46 +1,38 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1997, 1999-2013 Free Software Foundation, Inc. +@c Copyright (C) 1997, 1999-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node International @chapter International Character Set Support @c This node is referenced in the tutorial. When renaming or deleting @c it, the tutorial needs to be adjusted. (TUTORIAL.de) -@cindex MULE @cindex international scripts @cindex multibyte characters @cindex encoding of characters -@cindex Celtic +@cindex Arabic +@cindex Bengali @cindex Chinese @cindex Cyrillic -@cindex Czech -@cindex Devanagari +@cindex Han @cindex Hindi -@cindex Marathi @cindex Ethiopic -@cindex German +@cindex Georgian @cindex Greek +@cindex Hangul @cindex Hebrew +@cindex Hindi @cindex IPA @cindex Japanese @cindex Korean -@cindex Lao @cindex Latin -@cindex Polish -@cindex Romanian -@cindex Slovak -@cindex Slovenian @cindex Thai -@cindex Tibetan -@cindex Turkish @cindex Vietnamese -@cindex Dutch -@cindex Spanish Emacs supports a wide variety of international character sets, including European and Vietnamese variants of the Latin alphabet, as -well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek, -Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA, -Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts. +well as Arabic scripts, Brahmic scripts (for languages such as +Bengali, Hindi, and Thai), Cyrillic, Ethiopic, Georgian, Greek, Han +(for Chinese and Japanese), Hangul (for Korean), Hebrew and IPA@. Emacs also supports various encodings of these characters that are used by other internationalized software, such as word processors and mailers. @@ -144,8 +136,11 @@ displayed on your terminal, they appear as @samp{?} or as hollow boxes Keyboards, even in the countries where these character sets are used, generally don't have keys for all the characters in them. You can insert characters that your keyboard does not support, using -@kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}} -(@code{insert-char}). @xref{Inserting Text}. Emacs also supports +@kbd{C-x 8 @key{RET}} (@code{insert-char}). @xref{Inserting Text}. +Shorthands are available for some common characters; for example, you +can insert a left single quotation mark @t{‘} by typing @kbd{C-x 8 +[}, or in Electric Quote mode often by simply typing @kbd{`}. +@xref{Quotation Marks}. Emacs also supports various @dfn{input methods}, typically one for each script or language, which make it easier to type characters in the script. @xref{Input Methods}. @@ -177,9 +172,9 @@ system encodes the character safely and with a single byte one byte, Emacs shows @samp{file ...}. As a special case, if the character lies in the range 128 (0200 -octal) through 159 (0237 octal), it stands for a ``raw'' byte that +octal) through 159 (0237 octal), it stands for a raw byte that does not correspond to any specific displayable character. Such a -``character'' lies within the @code{eight-bit-control} character set, +character lies within the @code{eight-bit-control} character set, and is displayed as an escaped octal character code. In this case, @kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}. @@ -197,17 +192,17 @@ within that character set; @acronym{ASCII} characters are identified as belonging to the @code{ascii} character set. @item -The character's syntax and categories. - -@item -The character's encodings, both internally in the buffer, and externally -if you were to save the file. +The character's script, syntax and categories. @item What keys to type to input the character in the current input method (if it supports the character). @item +The character's encodings, both internally in the buffer, and externally +if you were to save the file. + +@item If you are running Emacs on a graphical display, the font name and glyph code for the character. If you are running Emacs on a text terminal, the code(s) sent to the terminal. @@ -219,28 +214,29 @@ faces used to display the character, and any overlays containing it (@pxref{Overlays,,, elisp, the same manual}). @end itemize - Here's an example showing the Latin-1 character A with grave accent, -in a buffer whose coding system is @code{utf-8-unix}: + Here's an example, with some lines folded to fit into this manual: @smallexample position: 1 of 1 (0%), column: 0 - character: @`A (displayed as @`A) (codepoint 192, #o300, #xc0) + character: ê (displayed as ê) (codepoint 234, #o352, #xea) preferred charset: unicode (Unicode (ISO10646)) -code point in charset: 0xC0 - syntax: w which means: word - category: .:Base, L:Left-to-right (strong), +code point in charset: 0xEA + script: latin + syntax: w which means: word + category: .:Base, L:Left-to-right (strong), c:Chinese, j:Japanese, l:Latin, v:Viet - buffer code: #xC3 #x80 - file code: not encodable by coding system undecided-unix + to input: type "C-x 8 RET HEX-CODEPOINT" or "C-x 8 RET NAME" + buffer code: #xC3 #xAA + file code: #xC3 #xAA (encoded by coding system utf-8-unix) display: by this font (glyph code) xft:-unknown-DejaVu Sans Mono-normal-normal- - normal-*-13-*-*-*-m-0-iso10646-1 (#x82) + normal-*-15-*-*-*-m-0-iso10646-1 (#xAC) Character code properties: customize what to show - name: LATIN CAPITAL LETTER A WITH GRAVE - old-name: LATIN CAPITAL LETTER A GRAVE - general-category: Lu (Letter, Uppercase) - decomposition: (65 768) ('A' '`') + name: LATIN SMALL LETTER E WITH CIRCUMFLEX + old-name: LATIN SMALL LETTER E CIRCUMFLEX + general-category: Ll (Letter, Lowercase) + decomposition: (101 770) ('e' '^') @end smallexample @node Language Environments @@ -267,25 +263,107 @@ language environment also specifies a default input method. @code{current-language-environment} or use the command @kbd{M-x set-language-environment}. It makes no difference which buffer is current when you use this command, because the effects apply globally -to the Emacs session. The supported language environments -(see the variable @code{language-info-alist}) include: - -@cindex Euro sign -@cindex UTF-8 +to the Emacs session. See the variable @code{language-info-alist} for +the list of supported language environments, and use the command +@kbd{C-h L @var{lang-env} @key{RET}} (@code{describe-language-environment}) +for more information about the language environment @var{lang-env}. +Supported language environments include: + +@c @cindex entries below are split between portions of the list to +@c make them more accurate, i.e., land on the line that mentions the +@c language. However, makeinfo 4.x doesn't fill inside @quotation +@c lines that follow a @cindex entry and whose text has no whitespace. +@c To work around, we group the language environments together, so +@c that the blank that separates them triggers refill. @quotation -ASCII, Belarusian, Bengali, Brazilian Portuguese, Bulgarian, Cham, -Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GBK, -Chinese-GB18030, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, -Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French, -Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese, -Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, -Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated Latin-1 -with the Euro sign), Latvian, Lithuanian, Malayalam, Oriya, Polish, -Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish, -Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8 -(for a setup which prefers Unicode characters and files encoded in -UTF-8), Ukrainian, Vietnamese, Welsh, and Windows-1255 (for a setup -which prefers Cyrillic characters and files encoded in Windows-1255). +@cindex ASCII +@cindex Arabic +ASCII, Arabic, +@cindex Belarusian +@cindex Bengali +Belarusian, Bengali, +@cindex Brazilian Portuguese +@cindex Bulgarian +Brazilian Portuguese, Bulgarian, +@cindex Burmese +@cindex Cham +Burmese, Cham, +@cindex Chinese +Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, +Chinese-GB18030, Chinese-GBK, +@cindex Croatian +@cindex Cyrillic +Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, +@cindex Czech +@cindex Devanagari +Czech, Devanagari, +@cindex Dutch +@cindex English +Dutch, English, +@cindex Esperanto +@cindex Ethiopic +Esperanto, Ethiopic, +@cindex French +@cindex Georgian +French, Georgian, +@cindex German +@cindex Greek +@cindex Gujarati +German, Greek, Gujarati, +@cindex Hebrew +@cindex IPA +Hebrew, IPA, +@cindex Italian +Italian, +@cindex Japanese +@cindex Kannada +Japanese, Kannada, +@cindex Khmer +@cindex Korean +@cindex Lao +Khmer, Korean, Lao, +@cindex Latin +Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Latin-6, Latin-7, +Latin-8, Latin-9, +@cindex Latvian +@cindex Lithuanian +Latvian, Lithuanian, +@cindex Malayalam +@cindex Oriya +Malayalam, Oriya, +@cindex Persian +@cindex Polish +Persian, Polish, +@cindex Punjabi +@cindex Romanian +Punjabi, Romanian, +@cindex Russian +@cindex Sinhala +Russian, Sinhala, +@cindex Slovak +@cindex Slovenian +@cindex Spanish +Slovak, Slovenian, Spanish, +@cindex Swedish +@cindex TaiViet +Swedish, TaiViet, +@cindex Tajik +@cindex Tamil +Tajik, Tamil, +@cindex Telugu +@cindex Thai +Telugu, Thai, +@cindex Tibetan +@cindex Turkish +Tibetan, Turkish, +@cindex UTF-8 +@cindex Ukrainian +UTF-8, Ukrainian, +@cindex Vietnamese +@cindex Welsh +Vietnamese, Welsh, +@cindex Windows-1255 +and Windows-1255. @end quotation To display the script(s) used by your language environment on a @@ -343,7 +421,6 @@ character sets, coding systems, and input methods that go with it. It also shows some sample text to illustrate scripts used in this language environment. If you give an empty input for @var{lang-env}, this command describes the chosen language environment. -@anchor{Describe Language Environment} @vindex set-language-environment-hook You can customize any language environment with the normal hook @@ -462,6 +539,8 @@ searching for what you have already entered. To find out how to input the character after point using the current input method, type @kbd{C-u C-x =}. @xref{Position Info}. +@c TODO: document complex-only/default/t of +@c @code{input-method-verbose-flag} @vindex input-method-verbose-flag @vindex input-method-highlight-flag The variables @code{input-method-highlight-flag} and @@ -563,7 +642,7 @@ automatically. For example: @end lisp @noindent -This automatically activates the input method ``german-prefix'' in +This automatically activates the input method @code{german-prefix} in Text mode. @findex quail-set-keyboard-layout @@ -617,8 +696,8 @@ system; for example, to visit a file encoded in codepage 850, type In addition to converting various representations of non-@acronym{ASCII} characters, a coding system can perform end-of-line conversion. Emacs handles three different conventions for how to separate lines in a file: -newline (``unix''), carriage-return linefeed (``dos''), and just -carriage-return (``mac''). +newline (Unix), carriage-return linefeed (DOS), and just +carriage-return (Mac). @table @kbd @item C-h C @var{coding} @key{RET} @@ -1090,7 +1169,9 @@ current language environment. to use when encoding and decoding system strings such as system error messages and @code{format-time-string} formats and time stamps. That coding system is also used for decoding non-@acronym{ASCII} keyboard -input on the X Window System. You should choose a coding system that is compatible +input on the X Window System and for encoding text sent to the +standard output and error streams when in batch mode. You should +choose a coding system that is compatible with the underlying system's text representation, which is normally specified by one of the environment variables @env{LC_ALL}, @env{LC_CTYPE}, and @env{LANG}. (The first one, in the order @@ -1130,6 +1211,21 @@ In the default language environment, non-@acronym{ASCII} characters in file names are not encoded specially; they appear in the file system using the internal Emacs representation. +@cindex file-name encoding, MS-Windows +@vindex w32-unicode-filenames + When Emacs runs on MS-Windows versions that are descendants of the +NT family (Windows 2000, XP, Vista, Windows 7, and Windows 8), the +value of @code{file-name-coding-system} is largely ignored, as Emacs +by default uses APIs that allow to pass Unicode file names directly. +By contrast, on Windows 9X, file names are encoded using +@code{file-name-coding-system}, which should be set to the codepage +(@pxref{Coding Systems, codepage}) pertinent for the current system +locale. The value of the variable @code{w32-unicode-filenames} +controls whether Emacs uses the Unicode APIs when it calls OS +functions that accept file names. This variable is set by the startup +code to @code{nil} on Windows 9X, and to @code{t} on newer versions of +MS-Windows. + @strong{Warning:} if you change @code{file-name-coding-system} (or the language environment) in the middle of an Emacs session, problems can result if you have already visited files whose names were encoded using @@ -1466,6 +1562,20 @@ used. Some examples are: @end example +@cindex ignore font +@cindex fonts, how to ignore +@vindex face-ignored-fonts + Some fonts installed on your system might be broken, or produce +unpleasant results for characters for which they are used, and you may +wish to instruct Emacs to completely ignore them while searching for a +suitable font required to display a character. You can do that by +adding the offending fonts to the value of @code{face-ignored-fonts} +variable, which is a list. Here's an example to put in your +@file{~/.emacs}: + +@example +(add-to-list 'face-ignored-fonts "Some Bad Font") +@end example @node Undisplayable Characters @section Undisplayable Characters @@ -1537,7 +1647,7 @@ so far. @cindex 8-bit display Normally non-ISO-8859 characters (decimal codes between 128 and 159 inclusive) are displayed as octal escapes. You can change this for -non-standard ``extended'' versions of ISO-8859 character sets by using the +non-standard extended versions of ISO-8859 character sets by using the function @code{standard-display-8bit} in the @code{disp-table} library. There are two ways to input single-byte non-@acronym{ASCII} @@ -1560,28 +1670,28 @@ use these keys; they should simply work. On a text terminal, you should use the command @code{M-x set-keyboard-coding-system} or customize the variable @code{keyboard-coding-system} to specify which coding system your keyboard uses (@pxref{Terminal Coding}). Enabling this feature -will probably require you to use @kbd{ESC} to type Meta characters; +will probably require you to use @key{ESC} to type Meta characters; however, on a console terminal or in @code{xterm}, you can arrange for -Meta to be converted to @kbd{ESC} and still be able type 8-bit -characters present directly on the keyboard or using @kbd{Compose} or -@kbd{AltGr} keys. @xref{User Input}. +Meta to be converted to @key{ESC} and still be able type 8-bit +characters present directly on the keyboard or using @key{Compose} or +@key{AltGr} keys. @xref{User Input}. @kindex C-x 8 @cindex @code{iso-transl} library @cindex compose character @cindex dead character @item -For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose -character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing +You can use the key @kbd{C-x 8} as a compose-character prefix for +entry of non-@acronym{ASCII} Latin-1 and a few other printing characters. @kbd{C-x 8} is good for insertion (in the minibuffer as well as other buffers), for searching, and in any other context where a key sequence is allowed. @kbd{C-x 8} works by loading the @code{iso-transl} library. Once that -library is loaded, the @key{ALT} modifier key, if the keyboard has -one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together +library is loaded, the @key{Alt} modifier key, if the keyboard has +one, serves the same purpose as @kbd{C-x 8}: use @key{Alt} together with an accent character to modify the following letter. In addition, -if the keyboard has keys for the Latin-1 ``dead accent characters'', +if the keyboard has keys for the Latin-1 dead accent characters, they too are defined to compose with the following character, once @code{iso-transl} is loaded. @@ -1599,13 +1709,13 @@ addition to some charsets of its own (such as @code{emacs}, @code{unicode-bmp}, and @code{eight-bit}). All supported characters belong to one or more charsets. - Emacs normally ``does the right thing'' with respect to charsets, so + Emacs normally does the right thing with respect to charsets, so that you don't have to worry about them. However, it is sometimes helpful to know some of the underlying details about charsets. One example is font selection (@pxref{Fonts}). Each language -environment (@pxref{Language Environments}) defines a ``priority -list'' for the various charsets. When searching for a font, Emacs +environment (@pxref{Language Environments}) defines a priority +list for the various charsets. When searching for a font, Emacs initially attempts to find one that can display the highest-priority charsets. For instance, in the Japanese language environment, the charset @code{japanese-jisx0208} has the highest priority, so Emacs @@ -1625,9 +1735,13 @@ internal representation within Emacs. @findex list-character-sets @kbd{M-x list-character-sets} displays a list of all supported charsets. The list gives the names of charsets and additional -information to identity each charset; see the -@url{http://www.itscj.ipsj.or.jp/ISO-IR/, International Register of -Coded Character Sets} for more details. In this list, +information to identity each charset; for more details, see the +@url{https://www.itscj.ipsj.or.jp/itscj_english/iso-ir/ISO-IR.pdf, +ISO International Register of Coded Character Sets to be Used with +Escape Sequences (ISO-IR)} maintained by +the @url{https://www.itscj.ipsj.or.jp/itscj_english/, +Information Processing Society of Japan/Information Technology +Standards Commission of Japan (IPSJ/ITSCJ)}. In this list, charsets are divided into two categories: @dfn{normal charsets} are listed first, followed by @dfn{supplementary charsets}. A supplementary charset is one that is used to define another charset @@ -1704,7 +1818,7 @@ inserting special formatting characters in front of the paragraph. The special character @code{RIGHT-TO-LEFT MARK}, or @sc{rlm}, forces the right-to-left direction on the following paragraph, while @code{LEFT-TO-RIGHT MARK}, or @sc{lrm} forces the left-to-right -direction. (You can use @kbd{C-x 8 RET} to insert these characters.) +direction. (You can use @kbd{C-x 8 @key{RET}} to insert these characters.) In a GUI session, the @sc{lrm} and @sc{rlm} characters display as very thin blank characters; on text terminals they display as blanks. diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 6a7111fa296..1a6a735d3ae 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Packages @@ -30,9 +30,7 @@ third parties. @xref{Package Installation}. For information about turning an Emacs Lisp program into an installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference -Manual}. For information about finding third-party packages and other -Emacs Lisp extensions, @xref{Packages that do not come with -Emacs,,,efaq, GNU Emacs FAQ}. +Manual}. @menu * Package Menu:: Buffer for viewing and managing packages. @@ -59,8 +57,9 @@ The package's version number (e.g., @samp{11.86}). @item The package's status---normally one of @samp{available} (can be -downloaded from the package archive), @samp{installed}, or -@samp{built-in} (included in Emacs by default). +downloaded from the package archive), @samp{installed}, +@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}), +or @samp{built-in} (included in Emacs by default). The status can also be @samp{new}. This is equivalent to @samp{available}, except that it means the package became newly @@ -112,7 +111,7 @@ Remove any installation or deletion mark previously added to the current line by an @kbd{i} or @kbd{d} command. @item U -Mark all package with a newer available version for ``upgrading'' +Mark all package with a newer available version for upgrading (@code{package-menu-mark-upgrades}). This places an installation mark on the new available versions, and a deletion mark on the old installed versions. @@ -126,6 +125,12 @@ dependencies; also, delete all packages marked with @kbd{d} Refresh the package list (@code{package-menu-refresh}). This fetches the list of available packages from the package archive again, and recomputes the package list. + +@item f +Filter the package list (@code{package-menu-filter}). This prompts +for a keyword (e.g., @samp{games}), then shows only the packages +that relate to that keyword. To restore the full package list, +type @kbd{q}. @end table @noindent @@ -161,6 +166,45 @@ directory name of the package archive. You can alter this list if you wish to use third party package archives---but do so at your own risk, and use only third parties that you think you can trust! +@anchor{Package Signing} +@cindex package security +@cindex package signing + The maintainers of package archives can increase the trust that you +can have in their packages by @dfn{signing} them. They generate a +private/public pair of cryptographic keys, and use the private key to +create a @dfn{signature file} for each package. With the public key, you +can use the signature files to verify who created the package, and +that it has not been modified. A valid signature is not a cast-iron +guarantee that a package is not malicious, so you should still +exercise caution. Package archives should provide instructions +on how you can obtain their public key. One way is to download the +key from a server such as @url{http://pgp.mit.edu/}. +Use @kbd{M-x package-import-keyring} to import the key into Emacs. +Emacs stores package keys in the @file{gnupg} subdirectory +of @code{package-user-dir}. +The public key for the GNU package archive is distributed with Emacs, +in the @file{etc/package-keyring.gpg}. Emacs uses it automatically. + +@vindex package-check-signature +@vindex package-unsigned-archives + If the user option @code{package-check-signature} is non-@code{nil}, +Emacs attempts to verify signatures when you install packages. If the +option has the value @code{allow-unsigned}, you can still install a +package that is not signed. If you use some archives that do not sign +their packages, you can add them to the list @code{package-unsigned-archives}. + + For more information on cryptographic keys and signing, +@pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}. +Emacs comes with an interface to GNU Privacy Guard, +@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. + +@vindex package-pinned-packages + If you have more than one package archive enabled, and some of them +offer different versions of the same package, you may find the option +@code{package-pinned-packages} useful. You can add package/archive +pairs to this list, to ensure that the specified package is only ever +downloaded from the specified archive. + Once a package is downloaded and installed, it is @dfn{loaded} into the current Emacs session. Loading a package is not quite the same as loading a Lisp library (@pxref{Lisp Libraries}); its effect varies @@ -188,7 +232,7 @@ in your init file depends on a package). In that case, your init file should call the function @code{package-initialize}. It is up to you to ensure that relevant user options, such as @code{package-load-list} (see below), are set up prior to the @code{package-initialize} call. -You should also set @code{package-enable-at-startup} to @code{nil}, to +This will automatically set @code{package-enable-at-startup} to @code{nil}, to avoid loading the packages again after processing the init file. Alternatively, you may choose to completely inhibit package loading at startup, and invoke the command @kbd{M-x package-initialize} to load @@ -202,7 +246,7 @@ version @var{version} of the package named @var{name}. Here, @var{version} should be a version string (corresponding to a specific version of the package), or @code{t} (which means to load any installed version), or @code{nil} (which means no version; this -``disables'' the package, preventing it from being loaded). A list +disables the package, preventing it from being loaded). A list element can also be the symbol @code{all}, which means to load the latest installed version of any package not named by the other list elements. The default value is just @code{'(all)}. diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi index ae631ff3a1f..8a087acd306 100644 --- a/doc/emacs/picture-xtra.texi +++ b/doc/emacs/picture-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @@ -53,7 +53,7 @@ Additional extensions to Picture mode can be found in @menu * Basic Picture:: Basic concepts and simple commands of Picture Mode. * Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. + after self-inserting characters. * Tabs in Picture:: Various features for tab stops and indentation. * Rectangles in Picture:: Clearing and superimposing rectangles. @end menu @@ -143,10 +143,10 @@ Picture}). @kindex C-c ' @r{(Picture mode)} @kindex C-c / @r{(Picture mode)} @kindex C-c \ @r{(Picture mode)} - Since ``self-inserting'' characters in Picture mode overwrite and move + Since self-inserting characters in Picture mode overwrite and move point, there is no essential restriction on how point should be moved. Normally point moves right, but you can specify any of the eight -orthogonal or diagonal directions for motion after a ``self-inserting'' +orthogonal or diagonal directions for motion after a self-inserting character. This is useful for drawing lines in the buffer. @table @kbd @@ -163,14 +163,14 @@ Move up after insertion (@code{picture-movement-up}). @itemx C-c @key{DOWN} Move down after insertion (@code{picture-movement-down}). @item C-c ` -@itemx C-c @key{HOME} +@itemx C-c @key{Home} Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). @item C-c ' @itemx C-c @key{prior} Move up and right (``northeast'') after insertion (@code{picture-movement-ne}). @item C-c / -@itemx C-c @key{END} +@itemx C-c @key{End} Move down and left (``southwest'') after insertion @*(@code{picture-movement-sw}). @item C-c \ @@ -185,7 +185,7 @@ Move down and right (``southeast'') after insertion @findex picture-motion-reverse Two motion commands move based on the current Picture insertion direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the -same direction as motion after ``insertion'' currently does, while @kbd{C-c +same direction as motion after insertion currently does, while @kbd{C-c C-b} (@code{picture-motion-reverse}) moves in the opposite direction. @node Tabs in Picture diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 8bb851e75a4..1f2c8b1e1c2 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1,5 +1,6 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Programs @@ -35,7 +36,7 @@ Highlight program syntax (@pxref{Font Lock}). * Documentation:: Getting documentation of functions you plan to call. * Hideshow:: Displaying blocks selectively. * Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. +* MixedCase Words:: Dealing with identifiersLikeThis. * Semantic:: Suite of editing tools based on source code parsing. * Misc for Programs:: Other Emacs features useful for editing programs. * C Modes:: Special commands of C, C++, Objective-C, Java, @@ -75,20 +76,20 @@ mode for the C programming language is @code{c-mode}. @cindex VHDL mode @cindex M4 mode @cindex Shell-script mode -@cindex Delphi mode +@cindex OPascal mode @cindex PostScript mode @cindex Conf mode @cindex DNS mode @cindex Javascript mode Emacs has programming language modes for Lisp, Scheme, the -Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi, +Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont -(@TeX{}'s companion for font creation), Modula2, Objective-C, Octave, -Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and -VHDL@. An alternative mode for Perl is called CPerl mode. Modes are +(@TeX{}'s companion for font creation), Modula2, Object Pascal, Objective-C, +Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, +and VHDL@. An alternative mode for Perl is called CPerl mode. Modes are also available for the scripting languages of the common GNU and Unix -shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for -makefiles, DNS master files, and various sorts of configuration files. +shells, and MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, +DNS master files, and various sorts of configuration files. Ideally, Emacs should have a major mode for each programming language that you might want to edit. If it doesn't have a mode for @@ -96,7 +97,6 @@ your favorite language, the mode might be implemented in a package not distributed with Emacs (@pxref{Packages}); or you can contribute one. @kindex DEL @r{(programming modes)} -@findex c-electric-backspace @findex backward-delete-char-untabify In most programming languages, indentation should vary from line to line to illustrate the structure of the program. Therefore, in most @@ -365,9 +365,9 @@ which reformats Lisp objects with nice-looking indentation. @table @kbd @item @key{TAB} Adjust indentation of current line (@code{indent-for-tab-command}). -@item C-j +@item @key{RET} Insert a newline, then adjust indentation of following line -(@code{newline-and-indent}). +(@code{newline}). @end table @kindex TAB @r{(programming modes)} @@ -381,12 +381,9 @@ the current line, based on the indentation and syntactic content of the preceding lines; if the region is active, @key{TAB} indents each line within the region, not just the current line. -@kindex C-j @r{(indenting source code)} -@findex newline-and-indent - The command @kbd{C-j} (@code{newline-and-indent}), which was -documented in @ref{Indentation Commands}, does the same as @key{RET} -followed by @key{TAB}: it inserts a new line, then adjusts the line's -indentation. + The command @key{RET} (@code{newline}), which was documented in +@ref{Inserting Text}, does the same as @kbd{C-j} followed by +@key{TAB}: it inserts a new line, then adjusts the line's indentation. When indenting a line that starts within a parenthetical grouping, Emacs usually places the start of the line under the preceding line @@ -548,7 +545,7 @@ your selected @dfn{style} with the syntactic construct and adds this onto the indentation of the @dfn{anchor statement}. @table @kbd -@item C-c . @key{RET} @var{style} @key{RET} +@item C-c . @var{style} @key{RET} Select a predefined style @var{style} (@code{c-set-style}). @end table @@ -561,7 +558,7 @@ predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, styles are primarily intended for one language, but any of them can be used with any of the languages supported by these modes. To find out what a style looks like, select it and reindent some code, e.g., by -typing @key{C-M-q} at the start of a function definition. +typing @kbd{C-M-q} at the start of a function definition. @kindex C-c . @r{(C mode)} @findex c-set-style @@ -744,10 +741,10 @@ because of the parentheses. The following commands move over groupings delimited by parentheses (or whatever else serves as delimiters in the language you are working with). They ignore strings and comments, including any parentheses -within them, and also ignore parentheses that are ``quoted'' with an +within them, and also ignore parentheses that are quoted with an escape character. These commands are mainly intended for editing programs, but can be useful for editing any text containing -parentheses. They are referred to internally as ``list'' commands +parentheses. They are referred to internally as ``list commands'' because in Lisp these groupings are lists. These commands assume that the starting point is not inside a string @@ -769,7 +766,7 @@ Move down in parenthesis structure (@code{down-list}). @kindex C-M-p @findex forward-list @findex backward-list - The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and + The list commands @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p} (@code{backward-list}) move forward or backward over one (or @var{n}) parenthetical groupings. @@ -799,12 +796,12 @@ make it easy to see how and whether parentheses (or other delimiters) match up. Whenever you type a self-inserting character that is a closing -delimiter, the cursor moves momentarily to the location of the -matching opening delimiter, provided that is on the screen. If it is -not on the screen, Emacs displays some of the text near it in the echo -area. Either way, you can tell which grouping you are closing off. -If the opening delimiter and closing delimiter are mismatched---such -as in @samp{[x)}---a warning message is displayed in the echo area. +delimiter, Emacs briefly indicates the location of the matching +opening delimiter, provided that is on the screen. If it is not on +the screen, Emacs displays some of the text near it in the echo area. +Either way, you can tell which grouping you are closing off. If the +opening delimiter and closing delimiter are mismatched---such as in +@samp{[x)}---a warning message is displayed in the echo area. @vindex blink-matching-paren @vindex blink-matching-paren-distance @@ -814,13 +811,15 @@ as in @samp{[x)}---a warning message is displayed in the echo area. @itemize @bullet @item @code{blink-matching-paren} turns the feature on or off: @code{nil} -disables it, but the default is @code{t} to enable it. +disables it, but the default is @code{t} to enable it. Set it to +@code{jump} to make indication work by momentarily moving the cursor +to the matching opening delimiter. Set it to @code{jump-offscreen} to +make the cursor jump, even if the opening delimiter is off screen. @item -@code{blink-matching-delay} says how many seconds to leave the cursor -on the matching opening delimiter, before bringing it back to the real -location of point. This may be an integer or floating-point number; -the default is 1. +@code{blink-matching-delay} says how many seconds to keep indicating +the matching opening delimiter. This may be an integer or +floating-point number; the default is 1. @item @code{blink-matching-paren-distance} specifies how many characters @@ -844,8 +843,36 @@ show-paren-mode}. Electric Pair mode, a global minor mode, provides a way to easily insert matching delimiters. Whenever you insert an opening delimiter, the matching closing delimiter is automatically inserted as well, -leaving point between the two. To toggle Electric Pair mode, type -@kbd{M-x electric-pair-mode}. +leaving point between the two. Conversely, when you insert a closing +delimiter over an existing one, no inserting takes places and that +position is simply skipped over. These variables control additional +features of Electric Pair mode: + +@itemize @bullet +@item +@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the +default pairing logic balance out the number of opening and closing +delimiters. + +@item +@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes +backspacing between two adjacent delimiters also automatically delete +the closing delimiter. + +@item +@code{electric-pair-open-newline-between-pairs}, when non-@code{nil}, +makes inserting inserting a newline between two adjacent pairs also +automatically open and extra newline after point. + +@item +@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor +mode to skip whitespace forward before deciding whether to skip over +the closing delimiter. +@end itemize + +To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}. To +toggle the mode in a single buffer, use @kbd{M-x +electric-pair-local-mode}. @node Comments @section Manipulating Comments @@ -913,7 +940,7 @@ you use it. When a region is active (@pxref{Mark}), @kbd{M-;} either adds comment delimiters to the region, or removes them. If every line in -the region is already a comment, it ``uncomments'' each of those lines +the region is already a comment, it uncomments each of those lines by removing their comment delimiters. Otherwise, it adds comment delimiters to enclose the text in the region. @@ -1107,7 +1134,7 @@ You can also use @kbd{M-x info-lookup-file} to look for documentation for a file name. If you use @kbd{C-h S} in a major mode that does not support it, -it asks you to specify the ``symbol help mode''. You should enter +it asks you to specify the symbol help mode. You should enter a command such as @code{c-mode} that would select a major mode which @kbd{C-h S} does support. @@ -1194,7 +1221,7 @@ variables that you want to use. @xref{Name Help}. @cindex Eldoc mode @findex eldoc-mode Eldoc is a buffer-local minor mode that helps with looking up Lisp -documention. When it is enabled, the echo area displays some useful +documentation. When it is enabled, the echo area displays some useful information whenever there is a Lisp function or variable at point; for a function, it shows the argument list, and for a variable it shows the first line of the variable's documentation string. To @@ -1309,24 +1336,37 @@ another window. @xref{Completion}. In Text mode and related modes, @kbd{M-@key{TAB}} completes words based on the spell-checker's dictionary. @xref{Spelling}. -@node Glasses -@section Glasses minor mode -@cindex Glasses mode +@node MixedCase Words +@section MixedCase Words @cindex camel case -@findex mode, Glasses - Glasses mode is a buffer-local minor mode that makes it easier to -read mixed-case (or ``CamelCase'') symbols like -@samp{unReadableSymbol}, by altering how they are displayed. By -default, it displays extra underscores between each lower-case letter -and the following capital letter. This does not alter the buffer -text, only how it is displayed. + Some programming styles make use of mixed-case (or ``CamelCase'') +symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend +using underscores to separate words within an identifier, rather than +using case distinctions.) Emacs has various features to make it easier +to deal with such symbols. + +@cindex Glasses mode +@findex mode, Glasses + Glasses mode is a buffer-local minor mode that makes it easier to read +such symbols, by altering how they are displayed. By default, it +displays extra underscores between each lower-case letter and the +following capital letter. This does not alter the buffer text, only how +it is displayed. To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor Modes}). When Glasses mode is enabled, the minor mode indicator @samp{o^o} appears in the mode line. For more information about Glasses mode, type @kbd{C-h P glasses @key{RET}}. +@cindex Subword mode +@findex subword-mode + Subword mode is another buffer-local minor mode. In subword mode, +Emacs's word commands recognize upper case letters in +@samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is +enabled, the minor mode indicator @samp{,} appears in the mode line. +See also the similar @code{superword-mode} (@pxref{Misc for Programs}). + @node Semantic @section Semantic @cindex Semantic package @@ -1341,8 +1381,8 @@ see @ref{Top, Semantic,, semantic, Semantic}. see the Semantic Info manual, which is distributed with Emacs. @end iftex - Most of the ``language aware'' features in Emacs, such as Font Lock -mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular + Most of the language-aware features in Emacs, such as Font Lock +mode (@pxref{Font Lock}), rely on rules of thumb@footnote{Regular expressions and syntax tables.} that usually give good results but are never completely exact. In contrast, the parsers used by Semantic have an exact understanding of programming language syntax. This @@ -1412,6 +1452,19 @@ paragraph commands to work on. Auto Fill mode, if enabled in a programming language major mode, indents the new lines which it creates. +@findex superword-mode + Superword mode is a buffer-local minor mode that causes editing and +motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words. +When Superword mode is enabled, the minor mode indicator +@iftex +@samp{@math{^2}} +@end iftex +@ifnottex +@samp{²} +@end ifnottex +appears in the mode line. See also the similar @code{subword-mode} +(@pxref{MixedCase Words}). + @findex electric-layout-mode Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global minor mode that automatically inserts newlines when you type certain @@ -1425,10 +1478,22 @@ support Outline minor mode (@pxref{Outline Mode}), which can be used with the Foldout package (@pxref{Foldout}). @ifinfo - The ``automatic typing'' features may be useful for writing programs. + The automatic typing features may be useful for writing programs. @xref{Top,,Autotyping, autotype, Autotyping}. @end ifinfo +@findex prettify-symbols-mode + Prettify Symbols mode is a buffer-local minor mode that replaces +certain strings with more attractive versions for display +purposes. For example, in Emacs Lisp mode, it replaces the string +@samp{lambda} with the Greek lambda character @samp{λ}. You may wish +to use this +in non-programming modes as well. You can customize the mode by +adding more entries to @code{prettify-symbols-alist}. There is also a +global version, @code{global-prettify-symbols-mode}, which enables the +mode in all buffers that support it. + + @node C Modes @section C and Related Modes @cindex C mode @@ -1536,7 +1601,7 @@ Move point to the end of the innermost C statement or sentence; like In C mode and related modes, certain printing characters are @dfn{electric}---in addition to inserting themselves, they also reindent the current line, and optionally also insert newlines. The -``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, +electric characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. @@ -1592,20 +1657,20 @@ preprocessor commands. Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}). @item C-c C-d -@itemx C-c C-@key{DELETE} -@itemx C-c @key{DELETE} +@itemx C-c C-@key{Delete} +@itemx C-c @key{Delete} @findex c-hungry-delete-forward @kindex C-c C-d (C Mode) -@kindex C-c C-@key{DELETE} (C Mode) -@kindex C-c @key{DELETE} (C Mode) +@kindex C-c C-@key{Delete} (C Mode) +@kindex C-c @key{Delete} (C Mode) Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}). @end table As an alternative to the above commands, you can enable @dfn{hungry delete mode}. When this feature is enabled (indicated by @samp{/h} in the mode line after the mode name), a single @key{DEL} deletes all -preceding whitespace, not just one space, and a single @kbd{C-c C-d} -(but @emph{not} plain @key{DELETE}) deletes all following whitespace. +preceding whitespace, not just one space, and a single @kbd{C-d} +(but @emph{not} plain @key{Delete}) deletes all following whitespace. @table @kbd @item M-x c-toggle-hungry-state @@ -1624,35 +1689,22 @@ hungry-delete feature is enabled. @subsection Other Commands for C Mode @table @kbd -@item C-c C-w -@itemx M-x subword-mode -@findex subword-mode -Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word -commands recognize upper case letters in -@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by -the flag @samp{/w} on the mode line after the mode name -(e.g., @samp{C/law}). You can even use @kbd{M-x subword-mode} in -non-CC Mode buffers. - -In the GNU project, we recommend using underscores to separate words -within an identifier in C or C++, rather than using case distinctions. - @item M-x c-context-line-break @findex c-context-line-break This command inserts a line break and indents the new line in a manner appropriate to the context. In normal code, it does the work of -@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it -additionally inserts a @samp{\} at the line break, and within comments -it's like @kbd{M-j} (@code{c-indent-new-comment-line}). +@key{RET} (@code{newline}), in a C preprocessor line it additionally +inserts a @samp{\} at the line break, and within comments it's like +@kbd{M-j} (@code{c-indent-new-comment-line}). @code{c-context-line-break} isn't bound to a key by default, but it needs a binding to be useful. The following code will bind it to -@kbd{C-j}. We use @code{c-initialization-hook} here to make sure +@key{RET}. We use @code{c-initialization-hook} here to make sure the keymap is loaded before we try to change it. @example (defun my-bind-clb () - (define-key c-mode-base-map "\C-j" + (define-key c-mode-base-map "\C-m" 'c-context-line-break)) (add-hook 'c-initialization-hook 'my-bind-clb) @end example @@ -1746,7 +1798,7 @@ it work. Hide-ifdef minor mode hides selected code within @samp{#if} and @samp{#ifdef} preprocessor blocks. If you change the variable @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode -``shadows'' preprocessor blocks by displaying them with a less +shadows preprocessor blocks by displaying them with a less prominent face, instead of hiding them entirely. See the documentation string of @code{hide-ifdef-mode} for more information. @@ -1754,7 +1806,7 @@ documentation string of @code{hide-ifdef-mode} for more information. @cindex related files @findex ff-find-related-file @vindex ff-related-file-alist -Find a file ``related'' in a special way to the file visited by the +Find a file related in a special way to the file visited by the current buffer. Typically this will be the header file corresponding to a C/C++ source file, or vice versa. The variable @code{ff-related-file-alist} specifies how to compute related file @@ -1772,6 +1824,7 @@ defines these commands: @table @kbd @item @key{TAB} @code{tab-to-tab-stop}. +@c FIXME: Maybe this should be consistent with other programming modes. @item C-j Insert a newline and then indent using @code{tab-to-tab-stop}. @item : diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index 77545dff5b2..d8841caa311 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Registers @@ -29,6 +29,15 @@ you store something else in that register. To see what register Display a description of what register @var{r} contains. @end table +@vindex register-preview-delay +@cindex preview of registers + All of the commands that prompt for a register will display a +preview window that lists the existing registers (if there are +any) after a short delay. To change the length of the delay, +customize @code{register-preview-delay}. To prevent this display, set +that option to @code{nil}. You can explicitly request a preview +window by pressing @kbd{C-h} or @key{F1}. + @dfn{Bookmarks} record files and positions in them, so you can return to those positions when you look at the file again. Bookmarks are similar in spirit to registers, so they are also documented in @@ -41,6 +50,7 @@ this chapter. * Configuration Registers:: Saving window configurations in registers. * Number Registers:: Numbers in registers. * File Registers:: File names in registers. +* Keyboard Macro Registers:: Keyboard macros in registers. * Bookmarks:: Bookmarks are like registers, but persistent. @end menu @@ -111,7 +121,7 @@ reactivates the mark where it was last set. The mark is deactivated at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}}, the same command with a prefix argument, copies the text into register @var{r} and deletes the text from the buffer as well; you can think of -this as ``moving'' the region text into the register. +this as moving the region text into the register. @findex append-to-register @findex prepend-to-register @@ -139,9 +149,9 @@ during the collection process, you can use the following setting. @kindex C-x r i @findex insert-register @kbd{C-x r i @var{r}} inserts in the buffer the text from register -@var{r}. Normally it leaves point before the text and sets the mark -after, without activating it. With a numeric argument, it instead -puts point after the text and the mark before. +@var{r}. Normally it leaves point after the text and sets the mark +before, without activating it. With a numeric argument, it instead +puts point before the text and the mark after. @node Rectangle Registers @section Saving Rectangles in Registers @@ -172,7 +182,7 @@ rather than a text string, if the register contains a rectangle. @cindex saving window configuration in a register @findex window-configuration-to-register -@findex frame-configuration-to-register +@findex frameset-to-register @kindex C-x r w @kindex C-x r f You can save the window configuration of the selected frame in a @@ -186,7 +196,7 @@ Save the state of the selected frame's windows in register @var{r} (@code{window-configuration-to-register}). @item C-x r f @var{r} Save the state of all frames, including all their windows, in register -@var{r} (@code{frame-configuration-to-register}). +@var{r} (@code{frameset-to-register}). @end table Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. @@ -230,10 +240,10 @@ numeric argument stores zero in the register. If you visit certain file names frequently, you can visit them more conveniently if you put their names in registers. Here's the Lisp code -used to put a file name in a register: +used to put a file @var{name} into register @var{r}: @smallexample -(set-register ?@var{r} '(file . @var{name})) +(set-register @var{r} '(file . @var{name})) @end smallexample @need 3000 @@ -251,6 +261,23 @@ puts the file name shown in register @samp{z}. @var{r}}. (This is the same command used to jump to a position or restore a frame configuration.) +@node Keyboard Macro Registers +@section Keyboard Macro Registers +@cindex saving keyboard macro in a register +@cindex keyboard macros, in registers + +@kindex C-x C-k x +@findex kmacro-to-register + If you need to execute a keyboard macro (@pxref{Keyboard Macros}) +frequently, it is more convenient to put it in a register or save it +(@pxref{Save Keyboard Macro}). @kbd{C-x C-k x @var{r}} +(@code{kmacro-to-register}) stores the last keyboard macro in register +@var{r}. + + To execute the keyboard macro in register @var{r}, type @kbd{C-x r j +@var{r}}. (This is the same command used to jump to a position or +restore a frameset.) + @node Bookmarks @section Bookmarks @cindex bookmarks @@ -258,7 +285,7 @@ restore a frame configuration.) @dfn{Bookmarks} are somewhat like registers in that they record positions you can jump to. Unlike registers, they have long names, and they persist automatically from one Emacs session to the next. The -prototypical use of bookmarks is to record ``where you were reading'' in +prototypical use of bookmarks is to record where you were reading in various files. @table @kbd @@ -317,6 +344,10 @@ a number, says how many bookmark modifications should go by between saving. If you set this variable to @code{nil}, Emacs only saves bookmarks if you explicitly use @kbd{M-x bookmark-save}. +@vindex bookmark-default-file + The variable @code{bookmark-default-file} specifies the file in +which to save bookmarks by default. + @vindex bookmark-search-size Bookmark position values are saved with surrounding context, so that @code{bookmark-jump} can find the proper position even if the file is diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index 67afc29a277..6e2a60b6378 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Rmail @@ -82,7 +82,7 @@ file after merging new mail from an inbox file (@pxref{Rmail Inbox}). You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and saves the Rmail file, then buries the Rmail buffer as well as its summary buffer, if present (@pxref{Rmail Summary}). But there is no -need to ``exit'' formally. If you switch from Rmail to editing in +need to exit formally. If you switch from Rmail to editing in other buffers, and never switch back, you have exited. Just make sure to save the Rmail file eventually (like any other file you have changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save @@ -101,6 +101,7 @@ frequent that it deserves to be easier. @item @key{SPC} Scroll forward (@code{scroll-up-command}). @item @key{DEL} +@itemx S-@key{SPC} Scroll backward (@code{scroll-down-command}). @item . Scroll to start of message (@code{rmail-beginning-of-message}). @@ -110,10 +111,11 @@ Scroll to end of message (@code{rmail-end-of-message}). @kindex SPC @r{(Rmail)} @kindex DEL @r{(Rmail)} +@kindex S-SPC @r{(Rmail)} Since the most common thing to do while reading a message is to scroll through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} -do the same as @kbd{C-v} (@code{scroll-up-command}) and @kbd{M-v} -(@code{scroll-down-command}) respectively. +(or @kbd{S-@key{SPC}}) do the same as @kbd{C-v} (@code{scroll-up-command}) +and @kbd{M-v} (@code{scroll-down-command}) respectively. @kindex . @r{(Rmail)} @kindex / @r{(Rmail)} @@ -367,12 +369,20 @@ the rest of Rmail, since only Rmail operates on the Rmail file. @end enumerate @c FIXME remove this in Emacs 25; won't be relevant any more. +@cindex Babyl files +@cindex mbox files Rmail was originally written to use the Babyl format as its internal format. Since then, we have recognized that the usual inbox format (@samp{mbox}) on Unix and GNU systems is adequate for the job, and so since Emacs 23 Rmail uses that as its internal format. The Rmail file is still separate from the inbox file, even though their format is the same. +@c But this bit should stay in some form. +@vindex rmail-mbox-format +(In fact, there are a few slightly different mbox formats. +The differences are not very important, but you can set the variable +@code{rmail-mbox-format} to tell Rmail which form your system uses. +See that variable's documentation for more details.) @vindex rmail-preserve-inbox When getting new mail, Rmail first copies the new mail from the @@ -743,7 +753,7 @@ in replies, using the variable @code{mail-dont-reply-to-names}. Its value should be a regular expression; any recipients that match are excluded from the @samp{CC} field. They are also excluded from the @samp{To} field, unless this would leave the field empty. If this -variable is nil, then the first time you compose a reply it is +variable is @code{nil}, then the first time you compose a reply it is initialized to a default value that matches your own address. To omit the @samp{CC} field completely for a particular reply, enter @@ -784,7 +794,7 @@ message as the text, and a subject of the form @code{[@var{from}: @var{subject}]}, where @var{from} and @var{subject} are the sender and subject of the original message. All you have to do is fill in the recipients and send. When you forward a message, recipients get a -message which is ``from'' you, and which has the original message in +message which is from you, and which has the original message in its contents. @vindex rmail-enable-mime-composing @@ -807,7 +817,7 @@ following the current one. @findex rmail-resend @dfn{Resending} is an alternative similar to forwarding; the -difference is that resending sends a message that is ``from'' the +difference is that resending sends a message that is from the original sender, just as it reached you---with a few added header fields (@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs @@ -916,8 +926,7 @@ commas. @findex rmail-summary-by-recipients @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) makes a partial summary mentioning only the messages that have one or -more recipients matching the regular expression @var{rcpts}. You can -use commas to separate multiple regular expressions. These are matched +more recipients matching the regular expression @var{rcpts}. This is matched against the @samp{To}, @samp{From}, and @samp{CC} headers (supply a prefix argument to exclude this header). @@ -925,9 +934,8 @@ argument to exclude this header). @findex rmail-summary-by-topic @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic}) makes a partial summary mentioning only the messages whose subjects have -a match for the regular expression @var{topic}. You can use commas to -separate multiple regular expressions. With a prefix argument, the -match is against the whole message, not just the subject. +a match for the regular expression @var{topic}. With a prefix argument, +the match is against the whole message, not just the subject. @kindex C-M-s @r{(Rmail)} @findex rmail-summary-by-regexp @@ -940,8 +948,7 @@ expression @var{regexp}. @findex rmail-summary-by-senders @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders}) makes a partial summary that mentions only the messages whose @samp{From} -fields match the regular expression @var{senders}. You can use commas to -separate multiple regular expressions. +fields match the regular expression @var{senders}. Note that there is only one summary buffer for any Rmail buffer; making any kind of summary discards any previous summary. @@ -952,7 +959,7 @@ making any kind of summary discards any previous summary. use for the summary window. The variable @code{rmail-summary-line-count-flag} controls whether the summary line for a message should include the line count of the message. Setting -this option to nil might speed up the generation of summaries. +this option to @code{nil} might speed up the generation of summaries. @node Rmail Summary Edit @subsection Editing in Summaries @@ -994,10 +1001,10 @@ Here is a list of these commands: @table @kbd @item n -Move to next line, skipping lines saying `deleted', and select its +Move to next line, skipping lines saying ``deleted'', and select its message (@code{rmail-summary-next-msg}). @item p -Move to previous line, skipping lines saying `deleted', and select +Move to previous line, skipping lines saying ``deleted'', and select its message (@code{rmail-summary-previous-msg}). @item M-n Move to next line and select its message (@code{rmail-summary-next-all}). @@ -1206,14 +1213,14 @@ Toggle between @acronym{MIME} display and raw message immediately after its tagline, as part of the Rmail buffer, while @acronym{MIME} parts of other types are represented only by their taglines, with their actual contents hidden. In either case, you can -toggle a @acronym{MIME} part between its ``displayed'' and ``hidden'' +toggle a @acronym{MIME} part between its displayed and hidden states by typing @key{RET} anywhere in the part---or anywhere in its tagline (except for buttons for other actions, if there are any). Type @key{RET} (or click with the mouse) to activate a tagline button, and @key{TAB} to cycle point between tagline buttons. The @kbd{v} (@code{rmail-mime}) command toggles between the default -@acronym{MIME} display described above, and a ``raw'' display showing +@acronym{MIME} display described above, and a raw display showing the undecoded @acronym{MIME} data. With a prefix argument, this command toggles the display of only an entity at point. @@ -1365,8 +1372,8 @@ which applies the code when displaying the text. your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time, Rmail attempts to locate the @code{movemail} program and determine its version. There are two versions of the @code{movemail} program: the -native one, shipped with GNU Emacs (the ``emacs version'') and the one -included in GNU mailutils (the ``mailutils version'', +native one, shipped with GNU Emacs (the Emacs version) and the one +included in GNU mailutils (the mailutils version, @pxref{movemail,,,mailutils,GNU mailutils}). They support the same command line syntax and the same basic subset of options. However, the Mailutils version offers additional features. @@ -1482,7 +1489,7 @@ versions of POP. @cindex POP mailboxes No matter which flavor of @code{movemail} you use, you can specify a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP -@acronym{URL} is a ``file name'' of the form +@acronym{URL} is of the form @samp{pop://@var{username}@@@var{hostname}}, where @var{hostname} is the host name or IP address of the remote mail server and @var{username} is the user name on that server. diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi index 39077921a88..37e0e7e067b 100644 --- a/doc/emacs/screen.texi +++ b/doc/emacs/screen.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Screen @@ -8,7 +8,7 @@ @cindex frame On a graphical display, such as on GNU/Linux using the X Window -System, Emacs occupies a ``graphical window''. On a text terminal, +System, Emacs occupies a graphical window. On a text terminal, Emacs occupies the entire terminal screen. We will use the term @dfn{frame} to mean a graphical window or terminal screen occupied by Emacs. Emacs behaves very similarly on both kinds of frames. It @@ -27,7 +27,7 @@ information when Emacs asks for it. above the echo area, is called @dfn{the window}. Henceforth in this manual, we will use the word ``window'' in this sense. Graphical display systems commonly use the word ``window'' with a different -meaning; but, as stated above, we refer to those ``graphical windows'' +meaning; but, as stated above, we refer to those graphical windows as ``frames''. An Emacs window is where the @dfn{buffer}---the text you are @@ -123,7 +123,7 @@ beeping or by flashing the screen. you what the command has done, or to provide you with some specific information. These @dfn{informative} messages, unlike error messages, are not accompanied with a beep or flash. For example, @kbd{C-x =} -(hold down @key{CTRL} and type @kbd{x}, then let go of @key{CTRL} and +(hold down @key{Ctrl} and type @kbd{x}, then let go of @key{Ctrl} and type @kbd{=}) displays a message describing the character at point, its position in the buffer, and its current column in the window. Commands that take a long time often display messages ending in @@ -206,11 +206,11 @@ terminal output. Furthermore, if you are using an input method, string is displayed, that indicates a nontrivial end-of-line convention for encoding a file. Usually, lines of text are separated by @dfn{newline characters} in a file, but two other conventions are -sometimes used. The MS-DOS convention uses a ``carriage-return'' -character followed by a ``linefeed'' character; when editing such +sometimes used. The MS-DOS convention uses a carriage-return +character followed by a linefeed character; when editing such files, the colon changes to either a backslash (@samp{\}) or @samp{(DOS)}, depending on the operating system. Another convention, -employed by older Macintosh systems, uses a ``carriage-return'' +employed by older Macintosh systems, uses a carriage-return character instead of a newline; when editing such files, the colon changes to either a forward slash (@samp{/}) or @samp{(Mac)}. On some systems, Emacs displays @samp{(Unix)} instead of the colon for files @@ -219,7 +219,7 @@ that use newline as the line separator. The next element on the mode line is the string indicated by @var{ch}. This shows two dashes (@samp{--}) if the buffer displayed in the window has the same contents as the corresponding file on the -disk; i.e., if the buffer is ``unmodified''. If the buffer is +disk; i.e., if the buffer is unmodified. If the buffer is modified, it shows two stars (@samp{**}). For a read-only buffer, it shows @samp{%*} if the buffer is modified, and @samp{%%} otherwise. @@ -285,15 +285,11 @@ performs various commands. @xref{Mode Line Mouse}. can use to perform common operations. There's no need to list them here, as you can more easily see them yourself. -@kindex M-` -@kindex F10 -@findex tmm-menubar -@findex menu-bar-open - On a graphical display, you can use the mouse to choose a command -from the menu bar. An arrow on the right edge of a menu item means it -leads to a subsidiary menu, or @dfn{submenu}. A @samp{...} at the end -of a menu item means that the command will prompt you for further -input before it actually does anything. + On a display that supports a mouse, you can use the mouse to choose a +command from the menu bar. An arrow on the right edge of a menu item +means it leads to a subsidiary menu, or @dfn{submenu}. A @samp{...} +at the end of a menu item means that the command will prompt you for +further input before it actually does anything. Some of the commands in the menu bar have ordinary key bindings as well; if so, a key binding is shown in parentheses after the item @@ -301,18 +297,28 @@ itself. To view the full command name and documentation for a menu item, type @kbd{C-h k}, and then select the menu bar with the mouse in the usual way (@pxref{Key Help}). +@kindex F10 +@findex menu-bar-open +@cindex menu bar access using keyboard Instead of using the mouse, you can also invoke the first menu bar item by pressing @key{F10} (to run the command @code{menu-bar-open}). You can then navigate the menus with the arrow keys. To activate a selected menu item, press @key{RET}; to cancel menu navigation, press -@key{ESC}. - - On a text terminal, you can use the menu bar by typing @kbd{M-`} or -@key{F10} (these run the command @code{tmm-menubar}). This lets you -select a menu item with the keyboard. A provisional choice appears in -the echo area. You can use the up and down arrow keys to move through -the menu to different items, and then you can type @key{RET} to select -the item. Each menu item is also designated by a letter or digit -(usually the initial of some word in the item's name). This letter or -digit is separated from the item name by @samp{==>}. You can type the -item's letter or digit to select the item. +@kbd{C-g} or @kbd{@key{ESC} @key{ESC} @key{ESC}}. + +@kindex M-` +@findex tmm-menubar +@vindex tty-menu-open-use-tmm + On a text terminal, you can optionally access the menu-bar menus in +the echo area. To this end, customize the variable +@code{tty-menu-open-use-tmm} to a non-@code{nil} value. Then typing +@key{F10} will run the command @code{tmm-menubar} instead of dropping +down the menu. (You can also type @kbd{M-`}, which always invokes +@code{tmm-menubar}.) @code{tmm-menubar} lets you select a menu item +with the keyboard. A provisional choice appears in the echo area. +You can use the up and down arrow keys to move through the menu to +different items, and then you can type @key{RET} to select the item. +Each menu item is also designated by a letter or digit (usually the +initial of some word in the item's name). This letter or digit is +separated from the item name by @samp{==>}. You can type the item's +letter or digit to select the item. diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index ead7c3cbf16..ae275d1ca67 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Search @@ -80,12 +80,13 @@ past the end of the next occurrence of those characters in the buffer. For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the cursor after the first @samp{F} that occurs in the buffer after the -starting point. Then if you then type @kbd{O}, the cursor moves to -just after the first @samp{FO}; the @samp{F} in that @samp{FO} might -not be the first @samp{F} previously found. After another @kbd{O}, -the cursor moves to just after the first @samp{FOO}. +starting point. If you then type @kbd{O}, the cursor moves to just +after the first @samp{FO}; the @samp{F} in that @samp{FO} might not be +the first @samp{F} previously found. After another @kbd{O}, the +cursor moves to just after the first @samp{FOO}. @cindex faces for highlighting search matches +@cindex isearch face At each step, Emacs highlights the @dfn{current match}---the buffer text that matches the search string---using the @code{isearch} face (@pxref{Faces}). The current search string is also displayed in the @@ -145,8 +146,8 @@ you don't like this feature, you can disable it by setting After exiting a search, you can search for the same string again by typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that -invokes incremental search, and the second @kbd{C-s} means ``search -again''. Similarly, @kbd{C-r C-r} searches backward for the last +invokes incremental search, and the second @kbd{C-s} means to search +again. Similarly, @kbd{C-r C-r} searches backward for the last search string. In determining the last search string, it doesn't matter whether the string was searched for with @kbd{C-s} or @kbd{C-r}. @@ -226,15 +227,17 @@ special effects. By default, incremental search performs @dfn{lax space matching}: each space, or sequence of spaces, matches any sequence of one or more spaces in the text. Hence, @samp{foo bar} matches @samp{foo bar}, -@samp{foo bar}, @samp{foo bar}, and so on (but not @samp{foobar}). -More precisely, Emacs matches each sequence of space characters in the -search string to a regular expression specified by the variable -@code{search-whitespace-regexp}. For example, set it to -@samp{"[[:space:]\n]+"} to make spaces match sequences of newlines as -well as spaces. To toggle lax space matching, type @kbd{M-s SPC} +@samp{foo@w{ }bar}, @samp{foo@w{ }bar}, and so on (but not +@samp{foobar}). More precisely, Emacs matches each sequence of space +characters in the search string to a regular expression specified by +the variable @code{search-whitespace-regexp}. For example, to make +spaces match sequences of newlines as well as spaces, set it to +@samp{"[[:space:]\n]+"}. + + To toggle lax space matching, type @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}). To disable this feature entirely, change @code{search-whitespace-regexp} to @code{nil}; then -each space in the search string matches exactly one space +each space in the search string matches exactly one space. If the search string you entered contains only lower-case letters, the search is case-insensitive; as long as an upper-case letter exists @@ -242,17 +245,37 @@ in the search string, the search becomes case-sensitive. If you delete the upper-case character from the search string, it ceases to have this effect. @xref{Search Case}. +@cindex invisible text, searching for +@kindex M-s i @r{(Incremental search)} +@findex isearch-toggle-invisible + To toggle whether or not invisible text is searched, type +@kbd{M-s i} (@code{isearch-toggle-invisible}). @xref{Outline Search}. + To search for a newline character, type @kbd{C-j}. - To search for other control characters, such as @key{control-S}, -quote it by typing @kbd{C-q} first (@pxref{Inserting Text}). To -search for non-@acronym{ASCII} characters, you can either use -@kbd{C-q} and enter its octal code, or use an input method -(@pxref{Input Methods}). If an input method is enabled in the current -buffer when you start the search, you can use it in the search string -also. While typing the search string, you can toggle the input method -with the command @kbd{C-\} (@code{isearch-toggle-input-method}). You -can also turn on a non-default input method with @kbd{C-^} + To search for non-@acronym{ASCII} characters, use one of the +following methods: + +@itemize @bullet +@item +Type @kbd{C-q}, followed by a non-graphic character or a sequence of +octal digits. This adds a character to the search string, similar to +inserting into a buffer using @kbd{C-q} (@pxref{Inserting Text}). For +example, @kbd{C-q C-s} during incremental search adds the +@samp{control-S} character to the search string. + +@item +Type @kbd{C-x 8 @key{RET}}, followed by a Unicode name or code-point. +This adds the specified character into the search string, similar to +the usual @code{insert-char} command (@pxref{Inserting Text}). + +@item +Use an input method (@pxref{Input Methods}). If an input method is +enabled in the current buffer when you start the search, you can use +it in the search string also. While typing the search string, you can +toggle the input method with @kbd{C-\} +(@code{isearch-toggle-input-method}). You can also turn on a +non-default input method with @kbd{C-^} (@code{isearch-toggle-specified-input-method}), which prompts for the name of the input method. When an input method is active during incremental search, the search prompt includes the input method @@ -268,12 +291,13 @@ I-search [@var{im}]: where @var{im} is the mnemonic of the active input method. Any input method you enable during incremental search remains enabled in the current buffer afterwards. +@end itemize @kindex M-% @r{(Incremental search)} Typing @kbd{M-%} in incremental search invokes @code{query-replace} or @code{query-replace-regexp} (depending on search mode) with the -current search string used as the string to replace. @xref{Query -Replace}. +current search string used as the string to replace. A negative +prefix argument means to replace backward. @xref{Query Replace}. @kindex M-TAB @r{(Incremental search)} Typing @kbd{M-@key{TAB}} in incremental search invokes @@ -315,7 +339,8 @@ of whether to copy a character or a word is heuristic.) @findex isearch-yank-line Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest of the current line to the search string. If point is already at the -end of a line, it appends the next line. +end of a line, it appends the next line. With a prefix argument +@var{n}, it appends the next @var{n} lines. If the search is currently case-insensitive, both @kbd{C-w} and @kbd{M-s C-e} convert the text they copy to lower case, so that the @@ -398,7 +423,7 @@ because that is used to display the minibuffer. If an incremental search fails in the minibuffer, it tries searching the minibuffer history. @xref{Minibuffer History}. You can visualize -the minibuffer and its history as a series of ``pages'', with the +the minibuffer and its history as a series of pages, with the earliest history element on the first page and the current minibuffer on the last page. A forward search, @kbd{C-s}, searches forward to later pages; a reverse search, @kbd{C-r}, searches backwards to @@ -481,12 +506,13 @@ These run the commands @code{word-search-forward} and @code{word-search-backward} respectively. Incremental and nonincremental word searches differ slightly in the -way they find a match. In a nonincremental word search, the last word -in the search string must exactly match a whole word. In an -incremental word search, the matching is more lax: the last word in -the search string can match part of a word, so that the matching -proceeds incrementally as you type. This additional laxity does not -apply to the lazy highlight, which always matches whole words. +way they find a match. In a nonincremental word search, each word in +the search string must exactly match a whole word. In an incremental +word search, the matching is more lax: while you are typing the search +string, its first and last words need not match whole words. This is +so that the matching can proceed incrementally as you type. This +additional laxity does not apply to the lazy highlight +(@pxref{Incremental Search}), which always matches whole words. @node Symbol Search @section Symbol Search @@ -506,6 +532,9 @@ searching source code. If incremental search is active, toggle symbol search mode (@code{isearch-toggle-symbol}); otherwise, begin an incremental forward symbol search (@code{isearch-forward-symbol}). +@item M-s . +Start a symbol incremental search forward with the symbol found near +point added to the search string initially. @item M-s _ @key{RET} @var{symbol} @key{RET} Search forward for @var{symbol}, nonincrementally. @item M-s _ C-r @key{RET} @var{symbol} @key{RET} @@ -513,9 +542,12 @@ Search backward for @var{symbol}, nonincrementally. @end table @kindex M-s _ +@kindex M-s . @findex isearch-forward-symbol - To begin a forward incremental symbol search, type @kbd{M-s _}. If -incremental search is not already active, this runs the command +@findex isearch-forward-symbol-at-point + To begin a forward incremental symbol search, type @kbd{M-s _} (or +@kbd{M-s .} if the symbol to search is near point). If incremental +search is not already active, this runs the command @code{isearch-forward-symbol}. If incremental search is already active, @kbd{M-s _} switches to a symbol search, preserving the direction of the search and the current search string; you can disable @@ -571,12 +603,13 @@ Incremental regexp and non-regexp searches have independent defaults. They also have separate search rings, which you can access with @kbd{M-p} and @kbd{M-n}. - Just as in ordinary incremental search, any @key{SPC} typed in -incremental regexp search matches any sequence of one or more -whitespace characters. The variable @code{search-whitespace-regexp} -specifies the regexp for the lax space matching, and @kbd{M-s SPC} -(@code{isearch-toggle-lax-whitespace}) toggles the feature. -@xref{Special Isearch}. + Unlike ordinary incremental search, incremental regexp search +do not use lax space matching by default. To toggle this feature +use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}). +Then any @key{SPC} typed in incremental regexp search will match +any sequence of one or more whitespace characters. The variable +@code{search-whitespace-regexp} specifies the regexp for the lax +space matching. @xref{Special Isearch}. In some cases, adding characters to the regexp in an incremental regexp search can make the cursor move back and start again. For @@ -668,7 +701,7 @@ it possible to match the rest of the pattern. For example, in matching tries to match all three @samp{a}s; but the rest of the pattern is @samp{ar} and there is only @samp{r} left to match, so this try fails. The next alternative is for @samp{a*} to match only two @samp{a}s. -With this choice, the rest of the regexp matches successfully.@refill +With this choice, the rest of the regexp matches successfully. @item @kbd{+} is a postfix operator, similar to @samp{*} except that it must match @@ -830,11 +863,11 @@ either @var{a} matches it or @var{b} matches it. It works by trying to match @var{a}, and if that fails, by trying to match @var{b}. Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill +but no other string. @samp{\|} applies to the largest possible surrounding expressions. Only a surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill +@samp{\|}. Full backtracking capability exists to handle multiple uses of @samp{\|}. @@ -850,7 +883,7 @@ Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. To enclose a complicated expression for the postfix operators @samp{*}, @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any (zero or more) number of @samp{na} -strings.@refill +strings. @item To record a matched substring for future reference. @@ -860,15 +893,15 @@ This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that is assigned as a second meaning to the same @samp{\( @dots{} \)} construct. In practice there is usually no conflict between the two meanings; when there is -a conflict, you can use a ``shy'' group. +a conflict, you can use a shy group. @item \(?: @dots{} \) @cindex shy group, in regexp -specifies a ``shy'' group that does not record the matched substring; -you can't refer back to it with @samp{\@var{d}}. This is useful -in mechanically combining regular expressions, so that you -can add groups for syntactic purposes without interfering with -the numbering of the groups that are meant to be referred to. +specifies a shy group that does not record the matched substring; +you can't refer back to it with @samp{\@var{d}} (see below). This is +useful in mechanically combining regular expressions, so that you can +add groups for syntactic purposes without interfering with the +numbering of the groups that are meant to be referred to. @item \@var{d} @cindex back reference, in regexp @@ -912,7 +945,7 @@ matches the empty string, but only at point. matches the empty string, but only at the beginning or end of a word. Thus, @samp{\bfoo\b} matches any occurrence of @samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill +@samp{ball} or @samp{balls} as a separate word. @samp{\b} matches at the beginning or end of the buffer regardless of what text appears next to it. @@ -1005,7 +1038,7 @@ searching through, if you specify the text in lower case. Thus, if you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} also match. Regexps, and in particular character sets, behave likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or -@samp{B}.@refill +@samp{B}. An upper-case letter anywhere in the incremental search string makes the search case-sensitive. Thus, searching for @samp{Foo} does not find @@ -1013,12 +1046,6 @@ the search case-sensitive. Thus, searching for @samp{Foo} does not find well as to string search. The effect ceases if you delete the upper-case letter from the search string. - Typing @kbd{M-c} within an incremental search toggles the case -sensitivity of that search. The effect does not extend beyond the -current incremental search to the next one, but it does override the -effect of adding or removing an upper-case letter in the current -search. - @vindex case-fold-search If you set the variable @code{case-fold-search} to @code{nil}, then all letters must match exactly, including case. This is a per-buffer @@ -1028,6 +1055,13 @@ This variable applies to nonincremental searches also, including those performed by the replace commands (@pxref{Replace}) and the minibuffer history matching commands (@pxref{Minibuffer History}). +@c isearch-toggle-case-fold + Typing @kbd{M-c} within an incremental search toggles the case +sensitivity of that search. The effect does not extend beyond the +current incremental search to the next one, but it does override the +effect of adding or removing an upper-case letter in the current +search. + Several related variables control case-sensitivity of searching and matching for specific commands or activities. For instance, @code{tags-case-fold-search} controls case sensitivity for @@ -1237,7 +1271,8 @@ occurrence and asks you whether to replace it. Aside from querying, (@pxref{Unconditional Replace}). In particular, it preserves case provided @code{case-replace} is non-@code{nil}, as it normally is (@pxref{Replacement and Case}). A numeric argument means to consider -only occurrences that are bounded by word-delimiter characters. +only occurrences that are bounded by word-delimiter characters. A +negative prefix argument replaces backward. @kindex C-M-% @findex query-replace-regexp @@ -1246,6 +1281,8 @@ It works like @code{replace-regexp} except that it queries like @code{query-replace}. @cindex faces for highlighting query replace +@cindex query-replace face +@cindex lazy-highlight face These commands highlight the current match using the face @code{query-replace}. They highlight other matches using @code{lazy-highlight} just like incremental search (@pxref{Incremental @@ -1303,15 +1340,15 @@ to replace all remaining occurrences without asking again. @item Y @r{(Upper-case)} to replace all remaining occurrences in all remaining buffers in -multi-buffer replacements (like the Dired `Q' command which performs +multi-buffer replacements (like the Dired @key{Q} command that performs query replace on selected files). It answers this question and all -subsequent questions in the series with "yes", without further +subsequent questions in the series with ``yes'', without further user interaction. @item N @r{(Upper-case)} to skip to the next buffer in multi-buffer replacements without replacing remaining occurrences in the current buffer. It answers -this question "no", gives up on the questions for the current buffer, +this question ``no'', gives up on the questions for the current buffer, and continues to the next buffer in the sequence. @item ^ @@ -1360,6 +1397,10 @@ line. used the minibuffer to read its arguments. @xref{Repetition, C-x ESC ESC}. +@cindex invisible text, and query-replace + The option @code{search-invisible} determines how @code{query-replace} +treats invisible text. @xref{Outline Search}. + @xref{Operating on Files}, for the Dired @kbd{Q} command which performs query replace on selected files. See also @ref{Transforming File Names}, for Dired commands to rename, copy, or link files by @@ -1395,6 +1436,22 @@ matching that regexp. This command is just like @code{multi-isearch-buffers}, except it performs an incremental regexp search. +@item M-x multi-isearch-files +Prompt for one or more file names, ending with @key{RET}; then, +begin a multi-file incremental search in those files. (If the +search fails in one file, the next @kbd{C-s} tries searching the +next specified file, and so forth.) With a prefix argument, prompt +for a regexp and begin a multi-file incremental search in files +matching that regexp. + +@item M-x multi-isearch-files-regexp +This command is just like @code{multi-isearch-files}, except it +performs an incremental regexp search. + +In some modes that set the buffer-local variable +@code{multi-isearch-next-buffer-function} (e.g., in Change Log mode) +a multi-file incremental search is activated automatically. + @cindex Occur mode @cindex mode, Occur @item M-x occur diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi index 1402d8a85be..c5ca73b40a8 100644 --- a/doc/emacs/sending.texi +++ b/doc/emacs/sending.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Sending Mail @@ -136,7 +136,7 @@ Use both address and full name, as in:@* Use both address and full name, as in:@* @samp{Elvis Parsley <king@@grassland.com>}. @item any other value -Use @code{angles} normally. But if the address must be ``quoted'' to +Use @code{angles} normally. But if the address must be quoted to remain syntactically valid under the @code{angles} format but not under the @code{parens} format, use @code{parens} instead. This is the default. @@ -159,7 +159,7 @@ directed at them. @item BCC Additional mailing address(es) to send the message to, which should -not appear in the header of the message actually sent. ``BCC'' stands +not appear in the header of the message actually sent. @samp{BCC} stands for @dfn{blind carbon copies}. @item FCC @@ -256,7 +256,7 @@ This means that @var{nick} should expand into @var{fulladdresses}, where @var{fulladdresses} can be either a single address, or multiple addresses separated with spaces. For instance, to make @code{maingnu} stand for @code{gnu@@gnu.org} plus a local address of your own, put in -this line:@refill +this line: @example alias maingnu gnu@@gnu.org local-gnu @@ -276,7 +276,7 @@ of the address, such as the person's full name. Emacs puts them in if they are needed. For instance, it inserts the above address as @samp{"John Q. Smith" <none@@example.com>}. - Emacs also recognizes ``include'' commands in @file{.mailrc}. They + Emacs also recognizes include commands in @file{.mailrc}. They look like this: @example @@ -341,7 +341,7 @@ Send the message, and leave the mail buffer selected (@code{message-send}). @vindex message-kill-buffer-on-exit The usual command to send a message is @kbd{C-c C-c} (@code{mail-send-and-exit}). This sends the message and then -``buries'' the mail buffer, putting it at the lowest priority for +buries the mail buffer, putting it at the lowest priority for reselection. If you want it to kill the mail buffer instead, change the variable @code{message-kill-buffer-on-exit} to @code{t}. @@ -568,8 +568,8 @@ was yanked, but it checks the text that you yourself inserted (it looks for indentation or @code{mail-yank-prefix} to distinguish the cited lines from your input). @xref{Spelling}. -@vindex mail-mode-hook -@vindex mail-setup-hook +@vindex message-mode-hook +@vindex message-setup-hook Turning on Message mode (which @kbd{C-x m} does automatically) runs the normal hooks @code{text-mode-hook} and @code{message-mode-hook}. Initializing a new outgoing message runs the normal hook @@ -592,31 +592,37 @@ are inserted. @section Mail Signature @cindex mail signature -@vindex mail-signature-file -@vindex mail-signature +@vindex message-signature-file +@vindex message-signature You can add a standard piece of text---your @dfn{mail signature}---to the end of every message. This signature may contain information such as your telephone number or your physical location. -The variable @code{mail-signature} determines how Emacs handles the +The variable @code{message-signature} determines how Emacs handles the mail signature. - The default value of @code{mail-signature} is @code{t}; this means -to look for your mail signature in the file @file{~/.signature}. If -this file exists, its contents are automatically inserted into the end -of the mail buffer. You can change the signature file via the -variable @code{mail-signature-file}. + The default value of @code{message-signature} is @code{t}; this +means to look for your mail signature in the file @file{~/.signature}. +If this file exists, its contents are automatically inserted into the +end of the mail buffer. You can change the signature file via the +variable @code{message-signature-file}. - If you change @code{mail-signature} to a string, that specifies the -text of the signature directly. + If you change @code{message-signature} to a string, that specifies +the text of the signature directly. @kindex C-c C-w @r{(Message mode)} @findex message-insert-signature - If you change @code{mail-signature} to @code{nil}, Emacs will not + If you change @code{message-signature} to @code{nil}, Emacs will not insert your mail signature automatically. You can insert your mail signature by typing @kbd{C-c C-w} (@code{message-insert-signature}) in the mail buffer. Emacs will look for your signature in the signature file. +@vindex mail-signature-file +@vindex mail-signature + If you use Mail mode rather than Message mode for composing your +mail, the corresponding variables that determine how your signature is +sent are @code{mail-signature} and @code{mail-signature-file} instead. + By convention, a mail signature should be marked by a line whose contents are @samp{-- }. If your signature lacks this prefix, it is added for you. The remainder of your signature should be no more than @@ -642,7 +648,7 @@ it all. Whether or not this is true, it at least amuses some people. @findex fortune-to-signature @cindex fortune cookies - You can use the @code{fortune} program to put a ``fortune cookie'' + You can use the @code{fortune} program to put a fortune cookie message into outgoing mail. To do this, add @code{fortune-to-signature} to @code{mail-setup-hook}: diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index e5743b064fb..bab660e1e10 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -1,5 +1,6 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Text @@ -33,7 +34,7 @@ publish them in many formats. @cindex mode, XML @cindex mode, nXML @findex nxml-mode - Emacs has other major modes for text which contains ``embedded'' + Emacs has other major modes for text which contains embedded commands, such as @TeX{} and @LaTeX{} (@pxref{TeX Mode}); HTML and SGML (@pxref{HTML Mode}); XML @ifinfo @@ -45,9 +46,8 @@ SGML (@pxref{HTML Mode}); XML and Groff and Nroff (@pxref{Nroff Mode}). @cindex ASCII art - If you need to edit pictures made out of text characters (commonly -referred to as ``ASCII art''), use Picture mode, a special major mode -for editing such pictures. + If you need to edit ASCII art pictures made out of text characters, +use Picture mode, a special major mode for editing such pictures. @iftex @xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}. @end iftex @@ -60,7 +60,7 @@ for editing such pictures. @cindex templates @cindex autotyping @cindex automatic typing - The ``automatic typing'' features may be useful when writing text. + The automatic typing features may be useful when writing text. @inforef{Top,The Autotype Manual,autotype}. @end ifinfo @@ -69,6 +69,7 @@ for editing such pictures. * Sentences:: Moving over and killing sentences. * Paragraphs:: Moving over paragraphs. * Pages:: Moving over pages. +* Quotation Marks:: Inserting quotation marks. * Filling:: Filling or justifying text. * Case:: Changing the case of text. * Text Mode:: The major modes for editing text files. @@ -77,7 +78,7 @@ for editing such pictures. * TeX Mode:: Editing TeX and LaTeX files. * HTML Mode:: Editing HTML and SGML files. * Nroff Mode:: Editing input to the nroff formatter. -* Enriched Text:: Editing text "enriched" with fonts, colors, etc. +* Enriched Text:: Editing text enriched with fonts, colors, etc. * Text Based Tables:: Commands for editing text-based tables. * Two-Column:: Splitting text columns into separate windows. @end menu @@ -116,7 +117,7 @@ cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}. @findex backward-word The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) move forward and backward over words. These -@key{Meta}-based key sequences are analogous to the key sequences +@key{META}-based key sequences are analogous to the key sequences @kbd{C-f} and @kbd{C-b}, which move over single characters. The analogy extends to numeric arguments, which serve as repeat counts. @kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with @@ -330,7 +331,7 @@ in Fundamental mode, @code{paragraph-start} is @w{@code{"\f\\|[ @cindex formfeed character Within some text files, text is divided into @dfn{pages} delimited by the @dfn{formfeed character} (@acronym{ASCII} code 12, also denoted -as @key{control-L}), which is displayed in Emacs as the escape +as @samp{control-L}), which is displayed in Emacs as the escape sequence @samp{^L} (@pxref{Text Display}). Traditionally, when such text files are printed to hardcopy, each formfeed character forces a page break. Most Emacs commands treat it just like any other @@ -404,6 +405,48 @@ that separates pages (@pxref{Regexps}). The normal value of this variable is @code{"^\f"}, which matches a formfeed character at the beginning of a line. +@node Quotation Marks +@section Quotation Marks +@cindex Quotation marks +@cindex Electric Quote mode +@cindex mode, Electric Quote +@cindex curly quotes +@cindex curved quotes +@findex electric-quote-mode + One common way to quote is the typewriter convention, which quotes +using straight apostrophes @t{'like this'} or double-quotes @t{"like +this"}. Another common way is the curved quote convention, which uses +left and right single or double quotation marks @t{‘like this’} or +@t{“like this”}. In text files, typewriter quotes are simple and +portable; curved quotes are less ambiguous and typically look nicer. + + Electric Quote mode makes it easier to type curved quotes. As you +type characters it optionally converts @t{`} to @t{‘}, @t{'} to @t{’}, +@t{``} to @t{“}, and @t{''} to @t{”}. These conversions are +suppressed in buffers whose coding systems cannot represent curved +quote characters. + +@vindex electric-quote-paragraph +@vindex electric-quote-comment +@vindex electric-quote-string + You can customize the behavior of Electric Quote mode by customizing +variables that control where it is active. It is active in text +paragraphs if @code{electric-quote-paragraph} is non-@code{nil}, in +programming-language comments if @code{electric-quote-comment} is +non-@code{nil}, and in programming-language strings if +@code{electric-quote-string} is non-@code{nil}. The default is +@code{nil} for @code{electric-quote-string} and @code{t} for the other +variables. + + Electric Quote mode is disabled by default. To toggle it, type +@kbd{M-x electric-quote-mode}. To toggle it in a single buffer, use +@kbd{M-x electric-quote-local-mode}. To suppress it for a single use, +type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To +insert a curved quote even when Electric Quote is disabled or +inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for +@t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}. +@xref{Inserting Text}. + @node Filling @section Filling Text @cindex filling text @@ -562,10 +605,11 @@ customize the abnormal hook variable @code{fill-nobreak-predicate} (@pxref{Hooks}). Each function in this hook is called with no arguments, with point positioned where Emacs is considering breaking a line. If a function returns a non-@code{nil} value, Emacs will not -break the line there. Two functions you can use are +break the line there. Functions you can use there include: @code{fill-single-word-nobreak-p} (don't break after the first word of -a sentence or before the last) and @code{fill-french-nobreak-p} (don't -break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). +a sentence or before the last); @code{fill-single-char-nobreak-p} +(don't break after a one-letter word); and @code{fill-french-nobreak-p} +(don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). @node Fill Prefix @subsection The Fill Prefix @@ -639,7 +683,7 @@ delimiter on each line. prefix for each paragraph automatically. This command divides the region into paragraphs, treating every change in the amount of indentation as the start of a new paragraph, and fills each of these -paragraphs. Thus, all the lines in one ``paragraph'' have the same +paragraphs. Thus, all the lines in one paragraph have the same amount of indentation. That indentation serves as the fill prefix for that paragraph. @@ -1029,7 +1073,7 @@ revealing parts of the buffer, based on the outline structure. These commands are not undoable; their effects are simply not recorded by the undo mechanism, so you can undo right past them (@pxref{Undo}). - Many of these commands act on the ``current'' heading line. If + Many of these commands act on the current heading line. If point is on a heading line, that is the current heading line; if point is on a body line, the current heading line is the nearest preceding header line. @@ -1123,12 +1167,18 @@ though these are technically body lines). @kbd{C-c C-a} numeric argument @var{n}, it hides everything except the top @var{n} levels of heading lines. +@anchor{Outline Search} @findex reveal-mode +@vindex search-invisible When incremental search finds text that is hidden by Outline mode, it makes that part of the buffer visible. If you exit the search at -that position, the text remains visible. You can also automatically -make text visible as you navigate in it by using Reveal mode (@kbd{M-x -reveal-mode}), a buffer-local minor mode. +that position, the text remains visible. To toggle whether or not +an active incremental search can match hidden text, type @kbd{M-s i}. +To change the default for future searches, customize the option +@code{search-invisible}. (This option also affects how @code{query-replace} +and related functions treat hidden text, @pxref{Query Replace}.) +You can also automatically make text visible as you navigate in it by +using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode. @node Outline Views @subsection Viewing One Outline in Multiple Views @@ -1155,7 +1205,7 @@ buffers. @cindex folding editing The Foldout package extends Outline mode and Outline minor mode with -``folding'' commands. The idea of folding is that you zoom in on a +folding commands. The idea of folding is that you zoom in on a nested portion of the outline, while hiding its relatives at higher levels. @@ -1185,7 +1235,7 @@ show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}. While you're zoomed in, you can still use Outline mode's exposure and hiding functions without disturbing Foldout. Also, since the buffer is -narrowed, ``global'' editing actions will only affect text under the +narrowed, global editing actions will only affect text under the zoomed-in heading. This is useful for restricting changes to a particular chapter or section of your document. @@ -1243,7 +1293,7 @@ quad click: exit all folds and hide text. @c FIXME not marked as a user variable @vindex foldout-mouse-modifiers You can specify different modifier keys (instead of -@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if +@kbd{@key{Ctrl}-@key{META}-}) by setting @code{foldout-mouse-modifiers}; but if you have already loaded the @file{foldout.el} library, you must reload it in order for this to take effect. @@ -1286,7 +1336,7 @@ executed. @kindex S-TAB @r{(Org Mode)} @findex org-shifttab - Typing @key{S-TAB} (@code{org-shifttab}) anywhere in an Org mode + Typing @kbd{S-@key{TAB}} (@code{org-shifttab}) anywhere in an Org mode buffer cycles the visibility of the entire outline structure, between (i) showing only top-level heading lines, (ii) showing all heading lines but no body lines, and (iii) showing everything. @@ -1903,7 +1953,7 @@ characters themselves (@code{sgml-name-8bit-mode}). Run a shell command (which you must specify) to validate the current buffer as SGML (@code{sgml-validate}). -@item C-c TAB +@item C-c @key{TAB} @kindex C-c TAB @r{(SGML mode)} @findex sgml-tags-invisible Toggle the visibility of existing tags in the buffer. This can be @@ -1917,7 +1967,7 @@ used as a cheap preview (@code{sgml-tags-invisible}). The major mode for editing XML documents is called nXML mode. This is a powerful major mode that can recognize many existing XML schema and use them to provide completion of XML elements via -@kbd{M-@key{TAB}}, as well as ``on-the-fly'' XML +@kbd{M-@key{TAB}}, as well as on-the-fly XML validation with error highlighting. To enable nXML mode in an existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x xml-mode}. Emacs uses nXML mode for files which have the extension @@ -1998,7 +2048,7 @@ number (the header level). @cindex text/enriched MIME format Enriched mode is a minor mode for editing formatted text files in a -WYSIWYG (``what you see is what you get'') fashion. When Enriched +WYSIWYG (What You See Is What You Get) fashion. When Enriched mode is enabled, you can apply various formatting properties to the text in the buffer, such as fonts and colors; upon saving the buffer, those properties are saved together with the text, using the MIME @@ -2011,8 +2061,8 @@ highlighting (@pxref{Font Lock}). Unlike Enriched mode, Font Lock mode assigns text properties automatically, based on the current buffer contents; those properties are not saved to disk. - The file @file{etc/enriched.doc} in the Emacs distribution serves as -an example of the features of Enriched mode. + The file @file{enriched.txt} in Emacs's @code{data-directory} +serves as an example of the features of Enriched mode. @menu * Enriched Mode:: Entering and exiting Enriched mode. @@ -2022,7 +2072,7 @@ an example of the features of Enriched mode. * Enriched Indentation:: Changing the left and right margins. * Enriched Justification:: Centering, setting text flush with the left or right margin, etc. -* Enriched Properties:: The "special" text properties submenu. +* Enriched Properties:: The ``special text properties'' submenu. @end menu @node Enriched Mode @@ -2086,6 +2136,7 @@ newlines are used for filling. The @key{RET} (@code{newline}) and commands, including Auto Fill (@pxref{Auto Fill}), insert only soft newlines and delete only soft newlines, leaving hard newlines alone. +@c FIXME: I don't see 'unfilled' in that node. --xfq Thus, when editing with Enriched mode, you should not use @key{RET} or @kbd{C-o} to break lines in the middle of filled paragraphs. Use Auto Fill mode or explicit fill commands (@pxref{Fill Commands}) @@ -2097,11 +2148,12 @@ want to set the justification style to @code{unfilled} @node Editing Format Info @subsection Editing Format Information - The easiest way to alter properties is with the Text Properties -menu. You can get to this menu from the Edit menu in the menu bar -(@pxref{Menu Bar}), or with @kbd{C-Mouse-2} (@pxref{Menu Mouse -Clicks}). Some of the commands in the Text Properties menu are listed -below (you can also invoke them with @kbd{M-x}): + The easiest way to alter properties is with the @samp{Text +Properties} menu. You can get to this menu from the @samp{Edit} menu +in the menu bar (@pxref{Menu Bar}), or with @kbd{C-Mouse-2} +(@pxref{Menu Mouse Clicks}). Some of the commands in the @samp{Text +Properties} menu are listed below (you can also invoke them with +@kbd{M-x}): @table @code @findex facemenu-remove-face-props @@ -2294,13 +2346,13 @@ commands do nothing on text with this setting. You can, however, still indent the left margin. @end table -@c FIXME: We should explain the effect of these symbols. --xfq @vindex default-justification You can also specify justification styles using the Justification submenu in the Text Properties menu. The default justification style is specified by the per-buffer variable @code{default-justification}. Its value should be one of the symbols @code{left}, @code{right}, -@code{full}, @code{center}, or @code{none}. +@code{full}, @code{center}, or @code{none}; their meanings correspond +to the commands above. @node Enriched Properties @subsection Setting Other Text Properties @@ -2780,8 +2832,8 @@ puts the text after the separator into the right-hand buffer, and deletes the separator. Lines that don't have the column separator at the proper place remain unsplit; they stay in the left-hand buffer, and the right-hand buffer gets an empty line to correspond. (This is the -way to write a line that ``spans both columns while in two-column -mode'': write it in the left-hand buffer, and put an empty line in the +way to write a line that spans both columns while in two-column +mode: write it in the left-hand buffer, and put an empty line in the right-hand buffer.) @kindex F2 RET diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 0d5ce6820c7..087681b5618 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @@ -21,7 +21,7 @@ also considered. @table @kbd @item C-g -@itemx C-@key{BREAK} @r{(MS-DOS only)} +@itemx C-@key{Break} @r{(MS-DOS only)} Quit: cancel running or partially typed command. @item C-] Abort innermost recursive editing level and cancel the command which @@ -58,11 +58,11 @@ incremental search, @kbd{C-g} behaves specially; it may take two successive @kbd{C-g} characters to get out of a search. @xref{Incremental Search}, for details. - On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character + On MS-DOS, the character @kbd{C-@key{Break}} serves as a quit character like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to recognize @kbd{C-g} while a command is running, between interactions with the user. By contrast, it @emph{is} feasible to recognize -@kbd{C-@key{BREAK}} at all times. +@kbd{C-@key{Break}} at all times. @iftex @xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. @end iftex @@ -78,8 +78,8 @@ actually executed as a command if you type it while Emacs is waiting for input. In that case, the command it runs is @code{keyboard-quit}. On a text terminal, if you quit with @kbd{C-g} a second time before -the first @kbd{C-g} is recognized, you activate the ``emergency -escape'' feature and return to the shell. @xref{Emergency Escape}. +the first @kbd{C-g} is recognized, you activate the emergency-escape +feature and return to the shell. @xref{Emergency Escape}. @cindex NFS and quitting There are some situations where you cannot quit. When Emacs is @@ -118,7 +118,7 @@ it executes as an ordinary command, and Emacs doesn't notice it until it is ready for the next command. @findex top-level - The command @kbd{M-x top-level} is equivalent to ``enough'' + The command @kbd{M-x top-level} is equivalent to enough @kbd{C-]} commands to get you out of all the levels of recursive edits that you are in; it also exits the minibuffer if it is active. @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} @@ -135,6 +135,7 @@ facility. @node Lossage @section Dealing with Emacs Trouble +@cindex troubleshooting Emacs This section describes how to recognize and deal with situations in which Emacs does not work as you expect, such as keyboard code mixups, @@ -145,7 +146,7 @@ Emacs. @menu * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. +* Stuck Recursive:: '[...]' in mode line around the parentheses. * Screen Garbled:: Garbage on the screen. * Text Garbled:: Garbage in the text. * Memory Full:: How to cope when you run out of memory. @@ -158,14 +159,15 @@ Emacs. @subsection If @key{DEL} Fails to Delete @cindex @key{DEL} vs @key{BACKSPACE} @cindex @key{BACKSPACE} vs @key{DEL} +@cindex @key{DEL} does not delete - Every keyboard has a large key, usually labeled @key{Backspace}, + Every keyboard has a large key, usually labeled @key{BACKSPACE}, which is ordinarily used to erase the last character that you typed. In Emacs, this key is supposed to be equivalent to @key{DEL}. When Emacs starts up on a graphical display, it determines automatically which key should be @key{DEL}. In some unusual cases, -Emacs gets the wrong information from the system, and @key{Backspace} +Emacs gets the wrong information from the system, and @key{BACKSPACE} ends up deleting forwards instead of backwards. Some keyboards also have a @key{Delete} key, which is ordinarily @@ -173,9 +175,9 @@ used to delete forwards. If this key deletes backward in Emacs, that too suggests Emacs got the wrong information---but in the opposite sense. - On a text terminal, if you find that @key{Backspace} prompts for a + On a text terminal, if you find that @key{BACKSPACE} prompts for a Help command, like @kbd{Control-h}, instead of deleting a character, -it means that key is actually sending the @key{BS} character. Emacs +it means that key is actually sending the @samp{BS} character. Emacs ought to be treating @key{BS} as @key{DEL}, but it isn't. @findex normal-erase-is-backspace-mode @@ -189,8 +191,8 @@ sends character code 127. To fix the problem in every Emacs session, put one of the following lines into your initialization file (@pxref{Init File}). For the -first case above, where @key{Backspace} deletes forwards instead of -backwards, use this line to make @key{Backspace} act as @key{DEL}: +first case above, where @key{BACKSPACE} deletes forwards instead of +backwards, use this line to make @key{BACKSPACE} act as @key{DEL}: @lisp (normal-erase-is-backspace-mode 0) @@ -212,6 +214,8 @@ Customization}. @node Stuck Recursive @subsection Recursive Editing Levels +@cindex stuck in recursive editing +@cindex recursive editing, cannot exit Recursive editing levels are important and useful features of Emacs, but they can seem like malfunctions if you do not understand them. @@ -225,6 +229,9 @@ top-level}. @xref{Recursive Edit}. @node Screen Garbled @subsection Garbage on the Screen +@cindex garbled display +@cindex display, incorrect +@cindex screen display, wrong If the text on a text terminal looks wrong, the first thing to do is see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay @@ -242,6 +249,8 @@ bug in Emacs that appears for certain terminal types. @node Text Garbled @subsection Garbage in the Text +@cindex garbled text +@cindex buffer text garbled If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to see what commands you typed to produce the observed results. Then try @@ -333,7 +342,7 @@ Here, @var{backtrace} is the name of a text file containing a copy of the backtrace, @var{bindir} is the name of the directory that contains the Emacs executable, and @var{emacs-binary} is the name of the Emacs executable file, normally @file{emacs} on GNU and Unix -systems and @file{emacs.exe} on MS-Windows and MS-DOS. Omit the +systems and @file{emacs.exe} on MS-Windows and MS-DOS@. Omit the @option{-p} option if your version of @command{addr2line} is too old to have it. @@ -348,6 +357,7 @@ enable them by running the shell command @samp{ulimit -c unlimited} @node After a Crash @subsection Recovery After a Crash +@cindex recovering crashed session If Emacs or the computer crashes, you can recover the files you were editing at the time of the crash from their auto-save files. To do @@ -394,6 +404,7 @@ not make a backup of its old contents. @node Emergency Escape @subsection Emergency Escape +@cindex emergency escape On text terminals, the @dfn{emergency escape} feature suspends Emacs immediately if you type @kbd{C-g} a second time before Emacs can @@ -438,7 +449,7 @@ state. The quit you requested will happen by and by. displays, you can use the mouse to kill Emacs or switch to another program. - On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause + On MS-DOS, you must type @kbd{C-@key{Break}} (twice) to cause emergency escape---but there are cases where it won't work, when system call hangs or when Emacs is stuck in a tight loop in C code. @@ -475,10 +486,6 @@ file contains a list of particularly well-known issues that have been encountered in compiling, installing and running Emacs. Often, there are suggestions for workarounds and solutions. -@item -Some additional user-level problems can be found in @ref{Bugs and -problems, , Bugs and problems, efaq, GNU Emacs FAQ}. - @cindex bug tracker @item The GNU Bug Tracker at @url{http://debbugs.gnu.org}. Emacs bugs are @@ -500,7 +507,7 @@ by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}. The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup @samp{gnu.emacs.bug}). You can read the list archives at @url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list -works as a ``mirror'' of the Emacs bug reports and follow-up messages +works as a mirror of the Emacs bug reports and follow-up messages which are sent to the bug tracker. It also contains old bug reports from before the bug tracker was introduced (in early 2008). @@ -528,11 +535,13 @@ not feel obliged to read this list before reporting a bug. @node Bug Criteria @subsection When Is There a Bug +@cindex bug criteria +@cindex what constitutes an Emacs bug - If Emacs accesses an invalid memory location (``segmentation -fault''), or exits with an operating system error message that -indicates a problem in the program (as opposed to something like -``disk full''), then it is certainly a bug. + If Emacs accesses an invalid memory location (a.k.a.@: +``segmentation fault'') or exits with an operating system error +message that indicates a problem in the program (as opposed to +something like ``disk full''), then it is certainly a bug. If the Emacs display does not correspond properly to the contents of the buffer, then it is a bug. But you should check that features like @@ -541,7 +550,7 @@ buffer or change how it is displayed, are not responsible. Taking forever to complete a command can be a bug, but you must make sure that it is really Emacs's fault. Some commands simply take a -long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then +long time. Type @kbd{C-g} (@kbd{C-@key{Break}} on MS-DOS) and then @kbd{C-h l} to see whether the input Emacs received was what you intended to type; if the input was such that you @emph{know} it should have been processed quickly, report a bug. If you don't know whether @@ -580,6 +589,8 @@ with the manual, one of them must be wrong; that is a bug. @node Understanding Bug Reporting @subsection Understanding Bug Reporting +@cindex bug reporting +@cindex report an Emacs bug, how to @findex emacs-version When you decide that there is a bug, it is important to report it @@ -607,7 +618,7 @@ large file, and Emacs displayed @samp{I feel pretty today}.'' This is what we mean by ``guessing explanations''. The problem might be due to the fact that there is a @samp{z} in the file name. If this is so, then when we got your report, we would try out the problem with some -``large file'', probably with no @samp{z} in its name, and not see any +large file, probably with no @samp{z} in its name, and not see any problem. There is no way we could guess that we should try visiting a file with a @samp{z} in its name. @@ -631,10 +642,13 @@ easily reproducible at all. In that case, you should report what you have---but, as before, please stick to the raw facts about what you did to trigger the bug the first time. + If you have multiple issues that you want to report, please make a +separate bug report for each. + @node Checklist @subsection Checklist for Bug Reports - -@cindex reporting bugs +@cindex checklist before reporting a bug +@cindex bug reporting, checklist Before reporting a bug, first try to see if the problem has already been reported (@pxref{Known Problems}). @@ -725,7 +739,7 @@ unmodified Emacs. But if you've made modifications and you don't tell us, you are sending us on a wild goose chase.) Be precise about these changes. A description in English is not -enough---send a context diff for them. +enough---send a unified context diff for them. Adding files of your own, or porting to another machine, is a modification of the source. @@ -756,7 +770,9 @@ customizations. One way to record the input to Emacs precisely is to write a dribble file. To start the file, use the @kbd{M-x open-dribble-file @key{RET}} command. From then on, Emacs copies all your input to the -specified dribble file until the Emacs process is killed. +specified dribble file until the Emacs process is killed. Be aware +that sensitive information (such as passwords) may end up recorded in +the dribble file. @item @findex open-termscript @@ -827,7 +843,7 @@ conclusion from our observations. @item If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual fails to describe the actual behavior of Emacs, or that the text is -confusing, copy in the text from the online manual which you think is +confusing, copy in the text from the manual which you think is at fault. If the section is small, just the section name is enough. @item @@ -845,9 +861,9 @@ To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} before the error happens (that is to say, you must give that command and then make the bug happen). This causes the error to start the Lisp debugger, which shows you a backtrace. Copy the text of the -debugger's backtrace into the bug report. @xref{Debugger,, The Lisp -Debugger, elisp, the Emacs Lisp Reference Manual}, for information on -debugging Emacs Lisp programs with the Edebug package. +debugger's backtrace into the bug report. @xref{Edebug,, Edebug, +elisp, the Emacs Lisp Reference Manual}, for information on debugging +Emacs Lisp programs with the Edebug package. This use of the debugger is possible only if you know how to make the bug happen again. If you can't make it happen again, at least copy @@ -1040,19 +1056,44 @@ but using it will take extra work. Maintaining GNU Emacs is a lot of work in the best of circumstances, and we can't keep up unless you do your best to help. +Every patch must have several pieces of information before we +can properly evaluate it. + +When you have all these pieces, bundle them up in a mail message and +send it to the developers. Sending it to +@email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is +recommended, because that list is coupled to a tracking system that +makes it easier to locate patches. If your patch is not complete and +you think it needs more discussion, you might want to send it to +@email{emacs-devel@@gnu@@gnu.org} instead. If you revise your patch, +send it as a followup to the initial topic. + +We prefer to get the patches as plain text, either inline (be careful +your mail client does not change line breaks) or as MIME attachments. + @itemize @bullet @item -Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a fix for an existing bug, it is +Include an explanation with your changes of what problem they fix or what +improvement they bring about. + +@itemize +@item +For a fix for an existing bug, it is best to reply to the relevant discussion on the @samp{bug-gnu-emacs} list, or the bug entry in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Explain why your change fixes the bug. @item -Always include a proper bug report for the problem you think you have -fixed. We need to convince ourselves that the change is right before -installing it. Even if it is correct, we might have trouble -understanding it if we don't have a way to reproduce the problem. +For a new feature, include a description of the feature and your +implementation. + +@item +For a new bug, include a proper bug report for the problem you think +you have fixed. We need to convince ourselves that the change is +right before installing it. Even if it is correct, we might have +trouble understanding it if we don't have a way to reproduce the +problem. +@end itemize @item Include all the comments that are appropriate to help people reading the @@ -1084,16 +1125,23 @@ right away. That gives us the option of installing it immediately if it is important. @item -Use @samp{diff -c} to make your diffs. Diffs without context are hard +The patch itself. + +Use @samp{diff -u} to make your diffs. Diffs without context are hard to install reliably. More than that, they are hard to study; we must -always study a patch to decide whether we want to install it. Unidiff -format is better than contextless diffs, but not as easy to read as -@samp{-c} format. +always study a patch to decide whether we want to install it. Context +format is better than contextless diffs, but we prefer we unified format. -If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when +If you have GNU diff, use @samp{diff -u -F'^[_a-zA-Z0-9$]\+ *('} when making diffs of C code. This shows the name of the function that each change occurs in. +If you are using the Emacs repository, make sure your copy is +up-to-date (e.g., with @code{git pull}). You can commit your changes +to a private branch and generate a patch from the master version by +using @code{git format-patch master}. Or you can leave your changes +uncommitted and use @code{git diff}. + @item Avoid any ambiguity as to which is the old version and which is the new. Please make the old version the first argument to diff, and the new @@ -1117,9 +1165,17 @@ new function, all you need to say about it is that it is new. If you feel that the purpose needs explaining, it probably does---but put the explanation in comments in the code. It will be more useful there. -Please read the @file{ChangeLog} files in the @file{src} and -@file{lisp} directories to see what sorts of information to put in, -and to learn the style that we use. @xref{Change Log}. +Please look at the change log entries of recent commits to see what +sorts of information to put in, and to learn the style that we use. Note that, +unlike some other projects, we do require change logs for +documentation, i.e., Texinfo files. +@xref{Change Log}, +@ifset WWW_GNU_ORG +see +@url{http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html}, +@end ifset +@xref{Change Log Concepts, Change Log Concepts, +Change Log Concepts, gnu-coding-standards, GNU Coding Standards}. @item When you write the fix, keep in mind that we can't install a change that @@ -1144,6 +1200,48 @@ form that is clearly safe to install. @section Contributing to Emacs Development @cindex contributing to Emacs +Emacs is a collaborative project and we encourage contributions from +anyone and everyone. + +There are many ways to contribute to Emacs: + +@itemize +@item +find and report bugs; @xref{Bugs}. + +@item +answer questions on the Emacs user mailing list +@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}. + +@item +write documentation, either on the wiki, or in the Emacs source +repository (@pxref{Sending Patches}). + +@item +check if existing bug reports are fixed in newer versions of Emacs +@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}. + +@item +fix existing bug reports +@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}. + +@item +@c etc/TODO not in WWW_GNU_ORG +implement a feature listed in the @file{etc/TODO} file in the Emacs +distribution, and submit a patch. + +@item +implement a new feature, and submit a patch. + +@item +develop a package that works with Emacs, and publish it on your own +or in Gnu ELPA (@url{https://elpa.gnu.org/}). + +@item +port Emacs to a new platform, but that is not common nowadays. + +@end itemize + If you would like to work on improving Emacs, please contact the maintainers at @ifnothtml @email{emacs-devel@@gnu.org}. @@ -1165,19 +1263,157 @@ you have not yet started work, it is useful to contact before you start; it might be possible to suggest ways to make your extension fit in better with the rest of Emacs. +When implementing a feature, please follow the Emacs coding standards; +@xref{Coding Standards}. In addition, non-trivial contributions +require a copyright assignment to the FSF; @xref{Copyright Assignment}. + The development version of Emacs can be downloaded from the repository where it is actively maintained by a group of developers. See the Emacs project page -@url{http://savannah.gnu.org/projects/emacs/} for details. +@url{http://savannah.gnu.org/projects/emacs/} for access details. + +It is important to write your patch based on the current working +version. If you start from an older version, your patch may be +outdated (so that maintainers will have a hard time applying it), or +changes in Emacs may have made your patch unnecessary. After you have +downloaded the repository source, you should read the file +@file{INSTALL.REPO} for build instructions (they differ to some extent +from a normal build). + +If you would like to make more extensive contributions, see the +@file{./CONTRIBUTE} file in the Emacs distribution for information on +how to be an Emacs developer. + +For documentation on Emacs (to understand how to implement your +desired change), refer to: + +@itemize +@item +@ifset WWW_GNU_ORG +@ifhtml +the Emacs Manual +@url{http://www.gnu.org/software/emacs/manual/emacs.html}. +@end ifhtml +@ifnothtml +@xref{Top, Emacs Manual,,emacs}. +@end ifnothtml +@end ifset +@ifclear WWW_GNU_ORG +@xref{Top, Emacs Manual,,emacs}. +@end ifclear + +@item +@ifset WWW_GNU_ORG +@ifhtml +the Emacs Lisp Reference Manual +@url{http://www.gnu.org/software/emacs/manual/elisp.html}. +@end ifhtml +@ifnothtml +@xref{Top, Emacs Lisp Reference Manual,,elisp}. +@end ifnothtml +@end ifset +@ifclear WWW_GNU_ORG +@xref{Top, Emacs Lisp Reference Manual,,elisp}. +@end ifclear + +@item +@url{http://www.gnu.org/software/emacs} + +@item +@url{http://www.emacswiki.org/} +@end itemize + +@menu +* Coding Standards:: Gnu Emacs coding standards +* Copyright Assignment:: assigning copyright to the FSF +@end menu + +@node Coding Standards +@subsection Coding Standards +@cindex coding standards + +Contributed code should follow the GNU Coding Standards +@url{http://www.gnu.org/prep/standards/}. This may also be available +in info on your system. + +If it doesn't, we'll need to find someone to fix the code before we +can use it. + +Emacs has additional style and coding conventions: + +@itemize +@item +@ifset WWW_GNU_ORG +@ifhtml +the ``Tips and Conventions'' Appendix in the Emacs Lisp Reference +@url{http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}. +@end ifhtml +@ifnothtml +@xref{Tips, ``Tips and Conventions'' Appendix in the Emacs Lisp Reference, Tips +Appendix, elisp, Emacs Lisp Reference}. +@end ifnothtml +@end ifset +@ifclear WWW_GNU_ORG +@xref{Tips, ``Tips and Conventions'' Appendix in the Emacs Lisp Reference, Tips +Appendix, elisp, Emacs Lisp Reference}. +@end ifclear + +@item +Avoid using @code{defadvice} or @code{eval-after-load} for Lisp code +to be included in Emacs. + +@item +Remove all trailing whitespace in all source and text files. + +@item +Emacs has no convention on whether to use tabs in source code; please +don't change whitespace in the files you edit. + +@item +Use @code{?\s} instead of @code{? } in Lisp code for a space character. + +@end itemize + +@node Copyright Assignment +@subsection Copyright Assignment +@cindex copyright assignment + +The FSF (Free Software Foundation) is the copyright holder for GNU Emacs. +The FSF is a nonprofit with a worldwide mission to promote computer +user freedom and to defend the rights of all free software users. +For general information, see the website @url{http://www.fsf.org/}. + +Generally speaking, for non-trivial contributions to GNU Emacs we +require that the copyright be assigned to the FSF@. For the reasons +behind this, see @url{http://www.gnu.org/licenses/why-assign.html}. + +Copyright assignment is a simple process. Residents of some countries +can do it entirely electronically. We can help you get started, and +answer any questions you may have (or point you to the people with the +answers), at the @email{emacs-devel@@gnu.org} mailing list. + +(Please note: general discussion about why some GNU projects ask +for a copyright assignment is off-topic for emacs-devel. +See gnu-misc-discuss instead.) + +A copyright disclaimer is also a possibility, but we prefer an assignment. +Note that the disclaimer, like an assignment, involves you sending +signed paperwork to the FSF (simply saying ``this is in the public domain'' +is not enough). Also, a disclaimer cannot be applied to future work, it +has to be repeated each time you want to send something new. -For more information on how to contribute, see the @file{etc/CONTRIBUTE} -file in the Emacs distribution. +We can accept small changes (roughly, fewer than 15 lines) without +an assignment. This is a cumulative limit (e.g., three separate 5 line +patches) over all your contributions. @node Service @section How To Get Help with GNU Emacs +@cindex help in using Emacs +@cindex help-gnu-emacs mailing list +@cindex gnu.emacs.help newsgroup -If you need help installing, using or changing GNU Emacs, there are two -ways to find it: +If you need help installing, using or changing GNU Emacs, there are +two ways to find it: @itemize @bullet @item @@ -1194,9 +1430,8 @@ mailing list and newsgroup interconnect, so it does not matter which one you use.) @item -Look in the service directory for someone who might help you for a fee. -The service directory is found in the file named @file{etc/SERVICE} in the -Emacs distribution. +Look in the @uref{http://www.fsf.org/resources/service/, service +directory} for someone who might help you for a fee. @end itemize @ifnottex diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi index 41a10bc2ace..d224043b110 100644 --- a/doc/emacs/vc-xtra.texi +++ b/doc/emacs/vc-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included in emacs-xtra.texi when producing the printed diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index 96e171855a5..3eb9b035823 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in vc-xtra.texi (when producing the @@ -59,7 +59,7 @@ As above, but only find entries for the current buffer's file. For example, suppose the first line of @file{ChangeLog} is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore -log messages that start with `#'.}. Then @kbd{C-x v a} inserts this +log messages that start with '#'.}. Then @kbd{C-x v a} inserts this @file{ChangeLog} entry: @iftex @@ -69,7 +69,7 @@ log messages that start with `#'.}. Then @kbd{C-x v a} inserts this @group 1999-05-22 Nathaniel Bowditch <nat@@apn.org> - * rcs2log: Ignore log messages that start with `#'. + * rcs2log: Ignore log messages that start with '#'. @end group @end smallexample @iftex @@ -113,7 +113,7 @@ Prompt for a file name, delete the file from the working tree, and schedule the deletion for committing. @item M-x vc-rename-file -Prompt for two file names, @var{VAR} and @var{OLD}, rename them in the +Prompt for two file names, @var{var} and @var{old}, rename them in the working tree, and schedule the renaming for committing. @end table @@ -430,7 +430,7 @@ that @kbd{C-x v ~} saves old versions to @end ifnottex except for the additional dot (@samp{.}) after the version. The relevant VC commands can use both kinds of version backups. The main -difference is that the ``manual'' version backups made by @kbd{C-x v +difference is that the manual version backups made by @kbd{C-x v ~} are not deleted automatically when you commit. @cindex locking (CVS) diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 7c80cefcc7e..d844f3e4988 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Windows @@ -134,6 +134,18 @@ clicking @kbd{C-Mouse-2} in the scroll bar, which puts a horizontal divider where you click (this feature does not work when Emacs uses GTK+ scroll bars). +@vindex window-resize-pixelwise + By default, when you split a window, Emacs gives each of the +resulting windows dimensions that are an integral multiple of the +default font size of the frame. That might subdivide the screen +estate unevenly between the resulting windows. If you set the +variable @code{window-resize-pixelwise} to a non-@code{nil} value, +Emacs will give each window the same number of pixels (give or take +one pixel if the initial dimension was an odd number of pixels). Note +that when a frame's pixel size is not a multiple of the frame's +character size, at least one window may get resized pixelwise even if +this option is @code{nil}. + @node Other Window @section Using Other Windows @@ -211,10 +223,11 @@ Visit file @var{filename} and select its buffer in another window Select a Dired buffer for directory @var{directory} in another window (@code{dired-other-window}). @xref{Dired}. -@findex mail-other-window +@c Don't index @kbd{C-x 4 m} and @code{compose-mail-other-window} +@c here, they are indexed in sending.texi, in the "Sending Mail" node. @item C-x 4 m Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending -Mail}), but in another window (@code{mail-other-window}). +Mail}), but in another window (@code{compose-mail-other-window}). @findex find-tag-other-window @item C-x 4 . @@ -226,8 +239,10 @@ window (@code{find-file-read-only-other-window}). @xref{Visiting}. @end table @node Change Window -@section Deleting and Rearranging Windows +@section Deleting and Resizing Windows +@cindex delete window +@cindex deleting windows @table @kbd @item C-x 0 Delete the selected window (@code{delete-window}). @@ -273,6 +288,8 @@ selected window. whole frame. (This command cannot be used while the minibuffer window is active; attempting to do so signals an error.) +@cindex resize window +@cindex resizing windows @kindex C-x ^ @findex enlarge-window @kindex C-x @} @@ -298,6 +315,10 @@ signal an error if you attempt to reduce the width of any window below a certain minimum number of columns, specified by the variable @code{window-min-width} (the default is 10). + Mouse clicks on the mode line (@pxref{Mode Line Mouse}) or on window +dividers (@pxref{Window Dividers}) provide another way to change window +heights and to split or delete windows. + @kindex C-x - @findex shrink-window-if-larger-than-buffer @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) reduces the @@ -310,13 +331,10 @@ lines to other windows in the frame. You can also use @kbd{C-x +} (@code{balance-windows}) to even out the heights of all the windows in the selected frame. - Mouse clicks on the mode line provide another way to change window -heights and to delete windows. @xref{Mode Line Mouse}. - @node Displaying Buffers @section Displaying a Buffer in a Window - It is a common Emacs operation to display or ``pop up'' some buffer + It is a common Emacs operation to display or pop up some buffer in response to a user command. There are several different ways in which commands do this. @@ -327,7 +345,7 @@ usually work by calling @code{switch-to-buffer} internally (@pxref{Select Buffer}). @findex display-buffer - Some commands try to display ``intelligently'', trying not to take + Some commands try to display intelligently, trying not to take over the selected window, e.g., by splitting off a new window and displaying the desired buffer there. Such commands, which include the various help commands (@pxref{Help}), work by calling @@ -380,7 +398,7 @@ variables are @code{nil}, so this step is skipped. @item Otherwise, if the buffer is already displayed in an existing window, -``reuse'' that window. Normally, only windows on the selected frame +reuse that window. Normally, only windows on the selected frame are considered, but windows on other frames are also reusable if you change @code{pop-up-frames} (see below) to @code{t}. @@ -426,7 +444,7 @@ and display the buffer there. @cindex window configuration changes, undoing Winner mode is a global minor mode that records the changes in the window configuration (i.e., how the frames are partitioned into -windows), so that you can ``undo'' them. You can toggle Winner mode +windows), so that you can undo them. You can toggle Winner mode with @kbd{M-x winner-mode}, or by customizing the variable @code{winner-mode}. When the mode is enabled, @kbd{C-c left} (@code{winner-undo}) undoes the last window configuration change. If @@ -444,7 +462,7 @@ buffer. @xref{Follow Mode}. The Windmove package defines commands for moving directionally between neighboring windows in a frame. @kbd{M-x windmove-right} selects the window immediately to the right of the currently selected -one, and similarly for the ``left'', ``up'', and ``down'' +one, and similarly for the left, up, and down counterparts. @kbd{M-x windmove-default-keybindings} binds these commands to @kbd{S-right} etc.; doing so disables shift selection for those keys (@pxref{Shift Selection}). diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi index 3723c8e5e1d..afd27669967 100644 --- a/doc/emacs/xresources.texi +++ b/doc/emacs/xresources.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1987, 1993-1995, 1997, 2001-2013 Free Software +@c Copyright (C) 1987, 1993-1995, 1997, 2001-2015 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node X Resources @@ -12,10 +12,10 @@ resources, as is usual for programs that use X. graphical widgets, such as the menu-bar, scroll-bar, and dialog boxes, is determined by @ifnottex -``GTK resources'', which we will also describe. +GTK resources, which we will also describe. @end ifnottex @iftex -``GTK resources''. +GTK resources. @end iftex When Emacs is built without GTK+ support, the appearance of these widgets is determined by additional X resources. @@ -27,7 +27,7 @@ system registry (@pxref{MS-Windows Registry}). * Resources:: Using X resources with Emacs (in general). * Table of Resources:: Table of specific X resources that affect Emacs. * Lucid Resources:: X resources for Lucid menus. -* LessTif Resources:: X resources for LessTif and Motif menus. +* Motif Resources:: X resources for Motif and LessTif menus. * GTK resources:: Resources for GTK widgets. @end menu @@ -238,8 +238,8 @@ this way. @ifnottex @item @code{privateColormap} (class @code{PrivateColormap}) -If @samp{on}, use a private color map, in the case where the ``default -visual'' of class PseudoColor and Emacs is using it. +If @samp{on}, use a private color map, in the case where the default +visual of class PseudoColor and Emacs is using it. @item @code{reverseVideo} (class @code{ReverseVideo}) Switch foreground and background default colors if @samp{on}, use colors as @@ -260,7 +260,7 @@ compiled with GTK+ support. @ifnottex @item @code{selectionFont} (class @code{SelectionFont}) Font name for pop-up menu items, in non-toolkit versions of Emacs. (For -toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif +toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif Resources}.) @item @code{selectionTimeout} (class @code{SelectionTimeout}) @@ -370,15 +370,15 @@ elements. Default is 1. Margin of the menu bar, in characters. Default is 1. @end table -@node LessTif Resources -@appendixsec LessTif Menu X Resources -@cindex Menu X Resources (LessTif widgets) -@cindex LessTif Widget X Resources +@node Motif Resources +@appendixsec Motif Menu X Resources +@cindex Menu X Resources (Motif widgets) +@cindex Motif Widget X Resources - If Emacs is compiled with the X toolkit support using LessTif or -Motif widgets, you can use X resources to customize the appearance of -the menu bar, pop-up menus, and dialog boxes. However, the resources -are organized differently from Lucid widgets. + If Emacs is compiled with the X toolkit support using Motif or +LessTif widgets, you can use X resources to customize the appearance +of the menu bar, pop-up menus, and dialog boxes. However, the +resources are organized differently from Lucid widgets. The resource names for the menu bar are in the @samp{pane.menubar} class, and they must be specified in this form: @@ -677,7 +677,7 @@ class @code{GtkDialog}. For file selection, Emacs uses a widget named @code{emacs-filedialog}, of class @code{GtkFileSelection}. Because the widgets for pop-up menus and dialogs are free-standing -windows and not ``contained'' in the @code{Emacs} widget, their GTK+ +windows and not contained in the @code{Emacs} widget, their GTK+ absolute names do not start with @samp{Emacs}. To customize these widgets, use wildcards like this: @@ -747,8 +747,8 @@ This is the default state for widgets. @item ACTIVE This is the state for a widget that is ready to do something. It is also for the trough of a scroll bar, i.e., @code{bg[ACTIVE] = "red"} -sets the scroll bar trough to red. Buttons that have been pressed but -not released yet (``armed'') are in this state. +sets the scroll bar trough to red. Buttons that have been armed +(pressed but not released yet) are in this state. @item PRELIGHT This is the state for a widget that can be manipulated, when the mouse pointer is over it---for example when the mouse is over the thumb in diff --git a/doc/lispintro/.gitignore b/doc/lispintro/.gitignore deleted file mode 100644 index e1af5a918b0..00000000000 --- a/doc/lispintro/.gitignore +++ /dev/null @@ -1,21 +0,0 @@ -*.aux -*.fn -*.fns -*.cps -*.cp -*.kys -*.ky -*.toc -*.pgs -*.pg -*.log -*.vrs -*.vr -*.dvi -*.ps -*.tp -*.tps -*.tmp -*.txt -Makefile -makefile diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog.1 index db02a257a3a..c54c165d22c 100644 --- a/doc/lispintro/ChangeLog +++ b/doc/lispintro/ChangeLog.1 @@ -1,3 +1,126 @@ +2015-03-25 Stefan Monnier <monnier@iro.umontreal.ca> + + * emacs-lisp-intro.texi: `save-excursion' doesn't save&restore the mark. + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/eintr.info, emacs-lisp-intro.html): + Use them. + +2014-11-09 Glenn Morris <rgm@gnu.org> + + * Makefile.in (version): Remove variable. + (clean): No longer delete dist tarfile. + (dist): Remove rule; replace with code in admin.el. + +2014-10-20 Glenn Morris <rgm@gnu.org> + + * Merge in all changes up to 24.4 release. + +2014-10-13 Glenn Morris <rgm@gnu.org> + + * Makefile.in (dist): Update for new output variables. + +2014-07-16 Álvar Jesús Ibeas Martín <alvar.ibeas@unican.es> (tiny change) + + * emacs-lisp-intro.texi (Variables, Buffer Names, if & or) + (Symbols as Chest, fwd-para while): Fix typos. + +2014-07-03 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (Note for Novices, Finding More, Conclusion): + "Online" help doesn't mean what it used to any more. + +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with explicit rule. + (${buildinfodir}): New rule. + (${buildinfodir}/eintr.info): Use order-only prereq for output dir. + Use $<. + (emacs-lisp-intro.dvi, emacs-lisp-intro.pdf, emacs-lisp-intro.html): + Use $<. + (emacs-lisp-intro.ps): New rule. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-02 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (Autoload): Update loaddefs.el details. + +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + +2014-02-25 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (X11 Colors): Don't use setq with hooks. + +2014-02-06 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (Recursive Patterns): + Do not use colons in index entries. + +2014-01-23 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (lengths-list-file): Fix textual parentheses. + +2013-12-30 Paul Eggert <eggert@cs.ucla.edu> + + Specify .texi encoding (Bug#16292). + * emacs-lisp-intro.texi: Add @documentencoding. + +2013-12-30 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi: Use @quotation for license notice. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi: Tweak dircategory. + + * emacs-lisp-intro.texi: Sync direntry with info/dir version. + +2013-12-02 Paul Eggert <eggert@cs.ucla.edu> + + * emacs-lisp-intro.texi (Counting Words): Don't use ':' in xref + titles, as this isn't supported by Texinfo. + +2013-11-30 Glenn Morris <rgm@gnu.org> + + * Makefile.in (distclean): Remove Makefile. + +2013-10-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (install-dvi, install-html, install-pdf) + (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) + (uninstall-pdf): Quote entities that might contain whitespace. + +2013-09-01 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (beginning-of-buffer complete): + Put back a version of the removed paragraph about raw prefix arg. + +2013-09-01 Dani Moncayo <dmoncayo@gmail.com> + + * emacs-lisp-intro.texi (beginning-of-buffer complete): + Update function details. (Bug#15085) + +2013-08-28 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, + for portability to hosts where /bin/sh has problems. + 2013-08-12 Glenn Morris <rgm@gnu.org> * emacs-lisp-intro.texi (Complete copy-region-as-kill): Fix typo. @@ -15,8 +138,8 @@ (emacs-lisp-intro.ps): Remove explicit rule. (emacs-lisp-intro.html): Use HTML_OPTS. (clean): Use DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS. - (.PHONY): install-dvi, install-html, install-pdf, install-ps - ,install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, + (.PHONY): install-dvi, install-html, install-pdf, install-ps, + install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, uninstall-ps, and uninstall-doc. (install-dvi, install-html, install-pdf, install-ps, install-doc) (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) @@ -470,8 +593,8 @@ 2006-11-05 Robert J. Chassell <bob@rattlesnake.com> * emacs-lisp-intro.texi: Yet more minor changes: - (defcustom): Said that `:options' is usually for a hook. Remove - extraneous space in parenthetical remark concerning + (defcustom): Said that `:options' is usually for a hook. + Remove extraneous space in parenthetical remark concerning `text-mode-hook-identify'. At end, mention other defines, too. (Beginning a .emacs File): Reverse words about comments so they parallel numbers of listed semi-colons. @@ -493,12 +616,12 @@ Center images for TeX output. (kill-new function): Remove indentation for sentence talking about momentarily skipping code. - (cons & search-fwd Review): Document @code{funcall}. Document - @code{re-search-forward} with existing @code{search-forward}. + (cons & search-fwd Review): Document @code{funcall}. + Document @code{re-search-forward} with existing @code{search-forward}. Reference chapter on regular expression searches. (Recursion with list): Specify a more recent version as being Emacs. - (Recursion with list, Every, recursive-graph-body-print): Change - `if ... progn' expression to `when'. + (Recursion with list, Every, recursive-graph-body-print): + Change `if ... progn' expression to `when'. (Recursive triangle function): For printing in small book, ensure section name is not last on bottom of preceding page. (Keep): Remove extraneous space in function definition example. @@ -507,11 +630,11 @@ function. (fwd-sentence while loops): Write a function as one, not as a form. (fwd-para let): Add `which' to sentence with `parstart' and `parsep'. - (etags): Move sentences involving `find-tag' and sources. State - location of Emacs `src' directory. + (etags): Move sentences involving `find-tag' and sources. + State location of Emacs `src' directory. (Design count-words-region): Better explain two backslashes in a row. - (Find a File): Fix grammar; add a `to' and write `to visit'. Change - `named' to `selected'. + (Find a File): Fix grammar; add a `to' and write `to visit'. + Change `named' to `selected'. (lengths-list-file): Remove extraneous parenthesis from reference. (lengths-list-many-files): Explain `expand-file-name' better. (Files List): Rephrase sentence regarding Lisp sources directory. @@ -539,8 +662,8 @@ seen' the @code{eq} function. (kill-append function): Reformat `kill-append' function definition so it prints well. - (kill-new function): Indent the sentence beginning `notice'. Replace - `the same as' with `similar to'. Repair typo. Remove obsolete + (kill-new function): Indent the sentence beginning `notice'. + Replace `the same as' with `similar to'. Repair typo. Remove obsolete references to `yank' and `yank-pop. End section with a note that `we will digress into C.' @@ -564,8 +687,8 @@ is 3.00. Did not update ISBN number. * emacs-lisp-intro.texi: Remove version reference for X colors. - Document `='. Remove mention that :eval was new in 21. Updated - instance's edition-number to 3.01. + Document `='. Remove mention that :eval was new in 21. + Updated instance's edition-number to 3.01. 2006-10-30 Robert J. Chassell <bob@rattlesnake.com> @@ -659,7 +782,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 2001-2013 Free Software Foundation, Inc. + Copyright (C) 2001-2015 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index ad1b978f255..d1a696ce2c2 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1994-1999, 2001-2013 Free Software Foundation, Inc. +# Copyright (C) 1994-1999, 2001-2015 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -17,17 +17,14 @@ # 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 +SHELL = @SHELL@ -# NB If you add any more configure variables, -# update the sed rules in the dist target below. srcdir = @srcdir@ -version=@version@ buildinfodir = $(srcdir)/../../info # Directory with the (customized) texinfo.tex file. texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. +# Directory with docstyle.texi and emacsver.texi. emacsdir = $(srcdir)/../emacs prefix = @prefix@ @@ -46,9 +43,8 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -59,50 +55,58 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = \ + $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = emacs-lisp-intro.dvi HTML_TARGETS = emacs-lisp-intro.html PDF_TARGETS = emacs-lisp-intro.pdf PS_TARGETS = emacs-lisp-intro.ps -mkinfodir = @${MKDIR_P} ${buildinfodir} - srcs = ${srcdir}/emacs-lisp-intro.texi ${srcdir}/doclicense.texi \ - ${emacsdir}/emacsver.texi + ${emacsdir}/docstyle.texi ${emacsdir}/emacsver.texi -.PHONY: info dvi html pdf ps - -.SUFFIXES: .ps .dvi +## Disable implicit rules. +%.texi: ; -.dvi.ps: - $(DVIPS) -o $@ $< - -info: ${buildinfodir}/eintr$(INFO_EXT) +.PHONY: info dvi html pdf ps +info: ${buildinfodir}/eintr.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) +${buildinfodir}: + ${MKDIR_P} $@ + # The file name eintr must fit within 5 characters, to allow for # -NN extensions to fit into DOS 8+3 limits without clashing. -# Note: "<" is not portable in ordinary make rules. -${buildinfodir}/eintr$(INFO_EXT): ${srcs} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi +${buildinfodir}/eintr.info: ${srcs} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< emacs-lisp-intro.dvi: ${srcs} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-lisp-intro.texi + $(ENVADD) $(TEXI2DVI) $< emacs-lisp-intro.pdf: ${srcs} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-lisp-intro.texi + $(ENVADD) $(TEXI2PDF) $< emacs-lisp-intro.html: ${srcs} - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< + +emacs-lisp-intro.ps: emacs-lisp-intro.dvi + $(DVIPS) -o $@ $< -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean mostlyclean: rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ @@ -110,56 +114,35 @@ mostlyclean: clean: mostlyclean rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f emacs-lispintro-${version}.tar* distclean: clean + rm -f Makefile infoclean: - -cd $(buildinfodir) && rm -f eintr$(INFO_EXT) eintr$(INFO_EXT)-[1-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -dist: - rm -rf emacs-lispintro-${version} - mkdir emacs-lispintro-${version} - cp ${srcdir}/*.texi ${srcdir}/*.eps ${srcdir}/*.pdf \ - ${texinfodir}/texinfo.tex ${emacsdir}/emacsver.texi \ - ${srcdir}/ChangeLog* ${srcdir}/README emacs-lispintro-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - ${srcdir}/Makefile.in > emacs-lispintro-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-lispintro-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-lispintro-${version}.tar emacs-lispintro-${version} - rm -rf emacs-lispintro-${version} + rm -f \ + $(buildinfodir)/eintr.info \ + $(buildinfodir)/eintr.info-[1-9] +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc install-dvi: dvi - umask 022; $(MKDIR_P) $(DESTDIR)$(dvidir) - $(INSTALL_DATA) $(DVI_TARGETS) $(DESTDIR)$(dvidir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" + $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" install-html: html - umask 022; $(MKDIR_P) $(DESTDIR)$(htmldir) - $(INSTALL_DATA) $(HTML_TARGETS) $(DESTDIR)$(htmldir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" + $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" install-pdf: pdf - umask 022;$(MKDIR_P) $(DESTDIR)$(pdfdir) - $(INSTALL_DATA) $(PDF_TARGETS) $(DESTDIR)$(pdfdir) + umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" + $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" install-ps: ps - umask 022; $(MKDIR_P) $(DESTDIR)$(psdir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} $(DESTDIR)$(psdir); \ + $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ [ -n "${GZIP_PROG}" ] || continue; \ - rm -f $(DESTDIR)$(psdir)/$${file}.gz; \ - ${GZIP_PROG} -9n $(DESTDIR)$(psdir)/$${file}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ + ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ done ## Top-level Makefile installs the info pages. @@ -170,20 +153,20 @@ install-doc: install-dvi install-html install-pdf install-ps uninstall-dvi: for file in $(DVI_TARGETS); do \ - rm -f $(DESTDIR)$(dvidir)/$${file}; \ + rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ done uninstall-html: for file in $(HTML_TARGETS); do \ - rm -f $(DESTDIR)$(htmldir)/$${file}; \ + rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ done uninstall-ps: ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ for file in $(PS_TARGETS); do \ - rm -f $(DESTDIR)$(psdir)/$${file}$${ext}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ done uninstall-pdf: for file in $(PDF_TARGETS); do \ - rm -f $(DESTDIR)$(pdfdir)/$${file}; \ + rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ done uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps diff --git a/doc/lispintro/README b/doc/lispintro/README index d1e15bc6d89..e24f8f50726 100644 --- a/doc/lispintro/README +++ b/doc/lispintro/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2013 Free Software Foundation, Inc. +Copyright (C) 2001-2015 Free Software Foundation, Inc. See the end of the file for license conditions. diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps index 77d24cbddcc..4853d6a1d8d 100644 --- a/doc/lispintro/cons-1.eps +++ b/doc/lispintro/cons-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:58 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps index 961b00a13ec..258caa94858 100644 --- a/doc/lispintro/cons-2.eps +++ b/doc/lispintro/cons-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:39 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2a.eps b/doc/lispintro/cons-2a.eps index 993609638a1..710f66e4648 100644 --- a/doc/lispintro/cons-2a.eps +++ b/doc/lispintro/cons-2a.eps @@ -4,7 +4,7 @@ %%CreationDate: Tue Mar 14 15:09:30 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-3.eps b/doc/lispintro/cons-3.eps index e37dad0de60..2849a314133 100644 --- a/doc/lispintro/cons-3.eps +++ b/doc/lispintro/cons-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:41 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-4.eps b/doc/lispintro/cons-4.eps index 9af4c2afd75..d9331242818 100644 --- a/doc/lispintro/cons-4.eps +++ b/doc/lispintro/cons-4.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:06 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps index 8a400f320de..6ceec517f52 100644 --- a/doc/lispintro/cons-5.eps +++ b/doc/lispintro/cons-5.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:27:28 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/drawers.eps b/doc/lispintro/drawers.eps index abfec2a7362..dcd27a60b54 100644 --- a/doc/lispintro/drawers.eps +++ b/doc/lispintro/drawers.eps @@ -9,7 +9,7 @@ %%EndComments %%BeginProlog -% Copyright (C) 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 18ea8e87e19..245113b86d7 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1,9 +1,10 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header -@setfilename ../../info/eintr +@setfilename ../../info/eintr.info @c setfilename emacs-lisp-intro.info @c sethtmlfilename emacs-lisp-intro.html @settitle Programming in Emacs Lisp +@include docstyle.texi @syncodeindex vr cp @syncodeindex fn cp @finalout @@ -29,7 +30,7 @@ @c @set largebook @c (Note: if you edit the book so as to change the length of the -@c table of contents, you may have to change the value of `pageno' below.) +@c table of contents, you may have to change the value of 'pageno' below.) @c <<<< For hard copy printing, this file is now @c set for smallbook, which works for all sizes @@ -96,10 +97,9 @@ @c ---------------------------------------------------- -@dircategory GNU Emacs Lisp +@dircategory Emacs lisp @direntry -* Emacs Lisp Intro: (eintr). - A simple introduction to Emacs Lisp programming. +* Emacs Lisp Intro: (eintr). A simple introduction to Emacs Lisp programming. @end direntry @copying @@ -113,7 +113,7 @@ Edition @value{edition-number}, @value{update-date} Distributed with Emacs version @value{EMACSVER}. @end ifnottex @sp 1 -Copyright @copyright{} 1990--1995, 1997, 2001--2013 Free Software +Copyright @copyright{} 1990--1995, 1997, 2001--2015 Free Software Foundation, Inc. @sp 1 @@ -142,6 +142,7 @@ Boston, MA 02110-1301 USA @sp 1 ISBN 1-882114-43-4 +@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; there @@ -153,9 +154,10 @@ Documentation License''. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.'' +@end quotation @end copying -@c half title; two lines here, so do not use `shorttitlepage' +@c half title; two lines here, so do not use 'shorttitlepage' @tex {\begingroup% \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% @@ -350,7 +352,7 @@ How To Write Function Definitions * if:: What if? * else:: If--then--else expressions. * Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. +* save-excursion:: Keeping track of point and buffer. * Review:: * defun Exercises:: @@ -385,7 +387,7 @@ Truth and Falsehood in Emacs Lisp * Point and mark:: A review of various locations. * Template for save-excursion:: -A Few Buffer--Related Functions +A Few Buffer-Related Functions * Finding More:: How to find more information. * simplified-beginning-of-buffer:: Shows @code{goto-char}, @@ -806,7 +808,7 @@ In addition, I have written several programs as extended examples. Although these are examples, the programs are real. I use them. Other people use them. You may use them. Beyond the fragments of programs used for illustrations, there is very little in here that is -`just for teaching purposes'; what you see is used. This is a great +just for teaching purposes; what you see is used. This is a great advantage of Emacs Lisp: it is easy to learn to use it for work. @end ignore @@ -852,12 +854,12 @@ information so you won't be surprised later when the additional information is formally introduced.) When you read this text, you are not expected to learn everything the -first time. Frequently, you need only make, as it were, a `nodding -acquaintance' with some of the items mentioned. My hope is that I have +first time. Frequently, you need make only a nodding +acquaintance with some of the items mentioned. My hope is that I have structured the text and given you enough hints that you will be alert to what is important, and concentrate on it. -You will need to ``dive into'' some paragraphs; there is no other way +You will need to dive into some paragraphs; there is no other way to read them. But I have tried to keep down the number of such paragraphs. This book is intended as an approachable hill, rather than as a daunting mountain. @@ -901,7 +903,7 @@ file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) If you don't know GNU Emacs, you can still read this document profitably. However, I recommend you learn Emacs, if only to learn to move around your computer screen. You can teach yourself how to use -Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This +Emacs with the built-in tutorial. To use it, type @kbd{C-h t}. (This means you press and release the @key{CTRL} key and the @kbd{h} at the same time, and then press and release @kbd{t}.) @@ -926,7 +928,7 @@ along with the key that is labeled @key{ALT} and, at the same time, press the @key{\} key. In addition to typing a lone keychord, you can prefix what you type -with @kbd{C-u}, which is called the `universal argument'. The +with @kbd{C-u}, which is called the @dfn{universal argument}. The @kbd{C-u} keychord passes an argument to the subsequent command. Thus, to indent a region of plain text by 6 spaces, mark the region, and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, @@ -998,7 +1000,7 @@ bob@@gnu.org To the untutored eye, Lisp is a strange programming language. In Lisp code there are parentheses everywhere. Some people even claim that -the name stands for `Lots of Isolated Silly Parentheses'. But the +the name stands for ``Lots of Isolated Silly Parentheses''. But the claim is unwarranted. Lisp stands for LISt Processing, and the programming language handles @emph{lists} (and lists of lists) by putting them between parentheses. The parentheses mark the boundaries @@ -1088,7 +1090,7 @@ list is made up of the words @samp{a}, @samp{list}, @samp{inside}, In Lisp, what we have been calling words are called @dfn{atoms}. This term comes from the historical meaning of the word atom, which means -`indivisible'. As far as Lisp is concerned, the words we have been +``indivisible''. As far as Lisp is concerned, the words we have been using in the lists cannot be divided into any smaller parts and still mean the same thing as part of a program; likewise with numbers and single character symbols like @samp{+}. On the other hand, unlike an @@ -1157,7 +1159,7 @@ paragraphs---is also an atom. Here is an example: @noindent In Lisp, all of the quoted text including the punctuation mark and the blank spaces is a single atom. This kind of atom is called a -@dfn{string} (for `string of characters') and is the sort of thing that +@dfn{string} (for ``string of characters'') and is the sort of thing that is used for messages that a computer can print for a human to read. Strings are a different kind of atom than numbers or symbols and are used differently. @@ -1238,6 +1240,10 @@ command to do something. (Usually, of course, it is the last of these three things that you really want!) @c use code for the single apostrophe, not samp. +@findex quote +@cindex @code{'} for quoting +@cindex quoting using apostrophe +@cindex apostrophe for quoting The single apostrophe, @code{'}, that I put in front of some of the example lists in preceding sections is called a @dfn{quote}; when it precedes a list, it tells Lisp to do nothing with the list, other than @@ -1259,9 +1265,9 @@ hand parenthesis of the following list and then type @kbd{C-x C-e}: @c use code for the number four, not samp. @noindent -You will see the number @code{4} appear in the echo area. (In the -jargon, what you have just done is ``evaluate the list.'' The echo area -is the line at the bottom of the screen that displays or ``echoes'' +You will see the number @code{4} appear in the echo area. (What +you have just done is evaluate the list. The echo area +is the line at the bottom of the screen that displays or echoes text.) Now try the same thing with a quoted list: place the cursor right after the following list and type @kbd{C-x C-e}: @@ -1278,7 +1284,7 @@ In both cases, what you are doing is giving a command to the program inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the interpreter a command to evaluate the expression. The name of the Lisp interpreter comes from the word for the task done by a human who comes -up with the meaning of an expression---who ``interprets'' it. +up with the meaning of an expression---who interprets it. You can also evaluate an atom that is not part of a list---one that is not surrounded by parentheses; again, the Lisp interpreter translates @@ -1301,7 +1307,7 @@ signposts to a traveler in a strange country; deciphering them can be hard, but once understood, they can point the way. The error message is generated by a built-in GNU Emacs debugger. We -will `enter the debugger'. You get out of the debugger by typing @code{q}. +will enter the debugger. You get out of the debugger by typing @code{q}. What we will do is evaluate a list that is not quoted and does not have a meaningful command as its first element. Here is a list almost @@ -1363,9 +1369,9 @@ Based on what we already know, we can almost read this error message. You read the @file{*Backtrace*} buffer from the bottom up; it tells you what Emacs did. When you typed @kbd{C-x C-e}, you made an interactive call to the command @code{eval-last-sexp}. @code{eval} is -an abbreviation for `evaluate' and @code{sexp} is an abbreviation for -`symbolic expression'. The command means `evaluate last symbolic -expression', which is the expression just before your cursor. +an abbreviation for ``evaluate'' and @code{sexp} is an abbreviation for +``symbolic expression''. The command means ``evaluate last symbolic +expression'', which is the expression just before your cursor. Each line above tells you what the Lisp interpreter evaluated next. The most recent action is at the top. The buffer is called the @@ -1399,7 +1405,7 @@ definition of any set of instructions for the computer to carry out. The slightly odd word, @samp{void-function}, is designed to cover the way Emacs Lisp is implemented, which is that when a symbol does not have a function definition attached to it, the place that should -contain the instructions is `void'. +contain the instructions is void. On the other hand, since we were able to add 2 plus 2 successfully, by evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must @@ -1568,9 +1574,9 @@ compilation. When the Lisp interpreter works on an expression, the term for the activity is called @dfn{evaluation}. We say that the interpreter -`evaluates the expression'. I've used this term several times before. -The word comes from its use in everyday language, `to ascertain the -value or amount of; to appraise', according to @cite{Webster's New +``evaluates the expression''. I've used this term several times before. +The word comes from its use in everyday language, ``to ascertain the +value or amount of; to appraise'', according to @cite{Webster's New Collegiate Dictionary}. @menu @@ -1590,16 +1596,15 @@ instructions it found in the function definition, or perhaps it will give up on that function and produce an error message. (The interpreter may also find itself tossed, so to speak, to a different function or it may attempt to repeat continually what it is doing for ever and ever in -what is called an `infinite loop'. These actions are less common; and +an infinite loop. These actions are less common; and we can ignore them.) Most frequently, the interpreter returns a value. @cindex @samp{side effect} defined At the same time the interpreter returns a value, it may do something else as well, such as move a cursor or copy a file; this other kind of action is called a @dfn{side effect}. Actions that we humans think are -important, such as printing results, are often ``side effects'' to the -Lisp interpreter. The jargon can sound peculiar, but it turns out that -it is fairly easy to learn to use side effects. +important, such as printing results, are often side effects to the +Lisp interpreter. It is fairly easy to learn to use side effects. In summary, evaluating a symbolic expression most commonly causes the Lisp interpreter to return a value and perhaps carry out a side effect; @@ -1635,9 +1640,9 @@ evaluate, the interpreter prints that value in the echo area. Now it is easy to understand the name of the command invoked by the keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The -letters @code{sexp} are an abbreviation for `symbolic expression', and -@code{eval} is an abbreviation for `evaluate'. The command means -`evaluate last symbolic expression'. +letters @code{sexp} are an abbreviation for ``symbolic expression'', and +@code{eval} is an abbreviation for ``evaluate''. The command +evaluates the last symbolic expression. As an experiment, you can try evaluating the expression by putting the cursor at the beginning of the next line immediately following the @@ -1698,7 +1703,7 @@ Another way to think about this is to imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the drawer holding the -function definition, and vice-verse. +function definition, and vice versa. @menu * fill-column Example:: @@ -1836,7 +1841,7 @@ typing @kbd{q} in the @file{*Backtrace*} buffer.) This backtrace is different from the very first error message we saw, which said, @samp{Debugger entered--Lisp error: (void-function this)}. In this case, the function does not have a value as a variable; while -in the other error message, the function (the word `this') did not +in the other error message, the function (the word @samp{this}) did not have a definition. In this experiment with the @code{+}, what we did was cause the Lisp @@ -1885,22 +1890,22 @@ The numbers added by @code{+} are called the @dfn{arguments} of the function @code{+}. These numbers are the information that is given to or @dfn{passed} to the function. -The word `argument' comes from the way it is used in mathematics and +The word ``argument'' comes from the way it is used in mathematics and does not refer to a disputation between two people; instead it refers to the information presented to the function, in this case, to the @code{+}. In Lisp, the arguments to a function are the atoms or lists that follow the function. The values returned by the evaluation of these atoms or lists are passed to the function. Different functions require different numbers of arguments; some functions require none at -all.@footnote{It is curious to track the path by which the word `argument' +all.@footnote{It is curious to track the path by which the word ``argument'' came to have two different meanings, one in mathematics and the other in everyday English. According to the @cite{Oxford English Dictionary}, the word derives from the Latin for @samp{to make clear, prove}; thus it -came to mean, by one thread of derivation, `the evidence offered as -proof', which is to say, `the information offered', which led to its +came to mean, by one thread of derivation, ``the evidence offered as +proof'', which is to say, ``the information offered'', which led to its meaning in Lisp. But in the other thread of derivation, it came to mean -`to assert in a manner against which others may make counter -assertions', which led to the meaning of the word as a disputation. +``to assert in a manner against which others may make counter +assertions'', which led to the meaning of the word as a disputation. (Note here that the English word has two different definitions attached to it at the same time. By contrast, in Emacs Lisp, a symbol cannot have two different function definitions at the same time.)} @@ -1942,13 +1947,16 @@ following: @noindent The value produced by evaluating this expression is @code{"abcdef"}. +@cindex substring A function such as @code{substring} uses both a string and numbers as -arguments. The function returns a part of the string, a substring of +arguments. The function returns a part of the string, a @dfn{substring} of the first argument. This function takes three arguments. Its first -argument is the string of characters, the second and third arguments are -numbers that indicate the beginning and end of the substring. The -numbers are a count of the number of characters (including spaces and -punctuation) from the beginning of the string. +argument is the string of characters, the second and third arguments +are numbers that indicate the beginning (inclusive) and end +(exclusive) of the substring. The numbers are a count of the number +of characters (including spaces and punctuation) from the beginning of +the string. Note that the characters in a string are numbered from +zero, not one. @need 800 For example, if you evaluate the following: @@ -1965,7 +1973,7 @@ Note that the string passed to @code{substring} is a single atom even though it is made up of several words separated by spaces. Lisp counts everything between the two quotation marks as part of the string, including the spaces. You can think of the @code{substring} function as -a kind of `atom smasher' since it takes an otherwise indivisible atom +a kind of atom smasher since it takes an otherwise indivisible atom and extracts a part. However, @code{substring} is only able to extract a substring from an argument that is a string, not from another type of atom such as a number or symbol. @@ -2020,7 +2028,7 @@ Some functions, such as @code{concat}, @code{+} or @code{*}, take any number of arguments. (The @code{*} is the symbol for multiplication.) This can be seen by evaluating each of the following expressions in the usual way. What you will see in the echo area is printed in this -text after @samp{@result{}}, which you may read as `evaluates to'. +text after @samp{@result{}}, which you may read as ``evaluates to''. @need 1250 In the first set, the functions have no arguments: @@ -2121,7 +2129,7 @@ numeric value of marker positions as numbers. The @samp{p} of @code{number-or-marker-p} is the embodiment of a practice started in the early days of Lisp programming. The @samp{p} -stands for `predicate'. In the jargon used by the early Lisp +stands for ``predicate''. In the jargon used by the early Lisp researchers, a predicate refers to a function to determine whether some property is true or false. So the @samp{p} tells us that @code{number-or-marker-p} is the name of a function that determines @@ -2388,14 +2396,14 @@ to the symbol @code{herbivores}: not have fit on a page; and humans find it easier to read nicely formatted lists.) -Although I have been using the term `assign', there is another way of +Although I have been using the term ``assign'', there is another way of thinking about the workings of @code{set} and @code{setq}; and that is to say that @code{set} and @code{setq} make the symbol @emph{point} to the list. This latter way of thinking is very common and in forthcoming -chapters we shall come upon at least one symbol that has `pointer' as +chapters we shall come upon at least one symbol that has ``pointer'' as part of its name. The name is chosen because the symbol has a value, specifically a list, attached to it; or, expressed another way, -the symbol is set to ``point'' to the list. +the symbol is set to point to the list. @node Counting @subsection Counting @@ -2500,8 +2508,8 @@ of which the function is the first element. @item A function always returns a value when it is evaluated (unless it gets -an error); in addition, it may also carry out some action called a -``side effect''. In many cases, a function's primary purpose is to +an error); in addition, it may also carry out some action that is a +side effect. In many cases, a function's primary purpose is to create a side effect. @end itemize @@ -2637,9 +2645,9 @@ The former is the name of the buffer and the latter is the name of the file. In Info, the buffer name is @file{"*info*"}. Info does not point to any file, so the result of evaluating @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is -from the Latin word for `nothing'; in this case, it means that the +from the Latin word for ``nothing''; in this case, it means that the buffer is not associated with any file. (In Lisp, @code{nil} is also -used to mean `false' and is a synonym for the empty list, @code{()}.) +used to mean ``false'' and is a synonym for the empty list, @code{()}.) When I am writing, the name of my buffer is @file{"introduction.texinfo"}. The name of the file to which it @@ -2651,7 +2659,7 @@ functions; without the parentheses, the interpreter would attempt to evaluate the symbols as variables. @xref{Variables}.) In spite of the distinction between files and buffers, you will often -find that people refer to a file when they mean a buffer and vice-verse. +find that people refer to a file when they mean a buffer and vice versa. Indeed, most people say, ``I am editing a file,'' rather than saying, ``I am editing a buffer which I will soon save to a file.'' It is almost always clear from context what people mean. When dealing with @@ -2659,7 +2667,7 @@ computer programs, however, it is important to keep the distinction in mind, since the computer is not as smart as a person. @cindex Buffer, history of word -The word `buffer', by the way, comes from the meaning of the word as a +The word ``buffer'', by the way, comes from the meaning of the word as a cushion that deadens the force of a collision. In early computers, a buffer cushioned the interaction between files and the computer's central processing unit. The drums or tapes that held a file and the @@ -2836,10 +2844,10 @@ following more complex expression: @c noindent In this case, the first argument to @code{other-buffer} tells it which buffer to skip---the current one---and the second argument tells -@code{other-buffer} it is OK to switch to a visible buffer. -In regular use, @code{switch-to-buffer} takes you to an invisible -window since you would most likely use @kbd{C-x o} (@code{other-window}) -to go to another visible buffer.} +@code{other-buffer} it is OK to switch to a visible buffer. In +regular use, @code{switch-to-buffer} takes you to a buffer not visible +in windows since you would most likely use @kbd{C-x o} +(@code{other-window}) to go to another visible buffer.} In the programming examples in later sections of this document, you will see the function @code{set-buffer} more often than @@ -2862,7 +2870,7 @@ there until the command finishes running). Also, we have just introduced another jargon term, the word @dfn{call}. When you evaluate a list in which the first symbol is a function, you are calling that function. The use of the term comes from the notion of -the function as an entity that can do something for you if you `call' +the function as an entity that can do something for you if you call it---just as a plumber is an entity who can fix a leak if you call him or her. @@ -2905,7 +2913,7 @@ the following expression in the usual way: @end smallexample @noindent -As I write this, the value of @code{point} is 65724. The @code{point} +As I write this, the value of point is 65724. The @code{point} function is frequently used in some of the examples later in this book. @@ -2964,7 +2972,7 @@ symbol refers to it.) * if:: What if? * else:: If--then--else expressions. * Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. +* save-excursion:: Keeping track of point and buffer. * Review:: * defun Exercises:: @end menu @@ -3080,9 +3088,9 @@ function. Instead of choosing the word @code{number} for the name of the argument, I could have picked any other name. For example, I could have chosen -the word @code{multiplicand}. I picked the word `number' because it +the word @code{multiplicand}. I picked the word ``number'' because it tells what kind of value is intended for this slot; but I could just as -well have chosen the word `multiplicand' to indicate the role that the +well have chosen the word ``multiplicand'' to indicate the role that the value placed in this slot will play in the workings of the function. I could have called it @code{foogle}, but that would have been a bad choice because it would not tell humans what it means. The choice of @@ -3094,16 +3102,16 @@ list, even the name of a symbol used in some other function: the name you use in an argument list is private to that particular definition. In that definition, the name refers to a different entity than any use of the same name outside the function definition. Suppose you have a -nick-name `Shorty' in your family; when your family members refer to -`Shorty', they mean you. But outside your family, in a movie, for -example, the name `Shorty' refers to someone else. Because a name in an +nick-name ``Shorty'' in your family; when your family members refer to +``Shorty'', they mean you. But outside your family, in a movie, for +example, the name ``Shorty'' refers to someone else. Because a name in an argument list is private to the function definition, you can change the value of such a symbol inside the body of a function without changing its value outside the function. The effect is similar to that produced by a @code{let} expression. (@xref{let, , @code{let}}.) @ignore -Note also that we discuss the word `number' in two different ways: as a +Note also that we discuss the word ``number'' in two different ways: as a symbol that appears in the code, and as the name of something that will be replaced by a something else during the evaluation of the function. In the first case, @code{number} is a symbol, not a number; it happens @@ -3148,7 +3156,7 @@ to evaluate this yet! @noindent The symbol @code{number}, specified in the function definition in the -next section, is given or ``bound to'' the value 3 in the actual use of +next section, is bound to the value 3 in the actual use of the function. Note that although @code{number} was inside parentheses in the function definition, the argument passed to the @code{multiply-by-seven} function is not in parentheses. The @@ -3159,7 +3167,7 @@ definition begins. If you evaluate this example, you are likely to get an error message. (Go ahead, try it!) This is because we have written the function definition, but not yet told the computer about the definition---we have -not yet installed (or `loaded') the function definition in Emacs. +not yet loaded the function definition in Emacs. Installing a function is the process that tells the Lisp interpreter the definition of the function. Installation is described in the next section. @@ -3223,6 +3231,7 @@ function, @code{multiply-by-seven}. When you do this, a @smallexample @group multiply-by-seven is a Lisp function. + (multiply-by-seven NUMBER) Multiply NUMBER by seven. @@ -3248,8 +3257,8 @@ add the number to itself seven times instead of multiplying the number by seven. It produces the same answer, but by a different path. At the same time, we will add a comment to the code; a comment is text that the Lisp interpreter ignores, but that a human reader may find -useful or enlightening. The comment is that this is the ``second -version''. +useful or enlightening. The comment is that this is the second +version. @smallexample @group @@ -3352,7 +3361,7 @@ it could not be used as an example of key binding.) (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command to a key.) -A prefix argument is passed to an interactive function by typing the +A @dfn{prefix argument} is passed to an interactive function by typing the @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you type @kbd{C-u} without a number, it defaults to 4). @@ -3445,13 +3454,16 @@ a function. (@xref{Interactive Codes, , Code Characters for Consider the function @code{zap-to-char}. Its interactive expression is +@c FIXME: the interactive expression of zap-to-char has been changed +@c (in 2012-04-10). + @smallexample (interactive "p\ncZap to char: ") @end smallexample The first part of the argument to @code{interactive} is @samp{p}, with which you are already familiar. This argument tells Emacs to -interpret a `prefix', as a number to be passed to the function. You +interpret a prefix, as a number to be passed to the function. You can specify a prefix either by typing @kbd{C-u} followed by a number or by typing @key{META} followed by a number. The prefix is the number of specified characters. Thus, if your prefix is three and the @@ -3565,8 +3577,8 @@ variable of the same name that is not part of the function. To understand why the @code{let} special form is necessary, consider the situation in which you own a home that you generally refer to as -`the house', as in the sentence, ``The house needs painting.'' If you -are visiting a friend and your host refers to `the house', he is +``the house'', as in the sentence, ``The house needs painting.'' If you +are visiting a friend and your host refers to ``the house'', he is likely to be referring to @emph{his} house, not yours, that is, to a different house. @@ -3594,7 +3606,7 @@ and the two are not intended to refer to the same value. The The @code{let} special form prevents confusion. @code{let} creates a name for a @dfn{local variable} that overshadows any use of the same name outside the @code{let} expression. This is like understanding -that whenever your host refers to `the house', he means his house, not +that whenever your host refers to ``the house'', he means his house, not yours. (Symbols used in argument lists work the same way. @xref{defun, , The @code{defun} Macro}.) @@ -3607,21 +3619,21 @@ Another way to think about @code{let} is that it is like a @code{setq} that is temporary and local. The values set by @code{let} are automatically undone when the @code{let} is finished. The setting only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say ``the binding of +expression. In computer science jargon, we would say the binding of a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, scoping is dynamic, not lexical.'' +in Emacs Lisp, scoping is dynamic, not lexical. @code{let} can create more than one variable at once. Also, @code{let} gives each variable it creates an initial value, either a -value specified by you, or @code{nil}. (In the jargon, this is called -`binding the variable to the value'.) After @code{let} has created +value specified by you, or @code{nil}. (In the jargon, this is +binding the variable to the value.) After @code{let} has created and bound the variables, it executes the code in the body of the @code{let}, and returns the value of the last expression in the body, -as the value of the whole @code{let} expression. (`Execute' is a jargon +as the value of the whole @code{let} expression. (``Execute'' is a jargon term that means to evaluate a list; it comes from the use of the word -meaning `to give practical effect to' (@cite{Oxford English +meaning ``to give practical effect to'' (@cite{Oxford English Dictionary}). Since you evaluate an expression to perform an action, -`execute' has evolved as a synonym to `evaluate'.) +``execute'' has evolved as a synonym to ``evaluate''.) @node Parts of let Expression @subsection The Parts of a @code{let} Expression @@ -3682,26 +3694,26 @@ to the two variables @code{zebra} and @code{tiger}. The body of the @smallexample @group -(let ((zebra 'stripes) - (tiger 'fierce)) +(let ((zebra "stripes") + (tiger "fierce")) (message "One kind of animal has %s and another is %s." zebra tiger)) @end group @end smallexample -Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. +Here, the varlist is @code{((zebra "stripes") (tiger "fierce"))}. The two variables are @code{zebra} and @code{tiger}. Each variable is the first element of a two-element list and each value is the second element of its two-element list. In the varlist, Emacs binds the -variable @code{zebra} to the value @code{stripes}@footnote{According +variable @code{zebra} to the value @code{"stripes"}@footnote{According to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras become impossibly dangerous as they grow older'' but the claim here is that they do not become fierce like a tiger. (1997, W. W. Norton and Co., ISBN 0-393-03894-2, page 171)}, and binds the -variable @code{tiger} to the value @code{fierce}. In this example, -both values are symbols preceded by a quote. The values could just as -well have been another list or a string. The body of the @code{let} +variable @code{tiger} to the value @code{"fierce"}. In this example, +both values are strings. The values could just as well have been +another list or a symbol. The body of the @code{let} follows after the list holding the variables. In this example, the body is a list that uses the @code{message} function to print a string in the echo area. @@ -3781,8 +3793,8 @@ make decisions. You can write function definitions without using included here. It is used, for example, in the code for the function @code{beginning-of-buffer}. -The basic idea behind an @code{if}, is that ``@emph{if} a test is true, -@emph{then} an expression is evaluated.'' If the test is not true, the +The basic idea behind an @code{if}, is that @emph{if} a test is true, +@emph{then} an expression is evaluated. If the test is not true, the expression is not evaluated. For example, you might make a decision such as, ``if it is warm and sunny, then go to the beach!'' @@ -3798,7 +3810,7 @@ such as, ``if it is warm and sunny, then go to the beach!'' @cindex @samp{if-part} defined @cindex @samp{then-part} defined -An @code{if} expression written in Lisp does not use the word `then'; +An @code{if} expression written in Lisp does not use the word ``then''; the test and the action are the second and third elements of the list whose first element is @code{if}. Nonetheless, the test part of an @code{if} expression is often called the @dfn{if-part} and the second @@ -3806,7 +3818,7 @@ argument is often called the @dfn{then-part}. Also, when an @code{if} expression is written, the true-or-false-test is usually written on the same line as the symbol @code{if}, but the -action to carry out if the test is true, the ``then-part'', is written +action to carry out if the test is true, the then-part, is written on the second and subsequent lines. This makes the @code{if} expression easier to read. @@ -3846,17 +3858,17 @@ of time, we would not need to run the test!) For example, the value may be bound to an argument of a function definition. In the following function definition, the character of the animal is a value that is passed to the function. If the value bound to -@code{characteristic} is @code{fierce}, then the message, @samp{It's a +@code{characteristic} is @code{"fierce"}, then the message, @samp{It is a tiger!} will be printed; otherwise, @code{nil} will be returned. @smallexample @group (defun type-of-animal (characteristic) "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', +If the CHARACTERISTIC is the string \"fierce\", then warn of a tiger." - (if (equal characteristic 'fierce) - (message "It's a tiger!"))) + (if (equal characteristic "fierce") + (message "It is a tiger!"))) @end group @end smallexample @@ -3868,18 +3880,18 @@ can evaluate the following two expressions to see the results: @smallexample @group -(type-of-animal 'fierce) +(type-of-animal "fierce") -(type-of-animal 'zebra) +(type-of-animal "striped") @end group @end smallexample @c Following sentences rewritten to prevent overfull hbox. @noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; and -when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} +When you evaluate @code{(type-of-animal "fierce")}, you will see the +following message printed in the echo area: @code{"It is a tiger!"}; and +when you evaluate @code{(type-of-animal "striped")} you will see @code{nil} printed in the echo area. @node type-of-animal in detail @@ -3909,7 +3921,7 @@ The parts of the function that match this template look like this: @group (defun type-of-animal (characteristic) "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', +If the CHARACTERISTIC is the string \"fierce\", then warn of a tiger." @var{body: the} @code{if} @var{expression}) @end group @@ -3938,8 +3950,8 @@ looks like this: @smallexample @group -(if (equal characteristic 'fierce) - (message "It's a tiger!"))) +(if (equal characteristic "fierce") + (message "It is a tiger!"))) @end group @end smallexample @@ -3947,26 +3959,26 @@ looks like this: Here, the true-or-false-test is the expression: @smallexample -(equal characteristic 'fierce) +(equal characteristic "fierce") @end smallexample @noindent In Lisp, @code{equal} is a function that determines whether its first argument is equal to its second argument. The second argument is the -quoted symbol @code{'fierce} and the first argument is the value of the +string @code{"fierce"} and the first argument is the value of the symbol @code{characteristic}---in other words, the argument passed to this function. In the first exercise of @code{type-of-animal}, the argument -@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} -is equal to @code{fierce}, the expression, @code{(equal characteristic -'fierce)}, returns a value of true. When this happens, the @code{if} +@code{"fierce"} is passed to @code{type-of-animal}. Since @code{"fierce"} +is equal to @code{"fierce"}, the expression, @code{(equal characteristic +"fierce")}, returns a value of true. When this happens, the @code{if} evaluates the second argument or then-part of the @code{if}: -@code{(message "It's tiger!")}. +@code{(message "It is a tiger!")}. On the other hand, in the second exercise of @code{type-of-animal}, the -argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} -is not equal to @code{fierce}, so the then-part is not evaluated and +argument @code{"striped"} is passed to @code{type-of-animal}. @code{"striped"} +is not equal to @code{"fierce"}, so the then-part is not evaluated and @code{nil} is returned by the @code{if} expression. @node else @@ -4025,34 +4037,33 @@ arguments to the function. @group (defun type-of-animal (characteristic) ; @r{Second version.} "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger; -else say it's not fierce." - (if (equal characteristic 'fierce) - (message "It's a tiger!") - (message "It's not fierce!"))) +If the CHARACTERISTIC is the string \"fierce\", +then warn of a tiger; else say it is not fierce." + (if (equal characteristic "fierce") + (message "It is a tiger!") + (message "It is not fierce!"))) @end group @end smallexample @sp 1 @smallexample @group -(type-of-animal 'fierce) +(type-of-animal "fierce") -(type-of-animal 'zebra) +(type-of-animal "striped") @end group @end smallexample @c Following sentence rewritten to prevent overfull hbox. @noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; but -when you evaluate @code{(type-of-animal 'zebra)}, you will see -@code{"It's not fierce!"}. +When you evaluate @code{(type-of-animal "fierce")}, you will see the +following message printed in the echo area: @code{"It is a tiger!"}; but +when you evaluate @code{(type-of-animal "striped")}, you will see +@code{"It is not fierce!"}. -(Of course, if the @var{characteristic} were @code{ferocious}, the -message @code{"It's not fierce!"} would be printed; and it would be +(Of course, if the @var{characteristic} were @code{"ferocious"}, the +message @code{"It is not fierce!"} would be printed; and it would be misleading! When you write code, you need to take into account the possibility that some such argument will be tested by the @code{if} and write your program accordingly.) @@ -4064,10 +4075,10 @@ and write your program accordingly.) @findex nil There is an important aspect to the truth test in an @code{if} -expression. So far, we have spoken of `true' and `false' as values of +expression. So far, we have spoken of ``true'' and ``false'' as values of predicates as if they were new kinds of Emacs Lisp objects. In fact, -`false' is just our old friend @code{nil}. Anything else---anything -at all---is `true'. +``false'' is just our old friend @code{nil}. Anything else---anything +at all---is ``true''. The expression that tests for truth is interpreted as @dfn{true} if the result of evaluating it is a value that is not @code{nil}. In @@ -4148,8 +4159,8 @@ On the other hand, this function returns @code{nil} if the test is false. @section @code{save-excursion} @findex save-excursion @cindex Region, what it is -@cindex Preserving point, mark, and buffer -@cindex Point, mark, buffer preservation +@cindex Preserving point and buffer +@cindex Point and buffer preservation @findex point @findex mark @@ -4157,11 +4168,11 @@ The @code{save-excursion} function is the third and final special form that we will discuss in this chapter. In Emacs Lisp programs used for editing, the @code{save-excursion} -function is very common. It saves the location of point and mark, -executes the body of the function, and then restores point and mark to -their previous positions if their locations were changed. Its primary +function is very common. It saves the location of point, +executes the body of the function, and then restores point to +its previous position if its location was changed. Its primary purpose is to keep the user from being surprised and disturbed by -unexpected movement of point or mark. +unexpected movement of point. @menu * Point and mark:: A review of various locations. @@ -4198,8 +4209,8 @@ region}. Numerous commands work on the region, including @code{center-region}, @code{count-lines-region}, @code{kill-region}, and @code{print-region}. -The @code{save-excursion} special form saves the locations of point and -mark and restores those positions after the code within the body of the +The @code{save-excursion} special form saves the location of point and +restores this position after the code within the body of the special form is evaluated by the Lisp interpreter. Thus, if point were in the beginning of a piece of text and some code moved point to the end of the buffer, the @code{save-excursion} would put point back to where @@ -4210,16 +4221,16 @@ In Emacs, a function frequently moves point as part of its internal workings even though a user would not expect this. For example, @code{count-lines-region} moves point. To prevent the user from being bothered by jumps that are both unexpected and (from the user's point of -view) unnecessary, @code{save-excursion} is often used to keep point and -mark in the location expected by the user. The use of +view) unnecessary, @code{save-excursion} is often used to keep point in +the location expected by the user. The use of @code{save-excursion} is good housekeeping. To make sure the house stays clean, @code{save-excursion} restores the -values of point and mark even if something goes wrong in the code inside +value of point even if something goes wrong in the code inside of it (or, to be more precise and to use the proper jargon, ``in case of abnormal exit''). This feature is very helpful. -In addition to recording the values of point and mark, +In addition to recording the value of point, @code{save-excursion} keeps track of the current buffer, and restores it, too. This means you can write code that will change the buffer and have @code{save-excursion} switch you back to the original buffer. @@ -4246,7 +4257,7 @@ one expression in the body, the value of the last one will be returned as the value of the @code{save-excursion} function. The other expressions in the body are evaluated only for their side effects; and @code{save-excursion} itself is used only for its side effect (which -is restoring the positions of point and mark). +is restoring the position of point). @need 1250 In more detail, the template for a @code{save-excursion} expression @@ -4349,7 +4360,7 @@ The name of an existing buffer. The name of an existing file. @item p -The numeric prefix argument. (Note that this `p' is lower case.) +The numeric prefix argument. (Note that this @code{p} is lower case.) @item r Point and the mark, as two numeric arguments, smallest first. This @@ -4384,9 +4395,9 @@ For example, @end smallexample @item save-excursion -Record the values of point and mark and the current buffer before -evaluating the body of this special form. Restore the values of point -and mark and buffer afterward. +Record the values of point and the current buffer before +evaluating the body of this special form. Restore the value of point and +buffer afterward. @need 1250 For example, @@ -4441,7 +4452,7 @@ markers, are equal. @item equal @itemx eq Test whether two objects are the same. @code{equal} uses one meaning -of the word `same' and @code{eq} uses another: @code{equal} returns +of the word ``same'' and @code{eq} uses another: @code{equal} returns true if the two objects have a similar structure and contents, such as two copies of the same book. On the other hand, @code{eq}, returns true if both arguments are actually the same object. @@ -4470,7 +4481,7 @@ shorter, alternative name is @code{string=}. There are no string test functions that correspond to @var{>}, @code{>=}, or @code{<=}. @item message -Print a message in the echo area. The first argument is a string that +Print a message in the echo area. The first argument is a string that can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of arguments that follow the string. The argument used by @samp{%s} must be a string or a symbol; the argument used by @samp{%d} must be a @@ -4545,7 +4556,7 @@ and if so, prints an appropriate message. @end itemize @node Buffer Walk Through -@chapter A Few Buffer--Related Functions +@chapter A Few Buffer-Related Functions In this chapter we study in detail several of the functions used in GNU Emacs. This is called a ``walk-through''. These functions are used as @@ -4586,7 +4597,7 @@ function definition. Put point into the name of the file that contains the function and press the @key{RET} key. In this case, @key{RET} means -@code{push-button} rather than `return' or `enter'. Emacs will take +@code{push-button} rather than ``return'' or ``enter''. Emacs will take you directly to the function definition. @ignore @@ -4594,7 +4605,7 @@ Not In version 22 If you move point over the file name and press the @key{RET} key, which in this case means @code{help-follow} rather -than `return' or `enter', Emacs will take you directly to the function +than ``return'' or ``enter'', Emacs will take you directly to the function definition. @end ignore @@ -4604,7 +4615,7 @@ file, you can use the @code{find-tag} function to jump to it. Lisp, and C, and it works with non-programming text as well. For example, @code{find-tag} will jump to the various nodes in the Texinfo source file of this document. -The @code{find-tag} function depends on `tags tables' that record +The @code{find-tag} function depends on @dfn{tags tables} that record the locations of the functions, variables, and other items to which @code{find-tag} jumps. @@ -4622,7 +4633,7 @@ screen. To switch back to your current buffer, type @kbd{C-x b @cindex TAGS table, specifying @findex find-tag Depending on how the initial default values of your copy of Emacs are -set, you may also need to specify the location of your `tags table', +set, you may also need to specify the location of your tags table, which is a file called @file{TAGS}. For example, if you are interested in Emacs sources, the tags table you will most likely want, if it has already been created for you, will be in a subdirectory of @@ -4648,14 +4659,14 @@ After you become more familiar with Emacs Lisp, you will find that you will frequently use @code{find-tag} to navigate your way around source code; and you will create your own @file{TAGS} tables. -@cindex Library, as term for `file' +@cindex Library, as term for ``file'' Incidentally, the files that contain Lisp code are conventionally called @dfn{libraries}. The metaphor is derived from that of a specialized library, such as a law library or an engineering library, rather than a general library. Each library, or file, contains functions that relate to a particular topic or activity, such as @file{abbrev.el} for handling abbreviations and other typing -shortcuts, and @file{help.el} for on-line help. (Sometimes several +shortcuts, and @file{help.el} for help. (Sometimes several libraries provide code for a single activity, as the various @file{rmail@dots{}} files provide code for reading electronic mail.) In @cite{The GNU Emacs Manual}, you will see sentences such as ``The @@ -4914,7 +4925,7 @@ The expression works nearly the same as before. It sets a mark at the highest numbered place in the buffer that it can. However, in this version, @code{push-mark} has two additional arguments. The second argument to @code{push-mark} is @code{nil}. This tells the function -it @emph{should} display a message that says `Mark set' when it pushes +it @emph{should} display a message that says ``Mark set'' when it pushes the mark. The third argument is @code{t}. This tells @code{push-mark} to activate the mark when Transient Mark mode is turned on. Transient Mark mode highlights the currently active @@ -4929,6 +4940,8 @@ result of this, point is placed at the beginning of the buffer and mark is set at the end of the buffer. The whole buffer is, therefore, the region. +@c FIXME: the definition of append-to-buffer has been changed (in +@c 2010-03-30). @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -4954,8 +4967,7 @@ current buffer to a specified buffer. The @code{append-to-buffer} command uses the @code{insert-buffer-substring} function to copy the region. @code{insert-buffer-substring} is described by its name: it takes a -string of characters from part of a buffer, a ``substring'', and -inserts them into another buffer. +substring from a buffer, and inserts it into another buffer. Most of @code{append-to-buffer} is concerned with setting up the conditions for @@ -5199,8 +5211,8 @@ of the two-element list, @code{(oldbuf (current-buffer))}. The body of the @code{let} expression in @code{append-to-buffer} consists of a @code{save-excursion} expression. -The @code{save-excursion} function saves the locations of point and -mark, and restores them to those positions after the expressions in the +The @code{save-excursion} function saves the location of point, and restores it +to that position after the expressions in the body of the @code{save-excursion} complete execution. In addition, @code{save-excursion} keeps track of the original buffer, and restores it. This is how @code{save-excursion} is used in @@ -5388,7 +5400,7 @@ Conventionally bound to @kbd{M-.} (that's a period following the @key{META} key). @item save-excursion -Save the location of point and mark and restore their values after the +Save the location of point and restore its value after the arguments to @code{save-excursion} have been evaluated. Also, remember the current buffer and return to it. @@ -5520,7 +5532,7 @@ the buffer you are in (and you have not seen the computer shift its attention, so you don't know that that buffer is now called @code{oldbuf}). -Incidentally, this is what is meant by `replacement'. To replace text, +Incidentally, this is what is meant by ``replacement''. To replace text, Emacs erases the previous text and then inserts new text. @need 1250 @@ -5702,8 +5714,8 @@ then the buffer itself must be got. You can imagine yourself at a conference where an usher is wandering around holding a list with your name on it and looking for you: the -usher is ``bound'' to your name, not to you; but when the usher finds -you and takes your arm, the usher becomes ``bound'' to you. +usher is bound to your name, not to you; but when the usher finds +you and takes your arm, the usher becomes bound to you. @need 800 In Lisp, you might describe this situation like this: @@ -5754,8 +5766,7 @@ so the true-or-false-test looks like this: @noindent @code{not} is a function that returns true if its argument is false and false if its argument is true. So if @code{(bufferp buffer)} -returns true, the @code{not} expression returns false and vice-verse: -what is ``not true'' is false and what is ``not false'' is true. +returns true, the @code{not} expression returns false and vice versa. Using this test, the @code{if} expression works as follows: when the value of the variable @code{buffer} is actually a buffer rather than @@ -5894,7 +5905,7 @@ the value of point, which will be at the end of the inserted text, is recorded in the variable @code{newmark}. After the body of the outer @code{save-excursion} is evaluated, point -and mark are relocated to their original places. +is relocated to its original place. However, it is convenient to locate a mark at the end of the newly inserted text and locate point at its beginning. The @code{newmark} @@ -6133,7 +6144,7 @@ size of the buffer. The reason for this is that the old version 18 Emacs used numbers that are no bigger than eight million or so and in the computation that followed, the programmer feared that Emacs might try to use over-large numbers if the buffer were large. The term -`overflow', mentioned in the comment, means numbers that are over +``overflow'', mentioned in the comment, means numbers that are over large. More recent versions of Emacs use larger numbers, but this code has not been touched, if only because people now look at buffers that are far, far larger than ever before. @@ -6153,7 +6164,7 @@ was that function called several times, it gave the size of the whole buffer, not the accessible part. The computation makes much more sense when it handles just the accessible part. (@xref{Narrowing & Widening, , Narrowing and Widening}, for more information on focusing -attention to an `accessible' part.) +attention to an accessible part.) @need 800 The line looks like this: @@ -6181,8 +6192,8 @@ This expression is a multiplication, with two arguments to the function The first argument is @code{(prefix-numeric-value arg)}. When @code{"P"} is used as the argument for @code{interactive}, the value -passed to the function as its argument is passed a ``raw prefix -argument'', and not a number. (It is a number in a list.) To perform +passed to the function as its argument is passed a @dfn{raw prefix +argument}, and not a number. (It is a number in a list.) To perform the arithmetic, a conversion is necessary, and @code{prefix-numeric-value} does the job. @@ -6323,7 +6334,7 @@ and avoids clobbering the mark." (/ (+ 10 (* size (prefix-numeric-value arg))) 10))) (point-min)))) - (if arg (forward-line 1))) + (if (and arg (not (consp arg))) (forward-line 1))) @end group @end smallexample @@ -6390,7 +6401,7 @@ to move point to the beginning of the next line if the command is invoked with an argument: @smallexample -(if arg (forward-line 1))) +(if (and arg (not (consp arg))) (forward-line 1)) @end smallexample @noindent @@ -6399,14 +6410,10 @@ appropriate tenths position in the buffer. This is a flourish that means that the cursor is always located @emph{at least} the requested tenths of the way through the buffer, which is a nicety that is, perhaps, not necessary, but which, if it did not occur, would be sure -to draw complaints. - -On the other hand, it also means that if you specify the command with -a @kbd{C-u}, but without a number, that is to say, if the `raw prefix -argument' is simply a cons cell, then the command puts you at the -beginning of the second line @dots{} I don't know whether this is -intended or whether no one has dealt with the code to avoid this -happening. +to draw complaints. (The @code{(not (consp arg))} portion is so that +if you specify the command with a @kbd{C-u}, but without a number, +that is to say, if the raw prefix argument is simply a cons cell, +the command does not put you at the beginning of the second line.) @node Second Buffer Related Review @section Review @@ -6434,7 +6441,7 @@ is optional; this means that the function can be evaluated without the argument, if desired. @item prefix-numeric-value -Convert the `raw prefix argument' produced by @code{(interactive +Convert the raw prefix argument produced by @code{(interactive "P")} to a numeric value. @item forward-line @@ -6687,8 +6694,8 @@ restored just before the completion of the function by the @code{save-restriction} special form. The call to @code{widen} is followed by @code{save-excursion}, which -saves the location of the cursor (i.e., of point) and of the mark, and -restores them after the code in the body of the @code{save-excursion} +saves the location of the cursor (i.e., of point), and +restores it after the code in the body of the @code{save-excursion} uses the @code{beginning-of-line} function to move point. (Note that the @code{(widen)} expression comes between the @@ -6759,8 +6766,8 @@ it, and @code{count-lines} counts only the lines @emph{before} the current line. After @code{count-lines} has done its job, and the message has been -printed in the echo area, the @code{save-excursion} restores point and -mark to their original positions; and @code{save-restriction} restores +printed in the echo area, the @code{save-excursion} restores point to +its original position; and @code{save-restriction} restores the original narrowing, if any. @node narrow Exercise @@ -6816,11 +6823,11 @@ namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) @end ifnottex The name of the @code{cons} function is not unreasonable: it is an -abbreviation of the word `construct'. The origins of the names for +abbreviation of the word ``construct''. The origins of the names for @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} -is an acronym from the phrase `Contents of the Address part of the -Register'; and @code{cdr} (pronounced `could-er') is an acronym from -the phrase `Contents of the Decrement part of the Register'. These +is an acronym from the phrase ``Contents of the Address part of the +Register''; and @code{cdr} (pronounced ``could-er'') is an acronym from +the phrase ``Contents of the Decrement part of the Register''. These phrases refer to specific pieces of hardware on the very early computer on which the original Lisp was developed. Besides being obsolete, the phrases have been completely irrelevant for more than 25 @@ -6855,7 +6862,7 @@ Clearly, a more reasonable name for the @code{car} function would be @code{car} does not remove the first item from the list; it only reports what it is. After @code{car} has been applied to a list, the list is still the same as it was. In the jargon, @code{car} is -`non-destructive'. This feature turns out to be important. +``non-destructive''. This feature turns out to be important. The @sc{cdr} of a list is the rest of the list, that is, the @code{cdr} function returns the part of the list that follows the @@ -6940,10 +6947,10 @@ non-destructive---that is, they do not modify or change lists to which they are applied. This is very important for how they are used. Also, in the first chapter, in the discussion about atoms, I said that -in Lisp, ``certain kinds of atom, such as an array, can be separated +in Lisp, certain kinds of atom, such as an array, can be separated into parts; but the mechanism for doing this is different from the mechanism for splitting a list. As far as Lisp is concerned, the -atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The +atoms of a list are unsplittable. (@xref{Lisp Atoms}.) The @code{car} and @code{cdr} functions are used for splitting lists and are considered fundamental to Lisp. Since they cannot split or gain access to the parts of an array, an array is considered an atom. @@ -6977,8 +6984,8 @@ appear in the echo area. @code{cons} causes the creation of a new list in which the element is followed by the elements of the original list. -We often say that `@code{cons} puts a new element at the beginning of -a list; it attaches or pushes elements onto the list', but this +We often say that @code{cons} puts a new element at the beginning of +a list, or that it attaches or pushes elements onto the list, but this phrasing can be misleading, since @code{cons} does not change an existing list, but creates a new one. @@ -7003,7 +7010,7 @@ need to provide at least an empty list at the beginning. Here is a series of @code{cons} expressions that build up a list of flowers. If you are reading this in Info in GNU Emacs, you can evaluate each of the expressions in the usual way; the value is printed in this text -after @samp{@result{}}, which you may read as `evaluates to'. +after @samp{@result{}}, which you may read as ``evaluates to''. @smallexample @group @@ -7116,7 +7123,7 @@ In an earlier version: This is written with a special notation, @samp{#<subr}, that indicates that the function @code{length} is one of the primitive functions written in C rather than in Emacs Lisp. (@samp{subr} is an - abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a + abbreviation for ``subroutine''.) @xref{What Is a Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more about subroutines. @end ignore @@ -7275,9 +7282,9 @@ This can be very convenient. Note that the elements are numbered from zero, not one. That is to say, the first element of a list, its @sc{car} is the zeroth element. -This is called `zero-based' counting and often bothers people who +This zero-based counting often bothers people who are accustomed to the first element in a list being number one, which -is `one-based'. +is one-based. @need 1250 For example: @@ -7416,7 +7423,7 @@ variable which has a list as its value, and the list to which the @noindent If you evaluate this expression, the list @code{(cat dog)} will appear in the echo area. This is the value returned by the function. The -result we are interested in is the ``side effect'', which we can see by +result we are interested in is the side effect, which we can see by evaluating the variable @code{domesticated-animals}: @smallexample @@ -7448,17 +7455,17 @@ fish. Replace the rest of that list with a list of other fish. @cindex Erasing text @cindex Deleting text -Whenever you cut or clip text out of a buffer with a `kill' command in +Whenever you cut or clip text out of a buffer with a @dfn{kill} command in GNU Emacs, it is stored in a list and you can bring it back with a -`yank' command. +@dfn{yank} command. -(The use of the word `kill' in Emacs for processes which specifically +(The use of the word ``kill'' in Emacs for processes which specifically @emph{do not} destroy the values of the entities is an unfortunate -historical accident. A much more appropriate word would be `clip' since +historical accident. A much more appropriate word would be ``clip'' since that is what the kill commands do; they clip text out of a buffer and put it into storage from which it can be brought back. I have often -been tempted to replace globally all occurrences of `kill' in the Emacs -sources with `clip' and all occurrences of `killed' with `clipped'.) +been tempted to replace globally all occurrences of ``kill'' in the Emacs +sources with ``clip'' and all occurrences of ``killed'' with ``clipped''.) @menu * Storing Text:: Text is stored in a list. @@ -7487,7 +7494,7 @@ look like this: @need 1200 @noindent The function @code{cons} can be used to create a new list from a piece -of text (an `atom', to use the jargon) and an existing list, like +of text (an ``atom'', to use the jargon) and an existing list, like this: @smallexample @@ -7531,7 +7538,7 @@ than nothing at all. The list that holds the pieces of text is called the @dfn{kill ring}. This chapter leads up to a description of the kill ring and how it is used by first tracing how the @code{zap-to-char} function works. This -function uses (or `calls') a function that invokes a function that +function calls a function that invokes a function that manipulates the kill ring. Thus, before reaching the mountains, we climb the foothills. @@ -7612,7 +7619,20 @@ Goes backward if ARG is negative; error if CHAR not found." @end smallexample The documentation is thorough. You do need to know the jargon meaning -of the word `kill'. +of the word ``kill''. + +@cindex curved quotes +@cindex curly quotes +The version 22 documentation string for @code{zap-to-char} uses ASCII +grave accent and apostrophe to quote a symbol, so it appears as +@t{`case-fold-search'}. This quoting style was inspired by 1970s-era +displays in which grave accent and apostrophe were often mirror images +suitable for use as quotes. On most modern displays this is no longer +true, and when these two ASCII characters appear in documentation +strings or diagnostic message formats, Emacs typically transliterates +them to curved single quotes, so that the abovequoted symbol appears +as @t{‘case-fold-search’}. Source-code strings can also simply use +curved quotes directly. @node zap-to-char interactive @subsection The @code{interactive} Expression @@ -7629,7 +7649,7 @@ The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies two different things. First, and most simply, is the @samp{p}. This part is separated from the next part by a newline, @samp{\n}. The @samp{p} means that the first argument to the function will be -passed the value of a `processed prefix'. The prefix argument is +passed the value of a @dfn{processed prefix}. The prefix argument is passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If the function is called interactively without a prefix, 1 is passed to this argument. @@ -7700,7 +7720,7 @@ function @code{char-to-string} to ensure that the computer treats that character as a string.) If the search is backwards, @code{search-forward} leaves point just before the first character in the target. Also, @code{search-forward} returns @code{t} for true. -(Moving point is therefore a `side effect'.) +(Moving point is therefore a side effect.) @need 1250 In @code{zap-to-char}, the @code{search-forward} function looks like this: @@ -7930,13 +7950,13 @@ The command \\[yank] can retrieve it from there. @dots{} " ;; @bullet{} Since order matters, pass point first. (interactive (list (point) (mark))) ;; @bullet{} And tell us if we cannot cut the text. - ;; `unless' is an `if' without a then-part. + ;; 'unless' is an 'if' without a then-part. (unless (and beg end) (error "The mark is not set now, so there is no region")) @end group @group - ;; @bullet{} `condition-case' takes three arguments. + ;; @bullet{} 'condition-case' takes three arguments. ;; If the first argument is nil, as it is here, ;; information about the error signal is not ;; stored for use by another function. @@ -7944,33 +7964,33 @@ The command \\[yank] can retrieve it from there. @dots{} " @end group @group - ;; @bullet{} The second argument to `condition-case' tells the + ;; @bullet{} The second argument to 'condition-case' tells the ;; Lisp interpreter what to do when all goes well. @end group @group - ;; It starts with a `let' function that extracts the string + ;; It starts with a 'let' function that extracts the string ;; and tests whether it exists. If so (that is what the - ;; `when' checks), it calls an `if' function that determines + ;; 'when' checks), it calls an 'if' function that determines ;; whether the previous command was another call to - ;; `kill-region'; if it was, then the new text is appended to + ;; 'kill-region'; if it was, then the new text is appended to ;; the previous text; if not, then a different function, - ;; `kill-new', is called. + ;; 'kill-new', is called. @end group @group - ;; The `kill-append' function concatenates the new string and - ;; the old. The `kill-new' function inserts text into a new + ;; The 'kill-append' function concatenates the new string and + ;; the old. The 'kill-new' function inserts text into a new ;; item in the kill ring. @end group @group - ;; `when' is an `if' without an else-part. The second `when' + ;; 'when' is an 'if' without an else-part. The second 'when' ;; again checks whether the current string exists; in ;; addition, it checks whether the previous command was - ;; another call to `kill-region'. If one or the other + ;; another call to 'kill-region'. If one or the other ;; condition is true, then it sets the current command to - ;; be `kill-region'. + ;; be 'kill-region'. @end group @group (let ((string (filter-buffer-substring beg end t))) @@ -7979,10 +7999,10 @@ The command \\[yank] can retrieve it from there. @dots{} " (if (eq last-command 'kill-region) @end group @group - ;; @minus{} `yank-handler' is an optional argument to - ;; `kill-region' that tells the `kill-append' and - ;; `kill-new' functions how deal with properties - ;; added to the text, such as `bold' or `italics'. + ;; @minus{} 'yank-handler' is an optional argument to + ;; 'kill-region' that tells the 'kill-append' and + ;; 'kill-new' functions how deal with properties + ;; added to the text, such as 'bold' or 'italics'. (kill-append string (< end beg) yank-handler) (kill-new string nil yank-handler))) (when (or string (eq last-command 'kill-region)) @@ -7991,7 +8011,7 @@ The command \\[yank] can retrieve it from there. @dots{} " @end group @group - ;; @bullet{} The third argument to `condition-case' tells the interpreter + ;; @bullet{} The third argument to 'condition-case' tells the interpreter ;; what to do with an error. @end group @group @@ -8034,7 +8054,7 @@ The text is deleted but saved in the kill ring." @end group @group - ;; 1. `condition-case' takes three arguments. + ;; 1. 'condition-case' takes three arguments. ;; If the first argument is nil, as it is here, ;; information about the error signal is not ;; stored for use by another function. @@ -8042,25 +8062,25 @@ The text is deleted but saved in the kill ring." @end group @group - ;; 2. The second argument to `condition-case' + ;; 2. The second argument to 'condition-case' ;; tells the Lisp interpreter what to do when all goes well. @end group @group - ;; The `delete-and-extract-region' function usually does the + ;; The 'delete-and-extract-region' function usually does the ;; work. If the beginning and ending of the region are both - ;; the same, then the variable `string' will be empty, or nil + ;; the same, then the variable 'string' will be empty, or nil (let ((string (delete-and-extract-region beg end))) @end group @group - ;; `when' is an `if' clause that cannot take an `else-part'. - ;; Emacs normally sets the value of `last-command' to the + ;; 'when' is an 'if' clause that cannot take an 'else-part'. + ;; Emacs normally sets the value of 'last-command' to the ;; previous command. @end group @group - ;; `kill-append' concatenates the new string and the old. - ;; `kill-new' inserts text into a new item in the kill ring. + ;; 'kill-append' concatenates the new string and the old. + ;; 'kill-new' inserts text into a new item in the kill ring. (when string (if (eq last-command 'kill-region) ;; if true, prepend string @@ -8070,7 +8090,7 @@ The text is deleted but saved in the kill ring." @end group @group - ;; 3. The third argument to `condition-case' tells the interpreter + ;; 3. The third argument to 'condition-case' tells the interpreter ;; what to do with an error. @end group @group @@ -8138,7 +8158,7 @@ However, if an error occurs, among its other actions, the function generating the error signal will define one or more error condition names. -An error handler is the third argument to @code{condition case}. +An error handler is the third argument to @code{condition-case}. An error handler has two parts, a @var{condition-name} and a @var{body}. If the @var{condition-name} part of an error handler matches a condition name generated by an error, then the @var{body} @@ -8200,7 +8220,7 @@ Technically speaking, @code{when} is a Lisp macro. A Lisp macro enables you to define new control constructs and other language features. It tells the interpreter how to compute another Lisp expression which will in turn compute the value. In this case, the -`other expression' is an @code{if} expression. +other expression is an @code{if} expression. The @code{kill-region} function definition also has an @code{unless} macro; it is the converse of @code{when}. The @code{unless} macro is @@ -8234,7 +8254,7 @@ The then-part is evaluated if the previous command was another call to @code{yank-handler} is an optional argument to @code{kill-region} that tells the @code{kill-append} and @code{kill-new} functions how deal -with properties added to the text, such as `bold' or `italics'. +with properties added to the text, such as bold or italics. @code{last-command} is a variable that comes with Emacs that we have not seen before. Normally, whenever a function is executed, Emacs @@ -8322,7 +8342,7 @@ document from the beginning, understanding these parts of a function is almost becoming routine. The documentation is somewhat confusing unless you remember that the -word `kill' has a meaning different from usual. The `Transient Mark' +word ``kill'' has a meaning different from usual. The Transient Mark and @code{interprogram-cut-function} comments explain certain side-effects. @@ -8474,8 +8494,8 @@ a moment. (Also, the function provides an optional argument called @code{yank-handler}; when invoked, this argument tells the function -how to deal with properties added to the text, such as `bold' or -`italics'.) +how to deal with properties added to the text, such as bold or +italics.) @c !!! bug in GNU Emacs 22 version of kill-append ? It has a @code{let*} function to set the value of the first element of @@ -8567,20 +8587,8 @@ function which in turn uses the @code{setcar} function. @unnumberedsubsubsec The @code{kill-new} function @findex kill-new -@c in GNU Emacs 22, additional documentation to kill-new: -@ignore -Optional third arguments YANK-HANDLER controls how the STRING is later -inserted into a buffer; see `insert-for-yank' for details. -When a yank handler is specified, STRING must be non-empty (the yank -handler, if non-nil, is stored as a `yank-handler' text property on STRING). - -When the yank handler has a non-nil PARAM element, the original STRING -argument is not used by `insert-for-yank'. However, since Lisp code -may access and use elements from the kill ring directly, the STRING -argument should still be a \"useful\" string for such uses." -@end ignore @need 1200 -The @code{kill-new} function looks like this: +In version 22 the @code{kill-new} function looks like this: @smallexample @group @@ -8645,7 +8653,7 @@ As usual, we can look at this function in parts. The function definition has an optional @code{yank-handler} argument, which when invoked tells the function how to deal with properties -added to the text, such as `bold' or `italics'. We will skip that. +added to the text, such as bold or italics. We will skip that. @need 1200 The first line of the documentation makes sense: @@ -8889,7 +8897,7 @@ It starts with an @code{if} expression In this case, the expression tests first to see whether @code{menu-bar-update-yank-menu} exists as a function, and if so, calls it. The @code{fboundp} function returns true if the symbol it -is testing has a function definition that `is not void'. If the +is testing has a function definition that is not void. If the symbol's function definition were void, we would receive an error message, as we did when we created errors intentionally (@pxref{Making Errors, , Generate an Error Message}). @@ -8916,7 +8924,7 @@ The expression determines whether the second argument to @end ignore @code{menu-bar-update-yank-menu} is one of the functions that make it -possible to use the `Select and Paste' menu in the Edit item of a menu +possible to use the ``Select and Paste'' menu in the Edit item of a menu bar; using a mouse, you can look at the various pieces of text you have saved and select one piece to paste. @@ -8952,7 +8960,7 @@ an existing element or as a new element, leads us to the code for bringing back text that has been cut out of the buffer---the yank commands. However, before discussing the yank commands, it is better to learn how lists are implemented in a computer. This will make -clear such mysteries as the use of the term `pointer'. But before +clear such mysteries as the use of the term ``pointer''. But before that, we will digress into C. @ignore @@ -8963,7 +8971,7 @@ expression is true, @code{kill-append} prepends the string to the just previously clipped text. For a detailed discussion, see @ref{kill-append function, , The @code{kill-append} function}.) -If you then yank back the text, i.e., `paste' it, you get both +If you then yank back the text, i.e., paste it, you get both pieces of text at once. That way, if you delete two words in a row, and then yank them back, you get both words, in their proper order, with one yank. (The @w{@code{(< end beg))}} expression makes sure the @@ -9069,7 +9077,7 @@ The sixth part is nearly like the argument that follows the @code{interactive} declaration in a function written in Lisp: a letter followed, perhaps, by a prompt. The only difference from the Lisp is when the macro is called with no arguments. Then you write a @code{0} -(which is a `null string'), as in this macro. +(which is a null string), as in this macro. If you were to specify arguments, you would place them between quotation marks. The C macro for @code{goto-char} includes @@ -9081,13 +9089,13 @@ and provides a prompt. The seventh part is a documentation string, just like the one for a function written in Emacs Lisp. This is written as a C comment. (When you build Emacs, the program @command{lib-src/make-docfile} extracts -these comments and uses them to make the ``real'' documentation.) +these comments and uses them to make the documentation.) @end itemize @need 1200 In a C macro, the formal parameters come next, with a statement of -what kind of object they are, followed by what might be called the `body' -of the macro. For @code{delete-and-extract-region} the `body' +what kind of object they are, followed by the body +of the macro. For @code{delete-and-extract-region} the body consists of the following four lines: @smallexample @@ -9113,13 +9121,13 @@ passed to @code{del_range}. These are @w{@code{XINT (start)}} and As far as the C language is concerned, @code{start} and @code{end} are two integers that mark the beginning and end of the region to be deleted@footnote{More precisely, and requiring more expert knowledge -to understand, the two integers are of type `Lisp_Object', which can +to understand, the two integers are of type @code{Lisp_Object}, which can also be a C union instead of an integer type.}. In early versions of Emacs, these two numbers were thirty-two bits long, but the code is slowly being generalized to handle other lengths. Three of the available bits are used to specify the type of -information; the remaining bits are used as `content'. +information; the remaining bits are used as content. @samp{XINT} is a C macro that extracts the relevant number from the longer collection of bits; the three other bits are discarded. @@ -9328,7 +9336,7 @@ For example: its remaining arguments to its first argument. @item nthcdr -Return the result of taking @sc{cdr} `n' times on a list. +Return the result of taking @sc{cdr} @var{n} times on a list. @iftex The @tex @@ -9336,7 +9344,7 @@ $n^{th}$ @end tex @code{cdr}. @end iftex -The `rest of the rest', as it were. +The ``rest of the rest'', as it were. @need 1250 For example: @@ -9645,7 +9653,7 @@ address-boxes for the list.) If a symbol is set to the @sc{cdr} of a list, the list itself is not changed; the symbol simply has an address further down the list. (In -the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, +the jargon, @sc{car} and @sc{cdr} are ``non-destructive''.) Thus, evaluation of the following expression @smallexample @@ -9807,7 +9815,7 @@ In an earlier section, I suggested that you might imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the -drawer holding the function definition, and vice-verse. +drawer holding the function definition, and vice versa. Actually, what is put in each drawer is the address of the value or function definition. It is as if you found an old chest in the attic, @@ -9815,7 +9823,7 @@ and in one of its drawers you found a map giving you directions to where the buried treasure lies. (In addition to its name, symbol definition, and variable value, a -symbol has a `drawer' for a @dfn{property list} which can be used to +symbol has a drawer for a @dfn{property list} which can be used to record other information. Property lists are not discussed here; see @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp Reference Manual}.) @@ -9909,8 +9917,8 @@ What does the @code{more-flowers} list now contain? @cindex Retrieving text @cindex Pasting text -Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, -you can bring it back with a `yank' command. The text that is cut out of +Whenever you cut text out of a buffer with a kill command in GNU Emacs, +you can bring it back with a yank command. The text that is cut out of the buffer is put in the kill ring and the yank commands insert the appropriate contents of the kill ring back into a buffer (not necessarily the original buffer). @@ -9922,7 +9930,7 @@ the second element. Successive @kbd{M-y} commands replace the second element with the third, fourth, or fifth element, and so on. When the last element in the kill ring is reached, it is replaced by the first element and the cycle is repeated. (Thus the kill ring is called a -`ring' rather than just a `list'. However, the actual data structure +``ring'' rather than just a ``list''. However, the actual data structure that holds the text is a list. @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the list is handled as a ring.) @@ -10066,7 +10074,7 @@ These two ways of talking about the same thing sound confusing at first but make sense on reflection. The kill ring is generally thought of as the complete structure of data that holds the information of what has recently been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} -on the other hand, serves to indicate---that is, to `point to'---that part +on the other hand, serves to indicate---that is, to point to---that part of the kill ring of which the first element (the @sc{car}) will be inserted. @@ -10150,7 +10158,7 @@ their kin; but you can use recursion, which provides a very powerful way to think about and then to solve problems@footnote{You can write recursive functions to be frugal or wasteful of mental or computer resources; as it happens, methods that people find easy---that are -frugal of `mental resources'---sometimes use considerable computer +frugal of mental resources---sometimes use considerable computer resources. Emacs was designed to run on machines that we now consider limited and its default settings are conservative. You may want to increase the values of @code{max-specpdl-size} and @@ -10213,7 +10221,7 @@ evaluated. This process is called a loop since the Lisp interpreter repeats the same thing again and again, like an airplane doing a loop. When the result of evaluating the true-or-false-test is false, the Lisp interpreter does not evaluate the rest of the @code{while} -expression and `exits the loop'. +expression and exits the loop. Clearly, if the value returned by evaluating the first argument to @code{while} is always true, the body following will be evaluated @@ -10374,7 +10382,7 @@ expression, @code{(print-elements-of-list animals)}, by typing to be printed in the @file{*scratch*} buffer instead of being printed in the echo area. (Otherwise you will see something like this in your echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which -each @samp{^J} stands for a `newline'.) +each @samp{^J} stands for a newline.) @need 1500 In a recent instance of GNU Emacs, you can evaluate these expressions @@ -10943,8 +10951,8 @@ provide for looping. Sometimes these are quicker to write than the equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) -@code{dolist} works like a @code{while} loop that `@sc{cdr}s down a -list': @code{dolist} automatically shortens the list each time it +@code{dolist} works like a @code{while} loop that @sc{cdr}s down a +list: @code{dolist} automatically shortens the list each time it loops---takes the @sc{cdr} of the list---and binds the @sc{car} of each shorter version of the list to the first of its arguments. @@ -11045,7 +11053,7 @@ of the work you have to do when writing a @code{while} expression. Like a @code{while} loop, a @code{dolist} loops. What is different is that it automatically shortens the list each time it loops---it -`@sc{cdr}s down the list' on its own---and it automatically binds +@sc{cdr}s down the list on its own---and it automatically binds the @sc{car} of each shorter version of the list to the first of its arguments. @@ -11100,7 +11108,7 @@ up the number of pebbles in a triangle. @smallexample @group (defun triangle-using-dotimes (number-of-rows) - "Using dotimes, add up the number of pebbles in a triangle." + "Using `dotimes', add up the number of pebbles in a triangle." (let ((total 0)) ; otherwise a total is a void variable (dotimes (number number-of-rows total) (setq total (+ total (1+ number)))))) @@ -11118,10 +11126,10 @@ call a program that runs exactly like itself, but with slightly different arguments. The code runs exactly the same because it has the same name. However, even though the program has the same name, it is not the same entity. It is different. In the jargon, it is a -different `instance'. +different ``instance''. -Eventually, if the program is written correctly, the `slightly -different arguments' will become sufficiently different from the first +Eventually, if the program is written correctly, the slightly +different arguments will become sufficiently different from the first arguments that the final instance will stop. @menu @@ -11161,10 +11169,10 @@ install a function definition, that is, when you evaluate a @code{defun} macro, you install the necessary equipment to build robots. It is as if you were in a factory, setting up an assembly line. Robots with the same name are built according to the same -blueprints. So they have, as it were, the same `model number', but a -different `serial number'. +blueprints. So they have the same model number, but a +different serial number. -We often say that a recursive function `calls itself'. What we mean +We often say that a recursive function ``calls itself''. What we mean is that the instructions in a recursive function cause the Lisp interpreter to run a different function that has the same name and does the same job as the first, but with different arguments. @@ -11275,7 +11283,7 @@ Uses recursion." The @code{print-elements-recursively} function first tests whether there is any content in the list; if there is, the function prints the first element of the list, the @sc{car} of the list. Then the -function `invokes itself', but gives itself as its argument, not the +function invokes itself, but gives itself as its argument, not the whole list, but the second and subsequent elements of the list, the @sc{cdr} of the list. @@ -11291,16 +11299,16 @@ a different individual from the first, but is the same model. When the second evaluation occurs, the @code{when} expression is evaluated and if true, prints the first element of the list it receives as its argument (which is the second element of the original -list). Then the function `calls itself' with the @sc{cdr} of the list +list). Then the function calls itself with the @sc{cdr} of the list it is invoked with, which (the second time around) is the @sc{cdr} of the @sc{cdr} of the original list. -Note that although we say that the function `calls itself', what we +Note that although we say that the function ``calls itself'', what we mean is that the Lisp interpreter assembles and instructs a new instance of the program. The new instance is a clone of the first, but is a separate individual. -Each time the function `invokes itself', it invokes itself on a +Each time the function invokes itself, it does so on a shorter version of the original list. It creates a new instance that works on a shorter list. @@ -11612,7 +11620,7 @@ and this provides a sense of its primal capabilities. @node Every @unnumberedsubsubsec Recursive Pattern: @emph{every} @cindex Every, type of recursive pattern -@cindex Recursive pattern: every +@cindex Recursive pattern - every In the @code{every} recursive pattern, an action is performed on every element of a list. @@ -11711,14 +11719,14 @@ But when the list has at least one element, @node Accumulate @unnumberedsubsubsec Recursive Pattern: @emph{accumulate} @cindex Accumulate, type of recursive pattern -@cindex Recursive pattern: accumulate +@cindex Recursive pattern - accumulate Another recursive pattern is called the @code{accumulate} pattern. In the @code{accumulate} recursive pattern, an action is performed on every element of a list and the result of that action is accumulated with the results of performing the action on the other elements. -This is very like the `every' pattern using @code{cons}, except that +This is very like the @code{every} pattern using @code{cons}, except that @code{cons} is not used, but some other combiner. @need 1500 @@ -11762,14 +11770,14 @@ accumulate pattern. @node Keep @unnumberedsubsubsec Recursive Pattern: @emph{keep} @cindex Keep, type of recursive pattern -@cindex Recursive pattern: keep +@cindex Recursive pattern - keep A third recursive pattern is called the @code{keep} pattern. In the @code{keep} recursive pattern, each element of a list is tested; the element is acted on and the results are kept only if the element meets a criterion. -Again, this is very like the `every' pattern, except the element is +Again, this is very like the @code{every} pattern, except the element is skipped unless it meets a criterion. @need 1500 @@ -11870,7 +11878,7 @@ think of it as a little robot---cannot complete its job. It must hand off the calculation for @code{(triangle-recursively 6)} to a second instance of the program, to a second robot. This second individual is completely different from the first one; it is, in the jargon, a -`different instantiation'. Or, put another way, it is a different +``different instantiation''. Or, put another way, it is a different robot. It is the same model as the first; it calculates triangle numbers recursively; but it has a different serial number. @@ -11914,18 +11922,17 @@ more steps. @node No deferment solution @subsection No Deferment Solution @cindex No deferment solution -@cindex Defermentless solution @cindex Solution without deferment The solution to the problem of deferred operations is to write in a manner that does not defer operations@footnote{The phrase @dfn{tail recursive} is used to describe such a process, one that uses -`constant space'.}. This requires +constant space.}. This requires writing to a different pattern, often one that involves writing two -function definitions, an `initialization' function and a `helper' +function definitions, an initialization function and a helper function. -The `initialization' function sets up the job; the `helper' function +The initialization function sets up the job; the helper function does the work. @need 1200 @@ -11936,7 +11943,7 @@ so simple, I find them hard to understand. @group (defun triangle-initialization (number) "Return the sum of the numbers 1 through NUMBER inclusive. -This is the `initialization' component of a two function +This is the initialization component of a two function duo that uses recursion." (triangle-recursive-helper 0 0 number)) @end group @@ -11946,7 +11953,7 @@ duo that uses recursion." @group (defun triangle-recursive-helper (sum counter number) "Return SUM, using COUNTER, through NUMBER inclusive. -This is the `helper' component of a two function duo +This is the helper component of a two function duo that uses recursion." (if (> counter number) sum @@ -11967,21 +11974,21 @@ Install both function definitions by evaluating them, then call @end group @end smallexample -The `initialization' function calls the first instance of the `helper' +The initialization function calls the first instance of the helper function with three arguments: zero, zero, and a number which is the number of rows in the triangle. -The first two arguments passed to the `helper' function are +The first two arguments passed to the helper function are initialization values. These values are changed when @code{triangle-recursive-helper} invokes new instances.@footnote{The jargon is mildly confusing: @code{triangle-recursive-helper} uses a process that is iterative in a procedure that is recursive. The process is called iterative because the computer need only record the three values, @code{sum}, @code{counter}, and @code{number}; the -procedure is recursive because the function `calls itself'. On the +procedure is recursive because the function calls itself. On the other hand, both the process and the procedure used by @code{triangle-recursively} are called recursive. The word -`recursive' has different meanings in the two contexts.} +``recursive'' has different meanings in the two contexts.} Let's see what happens when we have a triangle that has one row. (This triangle will have one pebble in it!) @@ -12117,7 +12124,7 @@ Internet, see @uref{http://www.gnu.org/software/texinfo/manual/texinfo/} @end ifhtml @iftex -``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU +``Indicating Definitions, Commands, etc.''@: in @cite{Texinfo, The GNU Documentation Format}. @end iftex @end itemize @@ -12134,8 +12141,8 @@ Documentation Format}. Regular expression searches are used extensively in GNU Emacs. The two functions, @code{forward-sentence} and @code{forward-paragraph}, illustrate these searches well. They use regular expressions to find -where to move point. The phrase `regular expression' is often written -as `regexp'. +where to move point. The phrase ``regular expression'' is often written +as ``regexp''. Regular expression searches are described in @ref{Regexp Search, , Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in @@ -12332,7 +12339,7 @@ search is successful, it leaves point immediately after the last character in the target. If the search is backwards, it leaves point just before the first character in the target. You may tell @code{re-search-forward} to return @code{t} for true. (Moving point -is therefore a `side effect'.) +is therefore a side effect.) Like @code{search-forward}, the @code{re-search-forward} function takes four arguments: @@ -12422,8 +12429,8 @@ Here is the code for @code{forward-sentence}: @smallexample @group (defun forward-sentence (&optional arg) - "Move forward to next `sentence-end'. With argument, repeat. -With negative argument, move backward repeatedly to `sentence-beginning'. + "Move forward to next end of sentence. With argument, repeat. +With negative argument, move backward repeatedly to start of sentence. The variable `sentence-end' is a regular expression that matches ends of sentences. Also, every paragraph boundary terminates sentences as well." @@ -12634,7 +12641,7 @@ evaluates its then-part; otherwise, the Emacs Lisp interpreter evaluates the else-part. The true-or-false-test of the @code{if} expression is the regular expression search. -It may seem odd to have what looks like the `real work' of +It may seem odd to have what looks like the real work of the @code{forward-sentence} function buried here, but this is a common way this kind of operation is carried out in Lisp. @@ -12916,6 +12923,7 @@ The next line of the @code{forward-paragraph} function begins a @code{let*} expression. This is a different than @code{let}. The symbol is @code{let*} not @code{let}. +@findex let* The @code{let*} special form is like @code{let} except that Emacs sets each variable in sequence, one after another, and variables in the latter part of the varlist can make use of the values to which Emacs @@ -13238,7 +13246,7 @@ Consider what happens when there is no fill prefix. @noindent This @code{while} loop has us searching forward for @code{sp-parstart}, which is the combination of possible whitespace -with a the local value of the start of a paragraph or of a paragraph +with the local value of the start of a paragraph or of a paragraph separator. (The latter two are within an expression starting @code{\(?:} so that they are not referenced by the @code{match-beginning} function.) @@ -13365,7 +13373,7 @@ of which I load 12---you can create a @file{TAGS} file for the Emacs Lisp files in that directory. @need 1250 -The @code{etags} program takes all the usual shell `wildcards'. For +The @code{etags} program takes all the usual shell wildcards. For example, if you have two directories for which you want a single @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where @file{../elisp/} is the second directory: @@ -13404,7 +13412,7 @@ program to attempt to find it. Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list for you the full path names of all your @file{TAGS} files. On my system, this command lists 34 @file{TAGS} files. On the other hand, a -`plain vanilla' system I recently installed did not contain any +plain vanilla system I recently installed did not contain any @file{TAGS} files. If the tags table you want has been created, you can use the @code{M-x @@ -13420,7 +13428,7 @@ visit-tags-table}. The GNU Emacs sources come with a @file{Makefile} that contains a sophisticated @code{etags} command that creates, collects, and merges tags tables from all over the Emacs sources and puts the information -into one @file{TAGS} file in the @file{src/} directory. (The +into one @file{TAGS} file in the @file{src/} directory. (The @file{src/} directory is below the top level of your Emacs directory.) @need 1250 @@ -13507,9 +13515,9 @@ For example: @smallexample @group (let* ((foo 7) - (bar (* 3 foo))) + (bar (* 3 foo))) (message "`bar' is %d." bar)) - @result{} `bar' is 21. + @result{} ‘bar’ is 21. @end group @end smallexample @@ -13538,7 +13546,7 @@ Write a function to search for a regular expression that matches two or more blank lines in sequence. @item -Write a function to search for duplicated words, such as `the the'. +Write a function to search for duplicated words, such as ``the the''. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for information on how to write a regexp (a regular expression) to match a string that is composed of two identical @@ -13548,7 +13556,7 @@ regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. @end itemize @node Counting Words -@chapter Counting: Repetition and Regexps +@chapter Counting via Repetition and Regexps @cindex Repetition for word counting @cindex Regular expressions for word counting @@ -13673,7 +13681,7 @@ forward, and false when point is at the end of the region. We could use @code{(forward-word 1)} as the expression for moving point forward word by word, but it is easier to see what Emacs identifies as a -`word' if we use a regular expression search. +``word'' if we use a regular expression search. A regular expression search that finds the pattern for which it is searching leaves point after the last character matched. This means @@ -13717,7 +13725,7 @@ single backslash has special meaning to the Emacs Lisp interpreter. It indicates that the following character is interpreted differently than usual. For example, the two characters, @samp{\n}, stand for @samp{newline}, rather than for a backslash followed by @samp{n}. Two -backslashes in a row stand for an ordinary, `unspecial' backslash, so +backslashes in a row stand for an ordinary, unspecial backslash, so Emacs Lisp interpreter ends of seeing a single backslash followed by a letter. So it discovers the letter is special.) @@ -13940,7 +13948,7 @@ What happens is this: the search is limited to the region, and fails as you expect because there are no word-constituent characters in the region. Since it fails, we receive an error message. But we do not want to receive an error message in this case; we want to receive the -message that "The region does NOT have any words." +message ``The region does NOT have any words.'' The solution to this problem is to provide @code{re-search-forward} with a third argument of @code{t}, which causes the function to return @@ -14109,8 +14117,8 @@ the region, as returned by the recursive call; and then the user. Often, one thinks of the binding within a @code{let} expression as -somehow secondary to the `primary' work of a function. But in this -case, what you might consider the `primary' job of the function, +somehow secondary to the primary work of a function. But in this +case, what you might consider the primary job of the function, counting words, is done within the @code{let} expression. @need 1250 @@ -14151,8 +14159,8 @@ Using @code{let}, the function definition looks like this: Next, we need to write the recursive counting function. -A recursive function has at least three parts: the `do-again-test', the -`next-step-expression', and the recursive call. +A recursive function has at least three parts: the do-again-test, the +next-step-expression, and the recursive call. The do-again-test determines whether the function will or will not be called again. Since we are counting words in a region and can use a @@ -14176,7 +14184,7 @@ the expression that moves point forward, word by word. The third part of a recursive function is the recursive call. -Somewhere, also, we also need a part that does the `work' of the +Somewhere, also, we also need a part that does the work of the function, a part that does the counting. A vital part! @need 1250 @@ -14432,7 +14440,7 @@ exclamation mark, and question mark. Do the same using recursion. Our next project is to count the number of words in a function definition. Clearly, this can be done using some variant of -@code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting Words: +@code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting via Repetition and Regexps}. If we are just going to count the words in one definition, it is easy enough to mark the definition with the @kbd{C-M-h} (@code{mark-defun}) command, and then call @@ -14502,9 +14510,9 @@ be difficult. When we first start thinking about how to count the words in a function definition, the first question is (or ought to be) what are -we going to count? When we speak of `words' with respect to a Lisp +we going to count? When we speak of ``words'' with respect to a Lisp function definition, we are actually speaking, in large part, of -`symbols'. For example, the following @code{multiply-by-seven} +symbols. For example, the following @code{multiply-by-seven} function contains the five symbols @code{defun}, @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In addition, in the documentation string, it contains the four words @@ -14546,8 +14554,8 @@ regexp is: @noindent This regular expression is a pattern defining one or more word constituent characters possibly followed by one or more characters -that are not word constituents. What is meant by `word constituent -characters' brings us to the issue of syntax, which is worth a section +that are not word constituents. What is meant by ``word constituent +characters'' brings us to the issue of syntax, which is worth a section of its own. @node Syntax @@ -14565,9 +14573,9 @@ character. (For more information, @pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.) Syntax tables specify which characters belong to which categories. -Usually, a hyphen is not specified as a `word constituent character'. -Instead, it is specified as being in the `class of characters that are -part of symbol names but not words.' This means that the +Usually, a hyphen is not specified as a word constituent character. +Instead, it is specified as being in the class of characters that are +part of symbol names but not words. This means that the @code{@value{COUNT-WORDS}} function treats it in the same way it treats an interword white space, which is why @code{@value{COUNT-WORDS}} counts @samp{multiply-by-seven} as three words. @@ -14586,8 +14594,8 @@ Alternatively, we can redefine the regexp used in the procedure has the merit of clarity, but the task is a little tricky. @need 1200 -The first part is simple enough: the pattern must match ``at least one -character that is a word or symbol constituent''. Thus: +The first part is simple enough: the pattern must match at least one +character that is a word or symbol constituent. Thus: @smallexample "\\(\\w\\|\\s_\\)+" @@ -14603,8 +14611,8 @@ following the group indicates that the word or symbol constituent characters must be matched at least once. However, the second part of the regexp is more difficult to design. -What we want is to follow the first part with ``optionally one or more -characters that are not constituents of a word or symbol''. At first, +What we want is to follow the first part with optionally one or more +characters that are not constituents of a word or symbol. At first, I thought I could define this with the following: @smallexample @@ -14970,7 +14978,7 @@ The task is easy: use @code{find-file-noselect} and @code{set-buffer}. @section @code{lengths-list-file} in Detail The core of the @code{lengths-list-file} function is a @code{while} -loop containing a function to move point forward `defun by defun' and +loop containing a function to move point forward defun by defun, and a function to count the number of words and symbols in each defun. This core must be surrounded by functions that do various other tasks, including finding the file, and ensuring that point starts out at the @@ -15036,14 +15044,14 @@ Next comes a call to widen the buffer if it is narrowed. This function is usually not needed---Emacs creates a fresh buffer if none already exists; but if a buffer visiting the file already exists Emacs returns that one. In this case, the buffer may be narrowed and must -be widened. If we wanted to be fully `user-friendly', we would +be widened. If we wanted to be fully user-friendly, we would arrange to save the restriction and the location of point, but we won't. The @code{(goto-char (point-min))} expression moves point to the beginning of the buffer. -Then comes a @code{while} loop in which the `work' of the function is +Then comes a @code{while} loop in which the work of the function is carried out. In the loop, Emacs determines the length of each definition and constructs a lengths' list containing the information. @@ -15064,18 +15072,19 @@ C-e} (@code{eval-last-sexp}). @c !!! 22.1.1 lisp sources location here @smallexample (lengths-list-file - "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el") + "/usr/local/share/emacs/22.1/lisp/emacs-lisp/debug.el") @end smallexample @noindent -(You may need to change the pathname of the file; the one here is for -GNU Emacs version 22.1.1. To change the expression, copy it to +You may need to change the pathname of the file; the one here is for +GNU Emacs version 22.1. To change the expression, copy it to the @file{*scratch*} buffer and edit it. @need 1200 @noindent -(Also, to see the full length of the list, rather than a truncated +Also, to see the full length of the list, rather than a truncated version, you may have to evaluate the following: +@c We do not want to insert, so do not mention the zero prefix argument. @smallexample (custom-set-variables '(eval-expression-print-length nil)) @@ -15101,7 +15110,8 @@ took seven seconds to produce and looked like this: (75 41 80 62 20 45 44 68 45 12 34 235) @end smallexample -(The newer version of @file{debug.el} contains more defuns than the +@noindent +The newer version of @file{debug.el} contains more defuns than the earlier one; and my new machine is much faster than the old one.) Note that the length of the last definition in the file is first in @@ -15262,11 +15272,11 @@ Besides a @code{while} loop, you can work on each of a list of files with recursion. A recursive version of @code{lengths-list-many-files} is short and simple. -The recursive function has the usual parts: the `do-again-test', the -`next-step-expression', and the recursive call. The `do-again-test' +The recursive function has the usual parts: the do-again-test, the +next-step-expression, and the recursive call. The do-again-test determines whether the function should call itself again, which it will do if the @code{list-of-files} contains any remaining elements; -the `next-step-expression' resets the @code{list-of-files} to the +the next-step-expression resets the @code{list-of-files} to the @sc{cdr} of itself, so eventually the list will be empty; and the recursive call calls itself on the shorter list. The complete function is shorter than this description! @@ -15367,7 +15377,7 @@ numbers. @end ifnottex Based on what we have done before, we can readily foresee that it -should not be too hard to write a function that `@sc{cdr}s' down the +should not be too hard to write a function that @sc{cdr}s down the lengths' list, looks at each element, determines which length range it is in, and increments a counter for that range. @@ -15387,7 +15397,7 @@ that we will need. Emacs contains a function to sort lists, called (as you might guess) @code{sort}. The @code{sort} function takes two arguments, the list to be sorted, and a predicate that determines whether the first of -two list elements is ``less'' than the second. +two list elements is less than the second. As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong Type Object as an Argument}), a predicate is a function that @@ -15506,7 +15516,7 @@ as a list that looks like this (but with more elements): The @code{directory-files-and-attributes} function returns a list of lists. Each of the lists within the main list consists of 13 elements. The first element is a string that contains the name of the -file---which, in GNU/Linux, may be a `directory file', that is to +file---which, in GNU/Linux, may be a @dfn{directory file}, that is to say, a file with the special attributes of a directory. The second element of the list is @code{t} for a directory, a string for symbolic link (the string is the name linked to), or @code{nil}. @@ -15571,8 +15581,8 @@ the function comes upon a sub-directory, it should go into that sub-directory and repeat its actions. However, we should note that every directory contains a name that -refers to itself, called @file{.}, (``dot'') and a name that refers to -its parent directory, called @file{..} (``double dot''). (In +refers to itself, called @file{.} (``dot''), and a name that refers to +its parent directory, called @file{..} (``dot dot''). (In @file{/}, the root directory, @file{..} refers to itself, since @file{/} has no parent.) Clearly, we do not want our @code{files-in-below-directory} function to enter those directories, @@ -15605,8 +15615,8 @@ Let's write a function definition to do these tasks. We will use a @code{while} loop to move from one filename to another within a directory, checking what needs to be done; and we will use a recursive call to repeat the actions on each sub-directory. The recursive -pattern is `accumulate' -(@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), +pattern is Accumulate +(@pxref{Accumulate}), using @code{append} as the combiner. @ignore @@ -15641,7 +15651,7 @@ Here is the function: @end group @group (cond - ;; check to see whether filename ends in `.el' + ;; check to see whether filename ends in '.el' ;; and if so, append its name to a list. ((equal ".el" (substring (car (car current-directory-list)) -3)) (setq el-files-list @@ -15857,7 +15867,7 @@ produces: (4 3 2 1) @end smallexample -Note that the @code{nreverse} function is ``destructive''---that is, +Note that the @code{nreverse} function is destructive---that is, it changes the list to which it is applied; this contrasts with the @code{car} and @code{cdr} functions, which are non-destructive. In this case, we do not want the original @code{defuns-per-range-list}, @@ -16063,7 +16073,7 @@ the function to label the axes automatically. Since Emacs is designed to be flexible and work with all kinds of terminals, including character-only terminals, the graph will need to -be made from one of the `typewriter' symbols. An asterisk will do; as +be made from one of the typewriter symbols. An asterisk will do; as we enhance the graph-printing function, we can make the choice of symbol a user option. @@ -16093,7 +16103,7 @@ a regular expression, including functions that are not interactive. What we want to look for is some command that prints or inserts columns. Very likely, the name of the function will contain either -the word `print' or the word `insert' or the word `column'. +the word ``print'' or the word ``insert'' or the word ``column''. Therefore, we can simply type @kbd{M-x apropos RET print\|insert\|column RET} and look at the result. On my system, this command once too takes quite some time, and then produced a list of 79 @@ -16230,7 +16240,7 @@ Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) @findex apply We need a function that passes a list of arguments to a function. -This function is @code{apply}. This function `applies' its first +This function is @code{apply}. This function applies its first argument (a function) to its remaining arguments, the last of which may be a list. @@ -16248,7 +16258,7 @@ returns 8. without a book such as this. It is possible to discover other functions, like @code{search-forward} or @code{insert-rectangle}, by guessing at a part of their names and then using @code{apropos}. Even -though its base in metaphor is clear---`apply' its first argument to +though its base in metaphor is clear---apply its first argument to the rest---I doubt a novice would come up with that particular word when using @code{apropos} or other aid. Of course, I could be wrong; after all, the function was first named by someone who had to invent @@ -16336,7 +16346,7 @@ returns As written, @code{column-of-graph} contains a major flaw: the symbols used for the blank and for the marked entries in the column are -`hard-coded' as a space and asterisk. This is fine for a prototype, +hard-coded as a space and asterisk. This is fine for a prototype, but you, or another user, may wish to use other symbols. For example, in testing the graph function, you many want to use a period in place of the space, to make sure the point is being repositioned properly @@ -16415,7 +16425,7 @@ is no more than a bar graph in which the part of each bar that is below the top is blank. To construct a column for a line graph, the function first constructs a list of blanks that is one shorter than the value, then it uses @code{cons} to attach a graph symbol to the -list; then it uses @code{cons} again to attach the `top blanks' to +list; then it uses @code{cons} again to attach the top blanks to the list. It is easy to see how to write such a function, but since we don't @@ -16531,7 +16541,7 @@ The one unexpected expression in this function is the @w{@code{(sit-for 0)}} expression in the @code{while} loop. This expression makes the graph printing operation more interesting to watch than it would be otherwise. The expression causes Emacs to -`sit' or do nothing for a zero length of time and then redraw the +@dfn{sit} or do nothing for a zero length of time and then redraw the screen. Placed here, it causes Emacs to redraw the screen column by column. Without it, Emacs would not redraw the screen until the function exits. @@ -16593,14 +16603,14 @@ Emacs will print a graph like this: @findex recursive-graph-body-print The @code{graph-body-print} function may also be written recursively. -The recursive solution is divided into two parts: an outside `wrapper' +The recursive solution is divided into two parts: an outside wrapper that uses a @code{let} expression to determine the values of several variables that need only be found once, such as the maximum height of the graph, and an inside function that is called recursively to print the graph. @need 1250 -The `wrapper' is uncomplicated: +The wrapper is uncomplicated: @smallexample @group @@ -16618,13 +16628,13 @@ The numbers-list consists of the Y-axis values." @end smallexample The recursive function is a little more difficult. It has four parts: -the `do-again-test', the printing code, the recursive call, and the -`next-step-expression'. The `do-again-test' is a @code{when} +the do-again-test, the printing code, the recursive call, and the +next-step-expression. The do-again-test is a @code{when} expression that determines whether the @code{numbers-list} contains any remaining elements; if it does, the function prints one column of the graph using the printing code and calls itself again. The function calls itself again according to the value produced by the -`next-step-expression' which causes the call to act on a shorter +next-step-expression which causes the call to act on a shorter version of the @code{numbers-list}. @smallexample @@ -16700,8 +16710,8 @@ Write a line graph version of the graph printing functions. @cindex Initialization file ``You don't have to like Emacs to like it''---this seemingly -paradoxical statement is the secret of GNU Emacs. The plain, `out of -the box' Emacs is a generic tool. Most people who use it, customize +paradoxical statement is the secret of GNU Emacs. The plain, out-of-the-box +Emacs is a generic tool. Most people who use it, customize it to suit themselves. GNU Emacs is mostly written in Emacs Lisp; this means that by writing @@ -16739,7 +16749,7 @@ person hopes to do with an unadorned file? Fundamental mode is the right default for such a file, just as C mode is the right default for editing C code. (Enough programming languages have syntaxes that enable them to share or nearly share features, so C mode is -now provided by CC mode, the `C Collection'.) +now provided by CC mode, the C Collection.) But when you do know who is going to use Emacs---you, yourself---then it makes sense to customize Emacs. @@ -16784,8 +16794,8 @@ have the same form as your @file{.emacs} file, but are loaded by everyone. Two site-wide initialization files, @file{site-load.el} and -@file{site-init.el}, are loaded into Emacs and then `dumped' if a -`dumped' version of Emacs is created, as is most common. (Dumped +@file{site-init.el}, are loaded into Emacs and then dumped if a +dumped version of Emacs is created, as is most common. (Dumped copies of Emacs load more quickly. However, once a file is loaded and dumped, a change to it does not lead to a change in Emacs unless you load it yourself or re-dump Emacs. @xref{Building Emacs, , Building @@ -16897,7 +16907,7 @@ M-x customize @end smallexample @noindent -and find that the group for editing files of data is called `data'. +and find that the group for editing files of data is called ``data''. Enter that group. Text Mode Hook is the first member. You can click on its various options, such as @code{turn-on-auto-fill}, to set the values. After you click on the button to @@ -17057,7 +17067,7 @@ Just remember: type @kbd{C-h} two times for help. @end smallexample @noindent -`Mode help', as I call this, is very helpful. Usually, it tells you +``Mode help'', as I call this, is very helpful. Usually, it tells you all you need to know. Of course, you don't need to include comments like these in your @@ -17068,7 +17078,7 @@ remember to look here to remind myself. @node Text and Auto-fill @section Text and Auto Fill Mode -Now we come to the part that `turns on' Text mode and +Now we come to the part that turns on Text mode and Auto Fill mode. @smallexample @@ -17100,7 +17110,7 @@ on C mode. Also, Emacs looks at first nonblank line of the file; if the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs possesses a list of extensions and specifications that it uses automatically. In addition, Emacs looks near the last page for a -per-buffer, ``local variables list'', if any. +per-buffer, local variables list, if any. @ifinfo @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU @@ -17153,7 +17163,7 @@ In this line, the @code{add-hook} command adds @code{turn-on-auto-fill} is the name of a program, that, you guessed it!, turns on Auto Fill mode. -Every time Emacs turns on Text mode, Emacs runs the commands `hooked' +Every time Emacs turns on Text mode, Emacs runs the commands hooked onto Text mode. So every time Emacs turns on Text mode, Emacs also turns on Auto Fill mode. @@ -17190,15 +17200,15 @@ fill commands to insert two spaces after a colon: @node Mail Aliases @section Mail Aliases -Here is a @code{setq} that `turns on' mail aliases, along with more +Here is a @code{setq} that turns on mail aliases, along with more reminders. @smallexample @group ;;; Mail mode -; To enter mail mode, type `C-x m' +; To enter mail mode, type 'C-x m' ; To enter RMAIL (for reading mail), -; type `M-x rmail' +; type 'M-x rmail' (setq mail-aliases t) @end group @end smallexample @@ -17210,7 +17220,7 @@ This @code{setq} command sets the value of the variable says, in effect, ``Yes, use mail aliases.'' Mail aliases are convenient short names for long email addresses or -for lists of email addresses. The file where you keep your `aliases' +for lists of email addresses. The file where you keep your aliases is @file{~/.mailrc}. You write an alias like this: @smallexample @@ -17248,7 +17258,7 @@ command sets values only in buffers that do not have their own local values for the variable. @ifinfo -@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. +@xref{Just Spaces, , Tabs vs.@: Spaces, emacs, The GNU Emacs Manual}. @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}. @@ -17285,9 +17295,9 @@ This also shows how to set a key globally, for all modes. @findex global-set-key The command is @code{global-set-key}. It is followed by the keybinding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for `control-c', which means `press the -control key and the @key{c} key at the same time'. The @code{w} means -`press the @key{w} key'. The keybinding is surrounded by double +shown: @code{\C-c} stands for Control-C, which means to press the +control key and the @key{c} key at the same time. The @code{w} means +to press the @key{w} key. The keybinding is surrounded by double quotation marks. In documentation, you would write this as @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather than a @key{CTRL} key, you would write @@ -17308,19 +17318,19 @@ adapt what is there. As for the keybinding itself: @kbd{C-c w}. This combines the prefix key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This set of keys, @kbd{C-c} followed by a single character, is strictly -reserved for individuals' own use. (I call these `own' keys, since +reserved for individuals' own use. (I call these @dfn{own} keys, since these are for my own use.) You should always be able to create such a keybinding for your own use without stomping on someone else's keybinding. If you ever write an extension to Emacs, please avoid taking any of these keys for public use. Create a key like @kbd{C-c -C-w} instead. Otherwise, we will run out of `own' keys. +C-w} instead. Otherwise, we will run out of own keys. @need 1250 Here is another keybinding, with a comment: @smallexample @group -;;; Keybinding for `occur' +;;; Keybinding for 'occur' ; I use occur a lot, so let's bind it to a key: (global-set-key "\C-co" 'occur) @end group @@ -17341,7 +17351,7 @@ work: @smallexample @group -;;; Unbind `C-x f' +;;; Unbind 'C-x f' (global-unset-key "\C-xf") @end group @end smallexample @@ -17359,7 +17369,7 @@ The following rebinds an existing key: @smallexample @group -;;; Rebind `C-x C-b' for `buffer-menu' +;;; Rebind 'C-x C-b' for 'buffer-menu' (global-set-key "\C-x\C-b" 'buffer-menu) @end group @end smallexample @@ -17512,8 +17522,13 @@ Incidentally, @code{load-library} is an interactive interface to the @smallexample @group (defun load-library (library) - "Load the library named LIBRARY. -This is an interface to the function `load'." + "Load the Emacs Lisp library named LIBRARY. +This is an interface to the function `load'. LIBRARY is searched +for in `load-path', both with and without `load-suffixes' (as +well as `load-file-rep-suffixes'). + +See Info node `(emacs)Lisp Libraries' for more details. +See `load-file' for a different interface to `load'." (interactive (list (completing-read "Load library: " (apply-partially 'locate-file-completion-table @@ -17524,7 +17539,7 @@ This is an interface to the function `load'." @end smallexample The name of the function, @code{load-library}, comes from the use of -`library' as a conventional synonym for `file'. The source for the +``library'' as a conventional synonym for ``file''. The source for the @code{load-library} command is in the @file{files.el} library. Another interactive command that does a slightly different job is @@ -17549,15 +17564,15 @@ are not loaded right away; but you need to wait a moment when you first use such a function, while its containing file is evaluated. Rarely used functions are frequently autoloaded. The -@file{loaddefs.el} library contains hundreds of autoloaded functions, -from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may -come to use a `rare' function frequently. When you do, you should +@file{loaddefs.el} library contains thousands of autoloaded functions, +from @code{5x5} to @code{zone}. Of course, you may +come to use a rare function frequently. When you do, you should load that function's file with a @code{load} expression in your @file{.emacs} file. In my @file{.emacs} file, I load 14 libraries that contain functions that would otherwise be autoloaded. (Actually, it would have been -better to include these files in my `dumped' Emacs, but I forgot. +better to include these files in my dumped Emacs, but I forgot. @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the @file{INSTALL} file for more about dumping.) @@ -17684,7 +17699,7 @@ emacs -Q -D @group (when (>= emacs-major-version 21) (blink-cursor-mode 0) - ;; Insert newline when you press `C-n' (next-line) + ;; Insert newline when you press 'C-n' (next-line) ;; at the end of the buffer (setq next-line-add-newlines t) @end group @@ -17756,7 +17771,7 @@ file that set values: @group ;; Set calendar highlighting colors -(setq calendar-load-hook +(add-hook 'calendar-load-hook (lambda () (set-face-foreground 'diary-face "skyblue") (set-face-background 'holiday-face "slate blue") @@ -17805,9 +17820,9 @@ Set the shape and color of the mouse cursor: @smallexample @group ; Cursor shapes are defined in -; `/usr/include/X11/cursorfont.h'; -; for example, the `target' cursor is number 128; -; the `top_left_arrow' cursor is number 132. +; '/usr/include/X11/cursorfont.h'; +; for example, the 'target' cursor is number 128; +; the 'top_left_arrow' cursor is number 132. @end group @group @@ -17858,10 +17873,10 @@ problem recently.) @smallexample @group -;; Translate `C-h' to <DEL>. +;; Translate 'C-h' to <DEL>. ; (keyboard-translate ?\C-h ?\C-?) -;; Translate <DEL> to `C-h'. +;; Translate <DEL> to 'C-h'. (keyboard-translate ?\C-? ?\C-h) @end group @end smallexample @@ -17879,7 +17894,7 @@ problem recently.) or start GNU Emacs with the command @code{emacs -nbc}. @need 1250 -@item When using `grep'@* +@item When using @command{grep}@* @samp{-i}@w{ } Ignore case distinctions@* @samp{-n}@w{ } Prefix each line of output with line number@* @samp{-H}@w{ } Print the filename for each match.@* @@ -17918,7 +17933,7 @@ This avoids problems with symbolic links. @end group @end smallexample -If you want to write with Chinese `GB' characters, set this instead: +If you want to write with Chinese GB characters, set this instead: @smallexample @group @@ -17961,7 +17976,7 @@ Lock} key is at the far left of the home row: @smallexample @group -# Bind the key labeled `Caps Lock' to `Control' +# Bind the key labeled 'Caps Lock' to 'Control' # (Such a broken user interface suggests that keyboard manufacturers # think that computers are typewriters from 1885.) @@ -18098,7 +18113,7 @@ beginning @code{(#("%12b" 0 4 @dots{}}. The @code{#(} begins the list. The @samp{"%12b"} displays the current buffer name, using the -@code{buffer-name} function with which we are familiar; the `12' +@code{buffer-name} function with which we are familiar; the @samp{12} specifies the maximum number of characters that will be displayed. When a name has fewer characters, whitespace is added to fill out to this number. (Buffer names can and often should be longer than 12 @@ -18108,7 +18123,7 @@ window.) @code{:eval} says to evaluate the following form and use the result as a string to display. In this case, the expression displays the first component of the full system name. The end of the first component is -a @samp{.} (`period'), so I use the @code{string-match} function to +a @samp{.} (period), so I use the @code{string-match} function to tell me the length of the first component. The substring from the zeroth character to that length is the name of the machine. @@ -18123,18 +18138,18 @@ This is the expression: @end smallexample @samp{%[} and @samp{%]} cause a pair of square brackets -to appear for each recursive editing level. @samp{%n} says `Narrow' +to appear for each recursive editing level. @samp{%n} says ``Narrow'' when narrowing is in effect. @samp{%P} tells you the percentage of -the buffer that is above the bottom of the window, or `Top', `Bottom', -or `All'. (A lower case @samp{p} tell you the percentage above the +the buffer that is above the bottom of the window, or ``Top'', ``Bottom'', +or ``All''. (A lower case @samp{p} tell you the percentage above the @emph{top} of the window.) @samp{%-} inserts enough dashes to fill out the line. -Remember, ``You don't have to like Emacs to like it''---your own +Remember, you don't have to like Emacs to like it---your own Emacs can have different colors, different commands, and different keys than a default Emacs. -On the other hand, if you want to bring up a plain `out of the box' +On the other hand, if you want to bring up a plain out-of-the-box Emacs, with no customization, type: @smallexample @@ -18235,9 +18250,9 @@ Debugger entered--Lisp error: (void-function 1=) long lines. As usual, you can quit the debugger by typing @kbd{q} in the @file{*Backtrace*} buffer.) -In practice, for a bug as simple as this, the `Lisp error' line will +In practice, for a bug as simple as this, the Lisp error line will tell you what you need to know to correct the definition. The -function @code{1=} is `void'. +function @code{1=} is void. @ignore @need 800 @@ -18533,7 +18548,7 @@ beginning of the @code{if} line of the function. Also, you will see an arrowhead at the left hand side of that line. The arrowhead marks the line where the function is executing. (In the following examples, we show the arrowhead with @samp{=>}; in a windowing system, you may -see the arrowhead as a solid triangle in the window `fringe'.) +see the arrowhead as a solid triangle in the window fringe.) @smallexample =>@point{}(if (= number 1) @@ -18568,7 +18583,7 @@ Result: 3 (#o3, #x3, ?\C-c) @noindent This means the value of @code{number} is 3, which is octal three, -hexadecimal three, and @sc{ascii} `control-c' (the third letter of the +hexadecimal three, and @sc{ascii} Control-C (the third letter of the alphabet, in case you need to know this information). You can continue moving through the code until you reach the line with @@ -18615,7 +18630,7 @@ Lisp Reference Manual}. Install the @code{@value{COUNT-WORDS}} function and then cause it to enter the built-in debugger when you call it. Run the command on a region containing two words. You will need to press @kbd{d} a -remarkable number of times. On your system, is a `hook' called after +remarkable number of times. On your system, is a hook called after the command finishes? (For information on hooks, see @ref{Command Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference Manual}.) @@ -18686,9 +18701,9 @@ easy-to-read description of Emacs Lisp. It is written not only for experts, but for people who know what you know. (The @cite{Reference Manual} comes with the standard GNU Emacs distribution. Like this introduction, it comes as a Texinfo source file, so you can read it -on-line and as a typeset, printed book.) +on your computer and as a typeset, printed book.) -Go to the other on-line help that is part of GNU Emacs: the on-line +Go to the other built-in help that is part of GNU Emacs: the built-in documentation for all functions and variables, and @code{find-tag}, the program that takes you to sources. @@ -18736,7 +18751,7 @@ customize the @code{interactive} expression without using the standard character codes; and it shows how to create a temporary buffer. (The @code{indent-to} function is written in C rather than Emacs Lisp; -it is a `built-in' function. @code{help-follow} takes you to its +it is a built-in function. @code{help-follow} takes you to its source as does @code{find-tag}, when properly set up.) You can look at a function's source using @code{find-tag}, which is @@ -18804,7 +18819,7 @@ The GNU Emacs Lisp Reference Manual}.) You might try searching just for duplicated word-constituent characters but that does not work since the pattern detects doubles -such as the two occurrences of `th' in `with the'. +such as the two occurrences of ``th'' in ``with the''. Another possible regexp searches for word-constituent characters followed by non-word-constituent characters, reduplicated. Here, @@ -18851,7 +18866,7 @@ Here is the @code{the-the} function, as I include it in my @end group @group -;; Bind `the-the' to C-c \ +;; Bind 'the-the' to C-c \ (global-set-key "\C-c\\" 'the-the) @end group @end smallexample @@ -18997,13 +19012,21 @@ The @code{current-kill} function is used by @code{yank} and by @group (defun current-kill (n &optional do-not-move) "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. +If N is zero and `interprogram-paste-function' is set to a +function that returns a string or a list of strings, and if that +function doesn't return nil, then that string (or list) is added +to the front of the kill ring and the string (or first string in +the list) is returned as the latest kill. @end group @group -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." +If N is not zero, and if `yank-pop-change-selection' is +non-nil, use `interprogram-cut-function' to transfer the +kill at the new yank point into the window system selection. +@end group +@group +If optional arg DO-NOT-MOVE is non-nil, then don't actually +move the yanking point; just return the Nth kill forward." + (let ((interprogram-paste (and (= n 0) interprogram-paste-function (funcall interprogram-paste-function)))) @@ -19015,8 +19038,10 @@ yanking point; just return the Nth kill forward." ;; text to the kill ring, so Emacs doesn't try to own the ;; selection, with identical text. (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) + (if (listp interprogram-paste) + (mapc 'kill-new (nreverse interprogram-paste)) + (kill-new interprogram-paste))) + (car kill-ring)) @end group @group (or kill-ring (error "Kill ring is empty")) @@ -19024,8 +19049,12 @@ yanking point; just return the Nth kill forward." (nthcdr (mod (- n (length kill-ring-yank-pointer)) (length kill-ring)) kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) + (unless do-not-move + (setq kill-ring-yank-pointer ARGth-kill-element) + (when (and yank-pop-change-selection + (> n 0) + interprogram-cut-function) + (funcall interprogram-cut-function (car ARGth-kill-element)))) (car ARGth-kill-element))))) @end group @end smallexample @@ -19092,7 +19121,7 @@ The @code{if} expression has two parts, one if there exists @code{interprogram-paste} and one if not. @need 2000 -Let us consider the `if not' or else-part of the @code{current-kill} +Let us consider the else-part of the @code{current-kill} function. (The then-part uses the @code{kill-new} function, which we have already described. @xref{kill-new function, , The @code{kill-new} function}.) @@ -19156,14 +19185,14 @@ list even if the @code{do-not-move} argument is true. @ifnottex @node Digression concerning error -@unnumberedsubsubsec Digression about the word `error' +@unnumberedsubsubsec Digression about the word ``error'' @end ifnottex In my opinion, it is slightly misleading, at least to humans, to use -the term `error' as the name of the @code{error} function. A better -term would be `cancel'. Strictly speaking, of course, you cannot +the term ``error'' as the name of the @code{error} function. A better +term would be ``cancel''. Strictly speaking, of course, you cannot point to, much less rotate a pointer to a list that has no length, so -from the point of view of the computer, the word `error' is correct. +from the point of view of the computer, the word ``error'' is correct. But a human expects to attempt this sort of thing, if only to find out whether the kill ring is full or empty. This is an act of exploration. @@ -19173,8 +19202,8 @@ not necessarily an error, and therefore should not be labeled as one, even in the bowels of a computer. As it is, the code in Emacs implies that a human who is acting virtuously, by exploring his or her environment, is making an error. This is bad. Even though the computer -takes the same steps as it does when there is an `error', a term such as -`cancel' would have a clearer connotation. +takes the same steps as it does when there is an error, a term such as +``cancel'' would have a clearer connotation. @ifnottex @node Determining the Element @@ -19336,15 +19365,15 @@ The code looks like this: "Reinsert (\"paste\") the last stretch of killed text. More precisely, reinsert the stretch of killed text most recently killed OR yanked. Put point at end, and set mark at beginning. -With just \\[universal-argument] as argument, same but put point at -beginning (and mark at end). With argument N, reinsert the Nth most -recently killed stretch of killed text. +With just \\[universal-argument] as argument, same but put point at beginning (and mark at end). +With argument N, reinsert the Nth most recently killed stretch of killed +text. When this command inserts killed text into the buffer, it honors `yank-excluded-properties' and `yank-handler' as described in the doc string for `insert-for-yank-1', which see. -See also the command \\[yank-pop]." +See also the command `yank-pop' (\\[yank-pop])." @end group @group (interactive "*P") @@ -19360,8 +19389,7 @@ See also the command \\[yank-pop]." ((eq arg '-) -2) (t (1- arg))))) (if (consp arg) - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. + ;; This is like exchange-point-and-mark, but doesn't activate the mark. ;; It is cleaner to avoid activation, even though the command ;; loop would deactivate the mark because we inserted text. (goto-char (prog1 (mark t) @@ -19790,9 +19818,9 @@ For example, if you evaluate the following, the result is 15: (* (1+ (/ 12 5)) 5) @end smallexample -All through this discussion, we have been using `five' as the value +All through this discussion, we have been using 5 as the value for spacing labels on the Y axis; but we may want to use some other -value. For generality, we should replace `five' with a variable to +value. For generality, we should replace 5 with a variable to which we can assign a value. The best name I can think of for this variable is @code{Y-axis-label-spacing}. @@ -20017,7 +20045,7 @@ the @code{print-Y-axis} function, which inserts the list as a column. Height must be the maximum height of the graph. Full width is the width of the highest label element." ;; Value of height and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by print-graph. @end group @group (let ((start (point))) @@ -20299,7 +20327,7 @@ First, we create a numbered element with blank spaces before each number: @end smallexample Next, we create the function to print the numbered line, starting with -the number ``1'' under the first column: +the number 1 under the first column: @findex print-X-axis-numbered-line @smallexample @@ -20707,9 +20735,9 @@ The graph looks like this: @end smallexample @noindent -(A question: is the `2' on the bottom of the vertical axis a bug or a -feature? If you think it is a bug, and should be a `1' instead, (or -even a `0'), you can modify the sources.) +(A question: is the @samp{2} on the bottom of the vertical axis a bug or a +feature? If you think it is a bug, and should be a @samp{1} instead, (or +even a @samp{0}), you can modify the sources.) @node Graphing words in defuns @appendixsubsec Graphing Numbers of Words and Symbols @@ -20817,8 +20845,8 @@ Thus, @end smallexample @noindent -is a function definition that says `return the value resulting from -dividing whatever is passed to me as @code{arg} by 50'. +is a function that returns the value resulting from +dividing whatever is passed to it as @code{arg} by 50. @need 1200 Earlier, for example, we had a function @code{multiply-by-seven}; it @@ -20959,7 +20987,7 @@ element of its second argument, in turn. The second argument must be a sequence. The @samp{map} part of the name comes from the mathematical phrase, -`mapping over a domain', meaning to apply a function to each of the +``mapping over a domain'', meaning to apply a function to each of the elements in a domain. The mathematical phrase is based on the metaphor of a surveyor walking, one step at a time, over an area he is mapping. And @samp{car}, of course, comes from the Lisp notion of the @@ -21039,7 +21067,7 @@ that none had that many words or symbols.) @cindex Bug, most insidious type @cindex Insidious type of bug -I said `almost ready to print'! Of course, there is a bug in the +I said ``almost ready to print''! Of course, there is a bug in the @code{print-graph} function @dots{} It has a @code{vertical-step} option, but not a @code{horizontal-step} option. The @code{top-of-range} scale goes from 10 to 300 by tens. But the @@ -21142,7 +21170,7 @@ each column." @end group @group ;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by print-graph. (let* ((leading-spaces (make-string full-Y-label-width ? )) ;; symbol-width @r{is provided by} graph-body-print @@ -21470,7 +21498,7 @@ Optionally, print according to VERTICAL-STEP." @end group @group ;; Value of height and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by 'print-graph'. (let ((start (point))) (insert-rectangle (Y-axis-column height full-Y-label-width vertical-step)) @@ -21635,7 +21663,7 @@ each column." @end group @group ;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by 'print-graph'. (let* ((leading-spaces (make-string full-Y-label-width ? )) ;; symbol-width @r{is provided by} graph-body-print @@ -21873,7 +21901,7 @@ users think that a proprietary manual is good enough---so they don't see the need to write a free manual. They do not see that the free operating system has a gap that needs filling. -Why do users think that proprietary manuals are good enough? Some have +Why do users think that proprietary manuals are good enough? Some have not considered the issue. I hope this article will do something to change that. diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps index 11f3318037c..21b180c27cf 100644 --- a/doc/lispintro/lambda-1.eps +++ b/doc/lispintro/lambda-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:31:53 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps index 3022ce9bb6c..6eff61bbd22 100644 --- a/doc/lispintro/lambda-2.eps +++ b/doc/lispintro/lambda-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:09 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-3.eps b/doc/lispintro/lambda-3.eps index 0d66eb73332..6ab228262d5 100644 --- a/doc/lispintro/lambda-3.eps +++ b/doc/lispintro/lambda-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:49 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in deleted file mode 100644 index 39760ba5612..00000000000 --- a/doc/lispintro/makefile.w32-in +++ /dev/null @@ -1,85 +0,0 @@ -#### -*- Makefile -*- for the Emacs Lisp Introduction manual. - -# Copyright (C) 2003-2013 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. - - -srcdir = . - -infodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs - -INFO_EXT=.info -INFO_OPTS=--no-split -I$(emacsdir) -INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi $(emacsdir)/emacsver.texi \ - $(srcdir)/doclicense.texi -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing -INFO_TARGETS = $(infodir)/eintr$(INFO_EXT) -DVI_TARGETS = emacs-lisp-intro.dvi - -MAKEINFO = makeinfo -INSTALL_INFO = install-info -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips -ENVADD = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir) -I$(emacsdir) -I$(texinfodir)" /C - -.SUFFIXES: .dvi .ps .texi - -info: $(INFO_TARGETS) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -$(infodir)/eintr$(INFO_EXT): $(INFO_SOURCES) - $(MAKEINFO) $(INFO_OPTS) -o $@ $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.dvi: $(INFO_SOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.pdf: $(INFO_SOURCES) - $(ENVADD) $(TEXI2PDF) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.html: $(INFO_SOURCES) - $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi - -.dvi.ps: - $(DVIPS) $< -o $@ - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr *.tp - -clean: mostlyclean - - $(DEL) *.dvi $(infodir)/eintr$(INFO_EXT)* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc - -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/doc/lispref/.gitignore b/doc/lispref/.gitignore deleted file mode 100644 index ba74d365995..00000000000 --- a/doc/lispref/.gitignore +++ /dev/null @@ -1,13 +0,0 @@ -texput.log -elisp.?? -elisp.??? -config.log -config.cache -config.status -Makefile -makefile -elisp -elisp-? -elisp-?? -elisp1* -elisp2* diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog.1 index d2e86c25cc1..e508839cd5b 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog.1 @@ -1,3 +1,1634 @@ +2015-03-29 Glenn Morris <rgm@gnu.org> + + * objects.texi (Equality Predicates): Fix typo in example. + +2015-03-25 Stefan Monnier <monnier@iro.umontreal.ca> + + * positions.texi (Excursions, Narrowing): `save-excursion' does not + save&restore the mark any more. + +2015-03-24 Paul Eggert <eggert@cs.ucla.edu> + + * numbers.texi (Float Basics): Improve ldexp documentation. + +2015-03-23 Eli Zaretskii <eliz@gnu.org> + + * commands.texi (Event Input Misc): Fix incorrect usage of @code. + (Bug#20174) + (Accessing Mouse): Expand documentation of 'posn-actual-col-row'. + (Bug#20169) + More accurate description of 'posn-object-x-y'. (Bug#20168) + +2015-03-23 Daiki Ueno <ueno@gnu.org> + + * processes.texi (Asynchronous Processes): Mention `make-process'. + +2015-03-18 Eli Zaretskii <eliz@gnu.org> + + * minibuf.texi (Basic Completion): Fix a typo. (Bug#20108) + +2015-03-09 Nicolas Petton <nicolas@petton.fr> + + * sequences.texi (seq-into): Add documentation for the new + seq-into function. + +2015-03-03 Eli Zaretskii <eliz@gnu.org> + + * processes.texi (Synchronous Processes): Update documentation of + call-process-shell-command and process-file-shell-command. + +2015-03-03 Daniel Colascione <dancol@dancol.org> + + * control.texi (Generators): Correct missing word. Clarify which + forms are legal in which parts of `unwind-protect'. Fix orphaned + close parenthesis. + + * objects.texi (Finalizer Type): New section for finalizer objects. + (Type Predicates): Mention finalizers in `type-of' documentation. + * elisp.texi (Top): Link to finalizer type. + +2015-03-02 Daniel Colascione <dancol@dancol.org> + + * control.texi (Generators): New section + * elisp.texi: Reference new section. + +2015-02-28 Eli Zaretskii <eliz@gnu.org> + + * searching.texi (Char Classes): Update the documentation of + [:alpha:] and [:alnum:]. (Bug#19878) + +2015-02-27 Eli Zaretskii <eliz@gnu.org> + + * os.texi (Startup Summary): + * display.texi (Window Systems): Mention peculiarities of daemon + mode on MS-Windows. + +2015-02-11 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size Parameters): Update description of + fullscreen frame parameter. Describe `fullscreen-restore' + parameter. + +2015-02-09 Nicolas Petton <nicolas@petton.fr> + + * sequences.texi (Sequence Functions): Update documentation + examples for seq-group-by. + +2015-02-09 Eli Zaretskii <eliz@gnu.org> + + * positions.texi (Screen Lines): Update the documentation of + vertical-motion to document the new additional argument. + +2015-02-06 Nicolas Petton <nicolas@petton.fr> + + * sequences.texi (Sequence Functions): Add documentation for + seq-mapcat, seq-partition and seq-group-by. + +2015-02-05 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Size of Displayed Text): Remove description of + optional argument BUFFER of `window-text-pixel-size'. + +2015-02-01 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Size of Displayed Text): Describe optional + argument BUFFER of `window-text-pixel-size'. + +2015-01-28 Eli Zaretskii <eliz@gnu.org> + + * searching.texi (Regexp Search): Add a cross-reference to "Syntax + of Regexps". (Bug#19668) + +2015-01-28 Daniel Koning <dk@danielkoning.com> (tiny change) + + * commands.texi (Drag Events, Motion Events, Event Examples) + (Accessing Mouse): Describe actual range of values that mouse + position objects can have. + +2015-01-28 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Manipulating Buttons): Explain more about the + 'action' property. (Bug#19628) + + * text.texi (Clickable Text): Improve indexing. (Bug#19629) + + * variables.texi (Creating Buffer-Local): Improve indexing. (Bug#19608) + + * frames.texi (Display Feature Testing): Make the description of + x-server-version and x-server-vendor less X-specific. (Bug#19502) + +2015-01-15 Eli Zaretskii <eliz@gnu.org> + + * streams.texi (Input Functions): Document 'set-binary-mode'. + (Output Functions): Cross-reference to documentation of + 'set-binary-mode'. + +2015-01-04 Paul Eggert <eggert@cs.ucla.edu> + + batch write-region no longer says "Wrote FOO" + * files.texi (Writing to Files): Document this. + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/elisp.info, elisp.html): + Use them. + +2014-12-30 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Temporary Displays): Amend description of + `with-temp-buffer-window'. Add descriptions for + `with-current-buffer-window', `with-displayed-buffer-window' and + `temp-buffer-resize-mode', `temp-buffer-max-height' and + `temp-buffer-max-width'. + +2014-12-29 Paul Eggert <eggert@cs.ucla.edu> + + * os.texi (System Environment): Update for system-name changes. + +2014-12-27 Glenn Morris <rgm@gnu.org> + + * control.texi (Pattern matching case statement): + * os.texi (Desktop Notifications): + * modes.texi (Defining Minor Modes, SMIE Lexer): Markup fixes. + +2014-12-27 Eli Zaretskii <eliz@gnu.org> + + * windows.texi (Recombining Windows): Index subject of sections. + + * variables.texi (Variables with Restricted Values) + (Generalized Variables): Index subject of sections. + + * text.texi (Buffer Contents, Examining Properties) + (Changing Properties, Property Search, Substitution): Index + subject of sections. + + * syntax.texi (Motion and Syntax, Parsing Expressions) + (Motion via Parsing, Position Parse, Control Parsing): Index + subject of sections. + + * strings.texi (Predicates for Strings, Creating Strings) + (Modifying Strings, Text Comparison): Index subject of sections. + + * searching.texi (Syntax of Regexps, Regexp Special) + (Regexp Functions, Regexp Functions): Index subject of sections. + + * processes.texi (Subprocess Creation, Process Information): Index + subject of sections. + + * positions.texi (Screen Lines): Index subject of sections. + + * nonascii.texi (Scanning Charsets, Specifying Coding Systems): + Index subject of sections. + + * minibuf.texi (Text from Minibuffer, Object from Minibuffer) + (Multiple Queries, Minibuffer Contents): Index subject of + sections. + + * markers.texi (Predicates on Markers, Creating Markers) + (Information from Markers, Moving Markers): Index subject of + sections. + + * macros.texi (Defining Macros, Problems with Macros): Index + subject of sections. + + * loading.texi (Loading Non-ASCII, Where Defined): Index subject + of sections. + + * lists.texi (List-related Predicates, List Variables, Setcar) + (Setcdr, Plist Access): Index subject of sections. + + * keymaps.texi (Controlling Active Maps, Scanning Keymaps) + (Modifying Menus): Index subject of sections. + + * help.texi (Accessing Documentation, Help Functions): Index + subject of sections. + + * hash.texi (Hash Access): Index subject of sections. + + * functions.texi (Core Advising Primitives) + (Advising Named Functions, Porting old advices): Index subject of + sections. + + * frames.texi (Creating Frames, Initial Parameters) + (Position Parameters, Buffer Parameters, Minibuffers and Frames) + (Pop-Up Menus, Drag and Drop): Index subject of sections. + + * files.texi (Visiting Functions, Kinds of Files) + (Unique File Names): Index subject of sections. + + * display.texi (Refresh Screen, Echo Area Customization) + (Warning Variables, Warning Options, Delayed Warnings) + (Temporary Displays, Managing Overlays, Overlay Properties) + (Finding Overlays, Size of Displayed Text, Defining Faces) + (Attribute Functions, Displaying Faces, Face Remapping) + (Basic Faces, Font Lookup, Fontsets, Replacing Specs) + (Defining Images, Showing Images): Index subject of sections. + + * debugging.texi (Debugging, Explicit Debug) + (Invoking the Debugger, Excess Open, Excess Close): Index subject + of sections. + + * customize.texi (Defining New Types, Applying Customizations) + (Custom Themes): Index subject of sections. + + * control.texi (Sequencing, Combining Conditions) + (Processing of Errors, Cleanups): Index subject of sections. + + * compile.texi (Eval During Compile): Index subject of sections. + + * commands.texi (Using Interactive, Distinguish Interactive) + (Command Loop Info, Classifying Events, Event Mod) + (Invoking the Input Method): Index subject of sections. + + * buffers.texi (Buffer List, Buffer Gap): Index subject of sections. + + * backups.texi (Making Backups, Numbered Backups, Backup Names) + (Reverting): Index subject of sections. + + * abbrevs.texi (Abbrev Tables, Defining Abbrevs, Abbrev Files) + (Abbrev Expansion, Standard Abbrev Tables, Abbrev Properties) + (Abbrev Table Properties): Index subject of sections. + + * os.texi (Time of Day, Time Conversion, Time Parsing) + (Time Calculations, Idle Timers): Index subject of sections. + +2014-12-25 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Windows): Resync @menu order with @node order. + + * minibuf.texi (Minibuffer Windows): Add descriptions of + `resize-mini-windows' and `max-mini-window-height'. + +2014-12-25 Glenn Morris <rgm@gnu.org> + + * windows.texi (Windows): Sync @menu order with @node order. + + * sequences.texi (Sequence Functions): Copyedits. + + * control.texi (Pattern matching case statement): + * positions.texi (List Motion): + * streams.texi (Output Functions): + * strings.texi (Text Comparison): + * text.texi (Document Object Model): Markup fixes. + +2014-12-22 Paul Eggert <eggert@cs.ucla.edu> + + Remove obsolete references to pre-C99 builds + * internals.texi (C Integer Types): Don't mention pre-C99 compilers. + +2014-12-19 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Resizing Windows): Describe new argument of + `fit-window-to-buffer'. Move description of `window-size-fixed' + to new section below. + (Preserving Window Sizes): New section describing + `window-size-fixed' and `window-preserve-size'. + (Display Action Functions): Describe `preserve-size' alist + entry. + (Window Parameters): Describe `preserved-size' parameter. + +2014-12-18 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Low-Level Font): Document font-info and query-font. + +2014-12-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * display.texi (Forcing Redisplay): Remove references to + redisplay-dont-pause and redisplay-preemption-period (which doesn't + even exist). + +2014-12-16 Nicolas Petton <petton.nicolas@gmail.com> + + * sequences.texi (Seq Library): Add documentation for seq.el. + +2014-12-15 Alan Mackenzie <acm@muc.de> + + "Advice" is a mass noun. Amend text accordingly. + * functions.texi: (Advising Functions, Core Advising Primitives) + (Advising Named Functions, Advice combinators) + (Porting old advice): Replace, e.g., "an advice" with "advice". + +2014-12-13 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * files.texi (Relative File Names): Mention `directory-name-p'. + +2014-12-13 Eli Zaretskii <eliz@gnu.org> + + * text.texi (Comparing Text): Prevent a text string from being + broken between 2 lines. (Bug#19257) + +2014-12-09 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * files.texi (Contents of Directories): + Document directory-files-recursively. + +2014-12-04 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): + Document 'buffer-substring-with-bidi-context'. + + * text.texi (Buffer Contents): + Mention 'buffer-substring-with-bidi-context' with a cross-reference. + +2014-12-02 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): + Document 'bidi-find-overridden-directionality'. + +2014-11-29 Paul Eggert <eggert@cs.ucla.edu> + + Lessen focus on ChangeLog files, as opposed to change log entries. + * intro.texi (Acknowledgments): ChangeLog file -> change log entries. + * tips.texi (Library Headers): Emacs uses a version control system. + +2014-11-27 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Document Object Model): Mention `dom-pp'. + +2014-11-26 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Document Object Model): New node to document dom.el. + +2014-11-24 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * processes.texi (Network Security): Made into its own section and + fleshed out. + (Network Security): Mention more NSM variables. + (Processes): Move the Network Security Manager stuff to the Emacs + manual. + +2014-11-23 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * processes.texi (Network): Mention the new :warn-unless-encrypted + parameter to `open-network-stream'. + (Network): Mention the Network Security Manager. + +2014-11-21 Ulf Jasper <ulf.jasper@web.de> + + * text.texi (Parsing HTML/XML): Document new optional parameter + 'discard-comments' of 'libxml-parse(html|xml)-region'. + +2014-11-18 Leo Liu <sdl.web@gmail.com> + + * functions.texi (Advising Named Functions): + Document define-advice. + +2014-11-17 Paul Eggert <eggert@cs.ucla.edu> + + Improve time stamp handling, and be more consistent about it. + * os.texi (Time of Day, Time Conversion, Time Parsing) + (Processor Run Time, Time Calculations): + Document the new behavior, plus be clearer about the old behavior. + (Idle Timers): Take advantage of new functionality. + +2014-11-16 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Special Properties): Mention `inhibit-read-only'. + +2014-11-14 Paul Eggert <eggert@cs.ucla.edu> + + * os.texi (Time of Day): + Use leading zero with 24-hour times less than 10:00. + +2014-11-09 Glenn Morris <rgm@gnu.org> + + * Makefile.in (version): Remove variable. + (clean): No longer delete dist tarfile. + (dist): Remove rule; replace with code in admin.el. + +2014-11-07 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size and Position): Rewrite description of + `frame-inhibit-implied-resize'. + +2014-10-22 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size Parameters): Replace "frame contents" by + "frame's text area". Add reference to Size and Position + section. + (Size and Position): Major rewrite. Add explanations for + frame's default font, text and display areas. Add descriptions + for `set-frame-font', `frame-text-height', `frame-text-width' + and `frame-inhibit-implied-resize'. + +2014-10-20 Glenn Morris <rgm@gnu.org> + + * Merge in all changes up to 24.4 release. + +2014-10-20 Tom Tromey <tom@tromey.com> + + * objects.texi (Type Predicates): Don't mention display-table-p. + +2014-10-15 Eli Zaretskii <eliz@gnu.org> + + * nonascii.texi (Character Properties): Document the new + properties 'bracket-type' and 'paired-bracket'. + + * display.texi (Bidirectional Display): Update the version of the + UBA to which we are conforming. + +2014-10-13 Glenn Morris <rgm@gnu.org> + + * Makefile.in (dist): Update for new output variables. + +2014-10-12 Glenn Morris <rgm@gnu.org> + + * elisp.texi (DATE): Bump to October 2014. + +2014-10-09 Glenn Morris <rgm@gnu.org> + + * frames.texi (Multiple Terminals): Copyedits. + +2014-10-09 Eli Zaretskii <eliz@gnu.org> + + * frames.texi (Multiple Terminals): Improve the description of X + display names. Add index entries. + (Basic Parameters): Add a cross-reference to where X display names + are described. + (Position Parameters): Mention that positional parameters of the + form (+ POS) can be negative if they are on a non-primary monitor + of a multi-monitor display. (Bug#18636) + (Creating Frames): Mention that on multi-monitor displays the + frame might be positioned differently than specified by the frame + parameters alist. + +2014-10-08 Leo Liu <sdl.web@gmail.com> + + * streams.texi (Output Functions): Document new argument ENSURE to + terpri. (Bug#18652) + +2014-10-04 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Scroll Bars): Add description of horizontal scroll + bars and associated functions. + * frames.texi (Layout Parameters): Add horizontal scroll bar + entries. Remove paragraph on "combined fringe widths". + * windows.texi (Window Sizes): Describe affects of horizontal + scroll bars on window layout and sizes. Fix description of + window-full-height-p. + (Resizing Windows): Mention horizontal scroll bar. + +2014-10-04 Glenn Morris <rgm@gnu.org> + + * commands.texi (Generic Commands): Copyedits. + + * display.texi (Scroll Bars): + * modes.texi (Header Lines): Copyedits. + + * buffers.texi (Buffer List): + * display.texi (Image Descriptors, Defining Images): + * functions.texi (Core Advising Primitives): Small fixes re @var usage. + + * windows.texi (Window Sizes, Resizing Windows): Copyedits. + + * frames.texi (Multiple Terminals): Copyedits re multiple monitors. + +2014-10-03 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size Parameters, Size and Position): Mention that + with some window managers you have to set `frame-resize-pixelwise' + in order make a frame truly fullscreen or maximized. + +2014-10-01 Paul Eggert <eggert@cs.ucla.edu> + + Improve doc for use of 'int', and discuss 'ssize_t'. + * internals.texi (C Integer Types): Mention 'int' for other + randomish values that lie in 'int' range. Mention 'ssize_t'. See: + http://lists.gnu.org/archive/html/emacs-devel/2014-10/msg00019.html + + Use AUTO_CONS instead of SCOPED_CONS, etc. + * internals.texi (Stack-allocated Objects): + Adjust to match the revised, less error-prone macros. + +2014-09-30 Paul Eggert <eggert@cs.ucla.edu> + + * internals.texi (Stack-allocated Objects): Further improvements. + Give an example of misuse. + +2014-09-30 Eli Zaretskii <eliz@gnu.org> + + * internals.texi (Stack-allocated Objects): Minor improvements of + the wording and the indexing. + +2014-09-30 Dmitry Antipov <dmantipov@yandex.ru> + + * internals.texi (Stack-allocated Objects): Describe this feature. + +2014-09-15 Daniel Colascione <dancol@dancol.org> + + * text.texi (Registers): Make `insert-register' documentation + reflect interface change. + +2014-09-08 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Core Advising Primitives): Add a note about the + confusing treatment of `interactive' for :filter-args (bug#18399). + +2014-09-07 Michael Albinus <michael.albinus@gmx.de> + + * strings.texi (Text Comparison): Describe `string-collate-equalp' + and `string-collate-lessp'. + +2014-09-06 Leo Liu <sdl.web@gmail.com> + + * control.texi (Pattern matching case statement): Document vector + qpattern. (Bug#18327) + +2014-08-29 Dmitry Antipov <dmantipov@yandex.ru> + + * lists.texi (Functions that Rearrange Lists): + Remove description of sort ... + * sequences.texi (Sequence Functions): ... and generalize + it for sequences. Add an example. + +2014-08-28 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): Update the Emacs's class + of bidirectional conformance. + +2014-08-27 Dmitry Antipov <dmantipov@yandex.ru> + + * eval.texi (Eval): Mention possible recovery from stack overflow. + +2014-07-11 Eli Zaretskii <eliz@gnu.org> + + * internals.texi (Garbage Collection): Fix last change. + +2014-07-11 Dmitry Antipov <dmantipov@yandex.ru> + + * internals.texi (Garbage Collection): Mention memory-info. + +2014-07-11 Michael Albinus <michael.albinus@gmx.de> + + * minibuf.texi (Intro to Minibuffers, Reading a Password): + Password hiding is available in batch mode, do not mention it in + the exclusion list. Mention `read-hide-char'. (Bug#17839) + +2014-07-09 Stefan Monnier <monnier@iro.umontreal.ca> + + * debugging.texi (Function Debugging, Debugger Commands): + Update debug-on-entry w.r.t behavior after redefinitions (bug#17902). + +2014-07-03 Glenn Morris <rgm@gnu.org> + + * help.texi (Help Functions): "Online" help doesn't mean what it + used to any more. + +2014-07-02 Stefan Monnier <monnier@iro.umontreal.ca> + + * keymaps.texi (Key Lookup): Remove mention of indirect entries. + (Scanning Keymaps): Reword the `noindirect' argument. + +2014-06-28 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Intro to Minibuffers): Batch mode is basic. + (Reading a Password): Mention batch mode. (Bug#17839) + +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with explicit rule. + (html): Declare as PHONY. + (${buildinfodir}): New rule. + ($(buildinfodir)/elisp.info): Use order-only prereq for output dir. + Use $<. + (elisp.dvi, elisp.html, elisp.pdf): Use $<. + (elisp.ps): New rule. + +2014-06-21 Eli Zaretskii <eliz@gnu.org> + + * positions.texi (Screen Lines): Clarify how columns are counted + by vertical-motion. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-15 Eli Zaretskii <eliz@gnu.org> + + * commands.texi (Accessing Mouse): Improve the wording of the + posn-col-row documentation. (Bug#17768) + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-09 Paul Eggert <eggert@cs.ucla.edu> + + Say (accept-process-output P)'s result pertains to P if P is non-nil. + * processes.texi (Accepting Output): Mention that if PROCESS is non-nil, + the return value is about PROCESS, not about other processes. + +2014-06-08 Glenn Morris <rgm@gnu.org> + + * os.texi (Startup Summary): Small fix for initial-buffer-choice. + + * files.texi (Subroutines of Visiting): Mention uniquify. + + * numbers.texi (Comparison of Numbers): Copyedits. + +2014-06-08 Glenn Morris <rgm@gnu.org> + + * display.texi (Window Systems): Remove window-setup-hook. + * os.texi (Startup Summary, Init File): + Improve description of window-setup-hook. + (Terminal-Specific): Update window-setup-hook cross-reference. + * hooks.texi (Standard Hooks): Update window-setup-hook cross-reference. + + * display.texi (Overlay Properties): Update re priority. (Bug#17234) + + * package.texi (Package Archives): Mention signing packages. + +2014-06-07 Eli Zaretskii <eliz@gnu.org> + + * commands.texi (Click Events): Update contents of click event's + position list due to last changes in make_lispy_position. + +2014-06-02 Glenn Morris <rgm@gnu.org> + + * text.texi (Buffer Contents): + Update for filter-buffer-substring changes. + + * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes. + * functions.texi (Advising Functions): Standardize menu case. + +2014-05-26 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Invisible Text): Clarify the description of + line-move-ignore-invisible. (Bug#17511) + +2014-05-22 Leo Liu <sdl.web@gmail.com> + + * sequences.texi (Sequence Functions): Don't mention when and how + SEQ to nreverse is mutated. + +2014-05-21 Leo Liu <sdl.web@gmail.com> + + * sequences.texi (Sequence Functions): Update nreverse. + +2014-05-19 Paul Eggert <eggert@cs.ucla.edu> + + Allow any non-nil value to count as true in bool-vector. + * sequences.texi (Bool-Vectors): Coalesce discussion of how to + print them. bool-vector's args need not be t or nil. + +2014-05-19 Dmitry Antipov <dmantipov@yandex.ru> + + * sequences.texi (Bool-vectors): Mention bool-vector. + +2014-05-17 Paul Eggert <eggert@cs.ucla.edu> + + Assume C99 or later (Bug#17487). + * internals.texi (C Dialect): Document this. + +2014-05-15 Dmitry Antipov <dmantipov@yandex.ru> + + * lists.texi (Building Cons Cells and Lists): + Remove description of `reverse' and `'nreverse' to generalize them... + * sequences.texi (Sequences): ...for sequences here. + +2014-05-14 Glenn Morris <rgm@gnu.org> + + * files.texi (Changing Files): Mention with-file-modes. + +2014-05-08 Paul Eggert <eggert@cs.ucla.edu> + + * internals.texi (C Dialect): New section. + (C Integer Types): Mention bool_bf. + +2014-04-30 Stefan Monnier <monnier@iro.umontreal.ca> + + * processes.texi (Filter Functions, Sentinels): Advertise add-function. + +2014-04-29 Stefan Monnier <monnier@iro.umontreal.ca> + + * windows.texi (Window Configurations, Window Configurations): + Window configs don't store marks any more. + +2014-04-25 Eli Zaretskii <eliz@gnu.org> + + * strings.texi (Text Comparison): Mention equal-including-properties + for when text properties of the strings matter for comparison. + +2014-04-22 Eli Zaretskii <eliz@gnu.org> + + * text.texi (Registers): Document register-read-with-preview. + + * internals.texi (Building Emacs): Improve indexing. + +2014-04-17 Daniel Colascione <dancol@dancol.org> + + * frames.texi (Terminal Parameters): Document new + tty-mode-set-strings and tty-mode-reset-strings terminal + parameters. + +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + +2014-04-09 Daniel Colascione <dancol@dancol.org> + + * errors.texi (Standard Errors): Document required error + parameters for `scan-error'. + + * positions.texi (List Motion): Explain new `up-list' arguments. + Mention `backward-up-list'. + +2014-04-08 Daniel Colascione <dancol@dancol.org> + + * minibuf.texi (Programmed Completion): Improve phrasing, remove + incorrect bullet count. + +2014-04-07 Glenn Morris <rgm@gnu.org> + + * os.texi (Recording Input): Dribble files may contain passwords. + + * backups.texi (Making Backups, Reverting): + Update for default values of some -function vars no longer being nil. + (Reverting): Update for buffer-stale-function + also applying to file-buffers. + +2014-03-31 Daniel Colascione <dancol@dancol.org> + + * minibuf.texi (Completion in Buffers): Discuss using lazy + completion tables for inline completion. + +2014-03-28 Glenn Morris <rgm@gnu.org> + + * os.texi (Terminal-Specific): Mention term-file-aliases. + +2014-03-26 Eli Zaretskii <eliz@gnu.org> + + * files.texi (Kinds of Files): Improve documentation of + file-symlink-p. (Bug#17073) Add cross-references. + +2014-03-26 Barry O'Reilly <gundaetiapo@gmail.com> + + * markers.texi (Moving Marker Positions): The 2014-03-02 doc + change mentioning undo's inability to handle relocated markers no + longer applies. See bug#16818. + * text.texi (Undo): Expand documentation of (TEXT . POS) and + (MARKER . ADJUSTMENT) undo elements. + +2014-03-26 Glenn Morris <rgm@gnu.org> + + * files.texi (File Locks): All systems support locking. + +2014-03-22 Glenn Morris <rgm@gnu.org> + + * commands.texi (Defining Commands): + Mention that interactive-only also affects describe-function. + + * functions.texi (Declare Form): Add interactive-only. + * commands.texi (Defining Commands) Mention declare. + + * commands.texi (Defining Commands): List interactive-only values. + +2014-03-22 Eli Zaretskii <eliz@gnu.org> + + * functions.texi (Core Advising Primitives): Fix cross-reference + in last change. + +2014-03-22 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Advising Functions): Explain a bit more how + arguments work. + (Advice combinators): New node. + (Core Advising Primitives): Use it. Expand description of "depth". + (Advising Named Functions): Document limitation of advices on macros. + +2014-03-21 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size and Position): In `frame-resize-pixelwise' + description drop remark about frame maximization. + * windows.texi (Display Action Functions): Add description for + `display-buffer-no-window' and explain use of `allow-no-window' + alist entries. + +2014-03-21 Glenn Morris <rgm@gnu.org> + + * commands.texi (Defining Commands): Copyedit re `interactive-only'. + +2014-03-20 Paul Eggert <eggert@cs.ucla.edu> + + * internals.texi (C Integer Types): Prefer 'false' and 'true' + to '0' and '1' for booleans. + +2014-03-19 Paul Eggert <eggert@cs.ucla.edu> + + * numbers.texi: Improve and clarify a bit, and fix some minor bugs. + Remove now-obsolete hypothetical note about negative division, + as the C standard has changed. + + Fix porting inconsistency about rounding to even. + * numbers.texi (Numeric Conversions, Rounding Operations): + Document that 'round' and 'fround' round to even. + +2014-03-18 Juanma Barranquero <lekktu@gmail.com> + + * customize.texi (Variable Definitions): Recommend avoiding + destructive modification of the value argument of :set (bug#16755). + +2014-03-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * modes.texi (Auto-Indentation): Mention electric-indent variables. + +2014-03-18 Juanma Barranquero <lekktu@gmail.com> + + * functions.texi (Advising Named Functions): Fix reference. + +2014-03-18 Paul Eggert <eggert@cs.ucla.edu> + + Improve documentation for integer and floating-point basics. + * numbers.texi (Numbers, Integer Basics, Float Basics): + Document the basics a bit more precisely. Say more clearly + that Emacs floating-point numbers are IEEE doubles on all + current platforms. Give more details about frexp. + Say more clearly that '1.' is an integer. + (Predicates on Numbers): Fix wholenump typo. + * objects.texi (Integer Type): Adjust to match numbers.texi. + +2014-03-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Advising Functions): Try and improve the text. + Add example use of advice-add (bug#16959). + (Core Advising Primitives): Rename. Explain handling of interactive + specs, including advice-eval-interactive-spec. + (Advising Named Functions): Try and better explain the difference with + add-function. + (Porting old advices): New node. + +2014-03-18 Paul Eggert <eggert@cs.ucla.edu> + + Style fixes for floating-point doc. + * commands.texi, customize.texi, display.texi, elisp.texi, files.texi: + * frames.texi, hash.texi, internals.texi, keymaps.texi, lists.texi: + * minibuf.texi, nonascii.texi, numbers.texi, objects.texi, os.texi: + * processes.texi, streams.texi, strings.texi, text.texi: + * variables.texi, windows.texi: + Hyphenate "floating-point" iff it precedes a noun. + Reword to avoid nouns and hyphenation when that's easy. + Prefer "integer" to "integer number" and "is floating point" + to "is a floating point number". + Prefer "@minus{}" to "-" when it's a minus. + +2014-03-16 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Temporary Displays): Rewrite descriptions of + `with-output-to-temp-buffer' and `with-temp-buffer-window'. + * help.texi (Help Functions): Rewrite description of `with-help-window'. + +2014-03-15 Dmitry Gutov <dgutov@yandex.ru> + + * display.texi (Blinking): Update WRT to the new + `blink-matchin-paren' behavior. + +2014-03-14 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Temporary Displays): Say that + `with-temp-buffer-window' makes its buffer current. + * frames.texi (Size and Position): Describe new option + `frame-resize-pixelwise'. Rewrite descriptions of + `set-frame-size', `set-frame-height' and `set-frame-width'. + +2014-03-09 Martin Rudalics <rudalics@gmx.at> + + * elisp.texi (Top): Rename section "Width" to "Size of Displayed Text". + * text.texi (Primitive Indent): + * strings.texi (String Basics): + * sequences.texi (Sequence Functions): Update references accordingly. + * display.texi (Size of Displayed Text): Rename section from + "Width". Add description for `window-text-pixel-size'. + (Window Dividers): Reword description of window dividers. + * frames.texi (Layout Parameters): Improve description of window + divider parameters. + * windows.texi (Window Sizes): Add descriptions of + `window-mode-line-height' and `window-header-line-height'. + (Coordinates and Windows): Mention window dividers. + +2014-03-07 Martin Rudalics <rudalics@gmx.at> + + * buffers.texi (The Buffer List): Rename node to Buffer List. + Describe `buffer-list-update-hook'. + * elisp.texi (Top): "The Buffer List" renamed to "Buffer List". + Add node for Window Dividers. + * hooks.texi (Standard Hooks): Add reference to + `buffer-list-update-hook'. + * windows.texi (Window Sizes): Describe `window-min-size'. + (Splitting Windows): Update description of `split-window'. + (Selecting Windows): Update description of `select-window'. + +2014-03-06 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size and Position): Rewrite entries for + `fit-frame-to-buffer' and `fit-frame-to-buffer-margins'. + Add description for `fit-frame-to-buffer-sizes'. + * windows.texi (Resizing Windows): Add descriptions for + pixelwise resizing. Add entries for `window-resize-pixelwise' + and `fit-window-to-buffer-horizontally'. + Rewrite `fit-window-to-buffer' entry. + +2014-03-06 Xue Fuqiao <xfq@gnu.org> + + * internals.texi (Window Internals): Remove field `region_showing'. + +2014-03-06 Glenn Morris <rgm@gnu.org> + + * searching.texi (Replacing Match): + Remove incorrect, uninteresting return value. (Bug#16942) + +2014-03-05 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Window Dividers): New section. + * frames.texi (Layout Parameters): Add right-divider-width and + bottom-divider-width. + * windows.texi (Window Sizes): Redraw schematic and rewrite its + description. Rewrite descriptions of `window-total-height', + `window-total-width', `window-total-size', `window-body-height', + `window-body-width' and `window-size-fixed'. Add descriptions + for `window-pixel-height', `window-pixel-width', + `window-min-height' and `window-min-width'. Remove description + of `window-size-fixed-p' moving part of it to that of + `window-size-fixed'. + (Resizing Windows): Mention dividers when talking about minimum sizes. + +2014-03-05 Glenn Morris <rgm@gnu.org> + + * modes.texi (SMIE Customization): New section. + * elisp.texi (Top): Update detailed menu. + +2014-03-04 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Windows and Frames): Add some missing &optional + designators. Adjust description of window-in-direction. + +2014-03-02 Barry O'Reilly <gundaetiapo@gmail.com> + + * markers.texi (Moving Marker Positions): Clarify guidance about + when to move markers and when to create a new one, as discussed at + http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16818#17 + +2014-03-02 Glenn Morris <rgm@gnu.org> + + * text.texi (Decompression): New node. + * elisp.texi (Top): Update detailed menu. + +2014-03-01 Glenn Morris <rgm@gnu.org> + + * display.texi (Forcing Redisplay): Mention pre-redisplay-function. + +2014-02-28 Xue Fuqiao <xfq@gnu.org> + + * functions.texi (Advising Functions, Advising Named Functions): + Tweak markup. + + * display.texi (Defining Faces): Doc fix for `face-spec-set'. + + * elisp.texi (Top): + * commands.texi (Generic Commands, Defining Commands): + Document `define-alternatives'. + +2014-02-27 Xue Fuqiao <xfq@gnu.org> + + * windows.texi (Window Sizes): Document `window-size'. + (Display Action Functions): Document `display-buffer-at-bottom'. + (Window Configurations): Minor fixes. + + * modes.texi (Header Lines): Document `window-header-line-height'. + + * display.texi (Scroll Bars): Document `window-scroll-bar-width'. + + * windows.texi (Window Sizes, Resizing Windows): Document some + pixelwise window operations. + + * text.texi (Margins): Fix the description of RET and `C-j'. + + * frames.texi (Multiple Terminals): Document + `display-monitor-attributes-list' and `display-monitor-attributes'. + (Display Feature Testing): Add some notes about multi-monitor. + +2014-02-27 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Programmed Completion): + Mention completion-table-with-cache. + +2014-02-25 Glenn Morris <rgm@gnu.org> + + * display.texi (Window Systems): + Replace term-setup-hook with emacs-startup-hook. + * hooks.texi (Standard Hooks): + Replace term-setup-hook with tty-setup-hook. + * os.texi (Startup Summary, Init File, Terminal-Specific): + Replace term-setup-hook with tty-setup-hook, and update. + +2014-02-22 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Declare Form): Document gv-expander, gv-setter, + and compiler-macro (bug#16829, bug#15093). + +2014-02-21 Juanma Barranquero <lekktu@gmail.com> + + * windows.texi (Window Configurations): Doc fix. + (Windows and Frames): Fix typo. + +2014-02-21 Glenn Morris <rgm@gnu.org> + + * internals.texi (Process Internals): + * processes.texi (Subprocess Creation, Deleting Processes) + (Output from Processes, Process Buffers, Filter Functions) + (Accepting Output, Sentinels, Network, Network Servers): + Filters and sentinels can no longer be nil. + * elisp.texi (Top): Menu update. + +2014-02-20 Glenn Morris <rgm@gnu.org> + + * functions.texi (Defining Functions): Mention defalias-fset-function. + +2014-02-17 Stefan Monnier <monnier@iro.umontreal.ca> + + * minibuf.texi (Completion Commands): Don't document obsolete + `common-substring' arg of display-completion-list. + +2014-02-17 Glenn Morris <rgm@gnu.org> + + * minibuf.texi (Text from Minibuffer): Update read-regexp details. + Mention read-regexp-defaults-function. + +2014-02-13 Glenn Morris <rgm@gnu.org> + + * debugging.texi (Debugger Commands): Tiny edits. + +2014-02-12 Glenn Morris <rgm@gnu.org> + + * package.texi (Simple Packages): Describe URL and Keywords headers. + +2014-02-10 Lars Ingebrigtsen <larsi@gnus.org> + + * text.texi (User-Level Deletion): + Document `delete-trailing-whitespace' (bug#15309). + +2014-02-09 Lars Ingebrigtsen <larsi@gnus.org> + + * text.texi (Changing Properties): Clarify `propertize' (bug#9825). + + * display.texi (Blinking): Clarify doc string in example (bug#10658). + + * commands.texi (Accessing Mouse): Mention that these function + also work on keyboard events (bug#14228). + (Quitting): Refer to the right node for `set-input-mode' (bug#11458). + +2014-02-08 Lars Ingebrigtsen <larsi@gnus.org> + + * display.texi (Face Attributes): Add an index (bug#14924). + + * keymaps.texi (Menu Bar): Minor clarification (bug#15657). + +2014-02-06 Glenn Morris <rgm@gnu.org> + + * display.texi (Truncation): + * positions.texi (Screen Lines): Do not mention cache-long-scans. + +2014-01-31 Juri Linkov <juri@jurta.org> + + * searching.texi (String Search): Incremental word search fixes. + +2014-01-28 Glenn Morris <rgm@gnu.org> + + * text.texi (Indent Tabs): Update related to tab-stops. + +2014-01-24 Glenn Morris <rgm@gnu.org> + + * control.texi (Handling Errors): Update with-demoted-errors. + + * files.texi (File Locks): Every platform supports locking now. + +2014-01-22 Glenn Morris <rgm@gnu.org> + + * display.texi (ImageMagick Images): Expand on image-format-suffixes. + +2014-01-20 Glenn Morris <rgm@gnu.org> + + * hash.texi (Other Hash): Do not mention subr-x.el functions; + reverts 2013-12-22 change. + +2014-01-10 Stefan Monnier <monnier@iro.umontreal.ca> + + * functions.texi (Advising Functions): New section. + * modes.texi (Running Hooks): Don't document with-wrapper-hook and + run-hook-wrapped any more. + (Hooks): Link to the new Advising Functions node. + * elisp.texi (Top): Don't include advice.texi. + * advice.texi: Remove. + * makefile.w32-in (srcs): + * Makefile.in (srcs): Adjust accordingly. + +2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * text.texi (Parsing HTML/XML): Document `shr-insert-document'. + + * strings.texi (Text Comparison): Document `string-suffix-p'. + +2014-01-07 Glenn Morris <rgm@gnu.org> + + * files.texi (File Attributes): Fix superscipt typo. + +2014-01-07 Chong Yidong <cyd@gnu.org> + + * files.texi (Changing Files): Document copy-file changes. + +2014-01-07 Glenn Morris <rgm@gnu.org> + + * display.texi (Logging Messages): Copyedits re messages-buffer. + +2014-01-06 Paul Eggert <eggert@cs.ucla.edu> + + Specify .texi encoding (Bug#16292). + * back.texi, book-spine.texi, lay-flat.texi: + Add @documentencoding. + +2014-01-05 Chong Yidong <cyd@gnu.org> + + * backups.texi (Making Backups): Document backup-buffer change. + + * files.texi (Visiting Files): Copyedits. + (Testing Accessibility): Mention ACLs. Move file-modes here from + File Attributes. + (Truenames): Move file-equal-p here from Kinds of Files. + (File Attributes): Move file-newer-than-file-p here from Testing + Accessibility. + (Extended Attributes): New node. Add file-extended-attributes. + (Changing Files): Document set-file-extended-attributes. + + * commands.texi (Defining Commands): Document the interactive-form + property more carefully. Document interactive-only. + + * compile.texi (Compiler Errors): Copyedits. Note that the + details for byte-compile-warnings are in its docstring. + + * minibuf.texi (Minibuffer Contents): Remove obsolete function + minibuffer-completion-contents. + + * variables.texi (Defining Variables): Note that defvar acts + always on the dynamic value. + + * customize.texi (Variable Definitions): Likewise. + +2014-01-05 Paul Eggert <eggert@cs.ucla.edu> + + Document vconcat and the empty vector (Bug#16246). + * sequences.texi (Vector Functions): + Document behavior better when the result is empty. + + Document behavior of (string-to-number "+@") (Bug#16293). + * strings.texi (String Conversion): Document behavior of + string-to-number on invalid strings that begin with "+", too. + +2014-01-03 Chong Yidong <cyd@gnu.org> + + * help.texi (Documentation, Accessing Documentation): Copyedits. + (Documentation Basics): Rewrite, avoiding a repeat discussion of + docstring conventions. + + * tips.texi (Documentation Tips): Move discussion of + emacs-lisp-docstring-fill-column here from Documentation Basics. + + * compile.texi (Docs and Compilation): Copyedits. + +2014-01-02 Glenn Morris <rgm@gnu.org> + + * numbers.texi (Numeric Conversions): Fix a typo. + +2013-12-29 Paul Eggert <eggert@cs.ucla.edu> + + Plain copy-file no longer chmods an existing destination (Bug#16133). + * files.texi (Changing Files): Document this. + +2013-12-28 Chong Yidong <cyd@gnu.org> + + * modes.texi (Auto Major Mode): Document interpreter-mode-alist change. + + * buffers.texi (Modification Time): Document visited-file-modtime + change. + +2013-12-28 Glenn Morris <rgm@gnu.org> + + * control.texi (Pattern matching case statement): Brevity. + +2013-12-27 Chong Yidong <cyd@gnu.org> + + * functions.texi (Function Cells): + * eval.texi (Function Indirection): Update for the fact that + symbol-function no longer signals an error. + + * commands.texi (Reading One Event): Mention keyboard coding. + + * keymaps.texi (Translation Keymaps, Translation Keymaps): + * nonascii.texi (Terminal I/O Encoding): Copyedits. + +2013-12-26 Chong Yidong <cyd@gnu.org> + + * advice.texi (Advising Functions, Defining Advice): Special forms + can no longer be advised. + +2013-12-25 Chong Yidong <cyd@gnu.org> + + * keymaps.texi (Active Keymaps): Re-organize the text. + (Searching Keymaps): Rewrite the pseudo-code for 24.4 changes. + (Controlling Active Maps): Note that set-transient-map uses + overriding-terminal-local-map. + + * tips.texi (Coding Conventions): Tweak the coding system tip; + Emacs now uses utf-8 by default for Emacs Lisp source files. + + * display.texi (Font Selection): Tweak example. + + * commands.texi (Event Input Misc): Document new arg to input-pending-p. + + * nonascii.texi (Specifying Coding Systems): Don't refer to + emacs-mule-dos. + (Lisp and Coding Systems): Describe emacs-mule return value in + modern terms. + +2013-12-25 Tassilo Horn <tsdh@gnu.org> + + * control.texi (Pattern matching case statement): Rephrase lexical + binding requirement: the example needs it, not `pcase' itself. + +2013-12-25 Chong Yidong <cyd@gnu.org> + + * eval.texi (Eval): Document the LEXICAL arg to eval. + + * variables.texi (Variables, Void Variables): Use "scoping rule" + terminology consistently. + (Variable Scoping): Add index entries, and use "dynamic scope" + terminology in place of "indefinite scope" to reduce confusion. + (Lexical Binding): Document lexical environment format. + (Using Lexical Binding): Add index entries for error messages. + +2013-12-24 Tassilo Horn <tsdh@gnu.org> + + * control.texi (Pattern matching case statement): Fix missing + argument in simple expression language sample (Bug#16238). + Add some sample programs written in that language. Mention that + `pcase' requires lexical binding. + +2013-12-23 Xue Fuqiao <xfq.free@gmail.com> + + * eval.texi (Special Forms): Document `special-form-p'. + + * macros.texi (Simple Macro): Document `macrop'. + + * files.texi (Changing Files): Fix an argument of `copy-file'. + + * strings.texi (Creating Strings): Document TRIM in `split-string'. + +2013-12-23 Chong Yidong <cyd@gnu.org> + + * keymaps.texi (Controlling Active Maps): + Rename set-temporary-overlay-map to set-transient map. Doc fixes. + (Searching Keymaps): The transient keymap takes precedence. + +2013-12-23 Glenn Morris <rgm@gnu.org> + + * loading.texi (How Programs Do Loading, Load Suffixes): + Mention `load-prefer-newer'. + +2013-12-22 Xue Fuqiao <xfq.free@gmail.com> + + * hash.texi (Other Hash): Document `hash-table-keys' + and `hash-table-values'. + +2013-12-22 Eli Zaretskii <eliz@gnu.org> + + * nonascii.texi (Character Properties): NAME or OLD-NAME + properties can be nil (there's no empty string). + (Character Properties): Update the reference to the UCD. + +2013-12-22 Xue Fuqiao <xfq.free@gmail.com> + + * sequences.texi (Bool-Vectors): Document new bool-vector set + operation functions. + + * text.texi (Examining Properties): Document `get-pos-property'. + + * variables.texi (Directory Local Variables): + Document `enable-dir-local-variables'. + + * debugging.texi (Debugger Commands): + Document `debugger-toggle-locals'. + +2013-12-21 Chong Yidong <cyd@gnu.org> + + * text.texi (Region Indent): Note the new interactive behavior of + indent-rigidly. + +2013-12-20 Tassilo Horn <tsdh@gnu.org> + + * numbers.texi (numbers): Document that =, <, <=, >, >= now accept + one or many arguments. + + * display.texi: Document `messages-buffer'. + + * os.texi: Document `initial-buffer-choice' changes. + +2013-12-20 Chong Yidong <cyd@gnu.org> + + * text.texi (Changing Properties): Improve documentation for + add-face-text-property. + (Special Properties): Mention add-face-text-property. + +2013-12-18 Chong Yidong <cyd@gnu.org> + + * customize.texi (Custom Themes): Document custom-known-themes + (Bug#15717). + + * modes.texi (Defining Minor Modes): Fix typo (Bug#14874). + (Keymaps and Minor Modes): Fix binding convention (Bug#11522). + +2013-12-13 Glenn Morris <rgm@gnu.org> + + * internals.texi (Building Emacs): + * loading.texi (Library Search): Mention that site-load, + site-init cannot change load-path. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * elisp.texi: Tweak dircategory. + +2013-12-12 Eli Zaretskii <eliz@gnu.org> + + * nonascii.texi (Encoding and I/O): Document file-name encoding + peculiarities on MS-Windows. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * elisp.texi: Sync direntry with info/dir version. + +2013-12-08 Juanma Barranquero <lekktu@gmail.com> + + * display.texi (Progress, Face Remapping): + * processes.texi (Serial Ports): + * windows.texi (Recombining Windows): Fix typos. (Bug#16089) + +2013-12-04 Juri Linkov <juri@jurta.org> + + * searching.texi (Search and Replace): Fix `unread-command-events' + and add ref. + +2013-12-03 Juri Linkov <juri@jurta.org> + + * windows.texi (Choosing Window): Rename `no-display-ok' to + `allow-no-window'. (Bug#13594) + +2013-11-30 Glenn Morris <rgm@gnu.org> + + * Makefile.in (distclean): Remove Makefile. + +2013-11-29 Andreas Politz <politza@fh-trier.de> + + * modes.texi (Imenu): Make it clear that sub-alist is the cdr + (Bug#14029). + +2013-11-27 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): + * os.texi (Startup Summary): No more leim directory. + +2013-11-26 Glenn Morris <rgm@gnu.org> + + * os.texi (Startup Summary): Update for leim-list being preloaded. + +2013-11-23 Brian Jenkins <brian@brianjenkins.org> (tiny change) + + * frames.texi (Input Focus): + * hooks.texi (Standard Hooks): Mention focus-in-hook, focus-out-hook. + +2013-11-23 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): + Empty elements in EMACSLOADPATH now mean the default load-path. + +2013-11-22 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): Minor clarification. + +2013-11-20 Leo Liu <sdl.web@gmail.com> + + * windows.texi (Choosing Window): Mention `no-display-ok'. (Bug#13594) + +2013-11-19 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (File Notifications): Add an index. + + * loading.texi (Loading): Add an cross-reference. + +2013-11-18 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (Session Management, Desktop Notifications): Add some + indexes and a cross-reference. + +2013-11-17 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (Time Parsing, Processor Run Time, Input Modes) + (Terminal Output): Minor fixes. + +2013-11-14 Glenn Morris <rgm@gnu.org> + + * loading.texi (Library Search): Update section. + +2013-11-11 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (User Identification, Time of Day, Time Conversion): + Minor fixes. + +2013-11-10 Jan Djärv <jan.h.d@swipnet.se> + + * keymaps.texi (Tool Bar): Mention that Gtk+/NS ignores item 1 to 3. + +2013-11-09 Xue Fuqiao <xfq.free@gmail.com> + + * os.texi (Startup Summary): Add an index about startup screen. + Typo fix. + (Command-Line Arguments): Add cross-reference for `dump-emacs'. + +2013-11-08 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Truncation): Document that cache-long-scans is now + non-nil by default. (Bug#15797) + +2013-11-05 Eli Zaretskii <eliz@gnu.org> + + * lists.texi (Rearrangement): Fix indexing. + + * display.texi (Bidirectional Display): Fix indexing. + +2013-11-05 Xue Fuqiao <xfq.free@gmail.com> + + * lists.texi (Rearrangement): Improve indexing. + + * display.texi (Glyphs): Add an index for glyph code. + (Bidirectional Display): Improve indexing. + +2013-11-01 Jan Djärv <jan.h.d@swipnet.se> + + * display.texi (Face Attributes): Document :distant-foreground. + +2013-10-30 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Abstract Display): Improve indexing. + +2013-10-29 Stefan Monnier <monnier@iro.umontreal.ca> + + * display.texi (Selective Display): Discourage the use of explicit + selective display. + +2013-10-29 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Showing Images): Add an index for image-size. + Use @code instead of @var for a normal variable. + (Multi-Frame Images): Improve indexing. + (Button Buffer Commands): Use @code instead of @var for a normal + variable. + (Abstract Display): Explain the meaning of Ewoc. + +2013-10-27 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Image Descriptors): Improve indexing. + +2013-10-26 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Fringe Indicators): Add indexes for fringe indicators. + (Customizing Bitmaps): Add an index for customizing fringe bitmaps. + +2013-10-25 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Fontsets): Minor wording fix. + (Low-Level Font): Improve indexing. + + * nonascii.texi (Character Properties): Add an index for script symbols. + +2013-10-24 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Face Remapping): Add indexes for face remapping. + (Font Selection): Add indexes. + (Low-Level Font): Add an index for font registry. + +2013-10-23 Glenn Morris <rgm@gnu.org> + + * eval.texi, files.texi, intro.texi, objects.texi, searching.texi: + Nuke @refill. + + * Makefile.in (install-dvi, install-html, install-pdf) + (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) + (uninstall-pdf): Quote entities that might contain whitespace. + +2013-10-19 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Face Attributes): Add indexes for the ‘:box’ + face attribute. + +2013-10-18 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Line Height): Add indexes for line height. + +2013-10-17 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Width): Fix arguments of ‘truncate-string-to-width’. + +2013-10-16 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Selective Display): Add an index for explicit + selective display. + +2013-10-15 Xue Fuqiao <xfq.free@gmail.com> + + * display.texi (Warning Basics): Mention the ‘*Warnings*’ buffer. + +2013-10-13 Glenn Morris <rgm@gnu.org> + + * intro.texi (Acknowledgments): Use accented form of some names. + +2013-10-09 Glenn Morris <rgm@gnu.org> + + * control.texi (Conditionals): Copyedits. (Bug#15558) + +2013-10-08 Eli Zaretskii <eliz@gnu.org> + + Support menus on text-mode terminals. + * keymaps.texi (Defining Menus, Mouse Menus, Menu Bar): + Modify wording to the effect that menus are supported on TTYs. + + * frames.texi (Pop-Up Menus, Dialog Boxes) + (Display Feature Testing): Update for menu support on TTYs. + +2013-10-07 Stefan Monnier <monnier@iro.umontreal.ca> + + * tips.texi (Comment Tips): Discourage use of triple semi-colons for + non-headings. + +2013-10-05 Xue Fuqiao <xfq.free@gmail.com> + + * syntax.texi (Categories): Add an index for category sets. + +2013-10-03 Xue Fuqiao <xfq.free@gmail.com> + + * syntax.texi (Syntax Flags, Syntax Table Functions): Add indexes. + +2013-10-02 Xue Fuqiao <xfq.free@gmail.com> + + * syntax.texi (Syntax Class Table): Add an index for syntax class table. + +2013-09-29 Xue Fuqiao <xfq.free@gmail.com> + + * searching.texi (Regexp Search): Refine. + +2013-09-22 Xue Fuqiao <xfq.free@gmail.com> + + * nonascii.texi (Default Coding Systems): Typo fix. + +2013-09-21 Xue Fuqiao <xfq.free@gmail.com> + + * nonascii.texi (Coding System Basics): Add information about + carriage-return. + +2013-09-14 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Display Margins): State the units of measuring + margin width. (Bug#15375) + +2013-09-13 Eli Zaretskii <eliz@gnu.org> + + * text.texi (Not Intervals): Minor wording fix. + +2013-09-12 Xue Fuqiao <xfq.free@gmail.com> + + * functions.texi (Obsolete Functions): Add an index for obsolete + functions. + +2013-09-11 Xue Fuqiao <xfq.free@gmail.com> + + * nonascii.texi (Character Properties): Character properties fix + for decimal-digit-value and digit-value. + +2013-09-08 Stefan Monnier <monnier@iro.umontreal.ca> + + * macros.texi (Defining Macros): Prefer "function" to "lambda + expression" (bug#15296). + +2013-08-28 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, + for portability to hosts where /bin/sh has problems. + +2013-08-26 Stefan Monnier <monnier@iro.umontreal.ca> + + * variables.texi (File Local Variables): Don't recommend quoting! Ever! + 2013-08-20 Eli Zaretskii <eliz@gnu.org> * files.texi (Information about Files): Mention file names with @@ -29,8 +1660,8 @@ (Undo): Doc fix for `buffer-undo-list'. * positions.texi (Character Motion): - * markers.texi (Moving Markers): - (Creating Markers): Comment out undefined behavior. + * markers.texi (Moving Markers, Creating Markers): + Comment out undefined behavior. 2013-08-15 Xue Fuqiao <xfq.free@gmail.com> @@ -66,8 +1697,8 @@ (dvi, html, pdf, ps): Use *_TARGETS variables. (elisp.html): Use HTML_OPTS. (elisp.ps): Remove explicit rule. - (.PHONY): install-dvi, install-html, install-pdf, install-ps - ,install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, + (.PHONY): install-dvi, install-html, install-pdf, install-ps, + install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, uninstall-ps, and uninstall-doc. (install-dvi, install-html, install-pdf, install-ps, install-doc) (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) @@ -112,7 +1743,8 @@ 2013-07-31 Xue Fuqiao <xfq.free@gmail.com> * nonascii.texi (Non-ASCII Characters): Update menu. - (Disabling Multibyte): Move here from doc/emacs/mule.texi. Fix cross-references. + (Disabling Multibyte): Move here from doc/emacs/mule.texi. + Fix cross-references. * elisp.texi (Top): Update menu. @@ -137,8 +1769,8 @@ 2013-07-22 Michael Albinus <michael.albinus@gmx.de> * files.texi (Magic File Names): Add file-notify-add-watch, - file-notify-rm-watch and file-notify-supported-p. Move - file-remote-p down. + file-notify-rm-watch and file-notify-supported-p. + Move file-remote-p down. * errors.texi (Standard Errors): Add file-notify-error. @@ -277,7 +1909,7 @@ 2013-04-21 Xue Fuqiao <xfq.free@gmail.com> * internals.texi (Writing Emacs Primitives): Remove unnecessary - references to the sources. (Bug#13800) + references to the sources. (Bug#13800) * searching.texi (Regexp Backslash): Doc fix for backslash constructs in regular expressions. @@ -510,7 +2142,7 @@ 2012-12-14 Paul Eggert <eggert@cs.ucla.edu> - Fix permissions bugs with setgid directories etc. (Bug#13125) + Fix permissions bugs with setgid directories etc. (Bug#13125) * files.texi (Testing Accessibility): Document GROUP arg of file-ownership-preserved-p. (File Attributes): Document that 9th element is now @@ -928,14 +2560,16 @@ Tweak markup. Remove domain-error and friends, which seem to be unused after the floating-point code revamp. - * functions.texi (Obsolete Functions): Obsolescence also affects + * functions.texi (Defining Functions): defun is now a macro. + (Obsolete Functions): Obsolescence also affects documentation commands. Various clarifications. (Declare Form): New node. * strings.texi (String Basics): Copyedits. - * os.texi (Idle Timers): Minor clarifications. + * os.texi (Startup Summary): Document leim-list.el change. (User Identification): Add system-users and system-groups. + (Idle Timers): Minor clarifications. * macros.texi (Defining Macros): Move description of `declare' to Declare Form node. @@ -951,14 +2585,6 @@ the machine-independence of negative division since it does not happen in practice. -2012-09-28 Chong Yidong <cyd@gnu.org> - - * os.texi (Startup Summary): Document leim-list.el change. - -2012-09-25 Chong Yidong <cyd@gnu.org> - - * functions.texi (Defining Functions): defun is now a macro. - 2012-09-28 Leo Liu <sdl.web@gmail.com> * files.texi (Files): Fix typo. @@ -1151,7 +2777,7 @@ 2012-07-06 Richard Stallman <rms@gnu.org> - * intro.texi (Evaluation Notation, A Sample Function Description): + * intro.texi (Evaluation Notation, A Sample Function Description) (A Sample Variable Description): Improve/undo previous changes. 2012-07-05 Glenn Morris <rgm@gnu.org> @@ -1466,7 +3092,7 @@ (Resizing Windows, Deleting Windows, Selecting Windows) (Choosing Window Options, Horizontal Scrolling) (Cyclic Window Ordering, Window History, Dedicated Windows) - (Quitting Windows, Window Configurations, Textual Scrolling): + (Quitting Windows, Window Configurations, Textual Scrolling) (Coordinates and Windows, Window Configurations) (Window Parameters, Window Hooks): Copyedits. (Splitting Windows, Deleting Windows): @@ -1544,7 +3170,7 @@ * processes.texi (Output from Processes, Filter Functions): Mention waiting-for-user-input-p. - (Sentinels, Query Before Exit, System Processes, Transaction Queues): + (Sentinels, Query Before Exit, System Processes, Transaction Queues) (Network Servers, Datagrams, Network Processes, Network Options) (Network Feature Testing, Serial Ports): Copyedits. (Network): Add encrypted network overview paragraph. @@ -1566,7 +3192,7 @@ 2012-04-15 Glenn Morris <rgm@gnu.org> - * processes.texi (Processes, Subprocess Creation, Shell Arguments): + * processes.texi (Processes, Subprocess Creation, Shell Arguments) (Synchronous Processes, Asynchronous Processes, Deleting Processes): Copyedits. (Subprocess Creation): Discourage modifying exec-path directly. @@ -1586,8 +3212,7 @@ 2012-04-14 Chong Yidong <cyd@gnu.org> - * customize.texi (Applying Customizations): - (Custom Themes): New nodes. + * customize.texi (Applying Customizations, Custom Themes): New nodes. * display.texi (Defining Faces): Reference custom-set-faces. @@ -1716,8 +3341,8 @@ 2012-03-28 Glenn Morris <rgm@gnu.org> - * searching.texi (Regular Expressions, Regexp Special): - (Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search): + * searching.texi (Regular Expressions, Regexp Special) + (Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search) (Simple Match Data, Saving Match Data, Standard Regexps): Copyedits. (Regexp Special): Mention collation. Clarify char classes with an example. @@ -1948,7 +3573,7 @@ (Pure Storage): Small changes. (Memory Usage): Copyedit. (Writing Emacs Primitives): Update Fcoordinates_in_window_p and For - example definitions. Give examples of things with non-nil + example definitions. Give examples of things with non-nil interactive args. Mention eval_sub. Remove old info about strings and GCPRO. Mention cus-start.el. (Buffer Internals, Window Internals, Process Internals): @@ -2124,7 +3749,7 @@ (Syntax Class Table): Use a table. (Syntax Properties): Document syntax-propertize-function and syntax-propertize-extend-region-functions. - (Motion via Parsing): Clarify scan-lists. Fix indentation. + (Motion via Parsing): Clarify scan-lists. Fix indentation. (Parser State): Update for the new "c" comment style. Fix description of item 7 (comment style). @@ -2991,7 +4616,7 @@ 2011-07-16 Lars Magne Ingebrigtsen <larsi@gnus.org> Tim Cross <theophilusx@gmail.com> (tiny change) - Glenn Morris <rgm@gnu.org> + Glenn Morris <rgm@gnu.org> * keymaps.texi (Toolkit Differences): New node. (Bug#8176) @@ -3163,7 +4788,7 @@ Document wide integers better. * files.texi (File Attributes): Document ino_t values better. ino_t values no longer map to anything larger than a single cons. - * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations): + * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations) (Bitwise Operations): * objects.texi (Integer Type): Use a binary notation that is a bit easier to read, and that will port better if 62-bits becomes the default. @@ -3446,7 +5071,7 @@ (texinputdir, $(infodir)/elisp): Use $(MAKEINFO_OPTS). 2011-01-25 Chong Yidong <cyd@stupidchicken.com> - Richard Kim <emacs18@gmail.com> + Richard Kim <emacs18@gmail.com> * loading.texi (Library Search): Document list-load-path-shadows (Bug#7757). @@ -6611,8 +8236,7 @@ * positions.texi (List Motion): * hash.texi (Hash Tables, Creating Hash, Defining Hash): * numbers.texi (Arithmetic Operations, Math Functions) - (Predicates on Numbers, Comparison of Numbers): - (Numeric Conversions): + (Predicates on Numbers, Comparison of Numbers, Numeric Conversions): * locals.texi (Standard Buffer-Local Variables): * maps.texi (Standard Keymaps): * os.texi (User Identification, System Environment, Recording Input) @@ -8887,7 +10511,7 @@ * variables.texi (Variable Aliases): Simplify. - * anti.texi, backups.texi, compile.texi, customization.texi: + * anti.texi, backups.texi, compile.texi, customize.texi: * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi: * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi: * os.texi, processes.texi, searching.texi, strings.texi, text.texi: @@ -11251,15 +12875,12 @@ 2003-11-02 Jesper Harder <harder@ifa.au.dk> (tiny change) - * lispref/anti.texi, lispref/backups.texi, lispref/commands.texi - lispref/customize.texi, lispref/display.texi, lispref/files.texi, - lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi, - lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi, - lispref/objects.texi, lispref/os.texi, lispref/positions.texi, - lispref/processes.texi, lispref/searching.texi, - lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi, - lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with - @acronym{FOO}. + * anti.texi, backups.texi, commands.texi, customize.texi: + * display.texi, files.texi, internals.texi, keymaps.texi: + * loading.texi, modes.texi, nonascii.texi, numbers.texi: + * objects.texi, os.texi, positions.texi, processes.texi: + * searching.texi, sequences.texi, streams.texi, strings.texi: + * syntax.texi, text.texi: Replace @sc{foo} with @acronym{FOO}. 2003-10-27 Luc Teirlinck <teirllm@auburn.edu> @@ -12210,7 +13831,7 @@ 1998-01-30 Richard Stallman <rms@psilocin.gnu.org> - * Makefile (SHELL): Defined. + * Makefile (SHELL): Define. 1998-01-27 Richard Stallman <rms@psilocin.gnu.org> @@ -12368,7 +13989,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1998-2013 Free Software Foundation, Inc. + Copyright (C) 1998-2015 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 675cac7949d..6ac2840cb9a 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1990-1996, 1998-2013 Free Software Foundation, Inc. +# Copyright (C) 1990-1996, 1998-2015 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -17,7 +17,7 @@ # 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 +SHELL = @SHELL@ # NB If you add any more configure variables, # update the sed rules in the dist target below. @@ -25,12 +25,10 @@ SHELL = /bin/sh # Standard configure variables. srcdir = @srcdir@ -version=@version@ - buildinfodir = $(srcdir)/../../info # Directory with the (customized) texinfo.tex file. texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. +# Directory with docstyle.tex and emacsver.texi. emacsdir = $(srcdir)/../emacs prefix = @prefix@ @@ -49,9 +47,8 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -62,8 +59,17 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = \ + $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = elisp.dvi HTML_TARGETS = elisp.html @@ -74,9 +80,9 @@ PS_TARGETS = elisp.ps srcs = \ $(srcdir)/elisp.texi \ + $(emacsdir)/docstyle.texi \ $(emacsdir)/emacsver.texi \ $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ $(srcdir)/anti.texi \ $(srcdir)/backups.texi \ $(srcdir)/buffers.texi \ @@ -127,36 +133,36 @@ srcs = \ $(srcdir)/gpl.texi \ $(srcdir)/doclicense.texi -mkinfodir = @${MKDIR_P} ${buildinfodir} - -.PHONY: info dvi pdf ps - -.SUFFIXES: .ps .dvi +## Disable implicit rules. +%.texi: ; -.dvi.ps: - $(DVIPS) -o $@ $< +.PHONY: info dvi html pdf ps -info: $(buildinfodir)/elisp$(INFO_EXT) +info: $(buildinfodir)/elisp.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) -## Note: "<" is not portable in ordinary make rules. -$(buildinfodir)/elisp$(INFO_EXT): $(srcs) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $(srcdir)/elisp.texi +${buildinfodir}: + ${MKDIR_P} $@ + +$(buildinfodir)/elisp.info: $(srcs) | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< elisp.dvi: $(srcs) - $(ENVADD) $(TEXI2DVI) $(srcdir)/elisp.texi + $(ENVADD) $(TEXI2DVI) $< elisp.html: $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $(srcdir)/elisp.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< elisp.pdf: $(srcs) - $(ENVADD) $(TEXI2PDF) $(srcdir)/elisp.texi + $(ENVADD) $(TEXI2PDF) $< -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +elisp.ps: elisp.dvi + $(DVIPS) -o $@ $< + +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean ## [12] stuff is from two-volume.make. mostlyclean: @@ -167,56 +173,36 @@ mostlyclean: clean: mostlyclean rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) rm -f vol[12].dvi vol[12].pdf vol[12].ps - rm -f emacs-lispref-${version}.tar* distclean: clean + rm -f Makefile infoclean: - -cd $(buildinfodir) && rm -f elisp$(INFO_EXT) elisp$(INFO_EXT)-[1-9] elisp$(INFO_EXT)-[1-9][0-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -## Note this excludes the two-volume stuff. -dist: - rm -rf emacs-lispref-${version} - mkdir emacs-lispref-${version} - cp ${srcdir}/*.texi ${texinfodir}/texinfo.tex \ - $(emacsdir)/emacsver.texi ${srcdir}/ChangeLog* \ - ${srcdir}/README emacs-lispref-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - ${srcdir}/Makefile.in > emacs-lispref-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-lispref-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-lispref-${version}.tar emacs-lispref-${version} - rm -rf emacs-lispref-${version} + rm -f \ + $(buildinfodir)/elisp.info \ + $(buildinfodir)/elisp.info-[1-9] \ + $(buildinfodir)/elisp.info-[1-9][0-9] + +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc install-dvi: dvi - umask 022; $(MKDIR_P) $(DESTDIR)$(dvidir) - $(INSTALL_DATA) $(DVI_TARGETS) $(DESTDIR)$(dvidir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" + $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" install-html: html - umask 022; $(MKDIR_P) $(DESTDIR)$(htmldir) - $(INSTALL_DATA) $(HTML_TARGETS) $(DESTDIR)$(htmldir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" + $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" install-pdf: pdf - umask 022;$(MKDIR_P) $(DESTDIR)$(pdfdir) - $(INSTALL_DATA) $(PDF_TARGETS) $(DESTDIR)$(pdfdir) + umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" + $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" install-ps: ps - umask 022; $(MKDIR_P) $(DESTDIR)$(psdir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} $(DESTDIR)$(psdir); \ + $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ [ -n "${GZIP_PROG}" ] || continue; \ - rm -f $(DESTDIR)$(psdir)/$${file}.gz; \ - ${GZIP_PROG} -9n $(DESTDIR)$(psdir)/$${file}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ + ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ done ## Top-level Makefile installs the info pages. @@ -227,20 +213,20 @@ install-doc: install-dvi install-html install-pdf install-ps uninstall-dvi: for file in $(DVI_TARGETS); do \ - rm -f $(DESTDIR)$(dvidir)/$${file}; \ + rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ done uninstall-html: for file in $(HTML_TARGETS); do \ - rm -f $(DESTDIR)$(htmldir)/$${file}; \ + rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ done uninstall-ps: ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ for file in $(PS_TARGETS); do \ - rm -f $(DESTDIR)$(psdir)/$${file}$${ext}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ done uninstall-pdf: for file in $(PDF_TARGETS); do \ - rm -f $(DESTDIR)$(pdfdir)/$${file}; \ + rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ done uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps diff --git a/doc/lispref/README b/doc/lispref/README index b94bd10789c..fd943ce97c2 100644 --- a/doc/lispref/README +++ b/doc/lispref/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2013 Free Software Foundation, Inc. -*- outline -*- +Copyright (C) 2001-2015 Free Software Foundation, Inc. -*- outline -*- See the end of the file for license conditions. @@ -21,15 +21,15 @@ Buying a manual from the Free Software Foundation helps support our GNU development work. See <http://shop.fsf.org/>. (At time of writing, this manual is out of print.) -* The master file for formatting this manual for Tex is called `elisp.texi'. +* The master file for formatting this manual for Tex is called 'elisp.texi'. It contains @include commands to include all the chapters that make up the manual. * This distribution contains a Makefile that you can use with GNU Make. -** To make an Info file, you need to install Texinfo, then run `make info'. +** To make an Info file, you need to install Texinfo, then run 'make info'. -** Use `make elisp.pdf' or `make elisp.html' to create PDF or HTML versions. +** Use 'make elisp.pdf' or 'make elisp.html' to create PDF or HTML versions. This file is part of GNU Emacs. diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index 7cc558f9391..bcbea87c04d 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1994, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Abbrevs @@ -59,6 +59,7 @@ expanded in the buffer. For the user-level commands for abbrevs, see @node Abbrev Tables @section Abbrev Tables +@cindex abbrev tables This section describes how to create and manipulate abbrev tables. @@ -126,13 +127,14 @@ to add these to @var{name} separately.) @node Defining Abbrevs @section Defining Abbrevs +@cindex defining abbrevs @code{define-abbrev} is the low-level basic function for defining an abbrev in an abbrev table. When a major mode defines a system abbrev, it should call @code{define-abbrev} and specify @code{t} for the @code{:system} -property. Be aware that any saved non-``system'' abbrevs are restored +property. Be aware that any saved non-system abbrevs are restored at startup, i.e., before some major modes are loaded. Therefore, major modes should not assume that their abbrev tables are empty when they are first loaded. @@ -143,13 +145,13 @@ This function defines an abbrev named @var{name}, in with properties @var{props} (@pxref{Abbrev Properties}). The return value is @var{name}. The @code{:system} property in @var{props} is treated specially here: if it has the value @code{force}, then it will -overwrite an existing definition even for a non-``system'' abbrev of +overwrite an existing definition even for a non-system abbrev of the same name. @var{name} should be a string. The argument @var{expansion} is normally the desired expansion (a string), or @code{nil} to undefine the abbrev. If it is anything but a string or @code{nil}, then the -abbreviation ``expands'' solely by running @var{hook}. +abbreviation expands solely by running @var{hook}. The argument @var{hook} is a function or @code{nil}. If @var{hook} is non-@code{nil}, then it is called with no arguments after the abbrev is @@ -181,6 +183,7 @@ callers. @node Abbrev Files @section Saving Abbrevs in Files +@cindex save abbrevs in files A file of saved abbrev definitions is actually a file of Lisp code. The abbrevs are saved in the form of a Lisp program to define the same @@ -232,6 +235,9 @@ define the same abbrevs. If @var{filename} is @code{nil} or omitted, @node Abbrev Expansion @section Looking Up and Expanding Abbreviations +@cindex looking up abbrevs +@cindex expanding abbrevs +@cindex abbrevs, looking up and expanding Abbrevs are usually expanded by certain interactive commands, including @code{self-insert-command}. This section describes the @@ -257,13 +263,16 @@ as in @code{abbrev-symbol}. @deffn Command expand-abbrev This command expands the abbrev before point, if any. If point does not -follow an abbrev, this command does nothing. The command returns the -abbrev symbol if it did expansion, @code{nil} otherwise. - -If the abbrev symbol has a hook function that is a symbol whose -@code{no-self-insert} property is non-@code{nil}, and if the hook -function returns @code{nil} as its value, then @code{expand-abbrev} -returns @code{nil} even though expansion did occur. +follow an abbrev, this command does nothing. To do the expansion, it +calls the function that is the value of the @code{abbrev-expand-function} +variable, with no arguments, and returns whatever that function does. + +The default expansion function returns the abbrev symbol if it did +expansion, and @code{nil} otherwise. If the abbrev symbol has a hook +function that is a symbol whose @code{no-self-insert} property is +non-@code{nil}, and if the hook function returns @code{nil} as its +value, then the default expansion function returns @code{nil}, +even though expansion did occur. @end deffn @defun abbrev-insert abbrev &optional name start end @@ -331,24 +340,21 @@ has already been unexpanded. This contains information left by @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. @end defvar -@defvar abbrev-expand-functions -This is a wrapper hook (@pxref{Running Hooks}) run around the -@code{expand-abbrev} function. Each function on this hook is called -with a single argument: a function that performs the normal abbrev -expansion. The hook function can hence do anything it wants before -and after performing the expansion. It can also choose not to call -its argument, thus overriding the default behavior; or it may even -call it several times. The function should return the abbrev symbol -if expansion took place. +@defvar abbrev-expand-function +The value of this variable is a function that @code{expand-abbrev} +will call with no arguments to do the expansion. The function can do +anything it wants before and after performing the expansion. +It should return the abbrev symbol if expansion took place. @end defvar The following sample code shows a simple use of -@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a +@code{abbrev-expand-function}. It assumes that @code{foo-mode} is a mode for editing certain files in which lines that start with @samp{#} are comments. You want to use Text mode abbrevs for those lines. The regular local abbrev table, @code{foo-mode-abbrev-table} is appropriate for all other lines. @xref{Standard Abbrev Tables}, for the definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. +@xref{Advising Functions}, for details of @code{add-function}. @smallexample (defun foo-mode-abbrev-expand-function (expand) @@ -361,13 +367,13 @@ definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. (add-hook 'foo-mode-hook #'(lambda () - (add-hook 'abbrev-expand-functions - 'foo-mode-abbrev-expand-function - nil t))) + (add-function :around (local 'abbrev-expand-function) + #'foo-mode-abbrev-expand-function))) @end smallexample @node Standard Abbrev Tables @section Standard Abbrev Tables +@cindex standard abbrev tables Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs. @@ -410,6 +416,7 @@ Properties}. @node Abbrev Properties @section Abbrev Properties +@cindex abbrev properties Abbrevs have properties, some of which influence the way they work. You can provide them as arguments to @code{define-abbrev}, and @@ -450,6 +457,7 @@ modifies the capitalization of the expansion. @node Abbrev Table Properties @section Abbrev Table Properties +@cindex abbrev table properties Like abbrevs, abbrev tables have properties, some of which influence the way they work. You can provide them as arguments to diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi deleted file mode 100644 index e8d1bd3cdbc..00000000000 --- a/doc/lispref/advice.texi +++ /dev/null @@ -1,748 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2013 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Advising Functions -@chapter Advising Emacs Lisp Functions -@cindex advising functions - - The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. This is a cleaner method -for a library to customize functions defined within Emacs---cleaner -than redefining the whole function. - -@cindex piece of advice - Each function can have multiple @dfn{pieces of advice}, each of -which can be separately defined and then @dfn{enabled} or -@dfn{disabled}. All the enabled pieces of advice for any given -function actually take effect when you @dfn{activate advice} for that -function, or when you define or redefine the function. Note that -enabling a piece of advice and activating advice for a function are -not the same thing. - - Advice is useful for altering the behavior of existing calls to an -existing function. If you want the new behavior for new function -calls or new key bindings, you should define a new function or -command, and have it use the existing function as a subroutine. - - Advising a function can cause confusion in debugging, since people -who debug calls to the original function may not notice that it has -been modified with advice. Therefore, if you have the possibility to -change the code of that function to run a hook, please solve the -problem that way. Advice should be reserved for the cases where you -cannot get the function changed. In particular, Emacs's own source -files should not put advice on functions in Emacs. There are -currently a few exceptions to this convention, but we aim to correct -them. - - Unless you know what you are doing, do @emph{not} advise a primitive -(@pxref{What Is a Function}). Some primitives are used by the advice -mechanism; advising them could cause an infinite recursion. Also, -many primitives are called directly from C code. Calls to the -primitive from Lisp code will take note of the advice, but calls from -C code will ignore the advice. - -@menu -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Combined Definition:: How advice is implemented. -@end menu - -@node Simple Advice -@section A Simple Advice Example - - The command @code{next-line} moves point down vertically one or more -lines; it is the standard binding of @kbd{C-n}. When used on the last -line of the buffer, this command inserts a newline to create a line to -move to if @code{next-line-add-newlines} is non-@code{nil} (its default -is @code{nil}.) - - Suppose you wanted to add a similar feature to @code{previous-line}, -which would insert a new line at the beginning of the buffer for the -command to move to (when @code{next-line-add-newlines} is -non-@code{nil}). How could you do this? - - You could do it by redefining the whole function, but that is not -modular. The advice feature provides a cleaner alternative: you can -effectively add your code to the existing function definition, without -actually changing or even seeing that definition. Here is how to do -this: - -@example -(defadvice previous-line (before next-line-at-end - (&optional arg try-vscroll)) - "Insert an empty line when moving up from the top line." - (if (and next-line-add-newlines (= arg 1) - (save-excursion (beginning-of-line) (bobp))) - (progn - (beginning-of-line) - (newline)))) -@end example - - This expression defines a @dfn{piece of advice} for the function -@code{previous-line}. This piece of advice is named -@code{next-line-at-end}, and the symbol @code{before} says that it is -@dfn{before-advice} which should run before the regular definition of -@code{previous-line}. @code{(&optional arg try-vscroll)} specifies -how the advice code can refer to the function's arguments. - - When this piece of advice runs, it creates an additional line, in the -situation where that is appropriate, but does not move point to that -line. This is the correct way to write the advice, because the normal -definition will run afterward and will move back to the newly inserted -line. - - Defining the advice doesn't immediately change the function -@code{previous-line}. That happens when you @dfn{activate} the advice, -like this: - -@example -(ad-activate 'previous-line) -@end example - -@noindent -This is what actually begins to use the advice that has been defined so -far for the function @code{previous-line}. Henceforth, whenever that -function is run, whether invoked by the user with @kbd{C-p} or -@kbd{M-x}, or called from Lisp, it runs the advice first, and its -regular definition second. - - This example illustrates before-advice, which is one @dfn{class} of -advice: it runs before the function's base definition. There are two -other advice classes: @dfn{after-advice}, which runs after the base -definition, and @dfn{around-advice}, which lets you specify an -expression to wrap around the invocation of the base definition. - -@node Defining Advice -@section Defining Advice -@cindex defining advice -@cindex advice, defining - - To define a piece of advice, use the macro @code{defadvice}. A call -to @code{defadvice} has the following syntax, which is based on the -syntax of @code{defun} and @code{defmacro}, but adds more: - -@findex defadvice -@example -(defadvice @var{function} (@var{class} @var{name} - @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} - @var{flags}...) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-form}@r{]} - @var{body-forms}...) -@end example - -@noindent -Here, @var{function} is the name of the function (or macro or special -form) to be advised. From now on, we will write just ``function'' when -describing the entity being advised, but this always includes macros and -special forms. - - In place of the argument list in an ordinary definition, an advice -definition calls for several different pieces of information. - -@cindex class of advice -@cindex before-advice -@cindex after-advice -@cindex around-advice -@var{class} specifies the @dfn{class} of the advice---one of @code{before}, -@code{after}, or @code{around}. Before-advice runs before the function -itself; after-advice runs after the function itself; around-advice is -wrapped around the execution of the function itself. After-advice and -around-advice can override the return value by setting -@code{ad-return-value}. - -@defvar ad-return-value -While advice is executing, after the function's original definition has -been executed, this variable holds its return value, which will -ultimately be returned to the caller after finishing all the advice. -After-advice and around-advice can arrange to return some other value -by storing it in this variable. -@end defvar - -The argument @var{name} is the name of the advice, a non-@code{nil} -symbol. The advice name uniquely identifies one piece of advice, within all -the pieces of advice in a particular class for a particular -@var{function}. The name allows you to refer to the piece of -advice---to redefine it, or to enable or disable it. - -The optional @var{position} specifies where, in the current list of -advice of the specified @var{class}, this new advice should be placed. -It should be either @code{first}, @code{last} or a number that specifies -a zero-based position (@code{first} is equivalent to 0). If no position -is specified, the default is @code{first}. Position values outside the -range of existing positions in this class are mapped to the beginning or -the end of the range, whichever is closer. The @var{position} value is -ignored when redefining an existing piece of advice. - -The optional @var{arglist} can be used to define the argument list for -the sake of advice. This becomes the argument list of the combined -definition that is generated in order to run the advice (@pxref{Combined -Definition}). Therefore, the advice expressions can use the argument -variables in this list to access argument values. - -The argument list used in advice need not be the same as the argument -list used in the original function, but must be compatible with it, so -that it can handle the ways the function is actually called. If two -pieces of advice for a function both specify an argument list, they must -specify the same argument list. - -@xref{Argument Access in Advice}, for more information about argument -lists and advice, and a more flexible way for advice to access the -arguments. - -The remaining elements, @var{flags}, are symbols that specify further -information about how to use this piece of advice. Here are the valid -symbols and their meanings: - -@table @code -@item activate -Activate the advice for @var{function} now. Changes in a function's -advice always take effect the next time you activate advice for the -function; this flag says to do so, for @var{function}, immediately after -defining this piece of advice. - -@cindex forward advice -This flag has no immediate effect if @var{function} itself is not defined yet (a -situation known as @dfn{forward advice}), because it is impossible to -activate an undefined function's advice. However, defining -@var{function} will automatically activate its advice. - -@item protect -Protect this piece of advice against non-local exits and errors in -preceding code and advice. Protecting advice places it as a cleanup in -an @code{unwind-protect} form, so that it will execute even if the -previous code gets an error or uses @code{throw}. @xref{Cleanups}. - -@item compile -Compile the combined definition that is used to run the advice. This -flag is ignored unless @code{activate} is also specified. -@xref{Combined Definition}. - -@item disable -Initially disable this piece of advice, so that it will not be used -unless subsequently explicitly enabled. @xref{Enabling Advice}. - -@item preactivate -Activate advice for @var{function} when this @code{defadvice} is -compiled or macroexpanded. This generates a compiled advised definition -according to the current advice state, which will be used during -activation if appropriate. @xref{Preactivation}. - -This is useful only if this @code{defadvice} is byte-compiled. -@end table - -The optional @var{documentation-string} serves to document this piece of -advice. When advice is active for @var{function}, the documentation for -@var{function} (as returned by @code{documentation}) combines the -documentation strings of all the advice for @var{function} with the -documentation string of its original function definition. - -The optional @var{interactive-form} form can be supplied to change the -interactive behavior of the original function. If more than one piece -of advice has an @var{interactive-form}, then the first one (the one -with the smallest position) found among all the advice takes precedence. - -The possibly empty list of @var{body-forms} specifies the body of the -advice. The body of an advice can access or change the arguments, the -return value, the binding environment, and perform any other kind of -side effect. - -@strong{Warning:} When you advise a macro, keep in mind that macros are -expanded when a program is compiled, not when a compiled program is run. -All subroutines used by the advice need to be available when the byte -compiler expands the macro. - -@deffn Command ad-unadvise function -This command deletes all pieces of advice from @var{function}. -@end deffn - -@deffn Command ad-unadvise-all -This command deletes all pieces of advice from all functions. -@end deffn - -@node Around-Advice -@section Around-Advice - - Around-advice lets you ``wrap'' a Lisp expression ``around'' the -original function definition. You specify where the original function -definition should go by means of the special symbol @code{ad-do-it}. -Where this symbol occurs inside the around-advice body, it is replaced -with a @code{progn} containing the forms of the surrounded code. Here -is an example: - -@example -(defadvice foo (around foo-around) - "Ignore case in `foo'." - (let ((case-fold-search t)) - ad-do-it)) -@end example - -@noindent -Its effect is to make sure that case is ignored in -searches when the original definition of @code{foo} is run. - -@defvar ad-do-it -This is not really a variable, rather a place-holder that looks like a -variable. You use it in around-advice to specify the place to run the -function's original definition and other ``earlier'' around-advice. -@end defvar - -If the around-advice does not use @code{ad-do-it}, then it does not run -the original function definition. This provides a way to override the -original definition completely. (It also overrides lower-positioned -pieces of around-advice). - -If the around-advice uses @code{ad-do-it} more than once, the original -definition is run at each place. In this way, around-advice can execute -the original definition (and lower-positioned pieces of around-advice) -several times. Another way to do that is by using @code{ad-do-it} -inside of a loop. - -@node Computed Advice -@section Computed Advice - -The macro @code{defadvice} resembles @code{defun} in that the code for -the advice, and all other information about it, are explicitly stated in -the source code. You can also create advice whose details are computed, -using the function @code{ad-add-advice}. - -@defun ad-add-advice function advice class position -Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to -@var{function} in class @var{class}. The argument @var{advice} has -this form: - -@example -(@var{name} @var{protected} @var{enabled} @var{definition}) -@end example - -@noindent -Here, @var{protected} and @var{enabled} are flags; if @var{protected} -is non-@code{nil}, the advice is protected against non-local exits -(@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the -advice is initially disabled (@pxref{Enabling Advice}). -@var{definition} should have the form - -@example -(advice . @var{lambda}) -@end example - -@noindent -where @var{lambda} is a lambda expression; this lambda expression is -called in order to perform the advice. @xref{Lambda Expressions}. - -If the @var{function} argument to @code{ad-add-advice} already has one -or more pieces of advice in the specified @var{class}, then -@var{position} specifies where in the list to put the new piece of -advice. The value of @var{position} can either be @code{first}, -@code{last}, or a number (counting from 0 at the beginning of the -list). Numbers outside the range are mapped to the beginning or the -end of the range, whichever is closer. The @var{position} value is -ignored when redefining an existing piece of advice. - -If @var{function} already has a piece of @var{advice} with the same -name, then the position argument is ignored and the old advice is -replaced with the new one. -@end defun - -@node Activation of Advice -@section Activation of Advice -@cindex activating advice -@cindex advice, activating - -By default, advice does not take effect when you define it---only when -you @dfn{activate} advice for the function. However, the advice will -be activated automatically if you define or redefine the function -later. You can request the activation of advice for a function when -you define the advice, by specifying the @code{activate} flag in the -@code{defadvice}; or you can activate the advice separately by calling -the function @code{ad-activate} or one of the other activation -commands listed below. - -Separating the activation of advice from the act of defining it permits -you to add several pieces of advice to one function efficiently, without -redefining the function over and over as each advice is added. More -importantly, it permits defining advice for a function before that -function is actually defined. - -When a function's advice is first activated, the function's original -definition is saved, and all enabled pieces of advice for that function -are combined with the original definition to make a new definition. -(Pieces of advice that are currently disabled are not used; see -@ref{Enabling Advice}.) This definition is installed, and optionally -byte-compiled as well, depending on conditions described below. - -In all of the commands to activate advice, if @var{compile} is -@code{t} (or anything but @code{nil} or a negative number), the -command also compiles the combined definition which implements the -advice. If it is @code{nil} or a negative number, what happens -depends on @code{ad-default-compilation-action} as described below. - -@deffn Command ad-activate function &optional compile -This command activates all the advice defined for @var{function}. -@end deffn - - Activating advice does nothing if @var{function}'s advice is already -active. But if there is new advice, added since the previous time you -activated advice for @var{function}, it activates the new advice. - -@deffn Command ad-deactivate function -This command deactivates the advice for @var{function}. -@cindex deactivating advice -@c @cindex advice, deactivating "advice, activating" is just above -@end deffn - -@deffn Command ad-update function &optional compile -This command activates the advice for @var{function} -if its advice is already activated. This is useful -if you change the advice. -@end deffn - -@deffn Command ad-activate-all &optional compile -This command activates the advice for all functions. -@end deffn - -@deffn Command ad-deactivate-all -This command deactivates the advice for all functions. -@end deffn - -@deffn Command ad-update-all &optional compile -This command activates the advice for all functions -whose advice is already activated. This is useful -if you change the advice of some functions. -@end deffn - -@deffn Command ad-activate-regexp regexp &optional compile -This command activates all pieces of advice whose names match -@var{regexp}. More precisely, it activates all advice for any function -which has at least one piece of advice that matches @var{regexp}. -@end deffn - -@deffn Command ad-deactivate-regexp regexp -This command deactivates all pieces of advice whose names match -@var{regexp}. More precisely, it deactivates all advice for any -function which has at least one piece of advice that matches -@var{regexp}. -@end deffn - -@deffn Command ad-update-regexp regexp &optional compile -This command activates pieces of advice whose names match @var{regexp}, -but only those for functions whose advice is already activated. -@cindex reactivating advice - -Reactivating a function's advice is useful for putting into effect all -the changes that have been made in its advice (including enabling and -disabling specific pieces of advice; @pxref{Enabling Advice}) since the -last time it was activated. -@end deffn - -@deffn Command ad-start-advice -Turn on automatic advice activation when a function is defined or -redefined. This is the default mode. -@end deffn - -@deffn Command ad-stop-advice -Turn off automatic advice activation when a function is defined or -redefined. -@end deffn - -@defopt ad-default-compilation-action -This variable controls whether to compile the combined definition -that results from activating advice for a function. - -A value of @code{always} specifies to compile unconditionally. -A value of @code{never} specifies never compile the advice. - -A value of @code{maybe} specifies to compile if the byte compiler is -already loaded. A value of @code{like-original} specifies to compile -the advice if the original definition of the advised function is -compiled or a built-in function. - -This variable takes effect only if the @var{compile} argument of -@code{ad-activate} (or any of the above functions) did not force -compilation. -@end defopt - - If the advised definition was constructed during ``preactivation'' -(@pxref{Preactivation}), then that definition must already be compiled, -because it was constructed during byte-compilation of the file that -contained the @code{defadvice} with the @code{preactivate} flag. - -@node Enabling Advice -@section Enabling and Disabling Advice -@cindex enabling advice -@cindex advice, enabling and disabling -@cindex disabling advice - - Each piece of advice has a flag that says whether it is enabled or -not. By enabling or disabling a piece of advice, you can turn it on -and off without having to undefine and redefine it. For example, here is -how to disable a particular piece of advice named @code{my-advice} for -the function @code{foo}: - -@example -(ad-disable-advice 'foo 'before 'my-advice) -@end example - - This function by itself only changes the enable flag for a piece of -advice. To make the change take effect in the advised definition, you -must activate the advice for @code{foo} again: - -@example -(ad-activate 'foo) -@end example - -@deffn Command ad-disable-advice function class name -This command disables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - -@deffn Command ad-enable-advice function class name -This command enables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - - You can also disable many pieces of advice at once, for various -functions, using a regular expression. As always, the changes take real -effect only when you next reactivate advice for the functions in -question. - -@deffn Command ad-disable-regexp regexp -This command disables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@deffn Command ad-enable-regexp regexp -This command enables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@node Preactivation -@section Preactivation -@cindex preactivating advice -@cindex advice, preactivating - - Constructing a combined definition to execute advice is moderately -expensive. When a library advises many functions, this can make loading -the library slow. In that case, you can use @dfn{preactivation} to -construct suitable combined definitions in advance. - - To use preactivation, specify the @code{preactivate} flag when you -define the advice with @code{defadvice}. This @code{defadvice} call -creates a combined definition which embodies this piece of advice -(whether enabled or not) plus any other currently enabled advice for the -same function, and the function's own definition. If the -@code{defadvice} is compiled, that compiles the combined definition -also. - - When the function's advice is subsequently activated, if the enabled -advice for the function matches what was used to make this combined -definition, then the existing combined definition is used, thus avoiding -the need to construct one. Thus, preactivation never causes wrong -results---but it may fail to do any good, if the enabled advice at the -time of activation doesn't match what was used for preactivation. - - Here are some symptoms that can indicate that a preactivation did not -work properly, because of a mismatch. - -@itemize @bullet -@item -Activation of the advised -function takes longer than usual. -@item -The byte compiler gets -loaded while an advised function gets activated. -@item -@code{byte-compile} is included in the value of @code{features} even -though you did not ever explicitly use the byte compiler. -@end itemize - -Compiled preactivated advice works properly even if the function itself -is not defined until later; however, the function needs to be defined -when you @emph{compile} the preactivated advice. - -There is no elegant way to find out why preactivated advice is not being -used. What you can do is to trace the function -@code{ad-cache-id-verification-code} (with the function -@code{trace-function-background}) before the advised function's advice -is activated. After activation, check the value returned by -@code{ad-cache-id-verification-code} for that function: @code{verified} -means that the preactivated advice was used, while other values give -some information about why they were considered inappropriate. - - @strong{Warning:} There is one known case that can make preactivation -fail, in that a preconstructed combined definition is used even though -it fails to match the current state of advice. This can happen when two -packages define different pieces of advice with the same name, in the -same class, for the same function. But you should avoid that anyway. - -@node Argument Access in Advice -@section Argument Access in Advice - - The simplest way to access the arguments of an advised function in the -body of a piece of advice is to use the same names that the function -definition uses. To do this, you need to know the names of the argument -variables of the original function. - - While this simple method is sufficient in many cases, it has a -disadvantage: it is not robust, because it hard-codes the argument names -into the advice. If the definition of the original function changes, -the advice might break. - - Another method is to specify an argument list in the advice itself. -This avoids the need to know the original function definition's argument -names, but it has a limitation: all the advice on any particular -function must use the same argument list, because the argument list -actually used for all the advice comes from the first piece of advice -for that function. - - A more robust method is to use macros that are translated into the -proper access forms at activation time, i.e., when constructing the -advised definition. Access macros access actual arguments by their -(zero-based) position, regardless of how these actual arguments get -distributed onto the argument variables of a function. This is robust -because in Emacs Lisp the meaning of an argument is strictly -determined by its position in the argument list. - -@defmac ad-get-arg position -This returns the actual argument that was supplied at @var{position}. -@end defmac - -@defmac ad-get-args position -This returns the list of actual arguments supplied starting at -@var{position}. -@end defmac - -@defmac ad-set-arg position value -This sets the value of the actual argument at @var{position} to -@var{value} -@end defmac - -@defmac ad-set-args position value-list -This sets the list of actual arguments starting at @var{position} to -@var{value-list}. -@end defmac - - Now an example. Suppose the function @code{foo} is defined as - -@example -(defun foo (x y &optional z &rest r) ...) -@end example - -@noindent -and is then called with - -@example -(foo 0 1 2 3 4 5 6) -@end example - -@noindent -which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is -@code{(3 4 5 6)} within the body of @code{foo}. Here is what -@code{ad-get-arg} and @code{ad-get-args} return in this case: - -@example -(ad-get-arg 0) @result{} 0 -(ad-get-arg 1) @result{} 1 -(ad-get-arg 2) @result{} 2 -(ad-get-arg 3) @result{} 3 -(ad-get-args 2) @result{} (2 3 4 5 6) -(ad-get-args 4) @result{} (4 5 6) -@end example - - Setting arguments also makes sense in this example: - -@example -(ad-set-arg 5 "five") -@end example - -@noindent -has the effect of changing the sixth argument to @code{"five"}. If this -happens in advice executed before the body of @code{foo} is run, then -@var{r} will be @code{(3 4 "five" 6)} within that body. - - Here is an example of setting a tail of the argument list: - -@example -(ad-set-args 0 '(5 4 3 2 1 0)) -@end example - -@noindent -If this happens in advice executed before the body of @code{foo} is run, -then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} -will be 3, and @var{r} will be @code{(2 1 0)} inside the body of -@code{foo}. - - These argument constructs are not really implemented as Lisp macros. -Instead they are implemented specially by the advice mechanism. - -@node Combined Definition -@section The Combined Definition - - Suppose that a function has @var{n} pieces of before-advice -(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of -around-advice and @var{k} pieces of after-advice. Assuming no piece -of advice is protected, the combined definition produced to implement -the advice for a function looks like this: - -@example -(lambda @var{arglist} - @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} - (let (ad-return-value) - @r{before-0-body-form}... - .... - @r{before-@var{n}@minus{}1-body-form}... - @r{around-0-body-form}... - @r{around-1-body-form}... - .... - @r{around-@var{m}@minus{}1-body-form}... - (setq ad-return-value - @r{apply original definition to @var{arglist}}) - @r{end-of-around-@var{m}@minus{}1-body-form}... - .... - @r{end-of-around-1-body-form}... - @r{end-of-around-0-body-form}... - @r{after-0-body-form}... - .... - @r{after-@var{k}@minus{}1-body-form}... - ad-return-value)) -@end example - -Macros are redefined as macros, which means adding @code{macro} to -the beginning of the combined definition. - -The interactive form is present if the original function or some piece -of advice specifies one. When an interactive primitive function is -advised, advice uses a special method: it calls the primitive with -@code{call-interactively} so that it will read its own arguments. -In this case, the advice cannot access the arguments. - -The body forms of the various advice in each class are assembled -according to their specified order. The forms of around-advice @var{l} -are included in one of the forms of around-advice @var{l} @minus{} 1. - -The innermost part of the around advice onion is - -@display -apply original definition to @var{arglist} -@end display - -@noindent -whose form depends on the type of the original function. The variable -@code{ad-return-value} is set to whatever this returns. The variable is -visible to all pieces of advice, which can access and modify it before -it is actually returned from the advised function. - -The semantic structure of advised functions that contain protected -pieces of advice is the same. The only difference is that -@code{unwind-protect} forms ensure that the protected advice gets -executed even if some previous piece of advice had an error or a -non-local exit. If any around-advice is protected, then the whole -around-advice onion is protected as a result. diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi index 577411ba9df..2fc43da8e53 100644 --- a/doc/lispref/anti.texi +++ b/doc/lispref/anti.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002-2013 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2002-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c This node must have no pointers. @@ -30,7 +30,7 @@ minimum of fuss. But @xref{Dynamic Binding Tips}, for tips to avoid making your programs hard to understand. @item -Calling a minor mode function from Lisp with a nil or omitted argument +Calling a minor mode function from Lisp with a @code{nil} or omitted argument does not enable the minor mode unconditionally; instead, it toggles the minor mode---which is the straightforward thing to do, since that is the behavior when invoked interactively. One downside is that it @@ -56,8 +56,8 @@ there is no need to worry about the insertion of right-to-left text messing up how lines and paragraphs are displayed, the function @code{bidi-string-mark-left-to-right} has been removed; so have many other functions and variables related to bidirectional display. -Unicode directionality characters like @code{U+200E} ("left-to-right -mark") have no special effect on display. +Unicode directionality characters like @code{U+200E} LEFT-TO-RIGHT +MARK have no special effect on display. @item Emacs windows now have most of their internal state hidden from Lisp. @@ -66,7 +66,7 @@ Internal windows are no longer visible to Lisp; functions such as and window-local buffer lists have all been removed. Functions for resizing windows can delete windows if they become too small. -The ``action function'' feature for controlling buffer display has +The action-function feature for controlling buffer display has been removed, including @code{display-buffer-overriding-action} and related variables, as well as the @var{action} argument to @code{display-buffer} and other functions. The way to @@ -78,7 +78,7 @@ other variables. The standard completion interface has been simplified, eliminating the @code{completion-extra-properties} variable, the @code{metadata} action flag for completion functions, and the concept of -``completion categories''. Lisp programmers may now find the choice +completion categories. Lisp programmers may now find the choice of methods for tuning completion less bewildering, but if a package finds the streamlined interface insufficient for its needs, it must implement its own specialized completion feature. diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi index ef20f8b79e0..c4f2b5eb852 100644 --- a/doc/lispref/back.texi +++ b/doc/lispref/back.texi @@ -1,11 +1,12 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c @c %**start of header @setfilename back-cover @settitle GNU Emacs Lisp Reference Manual +@include docstyle.texi @c %**end of header . @sp 7 @@ -16,7 +17,7 @@ Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming +than a mere extension language; it is a full computer programming language in its own right. You can use it as you would any other programming language. diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index f2599c773ea..d37df25d267 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1995, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Backups and Auto-Saving @@ -50,6 +50,7 @@ don't want them any more, or Emacs can delete them automatically. @node Making Backups @subsection Making Backup Files +@cindex making backup files @defun backup-buffer This function makes a backup of the file visited by the current @@ -57,13 +58,15 @@ buffer, if appropriate. It is called by @code{save-buffer} before saving the buffer the first time. If a backup was made by renaming, the return value is a cons cell of -the form (@var{modes} @var{context} @var{backupname}), where +the form (@var{modes} @var{extra-alist} @var{backupname}), where @var{modes} are the mode bits of the original file, as returned by -@code{file-modes} (@pxref{File Attributes,, Other Information about -Files}), @var{context} is a list describing the original file's -SELinux context (@pxref{File Attributes}), and @var{backupname} is the -name of the backup. In all other cases, that is, if a backup was made -by copying or if no backup was made, this function returns @code{nil}. +@code{file-modes} (@pxref{Testing Accessibility}), @var{extra-alist} +is an alist describing the original file's extended attributes, as +returned by @code{file-extended-attributes} (@pxref{Extended +Attributes}), and @var{backupname} is the name of the backup. + +In all other cases (i.e., if a backup was made by copying or if no +backup was made), this function returns @code{nil}. @end defun @defvar buffer-backed-up @@ -88,8 +91,7 @@ save disk space. (You would put this code in your init file.) @smallexample @group (add-hook 'rmail-mode-hook - (lambda () - (set (make-local-variable 'make-backup-files) nil))) + (lambda () (setq-local make-backup-files nil))) @end group @end smallexample @end defopt @@ -148,13 +150,12 @@ ignored. @end defopt @defopt make-backup-file-name-function -This variable's value is a function to use for making backups instead -of the default @code{make-backup-file-name}. A value of @code{nil} -gives the default @code{make-backup-file-name} behavior. +This variable's value is a function to use for making backup file names. +The function @code{make-backup-file-name} calls it. @xref{Backup Names,, Naming Backup Files}. This could be buffer-local to do something special for specific -files. If you define it, you may need to change +files. If you change it, you may need to change @code{backup-file-name-p} and @code{file-name-sans-versions} too. @end defopt @@ -238,6 +239,7 @@ The default is 200. @node Numbered Backups @subsection Making and Deleting Numbered Backup Files +@cindex numbered backups If a file's name is @file{foo}, the names of its numbered backup versions are @file{foo.~@var{v}~}, for various integers @var{v}, like @@ -299,6 +301,7 @@ file. The default is@tie{}2. @node Backup Names @subsection Naming Backup Files +@cindex naming backup files The functions in this section are documented mainly because you can customize the naming conventions for backup files by redefining them. @@ -395,7 +398,7 @@ those versions by excluding them from the @sc{cdr} of the value. @xref{Numbered Backups}. In this example, the value says that @file{~rms/foo.~5~} is the name -to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' +to use for the new backup file, and @file{~rms/foo.~3~} is an excess version that the caller should consider deleting now. @smallexample @@ -668,6 +671,7 @@ not initialize @code{auto-save-list-file-name}. @node Reverting @section Reverting +@cindex reverting buffers If you have made extensive changes to a file and then change your mind about them, you can get rid of them by reading in the previous version @@ -725,25 +729,24 @@ buffer-local bindings for these variables: @defvar revert-buffer-function @anchor{Definition of revert-buffer-function} The value of this variable is the function to use to revert this -buffer. If non-@code{nil}, it should be a function with two optional +buffer. It should be a function with two optional arguments to do the work of reverting. The two optional arguments, @var{ignore-auto} and @var{noconfirm}, are the arguments that -@code{revert-buffer} received. If the value is @code{nil}, reverting -works the usual way. +@code{revert-buffer} received. Modes such as Dired mode, in which the text being edited does not consist of a file's contents but can be regenerated in some other -fashion, can give this variable a buffer-local value that is a function to -regenerate the contents. +fashion, can give this variable a buffer-local value that is a special +function to regenerate the contents. @end defvar @defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, specifies the function to use to +The value of this variable specifies the function to use to insert the updated contents when reverting this buffer. The function receives two arguments: first the file name to use; second, @code{t} if the user has asked to read the auto-save file. -The reason for a mode to set this variable instead of +The reason for a mode to change this variable instead of @code{revert-buffer-function} is to avoid duplicating or replacing the rest of what @code{revert-buffer} does: asking for confirmation, clearing the undo list, deciding the proper major mode, and running the @@ -751,21 +754,23 @@ hooks listed below. @end defvar @defvar before-revert-hook -This normal hook is run by @code{revert-buffer} before -inserting the modified contents---but only if -@code{revert-buffer-function} is @code{nil}. +This normal hook is run by the default @code{revert-buffer-function} +before inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. @end defvar @defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after inserting -the modified contents---but only if @code{revert-buffer-function} is -@code{nil}. +This normal hook is run by the default @code{revert-buffer-function} +after inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. @end defvar @c FIXME? Move this section from arevert-xtra to here? @defvar buffer-stale-function -The value of this variable, if non-@code{nil}, specifies a function -to call to check whether a non-file buffer needs reverting +The value of this variable specifies a function to call to check +whether a buffer needs reverting. The default value only handles +buffers that are visiting files, by checking their modification time. +Buffers that are not visiting files require a custom function @iftex (@pxref{Supporting additional buffers,,, emacs-xtra, Specialized Emacs Features}). @end iftex diff --git a/doc/lispref/book-spine.texi b/doc/lispref/book-spine.texi index 721416316d2..8c6381f3d81 100644 --- a/doc/lispref/book-spine.texi +++ b/doc/lispref/book-spine.texi @@ -2,6 +2,7 @@ @c %**start of header @setfilename book-spine @settitle book-spine +@include docstyle.texi @c %**end of header @include emacsver.texi diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 01269851250..45a21c8e806 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Buffers @@ -23,9 +23,9 @@ not be displayed in any windows. * Buffer File Name:: The buffer file name indicates which file is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". + behind Emacs's back. * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. -* The Buffer List:: How to look at all the existing buffers. +* Buffer List:: How to look at all the existing buffers. * Creating Buffers:: Functions that create buffers. * Killing Buffers:: Buffers exist until explicitly killed. * Indirect Buffers:: An indirect buffer shares text with some other buffer. @@ -632,13 +632,12 @@ exceptional places where the usual test to avoid overwriting a changed file should not be done. @end defun -@c Emacs 19 feature @defun visited-file-modtime This function returns the current buffer's recorded last file modification time, as a list of the form @code{(@var{high} @var{low} -@var{microsec} @var{picosec})}. -(This is the same format that @code{file-attributes} uses to return -time values; see @ref{File Attributes}.) +@var{microsec} @var{picosec})}. (This is the same format that +@code{file-attributes} uses to return time values; @pxref{File +Attributes}.) If the buffer has no recorded last modification time, this function returns zero. This case occurs, for instance, if the buffer is not @@ -648,17 +647,9 @@ visiting a file or if the time has been explicitly cleared by too. For instance, in a Dired buffer listing a directory, it returns the last modification time of that directory, as recorded by Dired. -For a new buffer visiting a not yet existing file, @var{high} is -@minus{}1 and @var{low} is 65535, that is, -@ifnottex -@w{2**16 @minus{} 1.} -@end ifnottex -@tex -@math{2^{16}-1}. -@end tex +If the buffer is not visiting a file, this function returns -1. @end defun -@c Emacs 19 feature @defun set-visited-file-modtime &optional time This function updates the buffer's record of the last modification time of the visited file, to the value specified by @var{time} if @var{time} @@ -768,9 +759,10 @@ buffer is read-only. @xref{Using Interactive}, for another way to signal an error if the current buffer is read-only. @end defun -@node The Buffer List +@node Buffer List @section The Buffer List @cindex buffer list +@cindex listing all buffers The @dfn{buffer list} is a list of all live buffers. The order of the buffers in this list is based primarily on how recently each buffer has @@ -852,7 +844,7 @@ names start with a space are not considered at all. If @var{buffer} is not supplied (or if it is not a live buffer), then @code{other-buffer} returns the first buffer in the selected frame's -local buffer list. (If @var{frame} is non-@code{nil}, it returns the +local buffer list. (If @var{frame} is non-@code{nil}, it returns the first buffer in @var{frame}'s local buffer list instead.) If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, @@ -872,7 +864,7 @@ If no suitable buffer exists, the buffer @file{*scratch*} is returned @defun last-buffer &optional buffer visible-ok frame This function returns the last buffer in @var{frame}'s buffer list other -than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the +than @var{buffer}. If @var{frame} is omitted or @code{nil}, it uses the selected frame's buffer list. The argument @var{visible-ok} is handled as with @code{other-buffer}, @@ -901,7 +893,7 @@ another buffer is shown in it. More precisely, if the selected window is dedicated (@pxref{Dedicated Windows}) and there are other windows on its frame, the window is deleted. If it is the only window on its frame and that frame is not the only frame on its terminal, the frame is -``dismissed'' by calling the function specified by +dismissed by calling the function specified by @code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise, it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show another buffer in that window. If @var{buffer-or-name} is displayed in @@ -919,6 +911,13 @@ buffer returned by @code{last-buffer} (see above), in the selected window. @end deffn +@defvar buffer-list-update-hook +This is a normal hook run whenever the buffer list changes. Functions +(implicitly) running this hook are @code{get-buffer-create} +(@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}), +@code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see +above) and @code{select-window} (@pxref{Selecting Windows}). +@end defvar @node Creating Buffers @section Creating Buffers @@ -1033,7 +1032,7 @@ memory for other uses or to be returned to the operating system. If buffer. Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} (``hangup'') signal, which normally causes them +sent the @code{SIGHUP} (hangup) signal, which normally causes them to terminate. @xref{Signals to Processes}. If the buffer is visiting a file and contains unsaved changes, @@ -1140,7 +1139,7 @@ be a live buffer or the name (a string) of an existing buffer. If @var{name} is the name of an existing buffer, an error is signaled. If @var{clone} is non-@code{nil}, then the indirect buffer originally -shares the ``state'' of @var{base-buffer} such as major mode, minor +shares the state of @var{base-buffer} such as major mode, minor modes, buffer local variables and so on. If @var{clone} is omitted or @code{nil} the indirect buffer's state is set to the default state for new buffers. @@ -1217,6 +1216,7 @@ in the text it is swapped with will not interfere with auto-saving. @node Buffer Gap @section The Buffer Gap +@cindex buffer gap Emacs buffers are implemented using an invisible @dfn{gap} to make insertion and deletion faster. Insertion works by filling in part of diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 846d6f3a4a9..7ddf5ee8f74 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Command Loop @@ -108,24 +108,46 @@ command does. The special form @code{interactive} turns a Lisp function into a command. The @code{interactive} form must be located at top-level in -the function body (usually as the first form in the body), or in the -@code{interactive-form} property of the function symbol. When the -@code{interactive} form is located in the function body, it does -nothing when actually executed. Its presence serves as a flag, which -tells the Emacs command loop that the function can be called -interactively. The argument of the @code{interactive} form controls -the reading of arguments for an interactive call. +the function body, usually as the first form in the body; this applies +to both lambda expressions (@pxref{Lambda Expressions}) and +@code{defun} forms (@pxref{Defining Functions}). This form does +nothing during the actual execution of the function; its presence +serves as a flag, telling the Emacs command loop that the function can +be called interactively. The argument of the @code{interactive} form +specifies how the arguments for an interactive call should be read. + +@cindex @code{interactive-form} property + Alternatively, an @code{interactive} form may be specified in a +function symbol's @code{interactive-form} property. A non-@code{nil} +value for this property takes precedence over any @code{interactive} +form in the function body itself. This feature is seldom used. + +@anchor{The interactive-only property} +@cindex @code{interactive-only} property + Sometimes, a function is only intended to be called interactively, +never directly from Lisp. In that case, give the function a +non-@code{nil} @code{interactive-only} property, either directly +or via @code{declare} (@pxref{Declare Form}). This causes the +byte compiler to warn if the command is called from Lisp. The output +of @code{describe-function} will include similar information. +The value of the property can be: a string, which the byte-compiler +will use directly in its warning (it should end with a period, and not +start with a capital, e.g., @code{"use (system-name) instead."}); @code{t}; any +other symbol, which should be an alternative function to use in Lisp +code. @menu * Using Interactive:: General rules for @code{interactive}. * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Generic Commands:: Select among command alternatives. @end menu @node Using Interactive @subsection Using @code{interactive} @cindex arguments, interactive entry +@cindex interactive spec, using This section describes how to write the @code{interactive} form that makes a Lisp function an interactively-callable command, and how to @@ -189,7 +211,7 @@ argument. The prompt string can use @samp{%} to include previous argument values (starting with the first argument) in the prompt. This is done using -@code{format} (@pxref{Formatting Strings}). For example, here is how +@code{format-message} (@pxref{Formatting Strings}). For example, here is how you could read the name of an existing buffer followed by a new name to give to that buffer: @@ -562,6 +584,34 @@ Put them into three windows, selecting the last one." @end group @end example +@node Generic Commands +@subsection Select among Command Alternatives +@cindex generic commands +@cindex alternatives, defining + +The macro @code{define-alternatives} can be used to define +@dfn{generic commands}. These are interactive functions whose +implementation can be selected from several alternatives, as a matter +of user preference. + +@defmac define-alternatives command &rest customizations +Define the new command @var{command}, a symbol. + +When a user runs @kbd{M-x @var{command} @key{RET}} for the first time, +Emacs prompts for which real form of the command to use, and records +the selection by way of a custom variable. Using a prefix argument +repeats this process of choosing an alternative. + +The variable @code{@var{command}-alternatives} should contain an alist +with alternative implementations of @var{command}. +Until this variable is set, @code{define-alternatives} has no effect. + +If @var{customizations} is non-@code{nil}, it should consist of +alternating @code{defcustom} keywords (typically @code{:group} and +@code{:version}) and values to add to the declaration of +@code{@var{command}-alternatives}. +@end defmac + @node Interactive Call @section Interactive Call @cindex interactive call @@ -698,6 +748,8 @@ part of the prompt. @node Distinguish Interactive @section Distinguish Interactive Calls +@cindex distinguish interactive calls +@cindex is this call interactive Sometimes a command should display additional visual feedback (such as an informative message in the echo area) for interactive calls @@ -786,6 +838,7 @@ Here is another example that contrasts direct and indirect calls to @node Command Loop Info @section Information from the Command Loop +@cindex command loop variables The editor command loop sets several Lisp variables to keep status records for itself and for commands that are run. With the exception of @@ -990,8 +1043,8 @@ the current Emacs session. If a symbol has not yet been so used, @end defun @menu -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. +* Keyboard Events:: Ordinary characters -- keys with symbols on them. +* Function Keys:: Function keys -- keys with names, not symbols. * Mouse Events:: Overview of mouse events. * Click Events:: Pushing and releasing a mouse button. * Drag Events:: Moving the mouse before releasing the button. @@ -1342,8 +1395,9 @@ The position in the string where the click occurred. @item @var{text-pos} For clicks on a marginal area or on a fringe, this is the buffer position of the first visible character in the corresponding line in -the window. For other events, it is the current buffer position in -the window. +the window. For clicks on the mode line or the header line, this is +@code{nil}. For other events, it is the buffer position closest to +the click. @item @var{col}, @var{row} These are the actual column and row coordinate numbers of the glyph @@ -1408,7 +1462,7 @@ the symbols @code{handle} (the scroll bar handle), @code{above-handle} (the area above the handle), @code{below-handle} (the area below the handle), @code{up} (the up arrow at one end of the scroll bar), or @code{down} (the down arrow at one end of the scroll bar). -@c The `top', `bottom', and `end-scroll' codes don't seem to be used. +@c The 'top', 'bottom', and 'end-scroll' codes don't seem to be used. @end table @@ -1435,8 +1489,10 @@ prefix @samp{drag-}. For example, dragging the mouse with button 2 held down generates a @code{drag-mouse-2} event. The second and third elements of the event give the starting and ending position of the drag, as mouse position lists (@pxref{Click Events}). You can access -the second element of any mouse event in the same way, with no need to -distinguish drag events from others. +the second element of any mouse event in the same way. However, the +drag event may end outside the boundaries of the frame that was +initially selected. In that case, the third element's position list +contains that frame in place of a window. The @samp{drag-} prefix follows the modifier key prefixes such as @samp{C-} and @samp{M-}. @@ -1501,8 +1557,8 @@ the command binding of the double click event to assume that the single-click command has already run. It must produce the desired results of a double click, starting from the results of a single click. -This is convenient, if the meaning of a double click somehow ``builds -on'' the meaning of a single click---which is recommended user interface +This is convenient, if the meaning of a double click somehow builds +on the meaning of a single click---which is recommended user interface design practice for double clicks. If you click a button, then press it down again and start moving the @@ -1581,7 +1637,10 @@ represented by lists that look like this: @noindent @var{position} is a mouse position list (@pxref{Click Events}), -specifying the current position of the mouse cursor. +specifying the current position of the mouse cursor. As with the +end-position of a drag event, this position list may represent a +location outside the boundaries of the initially selected frame, in +which case the list contains that frame in place of a window. The special form @code{track-mouse} enables generation of motion events within its body. Outside of @code{track-mouse} forms, Emacs @@ -1661,7 +1720,7 @@ occurred. @vindex mouse-wheel-up-event @vindex mouse-wheel-down-event -This kind of event is generated only on some kinds of systems. On some +This kind of event is generated only on some kinds of systems. On some systems, @code{mouse-4} and @code{mouse-5} are used instead. For portable code, use the variables @code{mouse-wheel-up-event} and @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine @@ -1796,6 +1855,14 @@ into another window. That produces a pair of events like these: -453816)) @end smallexample +The frame with input focus might not take up the entire screen, and +the user might move the mouse outside the scope of the frame. Inside +the @code{track-mouse} special form, that produces an event like this: + +@smallexample +(mouse-movement (#<frame *ielm* 0x102849a30> nil (563 . 205) 532301936)) +@end smallexample + To handle a SIGUSR1 signal, define an interactive function, and bind it to the @code{signal usr1} event sequence: @@ -1809,6 +1876,7 @@ bind it to the @code{signal usr1} event sequence: @node Classifying Events @subsection Classifying Events @cindex event type +@cindex classifying events Every event has an @dfn{event type}, which classifies the event for key binding purposes. For a keyboard event, the event type equals the @@ -1921,9 +1989,12 @@ must be the last element of the list. For example, @node Accessing Mouse @subsection Accessing Mouse Events @cindex mouse events, data in +@cindex keyboard events, data in This section describes convenient functions for accessing the data in -a mouse button or motion event. +a mouse button or motion event. Keyboard event data can be accessed +using the same functions, but data elements that aren't applicable to +keyboard events are zero or @code{nil}. The following two functions return a mouse position list (@pxref{Click Events}), specifying the position of a mouse event. @@ -1956,7 +2027,9 @@ Events}); and @code{nil} otherwise. various parts of it: @defun posn-window position -Return the window that @var{position} is in. +Return the window that @var{position} is in. If @var{position} +represents a location outside the frame where the event was initiated, +return that frame instead. @end defun @defun posn-area position @@ -1995,23 +2068,30 @@ POSITION is assumed to lie in a window text area." @defun posn-col-row position This function returns a cons cell @code{(@var{col} . @var{row})}, containing the estimated column and row corresponding to buffer -position @var{position}. The return value is given in units of the -frame's default character width and height, as computed from the -@var{x} and @var{y} values corresponding to @var{position}. (So, if -the actual characters have non-default sizes, the actual row and -column may differ from these computed values.) +position in @var{position}. The return value is given in units of the +frame's default character width and default line height (including +spacing), as computed from the @var{x} and @var{y} values +corresponding to @var{position}. (So, if the actual characters have +non-default sizes, the actual row and column may differ from these +computed values.) Note that @var{row} is counted from the top of the text area. If the -window possesses a header line (@pxref{Header Lines}), it is -@emph{not} counted as the first line. +window given by @var{position} possesses a header line (@pxref{Header +Lines}), it is @emph{not} included in the @var{row} count. @end defun @defun posn-actual-col-row position Return the actual row and column in @var{position}, as a cons cell @code{(@var{col} . @var{row})}. The values are the actual row and -column numbers in the window. @xref{Click Events}, for details. It -returns @code{nil} if @var{position} does not include actual positions -values. +column numbers in the window given by @var{position}. @xref{Click +Events}, for details. The function returns @code{nil} if +@var{position} does not include actual position values; in that case +@code{posn-col-row} can be used to get approximate values. + +Note that this function doesn't account for the visual width of +characters on display, like the number of visual columns taken by a +tab character or an image. If you need the coordinates in canonical +character units, use @code{posn-col-row} instead. @end defun @defun posn-string position @@ -2033,8 +2113,9 @@ Return the image or string object in @var{position}, either @defun posn-object-x-y position Return the pixel-based x and y coordinates relative to the upper left corner of the object in @var{position} as a cons cell @code{(@var{dx} -. @var{dy})}. If the @var{position} is a buffer position, return the -relative position in the character at that position. +. @var{dy})}. If the @var{position} is on buffer text, return the +relative position of the buffer-text character closest to that +position. @end defun @defun posn-object-width-height position @@ -2363,7 +2444,7 @@ same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event---in the coordinates. But @code{read-key-sequence} translates this information into imaginary -``prefix keys'', all of which are symbols: @code{header-line}, +prefix keys, all of which are symbols: @code{header-line}, @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, @code{vertical-line}, and @code{vertical-scroll-bar}. You can define meanings for mouse clicks in special window parts by defining key @@ -2395,9 +2476,12 @@ and key sequences read from keyboard macros being executed. @code{read-char}, and @code{read-char-exclusive}. @defun read-event &optional prompt inherit-input-method seconds -This function reads and returns the next event of command input, waiting -if necessary until an event is available. Events can come directly from -the user or from a keyboard macro. +This function reads and returns the next event of command input, +waiting if necessary until an event is available. + +The returned event may come directly from the user, or from a keyboard +macro. It is not decoded by the keyboard's input coding system +(@pxref{Terminal I/O Encoding}). If the optional argument @var{prompt} is non-@code{nil}, it should be a string to display in the echo area as a prompt. Otherwise, @@ -2418,7 +2502,7 @@ displayed there. Otherwise @code{read-event} does not move the cursor. If @var{seconds} is non-@code{nil}, it should be a number specifying the maximum time to wait for input, in seconds. If no input arrives within that time, @code{read-event} stops waiting and returns -@code{nil}. A floating-point value for @var{seconds} means to wait +@code{nil}. A floating point @var{seconds} means to wait for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, @var{seconds} is rounded down. If @var{seconds} is @code{nil}, @code{read-event} waits as long as @@ -2503,7 +2587,7 @@ If you wish to read a single key taking these translations into account, use the function @code{read-key}: @defun read-key &optional prompt -This function reads a single key. It is ``intermediate'' between +This function reads a single key. It is intermediate between @code{read-key-sequence} and @code{read-event}. Unlike the former, it reads a single key, not a key sequence. Unlike the latter, it does not return a raw event, but decodes and translates the user input @@ -2527,6 +2611,9 @@ then continues to wait for a valid input character, or keyboard-quit. @node Event Mod @subsection Modifying and Translating Input Events +@cindex modifiers of events +@cindex translating input events +@cindex event translation Emacs modifies every event it reads according to @code{extra-keyboard-modifiers}, then translates it through @@ -2546,7 +2633,7 @@ character for this purpose, but as a character with no modifiers. Thus, setting @code{extra-keyboard-modifiers} to zero cancels any modification. -When using a window system, the program can ``press'' any of the +When using a window system, the program can press any of the modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can be virtually pressed. @@ -2608,6 +2695,7 @@ at the level of @code{read-key-sequence}. @node Invoking the Input Method @subsection Invoking the Input Method +@cindex invoking input method The event-reading functions invoke the current input method, if any (@pxref{Input Methods}). If the value of @code{input-method-function} @@ -2695,7 +2783,7 @@ What character @kbd{1 7 7}- @node Event Input Misc @subsection Miscellaneous Event Input Features -This section describes how to ``peek ahead'' at events without using +This section describes how to peek ahead at events without using them up, how to check for pending input, and how to discard pending input. See also the function @code{read-passwd} (@pxref{Reading a Password}). @@ -2730,7 +2818,7 @@ most recently unread will be reread first. Events read from this list are not normally added to the current command's key sequence (as returned by, e.g., @code{this-command-keys}), as the events will already have been added once as they were read for -the first time. An element of the form @code{(@code{t} . @var{event})} +the first time. An element of the form @w{@code{(t . @var{event})}} forces @var{event} to be added to the current command's key sequence. @end defvar @@ -2739,12 +2827,16 @@ This function converts the string or vector @var{key} to a list of individual events, which you can put in @code{unread-command-events}. @end defun -@defun input-pending-p +@defun input-pending-p &optional check-timers @cindex waiting for command key input This function determines whether any command input is currently available to be read. It returns immediately, with value @code{t} if there is available input, @code{nil} otherwise. On rare occasions it may return @code{t} when no input is available. + +If the optional argument @var{check-timers} is non-@code{nil}, then if +no input is available, Emacs runs any timers which are ready. +@xref{Timers}. @end defun @defvar last-input-event @@ -2858,8 +2950,8 @@ time to read text that you display. The value is @code{t} if @code{sit-for} waited the full time with no input arriving (@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sit-for} waits for a fractional number of seconds. +The argument @var{seconds} need not be an integer. If it is floating +point, @code{sit-for} waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, @var{seconds} is rounded down. @@ -2885,8 +2977,8 @@ This function simply pauses for @var{seconds} seconds without updating the display. It pays no attention to available input. It returns @code{nil}. -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sleep-for} waits for a fractional number of seconds. +The argument @var{seconds} need not be an integer. If it is floating +point, @code{sleep-for} waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, @var{seconds} is rounded down. @@ -2956,7 +3048,7 @@ usual result of this---a quit---is prevented. Eventually, binding is unwound at the end of a @code{let} form. At that time, if @code{quit-flag} is still non-@code{nil}, the requested quit happens immediately. This behavior is ideal when you wish to make sure that -quitting does not happen within a ``critical section'' of the program. +quitting does not happen within a critical section of the program. @cindex @code{read-quoted-char} quitting In some functions (such as @code{read-quoted-char}), @kbd{C-g} is @@ -3024,7 +3116,7 @@ in @ref{Errors}.) @end deffn You can specify a character other than @kbd{C-g} to use for quitting. -See the function @code{set-input-mode} in @ref{Terminal Input}. +See the function @code{set-input-mode} in @ref{Input Modes}. @node Prefix Command Arguments @section Prefix Command Arguments @@ -3219,7 +3311,7 @@ using the minibuffer. Usually it is more convenient for the user if you change the major mode of the current buffer temporarily to a special major mode, which should have a command to go back to the previous mode. (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively'', create and select +give the user different text to edit recursively, create and select a new buffer in a special mode. In this mode, define a command to complete the processing and go back to the previous buffer. (The @kbd{m} command in Rmail does this.) diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 95f7341c19c..8c23086e8d1 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Byte Compilation @chapter Byte Compilation @@ -140,7 +140,7 @@ definition of @var{symbol} (@pxref{Byte-Code Objects}). If @var{symbol}'s definition is a byte-code function object, @code{byte-compile} does nothing and returns @code{nil}. It does not -``compile the symbol's definition again'', since the original +compile the symbol's definition again, since the original (non-compiled) code has already been replaced in the symbol's function cell by the byte-compiled code. @@ -240,60 +240,50 @@ $ emacs -batch -f batch-byte-compile *.el @section Documentation Strings and Compilation @cindex dynamic loading of documentation - Functions and variables loaded from a byte-compiled file access their -documentation strings dynamically from the file whenever needed. This -saves space within Emacs, and makes loading faster because the -documentation strings themselves need not be processed while loading the -file. Actual access to the documentation strings becomes slower as a -result, but this normally is not enough to bother users. + When Emacs loads functions and variables from a byte-compiled file, +it normally does not load their documentation strings into memory. +Each documentation string is dynamically loaded from the +byte-compiled file only when needed. This saves memory, and speeds up +loading by skipping the processing of the documentation strings. - Dynamic access to documentation strings does have drawbacks: + This feature has a drawback: if you delete, move, or alter the +compiled file (such as by compiling a new version), Emacs may no +longer be able to access the documentation string of previously-loaded +functions or variables. Such a problem normally only occurs if you +build Emacs yourself, and happen to edit and/or recompile the Lisp +source files. To solve it, just reload each file after recompilation. -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer access the documentation strings for the functions and variables -in the file. - -@item -If you alter the compiled file (such as by compiling a new version), -then further access to documentation strings in this file will -probably give nonsense results. -@end itemize + Dynamic loading of documentation strings from byte-compiled files is +determined, at compile time, for each byte-compiled file. It can be +disabled via the option @code{byte-compile-dynamic-docstrings}. -@noindent -These problems normally occur only if you build Emacs yourself and use -it from the directory where you built it, and you happen to edit -and/or recompile the Lisp source files. They can be easily cured by -reloading each file after recompiling it. +@defopt byte-compile-dynamic-docstrings +If this is non-@code{nil}, the byte compiler generates compiled files +that are set up for dynamic loading of documentation strings. -@cindex @samp{#@@@var{count}} -@cindex @samp{#$} - The dynamic documentation string feature writes compiled files that -use a special Lisp reader construct, @samp{#@@@var{count}}. This -construct skips the next @var{count} characters. It also uses the -@samp{#$} construct, which stands for ``the name of this file, as a -string''. It is usually best not to use these constructs in Lisp source -files, since they are not designed to be clear to humans reading the -file. - - You can disable the dynamic documentation string feature at compile -time by setting @code{byte-compile-dynamic-docstrings} to @code{nil}; -this is useful mainly if you expect to change the file, and you want -Emacs processes that have already loaded it to keep working when the -file changes. You can do this globally, or for one source file by -specifying a file-local binding for the variable. One way to do that -is by adding this string to the file's first line: +To disable the dynamic loading feature for a specific file, set this +option to @code{nil} in its header line (@pxref{File Variables, , +Local Variables in Files, emacs, The GNU Emacs Manual}), like this: -@example +@smallexample -*-byte-compile-dynamic-docstrings: nil;-*- -@end example +@end smallexample -@defopt byte-compile-dynamic-docstrings -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic loading of documentation strings. +This is useful mainly if you expect to change the file, and you want +Emacs sessions that have already loaded it to keep working when the +file changes. @end defopt +@cindex @samp{#@@@var{count}} +@cindex @samp{#$} +Internally, the dynamic loading of documentation strings is +accomplished by writing compiled files with a special Lisp reader +construct, @samp{#@@@var{count}}. This construct skips the next +@var{count} characters. It also uses the @samp{#$} construct, which +stands for the name of this file, as a string. Do not use these +constructs in Lisp source files; they are not designed to be clear to +humans reading the file. + @node Dynamic Loading @section Dynamic Loading of Individual Functions @@ -357,6 +347,7 @@ it does nothing. It always returns @var{function}. @node Eval During Compile @section Evaluation During Compilation +@cindex eval during compilation These features permit you to write code to be evaluated during compilation of a program. @@ -440,29 +431,35 @@ to what @code{eval-when-compile} does. @section Compiler Errors @cindex compiler errors - Byte compilation outputs all errors and warnings into the buffer -@file{*Compile-Log*}. The messages include file names and line -numbers that identify the location of the problem. The usual Emacs -commands for operating on compiler diagnostics work properly on these + Error and warning messages from byte compilation are printed in a +buffer named @file{*Compile-Log*}. These messages include file names +and line numbers identifying the location of the problem. The usual +Emacs commands for operating on compiler output can be used on these messages. When an error is due to invalid syntax in the program, the byte compiler might get confused about the errors' exact location. One way -to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}. -(This buffer name starts with a space, so it does not show up in -@kbd{M-x list-buffers}.) This buffer contains the program being +to investigate is to switch to the buffer @w{@file{ *Compiler +Input*}}. (This buffer name starts with a space, so it does not show +up in the Buffer Menu.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read; the cause of the error might be nearby. @xref{Syntax Errors}, for some tips for locating syntax errors. - When the byte compiler warns about functions that were used but not -defined, it always reports the line number for the end of the file, -not the locations where the missing functions were called. To find -the latter, you must search for the function names. + A common type of warning issued by the byte compiler is for +functions and variables that were used but not defined. Such warnings +report the line number for the end of the file, not the locations +where the missing functions or variables were used; to find these, you +must search the file manually. + + If you are sure that a warning message about a missing function or +variable is unjustified, there are several ways to suppress it: - You can suppress the compiler warning for calling an undefined -function @var{func} by conditionalizing the function call on an -@code{fboundp} test, like this: +@itemize @bullet +@item +You can suppress the warning for a specific call to a function +@var{func} by conditionalizing it on an @code{fboundp} test, like +this: @example (if (fboundp '@var{func}) ...(@var{func} ...)...) @@ -473,14 +470,10 @@ The call to @var{func} must be in the @var{then-form} of the @code{if}, and @var{func} must appear quoted in the call to @code{fboundp}. (This feature operates for @code{cond} as well.) - You can tell the compiler that a function is defined using -@code{declare-function} (@pxref{Declaring Functions}). Likewise, you -can tell the compiler that a variable is defined using @code{defvar} -with no initial value. - - You can suppress the compiler warning for a specific use of an -undefined variable @var{variable} by conditionalizing its use on a -@code{boundp} test, like this: +@item +Likewise, you can suppress the warning for a specific use of a +variable @var{variable} by conditionalizing it on a @code{boundp} +test: @example (if (boundp '@var{variable}) ...@var{variable}...) @@ -491,7 +484,17 @@ The reference to @var{variable} must be in the @var{then-form} of the @code{if}, and @var{variable} must appear quoted in the call to @code{boundp}. - You can suppress any and all compiler warnings within a certain +@item +You can tell the compiler that a function is defined using +@code{declare-function}. @xref{Declaring Functions}. + +@item +Likewise, you can tell the compiler that a variable is defined using +@code{defvar} with no initial value. (Note that this marks the +variable as special.) @xref{Defining Variables}. +@end itemize + + You can also suppress any and all compiler warnings within a certain expression using the construct @code{with-no-warnings}: @c This is implemented with a defun, but conceptually it is @@ -507,8 +510,9 @@ possible piece of code, to avoid missing possible warnings other than one you intend to suppress. @end defspec - More precise control of warnings is possible by setting the variable -@code{byte-compile-warnings}. + Byte compiler warnings can be controlled more precisely by setting +the variable @code{byte-compile-warnings}. See its documentation +string for details. @node Byte-Code Objects @section Byte-Code Function Objects diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 70eabcd84a4..412903f8fbc 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Control Structures @@ -39,11 +39,14 @@ structure constructs (@pxref{Macros}). * Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. * Combining Conditions:: @code{and}, @code{or}, @code{not}. * Iteration:: @code{while} loops. +* Generators:: Generic sequences and coroutines. * Nonlocal Exits:: Jumping out of a sequence. @end menu @node Sequencing @section Sequencing +@cindex sequencing +@cindex sequential execution Evaluating forms in the order they appear is the most common way control passes from one form to another. In some contexts, such as in a @@ -70,7 +73,7 @@ The value of the last form in the body becomes the value of the entire two or more forms in succession and use the value of the last of them. But programmers found they often needed to use a @code{progn} in the body of a function, where (at that time) only one form was allowed. So -the body of a function was made into an ``implicit @code{progn}'': +the body of a function was made into an implicit @code{progn}: several forms are allowed just as in the body of an actual @code{progn}. Many other control structures likewise contain an implicit @code{progn}. As a result, @code{progn} is not used as much as it was many years ago. @@ -217,16 +220,12 @@ list is the @var{condition}; the remaining elements, if any, the @code{cond} tries the clauses in textual order, by evaluating the @var{condition} of each clause. If the value of @var{condition} is -non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its -@var{body-forms}, and the value of the last of @var{body-forms} becomes -the value of the @code{cond}. The remaining clauses are ignored. +non-@code{nil}, the clause succeeds; then @code{cond} evaluates its +@var{body-forms}, and returns the value of the last of @var{body-forms}. +Any remaining clauses are ignored. -If the value of @var{condition} is @code{nil}, the clause ``fails'', so -the @code{cond} moves on to the following clause, trying its -@var{condition}. - -If every @var{condition} evaluates to @code{nil}, so that every clause -fails, @code{cond} returns @code{nil}. +If the value of @var{condition} is @code{nil}, the clause fails, so +the @code{cond} moves on to the following clause, trying its @var{condition}. A clause may also look like this: @@ -235,8 +234,11 @@ A clause may also look like this: @end example @noindent -Then, if @var{condition} is non-@code{nil} when tested, the value of -@var{condition} becomes the value of the @code{cond} form. +Then, if @var{condition} is non-@code{nil} when tested, the @code{cond} +form returns the value of @var{condition}. + +If every @var{condition} evaluates to @code{nil}, so that every clause +fails, @code{cond} returns @code{nil}. The following example has four clauses, which test for the cases where the value of @code{x} is a number, string, buffer and symbol, @@ -323,18 +325,19 @@ In the last clause, @code{code} is a variable that gets bound to the value that was returned by @code{(get-return-code x)}. To give a more complex example, a simple interpreter for a little -expression language could look like: +expression language could look like (note that this example requires +lexical binding): @example (defun evaluate (exp env) (pcase exp - (`(add ,x ,y) (+ (evaluate x env) (evaluate y env))) - (`(call ,fun ,arg) (funcall (evaluate fun) (evaluate arg env))) - (`(fn ,arg ,body) (lambda (val) - (evaluate body (cons (cons arg val) env)))) - ((pred numberp) exp) - ((pred symbolp) (cdr (assq exp env))) - (_ (error "Unknown expression %S" exp)))) + (`(add ,x ,y) (+ (evaluate x env) (evaluate y env))) + (`(call ,fun ,arg) (funcall (evaluate fun env) (evaluate arg env))) + (`(fn ,arg ,body) (lambda (val) + (evaluate body (cons (cons arg val) env)))) + ((pred numberp) exp) + ((pred symbolp) (cdr (assq exp env))) + (_ (error "Unknown expression %S" exp)))) @end example Where @code{`(add ,x ,y)} is a pattern that checks that @code{exp} is a three @@ -343,6 +346,15 @@ third elements and binds them to the variables @code{x} and @code{y}. @code{(pred numberp)} is a pattern that simply checks that @code{exp} is a number, and @code{_} is the catch-all pattern that matches anything. +Here are some sample programs including their evaluation results: + +@example +(evaluate '(add 1 2) nil) ;=> 3 +(evaluate '(add x y) '((x . 1) (y . 2))) ;=> 3 +(evaluate '(call (fn x (add 1 x)) 2) nil) ;=> 3 +(evaluate '(sub 1 2) nil) ;=> error +@end example + There are two kinds of patterns involved in @code{pcase}, called @emph{U-patterns} and @emph{Q-patterns}. The @var{upattern} mentioned above are U-patterns and can take the following forms: @@ -359,8 +371,12 @@ that location. More specifically, a Q-pattern can take the following forms: @table @code @item (@var{qpattern1} . @var{qpattern2}) -This pattern matches any cons cell whose @code{car} matches @var{QPATTERN1} and -whose @code{cdr} matches @var{PATTERN2}. +This pattern matches any cons cell whose @code{car} matches @var{qpattern1} and +whose @code{cdr} matches @var{qpattern2}. +@item [@var{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}] +This pattern matches a vector of length @var{M} whose 0..(@var{M}-1)th +elements match @var{qpattern1}, @var{qpattern2} @dots{} @var{qpatternm}, +respectively. @item @var{atom} This pattern matches any atom @code{equal} to @var{atom}. @item ,@var{upattern} @@ -392,6 +408,7 @@ the variable @code{x}. @node Combining Conditions @section Constructs for Combining Conditions +@cindex combining conditions This section describes three constructs that are often used together with @code{if} and @code{cond} to express complicated conditions. The @@ -554,7 +571,7 @@ The value of a @code{while} form is always @code{nil}. @end group @end example -To write a ``repeat...until'' loop, which will execute something on each +To write a repeat-until loop, which will execute something on each iteration and then do the end-test, put the body followed by the end-test in a @code{progn} as the first argument of @code{while}, as shown here: @@ -604,6 +621,123 @@ Here is an example of using @code{dotimes} to do something 100 times: @end example @end defmac +@node Generators +@section Generators +@cindex generators + + A @dfn{generator} is a function that produces a potentially-infinite +stream of values. Each time the function produces a value, it +suspends itself and waits for a caller to request the next value. + +@defmac iter-defun name args [doc] [declare] [interactive] body@dots{} +@code{iter-defun} defines a generator function. A generator function +has the same signature as a normal function, but works differently. +Instead of executing @var{body} when called, a generator function +returns an iterator object. That iterator runs @var{body} to generate +values, emitting a value and pausing where @code{iter-yield} or +@code{iter-yield-from} appears. When @var{body} returns normally, +@code{iter-next} signals @code{iter-end-of-sequence} with @var{body}'s +result as its condition data. + +Any kind of Lisp code is valid inside @var{body}, but +@code{iter-yield} and @code{iter-yield-from} cannot appear inside +@code{unwind-protect} forms. + +@end defmac + +@defmac iter-lambda args [doc] [interactive] body@dots{} +@code{iter-lambda} produces an unnamed generator function that works +just like a generator function produced with @code{iter-defun}. +@end defmac + +@defmac iter-yield value +When it appears inside a generator function, @code{iter-yield} +indicates that the current iterator should pause and return +@var{value} from @code{iter-next}. @code{iter-yield} evaluates to the +@code{value} parameter of next call to @code{iter-next}. +@end defmac + +@defmac iter-yield-from iterator +@code{iter-yield-from} yields all the values that @var{iterator} +produces and evaluates to the value that @var{iterator}'s generator +function returns normally. While it has control, @var{iterator} +receives values sent to the iterator using @code{iter-next}. +@end defmac + + To use a generator function, first call it normally, producing a +@dfn{iterator} object. An iterator is a specific instance of a +generator. Then use @code{iter-next} to retrieve values from this +iterator. When there are no more values to pull from an iterator, +@code{iter-next} raises an @code{iter-end-of-sequence} condition with +the iterator's final value. + +It's important to note that generator function bodies only execute +inside calls to @code{iter-next}. A call to a function defined with +@code{iter-defun} produces an iterator; you must drive this +iterator with @code{iter-next} for anything interesting to happen. +Each call to a generator function produces a @emph{different} +iterator, each with its own state. + +@defun iter-next iterator value +Retrieve the next value from @var{iterator}. If there are no more +values to be generated (because @var{iterator}'s generator function +returned), @code{iter-next} signals the @code{iter-end-of-sequence} +condition; the data value associated with this condition is the value +with which @var{iterator}'s generator function returned. + +@var{value} is sent into the iterator and becomes the value to which +@code{iter-yield} evaluates. @var{value} is ignored for the first +@code{iter-next} call to a given iterator, since at the start of +@var{iterator}'s generator function, the generator function is not +evaluating any @code{iter-yield} form. +@end defun + +@defun iter-close iterator +If @var{iterator} is suspended inside an @code{unwind-protect}'s +@code{bodyform} and becomes unreachable, Emacs will eventually run +unwind handlers after a garbage collection pass. (Note that +@code{iter-yield} is illegal inside an @code{unwind-protect}'s +@code{unwindforms}.) To ensure that these handlers are run before +then, use @code{iter-close}. +@end defun + +Some convenience functions are provided to make working with +iterators easier: + +@defmac iter-do (var iterator) body @dots{} +Run @var{body} with @var{var} bound to each value that +@var{iterator} produces. +@end defmac + +The Common Lisp loop facility also contains features for working with +iterators. See @xref{Loop Facility,,,cl,Common Lisp Extensions}. + +The following piece of code demonstrates some important principles of +working with iterators. + +@example +(iter-defun my-iter (x) + (iter-yield (1+ (iter-yield (1+ x)))) + ;; Return normally + -1) + +(let* ((iter (my-iter 5)) + (iter2 (my-iter 0))) + ;; Prints 6 + (print (iter-next iter)) + ;; Prints 9 + (print (iter-next iter 8)) + ;; Prints 1; iter and iter2 have distinct states + (print (iter-next iter2 nil)) + + ;; We expect the iter sequence to end now + (condition-case x + (iter-next iter) + (iter-end-of-sequence + ;; Prints -1, which my-iter returned normally + (print (cdr x))))) +@end example + @node Nonlocal Exits @section Nonlocal Exits @cindex nonlocal exits @@ -724,7 +858,7 @@ error is signaled with data @code{(@var{tag} @var{value})}. @subsection Examples of @code{catch} and @code{throw} One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``goto''.) +nested loop. (In most languages, this would be done with a @code{goto}.) Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} varying from 0 to 9: @@ -838,7 +972,7 @@ returns to a point that is set up to handle the error (@pxref{Processing of Errors}). Here we describe how to signal an error. - Most errors are signaled ``automatically'' within Lisp primitives + Most errors are signaled automatically within Lisp primitives which you call for other purposes, such as if you try to take the @sc{car} of an integer or move forward a character at the end of the buffer. You can also signal errors explicitly with the functions @@ -856,7 +990,7 @@ should not end with any sort of punctuation. @defun error format-string &rest args This function signals an error with an error message constructed by -applying @code{format} (@pxref{Formatting Strings}) to +applying @code{format-message} (@pxref{Formatting Strings}) to @var{format-string} and @var{args}. These examples show typical uses of @code{error}: @@ -868,19 +1002,25 @@ These examples show typical uses of @code{error}: @end group @group -(error "You have committed %d errors" 10) - @error{} You have committed 10 errors +(error "Invalid name `%s'" "A%%B") + @error{} Invalid name ‘A%%B’ @end group @end example @code{error} works by calling @code{signal} with two arguments: the error symbol @code{error}, and a list containing the string returned by -@code{format}. +@code{format-message}. + +In a format string containing single quotes, curved quotes @t{‘like +this’} and grave quotes @t{`like this'} work better than straight +quotes @t{'like this'}, as @code{error} typically formats every +straight quote as a curved closing quote. @strong{Warning:} If you want to use your own string as an error message verbatim, don't just write @code{(error @var{string})}. If @var{string} -contains @samp{%}, it will be interpreted as a format specifier, with -undesirable results. Instead, use @code{(error "%s" @var{string})}. +@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be +reformatted, with undesirable results. Instead, use @code{(error "%s" +@var{string})}. @end defun @defun signal error-symbol data @@ -891,7 +1031,7 @@ the circumstances of the error. The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol defined with @code{define-error}. This is how Emacs Lisp classifies different -sorts of errors. @xref{Error Symbols}, for a description of error symbols, +sorts of errors. @xref{Error Symbols}, for a description of error symbols, error conditions and condition names. If the error is not handled, the two arguments are used in printing @@ -949,6 +1089,7 @@ concept of continuable errors. @node Processing of Errors @subsubsection How Emacs Processes Errors +@cindex processing of errors When an error is signaled, @code{signal} searches for an active @dfn{handler} for the error. A handler is a sequence of Lisp @@ -1243,10 +1384,13 @@ Here's the example at the beginning of this subsection rewritten using @end example @end defmac -@defmac with-demoted-errors body@dots{} +@defmac with-demoted-errors format body@dots{} This macro is like a milder version of @code{ignore-errors}. Rather than suppressing errors altogether, it converts them into messages. -Use this form around code that is not expected to signal errors, but +It uses the string @var{format} to format the message. +@var{format} should contain a single @samp{%}-sequence; e.g., +@code{"Error: %S"}. Use @code{with-demoted-errors} around code +that is not expected to signal errors, but should be robust if one does occur. Note that this macro uses @code{condition-case-unless-debug} rather than @code{condition-case}. @end defmac @@ -1351,6 +1495,7 @@ and their conditions. @node Cleanups @subsection Cleaning Up from Nonlocal Exits +@cindex nonlocal exits, cleaning up The @code{unwind-protect} construct is essential whenever you temporarily put a data structure in an inconsistent state; it permits diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index e9260309057..51d729f665c 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997-2013 Free Software Foundation, Inc. +@c Copyright (C) 1997-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Customization @chapter Customization Settings @@ -287,13 +287,17 @@ customizable variable). You should not quote @var{option}. The argument @var{standard} is an expression that specifies the standard value for @var{option}. Evaluating the @code{defcustom} form -evaluates @var{standard}, but does not necessarily install the -standard value. If @var{option} already has a default value, -@code{defcustom} does not change it. If the user has saved a -customization for @var{option}, @code{defcustom} installs the user's -customized value as @var{option}'s default value. If neither of those -cases applies, @code{defcustom} installs the result of evaluating -@var{standard} as the default value. +evaluates @var{standard}, but does not necessarily bind the option to +that value. If @var{option} already has a default value, it is left +unchanged. If the user has already saved a customization for +@var{option}, the user's customized value is installed as the default +value. Otherwise, the result of evaluating @var{standard} is +installed as the default value. + +Like @code{defvar}, this macro marks @code{option} as a special +variable, meaning that it should always be dynamically bound. If +@var{option} is already lexically bound, that lexical binding remains +in effect until the binding construct exits. @xref{Variable Scoping}. The expression @var{standard} can be evaluated at various other times, too---whenever the customization facility needs to know @var{option}'s @@ -349,8 +353,9 @@ option when using the Customize interface. The function @var{setfunction} should take two arguments, a symbol (the option name) and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting -the option as a Lisp variable). The default for @var{setfunction} is -@code{set-default}. +the option as a Lisp variable); preferably, though, it should not +modify its value argument destructively. The default for +@var{setfunction} is @code{set-default}. If you specify this keyword, the variable's documentation string should describe how to do the same job in hand-written Lisp code. @@ -360,7 +365,7 @@ should describe how to do the same job in hand-written Lisp code. Specify @var{getfunction} as the way to extract the value of this option. The function @var{getfunction} should take one argument, a symbol, and should return whatever customize should use as the -``current value'' for that symbol (which need not be the symbol's Lisp +current value for that symbol (which need not be the symbol's Lisp value). The default is @code{default-value}. You have to really understand the workings of Custom to use @@ -436,7 +441,7 @@ those other variables already have their intended values. @end table It is useful to specify the @code{:require} keyword for an option -that ``turns on'' a certain feature. This causes Emacs to load the +that turns on a certain feature. This causes Emacs to load the feature, if it is not already loaded, whenever the option is set. @xref{Common Keywords}. Here is an example, from the library @file{saveplace.el}: @@ -567,7 +572,7 @@ The value must be an integer. The value must be a number (floating point or integer). @item float -The value must be a floating point number. +The value must be floating point. @item string The value must be a string. The customization buffer shows the string @@ -718,7 +723,7 @@ simply atoms, which stand for themselves. For example: @end example @noindent -specifies that there are three ``known'' keys, namely @code{"foo"}, +specifies that there are three known keys, namely @code{"foo"}, @code{"bar"} and @code{"baz"}, which will always be shown first. You may want to restrict the value type for specific keys, for @@ -837,7 +842,7 @@ symbols, and symbols are not treated like other Lisp expressions. @item (radio @var{element-types}@dots{}) This is similar to @code{choice}, except that the choices are displayed -using `radio buttons' rather than a menu. This has the advantage of +using radio buttons rather than a menu. This has the advantage of displaying documentation for the choices when applicable and so is often a good choice for a choice between constant functions (@code{function-item} customization types). @@ -1222,6 +1227,8 @@ arguments, which will be used when creating the @code{radio-button} or @node Defining New Types @subsection Defining New Types +@cindex customization types, define new +@cindex define new customization types In the previous sections we have described how to construct elaborate type specifications for @code{defcustom}. In some cases you may want @@ -1291,6 +1298,7 @@ its @code{:type} argument only when needed. @node Applying Customizations @section Applying Customizations +@cindex applying customizations The following functions are responsible for installing the user's customization settings for variables and faces, respectively. When @@ -1348,6 +1356,7 @@ evaluated. @var{comment} is a string describing the customization. @node Custom Themes @section Custom Themes +@cindex custom themes @dfn{Custom themes} are collections of settings that can be enabled or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs Manual}. Each Custom theme is defined by an Emacs Lisp source file, @@ -1369,8 +1378,8 @@ the theme; this is the description shown when the user invokes the Themes*} buffer. Two special theme names are disallowed (using them causes an error): -@code{user} is a ``dummy'' theme that stores the user's direct -customization settings, and @code{changed} is a ``dummy'' theme that +@code{user} is a dummy theme that stores the user's direct +customization settings, and @code{changed} is a dummy theme that stores changes made outside of the Customize system. @end defmac @@ -1413,7 +1422,7 @@ where the list entries have the same meanings as in @end defun In theory, a theme file can also contain other Lisp forms, which -would be evaluated when loading the theme, but that is ``bad form''. +would be evaluated when loading the theme, but that is bad form. To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time. @@ -1428,6 +1437,17 @@ loaded into Emacs, whether or not the theme is enabled). Otherwise, it returns @code{nil}. @end defun +@defvar custom-known-themes +The value of this variable is a list of themes loaded into Emacs. +Each theme is represented by a Lisp symbol (the theme name). The +default value of this variable is a list containing two dummy +themes: @code{(user changed)}. The @code{changed} theme stores +settings made before any Custom themes are applied (e.g., variables +set outside of Customize). The @code{user} theme stores settings the +user has customized and saved. Any additional themes declared with +the @code{deftheme} macro are added to the front of this list. +@end defvar + @deffn Command load-theme theme &optional no-confirm no-enable This function loads the Custom theme named @var{theme} from its source file, looking for the source file in the directories specified by the diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 335e3f802d2..e82efbb0b72 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -1,10 +1,11 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1994, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Debugging @chapter Debugging Lisp Programs +@cindex debugging lisp programs There are several ways to find and investigate problems in an Emacs Lisp program. @@ -226,9 +227,7 @@ function, and then step through its caller. @deffn Command debug-on-entry function-name This function requests @var{function-name} to invoke the debugger each -time it is called. It works by inserting the form -@code{(implement-debug-on-entry)} into the function definition as the -first form. +time it is called. Any function or macro defined as Lisp code may be set to break on entry, regardless of whether it is interpreted code or compiled code. @@ -244,11 +243,6 @@ When @code{debug-on-entry} is called interactively, it prompts for up to invoke the debugger on entry, @code{debug-on-entry} does nothing. @code{debug-on-entry} always returns @var{function-name}. -@strong{Warning:} if you redefine a function after using -@code{debug-on-entry} on it, the code to enter the debugger is -discarded by the redefinition. In effect, redefining the function -cancels the break-on-entry feature for that function. - Here's an example to illustrate use of this function: @example @@ -277,12 +271,6 @@ Debugger entered--entering a function: ------ Buffer: *Backtrace* ------ @end group -@group -(symbol-function 'fact) - @result{} (lambda (n) - (debug (quote debug)) - (if (zerop n) 1 (* n (fact (1- n))))) -@end group @end example @end deffn @@ -297,6 +285,8 @@ not currently set up to break on entry. @node Explicit Debug @subsection Explicit Entry to the Debugger +@cindex debugger, explicit entry +@cindex force entry to debugger You can cause the debugger to be called at a certain point in your program by writing the expression @code{(debug)} at that point. To do @@ -388,6 +378,7 @@ the same function. (To do this, visit the source for the function and type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger to step through a primitive function. +@c FIXME: Add @findex for the following commands? --xfq Here is a list of Debugger mode commands: @table @kbd @@ -424,7 +415,8 @@ Flag the current frame like @kbd{b}. Then continue execution like are set up to do so by @code{debug-on-entry}. @item e -Read a Lisp expression in the minibuffer, evaluate it, and print the +Read a Lisp expression in the minibuffer, evaluate it (with the +relevant lexical environment, if applicable), and print the value in the echo area. The debugger alters certain important variables, and the current buffer, as part of its operation; @kbd{e} temporarily restores their values from outside the debugger, so you can @@ -459,13 +451,15 @@ You can't use @kbd{r} when the debugger was entered due to an error. @item l Display a list of functions that will invoke the debugger when called. This is a list of functions that are set to break on entry by means of -@code{debug-on-entry}. @strong{Warning:} if you redefine such a -function and thus cancel the effect of @code{debug-on-entry}, it may -erroneously show up in this list. +@code{debug-on-entry}. + +@item v +Toggle the display of local variables of the current stack frame. @end table @node Invoking the Debugger @subsection Invoking the Debugger +@cindex invoking lisp debugger Here we describe in full detail the function @code{debug} that is used to invoke the debugger. @@ -690,11 +684,11 @@ If @var{frame-number} is out of range, @code{backtrace-frame} returns @cindex debugging invalid Lisp syntax The Lisp reader reports invalid syntax, but cannot say where the real -problem is. For example, the error ``End of file during parsing'' in +problem is. For example, the error @samp{End of file during parsing} in evaluating an expression indicates an excess of open parentheses (or square brackets). The reader detects this imbalance at the end of the file, but it cannot figure out where the close parenthesis should have -been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close +been. Likewise, @samp{Invalid read syntax: ")"} indicates an excess close parenthesis or missing open parenthesis, but does not say where the missing parenthesis belongs. How, then, to find what to change? @@ -717,6 +711,7 @@ find the mismatch.) @node Excess Open @subsection Excess Open Parentheses +@cindex excess open parentheses The first step is to find the defun that is unbalanced. If there is an excess open parenthesis, the way to do this is to go to the end of @@ -751,6 +746,7 @@ anything. @node Excess Close @subsection Excess Close Parentheses +@cindex excess close parentheses To deal with an excess close parenthesis, first go to the beginning of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first @@ -819,6 +815,7 @@ be cleaner to combine them. @node Profiling @section Profiling @cindex profiling +@cindex profile @cindex measuring resource usage @cindex memory usage diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index ff9d98170d1..ad248b116ed 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Display @chapter Emacs Display @@ -18,12 +18,13 @@ that Emacs presents to the user. * Selective Display:: Hiding part of the buffer text (the old way). * Temporary Displays:: Displays that go away automatically. * Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. +* Size of Displayed Text:: How large displayed text is. * Line Height:: Controlling the height of lines. * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. +* Scroll Bars:: Controlling scroll bars. +* Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. @@ -38,6 +39,8 @@ that Emacs presents to the user. @node Refresh Screen @section Refreshing the Screen +@cindex refresh the screen +@cindex screen refresh The function @code{redraw-frame} clears and redisplays the entire contents of a given frame (@pxref{Frames}). This is useful if the @@ -84,10 +87,7 @@ waiting for input. @defun redisplay &optional force This function tries immediately to redisplay. The optional argument @var{force}, if non-@code{nil}, forces the redisplay to be performed, -instead of being preempted, even if input is pending and the variable -@code{redisplay-dont-pause} is @code{nil} (see below). If -@code{redisplay-dont-pause} is non-@code{nil} (the default), this -function redisplays in any case, i.e., @var{force} does nothing. +instead of being preempted if input is pending. The function returns @code{t} if it actually tried to redisplay, and @code{nil} otherwise. A value of @code{t} does not mean that @@ -95,26 +95,9 @@ redisplay proceeded to completion; it could have been preempted by newly arriving input. @end defun -@defvar redisplay-dont-pause -If this variable is @code{nil}, arriving input events preempt -redisplay; Emacs avoids starting a redisplay, and stops any redisplay -that is in progress, until the input has been processed. In -particular, @code{(redisplay)} returns @code{nil} without actually -redisplaying, if there is pending input. - -The default value is @code{t}, which means that pending input does not -preempt redisplay. -@end defvar - -@defvar redisplay-preemption-period -If @code{redisplay-dont-pause} is @code{nil}, this variable specifies -how many seconds Emacs waits between checks for new input during -redisplay; if input arrives during this interval, redisplay stops and -the input is processed. The default value is 0.1; if the value is -@code{nil}, Emacs does not check for input during redisplay. - -This variable has no effect when @code{redisplay-dont-pause} is -non-@code{nil} (the default). +@defvar pre-redisplay-function +A function run just before redisplay. It is called with one argument, +the set of windows to redisplay. @end defvar Although @code{redisplay} tries immediately to redisplay, it does @@ -143,7 +126,7 @@ it waits for input, or when the function @code{redisplay} is called. @cindex @samp{\} in display When a line of text extends beyond the right edge of a window, Emacs -can @dfn{continue} the line (make it ``wrap'' to the next screen +can @dfn{continue} the line (make it wrap to the next screen line), or @dfn{truncate} the line (limit it to one screen line). The additional screen lines used to display a long text line are called @dfn{continuation} lines. Continuation is not the same as filling; @@ -155,7 +138,7 @@ boundary. @xref{Filling}. indicate truncated and continued lines (@pxref{Fringes}). On a text terminal, a @samp{$} in the rightmost column of the window indicates truncation; a @samp{\} on the rightmost column indicates a line that -``wraps''. (The display table can specify alternate characters to use +wraps. (The display table can specify alternate characters to use for this; @pxref{Display Tables}). @defopt truncate-lines @@ -168,6 +151,7 @@ entire frame width). @end defopt @defopt truncate-partial-width-windows +@cindex partial-width windows This variable controls line truncation in @dfn{partial-width} windows. A partial-width window is one that does not occupy the entire frame width (@pxref{Splitting Windows}). If the value is @code{nil}, line @@ -213,28 +197,28 @@ A line prefix may also be specified for regions of text using the over the @code{line-prefix} variable. @xref{Special Properties}. @end defvar - If your buffer contains @emph{very} long lines, and you use -continuation to display them, computing the continuation lines can -make redisplay slow. The column computation and indentation functions -also become slow. Then you might find it advisable to set -@code{cache-long-scans} to @code{t}. +@ignore + If your buffer contains only very short lines, you might find it +advisable to set @code{cache-long-scans} to @code{nil}. @defvar cache-long-scans -If this variable is non-@code{nil}, various indentation and motion -functions, and Emacs redisplay, cache the results of scanning the -buffer, and consult the cache to avoid rescanning regions of the buffer -unless they are modified. +If this variable is non-@code{nil} (the default), various indentation +and motion functions, and Emacs redisplay, cache the results of +scanning the buffer, and consult the cache to avoid rescanning regions +of the buffer unless they are modified. -Turning on the cache slows down processing of short lines somewhat. +Turning off the cache speeds up processing of short lines somewhat. This variable is automatically buffer-local in every buffer. @end defvar +@end ignore @node The Echo Area @section The Echo Area @cindex error display @cindex echo area +@c FIXME: Why not use @xref{Minibuffers} directly? --xfq The @dfn{echo area} is used for displaying error messages (@pxref{Errors}), for messages made with the @code{message} primitive, and for echoing keystrokes. It is not the same as the minibuffer, @@ -263,16 +247,24 @@ messages in the echo area. @defun message format-string &rest arguments This function displays a message in the echo area. @var{format-string} is a format string, and @var{arguments} are the -objects for its format specifications, like in the @code{format} +objects for its format specifications, like in the @code{format-message} function (@pxref{Formatting Strings}). The resulting formatted string is displayed in the echo area; if it contains @code{face} text properties, it is displayed with the specified faces (@pxref{Faces}). The string is also added to the @file{*Messages*} buffer, but without text properties (@pxref{Logging Messages}). +In a format string containing single quotes, curved quotes @t{‘like +this’} and grave quotes @t{`like this'} work better than straight +quotes @t{'like this'}, as @code{message} typically formats every +straight quote as a curved closing quote. + In batch mode, the message is printed to the standard error stream, followed by a newline. +When @code{inhibit-message} is non-@code{nil}, no message will be displayed +in the echo area, it will only be logged to @samp{*Messages*}. + If @var{format-string} is @code{nil} or the empty string, @code{message} clears the echo area; if the echo area has been expanded automatically, this brings it back to its normal size. If @@ -281,23 +273,33 @@ onto the screen immediately. @example @group -(message "Minibuffer depth is %d." - (minibuffer-depth)) - @print{} Minibuffer depth is 0. -@result{} "Minibuffer depth is 0." +(message "Reverting `%s'..." (buffer-name)) + @print{} Reverting ‘subr.el’... +@result{} "Reverting ‘subr.el’..." @end group @group ---------- Echo Area ---------- -Minibuffer depth is 0. +Reverting ‘subr.el’... ---------- Echo Area ---------- @end group @end example To automatically display a message in the echo area or in a pop-buffer, depending on its size, use @code{display-message-or-buffer} (see below). + +@strong{Warning:} If you want to use your own string as a message +verbatim, don't just write @code{(message @var{string})}. If +@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be +reformatted, with undesirable results. Instead, use @code{(message +"%s" @var{string})}. @end defun +@defvar inhibit-message +When this variable is non-@code{nil}, @code{message} and related functions +will not use the Echo Area to display messages. +@end defvar + @defmac with-temp-message message &rest body This construct displays a message in the echo area temporarily, during the execution of @var{body}. It displays @var{message}, executes @@ -383,12 +385,12 @@ reporting very fast. When this progress reporter is subsequently used, it will display @var{message} in the echo area, followed by progress percentage. @var{message} is treated as a simple string. If you need it to depend -on a filename, for instance, use @code{format} before calling this +on a filename, for instance, use @code{format-message} before calling this function. The arguments @var{min-value} and @var{max-value} should be numbers standing for the starting and final states of the operation. For -instance, an operation that ``scans'' a buffer should set these to the +instance, an operation that scans a buffer should set these to the results of @code{point-min} and @code{point-max} correspondingly. @var{max-value} should be greater than @var{min-value}. @@ -440,20 +442,20 @@ that it prints a message in the echo area unconditionally. The first two arguments have the same meaning as for @code{progress-reporter-update}. Optional @var{new-message} allows -you to change the message of the @var{reporter}. Since this functions +you to change the message of the @var{reporter}. Since this function always updates the echo area, such a change will be immediately presented to the user. @end defun @defun progress-reporter-done reporter This function should be called when the operation is finished. It -prints the message of @var{reporter} followed by word ``done'' in the +prints the message of @var{reporter} followed by word @samp{done} in the echo area. You should always call this function and not hope for -@code{progress-reporter-update} to print ``100%''. Firstly, it may +@code{progress-reporter-update} to print @samp{100%}. Firstly, it may never print it, there are many good reasons for this not to happen. -Secondly, ``done'' is more explicit. +Secondly, @samp{done} is more explicit. @end defun @defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} @@ -479,7 +481,17 @@ this macro this way: Almost all the messages displayed in the echo area are also recorded in the @file{*Messages*} buffer so that the user can refer back to them. This includes all the messages that are output with -@code{message}. +@code{message}. By default, this buffer is read-only and uses the major +mode @code{messages-buffer-mode}. Nothing prevents the user from +killing the @file{*Messages*} buffer, but the next display of a message +recreates it. Any Lisp code that needs to access the +@file{*Messages*} buffer directly and wants to ensure that it exists +should use the function @code{messages-buffer}. + +@defun messages-buffer +This function returns the @file{*Messages*} buffer. If it does not +exist, it creates it, and switches it to @code{messages-buffer-mode}. +@end defun @defopt message-log-max This variable specifies how many lines to keep in the @file{*Messages*} @@ -498,13 +510,13 @@ facility combines successive identical messages. It also combines successive related messages for the sake of two cases: question followed by answer, and a series of progress messages. - A ``question followed by an answer'' means two messages like the + A question followed by an answer has two messages like the ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, and the second is @samp{@var{question}...@var{answer}}. The first message conveys no additional information beyond what's in the second, so logging the second message discards the first from the log. - A ``series of progress messages'' means successive messages like + A series of progress messages has successive messages like those produced by @code{make-progress-reporter}. They have the form @samp{@var{base}...@var{how-far}}, where @var{base} is the same each time, while @var{how-far} varies. Logging each message in the series @@ -517,6 +529,7 @@ are logged that share a common prefix ending in @samp{...}. @node Echo Area Customization @subsection Echo Area Customization +@cindex echo area customization These variables control details of how the echo area works. @@ -537,8 +550,7 @@ This normal hook is run whenever the echo area is cleared---either by @defopt echo-keystrokes This variable determines how much time should elapse before command -characters echo. Its value must be an integer or floating point number, -which specifies the +characters echo. Its value must be a number, and specifies the number of seconds to wait before echoing. If the user types a prefix key (such as @kbd{C-x}) and then delays this many seconds before continuing, the prefix key is echoed in the echo area. (Once echoing @@ -609,6 +621,9 @@ program signals a Lisp error and then handles it with @code{condition-case}, the user won't see the error message; it could show the message to the user by reporting it as a warning.) +@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply +@c "bytecomp" here? The parens are part of warning-type-format but +@c not part of the warning type. --xfq @cindex warning type Each warning has a @dfn{warning type} to classify it. The type is a list of symbols. The first symbol should be the custom group that you @@ -627,13 +642,13 @@ for logging the warning. By default, it is @file{*Warnings*}. @end defun @defun lwarn type level message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message. In other respects it is -equivalent to @code{display-warning}. +This function reports a warning using the value of @code{(format-message +@var{message} @var{args}...)} as the message in the @file{*Warnings*} +buffer. In other respects it is equivalent to @code{display-warning}. @end defun @defun warn message &rest args -This function reports a warning using the value of @code{(format +This function reports a warning using the value of @code{(format-message @var{message} @var{args}...)} as the message, @code{(emacs)} as the type, and @code{:warning} as the severity level. It exists for compatibility only; we recommend not using it, because you should @@ -642,6 +657,7 @@ specify a specific warning type. @node Warning Variables @subsection Warning Variables +@cindex warning variables Programs can customize how their warnings appear by binding the variables described in this section. @@ -719,6 +735,7 @@ all. @node Warning Options @subsection Warning Options +@cindex warning options These variables are used by users to control what happens when a Lisp program reports a warning. @@ -752,6 +769,7 @@ that warning is not logged. @node Delayed Warnings @subsection Delayed Warnings +@cindex delayed warnings Sometimes, you may wish to avoid showing a warning while a command is running, and only show it only after the end of the command. You can @@ -911,12 +929,14 @@ current value of @code{buffer-invisibility-spec}. @vindex line-move-ignore-invisible Ordinarily, functions that operate on text or move point do not care -whether the text is invisible. The user-level line motion commands -ignore invisible newlines if @code{line-move-ignore-invisible} is -non-@code{nil} (the default), but only because they are explicitly -programmed to do so. - - However, if a command ends with point inside or at the boundary of +whether the text is invisible, they process invisible characters and +visible characters alike. The user-level line motion commands, +such as @code{next-line}, @code{previous-line}, ignore invisible +newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the +default), i.e., behave like these invisible newlines didn't exist in +the buffer, but only because they are explicitly programmed to do so. + + If a command ends with point inside or at the boundary of invisible text, the main editing loop relocates point to one of the two ends of the invisible text. Emacs chooses the direction of relocation so that it is the same as the overall movement direction of @@ -933,6 +953,10 @@ command moved point forward into an invisible range, Emacs moves point forward to the first visible character that follows the invisible text and then forward one more character. + These @dfn{adjustments} of point that ended up in the middle of +invisible text can be disabled by setting @code{disable-point-adjustment} +to a non-@code{nil} value. @xref{Adjusting Point}. + Incremental search can make invisible overlays visible temporarily and/or permanently when a match includes invisible text. To enable this, the overlay should have a non-@code{nil} @@ -956,11 +980,11 @@ make it invisible again. @dfn{Selective display} refers to a pair of related features for hiding certain lines on the screen. - The first variant, explicit selective display, is designed for use -in a Lisp program: it controls which lines are hidden by altering the -text. This kind of hiding in some ways resembles the effect of the -@code{invisible} property (@pxref{Invisible Text}), but the two -features are different and do not work the same way. +@cindex explicit selective display + The first variant, explicit selective display, was designed for use in a Lisp +program: it controls which lines are hidden by altering the text. This kind of +hiding is now obsolete; instead you can get the same effect with the +@code{invisible} property (@pxref{Invisible Text}). In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a @@ -1069,34 +1093,36 @@ You can use a display table to substitute other text for the ellipsis @node Temporary Displays @section Temporary Displays +@cindex temporary display +@cindex temporary buffer display Temporary displays are used by Lisp programs to put output into a buffer and then present it to the user for perusal rather than for editing. Many help commands use this feature. -@defmac with-output-to-temp-buffer buffer-name forms@dots{} -This function executes @var{forms} while arranging to insert any output -they print into the buffer named @var{buffer-name}, which is first -created if necessary, and put into Help mode. Finally, the buffer is -displayed in some window, but not selected. (See the similar -form @code{with-temp-buffer-window} below.) - -If the @var{forms} do not change the major mode in the output buffer, -so that it is still Help mode at the end of their execution, then -@code{with-output-to-temp-buffer} makes this buffer read-only at the -end, and also scans it for function and variable names to make them -into clickable cross-references. @xref{Docstring hyperlinks, , Tips -for Documentation Strings}, in particular the item on hyperlinks in +@defmac with-output-to-temp-buffer buffer-name body@dots{} +This function executes the forms in @var{body} while arranging to insert +any output they print into the buffer named @var{buffer-name}, which is +first created if necessary, and put into Help mode. (See the similar +form @code{with-temp-buffer-window} below.) Finally, the buffer is +displayed in some window, but that window is not selected. + +If the forms in @var{body} do not change the major mode in the output +buffer, so that it is still Help mode at the end of their execution, +then @code{with-output-to-temp-buffer} makes this buffer read-only at +the end, and also scans it for function and variable names to make them +into clickable cross-references. @xref{Docstring hyperlinks, , Tips for +Documentation Strings}, in particular the item on hyperlinks in documentation strings, for more details. -The string @var{buffer-name} specifies the temporary buffer, which -need not already exist. The argument must be a string, not a buffer. -The buffer is erased initially (with no questions asked), and it is -marked as unmodified after @code{with-output-to-temp-buffer} exits. +The string @var{buffer-name} specifies the temporary buffer, which need +not already exist. The argument must be a string, not a buffer. The +buffer is erased initially (with no questions asked), and it is marked +as unmodified after @code{with-output-to-temp-buffer} exits. @code{with-output-to-temp-buffer} binds @code{standard-output} to the -temporary buffer, then it evaluates the forms in @var{forms}. Output -using the Lisp output functions within @var{forms} goes by default to +temporary buffer, then it evaluates the forms in @var{body}. Output +using the Lisp output functions within @var{body} goes by default to that buffer (but screen display and messages in the echo area, although they are ``output'' in the general sense of the word, are not affected). @xref{Output Functions}. @@ -1104,7 +1130,7 @@ they are ``output'' in the general sense of the word, are not affected). Several hooks are available for customizing the behavior of this construct; they are listed below. -The value of the last form in @var{forms} is returned. +The value of the last form in @var{body} is returned. @example @group @@ -1120,6 +1146,7 @@ The value of the last form in @var{forms} is returned. @result{} #<buffer foo> ---------- Buffer: foo ---------- + 20 #<buffer foo> @@ -1153,29 +1180,28 @@ displaying the temporary buffer. When the hook runs, the temporary buffer is current, and the window it was displayed in is selected. @end defvar -@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{} -This macro is similar to @code{with-output-to-temp-buffer}. -Like that construct, it executes @var{forms} while arranging to insert -any output they print into the buffer named @var{buffer-or-name}. -Finally, the buffer is displayed in some window, but not selected. -Unlike @code{with-output-to-temp-buffer}, this does not switch to Help -mode. +@defmac with-temp-buffer-window buffer-or-name action quit-function body@dots{} +This macro is similar to @code{with-output-to-temp-buffer}. Like that +construct, it executes @var{body} while arranging to insert any output +it prints into the buffer named @var{buffer-or-name} and displays that +buffer in some window. Unlike @code{with-output-to-temp-buffer}, +however, it does not automatically switch that buffer to Help mode. -The argument @var{buffer-or-name} specifies the temporary buffer. -It can be either a buffer, which must already exist, or a string, -in which case a buffer of that name is created if necessary. -The buffer is marked as unmodified and read-only when -@code{with-temp-buffer-window} exits. +The argument @var{buffer-or-name} specifies the temporary buffer. It +can be either a buffer, which must already exist, or a string, in which +case a buffer of that name is created, if necessary. The buffer is +marked as unmodified and read-only when @code{with-temp-buffer-window} +exits. This macro does not call @code{temp-buffer-show-function}. Rather, it -passes the @var{action} argument to @code{display-buffer} in order to -display the buffer. +passes the @var{action} argument to @code{display-buffer} +(@pxref{Choosing Window}) in order to display the buffer. -The value of the last form in @var{forms} is returned, unless the -argument @var{quit-function} is specified. In that case, -it is called with two arguments: the window showing the buffer -and the result of @var{forms}. The final return value is then -whatever @var{quit-function} returns. +The value of the last form in @var{body} is returned, unless the +argument @var{quit-function} is specified. In that case, it is called +with two arguments: the window showing the buffer and the result of +@var{body}. The final return value is then whatever @var{quit-function} +returns. @vindex temp-buffer-window-setup-hook @vindex temp-buffer-window-show-hook @@ -1184,6 +1210,56 @@ and @code{temp-buffer-window-show-hook} in place of the analogous hooks run by @code{with-output-to-temp-buffer}. @end defmac +The two constructs described next are mostly identical to +@code{with-temp-buffer-window} but differ from it as specified: + +@defmac with-current-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-temp-buffer-window} but unlike that makes +the buffer specified by @var{buffer-or-name} current for running +@var{body}. +@end defmac + +@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-current-buffer-window} but unlike that +displays the buffer specified by @var{buffer-or-name} @emph{before} +running @var{body}. +@end defmac + +A window showing a temporary buffer can be fit to the size of that +buffer using the following mode: + +@defopt temp-buffer-resize-mode +When this minor mode is enabled, windows showing a temporary buffer are +automatically resized to fit their buffer's contents. + +A window is resized if and only if it has been specially created for the +buffer. In particular, windows that have shown another buffer before +are not resized. By default, this mode uses @code{fit-window-to-buffer} +(@pxref{Resizing Windows}) for resizing. You can specify a different +function by customizing the options @code{temp-buffer-max-height} and +@code{temp-buffer-max-width} below. +@end defopt + +@defopt temp-buffer-max-height +This option specifies the maximum height (in lines) of a window +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the height +for such a buffer. It gets one argument, the buffer, and should return +a positive integer. At the time the function is called, the window to +be resized is selected. +@end defopt + +@defopt temp-buffer-max-width +This option specifies the maximum width of a window (in columns) +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the width for +such a buffer. It gets one argument, the buffer, and should return a +positive integer. At the time the function is called, the window to be +resized is selected. +@end defopt + +The following function uses the current buffer for temporal display: + @defun momentary-string-display string position &optional char message This function momentarily displays @var{string} in the current buffer at @var{position}. It has no effect on the undo list or on the buffer's @@ -1252,6 +1328,7 @@ beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay. @cindex scalability of overlays +@cindex overlays, scalability The visual effect of an overlay is the same as of the corresponding text property (@pxref{Text Properties}). However, due to a different implementation, overlays generally don't scale well (many operations @@ -1274,6 +1351,8 @@ inside the overlay or outside, and likewise for the end of the overlay. @node Managing Overlays @subsection Managing Overlays +@cindex managing overlays +@cindex overlays, managing This section describes the functions to create, delete and move overlays, and to examine their contents. Overlay changes are not @@ -1291,6 +1370,15 @@ and @var{end} must specify buffer positions; they may be integers or markers. If @var{buffer} is omitted, the overlay is created in the current buffer. +@cindex empty overlay +@cindex overlay, empty +An overlay whose @var{start} and @var{end} specify the same buffer +position is known as @dfn{empty}. A non-empty overlay can become +empty if the text between its @var{start} and @var{end} is deleted. +When that happens, the overlay is by default not deleted, but you can +cause it to be deleted by giving it the @samp{evaporate} property +(@pxref{Overlay Properties, evaporate property}). + The arguments @var{front-advance} and @var{rear-advance} specify the marker insertion type for the start of the overlay and for the end of the overlay, respectively. @xref{Marker Insertion Types}. If they @@ -1341,7 +1429,7 @@ The return value is @var{overlay}. This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be -``lost''. +lost. @end defun @defun remove-overlays &optional start end name value @@ -1418,7 +1506,7 @@ foo @end example Emacs stores the overlays of each buffer in two lists, divided -around an arbitrary ``center position''. One list extends backwards +around an arbitrary center position. One list extends backwards through the buffer from that center position, and the other extends forwards from that center position. The center position can be anywhere in the buffer. @@ -1434,6 +1522,7 @@ faster if you do @code{(overlay-recenter (point-max))} first. @node Overlay Properties @subsection Overlay Properties +@cindex overlay properties Overlay properties are like text properties in that the properties that alter how a character is displayed can come from either source. But in @@ -1450,8 +1539,10 @@ the buffer's undo list. Since more than one overlay can specify a property value for the same character, Emacs lets you specify a priority value of each -overlay. You should not make assumptions about which overlay will -prevail when there is a conflict and they have the same priority. +overlay. In case two overlays have the same priority value, and one +is nested in the other, then the inner one will have priority over the +outer one. If neither is nested in the other then you should not make +assumptions about which overlay will prevail. These functions read and set the properties of an overlay: @@ -1482,9 +1573,9 @@ of them: @table @code @item priority @kindex priority @r{(overlay property)} -This property's value (which should be a non-negative integer number) -determines the priority of the overlay. No priority, or @code{nil}, -means zero. +This property's value determines the priority of the overlay. +If you want to specify a priority value, use either @code{nil} +(or zero), or a positive integer. Any other value has undefined behavior. The priority matters when two or more overlays cover the same character and both specify the same property; the one whose @@ -1494,9 +1585,13 @@ completely override the other value; instead, its face attributes override the face attributes of the lower priority @code{face} property. -Currently, all overlays take priority over text properties. Please -avoid using negative priority values, as we have not yet decided just -what they should mean. +Currently, all overlays take priority over text properties. + +Note that Emacs sometimes uses non-numeric priority values for some of +its internal overlays, so do not try to do arithmetic on the +priority of an overlay (unless it is one that you created). If you +need to put overlays in priority order, use the @var{sorted} argument +of @code{overlays-at}. @xref{Finding Overlays}. @item window @kindex window @r{(overlay property)} @@ -1653,8 +1748,11 @@ line at display-time. @xref{Truncation}. @kindex evaporate @r{(overlay property)} If this property is non-@code{nil}, the overlay is deleted automatically if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay a non-@code{nil} @code{evaporate} property, that deletes -it immediately. +an empty overlay (@pxref{Managing Overlays, empty overlay}) a +non-@code{nil} @code{evaporate} property, that deletes it immediately. +Note that, unless an overlay has this property, it will not be deleted +when the text between its starting and ending positions is deleted +from the buffer. @item keymap @cindex keymap of character (and overlays) @@ -1680,12 +1778,15 @@ Properties}. @node Finding Overlays @subsection Searching for Overlays +@cindex searching for overlays +@cindex overlays, searching for -@defun overlays-at pos -This function returns a list of all the overlays that cover the -character at position @var{pos} in the current buffer. The list is in -no particular order. An overlay contains position @var{pos} if it -begins at or before @var{pos}, and ends after @var{pos}. +@defun overlays-at pos &optional sorted +This function returns a list of all the overlays that cover the character at +position @var{pos} in the current buffer. If @var{sorted} is non-@code{nil}, +the list is in decreasing order of priority, otherwise it is in no particular +order. An overlay contains position @var{pos} if it begins at or before +@var{pos}, and ends after @var{pos}. To illustrate usage, here is a Lisp function that returns a list of the overlays that specify property @var{prop} for the character at point: @@ -1705,12 +1806,11 @@ overlays that specify property @var{prop} for the character at point: @defun overlays-in beg end This function returns a list of the overlays that overlap the region -@var{beg} through @var{end}. ``Overlap'' means that at least one -character is contained within the overlay and also contained within the -specified region; however, empty overlays are included in the result if -they are located at @var{beg}, strictly between @var{beg} and @var{end}, -or at @var{end} when @var{end} denotes the position at the end of the -buffer. +@var{beg} through @var{end}. An overlay overlaps with a region if it +contains one or more characters in the region; empty overlays +(@pxref{Managing Overlays, empty overlay}) overlap if they are at +@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} +when @var{end} denotes the position at the end of the buffer. @end defun @defun next-overlay-change pos @@ -1744,8 +1844,10 @@ changes. (point))) @end smallexample -@node Width -@section Width +@node Size of Displayed Text +@section Size of Displayed Text +@cindex size of text on display +@cindex character width on display Since not all characters have the same width, these functions let you check the width of a character. @xref{Primitive Indent}, and @@ -1788,9 +1890,9 @@ the beginning of the result if one multi-column character in @var{string} extends across the column @var{start-column}. If @var{ellipsis} is non-@code{nil}, it should be a string which will -replace the end of @var{str} (including any padding) if it extends -beyond @var{end-column}, unless the display width of @var{str} is -equal to or less than the display width of @var{ellipsis}. If +replace the end of @var{string} (including any padding) if it extends +beyond @var{width}, unless the display width of @var{string} is equal +to or less than the display width of @var{ellipsis}. If @var{ellipsis} is non-@code{nil} and not a string, it stands for @code{"..."}. @@ -1802,20 +1904,69 @@ equal to or less than the display width of @var{ellipsis}. If @end example @end defun +The following function returns the size in pixels of text as if it were +displayed in a given window. This function is used by +@code{fit-window-to-buffer} and @code{fit-frame-to-buffer} +(@pxref{Resizing Windows}) to make a window exactly as large as the text +it contains. + +@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line +This function returns the size of the text of @var{window}'s buffer in +pixels. @var{window} must be a live window and defaults to the selected +one. The return value is a cons of the maximum pixel-width of any text +line and the maximum pixel-height of all text lines. + +The optional argument @var{from}, if non-@code{nil}, specifies the first +text position to consider and defaults to the minimum accessible +position of the buffer. If @var{from} is @code{t}, it uses the minimum +accessible position that is not a newline character. The optional +argument @var{to}, if non-@code{nil}, specifies the last text position +to consider and defaults to the maximum accessible position of the +buffer. If @var{to} is @code{t}, it uses the maximum accessible +position that is not a newline character. + +The optional argument @var{x-limit}, if non-@code{nil}, specifies the +maximum pixel-width that can be returned. @var{x-limit} @code{nil} or +omitted, means to use the pixel-width of @var{window}'s body +(@pxref{Window Sizes}); this is useful when the caller does not intend +to change the width of @var{window}. Otherwise, the caller should +specify here the maximum width @var{window}'s body may assume. Text +whose x-coordinate is beyond @var{x-limit} is ignored. Since +calculating the width of long lines can take some time, it's always a +good idea to make this argument as small as needed; in particular, if +the buffer might contain long lines that will be truncated anyway. + +The optional argument @var{y-limit}, if non-@code{nil}, specifies the +maximum pixel-height that can be returned. Text lines whose +y-coordinate is beyond @var{y-limit} are ignored. Since calculating the +pixel-height of a large buffer can take some time, it makes sense to +specify this argument; in particular, if the caller does not know the +size of the buffer. + +The optional argument @var{mode-and-header-line} @code{nil} or omitted +means to not include the height of the mode- or header-line of +@var{window} in the return value. If it is either the symbol +@code{mode-line} or @code{header-line}, include only the height of that +line, if present, in the return value. If it is @code{t}, include the +height of both, if present, in the return value. +@end defun + + @node Line Height @section Line Height @cindex line height +@cindex height of a line The total height of each display line consists of the height of the contents of the line, plus optional additional vertical line spacing above or below the display line. - The height of the line contents is the maximum height of any -character or image on that display line, including the final newline -if there is one. (A display line that is continued doesn't include a -final newline.) That is the default line height, if you do nothing to -specify a greater height. (In the most common case, this equals the -height of the default frame font.) + The height of the line contents is the maximum height of any character +or image on that display line, including the final newline if there is +one. (A display line that is continued doesn't include a final +newline.) That is the default line height, if you do nothing to specify +a greater height. (In the most common case, this equals the height of +the corresponding frame's default font, see @ref{Frame Font}.) There are several ways to explicitly specify a larger line height, either by specifying an absolute height for the display line, or by @@ -1839,6 +1990,7 @@ First Emacs uses @var{height} as a height spec to control extra space to bring the total line height up to @var{total}. In this case, the other ways to specify the line spacing are ignored. +@cindex height spec Any other kind of property value is a height spec, which translates into a number---the specified line height. There are several ways to write a height spec; here's how each of them translates into a number: @@ -1873,14 +2025,14 @@ parts of Emacs text. lines in a frame, using the @code{line-spacing} frame parameter (@pxref{Layout Parameters}). However, if the default value of @code{line-spacing} is non-@code{nil}, it overrides the -frame's @code{line-spacing} parameter. An integer value specifies the -number of pixels put below lines. A floating point number specifies +frame's @code{line-spacing} parameter. An integer specifies the +number of pixels put below lines. A floating-point number specifies the spacing relative to the frame's default line height. @vindex line-spacing You can specify the line spacing for all lines in a buffer via the -buffer-local @code{line-spacing} variable. An integer value specifies -the number of pixels put below lines. A floating point number +buffer-local @code{line-spacing} variable. An integer specifies +the number of pixels put below lines. A floating-point number specifies the spacing relative to the default frame line height. This overrides line spacings specified for the frame. @@ -1994,11 +2146,11 @@ Relative character width. This should be one of the symbols The height of the font. In the simplest case, this is an integer in units of 1/10 point. -The value can also be a floating point number or a function, which +The value can also be floating point or a function, which specifies the height relative to an @dfn{underlying face} -(@pxref{Displaying Faces}). If the value is a floating point number, -that specifies the amount by which to scale the height of the -underlying face. If the value is a function, that function is called +(@pxref{Displaying Faces}). A floating-point value +specifies the amount by which to scale the height of the +underlying face. A function value is called with one argument, the height of the underlying face, and returns the height of the new face. If the function is passed an integer argument, it must return an integer. @@ -2028,6 +2180,15 @@ name, or a hexadecimal color specification. @xref{Color Names}. On black-and-white displays, certain shades of gray are implemented by stipple patterns. +@item :distant-foreground +Alternative foreground color, a string. This is like @code{:foreground} +but the color is only used as a foreground when the background color is +near to the foreground that would have been used. This is useful for +example when marking text (i.e., the region face). If the text has a foreground +that is visible with the region face, that foreground is used. +If the foreground is near the region face background, +@code{:distant-foreground} is used instead so the text is readable. + @item :background Background color, a string. The value can be a system-defined color name, or a hexadecimal color specification. @xref{Color Names}. @@ -2068,6 +2229,8 @@ value @code{nil} means do not overline. Whether or not characters should be strike-through, and in what color. The value is used like that of @code{:overline}. +@cindex 2D box +@cindex 3D box @item :box Whether or not a box should be drawn around characters, its color, the width of the box lines, and 3D appearance. Here are the possible @@ -2141,6 +2304,7 @@ font matching those wildcards. Specifying this attribute also changes the values of the @code{:family}, @code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and @code{:slant} attributes. +@cindex inheritance, for faces @item :inherit The name of a face from which to inherit attributes, or a list of face names. Attributes from inherited faces are merged into the face like @@ -2174,6 +2338,7 @@ suitable for use with @code{:stipple} (see above). It returns @node Defining Faces @subsection Defining Faces +@cindex defining faces @cindex face spec The usual way to define a face is through the @code{defface} macro. @@ -2330,20 +2495,25 @@ This function applies @var{spec} as a face spec for @code{face}. @var{spec} should be a face spec, as described in the above documentation for @code{defface}. +This function also defines @var{face} as a valid face name if it is +not already one, and (re)calculates its attributes on existing frames. + @cindex override spec @r{(for a face)} The argument @var{spec-type} determines which spec to set. If it is @code{nil} or @code{face-override-spec}, this function sets the @dfn{override spec}, which overrides over all other face specs on -@var{face}. If it is @code{face-defface-spec}, this function sets the -default face spec (the same one set by @code{defface}). If it is -@code{reset}, this function clears out all customization specs and -override specs from @var{face} (in this case, the value of @var{spec} -is ignored). Any other value of @var{spec-type} is reserved for -internal use. +@var{face}. If it is @code{customized-face} or @code{saved-face}, +this function sets the customized spec or the saved custom spec. If +it is @code{face-defface-spec}, this function sets the default face +spec (the same one set by @code{defface}). If it is @code{reset}, +this function clears out all customization specs and override specs +from @var{face} (in this case, the value of @var{spec} is ignored). +Any other value of @var{spec-type} is reserved for internal use. @end defun @node Attribute Functions @subsection Face Attribute Functions +@cindex face attributes, access and modification This section describes functions for directly accessing and modifying the attributes of a named face. @@ -2381,6 +2551,7 @@ For example, @end example @end defun +@c FIXME: Add an index for "relative face attribute", maybe here? --xfq @defun face-attribute-relative-p attribute value This function returns non-@code{nil} if @var{value}, when used as the value of the face attribute @var{attribute}, is relative. This means @@ -2544,6 +2715,8 @@ a non-@code{nil} @code{:inverse-video} attribute. @node Displaying Faces @subsection Displaying Faces +@cindex displaying faces +@cindex face merging When Emacs displays a given piece of text, the visual appearance of the text may be determined by faces drawn from different sources. If @@ -2565,8 +2738,8 @@ Manual}. @item If the text lies within an overlay with a non-@code{nil} @code{face} property, Emacs applies the face(s) specified by that property. If -the overlay has a @code{mouse-face} property and the mouse is ``near -enough'' to the overlay, Emacs applies the face or face attributes +the overlay has a @code{mouse-face} property and the mouse is near +enough to the overlay, Emacs applies the face or face attributes specified by the @code{mouse-face} property instead. @xref{Overlay Properties}. @@ -2599,6 +2772,7 @@ at the next level of face merging. @node Face Remapping @subsection Face Remapping +@cindex face remapping The variable @code{face-remapping-alist} is used for buffer-local or global changes in the appearance of a face. For instance, it is used @@ -2639,12 +2813,14 @@ then the new definition of the @code{mode-line} face inherits from the @code{mode-line} face. @end defvar +@cindex relative remapping, faces +@cindex base remapping, faces The following functions implement a higher-level interface to @code{face-remapping-alist}. Most Lisp code should use these functions instead of setting @code{face-remapping-alist} directly, to avoid trampling on remappings applied elsewhere. These functions are intended for buffer-local remappings, so they all make -@code{face-remapping-alist} buffer-local as a side-effect. They manage +@code{face-remapping-alist} buffer-local as a side-effect. They manage @code{face-remapping-alist} entries of the form @example @@ -2664,21 +2840,21 @@ and @code{face-remap-reset-base} functions; it is intended for major modes to remap faces in the buffers they control. @defun face-remap-add-relative face &rest specs -This functions adds the face spec in @var{specs} as relative +This function adds the face spec in @var{specs} as relative remappings for face @var{face} in the current buffer. The remaining arguments, @var{specs}, should form either a list of face names, or a property list of attribute/value pairs. -The return value is a Lisp object that serves as a ``cookie''; you can +The return value is a Lisp object that serves as a cookie; you can pass this object as an argument to @code{face-remap-remove-relative} if you need to remove the remapping later. @example -;; Remap the `escape-glyph' face into a combination -;; of the `highlight' and `italic' faces: +;; Remap the 'escape-glyph' face into a combination +;; of the 'highlight' and 'italic' faces: (face-remap-add-relative 'escape-glyph 'highlight 'italic) -;; Increase the size of the `default' face by 50%: +;; Increase the size of the 'default' face by 50%: (face-remap-add-relative 'default :height 1.5) @end example @end defun @@ -2794,12 +2970,13 @@ usually assign faces to around 400 to 600 characters at each call. @node Basic Faces @subsection Basic Faces +@cindex basic faces If your Emacs Lisp program needs to assign some faces to text, it is often a good idea to use certain existing faces or inherit from them, rather than defining entirely new faces. This way, if other users have customized the basic faces to give Emacs a certain look, your -program will ``fit in'' without additional customization. +program will fit in without additional customization. Some of the basic faces defined in Emacs are listed below. In addition to these, you might want to make use of the Font Lock faces @@ -2824,14 +3001,14 @@ has a bold @code{:weight} attribute), with all other attributes unspecified (and so given by @code{default}). @item shadow -For ``dimmed out'' text. For example, it is used for the ignored +For dimmed-out text. For example, it is used for the ignored part of a filename in the minibuffer (@pxref{Minibuffer File,, Minibuffers for File Names, emacs, The GNU Emacs Manual}). @item link @itemx link-visited For clickable text buttons that send the user to a different -buffer or ``location''. +buffer or location. @item highlight For stretches of text that should temporarily stand out. For example, @@ -2850,6 +3027,8 @@ these are used for messages in @file{*Compilation*} buffers. @node Font Selection @subsection Font Selection +@cindex font selection +@cindex selecting a font Before Emacs can draw a character on a graphical display, it must select a @dfn{font} for that character@footnote{In this context, the @@ -2920,6 +3099,7 @@ other registries given in @var{alternate-registries}, one by one, until it finds a registry that does exist. @end defopt +@cindex scalable fonts Emacs can make use of scalable fonts, but by default it does not use them. @@ -2933,11 +3113,11 @@ scalable font is enabled for use if its name matches any regular expression in the list. For example, @example -(setq scalable-fonts-allowed '("muleindian-2$")) +(setq scalable-fonts-allowed '("iso10646-1$")) @end example @noindent -allows the use of scalable fonts with registry @code{muleindian-2}. +allows the use of scalable fonts with registry @code{iso10646-1}. @end defopt @defvar face-font-rescale-alist @@ -2957,6 +3137,8 @@ nominal heights and widths would suggest. @node Font Lookup @subsection Looking Up Fonts +@cindex font lookup +@cindex looking up fonts @defun x-list-fonts name &optional reference-face frame maximum width This function returns a list of available font names that match @@ -3014,12 +3196,13 @@ encoding of the font. @node Fontsets @subsection Fontsets +@cindex fontset A @dfn{fontset} is a list of fonts, each assigned to a range of character codes. An individual font cannot display the whole range of characters that Emacs supports, but a fontset can. Fontsets have names, just as fonts do, and you can use a fontset name in place of a font name -when you specify the ``font'' for a frame or a face. Here is +when you specify the font for a frame or a face. Here is information about defining a fontset under Lisp program control. @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror @@ -3047,7 +3230,7 @@ function does nothing. If optional argument @var{style-variant-p} is non-@code{nil}, that says to create bold, italic and bold-italic variants of the fontset as well. These variant fontsets do not have a short name, only a long one, which -is made by altering @var{fontpattern} to indicate the bold or italic +is made by altering @var{fontpattern} to indicate the bold and/or italic status. The specification string also says which fonts to use in the fontset. @@ -3110,7 +3293,7 @@ field. @defun set-fontset-font name character font-spec &optional frame add This function modifies the existing fontset @var{name} to use the font -matching with @var{font-spec} for the character @var{character}. +matching with @var{font-spec} for the specified @var{character}. If @var{name} is @code{nil}, this function modifies the fontset of the selected frame or that of @var{frame} if @var{frame} is not @@ -3119,10 +3302,10 @@ selected frame or that of @var{frame} if @var{frame} is not If @var{name} is @code{t}, this function modifies the default fontset, whose short name is @samp{fontset-default}. -@var{character} may be a cons; @code{(@var{from} . @var{to})}, where -@var{from} and @var{to} are character codepoints. In that case, use -@var{font-spec} for all characters in the range @var{from} and @var{to} -(inclusive). +In addition to specifying a single codepoint, @var{character} may be a +cons @code{(@var{from} . @var{to})}, where @var{from} and @var{to} are +character codepoints. In that case, use @var{font-spec} for all the +characters in the range @var{from} and @var{to} (inclusive). @var{character} may be a charset. In that case, use @var{font-spec} for all character in the charsets. @@ -3130,6 +3313,9 @@ fontset, whose short name is @samp{fontset-default}. @var{character} may be a script name. In that case, use @var{font-spec} for all character in the charsets. +@var{font-spec} may be a font-spec object created by the function +@code{font-spec} (@pxref{Low-Level Font}). + @var{font-spec} may be a cons; @code{(@var{family} . @var{registry})}, where @var{family} is a family name of a font (possibly including a foundry name at the head), @var{registry} is a registry name of a font @@ -3137,6 +3323,12 @@ foundry name at the head), @var{registry} is a registry name of a font @var{font-spec} may be a font name string. +@var{font-spec} may be @code{nil}, which explicitly specifies that +there's no font for the specified @var{character}. This is useful, +for example, to avoid expensive system-wide search for fonts for +characters that have no glyphs, like those from the Unicode Private +Use Area (PUA). + The optional argument @var{add}, if non-@code{nil}, specifies how to add @var{font-spec} to the font specifications previously set. If it is @code{prepend}, @var{font-spec} is prepended. If it is @@ -3164,6 +3356,7 @@ does that, this function's value may not be accurate. @node Low-Level Font @subsection Low-Level Font Representation +@cindex font property Normally, it is not necessary to manipulate fonts directly. In case you need to do so, this section explains how. @@ -3182,6 +3375,7 @@ should be one of @code{font-object}, @code{font-spec}, or @code{font-entity}. @end defun +@cindex font object A font object is a Lisp object that represents a font that Emacs has @dfn{opened}. Font objects cannot be modified in Lisp, but they can be inspected. @@ -3195,6 +3389,7 @@ otherwise, @var{string} should be a string, and @var{position} specifies a position in that string. @end defun +@cindex font spec A font spec is a Lisp object that contains a set of specifications that can be used to find a font. More than one font may match the specifications in a font spec. @@ -3219,12 +3414,13 @@ These have the same meanings as the face attributes of the same name. @item :size The font size---either a non-negative integer that specifies the pixel -size, or a floating point number that specifies the point size. +size, or a floating-point number that specifies the point size. @item :adstyle Additional typographic style information for the font, such as @samp{sans}. The value should be a string or a symbol. +@cindex font registry @item :registry The charset registry and encoding of the font, such as @samp{iso8859-1}. The value should be a string or a symbol. @@ -3232,11 +3428,21 @@ The charset registry and encoding of the font, such as @item :script The script that the font must support (a symbol). +@item :lang +The language that the font should support. The value should be a +symbol whose name is a two-letter ISO-639 language name. On X, the +value is matched against the ``Additional Style'' field of the XLFD +name of a font, if it is non-empty. On MS-Windows, fonts matching the +spec are required to support codepages needed for the language. +Currently, only a small set of CJK languages is supported with this +property: @samp{ja}, @samp{ko}, and @samp{zh}. + @item :otf +@cindex OpenType font The font must be an OpenType font that supports these OpenType -features, provided Emacs is compiled with support for @samp{libotf} (a -library for performing complex text layout in certain scripts). The -value must be a list of the form +features, provided Emacs is compiled with a library, such as +@samp{libotf} on GNU/Linux, that supports complex text layout for +scripts which need that. The value must be a list of the form @smallexample @code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})} @@ -3259,6 +3465,7 @@ Set the font property @var{property} in the font-spec @var{font-spec} to @var{value}. @end defun +@cindex font entity A font entity is a reference to a font that need not be open. Its properties are intermediate between a font object and a font spec: like a font object, and unlike a font spec, it refers to a single, @@ -3283,13 +3490,13 @@ frame on which the fonts are to be displayed. The optional argument maximum length of the returned list. The optional argument @var{prefer}, if non-@code{nil}, should be another font spec, which is used to control the order of the returned list; the returned font -entities are sorted in order of decreasing ``closeness'' to that font +entities are sorted in order of decreasing closeness to that font spec. @end defun If you call @code{set-face-attribute} and pass a font spec, font entity, or font name string as the value of the @code{:font} -attribute, Emacs opens the best ``matching'' font that is available +attribute, Emacs opens the best matching font that is available for display. It then stores the corresponding font object as the actual value of the @code{:font} attribute for that face. @@ -3334,6 +3541,124 @@ If the optional argument @var{fold-wildcards} is non-@code{nil}, consecutive wildcards in the XLFD are folded into one. @end defun +The following two functions return important information about a font. + +@defun font-info name &optional frame +This function returns information about a font specified by its +@var{name}, a string, as it is used on @var{frame}. If @var{frame} is +omitted or @code{nil}, it defaults to the selected frame. + +The value returned by the function is a vector of the form +@code{[@var{opened-name} @var{full-name} @var{size} @var{height} +@var{baseline-offset} @var{relative-compose} @var{default-ascent} +@var{max-width} @var{ascent} @var{descent} @var{space-width} +@var{average-width} @var{filename} @var{capability}]}. Here's the +description of each components of this vector: + +@table @var +@item opened-name +The name used to open the font, a string. + +@item full-name +The full name of the font, a string. + +@item size +The pixel size of the font. + +@item height +The height of the font in pixels. + +@item baseline-offset +The offset in pixels from the @acronym{ASCII} baseline, positive +upward. + +@item relative-compose +@itemx default-ascent +Numbers controlling how to compose characters. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +should be equal to the value of @var{height} above. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + +@defun query-font font-object +This function returns information about a @var{font-object}. (This is +in contrast to @code{font-info}, which takes the font name, a string, +as its argument.) + +The value returned by the function is a vector of the form +@code{[@var{name} @var{filename} @var{pixel-size} @var{max-width} +@var{ascent} @var{descent} @var{space-width} @var{average-width} +@var{capability}]}. Here's the description of each components of this +vector: + +@table @var +@item name +The font name, a string. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item pixel-size +The pixel size of the font used to open the font. + +@item max-width +The maximum advance width of the font. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +gives the font height. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + @node Fringes @section Fringes @cindex fringes @@ -3417,6 +3742,7 @@ etc. @defopt indicate-empty-lines @cindex fringes, and empty line indication +@cindex empty lines, indicating When this is non-@code{nil}, Emacs displays a special glyph in the fringe of each empty line at the end of the buffer, on graphical displays. @xref{Fringes}. This variable is automatically @@ -3424,6 +3750,7 @@ buffer-local in every buffer. @end defopt @defopt indicate-buffer-boundaries +@cindex buffer boundaries, indicating This buffer-local variable controls how the buffer boundaries and window scrolling are indicated in the window fringes. @@ -3552,6 +3879,8 @@ See the next subsection for details. @xref{Fringe Bitmaps}. @end ifnottex +@c FIXME: I can't find the fringes-indicator-alist variable. Maybe +@c it should be fringe-indicator-alist or fringe-cursor-alist? --xfq When @code{fringe-cursor-alist} has a buffer-local value, and there is no bitmap defined for a cursor type, the corresponding value from the default value of @code{fringes-indicator-alist} is used. @@ -3643,6 +3972,7 @@ If @var{pos} is @code{nil}, that stands for the value of point in @node Customizing Bitmaps @subsection Customizing Fringe Bitmaps +@cindex fringe bitmaps, customizing @defun define-fringe-bitmap bitmap bits &optional height width align This function defines the symbol @var{bitmap} as a new fringe bitmap, @@ -3745,95 +4075,227 @@ arrow position. If either property is not set, the default @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator is used. + @node Scroll Bars @section Scroll Bars @cindex scroll bars Normally the frame parameter @code{vertical-scroll-bars} controls -whether the windows in the frame have vertical scroll bars, and -whether they are on the left or right. The frame parameter -@code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Layout Parameters}. +whether the windows in the frame have vertical scroll bars, and whether +they are on the left or right. The frame parameter +@code{scroll-bar-width} specifies how wide they are (@code{nil} meaning +the default). + + The frame parameter @code{horizontal-scroll-bars} controls whether +the windows in the frame have horizontal scroll bars. The frame +parameter @code{scroll-bar-height} specifies how high they are +(@code{nil} meaning the default). @xref{Layout Parameters}. + +@vindex horizontal-scroll-bars-available-p + Horizontal scroll bars are not available on all platforms. The +function @code{horizontal-scroll-bars-available-p} which takes no +argument returns non-@code{nil} if they are available on your system. + + The following three functions take as argument a live frame which +defaults to the selected one. @defun frame-current-scroll-bars &optional frame -This function reports the scroll bar type settings for frame -@var{frame}. The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}, where -@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} -(which means no scroll bar.) @var{horizontal-type} is meant to -specify the horizontal scroll bar type, but since they are not -implemented, it is always @code{nil}. -@end defun - -@vindex vertical-scroll-bar - You can enable or disable scroll bars for a particular buffer, -by setting the variable @code{vertical-scroll-bar}. This variable -automatically becomes buffer-local when set. The possible values are -@code{left}, @code{right}, @code{t}, which means to use the -frame's default, and @code{nil} for no scroll bar. +This function reports the scroll bar types for frame @var{frame}. The +value is a cons cell @code{(@var{vertical-type} .@: +@var{horizontal-type})}, where @var{vertical-type} is either +@code{left}, @code{right}, or @code{nil} (which means no vertical scroll +bar.) @var{horizontal-type} is either @code{bottom} or @code{nil} +(which means no horizontal scroll bar). +@end defun + +@defun frame-scroll-bar-width &optional Lisp_Object &optional frame +This function returns the width of vertical scroll bars of @var{frame} +in pixels. +@end defun - You can also control this for individual windows. Call the function -@code{set-window-scroll-bars} to specify what to do for a specific window: +@defun frame-scroll-bar-height &optional Lisp_Object &optional frame +This function returns the height of horizontal scroll bars of +@var{frame} in pixels. +@end defun -@defun set-window-scroll-bars window width &optional vertical-type horizontal-type -This function sets the width and type of scroll bars for window -@var{window}. +You can override the frame specific settings for individual windows by +using the following function: -@var{width} specifies the scroll bar width in pixels (@code{nil} means -use the width specified for the frame). @var{vertical-type} specifies -whether to have a vertical scroll bar and, if so, where. The possible -values are @code{left}, @code{right} and @code{nil}, just like the -values of the @code{vertical-scroll-bars} frame parameter. +@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type +This function sets the width and/or height and the types of scroll bars +for window @var{window}. -The argument @var{horizontal-type} is meant to specify whether and -where to have horizontal scroll bars, but since they are not -implemented, it has no effect. If @var{window} is @code{nil}, the -selected window is used. +@var{width} specifies the width of the vertical scroll bar in pixels +(@code{nil} means use the width specified for the frame). +@var{vertical-type} specifies whether to have a vertical scroll bar and, +if so, where. The possible values are @code{left}, @code{right}, +@code{t}, which means to use the frame's default, and @code{nil} for no +vertical scroll bar. + +@var{height} specifies the height of the horizontal scroll bar in pixels +(@code{nil} means use the height specified for the frame). +@var{horizontal-type} specifies whether to have a horizontal scroll bar. +The possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no horizontal scroll bar. + +If @var{window} is @code{nil}, the selected window is used. @end defun +The following four functions take as argument a live window which +defaults to the selected one. + @defun window-scroll-bars &optional window -Report the width and type of scroll bars specified for @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a list of the form @code{(@var{width} -@var{cols} @var{vertical-type} @var{horizontal-type})}. The value -@var{width} is the value that was specified for the width (which may -be @code{nil}); @var{cols} is the number of columns that the scroll -bar actually occupies. +This function returns a list of the form @code{(@var{width} +@var{columns} @var{vertical-type} @var{height} @var{lines} +@var{horizontal-type})}. + +The value @var{width} is the value that was specified for the width of +the vertical scroll bar (which may be @code{nil}); @var{columns} is the +(possibly rounded) number of columns that the vertical scroll bar +actually occupies. + +The value @var{height} is the value that was specified for the height of +the horizontal scroll bar (which may be @code{nil}); @var{lines} is the +(possibly rounded) number of lines that the horizontally scroll bar +actually occupies. +@end defun + +@defun window-current-scroll-bars &optional window +This function reports the scroll bar type for window @var{window}. The +value is a cons cell @code{(@var{vertical-type} .@: +@var{horizontal-type})}. Unlike @code{window-scroll-bars}, this reports +the scroll bar type actually used, once frame defaults and +@code{scroll-bar-mode} are taken into account. +@end defun -@var{horizontal-type} is not actually meaningful. +@defun window-scroll-bar-width &optional window +This function returns the width in pixels of @var{window}'s vertical +scrollbar. +@end defun + +@defun window-scroll-bar-height &optional window +This function returns the height in pixels of @var{window}'s horizontal +scrollbar. @end defun If you don't specify these values for a window with @code{set-window-scroll-bars}, the buffer-local variables -@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being -displayed control the window's vertical scroll bars. The function +@code{vertical-scroll-bar}, @code{horizontal-scroll-bar}, +@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being +displayed control the window's scroll bars. The function @code{set-window-buffer} examines these variables. If you change them -in a buffer that is already visible in a window, you can make the -window take note of the new values by calling @code{set-window-buffer} +in a buffer that is already visible in a window, you can make the window +take note of the new values by calling @code{set-window-buffer} specifying the same buffer that is already displayed. +You can control the appearance of scroll bars for a particular buffer by +setting the following variables which automatically become buffer-local +when set. + +@defvar vertical-scroll-bar +This variable specifies the location of the vertical scroll bar. The +possible values are @code{left}, @code{right}, @code{t}, which means to +use the frame's default, and @code{nil} for no scroll bar. +@end defvar + +@defvar horizontal-scroll-bar +This variable specifies the location of the horizontal scroll bar. The +possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no scroll bar. +@end defvar + +@defvar scroll-bar-width +This variable specifies the width of the buffer's vertical scroll bars, +measured in pixels. A value of @code{nil} means to use the value +specified by the frame. +@end defvar + +@defvar scroll-bar-height +This variable specifies the height of the buffer's horizontal scroll +bar, measured in pixels. A value of @code{nil} means to use the value +specified by the frame. +@end defvar + +Finally you can toggle the display of scroll bars on all frames by +customizing the variables @code{scroll-bar-mode} and +@code{horizontal-scroll-bar-mode}. + @defopt scroll-bar-mode -This variable, always local in all buffers, controls whether and where -to put scroll bars in windows displaying the buffer. The possible values -are @code{nil} for no scroll bar, @code{left} to put a scroll bar on -the left, and @code{right} to put a scroll bar on the right. +This variable controls whether and where to put vertical scroll bars in +all frames. The possible values are @code{nil} for no scroll bars, +@code{left} to put scroll bars on the left and @code{right} to put +scroll bars on the right. @end defopt -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. +@defopt horizontal-scroll-bar-mode +This variable controls whether to display horizontal scroll bars on all +frames. +@end defopt + + +@node Window Dividers +@section Window Dividers +@cindex window dividers +@cindex right dividers +@cindex bottom dividers + +Window dividers are bars drawn between a frame's windows. A right +divider is drawn between a window and any adjacent windows on the right. +Its width (thickness) is specified by the frame parameter +@code{right-divider-width}. A bottom divider is drawn between a +window and adjacent windows on the bottom or the echo area. Its width +is specified by the frame parameter @code{bottom-divider-width}. In +either case, specifying a width of zero means to not draw such dividers. +@xref{Layout Parameters}. + + Technically, a right divider belongs to the window on its left, +which means that its width contributes to the total width of that +window. A bottom divider belongs to the window above it, which +means that its width contributes to the total height of that window. +@xref{Window Sizes}. When a window has both, a right and a bottom +divider, the bottom divider prevails. This means that a bottom +divider is drawn over the full total width of its window while the right +divider ends above the bottom divider. + + Dividers can be dragged with the mouse and are therefore useful for +adjusting the sizes of adjacent windows with the mouse. They also serve +to visually set apart adjacent windows when no scroll bars or mode lines +are present. The following three faces allow to customize the +appearance of dividers: + +@table @code +@item window-divider +When a divider is less than three pixels wide, it is drawn solidly with +the foreground of this face. For larger dividers this face is used for +the inner part only, excluding the first and last pixel. + +@item window-divider-first-pixel +This is the face used for drawing the first pixel of a divider that is +at least three pixels wide. To obtain a solid appearance, set this to +the same value used for the @code{window-divider} face. + +@item window-divider-last-pixel +This is the face used for drawing the last pixel of a divider that is at +least three pixels wide. To obtain a solid appearance, set this to the +same value used for the @code{window-divider} face. +@end table + +You can get the sizes of the dividers of a specific window with the +following two functions. + +@defun window-right-divider-width &optional window +Return the width (thickness) in pixels of @var{window}'s right divider. +@var{window} must be a live window and defaults to the selected one. +The return value is always zero for a rightmost window. +@end defun + +@defun window-bottom-divider-width &optional window +Return the width (thickness) in pixels of @var{window}'s bottom divider. +@var{window} must be a live window and defaults to the selected one. +The return value is zero for the minibuffer window or a bottommost +window on a minibuffer-less frame. @end defun -@defvar scroll-bar-width -This variable, always local in all buffers, specifies the width of the -buffer's scroll bars, measured in pixels. A value of @code{nil} means -to use the value specified by the frame. -@end defvar @node Display Property @section The @code{display} Property @@ -3866,6 +4328,7 @@ display specifications and what they mean. @node Replacing Specs @subsection Display Specs That Replace The Text +@cindex replacing display specs Some kinds of display specifications specify something to display instead of the text that has the property. These are called @@ -3878,8 +4341,8 @@ display specification, the first overrides the rest. Replacing display specifications make most other display specifications irrelevant, since those don't apply to the replacement. - For replacing display specifications, ``the text that has the -property'' means all the consecutive characters that have the same + For replacing display specifications, @dfn{the text that has the +property} means all the consecutive characters that have the same Lisp object as their @code{display} property; these characters are replaced as a single unit. If two characters have different Lisp objects as their @code{display} properties (i.e., objects which are @@ -3925,7 +4388,7 @@ can use in @var{props} to specify the weight of the space: @table @code @item :width @var{width} -If @var{width} is an integer or floating point number, it specifies +If @var{width} is a number, it specifies that the space width should be @var{width} times the normal character width. @var{width} can also be a @dfn{pixel width} specification (@pxref{Pixel Specification}). @@ -3933,8 +4396,10 @@ width. @var{width} can also be a @dfn{pixel width} specification @item :relative-width @var{factor} Specifies that the width of the stretch should be computed from the first character in the group of consecutive characters that have the -same @code{display} property. The space width is the width of that -character, multiplied by @var{factor}. +same @code{display} property. The space width is the pixel width of +that character, multiplied by @var{factor}. (On text-mode terminals, +the ``pixel width'' of a character is usually 1, but it could be more +for TABs and double-width CJK characters.) @item :align-to @var{hpos} Specifies that the space should be wide enough to reach @var{hpos}. @@ -3949,7 +4414,7 @@ also specify the height of the space, with these properties: @table @code @item :height @var{height} Specifies the height of the space. -If @var{height} is an integer or floating point number, it specifies +If @var{height} is a number, it specifies that the space height should be @var{height} times the normal character height. The @var{height} may also be a @dfn{pixel height} specification (@pxref{Pixel Specification}). @@ -4072,7 +4537,7 @@ This specification together with @code{image} specifies a @dfn{slice} (a partial area) of the image to display. The elements @var{y} and @var{x} specify the top left corner of the slice, within the image; @var{width} and @var{height} specify the width and height of the -slice. Integer values are numbers of pixels. A floating point number +slice. Integers are numbers of pixels. A floating-point number in the range 0.0--1.0 stands for that fraction of the width or height of the entire image. @@ -4104,7 +4569,8 @@ Here are the possibilities for @var{height}: @table @asis @item @code{(+ @var{n})} -This means to use a font that is @var{n} steps larger. A ``step'' is +@c FIXME: Add an index for "step"? --xfq +This means to use a font that is @var{n} steps larger. A @dfn{step} is defined by the set of available fonts---specifically, those that match what was otherwise specified for this text, in all attributes except height. Each size for which a suitable font is available counts as @@ -4141,7 +4607,7 @@ not affect the amount of raising or lowering, which is based on the faces used for the text. @end table -@c We put all the `@code{(when ...)}' on one line to encourage +@c We put all the '@code{(when ...)}' on one line to encourage @c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot @c was at eol; the info file ended up w/ two spaces rendered after it. You can make any display specification conditional. To do that, @@ -4189,13 +4655,15 @@ them a nonzero width. The usual way to do that is to set these variables: @defvar left-margin-width -This variable specifies the width of the left margin. -It is buffer-local in all buffers. +This variable specifies the width of the left margin, in character +cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers. +A value of @code{nil} means no left marginal area. @end defvar @defvar right-margin-width -This variable specifies the width of the right margin. -It is buffer-local in all buffers. +This variable specifies the width of the right margin, in character +cell units. It is buffer-local in all buffers. A value of @code{nil} +means no right marginal area. @end defvar Setting these variables does not immediately affect the window. These @@ -4206,15 +4674,18 @@ Thus, you can make changes take effect by calling You can also set the margin widths immediately. @defun set-window-margins window left &optional right -This function specifies the margin widths for window @var{window}. -The argument @var{left} controls the left margin and -@var{right} controls the right margin (default @code{0}). +This function specifies the margin widths for window @var{window}, in +character cell units. The argument @var{left} controls the left +margin, and @var{right} controls the right margin (default @code{0}). @end defun @defun window-margins &optional window -This function returns the left and right margins of @var{window} -as a cons cell of the form @code{(@var{left} . @var{right})}. -If @var{window} is @code{nil}, the selected window is used. +This function returns the width of the left and right margins of +@var{window} as a cons cell of the form @w{@code{(@var{left} +. @var{right})}}. If one of the two marginal areas does not exist, +its width is returned as @code{nil}; if neither of the two margins exist, +the function returns @code{(nil)}. If @var{window} is @code{nil}, the +selected window is used. @end defun @node Images @@ -4306,7 +4777,7 @@ functions to insert images into buffers. Each image descriptor has the form @code{(image . @var{props})}, where @var{props} is a property list of alternating keyword symbols -and values, including at least the pair @code{:type @var{TYPE}} which +and values, including at least the pair @code{:type @var{type}} that specifies the image type. The following is a list of properties that are meaningful for all @@ -4376,9 +4847,10 @@ which algorithm. Specifies the Laplace edge detection algorithm, which blurs out small differences in color while highlighting larger differences. People sometimes consider this useful for displaying the image for a -``disabled'' button. +disabled button. @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) +@cindex edge detection, images Specifies a general edge-detection algorithm. @var{matrix} must be either a nine-element list or a nine-element vector of numbers. A pixel at position @math{x/y} in the transformed image is computed from @@ -4440,7 +4912,7 @@ $$\pmatrix{ 2 & -1 & 0 \cr @end ifnottex @item disabled -Specifies transforming the image so that it looks ``disabled''. +Specifies transforming the image so that it looks disabled. @end table @item :mask @var{mask} @@ -4462,6 +4934,7 @@ This specifies the pointer shape when the mouse pointer is over this image. @xref{Pointer Shape}, for available pointer shapes. @item :map @var{map} +@cindex image maps This associates an image map of @dfn{hot spots} with this image. An image map is an alist where each element has the format @@ -4639,6 +5112,16 @@ should never be rendered using ImageMagick, regardless of the value of ImageMagick entirely. @end defopt +@defvar image-format-suffixes +This variable is an alist mapping image types to file name extensions. +Emacs uses this in conjunction with the @code{:format} image property +(see below) to give a hint to the ImageMagick library as to the type +of an image. Each element has the form @code{(@var{type} +@var{extension})}, where @var{type} is a symbol specifying an image +content-type, and @var{extension} is a string that specifies the +associated file name extension. +@end defvar + Images loaded with ImageMagick support the following additional image descriptor properties: @@ -4649,13 +5132,13 @@ color, which is used as the image's background color if the image supports transparency. If the value is @code{nil}, it defaults to the frame's background color. -@item :width, :height +@item :width @var{width}, :height @var{height} The @code{:width} and @code{:height} keywords are used for scaling the image. If only one of them is specified, the other one will be calculated so as to preserve the aspect ratio. If both are specified, aspect ratio may not be preserved. -@item :max-width, :max-height +@item :max-width @var{max-width}, :max-height @var{max-height} The @code{:max-width} and @code{:max-height} keywords are used for scaling if the size of the image of the image exceeds these values. If @code{:width} is set it will have precedence over @code{max-width}, @@ -4664,18 +5147,16 @@ and if @code{:height} is set it will have precedence over wish. @code{:max-width} and @code{:max-height} will always preserve the aspect ratio. -@item :format -ImageMagick tries to auto-detect the image type, but it isn't always -able to. By using @code{:format-type}, we can give ImageMagick a hint -to try to help it. It's used in conjunction with the -@code{image-format-suffixes} variable, which provides a mapping from -content types to file name suffixes. This is then given to -ImageMagick as a file name hint. +@item :format @var{type} +The value, @var{type}, should be a symbol specifying the type of the +image data, as found in @code{image-format-suffixes}. This is used +when the image does not have an associated file name, to provide a +hint to ImageMagick to help it detect the image type. -@item :rotation +@item :rotation @var{angle} Specifies a rotation angle in degrees. -@item :index +@item :index @var{frame} @c Doesn't work: http://debbugs.gnu.org/7978 @xref{Multi-Frame Images}. @end table @@ -4726,6 +5207,7 @@ Supports the @code{:index} property. @xref{Multi-Frame Images}. @node Defining Images @subsection Defining Images +@cindex define image The functions @code{create-image}, @code{defimage} and @code{find-image} provide convenient ways to create image descriptors. @@ -4744,6 +5226,7 @@ from the file's name. The remaining arguments, @var{props}, specify additional image properties---for example, +@c ':heuristic-mask' is not documented? @example (create-image "foo.xpm" 'xpm nil :heuristic-mask t) @end example @@ -4787,7 +5270,7 @@ of a list of image specifications @var{specs}. Each specification in @var{specs} is a property list with contents depending on image type. All specifications must at least contain the properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} -or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying +or @w{@code{:data @var{data}}}, where @var{type} is a symbol specifying the image type, e.g., @code{xbm}, @var{file} is the file to load the image from, and @var{data} is a string containing the actual image data. The first specification in the list whose @var{type} is supported, and @@ -4852,6 +5335,7 @@ Here is an example of using @code{image-load-path-for-library}: @node Showing Images @subsection Showing Images +@cindex show image You can use an image descriptor by setting up the @code{display} property yourself, but it is easier to use the functions in this @@ -4876,7 +5360,7 @@ The argument @var{slice} specifies a slice of the image to insert. If Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width} @var{height})} which specifies the @var{x} and @var{y} positions and @var{width} and @var{height} of the image area to insert. Integer -values are in units of pixels. A floating point number in the range +values are in units of pixels. A floating-point number in the range 0.0--1.0 stands for that fraction of the width or height of the entire image. @@ -4892,8 +5376,8 @@ This function inserts @var{image} in the current buffer at point, like @code{insert-image}, but splits the image into @var{rows}x@var{cols} equally sized slices. -If an image is inserted ``sliced'', Emacs displays each slice as a -separate image, and allow more intuitive scrolling up/down, instead of +Emacs displays each slice as a +separate image, and allows more intuitive scrolling up/down, instead of jumping up/down the entire image when paging through a buffer that displays (large) images. @end defun @@ -4930,14 +5414,14 @@ This removes only images that were put into @var{buffer} the way @end defun @defun image-size spec &optional pixels frame +@cindex size of image This function returns the size of an image as a pair @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image -specification. @var{pixels} non-@code{nil} means return sizes -measured in pixels, otherwise return sizes measured in canonical -character units (fractions of the width/height of the frame's default -font). @var{frame} is the frame on which the image will be displayed. -@var{frame} null or omitted means use the selected frame (@pxref{Input -Focus}). +specification. @var{pixels} non-@code{nil} means return sizes measured +in pixels, otherwise return sizes measured in the default character size +of @var{frame} (@pxref{Frame Font}). @var{frame} is the frame on which +the image will be displayed. @var{frame} null or omitted means use the +selected frame (@pxref{Input Focus}). @end defun @defvar max-image-size @@ -4946,8 +5430,8 @@ will load. Emacs will refuse to load (and display) any image that is larger than this limit. If the value is an integer, it directly specifies the maximum -image height and width, measured in pixels. If it is a floating -point number, it specifies the maximum image height and width +image height and width, measured in pixels. If it is floating +point, it specifies the maximum image height and width as a ratio to the frame height and width. If the value is non-numeric, there is no explicit limit on the size of images. @@ -4955,11 +5439,12 @@ The purpose of this variable is to prevent unreasonably large images from accidentally being loaded into Emacs. It only takes effect the first time an image is loaded. Once an image is placed in the image cache, it can always be displayed, even if the value of -@var{max-image-size} is subsequently changed (@pxref{Image Cache}). +@code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar @node Multi-Frame Images @subsection Multi-Frame Images +@cindex multi-frame images @cindex animation @cindex image animation @@ -4969,7 +5454,7 @@ are multiple ``frames'' in the image. At present, Emacs supports multiple frames for GIF, TIFF, and certain ImageMagick formats such as DJVM@. -The frames can be used either to represent multiple ``pages'' (this is +The frames can be used either to represent multiple pages (this is usually the case with multi-frame TIFF files, for example), or to create animation (usually the case with multi-frame GIF files). @@ -5007,6 +5492,8 @@ or @code{nil}, the image animates once only; if @code{t} it loops forever; if a number animation stops after that many seconds. @end defun +@vindex image-minimum-frame-delay +@vindex image-default-frame-delay @noindent Animation operates by means of a timer. Note that Emacs imposes a minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds. If the image itself does not specify a delay, Emacs uses @@ -5190,7 +5677,7 @@ so that it's easy to define special-purpose types of buttons for specific tasks. @defun define-button-type name &rest properties -Define a `button type' called @var{name} (a symbol). +Define a button type called @var{name} (a symbol). The remaining arguments form a sequence of @var{property value} pairs, specifying default property values for buttons with this type (a button's type may be set @@ -5297,10 +5784,12 @@ Set @var{button}'s @var{prop} property to @var{val}. @end defun @defun button-activate button &optional use-mouse-action -Call @var{button}'s @code{action} property (i.e., invoke it). If -@var{use-mouse-action} is non-@code{nil}, try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. +Call @var{button}'s @code{action} property (i.e., invoke the function +that is the value of that property, passing it the single argument +@var{button}). If @var{use-mouse-action} is non-@code{nil}, try to +invoke the button's @code{mouse-action} property instead of +@code{action}; if the button has no @code{mouse-action} property, use +@code{action} as normal. @end defun @defun button-label button @@ -5341,7 +5830,7 @@ Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. These are commands and functions for locating and operating on buttons in an Emacs buffer. -@code{push-button} is the command that a user uses to actually `push' +@code{push-button} is the command that a user uses to actually push a button, and is bound by default in the button itself to @key{RET} and to @key{mouse-2} using a local keymap in the button's overlay or text properties. Commands that are useful outside the buttons itself, @@ -5351,7 +5840,7 @@ additionally available in the keymap stored in @code{button-buffer-map} as a parent keymap for its keymap. If the button has a non-@code{nil} @code{follow-link} property, and -@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click +@code{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click will also activate the @code{push-button} command. @xref{Clickable Text}. @@ -5390,7 +5879,7 @@ is skipped over. Returns the button found. @defun next-button pos &optional count-current @defunx previous-button pos &optional count-current -Return the next button after (for @code{next-button} or before (for +Return the next button after (for @code{next-button}) or before (for @code{previous-button}) position @var{pos} in the current buffer. If @var{count-current} is non-@code{nil}, count any button at @var{pos} in the search, instead of starting at the next button. @@ -5407,7 +5896,8 @@ in the search, instead of starting at the next button. The Ewoc package constructs buffer text that represents a structure of Lisp objects, and updates the text to follow changes in that structure. This is like the ``view'' component in the -``model/view/controller'' design paradigm. +``model--view--controller'' design paradigm. Ewoc means ``Emacs's +Widget for Object Collections''. An @dfn{ewoc} is a structure that organizes information required to construct buffer text that represents certain Lisp data. The buffer @@ -5427,6 +5917,8 @@ The text's start position in the buffer. The header and footer strings. @item +@cindex node, ewoc +@c or "@cindex node, abstract display"? A doubly-linked chain of @dfn{nodes}, each of which contains: @itemize @@ -5451,6 +5943,8 @@ between buffer positions and nodes, move point from one node's textual representation to another, and so forth. @xref{Abstract Display Functions}. +@cindex encapsulation, ewoc +@c or "@cindex encapsulation, abstract display"? A node @dfn{encapsulates} a data element much the way a variable holds a value. Normally, encapsulation occurs as a part of adding a node to the ewoc. You can retrieve the data element value and place a @@ -5466,7 +5960,7 @@ new value in its place, like so: @noindent You can also use, as the data element value, a Lisp object (list or -vector) that is a container for the ``real'' value, or an index into +vector) that is a container for the real value, or an index into some other structure. The example (@pxref{Abstract Display Example}) uses the latter approach. @@ -5502,7 +5996,7 @@ Normally, a newline is automatically inserted after the header, the footer and every node's textual description. If @var{nosep} is non-@code{nil}, no newline is inserted. This may be useful for displaying an entire ewoc on a single line, for example, or for -making nodes ``invisible'' by arranging for @var{pretty-printer} +making nodes invisible by arranging for @var{pretty-printer} to do nothing for those nodes. An ewoc maintains its text in the buffer that is current when @@ -5622,7 +6116,7 @@ Any @var{args} are passed to @var{map-function}. @subsection Abstract Display Example Here is a simple example using functions of the ewoc package to -implement a ``color components display'', an area in a buffer that +implement a @dfn{color components} display, an area in a buffer that represents a vector of three integers (itself representing a 24-bit RGB value) in various ways. @@ -5681,10 +6175,10 @@ The buffer is in Color Components mode." @end example @cindex controller part, model/view/controller - This example can be extended to be a ``color selection widget'' (in -other words, the controller part of the ``model/view/controller'' + This example can be extended to be a color selection widget (in +other words, the ``controller'' part of the ``model--view--controller'' design paradigm) by defining commands to modify @code{colorcomp-data} -and to ``finish'' the selection process, and a keymap to tie it all +and to finish the selection process, and a keymap to tie it all together conveniently. @smallexample @@ -5758,25 +6252,26 @@ parenthesis before giving up. @end defopt @defopt blink-matching-delay -This variable specifies the number of seconds for the cursor to remain -at the matching parenthesis. A fraction of a second often gives -good results, but the default is 1, which works on all systems. +This variable specifies the number of seconds to keep indicating the +matching parenthesis. A fraction of a second often gives good +results, but the default is 1, which works on all systems. @end defopt @deffn Command blink-matching-open This function is the default value of @code{blink-paren-function}. It -assumes that point follows a character with close parenthesis syntax and -moves the cursor momentarily to the matching opening character. If that -character is not already on the screen, it displays the character's -context in the echo area. To avoid long delays, this function does not -search farther than @code{blink-matching-paren-distance} characters. +assumes that point follows a character with close parenthesis syntax +and applies the appropriate effect momentarily to the matching opening +character. If that character is not already on the screen, it +displays the character's context in the echo area. To avoid long +delays, this function does not search farther than +@code{blink-matching-paren-distance} characters. Here is an example of calling this function explicitly. @smallexample @group (defun interactive-blink-matching-open () - "Indicate momentarily the start of sexp before point." + "Indicate momentarily the start of parenthesized sexp before point." (interactive) @end group @group @@ -5933,9 +6428,9 @@ display the character @var{c} as those glyphs; @pxref{Glyphs}). @strong{Warning:} if you use the display table to change the display of newline characters, the whole buffer will be displayed as one long -``line''. +line. - The display table also has six ``extra slots'' which serve special + The display table also has six @dfn{extra slots} which serve special purposes. Here is a table of their meanings; @code{nil} in any slot means to use the default for that slot, as stated below. @@ -6046,8 +6541,11 @@ no buffer display table. @defvar standard-display-table The value of this variable is the standard display table, which is used when Emacs is displaying a buffer in a window with neither a -window display table nor a buffer display table defined. Its default -is @code{nil}. +window display table nor a buffer display table defined, or when Emacs +is outputting text to the standard output or error streams. Although its +default is typically @code{nil}, in an interactive session if the +terminal cannot display curved quotes, its default maps curved quotes +to ASCII approximations. @xref{Keys in Documentation}. @end defvar The @file{disp-table} library defines several functions for changing @@ -6057,6 +6555,7 @@ the standard display table. @subsection Glyphs @cindex glyph +@cindex glyph code A @dfn{glyph} is a graphical symbol which occupies a single character position on the screen. Each glyph is represented in Lisp as a @dfn{glyph code}, which specifies a character and optionally a @@ -6146,7 +6645,8 @@ Display a box containing the Unicode codepoint of the character, in hexadecimal notation. @item an @acronym{ASCII} string -Display a box containing that string. +Display a box containing that string. The string should contain at +most 6 @acronym{ASCII} characters. @item a cons cell @code{(@var{graphical} . @var{text})} Display with @var{graphical} on graphical displays, and with @@ -6157,7 +6657,8 @@ must be one of the display methods described above. @noindent The @code{thin-space}, @code{empty-box}, @code{hex-code}, and @acronym{ASCII} string display methods are drawn with the -@code{glyphless-char} face. +@code{glyphless-char} face. On text terminals, a box is emulated by +square brackets, @samp{[]}. The char-table has one extra slot, which determines how to display any character that cannot be displayed with any available font, or cannot @@ -6196,7 +6697,7 @@ Non-@acronym{ASCII}, non-printing characters @code{U+0080} to @samp{\230}). @item format-control -Characters of Unicode General Category `Cf', such as @samp{U+200E} +Characters of Unicode General Category [Cf], such as @samp{U+200E} (Left-to-Right Mark), but excluding characters that have graphic images, such as @samp{U+00AD} (Soft Hyphen). @@ -6205,9 +6706,9 @@ Characters for there is no suitable font, or which cannot be encoded by the terminal's coding system. @end table -@c FIXME: this can also be `acronym', but that's not currently +@c FIXME: this can also be 'acronym', but that's not currently @c completely implemented; it applies only to the format-control -@c group, and only works if the acronym is in `char-acronym-table'. +@c group, and only works if the acronym is in 'char-acronym-table'. The @var{method} symbol should be one of @code{zero-width}, @code{thin-space}, @code{empty-box}, or @code{hex-code}. These have the same meanings as in @code{glyphless-char-display}, above. @@ -6243,8 +6744,8 @@ capability (@samp{vb}). @end defopt @defvar ring-bell-function -If this is non-@code{nil}, it specifies how Emacs should ``ring the -bell''. Its value should be a function of no arguments. If this is +If this is non-@code{nil}, it specifies how Emacs should ring the +bell. Its value should be a function of no arguments. If this is non-@code{nil}, it takes precedence over the @code{visible-bell} variable. @end defvar @@ -6281,8 +6782,9 @@ Emacs is displaying the frame on a character-based terminal. This variable holds the value of @code{window-system} used for the first frame created by Emacs during startup. (When Emacs is invoked with the @option{--daemon} option, it does not create any initial -frames, so @code{initial-window-system} is @code{nil}. @xref{Initial -Options, daemon,, emacs, The GNU Emacs Manual}.) +frames, so @code{initial-window-system} is @code{nil}, except on +MS-Windows, where it is still @code{w32}. @xref{Initial Options, +daemon,, emacs, The GNU Emacs Manual}.) @end defvar @defun window-system &optional frame @@ -6300,18 +6802,6 @@ indicator of Emacs capabilities on a given display type. Instead, use @code{display-graphic-p} or any of the other @code{display-*-p} predicates described in @ref{Display Feature Testing}. -@defvar window-setup-hook -This variable is a normal hook which Emacs runs after handling the -initialization files. Emacs runs this hook after it has completed -loading your init file, the default initialization file (if -any), and the terminal-specific Lisp code, and running the hook -@code{term-setup-hook}. - -This hook is used for internal purposes: setting up communication with -the window system, and creating the initial window. Users should not -interfere with it. -@end defvar - @node Bidirectional Display @section Bidirectional Display @cindex bidirectional display @@ -6332,7 +6822,9 @@ and displaying bidirectional text. @cindex reading order @cindex visual order @cindex unicode bidirectional algorithm +@cindex UBA @cindex bidirectional reordering +@cindex reordering, of bidirectional text Text is stored in Emacs buffers and strings in @dfn{logical} (or @dfn{reading}) order, i.e., the order in which a human would read each character. In right-to-left and bidirectional text, the order in @@ -6343,7 +6835,8 @@ position. In performing this @dfn{bidirectional reordering}, Emacs follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}), which is described in Annex #9 of the Unicode standard (@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full -Bidirectionality'' class implementation of the @acronym{UBA}. +Bidirectionality'' class implementation of the @acronym{UBA}, +consistent with the requirements of the Unicode Standard v8.0. @defvar bidi-display-reordering If the value of this buffer-local variable is non-@code{nil} (the @@ -6468,7 +6961,7 @@ The function returns the new buffer position as its value. when two strings with bidirectional content are juxtaposed in a buffer, or otherwise programmatically concatenated into a string of text. A typical problematic case is when a buffer consists of -sequences of text ``fields'' separated by whitespace or punctuation +sequences of text fields separated by whitespace or punctuation characters, like Buffer Menu mode or Rmail Summary Mode. Because the punctuation characters used as separators have @dfn{weak directionality}, they take on the directionality of surrounding text. @@ -6528,3 +7021,81 @@ affect all Emacs frames and windows. appropriate mirrored character in the reordered text. Lisp programs can affect the mirrored display by changing this property. Again, any such changes affect all of Emacs display. + +@cindex overriding bidirectional properties +@cindex directional overrides +@cindex LRO +@cindex RLO + The bidirectional properties of characters can be overridden by +inserting into the text special directional control characters, +LEFT-TO-RIGHT OVERRIDE (@acronym{LRO}) and RIGHT-TO-LEFT OVERRIDE +(@acronym{RLO}). Any characters between a @acronym{RLO} and the +following newline or POP DIRECTIONAL FORMATTING (@acronym{PDF}) +control character, whichever comes first, will be displayed as if they +were strong right-to-left characters, i.e.@: they will be reversed on +display. Similarly, any characters between @acronym{LRO} and +@acronym{PDF} or newline will display as if they were strong +left-to-right, and will @emph{not} be reversed even if they are strong +right-to-left characters. + +@cindex phishing using directional overrides +@cindex malicious use of directional overrides + These overrides are useful when you want to make some text +unaffected by the reordering algorithm, and instead directly control +the display order. But they can also be used for malicious purposes, +known as @dfn{phishing}. Specifically, a URL on a Web page or a link +in an email message can be manipulated to make its visual appearance +unrecognizable, or similar to some popular benign location, while the +real location, interpreted by a browser in the logical order, is very +different. + + Emacs provides a primitive that applications can use to detect +instances of text whose bidirectional properties were overridden so as +to make a left-to-right character display as if it were a +right-to-left character, or vise versa. + +@defun bidi-find-overridden-directionality from to &optional object +This function looks at the text of the specified @var{object} between +positions @var{from} (inclusive) and @var{to} (exclusive), and returns +the first position where it finds a strong left-to-right character +whose directional properties were forced to display the character as +right-to-left, or for a strong right-to-left character that was forced +to display as left-to-right. If it finds no such characters in the +specified region of text, it returns @code{nil}. + +The optional argument @var{object} specifies which text to search, and +defaults to the current buffer. If @var{object} is non-@code{nil}, it +can be some other buffer, or it can be a string or a window. If it is +a string, the function searches that string. If it is a window, the +function searches the buffer displayed in that window. If a buffer +whose text you want to examine is displayed in some window, we +recommend to specify it by that window, rather than pass the buffer to +the function. This is because telling the function about the window +allows it to correctly account for window-specific overlays, which +might change the result of the function if some text in the buffer is +covered by overlays. +@end defun + +@cindex copying bidirectional text, preserve visual order +@cindex visual order, preserve when copying bidirectional text + When text that includes mixed right-to-left and left-to-right +characters and bidirectional controls is copied into a different +location, it can change its visual appearance, and also can affect the +visual appearance of the surrounding text at destination. This is +because reordering of bidirectional text specified by the +@acronym{UBA} has non-trivial context-dependent effects both on the +copied text and on the text at copy destination that will surround it. + + Sometimes, a Lisp program may need to preserve the exact visual +appearance of the copied text at destination, and of the text that +surrounds the copy. Lisp programs can use the following function to +achieve that effect. + +@defun buffer-substring-with-bidi-context start end &optional no-properties +This function works similar to @code{buffer-substring} (@pxref{Buffer +Contents}), but it prepends and appends to the copied text bidi +directional control characters necessary to preserve the visual +appearance of the text when it is inserted at another place. Optional +argument @var{no-properties}, if non-@code{nil}, means remove the text +properties from the copy of the text. +@end defun diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 8384c31a380..96bb03b34c0 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1,6 +1,6 @@ @comment -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992-1994, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1992-1994, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @@ -281,6 +281,26 @@ can still stop the program by typing @kbd{S}, or any editing command. In general, the execution modes earlier in the above list run the program more slowly or stop sooner than the modes later in the list. +When you enter a new Edebug level, Edebug will normally stop at the +first instrumented function it encounters. If you prefer to stop only +at a break point, or not at all (for example, when gathering coverage +data), change the value of @code{edebug-initial-mode} from its default +@code{step} to @code{go}, or @code{Go-nonstop}, or one of its other +values (@pxref{Edebug Options}). You can do this readily with +@kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}): + +@deffn Command edebug-set-initial-mode +@kindex C-x C-a C-m +This command, bound to @kbd{C-x C-a C-m}, sets +@code{edebug-initial-mode}. It prompts you for a key to indicate the +mode. You should enter one of the eight keys listed above, which sets +the corresponding mode. +@end deffn + +Note that you may reenter the same Edebug level several times if, for +example, an instrumented function is called several times from one +command. + While executing or tracing, you can interrupt the execution by typing any Edebug command. Edebug stops the program at the next stop point and then executes the command you typed. For example, typing @kbd{t} during @@ -300,13 +320,6 @@ executing a keyboard macro outside of Edebug does not affect commands inside Edebug. This is usually an advantage. See also the @code{edebug-continue-kbd-macro} option in @ref{Edebug Options}. -When you enter a new Edebug level, the initial execution mode comes -from the value of the variable @code{edebug-initial-mode} -(@pxref{Edebug Options}). By default, this specifies step mode. Note -that you may reenter the same Edebug level several times if, for -example, an instrumented function is called several times from one -command. - @defopt edebug-sit-for-seconds This option specifies how many seconds to wait between execution steps in trace mode or continue mode. The default is 1 second. @@ -363,7 +376,7 @@ at point, rather than at the stop point. If you want to execute one expression @emph{from the current stop point}, first type @kbd{w} (@code{edebug-where}) to move point there, and then type @kbd{f}. -The @kbd{o} command continues ``out of'' an expression. It places a +The @kbd{o} command continues out of an expression. It places a temporary breakpoint at the end of the sexp containing point. If the containing sexp is a function definition itself, @kbd{o} continues until just before the last sexp in the definition. If that is where you are @@ -875,7 +888,7 @@ lines inserted. frequency. Coverage testing works by comparing the result of each expression with -the previous result; each form in the program is considered ``covered'' +the previous result; each form in the program is considered covered if it has returned two different values since you began testing coverage in the current Emacs session. Thus, to do coverage testing on your program, execute it under various conditions and note whether it behaves @@ -908,7 +921,7 @@ earlier expression on the same line. The character @samp{=} following the count for an expression says that the expression has returned the same value each time it was evaluated. -In other words, it is not yet ``covered'' for coverage testing purposes. +In other words, it is not yet covered for coverage testing purposes. To clear the frequency count and coverage data for a definition, simply reinstrument it with @code{eval-defun}. @@ -978,14 +991,14 @@ unless @code{edebug-continue-kbd-macro} is non-@code{nil}. @c This paragraph is not filled, because LaLiberte's conversion script @c needs an xref to be on just one line. When Edebug needs to display something (e.g., in trace mode), it saves -the current window configuration from ``outside'' Edebug +the current window configuration from outside Edebug (@pxref{Window Configurations}). When you exit Edebug, it restores the previous window configuration. Emacs redisplays only when it pauses. Usually, when you continue execution, the program re-enters Edebug at a breakpoint or after stepping, without pausing or reading input in between. In such cases, -Emacs never gets a chance to redisplay the ``outside'' configuration. +Emacs never gets a chance to redisplay the outside configuration. Consequently, what you see is the same window configuration as the last time Edebug was active, with no interruption. @@ -1563,7 +1576,8 @@ mode for Edebug when it is first activated. Possible values are @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, @code{Trace-fast}, @code{continue}, and @code{Continue-fast}. -The default value is @code{step}. +The default value is @code{step}. This variable can be set +interactively with @kbd{C-x C-a C-m} (@code{edebug-set-initial-mode}). @xref{Edebug Execution Modes}. @end defopt @@ -1605,7 +1619,7 @@ and consider a macro of the form: If you instrument the @code{test} macro and step through it, then by default the result of the @code{symbol-function} call has numerous @code{edebug-after} and @code{edebug-before} forms, which can make it -difficult to see the ``actual'' result. If +difficult to see the actual result. If @code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove these forms from the result. @end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index e05253638d7..b2b3bbc31d3 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename elisp +@setfilename ../../info/elisp.info @ifset VOL1 @set volflag @@ -18,6 +18,7 @@ @ifclear volflag @settitle GNU Emacs Lisp Reference Manual @end ifclear +@include docstyle.texi @c %**end of header @@ -56,7 +57,7 @@ @c (See comments for EDITION in emacs.texi) @set VERSION 3.1 @include emacsver.texi -@set DATE January 2013 +@set DATE October 2014 @c in general, keep the following line commented out, unless doing a @c copy of this manual that will be published. The manual should go @@ -98,14 +99,14 @@ This is the @cite{GNU Emacs Lisp Reference Manual} @end ifnottex corresponding to Emacs version @value{EMACSVER}. -Copyright @copyright{} 1990--1996, 1998--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1990--1996, 1998--2015 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License,'' with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover +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.'' @@ -115,11 +116,9 @@ developing GNU and promoting software freedom.'' @end quotation @end copying -@documentencoding UTF-8 - -@dircategory GNU Emacs Lisp +@dircategory Emacs lisp @direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. +* Elisp: (elisp). The Emacs Lisp Reference Manual. @end direntry @titlepage @@ -194,7 +193,6 @@ To view this manual in other formats, click * Loading:: Reading files of Lisp code into Lisp. * Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. * Debugging:: Tools and tips for debugging Lisp programs. * Read and Print:: Converting Lisp objects to text and back. @@ -249,9 +247,9 @@ Appendices @end ignore @c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In +@c be correctly identified by 'texinfo-multiple-files-update'. In @c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. +@c value of 'texinfo-master-menu-header'. See texnfo-upd.el. @detailmenu --- The Detailed Node Listing --- @@ -298,7 +296,7 @@ Lisp Data Types Programming Types * Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. +* Floating-Point Type:: Numbers with fractional parts and with a large range. * Character Type:: The representation of letters, numbers and control characters. * Symbol Type:: A multi-use object that refers to a function, @@ -318,6 +316,7 @@ Programming Types * Byte-Code Type:: A function written in Lisp, then compiled. * Autoload Type:: A type used for automatically loading seldom-used functions. +* Finalizer Type:: Runs code when no longer reachable. Character Type @@ -363,7 +362,7 @@ Numbers * Comparison of Numbers:: Equality and inequality predicates. * Numeric Conversions:: Converting float to integer and vice versa. * Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. +* Rounding Operations:: Explicitly rounding floating-point numbers. * Bitwise Operations:: Logical and, or, not, shifting. * Math Functions:: Trig, exponential and logarithmic functions. * Random Numbers:: Obtaining random integers, predictable or not. @@ -455,7 +454,7 @@ Kinds of Forms we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, +* Special Forms:: Special forms are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -466,6 +465,7 @@ Control Structures * Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. * Combining Conditions:: @code{and}, @code{or}, @code{not}. * Iteration:: @code{while} loops. +* Generators:: Generic sequences and coroutines. * Nonlocal Exits:: Jumping out of a sequence. Nonlocal Exits @@ -486,7 +486,7 @@ Errors Variables * Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. +* Constant Variables:: Variables that never change. * Local Variables:: Variable values that exist only temporarily. * Void Variables:: Symbols that lack values. * Defining Variables:: A definition says a symbol is used as a variable. @@ -600,7 +600,7 @@ Loading * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. +* Unloading:: How to unload a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @@ -615,19 +615,6 @@ Byte Compilation * Byte-Code Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code. -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Combined Definition:: How advice is implemented. - Debugging Lisp Programs * Debugger:: A debugger for the Emacs Lisp evaluator. @@ -761,11 +748,13 @@ Defining Commands * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Generic Commands:: Select among command alternatives. + Input Events -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. +* Keyboard Events:: Ordinary characters -- keys with symbols on them. +* Function Keys:: Function keys -- keys with names, not symbols. * Mouse Events:: Overview of mouse events. * Click Events:: Pushing and releasing a mouse button. * Drag Events:: Moving the mouse before releasing the button. @@ -916,6 +905,7 @@ Simple Minded Indentation Engine * SMIE Indentation:: Specifying indentation rules. * SMIE Indentation Helpers:: Helper functions for indentation rules. * SMIE Indentation Example:: Sample indentation rules. +* SMIE Customization:: Customizing indentation. Documentation @@ -952,7 +942,8 @@ Information about Files * Testing Accessibility:: Is a given file readable? Writable? * Kinds of Files:: Is it a directory? A symbolic link? * Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. +* File Attributes:: File sizes, modification times, etc. +* Extended Attributes:: Extended file attributes for access control. * Locating Files:: How to find a file in standard places. File Names @@ -1000,10 +991,10 @@ Buffers is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". + behind Emacs's back. * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. -* The Buffer List:: How to look at all the existing buffers. +* Buffer List:: How to look at all the existing buffers. * Creating Buffers:: Functions that create buffers. * Killing Buffers:: Buffers exist until explicitly killed. * Indirect Buffers:: An indirect buffer shares text with some @@ -1017,6 +1008,7 @@ Windows * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Splitting one window into two windows. * Deleting Windows:: Deleting a window gives its space to other windows. * Recombining Windows:: Preserving the frame layout when splitting and @@ -1050,6 +1042,7 @@ Frames * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. +* Frame Geometry:: Geometric properties of frames. * Frame Parameters:: Controlling frame size, position, font, etc. * Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. @@ -1073,12 +1066,18 @@ Frames * Resources:: Getting resource values from the server. * Display Feature Testing:: Determining the features of a terminal. +Frame Geometry + +* Frame Layout:: Basic layout of frames. +* Frame Font:: The default font of a frame and how to set it. +* Size and Position:: Changing the size and position of a frame. +* Implied Frame Resizing:: Implied resizing of frames and how to prevent it. + Frame Parameters * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. * Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. * Geometry:: Parsing geometry specifications. Window Frame Parameters @@ -1119,8 +1118,8 @@ Markers * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". +* The Mark:: How the mark is implemented with a marker. +* The Region:: How to access the region. Text @@ -1150,10 +1149,11 @@ Text * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Transposition:: Swapping two portions of a buffer. +* Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. * Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". +* Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. The Kill Ring @@ -1325,7 +1325,7 @@ Processes Receiving Output from Processes -* Process Buffers:: If no filter, output is put in a buffer. +* Process Buffers:: By default, output is put in a buffer. * Filter Functions:: Filter functions accept output from the process. * Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives. @@ -1354,18 +1354,19 @@ Emacs Display * Selective Display:: Hiding part of the buffer text (the old way). * Temporary Displays:: Displays that go away automatically. * Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. +* Size of Displayed Text:: How large displayed text is. * Line Height:: Controlling the height of lines. * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. +* Scroll Bars:: Controlling scroll bars. +* Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs's Widget for Object Collections. * Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. +* Character Display:: How Emacs displays individual characters. * Beeping:: Audible signal to the user. * Window Systems:: Which window system is being used. * Bidirectional Display:: Display of bidirectional scripts, such as @@ -1400,10 +1401,10 @@ Faces * Attribute Functions:: Functions to examine and set face attributes. * Displaying Faces:: How Emacs combines the faces specified for a character. -* Face Remapping:: Remapping faces to alternative definitions. +* Face Remapping:: Remapping faces to alternative definitions. * Face Functions:: How to define and examine faces. * Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. +* Basic Faces:: Faces that are defined by default. * Font Selection:: Finding the best available font for a face. * Font Lookup:: Looking up the names of available fonts and information about them. @@ -1493,6 +1494,7 @@ Operating System Interface * Desktop Notifications:: Desktop notifications. * File Notifications:: File notifications. * Dynamic Libraries:: On-demand loading of support libraries. +* Security Considerations:: Running Emacs in an unfriendly environment. Starting Up Emacs @@ -1567,7 +1569,6 @@ Object Internals @include customize.texi @include loading.texi @include compile.texi -@include advice.texi @c This includes edebug.texi. @include debugging.texi diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 8a10fbf0c47..d485b3b6f15 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1993, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Errors @@ -157,7 +157,10 @@ The message is @samp{Attempt to modify a protected file}. @item scan-error The message is @samp{Scan error}. This happens when certain syntax-parsing functions find invalid syntax or mismatched -parentheses. @xref{List Motion}, and @xref{Parsing Expressions}. +parentheses. Conventionally raised with three argument: a +human-readable error message, the start of the obstacle that cannot be +moved over, and the end of the obstacle. @xref{List Motion}, and +@xref{Parsing Expressions}. @item search-failed The message is @samp{Search failed}. @xref{Searching and Matching}. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 4b83d575fef..067dbd2d99f 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1994, 1998, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Evaluation @@ -104,9 +104,9 @@ interpretation. @xref{Command Loop}. A Lisp object that is intended to be evaluated is called a @dfn{form} (or an @dfn{expression}). How Emacs evaluates a form depends on its data type. Emacs has three different kinds of form -that are evaluated differently: symbols, lists, and ``all other -types''. This section describes all three kinds, one by one, starting -with the ``all other types'' which are self-evaluating forms. +that are evaluated differently: symbols, lists, and all other +types. This section describes all three kinds, one by one, starting +with the other types, which are self-evaluating forms. @menu * Self-Evaluating Forms:: Forms that evaluate to themselves. @@ -116,7 +116,7 @@ with the ``all other types'' which are self-evaluating forms. we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, +* Special Forms:: Special forms are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -146,7 +146,7 @@ contents unchanged. @result{} 123 @end group @group -(eval '123) ; @r{Evaluated ``by hand''---result is the same.} +(eval '123) ; @r{Evaluated "by hand"---result is the same.} @result{} 123 @end group @group @@ -242,11 +242,9 @@ it obtains a non-symbol. @xref{Function Names}, for more information about symbol function indirection. One possible consequence of this process is an infinite loop, in the -event that a symbol's function cell refers to the same symbol. Or a -symbol may have a void function cell, in which case the subroutine -@code{symbol-function} signals a @code{void-function} error. But if -neither of these things happens, we eventually obtain a non-symbol, -which ought to be a function or other suitable object. +event that a symbol's function cell refers to the same symbol. +Otherwise, we eventually obtain a non-symbol, which ought to be a +function or other suitable object. @kindex invalid-function More precisely, we should now have a Lisp function (a lambda @@ -255,12 +253,12 @@ a special form, or an autoload object. Each of these types is a case described in one of the following sections. If the object is not one of these types, Emacs signals an @code{invalid-function} error. - The following example illustrates the symbol indirection process. We -use @code{fset} to set the function cell of a symbol and + The following example illustrates the symbol indirection process. +We use @code{fset} to set the function cell of a symbol and @code{symbol-function} to get the function cell contents -(@pxref{Function Cells}). Specifically, we store the symbol @code{car} -into the function cell of @code{first}, and the symbol @code{first} into -the function cell of @code{erste}. +(@pxref{Function Cells}). Specifically, we store the symbol +@code{car} into the function cell of @code{first}, and the symbol +@code{first} into the function cell of @code{erste}. @example @group @@ -440,6 +438,11 @@ begins with @code{lambda} but is not a well-formed @code{lambda} expression, so Emacs may signal an error, or may return 3 or 4 or @code{nil}, or may behave in other ways. +@defun special-form-p object +This predicate tests whether its argument is a special form, and +returns @code{t} if so, @code{nil} otherwise. +@end defun + Here is a list, in alphabetical order, of all of the special forms in Emacs Lisp with a reference to where each is described. @@ -523,7 +526,7 @@ GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and doesn't exist in Common Lisp. @code{throw} is a special form in Common Lisp (because it must be able to throw multiple values), but it is a function in Emacs Lisp (which doesn't have multiple -values).@refill +values). @end quotation @node Autoloading @@ -710,12 +713,18 @@ arguments. @defun eval form &optional lexical This is the basic function for evaluating an expression. It evaluates -@var{form} in the current environment and returns the result. How the -evaluation proceeds depends on the type of the object (@pxref{Forms}). - -The argument @var{lexical}, if non-@code{nil}, means to evaluate -@var{form} using lexical scoping rules for variables, instead of the -default dynamic scoping rules. @xref{Lexical Binding}. +@var{form} in the current environment, and returns the result. The +type of the @var{form} object determines how it is evaluated. +@xref{Forms}. + +The argument @var{lexical} specifies the scoping rule for local +variables (@pxref{Variable Scoping}). If it is omitted or @code{nil}, +that means to evaluate @var{form} using the default dynamic scoping +rule. If it is @code{t}, that means to use the lexical scoping rule. +The value of @var{lexical} can also be a non-empty alist specifying a +particular @dfn{lexical environment} for lexical bindings; however, +this feature is only useful for specialized purposes, such as in Emacs +Lisp debuggers. @xref{Lexical Binding}. Since @code{eval} is a function, the argument expression that appears in a call to @code{eval} is evaluated twice: once as preparation before @@ -796,7 +805,12 @@ message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This limit, with the associated error when it is exceeded, is one way Emacs Lisp avoids infinite recursion on an ill-defined function. If you increase the value of @code{max-lisp-eval-depth} too much, such -code can cause stack overflow instead. +code can cause stack overflow instead. On some systems, this overflow +can be handled. In that case, normal Lisp evaluation is interrupted +and control is transferred back to the top level command loop +(@code{top-level}). Note that there is no way to enter Emacs Lisp +debugger in this situation. @xref{Error Debugging}. + @cindex Lisp nesting error The depth limit counts internal uses of @code{eval}, @code{apply}, and diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 1f7169522cc..9a1b2cd217f 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1,27 +1,27 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Files @chapter Files This chapter describes the Emacs Lisp functions and variables to -find, create, view, save, and otherwise work with files and file +find, create, view, save, and otherwise work with files and directories. A few other file-related functions are described in @ref{Buffers}, and those related to backups and auto-saving are described in @ref{Backups and Auto-Saving}. Many of the file functions take one or more arguments that are file -names. A file name is actually a string. Most of these functions -expand file name arguments by calling @code{expand-file-name}, so that +names. A file name is a string. Most of these functions expand file +name arguments using the function @code{expand-file-name}, so that @file{~} is handled correctly, as are relative file names (including -@samp{../}). @xref{File Name Expansion}. +@file{../}). @xref{File Name Expansion}. In addition, certain @dfn{magic} file names are handled specially. For example, when a remote file name is specified, Emacs accesses the -file over the network via an appropriate protocol (@pxref{Remote -Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is +file over the network via an appropriate protocol. @xref{Remote +Files,, Remote Files, emacs, The GNU Emacs Manual}. This handling is done at a very low level, so you may assume that all the functions described in this chapter accept magic file names as file name arguments, except where noted. @xref{Magic File Names}, for details. @@ -55,25 +55,24 @@ to locale @code{system-messages-locale}, and decoded using coding system Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is @dfn{visiting} that file, and call the -file ``the visited file'' of the buffer. +file @dfn{the visited file} of the buffer. A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; then we -say the buffer is visiting that file. The copy in the buffer is what -you modify with editing commands. Such changes to the buffer do not -change the file; therefore, to make the changes permanent, you must -@dfn{save} the buffer, which means copying the altered buffer contents -back into the file. - - In spite of the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we say, -``I am editing a file'', rather than, ``I am editing a buffer that I -will soon save as a file of the same name''. Humans do not usually need -to make the distinction explicit. When dealing with a computer program, -however, it is good to keep the distinction in mind. +recorded permanently in the computer (unless you delete it). A +buffer, on the other hand, is information inside of Emacs that will +vanish at the end of the editing session (or when you kill the +buffer). When a buffer is visiting a file, it contains information +copied from the file. The copy in the buffer is what you modify with +editing commands. Changes to the buffer do not change the file; to +make the changes permanent, you must @dfn{save} the buffer, which +means copying the altered buffer contents back into the file. + + Despite the distinction between files and buffers, people often +refer to a file when they mean a buffer and vice-versa. Indeed, we +say, ``I am editing a file'', rather than, ``I am editing a buffer +that I will soon save as a file of the same name''. Humans do not +usually need to make the distinction explicit. When dealing with a +computer program, however, it is good to keep the distinction in mind. @menu * Visiting Functions:: The usual interface functions for visiting. @@ -82,6 +81,8 @@ however, it is good to keep the distinction in mind. @node Visiting Functions @subsection Functions for Visiting Files +@cindex visiting files, functions for +@cindex how to visit files This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with @@ -255,11 +256,16 @@ is permanent local, so it is unaffected by changes of major modes. which are sometimes useful in user Lisp code: @code{create-file-buffer} and @code{after-find-file}. This section explains how to use them. +@c FIXME This does not describe the default behavior, because +@c uniquify is enabled by default and advises this function. +@c This is confusing. uniquify should be folded into the function proper. @defun create-file-buffer filename This function creates a suitably named buffer for visiting @var{filename}, and returns it. It uses @var{filename} (sans directory) as the name if that name is free; otherwise, it appends a string such as @samp{<2>} to get an unused name. See also @ref{Creating Buffers}. +Note that the @file{uniquify} library affects the result of this +function. @xref{Uniquify,,, emacs, The GNU Emacs Manual}. @strong{Please note:} @code{create-file-buffer} does @emph{not} associate the new buffer with a file and does not select the buffer. @@ -417,7 +423,7 @@ To do so, execute the following code: You might wish to save the file modes value returned by @code{backup-buffer} and use that (if non-@code{nil}) to set the mode bits of the file that you write. This is what @code{save-buffer} -normally does. @xref{Making Backups,, Making Backup Files}. +normally does. @xref{Making Backups,, Making Backup Files}. The hook functions in @code{write-file-functions} are also responsible for encoding the data (if desired): they must choose a suitable coding @@ -507,9 +513,9 @@ Name}). @section Reading from Files @cindex reading from files - You can copy a file from the disk and insert it into a buffer -using the @code{insert-file-contents} function. Don't use the user-level -command @code{insert-file} in a Lisp program, as that sets the mark. + To copy the contents of a file into a buffer, use the function +@code{insert-file-contents}. (Don't use the command +@code{insert-file} in a Lisp program, as that sets the mark.) @defun insert-file-contents filename &optional visit beg end replace This function inserts the contents of file @var{filename} into the @@ -647,8 +653,9 @@ and also calls the functions in the list @xref{Format Conversion}. Normally, @code{write-region} displays the message @samp{Wrote -@var{filename}} in the echo area. If @var{visit} is neither @code{t} -nor @code{nil} nor a string, then this message is inhibited. This +@var{filename}} in the echo area. This message is inhibited if +@var{visit} is neither @code{t} nor @code{nil} nor a string, or if +Emacs is operating in batch mode (@pxref{Batch Mode}). This feature is useful for programs that use files for internal purposes, files that the user does not need to know about. @end deffn @@ -677,14 +684,15 @@ with-temp-buffer,, The Current Buffer}. When two users edit the same file at the same time, they are likely to interfere with each other. Emacs tries to prevent this situation from arising by recording a @dfn{file lock} when a file is being -modified. (File locks are not implemented on Microsoft systems.) +modified. Emacs can then detect the first attempt to modify a buffer visiting a file that is locked by another Emacs job, and ask the user what to do. The file lock is really a file, a symbolic link with a special name, -stored in the same directory as the file you are editing. +stored in the same directory as the file you are editing. (On file +systems that do not support symbolic links, a regular file is used.) When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously''. +you and another user will both lock the same file simultaneously. If this happens, it is possible for the two users to make changes simultaneously, but Emacs will still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed @@ -709,22 +717,17 @@ some other job. This function locks the file @var{filename}, if the current buffer is modified. The argument @var{filename} defaults to the current buffer's visited file. Nothing is done if the current buffer is not visiting a -file, or is not modified, or if the system does not support locking. +file, or is not modified, or if the option @code{create-lockfiles} is +@code{nil}. @end defun @defun unlock-buffer This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also -does nothing if the current buffer is not visiting a file, or if the -system does not support locking. +does nothing if the current buffer is not visiting a file, or is not locked. @end defun - File locking is not supported on some systems. On systems that do not -support it, the functions @code{lock-buffer}, @code{unlock-buffer} and -@code{file-locked-p} do nothing and return @code{nil}. It is also -possible to disable locking, by setting the variable @code{create-lockfiles}. - @defopt create-lockfiles If this variable is @code{nil}, Emacs does not lock files. @end defopt @@ -761,34 +764,31 @@ name of the user who has locked the file. @end itemize If you wish, you can replace the @code{ask-user-about-lock} function -with your own version that makes the decision in another way. The code -for its usual definition is in @file{userlock.el}. +with your own version that makes the decision in another way. @end defun @node Information about Files @section Information about Files @cindex file, information about - The functions described in this section all operate on strings that -designate file names. With a few exceptions, all the functions have -names that begin with the word @samp{file}. These functions all -return information about actual files or directories, so their -arguments must all exist as actual files or directories unless -otherwise noted. + This section describes the functions for retrieving various types of +information about files (or directories or symbolic links), such as +whether a file is readable or writable, and its size. These functions +all take arguments which are file names. Except where noted, these +arguments need to specify existing files, or an error is signaled. @cindex file names, trailing whitespace @cindex trailing blanks in file names -Be careful with file names that end in blanks: some filesystems -(notably, MS-Windows) will ignore trailing whitespace in file names, -and return information about the file after stripping those blanks -from the name, not about the file whose name you passed to the -functions described in this section. + Be careful with file names that end in spaces. On some filesystems +(notably, MS-Windows), trailing whitespace characters in file names +are silently and automatically ignored. @menu * Testing Accessibility:: Is a given file readable? Writable? * Kinds of Files:: Is it a directory? A symbolic link? * Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. +* File Attributes:: File sizes, modification times, etc. +* Extended Attributes:: Extended file attributes for access control. * Locating Files:: How to find a file in standard places. @end menu @@ -797,10 +797,16 @@ functions described in this section. @cindex accessibility of a file @cindex file accessibility - These functions test for permission to access a file in specific -ways. Unless explicitly stated otherwise, they recursively follow -symbolic links for their file name arguments, at all levels (at the -level of the file itself and at all levels of parent directories). + These functions test for permission to access a file for reading, +writing, or execution. Unless explicitly stated otherwise, they +recursively follow symbolic links for their file name arguments, at +all levels (at the level of the file itself and at all levels of +parent directories). + + On some operating systems, more complex sets of access permissions +can be specified, via mechanisms such as Access Control Lists (ACLs). +@xref{Extended Attributes}, for how to query and set those +permissions. @defun file-exists-p filename This function returns @code{t} if a file named @var{filename} appears @@ -810,9 +816,8 @@ true if the file exists and you have execute permission on the containing directories, regardless of the permissions of the file itself.) -If the file does not exist, or if fascist access control policies -prevent you from finding the attributes of the file, this function -returns @code{nil}. +If the file does not exist, or if access control policies prevent you +from finding its attributes, this function returns @code{nil}. Directories are files, so @code{file-exists-p} returns @code{t} when given a directory name. However, symbolic links are treated @@ -823,24 +828,8 @@ name only if the target file exists. @defun file-readable-p filename This function returns @code{t} if a file named @var{filename} exists and you can read it. It returns @code{nil} otherwise. - -@example -@group -(file-readable-p "files.texi") - @result{} t -@end group -@group -(file-exists-p "/usr/spool/mqueue") - @result{} t -@end group -@group -(file-readable-p "/usr/spool/mqueue") - @result{} nil -@end group -@end example @end defun -@c Emacs 19 feature @defun file-executable-p filename This function returns @code{t} if a file named @var{filename} exists and you can execute it. It returns @code{nil} otherwise. On Unix and @@ -856,27 +845,18 @@ file exists and you can write it. It is creatable if it does not exist, but the specified directory does exist and you can write in that directory. -In the third example below, @file{foo} is not writable because the -parent directory does not exist, even though the user could create such -a directory. +In the example below, @file{foo} is not writable because the parent +directory does not exist, even though the user could create such a +directory. @example @group -(file-writable-p "~/foo") - @result{} t -@end group -@group -(file-writable-p "/foo") - @result{} nil -@end group -@group (file-writable-p "~/no-such-dir/foo") @result{} nil @end group @end example @end defun -@c Emacs 19 feature @defun file-accessible-directory-p dirname This function returns @code{t} if you have permission to open existing files in the directory whose name as a file is @var{dirname}; @@ -885,16 +865,13 @@ The value of @var{dirname} may be either a directory name (such as @file{/foo/}) or the file name of a file which is a directory (such as @file{/foo}, without the final slash). -Example: after the following, +For example, from the following we deduce that any attempt to read a +file in @file{/foo/} will give an error: @example (file-accessible-directory-p "/foo") @result{} nil @end example - -@noindent -we can deduce that any attempt to read a file in @file{/foo/} will -give an error. @end defun @defun access-file filename string @@ -917,43 +894,65 @@ replace @var{filename} with its target. However, it does recursively follow symbolic links at all levels of parent directories. @end defun -@defun file-newer-than-file-p filename1 filename2 -@cindex file age -@cindex file modification time -This function returns @code{t} if the file @var{filename1} is -newer than file @var{filename2}. If @var{filename1} does not -exist, it returns @code{nil}. If @var{filename1} does exist, but -@var{filename2} does not, it returns @code{t}. +@defun file-modes filename +@cindex mode bits +@cindex file permissions +@cindex permissions, file +@cindex file modes +This function returns the @dfn{mode bits} of @var{filename}---an +integer summarizing its read, write, and execution permissions. +Symbolic links in @var{filename} are recursively followed at all +levels. If the file does not exist, the return value is @code{nil}. -In the following example, assume that the file @file{aug-19} was written -on the 19th, @file{aug-20} was written on the 20th, and the file -@file{no-file} doesn't exist at all. +@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils} +Manual}, for a description of mode bits. For example, if the +low-order bit is 1, the file is executable by all users; if the +second-lowest-order bit is 1, the file is writable by all users; etc. +The highest possible value is 4095 (7777 octal), meaning that everyone +has read, write, and execute permission, the @acronym{SUID} bit is set +for both others and group, and the sticky bit is set. + +@xref{Changing Files}, for the @code{set-file-modes} function, which +can be used to set these permissions. @example @group -(file-newer-than-file-p "aug-19" "aug-20") - @result{} nil +(file-modes "~/junk/diffs") + @result{} 492 ; @r{Decimal integer.} @end group @group -(file-newer-than-file-p "aug-20" "aug-19") - @result{} t +(format "%o" 492) + @result{} "754" ; @r{Convert to octal.} @end group + @group -(file-newer-than-file-p "aug-19" "no-file") - @result{} t +(set-file-modes "~/junk/diffs" #o666) + @result{} nil @end group + @group -(file-newer-than-file-p "no-file" "aug-19") - @result{} nil +$ ls -l diffs +-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs @end group @end example -You can use @code{file-attributes} to get a file's last modification -time as a list of four integers. @xref{File Attributes}. +@cindex MS-DOS and file modes +@cindex file modes and MS-DOS +@strong{MS-DOS note:} On MS-DOS, there is no such thing as an +executable file mode bit. So @code{file-modes} considers a file +executable if its name ends in one of the standard executable +extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some +others. Files that begin with the Unix-standard @samp{#!} signature, +such as shell and Perl scripts, are also considered executable. +Directories are also reported as executable, for compatibility with +Unix. These conventions are also followed by @code{file-attributes} +(@pxref{File Attributes}). @end defun @node Kinds of Files @subsection Distinguishing Kinds of Files +@cindex file classification +@cindex classification of file types This section describes how to distinguish various kinds of files, such as directories, symbolic links, and ordinary files. @@ -961,22 +960,26 @@ as directories, symbolic links, and ordinary files. @defun file-symlink-p filename @cindex file symbolic links If the file @var{filename} is a symbolic link, the -@code{file-symlink-p} function returns the (non-recursive) link target -as a string. (Determining the file name that the link points to from -the target is nontrivial.) First, this function recursively follows -symbolic links at all levels of parent directories. - -If the file @var{filename} is not a symbolic link (or there is no such file), +@code{file-symlink-p} function returns its (non-recursive) link target +as a string. (The link target string is not necessarily the full +absolute file name of the target; determining the full file name that +the link points to is nontrivial, see below.) If the leading +directories of @var{filename} include symbolic links, this function +recursively follows them. + +If the file @var{filename} is not a symbolic link, or does not exist, @code{file-symlink-p} returns @code{nil}. +Here are a few examples of using this function: + @example @group -(file-symlink-p "foo") +(file-symlink-p "not-a-symlink") @result{} nil @end group @group (file-symlink-p "sym-link") - @result{} "foo" + @result{} "not-a-symlink" @end group @group (file-symlink-p "sym-link2") @@ -988,7 +991,39 @@ If the file @var{filename} is not a symbolic link (or there is no such file), @end group @end example -@c !!! file-symlink-p: should show output of ls -l for comparison +Note that in the third example, the function returned @file{sym-link}, +but did not proceed to resolve it, although that file is itself a +symbolic link. This is what we meant by ``non-recursive'' above---the +process of following the symbolic links does not recurse if the link +target is itself a link. + +The string that this function returns is what is recorded in the +symbolic link; it may or may not include any leading directories. +This function does @emph{not} expand the link target to produce a +fully-qualified file name, and in particular does not use the leading +directories, if any, of the @var{filename} argument if the link target +is not an absolute file name. Here's an example: + +@example +@group +(file-symlink-p "/foo/bar/baz") + @result{} "some-file" +@end group +@end example + +@noindent +Here, although @file{/foo/bar/baz} was given as a fully-qualified file +name, the result is not, and in fact does not have any leading +directories at all. And since @file{some-file} might itself be a +symbolic link, you cannot simply prepend leading directories to it, +nor even naively use @code{expand-file-name} (@pxref{File Name +Expansion}) to produce its absolute file name. + +For this reason, this function is seldom useful if you need to +determine more than just the fact that a file is or isn't a symbolic +link. If you actually need the file name of the link target, use +@code{file-chase-links} or @code{file-truename}, described in +@ref{Truenames}. @end defun The next two functions recursively follow symbolic links at @@ -1029,21 +1064,6 @@ a regular file (not a directory, named pipe, terminal, or other I/O device). @end defun -@defun file-equal-p file1 file2 -This function returns @code{t} if the files @var{file1} and -@var{file2} name the same file. If @var{file1} or @var{file2} does -not exist, the return value is unspecified. -@end defun - -@defun file-in-directory-p file dir -This function returns @code{t} if @var{file} is a file in directory -@var{dir}, or in a subdirectory of @var{dir}. It also returns -@code{t} if @var{file} and @var{dir} are the same directory. It -compares the @code{file-truename} values of the two directories -(@pxref{Truenames}). If @var{dir} does not name an existing -directory, the return value is @code{nil}. -@end defun - @node Truenames @subsection Truenames @cindex truename (of file) @@ -1066,14 +1086,14 @@ This function does not expand environment variables. Only substitute-in-file-name}. If you may need to follow symbolic links preceding @samp{..}@: -appearing as a name component, you should make sure to call -@code{file-truename} without prior direct or indirect calls to -@code{expand-file-name}, as otherwise the file name component -immediately preceding @samp{..} will be ``simplified away'' before -@code{file-truename} is called. To eliminate the need for a call to -@code{expand-file-name}, @code{file-truename} handles @samp{~} in the -same way that @code{expand-file-name} does. @xref{File Name -Expansion,, Functions that Expand Filenames}. +appearing as a name component, call @code{file-truename} without prior +direct or indirect calls to @code{expand-file-name}. Otherwise, the +file name component immediately preceding @samp{..} will be +simplified away before @code{file-truename} is called. To +eliminate the need for a call to @code{expand-file-name}, +@code{file-truename} handles @samp{~} in the same way that +@code{expand-file-name} does. @xref{File Name Expansion,, Functions +that Expand Filenames}. @end defun @defun file-chase-links filename &optional limit @@ -1102,70 +1122,61 @@ we would have: @result{} "/home/foo/hello" @end example - @xref{Buffer File Name}, for related information. +@defun file-equal-p file1 file2 +This function returns @code{t} if the files @var{file1} and +@var{file2} name the same file. This is similar to comparing their +truenames, except that remote file names are also handled in an +appropriate manner. If @var{file1} or @var{file2} does not exist, the +return value is unspecified. +@end defun + +@defun file-in-directory-p file dir +This function returns @code{t} if @var{file} is a file in directory +@var{dir}, or in a subdirectory of @var{dir}. It also returns +@code{t} if @var{file} and @var{dir} are the same directory. It +compares the truenames of the two directories. If @var{dir} does not +name an existing directory, the return value is @code{nil}. +@end defun @node File Attributes -@subsection Other Information about Files +@subsection File Attributes +@cindex file attributes This section describes the functions for getting detailed -information about a file, other than its contents. This information -includes the mode bits that control access permissions, the owner and -group numbers, the number of names, the inode number, the size, and -the times of access and modification. +information about a file, including the owner and group numbers, the +number of names, the inode number, the size, and the times of access +and modification. -@defun file-modes filename -@cindex file permissions -@cindex permissions, file -@cindex file attributes -@cindex file modes -This function returns the @dfn{mode bits} describing the @dfn{file -permissions} of @var{filename}, as an integer. It recursively follows -symbolic links in @var{filename} at all levels. If @var{filename} -does not exist, the return value is @code{nil}. +@defun file-newer-than-file-p filename1 filename2 +@cindex file age +@cindex file modification time +This function returns @code{t} if the file @var{filename1} is +newer than file @var{filename2}. If @var{filename1} does not +exist, it returns @code{nil}. If @var{filename1} does exist, but +@var{filename2} does not, it returns @code{t}. -@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils} -Manual}, for a description of mode bits. If the low-order bit is 1, -then the file is executable by all users, if the second-lowest-order -bit is 1, then the file is writable by all users, etc. The highest -value returnable is 4095 (7777 octal), meaning that everyone has read, -write, and execute permission, that the @acronym{SUID} bit is set for -both others and group, and that the sticky bit is set. +In the following example, assume that the file @file{aug-19} was written +on the 19th, @file{aug-20} was written on the 20th, and the file +@file{no-file} doesn't exist at all. @example @group -(file-modes "~/junk/diffs") - @result{} 492 ; @r{Decimal integer.} +(file-newer-than-file-p "aug-19" "aug-20") + @result{} nil @end group @group -(format "%o" 492) - @result{} "754" ; @r{Convert to octal.} +(file-newer-than-file-p "aug-20" "aug-19") + @result{} t @end group - @group -(set-file-modes "~/junk/diffs" #o666) - @result{} nil +(file-newer-than-file-p "aug-19" "no-file") + @result{} t @end group - @group -$ ls -l diffs --rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs +(file-newer-than-file-p "no-file" "aug-19") + @result{} nil @end group @end example - -@xref{Changing Files}, for functions that change file permissions, -such as @code{set-file-modes}. - -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS -@strong{MS-DOS note:} On MS-DOS, there is no such thing as an -``executable'' file mode bit. So @code{file-modes} considers a file -executable if its name ends in one of the standard executable -extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some -others. Files that begin with the Unix-standard @samp{#!} signature, -such as shell and Perl scripts, are also considered executable. -Directories are also reported as executable, for compatibility with -Unix. These conventions are also followed by @code{file-attributes}, -below. @end defun If the @var{filename} argument to the next two functions is a @@ -1173,31 +1184,6 @@ symbolic link, then these function do @emph{not} replace it with its target. However, they both recursively follow symbolic links at all levels of parent directories. -@defun file-nlinks filename -This function returns the number of names (i.e., hard links) that -file @var{filename} has. If the file does not exist, this function -returns @code{nil}. Note that symbolic links have no effect on this -function, because they are not considered to be names of the files -they link to. - -@example -@group -$ ls -l foo* --rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo --rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1 -@end group - -@group -(file-nlinks "foo") - @result{} 2 -@end group -@group -(file-nlinks "doesnt-exist") - @result{} nil -@end group -@end example -@end defun - @defun file-attributes filename &optional id-format @anchor{Definition of file-attributes} This function returns a list of attributes of file @var{filename}. If @@ -1224,8 +1210,7 @@ links, can be created by using the @code{add-name-to-file} function @item The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is an integer or a floating -point number. +not correspond to a named user, the value is a number. @item The file's @acronym{GID}, likewise. @@ -1249,8 +1234,8 @@ its owner and group, and other information recorded in the filesystem for the file, beyond the file's contents. @item -The size of the file in bytes. If the size is too large to fit in a -Lisp integer, this is a floating point number. +The size of the file in bytes. This is floating point if the size is +too large to fit in a Lisp integer. @item The file's modes, as a string of ten letters or dashes, @@ -1262,7 +1247,7 @@ An unspecified value, present for backward compatibility. @item The file's inode number. If possible, this is an integer. If the inode number is too large to be represented as an integer in Emacs -Lisp but dividing it by @math{2^16} yields a representable integer, +Lisp but dividing it by @math{2^{16}} yields a representable integer, then the value has the form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 bits. If the inode number is too wide for even that, the value is of the form @@ -1306,10 +1291,10 @@ has only one name (the name @file{files.texi} in the current default directory). @item "lh" -is owned by the user with name "lh". +is owned by the user with name @samp{lh}. @item "users" -is in the group with name "users". +is in the group with name @samp{users}. @item (20614 64019 50040 152000) was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. @@ -1339,52 +1324,99 @@ is on the file-system device whose number is 1014478468. @end table @end defun -@cindex SELinux context - SELinux is a Linux kernel feature which provides more sophisticated -file access controls than ordinary ``Unix-style'' file permissions. -If Emacs has been compiled with SELinux support on a system with -SELinux enabled, you can use the function @code{file-selinux-context} -to retrieve a file's SELinux security context. For the function -@code{set-file-selinux-context}, see @ref{Changing Files}. +@defun file-nlinks filename +This function returns the number of names (i.e., hard links) that +file @var{filename} has. If the file does not exist, this function +returns @code{nil}. Note that symbolic links have no effect on this +function, because they are not considered to be names of the files +they link to. -@defun file-selinux-context filename -This function returns the SELinux security context of the file -@var{filename}. This return value is a list of the form -@code{(@var{user} @var{role} @var{type} @var{range})}, whose elements -are the context's user, role, type, and range respectively, as Lisp -strings. See the SELinux documentation for details about what these -actually mean. +@example +@group +$ ls -l foo* +-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo +-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1 +@end group -If the file does not exist or is inaccessible, or if the system does -not support SELinux, or if Emacs was not compiled with SELinux -support, then the return value is @code{(nil nil nil nil)}. +@group +(file-nlinks "foo") + @result{} 2 +@end group +@group +(file-nlinks "doesnt-exist") + @result{} nil +@end group +@end example @end defun +@node Extended Attributes +@subsection Extended File Attributes +@cindex extended file attributes + +On some operating systems, each file can be associated with arbitrary +@dfn{extended file attributes}. At present, Emacs supports querying +and setting two specific sets of extended file attributes: Access +Control Lists (ACLs) and SELinux contexts. These extended file +attributes are used, on some systems, to impose more sophisticated +file access controls than the basic Unix-style permissions +discussed in the previous sections. + @cindex access control list @cindex ACL entries - If Emacs has been compiled with @dfn{ACL} (access control list) -support, you can use the function @code{file-acl} to retrieve a file's -ACL entries. The interface implementation is platform-specific; on -GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on -MS-Windows Emacs emulates the POSIX ACL interface with native file -security APIs. +@cindex SELinux context + A detailed explanation of ACLs and SELinux is beyond the scope of +this manual. For our purposes, each file can be associated with an +@dfn{ACL}, which specifies its properties under an ACL-based file +control system, and/or an @dfn{SELinux context}, which specifies its +properties under the SELinux system. @defun file-acl filename -This function returns the ACL entries of the file @var{filename}. The -return value is a platform-dependent object containing some -representation of the ACL entries. Don't use it for anything except -passing it to the @code{set-file-acl} function (@pxref{Changing Files, -set-file-acl}). +This function returns the ACL for the file @var{filename}. The exact +Lisp representation of the ACL is unspecified (and may change in +future Emacs versions), but it is the same as what @code{set-file-acl} +takes for its @var{acl} argument (@pxref{Changing Files}). -If the file does not exist or is inaccessible, or if Emacs was unable to -determine the ACL entries, then the return value is @code{nil}. The -latter can happen for local files if Emacs was not compiled with ACL -support, or for remote files if the file handler returns nil for the -file's ACL entries. +The underlying ACL implementation is platform-specific; on GNU/Linux +and BSD, Emacs uses the POSIX ACL interface, while on MS-Windows Emacs +emulates the POSIX ACL interface with native file security APIs. + +If Emacs was not compiled with ACL support, or the file does not exist +or is inaccessible, or Emacs was unable to determine the ACL entries +for any other reason, then the return value is @code{nil}. +@end defun + +@defun file-selinux-context filename +This function returns the SELinux context of the file @var{filename}, +as a list of the form @code{(@var{user} @var{role} @var{type} +@var{range})}. The list elements are the context's user, role, type, +and range respectively, as Lisp strings; see the SELinux documentation +for details about what these actually mean. The return value has the +same form as what @code{set-file-selinux-context} takes for its +@var{context} argument (@pxref{Changing Files}). + +If Emacs was not compiled with SELinux support, or the file does not +exist or is inaccessible, or if the system does not support SELinux, +then the return value is @code{(nil nil nil nil)}. +@end defun + +@defun file-extended-attributes filename +This function returns an alist of the Emacs-recognized extended +attributes of file @var{filename}. Currently, it serves as a +convenient way to retrieve both the ACL and SELinux context; you can +then call the function @code{set-file-extended-attributes}, with the +returned alist as its second argument, to apply the same file access +attributes to another file (@pxref{Changing Files}). + +One of the elements is @code{(acl . @var{acl})}, where @var{acl} has +the same form returned by @code{file-acl}. + +Another element is @code{(selinux-context . @var{context})}, where +@var{context} is the SELinux context, in the same form returned by +@code{file-selinux-context}. @end defun @node Locating Files -@subsection How to Locate Files in Standard Places +@subsection Locating Files in Standard Places @cindex locate file in path @cindex find file in path @@ -1449,7 +1481,10 @@ in @code{exec-path}, and tries all the file-name extensions in @cindex setting modes of files The functions in this section rename, copy, delete, link, and set -the modes (permissions) of files. +the modes (permissions) of files. They all signal a @code{file-error} +error if they fail to perform their function, reporting the +system-dependent error message that describes the reason for the +failure. In the functions that have an argument @var{newname}, if a file by the name of @var{newname} already exists, the actions taken depend on the @@ -1477,8 +1512,8 @@ replaces it with its (recursive) target. @cindex file with multiple names @cindex file hard link This function gives the file named @var{oldname} the additional name -@var{newname}. This means that @var{newname} becomes a new ``hard -link'' to @var{oldname}. +@var{newname}. This means that @var{newname} becomes a new hard +link to @var{oldname}. In the first part of the following example, we list two files, @file{foo} and @file{foo3}. @@ -1550,7 +1585,7 @@ with @code{add-name-to-file} and then deleting @var{filename} has the same effect as renaming, aside from momentary intermediate states. @end deffn -@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-selinux +@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-extended-attributes This command copies the file @var{oldname} to @var{newname}. An error is signaled if @var{oldname} does not exist. If @var{newname} names a directory, it copies @var{oldname} into that directory, @@ -1563,8 +1598,6 @@ some operating systems.) If setting the time gets an error, interactive call, a prefix argument specifies a non-@code{nil} value for @var{time}. -This function copies the file modes, too. - If argument @var{preserve-uid-gid} is @code{nil}, we let the operating system decide the user and group ownership of the new file (this is usually set to the user running Emacs). If @var{preserve-uid-gid} is @@ -1572,10 +1605,16 @@ non-@code{nil}, we attempt to copy the user and group ownership of the file. This works only on some operating systems, and only if you have the correct permissions to do so. -If the optional argument @var{preserve-extended-attributes} is -non-@code{nil}, and Emacs has been built with the appropriate support, -this function attempts to copy the file's extended attributes, such as -its SELinux context and ACL entries (@pxref{File Attributes}). +If the optional argument @var{preserve-permissions} is non-@code{nil}, +this function copies the file modes (or ``permissions'') of +@var{oldname} to @var{newname}, as well as the Access Control List and +SELinux context (if any). @xref{Information about Files}. + +Otherwise, the file modes of @var{newname} are left unchanged if it is +an existing file, and set to those of @var{oldname}, masked by the +default file permissions (see @code{set-default-file-modes} below), if +@var{newname} is to be newly created. The Access Control List or +SELinux context are not copied over in either case. @end deffn @deffn Command make-symbolic-link filename newname &optional ok-if-exists @@ -1617,7 +1656,7 @@ See also @code{delete-directory} in @ref{Create/Delete Dirs}. @cindex permissions, file @cindex file modes, setting @deffn Command set-file-modes filename mode -This function sets the @dfn{file mode} (or @dfn{file permissions}) of +This function sets the @dfn{file mode} (or @dfn{permissions}) of @var{filename} to @var{mode}. It recursively follows symbolic links at all levels for @var{filename}. @@ -1646,13 +1685,12 @@ returns the permissions of a file. @defun set-default-file-modes mode @cindex umask -This function sets the default file permissions for new files created -by Emacs and its subprocesses. Every file created with Emacs -initially has these permissions, or a subset of them -(@code{write-region} will not grant execute permissions even if the -default file permissions allow execution). On Unix and GNU/Linux, the -default permissions are given by the bitwise complement of the -``umask'' value. +This function sets the default permissions for new files created by +Emacs and its subprocesses. Every file created with Emacs initially +has these permissions, or a subset of them (@code{write-region} will +not grant execute permissions even if the default file permissions +allow execution). On Unix and GNU/Linux, the default permissions are +given by the bitwise complement of the @samp{umask} value. The argument @var{mode} should be an integer which specifies the permissions, similar to @code{set-file-modes} above. Only the lowest @@ -1663,6 +1701,16 @@ version of an existing file; saving a file preserves its existing permissions. @end defun +@defmac with-file-modes mode body@dots{} +This macro evaluates the @var{body} forms with the default +permissions for new files temporarily set to @var{modes} (whose value +is as for @code{set-file-modes} above). When finished, it restores +the original default file permissions, and returns the value of the +last form in @var{body}. + +This is useful for creating private files, for example. +@end defmac + @defun default-file-modes This function returns the default file permissions, as an integer. @end defun @@ -1691,7 +1739,7 @@ specifications. @defun file-modes-symbolic-to-number modes &optional base-modes This function converts a symbolic file mode specification in -@var{modes} into the equivalent integer value. If the symbolic +@var{modes} into the equivalent integer. If the symbolic specification is based on an existing file, that file's mode bits are taken from the optional argument @var{base-modes}; if that argument is omitted or @code{nil}, it defaults to 0, i.e., no access rights at @@ -1706,25 +1754,33 @@ time and must be in the format returned by @code{current-time} (@pxref{Time of Day}). @end defun +@defun set-file-extended-attributes filename attribute-alist +This function sets the Emacs-recognized extended file attributes for +@code{filename}. The second argument @var{attribute-alist} should be +an alist of the same form returned by @code{file-extended-attributes}. +The return value is @code{t} if the attributes are successfully set, +otherwise it is @code{nil}. +@xref{Extended Attributes}. +@end defun + @defun set-file-selinux-context filename context -This function sets the SELinux security context of the file -@var{filename} to @var{context}. @xref{File Attributes}, for a brief -description of SELinux contexts. The @var{context} argument should be -a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the -return value of @code{file-selinux-context}. The function returns -@code{t} if it succeeds to set the SELinux security context of -@var{filename}, @code{nil} otherwise. The function does nothing and -returns @code{nil} if SELinux is disabled, or if Emacs was compiled -without SELinux support. -@end defun - -@defun set-file-acl filename acl-string -This function sets the ACL entries of the file @var{filename} to -@var{acl-string}. @xref{File Attributes}, for a brief description of -ACLs. The @var{acl-string} argument should be a string containing the -textual representation of the desired ACL entries as returned by -@code{file-acl} (@pxref{File Attributes, file-acl}). The function -returns @code{t} if it succeeds to set the ACL entries of +This function sets the SELinux security context for @var{filename} to +@var{context}. The @var{context} argument should be a list +@code{(@var{user} @var{role} @var{type} @var{range})}, where each +element is a string. @xref{Extended Attributes}. + +The function returns @code{t} if it succeeds in setting the SELinux +context of @var{filename}. It returns @code{nil} if the context was +not set (e.g., if SELinux is disabled, or if Emacs was compiled +without SELinux support). +@end defun + +@defun set-file-acl filename acl +This function sets the Access Control List for @var{filename} to +@var{acl}. The @var{acl} argument should have the same form returned +by the function @code{file-acl}. @xref{Extended Attributes}. + +The function returns @code{t} if it successfully sets the ACL of @var{filename}, @code{nil} otherwise. @end defun @@ -1857,7 +1913,7 @@ return value, but backup version numbers are kept. @end defun @defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension'', if any, +This function returns @var{filename}'s final extension, if any, after applying @code{file-name-sans-versions} to remove any version/backup part. The extension, in a file name, is the part that follows the last @samp{.} in the last name component (minus any @@ -1867,7 +1923,7 @@ This function returns @code{nil} for extensionless file names such as @file{foo}. It returns @code{""} for null extensions, as in @file{foo.}. If the last component of a file name begins with a @samp{.}, that @samp{.} doesn't count as the beginning of an -extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not +extension. Thus, @file{.emacs}'s extension is @code{nil}, not @samp{.emacs}. If @var{period} is non-@code{nil}, then the returned value includes @@ -1974,35 +2030,43 @@ form. @end example @end defun +@defun directory-name-p filename +This function returns non-@code{nil} if @var{filename} ends with a +forward slash (@samp{/}) character. +@end defun + @node Directory Names @subsection Directory Names @cindex directory name +@cindex directory file name @cindex file name of directory A @dfn{directory name} is the name of a directory. A directory is -actually a kind of file, so it has a file name, which is related to -the directory name but not identical to it. (This is not quite the -same as the usual Unix terminology.) These two different names for -the same entity are related by a syntactic transformation. On GNU and -Unix systems, this is simple: a directory name ends in a slash, -whereas the directory's name as a file lacks that slash. On MS-DOS -the relationship is more complicated. - - The difference between a directory name and its name as a file is +actually a kind of file, so it has a file name (called the +@dfn{directory file name}, which is related to the directory name but +not identical to it. (This is not quite the same as the usual Unix +terminology.) These two different names for the same entity are +related by a syntactic transformation. On GNU and Unix systems, this +is simple: a directory name ends in a slash, whereas the directory +file name lacks that slash. On MS-DOS the relationship is more +complicated. + + The difference between directory name and directory file name is subtle but crucial. When an Emacs variable or function argument is -described as being a directory name, a file name of a directory is not +described as being a directory name, a directory file name is not acceptable. When @code{file-name-directory} returns a string, that is always a directory name. - The following two functions convert between directory names and file -names. They do nothing special with environment variable substitutions -such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. + The following two functions convert between directory names and +directory file names. They do nothing special with environment +variable substitutions such as @samp{$HOME}, and the constructs +@samp{~}, @samp{.} and @samp{..}. @defun file-name-as-directory filename This function returns a string representing @var{filename} in a form -that the operating system will interpret as the name of a directory. On -most systems, this means appending a slash to the string (if it does not -already end in one). +that the operating system will interpret as the name of a directory (a +directory name). On most systems, this means appending a slash to the +string (if it does not already end in one). @example @group @@ -2013,10 +2077,10 @@ already end in one). @end defun @defun directory-file-name dirname -This function returns a string representing @var{dirname} in a form that -the operating system will interpret as the name of a file. On most -systems, this means removing the final slash (or backslash) from the -string. +This function returns a string representing @var{dirname} in a form +that the operating system will interpret as the name of a file (a +directory file name). On most systems, this means removing the final +slash (or backslash) from the string. @example @group @@ -2058,6 +2122,13 @@ Don't try concatenating a slash by hand, as in because this is not portable. Always use @code{file-name-as-directory}. + To avoid the issues mentioned above, or if the @var{dirname} value +might be nil (for example, from an element of @code{load-path}), use: + +@example +(expand-file-name @var{relfile} @var{dirname}) +@end example + To convert a directory name to its abbreviation, use this function: @@ -2142,7 +2213,7 @@ In some cases, a leading @samp{..} component can remain in the output: @noindent This is for the sake of filesystems that have the concept of a -``superroot'' above the root directory @file{/}. On other filesystems, +superroot above the root directory @file{/}. On other filesystems, @file{/../} is interpreted exactly the same as @file{/}. Note that @code{expand-file-name} does @emph{not} expand environment @@ -2201,7 +2272,7 @@ This function replaces environment variable references in @var{filename} with the environment variable values. Following standard Unix shell syntax, @samp{$} is the prefix to substitute an environment variable value. If the input contains @samp{$$}, that is -converted to @samp{$}; this gives the user a way to ``quote'' a +converted to @samp{$}; this gives the user a way to quote a @samp{$}. The environment variable name is the series of alphanumeric characters @@ -2249,6 +2320,8 @@ through the immediately preceding @samp{/}). @node Unique File Names @subsection Generating Unique File Names +@cindex unique file names +@cindex temporary files Some programs need to write temporary files. Here is the usual way to construct a name for such a file: @@ -2378,7 +2451,7 @@ buffer's default directory is prepended to @var{directory}, if In the following example, suppose that @file{~rms/lewis} is the current default directory, and has five files whose names begin with @samp{f}: @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill +@file{file.c.~2~}. @example @group @@ -2409,7 +2482,7 @@ function returns @code{t}. The function returns @code{nil} if directory In the following example, suppose that the current default directory has five files whose names begin with @samp{f}: @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill +@file{file.c.~2~}. @example @group @@ -2438,7 +2511,7 @@ has five files whose names begin with @samp{f}: @file{foo}, @code{file-name-completion} usually ignores file names that end in any string in this list. It does not ignore them when all the possible completions end in one of these suffixes. This variable has no effect -on @code{file-name-all-completions}.@refill +on @code{file-name-all-completions}. A typical value might look like this: @@ -2559,6 +2632,14 @@ An error is signaled if @var{directory} is not the name of a directory that can be read. @end defun +@defun directory-files-recursively directory match &optional include-directories +Return all files under @var{directory} whose file names match +@var{match} recursively. The file names are returned depth first, +meaning that contents of sub-directories are returned before contents +of the directories. If @var{include-directories} is non-@code{nil}, +also return directory names that have matching names. +@end defun + @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format This is similar to @code{directory-files} in deciding which files to report on and how to report their names. However, instead @@ -2788,6 +2869,7 @@ first, before handlers for jobs such as remote file access. @code{file-name-nondirectory}, @code{file-name-sans-versions}, @code{file-newer-than-file-p}, @code{file-notify-add-watch}, @code{file-notify-rm-watch}, +@code{file-notify-valid-p}, @code{file-ownership-preserved-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, @@ -2841,6 +2923,7 @@ first, before handlers for jobs such as remote file access. @code{file-name-nondirec@discretionary{}{}{}tory}, @code{file-name-sans-versions}, @code{file-newer-than-file-p}, @code{file-notify-add-watch}, @code{file-notify-rm-watch}, +@code{file-notify-valid-p}, @code{file-ownership-pre@discretionary{}{}{}served-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, @@ -2877,7 +2960,7 @@ unlocking the buffer if it is locked. possibly others to be added in the future. It need not implement all these operations itself---when it has nothing special to do for a certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way''. It should always reinvoke the primitive +operation in the usual way. It should always reinvoke the primitive for an operation it does not recognize. Here's one way to do this: @smallexample @@ -2910,7 +2993,7 @@ each have handlers. Handlers that don't really do anything special for actual access to the file---such as the ones that implement completion of host names for remote file names---should have a non-@code{nil} @code{safe-magic} -property. For instance, Emacs normally ``protects'' directory names +property. For instance, Emacs normally protects directory names it finds in @code{PATH} from becoming magic, if they look like magic file names, by prefixing them with @samp{/:}. But if the handler that would be used for them has a non-@code{nil} @code{safe-magic} @@ -2998,12 +3081,12 @@ making connections when they don't exist. @end defun @defun unhandled-file-name-directory filename -This function returns the name of a directory that is not magic. It -uses the directory part of @var{filename} if that is not magic. For a -magic file name, it invokes the file name handler, which therefore -decides what value to return. If @var{filename} is not accessible -from a local process, then the file name handler should indicate it by -returning @code{nil}. +This function returns the name of a directory that is not magic. For +a non-magic @var{filename} it returns the corresponding directory name +(@pxref{Directory Names}). For a magic @var{filename}, it invokes the +file name handler, which therefore decides what value to return. If +@var{filename} is not accessible from a local process, then the file +name handler should indicate that by returning @code{nil}. This is useful for running a subprocess; every subprocess must have a non-magic directory to serve as its current directory, and this function @@ -3286,8 +3369,8 @@ from the buffer is actually written to the file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer. -@c ??? What about ``overriding'' conversions like those allowed -@c ??? for `write-region-annotate-functions', below? --ttn +@c ??? What about "overriding" conversions like those allowed +@c ??? for 'write-region-annotate-functions', below? --ttn In contrast, when reading, the annotations intermixed with the text are handled immediately. @code{insert-file-contents} sets point to @@ -3340,8 +3423,8 @@ with one argument, the number of characters inserted, and with point at the beginning of the inserted text. Each function should leave point unchanged, and return the new character count describing the inserted text as modified by the function. -@c ??? The docstring mentions a handler from `file-name-handler-alist' -@c "intercepting" `insert-file-contents'. Hmmm. --ttn +@c ??? The docstring mentions a handler from 'file-name-handler-alist' +@c "intercepting" 'insert-file-contents'. Hmmm. --ttn @end defvar We invite users to write Lisp programs to store and retrieve text diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 370098c8b62..3ae33082fc4 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Frames @@ -80,6 +80,7 @@ for @code{framep} above. @menu * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. +* Frame Geometry:: Geometric properties of frames. * Frame Parameters:: Controlling frame size, position, font, etc. * Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. @@ -106,6 +107,7 @@ for @code{framep} above. @node Creating Frames @section Creating Frames +@cindex frame creation To create a new frame, call the function @code{make-frame}. @@ -131,6 +133,13 @@ applies any parameters listed in @code{frame-inherited-parameters} (see below) and not present in the argument, taking the values from the frame that was selected when @code{make-frame} was called. +Note that on multi-monitor displays (@pxref{Multiple Terminals}), the +window manager might position the frame differently than specified by +the positional parameters in @var{alist} (@pxref{Position +Parameters}). For example, some window managers have a policy of +displaying the frame on the monitor that contains the largest part of +the window (a.k.a.@: the @dfn{dominating} monitor). + This function itself does not make the new frame the selected frame. @xref{Input Focus}. The previously selected frame remains selected. On graphical terminals, however, the windowing system may select the @@ -253,30 +262,40 @@ variable, or by the @samp{--display} option (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). Emacs can connect to other X displays via the command @code{make-frame-on-display}. Each X display has its own selected frame and its own minibuffer windows; however, only one -of those frames is ``@emph{the} selected frame'' at any given moment +of those frames is @emph{the} selected frame at any given moment (@pxref{Input Focus}). Emacs can even connect to other text terminals, by interacting with the @command{emacsclient} program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@cindex X display names +@cindex display name on X A single X server can handle more than one display. Each X display -has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}. -The first two parts, @var{host} and @var{server}, identify the X -server; the third part, @var{screen}, identifies a screen number on -that X server. When you use two or more screens belonging to one -server, Emacs knows by the similarity in their names that they share a -single keyboard. - - On some ``multi-monitor'' setups, a single X display outputs to more -than one physical monitor. Currently, there is no way for Emacs to -distinguish between the different physical monitors. +has a three-part name, +@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}. The +first part, @var{hostname}, specifies the name of the machine to which +the display is physically connected. The second part, +@var{displaynumber}, is a zero-based number that identifies one or +more monitors connected to that machine that share a common keyboard +and pointing device (mouse, tablet, etc.). The third part, +@var{screennumber}, identifies a zero-based screen number (a separate +monitor) that is part of a single monitor collection on that X server. +When you use two or more screens belonging to one server, Emacs knows +by the similarity in their names that they share a single keyboard. + + Systems that don't use the X window system, such as MS-Windows, +don't support the notion of X displays, and have only one display on +each host. The display name on these systems doesn't follow the above +3-part format; for example, the display name on MS-Windows systems is +a constant string @samp{w32}, and exists for compatibility, so that +you could pass it to functions that expect a display name. @deffn Command make-frame-on-display display &optional parameters This function creates and returns a new frame on @var{display}, taking the other frame parameters from the alist @var{parameters}. @var{display} should be the name of an X display (a string). -Before creating the frame, this function ensures that Emacs is ``set -up'' to display graphics. For instance, if Emacs has not processed X +Before creating the frame, this function ensures that Emacs is set +up to display graphics. For instance, if Emacs has not processed X resources (e.g., if it was started on a text terminal), it does so at this time. In all other respects, this function behaves like @code{make-frame} (@pxref{Creating Frames}). @@ -316,6 +335,627 @@ you can do this, you must first delete all the frames that were open on that display (@pxref{Deleting Frames}). @end defun +@cindex multi-monitor + On some multi-monitor setups, a single X display outputs to more +than one physical monitor. You can use the functions +@code{display-monitor-attributes-list} and @code{frame-monitor-attributes} +to obtain information about such setups. + +@defun display-monitor-attributes-list &optional display +This function returns a list of physical monitor attributes on +@var{display}, which can be a display name (a string), a terminal, or +a frame; if omitted or @code{nil}, it defaults to the selected frame's +display. Each element of the list is an association list, +representing the attributes of a physical monitor. The first element +corresponds to the primary monitor. The attribute keys and values +are: + +@table @samp +@item geometry +Position of the top-left corner of the monitor's screen and its size, +in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}. Note +that, if the monitor is not the primary monitor, some of the +coordinates might be negative. + +@item workarea +Position of the top-left corner and size of the work area (usable +space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}. +This may be different from @samp{geometry} in that space occupied by +various window manager features (docks, taskbars, etc.)@: may be +excluded from the work area. Whether or not such features actually +subtract from the work area depends on the platform and environment. +Again, if the monitor is not the primary monitor, some of the +coordinates might be negative. + +@item mm-size +Width and height in millimeters as @samp{(@var{width} @var{height})} + +@item frames +List of frames that this physical monitor dominates (see below). + +@item name +Name of the physical monitor as @var{string}. + +@item source +Source of the multi-monitor information as @var{string}; +e.g., @samp{XRandr} or @samp{Xinerama}. +@end table + +@var{x}, @var{y}, @var{width}, and @var{height} are integers. +@samp{name} and @samp{source} may be absent. + +A frame is @dfn{dominated} by a physical monitor when either the +largest area of the frame resides in that monitor, or (if the frame +does not intersect any physical monitors) that monitor is the closest +to the frame. Every (non-tooltip) frame (whether visible or not) in a +graphical display is dominated by exactly one physical monitor at a +time, though the frame can span multiple (or no) physical monitors. + +Here's an example of the data produced by this function on a 2-monitor +display: + +@lisp + (display-monitor-attributes-list) + @result{} + (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor} + (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height} + (mm-size 677 381) + (name . "DISPLAY1") + (frames #<frame emacs@@host *Messages* 0x11578c0> + #<frame emacs@@host *scratch* 0x114b838>)) + ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor} + (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used} + (mm-size 593 370) + (name . "DISPLAY2") + (frames))) +@end lisp + +@end defun + +@defun frame-monitor-attributes &optional frame +This function returns the attributes of the physical monitor +dominating (see above) @var{frame}, which defaults to the selected frame. +@end defun + + +@node Frame Geometry +@section Frame Geometry +@cindex frame geometry +@cindex frame position +@cindex position of frame +@cindex frame size +@cindex size of frame + +The geometry of a frame depends on the toolkit that was used to build +this instance of Emacs and the terminal that displays the frame. This +chapter describes these dependencies and some of the functions to deal +with them. Note that the @var{frame} argument of all of these functions +has to specify a live frame (@pxref{Deleting Frames}). If omitted or +@code{nil}, it specifies the selected frame (@pxref{Input Focus}). + +@menu +* Frame Layout:: Basic layout of frames. +* Frame Font:: The default font of a frame and how to set it. +* Size and Position:: Changing the size and position of a frame. +* Implied Frame Resizing:: Implied resizing of frames and how to prevent it. +@end menu + + +@node Frame Layout +@subsection Frame Layout +@cindex frame layout +@cindex layout of frame + +The drawing below sketches the layout of a frame on a graphical +terminal: +@smallexample +@group + + <------------ Outer Frame Width -----------> + ___________________________________________ + ^(0) ___________ External Border __________ | + | | |_____________ Title Bar ______________| | + | | (1)_____________ Menu Bar ______________| | ^ + | | (2)_____________ Tool Bar ______________| | ^ + | | (3) _________ Internal Border ________ | | ^ + | | | | ^ | | | | + | | | | | | | | | +Outer | | | Inner | | | Native +Frame | | | Frame | | | Frame +Height | | | Height | | | Height + | | | | | | | | | + | | | |<--+--- Inner Frame Width ------->| | | | + | | | | | | | | | + | | | |___v______________________________| | | | + | | |___________ Internal Border __________| | v + v |______________ External Border _____________| + <-------- Native Frame Width --------> + +@end group +@end smallexample + +In practice not all of the areas shown in the drawing will or may be +present. The meaning of these areas is: + +@table @samp +@item Outer Frame +@cindex outer frame +@cindex outer edges +@cindex outer width +@cindex outer height +The @dfn{outer frame} is a rectangle comprising all areas shown in the +drawing. The edges of that rectangle are called the @dfn{outer edges} +of the frame. The @dfn{outer width} and @dfn{outer height} of the frame +specify the size of that rectangle. + +@cindex outer position +The upper left corner of the outer frame (indicated by @samp{(0)} in the +drawing above) is the @dfn{outer position} or the frame. It is +specified by and settable via the @code{left} and @code{top} frame +parameters (@pxref{Position Parameters}) as well as the functions +@code{frame-position} and @code{set-frame-position} (@pxref{Size and +Position}). + +@item External Border +@cindex external border +The @dfn{external border} is part of the decorations supplied by the +window manager. It's typically used for resizing the frame with the +mouse. The external border is normally not shown on ``fullboth'' and +maximized frames (@pxref{Size Parameters}) and doesn't exist for text +terminal frames. + + The external border should not be confused with the @dfn{outer +border} specified by the @code{border-width} frame parameter +(@pxref{Layout Parameters}). Since the outer border is usually ignored +on most platforms it is not covered here. + +@item Title Bar +@cindex title bar +The @dfn{title bar} is also part of the window manager's decorations and +typically displays the title of the frame (@pxref{Frame Titles}) as well +as buttons for minimizing, maximizing and deleting the frame. The title +bar is usually not displayed on fullboth (@pxref{Size Parameters}) +or tooltip frames. Title bars don't exist for text terminal frames. + +@item Menu Bar +@cindex internal menu bar +@cindex external menu bar +The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs +itself) or external (drawn by a toolkit). Most builds (GTK+, Lucid, +Motif and Windows) rely on an external menu bar. NS also uses an +external menu bar which, however, is not part of the outer frame. +Non-toolkit builds can provide an internal menu bar. On text terminal +frames, the menu bar is part of the frame's root window (@pxref{Windows +and Frames}). + +@item Tool Bar +@cindex internal tool bar +@cindex external tool bar +Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either +internal (drawn by Emacs itself) or external (drawn by a toolkit). The +GTK+ and NS builds have the tool bar drawn by the toolkit. The +remaining builds use internal tool bars. With GTK+ the tool bar can be +located on either side of the frame, immediately outside the internal +border, see below. + +@item Native Frame +@cindex native frame +@cindex native edges +@cindex native width +@cindex native height +@cindex display area +The @dfn{native frame} is a rectangle located entirely within the outer +frame. It excludes the areas occupied by the external border, the title +bar and any external menu or external tool bar. The area enclosed by +the native frame is sometimes also referred to as the @dfn{display area} +of the frame. The edges of the native frame are called the @dfn{native +edges} of the frame. The @dfn{native width} and @dfn{native height} of +the frame specify the size of the rectangle. + +@cindex native position +The top left corner of the native frame specifies the @dfn{native +position} of the frame. (1)--(3) in the drawing above indicate that +position for the various builds: + +@itemize @w +@item (1) non-toolkit and terminal frames + +@item (2) Lucid, Motif and Windows frames + +@item (3) GTK+ and NS frames +@end itemize + +Accordingly, the native height of a frame includes the height of the +tool bar but not that of the menu bar (Lucid, Motif, Windows) or those +of the menu bar and the tool bar (non-toolkit and text terminal frames). + +The native position of a frame is the reference position of functions +that set or return the current position of the mouse (@pxref{Mouse +Position}) and for functions dealing with the position of windows like +@code{window-edges}, @code{window-at} or @code{coordinates-in-window-p} +(@pxref{Coordinates and Windows}). + +@item Internal Border +The internal border (@pxref{Layout Parameters}) is a border drawn by +Emacs around the inner frame (see below). + +@item Inner Frame +@cindex inner frame +@cindex inner edges +@cindex inner width +@cindex inner height +The @dfn{inner frame} is the rectangle reserved for the frame's windows. +It's enclosed by the internal border which, however, is not part of the +inner frame. Its edges are called the @dfn{inner edges} of the frame. +The @dfn{inner width} and @dfn{inner height} specify the size of the +rectangle. + +@cindex minibuffer-less frame +@cindex minibuffer-only frame +As a rule, the inner frame is subdivided into the frame's root window +(@pxref{Windows and Frames}) and the frame's minibuffer window +(@pxref{Minibuffer Windows}). There are two notable exceptions to this +rule: A @dfn{minibuffer-less frame} contains a root window only and does +not contain a minibuffer window. A @dfn{minibuffer-only frame} contains +only a minibuffer window which also serves as that frame's root window. +See @ref{Initial Parameters} for how to create such frame +configurations. + +@item Text Area +@cindex text area +The @dfn{text area} of a frame is a somewhat fictitious area located +entirely within the native frame. It can be obtained by removing from +the native frame any internal borders, one vertical and one horizontal +scroll bar, and one left and one right fringe as specified for this +frame, see @ref{Layout Parameters}. +@end table + +@cindex absolute position +The @dfn{absolute position} of a frame or its edges is usually given in +terms of pixels counted from an origin at position (0, 0) of the frame's +display. Note that with multiple monitors the origin does not +necessarily coincide with the top left corner of the entire usable +display area. Hence the absolute outer position of a frame or the +absolute positions of the edges of the outer, native or inner frame can +be negative in such an environment even when that frame is completely +visible. + + For a frame on a graphical terminal the following function returns the +sizes of the areas described above: + +@defun frame-geometry &optional frame +This function returns geometric attributes of @var{frame}. The return +value is an association list of the attributes listed below. All +coordinate, height and width values are integers counting pixels. + +@table @code +@item outer-position +A cons of the absolute X- and Y-coordinates of the outer position of +@var{frame}, relative to the origin at position (0, 0) of @var{frame}'s +display. + +@item outer-size +A cons of the outer width and height of @var{frame}. + +@item external-border-size +A cons of the horizontal and vertical width of @var{frame}'s external +borders as supplied by the window manager. If the window manager +doesn't supply these values, Emacs will try to guess them from the +coordinates of the outer and inner frame. + +@item title-bar-size +A cons of the width and height of the title bar of @var{frame} as +supplied by the window manager or operating system. If both of them are +zero, the frame has no title bar. If only the width is zero, Emacs was +not able to retrieve the width information. + +@item menu-bar-external +If non-@code{nil}, this means the menu bar is external (not part of the +native frame of @var{frame}). + +@item menu-bar-size +A cons of the width and height of the menu bar of @var{frame}. + +@item tool-bar-external +If non-@code{nil}, this means the tool bar is external (not part of the +native frame of @var{frame}). + +@item tool-bar-position +This tells on which side the tool bar on @var{frame} is and can be one +of @code{left}, @code{top}, @code{right} or @code{bottom}. The only +toolkit that currently supports a value other than @code{top} is GTK+. + +@item tool-bar-size +A cons of the width and height of the tool bar of @var{frame}. + +@item internal-border-width +The width of the internal border of @var{frame}. +@end table +@end defun + +The following function can be used to retrieve the edges of the outer, +native and inner frame. + +@defun frame-edges &optional frame type +This function returns the edges of the outer, native or inner frame of +@var{frame}. @var{frame} must be a live frame and defaults to the +selected one. The list returned has the form (@var{left} @var{top} +@var{right} @var{bottom}) where all values are in pixels relative to the +position (0, 0) of @var{frame}'s display. For terminal frames +@var{left} and @var{top} are both zero. + +Optional argument @var{type} specifies the type of the edges to return: +@var{type} @code{outer-edges} means to return the outer edges of +@var{frame}, @code{native-edges} (or @code{nil}) means to return its +native edges and @code{inner-edges} means to return its inner edges. + +Notice that the pixels at the positions @var{bottom} and @var{right} +lie immediately outside the corresponding frame. This means that if you +have, for example, two side-by-side frames positioned such that the +right outer edge of the frame on the left equals the left outer edge of +the frame on the right, the pixels representing that edge are part +of the frame on the right. +@end defun + + +@node Frame Font +@subsection Frame Font +@cindex default font +@cindex default character size +@cindex default character width +@cindex default width of character +@cindex default character height +@cindex default height of character +Each frame has a @dfn{default font} which specifies the default +character size for that frame. This size is meant when retrieving or +changing the size of a frame in terms of columns or lines +(@pxref{Size Parameters}). It is also used when resizing (@pxref{Window +Sizes}) or splitting (@pxref{Splitting Windows}) windows. + +@cindex line height +@cindex column width +The term @dfn{line height} is sometimes used instead of ``default +character height''. Similarly, the term @dfn{column width} is used as +shorthand for ``default character width''. + +@defun frame-char-height &optional frame +@defunx frame-char-width &optional frame +These functions return the default height and width of a character in +@var{frame}, measured in pixels. Together, these values establish the +size of the default font on @var{frame}. The values depend on the +choice of font for @var{frame}, see @ref{Font and Color Parameters}. +@end defun + +The default font can be also set directly with the following function: + +@deffn Command set-frame-font font &optional keep-size frames +This sets the default font to @var{font}. When called interactively, it +prompts for the name of a font, and uses that font on the selected +frame. When called from Lisp, @var{font} should be a font name (a +string), a font object, font entity, or a font spec. + +If the optional argument @var{keep-size} is @code{nil}, this keeps the +number of frame lines and columns fixed. (If non-@code{nil}, the option +@code{frame-inhibit-implied-resize} described in the next section will +override this.) If @var{keep-size} is non-@code{nil} (or with a prefix +argument), it tries to keep the size of the display area of the current +frame fixed by adjusting the number of lines and columns. + +If the optional argument @var{frames} is @code{nil}, this applies the +font to the selected frame only. If @var{frames} is non-@code{nil}, it +should be a list of frames to act upon, or @code{t} meaning all existing +and all future graphical frames. +@end deffn + + +@node Size and Position +@subsection Size and Position +@cindex frame size +@cindex frame position +@cindex position of frame + +You can read or change the position of a frame using the frame +parameters @code{left} and @code{top} (@pxref{Position Parameters}) and +its size using the @code{height} and @code{width} parameters +(@pxref{Size Parameters}). Here are some special features for working +with sizes and positions. For all of these functions the argument +@var{frame} must denote a live frame and defaults to the selected frame. + +@defun frame-position &optional Lisp_Object &optional frame +This function returns the outer position (@pxref{Frame Layout}) of +@var{frame} in pixels. The value is a cons giving the coordinates of +the top left corner of the outer frame of @var{frame} relative to an +origin at the position (0, 0) of the frame's display. On a text +terminal frame both values are zero. +@end defun + +@defun set-frame-position frame X Y +This function sets the outer frame position of @var{frame} to @var{X} +and @var{Y}. The latter arguments specify pixels and normally count +from an origin at the position (0, 0) of @var{frame}'s display. + +A negative parameter value positions the right edge of the outer frame +by @var{-x} pixels left from the right edge of the screen or the bottom +edge by @var{-y} pixels up from the bottom edge of the screen. + +This function has no effect on text terminal frames. +@end defun + +@defun frame-pixel-height &optional frame +@defunx frame-pixel-width &optional frame + These functions return the inner height and width (the height and +width of the display area, see @ref{Frame Layout}) of @var{frame} in +pixels. For a text terminal, the results are in characters rather than +pixels. +@end defun + +@defun frame-text-height &optional frame +@defunx frame-text-width &optional frame +These functions return the height and width of the text area of +@var{frame} (@pxref{Frame Layout}), measured in pixels. For a text +terminal, the results are in characters rather than pixels. + +The value returned by @code{frame-text-height} differs from that +returned by @code{frame-pixel-height} by not including the heights of +any internal tool bar or menu bar, the height of one horizontal scroll +bar and the widths of the internal border. + +The value returned by @code{frame-text-width} differs from that returned +by @code{frame-pixel-width} by not including the width of one vertical +scroll bar, the widths of one left and one right fringe and the widths +of the internal border. +@end defun + +@defun frame-height &optional frame +@defunx frame-width &optional frame +These functions return the height and width of the text area of +@var{frame}, measured in units of the default font height and width of +@var{frame} (@pxref{Frame Font}). These functions are plain shorthands +for writing @code{(frame-parameter frame 'height)} and +@code{(frame-parameter frame 'width)}. + +If the text area of @var{frame} measured in pixels is not a multiple of +its default font size, the values returned by these functions are +rounded down to the number of characters of the default font that fully +fit into the text area. +@end defun + +@defopt frame-resize-pixelwise +If this option is @code{nil}, a frame's size is usually rounded to a +multiple of the current values of that frame's @code{frame-char-height} +and @code{frame-char-width} whenever the frame is resized. If this is +non-@code{nil}, no rounding occurs, hence frame sizes can +increase/decrease by one pixel. + +Setting this variable usually causes the next resize operation to pass +the corresponding size hints to the window manager. This means that +this variable should be set only in a user's initial file; applications +should never bind it temporarily. + +The precise meaning of a value of @code{nil} for this option depends on +the toolkit used. Dragging the external border with the mouse is done +character-wise provided the window manager is willing to process the +corresponding size hints. Calling @code{set-frame-size} (see below) +with arguments that do not specify the frame size as an integer multiple +of its character size, however, may: be ignored, cause a rounding +(GTK+), or be accepted (Lucid, Motif, MS-Windows). + +With some window managers you may have to set this to non-@code{nil} in +order to make a frame appear truly maximized or full-screen. +@end defopt + +@defun set-frame-size frame width height pixelwise +This function sets the size of the text area of @var{frame}, measured in +terms of the canonical height and width of a character on @var{frame} +(@pxref{Frame Font}). + +The optional argument @var{pixelwise} non-@code{nil} means to measure +the new width and height in units of pixels instead. Note that if +@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to +fully honor the request if it does not increase/decrease the frame size +to a multiple of its character size. +@end defun + +@defun set-frame-height frame height &optional pretend pixelwise +This function resizes the text area of @var{frame} to a height of +@var{height} lines. The sizes of existing windows in @var{frame} are +altered proportionally to fit. + +If @var{pretend} is non-@code{nil}, then Emacs displays @var{height} +lines of output in @var{frame}, but does not change its value for the +actual height of the frame. This is only useful on text terminals. +Using a smaller height than the terminal actually implements may be +useful to reproduce behavior observed on a smaller screen, or if the +terminal malfunctions when using its whole screen. Setting the frame +height directly does not always work, because knowing the correct +actual size may be necessary for correct cursor positioning on +text terminals. + +The optional fourth argument @var{pixelwise} non-@code{nil} means that +@var{frame} should be @var{height} pixels high. Note that if +@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to +fully honor the request if it does not increase/decrease the frame +height to a multiple of its character height. +@end defun + +@defun set-frame-width frame width &optional pretend pixelwise +This function sets the width of the text area of @var{frame}, measured +in characters. The argument @var{pretend} has the same meaning as in +@code{set-frame-height}. + +The optional fourth argument @var{pixelwise} non-@code{nil} means that +@var{frame} should be @var{width} pixels wide. Note that if +@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to +fully honor the request if it does not increase/decrease the frame width +to a multiple of its character width. +@end defun + +None of these three functions will make a frame smaller than needed to +display all of its windows together with their scroll bars, fringes, +margins, dividers, mode and header lines. This contrasts with requests +by the window manager triggered, for example, by dragging the external +border of a frame with the mouse. Such requests are always honored by +clipping, if necessary, portions that cannot be displayed at the right, +bottom corner of the frame. + + +@node Implied Frame Resizing +@subsection Implied Frame Resizing +@cindex implied frame resizing +@cindex implied resizing of frame + +By default, Emacs tries to keep the number of lines and columns of a +frame's text area unaltered when, for example, adding or removing the +menu bar, changing the default font or setting the width of the frame's +scroll bars. This means, however, that in such case Emacs must ask the +window manager to resize the outer frame in order to accommodate the +size change. Note that wrapping a menu or tool bar usually does not +resize the frame's outer size, hence this will alter the number of +displayed lines. + + Occasionally, such @dfn{implied frame resizing} may be unwanted, for +example, when the frame is maximized or made full-screen (where it's +turned off by default). In other cases you can disable implied resizing +with the following option: + +@defopt frame-inhibit-implied-resize +If this option is @code{nil}, changing font, menu bar, tool bar, +internal borders, fringes or scroll bars of a specific frame may +implicitly resize the frame's display area in order to preserve the +number of columns or lines the frame displays. If this option is +non-@code{nil}, no implied resizing is done. + +The value of this option can be also be a list of frame parameters. In +that case, implied resizing is inhibited when changing a parameter that +appears in this list. The frame parameters currently handled by this +option are: @code{font}, @code{font-backend}, +@code{internal-border-width}, @code{menu-bar-lines} and +@code{tool-bar-lines}. + +Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height}, +@code{vertical-scroll-bars}, @code{horizontal-scroll-bars}, +@code{left-fringe} and @code{right-fringe} frame parameters is handled +as if the frame contained just one live window. This means, for +example, that removing vertical scroll bars on a frame containing +several side by side windows will shrink the outer frame width by the +width of one scroll bar provided this option is @code{nil} and keep it +unchanged if this option is either @code{t} or a list containing +@code{vertical-scroll-bars}. + +The default value is @code{'(tool-bar-lines)} for Lucid, Motif and +Windows (which means that adding/removing a tool bar there does not +change the outer frame height), @code{nil} on all other window systems +including GTK+ (which means that changing any of the parameters listed +above may change the size of the outer frame), and @code{t} otherwise +(which means the outer frame size never changes implicitly when there's +no window system support). + +Note that when a frame is not large enough to accommodate a change of +any of the parameters listed above, Emacs may try to enlarge the frame +even if this option is non-@code{nil}. +@end defopt + + @node Frame Parameters @section Frame Parameters @cindex frame parameters @@ -338,7 +978,6 @@ frame transparency, the parameter @code{alpha} is also meaningful. * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. * Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. * Geometry:: Parsing geometry specifications. @end menu @@ -385,6 +1024,7 @@ parameter values to frames that will be created henceforth. @node Initial Parameters @subsection Initial Frame Parameters +@cindex parameters of initial frame You can specify the parameters for the initial startup frame by setting @code{initial-frame-alist} in your init file (@pxref{Init @@ -485,8 +1125,9 @@ frame. @code{title} and @code{name} are meaningful on all terminals. @vindex display, a frame parameter @item display The display on which to open this frame. It should be a string of the -form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the -@env{DISPLAY} environment variable. +form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the +@env{DISPLAY} environment variable. @xref{Multiple Terminals}, for +more details about display names. @vindex display-type, a frame parameter @item display-type @@ -523,6 +1164,7 @@ named, this parameter will be @code{nil}. @node Position Parameters @subsubsection Position Parameters @cindex window position on display +@cindex frame position Position parameters' values are normally measured in pixels, but on text terminals they count characters or lines instead. @@ -542,18 +1184,30 @@ right screen edge. @item @code{(+ @var{pos})} This specifies the position of the left frame edge relative to the left screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. +negative value specifies a position outside the screen or on a monitor +other than the primary one (for multi-monitor displays). @item @code{(- @var{pos})} This specifies the position of the right frame edge relative to the right screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. +negative value specifies a position outside the screen or on a monitor +other than the primary one (for multi-monitor displays). @end table Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-@code{nil} value for the @code{user-position} parameter as well. +If the window manager refuses to align a frame at the left or top screen +edge, combining position notation and @code{user-position} as in + +@example +(modify-frame-parameters + nil '((user-position . t) (left . (+ -4)))) +@end example + +may help to override that. + @vindex top, a frame parameter @item top The screen position of the top (or bottom) edge, in pixels, with respect @@ -596,6 +1250,7 @@ parameters represent the user's stated preference; otherwise, use @code{nil}. @end table + @node Size Parameters @subsubsection Size Parameters @cindex window size on display @@ -607,13 +1262,13 @@ pixel sizes of these character units (@pxref{Face Attributes}). @table @code @vindex height, a frame parameter @item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) +The height of the frame's text area (@pxref{Frame Geometry}), in +characters. @vindex width, a frame parameter @item width -The width of the frame contents, in characters. (To get the width in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) +The width of the frame's text area (@pxref{Frame Geometry}), in +characters. @vindex user-size, a frame parameter @item user-size @@ -622,21 +1277,57 @@ the @code{user-position} parameter (@pxref{Position Parameters, user-position}) does for the position parameters @code{top} and @code{left}. -@cindex full-screen frames +@cindex fullboth frames +@cindex fullheight frames +@cindex fullwidth frames +@cindex maximized frames @vindex fullscreen, a frame parameter @item fullscreen -Specify that width, height or both shall be maximized. The value -@code{fullwidth} specifies that width shall be as wide as possible. -The value @code{fullheight} specifies that height shall be as tall as -possible. The value @code{fullboth} specifies that both the width and -the height shall be set to the size of the screen. The value -@code{maximized} specifies that the frame shall be maximized. The -difference between @code{maximized} and @code{fullboth} is that the -former can still be resized by dragging window manager decorations -with the mouse, while the latter really covers the whole screen and -does not allow resizing by mouse dragging. +This parameter specifies whether to maximize the frame's width, height +or both. Its value can be @code{fullwidth}, @code{fullheight}, +@code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as +wide as possible, a @dfn{fullheight} frame is as tall as possible, and +a @dfn{fullboth} frame is both as wide and as tall as possible. A +@dfn{maximized} frame is like a ``fullboth'' frame, except that it usually +keeps its title bar and the buttons for resizing +and closing the frame. Also, maximized frames typically avoid hiding +any task bar or panels displayed on the desktop. A ``fullboth'' frame, +on the other hand, usually omits the title bar and occupies the entire +available screen space. + +Full-height and full-width frames are more similar to maximized +frames in this regard. However, these typically display an external +border which might be absent with maximized frames. Hence the heights +of maximized and full-height frames and the widths of maximized and +full-width frames often differ by a few pixels. + +With some window managers you may have to customize the variable +@code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to +make a frame truly appear maximized or full-screen. Moreover, +some window managers might not support smooth transition between the +various full-screen or maximization states. Customizing the variable +@code{x-frame-normalize-before-maximize} can help to overcome that. + +@vindex fullscreen-restore, a frame parameter +@item fullscreen-restore +This parameter specifies the desired fullscreen state of the frame +after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame +Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state. +Normally this parameter is installed automatically by that command when +toggling the state to fullboth. If, however, you start Emacs in the +``fullboth'' state, you have to specify the desired behavior in your initial +file as, for example + +@example +(setq default-frame-alist + '((fullscreen . fullboth) (fullscreen-restore . fullheight))) +@end example + +This will give a new frame full height after typing in it @key{F11} for +the first time. @end table + @node Layout Parameters @subsubsection Layout Parameters @cindex layout parameters of frames @@ -660,19 +1351,21 @@ Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are @code{left}, @code{right}, and @code{nil} for no scroll bars. -@ignore @vindex horizontal-scroll-bars, a frame parameter @item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). Horizontal scroll bars are not currently -implemented. -@end ignore +Whether the frame has scroll bars for horizontal scrolling (@code{t} and +@code{bottom} mean yes, @code{nil} means no). @vindex scroll-bar-width, a frame parameter @item scroll-bar-width The width of vertical scroll bars, in pixels, or @code{nil} meaning to use the default width. +@vindex scroll-bar-height, a frame parameter +@item scroll-bar-height +The height of horizontal scroll bars, in pixels, or @code{nil} meaning +to use the default height. + @vindex left-fringe, a frame parameter @vindex right-fringe, a frame parameter @item left-fringe @@ -686,13 +1379,17 @@ these two frame parameters, the return value is always an integer. When using @code{set-frame-parameter}, passing a @code{nil} value imposes an actual default value of 8 pixels. -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame, as -reported by @code{frame-parameter}, may be larger than what you -specify. Any extra width is distributed evenly between the left and -right fringe. However, you can force one fringe or the other to a -precise width by specifying that width as a negative integer. If both -widths are negative, only the left fringe gets the specified width. +@vindex right-divider-width, a frame parameter +@item right-divider-width +The width (thickness) reserved for the right divider (@pxref{Window +Dividers}) of any window on the frame, in pixels. A value of zero means +to not draw right dividers. + +@vindex bottom-divider-width, a frame parameter +@item bottom-divider-width +The width (thickness) reserved for the bottom divider (@pxref{Window +Dividers}) of any window on the frame, in pixels. A value of zero means +to not draw bottom dividers. @vindex menu-bar-lines frame parameter @item menu-bar-lines @@ -720,6 +1417,8 @@ integer). @xref{Line Height}, for more information. @node Buffer Parameters @subsubsection Buffer Parameters +@cindex frame, which buffers to display +@cindex buffers to display on frame These frame parameters, meaningful on all kinds of terminals, deal with which buffers have been, or should, be displayed in the frame. @@ -877,12 +1576,25 @@ means use a standard modification of the usual cursor type (solid box becomes hollow box, and bar becomes a narrower bar). @end defopt +@defopt x-stretch-cursor +This variable controls the width of the block cursor displayed on +extra-wide glyphs such as a tab or a stretch of white space. By +default, the block cursor is only as wide as the font's default +character, and will not cover all of the width of the glyph under it +if that glyph is extra-wide. A non-@code{nil} value of this variable +means draw the block cursor as wide as the glyph under it. The +default value is @code{nil}. + +This variable has no effect on text-mode frames, since the text-mode +cursor is drawn by the terminal out of Emacs's control. +@end defopt + @defopt blink-cursor-alist This variable specifies how to blink the cursor. Each element has the form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor type equals @var{on-state} (comparing using @code{equal}), the corresponding @var{off-state} specifies what the cursor looks like -when it blinks ``off''. Both @var{on-state} and @var{off-state} +when it blinks off. Both @var{on-state} and @var{off-state} should be suitable values for the @code{cursor-type} frame parameter. There are various defaults for how to blink each type of cursor, if @@ -903,7 +1615,7 @@ variable do not take effect immediately, only when you specify the A list of symbols, specifying the @dfn{font backends} to use for drawing fonts in the frame, in order of priority. On X, there are currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On Windows, there are +driver) and @code{xft} (the Xft font driver). On MS-Windows, there are currently two available font backends: @code{gdi} and @code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs Manual}). On other systems, there is only one available font backend, @@ -933,9 +1645,9 @@ used instead. @vindex screen-gamma, a frame parameter @item screen-gamma @cindex gamma correction -If this is a number, Emacs performs ``gamma correction'' which adjusts +If this is a number, Emacs performs gamma correction which adjusts the brightness of all colors. The value should be the screen gamma of -your display, a floating point number. +your display. Usual PC monitors have a screen gamma of 2.2, so color values in Emacs, and in X windows generally, are calibrated to display properly @@ -968,8 +1680,8 @@ variable, Emacs uses the latter. By default, @code{frame-alpha-lower-limit} is 20. The @code{alpha} frame parameter can also be a cons cell -@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the -opacity of the frame when it is selected, and @samp{inactive} is the +@code{(@var{active} . @var{inactive})}, where @var{active} is the +opacity of the frame when it is selected, and @var{inactive} is the opacity when it is not selected. @end table @@ -1023,112 +1735,6 @@ equivalent to the @code{:background} attribute of the @code{scroll-bar} face. @end table -@node Size and Position -@subsection Frame Size And Position -@cindex size of frame -@cindex screen size -@cindex frame size -@cindex resize frame - - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. - - Here are some special features for working with sizes and positions. -(For the precise meaning of ``selected frame'' used by these functions, -see @ref{Input Focus}.) - -@defun set-frame-position frame left top -This function sets the position of the top left corner of @var{frame} to -@var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen. - -Negative parameter values position the bottom edge of the window up from -the bottom edge of the screen, or the right window edge to the left of -the right edge of the screen. It would probably be better if the values -were always counted from the left and top, so that negative arguments -would position the frame partly off the top or left edge of the screen, -but it seems inadvisable to change that now. -@end defun - -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -lines and columns. If you don't supply @var{frame}, they use the -selected frame. -@end defun - -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame -These functions return the height and width of the main display area -of @var{frame}, measured in pixels. If you don't supply @var{frame}, -they use the selected frame. For a text terminal, the results are in -characters rather than pixels. - -These values include the internal borders, and windows' scroll bars -and fringes (which belong to individual windows, not to the frame -itself). The exact value of the heights depends on the window-system -and toolkit in use. With GTK+, the height does not include any tool -bar or menu bar. With the Motif or Lucid toolkits, it includes the -tool bar but not the menu bar. In a graphical version with no -toolkit, it includes both the tool bar and menu bar. For a text -terminal, the result includes the menu bar. -@end defun - -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. -@end defun - -@defun set-frame-size frame cols rows -This function sets the size of @var{frame}, measured in characters; -@var{cols} and @var{rows} specify the new width and height. - -To set the size based on values measured in pixels, use -@code{frame-char-height} and @code{frame-char-width} to convert -them to units of characters. -@end defun - -@defun set-frame-height frame lines &optional pretend -This function resizes @var{frame} to a height of @var{lines} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. - -If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} -lines of output in @var{frame}, but does not change its value for the -actual height of the frame. This is only useful on text terminals. -Using a smaller height than the terminal actually implements may be -useful to reproduce behavior observed on a smaller screen, or if the -terminal malfunctions when using its whole screen. Setting the frame -height ``for real'' does not always work, because knowing the correct -actual size may be necessary for correct cursor positioning on -text terminals. -@end defun - -@defun set-frame-width frame width &optional pretend -This function sets the width of @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in -@code{set-frame-height}. -@end defun - -@c FIXME? Belongs more in Emacs manual than here? -@c But, e.g., fit-window-to-buffer is in this manual. -@deffn Command fit-frame-to-buffer &optional frame max-height min-height -This command adjusts the height of @var{frame} (the default is the -selected frame) to fit its contents. The optional arguments -@var{max-height} and @var{min-height} specify the maximum and minimum -new frame heights, respectively. - -@vindex fit-frame-to-buffer-bottom-margin -The default minimum height corresponds to @code{window-min-height}. -The default maximum height is the screen height below the current top -position of the frame, minus any margin specified by the option -@code{fit-frame-to-buffer-bottom-margin}. -@end deffn @node Geometry @subsection Geometry @@ -1189,7 +1795,7 @@ symbol) of @var{terminal}. If @var{terminal} has no setting for @end defun @defun set-terminal-parameter terminal parameter value -This function sets the parameter @var{parm} of @var{terminal} to the +This function sets the parameter @var{parameter} of @var{terminal} to the specified @var{value}, and returns the previous value of that parameter. @end defun @@ -1208,6 +1814,18 @@ terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. @item terminal-initted After the terminal is initialized, this is set to the terminal-specific initialization function. +@item tty-mode-set-strings +When present, a list of strings containing escape sequences that Emacs +will output while configuring a tty for rendering. Emacs emits these +strings only when configuring a terminal: if you want to enable a mode +on a terminal that is already active (for example, while in +@code{tty-setup-hook}), explicitly output the necessary escape +sequence using @code{send-string-to-terminal} in addition to adding +the sequence to @code{tty-mode-set-strings}. +@item tty-mode-reset-strings +When present, a list of strings that undo the effects of the strings +in @code{tty-mode-set-strings}. Emacs emits these strings when +exiting, deleting a terminal, or suspending itself. @end table @node Frame Titles @@ -1266,7 +1884,8 @@ tooltip, it first runs the hook @code{delete-frame-functions} (each function gets one argument, @var{frame}). By default, @var{frame} is the selected frame. -A frame cannot be deleted if its minibuffer is used by other frames. +A frame cannot be deleted as long as its minibuffer serves as surrogate +minibuffer for another frame (@pxref{Minibuffers and Frames}). Normally, you cannot delete a frame if all other frames are invisible, but if @var{force} is non-@code{nil}, then you are allowed to do so. @end deffn @@ -1298,13 +1917,13 @@ internals of Emacs. @defun visible-frame-list This function returns a list of just the currently visible frames. @xref{Visibility of Frames}. Frames on text terminals always count as -``visible'', even though only the selected one is actually displayed. +visible, even though only the selected one is actually displayed. @end defun @defun next-frame &optional frame minibuf This function lets you cycle conveniently through all the frames on the current display from an arbitrary starting point. It returns the -``next'' frame after @var{frame} in the cycle. If @var{frame} is +next frame after @var{frame} in the cycle. If @var{frame} is omitted or @code{nil}, it defaults to the selected frame (@pxref{Input Focus}). @@ -1341,12 +1960,19 @@ is used whenever that frame is selected. If the frame has a minibuffer, you can get it with @code{minibuffer-window} (@pxref{Definition of minibuffer-window}). -However, you can also create a frame with no minibuffer. Such a frame -must use the minibuffer window of some other frame. When you create the -frame, you can explicitly specify the minibuffer window to use (in some -other frame). If you don't, then the minibuffer is found in the frame -which is the value of the variable @code{default-minibuffer-frame}. Its -value should be a frame that does have a minibuffer. +@cindex frame without a minibuffer +@cindex surrogate minibuffer frame +However, you can also create a frame without a minibuffer. Such a frame +must use the minibuffer window of some other frame. That other frame +will serve as @dfn{surrogate minibuffer frame} for this frame and cannot +be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as +this frame is live. + +When you create the frame, you can explicitly specify the minibuffer +window to use (in some other frame). If you don't, then the minibuffer +is found in the frame which is the value of the variable +@code{default-minibuffer-frame}. Its value should be a frame that does +have a minibuffer. If you use a minibuffer-only frame, you might want that frame to raise when you enter the minibuffer. If so, set the variable @@ -1369,7 +1995,7 @@ window always resides on the selected frame. When Emacs displays its frames on several terminals (@pxref{Multiple Terminals}), each terminal has its own selected frame. But only one -of these is ``@emph{the} selected frame'': it's the frame that belongs +of these is @emph{the} selected frame: it's the frame that belongs to the terminal from which the most recent input came. That is, when Emacs runs a command that came from a certain terminal, the selected frame is the one of that terminal. Since Emacs runs only a single @@ -1389,7 +2015,7 @@ way, Emacs automatically keeps track of which frame has the focus. To explicitly switch to a different frame from a Lisp function, call @code{select-frame-set-input-focus}. -Lisp programs can also switch frames ``temporarily'' by calling the +Lisp programs can also switch frames temporarily by calling the function @code{select-frame}. This does not alter the window system's concept of focus; rather, it escapes from the window manager's control until that control is somehow reasserted. @@ -1479,6 +2105,14 @@ The redirection lasts until @code{redirect-frame-focus} is called to change it. @end defun +@defvar focus-in-hook +This is a normal hook run when an Emacs frame gains input focus. +@end defvar + +@defvar focus-out-hook +This is a normal hook run when an Emacs frame loses input focus. +@end defvar + @defopt focus-follows-mouse This option is how you inform Emacs whether the window manager transfers focus when the user moves the mouse. Non-@code{nil} says that it does. @@ -1510,7 +2144,7 @@ This function returns the visibility status of frame @var{frame}. The value is @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and @code{icon} if it is iconified. -On a text terminal, all frames are considered ``visible'' for the +On a text terminal, all frames are considered visible for the purposes of this function, even though only one frame is displayed. @xref{Raising and Lowering}. @end defun @@ -1634,6 +2268,19 @@ The value of @code{track-mouse} is that of the last form in @var{body}. You should design @var{body} to return when it sees the up-event that indicates the release of the button, or whatever kind of event means it is time to stop tracking. + +The @code{track-mouse} form causes Emacs to generate mouse motion +events by binding the variable @code{track-mouse} to a +non-@code{nil} value. If that variable has the special value +@code{dragging}, it additionally instructs the display engine to +refrain from changing the shape of the mouse pointer. This is +desirable in Lisp programs that require mouse dragging across large +portions of Emacs display, which might otherwise cause the mouse +pointer to change its shape according to the display portion it hovers +on (@pxref{Pointer Shape}). Therefore, Lisp programs that need the +mouse pointer to retain its original shape during dragging should bind +@code{track-mouse} to the value @code{dragging} at the beginning of +their @var{body}. @end defspec The usual purpose of tracking mouse motion is to indicate on the screen @@ -1691,8 +2338,10 @@ give access to the current position of the mouse. @defun mouse-position This function returns a description of the position of the mouse. The value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} -and @var{y} are integers giving the position in characters relative to -the top left corner of the inside of @var{frame}. +and @var{y} are integers giving the (possibly rounded) position in +multiples of the default character size of @var{frame} (@pxref{Frame +Font}) relative to the native position of @var{frame} (@pxref{Frame +Geometry}). @end defun @defvar mouse-position-function @@ -1708,9 +2357,13 @@ This abnormal hook exists for the benefit of packages like @defun set-mouse-position frame x y This function @dfn{warps the mouse} to position @var{x}, @var{y} in frame @var{frame}. The arguments @var{x} and @var{y} are integers, -giving the position in characters relative to the top left corner of the -inside of @var{frame}. If @var{frame} is not visible, this function -does nothing. The return value is not significant. +giving the position in multiples of the default character size of +@var{frame} (@pxref{Frame Font}) relative to the native position of +@var{frame} (@pxref{Frame Geometry}). + +The resulting mouse position is constrained to the native frame of +@var{frame}. If @var{frame} is not visible, this function does nothing. +The return value is not significant. @end defun @defun mouse-pixel-position @@ -1721,12 +2374,31 @@ coordinates in units of pixels rather than units of characters. @defun set-mouse-pixel-position frame x y This function warps the mouse like @code{set-mouse-position} except that @var{x} and @var{y} are in units of pixels rather than units of -characters. These coordinates are not required to be within the frame. +characters. -If @var{frame} is not visible, this function does nothing. The return -value is not significant. +The resulting mouse position is not constrained to the native frame of +@var{frame}. If @var{frame} is not visible, this function does nothing. +The return value is not significant. @end defun +On a graphical terminal the following two functions allow to retrieve +and set the absolute position of the mouse cursor. + +@defun mouse-absolute-pixel-position +This function returns a cons cell (@var{x} . @var{y}) of the coordinates +of the mouse cursor position in pixels, relative to a position (0, 0) of +the selected frame's display. +@end defun + +@defun set-mouse-absolute-pixel-position x y +This function moves the mouse cursor to the position (@var{x}, @var{y}). +The coordinates @var{x} and @var{y} are interpreted in pixels relative +to a position (0, 0) of the selected frame's display. +@end defun + +The following function can tell whether the mouse cursor is currently +visible on a frame: + @defun frame-pointer-visible-p &optional frame This predicate function returns non-@code{nil} if the mouse pointer displayed on @var{frame} is visible; otherwise it returns @code{nil}. @@ -1740,9 +2412,12 @@ allows to know if the pointer has been hidden. @node Pop-Up Menus @section Pop-Up Menus +@cindex menus, popup - When using a window system, a Lisp program can pop up a menu so that -the user can choose an alternative with the mouse. + A Lisp program can pop up a menu so that the user can choose an +alternative with the mouse. On a text terminal, if the mouse is not +available, the user can choose an alternative using the keyboard +motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys. @defun x-popup-menu position menu This function displays a pop-up menu and returns an indication of @@ -1763,20 +2438,22 @@ pixels, counting from the top left corner of @var{window}. @var{window} may be a window or a frame. If @var{position} is @code{t}, it means to use the current mouse -position. If @var{position} is @code{nil}, it means to precompute the -key binding equivalents for the keymaps specified in @var{menu}, -without actually displaying or popping up the menu. +position (or the top-left corner of the frame if the mouse is not +available on a text terminal). If @var{position} is @code{nil}, it +means to precompute the key binding equivalents for the keymaps +specified in @var{menu}, without actually displaying or popping up the +menu. The argument @var{menu} says what to display in the menu. It can be a keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the return value is the list of events corresponding to the user's choice. This list has more than one element if the choice occurred in a submenu. (Note that @code{x-popup-menu} does not actually execute the -command bound to that sequence of events.) On toolkits that support -menu titles, the title is taken from the prompt string of @var{menu} -if @var{menu} is a keymap, or from the prompt string of the first -keymap in @var{menu} if it is a list of keymaps (@pxref{Defining -Menus}). +command bound to that sequence of events.) On text terminals and +toolkits that support menu titles, the title is taken from the prompt +string of @var{menu} if @var{menu} is a keymap, or from the prompt +string of the first keymap in @var{menu} if it is a list of keymaps +(@pxref{Defining Menus}). Alternatively, @var{menu} can have the following form: @@ -1800,7 +2477,7 @@ cell; this makes a non-selectable menu item. If the user gets rid of the menu without making a valid choice, for instance by clicking the mouse away from a valid choice or by typing -keyboard input, then this normally results in a quit and +@kbd{C-g}, then this normally results in a quit and @code{x-popup-menu} does not return. But if @var{position} is a mouse button event (indicating that the user invoked the menu with the mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. @@ -1872,7 +2549,8 @@ window don't matter; only the frame matters. If @var{header} is non-@code{nil}, the frame title for the box is @samp{Information}, otherwise it is @samp{Question}. The former is used -for @code{message-box} (@pxref{message-box}). +for @code{message-box} (@pxref{message-box}). (On text terminals, the +box title is not displayed.) In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the @@ -1999,6 +2677,7 @@ clipboard as empty. @node Drag and Drop @section Drag and Drop +@cindex drag and drop @vindex x-dnd-test-function @vindex x-dnd-known-types @@ -2226,7 +2905,7 @@ If you specify them, the key is @defvar x-resource-class This variable specifies the application name that @code{x-get-resource} should look up. The default value is @code{"Emacs"}. You can examine X -resources for application names other than ``Emacs'' by binding this +resources for other application names by binding this variable to some other string, around a call to @code{x-get-resource}. @end defvar @@ -2284,9 +2963,9 @@ obtain information about displays. @defun display-popup-menus-p &optional display This function returns @code{t} if popup menus are supported on -@var{display}, @code{nil} if not. Support for popup menus requires that -the mouse be available, since the user cannot choose menu items without -a mouse. +@var{display}, @code{nil} if not. Support for popup menus requires +that the mouse be available, since the menu is popped up by clicking +the mouse on some portion of the Emacs display. @end defun @defun display-graphic-p &optional display @@ -2319,7 +2998,7 @@ This function returns @code{t} if the screen can display shades of gray. This function returns non-@code{nil} if all the face attributes in @var{attributes} are supported (@pxref{Face Attributes}). -The definition of `supported' is somewhat heuristic, but basically +The definition of ``supported'' is somewhat heuristic, but basically means that a face containing all the attributes in @var{attributes}, when merged with the default face for display, can be represented in a way that's @@ -2329,14 +3008,14 @@ way that's different in appearance than the default face, and @item -`close in spirit' to what the attributes specify, if not exact. +close in spirit to what the attributes specify, if not exact. @end enumerate Point (2) implies that a @code{:weight black} attribute will be satisfied by any display that can display bold, as will @code{:foreground "yellow"} as long as some yellowish color can be displayed, but @code{:slant italic} will @emph{not} be satisfied by -the tty display code's automatic substitution of a `dim' face for +the tty display code's automatic substitution of a dim face for italic. @end defun @@ -2361,8 +3040,8 @@ This function returns the number of screens associated with the display. This function returns the height of the screen in pixels. On a character terminal, it gives the height in characters. -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with +For graphical terminals, note that on multi-monitor setups this +refers to the pixel height for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun @@ -2370,7 +3049,7 @@ refers to the pixel width for all physical monitors associated with This function returns the width of the screen in pixels. On a character terminal, it gives the width in characters. -For graphical terminals, note that on ``multi-monitor'' setups this +For graphical terminals, note that on multi-monitor setups this refers to the pixel width for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun @@ -2378,11 +3057,19 @@ refers to the pixel width for all physical monitors associated with @defun display-mm-height &optional display This function returns the height of the screen in millimeters, or @code{nil} if Emacs cannot get that information. + +For graphical terminals, note that on multi-monitor setups this +refers to the height for all physical monitors associated with +@var{display}. @xref{Multiple Terminals}. @end defun @defun display-mm-width &optional display This function returns the width of the screen in millimeters, or @code{nil} if Emacs cannot get that information. + +For graphical terminals, note that on multi-monitor setups this +refers to the width for all physical monitors associated with +@var{display}. @xref{Multiple Terminals}. @end defun @defopt display-mm-dimensions-alist @@ -2431,20 +3118,26 @@ colors). This function returns the number of color cells the screen supports. @end defun - These functions obtain additional information specifically -about X displays. + These functions obtain additional information about the window +system in use where Emacs shows the specified @var{display}. (Their +names begin with @code{x-} for historical reasons.) @defun x-server-version &optional display -This function returns the list of version numbers of the X server -running the display. The value is a list of three integers: the major -and minor version numbers of the X protocol, and the -distributor-specific release number of the X server software itself. +This function returns the list of version numbers of the GUI window +system running on @var{display}, such as the X server on GNU and Unix +systems. The value is a list of three integers: the major and minor +version numbers of the protocol, and the distributor-specific release +number of the window system software itself. On GNU and Unix systems, +these are normally the version of the X protocol and the +distributor-specific release number of the X server software. On +MS-Windows, this is the version of the Windows OS. @end defun @defun x-server-vendor &optional display -This function returns the ``vendor'' that provided the X server -software (as a string). Really this means whoever distributes the X -server. +This function returns the vendor that provided the window system +software (as a string). On GNU and Unix systems this really means +whoever distributes the X server. On MS-Windows this is the vendor ID +string of the Windows OS (Microsoft). When the developers of X labeled software distributors as ``vendors'', they showed their false assumption that no system could diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 39a9ff6b62c..8835667b82d 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Functions @@ -11,22 +11,23 @@ explains what functions are, how they accept arguments, and how to define them. @menu -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition +* What Is a Function:: Lisp functions vs. primitives; terminology. +* Lambda Expressions:: How functions are expressed as Lisp objects. +* Function Names:: A symbol can serve as the name of a function. +* Defining Functions:: Lisp expressions for defining functions. +* Calling Functions:: How to use an existing function. +* Mapping Functions:: Applying a function to each element of a list, etc. +* Anonymous Functions:: Lambda expressions are functions with no names. +* Function Cells:: Accessing or setting the function definition of a symbol. -* Closures:: Functions that enclose a lexical environment. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Functions that the compiler will expand inline. -* Declare Form:: Adding additional information about a function. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives +* Closures:: Functions that enclose a lexical environment. +* Advising Functions:: Adding to the definition of a function. +* Obsolete Functions:: Declaring functions obsolete. +* Inline Functions:: Functions that the compiler will expand inline. +* Declare Form:: Adding additional information about a function. +* Declaring Functions:: Telling the compiler that a function is defined. +* Function Safety:: Determining whether a function is safe to call. +* Related Topics:: Cross-references to specific Lisp primitives that have a special bearing on how functions work. @end menu @@ -117,7 +118,7 @@ Components}); such a @dfn{named command} can be invoked with @item closure A function object that is much like a lambda expression, except that -it also encloses an ``environment'' of lexical variable bindings. +it also encloses an environment of lexical variable bindings. @xref{Closures}. @item byte-code function @@ -207,10 +208,10 @@ Before going into these details, the following subsections describe the components of a lambda expression and what they do. @menu -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. +* Lambda Components:: The parts of a lambda expression. +* Simple Lambda:: A simple example. +* Argument List:: Details and special features of argument lists. +* Function Documentation:: How to put documentation in a function. @end menu @node Lambda Components @@ -367,7 +368,7 @@ This is what @code{substring} does; @code{nil} as the third argument to @quotation @b{Common Lisp note:} Common Lisp allows the function to specify what default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' +always uses @code{nil}. Emacs Lisp does not support @code{supplied-p} variables that tell you whether an argument was explicitly passed. @end quotation @@ -591,6 +592,11 @@ If @var{doc} is non-@code{nil}, it becomes the function documentation of @var{name}. Otherwise, any documentation provided by @var{definition} is used. +@cindex defalias-fset-function property +Internally, @code{defalias} normally uses @code{fset} to set the definition. +If @var{name} has a @code{defalias-fset-function} property, however, +the associated value is used as a function to call in place of @code{fset}. + The proper place to use @code{defalias} is where a specific function name is being defined---especially where that name appears explicitly in the source file being loaded. This is because @code{defalias} records @@ -654,7 +660,7 @@ already been evaluated. The argument @var{function} must be either a Lisp function or a primitive function. Special forms and macros are not allowed, because -they make sense only when given the ``unevaluated'' argument +they make sense only when given the unevaluated argument expressions. @code{funcall} cannot provide these because, as we saw above, it never knows them in the first place. @@ -906,7 +912,7 @@ This macro returns an anonymous function with argument list @var{args}, documentation string @var{doc} (if any), interactive spec @var{interactive} (if any), and body forms given by @var{body}. -In effect, this macro makes @code{lambda} forms ``self-quoting'': +In effect, this macro makes @code{lambda} forms self-quoting: evaluating a form whose @sc{car} is @code{lambda} yields the form itself: @@ -1001,12 +1007,12 @@ indirect-function}. @defun symbol-function symbol @kindex void-function -This returns the object in the function cell of @var{symbol}. If the -symbol's function cell is void, a @code{void-function} error is -signaled. +This returns the object in the function cell of @var{symbol}. It does +not check that the returned object is a legitimate function. -This function does not check that the returned object is a legitimate -function. +If the function cell is void, the return value is @code{nil}. To +distinguish between a function cell that is void and one set to +@code{nil}, use @code{fboundp} (see below). @example @group @@ -1026,10 +1032,10 @@ function. @end defun @cindex void function cell - If you have never given a symbol any function definition, we say that -that symbol's function cell is @dfn{void}. In other words, the function -cell does not have any Lisp object in it. If you try to call such a symbol -as a function, it signals a @code{void-function} error. + If you have never given a symbol any function definition, we say +that that symbol's function cell is @dfn{void}. In other words, the +function cell does not have any Lisp object in it. If you try to call +the symbol as a function, Emacs signals a @code{void-function} error. Note that void is not the same as @code{nil} or the symbol @code{void}. The symbols @code{nil} and @code{void} are Lisp objects, @@ -1077,12 +1083,10 @@ This function stores @var{definition} in the function cell of this is not checked. The argument @var{symbol} is an ordinary evaluated argument. -The primary use of this function is as a subroutine by constructs that -define or alter functions, like @code{defadvice} (@pxref{Advising -Functions}). (If @code{defun} were not a primitive, it could be -written as a Lisp macro using @code{fset}.) You can also use it to -give a symbol a function definition that is not a list, e.g., a -keyboard macro (@pxref{Keyboard Macros}): +The primary use of this function is as a subroutine by constructs that define +or alter functions, like @code{defun} or @code{advice-add} (@pxref{Advising +Functions}). You can also use it to give a symbol a function definition that +is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}): @example ;; @r{Define a named keyboard macro.} @@ -1129,12 +1133,467 @@ argument list and body forms as the remaining elements: @noindent However, the fact that the internal structure of a closure is -``exposed'' to the rest of the Lisp world is considered an internal +exposed to the rest of the Lisp world is considered an internal implementation detail. For this reason, we recommend against directly examining or altering the structure of closure objects. +@node Advising Functions +@section Advising Emacs Lisp Functions +@cindex advising functions +@cindex piece of advice + +When you need to modify a function defined in another library, or when you need +to modify a hook like @code{@var{foo}-function}, a process filter, or basically +any variable or object field which holds a function value, you can use the +appropriate setter function, such as @code{fset} or @code{defun} for named +functions, @code{setq} for hook variables, or @code{set-process-filter} for +process filters, but those are often too blunt, completely throwing away the +previous value. + + The @dfn{advice} feature lets you add to the existing definition of +a function, by @dfn{advising the function}. This is a cleaner method +than redefining the whole function. + +Emacs's advice system provides two sets of primitives for that: the core set, +for function values held in variables and object fields (with the corresponding +primitives being @code{add-function} and @code{remove-function}) and another +set layered on top of it for named functions (with the main primitives being +@code{advice-add} and @code{advice-remove}). + +For example, in order to trace the calls to the process filter of a process +@var{proc}, you could use: + +@example +(defun my-tracing-function (proc string) + (message "Proc %S received %S" proc string)) + +(add-function :before (process-filter @var{proc}) #'my-tracing-function) +@end example + +This will cause the process's output to be passed to @code{my-tracing-function} +before being passed to the original process filter. @code{my-tracing-function} +receives the same arguments as the original function. When you're done with +it, you can revert to the untraced behavior with: + +@example +(remove-function (process-filter @var{proc}) #'my-tracing-function) +@end example + +Similarly, if you want to trace the execution of the function named +@code{display-buffer}, you could use: + +@example +(defun his-tracing-function (orig-fun &rest args) + (message "display-buffer called with args %S" args) + (let ((res (apply orig-fun args))) + (message "display-buffer returned %S" res) + res)) + +(advice-add 'display-buffer :around #'his-tracing-function) +@end example + +Here, @code{his-tracing-function} is called instead of the original function +and receives the original function (additionally to that function's arguments) +as argument, so it can call it if and when it needs to. +When you're tired of seeing this output, you can revert to the untraced +behavior with: + +@example +(advice-remove 'display-buffer #'his-tracing-function) +@end example + +The arguments @code{:before} and @code{:around} used in the above examples +specify how the two functions are composed, since there are many different +ways to do it. The added function is also called a piece of @emph{advice}. + +@menu +* Core Advising Primitives:: Primitives to manipulate advice. +* Advising Named Functions:: Advising named functions. +* Advice combinators:: Ways to compose advice. +* Porting old advice:: Adapting code using the old defadvice. +@end menu + +@node Core Advising Primitives +@subsection Primitives to manipulate advices +@cindex advice, add and remove + +@defmac add-function where place function &optional props +This macro is the handy way to add the advice @var{function} to the function +stored in @var{place} (@pxref{Generalized Variables}). + +@var{where} determines how @var{function} is composed with the +existing function, e.g., whether @var{function} should be called before, or +after the original function. @xref{Advice combinators}, for the list of +available ways to compose the two functions. + +When modifying a variable (whose name will usually end with @code{-function}), +you can choose whether @var{function} is used globally or only in the current +buffer: if @var{place} is just a symbol, then @var{function} is added to the +global value of @var{place}. Whereas if @var{place} is of the form +@code{(local @var{symbol})}, where @var{symbol} is an expression which returns +the variable name, then @var{function} will only be added in the +current buffer. Finally, if you want to modify a lexical variable, you will +have to use @code{(var @var{variable})}. + +Every function added with @code{add-function} can be accompanied by an +association list of properties @var{props}. Currently only two of those +properties have a special meaning: + +@table @code +@item name +This gives a name to the advice, which @code{remove-function} can use to +identify which function to remove. Typically used when @var{function} is an +anonymous function. + +@item depth +This specifies how to order the advice, should several pieces of +advice be present. By default, the depth is 0. A depth of 100 +indicates that this piece of advice should be kept as deep as +possible, whereas a depth of -100 indicates that it should stay as the +outermost piece. When two pieces of advice specify the same depth, +the most recently added one will be outermost. + +For @code{:before} advice, being outermost means that this advice will +be run first, before any other advice, whereas being innermost means +that it will run right before the original function, with no other +advice run between itself and the original function. Similarly, for +@code{:after} advice innermost means that it will run right after the +original function, with no other advice run in between, whereas +outermost means that it will be run right at the end after all other +advice. An innermost @code{:override} piece of advice will only +override the original function and other pieces of advice will apply +to it, whereas an outermost @code{:override} piece of advice will +override not only the original function but all other advice applied +to it as well. +@end table + +If @var{function} is not interactive, then the combined function will inherit +the interactive spec, if any, of the original function. Else, the combined +function will be interactive and will use the interactive spec of +@var{function}. One exception: if the interactive spec of @var{function} +is a function (rather than an expression or a string), then the interactive +spec of the combined function will be a call to that function with as sole +argument the interactive spec of the original function. To interpret the spec +received as argument, use @code{advice-eval-interactive-spec}. + +Note: The interactive spec of @var{function} will apply to the combined +function and should hence obey the calling convention of the combined function +rather than that of @var{function}. In many cases, it makes no difference +since they are identical, but it does matter for @code{:around}, +@code{:filter-args}, and @code{filter-return}, where @var{function}. +@end defmac + +@defmac remove-function place function +This macro removes @var{function} from the function stored in +@var{place}. This only works if @var{function} was added to @var{place} +using @code{add-function}. + +@var{function} is compared with functions added to @var{place} using +@code{equal}, to try and make it work also with lambda expressions. It is +additionally compared also with the @code{name} property of the functions added +to @var{place}, which can be more reliable than comparing lambda expressions +using @code{equal}. +@end defmac + +@defun advice-function-member-p advice function-def +Return non-@code{nil} if @var{advice} is already in @var{function-def}. +Like for @code{remove-function} above, instead of @var{advice} being the actual +function, it can also be the @code{name} of the piece of advice. +@end defun + +@defun advice-function-mapc f function-def +Call the function @var{f} for every piece of advice that was added to +@var{function-def}. @var{f} is called with two arguments: the advice function +and its properties. +@end defun + +@defun advice-eval-interactive-spec spec +Evaluate the interactive @var{spec} just like an interactive call to a function +with such a spec would, and then return the corresponding list of arguments +that was built. E.g., @code{(advice-eval-interactive-spec "r\nP")} will +return a list of three elements, containing the boundaries of the region and +the current prefix argument. +@end defun + +@node Advising Named Functions +@subsection Advising Named Functions +@cindex advising named functions + +A common use of advice is for named functions and macros. +You could just use @code{add-function} as in: + +@example +(add-function :around (symbol-function '@var{fun}) #'his-tracing-function) +@end example + + But you should use @code{advice-add} and @code{advice-remove} for that +instead. This separate set of functions to manipulate pieces of advice applied +to named functions, offers the following extra features compared to +@code{add-function}: they know how to deal with macros and autoloaded +functions, they let @code{describe-function} preserve the original docstring as +well as document the added advice, and they let you add and remove advice +before a function is even defined. + + @code{advice-add} can be useful for altering the behavior of existing calls +to an existing function without having to redefine the whole function. +However, it can be a source of bugs, since existing callers to the function may +assume the old behavior, and work incorrectly when the behavior is changed by +advice. Advice can also cause confusion in debugging, if the person doing the +debugging does not notice or remember that the function has been modified +by advice. + + For these reasons, advice should be reserved for the cases where you +cannot modify a function's behavior in any other way. If it is +possible to do the same thing via a hook, that is preferable +(@pxref{Hooks}). If you simply want to change what a particular key +does, it may be better to write a new command, and remap the old +command's key bindings to the new one (@pxref{Remapping Commands}). +In particular, Emacs's own source files should not put advice on +functions in Emacs. (There are currently a few exceptions to this +convention, but we aim to correct them.) + + Special forms (@pxref{Special Forms}) cannot be advised, however macros can +be advised, in much the same way as functions. Of course, this will not affect +code that has already been macro-expanded, so you need to make sure the advice +is installed before the macro is expanded. + + It is possible to advise a primitive (@pxref{What Is a Function}), +but one should typically @emph{not} do so, for two reasons. Firstly, +some primitives are used by the advice mechanism, and advising them +could cause an infinite recursion. Secondly, many primitives are +called directly from C, and such calls ignore advice; hence, one ends +up in a confusing situation where some calls (occurring from Lisp +code) obey the advice and other calls (from C code) do not. + +@defmac define-advice symbol (where lambda-list &optional name depth) &rest body +This macro defines a piece of advice and adds it to the function named +@var{symbol}. The advice is an anonymous function if @var{name} is +nil or a function named @code{symbol@@name}. See @code{advice-add} +for explanation of other arguments. +@end defmac + +@defun advice-add symbol where function &optional props +Add the advice @var{function} to the named function @var{symbol}. +@var{where} and @var{props} have the same meaning as for @code{add-function} +(@pxref{Core Advising Primitives}). +@end defun + +@defun advice-remove symbol function +Remove the advice @var{function} from the named function @var{symbol}. +@var{function} can also be the @code{name} of a piece of advice. +@end defun + +@defun advice-member-p function symbol +Return non-@code{nil} if the advice @var{function} is already in the named +function @var{symbol}. @var{function} can also be the @code{name} of +a piece of advice. +@end defun + +@defun advice-mapc function symbol +Call @var{function} for every piece of advice that was added to the +named function @var{symbol}. @var{function} is called with two +arguments: the advice function and its properties. +@end defun + +@node Advice combinators +@subsection Ways to compose advice + +Here are the different possible values for the @var{where} argument of +@code{add-function} and @code{advice-add}, specifying how the advice +@var{function} and the original function should be composed. + +@table @code +@item :before +Call @var{function} before the old function. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r)) +@end example +@code{(add-function :before @var{funvar} @var{function})} is comparable for +single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} for +normal hooks. + +@item :after +Call @var{function} after the old function. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r))) +@end example +@code{(add-function :after @var{funvar} @var{function})} is comparable for +single-function hooks to @code{(add-hook '@var{hookvar} @var{function} +'append)} for normal hooks. + +@item :override +This completely replaces the old function with the new one. The old function +can of course be recovered if you later call @code{remove-function}. + +@item :around +Call @var{function} instead of the old function, but provide the old function +as an extra argument to @var{function}. This is the most flexible composition. +For example, it lets you call the old function with different arguments, or +many times, or within a let-binding, or you can sometimes delegate the work to +the old function and sometimes override it completely. More specifically, the +composition of the two functions behaves like: +@example +(lambda (&rest r) (apply @var{function} @var{oldfun} r)) +@end example + +@item :before-while +Call @var{function} before the old function and don't call the old +function if @var{function} returns @code{nil}. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r))) +@end example +@code{(add-function :before-while @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} +when @var{hookvar} is run via @code{run-hook-with-args-until-failure}. + +@item :before-until +Call @var{function} before the old function and only call the old function if +@var{function} returns @code{nil}. More specifically, the composition of the +two functions behaves like: +@example +(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r))) +@end example +@code{(add-function :before-until @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} +when @var{hookvar} is run via @code{run-hook-with-args-until-success}. + +@item :after-while +Call @var{function} after the old function and only if the old function +returned non-@code{nil}. Both functions receive the same arguments, and the +return value of the composition is the return value of @var{function}. +More specifically, the composition of the two functions behaves like: +@example +(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r))) +@end example +@code{(add-function :after-while @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function} +'append)} when @var{hookvar} is run via +@code{run-hook-with-args-until-failure}. + +@item :after-until +Call @var{function} after the old function and only if the old function +returned @code{nil}. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r))) +@end example +@code{(add-function :after-until @var{funvar} @var{function})} is comparable +for single-function hooks to @code{(add-hook '@var{hookvar} @var{function} +'append)} when @var{hookvar} is run via +@code{run-hook-with-args-until-success}. + +@item :filter-args +Call @var{function} first and use the result (which should be a list) as the +new arguments to pass to the old function. More specifically, the composition +of the two functions behaves like: +@example +(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r))) +@end example + +@item :filter-return +Call the old function first and pass the result to @var{function}. +More specifically, the composition of the two functions behaves like: +@example +(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r))) +@end example +@end table + + +@node Porting old advice +@subsection Adapting code using the old defadvice +@cindex old advices, porting + +A lot of code uses the old @code{defadvice} mechanism, which is largely made +obsolete by the new @code{advice-add}, whose implementation and semantics is +significantly simpler. + +An old piece of advice such as: + +@example +(defadvice previous-line (before next-line-at-end + (&optional arg try-vscroll)) + "Insert an empty line when moving up from the top line." + (if (and next-line-add-newlines (= arg 1) + (save-excursion (beginning-of-line) (bobp))) + (progn + (beginning-of-line) + (newline)))) +@end example + +could be translated in the new advice mechanism into a plain function: + +@example +(defun previous-line--next-line-at-end (&optional arg try-vscroll) + "Insert an empty line when moving up from the top line." + (if (and next-line-add-newlines (= arg 1) + (save-excursion (beginning-of-line) (bobp))) + (progn + (beginning-of-line) + (newline)))) +@end example + +Obviously, this does not actually modify @code{previous-line}. For that the +old advice needed: +@example +(ad-activate 'previous-line) +@end example +whereas the new advice mechanism needs: +@example +(advice-add 'previous-line :before #'previous-line--next-line-at-end) +@end example + +Note that @code{ad-activate} had a global effect: it activated all pieces of +advice enabled for that specified function. If you wanted to only activate or +deactivate a particular piece, you needed to @emph{enable} or @emph{disable} +it with @code{ad-enable-advice} and @code{ad-disable-advice}. +The new mechanism does away with this distinction. + +Around advice such as: + +@example +(defadvice foo (around foo-around) + "Ignore case in `foo'." + (let ((case-fold-search t)) + ad-do-it)) +(ad-activate 'foo) +@end example + +could translate into: + +@example +(defun foo--foo-around (orig-fun &rest args) + "Ignore case in `foo'." + (let ((case-fold-search t)) + (apply orig-fun args))) +(advice-add 'foo :around #'foo--foo-around) +@end example + +Regarding the advice's @emph{class}, note that the new @code{:before} is not +quite equivalent to the old @code{before}, because in the old advice you could +modify the function's arguments (e.g., with @code{ad-set-arg}), and that would +affect the argument values seen by the original function, whereas in the new +@code{:before}, modifying an argument via @code{setq} in the advice has no +effect on the arguments seen by the original function. +When porting @code{before} advice which relied on this behavior, you'll need +to turn it into new @code{:around} or @code{:filter-args} advice instead. + +Similarly old @code{after} advice could modify the returned value by +changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so +when porting such old @code{after} advice, you'll need to turn it into new +@code{:around} or @code{:filter-return} advice instead. + @node Obsolete Functions @section Declaring Functions Obsolete +@cindex obsolete functions You can mark a named function as @dfn{obsolete}, meaning that it may be removed at some point in the future. This causes Emacs to warn @@ -1261,7 +1720,7 @@ performed later on in the same file, just like macros. @section The @code{declare} Form @findex declare - @code{declare} is a special macro which can be used to add ``meta'' + @code{declare} is a special macro which can be used to add meta properties to a function or macro: for example, marking it as obsolete, or giving its forms a special @key{TAB} indentation convention in Emacs Lisp mode. @@ -1286,20 +1745,27 @@ following effects: This acts like a call to @code{set-advertised-calling-convention} (@pxref{Obsolete Functions}); @var{signature} specifies the correct argument list for calling the function or macro, and @var{when} should -be a string indicating when the variable was first made obsolete. +be a string indicating when the old argument list was first made obsolete. @item (debug @var{edebug-form-spec}) This is valid for macros only. When stepping through the macro with Edebug, use @var{edebug-form-spec}. @xref{Instrumenting Macro Calls}. @item (doc-string @var{n}) -Use element number @var{n}, if any, as the documentation string. +This is used when defining a function or macro which itself will be used to +define entities like functions, macros, or variables. It indicates that +the @var{n}th argument, if any, should be considered +as a documentation string. @item (indent @var{indent-spec}) Indent calls to this function or macro according to @var{indent-spec}. This is typically used for macros, though it works for functions too. @xref{Indenting Macros}. +@item (interactive-only @var{value}) +Set the function's @code{interactive-only} property to @var{value}. +@xref{The interactive-only property}. + @item (obsolete @var{current-name} @var{when}) Mark the function or macro as obsolete, similar to a call to @code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name} @@ -1308,7 +1774,37 @@ instead), a string (specifying the warning message), or @code{nil} (in which case the warning message gives no extra details). @var{when} should be a string indicating when the function or macro was first made obsolete. + +@item (compiler-macro @var{expander}) +This can only be used for functions, and tells the compiler to use +@var{expander} as an optimization function. When encountering a call to the +function, of the form @code{(@var{function} @var{args}@dots{})}, the macro +expander will call @var{expander} with that form as well as with +@var{args}@dots{}, and @var{expander} can either return a new expression to use +instead of the function call, or it can return just the form unchanged, +to indicate that the function call should be left alone. @var{expander} can +be a symbol, or it can be a form @code{(lambda (@var{arg}) @var{body})} in +which case @var{arg} will hold the original function call expression, and the +(unevaluated) arguments to the function can be accessed using the function's +formal arguments. + +@item (gv-expander @var{expander}) +Declare @var{expander} to be the function to handle calls to the macro (or +function) as a generalized variable, similarly to @code{gv-define-expander}. +@var{expander} can be a symbol or it can be of the form @code{(lambda +(@var{arg}) @var{body})} in which case that function will additionally have +access to the macro (or function)'s arguments. + +@item (gv-setter @var{setter}) +Declare @var{setter} to be the function to handle calls to the macro (or +function) as a generalized variable. @var{setter} can be a symbol in which +case it will be passed to @code{gv-define-simple-setter}, or it can be of the +form @code{(lambda (@var{arg}) @var{body})} in which case that function will +additionally have access to the macro (or function)'s arguments and it will +passed to @code{gv-define-setter}. + @end table + @end defmac @node Declaring Functions @@ -1325,7 +1821,7 @@ example, byte-compiling @file{fortran.el} used to warn: @example In end of data: -fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not +fortran.el:2152:1:Warning: the function ‘gud-find-c-expr’ is not known to be defined. @end example @@ -1416,7 +1912,7 @@ list of buffer-local bindings. Being quick and simple, @code{unsafep} does a very light analysis and rejects many Lisp expressions that are actually safe. There are no known cases where @code{unsafep} returns @code{nil} for an unsafe -expression. However, a ``safe'' Lisp expression can return a string +expression. However, a safe Lisp expression can return a string with a @code{display} property, containing an associated Lisp expression to be executed after the string is inserted into a buffer. This associated expression can be a virus. In order to be safe, you diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 655f31ab114..22b7217506f 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Hash Tables @chapter Hash Tables @@ -31,10 +31,10 @@ the way two alists can share a common tail. with a series of functions for operating on them. Hash tables have a special printed representation, which consists of @samp{#s} followed by a list specifying the hash table properties and contents. -@xref{Creating Hash}. (Note that the term ``hash notation'', which -refers to the initial @samp{#} character used in the printed +@xref{Creating Hash}. +(Hash notation, the initial @samp{#} character used in the printed representations of objects with no read representation, has nothing to -do with the term ``hash table''. @xref{Printed Representation}.) +do with hash tables. @xref{Printed Representation}.) Obarrays are also a kind of hash table, but they are a different type of object and are used only for recording interned symbols @@ -71,16 +71,16 @@ alternatives: @table @code @item eql -Keys which are numbers are ``the same'' if they are @code{equal}, that +Keys which are numbers are the same if they are @code{equal}, that is, if they are equal in value and either both are integers or both -are floating point numbers; otherwise, two distinct objects are never -``the same''. +are floating point; otherwise, two distinct objects are never +the same. @item eq -Any two distinct Lisp objects are ``different'' as keys. +Any two distinct Lisp objects are different as keys. @item equal -Two Lisp objects are ``the same'', as keys, if they are equal +Two Lisp objects are the same, as keys, if they are equal according to @code{equal}. @end table @@ -128,35 +128,27 @@ doing that takes some extra time. The default size is 65. @item :rehash-size @var{rehash-size} -When you add an association to a hash table and the table is ``full'', +When you add an association to a hash table and the table is full, it grows automatically. This value specifies how to make the hash table larger, at that time. If @var{rehash-size} is an integer, it should be positive, and the hash table grows by adding that much to the nominal size. If -@var{rehash-size} is a floating point number, it had better be greater +@var{rehash-size} is floating point, it had better be greater than 1, and the hash table grows by multiplying the old size by that number. The default value is 1.5. @item :rehash-threshold @var{threshold} -This specifies the criterion for when the hash table is ``full'' (so +This specifies the criterion for when the hash table is full (so it should be made larger). The value, @var{threshold}, should be a -positive floating point number, no greater than 1. The hash table is -``full'' whenever the actual number of entries exceeds this fraction +positive floating-point number, no greater than 1. The hash table is +full whenever the actual number of entries exceeds this fraction of the nominal size. The default for @var{threshold} is 0.8. @end table @end defun -@defun makehash &optional test -This is equivalent to @code{make-hash-table}, but with a different style -argument list. The argument @var{test} specifies the method -of key lookup. - -This function is obsolete. Use @code{make-hash-table} instead. -@end defun - You can also create a new hash table using the printed representation for hash tables. The Lisp reader can read this printed representation, provided each element in the specified hash table has @@ -188,6 +180,8 @@ Such objects may be added to the hash table after it is created. @node Hash Access @section Hash Table Access +@cindex accessing hash tables +@cindex hash table access This section describes the functions for accessing and storing associations in a hash table. In general, any Lisp object can be used @@ -259,14 +253,14 @@ This function defines a new hash table test, named @var{name}. After defining @var{name} in this way, you can use it as the @var{test} argument in @code{make-hash-table}. When you do that, the hash table will use @var{test-fn} to compare key values, and @var{hash-fn} to compute -a ``hash code'' from a key value. +a hash code from a key value. The function @var{test-fn} should accept two arguments, two keys, and -return non-@code{nil} if they are considered ``the same''. +return non-@code{nil} if they are considered the same. The function @var{hash-fn} should accept one argument, a key, and return -an integer that is the ``hash code'' of that key. For good results, the -function should use the whole range of integer values for hash codes, +an integer that is the hash code of that key. For good results, the +function should use the whole range of integers for hash codes, including negative integers. The specified functions are stored in the property list of @var{name} diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index aa77ba1f36d..387587a4203 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Documentation @@ -10,8 +10,13 @@ GNU Emacs has convenient built-in help facilities, most of which derive their information from documentation strings associated with functions and variables. This chapter describes how to access -documentation strings in Lisp programs. @xref{Documentation Tips}, -for how to write good documentation strings. +documentation strings in Lisp programs. + + The contents of a documentation string should follow certain +conventions. In particular, its first line should be a complete +sentence (or two complete sentences) that briefly describes what the +function or variable does. @xref{Documentation Tips}, for how to +write good documentation strings. Note that the documentation strings for Emacs are not the same thing as the Emacs manual. Manuals have their own source files, written in @@ -40,80 +45,52 @@ Help, emacs, The GNU Emacs Manual}. @cindex string, writing a doc string A documentation string is written using the Lisp syntax for strings, -with double-quote characters surrounding the text of the string. This -is because it really is a Lisp string object. The string serves as -documentation when it is written in the proper place in the definition -of a function or variable. In a function definition, the documentation -string follows the argument list. In a variable definition, the -documentation string follows the initial value of the variable. - - When you write a documentation string, make the first line a -complete sentence (or two complete sentences) that briefly describes -what the function or variable does. Some commands, such as -@code{apropos}, show only the first line of a multi-line documentation -string. Also, you should not indent the second line of a -documentation string, if it has one, because that looks odd when you -use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v} -(@code{describe-variable}) to view the documentation string. There -are many other conventions for documentation strings; see -@ref{Documentation Tips}. - - Documentation strings can contain several special text sequences, -referring to key bindings which are looked up in the current keymaps -when the user views the documentation. This allows the help commands -to display the correct keys even if a user rearranges the default key -bindings. @xref{Keys in Documentation}. - - In the documentation string of an autoloaded command -(@pxref{Autoload}), these special text sequences have an additional -special effect: they cause @kbd{C-h f} (@code{describe-function}) on -the command to trigger autoloading. (This is needed for correctly -setting up the hyperlinks in the @file{*Help*} buffer). - -@vindex emacs-lisp-docstring-fill-column - Emacs Lisp mode fills documentation strings to the width -specified by @code{emacs-lisp-docstring-fill-column}. - - Exactly where a documentation string is stored depends on how its -function or variable was defined or loaded into memory: - -@itemize @bullet -@item -@kindex function-documentation -When you define a function (@pxref{Lambda Expressions}, and -@pxref{Function Documentation}), the documentation string is stored in -the function definition itself. You can also put function -documentation in the @code{function-documentation} property of a -function name. That is useful for function definitions which can't -hold a documentation string, such as keyboard macros. - -@item -@kindex variable-documentation -When you define a variable with a @code{defvar} or related form -(@pxref{Defining Variables}), the documentation is stored in the -variable's @code{variable-documentation} property. +with double-quote characters surrounding the text. It is, in fact, an +actual Lisp string. When the string appears in the proper place in a +function or variable definition, it serves as the function's or +variable's documentation. + +@cindex @code{function-documentation} property + In a function definition (a @code{lambda} or @code{defun} form), the +documentation string is specified after the argument list, and is +normally stored directly in the function object. @xref{Function +Documentation}. You can also put function documentation in the +@code{function-documentation} property of a function name +(@pxref{Accessing Documentation}). + +@cindex @code{variable-documentation} property + In a variable definition (a @code{defvar} form), the documentation +string is specified after the initial value. @xref{Defining +Variables}. The string is stored in the variable's +@code{variable-documentation} property. @cindex @file{DOC} (documentation) file -@item -To save memory, the documentation for preloaded functions and -variables (including primitive functions and autoloaded functions) is -not kept in memory, but in the file -@file{emacs/etc/DOC}). - -@item -When a function or variable is loaded from a byte-compiled file during -the Emacs session, its documentation string is not loaded into memory. -Instead, Emacs looks it up in the byte-compiled file as needed. -@xref{Docs and Compilation}. -@end itemize + Sometimes, Emacs does not keep documentation strings in memory. +There are two such circumstances. Firstly, to save memory, the +documentation for preloaded functions and variables (including +primitives) is kept in a file named @file{DOC}, in the directory +specified by @code{doc-directory} (@pxref{Accessing Documentation}). +Secondly, when a function or variable is loaded from a byte-compiled +file, Emacs avoids loading its documentation string (@pxref{Docs and +Compilation}). In both cases, Emacs looks up the documentation string +from the file only when needed, such as when the user calls @kbd{C-h +f} (@code{describe-function}) for a function. + + Documentation strings can contain special @dfn{key substitution +sequences}, referring to key bindings which are looked up only when +the user views the documentation. This allows the help commands to +display the correct keys even if a user rearranges the default key +bindings. @xref{Keys in Documentation}. -@noindent -Regardless of where the documentation string is stored, you can -retrieve it using the @code{documentation} or -@code{documentation-property} function, described in the next section. + In the documentation string of an autoloaded command +(@pxref{Autoload}), these key-substitution sequences have an +additional special effect: they cause @kbd{C-h f} on the command to +trigger autoloading. (This is needed for correctly setting up the +hyperlinks in the @file{*Help*} buffer.) @node Accessing Documentation @section Access to Documentation Strings +@cindex accessing documentation strings @defun documentation-property symbol property &optional verbatim This function returns the documentation string recorded in @@ -122,18 +99,20 @@ most often used to look up the documentation strings of variables, for which @var{property} is @code{variable-documentation}. However, it can also be used to look up other kinds of documentation, such as for customization groups (but for function documentation, use the -@code{documentation} command, below). +@code{documentation} function, below). + +If the property value refers to a documentation string stored in the +@file{DOC} file or a byte-compiled file, this function looks up that +string and returns it. -If the value recorded in the property list refers to a documentation -string stored in a @file{DOC} file or a byte-compiled -file, it looks up that string and returns it. If the property value -isn't @code{nil}, isn't a string, and doesn't refer to text in a file, -then it is evaluated as a Lisp expression to obtain a string. +If the property value isn't @code{nil}, isn't a string, and doesn't +refer to text in a file, then it is evaluated as a Lisp expression to +obtain a string. -The last thing this function does is pass the string through -@code{substitute-command-keys} to substitute actual key bindings -(@pxref{Keys in Documentation}). However, it skips this step if -@var{verbatim} is non-@code{nil}. +Finally, this function passes the string through +@code{substitute-command-keys} to substitute key bindings (@pxref{Keys +in Documentation}). It skips this step if @var{verbatim} is +non-@code{nil}. @smallexample @group @@ -160,16 +139,18 @@ ordinary functions. If @var{function} is a symbol, this function first looks for the @code{function-documentation} property of that symbol; if that has a non-@code{nil} value, the documentation comes from that value (if the -value is not a string, it is evaluated). If @var{function} is not a -symbol, or if it has no @code{function-documentation} property, then -@code{documentation} extracts the documentation string from the actual -function definition, reading it from a file if called for. +value is not a string, it is evaluated). -Finally, unless @var{verbatim} is non-@code{nil}, it calls -@code{substitute-command-keys} so as to return a value containing the -actual (current) key bindings. +If @var{function} is not a symbol, or if it has no +@code{function-documentation} property, then @code{documentation} +extracts the documentation string from the actual function definition, +reading it from a file if called for. -The function @code{documentation} signals a @code{void-function} error +Finally, unless @var{verbatim} is non-@code{nil}, this function calls +@code{substitute-command-keys}. The result is the documentation +string to return. + +The @code{documentation} function signals a @code{void-function} error if @var{function} has no function definition. However, it is OK if the function definition has no documentation string. In that case, @code{documentation} returns @code{nil}. @@ -180,7 +161,6 @@ This function returns the documentation string of @var{face} as a face. @end defun -@c Wordy to prevent overfull hboxes. --rjc 15mar92 Here is an example of using the two functions, @code{documentation} and @code{documentation-property}, to display the documentation strings for several symbols in a @file{*Help*} buffer. @@ -191,7 +171,7 @@ several symbols in a @file{*Help*} buffer. (defun describe-symbols (pattern) "Describe the Emacs Lisp symbols matching PATTERN. All symbols that have PATTERN in their name are described -in the `*Help*' buffer." +in the *Help* buffer." (interactive "sDescribe symbols matching: ") (let ((describe-func (function @@ -262,6 +242,11 @@ Semipermanent goal column for vertical motion, as set by @dots{} @c That makes them incorrect. @group +minibuffer-temporary-goal-position Variable +not documented +@end group + +@group set-goal-column Keys: C-x C-n Set the current horizontal position as a goal for C-n and C-p. @end group @@ -269,17 +254,26 @@ Set the current horizontal position as a goal for C-n and C-p. @group Those commands will move to this position in the line moved to rather than trying to keep the same horizontal position. -With a non-nil argument, clears out the goal column +With a non-nil argument ARG, clears out the goal column so that C-n and C-p resume vertical motion. -The goal column is stored in the variable `goal-column'. +The goal column is stored in the variable ‘goal-column’. + +(fn ARG) @end group @group temporary-goal-column Variable Current goal column for vertical motion. -It is the column where point was -at the start of current run of vertical motion commands. -When the `track-eol' feature is doing its job, the value is 9999. +It is the column where point was at the start of the current run +of vertical motion commands. + +When moving by visual lines via the function ‘line-move-visual’, it is a cons +cell (COL . HSCROLL), where COL is the x-position, in pixels, +divided by the default column width, and HSCROLL is the number of +columns by which window is scrolled from left margin. + +When the ‘track-eol’ feature is doing its job, the value is +‘most-positive-fixnum’. ---------- Buffer: *Help* ---------- @end group @end smallexample @@ -313,6 +307,7 @@ without actually installing it. @xref{Definition of data-directory}. @cindex documentation, keys in @cindex keys in documentation strings @cindex substituting keys in documentation +@cindex key substitution sequence When documentation strings refer to key sequences, they should use the current, actual key bindings. They can do so using certain special text @@ -337,15 +332,38 @@ stands for no text itself. It is used only for a side effect: it specifies @var{mapvar}'s value as the keymap for any following @samp{\[@var{command}]} sequences in this documentation string. +@item ‘ +@itemx ` +(left single quotation mark and grave accent) both stand for a left quote. + +@item ’ +@itemx ' +(right single quotation mark and apostrophe) both stand for a right quote. + @item \= -quotes the following character and is discarded; thus, @samp{\=\[} puts -@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the -output. +quotes the following character and is discarded; thus, @samp{\=`} puts +@samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output, +and @samp{\=\=} puts @samp{\=} into the output. @end table @strong{Please note:} Each @samp{\} must be doubled when written in a string in Emacs Lisp. +@defvar text-quoting-style +@cindex curved quotes +@cindex curly quotes +The value of this variable specifies the style used to generate text +quotes. If the variable's value is @code{curve}, the style is +@t{‘like this’} with curved single quotes. If the value is +@code{straight}, the style is @t{'like this'} with straight +apostrophes. If the value is @code{grave}, the style is @t{`like +this'} with grave accent and apostrophe. The default value @code{nil} +acts like @code{curve} if curved single quotes are displayable, and +like @code{grave} otherwise. To use the traditional @code{grave} +style, put the line @code{(setq text-quoting-style 'grave)} into your +@file{~/.emacs} file. +@end defvar + @defun substitute-command-keys string This function scans @var{string} for the above special sequences and replaces them by what they stand for, returning the result as a string. @@ -373,8 +391,8 @@ specifies a key binding that the command does not actually have. @smallexample @group (substitute-command-keys - "To abort recursive edit, type: \\[abort-recursive-edit]") -@result{} "To abort recursive edit, type: C-]" + "To abort recursive edit, type `\\[abort-recursive-edit]'.") +@result{} "To abort recursive edit, type ‘C-]’." @end group @group @@ -394,9 +412,9 @@ C-g abort-recursive-edit @group (substitute-command-keys - "To abort a recursive edit from the minibuffer, type\ -\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].") -@result{} "To abort a recursive edit from the minibuffer, type C-g." + "To abort a recursive edit from the minibuffer, type \ +`\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.") +@result{} "To abort a recursive edit from the minibuffer, type ‘C-g’." @end group @end smallexample @@ -527,18 +545,19 @@ non-@code{nil}, the return value is always a vector. @node Help Functions @section Help Functions +@cindex help functions - Emacs provides a variety of on-line help functions, all accessible to + Emacs provides a variety of built-in help functions, all accessible to the user as subcommands of the prefix @kbd{C-h}. For more information about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here we describe some program-level interfaces to the same information. @deffn Command apropos pattern &optional do-all -This function finds all ``meaningful'' symbols whose names contain a +This function finds all meaningful symbols whose names contain a match for the apropos pattern @var{pattern}. An apropos pattern is either a word to match, a space-separated list of words of which at least two must match, or a regular expression (if any special regular -expression characters occur). A symbol is ``meaningful'' if it has a +expression characters occur). A symbol is meaningful if it has a definition as a function, variable, or face, or has properties. The function returns a list of elements that look like this: @@ -603,7 +622,7 @@ subcommands of the prefix key. @defopt help-event-list The value of this variable is a list of event types that serve as -alternative ``help characters''. These events are handled just like the +alternative help characters. These events are handled just like the event specified by @code{help-char}. @end defopt @@ -638,7 +657,7 @@ sequence. (The last event is, presumably, the help character.) @end deffn The following two functions are meant for modes that want to provide -help without relinquishing control, such as the ``electric'' modes. +help without relinquishing control, such as the electric modes. Their names begin with @samp{Helper} to distinguish them from the ordinary help functions. @@ -669,14 +688,17 @@ This function returns the name of the help buffer, which is normally @file{*Help*}; if such a buffer does not exist, it is first created. @end defun +@vindex help-window-select @defmac with-help-window buffer-name body@dots{} -This macro evaluates the @var{body} forms, inserting any output they -produce into a buffer named @var{buffer-name} like -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}). -(Usually, @var{buffer-name} should be the value returned by the -function @code{help-buffer}.) It also puts the specified buffer into -Help mode and displays a message telling the user how to quit and -scroll the help window. +This macro evaluates @var{body} like @code{with-output-to-temp-buffer} +(@pxref{Temporary Displays}), inserting any output produced by its forms +into a buffer named @var{buffer-name}. (Usually, @var{buffer-name} +should be the value returned by the function @code{help-buffer}.) It +also puts the specified buffer into Help mode and displays a message +telling the user how to quit and scroll the help window. It selects the +help window if the current value of the user option +@code{help-window-select} has been set accordingly. It returns the last +value in @var{body}. @end defmac @defun help-setup-xref item interactive-p diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 745393f8166..eb2e34318fd 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1993, 1998, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Hooks @@ -56,6 +56,7 @@ not exactly a hook, but does a similar job. @item after-init-hook @itemx before-init-hook @itemx emacs-startup-hook +@itemx window-setup-hook @xref{Init File}. @item after-insert-file-functions @@ -99,11 +100,11 @@ Hook run after a frame's font changes. @item buffer-list-update-hook @vindex buffer-list-update-hook -Hook run when the buffer list changes. +Hook run when the buffer list changes (@pxref{Buffer List}). @item buffer-quit-function @vindex buffer-quit-function -Function to call to ``quit'' the current buffer. +Function to call to quit the current buffer. @item change-major-mode-hook @xref{Creating Buffer-Local}. @@ -115,6 +116,12 @@ Function to call to ``quit'' the current buffer. @vindex delayed-warnings-hook The command loop runs this soon after @code{post-command-hook} (q.v.). +@item focus-in-hook +@vindex focus-in-hook +@itemx focus-out-hook +@vindex focus-out-hook +@xref{Input Focus}. + @item delete-frame-functions @xref{Deleting Frames}. @@ -207,7 +214,7 @@ Hook run when about to switch windows with a mouse command. @itemx temp-buffer-show-hook @xref{Temporary Displays}. -@item term-setup-hook +@item tty-setup-hook @xref{Terminal-Specific}. @item window-configuration-change-hook @@ -215,9 +222,6 @@ Hook run when about to switch windows with a mouse command. @itemx window-size-change-functions @xref{Window Hooks}. -@item window-setup-hook -@xref{Window Systems}. - @item window-text-change-functions @vindex window-text-change-functions Functions to call in redisplay when text in the window might change. @@ -235,11 +239,9 @@ choose-completion-string-functions completing-read-function completion-annotate-function completion-at-point-functions -completion-in-region-functions completion-list-insert-choice-function deactivate-current-input-method-function describe-current-input-method-function -filter-buffer-substring-functions font-lock-function menu-bar-select-buffer-function read-file-name-function diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 06375c1e18e..e620da0b4ff 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1993, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node GNU Emacs Internals @@ -14,7 +14,9 @@ internal aspects of GNU Emacs that may be of interest to C programmers. * Building Emacs:: How the dumped Emacs is made. * Pure Storage:: Kludge to make preloaded Lisp functions shareable. * Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* Stack-allocated Objects:: Temporary conses and strings on C stack. * Memory Usage:: Info about total size of Lisp objects made so far. +* C Dialect:: What C variant Emacs is written in. * Writing Emacs Primitives:: Writing C code for Emacs. * Object Internals:: Data formats of buffers, windows, processes. * C Integer Types:: How C integer types are used inside Emacs. @@ -111,11 +113,18 @@ drawback that the documentation strings take up space in Emacs all the time.) @end itemize +@cindex change @code{load-path} at configure time +@cindex @option{--enable-locallisppath} option to @command{configure} It is not advisable to put anything in @file{site-load.el} or @file{site-init.el} that would alter any of the features that users expect in an ordinary unmodified Emacs. If you feel you must override normal features for your site, do it with @file{default.el}, so that users can override your changes if they wish. @xref{Startup Summary}. +Note that if either @file{site-load.el} or @file{site-init.el} changes +@code{load-path}, the changes will be lost after dumping. +@xref{Library Search}. To make a permanent change to +@code{load-path}, use the @option{--enable-locallisppath} option +of @command{configure}. In a package that can be preloaded, it is sometimes necessary (or useful) to delay certain evaluations until Emacs subsequently starts @@ -249,7 +258,7 @@ accessible objects are also accessible. matter what the Lisp program or the user does, it is impossible to refer to them, since there is no longer a way to reach them. Their space might as well be reused, since no one will miss them. The second -(``sweep'') phase of the garbage collector arranges to reuse them. +(sweep) phase of the garbage collector arranges to reuse them. @c ??? Maybe add something describing weak hash tables here? @@ -505,6 +514,11 @@ created in this Emacs session. Each of these counters increments for a certain kind of object. See the documentation string for details. @end defun +@defun memory-info +This functions returns an amount of total system memory and how much +of it is free. On an unsupported system, the value may be @code{nil}. +@end defun + @defvar gcs-done This variable contains the total number of garbage collections done so far in this Emacs session. @@ -512,10 +526,39 @@ done so far in this Emacs session. @defvar gc-elapsed This variable contains the total number of seconds of elapsed time -during garbage collection so far in this Emacs session, as a floating -point number. +during garbage collection so far in this Emacs session, as a +floating-point number. @end defvar +@node Stack-allocated Objects +@section Stack-allocated Objects + +@cindex stack allocated Lisp objects +@cindex Lisp objects, stack-allocated + The garbage collector described above is used to manage data visible +from Lisp programs, as well as most of the data internally used by the +Lisp interpreter. Sometimes it may be useful to allocate temporary +internal objects using the C stack of the interpreter. This can help +performance, as stack allocation is typically faster than using heap +memory to allocate and the garbage collector to free. The downside is +that using such objects after they are freed results in undefined +behavior, so uses should be well thought out and carefully debugged by +using the @code{GC_CHECK_MARKED_OBJECTS} feature (see +@file{src/alloc.c}). In particular, stack-allocated objects should +never be made visible to user Lisp code. + + Currently, cons cells and strings can be allocated this way. This +is implemented by C macros like @code{AUTO_CONS} and +@code{AUTO_STRING} that define a named @code{Lisp_Object} with block +lifetime. These objects are not freed by the garbage collector; +instead, they have automatic storage duration, i.e., they are +allocated like local variables and are automatically freed at the end +of execution of the C block that defined the object. + + For performance reasons, stack-allocated strings are limited to +@acronym{ASCII} characters, and many of these strings are immutable, +i.e., calling @code{ASET} on them produces undefined behavior. + @node Memory Usage @section Memory Usage @cindex memory usage @@ -568,6 +611,19 @@ The total number of strings that have been allocated so far in this Emacs session. @end defvar +@node C Dialect +@section C Dialect +@cindex C programming language + +The C part of Emacs is portable to C99 or later: C11-specific features such +as @samp{<stdalign.h>} and @samp{_Noreturn} are not used without a check, +typically at configuration time, and the Emacs build procedure +provides a substitute implementation if necessary. Some C11 features, +such as anonymous structures and unions, are too difficult to emulate, +so they are avoided entirely. + +At some point in the future the base C dialect will no doubt change to C11. + @node Writing Emacs Primitives @section Writing Emacs Primitives @cindex primitive function internals @@ -582,7 +638,6 @@ to read the source, but we can explain some things here. @file{eval.c}. (An ordinary function would have the same general appearance.) -@cindex garbage collection protection @smallexample @group DEFUN ("or", For, Sor, 0, UNEVALLED, 0, @@ -592,15 +647,10 @@ The remaining args are not evalled at all. If all args return nil, return nil. @end group @group -usage: (or CONDITIONS ...) */) +usage: (or CONDITIONS...) */) (Lisp_Object args) @{ - register Lisp_Object val = Qnil; - struct gcpro gcpro1; -@end group - -@group - GCPRO1 (args); + Lisp_Object val = Qnil; @end group @group @@ -610,11 +660,11 @@ usage: (or CONDITIONS ...) */) if (!NILP (val)) break; args = XCDR (args); + QUIT; @} @end group @group - UNGCPRO; return val; @} @end group @@ -718,36 +768,25 @@ a primitive to accept only a certain type of argument, you must check the type explicitly using a suitable predicate (@pxref{Type Predicates}). @cindex type checking internals -@cindex @code{GCPRO} and @code{UNGCPRO} +@cindex garbage collection protection @cindex protect C variables from garbage collection - Within the function @code{For} itself, note the use of the macros -@code{GCPRO1} and @code{UNGCPRO}. These macros are defined for the -sake of the few platforms which do not use Emacs' default -stack-marking garbage collector. The @code{GCPRO1} macro ``protects'' -a variable from garbage collection, explicitly informing the garbage -collector that that variable and all its contents must be as -accessible. GC protection is necessary in any function which can -perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as -a subroutine, either directly or indirectly. - - It suffices to ensure that at least one pointer to each object is -GC-protected. Thus, a particular local variable can do without -protection if it is certain that the object it points to will be -preserved by some other pointer (such as another local variable that -has a @code{GCPRO}). Otherwise, the local variable needs a -@code{GCPRO}. - - The macro @code{GCPRO1} protects just one local variable. If you -want to protect two variables, use @code{GCPRO2} instead; repeating -@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4}, -@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros -implicitly use local variables such as @code{gcpro1}; you must declare -these explicitly, with type @code{struct gcpro}. Thus, if you use -@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. - - @code{UNGCPRO} cancels the protection of the variables that are -protected in the current function. It is necessary to do this -explicitly. + Within the function @code{For} itself, the local variable +@code{args} refers to objects controlled by Emacs's stack-marking +garbage collector. Although the garbage collector does not reclaim +objects reachable from C @code{Lisp_Object} stack variables, it may +move non-object components of an object, such as string contents; so +functions that access non-object components must take care to refetch +their addresses after performing Lisp evaluation. Lisp evaluation can +occur via calls to @code{eval_sub} or @code{Feval}, either directly or +indirectly. + +@cindex @code{QUIT}, use in Lisp primitives + Note the call to the @code{QUIT} macro inside the loop: this macro +checks whether the user pressed @kbd{C-g}, and if so, aborts the +processing. You should do that in any loop that can potentially +require a large number of iterations; in this case, the list of +arguments could be very long. This increases Emacs responsiveness and +improves user experience. You must not use C initializers for static or global variables unless the variables are never written once Emacs is dumped. These variables @@ -842,14 +881,14 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, @group switch (coordinates_in_window (w, x, y)) @{ - case ON_NOTHING: /* NOT in window at all. */ + case ON_NOTHING: /* NOT in window at all. */ return Qnil; @end group ... @group - case ON_MODE_LINE: /* In mode line of window. */ + case ON_MODE_LINE: /* In mode line of window. */ return Qmode_line; @end group @@ -876,9 +915,7 @@ the Lisp function @code{funcall} accepts an unlimited number of arguments, in C it takes two: the number of Lisp-level arguments, and a one-dimensional array containing their values. The first Lisp-level argument is the Lisp function to call, and the rest are the arguments to -pass to it. Since @code{Ffuncall} can call the evaluator, you must -protect pointers from garbage collection around the call to -@code{Ffuncall}. +pass to it. The C functions @code{call0}, @code{call1}, @code{call2}, and so on, provide handy ways to call a Lisp function conveniently with a fixed @@ -912,7 +949,7 @@ following basic data types: integer, symbol, string, cons cell, float, vectorlike or miscellaneous object. Each of these data types has the corresponding tag value. All tags are enumerated by @code{enum Lisp_Type} and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the -bits is the value itself. Integer values are immediate, i.e., directly +bits is the value itself. Integers are immediate, i.e., directly represented by those @dfn{value bits}, and all other objects are represented by the C pointers to a corresponding object allocated from the heap. Width of the @code{Lisp_Object} is platform- and configuration-dependent: usually @@ -940,7 +977,7 @@ Array, a fixed-size set of Lisp objects which may be accessed by an index. Symbol, the unique-named entity commonly used as an identifier. @item struct Lisp_Float -Floating point value. +Floating-point value. @item union Lisp_Misc Miscellaneous kinds of objects which don't fit into any of the above. @@ -1261,6 +1298,8 @@ except to shape their child windows. Emacs Lisp programs usually have no access to the parent windows; they operate on the windows at the leaves of the tree, which actually display buffers. +@c FIXME: These two slots and the 'buffer' slot below were replaced +@c with a single slot 'contents' on 2013-03-28. --xfq @item hchild @itemx vchild These fields contain the window's leftmost child and its topmost child @@ -1338,7 +1377,7 @@ The buffer's value of point, as of the last time a redisplay completed in this window. @item last_had_star -A non-@code{nil} value means the window's buffer was ``modified'' when the +A non-@code{nil} value means the window's buffer was modified when the window was last updated. @item vertical_scroll_bar @@ -1432,11 +1471,6 @@ The position in the buffer for which the line number is known, or @code{nil} meaning none is known. If it is a buffer, don't display the line number as long as the window shows that buffer. -@item region_showing -If the region (or part of it) is highlighted in this window, this field -holds the mark position that made one end of that region. Otherwise, -this field is @code{nil}. - @item column_number_displayed The column number currently displayed in this window's mode line, or @code{nil} if column numbers are not being displayed. @@ -1464,12 +1498,10 @@ process. For a network or serial process, it is @code{nil} if the process is running or @code{t} if the process is stopped. @item filter -If non-@code{nil}, a function used to accept output from the process -instead of a buffer. +A function used to accept output from the process. @item sentinel -If non-@code{nil}, a function called whenever the state of the process -changes. +A function called whenever the state of the process changes. @item buffer The associated buffer of the process. @@ -1561,7 +1593,7 @@ fit in @code{int} range. Do not assume that signed integer arithmetic wraps around on overflow. This is no longer true of Emacs porting targets: signed integer overflow has undefined behavior in practice, and can dump core or -even cause earlier or later code to behave ``illogically''. Unsigned +even cause earlier or later code to behave illogically. Unsigned overflow does wrap around reliably, modulo a power of two. @item @@ -1573,7 +1605,9 @@ similar advice may apply to the unsigned counterparts (e.g., of @code{intptr_t}). @item -Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF. +Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF@. +More generally, prefer @code{int} for integers known to be in +@code{int} range, e.g., screen column counts. @item Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the @@ -1585,6 +1619,17 @@ anyway since they would break pointer subtraction, so this does not impose an arbitrary limit. @item +Avoid @code{ssize_t} except when communicating to low-level APIs that +have @code{ssize_t}-related limitations. Although it's equivalent to +@code{ptrdiff_t} on typical platforms, @code{ssize_t} is occasionally +narrower, so using it for size-related calculations could overflow. +Also, @code{ptrdiff_t} is more ubiquitous and better-standardized, has +standard @code{printf} formats, and is the basis for Emacs's internal +size-overflow checking. When using @code{ssize_t}, please note that +POSIX requires support only for values in the range @minus{}1 ..@: +@code{SSIZE_MAX}. + +@item Prefer @code{intptr_t} for internal representations of pointers, or for integers bounded only by the number of objects that can exist at any given time or by the total number of bytes that can be allocated. @@ -1606,7 +1651,7 @@ although @code{off_t} is always signed, @code{time_t} need not be. @item Prefer the Emacs-defined type @code{printmax_t} for representing -values that might be any signed integer value that can be printed, +values that might be any signed integer that can be printed, using a @code{printf}-family function. @item @@ -1614,20 +1659,21 @@ Prefer @code{intmax_t} for representing values that might be any signed integer value. @item -In bitfields, prefer @code{unsigned int} or @code{signed int} to -@code{int}, as @code{int} is less portable: it might be signed, and -might not be. Single-bit bit fields are invariably @code{unsigned -int} so that their values are 0 and 1. - -@item -In C, Emacs commonly uses @code{bool}, 1, and 0 for boolean values. -Using @code{bool} for booleans can make programs easier to read and a -bit faster than using @code{int}. Although it is also OK to use -@code{int}, this older style is gradually being phased out. When +Prefer @code{bool}, @code{false} and @code{true} for booleans. +Using @code{bool} can make programs easier to read and a bit faster than +using @code{int}. Although it is also OK to use @code{int}, @code{0} +and @code{1}, this older style is gradually being phased out. When using @code{bool}, respect the limitations of the replacement implementation of @code{bool}, as documented in the source file -@file{lib/stdbool.in.h}, so that Emacs remains portable to pre-C99 -platforms. +@file{lib/stdbool.in.h}. In particular, boolean bitfields should be of type +@code{bool_bf}, not @code{bool}, so that they work correctly even when +compiling Objective C with standard GCC. + +@item +In bitfields, prefer @code{unsigned int} or @code{signed int} to +@code{int}, as @code{int} is less portable: it might be signed, and +might not be. Single-bit bit fields should be @code{unsigned int} or +@code{bool_bf} so that their values are 0 or 1. @end itemize @c FIXME Mention src/globals.h somewhere in this file? diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 803e5229f6e..865c6984864 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -1,6 +1,6 @@ @c -*-coding: utf-8-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Introduction @@ -9,7 +9,7 @@ Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming +than a mere extension language; it is a full computer programming language in its own right. You can use it as you would any other programming language. @@ -148,8 +148,8 @@ manual. You may want to skip this section and refer back to it later. printer'' refer to those routines in Lisp that convert textual representations of Lisp objects into actual Lisp objects, and vice versa. @xref{Printed Representation}, for more details. You, the -person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you''. ``The user'' is the person who uses Lisp +person reading this manual, are thought of as the programmer and are +addressed as ``you''. The user is the person who uses Lisp programs, including those you write. @cindex typographic conventions @@ -287,7 +287,7 @@ the echo area. @cindex buffer text notation Some examples describe modifications to the contents of a buffer, by -showing the ``before'' and ``after'' versions of the text. These +showing the before and after versions of the text. These examples show the contents of the buffer in question between two lines of dashes containing the buffer name. In addition, @samp{@point{}} indicates the location of point. (The symbol for point, of course, is @@ -456,7 +456,7 @@ described using a format like that for functions, except that there are no arguments. Here is a description of the imaginary @code{electric-future-map} -variable.@refill +variable. @defvar electric-future-map The value of this variable is a full keymap used by Electric Command @@ -480,8 +480,8 @@ running. It is useful to include this string in bug reports. @smallexample @group (emacs-version) - @result{} "GNU Emacs 23.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4) - of 2009-06-01 on cyd.mit.edu" + @result{} "GNU Emacs 24.5.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.16) + of 2015-06-01" @end group @end smallexample @@ -545,11 +545,11 @@ Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, Jesper Harder, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland McGrath, Stefan Monnier, Skip -Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, +Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potortì, Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney, Per Starbäck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn. For a more complete list of contributors, please see the relevant -ChangeLog file in the Emacs sources. +change log entries in the Emacs source repository. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index ef020364082..9bea4b0af1c 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Keymaps @chapter Keymaps @@ -622,75 +622,67 @@ string for the keymap. The prompt string should be given for menu keymaps @node Active Keymaps @section Active Keymaps @cindex active keymap -@cindex global keymap -@cindex local keymap - - Emacs normally contains many keymaps; at any given time, just a few -of them are @dfn{active}, meaning that they participate in the -interpretation of user input. All the active keymaps are used -together to determine what command to execute when a key is entered. - - Normally the active keymaps are the @code{keymap} property keymap, -the keymaps of any enabled minor modes, the current buffer's local -keymap, and the global keymap, in that order. Emacs searches for each -input key sequence in all these keymaps. @xref{Searching Keymaps}, -for more details of this procedure. - - When the key sequence starts with a mouse event, -the active keymaps are determined based on the -position in that event. If the event happened on a string embedded -with a @code{display}, @code{before-string}, or @code{after-string} -property (@pxref{Special Properties}), the non-@code{nil} map -properties of the string override those of the buffer (if the -underlying buffer text contains map properties in its text properties -or overlays, they are ignored). - - The @dfn{global keymap} holds the bindings of keys that are defined -regardless of the current buffer, such as @kbd{C-f}. The variable -@code{global-map} holds this keymap, which is always active. - - Each buffer may have another keymap, its @dfn{local keymap}, which -may contain new or overriding definitions for keys. The current -buffer's local keymap is always active except when -@code{overriding-local-map} overrides it. The @code{local-map} text -or overlay property can specify an alternative local keymap for certain -parts of the buffer; see @ref{Special Properties}. - - Each minor mode can have a keymap; if it does, the keymap is active -when the minor mode is enabled. Modes for emulation can specify -additional active keymaps through the variable -@code{emulation-mode-map-alists}. - - The highest precedence normal keymap comes from the @code{keymap} -text or overlay property. If that is non-@code{nil}, it is the first -keymap to be processed, in normal circumstances. - - However, there are also special ways for programs to substitute -other keymaps for some of those. The variable -@code{overriding-local-map}, if non-@code{nil}, specifies a keymap -that replaces all the usual active keymaps except the global keymap. - -The very highest precedence keymap comes from -@code{overriding-terminal-local-map}; it operates on a per-terminal basis and -is normally used for modal/transient keybindings. -@cindex major mode keymap - Since every buffer that uses the same major mode normally uses the -same local keymap, you can think of the keymap as local to the mode. A -change to the local keymap of a buffer (using @code{local-set-key}, for -example) is seen also in the other buffers that share that keymap. + Emacs contains many keymaps, but at any time only a few keymaps are +@dfn{active}. When Emacs receives user input, it translates the input +event (@pxref{Translation Keymaps}), and looks for a key binding in +the active keymaps. + + Usually, the active keymaps are: (i) the keymap specified by the +@code{keymap} property, (ii) the keymaps of enabled minor modes, (iii) +the current buffer's local keymap, and (iv) the global keymap, in that +order. Emacs searches for each input key sequence in all these +keymaps. + + Of these usual keymaps, the highest-precedence one is specified +by the @code{keymap} text or overlay property at point, if any. (For +a mouse input event, Emacs uses the event position instead of point; +@iftex +see the next section for details.) +@end iftex +@ifnottex +@pxref{Searching Keymaps}.) +@end ifnottex + + Next in precedence are keymaps specified by enabled minor modes. +These keymaps, if any, are specified by the variables +@code{emulation-mode-map-alists}, +@code{minor-mode-overriding-map-alist}, and +@code{minor-mode-map-alist}. @xref{Controlling Active Maps}. - The local keymaps that are used for Lisp mode and some other major -modes exist even if they have not yet been used. These local keymaps are -the values of variables such as @code{lisp-mode-map}. For most major -modes, which are less frequently used, the local keymap is constructed -only when the mode is used for the first time in a session. +@cindex local keymap + Next in precedence is the buffer's @dfn{local keymap}, containing +key bindings specific to the buffer. The minibuffer also has a local +keymap (@pxref{Intro to Minibuffers}). If there is a @code{local-map} +text or overlay property at point, that specifies the local keymap to +use, in place of the buffer's default local keymap. - The minibuffer has local keymaps, too; they contain various completion -and exit commands. @xref{Intro to Minibuffers}. +@cindex major mode keymap + The local keymap is normally set by the buffer's major mode, and +every buffer with the same major mode shares the same local keymap. +Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands}) +to change the local keymap in one buffer, that also affects the local +keymaps in other buffers with the same major mode. - Emacs has other keymaps that are used in a different way---translating -events within @code{read-key-sequence}. @xref{Translation Keymaps}. +@cindex global keymap + Finally, the @dfn{global keymap} contains key bindings that are +defined regardless of the current buffer, such as @kbd{C-f}. It is +always active, and is bound to the variable @code{global-map}. + + Apart from the above usual keymaps, Emacs provides special ways +for programs to make other keymaps active. Firstly, the variable +@code{overriding-local-map} specifies a keymap that replaces the usual +active keymaps, except for the global keymap. Secondly, the +terminal-local variable @code{overriding-terminal-local-map} specifies +a keymap that takes precedence over @emph{all} other keymaps +(including @code{overriding-local-map}); this is normally used for +modal/transient keybindings (the function @code{set-transient-map} +provides a convenient interface for this). @xref{Controlling Active +Maps}, for details. + + Making keymaps active is not the only way to use them. Keymaps are +also used in other ways, such as for translating events within +@code{read-key-sequence}. @xref{Translation Keymaps}. @xref{Standard Keymaps}, for a list of some standard keymaps. @@ -727,7 +719,7 @@ If @var{position} is non-@code{nil}, it should be either a buffer position or an event position like the value of @code{event-start}. Then the maps consulted are determined based on @var{position}. -An error is signaled if @var{key} is not a string or a vector. +Emacs signals an error if @var{key} is not a string or a vector. @example @group @@ -741,49 +733,56 @@ An error is signaled if @var{key} is not a string or a vector. @section Searching the Active Keymaps @cindex searching active keymaps for keys - After translation of event subsequences (@pxref{Translation -Keymaps}) Emacs looks for them in the active keymaps. Here is a -pseudo-Lisp description of the order and conditions for searching -them: +Here is a pseudo-Lisp summary of how Emacs searches the active +keymaps: @lisp -(or (cond - (overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map)) - (overriding-local-map - (@var{find-in} overriding-local-map)) - ((or (@var{find-in} (get-char-property (point) 'keymap)) - (@var{find-in} @var{temp-map}) +(or (if overriding-terminal-local-map + (@var{find-in} overriding-terminal-local-map)) + (if overriding-local-map + (@var{find-in} overriding-local-map) + (or (@var{find-in} (get-char-property (point) 'keymap)) (@var{find-in-any} emulation-mode-map-alists) (@var{find-in-any} minor-mode-overriding-map-alist) (@var{find-in-any} minor-mode-map-alist) (if (get-text-property (point) 'local-map) (@var{find-in} (get-char-property (point) 'local-map)) - (@var{find-in} (current-local-map)))))) + (@var{find-in} (current-local-map))))) (@var{find-in} (current-global-map))) @end lisp @noindent -@var{find-in} and @var{find-in-any} are pseudo functions that search -in one keymap and in an alist of keymaps, respectively. (Searching a -single keymap for a binding is called @dfn{key lookup}; see @ref{Key -Lookup}.) If the key sequence starts with a mouse event, that event's position -is used instead of point and the current buffer. Mouse events on an -embedded string use non-@code{nil} text properties from that string -instead of the buffer. @var{temp-map} is a pseudo variable that -represents the effect of a @code{set-temporary-overlay-map} call. - - When a match is found (@pxref{Key Lookup}), if the binding in the -keymap is a function, the search is over. However if the keymap entry -is a symbol with a value or a string, Emacs replaces the input key -sequences with the variable's value or the string, and restarts the -search of the active keymaps. - - The function finally found might also be remapped. @xref{Remapping -Commands}. +Here, @var{find-in} and @var{find-in-any} are pseudo functions that +search in one keymap and in an alist of keymaps, respectively. Note +that the @code{set-transient-map} function works by setting +@code{overriding-terminal-local-map} (@pxref{Controlling Active +Maps}). + + In the above pseudo-code, if a key sequence starts with a mouse +event (@pxref{Mouse Events}), that event's position is used instead of +point, and the event's buffer is used instead of the current buffer. +In particular, this affects how the @code{keymap} and @code{local-map} +properties are looked up. If a mouse event occurs on a string +embedded with a @code{display}, @code{before-string}, or +@code{after-string} property (@pxref{Special Properties}), and the +string has a non-@code{nil} @code{keymap} or @code{local-map} +property, that overrides the corresponding property in the underlying +buffer text (i.e., the property specified by the underlying text is +ignored). + + When a key binding is found in one of the active keymaps, and that +binding is a command, the search is over---the command is executed. +However, if the binding is a symbol with a value or a string, Emacs +replaces the input key sequences with the variable's value or the +string, and restarts the search of the active keymaps. @xref{Key +Lookup}. + + The command which is finally found might also be remapped. +@xref{Remapping Commands}. @node Controlling Active Maps @section Controlling the Active Keymaps +@cindex active keymap, controlling @defvar global-map This variable contains the default global keymap that maps Emacs @@ -857,7 +856,6 @@ keymap. @code{use-local-map} returns @code{nil}. Most major mode commands use this function. @end defun -@c Emacs 19 feature @defvar minor-mode-map-alist @anchor{Definition of minor-mode-map-alist} This variable is an alist describing keymaps that may or may not be @@ -942,28 +940,34 @@ event is run directly by @code{read-event}. @xref{Special Events}. @end defvar @defvar emulation-mode-map-alists -This variable holds a list of keymap alists to use for emulations +This variable holds a list of keymap alists to use for emulation modes. It is intended for modes or packages using multiple minor-mode keymaps. Each element is a keymap alist which has the same format and meaning as @code{minor-mode-map-alist}, or a symbol with a variable -binding which is such an alist. The ``active'' keymaps in each alist +binding which is such an alist. The active keymaps in each alist are used before @code{minor-mode-map-alist} and @code{minor-mode-overriding-map-alist}. @end defvar -@defun set-temporary-overlay-map keymap &optional keep -This function adds @var{keymap} as a temporary keymap that takes -precedence over most other keymaps. It does not take precedence over -the ``overriding'' maps (see above); and unlike them, if no match for -a key is found in @var{keymap}, the search continues. - -Normally, @var{keymap} is used only once. If the optional argument -@var{pred} is @code{t}, the map stays active if a key from @var{keymap} -is used. @var{pred} can also be a function of no arguments: if it returns -non-@code{nil} then @var{keymap} stays active. - -For a pseudo-Lisp description of exactly how and when this keymap applies, -@pxref{Searching Keymaps}. +@cindex transient keymap +@defun set-transient-map keymap &optional keep +This function adds @var{keymap} as a @dfn{transient} keymap, which +takes precedence over other keymaps for one (or more) subsequent keys. + +Normally, @var{keymap} is used just once, to look up the very next +key. If the optional argument @var{pred} is @code{t}, the map stays +active as long as the user types keys defined in @var{keymap}; when +the user types a key that is not in @var{keymap}, the transient keymap +is deactivated and normal key lookup continues for that key. + +The @var{pred} argument can also be a function. In that case, the +function is called with no arguments, prior to running each command, +while @var{keymap} is active; it should return non-@code{nil} if +@var{keymap} should stay active. + +This function works by adding and removing @code{keymap} from the +variable @code{overriding-terminal-local-map}, which takes precedence +over all other active keymaps (@pxref{Searching Keymaps}). @end defun @node Key Lookup @@ -979,7 +983,7 @@ not part of key lookup. the rest of the event is ignored. In fact, a key sequence used for key lookup may designate a mouse event with just its types (a symbol) instead of the entire event (a list). @xref{Input Events}. Such -a ``key sequence'' is insufficient for @code{command-execute} to run, +a key sequence is insufficient for @code{command-execute} to run, but it is sufficient for looking up or rebinding a key. When the key sequence consists of multiple events, key lookup @@ -1040,22 +1044,6 @@ lambda expression. This is presumed to be a function, and is treated as such (see above). In order to execute properly as a key binding, this function must be a command---it must have an @code{interactive} specification. @xref{Defining Commands}. - -@item -If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event -type, then this is an @dfn{indirect entry}: - -@example -(@var{othermap} . @var{othertype}) -@end example - -When key lookup encounters an indirect entry, it looks up instead the -binding of @var{othertype} in @var{othermap} and uses that. - -This feature permits you to define one key as an alias for another key. -For example, an entry whose @sc{car} is the keymap called @code{esc-map} -and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global -binding of @kbd{Meta-@key{SPC}}, whatever that may be''. @end itemize @item @var{symbol} @@ -1063,9 +1051,7 @@ binding of @kbd{Meta-@key{SPC}}, whatever that may be''. The function definition of @var{symbol} is used in place of @var{symbol}. If that too is a symbol, then this process is repeated, any number of times. Ultimately this should lead to an object that is -a keymap, a command, or a keyboard macro. A list is allowed if it is a -keymap or a command, but indirect entries are not understood when found -via symbols. +a keymap, a command, or a keyboard macro. Note that keymaps and keyboard macros (strings and vectors) are not valid functions, so a symbol with a keymap, string, or vector as its @@ -1083,7 +1069,7 @@ thing that is done automatically for an undefined key: it rings the bell @cindex preventing prefix key @code{undefined} is used in local keymaps to override a global key -binding and make the key ``undefined'' locally. A local binding of +binding and make the key undefined locally. A local binding of @code{nil} would fail to do this because it would not override the global binding. @@ -1094,8 +1080,7 @@ binding is not executable as a command. @end table In short, a keymap entry may be a keymap, a command, a keyboard -macro, a symbol that leads to one of them, or an indirection or -@code{nil}. +macro, a symbol that leads to one of them, or @code{nil}. @node Functions for Key Lookup @section Functions for Key Lookup @@ -1123,7 +1108,7 @@ the other functions described in this chapter that look up keys use @end example If the string or vector @var{key} is not a valid key sequence according -to the prefix keys specified in @var{keymap}, it must be ``too long'' +to the prefix keys specified in @var{keymap}, it must be too long and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of @var{key} that compose a complete key. @@ -1548,32 +1533,36 @@ specifies a list of keymaps to search in. This argument is ignored if @node Translation Keymaps @section Keymaps for Translating Sequences of Events +@cindex translation keymap @cindex keymaps for translating events - This section describes keymaps that are used during reading a key -sequence, to translate certain event sequences into others. -@code{read-key-sequence} checks every subsequence of the key sequence -being read, as it is read, against @code{input-decode-map}, then -@code{local-function-key-map}, and then against @code{key-translation-map}. - -These keymaps have the same structure as other keymaps, but they are used -differently: they specify translations to make while reading key sequences, -rather than bindings for key sequences. - -If one of these keymaps ``binds'' a key sequence @var{k} to a vector -@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a -key sequence, it is replaced with the events in @var{v}. - -For example, VT100 terminals send @kbd{@key{ESC} O P} when the -keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate -that sequence of events into the single event @code{pf1}. We accomplish -this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in -@code{input-decode-map}, when using a VT100. - -Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c -@key{ESC} O P}; later the function @code{read-key-sequence} translates -this back into @kbd{C-c @key{PF1}}, which it returns as the vector -@code{[?\C-c pf1]}. + When the @code{read-key-sequence} function reads a key sequence +(@pxref{Key Sequence Input}), it uses @dfn{translation keymaps} to +translate certain event sequences into others. The translation +keymaps are @code{input-decode-map}, @code{local-function-key-map}, +and @code{key-translation-map} (in order of priority). + + Translation keymaps have the same structure as other keymaps, but +are used differently: they specify translations to make while reading +key sequences, rather than bindings for complete key sequences. As +each key sequence is read, it is checked against each translation +keymap. If one of the translation keymaps binds @var{k} to a +vector @var{v}, then whenever @var{k} appears as a sub-sequence +@emph{anywhere} in a key sequence, that sub-sequence is replaced with +the events in @var{v}. + + For example, VT100 terminals send @kbd{@key{ESC} O P} when the +keypad key @key{PF1} is pressed. On such terminals, Emacs must +translate that sequence of events into a single event @code{pf1}. +This is done by binding @kbd{@key{ESC} O P} to @code{[pf1]} in +@code{input-decode-map}. Thus, when you type @kbd{C-c @key{PF1}} on +the terminal, the terminal emits the character sequence @kbd{C-c +@key{ESC} O P}, and @code{read-key-sequence} translates this back into +@kbd{C-c @key{PF1}} and returns it as the vector @code{[?\C-c pf1]}. + + Translation keymaps take effect only after Emacs has decoded the +keyboard input (via the input coding system specified by +@code{keyboard-coding-system}). @xref{Terminal I/O Encoding}. @defvar input-decode-map This variable holds a keymap that describes the character sequences sent @@ -1626,7 +1615,7 @@ to @code{self-insert-command}. @cindex key translation function You can use @code{input-decode-map}, @code{local-function-key-map}, and @code{key-translation-map} for more than simple aliases, by using -a function, instead of a key sequence, as the ``translation'' of a +a function, instead of a key sequence, as the translation of a key. Then this function is called to compute the translation of that key. @@ -1661,10 +1650,6 @@ to turn the character that follows into a Hyper character: @end group @end example - If you have enabled keyboard character set decoding using -@code{set-keyboard-coding-system}, decoding is done before the -translations listed above. @xref{Terminal I/O Encoding}. - @subsection Interaction with normal keymaps The end of a key sequence is detected when that key sequence either is bound @@ -1732,14 +1717,14 @@ they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you must type the keys as multibyte too. For instance, if you use this: @smallexample -(global-set-key "@"o" 'my-function) ; bind o-umlaut +(global-set-key "ö" 'my-function) ; bind o-umlaut @end smallexample @noindent or @smallexample -(global-set-key ?@"o 'my-function) ; bind o-umlaut +(global-set-key ?ö 'my-function) ; bind o-umlaut @end smallexample @noindent @@ -1822,6 +1807,8 @@ local map. @node Scanning Keymaps @section Scanning Keymaps +@cindex scanning keymaps +@cindex keymaps, scanning This section describes functions used to scan all the current keymaps for the sake of printing help information. @@ -1942,9 +1929,9 @@ entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} characters) are preferred to all other key sequences and that the return value can never be a menu binding. -If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't -follow indirect keymap bindings. This makes it possible to search for -an indirect definition itself. +If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't look +inside menu-items to find their commands. This makes it possible to search for +a menu-item itself. The fifth argument, @var{no-remap}, determines how this function treats command remappings (@pxref{Remapping Commands}). There are two @@ -2023,7 +2010,7 @@ which is a string that appears as an element of the keymap. the menu's commands. Emacs displays the overall prompt string as the menu title in some cases, depending on the toolkit (if any) used for displaying menus.@footnote{It is required for menus which do not use a -toolkit, e.g., under MS-DOS.} Keyboard menus also display the +toolkit, e.g., on a text terminal.} Keyboard menus also display the overall prompt string. The easiest way to construct a keymap with a prompt string is to @@ -2084,7 +2071,7 @@ the GTK+ toolkit). @end example @noindent -@var{help} specifies a ``help-echo'' string to display while the mouse +@var{help} specifies a help-echo string to display while the mouse is on that item in the same way as @code{help-echo} text properties (@pxref{Help display}). @@ -2101,7 +2088,7 @@ the menu but cannot be selected. controls whether the menu item is enabled. Every time the keymap is used to display a menu, Emacs evaluates the expression, and it enables the menu item only if the expression's value is non-@code{nil}. When a -menu item is disabled, it is displayed in a ``fuzzy'' fashion, and +menu item is disabled, it is displayed in a fuzzy fashion, and cannot be selected. The menu bar does not recalculate which items are enabled every time you @@ -2157,7 +2144,7 @@ does not appear, then the menu is displayed as if this item were not defined at all. @item :help @var{help} -The value of this property, @var{help}, specifies a ``help-echo'' string +The value of this property, @var{help}, specifies a help-echo string to display while the mouse is on that item. This is displayed in the same way as @code{help-echo} text properties (@pxref{Help display}). Note that this must be a constant string, unlike the @code{help-echo} @@ -2169,7 +2156,7 @@ The @sc{car}, @var{type}, says which: it should be @code{:toggle} or @code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the result of evaluating it says whether this button is currently selected. -A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off'' +A @dfn{toggle} is a menu item which is labeled as either on or off according to the value of @var{selected}. The command itself should toggle @var{selected}, setting it to @code{t} if it is @code{nil}, and to @code{nil} if it is @code{t}. Here is how the menu item @@ -2187,7 +2174,7 @@ This works because @code{toggle-debug-on-error} is defined as a command which toggles the variable @code{debug-on-error}. @dfn{Radio buttons} are a group of menu items, in which at any time one -and only one is ``selected''. There should be a variable whose value +and only one is selected. There should be a variable whose value says which one is selected at any time. The @var{selected} form for each radio button in the group should check whether the variable has the right value for selecting that button. Clicking on the button should @@ -2316,7 +2303,7 @@ displays a similar kind of separator that is supported. @node Alias Menu Items @subsubsection Alias Menu Items - Sometimes it is useful to make menu items that use the ``same'' + Sometimes it is useful to make menu items that use the same command but with different enable conditions. The best way to do this in Emacs now is with extended menu items; before that feature existed, it could be done by defining alias commands and using them in menu @@ -2331,7 +2318,7 @@ items. Here's an example that makes two aliases for @end example When using aliases in menus, often it is useful to display the -equivalent key bindings for the ``real'' command name, not the aliases +equivalent key bindings for the real command name, not the aliases (which typically don't have any key bindings except for the menu itself). To request this, give the alias symbol a non-@code{nil} @code{menu-alias} property. Thus, @@ -2371,16 +2358,17 @@ if the menu keymap contains a single nested keymap and no other menu items, the menu shows the contents of the nested keymap directly, not as a submenu. - However, if Emacs is compiled without X toolkit support, submenus -are not supported. Each nested keymap is shown as a menu item, but -clicking on it does not automatically pop up the submenu. If you wish -to imitate the effect of submenus, you can do that by giving a nested -keymap an item string which starts with @samp{@@}. This causes Emacs -to display the nested keymap using a separate @dfn{menu pane}; the -rest of the item string after the @samp{@@} is the pane label. If -Emacs is compiled without X toolkit support, menu panes are not used; -in that case, a @samp{@@} at the beginning of an item string is -omitted when the menu label is displayed, and has no other effect. + However, if Emacs is compiled without X toolkit support, or on text +terminals, submenus are not supported. Each nested keymap is shown as +a menu item, but clicking on it does not automatically pop up the +submenu. If you wish to imitate the effect of submenus, you can do +that by giving a nested keymap an item string which starts with +@samp{@@}. This causes Emacs to display the nested keymap using a +separate @dfn{menu pane}; the rest of the item string after the +@samp{@@} is the pane label. If Emacs is compiled without X toolkit +support, or if a menu is displayed on a text terminal, menu panes are +not used; in that case, a @samp{@@} at the beginning of an item string +is omitted when the menu label is displayed, and has no other effect. @node Keyboard Menus @subsection Menus and the Keyboard @@ -2439,19 +2427,19 @@ Next we define the menu items: @end smallexample @noindent -Note the symbols which the bindings are ``made for''; these appear +Note the symbols which the bindings are made for; these appear inside square brackets, in the key sequence being defined. In some cases, this symbol is the same as the command name; sometimes it is -different. These symbols are treated as ``function keys'', but they are +different. These symbols are treated as function keys, but they are not real function keys on the keyboard. They do not affect the -functioning of the menu itself, but they are ``echoed'' in the echo area +functioning of the menu itself, but they are echoed in the echo area when the user selects from the menu, and they appear in the output of @code{where-is} and @code{apropos}. The menu in this example is intended for use with the mouse. If a menu is intended for use with the keyboard, that is, if it is bound to a key sequence ending with a keyboard event, then the menu items -should be bound to characters or ``real'' function keys, that can be +should be bound to characters or real function keys, that can be typed with the keyboard. The binding whose definition is @code{("--")} is a separator line. @@ -2485,17 +2473,17 @@ can do it this way: @subsection The Menu Bar @cindex menu bar - On graphical displays, there is usually a @dfn{menu bar} at the top -of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu -bar items are subcommands of the fake ``function key'' -@code{menu-bar}, as defined in the active keymaps. + Emacs usually shows a @dfn{menu bar} at the top of each frame. +@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu bar items are +subcommands of the fake function key @code{menu-bar}, as defined +in the active keymaps. - To add an item to the menu bar, invent a fake ``function key'' of your + To add an item to the menu bar, invent a fake function key of your own (let's call it @var{key}), and make a binding for the key sequence @code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, so that pressing a button on the menu bar item leads to another menu. - When more than one active keymap defines the same ``function key'' + When more than one active keymap defines the same function key for the menu bar, the item appears just once. If the user clicks on that menu bar item, it brings up a single, combined menu containing all the subcommands of that item---the global subcommands, the local @@ -2555,7 +2543,7 @@ at the end of the menu bar, following local menu items. @defvar menu-bar-update-hook This normal hook is run by redisplay to update the menu bar contents, -before redisplaying the menu bar. You can use it to update submenus +before redisplaying the menu bar. You can use it to update menus whose contents should vary. Since this hook is run frequently, we advise you to ensure that the functions it calls do not take much time in the usual case. @@ -2575,7 +2563,7 @@ in Documentation}. A @dfn{tool bar} is a row of clickable icons at the top of a frame, just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs -Manual}. +Manual}. Emacs normally shows a tool bar on graphical displays. On each frame, the frame parameter @code{tool-bar-lines} controls how many lines' worth of height to reserve for the tool bar. A zero @@ -2586,7 +2574,7 @@ If the value is @code{grow-only}, the tool bar expands automatically, but does not contract automatically. The tool bar contents are controlled by a menu keymap attached to a -fake ``function key'' called @code{tool-bar} (much like the way the menu +fake function key called @code{tool-bar} (much like the way the menu bar is controlled). So you define a tool bar item using @code{define-key}, like this: @@ -2595,7 +2583,7 @@ bar is controlled). So you define a tool bar item using @end example @noindent -where @var{key} is a fake ``function key'' to distinguish this item from +where @var{key} is a fake function key to distinguish this item from other items, and @var{item} is a menu item key binding (@pxref{Extended Menu Items}), which says how to display this item and how it behaves. @@ -2605,7 +2593,7 @@ tool bar bindings and have their normal meanings. The @var{real-binding} in the item must be a command, not a keymap; in other words, it does not work to define a tool bar icon as a prefix key. - The @code{:help} property specifies a ``help-echo'' string to display + The @code{:help} property specifies a help-echo string to display while the mouse is on that item. This is displayed in the same way as @code{help-echo} text properties (@pxref{Help display}). @@ -2630,6 +2618,9 @@ Used when the item is disabled and deselected. @end table @end table +The GTK+ and NS versions of Emacs ignores items 1 to 3, because disabled and/or +deselected images are autocomputed from item 0. + If @var{image} is a single image specification, Emacs draws the tool bar button in disabled state by applying an edge-detection algorithm to the image. @@ -2753,7 +2744,7 @@ The value is an integer, a number of pixels. The default is 1. @defvar tool-bar-border This variable specifies the height of the border drawn below the tool -bar area. An integer value specifies height as a number of pixels. +bar area. An integer specifies height as a number of pixels. If the value is one of @code{internal-border-width} (the default) or @code{border-width}, the tool bar border height corresponds to the corresponding frame parameter. @@ -2787,6 +2778,7 @@ function keys. @node Modifying Menus @subsection Modifying Menus +@cindex menu modification When you insert a new item in an existing menu, you probably want to put it in a particular place among the menu's existing items. If you @@ -2894,7 +2886,7 @@ Documentation}). @item :key-sequence @var{keys} @var{keys} is a hint for speeding up Emacs's first display of the -menu. It should be nil if you know that the menu item has no keyboard +menu. It should be @code{nil} if you know that the menu item has no keyboard equivalent; otherwise it should be a string or vector specifying a keyboard equivalent for the menu item. @@ -2922,7 +2914,7 @@ anything else (meaning an ordinary menu item). @item :selected @var{selected} @var{selected} is an expression; the checkbox or radio button is -selected whenever the expression's value is non-nil. +selected whenever the expression's value is non-@code{nil}. @item :help @var{help} @var{help} is a string describing the menu item. diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi index f12e724d6a9..04aabd814fc 100644 --- a/doc/lispref/lay-flat.texi +++ b/doc/lispref/lay-flat.texi @@ -1,11 +1,12 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c @comment %**start of header @setfilename inner-covers.info @settitle Inner Covers +@include docstyle.texi @smallbook @comment %**end of header @@ -20,9 +21,9 @@ We have bound this manual using a new @dfn{lay-flat} binding technology. This type of binding allows you to open a soft cover book -so that it ``lays flat'' on a table without creasing the binding. +so that it lays flat on a table without creasing the binding. -In order to make the book lay flat properly, you need to ``crack'' the +In order to make the book lay flat properly, you need to crack the binding. To do this, divide the book into two sections and bend it so that the front and back covers meet. Do not worry; the pages are sewn and glued to the binding, and will not fall out easily. diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 9daf01cd0a2..48e1b57eede 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Lists @@ -41,7 +41,7 @@ pronounced ``could-er''. We say that ``the @sc{car} of this cons cell is'' whatever object its @sc{car} slot currently holds, and likewise for the @sc{cdr}. - A list is a series of cons cells ``chained together'', so that each + A list is a series of cons cells chained together, so that each cell refers to the next one. There is one cons cell for each element of the list. By convention, the @sc{car}s of the cons cells hold the elements of the list, and the @sc{cdr}s are used to chain the list @@ -84,6 +84,8 @@ structure made out of cons cells as a @dfn{list structure}. @node List-related Predicates @section Predicates on Lists +@cindex predicates for lists +@cindex list predicates The following predicates test whether a Lisp object is an atom, whether it is a cons cell or is a list, or whether it is the @@ -601,25 +603,6 @@ not a list, the sequence's elements do not become elements of the resulting list. Instead, the sequence becomes the final @sc{cdr}, like any other non-list final argument. -@defun reverse list -This function creates a new list whose elements are the elements of -@var{list}, but in reverse order. The original argument @var{list} is -@emph{not} altered. - -@example -@group -(setq x '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@group -(reverse x) - @result{} (4 3 2 1) -x - @result{} (1 2 3 4) -@end group -@end example -@end defun - @defun copy-tree tree &optional vecp This function returns a copy of the tree @code{tree}. If @var{tree} is a cons cell, this makes a new cons cell with the same @sc{car} and @@ -646,8 +629,8 @@ If @var{separation} is 0 and @var{to} is neither @code{nil} nor numerically equal to @var{from}, @code{number-sequence} signals an error, since those arguments specify an infinite sequence. -All arguments can be integers or floating point numbers. However, -floating point arguments can be tricky, because floating point +All arguments are numbers. +Floating-point arguments can be tricky, because floating-point arithmetic is inexact. For instance, depending on the machine, it may quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns the one element list @code{(0.4)}, whereas @@ -681,6 +664,8 @@ Some examples: @node List Variables @section Modifying List Variables +@cindex modify a list +@cindex list modification These functions, and one macro, provide convenient ways to modify a list which is stored in a variable. @@ -814,7 +799,7 @@ foo ;; @r{@code{foo} was changed.} @cindex destructive list operations You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the -primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' +primitives @code{setcar} and @code{setcdr}. These are destructive operations because they change existing list structure. @cindex CL note---@code{rplaca} vs @code{setcar} @@ -837,6 +822,8 @@ new @sc{car} or @sc{cdr}. @node Setcar @subsection Altering List Elements with @code{setcar} +@cindex replace list element +@cindex list, replace element Changing the @sc{car} of a cons cell is done with @code{setcar}. When used on a list, @code{setcar} replaces one element of a list with a @@ -942,6 +929,7 @@ x2: | @node Setcdr @subsection Altering the CDR of a List +@cindex replace part of list The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: @@ -1044,11 +1032,12 @@ x1 @node Rearrangement @subsection Functions that Rearrange Lists @cindex rearrangement of lists +@cindex reordering, of elements in lists @cindex modification of lists - Here are some functions that rearrange lists ``destructively'' by -modifying the @sc{cdr}s of their component cons cells. We call these -functions ``destructive'' because they chew up the original lists passed + Here are some functions that rearrange lists destructively by +modifying the @sc{cdr}s of their component cons cells. These functions +are destructive because they chew up the original lists passed to them as arguments, relinking their cons cells to form a new list that is the returned value. @@ -1142,126 +1131,6 @@ each time you run it! Here is what happens: @end smallexample @end defun -@defun nreverse list -@cindex reversing a list - This function reverses the order of the elements of @var{list}. -Unlike @code{reverse}, @code{nreverse} alters its argument by reversing -the @sc{cdr}s in the cons cells forming the list. The cons cell that -used to be the last one in @var{list} becomes the first cons cell of the -value. - - For example: - -@example -@group -(setq x '(a b c)) - @result{} (a b c) -@end group -@group -x - @result{} (a b c) -(nreverse x) - @result{} (c b a) -@end group -@group -;; @r{The cons cell that was first is now last.} -x - @result{} (a) -@end group -@end example - - To avoid confusion, we usually store the result of @code{nreverse} -back in the same variable which held the original list: - -@example -(setq x (nreverse x)) -@end example - - Here is the @code{nreverse} of our favorite example, @code{(a b c)}, -presented graphically: - -@smallexample -@group -@r{Original list head:} @r{Reversed list:} - ------------- ------------- ------------ -| car | cdr | | car | cdr | | car | cdr | -| a | nil |<-- | b | o |<-- | c | o | -| | | | | | | | | | | | | - ------------- | --------- | - | -------- | - - | | | | - ------------- ------------ -@end group -@end smallexample -@end defun - -@defun sort list predicate -@cindex stable sort -@cindex sorting lists -This function sorts @var{list} stably, though destructively, and -returns the sorted list. It compares elements using @var{predicate}. A -stable sort is one in which elements with equal sort keys maintain their -relative order before and after the sort. Stability is important when -successive sorts are used to order elements according to different -criteria. - -The argument @var{predicate} must be a function that accepts two -arguments. It is called with two elements of @var{list}. To get an -increasing order sort, the @var{predicate} should return non-@code{nil} if the -first element is ``less than'' the second, or @code{nil} if not. - -The comparison function @var{predicate} must give reliable results for -any given pair of arguments, at least within a single call to -@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is -less than @var{b}, @var{b} must not be less than @var{a}. It must be -@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} -is less than @var{c}, then @var{a} must be less than @var{c}. If you -use a comparison function which does not meet these requirements, the -result of @code{sort} is unpredictable. - -The destructive aspect of @code{sort} is that it rearranges the cons -cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort -function would create new cons cells to store the elements in their -sorted order. If you wish to make a sorted copy without destroying the -original, copy it first with @code{copy-sequence} and then sort. - -Sorting does not change the @sc{car}s of the cons cells in @var{list}; -the cons cell that originally contained the element @code{a} in -@var{list} still has @code{a} in its @sc{car} after sorting, but it now -appears in a different position in the list due to the change of -@sc{cdr}s. For example: - -@example -@group -(setq nums '(1 3 2 6 5 4 0)) - @result{} (1 3 2 6 5 4 0) -@end group -@group -(sort nums '<) - @result{} (0 1 2 3 4 5 6) -@end group -@group -nums - @result{} (1 2 3 4 5 6) -@end group -@end example - -@noindent -@strong{Warning}: Note that the list in @code{nums} no longer contains -0; this is the same cons cell that it was before, but it is no longer -the first one in the list. Don't assume a variable that formerly held -the argument now holds the entire sorted list! Instead, save the result -of @code{sort} and use that. Most often we store the result back into -the variable that held the original list: - -@example -(setq nums (sort nums '<)) -@end example - -@xref{Sorting}, for more functions that perform sorting. -See @code{documentation} in @ref{Accessing Documentation}, for a -useful example of @code{sort}. -@end defun - @node Sets And Lists @section Using Lists as Sets @cindex lists as sets @@ -1404,7 +1273,7 @@ sample-list @defun memql object list The function @code{memql} tests to see whether @var{object} is a member of @var{list}, comparing members with @var{object} using @code{eql}, -so floating point elements are compared by value. +so floating-point elements are compared by value. If @var{object} is a member, @code{memql} returns a list starting with its first occurrence in @var{list}. Otherwise, it returns @code{nil}. @@ -1653,7 +1522,7 @@ a @sc{cdr} @code{equal} to @var{value}. @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc}'', finding the key for a given value. +this as reverse @code{assoc}, finding the key for a given value. @end defun @defun assq key alist @@ -1694,7 +1563,7 @@ a @sc{cdr} @code{eq} to @var{value}. @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq}'', finding the key for a given value. +this as reverse @code{assq}, finding the key for a given value. For example: @@ -1897,6 +1766,8 @@ and later discarded; this is not possible with a property list. @node Plist Access @subsection Property Lists Outside Symbols +@cindex plist access +@cindex accessing plist properties The following functions can be used to manipulate property lists. They all compare property names using @code{eq}. diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index dab8e8d1255..82de765876e 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Loading @@ -29,6 +29,8 @@ into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions. +For on-demand loading of external libraries, @pxref{Dynamic Libraries}. + @menu * How Programs Do Loading:: The @code{load} function and others. * Load Suffixes:: Details about the suffixes that @code{load} tries. @@ -38,7 +40,7 @@ definitions. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. +* Unloading:: How to unload a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @end menu @@ -74,7 +76,7 @@ If Auto Compression mode is enabled, as it is by default, then if of the file before trying other file names. It decompresses and loads it if it exists. It looks for compressed versions by appending each of the suffixes in @code{jka-compr-load-suffixes} to the file name. -The value of this variable must be a list of strings. Its standard +The value of this variable must be a list of strings. Its standard value is @code{(".gz")}. If the optional argument @var{nosuffix} is non-@code{nil}, then @@ -91,6 +93,10 @@ If the optional argument @var{must-suffix} is non-@code{nil}, then @samp{.el} or @samp{.elc} (possibly extended with a compression suffix), unless it contains an explicit directory name. +If the option @code{load-prefer-newer} is non-@code{nil}, then when +searching suffixes, @code{load} selects whichever version of a file +(@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently. + If @var{filename} is a relative file name, such as @file{foo} or @file{baz/foo.bar}, @code{load} searches for the file using the variable @code{load-path}. It appends @var{filename} to each of the directories @@ -244,6 +250,12 @@ value of @code{(get-load-suffixes)} and then those in it skips the former group, and if @var{must-suffix} is non-@code{nil}, it skips the latter group. +@defopt load-prefer-newer +If this option is non-@code{nil}, then rather than stopping at the +first suffix that exists, @code{load} tests them all, and uses +whichever file is the newest. +@end defopt + @node Library Search @section Library Search @cindex library search @@ -253,37 +265,41 @@ it skips the latter group. in a list of directories specified by the variable @code{load-path}. @defvar load-path -@cindex @env{EMACSLOADPATH} environment variable The value of this variable is a list of directories to search when loading files with @code{load}. Each element is a string (which must be a directory name) or @code{nil} (which stands for the current working directory). @end defvar - Each time Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} to the -directories specified by the environment variable @env{EMACSLOADPATH}, -if that exists. The syntax of @env{EMACSLOADPATH} is the same as used -for @code{PATH}; directory names are separated by @samp{:} (or -@samp{;}, on some operating systems), and @samp{.} stands for the -current default directory. Here is an example of how to set -@env{EMACSLOADPATH} variable from @command{sh}: + When Emacs starts up, it sets up the value of @code{load-path} +in several steps. First, it initializes @code{load-path} using +default locations set when Emacs was compiled. Normally, this +is a directory something like @example -export EMACSLOADPATH -EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp +"/usr/local/share/emacs/@var{version}/lisp" @end example -@noindent -Here is how to set it from @code{csh}: - -@example -setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp -@end example +(In this and the following examples, replace @file{/usr/local} with +the installation prefix appropriate for your Emacs.) +These directories contain the standard Lisp files that come with +Emacs. If Emacs cannot find them, it will not start correctly. + +If you run Emacs from the directory where it was built---that is, an +executable that has not been formally installed---Emacs instead +initializes @code{load-path} using the @file{lisp} +directory in the directory containing the sources from which it +was built. +@c Though there should be no *.el files in builddir/lisp, so it's pointless. +If you built Emacs in a separate directory from the +sources, it also adds the lisp directories from the build directory. +(In all cases, elements are represented as absolute file names.) @cindex site-lisp directories - If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs -initializes @code{load-path} with the following two directories: +Unless you start Emacs with the @option{--no-site-lisp} option, +it then adds two more @file{site-lisp} directories to the front of +@code{load-path}. These are intended for locally installed Lisp files, +and are normally of the form: @example "/usr/local/share/emacs/@var{version}/site-lisp" @@ -297,26 +313,54 @@ and @end example @noindent -The first one is for locally installed packages for a particular Emacs -version; the second is for locally installed packages meant for use -with all installed Emacs versions. - - If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs puts two more -directories in @code{load-path}. These are the @code{lisp} and -@code{site-lisp} subdirectories of the main build directory. (Both -are represented as absolute file names.) - - Next, Emacs ``expands'' the initial list of directories in -@code{load-path} by adding the subdirectories of those directories. -Both immediate subdirectories and subdirectories multiple levels down -are added. But it excludes subdirectories whose names do not start -with a letter or digit, and subdirectories named @file{RCS} or -@file{CVS}, and subdirectories containing a file named -@file{.nosearch}. - - Next, Emacs adds any extra load directory that you specify using the -@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The +The first one is for locally installed files for a specific Emacs +version; the second is for locally installed files meant for use +with all installed Emacs versions. (If Emacs is running uninstalled, +it also adds @file{site-lisp} directories from the source and build +directories, if they exist. Normally these directories do not contain +@file{site-lisp} directories.) + +@cindex @env{EMACSLOADPATH} environment variable +If the environment variable @env{EMACSLOADPATH} is set, it modifies +the above initialization procedure. Emacs initializes +@code{load-path} based on the value of the environment variable. + +The syntax of @env{EMACSLOADPATH} is the same as used for @code{PATH}; +directory names are separated by @samp{:} (or @samp{;}, on some +operating systems). +@ignore +@c AFAICS, does not (yet) work right to specify non-absolute elements. +and @samp{.} stands for the current default directory. +@end ignore +Here is an example of how to set @env{EMACSLOADPATH} variable (from a +@command{sh}-style shell): + +@example +export EMACSLOADPATH=/home/foo/.emacs.d/lisp: +@end example + +An empty element in the value of the environment variable, whether +trailing (as in the above example), leading, or embedded, is replaced +by the default value of @code{load-path} as determined by the standard +initialization procedure. If there are no such empty elements, then +@env{EMACSLOADPATH} specifies the entire @code{load-path}. You must +include either an empty element, or the explicit path to the directory +containing the standard Lisp files, else Emacs will not function. +(Another way to modify @code{load-path} is to use the @option{-L} +command-line option when starting Emacs; see below.) + + For each directory in @code{load-path}, Emacs then checks to see if +it contains a file @file{subdirs.el}, and if so, loads it. The +@file{subdirs.el} file is created when Emacs is built/installed, +and contains code that causes Emacs to add any subdirectories of those +directories to @code{load-path}. Both immediate subdirectories and +subdirectories multiple levels down are added. But it excludes +subdirectories whose names do not start with a letter or digit, and +subdirectories named @file{RCS} or @file{CVS}, and subdirectories +containing a file named @file{.nosearch}. + + Next, Emacs adds any extra load directories that you specify using the +@option{-L} command-line option (@pxref{Action Arguments,,,emacs, The GNU Emacs Manual}). It also adds the directories where optional packages are installed, if any (@pxref{Packaging Basics}). @@ -327,12 +371,10 @@ add one or more directories to @code{load-path}. For example: (push "~/.emacs.d/lisp" load-path) @end example - Dumping Emacs uses a special value of @code{load-path}. If the -value of @code{load-path} at the end of dumping is unchanged (that is, -still the same special value), the dumped Emacs switches to the -ordinary @code{load-path} value when it starts up, as described above. -But if @code{load-path} has any other value at the end of dumping, -that value is used for execution of the dumped Emacs also. + Dumping Emacs uses a special value of @code{load-path}. If you use +a @file{site-load.el} or @file{site-init.el} file to customize the +dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path} +that these files make will be lost after dumping. @deffn Command locate-library library &optional nosuffix path interactive-call This command finds the precise file name for library @var{library}. It @@ -377,6 +419,8 @@ the shadowed files as a string. @node Loading Non-ASCII @section Loading Non-@acronym{ASCII} Characters +@cindex loading, and non-ASCII characters +@cindex non-ASCII characters in loaded files When Emacs Lisp programs contain string constants with non-@acronym{ASCII} characters, these can be represented within Emacs either as unibyte @@ -412,7 +456,7 @@ Autoloading can also be triggered by looking up the documentation of the function or macro (@pxref{Documentation Basics}). There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the +@code{autoload}, and by writing a ``magic'' comment in the source before the real definition. @code{autoload} is the low-level primitive for autoloading; any Lisp program can call @code{autoload} at any time. Magic comments are the most convenient way to make a function @@ -624,7 +668,7 @@ value of this variable is @code{";;;###autoload"}. @defvar generated-autoload-file The value of this variable names an Emacs Lisp file where the autoload calls should go. The default value is @file{loaddefs.el}, but you can -override that, e.g., in the ``Local Variables'' section of a +override that, e.g., in the local variables section of a @file{.el} file (@pxref{File Local Variables}). The autoload file is assumed to contain a trailer starting with a formfeed character. @end defvar @@ -865,6 +909,8 @@ with a call to @code{provide}. The order of the elements in the @node Where Defined @section Which File Defined a Certain Symbol +@cindex symbol, where defined +@cindex where was a symbol defined @defun symbol-file symbol &optional type This function returns the name of the file that defined @var{symbol}. diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index 5520bbbd1df..a90c6f1da6f 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1995, 1998, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Macros @@ -55,6 +55,11 @@ expansion, which is @code{(setq x (1+ x))}. Once the macro definition returns this expansion, Lisp proceeds to evaluate it, thus incrementing @code{x}. +@defun macrop object +This predicate tests whether its argument is a macro, and returns +@code{t} if so, @code{nil} otherwise. +@end defun + @node Expansion @section Expansion of a Macro Call @cindex expansion of macros @@ -189,10 +194,12 @@ During Compile}). @node Defining Macros @section Defining Macros +@cindex defining macros +@cindex macro, how to define A Lisp macro object is a list whose @sc{car} is @code{macro}, and -whose @sc{cdr} is a lambda expression. Expansion of the macro works -by applying the lambda expression (with @code{apply}) to the list of +whose @sc{cdr} is a function. Expansion of the macro works +by applying the function (with @code{apply}) to the list of @emph{unevaluated} arguments from the macro call. It is possible to use an anonymous Lisp macro just like an anonymous @@ -248,6 +255,7 @@ Form}. @node Problems with Macros @section Common Problems Using Macros +@cindex macro caveats Macro expansion can have counterintuitive consequences. This section describes some important consequences that can lead to @@ -299,7 +307,7 @@ program is actually run. When defining a macro you must pay attention to the number of times the arguments will be evaluated when the expansion is executed. The following macro (used to facilitate iteration) illustrates the -problem. This macro allows us to write a ``for'' loop construct. +problem. This macro allows us to write a for-loop construct. @findex for @example @@ -337,7 +345,7 @@ For example, (for i from 1 to 10 do (print i))." @noindent The arguments @code{from}, @code{to}, and @code{do} in this macro are -``syntactic sugar''; they are entirely ignored. The idea is that you +syntactic sugar; they are entirely ignored. The idea is that you will write noise words (such as @code{from}, @code{to}, and @code{do}) in those positions in the macro call. @@ -560,7 +568,7 @@ If @code{initialize} is interpreted, a new list @code{(nil)} is constructed each time @code{initialize} is called. Thus, no side effect survives between calls. If @code{initialize} is compiled, then the macro @code{empty-object} is expanded during compilation, producing a -single ``constant'' @code{(nil)} that is reused and altered each time +single constant @code{(nil)} that is reused and altered each time @code{initialize} is called. One way to avoid pathological cases like this is to think of diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in deleted file mode 100644 index 00b938dbf68..00000000000 --- a/doc/lispref/makefile.w32-in +++ /dev/null @@ -1,129 +0,0 @@ -# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 2003-2013 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. - - -# Standard configure variables. -srcdir = . - -infodir = $(srcdir)/../../info - -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -INFO_EXT=.info -INFO_OPTS=--no-split - -# Redefine `TEX' if `tex' does not invoke plain TeX. For example: -# TEX=platex -TEX=tex -INSTALL_INFO = install-info -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -I$(emacsdir) - -# The environment variable and its value to add $(srcdir) to the path -# searched for TeX input files. -texinputdir = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - -# List of all the texinfo files in the manual: - -srcs = \ - $(emacsdir)/emacsver.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/elisp.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/package.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - - -.PHONY: clean - -# The info file is named `elisp'. - -info: $(infodir)/elisp$(INFO_EXT) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp - -$(infodir)/elisp$(INFO_EXT): $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(texinputdir) $(TEX) $(srcdir)/elisp.texi - -clean: - - $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ - *.vr *.vrs *.pg *.pgs *.ky *.kys - - $(DEL) make.out core - - $(DEL) $(infodir)/elisp* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) elisp$(INFO_EXT) elisp$(INFO_EXT)-? elisp$(INFO_EXT)-?? elisp.dvi elisp.oaux diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi index d92f6a89f0a..cc127264478 100644 --- a/doc/lispref/maps.texi +++ b/doc/lispref/maps.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2013 Free Software Foundation, +@c Copyright (C) 1990-1993, 1999, 2001-2015 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Keymaps diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index d94908994e9..3eaba419034 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Markers @@ -20,8 +20,8 @@ deleted, so that it stays with the two characters on either side of it. * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". +* The Mark:: How the mark is implemented with a marker. +* The Region:: How to access the region. @end menu @node Overview of Markers @@ -118,6 +118,8 @@ m1 @node Predicates on Markers @section Predicates on Markers +@cindex predicates for markers +@cindex markers, predicates for You can test an object to see whether it is a marker, or whether it is either an integer or a marker. The latter test is useful in connection @@ -141,6 +143,8 @@ integer or floating point) or a marker, @code{nil} otherwise. @node Creating Markers @section Functions that Create Markers +@cindex creating markers +@cindex marker creation When you create a new marker, you can make it point nowhere, or point to the present position of point, or to the beginning or end of the @@ -269,6 +273,7 @@ if they both point nowhere. @node Information from Markers @section Information from Markers +@cindex marker information This section describes the functions for accessing the components of a marker object. @@ -282,8 +287,8 @@ This function returns the position that @var{marker} points to, or This function returns the buffer that @var{marker} points into, or @code{nil} if it points nowhere. -@c FIXME: The `buffer' argument of `set-marker' already defaults to -@c the current buffer, why use `(current-buffer)' explicitly here? +@c FIXME: The 'buffer' argument of 'set-marker' already defaults to +@c the current buffer, why use '(current-buffer)' explicitly here? @example @group (setq m (make-marker)) @@ -342,6 +347,8 @@ specify the insertion type, create them with insertion type @node Moving Markers @section Moving Marker Positions +@cindex moving markers +@cindex marker, how to move position This section describes how to change the position of an existing marker. When you do this, be sure you know whether the marker is used @@ -397,7 +404,7 @@ This is another name for @code{set-marker}. Each buffer has a special marker, which is designated @dfn{the mark}. When a buffer is newly created, this marker exists but does -not point anywhere; this means that the mark ``doesn't exist'' in that +not point anywhere; this means that the mark doesn't exist in that buffer yet. Subsequent commands can set the mark. The mark specifies a position to bound a range of text for many @@ -417,7 +424,7 @@ sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished. - Once the mark ``exists'' in a buffer, it normally never ceases to + Once the mark exists in a buffer, it normally never ceases to exist. However, it may become @dfn{inactive}, if Transient Mark mode is enabled. The buffer-local variable @code{mark-active}, if non-@code{nil}, means that the mark is active. A command can call the @@ -613,7 +620,7 @@ This piece of command_loop_1, run unless deactivating the mark: @end defvar @defun handle-shift-selection -This function implements the ``shift-selection'' behavior of +This function implements the shift-selection behavior of point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs Manual}. It is called automatically by the Emacs command loop whenever a command with a @samp{^} character in its @code{interactive} @@ -654,8 +661,8 @@ more marks than this are pushed onto the @code{mark-ring}, @node The Region @section The Region -@c The index entry must be just ``region'' to make it the first hit -@c when the user types ``i region RET'', because otherwise the Info +@c The index entry must be just "region" to make it the first hit +@c when the user types "i region RET", because otherwise the Info @c reader will present substring matches in alphabetical order, @c putting this one near the end, with something utterly unrelated as @c the first hit. @@ -705,4 +712,3 @@ A region is valid if it has a non-zero size, or if the user option cases, you should not use @code{region-active-p}, since if the region is empty it is often more appropriate to operate on point. @end defun - diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 9a1ec477b9f..0b1a4a90ba9 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Minibuffers @@ -81,7 +81,7 @@ there is an active minibuffer; such a minibuffer is called a incrementing the number at the end of the name. (The names begin with a space so that they won't show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently -entered) is the active minibuffer. We usually call this ``the'' +entered) is the active minibuffer. We usually call this @emph{the} minibuffer. You can permit or forbid recursive minibuffers by setting the variable @code{enable-recursive-minibuffers}, or by putting properties of that name on command symbols (@xref{Recursive Mini}.) @@ -101,10 +101,13 @@ the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that -was supplied when Emacs was started. +was supplied when Emacs was started. This supports only basic input: +none of the special minibuffer features (history, completion, etc.)@: +are available in batch mode. @node Text from Minibuffer @section Reading Text Strings with the Minibuffer +@cindex minibuffer input, reading text strings The most basic primitive for minibuffer input is @code{read-from-minibuffer}, which can be used to read either a string @@ -211,25 +214,39 @@ This function works by calling the @end smallexample @end defun -@defun read-regexp prompt &optional default history +@defun read-regexp prompt &optional defaults history This function reads a regular expression as a string from the -minibuffer and returns it. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. +minibuffer and returns it. If the minibuffer prompt string +@var{prompt} does not end in @samp{:} (followed by optional +whitespace), the function adds @samp{: } to the end, preceded by the +default return value (see below), if that is non-empty. -The optional argument @var{default} specifies a default value to -return if the user enters null input; it should be a string, or -@code{nil}, which is equivalent to an empty string. +The optional argument @var{defaults} controls the default value to +return if the user enters null input, and should be one of: a string; +@code{nil}, which is equivalent to an empty string; a list of strings; +or a symbol. -The optional argument @var{history}, if non-@code{nil}, is a symbol -specifying a minibuffer history list to use (@pxref{Minibuffer -History}). If it is omitted or @code{nil}, the history list defaults -to @code{regexp-history}. +If @var{defaults} is a symbol, @code{read-regexp} consults the value +of the variable @code{read-regexp-defaults-function} (see below), and +if that is non-@code{nil} uses it in preference to @var{defaults}. +The value in this case should be either: -@code{read-regexp} also collects a few useful candidates for input and -passes them to @code{read-from-minibuffer}, to make them available to -the user as the ``future minibuffer history list'' (@pxref{Minibuffer -History, future list,, emacs, The GNU Emacs Manual}). These -candidates are: +@itemize @minus +@item +@code{regexp-history-last}, which means to use the first element of +the appropriate minibuffer history list (see below). + +@item +A function of no arguments, whose return value (which should be +@code{nil}, a string, or a list of strings) becomes the value of +@var{defaults}. +@end itemize + +@code{read-regexp} now ensures that the result of processing +@var{defaults} is a list (i.e., if the value is @code{nil} or a +string, it converts it to a list of one element). To this list, +@code{read-regexp} then appends a few potentially useful candidates for +input. These are: @itemize @minus @item @@ -242,10 +259,37 @@ The last string used in an incremental search. The last string or pattern used in query-replace commands. @end itemize -This function works by calling the @code{read-from-minibuffer} -function, after computing the list of defaults as described above. +The function now has a list of regular expressions that it passes to +@code{read-from-minibuffer} to obtain the user's input. The first +element of the list is the default result in case of empty input. All +elements of the list are available to the user as the ``future +minibuffer history'' list (@pxref{Minibuffer History, future list,, +emacs, The GNU Emacs Manual}). + +The optional argument @var{history}, if non-@code{nil}, is a symbol +specifying a minibuffer history list to use (@pxref{Minibuffer +History}). If it is omitted or @code{nil}, the history list defaults +to @code{regexp-history}. @end defun +@defvar read-regexp-defaults-function +The function @code{read-regexp} may use the value of this variable to +determine its list of default regular expressions. If non-@code{nil}, +the value of this variable should be either: + +@itemize @minus +@item +The symbol @code{regexp-history-last}. + +@item +A function of no arguments that returns either @code{nil}, a string, +or a list of strings. +@end itemize + +@noindent +See @code{read-regexp} above for details of how these values are used. +@end defvar + @defvar minibuffer-allow-text-properties If this variable is @code{nil}, then @code{read-from-minibuffer} and @code{read-string} strip all text properties from the minibuffer @@ -347,6 +391,7 @@ following bindings, in addition to those of @code{minibuffer-local-map}: @node Object from Minibuffer @section Reading Lisp Objects with the Minibuffer +@cindex minibuffer input, reading lisp objects This section describes functions for reading Lisp objects with the minibuffer. @@ -678,7 +723,7 @@ just one matching completion, and the match is exact, it returns @code{t}. Otherwise, it returns the longest initial sequence common to all possible matching completions. -If @var{collection} is an list, the permissible completions are +If @var{collection} is a list, the permissible completions are specified by the elements of the list, each of which should be either a string, or a cons cell whose @sc{car} is either a string or a symbol (a symbol is converted to a string using @code{symbol-name}). If the @@ -850,7 +895,7 @@ pertains to the area after @code{"/usr/"} and before @code{"/doc"}. @end defun If you store a completion alist in a variable, you should mark the -variable as ``risky'' by giving it a non-@code{nil} +variable as risky by giving it a non-@code{nil} @code{risky-local-variable} property. @xref{File Local Variables}. @defvar completion-ignore-case @@ -889,6 +934,7 @@ Here is an example: @c FIXME? completion-table-with-context? @findex completion-table-case-fold @findex completion-table-in-turn +@findex completion-table-merge @findex completion-table-subvert @findex completion-table-with-quoting @findex completion-table-with-predicate @@ -897,9 +943,10 @@ Here is an example: @cindex completion tables, combining There are several functions that take an existing completion table and return a modified version. @code{completion-table-case-fold} returns -a case-insensitive table. @code{completion-table-in-turn} combines -multiple input tables. @code{completion-table-subvert} alters a table -to use a different initial prefix. @code{completion-table-with-quoting} +a case-insensitive table. @code{completion-table-in-turn} and +@code{completion-table-merge} combine multiple input tables in +different ways. @code{completion-table-subvert} alters a table to use +a different initial prefix. @code{completion-table-with-quoting} returns a table suitable for operating on quoted text. @code{completion-table-with-predicate} filters a table with a predicate function. @code{completion-table-with-terminator} adds a @@ -928,6 +975,9 @@ Thus, if @var{predicate} is non-@code{nil}, it should be compatible with @var{collection} and @code{completion-ignore-case}. @xref{Definition of test-completion}. +@xref{Programmed Completion}, for detailed requirements when +@var{collection} is a function. + The value of the optional argument @var{require-match} determines how the user may exit the minibuffer: @@ -1099,7 +1149,7 @@ The list of completions is displayed as text in a buffer named @file{*Completions*}. @end deffn -@defun display-completion-list completions &optional common-substring +@defun display-completion-list completions This function displays @var{completions} to the stream in @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more information about streams.) The argument @var{completions} is normally @@ -1110,13 +1160,6 @@ which is printed as if the strings were concatenated. The first of the two strings is the actual completion, the second string serves as annotation. -The argument @var{common-substring} is the prefix that is common to -all the completions. With normal Emacs completion, it is usually the -same as the string that was completed. @code{display-completion-list} -uses this to highlight text in the completion list for better visual -feedback. This is not needed in the minibuffer; for minibuffer -completion, you can pass @code{nil}. - This function is called by @code{minibuffer-completion-help}. A common way to use it is together with @code{with-output-to-temp-buffer}, like this: @@ -1124,8 +1167,7 @@ common way to use it is together with @example (with-output-to-temp-buffer "*Completions*" (display-completion-list - (all-completions (buffer-string) my-alist) - (buffer-string))) + (all-completions (buffer-string) my-alist))) @end example @end defun @@ -1699,7 +1741,7 @@ possible match, and ignore the match if the predicate returns @item A flag specifying the type of completion operation to perform. This -is one of the following four values: +flag may be one of the following values. @table @code @item nil @@ -1779,6 +1821,13 @@ possible completions of it. You can think of and the interface for programmed completion functions. @end defun +@defun completion-table-with-cache function &optional ignore-case +This is a wrapper for @code{completion-table-dynamic} that saves the +last argument-result pair. This means that multiple lookups with the +same argument only need to call @var{function} once. This can be useful +when a slow operation is involved, such as calling an external process. +@end defun + @node Completion in Buffers @subsection Completion in Ordinary Buffers @cindex inline completion @@ -1831,11 +1880,34 @@ next function in @code{completion-at-point-functions} instead of reporting a completion failure. @end table +Supplying a function for @var{collection} is strongly recommended if +generating the list of completions is an expensive operation. Emacs +may internally call functions in @code{completion-at-point-functions} +many times, but care about the value of @var{collection} for only some +of these calls. By supplying a function for @var{collection}, Emacs +can defer generating completions until necessary. You can use +@var{completion-table-dynamic} to create a wrapper function: + +@smallexample +;; Avoid this pattern. +(let ((beg ...) (end ...) (my-completions (my-make-completions))) + (list beg end my-completions)) + +;; Use this instead. +(let ((beg ...) (end ...)) + (list beg + end + (completion-table-dynamic + (lambda (_) + (my-make-completions))))) +@end smallexample + A function in @code{completion-at-point-functions} may also return a -function. In that case, that returned function is called, with no -argument, and it is entirely responsible for performing the -completion. We discourage this usage; it is intended to help convert -old code to using @code{completion-at-point}. +function instead of a list as described above. In that case, that +returned function is called, with no argument, and it is entirely +responsible for performing the completion. We discourage this usage; +it is intended to help convert old code to using +@code{completion-at-point}. The first function in @code{completion-at-point-functions} to return a non-@code{nil} value is used by @code{completion-at-point}. The @@ -1889,7 +1961,7 @@ the call. This function asks the user a question, expecting input in the echo area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like +and @key{DEL} to mean no. It accepts @kbd{C-]} to quit, like @kbd{C-g}, because the question might look like a minibuffer and for that reason the user might try to use @kbd{C-]} to get out. The answer is a single character, with no @key{RET} needed to terminate it. Upper @@ -1925,7 +1997,7 @@ appears on the screen at a time. Like @code{y-or-n-p}, except that if the user fails to answer within @var{seconds} seconds, this function stops waiting and returns @var{default}. It works by setting up a timer; see @ref{Timers}. -The argument @var{seconds} may be an integer or a floating point number. +The argument @var{seconds} should be a number. @end defun @defun yes-or-no-p prompt @@ -1977,9 +2049,10 @@ Do you really want to remove everything? (yes or no) @node Multiple Queries @section Asking Multiple Y-or-N Questions +@cindex multiple yes-or-no questions When you have a series of similar questions to ask, such as ``Do you -want to save this buffer'' for each buffer in turn, you should use +want to save this buffer?'' for each buffer in turn, you should use @code{map-y-or-n-p} to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at @@ -2050,7 +2123,7 @@ answer); @var{function} is a function of one argument (an object from When the user responds with @var{char}, @code{map-y-or-n-p} calls @var{function}. If it returns non-@code{nil}, the object is considered -``acted upon'', and @code{map-y-or-n-p} advances to the next object in +acted upon, and @code{map-y-or-n-p} advances to the next object in @var{list}. If it returns @code{nil}, the prompt is repeated for the same object. @@ -2080,8 +2153,10 @@ function @code{read-passwd}. @defun read-passwd prompt &optional confirm default This function reads a password, prompting with @var{prompt}. It does -not echo the password as the user types it; instead, it echoes @samp{.} -for each character in the password. +not echo the password as the user types it; instead, it echoes +@samp{.} for each character in the password. If you want to apply +another character to hide the password, let-bind the variable +@code{read-hide-char} with that character. The optional argument @var{confirm}, if non-@code{nil}, says to read the password twice and insist it must be the same both times. If it isn't @@ -2149,8 +2224,8 @@ contents of the minibuffer before the point. @section Minibuffer Windows @cindex minibuffer windows - These functions access and select minibuffer windows -and test whether they are active. +These functions access and select minibuffer windows, test whether they +are active and control how they get resized. @defun active-minibuffer-window This function returns the currently active minibuffer window, or @@ -2191,8 +2266,33 @@ This function returns non-@code{nil} if @var{window} is the currently active minibuffer window. @end defun +The following two options control whether minibuffer windows are resized +automatically and how large they can get in the process. + +@defopt resize-mini-windows +This option specifies whether minibuffer windows are resized +automatically. The default value is @code{grow-only}, which means that +a minibuffer window by default expands automatically to accommodate the +text it displays and shrinks back to one line as soon as the minibuffer +gets empty. If the value is @code{t}, Emacs will always try to fit the +height of a minibuffer window to the text it displays (with a minimum of +one line). If the value is @code{nil}, a minibuffer window never +changes size automatically. In that case the window resizing commands +(@pxref{Resizing Windows}) can be used to adjust its height. +@end defopt + +@defopt max-mini-window-height +This option provides a maximum height for resizing minibuffer windows +automatically. A floating-point number specifies a fraction of the +frame's height; an integer specifies the maximum number of lines. The +default value is 0.25. +@end defopt + + @node Minibuffer Contents @section Minibuffer Contents +@cindex access minibuffer contents +@cindex minibuffer contents, accessing These functions access the minibuffer prompt and contents. @@ -2224,12 +2324,6 @@ This is like @code{minibuffer-contents}, except that it does not copy text properties, just the characters themselves. @xref{Text Properties}. @end defun -@defun minibuffer-completion-contents -This is like @code{minibuffer-contents}, except that it returns only -the contents before point. That is the part that completion commands -operate on. @xref{Minibuffer Completion}. -@end defun - @defun delete-minibuffer-contents This function erases the editable contents of the minibuffer (that is, everything except the prompt), if a minibuffer is current. Otherwise, @@ -2322,7 +2416,7 @@ arrives, whichever comes first. The variable @code{minibuffer-message-timeout} specifies the number of seconds to wait in the absence of input. It defaults to 2. If @var{args} is non-@code{nil}, the actual message is obtained by passing @var{string} -and @var{args} through @code{format}. @xref{Formatting Strings}. +and @var{args} through @code{format-message}. @xref{Formatting Strings}. @end defun @deffn Command minibuffer-inactive-mode diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 180fef7241d..a1747707d11 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Modes @@ -69,11 +69,13 @@ functions are called with arguments, or their return values are used in some way. The hook's documentation says how the functions are called. You can use @code{add-hook} to add a function to an abnormal hook, but you must write the function to follow the hook's calling -convention. +convention. By convention, abnormal hook names end in @samp{-functions}. - By convention, abnormal hook names end in @samp{-functions}. If the -variable's name ends in @samp{-function}, then its value is just a single -function, not a list of functions. +@cindex single-function hook +If the variable's name ends in @samp{-function}, then its value is +just a single function, not a list of functions. @code{add-hook} cannot be +used to modify such a @emph{single function hook}, and you have to use +@code{add-function} instead (@pxref{Advising Functions}). @menu * Running Hooks:: How to run a hook. @@ -114,7 +116,7 @@ This function runs an abnormal hook by calling all the hook functions in @defun run-hook-with-args-until-failure hook &rest args This function runs an abnormal hook by calling each hook function in -turn, stopping if one of them ``fails'' by returning @code{nil}. Each +turn, stopping if one of them fails by returning @code{nil}. Each hook function is passed the arguments @var{args}. If this function stops because one of the hook functions fails, it returns @code{nil}; otherwise it returns a non-@code{nil} value. @@ -122,54 +124,13 @@ otherwise it returns a non-@code{nil} value. @defun run-hook-with-args-until-success hook &rest args This function runs an abnormal hook by calling each hook function, -stopping if one of them ``succeeds'' by returning a non-@code{nil} +stopping if one of them succeeds by returning a non-@code{nil} value. Each hook function is passed the arguments @var{args}. If this function stops because one of the hook functions returns a non-@code{nil} value, it returns that value; otherwise it returns @code{nil}. @end defun -@defmac with-wrapper-hook hook args &rest body -This macro runs the abnormal hook @code{hook} as a series of nested -``wrapper functions'' around the @var{body} forms. The effect is -similar to nested @code{around} advices (@pxref{Around-Advice}). - -Each hook function should accept an argument list consisting of a function -@var{fun}, followed by the additional arguments listed in @var{args}. -The first hook function is passed a function @var{fun} that, if it is -called with arguments @var{args}, performs @var{body} (i.e., the default -operation). The @var{fun} passed to each successive hook function is -constructed from all the preceding hook functions (and @var{body}); if -this @var{fun} is called with arguments @var{args}, it does what the -@code{with-wrapper-hook} call would if the preceding hook functions were -the only ones in @var{hook}. - -Each hook function may call its @var{fun} argument as many times as it -wishes, including never. In that case, such a hook function acts to -replace the default definition altogether, and any preceding hook -functions. Of course, a subsequent hook function may do the same thing. - -Each hook function definition is used to construct the @var{fun} passed -to the next hook function in @var{hook}, if any. The last or -``outermost'' @var{fun} is called once to produce the overall effect. - -When might you want to use a wrapper hook? The function -@code{filter-buffer-substring} illustrates a common case. There is a -basic functionality, performed by @var{body}---in this case, to extract -a buffer-substring. Then any number of hook functions can act in -sequence to modify that string, before returning the final result. -A wrapper-hook also allows for a hook function to completely replace the -default definition (by not calling @var{fun}). -@end defmac - -@defun run-hook-wrapped hook wrap-function &rest args -This function is similar to @code{run-hook-with-args-until-success}. -Like that function, it runs the functions on the abnormal hook -@code{hook}, stopping at the first one that returns non-@code{nil}. -Instead of calling the hook functions directly, though, it actually -calls @code{wrap-function} with arguments @code{fun} and @code{args}. -@end defun - @node Setting Hooks @subsection Setting Hooks @@ -385,14 +346,14 @@ reserved for users. A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and @kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally -be some kind of ``moving forward and backward'', but this does not +be some kind of moving forward and backward, but this does not necessarily mean cursor motion. It is legitimate for a major mode to rebind a standard key sequence if -it provides a command that does ``the same job'' in a way better +it provides a command that does the same job in a way better suited to the text this mode is used for. For example, a major mode for editing a programming language might redefine @kbd{C-M-a} to -``move to the beginning of a function'' in a way that works better for +move to the beginning of a function in a way that works better for that language. It is also legitimate for a major mode to rebind a standard key @@ -646,10 +607,10 @@ mode command. The default value is @code{lisp-interaction-mode}. @defvar interpreter-mode-alist This variable specifies major modes to use for scripts that specify a command interpreter in a @samp{#!} line. Its value is an alist with -elements of the form @code{(@var{interpreter} . @var{mode})}; for -example, @code{("perl" . perl-mode)} is one element present by -default. The element says to use mode @var{mode} if the file -specifies an interpreter which matches @var{interpreter}. +elements of the form @code{(@var{regexp} . @var{mode})}; this says to +use mode @var{mode} if the file specifies an interpreter which matches +@code{\\`@var{regexp}\\'}. For example, one of the default elements +is @code{("python[0-9.]*" . python-mode)}. @end defvar @defvar magic-mode-alist @@ -741,7 +702,7 @@ mode and minor modes. It uses the @code{documentation} function to retrieve the documentation strings of the major and minor mode commands (@pxref{Accessing Documentation}). -If called from Lisp with a non-nil @var{buffer} argument, this +If called from Lisp with a non-@code{nil} @var{buffer} argument, this function displays the documentation for that buffer's major and minor modes, rather than those of the current buffer. @end deffn @@ -788,7 +749,7 @@ The new mode has its own abbrev table, kept in the variable @item The new mode has its own mode hook, @code{@var{variant}-hook}. It runs this hook, after running the hooks of its ancestor modes, with -@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. +@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. @end itemize In addition, you can specify how to override other aspects of @@ -997,9 +958,9 @@ Menu,,, emacs, The GNU Emacs Manual}). way, specifying @code{tabulated-list-mode} as the second argument (@pxref{Derived Modes}). The body of the @code{define-derived-mode} form should specify the format of the tabulated data, by assigning -values to the variables documented below; then, it should call the -function @code{tabulated-list-init-header} to initialize the header -line. +values to the variables documented below; optionally, it can then call +the function @code{tabulated-list-init-header}, which will populate a +header with the names of the columns. The derived mode should also define a @dfn{listing command}. This, not the mode command, is what the user calls (e.g., @kbd{M-x @@ -1042,7 +1003,7 @@ should have the form @w{@code{(@var{id} @var{contents})}}, where @itemize @item @var{id} is either @code{nil}, or a Lisp object that identifies the -entry. If the latter, the cursor stays on the ``same'' entry when +entry. If the latter, the cursor stays on the same entry when re-sorting entries. Comparison is done with @code{equal}. @item @@ -1094,7 +1055,7 @@ the above variables (in particular, only after setting @code{tabulated-list-format}). @end defun -@defun tabulated-list-print &optional remember-pos +@defun tabulated-list-print &optional remember-pos update This function populates the current buffer with entries. It should be called by the listing command. It erases the buffer, sorts the entries specified by @code{tabulated-list-entries} according to @@ -1104,6 +1065,13 @@ specified by @code{tabulated-list-entries} according to If the optional argument @var{remember-pos} is non-@code{nil}, this function looks for the @var{id} element on the current line, if any, and tries to move to that entry after all the entries are (re)inserted. + +If the optional argument @var{update} is non-@code{nil}, this function +will only erase or add entries that have changed since the last print. +This is several times faster if most entries haven't changed since the +last time this function was called. The only difference in outcome is +that tags placed via @code{tabulated-list-put-tag} will not be removed +from entries that haven't changed (normally all tags are removed). @end defun @node Generic Modes @@ -1124,8 +1092,8 @@ documentation for the mode command. If you do not supply it, The argument @var{comment-list} is a list in which each element is either a character, a string of one or two characters, or a cons cell. A character or a string is set up in the mode's syntax table as a -``comment starter''. If the entry is a cons cell, the @sc{car} is set -up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''. +comment starter. If the entry is a cons cell, the @sc{car} is set +up as a comment starter and the @sc{cdr} as a comment ender. (Use @code{nil} for the latter if you want comments to end at the end of the line.) Note that the syntax table mechanism has limitations about what comment starters and enders are actually possible. @@ -1161,7 +1129,7 @@ the conventions listed above: (let ((st (make-syntax-table))) (modify-syntax-entry ?\" ". " st) (modify-syntax-entry ?\\ ". " st) - ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. + ;; Add 'p' so M-c on 'hello' leads to 'Hello', not 'hello'. (modify-syntax-entry ?' "w p" st) st) "Syntax table used while in `text-mode'.") @@ -1506,9 +1474,11 @@ designed for abbrevs and Auto Fill mode. Do not try substituting your own definition of @code{self-insert-command} for the standard one. The editor command loop handles this function specially.) -The key sequences bound in a minor mode should consist of @kbd{C-c} -followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other -punctuation characters are reserved for major modes.) +Minor modes may bind commands to key sequences consisting of @kbd{C-c} +followed by a punctuation character. However, sequences consisting of +@kbd{C-c} followed by one of @kbd{@{@}<>:;}, or a control character or +digit, are reserved for major modes. Also, @kbd{C-c @var{letter}} is +reserved for users. @xref{Key Binding Conventions}. @node Defining Minor Modes @subsection Defining Minor Modes @@ -1527,7 +1497,7 @@ A positive prefix argument enables the mode, any other prefix argument disables it. From Lisp, an argument of @code{toggle} toggles the mode, whereas an omitted or @code{nil} argument enables the mode. This makes it easy to enable the minor mode in a major mode hook, for example. -If @var{doc} is nil, the macro supplies a default documentation string +If @var{doc} is @code{nil}, the macro supplies a default documentation string explaining the above. By default, it also defines a variable named @var{mode}, which is set to @@ -1683,7 +1653,7 @@ minor modes don't need any. This defines a global toggle named @var{global-mode} whose meaning is to enable or disable the buffer-local minor mode @var{mode} in all buffers. To turn on the minor mode in a buffer, it uses the function -@var{turn-on}; to turn off the minor mode, it calls @code{mode} with +@var{turn-on}; to turn off the minor mode, it calls @var{mode} with @minus{}1 as argument. Globally enabling the mode also affects buffers subsequently created @@ -1812,7 +1782,7 @@ symbol whose value is void. There is one exception: if the value of @var{symbol} is a string, it is displayed verbatim: the @code{%}-constructs are not recognized. -Unless @var{symbol} is marked as ``risky'' (i.e., it has a +Unless @var{symbol} is marked as risky (i.e., it has a non-@code{nil} @code{risky-local-variable} property), all text properties specified in @var{symbol}'s value are ignored. This includes the text properties of strings in @var{symbol}'s value, as well as all @@ -2258,6 +2228,12 @@ is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). It is normally @code{nil}, so that ordinary buffers have no header line. @end defvar +@defun window-header-line-height &optional window +This function returns the height in pixels of @var{window}'s header +line. @var{window} must be a live window, and defaults to the +selected window. +@end defun + A window that is just one line tall never displays a header line. A window that is two lines tall cannot display both a mode line and a header line at once; if it has a mode line, then it does not display a @@ -2432,10 +2408,10 @@ variables @code{imenu-prev-index-position-function} and @defvar imenu-prev-index-position-function If this variable is non-@code{nil}, its value should be a function that -finds the next ``definition'' to put in the buffer index, scanning +finds the next definition to put in the buffer index, scanning backward in the buffer from point. It should return @code{nil} if it -doesn't find another ``definition'' before point. Otherwise it should -leave point at the place it finds a ``definition'' and return any +doesn't find another definition before point. Otherwise it should +leave point at the place it finds a definition and return any non-@code{nil} value. Setting this variable makes it buffer-local in the current buffer. @@ -2483,7 +2459,7 @@ Selecting a special element performs: A nested sub-alist element looks like this: @example -(@var{menu-title} @var{sub-alist}) +(@var{menu-title} . @var{sub-alist}) @end example It creates the submenu @var{menu-title} specified by @var{sub-alist}. @@ -2551,7 +2527,7 @@ If non-@code{nil}, the value should look like this: @example (@var{keywords} [@var{keywords-only} [@var{case-fold} - [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) + [@var{syntax-alist} @var{other-vars}@dots{}]]]) @end example The first element, @var{keywords}, indirectly specifies the value of @@ -2583,11 +2559,6 @@ fontification; the resulting syntax table is stored in @code{nil}, syntactic fontification uses the syntax table returned by the @code{syntax-table} function. @xref{Syntax Table Functions}. -The fifth element, @var{syntax-begin}, specifies the value of -@code{font-lock-beginning-of-syntax-function}. We recommend setting -this variable to @code{nil} and using @code{syntax-begin-function} -instead. - All the remaining elements (if any) are collectively called @var{other-vars}. Each of these elements should have the form @code{(@var{variable} . @var{value})}---which means, make @@ -3050,7 +3021,7 @@ default value is the symbol itself. Thus, the default value of @code{font-lock-comment-face} is @code{font-lock-comment-face}. The faces are listed with descriptions of their typical usage, and in -order of greater to lesser ``prominence''. If a mode's syntactic +order of greater to lesser prominence. If a mode's syntactic categories do not fit well with the usage descriptions, the faces can be assigned using the ordering as a guide. @@ -3148,26 +3119,6 @@ is @code{nil}, syntactic fontification uses the buffer's syntax table Table Functions}). @end defvar -@defvar font-lock-beginning-of-syntax-function -If this variable is non-@code{nil}, it should be a function to move -point back to a position that is syntactically at ``top level'' and -outside of strings or comments. The value is normally set through an -@var{other-vars} element in @code{font-lock-defaults}. If it is -@code{nil}, Font Lock uses @code{syntax-begin-function} to move back -outside of any comment, string, or sexp (@pxref{Position Parse}). - -This variable is semi-obsolete; we usually recommend setting -@code{syntax-begin-function} instead. One of its uses is to tune the -behavior of syntactic fontification, e.g., to ensure that different -kinds of strings or comments are highlighted differently. - -The specified function is called with no arguments. It should leave -point at the beginning of any enclosing syntactic block. Typical values -are @code{beginning-of-line} (used when the start of the line is known -to be outside a syntactic block), or @code{beginning-of-defun} for -programming modes, or @code{backward-paragraph} for textual modes. -@end defvar - @defvar font-lock-syntactic-face-function If this variable is non-@code{nil}, it should be a function to determine which face to use for a given syntactic element (a string or a comment). @@ -3331,18 +3282,28 @@ reasonably fast. @section Automatic Indentation of code For programming languages, an important feature of a major mode is to -provide automatic indentation. This is controlled in Emacs by -@code{indent-line-function} (@pxref{Mode-Specific Indent}). -Writing a good indentation function can be difficult and to a large -extent it is still a black art. - -Many major mode authors will start by writing a simple indentation -function that works for simple cases, for example by comparing with the -indentation of the previous text line. For most programming languages -that are not really line-based, this tends to scale very poorly: -improving such a function to let it handle more diverse situations tends -to become more and more difficult, resulting in the end with a large, -complex, unmaintainable indentation function which nobody dares to touch. +provide automatic indentation. There are two parts: one is to decide what +is the right indentation of a line, and the other is to decide when to +reindent a line. By default, Emacs reindents a line whenever you +type a character in @code{electric-indent-chars}, which by default only +includes Newline. Major modes can add chars to @code{electric-indent-chars} +according to the syntax of the language. + +Deciding what is the right indentation is controlled in Emacs by +@code{indent-line-function} (@pxref{Mode-Specific Indent}). For some modes, +the @emph{right} indentation cannot be known reliably, typically because +indentation is significant so several indentations are valid but with different +meanings. In that case, the mode should set @code{electric-indent-inhibit} to +make sure the line is not constantly re-indented against the user's wishes. + +Writing a good indentation function can be difficult and to a large extent it +is still a black art. Many major mode authors will start by writing a simple +indentation function that works for simple cases, for example by comparing with +the indentation of the previous text line. For most programming languages that +are not really line-based, this tends to scale very poorly: improving +such a function to let it handle more diverse situations tends to become more +and more difficult, resulting in the end with a large, complex, unmaintainable +indentation function which nobody dares to touch. A good indentation function will usually need to actually parse the text, according to the syntax of the language. Luckily, it is not @@ -3352,15 +3313,15 @@ indentation code will want to be somewhat friendly to syntactically incorrect code. Good maintainable indentation functions usually fall into two categories: -either parsing forward from some ``safe'' starting point until the +either parsing forward from some safe starting point until the position of interest, or parsing backward from the position of interest. Neither of the two is a clearly better choice than the other: parsing backward is often more difficult than parsing forward because programming languages are designed to be parsed forward, but for the purpose of indentation it has the advantage of not needing to -guess a ``safe'' starting point, and it generally enjoys the property +guess a safe starting point, and it generally enjoys the property that only a minimum of text will be analyzed to decide the indentation -of a line, so indentation will tend to be unaffected by syntax errors in +of a line, so indentation will tend to be less affected by syntax errors in some earlier unrelated piece of code. Parsing forward on the other hand is usually easier and has the advantage of making it possible to reindent efficiently a whole region at a time, with a single parse. @@ -3384,8 +3345,8 @@ of Lisp sexps and adapts it to non-Lisp languages. @cindex SMIE SMIE is a package that provides a generic navigation and indentation -engine. Based on a very simple parser using an ``operator precedence -grammar'', it lets major modes extend the sexp-based navigation of Lisp +engine. Based on a very simple parser using an operator precedence +grammar, it lets major modes extend the sexp-based navigation of Lisp to non-Lisp languages as well as provide a simple to use but reliable auto-indentation. @@ -3411,6 +3372,7 @@ resorting to some special tricks (@pxref{SMIE Tricks}). * SMIE Indentation:: Specifying indentation rules. * SMIE Indentation Helpers:: Helper functions for indentation rules. * SMIE Indentation Example:: Sample indentation rules. +* SMIE Customization:: Customizing indentation. @end menu @node SMIE setup @@ -3445,7 +3407,7 @@ provided grammar is precise enough, @code{transpose-sexps} can correctly transpose the two arguments of a @code{+} operator, taking into account the precedence rules of the language. -Calling `smie-setup' is also sufficient to make TAB indentation work in +Calling @code{smie-setup} is also sufficient to make TAB indentation work in the expected way, extends @code{blink-matching-paren} to apply to elements like @code{begin...end}, and provides some commands that you can bind in the major mode keymap. @@ -3679,7 +3641,7 @@ For example: Notice how those lexers return the empty string when in front of parentheses. This is because SMIE automatically takes care of the parentheses defined in the syntax table. More specifically if the lexer -returns nil or an empty string, SMIE tries to handle the corresponding +returns @code{nil} or an empty string, SMIE tries to handle the corresponding text as a sexp according to syntax tables. @node SMIE Tricks @@ -3821,8 +3783,8 @@ expressions (not separated by any token) rather than an expression. @end itemize When @var{arg} is a token, the function is called with point just before -that token. A return value of nil always means to fallback on the -default behavior, so the function should return nil for arguments it +that token. A return value of @code{nil} always means to fallback on the +default behavior, so the function should return @code{nil} for arguments it does not expect. @var{offset} can be: @@ -3894,7 +3856,7 @@ of instructions (enclosed in a @code{@{...@}} or @code{begin...end} block). @var{method} should be the method name that was passed to -`smie-rules-function'. +@code{smie-rules-function}. @end defun @node SMIE Indentation Example @@ -3921,7 +3883,7 @@ A few things to note: @itemize @item The first case indicates the basic indentation increment to use. -If @code{sample-indent-basic} is nil, then SMIE uses the global +If @code{sample-indent-basic} is @code{nil}, then SMIE uses the global setting @code{smie-indent-basic}. The major mode could have set @code{smie-indent-basic} buffer-locally instead, but that is discouraged. @@ -3989,6 +3951,52 @@ the previous @code{"else"}, rather than going all the way back to the first @code{"if"} of the sequence. @end itemize +@c In some sense this belongs more in the Emacs manual. +@node SMIE Customization +@subsubsection Customizing Indentation + +If you are using a mode whose indentation is provided by SMIE, you can +customize the indentation to suit your preferences. You can do this +on a per-mode basis (using the option @code{smie-config}), or a +per-file basis (using the function @code{smie-config-local} in a +file-local variable specification). + +@defopt smie-config +This option lets you customize indentation on a per-mode basis. +It is an alist with elements of the form @code{(@var{mode} . @var{rules})}. +For the precise form of rules, see the variable's documentation; but +you may find it easier to use the command @code{smie-config-guess}. +@end defopt + +@deffn Command smie-config-guess +This command tries to work out appropriate settings to produce +your preferred style of indentation. Simply call the command while +visiting a file that is indented with your style. +@end deffn + +@deffn Command smie-config-save +Call this command after using @code{smie-config-guess}, to save your +settings for future sessions. +@end deffn + +@deffn Command smie-config-show-indent &optional move +This command displays the rules that are used to indent the current +line. +@end deffn + +@deffn Command smie-config-set-indent +This command adds a local rule to adjust the indentation of the current line. +@end deffn + +@defun smie-config-local rules +This function adds @var{rules} as indentation rules for the current buffer. +These add to any mode-specific rules defined by the @code{smie-config} option. +To specify custom indentation rules for a specific file, add an entry +to the file's local variables of the form: +@code{eval: (smie-config-local '(@var{rules}))}. +@end defun + + @node Desktop Save Mode @section Desktop Save Mode @cindex desktop save mode diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 090310c5545..3351b841f45 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1998-1999, 2001-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Non-ASCII Characters @chapter Non-@acronym{ASCII} Characters @@ -50,7 +50,7 @@ inclusive. Emacs extends this range with codepoints in the range @code{#x110000..#x3FFFFF}, which it uses for representing characters that are not unified with Unicode and @dfn{raw 8-bit bytes} that cannot be interpreted as characters. Thus, a character codepoint in -Emacs is a 22-bit integer number. +Emacs is a 22-bit integer. @cindex internal representation of characters @cindex characters, representation in buffers and strings @@ -248,6 +248,7 @@ unibyte string, it is returned unchanged. Use this function for characters. @end defun +@c FIXME: Should '@var{character}' be '@var{byte}'? @defun byte-to-string byte @cindex byte to string This function returns a unibyte string containing a single byte of @@ -258,7 +259,7 @@ character data, @var{character}. It signals an error if @defun multibyte-char-to-unibyte char This converts the multibyte character @var{char} to a unibyte character, and returns that character. If @var{char} is neither -@acronym{ASCII} nor eight-bit, the function returns -1. +@acronym{ASCII} nor eight-bit, the function returns @minus{}1. @end defun @defun unibyte-char-to-multibyte char @@ -401,12 +402,14 @@ specifies how the character behaves and how it should be handled during text processing and display. Thus, character properties are an important part of specifying the character's semantics. +@c FIXME: Use the latest URI of this chapter? +@c http://www.unicode.org/versions/latest/ch04.pdf On the whole, Emacs follows the Unicode Standard in its implementation of character properties. In particular, Emacs supports the @uref{http://www.unicode.org/reports/tr23/, Unicode Character Property Model}, and the Emacs character property database is derived from the Unicode Character Database (@acronym{UCD}). See the -@uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character +@uref{http://www.unicode.org/versions/Unicode6.2.0/ch04.pdf, Character Properties chapter of the Unicode Standard}, for a detailed description of Unicode character properties and their meaning. This section assumes you are already familiar with that chapter of the @@ -437,7 +440,7 @@ properties that Emacs knows about: Corresponds to the @code{Name} Unicode property. The value is a string consisting of upper-case Latin letters A to Z, digits, spaces, and hyphen @samp{-} characters. For unassigned codepoints, the value -is an empty string. +is @code{nil}. @cindex unicode general category @item general-category @@ -448,7 +451,7 @@ is @code{Cn}. @item canonical-combining-class Corresponds to the @code{Canonical_Combining_Class} Unicode property. -The value is an integer number. For unassigned codepoints, the value +The value is an integer. For unassigned codepoints, the value is zero. @cindex bidirectional class of characters @@ -471,32 +474,36 @@ inside @samp{<..>} brackets, but the tag names in Emacs do not include the brackets; e.g., Unicode specifies @samp{<small>} where Emacs uses @samp{small}. }; the other elements are characters that give the compatibility decomposition sequence of this character. For -unassigned codepoints, the value is the character itself. +characters that don't have decomposition sequences, and for unassigned +codepoints, the value is a list with a single member, the character +itself. @item decimal-digit-value Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Digit}. The value is an -integer number. For unassigned codepoints, the value is @code{nil}, -which means @acronym{NaN}, or ``not-a-number''. +characters whose @code{Numeric_Type} is @samp{Decimal}. The value is +an integer, or @code{nil} if the character has no decimal digit value. +For unassigned codepoints, the value is @code{nil}, which means +@acronym{NaN}, or ``not a number''. @item digit-value Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Decimal}. The value is -an integer number. Examples of such characters include compatibility -subscript and superscript digits, for which the value is the -corresponding number. For unassigned codepoints, the value is -@code{nil}, which means @acronym{NaN}. +characters whose @code{Numeric_Type} is @samp{Digit}. The value is an +integer. Examples of such characters include compatibility subscript +and superscript digits, for which the value is the corresponding +number. For characters that don't have any numeric value, and for +unassigned codepoints, the value is @code{nil}, which means +@acronym{NaN}. @item numeric-value Corresponds to the Unicode @code{Numeric_Value} property for characters whose @code{Numeric_Type} is @samp{Numeric}. The value of -this property is an integer or a floating-point number. Examples of -characters that have this property include fractions, subscripts, -superscripts, Roman numerals, currency numerators, and encircled -numbers. For example, the value of this property for the character -@code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. For -unassigned codepoints, the value is @code{nil}, which means -@acronym{NaN}. +this property is a number. Examples of characters that have this +property include fractions, subscripts, superscripts, Roman numerals, +currency numerators, and encircled numbers. For example, the value of +this property for the character @code{U+2155} (@sc{vulgar fraction one +fifth}) is @code{0.2}. For characters that don't have any numeric +value, and for unassigned codepoints, the value is @code{nil}, which +means @acronym{NaN}. @cindex mirroring of characters @item mirrored @@ -517,13 +524,33 @@ property to display mirror images of characters when appropriate (@pxref{Bidirectional Display}). For unassigned codepoints, the value is @code{nil}. +@item paired-bracket +Corresponds to the Unicode @code{Bidi_Paired_Bracket} property. The +value of this property is the codepoint of a character's @dfn{paired +bracket}, or @code{nil} if the character is not a bracket character. +This establishes a mapping between characters that are treated as +bracket pairs by the Unicode Bidirectional Algorithm; Emacs uses this +property when it decides how to reorder for display parentheses, +braces, and other similar characters (@pxref{Bidirectional Display}). + +@item bracket-type +Corresponds to the Unicode @code{Bidi_Paired_Bracket_Type} property. +For characters whose @code{paired-bracket} property is non-@code{nil}, +the value of this property is a symbol, either @code{o} (for opening +bracket characters) or @code{c} (for closing bracket characters). For +characters whose @code{paired-bracket} property is @code{nil}, the +value is the symbol @code{n} (None). Like @code{paired-bracket}, this +property is used for bidirectional display. + @item old-name Corresponds to the Unicode @code{Unicode_1_Name} property. The value -is a string. For unassigned codepoints, the value is an empty string. +is a string. For unassigned codepoints, and characters that have no +value for this property, the value is @code{nil}. @item iso-10646-comment Corresponds to the Unicode @code{ISO_Comment} property. The value is -a string. For unassigned codepoints, the value is an empty string. +either a string or @code{nil}. For unassigned codepoints, the value +is @code{nil}. @item uppercase Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property. @@ -548,28 +575,36 @@ This function returns the value of @var{char}'s @var{propname} property. @example @group -(get-char-code-property ? 'general-category) +(get-char-code-property ?\s 'general-category) @result{} Zs @end group @group -(get-char-code-property ?1 'general-category) +(get-char-code-property ?1 'general-category) @result{} Nd @end group @group -;; subscript 4 +;; U+2084 SUBSCRIPT FOUR (get-char-code-property ?\u2084 'digit-value) @result{} 4 @end group @group -;; one fifth +;; U+2155 VULGAR FRACTION ONE FIFTH (get-char-code-property ?\u2155 'numeric-value) @result{} 0.2 @end group @group -;; Roman IV +;; U+2163 ROMAN NUMERAL FOUR (get-char-code-property ?\u2163 'numeric-value) @result{} 4 @end group +@group +(get-char-code-property ?\( 'paired-bracket) + @result{} 41 ;; closing parenthesis +@end group +@group +(get-char-code-property ?\) 'bracket-type) + @result{} c +@end group @end example @end defun @@ -605,6 +640,7 @@ property as a symbol. @end defvar @defvar char-script-table +@cindex script symbols The value of this variable is a char-table that specifies, for each character, a symbol whose name is the script to which the character belongs, according to the Unicode Standard classification of the @@ -681,6 +717,7 @@ which case the returned charset must be supported by that coding system (@pxref{Coding Systems}). @end defun +@c TODO: Explain the properties here and add indexes such as 'charset property'. @defun charset-plist charset This function returns the property list of the character set @var{charset}. Although @var{charset} is a symbol, this is not the @@ -751,6 +788,8 @@ of them is @code{nil}, it defaults to the first or last codepoint of @node Scanning Charsets @section Scanning for Character Sets +@cindex scanning for character sets +@cindex character set, searching Sometimes it is useful to find out which character set a particular character belongs to. One use for this is in determining which coding @@ -846,6 +885,8 @@ systems specifies its own translation tables, the table that is the value of this variable, if non-@code{nil}, is applied after them. @end defvar +@c FIXME: This variable is obsolete since 23.1. We should mention +@c that here or simply remove this defvar. --xfq @defvar translation-table-for-input Self-inserting characters are translated through this translation table before they are inserted. Search commands also translate their @@ -954,7 +995,8 @@ Unix convention, used on GNU and Unix systems, is to use the linefeed character (also called newline). The DOS convention, used on MS-Windows and MS-DOS systems, is to use a carriage-return and a linefeed at the end of a line. The Mac convention is to use just -carriage-return. +carriage-return. (This was the convention used on the Macintosh +system prior to OS X.) @cindex base coding system @cindex variant coding system @@ -1098,6 +1140,16 @@ visited file name, saving may use the wrong file name, or it may get an error. If such a problem happens, use @kbd{C-x C-w} to specify a new file name for that buffer. +@cindex file-name encoding, MS-Windows + On Windows 2000 and later, Emacs by default uses Unicode APIs to +pass file names to the OS, so the value of +@code{file-name-coding-system} is largely ignored. Lisp applications +that need to encode or decode file names on the Lisp level should use +@code{utf-8} coding-system when @code{system-type} is +@code{windows-nt}; the conversion of UTF-8 encoded file names to the +encoding appropriate for communicating with the OS is performed +internally by Emacs. + @node Lisp and Coding Systems @subsection Coding Systems in Lisp @@ -1268,17 +1320,18 @@ Sets}) supported by @var{coding-system}. Some coding systems that support too many character sets to list them all yield special values: @itemize @bullet @item -If @var{coding-system} supports all the ISO-2022 charsets, the value -is @code{iso-2022}. -@item If @var{coding-system} supports all Emacs characters, the value is @code{(emacs)}. @item -If @var{coding-system} supports all emacs-mule characters, the value -is @code{emacs-mule}. -@item If @var{coding-system} supports all Unicode characters, the value is @code{(unicode)}. +@item +If @var{coding-system} supports all ISO-2022 charsets, the value is +@code{iso-2022}. +@item +If @var{coding-system} supports all the characters in the internal +coding system used by Emacs version 21 (prior to the implementation of +internal Unicode support), the value is @code{emacs-mule}. @end itemize @end defun @@ -1327,7 +1380,7 @@ alternatives described above. The optional argument @var{accept-default-p}, if non-@code{nil}, should be a function to determine whether a coding system selected -without user interaction is acceptable. @code{select-safe-coding-system} +without user interaction is acceptable. @code{select-safe-coding-system} calls this function with one argument, the base coding system of the selected coding system. If @var{accept-default-p} returns @code{nil}, @code{select-safe-coding-system} rejects the silently selected coding @@ -1389,7 +1442,7 @@ don't change these variables; instead, override them using @cindex file contents, and default coding system @defopt auto-coding-regexp-alist This variable is an alist of text patterns and corresponding coding -systems. Each element has the form @code{(@var{regexp} +systems. Each element has the form @code{(@var{regexp} . @var{coding-system})}; a file whose first few kilobytes match @var{regexp} is decoded with @var{coding-system} when its contents are read into a buffer. The settings in this alist take priority over @@ -1563,7 +1616,7 @@ the alist; otherwise it returns @code{nil}. If @var{operation} is @code{insert-file-contents}, the argument corresponding to the target may be a cons cell of the form -@code{(@var{filename} . @var{buffer})}). In that case, @var{filename} +@code{(@var{filename} . @var{buffer})}. In that case, @var{filename} is a file name to look up in @code{file-coding-system-alist}, and @var{buffer} is a buffer that contains the file's contents (not yet decoded). If @code{file-coding-system-alist} specifies a function to @@ -1574,6 +1627,9 @@ contents (as it usually does), it should examine the contents of @node Specifying Coding Systems @subsection Specifying a Coding System for One Operation +@cindex specify coding system +@cindex force coding system for operation +@cindex coding system for operation You can specify the coding system for a specific operation by binding the variables @code{coding-system-for-read} and/or @@ -1596,8 +1652,7 @@ of the right way to use the variable: @example ;; @r{Read the file with no character code conversion.} -;; @r{Assume @acronym{crlf} represents end-of-line.} -(let ((coding-system-for-read 'emacs-mule-dos)) +(let ((coding-system-for-read 'no-conversion)) (insert-file-contents filename)) @end example @@ -1767,7 +1822,7 @@ original text: @example @group (decode-coding-string "Gr\374ss Gott" 'latin-1) - @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1)) + @result{} #("Grüss Gott" 0 9 (charset iso-8859-1)) @end group @end example @end defun @@ -1786,24 +1841,23 @@ decoding, you can call this function. @node Terminal I/O Encoding @subsection Terminal I/O Encoding - Emacs can decode keyboard input using a coding system, and encode + Emacs can use coding systems to decode keyboard input and encode terminal output. This is useful for terminals that transmit or -display text using a particular encoding such as Latin-1. Emacs does -not set @code{last-coding-system-used} for encoding or decoding of +display text using a particular encoding, such as Latin-1. Emacs does +not set @code{last-coding-system-used} when encoding or decoding terminal I/O. @defun keyboard-coding-system &optional terminal -This function returns the coding system that is in use for decoding -keyboard input from @var{terminal}---or @code{nil} if no coding system -is to be used for that terminal. If @var{terminal} is omitted or -@code{nil}, it means the selected frame's terminal. @xref{Multiple -Terminals}. +This function returns the coding system used for decoding keyboard +input from @var{terminal}. A value of @code{no-conversion} means no +decoding is done. If @var{terminal} is omitted or @code{nil}, it +means the selected frame's terminal. @xref{Multiple Terminals}. @end defun @deffn Command set-keyboard-coding-system coding-system &optional terminal This command specifies @var{coding-system} as the coding system to use for decoding keyboard input from @var{terminal}. If -@var{coding-system} is @code{nil}, that means do not decode keyboard +@var{coding-system} is @code{nil}, that means not to decode keyboard input. If @var{terminal} is a frame, it means that frame's terminal; if it is @code{nil}, that means the currently selected frame's terminal. @xref{Multiple Terminals}. @@ -1811,18 +1865,19 @@ terminal. @xref{Multiple Terminals}. @defun terminal-coding-system &optional terminal This function returns the coding system that is in use for encoding -terminal output from @var{terminal}---or @code{nil} if the output is -not encoded. If @var{terminal} is a frame, it means that frame's -terminal; if it is @code{nil}, that means the currently selected -frame's terminal. +terminal output from @var{terminal}. A value of @code{no-conversion} +means no encoding is done. If @var{terminal} is a frame, it means +that frame's terminal; if it is @code{nil}, that means the currently +selected frame's terminal. @end defun @deffn Command set-terminal-coding-system coding-system &optional terminal This command specifies @var{coding-system} as the coding system to use for encoding terminal output from @var{terminal}. If -@var{coding-system} is @code{nil}, terminal output is not encoded. If -@var{terminal} is a frame, it means that frame's terminal; if it is -@code{nil}, that means the currently selected frame's terminal. +@var{coding-system} is @code{nil}, that means not to encode terminal +output. If @var{terminal} is a frame, it means that frame's terminal; +if it is @code{nil}, that means the currently selected frame's +terminal. @end deffn @node Input Methods @@ -1901,7 +1956,7 @@ and @ref{Invoking the Input Method}. @section Locales @cindex locale - POSIX defines a concept of ``locales'' which control which language + In POSIX, locales control which language to use in language-related features. These Emacs variables control how Emacs interacts with these features. @@ -1909,6 +1964,7 @@ how Emacs interacts with these features. @cindex keyboard input decoding on X This variable specifies the coding system to use for decoding system error messages and---on X Window system only---keyboard input, for +sending batch output to the standard output and error streams, for encoding the format argument to @code{format-time-string}, and for decoding the return value of @code{format-time-string}. @end defvar diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 2b6f31b670b..54c8d3e5988 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Numbers @@ -9,13 +9,14 @@ @cindex numbers GNU Emacs supports two numeric data types: @dfn{integers} and -@dfn{floating point numbers}. Integers are whole numbers such as -@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point -numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or -2.71828. They can also be expressed in exponential notation: 1.5e2 -equals 150; in this example, @samp{e2} stands for ten to the second -power, and that is multiplied by 1.5. Floating point values are not -exact; they have a fixed, limited amount of precision. +@dfn{floating-point numbers}. Integers are whole numbers such as +@minus{}3, 0, 7, 13, and 511. Floating-point numbers are numbers with +fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can +also be expressed in exponential notation: @samp{1.5e2} is the same as +@samp{150.0}; here, @samp{e2} stands for ten to the second power, and +that is multiplied by 1.5. Integer computations are exact, though +they may overflow. Floating-point computations often involve rounding +errors, as the numbers have a fixed amount of precision. @menu * Integer Basics:: Representation and range of integers. @@ -24,7 +25,7 @@ exact; they have a fixed, limited amount of precision. * Comparison of Numbers:: Equality and inequality predicates. * Numeric Conversions:: Converting float to integer and vice versa. * Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. +* Rounding Operations:: Explicitly rounding floating-point numbers. * Bitwise Operations:: Logical and, or, not, shifting. * Math Functions:: Trig, exponential and logarithmic functions. * Random Numbers:: Obtaining random integers, predictable or not. @@ -34,9 +35,9 @@ exact; they have a fixed, limited amount of precision. @section Integer Basics The range of values for an integer depends on the machine. The -minimum range is @minus{}536870912 to 536870911 (30 bits; i.e., +minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex --2**29 +@minus{}2**29 @end ifnottex @tex @math{-2^{29}} @@ -61,7 +62,8 @@ Emacs range is treated as a floating-point number. 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 1073741825 ; @r{The floating point number 1073741825.0.} + 9000000000000000000 + ; @r{The floating-point number 9e18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -114,15 +116,15 @@ use the @samp{...} notation to make binary integers easier to read.) @minus{}1 is represented as 30 ones. (This is called @dfn{two's complement} notation.) - The negative integer, @minus{}5, is creating by subtracting 4 from -@minus{}1. In binary, the decimal integer 4 is 100. Consequently, + Subtracting 4 from @minus{}1 returns the negative integer @minus{}5. +In binary, the decimal integer 4 is 100. Consequently, @minus{}5 looks like this: @example 1111...111011 (30 bits total) @end example - In this implementation, the largest 30-bit binary integer value is + In this implementation, the largest 30-bit binary integer is 536,870,911 in decimal. In binary, it looks like this: @example @@ -145,111 +147,143 @@ arguments to such functions may be either numbers or markers, we often give these arguments the name @var{number-or-marker}. When the argument value is a marker, its position value is used and its buffer is ignored. -@cindex largest Lisp integer number -@cindex maximum Lisp integer number +@cindex largest Lisp integer +@cindex maximum Lisp integer @defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp -can handle. +The value of this variable is the largest integer that Emacs Lisp can +handle. Typical values are +@ifnottex +2**29 @minus{} 1 +@end ifnottex +@tex +@math{2^{29}-1} +@end tex +on 32-bit and +@ifnottex +2**61 @minus{} 1 +@end ifnottex +@tex +@math{2^{61}-1} +@end tex +on 64-bit platforms. @end defvar -@cindex smallest Lisp integer number -@cindex minimum Lisp integer number +@cindex smallest Lisp integer +@cindex minimum Lisp integer @defvar most-negative-fixnum The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. +handle. It is negative. Typical values are +@ifnottex +@minus{}2**29 +@end ifnottex +@tex +@math{-2^{29}} +@end tex +on 32-bit and +@ifnottex +@minus{}2**61 +@end ifnottex +@tex +@math{-2^{61}} +@end tex +on 64-bit platforms. @end defvar In Emacs Lisp, text characters are represented by integers. Any -integer between zero and the value of @code{max-char}, inclusive, is -considered to be valid as a character. @xref{String Basics}. +integer between zero and the value of @code{(max-char)}, inclusive, is +considered to be valid as a character. @xref{Character Codes}. @node Float Basics -@section Floating Point Basics +@section Floating-Point Basics @cindex @acronym{IEEE} floating point - Floating point numbers are useful for representing numbers that are -not integral. The precise range of floating point numbers is -machine-specific; it is the same as the range of the C data type -@code{double} on the machine you are using. Emacs uses the -@acronym{IEEE} floating point standard, which is supported by all -modern computers. - - The read syntax for floating point numbers requires either a decimal -point (with at least one digit following), an exponent, or both. For -example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and -@samp{.15e4} are five ways of writing a floating point number whose -value is 1500. They are all equivalent. You can also use a minus -sign to write negative floating point numbers, as in @samp{-1.0}. - - Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with -respect to @code{equal} and @code{=}), even though the two are -distinguishable in the @acronym{IEEE} floating point standard. + Floating-point numbers are useful for representing numbers that are +not integral. The range of floating-point numbers is +the same as the range of the C data type @code{double} on the machine +you are using. On all computers currently supported by Emacs, this is +double-precision @acronym{IEEE} floating point. + + The read syntax for floating-point numbers requires either a decimal +point, an exponent, or both. Optional signs (@samp{+} or @samp{-}) +precede the number and its exponent. For example, @samp{1500.0}, +@samp{+15e2}, @samp{15.0e+2}, @samp{+1500000e-3}, and @samp{.15e4} are +five ways of writing a floating-point number whose value is 1500. +They are all equivalent. Like Common Lisp, Emacs Lisp requires at +least one digit after any decimal point in a floating-point number; +@samp{1500.} is an integer, not a floating-point number. + + Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero +with respect to @code{equal} and @code{=}. This follows the +@acronym{IEEE} floating-point standard, which says @code{-0.0} and +@code{0.0} are numerically equal even though other operations can +distinguish them. @cindex positive infinity @cindex negative infinity @cindex infinity @cindex NaN - The @acronym{IEEE} floating point standard supports positive -infinity and negative infinity as floating point values. It also -provides for a class of values called NaN or ``not-a-number''; + The @acronym{IEEE} floating-point standard supports positive +infinity and negative infinity as floating-point values. It also +provides for a class of values called NaN, or ``not a number''; numerical functions return such values in cases where there is no -correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. (NaN -values can also carry a sign, but for practical purposes there's no -significant difference between different NaN values in Emacs Lisp.) - -When a function is documented to return a NaN, it returns an -implementation-defined value when Emacs is running on one of the -now-rare platforms that do not use @acronym{IEEE} floating point. For -example, @code{(log -1.0)} typically returns a NaN, but on -non-@acronym{IEEE} platforms it returns an implementation-defined -value. +correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. +Although NaN values carry a sign, for practical purposes there is no other +significant difference between different NaN values in Emacs Lisp. -Here are the read syntaxes for these special floating point values: +Here are read syntaxes for these special floating-point values: @table @asis -@item positive infinity -@samp{1.0e+INF} -@item negative infinity -@samp{-1.0e+INF} -@item Not-a-number -@samp{0.0e+NaN} or @samp{-0.0e+NaN}. +@item infinity +@samp{1.0e+INF} and @samp{-1.0e+INF} +@item not-a-number +@samp{0.0e+NaN} and @samp{-0.0e+NaN} @end table -@defun isnan number -This predicate tests whether its argument is NaN, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. -@end defun - - The following functions are specialized for handling floating point + The following functions are specialized for handling floating-point numbers: -@defun frexp x -This function returns a cons cell @code{(@var{sig} . @var{exp})}, -where @var{sig} and @var{exp} are respectively the significand and -exponent of the floating point number @var{x}: +@defun isnan x +This predicate returns @code{t} if its floating-point argument is a NaN, +@code{nil} otherwise. +@end defun -@smallexample -@var{x} = @var{sig} * 2^@var{exp} -@end smallexample +@defun frexp x +This function returns a cons cell @code{(@var{s} . @var{e})}, +where @var{s} and @var{e} are respectively the significand and +exponent of the floating-point number @var{x}. -@var{sig} is a floating point number between 0.5 (inclusive) and 1.0 -(exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}. +If @var{x} is finite, then @var{s} is a floating-point number between 0.5 +(inclusive) and 1.0 (exclusive), @var{e} is an integer, and +@ifnottex +@var{x} = @var{s} * 2**@var{e}. +@end ifnottex +@tex +@math{x = s 2^e}. +@end tex +If @var{x} is zero or infinity, then @var{s} is the same as @var{x}. +If @var{x} is a NaN, then @var{s} is also a NaN@. +If @var{x} is zero, then @var{e} is 0. @end defun -@defun ldexp sig &optional exp -This function returns a floating point number corresponding to the -significand @var{sig} and exponent @var{exp}. +@defun ldexp s e +Given a numeric significand @var{s} and an integer exponent @var{e}, +this function returns the floating point number +@ifnottex +@var{s} * 2**@var{e}. +@end ifnottex +@tex +@math{s 2^e}. +@end tex @end defun @defun copysign x1 x2 This function copies the sign of @var{x2} to the value of @var{x1}, -and returns the result. @var{x1} and @var{x2} must be floating point -numbers. +and returns the result. @var{x1} and @var{x2} must be floating point. @end defun -@defun logb number -This function returns the binary exponent of @var{number}. More -precisely, the value is the logarithm of |@var{number}| base 2, rounded +@defun logb x +This function returns the binary exponent of @var{x}. More +precisely, the value is the logarithm base 2 of @math{|x|}, rounded down to an integer. @example @@ -272,8 +306,8 @@ its argument. See also @code{integer-or-marker-p} and @code{number-or-marker-p}, in @ref{Predicates on Markers}. @defun floatp object -This predicate tests whether its argument is a floating point -number and returns @code{t} if so, @code{nil} otherwise. +This predicate tests whether its argument is floating point +and returns @code{t} if so, @code{nil} otherwise. @end defun @defun integerp object @@ -293,8 +327,8 @@ tests to see whether its argument is a nonnegative integer, and returns @code{t} if so, @code{nil} otherwise. 0 is considered non-negative. -@findex wholenump number -This is a synonym for @code{natnump}. +@findex wholenump +@code{wholenump} is a synonym for @code{natnump}. @end defun @defun zerop number @@ -310,13 +344,13 @@ if so, @code{nil} otherwise. The argument must be a number. @cindex comparing numbers To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating point -number objects with the same numeric value. If you use @code{eq} to +@code{=}, not @code{eq}. There can be many distinct floating-point +objects with the same numeric value. If you use @code{eq} to compare them, then you test whether two values are the same @emph{object}. By contrast, @code{=} compares only the numeric values of the objects. - In Emacs Lisp, each integer value is a unique Lisp object. + In Emacs Lisp, each integer is a unique Lisp object. Therefore, @code{eq} is equivalent to @code{=} where integers are concerned. It is sometimes convenient to use @code{eq} for comparing an unknown value with an integer, because @code{eq} does not report an @@ -328,18 +362,18 @@ use @code{=} if you can, even for comparing integers. Sometimes it is useful to compare numbers with @code{equal}, which treats two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, -@code{=} can treat an integer and a floating point number as equal. +@code{=} can treat an integer and a floating-point number as equal. @xref{Equality Predicates}. - There is another wrinkle: because floating point arithmetic is not -exact, it is often a bad idea to check for equality of two floating -point values. Usually it is better to test for approximate equality. + There is another wrinkle: because floating-point arithmetic is not +exact, it is often a bad idea to check for equality of floating-point +values. Usually it is better to test for approximate equality. Here's a function to do this: @example (defvar fuzz-factor 1.0e-6) (defun approx-equal (x y) - (or (and (= x 0) (= y 0)) + (or (= x y) (< (/ (abs (- x y)) (max (abs x) (abs y))) fuzz-factor))) @@ -351,12 +385,12 @@ Here's a function to do this: @code{=} because Common Lisp implements multi-word integers, and two distinct integer objects can have the same numeric value. Emacs Lisp can have just one integer object for any given value because it has a -limited range of integer values. +limited range of integers. @end quotation -@defun = number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if so, @code{nil} otherwise. +@defun = number-or-marker &rest number-or-markers +This function tests whether all its arguments are numerically equal, +and returns @code{t} if so, @code{nil} otherwise. @end defun @defun eql value1 value2 @@ -371,32 +405,29 @@ This function tests whether its arguments are numerically equal, and returns @code{t} if they are not, and @code{nil} if they are. @end defun -@defun < number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly less than -its second argument. It returns @code{t} if so, @code{nil} otherwise. +@defun < number-or-marker &rest number-or-markers +This function tests whether each argument is strictly less than the +following argument. It returns @code{t} if so, @code{nil} otherwise. @end defun -@defun <= number-or-marker1 number-or-marker2 -This function tests whether its first argument is less than or equal -to its second argument. It returns @code{t} if so, @code{nil} -otherwise. +@defun <= number-or-marker &rest number-or-markers +This function tests whether each argument is less than or equal to +the following argument. It returns @code{t} if so, @code{nil} otherwise. @end defun -@defun > number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly greater -than its second argument. It returns @code{t} if so, @code{nil} -otherwise. +@defun > number-or-marker &rest number-or-markers +This function tests whether each argument is strictly greater than +the following argument. It returns @code{t} if so, @code{nil} otherwise. @end defun -@defun >= number-or-marker1 number-or-marker2 -This function tests whether its first argument is greater than or -equal to its second argument. It returns @code{t} if so, @code{nil} -otherwise. +@defun >= number-or-marker &rest number-or-markers +This function tests whether each argument is greater than or equal to +the following argument. It returns @code{t} if so, @code{nil} otherwise. @end defun @defun max number-or-marker &rest numbers-or-markers This function returns the largest of its arguments. -If any of the arguments is floating-point, the value is returned +If any of the arguments is floating point, the value is returned as floating point, even if it was given as an integer. @example @@ -411,7 +442,7 @@ as floating point, even if it was given as an integer. @defun min number-or-marker &rest numbers-or-markers This function returns the smallest of its arguments. -If any of the arguments is floating-point, the value is returned +If any of the arguments is floating point, the value is returned as floating point, even if it was given as an integer. @example @@ -434,20 +465,20 @@ To convert an integer to floating point, use the function @code{float}. @defun float number This returns @var{number} converted to floating point. -If @var{number} is already a floating point number, @code{float} returns +If @var{number} is already floating point, @code{float} returns it unchanged. @end defun - There are four functions to convert floating point numbers to + There are four functions to convert floating-point numbers to integers; they differ in how they round. All accept an argument @var{number} and an optional argument @var{divisor}. Both arguments -may be integers or floating point numbers. @var{divisor} may also be +may be integers or floating-point numbers. @var{divisor} may also be @code{nil}. If @var{divisor} is @code{nil} or omitted, these functions convert @var{number} to an integer, or return it unchanged if it already is an integer. If @var{divisor} is non-@code{nil}, they divide @var{number} by @var{divisor} and convert the result to an -integer. integer. If @var{divisor} is zero (whether integer or -floating-point), Emacs signals an @code{arith-error} error. +integer. If @var{divisor} is zero (whether integer or +floating point), Emacs signals an @code{arith-error} error. @defun truncate number &optional divisor This returns @var{number}, converted to an integer by rounding towards @@ -505,8 +536,7 @@ This returns @var{number}, converted to an integer by rounding upward @defun round number &optional divisor This returns @var{number}, converted to an integer by rounding towards the nearest integer. Rounding a value equidistant between two integers -may choose the integer closer to zero, or it may prefer an even integer, -depending on your machine. +returns the even integer. @example (round 1.2) @@ -528,11 +558,11 @@ depending on your machine. (addition, subtraction, multiplication, and division), as well as remainder and modulus functions, and functions to add or subtract 1. Except for @code{%}, each of these functions accepts both integer and -floating point arguments, and returns a floating point number if any -argument is a floating point number. +floating-point arguments, and returns a floating-point number if any +argument is floating point. - It is important to note that in Emacs Lisp, arithmetic functions -do not check for overflow. Thus @code{(1+ 536870911)} may evaluate to + Emacs Lisp arithmetic functions do not check for integer overflow. +Thus @code{(1+ 536870911)} may evaluate to @minus{}536870912, depending on your hardware. @defun 1+ number-or-marker @@ -612,18 +642,15 @@ product. When given no arguments, @code{*} returns 1. @end example @end defun -@defun / dividend divisor &rest divisors -This function divides @var{dividend} by @var{divisor} and returns the -quotient. If there are additional arguments @var{divisors}, then it -divides @var{dividend} by each divisor in turn. Each argument may be a +@defun / number &rest divisors +With one or more @var{divisors}, this function divides @var{number} +by each divisor in @var{divisors} in turn, and returns the quotient. +With no @var{divisors}, this function returns 1/@var{number}, i.e., +the multiplicative inverse of @var{number}. Each argument may be a number or a marker. If all the arguments are integers, the result is an integer, obtained by rounding the quotient towards zero after each division. -(Hypothetically, some machines may have different rounding behavior -for negative arguments, because @code{/} is implemented using the C -division operator, which permits machine-dependent rounding; but this -does not happen in practice.) @example @group @@ -647,6 +674,14 @@ does not happen in practice.) @result{} 2.5 @end group @group +(/ 4.0) + @result{} 0.25 +@end group +@group +(/ 4) + @result{} 0 +@end group +@group (/ 25 3 2) @result{} 4 @end group @@ -658,9 +693,9 @@ does not happen in practice.) @cindex @code{arith-error} in division If you divide an integer by the integer 0, Emacs signals an -@code{arith-error} error (@pxref{Errors}). If you divide a floating -point number by 0, or divide by the floating point number 0.0, the -result is either positive or negative infinity (@pxref{Float Basics}). +@code{arith-error} error (@pxref{Errors}). Floating-point division of +a nonzero number by zero yields either positive or negative infinity +(@pxref{Float Basics}). @end defun @defun % dividend divisor @@ -678,8 +713,7 @@ For any two integers @var{dividend} and @var{divisor}, @end example @noindent -always equals @var{dividend}. If @var{divisor} is zero, Emacs signals -an @code{arith-error} error. +always equals @var{dividend} if @var{divisor} is nonzero. @example (% 9 4) @@ -700,7 +734,7 @@ in other words, the remainder after division of @var{dividend} by @var{divisor}, but with the same sign as @var{divisor}. The arguments must be numbers or markers. -Unlike @code{%}, @code{mod} permits floating point arguments; it +Unlike @code{%}, @code{mod} permits floating-point arguments; it rounds the quotient downward (towards minus infinity) to an integer, and uses that quotient to compute the remainder. @@ -741,7 +775,8 @@ For any two numbers @var{dividend} and @var{divisor}, @noindent always equals @var{dividend}, subject to rounding error if either -argument is floating point. For @code{floor}, see @ref{Numeric +argument is floating point and to an @code{arith-error} if @var{dividend} is an +integer and @var{divisor} is 0. For @code{floor}, see @ref{Numeric Conversions}. @end defun @@ -750,30 +785,31 @@ Conversions}. @cindex rounding without conversion The functions @code{ffloor}, @code{fceiling}, @code{fround}, and -@code{ftruncate} take a floating point argument and return a floating -point result whose value is a nearby integer. @code{ffloor} returns the +@code{ftruncate} take a floating-point argument and return a floating-point +result whose value is a nearby integer. @code{ffloor} returns the nearest integer below; @code{fceiling}, the nearest integer above; @code{ftruncate}, the nearest integer in the direction towards zero; @code{fround}, the nearest integer. @defun ffloor float This function rounds @var{float} to the next lower integral value, and -returns that value as a floating point number. +returns that value as a floating-point number. @end defun @defun fceiling float This function rounds @var{float} to the next higher integral value, and -returns that value as a floating point number. +returns that value as a floating-point number. @end defun @defun ftruncate float This function rounds @var{float} towards zero to an integral value, and -returns that value as a floating point number. +returns that value as a floating-point number. @end defun @defun fround float This function rounds @var{float} to the nearest integral value, -and returns that value as a floating point number. +and returns that value as a floating-point number. +Rounding a value equidistant between two integers returns the even integer. @end defun @node Bitwise Operations @@ -785,7 +821,7 @@ and returns that value as a floating point number. sequence of @dfn{bits} (digits which are either zero or one). A bitwise operation acts on the individual bits of such a sequence. For example, @dfn{shifting} moves the whole sequence left or right one or more places, -reproducing the same pattern ``moved over''. +reproducing the same pattern moved over. The bitwise operations in Emacs Lisp apply only to integers. @@ -962,17 +998,16 @@ Here are other examples: @end defun @defun logand &rest ints-or-markers -This function returns the ``logical and'' of the arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in all the arguments. (``Set'' means that the value of the bit is 1 -rather than 0.) +This function returns the bitwise AND of the arguments: the @var{n}th +bit is 1 in the result if, and only if, the @var{n}th bit is 1 in all +the arguments. -For example, using 4-bit binary numbers, the ``logical and'' of 13 and +For example, using 4-bit binary numbers, the bitwise AND of 13 and 12 is 12: 1101 combined with 1100 produces 1100. -In both the binary numbers, the leftmost two bits are set (i.e., they -are 1's), so the leftmost two bits of the returned value are set. -However, for the rightmost two bits, each is zero in at least one of -the arguments, so the rightmost two bits of the returned value are 0's. +In both the binary numbers, the leftmost two bits are both 1 +so the leftmost two bits of the returned value are both 1. +However, for the rightmost two bits, each is 0 in at least one of +the arguments, so the rightmost two bits of the returned value are both 0. @noindent Therefore, @@ -1013,9 +1048,9 @@ because its binary representation consists entirely of ones. If @end defun @defun logior &rest ints-or-markers -This function returns the ``inclusive or'' of its arguments: the @var{n}th bit -is set in the result if, and only if, the @var{n}th bit is set in at least -one of the arguments. If there are no arguments, the result is zero, +This function returns the bitwise inclusive OR of its arguments: the @var{n}th +bit is 1 in the result if, and only if, the @var{n}th bit is 1 in at +least one of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If @code{logior} is passed just one argument, it returns that argument. @@ -1038,9 +1073,9 @@ passed just one argument, it returns that argument. @end defun @defun logxor &rest ints-or-markers -This function returns the ``exclusive or'' of its arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in an odd number of the arguments. If there are no arguments, the +This function returns the bitwise exclusive OR of its arguments: the +@var{n}th bit is 1 in the result if, and only if, the @var{n}th bit is +1 in an odd number of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If @code{logxor} is passed just one argument, it returns that argument. @@ -1063,7 +1098,7 @@ result is 0, which is an identity element for this operation. If @end defun @defun lognot integer -This function returns the logical complement of its argument: the @var{n}th +This function returns the bitwise complement of its argument: the @var{n}th bit is one in the result if, and only if, the @var{n}th bit is zero in @var{integer}, and vice-versa. @@ -1082,7 +1117,7 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @cindex mathematical functions @cindex floating-point functions - These mathematical functions allow integers as well as floating point + These mathematical functions allow integers as well as floating-point numbers as arguments. @defun sin arg @@ -1165,8 +1200,8 @@ non-integer, @code{expt} returns a NaN. @end defun @defun sqrt arg -This returns the square root of @var{arg}. If @var{arg} is negative, -@code{sqrt} returns a NaN. +This returns the square root of @var{arg}. If @var{arg} is finite +and less than zero, @code{sqrt} returns a NaN. @end defun In addition, Emacs defines the following common mathematical @@ -1191,7 +1226,8 @@ fashion. The numbers are not truly random, but they have certain properties that mimic a random series. For example, all possible values occur equally often in a pseudo-random series. - Pseudo-random numbers are generated from a ``seed''. Starting from +@cindex seed, for random number generation + Pseudo-random numbers are generated from a @dfn{seed value}. Starting from any given seed, the @code{random} function always generates the same sequence of numbers. By default, Emacs initializes the random seed at startup, in such a way that the sequence of values of @code{random} @@ -1215,8 +1251,8 @@ any integer representable in Lisp, i.e., an integer between @code{most-negative-fixnum} and @code{most-positive-fixnum} (@pxref{Integer Basics}). -If @var{limit} is @code{t}, it means to choose a new seed based on the -current time of day and on Emacs's process @acronym{ID} number. +If @var{limit} is @code{t}, it means to choose a new seed as if Emacs +were restarting. If @var{limit} is a string, it means to choose a new seed based on the string's contents. diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 61007cc5a12..ec83f0b957a 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Lisp Data Types @@ -18,7 +18,7 @@ possible objects. have similar structures and may usually be used in the same contexts. Types can overlap, and objects can belong to two or more types. Consequently, we can ask whether an object belongs to a particular type, -but not for ``the'' type of an object. +but not for @emph{the} type of an object. @cindex primitive type A few fundamental object types are built into Emacs. These, from @@ -136,7 +136,7 @@ latter are unique to Emacs Lisp. @menu * Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. +* Floating-Point Type:: Numbers with fractional parts and with a large range. * Character Type:: The representation of letters, numbers and control characters. * Symbol Type:: A multi-use object that refers to a function, @@ -156,15 +156,17 @@ latter are unique to Emacs Lisp. * Byte-Code Type:: A function written in Lisp, then compiled. * Autoload Type:: A type used for automatically loading seldom-used functions. +* Finalizer Type:: Runs code when no longer reachable. + @end menu @node Integer Type @subsection Integer Type - The range of values for integers in Emacs Lisp is @minus{}536870912 to -536870911 (30 bits; i.e., + The range of values for an integer depends on the machine. The +minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex --2**29 +@minus{}2**29 @end ifnottex @tex @math{-2^{29}} @@ -176,9 +178,9 @@ to @tex @math{2^{29}-1}) @end tex -on typical 32-bit machines. (Some machines provide a wider range.) -Emacs Lisp arithmetic functions do not check for overflow. Thus -@code{(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 bits. +but many machines provide a wider range. +Emacs Lisp arithmetic functions do not check for integer overflow. Thus +@code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits. The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The @@ -187,7 +189,7 @@ leading @samp{+} or a final @samp{.}. @example @group --1 ; @r{The integer -1.} +-1 ; @r{The integer @minus{}1.} 1 ; @r{The integer 1.} 1. ; @r{Also the integer 1.} +1 ; @r{Also the integer 1.} @@ -197,26 +199,26 @@ leading @samp{+} or a final @samp{.}. @noindent As a special exception, if a sequence of digits specifies an integer too large or too small to be a valid integer object, the Lisp reader -reads it as a floating-point number (@pxref{Floating Point Type}). +reads it as a floating-point number (@pxref{Floating-Point Type}). For instance, if Emacs integers are 30 bits, @code{536870912} is read as the floating-point number @code{536870912.0}. @xref{Numbers}, for more information. -@node Floating Point Type -@subsection Floating Point Type +@node Floating-Point Type +@subsection Floating-Point Type - Floating point numbers are the computer equivalent of scientific -notation; you can think of a floating point number as a fraction + Floating-point numbers are the computer equivalent of scientific +notation; you can think of a floating-point number as a fraction together with a power of ten. The precise number of significant figures and the range of possible exponents is machine-specific; Emacs uses the C data type @code{double} to store the value, and internally this records a power of 2 rather than a power of 10. - The printed representation for floating point numbers requires either + The printed representation for floating-point numbers requires either a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, -@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point +both. For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2}, +@samp{+1500000e-3}, and @samp{.15e4} are five ways of writing a floating-point number whose value is 1500. They are all equivalent. @xref{Numbers}, for more information. @@ -308,7 +310,7 @@ vertical tab, formfeed, space, return, del, and escape as @samp{?\a}, @samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively. (@samp{?\s} followed by a dash has a different meaning---it applies -the ``super'' modifier to the following character.) Thus, +the Super modifier to the following character.) Thus, @example ?\a @result{} 7 ; @r{control-g, @kbd{C-g}} @@ -327,7 +329,7 @@ the ``super'' modifier to the following character.) Thus, @cindex escape sequence These sequences which start with backslash are also known as @dfn{escape sequences}, because backslash plays the role of an -``escape character''; this terminology has nothing to do with the +escape character; this has nothing to do with the character @key{ESC}. @samp{\s} is meant for use in character constants; in string constants, just write the space. @@ -373,13 +375,7 @@ that, Emacs signals an error. codes. A hexadecimal escape sequence consists of a backslash, @samp{x}, and the hexadecimal character code. Thus, @samp{?\x41} is the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and -@code{?\xe0} is the character -@iftex -@samp{@`a}. -@end iftex -@ifnottex -@samp{a} with grave accent. -@end ifnottex +@code{?\xe0} is the character @kbd{à} (@kbd{a} with grave accent). You can use any number of hex digits, so you can represent any character code in this way. @@ -560,7 +556,7 @@ do such a thing. @cindex CL note---case of letters @quotation @b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. In Emacs +folded to upper case, unless they are explicitly escaped. In Emacs Lisp, upper case and lower case letters are distinct. @end quotation @@ -593,8 +589,8 @@ FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} @cindex @samp{##} read syntax @ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu +@c This uses "colon" instead of a literal ':' because Info cannot +@c cope with a ':' in a menu. @cindex @samp{#@var{colon}} read syntax @end ifinfo @ifnotinfo @@ -648,7 +644,7 @@ same object, @code{nil}. A @dfn{cons cell} is an object that consists of two slots, called the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any -Lisp object. We also say that ``the @sc{car} of this cons cell is'' +Lisp object. We also say that the @sc{car} of this cons cell is whatever object its @sc{car} slot currently holds, and likewise for the @sc{cdr}. @@ -664,13 +660,13 @@ of lists, we refer to any structure made out of cons cells as a @quotation A note to C programmers: a Lisp list thus works as a @dfn{linked list} built up of cons cells. Because pointers in Lisp are implicit, we do -not distinguish between a cons cell slot ``holding'' a value versus -``pointing to'' the value. +not distinguish between a cons cell slot holding a value versus +pointing to the value. @end quotation @cindex atoms Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell''. These objects are called +an object which is not a cons cell. These objects are called @dfn{atoms}. @cindex parenthesis @@ -699,10 +695,10 @@ hold @code{nil}. The names @sc{car} and @sc{cdr} derive from the history of Lisp. The original Lisp implementation ran on an @w{IBM 704} computer which -divided words into two parts, called the ``address'' part and the -``decrement''; @sc{car} was an instruction to extract the contents of +divided words into two parts, the address and the +decrement; @sc{car} was an instruction to extract the contents of the address part of a register, and @sc{cdr} an instruction to extract -the contents of the decrement. By contrast, ``cons cells'' are named +the contents of the decrement. By contrast, cons cells are named for the function @code{cons} that creates them, which in turn was named for its purpose, the construction of cells. @@ -741,7 +737,7 @@ represents a reference to a Lisp object, either an atom or another cons cell. In this example, the first box, which holds the @sc{car} of the first -cons cell, refers to or ``holds'' @code{rose} (a symbol). The second +cons cell, refers to or holds @code{rose} (a symbol). The second box, holding the @sc{cdr} of the first cons cell, refers to the next pair of boxes, the second cons cell. The @sc{car} of the second cons cell is @code{violet}, and its @sc{cdr} is the third cons cell. The @@ -997,7 +993,7 @@ of a string returns the same string. The read syntax for a string is a double-quote, an arbitrary number of characters, and another double-quote, @code{"like this"}. To include a double-quote in a string, precede it with a backslash; thus, -@code{"\""} is a string containing just a single double-quote +@code{"\""} is a string containing just one double-quote character. Likewise, you can include a backslash by preceding it with another backslash, like this: @code{"this \\ is a single embedded backslash"}. @@ -1180,7 +1176,7 @@ a whole character set. @cindex @samp{#^} read syntax The printed representation of a char-table is like a vector except that there is an extra @samp{#^} at the beginning.@footnote{You -may also encounter @samp{#^^}, used for ``sub-char-tables''.} +may also encounter @samp{#^^}, used for sub-char-tables.} @xref{Char-Tables}, for special functions to operate on char-tables. Uses of char-tables include: @@ -1208,7 +1204,7 @@ be @code{t} or @code{nil}. The printed representation of a bool-vector is like a string, except that it begins with @samp{#&} followed by the length. The string constant that follows actually specifies the contents of the bool-vector -as a bitmap---each ``character'' in the string contains 8 bits, which +as a bitmap---each character in the string contains 8 bits, which specify the next 8 elements of the bool-vector (1 stands for @code{t}, and 0 for @code{nil}). The least significant bits of the character correspond to the lowest indices in the bool-vector. @@ -1283,8 +1279,8 @@ list whose first element is the symbol @code{macro} and whose @sc{cdr} is a Lisp function object, including the @code{lambda} symbol. Lisp macro objects are usually defined with the built-in -@code{defmacro} function, but any list that begins with @code{macro} is -a macro as far as Emacs is concerned. @xref{Macros}, for an explanation +@code{defmacro} macro, but any list that begins with @code{macro} is a +macro as far as Emacs is concerned. @xref{Macros}, for an explanation of how to write a macro. @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard @@ -1301,7 +1297,7 @@ called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is derived from ``subroutine''.) Most primitive functions evaluate all their arguments when they are called. A primitive function that does not evaluate all its arguments is called a @dfn{special form} -(@pxref{Special Forms}).@refill +(@pxref{Special Forms}). It does not matter to the caller of a function whether the function is primitive. However, this does matter if you try to redefine a primitive @@ -1361,6 +1357,31 @@ in the loaded file. @code{autoload}, which stores the object in the function cell of a symbol. @xref{Autoload}, for more details. +@node Finalizer Type +@subsection Finalizer Type + + A @dfn{finalizer object} helps Lisp code clean up after objects that +are no longer needed. A finalizer holds a Lisp function object. +When a finalizer object becomes unreachable after a garbage collection +pass, Emacs calls the finalizer's associated function object. +When deciding whether a finalizer is reachable, Emacs does not count +references from finalizer objects themselves, allowing you to use +finalizers without having to worry about accidentally capturing +references to finalized objects themselves. + +Errors in finalizers are printed to @code{*Messages*}. Emacs runs +a given finalizer object's associated function exactly once, even +if that function fails. + +@defun make-finalizer function +Make a finalizer that will run @var{function}. @var{function} will be +called after garbage collection when the returned finalizer object +becomes unreachable. If the finalizer object is reachable only +through references from finalizer objects, it does not count as +reachable for the purpose of deciding whether to run @var{function}. +@var{function} will be run once per finalizer object. +@end defun + @node Editing Types @section Editing Types @cindex editing types @@ -1402,7 +1423,7 @@ buffer}. The contents of a buffer are much like a string, but buffers are not used like strings in Emacs Lisp, and the available operations are different. For example, you can insert text efficiently into an -existing buffer, altering the buffer's contents, whereas ``inserting'' +existing buffer, altering the buffer's contents, whereas inserting text into a string requires concatenating substrings, and the result is an entirely new string object. @@ -1481,8 +1502,8 @@ in one window, no window, or several windows. Though many windows may exist simultaneously, at any time one window is designated the @dfn{selected window}. This is the window where the cursor is (usually) displayed when Emacs is ready for a command. The -selected window usually displays the current buffer, but this is not -necessarily the case. +selected window usually displays the current buffer (@pxref{Current +Buffer}), but this is not necessarily the case. Windows are grouped on the screen into frames; each window belongs to one and only one frame. @xref{Frame Type}. @@ -1694,7 +1715,7 @@ look alike but are not the same Lisp object. This shows the difference: @end example You can also use the same syntax to make a circular structure, which -appears as an ``element'' within itself. Here is an example: +appears as an element within itself. Here is an example: @example #1=(a #1#) @@ -1805,9 +1826,6 @@ with references to further information. @item custom-variable-p @xref{Variable Definitions, custom-variable-p}. -@item display-table-p -@xref{Display Tables, display-table-p}. - @item floatp @xref{Predicates on Numbers, floatp}. @@ -1919,12 +1937,12 @@ types. In most cases, it is more convenient to use type predicates than This function returns a symbol naming the primitive type of @var{object}. The value is one of the symbols @code{bool-vector}, @code{buffer}, @code{char-table}, @code{compiled-function}, -@code{condition-variable}, @code{cons}, @code{float}, -@code{font-entity}, @code{font-object}, @code{font-spec}, -@code{frame}, @code{hash-table}, @code{integer}, @code{marker}, -@code{mutex}, @code{overlay}, @code{process}, @code{string}, -@code{subr}, @code{symbol}, @code{thread}, @code{vector}, -@code{window}, or @code{window-configuration}. +@code{condition-variable}, @code{cons}, @code{finalizer}, +@code{float}, @code{font-entity}, @code{font-object}, +@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, +@code{marker}, @code{mutex}, @code{overlay}, @code{process}, +@code{string}, @code{subr}, @code{symbol}, @code{thread}, +@code{vector}, @code{window}, or @code{window-configuration}. @example (type-of 1) @@ -2121,12 +2139,12 @@ that for two strings to be equal, they have the same text properties. @example @group -(equal "asdf" (propertize "asdf" '(asdf t))) +(equal "asdf" (propertize "asdf" 'asdf t)) @result{} t @end group @group (equal-including-properties "asdf" - (propertize "asdf" '(asdf t))) + (propertize "asdf" 'asdf t)) @result{} nil @end group @end example diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 071fcf526da..7050df86a18 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node System Interface @@ -37,6 +37,7 @@ terminal and the screen. * Desktop Notifications:: Desktop notifications. * File Notifications:: File notifications. * Dynamic Libraries:: On-demand loading of support libraries. +* Security Considerations:: Running Emacs in an unfriendly environment. @end menu @node Starting Up @@ -71,11 +72,12 @@ in their turn. The files @file{subdirs.el} are normally generated automatically when Emacs is installed. @item -If the library @file{leim-list.el} exists, Emacs loads it. This -optional library is intended for registering input methods; Emacs -looks for it in @code{load-path} (@pxref{Library Search}), skipping -those directories containing the standard Emacs libraries (since -@file{leim-list.el} should not exist in those directories). +It loads any @file{leim-list.el} that it finds in the @code{load-path} +directories. This file is intended for registering input methods. +The search is only for any personal @file{leim-list.el} files that you +may have created; it skips the directories containing the standard Emacs +libraries (these should contain only a single @file{leim-list.el} file, +which is compiled into the Emacs executable). @vindex before-init-time @item @@ -174,8 +176,8 @@ If the buffer @file{*scratch*} exists and is still in Fundamental mode @item If started on a text terminal, it loads the terminal-specific -Lisp library, which is specified by the variable -@code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done +Lisp library (@pxref{Terminal-Specific}), and runs the hook +@code{tty-setup-hook}. This is not done in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}. @c Now command-line calls command-line-1. @@ -193,9 +195,23 @@ It processes any command-line options that were not handled earlier. It now exits if the option @code{--batch} was specified. @item -If @code{initial-buffer-choice} is a string, it visits the file with -that name. If the @file{*scratch*} buffer exists and is -empty, it inserts @code{initial-scratch-message} into that buffer. +If the @file{*scratch*} buffer exists and is empty, it inserts +@code{(substitute-command-keys initial-scratch-message)} into that buffer. + +@item +If @code{initial-buffer-choice} is a string, it visits the file (or +directory) with that name. If it is a function, it calls the function +with no arguments and selects the buffer that it returns. If one file +is given as a command line argument, that file is visited and its +buffer displayed alongside @code{initial-buffer-choice}. If more than +one file is given, all of the files are visited and the @file{*Buffer +List*} buffer is displayed alongside @code{initial-buffer-choice}. + +@ignore +@c I do not think this should be mentioned. AFAICS it is just a dodge +@c around inhibit-startup-screen not being settable on a site-wide basis. +If it is @code{t}, it selects the @file{*scratch*} buffer. +@end ignore @c To make things nice and confusing, the next three items can be @c called from two places. If displaying a startup screen, they are @@ -207,7 +223,7 @@ empty, it inserts @code{initial-scratch-message} into that buffer. @c daemon/session restore step? @item -It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. +It runs @code{emacs-startup-hook}. @item It calls @code{frame-notice-user-settings}, which modifies the @@ -215,9 +231,12 @@ parameters of the selected frame according to whatever the init files specify. @item -It runs @code{window-setup-hook}. @xref{Window Systems}. +It runs @code{window-setup-hook}. The only difference between this +hook and @code{emacs-startup-hook} is that this one runs after the +previously mentioned modifications to the frame parameters. @item +@cindex startup screen It displays the @dfn{startup screen}, which is a special buffer that contains information about copyleft and basic Emacs usage. This is not done if @code{inhibit-startup-screen} or @code{initial-buffer-choice} @@ -233,8 +252,9 @@ options were specified. @item If the option @code{--daemon} was specified, it calls -@code{server-start} and detaches from the controlling terminal. -@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@code{server-start}, and on Posix systems also detaches from the +controlling terminal. @xref{Emacs Server,,, emacs, The GNU Emacs +Manual}. @item If started by the X session manager, it calls @@ -269,11 +289,9 @@ aliases for this variable. If non-@code{nil}, this variable is a string that specifies a file or directory for Emacs to display after starting up, instead of the startup screen. -@ignore -@c I do not think this should be mentioned. AFAICS it is just a dodge -@c around inhibit-startup-screen not being settable on a site-wide basis. +If its value is a function, Emacs calls that function which must +return a buffer which is then displayed. If its value is @code{t}, Emacs displays the @file{*scratch*} buffer. -@end ignore @end defopt @defopt inhibit-startup-echo-area-message @@ -297,6 +315,7 @@ file will not inhibit the message for someone else. @defopt initial-scratch-message This variable, if non-@code{nil}, should be a string, which is +treated as documentation to be inserted into the @file{*scratch*} buffer when Emacs starts up. If it is @code{nil}, the @file{*scratch*} buffer is empty. @end defopt @@ -316,7 +335,7 @@ Run without an interactive terminal. @xref{Batch Mode}. Do not initialize any display; just start a server in the background. @item --no-init-file -@itemx -Q +@itemx -q Do not load either the init file, or the @file{default} library. @item --no-site-file @@ -406,8 +425,13 @@ terminal) and processing the command-line action arguments. @defvar emacs-startup-hook This normal hook is run, once, just after handling the command line -arguments, just before @code{term-setup-hook}. In batch mode, Emacs -does not run either of these hooks. +arguments. In batch mode, Emacs does not run this hook. +@end defvar + +@defvar window-setup-hook +This normal hook is very similar to @code{emacs-startup-hook}. +The only difference is that it runs slightly later, after setting +of the frame parameters. @xref{Startup Summary, window-setup-hook}. @end defvar @defvar user-init-file @@ -429,21 +453,24 @@ This variable holds the name of the @file{.emacs.d} directory. It is run on that type of terminal. The library's name is constructed by concatenating the value of the variable @code{term-file-prefix} and the terminal type (specified by the environment variable @env{TERM}). -Normally, @code{term-file-prefix} has the value -@code{"term/"}; changing this is not recommended. Emacs finds the file -in the normal manner, by searching the @code{load-path} directories, and -trying the @samp{.elc} and @samp{.el} suffixes. +Normally, @code{term-file-prefix} has the value @code{"term/"}; +changing this is not recommended. If there is an entry matching +@env{TERM} in the @code{term-file-aliases} association list, +Emacs uses the associated value in place of @env{TERM}. +Emacs finds the file in the normal manner, by searching the +@code{load-path} directories, and trying the @samp{.elc} and +@samp{.el} suffixes. @cindex Termcap The usual role of a terminal-specific library is to enable special keys to send sequences that Emacs can recognize. It may also need to set or add to @code{input-decode-map} if the Termcap or Terminfo entry -does not specify all the terminal's function keys. @xref{Terminal -Input}. +does not specify all the terminal's function keys. @xref{Terminal Input}. - When the name of the terminal type contains a hyphen or underscore, and no library -is found whose name is identical to the terminal's name, Emacs strips -from the terminal's name the last hyphen or underscore and everything that follows + When the name of the terminal type contains a hyphen or underscore, +and no library is found whose name is identical to the terminal's +name, Emacs strips from the terminal's name the last hyphen or +underscore and everything that follows it, and tries again. This process is repeated until Emacs finds a matching library, or until there are no more hyphens or underscores in the name (i.e., there is no terminal-specific library). For example, if the @@ -452,20 +479,16 @@ terminal name is @samp{xterm-256color} and there is no @file{term/xterm.el}. If necessary, the terminal library can evaluate @code{(getenv "TERM")} to find the full name of the terminal type. - Your init file can prevent the loading of the -terminal-specific library by setting the variable -@code{term-file-prefix} to @code{nil}. This feature is useful when -experimenting with your own peculiar customizations. + Your init file can prevent the loading of the terminal-specific +library by setting the variable @code{term-file-prefix} to @code{nil}. You can also arrange to override some of the actions of the -terminal-specific library by setting the variable -@code{term-setup-hook}. This is a normal hook that Emacs runs -at the end of its initialization, after loading both -your init file and any terminal-specific libraries. You could -use this hook to define initializations for terminals that do not +terminal-specific library by using @code{tty-setup-hook}. This is +a normal hook that Emacs runs after initializing a new text terminal. +You could use this hook to define initializations for terminals that do not have their own libraries. @xref{Hooks}. -@defvar term-file-prefix +@defopt term-file-prefix @cindex @env{TERM} environment variable If the value of this variable is non-@code{nil}, Emacs loads a terminal-specific initialization file as follows: @@ -480,17 +503,24 @@ init file if you do not wish to load the terminal-initialization file. On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}. -@end defvar +@end defopt -@defvar term-setup-hook -This variable is a normal hook that Emacs runs after loading your -init file, the default initialization file (if any) and the -terminal-specific Lisp file. +@defopt term-file-aliases +This variable is an an association list mapping terminal types to +their aliases. For example, an element of the form @code{("vt102" +. "vt100")} means to treat a terminal of type @samp{vt102} like one of +type @samp{vt100}. +@end defopt -You can use @code{term-setup-hook} to override the definitions made by a -terminal-specific file. +@defvar tty-setup-hook +This variable is a normal hook that Emacs runs after initializing a +new text terminal. (This applies when Emacs starts up in non-windowed +mode, and when making a tty @command{emacsclient} connection.) The +hook runs after loading your init file (if applicable) and the +terminal-specific Lisp file, so you can use it to adjust the +definitions made by that file. -For a related feature, @pxref{Window Systems, window-setup-hook}. +For a related feature, @pxref{Init File, window-setup-hook}. @end defvar @node Command-Line Arguments @@ -516,9 +546,10 @@ displays the startup messages. The value of this variable is @code{t} once the command line has been processed. -If you redump Emacs by calling @code{dump-emacs}, you may wish to set -this variable to @code{nil} first in order to cause the new dumped Emacs -to process its new command-line arguments. +If you redump Emacs by calling @code{dump-emacs} (@pxref{Building +Emacs}), you may wish to set this variable to @code{nil} first in +order to cause the new dumped Emacs to process its new command-line +arguments. @end defvar @defvar command-switch-alist @@ -550,8 +581,8 @@ sole argument. In some cases, the option is followed in the command line by an argument. In these cases, the @var{handler-function} can find all the remaining command-line arguments in the variable -@code{command-line-args-left}. (The entire list of command-line -arguments is in @code{command-line-args}.) +@code{command-line-args-left} (see below). (The entire list of +command-line arguments is in @code{command-line-args}.) The command-line arguments are parsed by the @code{command-line-1} function in the @file{startup.el} file. See also @ref{Emacs @@ -695,7 +726,7 @@ another application without doing anything special to Emacs. @c have SIGTSTP? @cindex SIGTSTP Some operating systems (those without @code{SIGTSTP}, or MS-DOS) do -not support suspension of jobs; on these systems, ``suspension'' +not support suspension of jobs; on these systems, suspension actually creates a new shell temporarily as a subprocess of Emacs. Then you would exit the shell to return to Emacs. @@ -737,7 +768,7 @@ Here is an example of how you could use these hooks: (add-hook 'suspend-resume-hook (lambda () (message "Resumed!") (sit-for 2))) @end smallexample -@c The sit-for prevents the ``nil'' that suspend-emacs returns +@c The sit-for prevents the @code{nil} that suspend-emacs returns @c hiding the message. Here is what you would see upon evaluating @code{(suspend-emacs "pwd")}: @@ -896,13 +927,6 @@ This function returns the name of the machine you are running on, as a string. @end defun - The symbol @code{system-name} is a variable as well as a function. In -fact, the function returns whatever value the variable -@code{system-name} currently holds. Thus, you can set the variable -@code{system-name} in case Emacs is confused about the name of your -system. The variable is also useful for constructing frame titles -(@pxref{Frame Titles}). - @c FIXME seems like this section is not the best place for this option? @defopt mail-host-address If this variable is non-@code{nil}, it is used instead of @@ -959,6 +983,7 @@ to access the value of @var{variable}. If @var{value} is omitted or removes @var{variable} from the environment. Otherwise, @var{value} should be a string. +@c FIXME: Document 'substitute-env-vars'? --xfq If the optional argument @var{substitute} is non-@code{nil}, Emacs calls the function @code{substitute-env-vars} to expand any environment variables in @var{value}. @@ -989,9 +1014,9 @@ process-environment @end group @end smallexample -If @code{process-environment} contains ``duplicate'' elements that +If @code{process-environment} contains multiple elements that specify the same environment variable, the first of these elements -specifies the variable, and the other ``duplicates'' are ignored. +specifies the variable, and the others are ignored. @end defvar @defvar initial-environment @@ -1044,7 +1069,7 @@ number of processes trying to run on the system. By default, the values are integers that are 100 times the system load averages, but if @var{use-float} is non-@code{nil}, then they are -returned as floating point numbers without multiplying by 100. +returned as floating-point numbers without multiplying by 100. If it is impossible to obtain the load average, this function signals an error. On some platforms, access to load averages requires @@ -1095,9 +1120,9 @@ originally logged in. The value reflects command-line options such as Lisp packages that load files of customizations, or any other sort of user profile, should obey this variable in deciding where to find it. They should load the profile of the user name found in this variable. -If @code{init-file-user} is @code{nil}, meaning that the @samp{-q} -option was used, then Lisp packages should not load any customization -files or user profile. +If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}, +@samp{-Q}, or @samp{-batch} option was used, then Lisp packages should +not load any customization files or user profile. @end defvar @defopt user-mail-address @@ -1143,29 +1168,31 @@ user-id or login name that isn't defined, it returns @code{nil}. The symbols @code{user-login-name}, @code{user-real-login-name} and @code{user-full-name} are variables as well as functions. The functions return the same values that the variables hold. These variables allow -you to ``fake out'' Emacs by telling the functions what to return. The +you to fake out Emacs by telling the functions what to return. The variables are also useful for constructing frame titles (@pxref{Frame Titles}). +@cindex UID @defun user-real-uid This function returns the real @acronym{UID} of the user. -The value may be a floating point number, in the (unlikely) event that +The value may be floating point, in the (unlikely) event that the UID is too large to fit in a Lisp integer. @end defun @defun user-uid This function returns the effective @acronym{UID} of the user. -The value may be a floating point number. +The value may be floating point. @end defun +@cindex GID @defun group-gid This function returns the effective @acronym{GID} of the Emacs process. -The value may be a floating point number. +The value may be floating point. @end defun @defun group-real-gid This function returns the real @acronym{GID} of the Emacs process. -The value may be a floating point number. +The value may be floating point. @end defun @defun system-users @@ -1184,44 +1211,42 @@ return value is @code{nil}. @node Time of Day @section Time of Day +@cindex time of day This section explains how to determine the current time and time zone. @cindex epoch - Most of these functions represent time as a list of either four -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, or of three -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of -two integers, @code{(@var{sec-high} @var{sec-low})}. The integers -@var{sec-high} and @var{sec-low} give the high and low bits of an -integer number of seconds. This integer number, + Most of these functions represent time as a list of four integers +@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. +This represents the number of seconds from the @dfn{epoch} (January +1, 1970 at 00:00 UTC), using the formula: @ifnottex -@var{high} * 2**16 + @var{low}, +@var{high} * 2**16 + @var{low} + @var{micro} * 10**@minus{}6 + +@var{pico} * 10**@minus{}12. @end ifnottex @tex -$high*2^{16}+low$, +$high*2^{16} + low + micro*10^{-6} + pico*10^{-12}$. @end tex -is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970 -UTC) to the specified time. The third list element @var{microsec}, if -present, gives the number of microseconds from the start of that -second to the specified time. -Similarly, the fourth list element @var{picosec}, if present, gives -the number of picoseconds from the start of that microsecond to the -specified time. - - The return value of @code{current-time} represents time using four -integers, as do the timestamps in the return value of -@code{file-attributes} (@pxref{Definition of -file-attributes}). In function arguments, e.g., the @var{time-value} -argument to @code{current-time-string}, two-, three-, and four-integer -lists are accepted. You can convert times from the list -representation into standard human-readable strings using -@code{current-time}, or to other forms using the @code{decode-time} -and @code{format-time-string} functions documented in the following -sections. - -@defun current-time-string &optional time-value +The return value of @code{current-time} represents time using this +form, as do the timestamps in the return values of other functions +such as @code{file-attributes} (@pxref{Definition of +file-attributes}). In some cases, functions may return two- or +three-element lists, with omitted @var{microsec} and @var{picosec} +components defaulting to zero. + +@cindex time value + Function arguments, e.g., the @var{time} argument to +@code{current-time-string}, accept a more-general @dfn{time value} +format, which can be a list of integers as above, or a single number +for seconds since the epoch, or @code{nil} for the current time. You +can convert a time value into a human-readable string using +@code{current-time-string} and @code{format-time-string}, into a list +of integers using @code{seconds-to-time}, and into other forms using +@code{decode-time} and @code{float-time}. These functions are +described in the following sections. + +@defun current-time-string &optional time zone This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day @@ -1232,8 +1257,9 @@ characters from the beginning of the string rather than from the end, as the year might not have exactly four digits, and additional information may some day be added at the end. -The argument @var{time-value}, if given, specifies a time to format -(represented as a list of integers), instead of the current time. +The argument @var{time}, if given, specifies a time to format, +instead of the current time. The optional argument @var{zone} +defaults to the current time zone rule. @example @group @@ -1252,17 +1278,26 @@ multiple of 1000, but this may change as higher-resolution clocks become available. @end defun -@defun float-time &optional time-value +@defun float-time &optional time This function returns the current time as a floating-point number of -seconds since the epoch. The optional argument @var{time-value}, if -given, specifies a time (represented as a list of integers) to convert -instead of the current time. +seconds since the epoch. The optional argument @var{time}, if +given, specifies a time to convert instead of the current time. @emph{Warning}: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required. + +@code{time-to-seconds} is an alias for this function. @end defun -@defun current-time-zone &optional time-value +@defun seconds-to-time time +This function converts a time value to list-of-integer form. +For example, if @var{time} is a number, @code{(time-to-seconds +(seconds-to-time @var{time}))} equals the number unless overflow +or rounding errors occur. +@end defun + +@defun current-time-zone &optional time zone +@cindex time zone, current This function returns a list describing the time zone that the user is in. @@ -1277,28 +1312,42 @@ adjustment, then the value is constant through time. If the operating system doesn't supply all the information necessary to compute the value, the unknown elements of the list are @code{nil}. -The argument @var{time-value}, if given, specifies a time (represented -as a list of integers) to analyze instead of the current time. +The argument @var{time}, if given, specifies a time value to +analyze instead of the current time. The optional argument @var{zone} +defaults to the current time zone rule. @end defun -The current time zone is determined by the @env{TZ} environment +@vindex TZ, environment variable +The default time zone is determined by the @env{TZ} environment variable. @xref{System Environment}. For example, you can tell Emacs -to use universal time with @code{(setenv "TZ" "UTC0")}. If @env{TZ} -is not in the environment, Emacs uses a platform-dependent default -time zone. +to default to universal time with @code{(setenv "TZ" "UTC0")}. If +@env{TZ} is not in the environment, Emacs uses system wall clock time, +which is a platform-dependent default time zone. + +@cindex time zone rule +Functions that convert to and from local time accept an optional +@dfn{time zone rule} argument, which specifies the conversion's time +zone and daylight saving time history. If the time zone rule is +omitted or @code{nil}, the conversion uses Emacs's default time zone. +If it is @code{t}, the conversion uses Universal Time. If it is +@code{wall}, the conversion uses the system wall clock time. If it is +a string, the conversion uses the time zone rule equivalent to setting +@env{TZ} to that string. @node Time Conversion @section Time Conversion +@cindex calendrical information +@cindex time conversion - These functions convert time values (lists of two to four integers, -as explained in the previous section) into calendrical information and -vice versa. + These functions convert time values (@pxref{Time of Day}) into +calendrical information and vice versa. - Many 32-bit operating systems are limited to time values containing -32 bits of information; these systems typically handle only the times -from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC@. -However, 64-bit and some 32-bit operating systems have larger time -values, and can represent times far in the past or future. + Many 32-bit operating systems are limited to system times containing +32 bits of information in their seconds component; these systems +typically handle only the times from 1901-12-13 20:45:52 UTC through +2038-01-19 03:14:07 UTC@. However, 64-bit and some 32-bit operating +systems have larger seconds components, and can represent times far in +the past or future. Time conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers @@ -1306,13 +1355,14 @@ count the number of years since the year 1 B.C., and do not skip zero as traditional Gregorian years do; for example, the year number @minus{}37 represents the Gregorian year 38 B.C@. -@defun decode-time &optional time +@defun decode-time &optional time zone This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return +you don't specify @var{time}, it decodes the current time, and similarly +@var{zone} defaults to the current time zone rule. The return value is a list of nine elements, as follows: @example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) +(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{utcoff}) @end example Here is what the elements mean: @@ -1336,30 +1386,30 @@ The day of week, as an integer between 0 and 6, where 0 stands for Sunday. @item dst @code{t} if daylight saving time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. +@item utcoff +An integer indicating the UTC offset in seconds, i.e., the number of +seconds east of Greenwich. @end table @strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. +@var{dow} and @var{utcoff}. @end defun @defun encode-time seconds minutes hour day month year &optional zone This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. +items of calendrical data into a list-of-integer time value. For the +meanings of the arguments, see the table above under +@code{decode-time}. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. -The optional argument @var{zone} defaults to the current time zone and -its daylight saving time rules. If specified, it can be either a list -(as you would get from @code{current-time-zone}), a string as in the -@env{TZ} environment variable, @code{t} for Universal Time, or an -integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight saving time. +The optional argument @var{zone} defaults to the current time zone rule. +In addition to the usual time zone rule values, it can also be a list +(as you would get from @code{current-time-zone}) or an integer (as +from @code{decode-time}), applied without any further alteration for +daylight saving time. If you pass more than seven arguments to @code{encode-time}, the first six are used as @var{seconds} through @var{year}, the last argument is @@ -1383,6 +1433,9 @@ on others, years as early as 1901 do work. @node Time Parsing @section Parsing and Formatting Times +@cindex time parsing +@cindex time formatting +@cindex formatting time values These functions convert time values to text in a string, and vice versa. Time values are lists of two to four integers (@pxref{Time of Day}). @@ -1392,9 +1445,12 @@ This function parses the time-string @var{string} and returns the corresponding time value. @end defun -@defun format-time-string format-string &optional time universal -This function converts @var{time} (or the current time, if @var{time} is -omitted) to a string according to @var{format-string}. The argument +@defun format-time-string format-string &optional time zone + +This function converts @var{time} (or the current time, if +@var{time} is omitted) to a string according to +@var{format-string}. The conversion uses the time zone rule @var{zone} +(or the current time zone rule, if omitted). The argument @var{format-string} may contain @samp{%}-sequences which say to substitute parts of the time. Here is a table of what the @samp{%}-sequences mean: @@ -1490,13 +1546,13 @@ because that is how @samp{%S} normally pads to two positions. The characters @samp{E} and @samp{O} act as modifiers when used between @samp{%} and one of the letters in the table above. @samp{E} specifies -using the current locale's ``alternative'' version of the date and time. +using the current locale's alternative version of the date and time. In a Japanese locale, for example, @code{%Ex} might yield a date format based on the Japanese Emperors' reigns. @samp{E} is allowed in @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and @samp{%EY}. -@samp{O} means to use the current locale's ``alternative'' +@samp{O} means to use the current locale's alternative representation of numbers, instead of the ordinary decimal digits. This is allowed with most letters, all the ones that output numbers. @@ -1514,12 +1570,6 @@ specified by @code{locale-coding-system} (@pxref{Locales}); after system. @end defun -@defun seconds-to-time seconds -This function converts @var{seconds}, a floating point number of -seconds since the epoch, to a time value and returns that. To perform -the inverse conversion, use @code{float-time}. -@end defun - @defun format-seconds format-string seconds This function converts its argument @var{seconds} into a string of years, days, hours, etc., according to @var{format-string}. The @@ -1579,6 +1629,7 @@ most-positive-fixnum}). both elapsed and processor time, used by the Emacs process. @deffn Command emacs-uptime &optional format +@cindex uptime of Emacs This function returns a string representing the Emacs @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is running. The string is formatted by @code{format-seconds} according @@ -1592,7 +1643,7 @@ When called interactively, it prints the uptime in the echo area. @defun get-internal-run-time This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{high} @var{low} @var{microsec} +of four integers: @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}, using the same format as @code{current-time} (@pxref{Time of Day}). @@ -1614,9 +1665,12 @@ interactively, it prints the duration in the echo area. @node Time Calculations @section Time Calculations +@cindex time calculations +@cindex comparing time values +@cindex calendrical computations These functions perform calendrical computations using time values -(the kind of list that @code{current-time} returns). +(@pxref{Time of Day}). @defun time-less-p t1 t2 This returns @code{t} if time value @var{t1} is less than time value @@ -1625,26 +1679,26 @@ This returns @code{t} if time value @var{t1} is less than time value @defun time-subtract t1 t2 This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, in the same format as a time value. +two time values, as a time value. @end defun @defun time-add t1 t2 -This returns the sum of two time values, one of which ought to -represent a time difference rather than a point in time. +This returns the sum of two time values, as a time value. +One argument should represent a time difference rather than a point in time. Here is how to add a number of seconds to a time value: @example -(time-add @var{time} (seconds-to-time @var{seconds})) +(time-add @var{time} @var{seconds}) @end example @end defun -@defun time-to-days time +@defun time-to-days time-value This function returns the number of days between the beginning of year -1 and @var{time}. +1 and @var{time-value}. @end defun -@defun time-to-day-in-year time -This returns the day number within the year corresponding to @var{time}. +@defun time-to-day-in-year time-value +This returns the day number within the year corresponding to @var{time-value}. @end defun @defun date-leap-year-p year @@ -1794,6 +1848,7 @@ cause anything special to happen. @node Idle Timers @section Idle Timers +@cindex idle timers Here is how to set up a timer that runs when Emacs is idle for a certain length of time. Aside from how to set them up, idle timers @@ -1801,9 +1856,8 @@ work just like ordinary timers. @deffn Command run-with-idle-timer secs repeat function &rest args Set up a timer which runs the next time Emacs is idle for @var{secs} -seconds. The value of @var{secs} may be an integer or a floating -point number; a value of the type returned by @code{current-idle-time} -is also allowed. +seconds. The value of @var{secs} may be a number or a value of the type +returned by @code{current-idle-time}. If @var{repeat} is @code{nil}, the timer runs just once, the first time Emacs remains idle for a long enough time. More often @var{repeat} is @@ -1889,8 +1943,7 @@ idleness. Here's an example: (run-with-idle-timer ;; Compute an idle time @var{break-length} ;; more than the current value. - (time-add (current-idle-time) - (seconds-to-time @var{break-length})) + (time-add (current-idle-time) @var{break-length}) nil 'my-timer-function)))) @end example @@ -1915,10 +1968,10 @@ functions. @defun set-input-mode interrupt flow meta &optional quit-char This function sets the mode for reading keyboard input. If -@var{interrupt} is non-null, then Emacs uses input interrupts. If it is -@code{nil}, then it uses @sc{cbreak} mode. The default setting is -system-dependent. Some systems always use @sc{cbreak} mode regardless -of what is specified. +@var{interrupt} is non-@code{nil}, then Emacs uses input interrupts. +If it is @code{nil}, then it uses @sc{cbreak} mode. The default +setting is system-dependent. Some systems always use @sc{cbreak} mode +regardless of what is specified. When Emacs communicates directly with X, it ignores this argument and uses interrupts if that is the way it knows how to communicate. @@ -1988,20 +2041,11 @@ This function opens a @dfn{dribble file} named @var{filename}. When a dribble file is open, each input event from the keyboard or mouse (but not those from keyboard macros) is written in that file. A non-character event is expressed using its printed representation -surrounded by @samp{<@dots{}>}. +surrounded by @samp{<@dots{}>}. Be aware that sensitive information +(such as passwords) may end up recorded in the dribble file. You close the dribble file by calling this function with an argument of @code{nil}. - -This function is normally used to record the input necessary to -trigger an Emacs bug, for the sake of a bug report. - -@example -@group -(open-dribble-file "~/dribble") - @result{} nil -@end group -@end example @end deffn See also the @code{open-termscript} function (@pxref{Terminal Output}). @@ -2068,17 +2112,17 @@ often than to actual Emacs bugs. Once you are certain which characters were actually output, you can determine reliably whether they correspond to the Termcap specifications in use. -You close the termscript file by calling this function with an -argument of @code{nil}. - -See also @code{open-dribble-file} in @ref{Recording Input}. - @example @group (open-termscript "../junk/termscript") @result{} nil @end group @end example + +You close the termscript file by calling this function with an +argument of @code{nil}. + +See also @code{open-dribble-file} in @ref{Recording Input}. @end deffn @node Sound Output @@ -2089,6 +2133,7 @@ See also @code{open-dribble-file} in @ref{Recording Input}. certain systems are supported; if you call @code{play-sound} on a system which cannot really do the job, it gives an error. +@c FIXME: Add indexes for Au and WAV? --xfq The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) or Sun Audio format (@samp{.au}). @@ -2148,9 +2193,9 @@ To define system-specific X11 keysyms, set the variable This variable's value should be an alist with one element for each system-specific keysym. Each element has the form @code{(@var{code} . @var{symbol})}, where @var{code} is the numeric keysym code (not -including the ``vendor specific'' bit, +including the vendor-specific bit, @ifnottex --2**28), +@minus{}2**28), @end ifnottex @tex $-2^{28}$), @@ -2160,7 +2205,7 @@ and @var{symbol} is the name for the function key. For example @code{(168 . mute-acute)} defines a system-specific key (used by HP X servers) whose numeric code is @ifnottex --2**28 +@minus{}2**28 @end ifnottex @tex $-2^{28}$ @@ -2235,6 +2280,7 @@ saved session to restore. For Emacs, this argument is @samp{--smid @var{session}}. @defvar emacs-save-session-functions +@cindex session file Emacs supports saving state via a hook called @code{emacs-save-session-functions}. Emacs runs this hook when the session manager tells it that the window system is shutting down. The @@ -2274,11 +2320,13 @@ Emacs is restarted by the session manager. @node Desktop Notifications @section Desktop Notifications @cindex desktop notifications +@cindex notifications, on desktop Emacs is able to send @dfn{notifications} on systems that support the freedesktop.org Desktop Notifications Specification. In order to use this functionality, Emacs must have been compiled with D-Bus support, -and the @code{notifications} library must be loaded. +and the @code{notifications} library must be loaded. @xref{Top, , +D-Bus,dbus,D-Bus integration in Emacs}. @defun notifications-notify &rest params This function sends a notification to the desktop via D-Bus, @@ -2321,10 +2369,10 @@ be anything, though implementations are free not to display it. @item :timeout @var{timeout} The timeout time in milliseconds since the display of the notification -at which the notification should automatically close. If -1, the +at which the notification should automatically close. If @minus{}1, the notification's expiration time is dependent on the notification server's settings, and may vary for the type of notification. If 0, -the notification never expires. Default value is -1. +the notification never expires. Default value is @minus{}1. @item :urgency @var{urgency} The urgency level. It can be @code{low}, @code{normal}, or @code{critical}. @@ -2359,7 +2407,7 @@ The path to a sound file to play when the notification pops up. @item :sound-name @var{name} A themable named sound from the freedesktop.org sound naming specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the -notification pops up. Similar to the icon name, only for sounds. An +notification pops up. Similar to the icon name, only for sounds. An example would be @samp{"message-new-instant"}. @item :suppress-sound @@ -2368,9 +2416,9 @@ ability. @item :resident When set the server will not automatically remove the notification -when an action has been invoked. The notification will remain resident +when an action has been invoked. The notification will remain resident in the server until it is explicitly removed by the user or by the -sender. This hint is likely only useful when the server has the +sender. This hint is likely only useful when the server has the @code{:persistence} capability. @item :transient @@ -2433,7 +2481,7 @@ argument of another @code{notifications-notify} call. For example: @end group @group -A message window opens on the desktop. Press "I agree" +A message window opens on the desktop. Press ``I agree''. @result{} Message 22, key "Confirm" pressed Message 22, closed due to "dismissed" @end group @@ -2507,17 +2555,18 @@ The server's version number. The specification version the server is compliant with. @end table -If @var{SPEC_VERSION} is @code{nil}, the server supports a +If @var{spec_version} is @code{nil}, the server supports a specification prior to @samp{"1.0"}. @end defun @node File Notifications @section Notifications on File Changes @cindex file notifications +@cindex watch, for filesystem events Several operating systems support watching of filesystems for changes of files. If configured properly, Emacs links a respective library -like @file{gfilenotify}, @file{inotify}, or @file{w32notify} +like @file{gfilenotify}, @file{inotify}, or @file{w32notify} statically. These libraries enable watching of filesystems on the local machine. @@ -2577,13 +2626,26 @@ any one of the following symbols: @item deleted @var{file} was deleted @item changed -@var{file} has changed +@var{file}'s contents has changed; with @file{w32notify} library, +reports attribute changes as well @item renamed @var{file} has been renamed to @var{file1} @item attribute-changed a @var{file} attribute was changed +@item stopped +watching @var{file} has been stopped @end table +Note that the @file{w32notify} library does not report +@code{attribute-changed} events. When some file's attribute, like +permissions or modification time, has changed, this library reports a +@code{changed} event. + +The @code{stopped} event reports, that watching the file has been +stopped. This could be because @code{file-notify-rm-watch} was called +(see below), or because the file being watched was deleted, or due to +another error reported from the underlying library. + @var{file} and @var{file1} are the name of the file(s) whose event is being reported. For example: @@ -2627,10 +2689,8 @@ being reported. For example: @end example Whether the action @code{renamed} is returned, depends on the used -watch library. It can be expected, when a directory is watched, and -both @var{file} and @var{file1} belong to this directory. Otherwise, -the actions @code{deleted} and @code{created} could be returned in a -random order. +watch library. Otherwise, the actions @code{deleted} and +@code{created} could be returned in a random order. @example @group @@ -2639,19 +2699,8 @@ random order. @end group @group -(file-notify-add-watch - "/var/tmp" '(change attribute-change) 'my-notify-callback) - @result{} 35025504 -@end group - -@group -(rename-file "/tmp/bla" "/var/tmp/bla") - @result{} ;; gfilenotify - Event (35025468 renamed "/tmp/bla" "/var/tmp/bla") - - @result{} ;; inotify - Event (35025504 created "/var/tmp/bla") - Event (35025468 deleted "/tmp/bla") +(delete-file "/tmp/bla") + @result{} Event (35025468 deleted "/tmp/bla") @end group @end example @end defun @@ -2662,6 +2711,71 @@ Removes an existing file watch specified by its @var{descriptor}. @code{file-notify-add-watch}. @end defun +@defun file-notify-valid-p descriptor +Checks a watch specified by its @var{descriptor} for validity. +@var{descriptor} should be an object returned by +@code{file-notify-add-watch}. + +A watch can become invalid if the file or directory it watches is +deleted, or if the watcher thread exits abnormally for any other +reason. Removing the watch by calling @code{file-notify-rm-watch} +also makes it invalid. + +@example +@group +(make-directory "/tmp/foo") + @result{} nil +@end group + +@group +(setq desc + (file-notify-add-watch + "/tmp/foo" '(change) 'my-notify-callback)) + @result{} 35025468 +@end group + +@group +(file-notify-valid-p desc) + @result{} t +@end group + +@group +(write-region "bla" nil "/tmp/foo/bla") + @result{} Event (35025468 created "/tmp/foo/.#bla") + Event (35025468 created "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/.#bla") +@end group + +@group +;; Deleting a file in the directory doesn't invalidate the watch. +(delete-file "/tmp/foo/bla") + @result{} Event (35025468 deleted "/tmp/foo/bla") +@end group + +@group +(write-region "bla" nil "/tmp/foo/bla") + @result{} Event (35025468 created "/tmp/foo/.#bla") + Event (35025468 created "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/bla") + Event (35025468 changed "/tmp/foo/.#bla") +@end group + +@group +;; Deleting the directory invalidates the watch. +(delete-directory "/tmp/foo" 'recursive) + @result{} Event (35025468 deleted "/tmp/foo/bla") + Event (35025468 deleted "/tmp/foo") + Event (35025468 stopped "/tmp/foo") +@end group + +@group +(file-notify-valid-p desc) + @result{} nil +@end group +@end example +@end defun + @node Dynamic Libraries @section Dynamically Loaded Libraries @cindex dynamic libraries @@ -2713,3 +2827,106 @@ be loaded through it. This variable is ignored if the given @var{library} is statically linked into Emacs. @end defvar + +@node Security Considerations +@section Security Considerations +@cindex security +@cindex hardening + +Like any application, Emacs can be run in a secure environment, where +the operating system enforces rules about access and the like. With +some care, Emacs-based applications can also be part of a security +perimeter that checks such rules. Although the default settings for +Emacs work well for a typical software development environment, they +may require adjustment in environments containing untrusted users that +may include attackers. Here is a compendium of security issues that +may be helpful if you are developing such applications. It is by no +means complete; it is intended to give you an idea of the security +issues involved, rather than to be a security checklist. + +@table @asis +@item Access control +Although Emacs normally respects access permissions of the underlying +operating system, in some cases it handles accesses specially. For +example, file names can have handlers that treat the files specially, +with their own access checking. @xref{Magic File Names}. Also, a +buffer can be read-only even if the corresponding file is writeable, +and vice versa, which can result in messages such as @samp{File passwd +is write-protected; try to save anyway? (yes or no)}. @xref{Read Only +Buffers}. + +@item Authentication +Emacs has several functions that deal with passwords, e.g., +@code{password-read}. Although these functions do not attempt to +broadcast passwords to the world, their implementations are not proof +against determined attackers with access to Emacs internals. For +example, even if Elisp code attempts to scrub a password from +its memory after using it, remnants of the password may still reside +in the garbage-collected free list. + +@item Code injection +Emacs can send commands to many other applications, and applications +should take care that strings sent as operands of these commands are +not misinterpreted as directives. For example, when sending a shell +command to rename a file @var{a} to @var{b}, do not simply use the +string @code{mv @var{a} @var{b}}, because either file name might start +with @samp{-}, or might contain shell metacharacters like @samp{;}. +Although functions like @code{shell-quote-argument} can help avoid +this sort of problem, they are not panaceas; for example, on a POSIX +platform @code{shell-quote-argument} quotes shell metacharacters but +not leading @samp{-}. @xref{Shell Arguments}. + +@item Coding systems +Emacs attempts to infer the coding systems of the files and network +connections it accesses. If it makes a mistake, or if the other +parties to the network connection disagree with Emacs's deductions, +the resulting system could be unreliable. Also, even when it infers +correctly, Emacs often can use bytes that other programs cannot. For +example, although to Emacs the NUL (all bits zero) byte is just a +character like any other, many other applications treat it as a string +terminator and mishandle strings or files containing NUL bytes. + +@item Environment and configuration variables +POSIX specifies several environment variables that can affect how +Emacs behaves. Any environment variable whose name consists entirely +of uppercase ASCII letters, digits, and the underscore may affect the +internal behavior of Emacs. Emacs uses several such variables, e.g., +@env{EMACSLOADPATH}. @xref{Library Search}. On some platforms some +environment variables (e.g., @env{PATH}, @env{POSIXLY_CORRECT}, +@env{SHELL}, @env{TMPDIR}) need to have properly-configured values in +order to get standard behavior for any utility Emacs might invoke. +Even seemingly-benign variables like @env{TZ} may have security +implications. + +Emacs has customization and other variables with similar +considerations. For example, if the variable @code{shell-file-name} +specifies a shell with nonstandard behavior, an Emacs-based +application may misbehave. + +@item Installation +When Emacs is installed, if the installation directory hierarchy can +be modified by untrusted users, the application cannot be trusted. +This applies also to the directory hierarchies of the programs that +Emacs uses, and of the files that Emacs reads and writes. + +@item Network access +Emacs often accesses the network, and you may want to configure it to +avoid network accesses that it would normally do. For example, unless +you set @code{tramp-mode} to @code{nil}, file names using a certain +syntax are interpreted as being network files, and are retrieved +across the network. @xref{Top, The Tramp Manual,, tramp, The Tramp +Manual}. + +@item Race conditions +Emacs applications have the same sort of race-condition issues that +other applications do. For example, even when +@code{(file-readable-p "foo.txt")} returns @code{t}, it could be that +@file{foo.txt} is unreadable because some other program changed the +file's permissions between the call to @code{file-readable-p} and now. + +@item Resource limits +When Emacs exhausts memory or other operating system resources, its +behavior can be less reliable, in that computations that ordinarily +run to completion may abort back to the top level. This may cause +Emacs to neglect operations that it normally would have done. +@end table diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index f4d6b590c77..21a8ddd5d03 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2010-2013 Free Software Foundation, Inc. +@c Copyright (C) 2010-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Packaging @chapter Preparing Lisp code for distribution @@ -113,8 +113,10 @@ package loading is disabled if the user option This function initializes Emacs' internal record of which packages are installed, and loads them. The user option @code{package-load-list} specifies which packages to load; by default, all installed packages -are loaded. @xref{Package Installation,,, emacs, The GNU Emacs -Manual}. +are loaded. If called during startup, this function also sets +@code{package-enable-at-startup} to @code{nil}, to avoid accidentally +loading the packages twice. @xref{Package Installation,,, emacs, The +GNU Emacs Manual}. The optional argument @var{no-activate}, if non-@code{nil}, causes Emacs to update its record of installed packages without actually @@ -141,7 +143,8 @@ the various headers, as illustrated by the following example: ;; Author: J. R. Hacker <jrh@@example.com> ;; Version: 1.3 ;; Package-Requires: ((flange "1.0")) -;; Keywords: frobnicate +;; Keywords: multimedia, frobnicate +;; URL: http://example.com/jrhacker/superfrobnicate @dots{} @@ -177,6 +180,11 @@ on the @samp{flange} package, version 1.0 or higher. @xref{Library Headers}, for a description of the @samp{Package-Requires} header. If the header is omitted, the package has no dependencies. + The @samp{Keywords} and @samp{URL} headers are optional, but recommended. +The command @code{describe-package} uses these to add links to its +output. The @samp{Keywords} header should contain at least one +standard keyword from the @code{finder-known-keywords} list. + The file ought to also contain one or more autoload magic comments, as explained in @ref{Packaging Basics}. In the above example, a magic comment autoloads @code{superfrobnicator-mode}. @@ -284,7 +292,7 @@ case for the default GNU archive). Otherwise, the base location should be a directory name. In this case, Emacs retrieves packages from this archive via ordinary file -access. Such ``local'' archives are mainly useful for testing. +access. Such local archives are mainly useful for testing. @end defopt A package archive is simply a directory in which the package files, @@ -336,3 +344,38 @@ otherwise, an error is raised. @noindent After you create an archive, remember that it is not accessible in the Package Menu interface unless it is in @code{package-archives}. + +@cindex package archive security +@cindex package signing +Maintaining a public package archive entails a degree of responsibility. +When Emacs users install packages from your archive, those packages +can cause Emacs to run arbitrary code with the permissions of the +installing user. (This is true for Emacs code in general, not just +for packages.) So you should ensure that your archive is +well-maintained and keep the hosting system secure. + + One way to increase the security of your packages is to @dfn{sign} +them using a cryptographic key. If you have generated a +private/public gpg key pair, you can use gpg to sign the package like +this: + +@c FIXME EasyPG / package-x way to do this. +@example +gpg -ba -o @var{file}.sig @var{file} +@end example + +@noindent +For a single-file package, @var{file} is the package Lisp file; +for a multi-file package, it is the package tar file. +You can also sign the archive's contents file in the same way. +Make the @file{.sig} files available in the same location as the packages. +You should also make your public key available for people to download; +e.g., by uploading it to a key server such as @url{http://pgp.mit.edu/}. +When people install packages from your archive, they can use +your public key to verify the signatures. + +A full explanation of these matters is outside the scope of this +manual. For more information on cryptographic keys and signing, +@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes +with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa, +Emacs EasyPG Assistant Manual}. diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index 69f1b80c431..72b76ce5c8f 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Positions @chapter Positions @@ -22,11 +22,11 @@ be a position (an integer), but accept a marker as a substitute, normally ignore which buffer the marker points into; they convert the marker to an integer, and use that integer, exactly as if you had passed the integer as the argument, even if the marker points to the -``wrong'' buffer. A marker that points nowhere cannot convert to an +wrong buffer. A marker that points nowhere cannot convert to an integer; using it instead of an integer causes an error. @xref{Markers}. - See also the ``field'' feature (@pxref{Fields}), which provides + See also the field feature (@pxref{Fields}), which provides functions that are used by many cursor-motion commands. @menu @@ -227,7 +227,7 @@ backward until encountering the front of a word, rather than forward. @c Emacs 19 feature This variable affects the behavior of @code{forward-word} and everything that uses it. If it is non-@code{nil}, then characters in the -``escape'' and ``character quote'' syntax classes count as part of +escape and character-quote syntax classes count as part of words. Otherwise, they do not. @end defopt @@ -350,10 +350,11 @@ would move to. @deffn Command forward-line &optional count @cindex beginning of line This function moves point forward @var{count} lines, to the beginning of -the line. If @var{count} is negative, it moves point -@minus{}@var{count} lines backward, to the beginning of a line. If -@var{count} is zero, it moves point to the beginning of the current -line. If @var{count} is @code{nil}, that means 1. +the line following that. If @var{count} is negative, it moves point +@minus{}@var{count} lines backward, to the beginning of a line +preceding that. If @var{count} is zero, it moves point to the +beginning of the current line. If @var{count} is @code{nil}, that +means 1. If @code{forward-line} encounters the beginning or end of the buffer (or of the accessible portion) before finding that many lines, it sets point @@ -362,7 +363,11 @@ there. No error is signaled. @code{forward-line} returns the difference between @var{count} and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point stops at -the end of the last line, and the value will be 2. +the end of the last line, and the value will be 2. As an explicit +exception, if the last accessible line is non-empty, but has no +newline (e.g., if the buffer ends without a newline), the function +sets point to the end of that line, and the value returned by the +function counts that line as one line successfully moved. In an interactive call, @var{count} is the numeric prefix argument. @end deffn @@ -404,7 +409,7 @@ mentioned here only for completeness. @deffn Command previous-line count @cindex goal column This function moves point up @var{count} lines (down if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' +is negative). In moving, it attempts to keep point in the @dfn{goal column} (normally the same column that it was at the beginning of the move). If there is no character in the target line exactly under the current @@ -429,7 +434,7 @@ to use and more reliable (no dependence on goal column, etc.). @deffn Command next-line count This function moves point down @var{count} lines (up if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' +is negative). In moving, it attempts to keep point in the goal column (normally the same column that it was at the beginning of the move). If there is no character in the target line exactly under the current @@ -465,6 +470,7 @@ beginning or end of a line. @node Screen Lines @subsection Motion by Screen Lines +@cindex screen lines, moving by The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen @@ -486,11 +492,13 @@ flag, and display table may vary between windows). @xref{Usual Display}. These functions scan text to determine where screen lines break, and -thus take time proportional to the distance scanned. If you intend to -use them heavily, Emacs provides caches which may improve the -performance of your code. @xref{Truncation, cache-long-scans}. +thus take time proportional to the distance scanned. +@ignore +If you intend to use them heavily, Emacs provides caches which may +improve the performance of your code. @xref{Truncation, cache-long-scans}. +@end ignore -@defun vertical-motion count &optional window +@defun vertical-motion count &optional window cur-col This function moves point to the start of the screen line @var{count} screen lines down from the screen line containing point. If @var{count} is negative, it moves up instead. @@ -498,7 +506,11 @@ is negative, it moves up instead. The @var{count} argument can be a cons cell, @code{(@var{cols} . @var{lines})}, instead of an integer. Then the function moves by @var{lines} screen lines, and puts point @var{cols} columns from the -start of that screen line. +visual start of that screen line. Note that @var{cols} are counted +from the @emph{visual} start of the line; if the window is scrolled +horizontally (@pxref{Horizontal Scrolling}), the column on which point +will end is in addition to the number of columns by which the text is +scrolled. The return value is the number of screen lines over which point was moved. The value may be less in absolute value than @var{count} if @@ -508,6 +520,14 @@ The window @var{window} is used for obtaining parameters such as the width, the horizontal scrolling, and the display table. But @code{vertical-motion} always operates on the current buffer, even if @var{window} currently displays some other buffer. + +The optional argument @var{cur-col} specifies the current column when +the function is called. This is the window-relative horizontal +coordinate of point, measured in units of font width of the frame's +default face. Providing it speeds up the function, especially in very +long lines, because it doesn't have to go back in the buffer in order +to determine the current column. Note that @var{cur-col} is also +counted from the visual start of the line. @end defun @defun count-screen-lines &optional beg end count-final-newline window @@ -645,9 +665,19 @@ parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) @end deffn -@deffn Command up-list &optional arg -This function moves forward out of @var{arg} (default 1) levels of parentheses. -A negative argument means move backward but still to a less deep spot. +@deffn Command up-list &optional arg escape-strings no-syntax-crossing +This function moves forward out of @var{arg} (default 1) levels of +parentheses. A negative argument means move backward but still to a +less deep spot. If @var{escape-strings} is non-@code{nil} (as it is +interactively), move out of enclosing strings as well. If +@var{no-syntax-crossing} is non-@code{nil} (as it is interactively), prefer +to break out of any enclosing string instead of moving to the start of +a list broken across multiple strings. On error, location of point is +unspecified. +@end deffn + +@deffn Command backward-up-list &optional arg escape-strings no-syntax-crossing +This function is just like @code{up-list}, but with a negated argument. @end deffn @deffn Command down-list &optional arg @@ -797,11 +827,11 @@ is zero or less. @section Excursions @cindex excursion - It is often useful to move point ``temporarily'' within a localized + It is often useful to move point temporarily within a localized portion of the program. This is called an @dfn{excursion}, and it is done with the @code{save-excursion} special form. This construct -remembers the initial identity of the current buffer, and its values -of point and the mark, and restores them after the excursion +remembers the initial identity of the current buffer, and its value +of point, and restores them after the excursion completes. It is the standard way to move point within one part of a program and avoid affecting the rest of the program, and is used thousands of times in the Lisp sources of Emacs. @@ -813,27 +843,26 @@ window configurations, see the forms described in @ref{Window Configurations} and in @ref{Frame Configurations}. @c frameset? @defspec save-excursion body@dots{} -@cindex mark excursion @cindex point excursion This special form saves the identity of the current buffer and the -values of point and the mark in it, evaluates @var{body}, and finally -restores the buffer and its saved values of point and the mark. All -three saved values are restored even in case of an abnormal exit via +value of point in it, evaluates @var{body}, and finally +restores the buffer and its saved value of point. Both saved values are +restored even in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). The value returned by @code{save-excursion} is the result of the last form in @var{body}, or @code{nil} if no body forms were given. @end defspec - Because @code{save-excursion} only saves point and mark for the + Because @code{save-excursion} only saves point for the buffer that was current at the start of the excursion, any changes -made to point and/or mark in other buffers, during the excursion, will +made to point in other buffers, during the excursion, will remain in effect afterward. This frequently leads to unintended consequences, so the byte compiler warns if you call @code{set-buffer} during an excursion: @example -Warning: Use `with-current-buffer' rather than +Warning: Use ‘with-current-buffer’ rather than save-excursion+set-buffer @end example @@ -863,10 +892,13 @@ type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved point value is restored, it normally comes before the inserted text. - Although @code{save-excursion} saves the location of the mark, it does -not prevent functions which modify the buffer from setting -@code{deactivate-mark}, and thus causing the deactivation of the mark -after the command finishes. @xref{The Mark}. +@defmac save-mark-and-excursion body@dots{} +@cindex mark excursion +@cindex point excursion +This macro is like @code{save-excursion}, but also saves and restores +the mark location and @code{mark-active}. This macro does what +@code{save-excursion} did before Emacs 25.1. +@end defmac @node Narrowing @section Narrowing @@ -955,7 +987,7 @@ restores the restrictions on the original buffer (the buffer whose restrictions it saved from), but it does not restore the identity of the current buffer. -@code{save-restriction} does @emph{not} restore point and the mark; use +@code{save-restriction} does @emph{not} restore point; use @code{save-excursion} for that. If you use both @code{save-restriction} and @code{save-excursion} together, @code{save-excursion} should come first (on the outside). Otherwise, the old point value would be diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index e869bb86e40..35f3c6ca470 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Processes @@ -63,6 +63,8 @@ Processes}. @node Subprocess Creation @section Functions that Create Subprocesses +@cindex create subprocess +@cindex process creation There are three primitives that create a new subprocess in which to run a program. One of them, @code{start-process}, creates an asynchronous @@ -112,7 +114,7 @@ described below. argument that specifies where the standard output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, that will create the buffer if it does not already exist. It can also -be @code{nil}, which says to discard the output unless a filter function +be @code{nil}, which says to discard the output, unless a custom filter function handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) Normally, you should avoid having multiple processes send output to the same buffer because their output would be intermixed randomly. @@ -178,7 +180,7 @@ and then pass it to a shell for execution. Precisely what this function does depends on your operating system. The function is designed to work with the syntax of your system's standard shell; if you use an unusual shell, you will need to redefine this -function. +function. @xref{Security Considerations}. @example ;; @r{This example shows the behavior on GNU and Unix systems.} @@ -194,7 +196,7 @@ Here's an example of using @code{shell-quote-argument} to construct a shell command: @example -(concat "diff -c " +(concat "diff -u " (shell-quote-argument oldfile) " " (shell-quote-argument newfile)) @@ -288,7 +290,7 @@ Here are the possibilities: Insert the output in that buffer, before point. This includes both the standard output stream and the standard error stream of the process. -@item a string +@item a buffer name (a string) Insert the output in a buffer with that name, before point. @item @code{t} @@ -501,17 +503,21 @@ inputinput@point{} @c It actually uses shell-command-switch, but no need to mention that here. @end defun -@defun call-process-shell-command command &optional infile destination display &rest args +@defun call-process-shell-command command &optional infile destination display This function executes the shell command @var{command} synchronously. -The final arguments @var{args} are additional arguments to add at the -end of @var{command}. The other arguments are handled as in -@code{call-process}. +The arguments are handled as in @code{call-process}. An old calling +convention allowed to pass any number of additional arguments after +@var{display}, which were concatenated to @var{command}; this is still +supported, but strongly discouraged. @end defun -@defun process-file-shell-command command &optional infile destination display &rest args +@defun process-file-shell-command command &optional infile destination display This function is like @code{call-process-shell-command}, but uses @code{process-file} internally. Depending on @code{default-directory}, -@var{command} can be executed also on remote hosts. +@var{command} can be executed also on remote hosts. An old calling +convention allowed to pass any number of additional arguments after +@var{display}, which were concatenated to @var{command}; this is still +supported, but strongly discouraged. @end defun @defun shell-command-to-string command @@ -686,6 +692,113 @@ use the function @code{process-tty-name} (@pxref{Process Information}). @end defvar +@defun make-process &rest args +This function is like @code{start-process}, but takes keyword arguments. + +The arguments @var{args} are a list of keyword/argument pairs. +Omitting a keyword is always equivalent to specifying it with value +@code{nil}. Here are the meaningful keywords: + +@table @asis +@item :name @var{name} +Use the string @var{name} as the process name. It is modified if +necessary to make it unique. + +@item :buffer @var{buffer} +Use @var{buffer} as the process buffer. + +@item :command @var{command} +Use @var{command} as the command line of the process. @var{command} +is a list starting with the program's executable file name, followed +by strings to give to program as arguments. + +@item :coding @var{coding} +If @var{coding} is a symbol, it specifies the coding system to be +used for both reading and writing of data from and to the +connection. If @var{coding} is a cons cell +@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding} +will be used for reading and @var{encoding} for writing. + +If @var{coding} is @code{nil}, the default rules for finding the +coding system will apply. @xref{Default Coding Systems}. + +@item :connection-type @var{TYPE} +Initialize the type of device used to communicate with the subprocess. +Possible values are @code{pty} to use a pty, @code{pipe} to use a +pipe, or @code{nil} to use the default derived from the value of +the @code{process-connection-type} variable. + +@item :noquery @var{query-flag} +Initialize the process query flag to @var{query-flag}. +@xref{Query Before Exit}. + +@item :stop @var{stopped} +If @var{stopped} is non-@code{nil}, start the process in the +stopped state. + +@item :filter @var{filter} +Initialize the process filter to @var{filter}. + +@item :sentinel @var{sentinel} +Initialize the process sentinel to @var{sentinel}. + +@item :stderr @var{stderr} +Associate @var{stderr} with the standard error of the process. +@var{stderr} is either a buffer or a pipe process created with +@code{make-pipe-process}. +@end table + +The original argument list, modified with the actual connection +information, is available via the @code{process-contact} function. +@end defun + +@defun make-pipe-process &rest args +This function creates a bidirectional pipe which can be attached to a +child process (currently only useful with the @code{:stderr} keyword +of @code{make-process}). + +The arguments @var{args} are a list of keyword/argument pairs. +Omitting a keyword is always equivalent to specifying it with value +@code{nil}, except for @code{:coding}. +Here are the meaningful keywords: + +@table @asis +@item :name @var{name} +Use the string @var{name} as the process name. It is modified if +necessary to make it unique. + +@item :buffer @var{buffer} +Use @var{buffer} as the process buffer. + +@item :coding @var{coding} +If @var{coding} is a symbol, it specifies the coding system to be +used for both reading and writing of data from and to the +connection. If @var{coding} is a cons cell +@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding} +will be used for reading and @var{encoding} for writing. + +If @var{coding} is @code{nil}, the default rules for finding the +coding system will apply. @xref{Default Coding Systems}. + +@item :noquery @var{query-flag} +Initialize the process query flag to @var{query-flag}. +@xref{Query Before Exit}. + +@item :stop @var{stopped} +If @var{stopped} is non-@code{nil}, start the process in the +stopped state. + +@item :filter @var{filter} +Initialize the process filter to @var{filter}. + +@item :sentinel @var{sentinel} +Initialize the process sentinel to @var{sentinel}. +@end table + +The original argument list, modified with the actual connection +information, is available via the @code{process-contact} function. +@end defun + @node Deleting Processes @section Deleting Processes @cindex deleting processes @@ -696,7 +809,7 @@ but not necessarily right away. You can delete a process explicitly at any time. If you explicitly delete a terminated process before it is deleted automatically, no harm results. Deleting a running process sends a signal to terminate it (and its child processes, if -any), and calls the process sentinel if it has one. @xref{Sentinels}. +any), and calls the process sentinel. @xref{Sentinels}. When a process is deleted, the process object itself continues to exist as long as other Lisp objects point to it. All the Lisp @@ -719,7 +832,7 @@ signal. The argument may be a process, the name of a process, a buffer, or the name of a buffer. (A buffer or buffer-name stands for the process that @code{get-buffer-process} returns.) Calling @code{delete-process} on a running process terminates it, updates the -process status, and runs the sentinel (if any) immediately. If the +process status, and runs the sentinel immediately. If the process has already terminated, calling @code{delete-process} has no effect on its status, or on the running of its sentinel (which will happen sooner or later). @@ -734,6 +847,7 @@ happen sooner or later). @node Process Information @section Process Information +@cindex process information Several functions return information about processes. @@ -956,7 +1070,7 @@ This function sets the process plist of @var{process} to @var{plist}. Asynchronous subprocesses receive input when it is sent to them by Emacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. The -data appears on the ``standard input'' of the subprocess. +data appears on the standard input of the subprocess. @c FIXME which? Some operating systems have limited space for buffered input in a @@ -1075,10 +1189,10 @@ job-control shells won't work when a pipe is used. See @defun interrupt-process &optional process current-group This function interrupts the process @var{process} by sending the -signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt -character'' (normally @kbd{C-c} on some systems, and @key{DEL} on +signal @code{SIGINT}. Outside of Emacs, typing the interrupt +character (normally @kbd{C-c} on some systems, and @key{DEL} on others) sends this signal. When the argument @var{current-group} is -non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' +non-@code{nil}, you can think of this function as typing @kbd{C-c} on the terminal by which Emacs talks to the subprocess. @end defun @@ -1090,10 +1204,8 @@ and cannot be handled by the subprocess. @defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process -@var{process}. This signal is the one sent by the ``quit -@c FIXME? Never heard of C-b being used for this. In readline, e.g., -@c bash, that is backward-word. -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside +@var{process}. This signal is the one sent by the quit +character (usually @kbd{C-\}) when you are not inside Emacs. @end defun @@ -1102,10 +1214,10 @@ This function stops the process @var{process} by sending the signal @code{SIGTSTP}. Use @code{continue-process} to resume its execution. -Outside of Emacs, on systems with job control, the ``stop character'' +Outside of Emacs, on systems with job control, the stop character (usually @kbd{C-z}) normally sends this signal. When @var{current-group} is non-@code{nil}, you can think of this function as -``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the +typing @kbd{C-z} on the terminal Emacs uses to communicate with the subprocess. @end defun @@ -1130,12 +1242,12 @@ children of Emacs. @xref{System Processes}. @cindex process output @cindex output from processes - There are two ways to receive the output that a subprocess writes to -its standard output stream. The output can be inserted in a buffer, -which is called the associated buffer of the process (@pxref{Process -Buffers}), or a function called the @dfn{filter function} can be -called to act on the output. If the process has no buffer and no -filter function, its output is discarded. + The output that a subprocess writes to its standard output stream +is passed to a function called the @dfn{filter function}. The default +filter function simply inserts the output into a buffer, which is +called the associated buffer of the process (@pxref{Process +Buffers}). If the process has no buffer then the default filter +discards the output. When a subprocess terminates, Emacs reads any pending output, then stops reading output from that subprocess. Therefore, if the @@ -1170,7 +1282,7 @@ redirect one of them to a file---for example, by using an appropriate shell command. @menu -* Process Buffers:: If no filter, output is put in a buffer. +* Process Buffers:: By default, output is put in a buffer. * Filter Functions:: Filter functions accept output from the process. * Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives. @@ -1188,11 +1300,12 @@ normal practice only one process is associated with any given buffer. Many applications of processes also use the buffer for editing input to be sent to the process, but this is not built into Emacs Lisp. - Unless the process has a filter function (@pxref{Filter Functions}), -its output is inserted in the associated buffer. The position to insert -the output is determined by the @code{process-mark}, which is then -updated to point to the end of the text just inserted. Usually, but not -always, the @code{process-mark} is at the end of the buffer. + By default, process output is inserted in the associated buffer. +(You can change this by defining a custom filter function, +@pxref{Filter Functions}.) The position to insert the output is +determined by the @code{process-mark}, which is then updated to point +to the end of the text just inserted. Usually, but not always, the +@code{process-mark} is at the end of the buffer. @findex process-kill-buffer-query-function Killing the associated buffer of a process also kills the process. @@ -1221,13 +1334,12 @@ marker that says where to insert output from the process. If @var{process} does not have a buffer, @code{process-mark} returns a marker that points nowhere. -Insertion of process output in a buffer uses this marker to decide where -to insert, and updates it to point after the inserted text. That is why -successive batches of output are inserted consecutively. +The default filter function uses this marker to decide where to +insert process output, and updates it to point after the inserted text. +That is why successive batches of output are inserted consecutively. -Filter functions normally should use this marker in the same fashion -as is done by direct insertion of output in the buffer. For an -example of a filter function that uses @code{process-mark}, +Custom filter functions normally should use this marker in the same fashion. +For an example of a filter function that uses @code{process-mark}, @pxref{Process Filter Example}. When the user is expected to enter input in the process buffer for @@ -1269,10 +1381,9 @@ subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). @cindex process filter A process @dfn{filter function} is a function that receives the -standard output from the associated process. If a process has a filter, -then @emph{all} output from that process is passed to the filter. The -process buffer is used directly for output from the process only when -there is no filter. +standard output from the associated process. @emph{All} output from +that process is passed to the filter. The default filter simply +outputs directly to the process buffer. The filter function can only be called when Emacs is waiting for something, because process output arrives only at such times. Emacs @@ -1301,8 +1412,8 @@ This makes it possible to use the Lisp debugger to debug the filter function. @xref{Debugger}. Many filter functions sometimes (or always) insert the output in the -process's buffer, mimicking the actions of Emacs when there is no -filter. Such filter functions need to make sure that they save the +process's buffer, mimicking the actions of the default filter. +Such filter functions need to make sure that they save the current buffer, select the correct buffer (if different) before inserting output, and then restore the original buffer. They should also check whether the buffer is still alive, update the @@ -1358,14 +1469,18 @@ received text into a temporary buffer, which can then be searched. @defun set-process-filter process filter This function gives @var{process} the filter function @var{filter}. If -@var{filter} is @code{nil}, it gives the process no filter. +@var{filter} is @code{nil}, it gives the process the default filter, +which inserts the process output into the process buffer. @end defun @defun process-filter process -This function returns the filter function of @var{process}, or @code{nil} -if it has none. +This function returns the filter function of @var{process}. @end defun +In case the process's output needs to be passed to several filters, you can +use @code{add-function} to combine an existing filter with a new one. +@xref{Advising Functions}. + Here is an example of the use of a filter function: @smallexample @@ -1402,8 +1517,7 @@ backup.mss dland syllabus.mss @ignore @c The code in this example doesn't show the right way to do things. Here is another, more realistic example, which demonstrates how to use -the process mark to do insertion in the same fashion as is done when -there is no filter function: +the process mark to do insertion in the same fashion as the default filter: @smallexample @group @@ -1475,19 +1589,19 @@ until output arrives from a process. @defun accept-process-output &optional process seconds millisec just-this-one This function allows Emacs to read pending output from processes. The -output is inserted in the associated buffers or given to their filter -functions. If @var{process} is non-@code{nil} then this function does -not return until some output has been received from @var{process}. +output is given to their filter functions. If @var{process} is +non-@code{nil} then this function does not return until some output +has been received from @var{process}. The arguments @var{seconds} and @var{millisec} let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods thus specified are added together, and @code{accept-process-output} -returns after that much time, whether or not there has been any +returns after that much time, even if there is no subprocess output. The argument @var{millisec} is obsolete (and should not be used), -because @var{seconds} can be a floating point number to specify +because @var{seconds} can be floating point to specify waiting a fractional number of seconds. If @var{seconds} is 0, the function accepts whatever output is pending but does not wait. @@ -1501,7 +1615,8 @@ recommended, but may be necessary for specific applications, such as speech synthesis. The function @code{accept-process-output} returns non-@code{nil} if it -did get some output, or @code{nil} if the timeout expired before output +got output from @var{process}, or from any process if @var{process} is +@code{nil}. It returns @code{nil} if the timeout expired before output arrived. @end defun @@ -1621,9 +1736,9 @@ while executing sentinels. @xref{Match Data}. @defun set-process-sentinel process sentinel This function associates @var{sentinel} with @var{process}. If -@var{sentinel} is @code{nil}, then the process will have no sentinel. -The default behavior when there is no sentinel is to insert a message in -the process's buffer when the process status changes. +@var{sentinel} is @code{nil}, then the process will have the default +sentinel, which inserts a message in the process's buffer when the +process status changes. Changes in process sentinels take effect immediately---if the sentinel is slated to be run but has not been called yet, and you specify a new @@ -1633,23 +1748,26 @@ sentinel, the eventual call to the sentinel will use the new one. @group (defun msg-me (process event) (princ - (format "Process: %s had the event `%s'" process event))) + (format "Process: %s had the event '%s'" process event))) (set-process-sentinel (get-process "shell") 'msg-me) @result{} msg-me @end group @group (kill-process (get-process "shell")) - @print{} Process: #<process shell> had the event `killed' + @print{} Process: #<process shell> had the event 'killed' @result{} #<process shell> @end group @end smallexample @end defun @defun process-sentinel process -This function returns the sentinel of @var{process}, or @code{nil} if it -has none. +This function returns the sentinel of @var{process}. @end defun +In case a process status changes need to be passed to several sentinels, you +can use @code{add-function} to combine an existing sentinel with a new one. +@xref{Advising Functions}. + @defun waiting-for-user-input-p While a sentinel or filter function is running, this function returns non-@code{nil} if Emacs was waiting for keyboard input from the user at @@ -1717,7 +1835,7 @@ attribute and @var{value} is the value of that attribute. The various attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating-point, +Values that are numbers can be either integer or floating point, depending on the magnitude of the value. @table @code @@ -1759,7 +1877,7 @@ interruptible sleep (waiting for some event) @item "T" stopped, e.g., by a job control signal @item "Z" -``zombie'': a process that terminated, but was not reaped by its parent +zombie: a process that terminated, but was not reaped by its parent @end table @noindent @@ -1984,7 +2102,7 @@ server is stopped; a non-@code{nil} value means yes. @cindex @acronym{STARTTLS} network connections Emacs can create encrypted network connections, using either built-in or external support. The built-in support uses the GnuTLS -(``Transport Layer Security'') library; see +Transport Layer Security Library; see @uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}. If your Emacs was compiled with GnuTLS support, the function @code{gnutls-available-p} is defined and returns non-@code{nil}. For @@ -2004,7 +2122,7 @@ is modified as necessary to make it unique. The @var{buffer} argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, -unless you specify a filter function to handle the output. If +unless you specify your own filter function to handle the output. If @var{buffer} is @code{nil}, it means that the connection is not associated with any buffer. @@ -2028,7 +2146,7 @@ The type of connection. Options are: An ordinary, unencrypted connection. @item tls @itemx ssl -A @acronym{TLS} (``Transport Layer Security'') connection. +A @acronym{TLS} (Transport Layer Security) connection. @item nil @itemx network Start with a plain connection, and if parameters @samp{:success} @@ -2065,6 +2183,12 @@ Regular expression matching a successful @acronym{STARTTLS} negotiation. If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs doesn't have built-in @acronym{TLS} support. +@item :warn-unless-encrypted @var{boolean} +If non-@code{nil}, and @code{:return-value} is also non-@code{nil}, +Emacs will warn if the connection isn't encrypted. This is useful for +protocols like @acronym{IMAP} and the like, where most users would +expect the network traffic to be encrypted. + @item :client-certificate @var{list-or-t} Either a list of the form @code{(@var{key-file} @var{cert-file})}, naming the certificate key file and certificate file itself, or @@ -2090,6 +2214,7 @@ The connection type: @samp{plain} or @samp{tls}. @end defun + @node Network Servers @section Network Servers @cindex network servers @@ -2112,7 +2237,7 @@ unique number in brackets, as in @samp{<@var{nnn}>}. The number is unique for each connection in the Emacs session. @item -If the server's filter is non-@code{nil}, the connection process does +If the server has a non-default filter, the connection process does not get a separate process buffer; otherwise, Emacs creates a new buffer for the purpose. The buffer name is the server's buffer name or process name, concatenated with the client identification string. @@ -2209,7 +2334,7 @@ necessary to make it unique. @item :type @var{type} Specify the communication type. A value of @code{nil} specifies a stream connection (the default); @code{datagram} specifies a datagram -connection; @code{seqpacket} specifies a ``sequenced packet stream'' +connection; @code{seqpacket} specifies a sequenced packet stream connection. Both connections and servers can be of these types. @item :server @var{server-flag} @@ -2276,7 +2401,7 @@ A local address is represented as a string, which specifies the address in the local address space. @item -An ``unsupported family'' address is represented by a cons +An unsupported-family address is represented by a cons @code{(@var{f} . @var{av})}, where @var{f} is the family number and @var{av} is a vector specifying the socket address using one element per address data byte. Do not rely on this format in portable code, @@ -2295,7 +2420,7 @@ has succeeded or failed. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the network connection or -server in the ``stopped'' state. +server in the stopped state. @item :buffer @var{buffer} Use @var{buffer} as the process buffer. @@ -2603,7 +2728,7 @@ Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. The flags defaults to @code{nil} if unspecified. @item :stop @var{bool} -Start process in the ``stopped'' state if @var{bool} is +Start process in the stopped state if @var{bool} is non-@code{nil}. In the stopped state, a serial process does not accept incoming data, but you can send outgoing data. The stopped state is cleared by @code{continue-process} and set by @@ -2643,7 +2768,7 @@ Here is an example: @cindex stopbits, in serial connections @cindex flowcontrol, in serial connections -This functions configures a serial port connection. Arguments are +This function configures a serial port connection. Arguments are specified as keyword/argument pairs. Attributes that are not given are re-initialized from the process's current configuration (available via the function @code{process-contact}), or set to reasonable default @@ -2733,7 +2858,7 @@ specification}, a special nested list describing named and typed @dfn{fields}. This specification controls the length of each field to be processed, and how to pack or unpack it. We normally keep bindat specs in variables whose names end in @samp{-bindat-spec}; that kind of name -is automatically recognized as ``risky''. +is automatically recognized as risky. @cindex endianness @cindex big endian @@ -2742,8 +2867,8 @@ is automatically recognized as ``risky''. A field's @dfn{type} describes the size (in bytes) of the object that the field represents and, in the case of multibyte fields, how the bytes are ordered within the field. The two possible orderings -are ``big endian'' (also known as ``network byte ordering'') and -``little endian''. For instance, the number @code{#x23cd} (decimal +are @dfn{big endian} (also known as ``network byte ordering'') and +@dfn{little endian}. For instance, the number @code{#x23cd} (decimal 9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; and in little endian, @code{#xcd} @code{#x23}. Here are the possible type values: diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 386d5bdde4c..adaf43159af 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Searching and Matching @@ -113,7 +113,7 @@ match. @end deffn @deffn Command word-search-forward string &optional limit noerror repeat -This function searches forward from point for a ``word'' match for +This function searches forward from point for a word match for @var{string}. If it finds a match, it sets point to the end of the match found, and returns the new value of point. @@ -137,7 +137,7 @@ the ball boy!" @group (word-search-forward "Please find the ball, boy.") - @result{} 36 + @result{} 39 ---------- Buffer: foo ---------- He said "Please! Find @@ -160,16 +160,17 @@ If @var{repeat} is non-@code{nil}, then the search is repeated that many times. Point is positioned at the end of the last match. @findex word-search-regexp -Internal, @code{word-search-forward} and related functions use the +Internally, @code{word-search-forward} and related functions use the function @code{word-search-regexp} to convert @var{string} to a regular expression that ignores punctuation. @end deffn @deffn Command word-search-forward-lax string &optional limit noerror repeat This command is identical to @code{word-search-forward}, except that -the end of @var{string} need not match a word boundary, unless @var{string} ends -in whitespace. For instance, searching for @samp{ball boy} matches -@samp{ball boyee}, but does not match @samp{aball boy}. +the beginning or the end of @var{string} need not match a word +boundary, unless @var{string} begins or ends in whitespace. +For instance, searching for @samp{ball boy} matches @samp{ball boyee}, +but does not match @samp{balls boy}. @end deffn @deffn Command word-search-backward string &optional limit noerror repeat @@ -181,8 +182,8 @@ beginning of the match. @deffn Command word-search-backward-lax string &optional limit noerror repeat This command is identical to @code{word-search-backward}, except that -the end of @var{string} need not match a word boundary, unless @var{string} ends -in whitespace. +the beginning or the end of @var{string} need not match a word +boundary, unless @var{string} begins or ends in whitespace. @end deffn @node Searching and Case @@ -256,6 +257,8 @@ it easier to verify even very complex regexps. @node Syntax of Regexps @subsection Syntax of Regular Expressions +@cindex regexp syntax +@cindex syntax of regular expressions Regular expressions have a syntax in which a few characters are special constructs and the rest are @dfn{ordinary}. An ordinary @@ -273,12 +276,12 @@ expression is ordinary, unless a @samp{\} precedes it. therefore @samp{f} is a regular expression that matches the string @samp{f} and no other string. (It does @emph{not} match the string @samp{fg}, but it does match a @emph{part} of that string.) Likewise, -@samp{o} is a regular expression that matches only @samp{o}.@refill +@samp{o} is a regular expression that matches only @samp{o}. Any two regular expressions @var{a} and @var{b} can be concatenated. The result is a regular expression that matches a string if @var{a} matches some amount of the beginning of that string and @var{b} matches the rest of -the string.@refill +the string. As a simple example, we can concatenate the regular expressions @samp{f} and @samp{o} to get the regular expression @samp{fo}, which matches only @@ -293,6 +296,7 @@ need to use one of the special regular expression constructs. @node Regexp Special @subsubsection Special Characters in Regular Expressions +@cindex regexp, special characters in Here is a list of the characters that are special in a regular expression. @@ -304,7 +308,7 @@ expression. is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like @samp{a.b}, which matches any three-character string that begins with @samp{a} and ends with -@samp{b}.@refill +@samp{b}. @item @samp{*} @cindex @samp{*} in regexp @@ -355,7 +359,7 @@ preceding expression either once or not at all. For example, @item @samp{*?}, @samp{+?}, @samp{??} @cindex non-greedy repetition characters in regexp -These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} +These are @dfn{non-greedy} variants of the operators @samp{*}, @samp{+} and @samp{?}. Where those operators match the largest possible substring (consistent with matching the entire containing expression), the non-greedy variants match the smallest possible substring @@ -488,7 +492,7 @@ example, the regular expression that matches the @samp{\} character is @samp{\\}. To write a Lisp string that contains the characters @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another @samp{\}. Therefore, the read syntax for a regular expression matching -@samp{\} is @code{"\\\\"}.@refill +@samp{\} is @code{"\\\\"}. @end table @strong{Please note:} For historical compatibility, special characters @@ -496,7 +500,7 @@ are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is no preceding expression on which the @samp{*} can act. It is poor practice to depend on this behavior; quote the -special character anyway, regardless of where it appears.@refill +special character anyway, regardless of where it appears. As a @samp{\} is not special inside a character alternative, it can never remove the special meaning of @samp{-} or @samp{]}. So you @@ -537,11 +541,15 @@ and what they mean: @item [:ascii:] This matches any @acronym{ASCII} character (codes 0--127). @item [:alnum:] -This matches any letter or digit. (At present, for multibyte -characters, it matches anything that has word syntax.) +This matches any letter or digit. For multibyte characters, it +matches characters whose Unicode @samp{general-category} property +(@pxref{Character Properties}) indicates they are alphabetic or +decimal number characters. @item [:alpha:] -This matches any letter. (At present, for multibyte characters, it -matches anything that has word syntax.) +This matches any letter. For multibyte characters, it matches +characters whose Unicode @samp{general-category} property +(@pxref{Character Properties}) indicates they are alphabetic +characters. @item [:blank:] This matches space and tab only. @item [:cntrl:] @@ -550,8 +558,11 @@ This matches any @acronym{ASCII} control character. This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} matches any digit, as well as @samp{+} and @samp{-}. @item [:graph:] -This matches graphic characters---everything except @acronym{ASCII} control -characters, space, and the delete character. +This matches graphic characters---everything except whitespace, +@acronym{ASCII} and non-@acronym{ASCII} control characters, +surrogates, and codepoints unassigned by Unicode, as indicated by the +Unicode @samp{general-category} property (@pxref{Character +Properties}). @item [:lower:] This matches any lower-case letter, as determined by the current case table (@pxref{Case Tables}). If @code{case-fold-search} is @@ -561,8 +572,8 @@ This matches any multibyte character (@pxref{Text Representations}). @item [:nonascii:] This matches any non-@acronym{ASCII} character. @item [:print:] -This matches printing characters---everything except @acronym{ASCII} control -characters and the delete character. +This matches any printing character---either whitespace, or a graphic +character matched by @samp{[:graph:]}. @item [:punct:] This matches any punctuation character. (At present, for multibyte characters, it matches anything that has non-word syntax.) @@ -599,14 +610,14 @@ a table of the special @samp{\} constructs. specifies an alternative. Two regular expressions @var{a} and @var{b} with @samp{\|} in between form an expression that matches anything that either @var{a} or -@var{b} matches.@refill +@var{b} matches. Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill +but no other string. @samp{\|} applies to the largest possible surrounding expressions. Only a surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill +@samp{\|}. If you need full backtracking capability to handle multiple uses of @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX @@ -785,7 +796,7 @@ matches the empty string, but only at point. matches the empty string, but only at the beginning or end of a word. Thus, @samp{\bfoo\b} matches any occurrence of @samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill +@samp{ball} or @samp{balls} as a separate word. @samp{\b} matches at the beginning or end of the buffer (or string) regardless of what text appears next to it. @@ -893,6 +904,7 @@ beyond the minimum needed to end a sentence. These functions operate on regular expressions. +@cindex quote special characters in regexp @defun regexp-quote string This function returns a regular expression whose only exact match is @var{string}. Using this regular expression in @code{looking-at} will @@ -923,6 +935,7 @@ whitespace: @end example @end defun +@cindex optimize regexp @defun regexp-opt strings &optional paren This function returns an efficient regular expression that will match any of the strings in the list @var{strings}. This is useful when you @@ -982,10 +995,11 @@ list of characters @var{chars}. @cindex searching for regexp In GNU Emacs, you can search for the next match for a regular -expression either incrementally or not. For incremental search -commands, see @ref{Regexp Search, , Regular Expression Search, emacs, -The GNU Emacs Manual}. Here we describe only the search functions -useful in programs. The principal one is @code{re-search-forward}. +expression (@pxref{Syntax of Regexps}) either incrementally or not. +For incremental search commands, see @ref{Regexp Search, , Regular +Expression Search, emacs, The GNU Emacs Manual}. Here we describe +only the search functions useful in programs. The principal one is +@code{re-search-forward}. These search functions convert the regular expression to multibyte if the buffer is multibyte; they convert the regular expression to unibyte @@ -1088,7 +1102,7 @@ For example, The index of the first character of the string is 0, the index of the second character is 1, and so on. -After this function returns, the index of the first character beyond +If this function finds a match, the index of the first character beyond the match is available as @code{(match-end 0)}. @xref{Match Data}. @example @@ -1146,13 +1160,7 @@ implemented by searching backwards from point for a match that ends at point. That can be quite slow if it has to search a long distance. You can bound the time required by specifying @var{limit}, which says not to search before @var{limit}. In this case, the match that is -found must begin at or after @var{limit}. - -If @var{greedy} is non-@code{nil}, this function extends the match -backwards as far as possible, stopping when a single additional -previous character cannot be part of a match for regexp. When the -match is extended, its starting position is allowed to occur before -@var{limit}. +found must begin at or after @var{limit}. Here's an example: @example @group @@ -1168,6 +1176,12 @@ comes back" twice. @end group @end example +If @var{greedy} is non-@code{nil}, this function extends the match +backwards as far as possible, stopping when a single additional +previous character cannot be part of a match for regexp. When the +match is extended, its starting position is allowed to occur before +@var{limit}. + @c http://debbugs.gnu.org/5689 As a general recommendation, try to avoid using @code{looking-back} wherever possible, since it is slow. For this reason, there are no @@ -1283,7 +1297,7 @@ If you did the last search in a buffer, you should omit the the current buffer is the one in which you performed the last search. Then this function edits the buffer, replacing the matched text with @var{replacement}. It leaves point at the end of the replacement -text, and returns @code{t}. +text. If you performed the last search on a string, pass the same string as @var{string}. Then this function returns a new string, in which the @@ -1411,8 +1425,9 @@ has no text properties. @end defun @defun match-beginning count -This function returns the position of the start of the text matched by the -last regular expression searched for, or a subexpression of it. +If the last regular expression search found a match, this function +returns the position of the start of the matching text or of a +subexpression of it. If @var{count} is zero, then the value is the position of the start of the entire match. Otherwise, @var{count} specifies a subexpression in @@ -1744,7 +1759,7 @@ in two ways: @itemize @bullet @item -The ``key bindings'' are not commands, just symbols that are meaningful +The key bindings are not commands, just symbols that are meaningful to the functions that use this map. @item @@ -1755,7 +1770,7 @@ event and look it up ``by hand''. @end itemize @end defvar -Here are the meaningful ``bindings'' for @code{query-replace-map}. +Here are the meaningful bindings for @code{query-replace-map}. Several of them are meaningful only for @code{query-replace} and friends. @@ -1772,7 +1787,7 @@ questions, assuming that the answers will be ``no''. @item exit-prefix Like @code{exit}, but add the key that was pressed to -@code{unread-comment-events}. +@code{unread-command-events} (@pxref{Event Input Misc}). @item act-and-exit Answer this question ``yes'', and give up on the entire series of @@ -1820,7 +1835,7 @@ Display some help, then ask again. @defvar multi-query-replace-map This variable holds a keymap that extends @code{query-replace-map} by providing additional keybindings that are useful in multi-buffer -replacements. The additional ``bindings'' are: +replacements. The additional bindings are: @table @code @item automatic-all diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 00384de7ec8..84a7c325424 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Sequences Arrays Vectors @@ -72,6 +72,7 @@ string, bool-vector, or char-table, @code{nil} otherwise. @cindex vector length @cindex sequence length @cindex char-table length +@anchor{Definition of length} This function returns the number of elements in @var{sequence}. If @var{sequence} is a dotted list, a @code{wrong-type-argument} error is signaled. Circular lists may cause an infinite loop. For a @@ -107,12 +108,13 @@ Emacs character code. @noindent See also @code{string-bytes}, in @ref{Text Representations}. -If you need to compute the width of a string on display, you should -use @code{string-width} (@pxref{Width}), not @code{length}, since -@code{length} only counts the number of characters, but does not +If you need to compute the width of a string on display, you should use +@code{string-width} (@pxref{Size of Displayed Text}), not @code{length}, +since @code{length} only counts the number of characters, but does not account for the display width of each character. @defun elt sequence index +@anchor{Definition of elt} @cindex elements of sequences This function returns the element of @var{sequence} indexed by @var{index}. Legitimate values of @var{index} are integers ranging @@ -217,6 +219,794 @@ y @result{} [foo (69 2)] @end example @end defun +@defun reverse sequence +@cindex string reverse +@cindex list reverse +@cindex vector reverse +@cindex sequence reverse +This function creates a new sequence whose elements are the elements +of @var{sequence}, but in reverse order. The original argument @var{sequence} +is @emph{not} altered. Note that char-tables cannot be reversed. + +@example +@group +(setq x '(1 2 3 4)) + @result{} (1 2 3 4) +@end group +@group +(reverse x) + @result{} (4 3 2 1) +x + @result{} (1 2 3 4) +@end group +@group +(setq x [1 2 3 4]) + @result{} [1 2 3 4] +@end group +@group +(reverse x) + @result{} [4 3 2 1] +x + @result{} [1 2 3 4] +@end group +@group +(setq x "xyzzy") + @result{} "xyzzy" +@end group +@group +(reverse x) + @result{} "yzzyx" +x + @result{} "xyzzy" +@end group +@end example +@end defun + +@defun nreverse sequence +@cindex reversing a string +@cindex reversing a list +@cindex reversing a vector + This function reverses the order of the elements of @var{sequence}. +Unlike @code{reverse} the original @var{sequence} may be modified. + + For example: + +@example +@group +(setq x '(a b c)) + @result{} (a b c) +@end group +@group +x + @result{} (a b c) +(nreverse x) + @result{} (c b a) +@end group +@group +;; @r{The cons cell that was first is now last.} +x + @result{} (a) +@end group +@end example + + To avoid confusion, we usually store the result of @code{nreverse} +back in the same variable which held the original list: + +@example +(setq x (nreverse x)) +@end example + + Here is the @code{nreverse} of our favorite example, @code{(a b c)}, +presented graphically: + +@smallexample +@group +@r{Original list head:} @r{Reversed list:} + ------------- ------------- ------------ +| car | cdr | | car | cdr | | car | cdr | +| a | nil |<-- | b | o |<-- | c | o | +| | | | | | | | | | | | | + ------------- | --------- | - | -------- | - + | | | | + ------------- ------------ +@end group +@end smallexample + + For the vector, it is even simpler because you don't need setq: + +@example +(setq x [1 2 3 4]) + @result{} [1 2 3 4] +(nreverse x) + @result{} [4 3 2 1] +x + @result{} [4 3 2 1] +@end example + +Note that unlike @code{reverse}, this function doesn't work with strings. +Although you can alter string data by using @code{aset}, it is strongly +encouraged to treat strings as immutable. + +@end defun + +@defun sort sequence predicate +@cindex stable sort +@cindex sorting lists +@cindex sorting vectors +This function sorts @var{sequence} stably. Note that this function doesn't work +for all sequences; it may be used only for lists and vectors. If @var{sequence} +is a list, it is modified destructively. This functions returns the sorted +@var{sequence} and compares elements using @var{predicate}. A stable sort is +one in which elements with equal sort keys maintain their relative order before +and after the sort. Stability is important when successive sorts are used to +order elements according to different criteria. + +The argument @var{predicate} must be a function that accepts two +arguments. It is called with two elements of @var{sequence}. To get an +increasing order sort, the @var{predicate} should return non-@code{nil} if the +first element is ``less'' than the second, or @code{nil} if not. + +The comparison function @var{predicate} must give reliable results for +any given pair of arguments, at least within a single call to +@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is +less than @var{b}, @var{b} must not be less than @var{a}. It must be +@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} +is less than @var{c}, then @var{a} must be less than @var{c}. If you +use a comparison function which does not meet these requirements, the +result of @code{sort} is unpredictable. + +The destructive aspect of @code{sort} for lists is that it rearranges the +cons cells forming @var{sequence} by changing @sc{cdr}s. A nondestructive +sort function would create new cons cells to store the elements in their +sorted order. If you wish to make a sorted copy without destroying the +original, copy it first with @code{copy-sequence} and then sort. + +Sorting does not change the @sc{car}s of the cons cells in @var{sequence}; +the cons cell that originally contained the element @code{a} in +@var{sequence} still has @code{a} in its @sc{car} after sorting, but it now +appears in a different position in the list due to the change of +@sc{cdr}s. For example: + +@example +@group +(setq nums '(1 3 2 6 5 4 0)) + @result{} (1 3 2 6 5 4 0) +@end group +@group +(sort nums '<) + @result{} (0 1 2 3 4 5 6) +@end group +@group +nums + @result{} (1 2 3 4 5 6) +@end group +@end example + +@noindent +@strong{Warning}: Note that the list in @code{nums} no longer contains +0; this is the same cons cell that it was before, but it is no longer +the first one in the list. Don't assume a variable that formerly held +the argument now holds the entire sorted list! Instead, save the result +of @code{sort} and use that. Most often we store the result back into +the variable that held the original list: + +@example +(setq nums (sort nums '<)) +@end example + +For the better understanding of what stable sort is, consider the following +vector example. After sorting, all items whose @code{car} is 8 are grouped +at the beginning of @code{vector}, but their relative order is preserved. +All items whose @code{car} is 9 are grouped at the end of @code{vector}, +but their relative order is also preserved: + +@example +@group +(setq + vector + (vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz") + '(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff"))) + @result{} [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz") + (9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")] +@end group +@group +(sort vector (lambda (x y) (< (car x) (car y)))) + @result{} [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee") + (9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")] +@end group +@end example + +@xref{Sorting}, for more functions that perform sorting. +See @code{documentation} in @ref{Accessing Documentation}, for a +useful example of @code{sort}. +@end defun + +@cindex sequence functions in seq +@cindex seq library + The @file{seq.el} library provides the following additional sequence +manipulation macros and functions, prefixed with @code{seq-}. To use +them, you must first load the @file{seq} library. + + All functions defined in this library are free of side-effects; +i.e., they do not modify any sequence (list, vector, or string) that +you pass as an argument. Unless otherwise stated, the result is a +sequence of the same type as the input. For those functions that take +a predicate, this should be a function of one argument. + + The @file{seq.el} library can be extended to work with additional +types of sequential data-structures. For that purpose, all functions +are defined using @code{cl-defgeneric}. + +@defun seq-elt sequence index + This function the element at the index @var{index} in +@var{sequence}. @var{index} can be an integer from zero up to the +length of @var{sequence} minus one. For out-of-range values on +built-in sequence types, @code{seq-elt} behaves like @code{elt}. +@xref{Definition of elt}. + +@example +@group +(seq-elt [1 2 3 4] 2) +@result{} 3 +@end group + + @code{seq-elt} returns settable places using @code{setf}. + +@group +(setq vec [1 2 3 4]) +(setf (seq-elt vec 2) 5) +vec +@result{} [1 2 5 4] +@end group +@end example +@end defun + +@defun seq-length sequence + This function returns the number of elements in @var{sequence}. For +built-in sequence types, @code{seq-length} behaves like @code{length}. +@xref{Definition of length}. +@end defun + +@defun seq-p sequence + This function returns non-@code{nil} if @var{sequence} is a sequence +(a list or array), or any additional type of sequence defined via +@file{seq.el} generic functions. + +@example +@group +(seq-p [1 2]) +@result{} t +@end group +@group +(seq-p 2) +@result{} nil +@end group +@end example +@end defun + +@defun seq-drop sequence n + This function returns all but the first @var{n} (an integer) +elements of @var{sequence}. If @var{n} is negative or zero, +the result is @var{sequence}. + +@example +@group +(seq-drop [1 2 3 4 5 6] 3) +@result{} [4 5 6] +@end group +@group +(seq-drop "hello world" -4) +@result{} "hello world" +@end group +@end example +@end defun + +@defun seq-take sequence n + This function returns the first @var{n} (an integer) elements of +@var{sequence}. If @var{n} is negative or zero, the result +is @code{nil}. + +@example +@group +(seq-take '(1 2 3 4) 3) +@result{} (1 2 3) +@end group +@group +(seq-take [1 2 3 4] 0) +@result{} [] +@end group +@end example +@end defun + +@defun seq-take-while predicate sequence + This function returns the members of @var{sequence} in order, +stopping before the first one for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2)) +@result{} (1 2 3) +@end group +@group +(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6]) +@result{} [] +@end group +@end example +@end defun + +@defun seq-drop-while predicate sequence + This function returns the members of @var{sequence} in order, +starting from the first one for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2)) +@result{} (-1 -2) +@end group +@group +(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6]) +@result{} [1 4 6] +@end group +@end example +@end defun + +@defun seq-do function sequence + This function applies @var{function} to each element of +@var{sequence} in turn (presumably for side effects) and returns +@var{sequence}. +@end defun + +@defun seq-map function sequence + This function returns the result of applying @var{function} to each +element of @var{sequence}. The returned value is a list. + +@example +@group +(seq-map #'1+ '(2 4 6)) +@result{} (3 5 7) +@end group +@group +(seq-map #'symbol-name [foo bar]) +@result{} ("foo" "bar") +@end group +@end example +@end defun + +@defun seq-mapn function &rest sequences + This function returns the result of applying @var{function} to each +element of @var{sequences}. The arity of @var{function} must match +the number of sequences. Mapping stops at the shortest sequence, and +the returned value is a list. + +@example +@group +(seq-mapn #'+ '(2 4 6) '(20 40 60)) +@result{} (22 44 66) +@end group +@group +(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"]) +@result{} ("moskitobee" "bitesting") +@end group +@end example +@end defun + +@defun seq-filter predicate sequence +@cindex filtering sequences + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns non-@code{nil}. + +@example +@group +(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5]) +@result{} (1 3 5) +@end group +@group +(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5)) +@result{} nil +@end group +@end example +@end defun + +@defun seq-remove predicate sequence +@cindex removing from sequences + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5]) +@result{} (-1 -3) +@end group +@group +(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5)) +@result{} nil +@end group +@end example +@end defun + +@defun seq-reduce function sequence initial-value +@cindex reducing sequences + This function returns the result of calling @var{function} with +@var{initial-value} and the first element of @var{sequence}, then calling +@var{function} with that result and the second element of @var{sequence}, +then with that result and the third element of @var{sequence}, etc. +@var{function} should be a function of two arguments. If +@var{sequence} is empty, this returns @var{initial-value} without +calling @var{function}. + +@example +@group +(seq-reduce #'+ [1 2 3 4] 0) +@result{} 10 +@end group +@group +(seq-reduce #'+ '(1 2 3 4) 5) +@result{} 15 +@end group +@group +(seq-reduce #'+ '() 3) +@result{} 3 +@end group +@end example +@end defun + +@defun seq-some predicate sequence + This function returns the first non-@code{nil} value returned by +applying @var{predicate} to each element of @var{sequence} in turn. + +@example +@group +(seq-some #'numberp ["abc" 1 nil]) +@result{} t +@end group +@group +(seq-some #'numberp ["abc" "def"]) +@result{} nil +@end group +@group +(seq-some #'null ["abc" 1 nil]) +@result{} t +@end group +@group +(seq-some #'1+ [2 4 6]) +@result{} 3 +@end group +@end example +@end defun + +@defun seq-find predicate sequence &optional default + This function returns the first element for which @var{predicate} +returns non-@code{nil} in @var{sequence}. If no element matches +@var{predicate}, @var{default} is returned. + +Note that this function has an ambiguity if the found element is +identical to @var{default}, as it cannot be known if an element was +found or not. + +@example +@group +(seq-find #'numberp ["abc" 1 nil]) +@result{} 1 +@end group +@group +(seq-find #'numberp ["abc" "def"]) +@result{} nil +@end group +@end example +@end defun + +@defun seq-every-p predicate sequence + This function returns non-@code{nil} if applying @var{predicate} +to every element of @var{sequence} returns non-@code{nil}. + +@example +@group +(seq-every-p #'numberp [2 4 6]) +@result{} t +@end group +@group +(seq-some #'numberp [2 4 "6"]) +@result{} nil +@end group +@end example +@end defun + +@defun seq-empty-p sequence + This function returns non-@code{nil} if @var{sequence} is empty. + +@example +@group +(seq-empty-p "not empty") +@result{} nil +@end group +@group +(seq-empty-p "") +@result{} t +@end group +@end example +@end defun + +@defun seq-count predicate sequence + This function returns the number of elements in @var{sequence} for which +@var{predicate} returns non-@code{nil}. + +@example +(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2]) +@result{} 2 +@end example +@end defun + +@cindex sorting sequences +@defun seq-sort function sequence + This function returns a copy of @var{sequence} that is sorted +according to @var{function}, a function of two arguments that returns +non-@code{nil} if the first argument should sort before the second. +@end defun + +@defun seq-contains sequence elt &optional function + This function returns the first element in @var{sequence} that is equal to +@var{elt}. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. + +@example +@group +(seq-contains '(symbol1 symbol2) 'symbol1) +@result{} symbol1 +@end group +@group +(seq-contains '(symbol1 symbol2) 'symbol3) +@result{} nil +@end group +@end example + +@end defun + +@defun seq-position sequence elt &optional function + This function returns the index of the first element in +@var{sequence} that is equal to @var{elt}. If the optional argument +@var{function} is non-@code{nil}, it is a function of two arguments to +use instead of the default @code{equal}. + +@example +@group +(seq-position '(a b c) 'b) +@result{} 1 +@end group +@group +(seq-position '(a b c) 'd) +@result{} nil +@end group +@end example +@end defun + + +@defun seq-uniq sequence &optional function + This function returns a list of the elements of @var{sequence} with +duplicates removed. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. + +@example +@group +(seq-uniq '(1 2 2 1 3)) +@result{} (1 2 3) +@end group +@group +(seq-uniq '(1 2 2.0 1.0) #'=) +@result{} [3 4] +@end group +@end example +@end defun + +@defun seq-subseq sequence start &optional end + This function returns a subset of @var{sequence} from @var{start} +to @var{end}, both integers (@var{end} defaults to the last element). +If @var{start} or @var{end} is negative, it counts from the end of +@var{sequence}. + +@example +@group +(seq-subseq '(1 2 3 4 5) 1) +@result{} (2 3 4 5) +@end group +@group +(seq-subseq '[1 2 3 4 5] 1 3) +@result{} [2 3] +@end group +@group +(seq-subseq '[1 2 3 4 5] -3 -1) +@result{} [3 4] +@end group +@end example +@end defun + +@defun seq-concatenate type &rest sequences + This function returns a sequence of type @var{type} made of the +concatenation of @var{sequences}. @var{type} may be: @code{vector}, +@code{list} or @code{string}. + +@example +@group +(seq-concatenate 'list '(1 2) '(3 4) [5 6]) +@result{} (1 2 3 5 6) +@end group +@group +(seq-concatenate 'string "Hello " "world") +@result{} "Hello world" +@end group +@end example +@end defun + +@defun seq-mapcat function sequence &optional type + This function returns the result of applying @code{seq-concatenate} +to the result of applying @var{function} to each element of +@var{sequence}. The result is a sequence of type @var{type}, or a +list if @var{type} is @code{nil}. + +@example +@group +(seq-mapcat #'seq-reverse '((3 2 1) (6 5 4))) +@result{} (1 2 3 4 5 6) +@end group +@end example +@end defun + +@defun seq-partition sequence n + This function returns a list of the elements of @var{sequence} +grouped into sub-sequences of length @var{n}. The last sequence may +contain less elements than @var{n}. @var{n} must be an integer. If +@var{n} is a negative integer or 0, nil is returned. + +@example +@group +(seq-partition '(0 1 2 3 4 5 6 7) 3) +@result{} ((0 1 2) (3 4 5) (6 7)) +@end group +@end example +@end defun + +@defun seq-intersection sequence1 sequence2 &optional function + This function returns a list of the elements that appear both in +@var{sequence1} and @var{sequence2}. If the optional argument +@var{function} is non-@code{nil}, it is a function of two arguments to +use to compare elements instead of the default @code{equal}. + +@example +@group +(seq-intersection [2 3 4 5] [1 3 5 6 7]) +@result{} (3 5) +@end group +@end example +@end defun + + +@defun seq-difference sequence1 sequence2 &optional function + This function returns a list of the elements that appear in +@var{sequence1} but not in @var{sequence2}. If the optional argument +@var{function} is non-@code{nil}, it is a function of two arguments to +use to compare elements instead of the default @code{equal}. + +@example +@group +(seq-difference '(2 3 4 5) [1 3 5 6 7]) +@result{} (2 4) +@end group +@end example +@end defun + +@defun seq-group-by function sequence + This function separates the elements of @var{sequence} into an alist +whose keys are the result of applying @var{function} to each element +of @var{sequence}. Keys are compared using @code{equal}. + +@example +@group +(seq-group-by #'integerp '(1 2.1 3 2 3.2)) +@result{} ((t 1 3 2) (nil 2.1 3.2)) +@end group +@group +(seq-group-by #'car '((a 1) (b 2) (a 3) (c 4))) +@result{} ((b (b 2)) (a (a 1) (a 3)) (c (c 4))) +@end group +@end example +@end defun + +@defun seq-into sequence type + This function converts the sequence @var{sequence} into a sequence +of type @var{type}. @var{type} can be one of the following symbols: +@code{vector}, @code{string} or @code{list}. + +@example +@group +(seq-into [1 2 3] 'list) +@result{} (1 2 3) +@end group +@group +(seq-into nil 'vector) +@result{} [] +@end group +@group +(seq-into "hello" 'vector) +@result{} [104 101 108 108 111] +@end group +@end example +@end defun + +@defun seq-min sequence + This function returns the smallest element of +@var{sequence}. @var{sequence} must be a sequence of numbers or +markers. + +@example +@group +(seq-min [3 1 2]) +@result{} 1 +@end group +@group +(seq-min "Hello") +@result{} 72 +@end group +@end example +@end defun + +@defun seq-max sequence + This function returns the largest element of +@var{sequence}. @var{sequence} must be a sequence of numbers or +markers. + +@example +@group +(seq-max [1 3 2]) +@result{} 3 +@end group +@group +(seq-max "Hello") +@result{} 111 +@end group +@end example +@end defun + +@defmac seq-doseq (var sequence) body@dots{} +@cindex sequence iteration + This macro is like @code{dolist}, except that @var{sequence} can be a list, +vector or string (@pxref{Iteration} for more information about the +@code{dolist} macro). This is primarily useful for side-effects. +@end defmac + +@defmac seq-let arguments sequence body@dots{} +@cindex sequence destructuring + This macro binds the variables defined in @var{arguments} to the +elements of the sequence @var{sequence}. @var{arguments} can itself +include sequences allowing for nested destructuring. + +The @var{arguments} sequence can also include the @code{&rest} marker +followed by a variable name to be bound to the rest of +@code{sequence}. + +@example +@group +(seq-let [first second] [1 2 3 4] + (list first second)) +@result{} (1 2) +@end group +@group +(seq-let (_ a _ b) '(1 2 3 4) + (list a b)) +@result{} (2 4) +@end group +@group +(seq-let [a [b [c]]] [1 [2 [3]]] + (list a b c)) +@result{} (1 2 3) +@end group +@group +(seq-let [a b &rest others] [1 2 3 4] + others) +@end group +@result{} [3 4] +@end example +@end defmac + + @node Arrays @section Arrays @cindex array @@ -471,11 +1261,11 @@ each initialized to @var{object}. @cindex copying vectors This function returns a new vector containing all the elements of @var{sequences}. The arguments @var{sequences} may be true lists, -vectors, strings or bool-vectors. If no @var{sequences} are given, an -empty vector is returned. +vectors, strings or bool-vectors. If no @var{sequences} are given, +the empty vector is returned. -The value is a newly constructed vector that is not @code{eq} to any -existing vector. +The value is either the empty vector, or is a newly constructed +nonempty vector that is not @code{eq} to any existing vector. @example @group @@ -600,13 +1390,13 @@ This function sets the parent of @var{char-table} to @var{new-parent}. @end defun @defun char-table-extra-slot char-table n -This function returns the contents of extra slot @var{n} of -@var{char-table}. The number of extra slots in a char-table is +This function returns the contents of extra slot @var{n} (zero based) +of @var{char-table}. The number of extra slots in a char-table is determined by its subtype. @end defun @defun set-char-table-extra-slot char-table n value -This function stores @var{value} in extra slot @var{n} of +This function stores @var{value} in extra slot @var{n} (zero based) of @var{char-table}. @end defun @@ -699,7 +1489,7 @@ value into an element of the bool-vector, the effect is to store and the length cannot be changed once the bool-vector is created. Bool-vectors are constants when evaluated. - There are two special functions for working with bool-vectors; aside + Several functions work specifically with bool-vectors; aside from that, you manipulate them with same functions used for other kinds of arrays. @@ -708,14 +1498,87 @@ Return a new bool-vector of @var{length} elements, each one initialized to @var{initial}. @end defun +@defun bool-vector &rest objects +This function creates and returns a bool-vector whose elements are the +arguments, @var{objects}. +@end defun + @defun bool-vector-p object This returns @code{t} if @var{object} is a bool-vector, and @code{nil} otherwise. @end defun - Here is an example of creating, examining, and updating a -bool-vector. Note that the printed form represents up to 8 boolean -values as a single character. +There are also some bool-vector set operation functions, described below: + +@defun bool-vector-exclusive-or a b &optional c +Return @dfn{bitwise exclusive or} of bool vectors @var{a} and @var{b}. +If optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-union a b &optional c +Return @dfn{bitwise or} of bool vectors @var{a} and @var{b}. If +optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-intersection a b &optional c +Return @dfn{bitwise and} of bool vectors @var{a} and @var{b}. If +optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-set-difference a b &optional c +Return @dfn{set difference} of bool vectors @var{a} and @var{b}. If +optional argument @var{c} is given, the result of this operation is +stored into @var{c}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-not a &optional b +Return @dfn{set complement} of bool vector @var{a}. If optional +argument @var{b} is given, the result of this operation is stored into +@var{b}. All arguments should be bool vectors of the same length. +@end defun + +@defun bool-vector-subsetp a b +Return @code{t} if every @code{t} value in @var{a} is also t in +@var{b}, @code{nil} otherwise. All arguments should be bool vectors of the +same length. +@end defun + +@defun bool-vector-count-consecutive a b i +Return the number of consecutive elements in @var{a} equal @var{b} +starting at @var{i}. @code{a} is a bool vector, @var{b} is @code{t} +or @code{nil}, and @var{i} is an index into @code{a}. +@end defun + +@defun bool-vector-count-population a +Return the number of elements that are @code{t} in bool vector @var{a}. +@end defun + + The printed form represents up to 8 boolean values as a single +character: + +@example +@group +(bool-vector t nil t nil) + @result{} #&4"^E" +(bool-vector) + @result{} #&0"" +@end group +@end example + +You can use @code{vconcat} to print a bool-vector like other vectors: + +@example +@group +(vconcat (bool-vector nil t nil t)) + @result{} [nil t nil t] +@end group +@end example + + Here is another example of creating, examining, and updating a +bool-vector: @example (setq bv (make-bool-vector 5 t)) @@ -741,7 +1604,7 @@ deletion, rotation, and modulo-indexed reference and traversal. An efficient ring data structure is implemented by the @code{ring} package. It provides the functions listed in this section. - Note that several ``rings'' in Emacs, like the kill ring and the + Note that several rings in Emacs, like the kill ring and the mark ring, are actually implemented as simple lists, @emph{not} using the @code{ring} package; thus the following functions won't work on them. diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 5b7e833b235..025b0e95c4e 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1994, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Read and Print @@ -113,8 +113,8 @@ When it is called with no arguments, it should return the next character. When it is called with one argument (always a character), @var{function} should save the argument and arrange to return it on the next call. This is called @dfn{unreading} the character; it happens when the Lisp -reader reads one character too many and wants to ``put it back where it -came from''. In this case, it makes no difference what value +reader reads one character too many and wants to put it back where it +came from. In this case, it makes no difference what value @var{function} returns. @end itemize @@ -339,6 +339,25 @@ shared structures. @xref{Circular Objects}. Its default value is @code{t}. @end defvar +@cindex binary I/O in batch mode +When reading or writing from the standard input/output streams of the +Emacs process in batch mode, it is sometimes required to make sure any +arbitrary binary data will be read/written verbatim, and/or that no +translation of newlines to or from CR-LF pairs are performed. This +issue does not exist on Posix hosts, only on MS-Windows and MS-DOS@. +The following function allows to control the I/O mode of any standard +stream of the Emacs process. + +@defun set-binary-mode stream mode +Switch @var{stream} into binary or text I/O mode. If @var{mode} is +non-@code{nil}, switch to binary mode, otherwise switch to text mode. +The value of @var{stream} can be one of @code{stdin}, @code{stdout}, +or @code{stderr}. This function flushes any pending output data of +@var{stream} as a side effect, and returns the previous value of I/O +mode for @var{stream}. On Posix hosts, it always returns a +non-@code{nil} value and does nothing except flushing pending output. +@end defun + @node Output Streams @section Output Streams @cindex stream (for printing) @@ -615,10 +634,13 @@ spacing between calls. @end example @end defun -@defun terpri &optional stream +@defun terpri &optional stream ensure @cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print''. +This function outputs a newline to @var{stream}. The name stands for +``terminate print''. If @var{ensure} is non-@code{nil} no newline is printed +if @var{stream} is already at the beginning of a line. Note in this +case @var{stream} can not be a function and an error is signalled if +it is. This function returns @code{t} if a newline is printed. @end defun @defun write-char character &optional stream @@ -679,10 +701,15 @@ returns @code{"The buffer is foo"}. @defun pp object &optional stream This function outputs @var{object} to @var{stream}, just like -@code{prin1}, but does it in a more ``pretty'' way. That is, it'll +@code{prin1}, but does it in a prettier way. That is, it'll indent and fill the object to make it more readable for humans. @end defun +If you need to use binary I/O in batch mode, e.g., use the functions +described in this section to write out arbitrary binary data or avoid +conversion of newlines on non-Posix hosts, see @ref{Input Functions, +set-binary-mode}. + @node Output Variables @section Variables Affecting Output @cindex output-controlling variables @@ -824,7 +851,7 @@ to bind it to @code{nil} when you bind @code{print-continuous-numbering}. @end defvar @defvar float-output-format -This variable specifies how to print floating point numbers. The +This variable specifies how to print floating-point numbers. The default is @code{nil}, meaning use the shortest output that represents the number without losing information. diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 340115062f9..143de82d9ad 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Strings and Characters @@ -48,13 +48,13 @@ Vectors}). Unlike in C, Emacs Lisp strings are @emph{not} terminated by a distinguished character code. Since strings are arrays, and therefore sequences as well, you can -operate on them with the general array and sequence functions -documented in @ref{Sequences Arrays Vectors}. For example, you can -access or change individual characters in a string using the functions -@code{aref} and @code{aset} (@pxref{Array Functions}). However, note -that @code{length} should @emph{not} be used for computing the width -of a string on display; use @code{string-width} (@pxref{Width}) -instead. +operate on them with the general array and sequence functions documented +in @ref{Sequences Arrays Vectors}. For example, you can access or +change individual characters in a string using the functions @code{aref} +and @code{aset} (@pxref{Array Functions}). However, note that +@code{length} should @emph{not} be used for computing the width of a +string on display; use @code{string-width} (@pxref{Size of Displayed +Text}) instead. There are two text representations for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte and multibyte. @@ -92,6 +92,8 @@ representations and to encode and decode character codes. @node Predicates for Strings @section Predicates for Strings +@cindex predicates for strings +@cindex string predicates For more information about general sequence and array predicates, see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. @@ -113,6 +115,8 @@ character (i.e., an integer), @code{nil} otherwise. @node Creating Strings @section Creating Strings +@cindex creating strings +@cindex string creation The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. @@ -268,7 +272,7 @@ string to be used as a shell command, see @ref{Shell Arguments, combine-and-quote-strings}. @end defun -@defun split-string string &optional separators omit-nulls +@defun split-string string &optional separators omit-nulls trim This function splits @var{string} into substrings based on the regular expression @var{separators} (@pxref{Regular Expressions}). Each match for @var{separators} defines a splitting point; the substrings between @@ -350,6 +354,11 @@ practice: @result{} ("o" "o" "o") @end example +If the optional argument @var{trim} is non-@code{nil}, it should be a +regular expression to match text to trim from the beginning and end of +each substring. If trimming makes the substring empty, it is treated +as null. + If you need to split a string into a list of individual command-line arguments suitable for @code{call-process} or @code{start-process}, see @ref{Shell Arguments, split-string-and-unquote}. @@ -362,6 +371,8 @@ usual value is @w{@code{"[ \f\t\n\r\v]+"}}. @node Modifying Strings @section Modifying Strings +@cindex modifying strings +@cindex string modification The most basic way to alter the contents of an existing string is with @code{aset} (@pxref{Array Functions}). @code{(aset @var{string} @@ -395,6 +406,7 @@ zeros. It may also change @var{string}'s length. @node Text Comparison @section Comparison of Characters and Strings @cindex string equality +@cindex text comparison @defun char-equal character1 character2 This function returns @code{t} if the arguments represent the same @@ -418,8 +430,10 @@ the symbol names are used. Case is always significant, regardless of This function is equivalent to @code{equal} for comparing two strings (@pxref{Equality Predicates}). In particular, the text properties of -the two strings are ignored. But if either argument is not a string -or symbol, an error is signaled. +the two strings are ignored; use @code{equal-including-properties} if +you need to distinguish between strings that differ only in their text +properties. However, unlike @code{equal}, if either argument is not a +string or symbol, @code{string=} signals an error. @example (string= "abc" "abc") @@ -451,6 +465,59 @@ Representations}. @code{string-equal} is another name for @code{string=}. @end defun +@defun string-collate-equalp string1 string2 &optional locale ignore-case +This function returns @code{t} if @var{string1} and @var{string2} are +equal with respect to collation rules. A collation rule is not only +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, characters with different coding points but +the same meaning might be considered as equal, like different grave +accent Unicode characters: + +@example +@group +(string-collate-equalp (string ?\uFF40) (string ?\u1FEF)) + @result{} t +@end group +@end example + +The optional argument @var{locale}, a string, overrides the setting of +your current locale identifier for collation. The value is system +dependent; a @var{locale} @code{"en_US.UTF-8"} is applicable on POSIX +systems, while it would be, e.g., @code{"enu_USA.1252"} on MS-Windows +systems. + +If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since +the codeset part of the locale cannot be @code{"UTF-8"} on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-equal}. + +Do @emph{not} use this function to compare file names for equality, only +for sorting them. +@end defun + +@defun string-prefix-p string1 string2 &optional ignore-case +This function returns non-@code{nil} if @var{string1} is a prefix of +@var{string2}; i.e., if @var{string2} starts with @var{string1}. If +the optional argument @var{ignore-case} is non-@code{nil}, the +comparison ignores case differences. +@end defun + +@defun string-suffix-p suffix string &optional ignore-case +This function returns non-@code{nil} if @var{suffix} is a suffix of +@var{string}; i.e., if @var{string} ends with @var{suffix}. If the +optional argument @var{ignore-case} is non-@code{nil}, the comparison +ignores case differences. +@end defun + @cindex lexical comparison @defun string< string1 string2 @c (findex string< causes problems for permuted index!!) @@ -509,6 +576,50 @@ are used. @code{string-lessp} is another name for @code{string<}. @end defun +@defun string-collate-lessp string1 string2 &optional locale ignore-case +This function returns @code{t} if @var{string1} is less than +@var{string2} in collation order. A collation order is not only +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, punctuation and whitespace characters might be considered +less significant for @ref{Sorting,,sorting}. + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp) + @result{} ("11" "1 1" "1.1" "12" "1 2" "1.2") +@end group +@end example + +The optional argument @var{locale}, a string, overrides the setting of +your current locale identifier for collation. The value is system +dependent; a @var{locale} @code{"en_US.UTF-8"} is applicable on POSIX +systems, while it would be, e.g., @code{"enu_USA.1252"} on MS-Windows +systems. The @var{locale} @code{"POSIX"} lets @code{string-collate-lessp} +behave like @code{string-lessp}: + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") + (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX"))) + @result{} ("1 1" "1 2" "1.1" "1.2" "11" "12") +@end group +@end example + +If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since +the codeset part of the locale cannot be @code{"UTF-8"} on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-lessp}. +@end defun + @defun string-prefix-p string1 string2 &optional ignore-case This function returns non-@code{nil} if @var{string1} is a prefix of @var{string2}; i.e., if @var{string2} starts with @var{string1}. If @@ -516,6 +627,13 @@ the optional argument @var{ignore-case} is non-@code{nil}, the comparison ignores case differences. @end defun +@defun string-suffix-p suffix string &optional ignore-case +This function returns non-@code{nil} if @var{suffix} is a suffix of +@var{string}; i.e., if @var{string} ends with @var{suffix}. If the +optional argument @var{ignore-case} is non-@code{nil}, the comparison +ignores case differences. +@end defun + @defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case This function compares a specified part of @var{string1} with a specified part of @var{string2}. The specified part of @var{string1} @@ -526,7 +644,7 @@ string. Likewise, the specified part of @var{string2} runs from index @var{start2} up to index @var{end2}. The strings are compared by the numeric values of their characters. -For instance, @var{str1} is considered ``smaller than'' @var{str2} if +For instance, @var{str1} is considered less than @var{str2} if its first differing character has a smaller numeric value. If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case before comparing them. Unibyte strings are converted to @@ -567,7 +685,7 @@ against a string, can be used for a kind of string comparison; see strings and integers. @code{format} (@pxref{Formatting Strings}) and @code{prin1-to-string} (@pxref{Output Functions}) can also convert Lisp objects into strings. @code{read-from-string} (@pxref{Input -Functions}) can ``convert'' a string representation of a Lisp object +Functions}) can convert a string representation of a Lisp object into an object. The functions @code{string-to-multibyte} and @code{string-to-unibyte} convert the text representation of a string (@pxref{Converting Representations}). @@ -581,9 +699,8 @@ are used primarily for making help messages. @cindex integer to string @cindex integer to decimal This function returns a string consisting of the printed base-ten -representation of @var{number}, which may be an integer or a floating -point number. The returned value starts with a minus sign if the argument is -negative. +representation of @var{number}. The returned value starts with a +minus sign if the argument is negative. @example (number-to-string 256) @@ -607,20 +724,18 @@ See also the function @code{format} in @ref{Formatting Strings}. This function returns the numeric value of the characters in @var{string}. If @var{base} is non-@code{nil}, it must be an integer between 2 and 16 (inclusive), and integers are converted in that base. -If @var{base} is @code{nil}, then base ten is used. Floating point +If @var{base} is @code{nil}, then base ten is used. Floating-point conversion only works in base ten; we have not implemented other -radices for floating point numbers, because that would be much more +radices for floating-point numbers, because that would be much more work and does not seem useful. If @var{string} looks like an integer but its value is too large to fit into a Lisp integer, -@code{string-to-number} returns a floating point result. +@code{string-to-number} returns a floating-point result. The parsing skips spaces and tabs at the beginning of @var{string}, then reads as much of @var{string} as it can interpret as a number in the given base. (On some systems it ignores other whitespace at the -beginning, not just spaces and tabs.) If the first character after -the ignored whitespace is neither a digit in the given base, nor a -plus or minus sign, nor the leading dot of a floating point number, -this function returns 0. +beginning, not just spaces and tabs.) If @var{string} cannot be +interpreted as a number, this function returns 0. @example (string-to-number "256") @@ -686,7 +801,7 @@ they appear; it is called a @dfn{format string}. Formatting is often useful for computing messages to be displayed. In fact, the functions @code{message} and @code{error} provide the same -formatting feature described here; they differ from @code{format} only +formatting feature described here; they differ from @code{format-message} only in how they use the result of formatting. @defun format string &rest objects @@ -700,6 +815,16 @@ are copied directly into the output, including their text properties, if any. @end defun +@defun format-message string &rest objects +@cindex curved quotes +@cindex curly quotes +This function acts like @code{format}, except it also converts any +curved single quotes in @var{string} as per the value of +@code{text-quoting-style}, and treats grave accent (@t{`}) and +apostrophe (@t{'}) as if they were curved single quotes. @xref{Keys +in Documentation}. +@end defun + @cindex @samp{%} in format @cindex format specification A format specification is a sequence of characters beginning with a @@ -777,15 +902,15 @@ integer. @samp{%x} uses lower case and @samp{%X} uses upper case. Replace the specification with the character which is the value given. @item %e -Replace the specification with the exponential notation for a floating -point number. +Replace the specification with the exponential notation for a +floating-point number. @item %f -Replace the specification with the decimal-point notation for a floating -point number. +Replace the specification with the decimal-point notation for a +floating-point number. @item %g -Replace the specification with notation for a floating point number, +Replace the specification with notation for a floating-point number, using either exponential notation or decimal-point notation, whichever is shorter. @@ -798,20 +923,23 @@ specification is unusual in that it does not use a value. For example, Any other format character results in an @samp{Invalid format operation} error. - Here are several examples: + Here are several examples, which assume the typical +@code{text-quoting-style} settings: @example @group -(format "The name of this buffer is %s." (buffer-name)) - @result{} "The name of this buffer is strings.texi." - -(format "The buffer object prints as %s." (current-buffer)) - @result{} "The buffer object prints as strings.texi." - (format "The octal value of %d is %o, and the hex value is %x." 18 18 18) @result{} "The octal value of 18 is 22, and the hex value is 12." + +(format-message + "The name of this buffer is ‘%s’." (buffer-name)) + @result{} "The name of this buffer is ‘strings.texi’." + +(format-message + "The buffer object prints as `%s'." (current-buffer)) + @result{} "The buffer object prints as ‘strings.texi’." @end group @end example @@ -833,7 +961,7 @@ the width specifier normally consists of spaces inserted on the left: If the width is too small, @code{format} does not truncate the object's printed representation. Thus, you can use a width to specify a minimum spacing between columns with no risk of losing information. -In the following three examples, @samp{%7s} specifies a minimum width +In the following two examples, @samp{%7s} specifies a minimum width of 7. In the first case, the string inserted in place of @samp{%7s} has only 3 letters, and needs 4 blank spaces as padding. In the second case, the string @code{"specification"} is 13 letters wide but @@ -841,12 +969,12 @@ is not truncated. @example @group -(format "The word `%7s' has %d letters in it." +(format "The word '%7s' has %d letters in it." "foo" (length "foo")) - @result{} "The word ` foo' has 3 letters in it." -(format "The word `%7s' has %d letters in it." + @result{} "The word ' foo' has 3 letters in it." +(format "The word '%7s' has %d letters in it." "specification" (length "specification")) - @result{} "The word `specification' has 13 letters in it." + @result{} "The word 'specification' has 13 letters in it." @end group @end example @@ -862,7 +990,7 @@ numbers and negative numbers use the same number of columns. They are ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if both flags are used, @samp{+} takes precedence. - The flag @samp{#} specifies an ``alternate form'' which depends on + The flag @samp{#} specifies an alternate form which depends on the format in use. For @samp{%o}, it ensures that the result begins with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, @@ -885,12 +1013,12 @@ ignored. (format "%06d is padded on the left with zeros" 123) @result{} "000123 is padded on the left with zeros" -(format "%-6d is padded on the right" 123) - @result{} "123 is padded on the right" +(format "'%-6d' is padded on the right" 123) + @result{} "'123 ' is padded on the right" -(format "The word `%-7s' actually has %d letters in it." +(format "The word '%-7s' actually has %d letters in it." "foo" (length "foo")) - @result{} "The word `foo ' actually has 3 letters in it." + @result{} "The word 'foo ' actually has 3 letters in it." @end group @end example @@ -1117,8 +1245,8 @@ Exits}). Some language environments modify the case conversions of @acronym{ASCII} characters; for example, in the Turkish language -environment, the @acronym{ASCII} character @samp{I} is downcased into -a Turkish ``dotless i''. This can interfere with code that requires +environment, the @acronym{ASCII} capital I is downcased into +a Turkish dotless i (@samp{ı}). This can interfere with code that requires ordinary @acronym{ASCII} case conversion, such as implementations of @acronym{ASCII}-based network protocols. In that case, use the @code{with-case-table} macro with the variable @var{ascii-case-table}, diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 82dfa0f4917..2605a3e7b5a 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Symbols @@ -176,7 +176,7 @@ cause complete confusion. @cindex obarray @cindex bucket (in obarray) When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it ``hashes'' those characters to find an index in a +of the name. Then it hashes those characters to find an index in a table called an @dfn{obarray}. Hashing is an efficient method of looking something up. For example, instead of searching a telephone book cover to cover when looking up Jan Jones, you start with the J's @@ -525,7 +525,7 @@ The value is an expression for determining whether the named menu item should be enabled in menus. @xref{Simple Menu Items}. @item mode-class -If the value is @code{special}, the named major mode is ``special''. +If the value is @code{special}, the named major mode is special. @xref{Major Mode Conventions}. @item permanent-local diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 6bbd7a3a7b7..7a984e3d87b 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Syntax Tables @@ -98,7 +98,7 @@ serves as the name of the class when you need to specify a class. Usually, this designator character is one that is often assigned that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has. Thus, -@samp{\} as a designator character always means ``escape character'' +@samp{\} as a designator character always stands for escape character syntax, regardless of whether the @samp{\} character actually has that syntax in the current syntax table. @ifnottex @@ -141,6 +141,7 @@ Internals}. @node Syntax Class Table @subsection Table of Syntax Classes +@cindex syntax class table Here is a table of syntax classes, the characters that designate them, their meanings, and examples of their use. @@ -202,7 +203,7 @@ suppressed. The Lisp modes have two string quote characters: double-quote (@samp{"}) and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it is used in Common Lisp. C also has two string quote characters: -double-quote for strings, and single-quote (@samp{'}) for character +double-quote for strings, and apostrophe (@samp{'}) for character constants. Human text has no string quote characters. We do not want quotation @@ -335,6 +336,7 @@ that this kind of comment can be nested. For a two-character comment delimiter, @samp{n} on either character makes it nestable. +@cindex comment style Emacs supports several comment styles simultaneously in any one syntax table. A comment style is a set of flags @samp{b}, @samp{c}, and @samp{n}, so there can be up to 8 different comment styles. @@ -375,7 +377,7 @@ character does not have the @samp{b} flag. @end table @item -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. +@samp{p} identifies an additional prefix character for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled according to their usual syntax classes. @@ -409,6 +411,7 @@ is not a syntax table. @end defun @deffn Command modify-syntax-entry char syntax-descriptor &optional table +@cindex syntax entry, setting This function sets the syntax entry for @var{char} according to @var{syntax-descriptor}. @var{char} must be a character, or a cons cell of the form @code{(@var{min} . @var{max})}; in the latter case, @@ -589,6 +592,8 @@ in turn, repeatedly, until they all return @code{nil}. @node Motion and Syntax @section Motion and Syntax +@cindex moving across syntax classes +@cindex skipping characters of certain syntax This section describes functions for moving across characters that have certain syntax classes. @@ -628,12 +633,14 @@ expression prefix syntax class, and characters with the @samp{p} flag. @node Parsing Expressions @section Parsing Expressions +@cindex parsing expressions +@cindex scanning expressions This section describes functions for parsing and scanning balanced expressions. We will refer to such expressions as @dfn{sexps}, following the terminology of Lisp, even though these functions can act on languages other than Lisp. Basically, a sexp is either a balanced -parenthetical grouping, a string, or a ``symbol'' (i.e., a sequence +parenthetical grouping, a string, or a symbol (i.e., a sequence of characters whose syntax is either word constituent or symbol constituent). However, characters in the expression prefix syntax class (@pxref{Syntax Class Table}) are treated as part of the sexp if @@ -647,7 +654,7 @@ higher-level functions for moving over balanced expressions. A character's syntax controls how it changes the state of the parser, rather than describing the state itself. For example, a string delimiter character toggles the parser state between -``in-string'' and ``in-code'', but the syntax of characters does not +in-string and in-code, but the syntax of characters does not directly say whether they are inside a string. For example (note that 15 is the syntax code for generic string delimiters), @@ -670,6 +677,7 @@ result, Emacs treats them as four consecutive empty string constants. @node Motion via Parsing @subsection Motion Commands Based on Parsing +@cindex motion based on parsing This section describes simple point-motion functions that operate based on parsing expressions. @@ -723,7 +731,7 @@ number of complete comments. If @var{count} comments are found as expected, with nothing except whitespace between them, it returns @code{t}; otherwise it returns @code{nil}. -This function cannot tell whether the ``comments'' it traverses are +This function cannot tell whether the comments it traverses are embedded within a string. If they look like comments, it treats them as comments. @@ -735,6 +743,7 @@ cannot exceed that many. @node Position Parse @subsection Finding the Parse State for a Position +@cindex parse state for a position For syntactic analysis, such as in indentation, often the useful thing is to compute the syntactic state corresponding to a given buffer @@ -916,6 +925,7 @@ nicely. @node Control Parsing @subsection Parameters to Control Parsing +@cindex parsing, control parameters @defvar multibyte-syntax-as-symbol If this variable is non-@code{nil}, @code{scan-sexps} treats all @@ -1057,6 +1067,7 @@ standard categories are available in all modes. the range @w{@samp{ }} to @samp{~}. You specify the name of a category when you define it with @code{define-category}. +@cindex category set The category table is actually a char-table (@pxref{Char-Tables}). The element of the category table at index @var{c} is a @dfn{category set}---a bool-vector---that indicates which categories character @var{c} @@ -1073,18 +1084,27 @@ documentation @var{docstring}, for the category table @var{table}. Here's an example of defining a new category for characters that have strong right-to-left directionality (@pxref{Bidirectional Display}) -and using it in a special category table: +and using it in a special category table. To obtain the information +about the directionality of characters, the example code uses the +@samp{bidi-class} Unicode property (@pxref{Character Properties, +bidi-class}). @example (defvar special-category-table-for-bidi + ;; Make an empty category-table. (let ((category-table (make-category-table)) - (uniprop-table (unicode-property-table-internal 'bidi-class))) + ;; Create a char-table which gives the 'bidi-class' Unicode + ;; property for each character. + (uniprop-table (unicode-property-table-internal 'bidi-class))) (define-category ?R "Characters of bidi-class R, AL, or RLO" category-table) + ;; Modify the category entry of each character whose 'bidi-class' + ;; Unicode property is R, AL, or RLO -- these have a + ;; right-to-left directionality. (map-char-table #'(lambda (key val) - (if (memq val '(R AL RLO)) - (modify-category-entry key ?R category-table))) + (if (memq val '(R AL RLO)) + (modify-category-entry key ?R category-table))) uniprop-table) category-table)) @end example diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index c4250f2f0ba..6d9d26f0ad1 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Text @chapter Text @@ -54,10 +54,11 @@ the character after point. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Transposition:: Swapping two portions of a buffer. +* Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. * Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". +* Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -161,6 +162,7 @@ the end of a line. @node Buffer Contents @section Examining Buffer Contents +@cindex buffer portion as string This section describes functions that allow a Lisp program to convert any portion of the text in the buffer into a string. @@ -218,16 +220,24 @@ This function returns the contents of the entire accessible portion of the current buffer, as a string. @end defun + If you need to make sure the resulting string, when copied to a +different location, will not change its visual appearance due to +reordering of bidirectional text, use the +@code{buffer-substring-with-bidi-context} function +(@pxref{Bidirectional Display, buffer-substring-with-bidi-context}). + @defun filter-buffer-substring start end &optional delete -This function passes the buffer text between @var{start} and @var{end} -through the filter functions specified by the wrapper hook -@code{filter-buffer-substring-functions}, and returns the result. The -obsolete variable @code{buffer-substring-filters} is also consulted. -If both of these variables are @code{nil}, the value is the unaltered -text from the buffer, i.e., what @code{buffer-substring} would -return. - -If @var{delete} is non-@code{nil}, this function deletes the text +This function filters the buffer text between @var{start} and @var{end} +using a function specified by the variable +@code{filter-buffer-substring-function}, and returns the result. + +The default filter function consults the obsolete wrapper hook +@code{filter-buffer-substring-functions}, and the obsolete variable +@code{buffer-substring-filters}. If both of these are @code{nil}, it +returns the unaltered text from the buffer, i.e., what +@code{buffer-substring} would return. + +If @var{delete} is non-@code{nil}, the function deletes the text between @var{start} and @var{end} after copying it, like @code{delete-and-extract-region}. @@ -235,20 +245,29 @@ Lisp code should use this function instead of @code{buffer-substring}, @code{buffer-substring-no-properties}, or @code{delete-and-extract-region} when copying into user-accessible data structures such as the kill-ring, X clipboard, and registers. -Major and minor modes can add functions to -@code{filter-buffer-substring-functions} to alter such text as it is -copied out of the buffer. +Major and minor modes can modify @code{filter-buffer-substring-function} +to alter such text as it is copied out of the buffer. @end defun -@c FIXME: `filter-buffer-substring-function' should be documented. +@defvar filter-buffer-substring-function +The value of this variable is a function that @code{filter-buffer-substring} +will call to do the actual work. The function receives three +arguments, the same as those of @code{filter-buffer-substring}, +which it should treat as per the documentation of that function. It +should return the filtered text (and optionally delete the source text). +@end defvar + +@noindent The following two variables are obsoleted by +@code{filter-buffer-substring-function}, but are still supported for +backward compatibility. + @defvar filter-buffer-substring-functions -This variable is a wrapper hook (@pxref{Running Hooks}), whose members -should be functions that accept four arguments: @var{fun}, -@var{start}, @var{end}, and @var{delete}. @var{fun} is a function -that takes three arguments (@var{start}, @var{end}, and @var{delete}), -and returns a string. In both cases, the @var{start}, @var{end}, and -@var{delete} arguments are the same as those of -@code{filter-buffer-substring}. +This obsolete variable is a wrapper hook, whose members should be functions +that accept four arguments: @var{fun}, @var{start}, @var{end}, and +@var{delete}. @var{fun} is a function that takes three arguments +(@var{start}, @var{end}, and @var{delete}), and returns a string. In +both cases, the @var{start}, @var{end}, and @var{delete} arguments are +the same as those of @code{filter-buffer-substring}. The first hook function is passed a @var{fun} that is equivalent to the default operation of @code{filter-buffer-substring}, i.e., it @@ -262,14 +281,12 @@ hook functions acting in sequence. @end defvar @defvar buffer-substring-filters -This variable is obsoleted by -@code{filter-buffer-substring-functions}, but is still supported for -backward compatibility. Its value should should be a list of -functions which accept a single string argument and return another -string. @code{filter-buffer-substring} passes the buffer substring to -the first function in this list, and the return value of each function -is passed to the next function. The return value of the last function -is passed to @code{filter-buffer-substring-functions}. +The value of this obsolete variable should be a list of functions +that accept a single string argument and return another string. +The default @code{filter-buffer-substring} function passes the buffer +substring to the first function in this list, and the return value of +each function is passed to the next function. The return value of the +last function is passed to @code{filter-buffer-substring-functions}. @end defvar @defun current-word &optional strict really-word @@ -333,10 +350,10 @@ This function ignores case when comparing characters if @code{case-fold-search} is non-@code{nil}. It always ignores text properties. -Suppose the current buffer contains the text @samp{foobarbar -haha!rara!}; then in this example the two substrings are @samp{rbar } -and @samp{rara!}. The value is 2 because the first substring is greater -at the second character. +Suppose you have the text @w{@samp{foobarbar haha!rara!}} in the +current buffer; then in this example the two substrings are @samp{rbar +} and @samp{rara!}. The value is 2 because the first substring is +greater at the second character. @example (compare-buffer-substrings nil 6 11 nil 16 21) @@ -495,7 +512,7 @@ non-@code{nil} and the character inserted is in the table @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 This command performs abbrev expansion if Abbrev mode is enabled and the inserted character does not have word-constituent -syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also +syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also responsible for calling @code{blink-paren-function} when the inserted character has close parenthesis syntax (@pxref{Blinking}). @@ -561,7 +578,7 @@ error; if some of the text in it is read-only, it signals a asking for any confirmation. It returns @code{nil}. Normally, deleting a large amount of text from a buffer inhibits further -auto-saving of that buffer ``because it has shrunk''. However, +auto-saving of that buffer because it has shrunk. However, @code{erase-buffer} does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text. @@ -771,6 +788,9 @@ space, or @var{n} spaces if @var{n} is specified. It returns @code{nil}. @end deffn +@c There is also cycle-spacing, but I cannot see it being useful in +@c Lisp programs, so it is not mentioned here. + @deffn Command delete-blank-lines This function deletes blank lines surrounding point. If point is on a blank line with one or more blank lines before or after it, then all but @@ -784,6 +804,19 @@ A blank line is defined as a line containing only tabs and spaces. @code{delete-blank-lines} returns @code{nil}. @end deffn +@deffn Command delete-trailing-whitespace start end +Delete trailing whitespace in the region defined by @var{start} and +@var{end}. + +This command deletes whitespace characters after the last +non-whitespace character in each line in the region. + +If this command acts on the entire buffer (i.e., if called +interactively with the mark inactive, or called from Lisp with +@var{end} @code{nil}), it also deletes all trailing lines at the end of the +buffer if the variable @code{delete-trailing-lines} is non-@code{nil}. +@end deffn + @node The Kill Ring @section The Kill Ring @cindex kill ring @@ -792,7 +825,7 @@ A blank line is defined as a line containing only tabs and spaces. it so that the user can reinsert it by @dfn{yanking}. Most of these functions have @samp{kill-} in their name. By contrast, the functions whose names start with @samp{delete-} normally do not save text for -yanking (though they can still be undone); these are ``deletion'' +yanking (though they can still be undone); these are deletion functions. Most of the kill commands are primarily for interactive use, and are @@ -813,8 +846,8 @@ that treat it as a ring. Some people think this use of the word ``kill'' is unfortunate, since it refers to operations that specifically @emph{do not} destroy the -entities ``killed''. This is in sharp contrast to ordinary life, in -which death is permanent and ``killed'' entities do not come back to +entities killed. This is in sharp contrast to ordinary life, in +which death is permanent and killed entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term ``cut ring'' makes sense to people who, in pre-computer days, used scissors and paste to cut up and rearrange manuscripts. However, it @@ -849,9 +882,9 @@ succession build up a single kill ring entry, which would be yanked as a unit; the second and subsequent consecutive kill commands add text to the entry made by the first one. - For yanking, one entry in the kill ring is designated the ``front'' of -the ring. Some yank commands ``rotate'' the ring by designating a -different element as the ``front''. But this virtual rotation doesn't + For yanking, one entry in the kill ring is designated the front of +the ring. Some yank commands rotate the ring by designating a +different element as the front. But this virtual rotation doesn't change the list itself---the most recent entry always comes first in the list. @@ -859,7 +892,7 @@ list. @subsection Functions for Killing @code{kill-region} is the usual subroutine for killing text. Any -command that calls this function is a ``kill command'' (and should +command that calls this function is a kill command (and should probably have @samp{kill} in its name). @code{kill-region} puts the newly killed text in a new element at the beginning of the kill ring or adds it to the most recent element. It determines automatically (using @@ -1068,7 +1101,7 @@ because they take care of interaction with window system selections @defun current-kill n &optional do-not-move The function @code{current-kill} rotates the yanking pointer, which -designates the ``front'' of the kill ring, by @var{n} places (from newer +designates the front of the kill ring, by @var{n} places (from newer kills to older ones), and returns the text at that place in the ring. If the optional second argument @var{do-not-move} is non-@code{nil}, @@ -1115,13 +1148,13 @@ programs, when you are using a window system. Its value should be @code{nil} or a function of no arguments. If the value is a function, @code{current-kill} calls it to get the -``most recent kill''. If the function returns a non-@code{nil} value, -then that value is used as the ``most recent kill''. If it returns +most recent kill. If the function returns a non-@code{nil} value, +then that value is used as the most recent kill. If it returns @code{nil}, then the front of the kill ring is used. To facilitate support for window systems that support multiple selections, this function may also return a list of strings. In that -case, the first string is used as the ``most recent kill'', and all +case, the first string is used as the most recent kill, and all the other strings are pushed onto the kill ring, for easy access by @code{yank-pop}. @@ -1153,7 +1186,7 @@ of the list. The @code{kill-ring-yank-pointer} variable points to a link in the kill ring list, whose @sc{car} is the text to yank next. We say it -identifies the ``front'' of the ring. Moving +identifies the front of the ring. Moving @code{kill-ring-yank-pointer} to a different link is called @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because the functions that move the yank pointer wrap around from the end of the @@ -1205,7 +1238,7 @@ killed first. @defvar kill-ring-yank-pointer This variable's value indicates which element of the kill ring is at the -``front'' of the ring for yanking. More precisely, the value is a tail +front of the ring for yanking. More precisely, the value is a tail of the value of @code{kill-ring}, and its @sc{car} is the kill string that @kbd{C-y} should yank. @end defvar @@ -1253,7 +1286,8 @@ This kind of element indicates how to reinsert text that was deleted. The deleted text itself is the string @var{text}. The place to reinsert it is @code{(abs @var{position})}. If @var{position} is positive, point was at the beginning of the deleted text, otherwise it -was at the end. +was at the end. Zero or more (@var{marker} . @var{adjustment}) +elements follow immediately after this element. @item (t . @var{time-flag}) This kind of element indicates that an unmodified buffer became @@ -1279,8 +1313,10 @@ Here's how you might undo the change: @item (@var{marker} . @var{adjustment}) This kind of element records the fact that the marker @var{marker} was relocated due to deletion of surrounding text, and that it moved -@var{adjustment} character positions. Undoing this element moves -@var{marker} @minus{} @var{adjustment} characters. +@var{adjustment} character positions. If the marker's location is +consistent with the (@var{text} . @var{position}) element preceding it +in the undo list, then undoing this element moves @var{marker} +@minus{} @var{adjustment} characters. @item (apply @var{funname} . @var{args}) This is an extensible undo item, which is undone by calling @@ -1387,7 +1423,7 @@ cannot specify any other buffer. This function returns @code{nil}. As editing continues, undo lists get longer and longer. To prevent them from using up all available memory space, garbage collection trims -them back to size limits you can set. (For this purpose, the ``size'' +them back to size limits you can set. (For this purpose, the size of an undo list measures the cons cells that make up the list, plus the strings of deleted text.) Three variables control the range of acceptable sizes: @code{undo-limit}, @code{undo-strong-limit} and @@ -1612,8 +1648,8 @@ Manual}. @defvar use-hard-newlines If this variable is non-@code{nil}, the filling functions do not delete -newlines that have the @code{hard} text property. These ``hard -newlines'' act as paragraph separators. @xref{Hard and Soft +newlines that have the @code{hard} text property. These hard +newlines act as paragraph separators. @xref{Hard and Soft Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. @end defvar @@ -1701,7 +1737,7 @@ is value of @code{indent-line-function} in Paragraph-Indent Text mode. @defopt left-margin This variable specifies the base left margin column. In Fundamental -mode, @kbd{C-j} indents to this column. This variable automatically +mode, @kbd{RET} indents to this column. This variable automatically becomes buffer-local when set in any fashion. @end defopt @@ -1787,7 +1823,7 @@ Used only in one-line paragraphs, this regular expression acts as an additional check of the validity of the one available candidate fill prefix: the candidate must match this regular expression, or match @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} -replaces the candidate with a string of spaces ``of the same width'' +replaces the candidate with a string of spaces of the same width as it. The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which @@ -1800,7 +1836,7 @@ whitespace. You can specify more complex ways of choosing a fill prefix automatically by setting this variable to a function. The function is called with point after the left margin (if any) of a line, and it -must preserve point. It should return either ``that line's'' fill +must preserve point. It should return either that line's fill prefix or @code{nil}, meaning it has failed to determine a prefix. @end defopt @@ -2185,7 +2221,7 @@ count from zero at the left margin. This section describes the primitive functions used to count and insert indentation. The functions in the following sections use these -primitives. @xref{Width}, for related functions. +primitives. @xref{Size of Displayed Text}, for related functions. @defun current-indentation @comment !!Type Primitive Function @@ -2344,21 +2380,19 @@ a different meaning and does not use this variable. @end defvar @deffn Command indent-rigidly start end count -This command indents all lines starting between @var{start} +This function indents all lines starting between @var{start} (inclusive) and @var{end} (exclusive) sideways by @var{count} columns. -This ``preserves the shape'' of the affected region, moving it as a -rigid unit. Consequently, this command is useful not only for indenting -regions of unindented text, but also for indenting regions of formatted -code. +This preserves the shape of the affected region, moving it as a +rigid unit. -For example, if @var{count} is 3, this command adds 3 columns of -indentation to each of the lines beginning in the region specified. +This is useful not only for indenting regions of unindented text, but +also for indenting regions of formatted code. For example, if +@var{count} is 3, this command adds 3 columns of indentation to every +line that begins in the specified region. -@c FIXME: I suggest using message-indent-citation as the example, or -@c just remove this paragraph. --xfq -In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses -@code{indent-rigidly} to indent the text copied from the message being -replied to. +If called interactively with no prefix argument, this command invokes +a transient mode for adjusting indentation rigidly. @xref{Indentation +Commands,,, emacs, The GNU Emacs Manual}. @end deffn @deffn Command indent-code-rigidly start end columns &optional nochange-regexp @@ -2447,10 +2481,10 @@ column, this command does nothing. @end deffn @node Indent Tabs -@subsection Adjustable ``Tab Stops'' +@subsection Adjustable Tab Stops @cindex tabs stops for indentation - This section explains the mechanism for user-specified ``tab stops'' + This section explains the mechanism for user-specified tab stops and the mechanisms that use and set them. The name ``tab stops'' is used because the feature is similar to that of the tab stops on a typewriter. The feature works by inserting an appropriate number of @@ -2462,19 +2496,19 @@ stop feature only in a few major modes, such as Text mode. @deffn Command tab-to-tab-stop This command inserts spaces or tabs before point, up to the next tab -stop column defined by @code{tab-stop-list}. It searches the list for -an element greater than the current column number, and uses that element -as the column to indent to. It does nothing if no such element is -found. +stop column defined by @code{tab-stop-list}. @end deffn @defopt tab-stop-list -This variable is the list of tab stop columns used by -@code{tab-to-tab-stops}. The elements should be integers in increasing -order. The tab stop columns need not be evenly spaced. - -Use @kbd{M-x edit-tab-stops} to edit the location of tab stops -interactively. +This variable defines the tab stop columns used by @code{tab-to-tab-stop}. +It should be either @code{nil}, or a list of increasing integers, +which need not be evenly spaced. The list is implicitly +extended to infinity through repetition of the interval between the +last and penultimate elements (or @code{tab-width} if the list has +fewer than two elements). A value of @code{nil} means a tab stop +every @code{tab-width} columns. + +Use @kbd{M-x edit-tab-stops} to edit the location of tab stops interactively. @end defopt @node Motion by Indent @@ -2646,6 +2680,8 @@ along with the characters; this includes such diverse functions as @node Examining Properties @subsection Examining Text Properties +@cindex examining text properties +@cindex text properties, examining The simplest way to examine text properties is to ask for the value of a particular property of a particular character. For that, use @@ -2681,6 +2717,13 @@ followed by the text properties. If @var{object} is a string, only text properties are considered, since strings never have overlays. @end defun +@defun get-pos-property position prop &optional object +This function is like @code{get-char-property}, except that it pays +attention to properties' stickiness and overlays' advancement settings +instead of the property of the character at (i.e., right after) +@var{position}. +@end defun + @defun get-char-property-and-overlay position prop &optional object This is like @code{get-char-property}, but gives extra information about the overlay that the property value comes from. @@ -2730,6 +2773,8 @@ used instead. Here is an example: @node Changing Properties @subsection Changing Text Properties +@cindex changing text properties +@cindex text properties, changing The primitives for changing properties apply to a specified range of text in a buffer or string. The function @code{set-text-properties} @@ -2825,36 +2870,43 @@ Do not rely on the return value of this function. @end defun @defun add-face-text-property start end face &optional appendp object -@code{face} text attributes can be combined. If you want to make a -section both italic and green, you can either define a new face that -have those attributes, or you can add both these attributes separately -to text: +This function acts on the text between @var{start} and @var{end}, +adding the face @var{face} to the @code{face} text property. +@var{face} should be a valid value for the @code{face} property +(@pxref{Special Properties}), such as a face name or an anonymous face +(@pxref{Faces}). + +If any text in the region already has a non-@code{nil} @code{face} property, +those face(s) are retained. This function sets the @code{face} +property to a list of faces, with @var{face} as the first element (by +default) and the pre-existing faces as the remaining elements. If the +optional argument @var{append} is non-@code{nil}, @var{face} is +appended to the end of the list instead. Note that in a face list, +the first occurring value for each attribute takes precedence. + +For example, the following code would assign a italicized green face +to the text between @var{start} and @var{end}: @example (add-face-text-property @var{start} @var{end} 'italic) -(add-face-text-property @var{start} @var{end} '(:foreground "#00ff00")) +(add-face-text-property @var{start} @var{end} '(:foreground "red")) +(add-face-text-property @var{start} @var{end} '(:foreground "green")) @end example -The attribute is (by default) prepended to the list of face -attributes, and the first attribute of the same type takes -precedence. So if you have two @code{:foreground} specifications, the -first one will take effect. - -If you pass in @var{appendp}, the attribute will be appended instead -of prepended, which means that it will have no effect if there is -already an attribute of the same type. - +The optional argument @var{object}, if non-@code{nil}, specifies a +buffer or string to act on, rather than the current buffer. If +@var{object} is a string, then @var{start} and @var{end} are +zero-based indices into the string. @end defun - The easiest way to make a string with text properties -is with @code{propertize}: + The easiest way to make a string with text properties is with +@code{propertize}: @defun propertize string &rest properties -This function returns a copy of @var{string} which has the text -properties @var{properties}. These properties apply to all the -characters in the string that is returned. Here is an example that -constructs a string with a @code{face} property and a @code{mouse-face} -property: +This function returns a copy of @var{string} with the text properties +@var{properties} added. These properties apply to all the characters +in the string that is returned. Here is an example that constructs a +string with a @code{face} property and a @code{mouse-face} property: @smallexample (propertize "foo" 'face 'italic @@ -2886,6 +2938,8 @@ buffer but does not copy its properties. @node Property Search @subsection Text Property Search Functions +@cindex searching text properties +@cindex text properties, searching In typical use of text properties, most of the time several or many consecutive characters have the same value for a property. Rather than @@ -3081,6 +3135,9 @@ Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by dynamically updating the @code{face} property of characters based on the context. +The @code{add-face-text-property} function provides a convenient way +to set this text property. @xref{Changing Properties}. + @item font-lock-face @kindex font-lock-face @r{(text property)} This property specifies a value for the @code{face} property that Font @@ -3108,7 +3165,7 @@ This property says whether the text is ready for display. If @code{nil}, Emacs's redisplay routine calls the functions in @code{fontification-functions} (@pxref{Auto Faces}) to prepare this part of the buffer before it is displayed. It is used internally by -the ``just in time'' font locking code. +the just-in-time font locking code. @item display This property activates various features that change the @@ -3197,6 +3254,11 @@ possible to remove a @code{read-only} property unless you know the special trick: bind @code{inhibit-read-only} to a non-@code{nil} value and then remove the property. @xref{Read Only Buffers}. +@item inhibit-read-only +@kindex inhibit-read-only @r{(text property)} +If a character has the property @code{inhibit-read-only}, and the +buffer is read-only, editing the character in question is allowed. + @item invisible @kindex invisible @r{(text property)} A non-@code{nil} @code{invisible} property can make a character invisible @@ -3237,7 +3299,7 @@ overlay and text property strings present at the current buffer position. You can place the cursor on any desired character of these strings by giving that character a non-@code{nil} @code{cursor} text property. In addition, if the value of the @code{cursor} property is -an integer number, it specifies the number of buffer's character +an integer, it specifies the number of buffer's character positions, starting with the position where the overlay or the @code{display} property begins, for which the cursor should be displayed on that character. Specifically, if the value of the @@ -3251,7 +3313,7 @@ text property begins in the buffer. In other words, the string character with the @code{cursor} property of any non-@code{nil} value is the character where to display the cursor. The value of the property says for which buffer positions to -display the cursor there. If the value is an integer number @var{n}, +display the cursor there. If the value is an integer @var{n}, the cursor is displayed there when point is anywhere between the beginning of the overlay or @code{display} property and @var{n} positions after that. If the value is anything else and @@ -3410,8 +3472,10 @@ function called to display help strings. These may be @code{help-echo} properties, menu help strings (@pxref{Simple Menu Items}, @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool Bar}). The specified function is called with one argument, the help -string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}) provides an example. +string to display, which is passed through +@code{substitute-command-keys} before being given to the function; see +@ref{Keys in Documentation}. Tooltip mode (@pxref{Tooltips,,, emacs, +The GNU Emacs Manual}) provides an example. @end defvar @node Format Properties @@ -3447,10 +3511,12 @@ of the text. @cindex sticky text properties @cindex inheritance, text property - Self-inserting characters normally take on the same properties as the -preceding character. This is called @dfn{inheritance} of properties. + Self-inserting characters, the ones that get inserted into a buffer +when the user types them (@pxref{Commands for Insertion}), normally +take on the same properties as the preceding character. This is +called @dfn{inheritance} of properties. - A Lisp program can do insertion with inheritance or without, + By contrast, a Lisp program can do insertion with inheritance or without, depending on the choice of insertion primitive. The ordinary text insertion functions, such as @code{insert}, do not inherit any properties. They insert text with precisely the properties of the @@ -3557,8 +3623,8 @@ once for the same part of the buffer, you can use the variable @defvar buffer-access-fontified-property If this variable's value is non-@code{nil}, it is a symbol which is used as a text property name. A non-@code{nil} value for that text property -means, ``the other text properties for this character have already been -computed''. +means the other text properties for this character have already been +computed. If all the characters in the range specified for @code{buffer-substring} have a non-@code{nil} value for this property, @code{buffer-substring} @@ -3669,16 +3735,17 @@ clicks on the link quickly without moving the mouse. This behavior is controlled by the user option @code{mouse-1-click-follows-link}. @xref{Mouse References,,, emacs, The GNU Emacs Manual}. +@cindex follow-link (text or overlay property) To set up the link so that it obeys @code{mouse-1-click-follows-link}, you must either (1) apply a @code{follow-link} text or overlay property to the link text, or (2) bind the @code{follow-link} event to a keymap (which can be a major mode keymap or a local keymap specified via the @code{keymap} text property). The value of the @code{follow-link} property, or the -binding for the @code{follow-link} event, acts as a ``condition'' for +binding for the @code{follow-link} event, acts as a condition for the link action. This condition tells Emacs two things: the circumstances under which a @kbd{Mouse-1} click should be regarded as -occurring ``inside'' the link, and how to compute an ``action code'' +occurring inside the link, and how to compute an action code that says what to translate the @kbd{Mouse-1} click into. The link action condition can be one of the following: @@ -3844,7 +3911,7 @@ This function deletes the text of the field specified by @var{pos}. @end defun @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property -This function ``constrains'' @var{new-pos} to the field that +This function constrains @var{new-pos} to the field that @var{old-pos} belongs to---in other words, it returns the position closest to @var{new-pos} that is in the same field as @var{old-pos}. @@ -3862,7 +3929,7 @@ after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, @var{new-pos} can be anywhere in the two adjacent fields. Additionally, if two fields are separated by another field with the special value @code{boundary}, then any point within this special -field is also considered to be ``on the boundary''. +field is also considered to be on the boundary. Commands like @kbd{C-a} with no argument, that normally move backward to a specific kind of location and stay there once there, probably @@ -3890,7 +3957,7 @@ You can cause @code{constrain-to-field} to ignore all field boundaries @cindex intervals Some editors that support adding attributes to text in the buffer do -so by letting the user specify ``intervals'' within the text, and adding +so by letting the user specify intervals within the text, and adding the properties to the intervals. Those editors permit the user or the programmer to determine where individual intervals start and end. We deliberately provided a different sort of interface in Emacs Lisp to @@ -3908,22 +3975,23 @@ Then if you yank back the killed text, you get two intervals with the same properties. Thus, editing does not preserve the distinction between one interval and two. - Suppose we ``fix'' this problem by coalescing the two intervals when + Suppose we attempt to fix this problem by coalescing the two intervals when the text is inserted. That works fine if the buffer originally was a single interval. But suppose instead that we have two adjacent intervals with the same properties, and we kill the text of one interval and yank it back. The same interval-coalescence feature that rescues the other case causes trouble in this one: after yanking, we have just -one interval. One again, editing does not preserve the distinction +one interval. Once again, editing does not preserve the distinction between one interval and two. Insertion of text at the border between intervals also raises questions that have no satisfactory answer. - However, it is easy to arrange for editing to behave consistently for -questions of the form, ``What are the properties of this character?'' -So we have decided these are the only questions that make sense; we have -not implemented asking questions about where intervals start or end. + However, it is easy to arrange for editing to behave consistently +for questions of the form, ``What are the properties of text at this +buffer or string position?'' So we have decided these are the only +questions that make sense; we have not implemented asking questions +about where intervals start or end. In practice, you can usually use the text property search functions in place of explicit interval boundaries. You can think of them as finding @@ -3935,6 +4003,8 @@ coalesced whenever possible. @xref{Property Search}. @node Substitution @section Substituting for a Character Code +@cindex replace characters in region +@cindex substitute characters The following functions replace characters within a specified region based on their character codes. @@ -4069,8 +4139,9 @@ buffer. Normally, this command puts point before the inserted text, and the mark after it. However, if the optional second argument @var{beforep} is non-@code{nil}, it puts the mark before and point after. -You can pass a non-@code{nil} second argument @var{beforep} to this -function interactively by supplying any prefix argument. + +When called interactively, the command defaults to putting point after +text, and a prefix argument inverts this behavior. If the register contains a rectangle, then the rectangle is inserted with its upper left corner at point. This means that text is inserted @@ -4081,6 +4152,18 @@ a rectangle (a list), currently useless things happen. This may be changed in the future. @end deffn +@defun register-read-with-preview prompt +@cindex register preview +This function reads and returns a register name, prompting with +@var{prompt} and possibly showing a preview of the existing registers +and their contents. The preview is shown in a temporary window, after +the delay specified by the user option @code{register-preview-delay}, +if its value and @code{register-alist} are both non-@code{nil}. The +preview is also shown if the user requests help (e.g., by typing the +help character). We recommend that all interactive commands which +read register names use this function. +@end defun + @node Transposition @section Transposition of Text @@ -4100,6 +4183,35 @@ is non-@code{nil}, @code{transpose-regions} does not do this---it leaves all markers unrelocated. @end defun +@node Decompression +@section Dealing With Compressed Data + +When @code{auto-compression-mode} is enabled, Emacs automatically +uncompresses compressed files when you visit them, and automatically +recompresses them if you alter and save them. @xref{Compressed +Files,,, emacs, The GNU Emacs Manual}. + +The above feature works by calling an external executable (e.g., +@command{gzip}). Emacs can also be compiled with support for built-in +decompression using the zlib library, which is faster than calling an +external program. + +@defun zlib-available-p +This function returns non-@code{nil} if built-in zlib decompression is +available. +@end defun + +@defun zlib-decompress-region start end +This function decompresses the region between @var{start} and +@var{end}, using built-in zlib decompression. The region should +contain data that were compressed with gzip or zlib. On success, the +function replaces the contents of the region with the decompressed +data. On failure, the function leaves the region unchanged and +returns @code{nil}. This function can be called only in unibyte +buffers. +@end defun + + @node Base 64 @section Base 64 Encoding @cindex base 64 encoding @@ -4165,7 +4277,7 @@ The decoding functions ignore newline characters in the encoded text. @cindex cryptographic hash Emacs has built-in support for computing @dfn{cryptographic hashes}. -A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint'' +A cryptographic hash, or @dfn{checksum}, is a digital fingerprint of a piece of data (e.g., a block of text) which can be used to check that you have an unaltered copy of that data. @@ -4174,7 +4286,7 @@ that you have an unaltered copy of that data. SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the oldest of these algorithms, and is commonly used in @dfn{message digests} to check the integrity of messages transmitted over a -network. MD5 is not ``collision resistant'' (i.e., it is possible to +network. MD5 is not collision resistant (i.e., it is possible to deliberately design different pieces of data which have the same MD5 hash), so you should not used it for anything security-related. A similar theoretical weakness also exists in SHA-1. Therefore, for @@ -4232,15 +4344,18 @@ coding instead. When Emacs is compiled with libxml2 support, the following functions are available to parse HTML or XML text into Lisp object trees. -@defun libxml-parse-html-region start end &optional base-url +@defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as HTML, and returns a list representing the HTML @dfn{parse tree}. It -attempts to handle ``real world'' HTML by robustly coping with syntax +attempts to handle real-world HTML by robustly coping with syntax mistakes. The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. +If the optional argument @var{discard-comments} is non-@code{nil}, +then the parse tree is created without any comments. + In the parse tree, each HTML node is represented by a list in which the first element is a symbol representing the node name, the second element is an alist of node attributes, and the remaining elements are @@ -4254,26 +4369,163 @@ document: @end example @noindent -A call to @code{libxml-parse-html-region} returns this: +A call to @code{libxml-parse-html-region} returns this @acronym{DOM} +(document object model): @example -(html () - (head ()) - (body ((width . "101")) - (div ((class . "thing")) - "Foo" - (div () - "Yes")))) +(html nil + (head nil) + (body ((width . "101")) + (div ((class . "thing")) + "Foo" + (div nil + "Yes")))) @end example @end defun +@cindex rendering html +@defun shr-insert-document dom +This function renders the parsed HTML in @var{dom} into the current +buffer. The argument @var{dom} should be a list as generated by +@code{libxml-parse-html-region}. This function is, e.g., used by +@ref{Top, EWW,, eww, The Emacs Web Wowser Manual}. +@end defun + @cindex parsing xml -@defun libxml-parse-xml-region start end &optional base-url +@defun libxml-parse-xml-region start end &optional base-url discard-comments This function is the same as @code{libxml-parse-html-region}, except that it parses the text as XML rather than HTML (so it is stricter about syntax). @end defun +@menu +* Document Object Model:: Access, manipulate and search the @acronym{DOM}. +@end menu + +@node Document Object Model +@subsection Document Object Model +@cindex HTML DOM +@cindex XML DOM +@cindex DOM +@cindex Document Object Model + +The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the +other @acronym{XML} parsing functions) is a tree structure where each +node has a node name (called a @dfn{tag}), and optional key/value +@dfn{attribute} list, and then a list of @dfn{child nodes}. The child +nodes are either strings or @acronym{DOM} objects. + +@example +(body ((width . "101")) + (div ((class . "thing")) + "Foo" + (div nil + "Yes"))) +@end example + +@defun dom-node tag &optional attributes &rest children +This function creates a @acronym{DOM} node of type @var{tag}. If +given, @var{attributes} should be a key/value pair list. +If given, @var{children} should be @acronym{DOM} nodes. +@end defun + +The following functions can be used to work with this structure. Each +function takes a @acronym{DOM} node, or a list of nodes. In the +latter case, only the first node in the list is used. + +Simple accessors: + +@table @code +@item dom-tag @var{node} +Return the @dfn{tag} (also called ``node name'') of the node. + +@item dom-attr @var{node} @var{attribute} +Return the value of @var{attribute} in the node. A common usage +would be: + +@lisp +(dom-attr img 'href) +=> "http://fsf.org/logo.png" +@end lisp + +@item dom-children @var{node} +Return all the children of the node. + +@item dom-non-text-children @var{node} +Return all the non-string children of the node. + +@item dom-attributes @var{node} +Return the key/value pair list of attributes of the node. + +@item dom-text @var{node} +Return all the textual elements of the node as a concatenated string. + +@item dom-texts @var{node} +Return all the textual elements of the node, as well as the textual +elements of all the children of the node, recursively, as a +concatenated string. This function also takes an optional separator +to be inserted between the textual elements. + +@item dom-parent @var{dom} @var{node} +Return the parent of @var{node} in @var{dom}. +@end table + +The following are functions for altering the @acronym{DOM}. + +@table @code +@item dom-set-attribute @var{node} @var{attribute} @var{value} +Set the @var{attribute} of the node to @var{value}. + +@item dom-append-child @var{node} @var{child} +Append @var{child} as the last child of @var{node}. + +@item dom-add-child-before @var{node} @var{child} @var{before} +Add @var{child} to @var{node}'s child list before the @var{before} +node. If @var{before} is @code{nil}, make @var{child} the first child. + +@item dom-set-attributes @var{node} @var{attributes} +Replace all the attributes of the node with a new key/value list. +@end table + +The following are functions for searching for elements in the +@acronym{DOM}. They all return lists of matching nodes. + +@table @code +@item dom-by-tag @var{dom} @var{tag} +Return all nodes in @var{dom} that are of type @var{tag}. A typical +use would be: + +@lisp +(dom-by-tag dom 'td) +=> '((td ...) (td ...) (td ...)) +@end lisp + +@item dom-by-class @var{dom} @var{match} +Return all nodes in @var{dom} that have class names that match +@var{match}, which is a regular expression. + +@item dom-by-style @var{dom} @var{style} +Return all nodes in @var{dom} that have styles that match @var{match}, +which is a regular expression. + +@item dom-by-id @var{dom} @var{style} +Return all nodes in @var{dom} that have IDs that match @var{match}, +which is a regular expression. + +@item dom-strings @var{dom} +Return all strings in @var{DOM}. + +@end table + +Utility functions: + +@table @code +@item dom-pp @var{dom} &optional @var{remove-empty} +Pretty-print @var{dom} at point. If @var{remove-empty}, don't print +textual nodes that just contain white-space. +@end table + + @node Atomic Changes @section Atomic Change Groups @cindex atomic changes @@ -4307,7 +4559,7 @@ lower-level functions that @code{atomic-change-group} uses. @defun prepare-change-group &optional buffer This function sets up a change group for buffer @var{buffer}, which -defaults to the current buffer. It returns a ``handle'' that +defaults to the current buffer. It returns a handle that represents the change group. You must use this handle to activate the change group and subsequently to finish it. @end defun diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 2e3760e573e..d9cbf473306 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -1,6 +1,6 @@ -@c -*-texinfo-*- +@c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Tips @@ -223,18 +223,13 @@ only for special-purpose buffers.) People will find Emacs more coherent if all libraries use the same conventions. @item -If your program contains non-ASCII characters in string or character -constants, you should make sure Emacs always decodes these characters -the same way, regardless of the user's settings. The easiest way to -do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding -System Basics}), and specify that coding in the @samp{-*-} line or the +The default file coding system for Emacs Lisp source files is UTF-8 +(@pxref{Text Representations}). In the rare event that your program +contains characters which are @emph{not} in UTF-8, you should specify +an appropriate coding system in the source file's @samp{-*-} line or local variables list. @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}. -@example -;; XXX.el -*- coding: utf-8-emacs; -*- -@end example - @item Indent the file using the default indentation parameters. @@ -403,7 +398,7 @@ Enter the answer (default 42): @item In @code{interactive}, if you use a Lisp expression to produce a list -of arguments, don't try to provide the ``correct'' default values for +of arguments, don't try to provide the correct default values for region or position arguments. Instead, provide @code{nil} for those arguments if they were not specified, and have the function body compute the default value when the argument is @code{nil}. For @@ -578,10 +573,13 @@ Format the documentation string so that it fits in an Emacs window on an 60 characters. The first line should not be wider than 67 characters or it will look bad in the output of @code{apropos}. -You can fill the text if that looks good. However, rather than blindly -filling the entire documentation string, you can often make it much more -readable by choosing certain line breaks with care. Use blank lines -between sections if the documentation string is long. +@vindex emacs-lisp-docstring-fill-column +You can fill the text if that looks good. Emacs Lisp mode fills +documentation strings to the width specified by +@code{emacs-lisp-docstring-fill-column}. However, you can sometimes +make a documentation string much more readable by adjusting its line +breaks with care. Use blank lines between sections if the +documentation string is long. @item The first line of the documentation string should consist of one or two @@ -659,23 +657,29 @@ starting double-quote is not part of the string! @anchor{Docstring hyperlinks} @item -@iftex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{`lambda'}. There are two exceptions: -write @code{t} and @code{nil} without single-quotes. -@end iftex -@ifnottex +@cindex curly quotes +@cindex curved quotes When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we use a different -convention, with single-quotes for all symbols.) -@end ifnottex +would be printed (which usually means in lower case), surrounding +it with curved single quotes (@t{‘} and @t{’}). There are +two exceptions: write @code{t} and @code{nil} without surrounding +punctuation. For example: @samp{CODE can be ‘lambda’, nil, or t}. +@xref{Quotation Marks,,, emacs, The GNU Emacs Manual}, for how to +enter curved single quotes. + +Documentation strings can also use an older single-quoting convention, +which quotes symbols with grave accent @t{`} and apostrophe +@t{'}: @t{`like-this'} rather than @t{‘like-this’}. This +older convention was designed for now-obsolete displays in which grave +accent and apostrophe were mirror images. + +Documentation using either convention is converted to the user's +preferred format when it is copied into a help buffer. @xref{Keys in +Documentation}. @cindex hyperlinks in documentation strings Help mode automatically creates a hyperlink when a documentation string -uses a symbol name inside single quotes, if the symbol has either a +uses a single-quoted symbol name, if the symbol has either a function or a variable definition. You do not need to do anything special to make use of this feature. However, when a symbol has both a function definition and a variable definition, and you want to refer to @@ -717,17 +721,17 @@ followed by the word @samp{face}. In that case, only the face documentation will be shown, even if the symbol is also defined as a variable or as a function. -To make a hyperlink to Info documentation, write the name of the Info -node (or anchor) in single quotes, preceded by @samp{info node}, -@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info -file name defaults to @samp{emacs}. For example, +To make a hyperlink to Info documentation, write the single-quoted +name of the Info node (or anchor), preceded by +@samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info +anchor}. The Info file name defaults to @samp{emacs}. For example, @smallexample See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. @end smallexample -Finally, to create a hyperlink to URLs, write the URL in single -quotes, preceded by @samp{URL}. For example, +Finally, to create a hyperlink to URLs, write the single-quoted URL, +preceded by @samp{URL}. For example, @smallexample The home page for the GNU project has more information (see URL @@ -768,7 +772,7 @@ is indicative and has a proper subject. @item The documentation string for a function that is a yes-or-no predicate should start with words such as ``Return t if'', to indicate -explicitly what constitutes ``truth''. The word ``return'' avoids +explicitly what constitutes truth. The word ``return'' avoids starting the sentence with lower-case ``t'', which could be somewhat distracting. @@ -836,10 +840,10 @@ For example: @smallexample @group -(setq base-version-list ; there was a base +(setq base-version-list ; There was a base (assoc (substring fn 0 start-vn) ; version to which file-version-assoc-list)) ; this looks like - ; a subversion + ; a subversion. @end group @end smallexample @@ -877,30 +881,14 @@ strings, though. @item ;;; Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. These are used, occasionally, for comments within -functions that should start at the margin. We also use them sometimes -for comments that are between functions---whether to use two or three -semicolons depends on whether the comment should be considered a -``heading'' by Outline minor mode. By default, comments starting with +the left margin. We use them +for comments which should be considered a +heading by Outline minor mode. By default, comments starting with at least three semicolons (followed by a single space and a non-whitespace character) are considered headings, comments starting -with two or fewer are not. - -Another use for triple-semicolon comments is for commenting out lines -within a function. We use three semicolons for this precisely so that -they remain at the left margin. By default, Outline minor mode does -not consider a comment to be a heading (even if it starts with at -least three semicolons) if the semicolons are followed by at least two -spaces. Thus, if you add an introductory comment to the commented out -code, make sure to indent it by at least two spaces after the three -semicolons. - -@smallexample -(defun foo (a) -;;; This is no longer necessary. -;;; (force-mode-line-update) - (message "Finished with %s" a)) -@end smallexample +with two or fewer are not. Historically, triple-semicolon comments have +also been used for commenting out lines within a function, but this use +is discouraged. When commenting out entire functions, use two semicolons. @@ -936,7 +924,7 @@ explains these conventions, starting with an example: @group ;;; foo.el --- Support for the Foo programming language -;; Copyright (C) 2010-2013 Your Name +;; Copyright (C) 2010-2015 Your Name @end group ;; Author: Your Name <yourname@@example.com> @@ -1080,9 +1068,9 @@ context. @item ;;; Change Log: This begins an optional log of changes to the file over time. Don't put too much information in this section---it is better to keep the -detailed logs in a separate @file{ChangeLog} file (as Emacs does), -and/or to use a version control system. @samp{History} is an -alternative to @samp{Change Log}. +detailed logs in a version control system (as Emacs does) or in a +separate @file{ChangeLog} file. @samp{History} is an alternative to +@samp{Change Log}. @item ;;; Code: This begins the actual code of the program. diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt index a134b8c4783..89336e1d43b 100644 --- a/doc/lispref/two-volume-cross-refs.txt +++ b/doc/lispref/two-volume-cross-refs.txt @@ -1,4 +1,4 @@ -Copyright (C) 2001-2013 Free Software Foundation, Inc. +Copyright (C) 2001-2015 Free Software Foundation, Inc. See end for copying conditions. Two Volume Cross References @@ -108,8 +108,8 @@ on elisp2-fn-vol-number-added (volume-index-markup "II") to create elisp2-fn-vol-number-added -insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' -insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' +insert elisp2-fn-vol-number-added into vol1.fn: do following 'cat' +insert elisp1-fn-vol-number-added into vol2.fn: do following 'cat' % cat elisp2-fn-vol-number-added >> vol1.fn % cat elisp1-fn-vol-number-added >> vol2.fn @@ -126,7 +126,7 @@ Be sure that .fn file has no blank lines. ### Create merged .toc file with volume number headings. -append vol2.toc to vol1.toc with following `cat' +append vol2.toc to vol1.toc with following 'cat' % cat vol1.toc vol2.toc > elisp-toc-2vol.toc diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make index 9ae4a33df44..bdcdb2f4fdd 100644 --- a/doc/lispref/two-volume.make +++ b/doc/lispref/two-volume.make @@ -1,4 +1,4 @@ -# Copyright (C) 2007-2013 Free Software Foundation, Inc. +# Copyright (C) 2007-2015 Free Software Foundation, Inc. # See end for copying conditions. # although it would be nice to use tex rather than pdftex to avoid @@ -26,9 +26,9 @@ tex2 = sed '/^@setfilename/a\ # elisp.texi specially defines \tocreadfilename when VOL1 or VOL2 is # set, so we can use our premade .toc's. -# +# vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready - @echo -e "\f Final TeX run for volume 1..." + @printf '\f Final TeX run for volume 1...\n' cp elisp1med-toc-ready elisp1-toc-ready.toc cp elisp1med-fns-ready vol1.fns cp elisp1med-aux-ready vol1.aux @@ -42,27 +42,27 @@ vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready $(tex2) # intermediate toc files. -# +# # vol1 toc: volume 1, page break, volume 2 (with II: prepended). elisp1med-toc-ready: elisp1med-init elisp2med-init echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ cat elisp1med-toc >>$@ echo '@page' >>$@ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@ + sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@ # # vol2 toc: volume 1 (with I: prepended), page break, volume 2. elisp2med-toc-ready: elisp1med-init elisp2med-init echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ + sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ echo '@page' >>$@ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ cat elisp2med-toc >>$@ # intermediate aux files. -# -# append vol2's fixed aux to normal vol1. +# +# append vol2's fixed aux to normal vol1. elisp1med-aux-ready: elisp2med-aux-vol-added cat elisp1med-aux $< >$@ # @@ -78,7 +78,7 @@ elisp2med-aux-vol-added: elisp2med-init sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@ # intermediate index (fns) file. -# +# elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added cat elisp2med-fn-vol-added >>vol1.fn texindex vol1.fn @@ -103,17 +103,17 @@ elisp2med-fn-vol-added: elisp2med-init # ----------------------------------------------------------------------------- # intermediate TeX runs. -# +# # this generates what would be the final versions -- except the page # numbers aren't right. The process of adding the I: and II: changes # the page breaks, so a few index entries, at least are wrong. (In # 2007, x-meta-keysym in vol.II ended up on page 374 when the index had # it on page 375 from the initial run.) -# +# # So, we start all over again, from these fns/aux/toc files. -# +# elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready $(texinfodir)/texinfo.tex - @echo -e "\f Intermediate TeX run for volume 1..." + @printf '\f Intermediate TeX run for volume 1...\n' cp elisp1init-toc-ready elisp1-toc-ready.toc cp elisp1-fns-ready vol1.fns cp elisp1-aux-ready vol1.aux @@ -134,26 +134,26 @@ elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfo # initial toc files. -# +# # vol1 toc: volume 1, page break, volume 2 (with II: prepended). elisp1init-toc-ready: elisp1-init elisp2-init echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ cat elisp1-toc >>$@ echo '@page' >>$@ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@ + sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@ # # vol2 toc: volume 1 (with I: prepended), page break, volume 2. elisp2init-toc-ready: elisp1-init elisp2-init echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ + sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ echo '@page' >>$@ echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ cat elisp2-toc >>$@ # initial aux files. -# +# # append vol2's fixed aux to normal vol1. The initial runs saved # elisp1-aux and elisp2-aux. elisp1-aux-ready: elisp2-aux-vol-added @@ -171,7 +171,7 @@ elisp2-aux-vol-added: elisp2-init sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@ # initial index (fns) file. -# +# # Append other volume's index entries to this one's. # Index entries in this volume will then take precedence. elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added @@ -195,14 +195,14 @@ elisp2-fn-vol-added: elisp2-init # initial TeX runs. -# +# # We use the .fn, .aux, and .toc files created here in subsequent # processing. The page numbers generated here will not be correct yet, # but we run texindex and TeX a second time just to get them closer. # Otherwise it might take even longer for them to converge. -# +# elisp1-init: elisp.texi - @echo -e "\f Initial TeX run for volume 1..." + @printf '\f Initial TeX run for volume 1...\n' rm -f vol1.aux vol1.toc $(tex1) texindex vol1.?? @@ -220,17 +220,16 @@ elisp2-init: elisp.texi touch $@ # COPYING CONDITIONS -# +# # This file is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. -# +# # This file is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. -# +# # You should have received a copy of the GNU General Public License # along with this file. If not, see <http://www.gnu.org/licenses/>. - diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 557add738ba..1d920942d10 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Variables @chapter Variables @@ -10,10 +10,10 @@ In Lisp, each variable is represented by a Lisp symbol (@pxref{Symbols}). The variable name is simply the symbol's name, and the variable's value is stored in the symbol's value cell@footnote{To -be precise, under the default @dfn{dynamic binding} rules the value +be precise, under the default @dfn{dynamic scoping} rule, the value cell always holds the variable's current value, but this is not the -case under @dfn{lexical binding} rules. @xref{Variable Scoping}, for -details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a +case under the @dfn{lexical scoping} rule. @xref{Variable Scoping}, +for details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a symbol as a variable is independent of its use as a function name. As previously noted in this manual, a Lisp program is represented @@ -25,7 +25,7 @@ representing the variable. @menu * Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. +* Constant Variables:: Variables that never change. * Local Variables:: Variable values that exist only temporarily. * Void Variables:: Symbols that lack values. * Defining Variables:: A definition says a symbol is used as a variable. @@ -131,7 +131,7 @@ starts with @samp{:}, interned in the standard obarray, and returns @code{nil} otherwise. @end defun -These constants are fundamentally different from the ``constants'' +These constants are fundamentally different from the constants defined using the @code{defconst} special form (@pxref{Defining Variables}). A @code{defconst} form serves to inform human readers that you do not intend to change the value of a variable, but Emacs @@ -178,7 +178,7 @@ It determines the value returned by evaluating the variable symbol, and it is the binding acted on by @code{setq}. For most purposes, you can think of the current binding as the -``innermost'' local binding, or the global binding if there is no +innermost local binding, or the global binding if there is no local binding. To be more precise, a rule called the @dfn{scoping rule} determines where in a program a local binding takes effect. The default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, @@ -263,7 +263,7 @@ Macro calls (@pxref{Macros}). Variables}); a few variables have terminal-local bindings (@pxref{Multiple Terminals}). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs. +where you are in Emacs. @defopt max-specpdl-size @anchor{Definition of max-specpdl-size} @@ -287,25 +287,27 @@ has room to execute. @end defopt @node Void Variables -@section When a Variable is ``Void'' +@section When a Variable is Void @cindex @code{void-variable} error @cindex void variable We say that a variable is void if its symbol has an unassigned value -cell (@pxref{Symbol Components}). Under Emacs Lisp's default dynamic -binding rules (@pxref{Variable Scoping}), the value cell stores the -variable's current (local or global) value. Note that an unassigned -value cell is @emph{not} the same as having @code{nil} in the value -cell. The symbol @code{nil} is a Lisp object and can be the value of -a variable, just as any other object can be; but it is still a value. -If a variable is void, trying to evaluate the variable signals a -@code{void-variable} error rather than a value. - - Under lexical binding rules, the value cell only holds the -variable's global value, i.e., the value outside of any lexical -binding construct. When a variable is lexically bound, the local value -is determined by the lexical environment; the variable may have a -local value if its symbol's value cell is unassigned. +cell (@pxref{Symbol Components}). + + Under Emacs Lisp's default dynamic scoping rule (@pxref{Variable +Scoping}), the value cell stores the variable's current (local or +global) value. Note that an unassigned value cell is @emph{not} the +same as having @code{nil} in the value cell. The symbol @code{nil} is +a Lisp object and can be the value of a variable, just as any other +object can be; but it is still a value. If a variable is void, trying +to evaluate the variable signals a @code{void-variable} error, instead +of returning a value. + + Under the optional lexical scoping rule, the value cell only holds +the variable's global value---the value outside of any lexical binding +construct. When a variable is lexically bound, the local value is +determined by the lexical environment; hence, variables can have local +values even if their symbols' value cells are unassigned. @defun makunbound symbol This function empties out the value cell of @var{symbol}, making the @@ -414,18 +416,23 @@ explicitly in the @code{defvar} form. The variable is marked as @dfn{special}, meaning that it should always be dynamically bound (@pxref{Variable Scoping}). -If @var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates @var{value} and sets @var{symbol} to the result. But if -@var{symbol} already has a value (i.e., it is not void), @var{value} -is not even evaluated, and @var{symbol}'s value remains unchanged. If -@var{value} is omitted, the value of @var{symbol} is not changed in -any case. +If @var{value} is specified, and @var{symbol} is void (i.e., it has no +dynamically bound value; @pxref{Void Variables}), then @var{value} is +evaluated and @var{symbol} is set to the result. But if @var{symbol} +is not void, @var{value} is not evaluated, and @var{symbol}'s value is +left unchanged. If @var{value} is omitted, the value of @var{symbol} +is not changed in any case. If @var{symbol} has a buffer-local binding in the current buffer, -@code{defvar} operates on the default value, which is buffer-independent, -not the current (buffer-local) binding. It sets the default value if +@code{defvar} acts on the default value, which is buffer-independent, +rather than the buffer-local binding. It sets the default value if the default value is void. @xref{Buffer-Local Variables}. +If @var{symbol} is already lexically bound (e.g., if the @code{defvar} +form occurs in a @code{let} form with lexical binding enabled), then +@code{defvar} sets the dynamic value. The lexical binding remains in +effect until its binding construct exits. @xref{Variable Scoping}. + When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} arranges to set the variable unconditionally, without @@ -538,8 +545,7 @@ The value is a list of forms (expressions). @item @dots{}-predicate The value is a predicate---a function of one argument that returns -non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' -arguments. +non-@code{nil} for success and @code{nil} for failure. @item @dots{}-flag The value is significant only as to whether it is @code{nil} or not. @@ -557,7 +563,7 @@ The value specifies options for a command. @end table When you define a variable, always consider whether you should mark -it as ``safe'' or ``risky''; see @ref{File Local Variables}. +it as safe or risky; see @ref{File Local Variables}. When defining and initializing a variable that holds a complicated value (such as a keymap with bindings in it), it's best to put the @@ -761,6 +767,7 @@ error is signaled. @node Variable Scoping @section Scoping Rules for Variable Bindings +@cindex scoping rule When you create a local binding for a variable, that binding takes effect only within a limited portion of the program (@pxref{Local @@ -774,12 +781,12 @@ binding can be accessed. @dfn{Extent} refers to @emph{when}, as the program is executing, the binding exists. @cindex dynamic binding -@cindex indefinite scope +@cindex dynamic scope @cindex dynamic extent By default, the local bindings that Emacs creates are @dfn{dynamic -bindings}. Such a binding has @dfn{indefinite scope}, meaning that -any part of the program can potentially access the variable binding. -It also has @dfn{dynamic extent}, meaning that the binding lasts only +bindings}. Such a binding has @dfn{dynamic scope}, meaning that any +part of the program can potentially access the variable binding. It +also has @dfn{dynamic extent}, meaning that the binding lasts only while the binding construct (such as the body of a @code{let} form) is being executed. @@ -788,11 +795,12 @@ being executed. @cindex indefinite extent Emacs can optionally create @dfn{lexical bindings}. A lexical binding has @dfn{lexical scope}, meaning that any reference to the -variable must be located textually within the binding construct. It -also has @dfn{indefinite extent}, meaning that under some -circumstances the binding can live on even after the binding construct -has finished executing, by means of special objects called -@dfn{closures}. +variable must be located textually within the binding +construct@footnote{With some exceptions; for instance, a lexical +binding can also be accessed from the Lisp debugger.}. It also has +@dfn{indefinite extent}, meaning that under some circumstances the +binding can live on even after the binding construct has finished +executing, by means of special objects called @dfn{closures}. The following subsections describe dynamic binding and lexical binding in greater detail, and how to enable lexical binding in Emacs @@ -814,22 +822,22 @@ at any point in the execution of the Lisp program is simply the most recently-created dynamic local binding for that symbol, or the global binding if there is no such local binding. - Dynamic bindings have indefinite scope and dynamic extent, as shown -by the following example: + Dynamic bindings have dynamic scope and extent, as shown by the +following example: @example @group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} +(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + x) ; @r{@code{x} is used free in this function.} (let ((x 1)) ; @r{@code{x} is dynamically bound.} (getx)) @result{} 1 ;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is -99.} +;; @r{previous value, which is @minus{}99.} (getx) @result{} -99 @@ -837,20 +845,20 @@ by the following example: @end example @noindent -The function @code{getx} refers to @code{x}. This is a ``free'' +The function @code{getx} refers to @code{x}. This is a @dfn{free} reference, in the sense that there is no binding for @code{x} within that @code{defun} construct itself. When we call @code{getx} from within a @code{let} form in which @code{x} is (dynamically) bound, it -retrieves the local value of @code{x} (i.e., 1). But when we call -@code{getx} outside the @code{let} form, it retrieves the global value -of @code{x} (i.e., -99). +retrieves the local value (i.e., 1). But when we call @code{getx} +outside the @code{let} form, it retrieves the global value (i.e., +@minus{}99). Here is another example, which illustrates setting a dynamically bound variable using @code{setq}: @example @group -(defvar x -99) ; @r{@code{x} receives an initial value of -99.} +(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} (defun addx () (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.} @@ -861,7 +869,7 @@ bound variable using @code{setq}: @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.} ;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is -99.} +;; @r{previous value, which is @minus{}99.} (addx) @result{} -98 @@ -888,12 +896,11 @@ technique: @itemize @bullet @item If a variable has no global definition, use it as a local variable -only within a binding construct, e.g., the body of the @code{let} -form where the variable was bound, or the body of the function for an -argument variable. If this convention is followed consistently -throughout a program, the value of the variable will not affect, nor -be affected by, any uses of the same variable symbol elsewhere in the -program. +only within a binding construct, such as the body of the @code{let} +form where the variable was bound. If this convention is followed +consistently throughout a program, the value of the variable will not +affect, nor be affected by, any uses of the same variable symbol +elsewhere in the program. @item Otherwise, define the variable with @code{defvar}, @code{defconst}, or @@ -925,12 +932,16 @@ variables like @code{case-fold-search}: @node Lexical Binding @subsection Lexical Binding -Optionally, you can create lexical bindings in Emacs Lisp. A -lexically bound variable has @dfn{lexical scope}, meaning that any -reference to the variable must be located textually within the binding -construct. + Lexical binding was introduced to Emacs, as an optional feature, in +version 24.1. We expect its importance to increase in the future. +Lexical binding opens up many more opportunities for optimization, so +programs using it are likely to run faster in future Emacs versions. +Lexical binding is also more compatible with concurrency, which we +want to add to Emacs in the future. - Here is an example + A lexically-bound variable has @dfn{lexical scope}, meaning that any +reference to the variable must be located textually within the binding +construct. Here is an example @iftex (see the next subsection, for how to actually enable lexical binding): @end iftex @@ -945,7 +956,7 @@ construct. @result{} 4 (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + x) ; @r{@code{x} is used free in this function.} (let ((x 1)) ; @r{@code{x} is lexically bound.} (getx)) @@ -969,6 +980,14 @@ wants the current value of a variable, it looks first in the lexical environment; if the variable is not specified in there, it looks in the symbol's value cell, where the dynamic value is stored. + (Internally, the lexical environment is an alist of symbol-value +pairs, with the final element in the alist being the symbol @code{t} +rather than a cons cell. Such an alist can be passed as the second +argument to the @code{eval} function, in order to specify a lexical +environment in which to evaluate a form. @xref{Eval}. Most Emacs +Lisp programs, however, should not interact directly with lexical +environments in this way; only specialized programs like debuggers.) + @cindex closures, example of using Lexical bindings have indefinite extent. Even after a binding construct has finished executing, its lexical environment can be @@ -1019,13 +1038,6 @@ binding of @code{x} in that lexical environment. the body of a @code{defun} or @code{defmacro} cannot refer to surrounding lexical variables. - Currently, lexical binding is not much used within the Emacs -sources. However, we expect its importance to increase in the future. -Lexical binding opens up a lot more opportunities for optimization, so -Emacs Lisp code that makes use of lexical binding is likely to run -faster in future Emacs versions. Such code is also much more friendly -to concurrency, which we want to add to Emacs in the near future. - @node Using Lexical Binding @subsection Using Lexical Binding @@ -1069,19 +1081,22 @@ discouraged. Doing so gives rise to unspecified behavior when lexical binding mode is enabled (it may use lexical binding sometimes, and dynamic binding other times). - Converting an Emacs Lisp program to lexical binding is pretty easy. -First, add a file-local variable setting of @code{lexical-binding} to -@code{t} in the Emacs Lisp source file. Second, check that every -variable in the program which needs to be dynamically bound has a -variable definition, so that it is not inadvertently bound lexically. + Converting an Emacs Lisp program to lexical binding is easy. First, +add a file-local variable setting of @code{lexical-binding} to +@code{t} in the header line of the Emacs Lisp source file (@pxref{File +Local Variables}). Second, check that every variable in the program +which needs to be dynamically bound has a variable definition, so that +it is not inadvertently bound lexically. +@cindex free variable +@cindex unused lexical variable A simple way to find out which variables need a variable definition is to byte-compile the source file. @xref{Byte Compilation}. If a non-special variable is used outside of a @code{let} form, the -byte-compiler will warn about reference or assignment to a ``free -variable''. If a non-special variable is bound but not used within a -@code{let} form, the byte-compiler will warn about an ``unused lexical -variable''. The byte-compiler will also issue a warning if you use a +byte-compiler will warn about reference or assignment to a free +variable. If a non-special variable is bound but not used within a +@code{let} form, the byte-compiler will warn about an unused lexical +variable. The byte-compiler will also issue a warning if you use a special variable as a function argument. (To silence byte-compiler warnings about unused variables, just use @@ -1387,9 +1402,10 @@ buffer-local variable interactively, just as it is useful to create buffer-local variables interactively. @end deffn +@cindex local variables, killed by major mode @defun kill-all-local-variables This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent'' and local +current buffer except for variables marked as permanent and local hook functions that have a non-@code{nil} @code{permanent-local-hook} property (@pxref{Setting Hooks}). As a result, the buffer will see the default values of most variables. @@ -1649,8 +1665,7 @@ non-@code{nil} given that value. Many commonly-encountered file variables have @code{safe-local-variable} properties; these include @code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}. For boolean-valued variables that are safe, use @code{booleanp} as the -property value. Lambda expressions should be quoted so that -@code{describe-variable} can display the predicate. +property value. When defining a user option using @code{defcustom}, you can set its @code{safe-local-variable} property by adding the arguments @@ -1835,6 +1850,12 @@ modification times of the associated directory local variables file updates this list. @end defvar +@defvar enable-dir-local-variables +If @code{nil}, directory-local variables are ignored. This variable +may be useful for modes that want to ignore directory-locals while +still respecting file-local variables (@pxref{File Local Variables}). +@end defvar + @node Variable Aliases @section Variable Aliases @cindex variable aliases @@ -1881,8 +1902,8 @@ the variable was first made obsolete (usually a version number string). The optional argument @var{access-type}, if non-@code{nil}, should -should specify the kind of access that will trigger obsolescence -warnings; it can be either @code{get} or @code{set}. +specify the kind of access that will trigger obsolescence warnings; it +can be either @code{get} or @code{set}. @end defun You can make two variables synonyms and declare one obsolete at the @@ -1930,6 +1951,7 @@ foo @node Variables with Restricted Values @section Variables with Restricted Values +@cindex lisp variables defined in C, restrictions Ordinary Lisp variables can be assigned any value that is a valid Lisp object. However, certain Lisp variables are not defined in Lisp, @@ -1955,7 +1977,7 @@ will set them to @code{t}: This variable holds a list of all variables of type @code{DEFVAR_BOOL}. @end defvar - Variables of type @code{DEFVAR_INT} can only take on integer values. + Variables of type @code{DEFVAR_INT} can take on only integer values. Attempting to assign them any other value will result in an error: @example @@ -1966,13 +1988,15 @@ Attempting to assign them any other value will result in an error: @node Generalized Variables @section Generalized Variables +@cindex generalized variable +@cindex place form A @dfn{generalized variable} or @dfn{place form} is one of the many places in Lisp memory where values can be stored. The simplest place form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values are stored. -Generalized variables are analogous to ``lvalues'' in the C +Generalized variables are analogous to lvalues in the C language, where @samp{x = a[i]} gets an element from an array and @samp{a[i] = x} stores an element using the same notation. Just as certain forms like @code{a[i]} can be lvalues in C, there @@ -2145,7 +2169,7 @@ of Common Lisp. Consult the source file @file{gv.el} for more details. @cindex CL note---no @code{setf} functions @quotation @b{Common Lisp note:} Common Lisp defines another way to specify the -@code{setf} behavior of a function, namely ``@code{setf} functions'', +@code{setf} behavior of a function, namely @code{setf} functions, whose names are lists @code{(setf @var{name})} rather than symbols. For example, @code{(defun (setf foo) @dots{})} defines the function that is used when @code{setf} is applied to @code{foo}. Emacs does diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 13c9ca53222..1da2d1cfe7b 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Windows @@ -16,6 +16,7 @@ is displayed in windows. * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Creating a new window. * Deleting Windows:: Removing a window from its frame. * Recombining Windows:: Preserving the frame layout when splitting and @@ -137,7 +138,7 @@ window). Each window belongs to exactly one frame (@pxref{Frames}). -@defun window-frame window +@defun window-frame &optional window This function returns the frame that the window @var{window} belongs to. If @var{window} is @code{nil}, it defaults to the selected window. @@ -252,19 +253,19 @@ child windows form a horizontal combination, consisting of the live window @var{W2} and the internal window @var{W3}. The child windows of @var{W3} form a vertical combination, consisting of the live windows @var{W4} and @var{W5}. Hence, the live windows in this -window tree are @var{W2} @var{W4}, and @var{W5}. +window tree are @var{W2}, @var{W4}, and @var{W5}. The following functions can be used to retrieve a child window of an internal window, and the siblings of a child window. -@defun window-top-child window +@defun window-top-child &optional window This function returns the topmost child window of @var{window}, if @var{window} is an internal window whose children form a vertical combination. For any other type of window, the return value is @code{nil}. @end defun -@defun window-left-child window +@defun window-left-child &optional window This function returns the leftmost child window of @var{window}, if @var{window} is an internal window whose children form a horizontal combination. For any other type of window, the return value is @@ -322,7 +323,7 @@ the assumption that the frame from our canonical example is selected @end defun @cindex window in direction -@defun window-in-direction direction &optional window ignore +@defun window-in-direction direction &optional window ignore sign wrap mini This function returns the nearest live window in direction @var{direction} as seen from the position of @code{window-point} in window @var{window}. The argument @var{direction} must be one of @@ -338,6 +339,23 @@ function tries to find another window in the indicated direction whose argument @var{ignore} is non-@code{nil}, a window may be returned even if its @code{no-other-window} parameter is non-@code{nil}. +If the optional argument @var{sign} is a negative number, it means to +use the right or bottom edge of @var{window} as reference position +instead of @code{window-point}. If @var{sign} is a positive number, it +means to use the left or top edge of @var{window} as reference position. + +If the optional argument @var{wrap} is non-@code{nil}, this means to +wrap @var{direction} around frame borders. For example, if @var{window} +is at the top of the frame and @var{direction} is @code{above}, then +return the minibuffer window provided the frame has one, and a window at +the bottom of the frame otherwise. + +If the optional argument @var{mini} is @code{nil}, this means to return +the minibuffer window if and only if it is currently active. If +@var{mini} is non-@code{nil}, it returns the minibuffer window even when +it's not active. However, if @var{wrap} non-@code{nil}, it always acts +as if @var{mini} were @code{nil}. + If it doesn't find a suitable window, this function returns @code{nil}. @end defun @@ -365,6 +383,7 @@ internal window). The @var{edges} element is a list @code{(@var{left} @code{window-edges} (@pxref{Coordinates and Windows}). @end defun + @node Window Sizes @section Window Sizes @cindex window size @@ -374,18 +393,19 @@ internal window). The @var{edges} element is a list @code{(@var{left} @smallexample @group - _________________________________________ - ^ |______________ Header Line_______________| - | |LS|LF|LM| |RM|RF|RS| ^ - | | | | | | | | | | - Window | | | | Text Area | | | | Window - Total | | | | (Window Body) | | | | Body - Height | | | | | | | | Height - | | | | |<- Window Body Width ->| | | | | - | |__|__|__|_______________________|__|__|__| v - v |_______________ Mode Line _______________| - - <----------- Window Total Width --------> + ____________________________________________ + |______________ Header Line ______________|RD| ^ + ^ |LS|LM|LF| |RF|RM|RS| | | + | | | | | | | | | | | +Window | | | | Text Area | | | | | Window +Body | | | | | (Window Body) | | | | | Total +Height | | | | | | | | | Height + | | | | |<- Window Body Width ->| | | | | | + v |__|__|__|_______________________|__|__|__| | | + |_________ Horizontal Scroll Bar _________| | | + |_______________ Mode Line _______________|__| | + |_____________ Bottom Divider _______________| v + <---------- Window Total Width ------------> @end group @end smallexample @@ -394,59 +414,125 @@ internal window). The @var{edges} element is a list @code{(@var{left} @cindex text area of a window @cindex body of a window At the center of the window is the @dfn{text area}, or @dfn{body}, -where the buffer text is displayed. On each side of the text area is -a series of vertical areas; from innermost to outermost, these are the -left and right margins, denoted by LM and RM in the schematic -(@pxref{Display Margins}); the left and right fringes, denoted by LF -and RF (@pxref{Fringes}); and the left or right scroll bar, only one of -which is present at any time, denoted by LS and RS (@pxref{Scroll -Bars}). At the top of the window is an optional header line -(@pxref{Header Lines}), and at the bottom of the window is the mode -line (@pxref{Mode Line Format}). - - Emacs provides several functions for finding the height and width of -a window. Except where noted, Emacs reports window heights and widths -as integer numbers of lines and columns, respectively. On a graphical -display, each ``line'' and ``column'' actually corresponds to the -height and width of a ``default'' character specified by the frame's -default font. Thus, if a window is displaying text with a different -font or size, the reported height and width for that window may differ -from the actual number of text lines or columns displayed within it. +where the buffer text is displayed. The text area can be surrounded by +a series of optional areas. On the left and right, from innermost to +outermost, these are the left and right fringes, denoted by LF and RF +(@pxref{Fringes}); the left and right margins, denoted by LM and RM in +the schematic (@pxref{Display Margins}); the left or right vertical +scroll bar, only one of which is present at any time, denoted by LS and +RS (@pxref{Scroll Bars}); and the right divider, denoted by RD +(@pxref{Window Dividers}). At the top of the window is the header line +(@pxref{Header Lines}). At the bottom of the window are the horizontal +scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line +Format}); and the bottom divider (@pxref{Window Dividers}). + + Emacs provides miscellaneous functions for finding the height and +width of a window. The return value of many of these functions can be +specified either in units of pixels or in units of lines and columns. +On a graphical display, the latter actually correspond to the height and +width of a default character specified by the frame's default font +as returned by @code{frame-char-height} and @code{frame-char-width} +(@pxref{Frame Font}). Thus, if a window is displaying text with a +different font or size, the reported line height and column width for +that window may differ from the actual number of text lines or columns +displayed within it. @cindex window height @cindex height of a window @cindex total height of a window + The @dfn{total height} of a window is the number of lines comprising +the window's body, the header line, the horizontal scroll bar, the mode +line and the bottom divider (if any). + +@defun window-total-height &optional window round +This function returns the total height, in lines, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. If @var{window} is an internal window, the return +value is the total height occupied by its descendant windows. + + If a window's pixel height is not an integral multiple of its frame's +default character height, the number of lines occupied by the window is +rounded internally. This is done in a way such that, if the window is a +parent window, the sum of the total heights of all its child windows +internally equals the total height of their parent. This means that +although two windows have the same pixel height, their internal total +heights may differ by one line. This means also, that if window is +vertically combined and has a next sibling, the topmost row of that +sibling can be calculated as the sum of this window's topmost row and +total height (@pxref{Coordinates and Windows}) + + If the optional argument @var{round} is @code{ceiling}, this +function returns the smallest integer larger than @var{window}'s pixel +height divided by the character height of its frame; if it is +@code{floor}, it returns the largest integer smaller than said value; +with any other @var{round} it returns the internal value of +@var{windows}'s total height. +@end defun + @cindex window width @cindex width of a window @cindex total width of a window - The @dfn{total height} of a window is the distance between the top -and bottom of the window, including the header line (if one exists) -and the mode line. The @dfn{total width} of a window is the distance -between the left and right edges of the mode line. Note that the -height of a frame is not the same as the height of its windows, since -a frame may also contain an echo area, menu bar, and tool bar -(@pxref{Size and Position}). +The @dfn{total width} of a window is the number of lines comprising the +window's body, its margins, fringes, scroll bars and a right divider (if +any). -@defun window-total-height &optional window -This function returns the total height, in lines, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. If @var{window} is an internal window, the -return value is the total height occupied by its descendant windows. +@defun window-total-width &optional window round +This function returns the total width, in columns, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. If @var{window} is internal, the return value is +the total width occupied by its descendant windows. + + If a window's pixel width is not an integral multiple of its frame's +character width, the number of lines occupied by the window is rounded +internally. This is done in a way such that, if the window is a parent +window, the sum of the total widths of all its children internally +equals the total width of their parent. This means that although two +windows have the same pixel width, their internal total widths may +differ by one column. This means also, that if this window is +horizontally combined and has a next sibling, the leftmost column of +that sibling can be calculated as the sum of this window's leftmost +column and total width (@pxref{Coordinates and Windows}). The optional +argument @var{round} behaves as it does for @code{window-total-height}. @end defun -@defun window-total-width &optional window -This function returns the total width, in columns, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. If @var{window} is internal, the return value -is the total width occupied by its descendant windows. +@defun window-total-size &optional window horizontal round +This function returns either the total height in lines or the total +width in columns of the window @var{window}. If @var{horizontal} is +omitted or @code{nil}, this is equivalent to calling +@code{window-total-height} for @var{window}; otherwise it is equivalent +to calling @code{window-total-width} for @var{window}. The optional +argument @var{round} behaves as it does for @code{window-total-height}. @end defun -@defun window-total-size &optional window horizontal -This function returns either the total height or width of the window -@var{window}. If @var{horizontal} is omitted or @code{nil}, this is -equivalent to calling @code{window-total-height} for @var{window}; -otherwise it is equivalent to calling @code{window-total-width} for -@var{window}. +The following two functions can be used to return the total size of a +window in units of pixels. + +@cindex window pixel height +@cindex pixel height of a window +@cindex total pixel height of a window + +@defun window-pixel-height &optional window +This function returns the total height of window @var{window} in pixels. +@var{window} must be a valid window and defaults to the selected one. + +The return value includes mode and header line, a horizontal scroll bar +and a bottom divider, if any. If @var{window} is an internal window, +its pixel height is the pixel height of the screen areas spanned by its +children. +@end defun + +@cindex window pixel height +@cindex pixel height of a window +@cindex total pixel height of a window + +@defun window-pixel-width &optional Lisp_Object &optional window +This function returns the width of window @var{window} in pixels. +@var{window} must be a valid window and defaults to the selected one. + +The return value includes the fringes and margins of @var{window} as +well as any vertical dividers or scroll bars belonging to @var{window}. +If @var{window} is an internal window, its pixel width is the width of +the screen areas spanned by its children. @end defun @cindex full-width window @@ -455,10 +541,12 @@ otherwise it is equivalent to calling @code{window-total-width} for window has any adjacent windows. @defun window-full-height-p &optional window -This function returns non-@code{nil} if @var{window} has no other -window above or below it in its frame, i.e., its total height equals -the total height of the root window on that frame. If @var{window} is -omitted or @code{nil}, it defaults to the selected window. +This function returns non-@code{nil} if @var{window} has no other window +above or below it in its frame. More precisely, this means that the +total height of @var{window} equals the total height of the root window +on that frame. The minibuffer window does not count in this regard. If +@var{window} is omitted or @code{nil}, it defaults to the selected +window. @end defun @defun window-full-width-p &optional window @@ -471,40 +559,52 @@ that of the root window on that frame. If @var{window} is omitted or @cindex window body height @cindex body height of a window @cindex window body width +The @dfn{body height} of a window is the height of its text area, which +does not include a mode or header line, a horizontal scroll bar, or a +bottom divider. + +@defun window-body-height &optional window pixelwise +This function returns the height, in lines, of the body of window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window; otherwise it must be a live window. + +If the optional argument @var{pixelwise} is non-@code{nil}, this +function returns the body height of @var{window} counted in pixels. + +If @var{pixelwise} is @code{nil}, the return value is rounded down to +the nearest integer, if necessary. This means that if a line at the +bottom of the text area is only partially visible, that line is not +counted. It also means that the height of a window's body can never +exceed its total height as returned by @code{window-total-height}. +@end defun + @cindex body width of a window @cindex body size of a window @cindex window body size - The @dfn{body height} of a window is the height of its text area, -which does not include the mode or header line. Similarly, the -@dfn{body width} is the width of the text area, which does not include -the scroll bar, fringes, or margins. - -@defun window-body-height &optional window -This function returns the body height, in lines, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window; otherwise it must be a live window. - -If there is a partially-visible line at the bottom of the text area, -that counts as a whole line; to exclude such a partially-visible line, -use @code{window-text-height}, below. -@end defun - -@defun window-body-width &optional window -This function returns the body width, in columns, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window; otherwise it must be a live window. -@end defun - -@defun window-body-size &optional window horizontal -This function returns the body height or body width of @var{window}. -If @var{horizontal} is omitted or @code{nil}, it is equivalent to -calling @code{window-body-height} for @var{window}; otherwise it is -equivalent to calling @code{window-body-width}. +The @dfn{body width} of a window is the width of its text area, which +does not include the scroll bar, fringes, margins or a right divider. + +@defun window-body-width &optional window pixelwise +This function returns the width, in columns, of the body of window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window; otherwise it must be a live window. + +If the optional argument @var{pixelwise} is non-@code{nil}, this +function returns the body width of @var{window} in units of pixels. + +If @var{pixelwise} is @code{nil}, the return value is rounded down to +the nearest integer, if necessary. This means that if a column on the +right of the text area is only partially visible, that column is not +counted. It also means that the width of a window's body can never +exceed its total width as returned by @code{window-total-width}. @end defun -@defun window-text-height &optional window -This function is like @code{window-body-height}, except that any -partially-visible line at the bottom of the text area is not counted. +@defun window-body-size &optional window horizontal pixelwise +This function returns the body height or body width of @var{window}. If +@var{horizontal} is omitted or @code{nil}, it is equivalent to calling +@code{window-body-height} for @var{window}; otherwise it is equivalent +to calling @code{window-body-width}. In either case, the optional +argument @var{pixelwise} is passed to the function called. @end defun For compatibility with previous versions of Emacs, @@ -512,47 +612,84 @@ partially-visible line at the bottom of the text area is not counted. @code{window-width} is an alias for @code{window-body-width}. These aliases are considered obsolete and will be removed in the future. + The pixel heights of a window's mode and header line can be retrieved +with the functions given below. Their return value is usually accurate +unless the window has not been displayed before: In that case, the +return value is based on an estimate of the font used for the window's +frame. + +@defun window-mode-line-height &optional window +This function returns the height in pixels of @var{window}'s mode line. +@var{window} must be a live window and defaults to the selected one. If +@var{window} has no mode line, the return value is zero. +@end defun + +@defun window-header-line-height &optional window +This function returns the height in pixels of @var{window}'s header +line. @var{window} must be a live window and defaults to the selected +one. If @var{window} has no header line, the return value is zero. +@end defun + +Functions for retrieving the height and/or width of window dividers +(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars +(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are +described in the corresponding sections. + @cindex fixed-size window @vindex window-min-height @vindex window-min-width Commands that change the size of windows (@pxref{Resizing Windows}), or split them (@pxref{Splitting Windows}), obey the variables -@code{window-min-height} and @code{window-min-width}, which specify -the smallest allowable window height and width. @xref{Change -Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs -Manual}. They also obey the variable @code{window-size-fixed}, with -which a window can be @dfn{fixed} in size: - -@defvar window-size-fixed -If this buffer-local variable is non-@code{nil}, the size of any -window displaying the buffer cannot normally be changed. Deleting a -window or changing the frame's size may still change its size, if -there is no choice. - -If the value is @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. -@end defvar +@code{window-min-height} and @code{window-min-width}, which specify the +smallest allowable window height and width. They also obey the variable +@code{window-size-fixed}, with which a window can be @dfn{fixed} in +size: + +@defopt window-min-height +This option specifies the minimum total height, in lines, of any window. +Its value has to accommodate at least one text line as well as a mode +and header line, a horizontal scroll bar and a bottom divider, if +present. +@end defopt -@defun window-size-fixed-p &optional window horizontal -This function returns a non-@code{nil} value if @var{window}'s height -is fixed. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If the optional argument @var{horizontal} is -non-@code{nil}, the return value is non-@code{nil} if @var{window}'s -width is fixed. +@defopt window-min-width +This option specifies the minimum total width, in columns, of any +window. Its value has to accommodate two text columns as well as +margins, fringes, a scroll bar and a right divider, if present. +@end defopt -A @code{nil} return value does not necessarily mean that @var{window} -can be resized in the desired direction. To determine that, use the -function @code{window-resizable}. @xref{Resizing Windows}. +The following function tells how small a specific window can get taking +into account the sizes of its areas and the values of +@code{window-min-height}, @code{window-min-width} and +@code{window-size-fixed}. + +@defun window-min-size &optional window horizontal ignore pixelwise +This function returns the minimum size of @var{window}. @var{window} +must be a valid window and defaults to the selected one. The optional +argument @var{horizontal} non-@code{nil} means to return the minimum +number of columns of @var{window}; otherwise return the minimum number +of @var{window}'s lines. + +The return value makes sure that all components of @var{window} remain +fully visible if @var{window}'s size were actually set to it. With +@var{horizontal} @code{nil} it includes the mode and header line, the +horizontal scroll bar and the bottom divider. With @var{horizontal} +non-@code{nil} it includes the fringes, a scroll bar, and a right +divider, if present. It does not, however, include the space reserved +for the margins. + +The optional argument @var{ignore}, if non-@code{nil}, means ignore +restrictions imposed by fixed size windows, @code{window-min-height} or +@code{window-min-width} settings. If @var{ignore} equals @code{safe}, +live windows may get as small as @code{window-safe-min-height} lines and +@code{window-safe-min-width} columns. If @var{ignore} is a window, +ignore restrictions for that window only. Any other non-@code{nil} +value means ignore all of the above restrictions for all windows. + +The optional argument @var{pixelwise} non-@code{nil} means to return the +minimum size of @var{window} counted in pixels. @end defun - @xref{Coordinates and Windows}, for more functions that report the -positions of various parts of a window relative to the frame, from -which you can calculate its size. In particular, you can use the -functions @code{window-pixel-edges} and -@code{window-inside-pixel-edges} to find the size in pixels, for -graphical displays. - @node Resizing Windows @section Resizing Windows @cindex window resizing @@ -571,7 +708,7 @@ changed except by resizing the frame (@pxref{Size and Position}). arguments. Resizing an internal window causes its child windows to be resized to fit the same space. -@defun window-resizable window delta &optional horizontal ignore +@defun window-resizable window delta &optional horizontal ignore pixelwise This function returns @var{delta} if the size of @var{window} can be changed vertically by @var{delta} lines. If the optional argument @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if @@ -587,18 +724,21 @@ lines or columns. If @var{delta} is non-zero, a return value of 0 means that the window cannot be resized. Normally, the variables @code{window-min-height} and -@code{window-min-width} specify the smallest allowable window size. -@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU -Emacs Manual}. However, if the optional argument @var{ignore} is -non-@code{nil}, this function ignores @code{window-min-height} and -@code{window-min-width}, as well as @code{window-size-fixed}. -Instead, it considers the minimum-height window to be one consisting -of a header (if any), a mode line, plus a text area one line tall; and -a minimum-width window as one consisting of fringes, margins, and -scroll bar (if any), plus a text area two columns wide. -@end defun - -@defun window-resize window delta &optional horizontal ignore +@code{window-min-width} specify the smallest allowable window size +(@pxref{Window Sizes}). However, if the optional argument @var{ignore} +is non-@code{nil}, this function ignores @code{window-min-height} and +@code{window-min-width}, as well as @code{window-size-fixed}. Instead, +it considers the minimum-height window to be one consisting of a header +and a mode line, a horizontal scrollbar and a bottom divider (if any), +plus a text area one line tall; and a minimum-width window as one +consisting of fringes, margins, a scroll bar and a right divider (if +any), plus a text area two columns wide. + +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} is interpreted as pixels. +@end defun + +@defun window-resize window delta &optional horizontal ignore pixelwise This function resizes @var{window} by @var{delta} increments. If @var{horizontal} is @code{nil}, it changes the height by @var{delta} lines; otherwise, it changes the width by @var{delta} columns. A @@ -611,24 +751,30 @@ the window cannot be resized as demanded, an error is signaled. The optional argument @var{ignore} has the same meaning as for the function @code{window-resizable} above. +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} will be interpreted as pixels. + The choice of which window edges this function alters depends on the values of the option @code{window-combination-resize} and the combination limits of the involved windows; in some cases, it may alter both edges. @xref{Recombining Windows}. To resize by moving only the bottom or right edge of a window, use the function -@code{adjust-window-trailing-edge}, below. +@code{adjust-window-trailing-edge}. @end defun @c The commands enlarge-window, enlarge-window-horizontally, @c shrink-window, and shrink-window-horizontally are documented in the @c Emacs manual. They are not preferred for calling from Lisp. -@defun adjust-window-trailing-edge window delta &optional horizontal +@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise This function moves @var{window}'s bottom edge by @var{delta} lines. If optional argument @var{horizontal} is non-@code{nil}, it instead moves the right edge by @var{delta} columns. If @var{window} is @code{nil}, it defaults to the selected window. +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} is interpreted as pixels. + A positive @var{delta} moves the edge downwards or to the right; a negative @var{delta} moves it upwards or to the left. If the edge cannot be moved as far as specified by @var{delta}, this function @@ -639,31 +785,119 @@ moved. If this is not possible for some reason (e.g., if that adjacent window is fixed-size), it may resize other windows. @end defun +@cindex pixelwise, resizing windows +@defopt window-resize-pixelwise +If the value of this option is non-@code{nil}, Emacs resizes windows in +units of pixels. This currently affects functions like +@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window}, +@code{minimize-window}, @code{fit-window-to-buffer}, +@code{fit-frame-to-buffer} and +@code{shrink-window-if-larger-than-buffer} (all listed below). + +Note that when a frame's pixel size is not a multiple of its character +size, at least one window may get resized pixelwise even if this +option is @code{nil}. The default value is @code{nil}. +@end defopt + The following commands resize windows in more specific ways. When called interactively, they act on the selected window. -@deffn Command fit-window-to-buffer &optional window max-height min-height override -This command adjusts the height of @var{window} to fit the text in it. -It returns non-@code{nil} if it was able to resize @var{window}, and -@code{nil} otherwise. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. Otherwise, it should be a live -window. +@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size +This command adjusts the height or width of @var{window} to fit the text +in it. It returns non-@code{nil} if it was able to resize @var{window}, +and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it +defaults to the selected window. Otherwise, it should be a live window. + +If @var{window} is part of a vertical combination, this function adjusts +@var{window}'s height. The new height is calculated from the actual +height of the accessible portion of its buffer. The optional argument +@var{max-height}, if non-@code{nil}, specifies the maximum total height +that this function can give @var{window}. The optional argument +@var{min-height}, if non-@code{nil}, specifies the minimum total height +that it can give, which overrides the variable @code{window-min-height}. +Both @var{max-height} and @var{min-height} are specified in lines and +include mode and header line and a bottom divider, if any. + +If @var{window} is part of a horizontal combination and the value of the +option @code{fit-window-to-buffer-horizontally} (see below) is +non-@code{nil}, this function adjusts @var{window}'s height. The new +width of @var{window} is calculated from the maximum length of its +buffer's lines that follow the current start position of @var{window}. +The optional argument @var{max-width} specifies a maximum width and +defaults to the width of @var{window}'s frame. The optional argument +@var{min-width} specifies a minimum width and defaults to +@code{window-min-width}. Both @var{max-width} and @var{min-width} are +specified in columns and include fringes, margins and scrollbars, if +any. -The optional argument @var{max-height}, if non-@code{nil}, specifies -the maximum total height that this function can give @var{window}. -The optional argument @var{min-height}, if non-@code{nil}, specifies -the minimum total height that it can give, which overrides the -variable @code{window-min-height}. +The optional argument @var{preserve-size}, if non-@code{nil}, will +install a parameter to preserve the size of @var{window} during future +resize operations (@pxref{Preserving Window Sizes}). -If the optional argument @var{override} is non-@code{nil}, this -function ignores any size restrictions imposed by -@code{window-min-height} and @code{window-min-width}. +If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil}, +this function will try to resize the frame of @var{window} to fit its +contents by calling @code{fit-frame-to-buffer} (see below). +@end deffn -@vindex fit-frame-to-buffer -If the option @code{fit-frame-to-buffer} is non-@code{nil}, this -command may resize the frame to fit its contents. +@defopt fit-window-to-buffer-horizontally +If this is non-@code{nil}, @code{fit-window-to-buffer} can resize +windows horizontally. If this is @code{nil} (the default) +@code{fit-window-to-buffer} never resizes windows horizontally. If this +is @code{only}, it can resize windows horizontally only. Any other +value means @code{fit-window-to-buffer} can resize windows in both +dimensions. +@end defopt + +@defopt fit-frame-to-buffer +If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a +frame to its buffer. A frame is fit if and only if its root window is a +live window and this option is non-@code{nil}. If this is +@code{horizontally}, frames are fit horizontally only. If this is +@code{vertically}, frames are fit vertically only. Any other +non-@code{nil} value means frames can be resized in both dimensions. +@end defopt + +If you have a frame that displays only one window, you can fit that +frame to its buffer using the command @code{fit-frame-to-buffer}. + +@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only +This command adjusts the size of @var{frame} to display the contents of +its buffer exactly. @var{frame} can be any live frame and defaults to +the selected one. Fitting is done only if @var{frame}'s root window is +live. The arguments @var{max-height}, @var{min-height}, @var{max-width} +and @var{min-width} specify bounds on the new total size of +@var{frame}'s root window. @var{min-height} and @var{min-width} default +to the values of @code{window-min-height} and @code{window-min-width} +respectively. + +If the optional argument @var{only} is @code{vertically}, this function +may resize the frame vertically only. If @var{only} is +@code{horizontally}, it may resize the frame horizontally only. @end deffn +The behavior of @code{fit-frame-to-buffer} can be controlled with the +help of the two options listed next. + +@defopt fit-frame-to-buffer-margins +This option can be used to specify margins around frames to be fit by +@code{fit-frame-to-buffer}. Such margins can be useful to avoid, for +example, that such frames overlap the taskbar. + +It specifies the numbers of pixels to be left free on the left, above, +the right, and below a frame that shall be fit. The default specifies +@code{nil} for each which means to use no margins. The value specified +here can be overridden for a specific frame by that frame's +@code{fit-frame-to-buffer-margins} parameter, if present. +@end defopt + +@defopt fit-frame-to-buffer-sizes +This option specifies size boundaries for @code{fit-frame-to-buffer}. +It specifies the total maximum and minimum lines and maximum and minimum +columns of the root window of any frame that shall be fit to its buffer. +If any of these values is non-@code{nil}, it overrides the corresponding +argument of @code{fit-frame-to-buffer}. +@end defopt + @deffn Command shrink-window-if-larger-than-buffer &optional window This command attempts to reduce @var{window}'s height as much as possible while still showing its full buffer, but no less than @@ -675,8 +909,12 @@ it should be a live window. This command does nothing if the window is already too short to display all of its buffer, or if any of the buffer is scrolled off-screen, or if the window is the only live window in its frame. + +This command calls @code{fit-window-to-buffer} (see above) to do its +work. @end deffn + @cindex balancing window sizes @deffn Command balance-windows &optional window-or-frame This function balances windows in a way that gives more space to @@ -709,6 +947,98 @@ window. @end deffn +@node Preserving Window Sizes +@section Preserving Window Sizes +@cindex preserving window sizes + +A window can get resized explicitly by using one of the functions from +the preceding section or implicitly, for example, when resizing an +adjacent window, when splitting or deleting a window (@pxref{Splitting +Windows}, @pxref{Deleting Windows}) or when resizing the window's frame +(@pxref{Size and Position}). + + It is possible to avoid implicit resizing of a specific window when +there are one or more other resizable windows on the same frame. For +this purpose, Emacs must be advised to @dfn{preserve} the size of that +window. There are two basic ways to do that. + +@defvar window-size-fixed +If this buffer-local variable is non-@code{nil}, the size of any window +displaying the buffer cannot normally be changed. Deleting a window or +changing the frame's size may still change the window's size, if there +is no choice. + +If the value is @code{height}, then only the window's height is fixed; +if the value is @code{width}, then only the window's width is fixed. +Any other non-@code{nil} value fixes both the width and the height. + +If this variable is @code{nil}, this does not necessarily mean that any +window showing the buffer can be resized in the desired direction. To +determine that, use the function @code{window-resizable}. +@xref{Resizing Windows}. +@end defvar + +Often @code{window-size-fixed} is overly aggressive because it inhibits +any attempt to explicitly resize or split an affected window as well. +This may even happen after the window has been resized implicitly, for +example, when deleting an adjacent window or resizing the window's +frame. The following function tries hard to never disallow resizing +such a window explicitly: + +@defun window-preserve-size &optional window horizontal preserve +This function (un-)marks the height of window @var{window} as preserved +for future resize operations. @var{window} must be a live window and +defaults to the selected one. If the optional argument @var{horizontal} +is non-@code{nil}, it (un-)marks the width of @var{window} as preserved. + +If the optional argument @var{preserve} is @code{t}, this means to +preserve the current height/width of @var{window}'s body. The +height/width of @var{window} will change only if Emacs has no better +choice. Resizing a window whose height/width is preserved by this +function never throws an error. + +If @var{preserve} is @code{nil}, this means to stop preserving the +height/width of @var{window}, lifting any respective restraint induced +by a previous call of this function for @var{window}. Calling +@code{enlarge-window}, @code{shrink-window} or +@code{fit-window-to-buffer} with @var{window} as argument may also +remove the respective restraint. +@end defun + +@code{window-preserve-size} is currently invoked by the following +functions: + +@table @code +@item fit-window-to-buffer +If the optional argument @var{preserve-size} of that function +(@pxref{Resizing Windows}) is non-@code{nil}, the size established by +that function is preserved. + +@item display-buffer +If the @var{alist} argument of that function (@pxref{Choosing Window}) +contains a @code{preserve-size} entry, the size of the window produced +by that function is preserved. +@end table + + @code{window-preserve-size} installs a window parameter (@pxref{Window +Parameters}) called @code{preserved-size} which is consulted by the +window resizing functions. This parameter will not prevent resizing the +window when the window shows another buffer than the one when +@code{window-preserve-size} was invoked or if its size has changed since +then. + +The following function can be used to check whether the height of a +particular window is preserved: + +@defun window-preserved-size &optional window horizontal +This function returns the preserved height of window @var{window} in +pixels. @var{window} must be a live window and defaults to the selected +one. If the optional argument @var{horizontal} is non-@code{nil}, it +returns the preserved width of @var{window}. It returns @code{nil} if +the size of @var{window} is not preserved. +@end defun + + @node Splitting Windows @section Splitting Windows @cindex splitting windows @@ -717,10 +1047,10 @@ window. This section describes functions for creating a new window by @dfn{splitting} an existing one. -@defun split-window &optional window size side +@defun split-window &optional window size side pixelwise This function creates a new live window next to the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. That window is ``split'', and reduced in +to the selected window. That window is split, and reduced in size. The space is taken up by the new window, which is returned. The optional second argument @var{size} determines the sizes of @@ -732,15 +1062,25 @@ value of @var{side}). If @var{size} is a negative number, the new window is given @minus{}@var{size} lines (or columns). If @var{size} is @code{nil}, this function obeys the variables -@code{window-min-height} and @code{window-min-width}. @xref{Change -Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs -Manual}. Thus, it signals an error if splitting would result in -making a window smaller than those variables specify. However, a +@code{window-min-height} and @code{window-min-width} (@pxref{Window +Sizes}). Thus, it signals an error if splitting would result in making +a window smaller than those variables specify. However, a non-@code{nil} value for @var{size} causes those variables to be -ignored; in that case, the smallest allowable window is considered to -be one that has space for a text area one line tall and/or two columns +ignored; in that case, the smallest allowable window is considered to be +one that has space for a text area one line tall and/or two columns wide. +Hence, if @var{size} is specified, it's the caller's responsibility to +check whether the emanating windows are large enough to encompass all +areas like a mode line or a scroll bar. The function +@code{window-min-size} (@pxref{Window Sizes}) can be used to determine +the minimum requirements of @var{window} in this regard. Since the new +window usually inherits areas like the mode line or the scroll bar +from @var{window}, that function is also a good guess for the minimum +size of the new window. The caller should specify a smaller size only +if it correspondingly removes an inherited area before the next +redisplay. + The optional third argument @var{side} determines the position of the new window relative to @var{window}. If it is @code{nil} or @code{below}, the new window is placed below @var{window}. If it is @@ -752,6 +1092,10 @@ the right of @var{window}. If @var{side} is @code{left}, the new window is placed on the left of @var{window}. In both these cases, @var{size} specifies a total window width, in columns. +The optional fourth argument @var{pixelwise}, if non-@code{nil}, means +to interpret @var{size} in units of pixels, instead of lines and +columns. + If @var{window} is a live window, the new window inherits various properties from it, including margins and scroll bars. If @var{window} is an internal window, the new window inherits the @@ -855,6 +1199,7 @@ point was previously on. Note that this only affects function. @end defopt + @node Deleting Windows @section Deleting Windows @cindex deleting windows @@ -947,6 +1292,8 @@ are the opposite of what they are in those other functions. @node Recombining Windows @section Recombining Windows +@cindex recombining windows +@cindex windows, recombining When deleting the last sibling of a window @var{W}, its parent window is deleted too, with @var{W} replacing it in the window tree. This @@ -1164,7 +1511,7 @@ vertical combination @var{W1}. @cindex window combination limit @defun set-window-combination-limit window limit -This functions sets the @dfn{combination limit} of the window +This function sets the @dfn{combination limit} of the window @var{window} to @var{limit}. This value can be retrieved via the function @code{window-combination-limit}. See below for its effects; note that it is only meaningful for internal windows. The @@ -1298,16 +1645,27 @@ windows. @defun select-window window &optional norecord This function makes @var{window} the selected window and the window selected within its frame (@pxref{Basic Windows}) and selects that -frame. @var{window} must be a live window. This function also makes -@var{window}'s buffer (@pxref{Buffers and Windows}) current and sets -that buffer's value of @code{point} to the value of @code{window-point} -(@pxref{Window Point}) in @var{window}. The return value is -@var{window}. +frame. It also makes @var{window}'s buffer (@pxref{Buffers and +Windows}) current and sets that buffer's value of @code{point} to the +value of @code{window-point} (@pxref{Window Point}) in @var{window}. +@var{window} must be a live window. The return value is @var{window}. By default, this function also moves @var{window}'s buffer to the front -of the buffer list (@pxref{The Buffer List}), and makes @var{window} the +of the buffer list (@pxref{Buffer List}), and makes @var{window} the most recently selected window. However, if the optional argument @var{norecord} is non-@code{nil}, these additional actions are omitted. + +This function runs @code{buffer-list-update-hook} (@pxref{Buffer List}) +unless @var{norecord} is non-@code{nil}. Note that applications and +internal routines often temporarily select a window in order to simplify +coding. As a rule, such selections (including those made by the macros +@code{save-selected-window} and @code{with-selected-window} below) are +not recorded thus avoiding to pollute @code{buffer-list-update-hook}. +Selections that really count are those causing a visible change in +the next redisplay of @var{window}'s frame and should be always +recorded. This also means that to run a function each time a window +gets selected, putting it on @code{buffer-list-update-hook} should be +the right choice. @end defun @cindex most recently selected windows @@ -1367,6 +1725,20 @@ function does not alter the list of most recently selected windows, nor the buffer list. @end defun +@cindex window use time +@cindex use time of window +@cindex window order by time of last use +@defun window-use-time &optional window +This functions returns the use time of window @var{window}. +@var{window} must be a live window and defaults to the selected one. +The @dfn{use time} of a window is not really a time value, but it does +increase monotonically with each window selection, so the window with +the lowest use time is the least recently selected one, and the +window with the highest use time is the most recently selected +one. +@end defun + + @node Cyclic Window Ordering @section Cyclic Ordering of Windows @cindex cyclic ordering of windows @@ -1393,7 +1765,7 @@ if omitted or @code{nil}, it defaults to the selected window. The optional argument @var{minibuf} specifies whether minibuffer windows should be included in the cyclic ordering. Normally, when @var{minibuf} is @code{nil}, a minibuffer window is included only if it is currently -``active''; this matches the behavior of @kbd{C-x o}. (Note that a +active; this matches the behavior of @kbd{C-x o}. (Note that a minibuffer window is active as long as its minibuffer is in use; see @ref{Minibuffers}). @@ -1487,8 +1859,8 @@ criterion, without selecting it: @cindex least recently used window @defun get-lru-window &optional all-frames dedicated not-selected -This function returns a live window which is heuristically the ``least -recently used'' window. The optional argument @var{all-frames} has +This function returns a live window which is heuristically the least +recently used. The optional argument @var{all-frames} has the same meaning as in @code{next-window}. If any full-width windows are present, only those windows are @@ -1500,6 +1872,13 @@ the optional argument @var{not-selected} is non-@code{nil}, this function returns @code{nil} in that case. @end defun +@cindex most recently used window +@defun get-mru-window &optional all-frames dedicated not-selected +This function is like @code{get-lru-window}, but it returns the most +recently used window instead. The meaning of the arguments is the +same as described for @code{get-lru-window}. +@end defun + @cindex largest window @defun get-largest-window &optional all-frames dedicated not-selected This function returns the window with the largest area (height times @@ -1626,7 +2005,9 @@ to eliminate this discrepancy. This function returns a list of all windows currently displaying @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the name of an existing buffer. If omitted or @code{nil}, it defaults to -the current buffer. +the current buffer. If the currently selected window displays +@var{buffer-or-name}, it will be the first in the list returned by +this function. The arguments @var{minibuf} and @var{all-frames} have the same meanings as in the function @code{next-window} (@pxref{Cyclic Window @@ -1676,7 +2057,7 @@ window and make it the current buffer. It is often used interactively return value is the buffer switched to. If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{The Buffer List}). If +returned by @code{other-buffer} (@pxref{Buffer List}). If @var{buffer-or-name} is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable @code{major-mode} @@ -1684,19 +2065,52 @@ buffer's major mode is determined by the variable @code{major-mode} Normally, the specified buffer is put at the front of the buffer list---both the global buffer list and the selected frame's buffer -list (@pxref{The Buffer List}). However, this is not done if the +list (@pxref{Buffer List}). However, this is not done if the optional argument @var{norecord} is non-@code{nil}. -Sometimes, @code{switch-to-buffer} may be unable to display the buffer -in the selected window. This happens if the selected window is a -minibuffer window, or if the selected window is strongly dedicated to -its buffer (@pxref{Dedicated Windows}). In that case, the command -normally tries to display the buffer in some other window, by invoking -@code{pop-to-buffer} (see below). However, if the optional argument -@var{force-same-window} is non-@code{nil}, it signals an error -instead. +Sometimes, the selected window may not be suitable for displaying the +buffer. This happens if the selected window is a minibuffer window, or +if the selected window is strongly dedicated to its buffer +(@pxref{Dedicated Windows}). In such cases, the command normally tries +to display the buffer in some other window, by invoking +@code{pop-to-buffer} (see below). + +If the optional argument @var{force-same-window} is non-@code{nil} and +the selected window is not suitable for displaying the buffer, this +function always signals an error when called non-interactively. In +interactive use, if the selected window is a minibuffer window, this +function will try to use some other window instead. If the selected +window is strongly dedicated to its buffer, the option +@code{switch-to-buffer-in-dedicated-window} described next can be used +to proceed. @end deffn +@defopt switch-to-buffer-in-dedicated-window +This option, if non-@code{nil}, allows @code{switch-to-buffer} to +proceed when called interactively and the selected window is strongly +dedicated to its buffer. + +The following values are respected: + +@table @code +@item nil +Disallows switching and signals an error as in non-interactive use. + +@item prompt +Prompts the user whether to allow switching. + +@item pop +Invokes @code{pop-to-buffer} to proceed. + +@item t +Marks the selected window as non-dedicated and proceeds. +@end table + +When called non-interactively, @code{switch-to-buffer} always signals an +error when the selected window is dedicated to its buffer and +@var{force-same-window} is non-@code{nil}. +@end defopt + By default, @code{switch-to-buffer} shows the buffer at its position of @code{point}. This behavior can be tuned using the following option. @@ -1762,7 +2176,7 @@ possible (@pxref{Input Focus}). The return value is the buffer that was switched to. If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{The Buffer List}). If +returned by @code{other-buffer} (@pxref{Buffer List}). If @var{buffer-or-name} is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable @code{major-mode} @@ -1842,7 +2256,10 @@ The constant @code{display-buffer-fallback-action}. @noindent Each action function is called in turn, passing the buffer as the first argument and the combined action alist as the second argument, -until one of the functions returns non-@code{nil}. +until one of the functions returns non-@code{nil}. The caller can +pass @code{(allow-no-window . t)} as an element of the action alist to +indicate its readiness to handle the case of not displaying the +buffer in a window. The argument @var{action} can also have a non-@code{nil}, non-list value. This has the special meaning that the buffer should be @@ -1876,7 +2293,7 @@ corresponding display action to display the buffer. @defopt display-buffer-base-action The value of this option should be a display action. This option can -be used to define a ``standard'' display action for calls to +be used to define a standard display action for calls to @code{display-buffer}. @end defopt @@ -1902,7 +2319,7 @@ to another buffer (@pxref{Dedicated Windows}). It also fails if @end defun @defun display-buffer-reuse-window buffer alist -This function tries to ``display'' @var{buffer} by finding a window +This function tries to display @var{buffer} by finding a window that is already displaying it. If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, @@ -1947,6 +2364,25 @@ the function specified in @code{pop-up-frame-function} is added to the newly created frame's parameters. @end defun +@defun display-buffer-use-some-frame buffer alist +This function tries to display @var{buffer} by trying to find a +frame that meets a predicate (by default any frame other than the +current frame). + +If this function chooses a window on another frame, it makes that frame +visible and, unless @var{alist} contains an @code{inhibit-switch-frame} +entry (@pxref{Choosing Window Options}), raises that frame if necessary. + +If @var{alist} has a non-nil @code{frame-predicate} entry, its value is a +function taking one argument (a frame), returning non-nil if the +frame is a candidate; this function replaces the default predicate. + +If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, +the selected window is used; thus if the selected frame has a single +window, it is not used. + +@end defun + @defun display-buffer-pop-up-window buffer alist This function tries to display @var{buffer} by splitting the largest or least recently-used window (typically one on the selected frame). @@ -1965,7 +2401,7 @@ adjust the window's height, use an entry whose @sc{car} is @item A number specifies the desired height of the new window. An integer -number specifies the number of lines of the window. A floating point +specifies the number of lines of the window. A floating-point number gives the fraction of the window's height with respect to the height of the frame's root window. @@ -1986,7 +2422,7 @@ To adjust the window's width, use an entry whose @sc{car} is @item A number specifies the desired width of the new window. An integer -number specifies the number of columns of the window. A floating point +specifies the number of columns of the window. A floating-point number gives the fraction of the window's width with respect to the width of the frame's root window. @@ -1996,6 +2432,13 @@ argument: the new window. The function is supposed to adjust the width of the window; its return value is ignored. @end itemize +If @var{alist} contains a @code{preserve-size} entry, Emacs will try to +preserve the size of the new window during future resize operations +(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a +cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width +of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve +the height of the window. + This function can fail if no window splitting can be performed for some reason (e.g., if the selected frame has an @code{unsplittable} frame parameter; @pxref{Buffer Parameters}). @@ -2022,12 +2465,30 @@ specified by that entry will override any other window found by the methods above, even if that window never showed @var{buffer} before. @end defun +@defun display-buffer-at-bottom buffer alist +This function tries to display @var{buffer} in a window at the bottom +of the selected frame. + +This either splits the window at the bottom of the frame or the +frame's root window, or reuses an existing window at the bottom of the +selected frame. +@end defun + @defun display-buffer-use-some-window buffer alist This function tries to display @var{buffer} by choosing an existing window and displaying the buffer in that window. It can fail if all windows are dedicated to another buffer (@pxref{Dedicated Windows}). @end defun +@defun display-buffer-no-window buffer alist +If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then +this function does not display @code{buffer}. This allows to override +the default action and avoid displaying the buffer. It is assumed that +when the caller specifies a non-@code{nil} @code{allow-no-window} value +it can handle a @code{nil} value returned from @code{display-buffer} in +this case. +@end defun + To illustrate the use of action functions, consider the following example. @@ -2056,7 +2517,7 @@ buffer there. If all these steps fail, it will proceed using whatever (provided *foo* was put by @code{display-buffer} there before) or a popped-up window as follows: If the window is part of a vertical combination, it will set its height to ten lines. Note that if, instead -of the number ``10'', we specified the function +of the number 10, we specified the function @code{fit-window-to-buffer}, @code{display-buffer} would come up with a one-line window to fit the empty buffer. If the window is part of a horizontal combination, it sets its width to 40 columns. Whether a new @@ -2066,7 +2527,7 @@ the window split and the values of and @code{split-width-threshold} (@pxref{Choosing Window Options}). Now suppose we combine this call with a preexisting setup for -`display-buffer-alist' as follows. +@code{display-buffer-alist} as follows. @example @group @@ -2097,7 +2558,7 @@ window below the selected window. selected one is dedicated to its buffer, @code{display-buffer} will proceed as described in the previous example. Note, however, that when it tries to adjust the height of any reused or popped-up window, it will -in any case try to set its number of lines to ``5'' since that value +in any case try to set its number of lines to 5 since that value overrides the corresponding specification in the @var{action} argument of @code{display-buffer}. @@ -2168,6 +2629,21 @@ least that many columns. If the value is @code{nil}, that means not to split this way. @end defopt +@defopt even-window-sizes +This variable, if non-nil, causes @code{display-buffer} to even window +sizes whenever it reuses an existing window and that window is adjacent +to the selected one. + +If its value is @code{width-only}, sizes are evened only if the reused +window is on the left or right of the selected one and the selected +window is wider than the reused one. If its value is @code{height-only} +sizes are evened only if the reused window is above or beneath the +selected window and the selected window is higher than the reused one. +Any other non-@code{nil} value means to even sizes in any of these cases +provided the selected window is larger than the reused one in the sense +of their combination. +@end defopt + @defopt pop-up-frames If the value of this variable is non-@code{nil}, that means @code{display-buffer} may display buffers by making new frames. The @@ -2306,9 +2782,9 @@ or killed, or has been already shown by a recent invocation of If repeated invocations of this command have already shown all buffers previously shown in @var{window}, further invocations will show buffers -from the buffer list of the frame @var{window} appears on (@pxref{The -Buffer List}), trying to skip buffers that are already shown in another -window on that frame. +from the buffer list of the frame @var{window} appears on (@pxref{Buffer +List}), trying to skip buffers that are already shown in another window +on that frame. @end deffn @deffn Command switch-to-next-buffer &optional window @@ -2319,7 +2795,7 @@ defaults to the selected one. If there is no recent invocation of @code{switch-to-prev-buffer} that can be undone, this function tries to show a buffer from the buffer list -of the frame @var{window} appears on (@pxref{The Buffer List}). +of the frame @var{window} appears on (@pxref{Buffer List}). @end deffn By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} @@ -2366,7 +2842,7 @@ called when a buffer gets killed, deletes the window in case (1) and behaves like @code{delete-windows-on} otherwise. @c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)? - When @code{bury-buffer} (@pxref{The Buffer List}) operates on the + When @code{bury-buffer} (@pxref{Buffer List}) operates on the selected window (which shows the buffer that shall be buried), it handles case (2) by calling @code{frame-auto-hide-function} (@pxref{Quitting Windows}) to deal with the selected frame. The other @@ -2405,7 +2881,7 @@ buffer is shown on a separate frame, you might want to call hand, a window has been reused for displaying the buffer, you might prefer showing the buffer previously shown in that window, by calling the function @code{switch-to-prev-buffer} (@pxref{Window History}). -Finally, you might want to either bury (@pxref{The Buffer List}) or kill +Finally, you might want to either bury (@pxref{Buffer List}) or kill (@pxref{Killing Buffers}) the window's buffer. The following command uses information on how the window for @@ -2487,11 +2963,12 @@ one window that should be either quit, or whose buffer should be buried. The function specified by this option is called to automatically hide frames. This function is called with one argument---a frame. -The function specified here is called by @code{bury-buffer} (@pxref{The -Buffer List}) when the selected window is dedicated and shows the buffer -to bury. It is also called by @code{quit-restore-window} (see above) -when the frame of the window to quit has been specially created for -displaying that window's buffer and the buffer is not killed. +The function specified here is called by @code{bury-buffer} +(@pxref{Buffer List}) when the selected window is dedicated and shows +the buffer to bury. It is also called by @code{quit-restore-window} +(see above) when the frame of the window to quit has been specially +created for displaying that window's buffer and the buffer is not +killed. The default is to call @code{iconify-frame} (@pxref{Visibility of Frames}). Alternatively, you may specify either @code{delete-frame} @@ -2548,7 +3025,7 @@ window's buffer) if that window were selected. The default for When @var{window} is the selected window, the value returned is the value of point in that window's buffer. Strictly speaking, it would be -more correct to return the ``top-level'' value of point, outside of any +more correct to return the top-level value of point, outside of any @code{save-excursion} forms. But that value is hard to find. @end defun @@ -2645,7 +3122,7 @@ screen. If this does place point off screen, the display routines move point to the left margin on the middle line in the window. For example, if point @w{is 1} and you set the start of the window -@w{to 37}, the start of the next line, point will be ``above'' the top +@w{to 37}, the start of the next line, point will be above the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example: @@ -2697,12 +3174,14 @@ position that works well with point, and thus @var{position} is not used. @defun pos-visible-in-window-p &optional position window partially This function returns non-@code{nil} if @var{position} is within the range of text currently visible on the screen in @var{window}. It -returns @code{nil} if @var{position} is scrolled vertically out of view. -Locations that are partially obscured are not considered visible unless -@var{partially} is non-@code{nil}. The argument @var{position} defaults -to the current position of point in @var{window}; @var{window}, to the -selected window. If @var{position} is @code{t}, that means to check the -last visible position in @var{window}. +returns @code{nil} if @var{position} is scrolled vertically out of +view. Locations that are partially obscured are not considered +visible unless @var{partially} is non-@code{nil}. The argument +@var{position} defaults to the current position of point in +@var{window}; @var{window} defaults to the selected window. If +@var{position} is @code{t}, that means to check either the first +visible position of the last screen line in @var{window}, or the +end-of-buffer position, whichever comes first. This function considers only vertical scrolling. If @var{position} is out of view only because @var{window} has been scrolled horizontally, @@ -2952,7 +3431,7 @@ only if point is already on that position do they signal an error. @cindex centering point This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does -not ``move point'' with respect to the text. +not move point with respect to the text. If @var{count} is a non-negative number, that puts the line containing point @var{count} lines down from the top of the window. If @@ -3087,8 +3566,8 @@ times the normal character width. How many characters actually disappear off to the left depends on their width, and could vary from line to line. - Because we read from side to side in the ``inner loop'', and from top -to bottom in the ``outer loop'', the effect of horizontal scrolling is + Because we read from side to side in the inner loop, and from top +to bottom in the outer loop, the effect of horizontal scrolling is not like that of textual or vertical scrolling. Textual scrolling involves selection of a portion of text to display, and vertical scrolling moves the window contents contiguously; but horizontal @@ -3208,33 +3687,28 @@ is off the screen due to horizontal scrolling: @end group @end example + @node Coordinates and Windows @section Coordinates and Windows @cindex frame-relative coordinate @cindex coordinate, relative to frame @cindex window position - This section describes functions that report the position of a -window. Most of these functions report positions relative to the -window's frame. In this case, the coordinate origin @samp{(0,0)} lies -near the upper left corner of the frame. For technical reasons, on -graphical displays the origin is not located at the exact corner of -the graphical window as it appears on the screen. If Emacs is built -with the GTK+ toolkit, the origin is at the upper left corner of the -frame area used for displaying Emacs windows, below the title-bar, -GTK+ menu bar, and tool bar (since these are drawn by the window -manager and/or GTK+, not by Emacs). But if Emacs is not built with -GTK+, the origin is at the upper left corner of the tool bar (since in -this case Emacs itself draws the tool bar). In both cases, the X and -Y coordinates increase rightward and downward respectively. - - Except where noted, X and Y coordinates are reported in integer -character units, i.e., numbers of lines and columns respectively. On a -graphical display, each ``line'' and ``column'' corresponds to the -height and width of a default character specified by the frame's -default font. - -@defun window-edges &optional window +This section describes functions that report the position of a window. +Most of these functions report positions relative to an origin at the +native position of the window's frame (@pxref{Frame Geometry}). Some +functions report positions relative to the origin of the display of the +window's frame. In any case, the origin has the coordinates (0, 0) and +X and Y coordinates increase rightward and downward +respectively. + + For the following functions, X and Y coordinates are reported in +integer character units, i.e., numbers of lines and columns +respectively. On a graphical display, each ``line'' and ``column'' +corresponds to the height and width of the default character specified by +the frame's default font (@pxref{Frame Font}). + +@defun window-edges &optional window body absolute pixelwise This function returns a list of the edge coordinates of @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window. @@ -3246,49 +3720,78 @@ coordinate of the topmost row, the X coordinate one column to the right of the rightmost column, and the Y coordinate one row down from the bottommost row. -Note that these are the actual outer edges of the window, including -any header line, mode line, scroll bar, fringes, and display margins. -On a text terminal, if the window has a neighbor on its right, its -right edge includes the separator line between the window and its +Note that these are the actual outer edges of the window, including any +header line, mode line, scroll bar, fringes, window divider and display +margins. On a text terminal, if the window has a neighbor on its right, +its right edge includes the separator line between the window and its neighbor. -@end defun -@defun window-inside-edges &optional window -This function is similar to @code{window-edges}, but the returned edge -values are for the text area of the window. They exclude any header -line, mode line, scroll bar, fringes, display margins, and vertical -separator. +If the optional argument @var{body} is @code{nil}, this means to +return the edges corresponding to the total size of @var{window}. +@var{body} non-@code{nil} means to return the edges of @var{window}'s +body (aka text area). If @var{body} is non-@code{nil}, @var{window} +must specify a live window. + +If the optional argument @var{absolute} is @code{nil}, this means to +return edges relative to the native position of @var{window}'s frame. +@var{absolute} non-@code{nil} means to return coordinates relative to +the origin (0, 0) of @var{window}'s display. On non-graphical systems +this argument has no effect. + +If the optional argument @var{pixelwise} is @code{nil}, this means to +return the coordinates in terms of the default character width and +height of @var{window}'s frame (@pxref{Frame Font}), rounded if +necessary. @var{pixelwise} non-@code{nil} means to return the +coordinates in pixels. Note that the pixel specified by @var{right} and +@var{bottom} is immediately outside of these edges. If @var{absolute} +is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too. @end defun -@defun window-top-line &optional window -This function returns the Y coordinate of the topmost row of -@var{window}, equivalent to the @var{top} entry in the list returned -by @code{window-edges}. +@defun window-body-edges &optional window +This function returns the edges of @var{window}'s body (@pxref{Window +Sizes}). Calling @code{(window-body-edges window)} is equivalent to +calling @code{(window-edges window t)}, see above. @end defun +@comment The following two functions are confusing and hardly used. +@ignore @defun window-left-column &optional window -This function returns the X coordinate of the leftmost column of -@var{window}, equivalent to the @var{left} entry in the list returned -by @code{window-edges}. +This function returns the leftmost column of @var{window}. This value +equals the @var{left} entry in the list returned by @code{(window-edges +window)} minus the number of columns occupied by the internal border of +@var{window}'s frame. +@end defun + +@defun window-top-line &optional window +This function returns the topmost row of @var{window}. This value is +equal to the @var{top} entry in the list returned by @code{(window-edges +window)} minus the number of lines occupied by the internal border of +@var{window}'s frame. @end defun +@end ignore The following functions can be used to relate a set of frame-relative coordinates to a window: @defun window-at x y &optional frame -This function returns the live window at the frame-relative -coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no -window at that position, the return value is @code{nil}. If -@var{frame} is omitted or @code{nil}, it defaults to the selected +This function returns the live window at the coordinates @var{x} and +@var{y} given in default character sizes (@pxref{Frame Font}) relative +to the native position of @var{frame} (@pxref{Frame Geometry}). + +If there is no window at that position, the return value is @code{nil}. +If @var{frame} is omitted or @code{nil}, it defaults to the selected frame. @end defun @defun coordinates-in-window-p coordinates window -This function checks whether a window @var{window} occupies the -frame-relative coordinates @var{coordinates}, and if so, which part of -the window that is. @var{window} should be a live window. +This function checks whether a window @var{window} occupies the frame +relative coordinates @var{coordinates}, and if so, which part of the +window that is. @var{window} should be a live window. + @var{coordinates} should be a cons cell of the form @code{(@var{x} -. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates. +. @var{y})}, where @var{x} and @var{y} are given in default character +sizes (@pxref{Frame Font}) relative to the native position of +@var{window}'s frame (@pxref{Frame Geometry}). If there is no window at the specified position, the return value is @code{nil} . Otherwise, the return value is one of the following: @@ -3306,6 +3809,14 @@ The coordinates are in the mode line of @var{window}. @item header-line The coordinates are in the header line of @var{window}. +@item right-divider +The coordinates are in the divider separating @var{window} from a +window on the right. + +@item bottom-divider +The coordinates are in the divider separating @var{window} from a +window beneath. + @item vertical-line The coordinates are in the vertical line between @var{window} and its neighbor to the right. This value occurs only if the window doesn't @@ -3331,42 +3842,103 @@ argument because it always uses the frame that @var{window} is on. The following functions return window positions in pixels, rather than character units. Though mostly useful on graphical displays, they can also be called on text terminals, where the screen area of -each text character is taken to be ``one pixel''. +each text character is taken to be one pixel. @defun window-pixel-edges &optional window This function returns a list of pixel coordinates for the edges of -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. +@var{window}. Calling @code{(window-pixel-edges window)} is equivalent +to calling @code{(window-edges window nil nil t)}, see above. +@end defun -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. The list elements are, respectively, the X pixel -coordinate of the left window edge, the Y pixel coordinate of the top -edge, one more than the X pixel coordinate of the right edge, and one -more than the Y pixel coordinate of the bottom edge. +@comment The following two functions are confusing and hardly used. +@ignore +@defun window-pixel-left &optional window +This function returns the left pixel edge of window @var{window}. This +value equals the @var{left} entry in the list returned by +@code{(window-pixel-edges window)} minus the number of pixels occupied +by the internal border of @var{window}'s frame. @var{window} must be a +valid window and defaults to the selected one. +@end defun + +@defun window-pixel-top &optional window +This function returns the top pixel edge of window @var{window}. This +value is equal to the @var{top} entry in the list returned by +@code{(window-pixel-edges window)} minus the number of pixels occupied +by the internal border of @var{window}'s frame. @var{window} must be a +valid window and defaults to the selected one. @end defun +@end ignore -@defun window-inside-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the pixel coordinates for the edges of the window's text area, -rather than the pixel coordinates for the edges of the window itself. -@var{window} must specify a live window. +@defun window-body-pixel-edges &optional window +This function returns the pixel edges of @var{window}'s body. Calling +@code{(window-body-pixel-edges window)} is equivalent to calling +@code{(window-edges window t nil t)}, see above. @end defun - The following functions return window positions in pixels, relative -to the display screen rather than the frame: + The following functions return window positions in pixels, relative to +the origin of the display screen rather than that of the frame: @defun window-absolute-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. +This function returns the pixel coordinates of @var{WINDOW} relative to +an origin at (0, 0) of the display of @var{window}'s frame. Calling +@code{(window-absolute-pixel-edges)} is equivalent to calling +@code{(window-edges window nil t t)}, see above. +@end defun + +@defun window-absolute-body-pixel-edges &optional window +This function returns the pixel coordinates of @var{WINDOW}'s body +relative to an origin at (0, 0) of the display of @var{window}'s frame. +Calling @code{(window-absolute-body-pixel-edges window)} is equivalent +to calling @code{(window-edges window t t t)}, see above. + +Combined with @code{set-mouse-absolute-pixel-position}, this function +can be used to move the mouse pointer to an arbitrary buffer position +visible in some window: + +@example +@group +(let ((edges (window-absolute-body-pixel-edges)) + (position (pos-visible-in-window-p nil nil t))) + (x-set-mouse-absolute-pixel-position + (+ (nth 0 edges) (nth 0 position)) + (+ (nth 1 edges) (nth 1 position)))) +@end group +@end example + +On a graphical terminal this form ``warps'' the mouse cursor to the +upper left corner of the glyph at the selected window's point. A +position calculated this way can be also used to show a tooltip window +there. @end defun -@defun window-inside-absolute-pixel-edges &optional window -This function is like @code{window-inside-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. @var{window} must specify a live window. +The following function returns the screen coordinates of a buffer +position visible in a window: + +@defun window-absolute-pixel-position &optional position window +If the buffer position @var{position} is visible in window @var{window}, +this function returns the display coordinates of the upper/left corner +of the glyph at @var{position}. The return value is a cons of the X- +and Y-coordinates of that corner, relative to an origin at (0, 0) of +@var{window}'s display. It returns @code{nil} if @var{position} is not +visible in @var{window}. + +@var{window} must be a live window and defaults to the selected +window. @var{position} defaults to the value of @code{window-point} +of @var{window}. + +This means that in order to move the mouse pointer to the position of +point in the selected window, it's sufficient to write: + +@example +@group +(let ((position (window-absolute-pixel-position))) + (set-mouse-absolute-pixel-position + (car position) (cdr position))) +@end group +@end example @end defun + @node Window Configurations @section Window Configurations @cindex window configurations @@ -3374,7 +3946,7 @@ the display screen. @var{window} must specify a live window. A @dfn{window configuration} records the entire layout of one frame---all windows, their sizes, which buffers they contain, how those -buffers are scrolled, and their values of point and the mark; also their +buffers are scrolled, and their value of point; also their fringes, margins, and scroll bar settings. It also includes the value of @code{minibuffer-scroll-window}. As a special exception, the window configuration does not record the value of point in the selected window @@ -3450,13 +4022,13 @@ This function returns @code{t} if @var{object} is a window configuration. @defun compare-window-configurations config1 config2 This function compares two window configurations as regards the -structure of windows, but ignores the values of point and mark and the +structure of windows, but ignores the values of point and the saved scrolling positions---it can return @code{t} even if those aspects differ. The function @code{equal} can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a -saved point or mark. +saved point. @end defun @defun window-configuration-frame config @@ -3477,6 +4049,7 @@ to clone the state of a frame into an arbitrary live window (@code{set-window-configuration} effectively clones the windows of a frame into the root window of that very frame only). +@cindex window state @defun window-state-get &optional window writable This function returns the state of @var{window} as a Lisp object. The argument @var{window} must be a valid window and defaults to the root @@ -3498,11 +4071,13 @@ written to disk and read back in another session. In either case, use the following function to restore the state of the window. @defun window-state-put state &optional window ignore -This function puts the window state @var{state} into @var{window}. The -argument @var{state} should be the state of a window returned by an -earlier invocation of @code{window-state-get}, see above. The optional -argument @var{window} must specify a live window and defaults to the -selected one. +This function puts the window state @var{state} into @var{window}. +The argument @var{state} should be the state of a window returned by +an earlier invocation of @code{window-state-get}, see above. The +optional argument @var{window} can be either a live window or an +internal window (@pxref{Windows and Frames}) and defaults to the +selected one. If @var{window} is not live, it is replaced by a live +window before putting @var{state} into it. If the optional argument @var{ignore} is non-@code{nil}, it means to ignore minimum window sizes and fixed-size restrictions. If @var{ignore} @@ -3622,6 +4197,15 @@ This parameter specifies the window that this one has been cloned from. It is installed by @code{window-state-get} (@pxref{Window Configurations}). +@item @code{preserved-size} +This parameter specifies a buffer, a direction where @code{nil} means +vertical and @code{t} horizontal, and a size in pixels. If this window +displays the specified buffer and its size in the indicated direction +equals the size specified by this parameter, then Emacs will try to +preserve the size of this window in the indicated direction. This +parameter is installed and updated by the function +@code{window-preserve-size} (@pxref{Preserving Window Sizes}). + @item @code{quit-restore} This parameter is installed by the buffer display functions (@pxref{Choosing Window}) and consulted by @code{quit-restore-window} diff --git a/doc/man/ChangeLog b/doc/man/ChangeLog.1 index 8b550dc4417..205e9b900cc 100644 --- a/doc/man/ChangeLog +++ b/doc/man/ChangeLog.1 @@ -1,3 +1,31 @@ +2014-12-14 Glenn Morris <rgm@gnu.org> + + * grep-changelog.1: Remove file. + +2014-11-10 Glenn Morris <rgm@gnu.org> + + * emacs.1.in: Rename from emacs.1. + +2014-10-20 Glenn Morris <rgm@gnu.org> + + * Merge in all changes up to 24.4 release. + +2014-09-29 Eli Zaretskii <eliz@gnu.org> + + * emacs.1: Bump version to 25.0.50. + +2014-01-12 Glenn Morris <rgm@gnu.org> + + * emacs.1: Replace reference to etc/MAILINGLISTS. + +2014-01-09 Glenn Morris <rgm@gnu.org> + + * emacs.1: Refer to online service directory rather than etc/SERVICE. + +2013-08-31 Ulrich Müller <ulm@gentoo.org> + + * emacs.1: Update manual links. + 2013-04-20 Petr Hracek <phracek@redhat.com> (tiny change) * emacs.1: Add some more command-line options. (Bug#14165) @@ -148,7 +176,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 2007-2013 Free Software Foundation, Inc. + Copyright (C) 2007-2015 Free Software Foundation, Inc. This file is part of GNU Emacs. @@ -164,4 +192,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/>. - diff --git a/doc/man/ebrowse.1 b/doc/man/ebrowse.1 index 89506db98ef..40c82a46482 100644 --- a/doc/man/ebrowse.1 +++ b/doc/man/ebrowse.1 @@ -16,7 +16,7 @@ is used to create the database used by the class browser in Emacs. .PP .SH OPTIONS The program follows the usual GNU command line syntax, with long -options starting with two dashes (`-'). +options starting with two dashes ("\-"). .TP .B \-a, \-\-append append output to existing file @@ -85,7 +85,7 @@ was written by Gerd Moellmann. Copyright .if t \(co .if n (C) -2008-2013 Free Software Foundation, Inc. +2008-2015 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/emacs.1 b/doc/man/emacs.1.in index 9149be2c523..98322aac810 100644 --- a/doc/man/emacs.1 +++ b/doc/man/emacs.1.in @@ -1,5 +1,5 @@ .\" See section COPYING for copyright and redistribution information. -.TH EMACS 1 "2007 April 13" "GNU Emacs 24.3.50" +.TH EMACS 1 "2007 April 13" "GNU Emacs @version@" . . .SH NAME @@ -251,8 +251,8 @@ Set additional X resources. .BI "\-\-color\fR,\fP \-\-color=" mode Override color mode for character terminals; .I mode -defaults to `auto', and can also be `never', `auto', `always', -or a mode name like `ansi8'. +defaults to "auto", and can also be "never", "auto", "always", +or a mode name like "ansi8". .TP .BI \-bw " pixels\fR,\fP " \-\-border\-width " pixels" Set the @@ -420,8 +420,8 @@ The value can be one of .IR fullwidth , or .IR fullheight , -which correspond to the command-line options `\-fs', `\-mm', `\-fw', -and `\-fh', respectively. +which correspond to the command-line options "\-fs", "\-mm", "\-fw", +and "\-fh", respectively. Note that this applies to the initial frame only. .TP .BR geometry " (class " Geometry ) @@ -445,7 +445,7 @@ Gives frames menu bars if .IR on ; don't have menu bars if .IR off . -See the Emacs manual, sections "Lucid Resources" and "LessTif +See the Emacs manual, sections "Lucid Resources" and "Motif Resources", for how to control the appearance of the menu bar if you have one. .TP @@ -482,17 +482,17 @@ the window will be displayed in reverse video. .TP .BR screenGamma " (class "ScreenGamma ) Gamma correction for colors, equivalent to the frame parameter -`screen\-gamma'. +"screen\-gamma". .TP .BR scrollBarWidth " (class "ScrollBarWidth ) The scroll bar width in pixels, equivalent to the frame parameter -`scroll\-bar\-width'. +"scroll\-bar\-width". .TP .BR selectionFont " (class " SelectionFont ) Font name for pop-up menu items, in non-toolkit versions of .IR Emacs . (For toolkit versions, see the Emacs manual, sections -"Lucid Resources" and "LessTif Resources".) +"Lucid Resources" and "Motif Resources".) .TP .BR selectionTimeout " (class " SelectionTimeout ) Number of milliseconds to wait for a selection reply. @@ -576,17 +576,14 @@ strings for the Lisp primitives and preloaded Lisp functions of GNU Emacs. They are stored here to reduce the size of Emacs proper. -/usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering -various services to assist users of GNU Emacs, including education, -troubleshooting, porting and customization. . . .SH BUGS -There is a mailing list, bug-gnu-emacs@gnu.org, for reporting Emacs +There is a mailing list, @PACKAGE_BUGREPORT@, for reporting Emacs bugs and fixes. But before reporting something as a bug, please try to be sure that it really is a bug, not a misunderstanding or a deliberate feature. -We ask you to read the section ``Reporting Bugs'' in the Emacs manual +We ask you to read the section "Reporting Bugs" in the Emacs manual for hints on how and when to report bugs. Also, include the version number of the Emacs you are running in \fIevery\fR bug report that you send in. @@ -597,12 +594,11 @@ easily reproduced. Do not expect a personal answer to a bug report. The purpose of reporting bugs is to get them fixed for everyone in the next release, if possible. -For personal assistance, look in the SERVICE file (see above) for -a list of people who offer it. +For personal assistance, consult the service directory at +<http://www.fsf.org/resources/service/> for a list of people who offer it. Please do not send anything but bug reports to this mailing list. -For more information about Emacs mailing lists, see the -file /usr/local/share/emacs/$VERSION/etc/MAILINGLISTS. +For other Emacs lists, see <http://savannah.gnu.org/mail/?group=emacs>. . . .SH UNRESTRICTIONS @@ -655,7 +651,7 @@ For detailed credits and acknowledgments, see the GNU Emacs manual. Copyright .if t \(co .if n (C) -1995, 1999-2013 Free Software Foundation, Inc. +1995, 1999-2015 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1 index a5abcff0d5d..e62fe930152 100644 --- a/doc/man/emacsclient.1 +++ b/doc/man/emacsclient.1 @@ -31,28 +31,31 @@ default editor. For .B emacsclient to work, you need an already running Emacs with a server. Within Emacs, -call the functions `server-start' or `server-mode'. (Your `.emacs' file -can do this automatically if you add either `(server-start)' or -`(server-mode 1)' to it.) +call the functions "server-start" or "server-mode". (Your ".emacs" file +can do this automatically if you add either "(server-start)" or +"(server-mode 1)" to it.) -When you've finished editing the buffer, type `C-x #' -(`server-edit'). This saves the file and sends a message back to the -`emacsclient' program telling it to exit. The programs that use -`EDITOR' wait for the "editor" (actually, `emacsclient') to exit. `C-x -#' also checks for other pending external requests to edit various +When you've finished editing the buffer, type "C-x #" +("server-edit"). This saves the file and sends a message back to the +.B emacsclient +program telling it to exit. The programs that use +EDITOR wait for the "editor" (actually, +.BR emacsclient ) +to exit. "C-x #" also checks for other pending external requests to +edit various files, and selects the next such file. -If you set the variable `server-window' to a window or a frame, `C-x -#' displays the server buffer in that window or in that frame. +If you set the variable "server-window" to a window or a frame, "C-x +#" displays the server buffer in that window or in that frame. .SH OPTIONS The programs follow the usual GNU command line syntax, with long -options starting with two dashes (`-'). +options starting with two dashes ("\-"). .TP .B \-a, \-\-alternate-editor=EDITOR if the Emacs server is not running, run the specified editor instead. -This can also be specified via the `ALTERNATE_EDITOR' environment variable. -If the value of EDITOR is the empty string, run `emacs --daemon' to +This can also be specified via the ALTERNATE_EDITOR environment variable. +If the value of EDITOR is the empty string, run "emacs \-\-daemon" to start Emacs in daemon mode, and try to connect to it. .TP .B -c, \-\-create-frame @@ -70,7 +73,7 @@ Lisp expressions. .TP .B \-f, \-\-server-file=FILENAME use TCP configuration file FILENAME for communication. -This can also be specified via the `EMACS_SERVER_FILE' environment variable. +This can also be specified via the EMACS_SERVER_FILE environment variable. .TP .B \-n, \-\-no-wait returns @@ -99,4 +102,3 @@ This manual page was written by Stephane Bortzmeyer <bortzmeyer@debian.org>, for the Debian GNU/Linux system (but may be used by others). .SH COPYING This manual page is in the public domain. - diff --git a/doc/man/etags.1 b/doc/man/etags.1 index 5ccf528868b..fab8901427d 100644 --- a/doc/man/etags.1 +++ b/doc/man/etags.1 @@ -11,7 +11,7 @@ etags, ctags \- generate tag file for Emacs, vi .SH SYNOPSIS .hy 0 .na -\fBetags\fP [\|\-aCDGIRVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|] +\fBetags\fP [\|\-aCDGIQRVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|] .if n .br [\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|] [\|\-\-parse\-stdin=\fIfile\fP\|] @@ -20,11 +20,12 @@ etags, ctags \- generate tag file for Emacs, vi [\|\-\-no\-globals\|] [\|\-\-include=\fIfile\fP\|] [\|\-\-ignore\-indentation\|] [\|\-\-language=\fIlanguage\fP\|] [\|\-\-members\|] [\|\-\-no\-members\|] [\|\-\-output=\fItagfile\fP\|] +[\|\-\-class\-qualify\|] [\|\-\-regex=\fIregexp\fP\|] [\|\-\-no\-regex\|] [\|\-\-help\|] [\|\-\-version\|] \fIfile\fP .\|.\|. -\fBctags\fP [\|\-aCdgIRVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|] +\fBctags\fP [\|\-aCdgIQRVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|] .if n .br [\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|] [\|\-\-parse\-stdin=\fIfile\fP\|] @@ -33,6 +34,7 @@ etags, ctags \- generate tag file for Emacs, vi [\|\-\-cxref\|] [\|\-\-no\-defines\|] [\|\-\-globals\|] [\|\-\-no\-globals\|] [\|\-\-ignore\-indentation\|] [\|\-\-language=\fIlanguage\fP\|] [\|\-\-members\|] [\|\-\-no\-members\|] +[\|\-\-class\-qualify\|] [\|\-\-output=\fItagfile\fP\|] [\|\-\-regex=\fIregexp\fP\|] [\|\-\-update\|] [\|\-\-help\|] [\|\-\-version\|] @@ -80,8 +82,8 @@ Append to existing tag file. (For \fBvi\fP-format tag files, see also .B \-B, \-\-backward\-search Tag files written in the format expected by \fBvi\fP contain regular expression search instructions; the \fB\-B\fP option writes them using -the delimiter `\|\fB?\fP\|', to search \fIbackwards\fP through files. -The default is to use the delimiter `\|\fB/\fP\|', to search \fIforwards\fP +the delimiter "\|\fB?\fP\|", to search \fIbackwards\fP through files. +The default is to use the delimiter "\|\fB/\fP\|", to search \fIforwards\fP through files. Only \fBctags\fP accepts this option. .TP @@ -117,8 +119,8 @@ final brace of a function or structure definition in C and C++. Parse the following files according to the given language. More than one such options may be intermixed with filenames. Use \fB\-\-help\fP to get a list of the available languages and their default filename -extensions. The `auto' language can be used to restore automatic -detection of language based on the file name. The `none' +extensions. The "auto" language can be used to restore automatic +detection of language based on the file name. The "none" language may be used to disable language parsing altogether; only regexp matching is done in this case (see the \fB\-\-regex\fP option). .TP @@ -137,6 +139,14 @@ May be used (only once) in place of a file name on the command line. \fBetags\fP will read from standard input and mark the produced tags as belonging to the file \fBFILE\fP. .TP +\fB\-\-class\-qualify\fP +Qualify tag names with their class name in C++, ObjC, and Java. +This produces tag names of the form \fIclass\fP\fB::\fP\fImember\fP +for C++, +\fIclass\fP\fB(\fP\fIcategory\fP\fB)\fP for Objective C, and \fIclass\fP\fB.\fP\fImember\fP for Java. +For Objective C, this also produces class methods qualified with +their arguments, as in \fIfoo\fP\fB:\fP\fIbar\fP\fB:\fP\fIbaz\fP\fB:\fP\fImore\fP. +.TP \fB\-o\fP \fItagfile\fP, \fB\-\-output=\fItagfile\fP Explicit name of file for tag table; for \fBetags\fP only, a file name of \- means standard output; overrides default \fBTAGS\fP or \fBtags\fP. @@ -256,7 +266,7 @@ Print the current version of the program (same as the version of the emacs \fBetags\fP is shipped with). .SH "SEE ALSO" -`\|\fBemacs\fP\|' entry in \fBinfo\fP; \fIGNU Emacs Manual\fP, Richard +"\|\fBemacs\fP\|" entry in \fBinfo\fP; \fIGNU Emacs Manual\fP, Richard Stallman. .br .BR cxref ( 1 ), @@ -268,7 +278,7 @@ Stallman. Copyright .if t \(co .if n (C) -1992, 1999, 2001-2013 Free Software Foundation, Inc. +1992, 1999, 2001-2015 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/grep-changelog.1 b/doc/man/grep-changelog.1 deleted file mode 100644 index ef4b2900988..00000000000 --- a/doc/man/grep-changelog.1 +++ /dev/null @@ -1,80 +0,0 @@ -.\" -*- nroff -*- -.\" See section COPYING for copyright and redistribution information. -.TH grep-changelog 1 -.SH NAME -grep-changelog \- print ChangeLog entries matching criteria -.SH SYNOPSIS -.B grep-changelog -.RI [ options ] -.RI [ CHANGELOG .\|.\|.] -.SH DESCRIPTION -.B grep-changelog -searches the named -.IR CHANGELOG s -(by default files matching the regular expressions -.B ChangeLog -and -.BR "ChangeLog\e.[0-9]+" ) -for entries matching the specified criteria. At least one option or -file must be specified. This program is distributed with -.BR "GNU Emacs" . -.PP -.SH OPTIONS -The program accepts unambiguous abbreviations for option names. -.TP -.B \-\-author=AUTHOR -Print entries whose author matches regular expression -.IR AUTHOR . -.TP -.B \-\-text=TEXT -Print entries whose text matches regular expression -.IR TEXT . -.TP -.B \-\-exclude=TEXT -Exclude entries matching regular expression -.IR TEXT . -.TP -.B \-\-from\-date=YYYY\-MM\-DD -Only consider entries made on or after the given date. -ChangeLog date entries not in the -\*(lqYYYY\-MM\-DD\*(rq format are never matched. -.TP -.B \-\-to\-date=YYYY\-MM\-DD -Only consider entries made on or before the given date. -.TP -.B \-\-rcs\-log -Print output in a format suitable for RCS log entries. -This format removes author lines, leading spaces, and file names. -.TP -.B \-\-with\-date -In RCS log format, print short dates. -.TP -.B \-\-reverse -Show matches in reverse order. -.TP -.B \-\-version -Display version information. -.TP -.B \-\-help -Display basic usage information. -. -.SH COPYING -Copyright -.if t \(co -.if n (C) -2008-2013 Free Software Foundation, Inc. -.PP -Permission is granted to make and distribute verbatim copies of this -document provided the copyright notice and this permission notice are -preserved on all copies. -.PP -Permission is granted to copy and distribute modified versions of -this document under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of -a permission notice identical to this one. -.PP -Permission is granted to copy and distribute translations of this -document into another language, under the above conditions for -modified versions, except that this permission notice may be stated -in a translation approved by the Free Software Foundation. -. diff --git a/doc/misc/.gitignore b/doc/misc/.gitignore deleted file mode 100644 index 3ff56b474dd..00000000000 --- a/doc/misc/.gitignore +++ /dev/null @@ -1,23 +0,0 @@ -*.aux -*.cp -*.cps -*.dvi -*.fn -*.fns -*.ky -*.kys -*.log -*.op -*.ops -*.pdf -*.pg -*.pgs -*.ps -*.tmp -*.toc -*.tp -*.tps -*.vr -*.vrs -Makefile -makefile diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog.1 index 554580c769a..2fd0d2c3eba 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog.1 @@ -1,3 +1,1555 @@ +2015-03-25 Glenn Morris <rgm@gnu.org> + + * newsticker.texi (Supported Formats): Remove dead url. + + * remember.texi (Function Reference): Copyedit. + + * idlwave.texi (HTML Help Browser Tips): Remove obsolete info. + +2015-03-18 Eli Zaretskii <eliz@gnu.org> + + * efaq-w32.texi: Remove outdated information and update. + +2015-03-18 Martin Rudalics <rudalics@gmx.at> + + * efaq.texi (Fullscreen mode on MS-Windows): + Fix description (Bug#20110). + +2015-03-04 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (External methods) <adb>: Explain, when Tramp + connects to devices. Mention port numbers. + (GVFS based methods, File name completion): Add index. + (Multi-hops, Remote Programs, File name completion, Ad-hoc multi-hops): + Improve wording. + + * trampver.texi: Update release number. + +2015-03-03 Kelvin White <kwhite@gnu.org> + + * erc.texi (Advanced Usage, Options): Add descriptions and examples + for erc-format-nick-function and erc-rename-buffers options. + (Connecting): Fix typo + +2015-03-02 Daniel Colascione <dancol@dancol.org> + + * cl.texi (Iteration Clauses): Mention iterator support. + +2015-02-25 Tassilo Horn <tsdh@gnu.org> + + * reftex.texi (Multifile Documents): Document + reftex-include-file-commands. + (Options): Mention that non-customize changes might require + calling reftex-compile-variables. + +2015-02-21 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2015-02-10 Lars Ingebrigtsen <larsi@gnus.org> + + * eww.texi (Basics): Mention eww-toggle-fonts. + +2015-02-05 Glenn Morris <rgm@gnu.org> + + * auth.texi (Multiple GMail accounts with Gnus): Markup fix. + +2015-02-05 Teodor Zlatanov <tzz@lifelogs.com> + + * auth.texi (Multiple GMail accounts with Gnus): Add FAQ. + +2015-02-05 Lars Ingebrigtsen <larsi@gnus.org> + + * gnus.texi (Using IMAP): Fix menu node name. + +2015-02-05 Trevor Murphy <trevor.m.murphy@gmail.com> + + * gnus.texi (Support for IMAP Extensions): Document the Gmail label + extension. + +2015-02-04 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2015-01-23 Thomas Fitzsimmons <fitzsim@fitzsim.org> + + * eudc.texi (LDAP Configuration): Rename from LDAP Requirements + and provide configuration examples. + +2015-01-17 Stefan Monnier <monnier@iro.umontreal.ca> + + * eieio.texi (Slot Options): Document :protection as unsupported. + +2015-01-01 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.2.11. + * trampver.texi: Update release number. + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/%.info, %.html, ${buildinfodir}/ccmode.info) + (${buildinfodir}/efaq%.info, efaq%.html): + Use them. + +2014-12-31 Filipp Gunbin <fgunbin@fastmail.fm> + + * info.texi (Create Info buffer): Mention info-display-manual prefix. + +2014-12-29 Paul Eggert <eggert@cs.ucla.edu> + + * efaq.texi (Displaying the current file name in the titlebar): + Prefer (system-name) to system-name. + * smtpmail.texi (Server workarounds): Fix grammar. + +2014-12-18 Eric Abrahamsen <eric@ericabrahamsen.net> + + * gnus.texi (Gnus Registry Setup): Explain pruning changes. + Mention gnus-registry-prune-factor. Explain sorting changes and + gnus-registry-default-sort-function. Correct file extension. + +2014-12-17 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (About This Manual): Update instructions + for building the manual. + +2014-12-15 Alan Mackenzie <acm@muc.de> + + "Advice" is a mass noun. Amend text accordingly. + * cl.texi (Obsolete Macros): Replace "an advice" with "advice". + +2014-12-12 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-12-08 Andrey Kotlarski <m00naticus@gmail.com> + + * eww.texi (Basics): Document managing multiple eww buffers. + +2014-12-05 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * eww.texi (Basics): Document eww PDF viewing. + +2014-11-23 Ivan Shmakov <ivan@siamics.net> + + * eww.texi (Advanced): Mention the Desktop stuff (bug#18010). + +2014-11-23 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Remote processes): Let-bind environment variables to + `process-environment' when running `process-file' or + `start-file-process'. + +2014-11-19 Ivan Shmakov <ivan@siamics.net> + + * eww.texi (Basics): Document `eww-history-limit'. + +2014-11-14 Paul Eggert <eggert@cs.ucla.edu> + + * org.texi (The date/time prompt, Matching tags and properties): + Use leading zero with 24-hour times less than 10:00. + +2014-11-13 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * eww.texi (Variable Index): Mention `eww-after-render-hook'. + +2014-11-10 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * eww.texi (Basics): Document `eww-readable'. + +2014-11-10 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Top): Add missing `HTML' menu. + (HTML): Fix xref to FAQ 4-16. + +2014-11-09 Glenn Morris <rgm@gnu.org> + + * Makefile.in (version): Remove variable. + (clean): No longer delete dist tarfile. + (dist): Remove rule; replace with code in admin.el. + +2014-11-08 Glenn Morris <rgm@gnu.org> + + * Makefile.in (${buildinfodir}/ccmode.info) + (${buildinfodir}/efaq%.info): Ensure output directory exists. + +2014-11-07 Tassilo Horn <tsdh@gnu.org> + + * gnus.texi (HTML): Update section so that it mentions shr and w3m. + Also link the full EWW manual that explains more on shr, too. + + * gnus-faq.texi (FAQ 4 - Reading messages, FAQ 4-16): Add Q&A on how to + increase contrast when displaying HTML mail with shr. + + * eww.texi (Advanced): Document increasing contrast with + shr-color-visible-distance-min and + shr-color-visible-luminance-min. + +2014-11-02 Teodor Zlatanov <tzz@lifelogs.com> + + * auth.texi (Help for users): Explain quoting rules better. + +2014-10-30 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Gnus does not work with NNTP): Remove; ancient. + +2014-10-30 Stefan Monnier <monnier@iro.umontreal.ca> + + * eieio.texi (Accessing Slots, CLOS compatibility): Adjust wording + since `setf' is in core rather than in CL nowadays. + +2014-10-29 Paul Eggert <eggert@cs.ucla.edu> + + Simplify use of current-time and friends. + * org.texi (Dynamic blocks): Omit unnecessary call to current-time + in example. + +2014-10-28 Christopher Schmidt <ch@ristopher.com> + + * calc.texi (Quick Calculator): Mention prefix argument of + `quick-calc'. + +2014-10-26 Eric S. Raymond <esr@thyrsus.com> + + * efaq-w32.texi: Neutralize language specific to a repository type. + +2014-10-25 Eric S. Raymond <esr@thyrsus.com> + + * gnus-coding.texi: Neutralize language specific to a repository type. + +2014-10-20 Glenn Morris <rgm@gnu.org> + + * Merge in all changes up to 24.4 release. + +2014-10-13 Glenn Morris <rgm@gnu.org> + + * Makefile.in (dist): Update for new output variables. + +2014-10-08 Leo Liu <sdl.web@gmail.com> + + * cl.texi (Porting Common Lisp): Remove parse-integer. + +2014-10-06 Ulf Jasper <ulf.jasper@web.de> + + * newsticker.texi (Supported Formats): Fix order of subheading and + itemize. + +2014-10-04 Glenn Morris <rgm@gnu.org> + + * vip.texi (Other Vi Commands): Markup fix. + +2014-10-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Key bindings and useful functions): Fix typo. + Use the correct function's name. + +2014-10-03 Michael Brand <michael.ch.brand@gmail.com> + + * org.texi (Formula syntax for Calc): Add `f-1' to TBLFM example + about `nan'. + +2014-10-03 Nicolas Goaziou <mail@nicolasgoaziou.fr> + + * org.texi (Export settings): Be more explicit about how output + file name is built. + + * org.texi (Headings and sectioning structure): Document menus. + + * org.texi (Include files, Publishing options): Remove reference + to nonexistent variable. + +2014-10-03 Eli Zaretskii <eliz@gnu.org> + + * erc.texi (Connecting): Remove stray "OA" that failed the manual + build. + +2014-10-03 Kelvin White <kwhite@gnu.org> + + * erc.texi (Advanced Usage, Options): Add descriptions and examples + for erc-format-nick-function and erc-rename-buffers options. + +2014-09-26 Leo Liu <sdl.web@gmail.com> + + * cl.texi (Predicates on Numbers): Document cl-digit-char-p. + (Numerical Functions): Document cl-parse-integer. (Bug#18557) + +2014-09-24 Ulf Jasper <ulf.jasper@web.de> + + * newsticker.texi: Reworked. Document new treeview group + commands. Remove VERSION, UPDATED, use EMACSVER instead. + Use term 'feed reader'. + +2014-09-04 Paul Eggert <eggert@cs.ucla.edu> + + Less chatter in 'make' output. + * Makefile.in (clean): Simplify, for shorter command line. + +2014-08-07 Reuben Thomas <rrt@sc3d.org> + + * ediff.texi (Merging and diff3): Don't mention lack of support + for VMS diff, we no longer support VMS. + +2014-08-07 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Remote shell setup): Explain, how to change command + line arguments of remote "nc" listener. + +2014-07-31 Tassilo Horn <tsdh@gnu.org> + + * gnus.texi (Group Parameters): Document that `gcc-self' may also be a + list. + +2014-07-28 Stephen Berman <stephen.berman@gmx.net> + + * todo-mode.texi (Marked Items): Correct omission of item deletion + from commands applying to both todo and done items. + +2014-07-18 Albert Krewinkel <albert+gnus@zeitkraut.de> + + * gnus.texi (Posting Styles): Document the possibility to perform + string replacements when matching against headers. + +2014-07-09 Stephen Berman <stephen.berman@gmx.net> + + * todo-mode.texi (Levels of Organization): Comment out statement + that Emacs recognizes todo files by their extension, since this + feature has been removed due to bug#17482. + +2014-07-03 Michael Albinus <michael.albinus@gmx.de> + + * trampver.texi: Update release number. + +2014-07-03 Glenn Morris <rgm@gnu.org> + + * info.texi, mh-e.texi: "Online help" doesn't mean what it + used to any more. + + * idlwave.texi (Introduction): Comment out dead http screenshot links. + +2014-06-24 Leo Liu <sdl.web@gmail.com> + + * dired-x.texi (Omitting Files in Dired, Omitting Variables): + Fix key binding to dired-omit-mode. (Bug#16354) + +2014-06-24 Eli Zaretskii <eliz@gnu.org> + + * autotype.texi (Skeleton Language): Document the \n feature better. + +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + +2014-06-22 Mario Lang <mlang@delysid.org> + + * srecode.texi (Base Arguments): The the -> to the. + + * org.texi (Images in ODT export): The the -> the. + +2014-06-21 Eli Zaretskii <eliz@gnu.org> + + * autotype.texi (Skeleton Language): Document the feature of \n + when at eol. + +2014-06-21 Michael Albinus <michael.albinus@gmx.de> + + * dbus.texi (Type Conversion): Formatting edits in example. + +2014-06-15 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.2.10. + + * tramp.texi (Inline methods): Remove restriction on "telnet". + Recommend sharing ssh connections for "plink". + (External methods): Remove "sftp". Merge "pscp" and "psftp" + descriptions. Recommend sharing ssh connections. Add "nc" method. + (GVFS based methods): Add "sftp". + (Customizing Completion, External packages, Issues): + Use @dots{}. + + * trampver.texi: Update release number. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-12 Vincent Belaïche <vincentb1@users.sourceforge.net> + + * ses.texi: Adding documentation for SES local printer functions. + +2014-06-12 Glenn Morris <rgm@gnu.org> + + * Makefile.in: Use GNU Make features to reduce duplication. + (mkinfodir): Remove. + (${buildinfodir}): Generate using an order-only prerequisite. + (.dvi.ps): Replace with pattern rule. + ($INFO_TARGETS): Mark as PHONY. + (${buildinfodir}): New rule. + (EXTRA_OPTS, need_emacsver, need_emacsver_prefix): New variables. + (${buildinfodir}/%.info, %.dvi, %.pdf, %.html, %.ps): + New pattern rules, replacing numerous previous explicit rules. + (info_template): New definition. + (gnus.dvi, gnus.pdf): Use distinct intermediate files. + (mostlyclean): Adjust for above gnus change. + +2014-06-11 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_INSTALL): Update for 2013-08-28 DOCMISC_W32 change. + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-08 Karl Berry <karl@gnu.org> + + * doc/info.texi (Help-^L): "mode line", "screenful", + stand-alone and Emacs Info both use the mode line. + Use x instead of weird C-x 0 to get rid of help msg + in standalone Info. + +2014-06-08 Glenn Morris <rgm@gnu.org> + + * vip.texi (Files): Defer to Emacs manual for uniquify details. + + * info.texi (Help-Small-Screen): Clarify details of S-SPC. + (Help-Small-Screen, Help-]): Do not mention S-SPC. + (Emacs Info Variables): Markup fix. + + * ebrowse.texi (Source Display, Finding/Viewing): + * erc.texi (Sample Session): + * ses.texi (The Basics): + * todo-mode.texi (Moving and Deleting Items): + * woman.texi (Navigation): Markup fixes re SPC, RET. + +2014-06-02 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Finding a package with particular functionality): + Update example. + * vip.texi: Mention this is obsolete. + +2014-05-27 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-05-26 Paul Eggert <eggert@cs.ucla.edu> + + Specify coding if Latin-1 Emacs would misinterpret (Bug#17575). + * htmlfontify.texi, org.texi: Add "coding: utf-8". + +2014-05-26 Stephen Berman <stephen.berman@gmx.net> + + * todo-mode.texi: Update in light of changes due to bug#17482. + Replace numerous mistaken uses of literal quotes with proper + Texinfo markup. + (Todo Mode Entry Points): Comment out reference to using find-file + or Dired to visit Todo files, since this has been disabled (bug#17482). + +2014-05-20 Leo Liu <sdl.web@gmail.com> + + * cl.texi (List Functions, Efficiency Concerns): Update cl-endp. + +2014-05-13 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-05-08 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Frequently Asked Questions): Mention HISTFILE + setting in ~/.ssh/environment. + +2014-05-04 Stephen Berman <stephen.berman@gmx.net> + + * todo-mode.texi: Update, improve exposition, add cross + references, fix typos. + (Inserting New Items, Editing Item Headers and Text): Rewrite to + document new user interface. + +2014-05-04 Glenn Morris <rgm@gnu.org> + + * autotype.texi (Skeleton Language): + * message.texi (Header Commands): Replace `iff'. + +2014-05-02 Paul Eggert <eggert@cs.ucla.edu> + + * vhdl-mode.texi: Add "@documentencoding UTF-8", + since this is a toplevel .texi file. + +2014-04-22 Bastien Guerry <bzg@gnu.org> + + * org.texi (Installation): Be more clear on why installing Org + through ELPA should be done without loading any Org file. + + * org.texi (Emphasis and monospace): Document the use of + =verbatim= and ~code~ to be consistent with + `org-element-text-markup-successor'. + + * org.texi (In-buffer settings, Radio tables): Tiny fixes. + + * org.texi (Initial visibility): + * org.texi (Literal examples): Fix typos. + +2014-04-22 Michael Brand <michael.ch.brand@gmail.com> + + * org.texi (Column attributes): Add a sentence to point out + the dependency on the format specifier. + +2014-04-22 Nicolas Goaziou <n.goaziou@gmail.com> + + * org.texi (The Export Dispatcher): Reformulation. + + * org.texi (@LaTeX{} specific attributes): Update manual. + + * org.texi (Top, Exporting): Org has its own documentation and + should therefore be removed from "Other build-in back-ends". + +2014-04-22 Stefan Monnier <monnier@iro.umontreal.ca> + + * cl.texi (Structures): Remove cl-struct-set-slot-value. + +2014-04-20 Daniel Colascione <dancol@dancol.org> + + * cl.texi (Declarations): Document changes to `cl-the' and defstruct functions. + +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + +2014-03-27 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_COMMON): Add vhdl-mode. + (vhdl_mode_deps, vhdl-mode, $(buildinfodir)/vhdl-mode$(INFO_EXT)) + (vhdl-mode.dvi, vhdl-mode.pdf, vhdl-mode.html): New rules/variables. + + * vhdl-mode.texi: General clean-up. Set copyright to FSF, add license. + Remove hand-written node pointers. Remove info re old Emacs versions. + Markup fixes. + (Getting Connected): Remove irrelevant info. + (Indentation Commands, Requirements): Remove empty/irrelevant nodes. + (Frequently Asked Questions): Electric indent is now enabled. + +2014-03-27 Reto Zimmermann <reto@gnu.org> + Rod Whitby <software.vhdl-mode@rwhitby.net> + + * vhdl-mode.texi: New file, imported from upstream vhdl-mode. + +2014-03-26 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-03-26 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Frequently Asked Questions): Add fish shell settings. + +2014-03-23 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Ma Gnus): Mention header attachment buttons. + +2014-03-23 Lars Ingebrigtsen <larsi@gnus.org> + + * emacs-mime.texi (MML Definition): Document recipient-filename. + +2014-03-23 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (MIME Commands): + Mention gnus-mime-buttonize-attachments-in-header and + gnus-mime-display-attachment-buttons-in-header. + +2014-03-23 Lars Ingebrigtsen <larsi@gnus.org> + + * message.texi (Forwarding): + Mention `message-forward-included-headers'. + +2014-03-23 Lars Ingebrigtsen <larsi@gnus.org> + + * gnus.texi: w3 is no longer supported by Gnus. + +2014-03-22 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Informational files for Emacs): Do not mention etc/GNU. + +2014-03-21 Glenn Morris <rgm@gnu.org> + + * ede.texi (ede-linux): + * vip.texi (New Bindings): Tiny copyedits. + +2014-03-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * vip.texi (Other Vi Commands): Adjust doc of C-j. + + * cc-mode.texi (Indentation Commands): Remove C-j, since it's not + defined by CC-mode but globally. + (FAQ): Tweak text about RET and auto-indentation. + +2014-03-18 David Engster <deng@randomsample.de> + + * ede.texi (Project Local Variables): Remove reference to + `ede-java-root' and the example using it. + (Android projects, ede-java-root): Remove nodes since they are + only in CEDET upstream (Bug#17030). All nodes updated. + (ede-cpp-root): Document the :compile-command slot. + (ede-linux): Document new variables + `project-linux-build-directory-default' and + `project-linux-architecture-default'. + +2014-03-12 Glenn Morris <rgm@gnu.org> + + * eww.texi (History and Acknowledgments): + Don't list everyone who changed the code. + + * ada-mode.texi, auth.texi, calc.texi, ebrowse.texi, efaq.texi: + * emacs-gnutls.texi, epa.texi, ert.texi, eshell.texi, eww.texi: + * flymake.texi, gnus.texi, info.texi, message.texi, mh-e.texi: + * newsticker.texi, pcl-cvs.texi, rcirc.texi, sem-user.texi: + * smtpmail.texi, url.texi, viper.texi, wisent.texi, woman.texi: + Use @file for buffers, per the Texinfo manual. + +2014-03-12 Paul Eggert <eggert@cs.ucla.edu> + + * org.texi: Don't set txicodequoteundirected and txicodequotebacktick + so that the Org Manual's style for ` and ' in code is consistent + with the other Emacs manuals. This affects PDF, not .info files. + +2014-03-12 Glenn Morris <rgm@gnu.org> + + * octave-mode.texi (Using Octave Mode): Remove outdated stuff + about RET and indentation. + +2014-03-03 Juanma Barranquero <lekktu@gmail.com> + + * gnus.texi: + * semantic.texi: Fix whitespace. + + * ede.texi (Android projects): + * eieio.texi (Class Options, Making New Objects) + (Method Invocation, CLOS compatibility): + * sem-user.texi (Tag Decoration Mode): Fix typos. + +2014-03-02 Xue Fuqiao <xfq@gnu.org> + + * sem-user.texi (Create System Databases): Markup fix. + +2014-02-28 Glenn Morris <rgm@gnu.org> + + * info.texi (Further Reading): Rename node from Expert Info. + Remove stuff about writing Info nodes by hand. + (Help-Cross): Move node from (mainly deleted) chapter 3 to chapter 1. + + * info.texi: Nuke hand-written node pointers. + +2014-02-28 Karl Berry <karl@gnu.org> + + * info.texi (Top): Mention H for a summary of all commands. + +2014-02-25 Glenn Morris <rgm@gnu.org> + + * edt.texi (Quick start, Starting emulation): Update hook details. + * efaq.texi (Fullscreen mode on MS-Windows) + (Terminal setup code works after Emacs has begun): Update hook details. + * vip.texi (Loading VIP): Fix hook example. + + * efaq-w32.texi (Bash): Don't use setq with hooks. + +2014-02-24 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-02-22 Xue Fuqiao <xfq@gnu.org> + + * remember.texi (Quick Start): Add an index. + (Function Reference, Quick Start): Add cross-references. + +2014-02-21 Glenn Morris <rgm@gnu.org> + + * flymake.texi (Starting the syntax check process): Grammar fix. + + * tramp.texi (External packages): Grammar fix. + Reword for default sentinel not being nil any more. + +2014-02-19 Michael Albinus <michael.albinus@gmx.de> + + * trampver.texi: Update release number. + +2014-02-19 Glenn Morris <rgm@gnu.org> + + * remember.texi: Copyedits. + (Quick Start): No need for manual autoloads. Mention remember-notes. + (Function Reference): Update arguments. Add new commands. + +2014-02-18 Glenn Morris <rgm@gnu.org> + + * remember.texi (copying): Bump remember mode version. + (Installation): Remove unnecessary chapter. + (Quick Start): No need to explicitly load remember.el. + (Separate Text Files): New section. + +2014-02-17 Glenn Morris <rgm@gnu.org> + + * eieio.texi (Class Values, CLOS compatibility): + Remove references to deleted eieio-describe-class/generic. + +2014-02-16 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.2.9. + * trampver.texi: Update release number. + + * efaq-w32.texi (Tramp ssh): Remove also pscp1 and pscp2. + +2014-02-14 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Single-Variable Statistics): Remove mention of + incorrect keybinding. + +2014-02-12 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-02-08 Glenn Morris <rgm@gnu.org> + + * auth.texi (GnuPG and EasyPG Assistant Configuration): + Be agnostic about authinfo/authinfo.gpg default order. (Bug#16642) + +2014-02-07 Glenn Morris <rgm@gnu.org> + + * viper.texi (File and Buffer Handling): Prefer ido to iswitchb. + +2014-02-06 Glenn Morris <rgm@gnu.org> + + * epa.texi (Mail-mode integration): Mention epa-mail-aliases. + + * mh-e.texi, viper.texi: Do not use colons in index entries. + +2014-02-05 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-02-05 Glenn Morris <rgm@gnu.org> + + * epa.texi: Add indices. + + * url.texi (Cookies): Mention url-cookie-list command. + +2014-02-03 Glenn Morris <rgm@gnu.org> + + * cl.texi (Blocks and Exits): Mention cl-tagbody. + +2014-02-02 Glenn Morris <rgm@gnu.org> + + * efaq-w32.texi (Tramp ssh): Remove deleted tramp methods. + +2014-01-31 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Replacing highlighted text): + Update delete-selection-mode doc. + +2014-01-30 Xue Fuqiao <xfq.free@gmail.com> + + * sem-user.texi (Include paths): Fix a Texinfo command. + +2014-01-27 Glenn Morris <rgm@gnu.org> + + * idlwave.texi (Lesson III---User Catalog, Online Help) + (Starting the Shell, Catalogs, User Catalog): + * remember.texi (Quick Start): + * viper.texi: + * vip.texi (Customization, Customizing Constants) + (Customizing Key Bindings): Update for files being in ~/.emacs.d/. + +2014-01-25 Xue Fuqiao <xfq.free@gmail.com> + + * cc-mode.texi (Minor Modes): Minor fix. + +2014-01-24 David Engster <deng@randomsample.de> + + * eieio.texi (Introduction): Fix references. + +2014-01-24 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Termcap/Terminfo entries for Emacs): + Use M-x term rather than M-x terminal-emulator. + + * emacs-mime.texi (time-date): Use float-time. + +2014-01-22 David Engster <deng@randomsample.de> + + * eieio.texi (Introduction): Move introductory paragraph about + EIEIO and CLOS from 'Building Classes' to here. + (Documentation): Remove, since eieio-doc is not part of Emacs. + (Class Values, CLOS compatibility): Mention that + `describe-function' will also give information about classes. + +2014-01-20 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-01-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (eww_deps): Does not depend on emacsver.texi. + +2014-01-12 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (all): Doc fix according to GNU Coding Standards. + Use "file name" instead of "filename" or "path". Use "host" + instead of "machine". + +2014-01-12 David Engster <deng@randomsample.de> + + * eieio.texi (Introduction): `class-of' is obsolete. + (Predicates, Basic Methods): Adapt function names to namespace + cleanup. + +2014-01-12 Xue Fuqiao <xfq.free@gmail.com> + + * eww.texi (Basics): Use "directory" instead of "path" (Bug#16419). + +2014-01-12 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Guidelines for newsgroup postings) + (Informational files for Emacs): + Remove references to etc/MAILINGLISTS, etc/INTERVIEW. + +2014-01-10 Stefan Monnier <monnier@iro.umontreal.ca> + + * cl.texi (Function Bindings): Fix incorrect description of cl-let. + +2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * Makefile.in: Add eww.texi. + * eww.texi: New file. + +2014-01-07 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Problems with very large files): Fix superscript typo. + +2013-01-07 Rasmus <w530@pank.eu> + + * org.texi (Global and local cycling): Fix missing '@'. + +2013-01-07 Bastien Guerry <bzg@gnu.org> + + * org.texi (Global and local cycling): Mention C-u C-u TAB. + (Include files, The Export Dispatcher) + (Advanced configuration) + (Header arguments in Org mode properties): Spelling fixes. + (Special blocks): Add #+BEGIN_ABSTRACT as another example. + (@LaTeX{} specific attributes): New index entries. + Use #+BEGIN_ABSTRACT in the example. + +2013-01-07 Nicolas Goaziou <n.goaziou@gmail.com> + + * org.texi (Org export): New section. + (HTML doctypes): Fix whitespace error. Fix display. + (Publishing options): Add missing html publishing options. + +2014-01-07 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Basic editing, Packages that do not come with Emacs): + Merge in some info from etc/MORE.STUFF. + +2014-01-05 Paul Eggert <eggert@cs.ucla.edu> + + Specify .texi encoding (Bug#16292). + * ada-mode.texi, auth.texi, autotype.texi, bovine.texi, calc.texi: + * cc-mode.texi, cl.texi, dbus.texi, dired-x.texi, ebrowse.texi: + * ede.texi, ediff.texi, edt.texi, efaq.texi, eieio.texi: + * emacs-gnutls.texi, epa.texi, erc.texi, ert.texi: + * eshell.texi, eudc.texi, flymake.texi, forms.texi, gnus-coding.texi: + * gnus-faq.texi, htmlfontify.texi, idlwave.texi, ido.texi, info.texi: + * message.texi, mh-e.texi, newsticker.texi, nxml-mode.texi: + * octave-mode.texi, org.texi, pcl-cvs.texi, pgg.texi, rcirc.texi: + * reftex.texi, remember.texi, sasl.texi, sc.texi, semantic.texi: + * ses.texi, sieve.texi, smtpmail.texi, speedbar.texi, srecode.texi: + * todo-mode.texi, tramp.texi, url.texi, vip.texi, viper.texi: + * widget.texi, wisent.texi, woman.texi: + Add @documentencoding. + +2014-01-03 Aidan Gauland <aidalgol@amuri.net> + + * eshell.texi (What Eshell is not): Clean up confusing clause. + +2014-01-03 Glenn Morris <rgm@gnu.org> + + * efaq-w32.texi, reftex.texi: Use @insertcopying in non-TeX. + + * ede.texi, eieio.texi, semantic.texi, srecode.texi: + Add copyright notice to titlepage. + + * dbus.texi, nxml-mode.texi, widget.texi: Add titlepage. + + * ert.texi: Add a titlepage. Use @insertcopying. + + * calc.texi (Top): Use @top rather than @chapter. + +2014-01-03 Aidan Gauland <aidalgol@amuri.net> + + * eshell.texi (top): Fix incorrect use of xref. + +2014-01-03 Aidan Gauland <aidalgol@amuri.net> + + * eshell.texi (top): Fix incorrect info filename in an xref. + +2014-01-02 Glenn Morris <rgm@gnu.org> + + * Makefile.in (cc_mode_deps): Rename from (typo) ccmode_deps. + +2014-01-02 Aidan Gauland <aidalgol@amuri.net> + + * eshell.texi (Command Basics): Remove `Command basics' chapter. + +2014-01-02 Aidan Gauland <aidalgol@amuri.net> + + * eshell.texi (What is Eshell?): Add section about what not to use + Eshell for. + +2013-12-23 Teodor Zlatanov <tzz@lifelogs.com> + + * emacs-gnutls.texi (Help For Users): Document `gnutls-verify-error'. + +2013-12-22 Glenn Morris <rgm@gnu.org> + + * woman.texi (Navigation): Use itemx where appropriate. + +2013-12-20 Tassilo Horn <tsdh@gnu.org> + + * info.texi, woman.texi: + Document `S-SPC' as alternative to `DEL' for scrolling. + +2013-12-20 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Stack Manipulation Commands): Mention using the variable + `calc-context-sensitive-enter' for `calc-enter' and `calc-pop'. + +2013-12-12 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (direntry): Use ssh but rsh. + (all): Encode all environment variable names with @env{...}. + (Bug Reports): Refer to Testing node. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * autotype.texi, cc-mode.texi, ediff.texi, ert.texi: + * htmlfontify.texi, ido.texi, octave-mode.texi, org.texi: + * srecode.texi, todo-mode.texi, tramp.texi: + Sync direntry with info/dir version. + +2013-12-11 Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * Makefile.in: Add octave-mode.texi. + +2013-12-11 Kurt Hornik <Kurt.Hornik@wu-wien.ac.at> + Rüdiger Sonderfeld <ruediger@c-plusplus.de> + + * octave-mode.texi: Import from GNU Octave (doc/interpreter/emacs.txi). + +2013-12-08 Juanma Barranquero <lekktu@gmail.com> + + * dbus.texi (Properties and Annotations): Fix typo. + +2013-12-06 Bastien Guerry <bzg@gnu.org> + + * org.texi: Don't include Emacs version within Org's version. + +2013-12-06 Nicolas Goaziou <n.goaziou@gmail.com> + + * org.texi (Creating one-off styles): Use new export snippet + syntax. + + * org.texi (Export settings): Documentation describing how text + above the first heading is ignored when an :export: tag is in a + file. + +2013-12-05 Michael Albinus <michael.albinus@gmx.de> + + * dbus.texi (Type Conversion): Clarify unibyte-ness of strings. + +2013-11-30 Glenn Morris <rgm@gnu.org> + + * Makefile.in (distclean): Remove Makefile. + +2013-11-20 era eriksson <era+emacsbugs@iki.fi> + + * ses.texi (Quick Tutorial): New chapter. (Bug#14748) + (The Basics, Formulas): Copyedits. + (Resizing, Printer functions): Add index entries. + +2013-11-17 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Customizing Calc): Mention new variable + `calc-context-sensitive-enter'. + +2013-11-12 Aaron Ecay <aaronecay@gmail.com> + + * org.texi (Exporting code blocks): Document the 'inline-only + setting for `org-export-babel-evaluate'. Document how :var + introduces code block dependencies. + +2013-11-12 Achim Gratz <Stromeko@Stromeko.DE> + + * org.texi (Header arguments): Document header-args[:lang] + properties and remove deprecated old-style properties from + documentation. + + * org.texi (Agenda commands): Remove footnote from @tsubheading + and add a sentence with the reference instead. + +2013-11-12 Bastien Guerry <bzg@gnu.org> + + * org.texi (Catching invisible edits): + * org.texi (Plain lists, Plain lists): + * org.texi (Advanced configuration): + * org.texi (Tag groups): + * org.texi (Conventions): + * org.texi (Checkboxes, Radio lists): + * org.texi (Top, Summary, Exporting): + * org.texi (In-buffer settings): Fix typos. + + * org.texi (Refile and copy): Document `org-copy' and `C-3 C-c + C-w'. Add an index entry for `org-refile-keep'. + + * org.texi (Plain lists): Add an index entry for sorting plain + list. Document sorting by checked status for check lists. + + * org.texi (Publishing options): Fix old variable names. + + * org.texi (Orgstruct mode): Fix suggested setting of + `orgstruct-heading-prefix-regexp'. + + * org.texi (Export settings): + Document `org-export-allow-bind-keywords'. + + * org.texi (History and Acknowledgments): Small rephrasing. + + * org.texi (Template elements): Add a footnote about tags accepted + in a year datetree. + + * org.texi (Beamer export, @LaTeX{} and PDF export) + (Header and sectioning, @LaTeX{} specific attributes): + Enhance style. + + * org.texi (Agenda commands): Add a footnote about dragging agenda + lines: it does not persist and it does not change the .org files. + + * org.texi (Agenda commands): Add a table heading for dragging + agenda lines forward/backward. + + * org.texi (Agenda commands): Add documentation for + `org-agenda-bulk-toggle' and `org-agenda-bulk-toggle-all'. + + * org.texi (Publishing options): Update the list of options. + (Simple example, Complex example): Fix the examples. + + * org.texi (Formula syntax for Calc): Don't use a bold font the + warning. + + * org.texi (Other built-in back-ends): New section. + + * org.texi (Editing source code): + Document `org-edit-src-auto-save-idle-delay' and + `org-edit-src-turn-on-auto-save'. + + * org.texi (External links): Document contributed link types + separately. + + * org.texi (Closing items): + Document `org-closed-keep-when-no-todo'. + + * org.texi (Export back-ends): Rename from "Export formats". + (The Export Dispatcher): Remove reference to + `org-export-run-in-background'. + (Export settings): Minor rewrites. + (ASCII/Latin-1/UTF-8 export): Update variable's name. + (In-buffer settings): Add #+HTML_HEAD_EXTRA. + + * org.texi (Export in foreign buffers): New section. + (Exporting): Remove documentation about converting the selected + region. + + * org.texi (Advanced configuration): Put the filter valid types in + a table. Use @lisp and @smalllisp. + + * org.texi: Use @code{nil} instead of nil. Update the maintainer + contact info. + + * org.texi (Exporting): Better introductory sentence. Add a note + about conversion commands. + (Feedback, Orgstruct mode, Built-in table editor) + (Built-in table editor, Orgtbl mode, Updating the table) + (Property syntax, Capturing column view, Capture) + (Agenda files, Agenda commands, CDLaTeX mode, CDLaTeX mode) + (Exporting, Extending ODT export) + (Working with @LaTeX{} math snippets, dir, Customization) + (Radio tables, A @LaTeX{} example, Pulling from MobileOrg): + Uniformly use @kbd{M-x command RET}. + + * org.texi (Filtering/limiting agenda items): New subsection. + Document the use of `org-agenda-max-*' options and + `org-agenda-limit-interactively' from the agenda. + (Agenda commands): Move details about filtering commands to + the new section, only include a summary here. + (Customizing tables in ODT export) + (System-wide header arguments, Conflicts, Dynamic blocks): + Use spaces for indentation. + + * org.texi (Emphasis and monospace): Mention `org-emphasis-alist'. + + * org.texi (Links in HTML export, Images in HTML export) + (post): Fix syntax within #+ATTR_*. + (Tables in HTML export): Document `org-html-table-row-tags' + and use `org-html-table-default-attributes' instead of + `org-html-table-tag'. + + * org.texi (Publishing action, Publishing options) + (Publishing links): Major rewrite. Enhance explanations for + `org-org-publish-to-org'. Remove reference to + `org-export-run-in-background'. + + * org.texi: Fix many small typos. Use #+NAME instead of + #+TBLNAME. Use @smalllisp instead of @example. + (Special symbols): Add index? + (HTML preamble and postamble): Don't mention obsolete use of + opt-plist. + (JavaScript support): Don't mention the org-jsinfo.el file as it + has been merged with ox-html.el. + + * org.texi (Installation, Feedback, Setting Options) + (Code evaluation security, org-crypt.el): Use @lisp instead of + @example. + (Agenda commands): Use @table instead of @example. + + * org.texi (Adding hyperlink types): New appendix. + + * org.texi (ODT export commands, Extending ODT export) + (Applying custom styles, Images in ODT export) + (Labels and captions in ODT export) + (Literal examples in ODT export) + (Configuring a document converter) + (Working with OpenDocument style files) + (Customizing tables in ODT export) + (Validating OpenDocument XML): Fix options names. + + * org.texi (History and Acknowledgments): Update acknowledgments + to Nicolas. Add Nicolas Goaziou to the list of contributors. + + * org.texi (System-wide header arguments): Don't use "customizing" + for setting a variable. Also remove comments. + + * org.texi (Weekly/daily agenda): Add `org-agenda-start-day' and + `org-agenda-start-on-weekday' to the variable index and document + them. + + * org.texi (Sparse trees, Agenda commands) + (@LaTeX{} fragments, Selective export, Export options) + (The export dispatcher, ASCII/Latin-1/UTF-8 export) + (HTML Export commands, @LaTeX{}/PDF export commands) + (iCalendar export, Publishing options, Triggering publication) + (In-buffer settings): Update to reflect changes from the new + export engine. + + * org.texi (Matching tags and properties): More examples. + Explain group tags expansion as regular expressions. + + * org.texi (Tag groups): New section. + + * org.texi (Setting tags): Tiny formatting fixes. + + * org.texi (Plain lists, Checkboxes): Use non-obsolete variable + names. + + * org.texi (Storing searches): Add "agenda" and "agenda*" to the + concept index. Include example for these agenda views. + (Special agenda views): Mention the "agenda*" agenda view. + + * org.texi (Repeated tasks): Document how to ignore a repeater + when using both a scheduled and a deadline timetamp. + + * org.texi (Global and local cycling): Wrap in a new subsection. + (Initial visibility, Catching invisible edits): New subsections. + + * org.texi (Visibility cycling): Mention that + `org-agenda-inhibit-startup' will prevent visibility setting when + the agenda opens an Org file for the first time. + + * org.texi (Org syntax): New section. + + * org.texi (Orgstruct mode): + Document `orgstruct-heading-prefix-regexp'. + + * org.texi (Speeding up your agendas): New section. + + * org.texi (Installation): When installing Org from ELPA, users + should do this from an Emacs session where no .org file has been + visited. + + * org.texi (CSS support, In-buffer settings): Update HTML options + names. + + * org.texi (Structure editing): Update documentation for + `org-insert-heading-or-item'. + (Plain lists, Relative timer): Update index entry. + + * org.texi (JavaScript support): Update variable names. + + * org.texi (comments): Minor formatting fix. + + * org.texi (@LaTeX{} fragments): Minor enhancement. + + * org.texi: Update the list contributions. + + * org.texi (Agenda commands): Exporting the agenda to an .org file + will not copy the subtrees and the inherited tags. + Document `org-agenda-filter-by-regexp'. + + * org.texi (Publishing action, Complex example): Fix names of + publishing functions. + + * org.texi (Top, Exporting): Delete references to Freemind. + (Freemind export): Delete section. + + * org.texi (Top, Exporting): Delete references to the XOXO export. + (XOXO export): Delete section. + + * org.texi (Capture): Mention that org-remember.el is not + supported anymore. + + * org.texi (Top, Exporting, Beamer class export): + Delete references to the TaskJuggler export. + (History and Acknowledgments): Mention that the TaskJuggler has + been rewritten by Nicolas and now lives in the contrib/ directory + of Org's distribution. Mention that Jambunathan rewrote the HTML + exporter. Remove Jambunathan from my own acknowledgments. + (TaskJuggler export): Delete. + + * org.texi (HTML preamble and postamble) + (Tables in HTML export, Images in HTML export) + (Math formatting in HTML export, CSS support) + (@LaTeX{} and PDF export, Publishing options): Fix the names of + the HTML export and publishing options. + + * org.texi (Literal examples, Export options) + (@LaTeX{} and PDF export, Header and sectioning) + (Publishing options): Fix LaTeX options names. + + * org.texi (Export options, CSS support, In-buffer settings): + Fix references to HTML_LINK_* and HTML_STYLE keywords. + + * org.texi (Export options, In-buffer settings): Fix references to + #+SELECT_TAGS and #+EXCLUDE_TAGS and remove reference to #+XSLT. + + * org.texi (Top, Markup, Initial text, Images and tables) + (@LaTeX{} fragments, @LaTeX{} fragments, Exporting) + (Export options, JavaScript support, Beamer class export): + Remove references to the DocBook export, which has been deleted. + (History and Acknowledgments): Mention that DocBook has been + deleted, suggest to use the Texinfo exporter instead, then to + convert the .texi to DocBook with makeinfo. + (Links in ODT export, Tables in ODT export): Fix indices. + + * org.texi (Deadlines and scheduling): Add a variable to the + index. Add documentation about delays for scheduled tasks. + + * org.texi (Emphasis and monospace): + Mention `org-fontify-emphasized-text' and + `org-emphasis-regexp-components'. + + * org.texi (References): Small enhancement. + + * org.texi (Column width and alignment): Make the example visually + more clear. + + * org.texi (The clock table): Document :mstart and :wstart as a + way to set the starting day of the week. + + * org.texi (In-buffer settings): Document new startup keywords. + Thanks to John J Foerch for this idea. + + * org.texi (Include files): Tiny formatting fix. + + * org.texi (Activation): Point to the "Conflicts" section. + +2013-11-12 Carsten Dominik <carsten.dominik@gmail.com> + + * org.texi (CSS support): Clarify this section. + + * org.texi (@LaTeX{} specific attributes): Document that tabu and + tabularx packages are not in the default set of packages. + + * org.texi (Agenda commands): Document fortnight view. + + * org.texi: Document conflict with ecomplete.el. + + * org.texi (History and Acknowledgments): Acknowledgements for + Jason Dunsmore and Rakcspace. + + * org.texi: Rename org-crypt.el node to org-crypt. + + * org.texi (A @LaTeX{} example): Fix typo in variable name. + + * org.texi (MobileOrg): Mention the new iPhone developer. + + * org.texi (Table of contents) Improve documentation of TOC + placement. + + * org.texi: Explain that date/time information at read-date prompt + should start at the beginning, not anywhere in the middle of a + long string. + +2013-11-12 Christopher Schmidt <christopher@ch.ristopher.com> + + * org.texi (Orgstruct mode): Fix wrong regexp. + +2013-11-12 Eric Abrahamsen <eric@ericabrahamsen.net> + + * org.texi: Document export to (X)HTML flavors. + +2013-11-12 Eric Schulte <schulte.eric@gmail.com> + + * org.texi (Extracting source code): Mention the prefix argument + to org-babel-tangle. + (noweb): Remove erroneous negative. + (Specific header arguments): Document new header arguments. + Documentation for new tangle-mode header argument. + (Top): Documentation for new tangle-mode header argument. + (rownames): Documentation for new tangle-mode header argument. + Mention elisp as special rowname case. + (tangle-mode): Documentation for new tangle-mode header argument. + (post): Documentation and an example of usage. + (var): Remove the "Alternate argument syntax" section from the + documentation. + (hlines): Note that :hline has no effect for Emacs Lisp code + blocks. + +2013-11-12 Feng Shu <tumashu@gmail.com> + + * org.texi (@LaTeX{} fragments, Previewing @LaTeX{} fragments) + (Math formatting in HTML export) + (Working with @LaTeX{} math snippets): Add document about creating + formula image with imagemagick. + + * org.texi (@LaTeX{} specific attributes): Document `:caption' + attribute of #+ATTR_LATEX. + +2013-11-12 Grégoire Jadi <gregoire.jadi@gmail.com> + + * org.texi (Handling links): Fix a typo in + `org-startup-with-inline-images' documentation. + + * org.texi (Previewing @LaTeX{} fragments): Document the startup + keywords to use for previewing LaTeX fragments or not. + (Summary of in-buffer settings): Improve formatting and add an + entry for the variable `org-startup-with-latex-preview'. + + * org.texi (Property syntax): Recall the user to refresh the org + buffer when properties are set on a per-file basis. + +2013-11-12 Gustav Wikström <gustav.erik@gmail.com> (tiny change) + + * org.texi (Matching tags and properties): Clarification. + +2013-11-12 Ippei Furuhashi <top.tuna+orgmode@gmail.com> + + * org.texi (Editing and debugging formulas): Add an example when a + table has multiple #+TBLFM lines. + +2013-11-12 Ivan Vilata i Balaguer <ivan@selidor.net> (tiny change) + + * org.texi (The clock table): Document acceptance of relative + times in tstart and tend, link to syntax description and provide + example. + +2013-11-12 Jarmo Hurri <jarmo.hurri@syk.fi> + + * org.texi (The spreadsheet): Document lookup functions. + +2013-11-12 Kodi Arfer <git@arfer.net> (tiny change) + + * org.texi (CSS support): Mention .figure-number, .listing-number, + and .table-number. + +2013-11-12 Michael Brand <michael.ch.brand@gmail.com> + + * org.texi + (Formula syntax for Calc, Emacs Lisp forms as formulas): Reformat + spreadsheet formula mode strings and some examples from @example + block with xy @r{yz} to @table. + + * org.texi (Formula syntax for Calc): Improve the documentation of + empty fields in formulas for spreadsheet. Add explanation and + example for empty field. Extend explanations of format + specifiers. Add a sentence to mention Calc defmath. + + * org.texi (Column formulas): Add a sentence to be more explicit + about when a table header is mandatory. + +2013-11-12 Nicolas Goaziou <n.goaziou@gmail.com> + + * org.texi (Subscripts and superscripts): Remove reference to + quoted underscores until this mechanism is implemented again. + + * org.texi (Beamer export): Be more accurate about BEAMER_OPT + property. + + * org.texi (Document title): Subtree export is no longer triggered + by marking one as the region. + (Horizontal rules): LaTeX export doesn't use "\hrule" anymore, and + giving examples isn't very useful: "horizontal rule" is, at least, + as explicit as <hr/>. + + * org.texi (HTML doctypes): Reflect keyword removal. + (CSS support): Reflect keyword removal. + + * org.texi (@LaTeX{} specific attributes): Document new :float + values. + + * org.texi (Export settings): Improve documentation. + + * org.texi (Math formatting in HTML export): Fix OPTIONS item's name. + (Text areas in HTML export): Update text areas. + (HTML Export commands): Update export commands. + + * org.texi (Header and sectioning): Add a footnote about the + different between LATEX_HEADER_EXTRA and LATEX_HEADER. + + * org.texi (The Export Dispatcher): + Document `org-export-in-background'. + + * org.texi (Footnotes): Export back-ends do not use + `org-footnote-normalize' anymore. + + * org.texi: Document variable changes. + + * org.texi (Export settings): Document p: item in OPTIONS keyword. + + * org.texi (Exporting): Massive rewrite of the first sections. + (Selective export): Delete. + (The Export Dispatcher): Rewrite. + (Export options): Rewrite as "Export settings". + + * org.texi: Small changes to documentation for embedded LaTeX. + + * org.texi (Internal links): Document #+NAME keyword and + cross-referencing during export. + + * org.texi (Include files): Remove reference to :prefix1 + and :prefix. Give more details for :minlevel. + + * org.texi (Macro replacement): Fix macro name. + Update documentation about possible locations and escaping mechanism. + + * org.texi (Table of contents): Update documentation. + Document lists of listings and lists of tables. Add documentation for + optional title and #+TOC: keyword. + +2013-11-12 Rick Frankel <rick@rickster.com> + + * org.texi (results): Add Format section, broken out of Type + section to match code. + (hlines, colnames): Remove incorrect Emacs Lisp exception. + Note that the actual default handling (at least for python and + emacs-lisp) does not seem to match the description. + +2013-11-12 Sacha Chua <sacha@sachachua.com> (tiny change) + + * org.texi (The date/time prompt): Update the documentation to + reflect the new way `org-read-date-get-relative' handles weekdays. + +2013-11-12 Yasushi Shoji <yashi@atmark-techno.com> + + * org.texi (Resolving idle time): + Document `org-clock-x11idle-program-name'. + +2013-10-24 Michael Albinus <michael.albinus@gmx.de> + + * ert.texi (Running Tests Interactively): Adapt examle output. + (Tests and Their Environment): Mention skip-unless. + +2013-10-23 Glenn Morris <rgm@gnu.org> + + * dired-x.texi, ebrowse.texi, ede.texi, eieio.texi, eshell.texi: + * pcl-cvs.texi, sc.texi, srecode.texi, vip.texi, viper.texi: + * widget.texi: Nuke @refill. + + * Makefile.in (install-dvi, install-html, install-pdf) + (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) + (uninstall-pdf): Quote entities that might contain whitespace. + +2013-10-17 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Data Type Formats): Don't specify the size at + which integers begin to be represented by lists. + +2013-10-14 Xue Fuqiao <xfq.free@gmail.com> + + * cl.texi (Argument Lists): Add indexes for &key and &aux. + +2013-10-07 Michael Albinus <michael.albinus@gmx.de> + + * trampver.texi: Update release number. + +2013-10-02 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.2.8. + + * tramp.texi (External packages): Use `non-essential'. + * trampver.texi: Update release number. + +2013-09-14 Glenn Morris <rgm@gnu.org> + + * eshell.texi: Markup fixes. + +2013-09-11 Xue Fuqiao <xfq.free@gmail.com> + + * ido.texi (Interactive Substring Matching): Use @key{RET} instead + of @kbd{RET}. + (Prefix Matching): Add an index. + +2013-09-08 Glenn Morris <rgm@gnu.org> + + * emacs-gnutls.texi: Tweak direntry. + +2013-09-06 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Alternative Syntax): Remove chapter. + +2013-08-28 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, + for portability to hosts where /bin/sh has problems. + +2013-08-28 Stefan Monnier <monnier@iro.umontreal.ca> + + Try to reduce redundancy in doc/misc/Makefile.in. + * Makefile.in (DOCMISC_W32): New var to replace DOCMISC_*_W32. + (TARGETS): New intermediate variable. + (DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS): Use it. + +2013-08-27 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Emacs for MS-Windows): Update location of MS FAQ. + + * efaq.texi: Rename from faq.texi, to match its output files. + * Makefile.in: Update for faq.texi name change. + + * efaq-w32.texi (EMACSVER): Get it from emacsver.texi. + + * Makefile.in (webhack): Remove; it's nothing to do with Emacs. + + * efaq-w32.texi: Move here from the web-pages repository. + * Makefile.in (DOCMISC_DVI_W32, DOCMISC_HTML_W32, DOCMISC_INFO_W32) + (DOCMISC_PDF_W32, DOCMISC_PS_W32): New configure output variables. + (INFO_COMMON, INFO_INSTALL): New derivations of INFO_TARGETS. + (DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS): + Add DOCMISC_*_W32 variables. + (echo-info): Use INFO_INSTALL rather than INFO_TARGETS. + (efaq_w32_deps): New variable. + (efaq-w32, $(buildinfodir)/efaq-w32$(INFO_EXT), efaq-w32.dvi) + (efaq-w32.pdf, efaq-w32.html): New rules. + (clean): Remove efaq-w32 products. + +2013-08-26 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + 2013-08-19 Katsumi Yamaoka <yamaoka@jpl.org> * emacs-mime.texi (Encoding Customization): Exclude iso-2022-jp-2 and @@ -46,7 +1598,7 @@ (INSTALL_DATA): New, set by configure. (HTML_OPTS, HTML_TARGETS, PS_TARGETS, DVIPS): New variables. (.PHONY): Add html, ps, install-dvi, install-html, install-pdf, - install-ps ,install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, + install-ps, install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, uninstall-ps, and uninstall-doc. (.SUFFIXES): Add .ps and .dvi. (.dvi.ps): New suffix rule. @@ -69,9 +1621,9 @@ 2013-08-10 Xue Fuqiao <xfq.free@gmail.com> - * ido.texi (Working Directories): - (Flexible Matching, Regexp Matching, Find File At Point) - (Ignoring, Misc Customization): Use @defopt for user options. + * ido.texi (Working Directories, Flexible Matching, Regexp Matching) + (Find File At Point, Ignoring, Misc Customization): Use @defopt + for user options. 2013-08-09 Xue Fuqiao <xfq.free@gmail.com> @@ -95,8 +1647,7 @@ 2013-08-07 Xue Fuqiao <xfq.free@gmail.com> * sc.texi (Introduction): Fix index. - (Usage Overview): - (Citations, Citation Elements, Recognizing Citations) + (Usage Overview, Citations, Citation Elements, Recognizing Citations) (Information Keys and the Info Alist, Reference Headers) (The Built-in Header Rewrite Functions) (Electric References, Reply Buffer Initialization) @@ -112,8 +1663,7 @@ * newsticker.texi (Usage): Use @key for RET. - * cl.texi (Argument Lists): - (For Clauses): + * cl.texi (Argument Lists, For Clauses) (Macros): Add indexes. 2013-08-05 Xue Fuqiao <xfq.free@gmail.com> @@ -123,7 +1673,7 @@ 2013-08-04 Stephen Berman <stephen.berman@gmx.net> * Makefile.in (INFO_TARGETS, DVI_TARGETS, PDF_TARGETS): Add todo-mode. - (todo-mode, $(buildinfodir)/todo-mode$(INFO_EXT)): + (todo-mode, $(buildinfodir)/todo-mode$(INFO_EXT)) (todo-mode.dvi, todo-mode.pdf): New rules. * todo-mode.texi: New file. @@ -139,6 +1689,10 @@ `gnus-subthread-sort-functions' and remove the obsolete documentation of `gnus-sort-threads-recursively'. +2012-07-30 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update to 2012-07-29.17 version. + 2013-07-29 David Engster <deng@randomsample.de> * eieio.texi (top): Make clear that EIEIO is not a full CLOS @@ -149,8 +1703,8 @@ 2013-07-29 Michael Albinus <michael.albinus@gmx.de> - * tramp.texi (Frequently Asked Questions): Mention - `tramp-use-ssh-controlmaster-options'. + * tramp.texi (Frequently Asked Questions): + Mention `tramp-use-ssh-controlmaster-options'. 2013-07-26 Tassilo Horn <tsdh@gnu.org> @@ -194,8 +1748,8 @@ 2013-07-08 Tassilo Horn <tsdh@gnu.org> * gnus.texi (lines): Correct description of - `gnus-registry-track-extra's default value. Mention - `gnus-registry-remove-extra-data'. + `gnus-registry-track-extra's default value. + Mention `gnus-registry-remove-extra-data'. 2013-07-06 Lars Ingebrigtsen <larsi@gnus.org> @@ -467,8 +2021,8 @@ 2013-02-09 Jay Belanger <jay.p.belanger@gmail.com> - * calc.texi (Basic Operations on Units): - (Customizing Calc): Mention the variable `calc-allow-units-as-numbers'. + * calc.texi (Basic Operations on Units, Customizing Calc): + Mention the variable `calc-allow-units-as-numbers'. 2013-02-08 Aidan Gauland <aidalgol@no8wireless.co.nz> @@ -487,7 +2041,7 @@ 2013-02-07 Eric Ludlam <zappo@gnu.org> - * doc/misc/ede.texi (Creating a project): Make ede-new doc less + * ede.texi (Creating a project): Make ede-new doc less specific, and only about items it supports, indicating that there might be more. Remove refs to simple project and direct automake from ede new. @@ -566,7 +2120,7 @@ * ede.texi (Top): Rename from top, all uses changed. * eshell.texi: Add missing argument to @sp. * forms.texi (Top): Reorder menu to match structure. - * htmlfontify.texi (Customisation): Add missing @item in + * htmlfontify.texi (Customization): Add missing @item in @enumerate. * org.texi (Advanced features): Add missing argument for @item. (Property searches): Use @backslashchar{} in macro argument. @@ -819,7 +2373,7 @@ 2012-11-22 Jay Belanger <jay.p.belanger@gmail.com> - * doc/misc/calc.texi (Date Forms): Mention the customizable + * calc.texi (Date Forms): Mention the customizable Gregorian-Julian switch. (Customizing Calc): Mention the variable `calc-gregorian-switch'. @@ -1200,7 +2754,7 @@ * org.texi (Clocking commands): Document the use of S-M-<up/down> on clock timestamps. - * org.texi (Fast access to TODO states): Explicitely says only + * org.texi (Fast access to TODO states): Explicitly says only letters are supported as fast TODO selection keys. * org.texi (Link abbreviations): Illustrate the use of the "%h" @@ -1482,9 +3036,13 @@ * org.texi (Durations and time values): Fix typo. +2012-05-26 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + 2012-05-19 Jay Belanger <jay.p.belanger@gmail.com> - * doc/misc/calc.texi (Basic Operations on Units, Customizing Calc): + * calc.texi (Basic Operations on Units, Customizing Calc): Mention `calc-ensure-consistent-units'. 2012-05-14 Andreas Schwab <schwab@linux-m68k.org> @@ -1976,7 +3534,7 @@ 2012-01-03 Bastien Guerry <bzg@gnu.org> (tiny change) - * org.texi (Selective export): Explicitely mention the default + * org.texi (Selective export): Explicitly mention the default values for `org-export-select-tags', `org-export-exclude-tags'. @@ -2114,6 +3672,10 @@ * gnus.texi (Gnus Utility Functions): Add more references and explanations (bug#9683). +2011-09-26 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Merge from gnulib. + 2011-09-21 Lars Magne Ingebrigtsen <larsi@gnus.org> * gnus.texi (Archived Messages): Note the default (bug#9552). @@ -2754,7 +4316,8 @@ 2013-02-18 Aidan Gauland <aidalgol@no8wireless.co.nz> - * eshell.texi (Input/Output): Document insert output redirection operator, >>>. + * eshell.texi (Input/Output): + Document insert output redirection operator, >>>. 2011-02-18 Glenn Morris <rgm@gnu.org> @@ -3168,8 +4731,8 @@ 2010-11-11 Carsten Dominik <carsten.dominik@gmail.com> - * org.texi (Handling links): - (In-buffer settings): Document inlining images on startup. + * org.texi (Handling links, In-buffer settings): + Document inlining images on startup. 2010-11-11 Carsten Dominik <carsten.dominik@gmail.com> @@ -4051,7 +5614,7 @@ 2009-12-15 Jay Belanger <jay.p.belanger@gmail.com> - * calc/calc.texi (Radix Modes): Clarify two's complement notation. + * calc.texi (Radix Modes): Clarify two's complement notation. 2009-12-14 Chong Yidong <cyd@stupidchicken.com> @@ -5323,8 +6886,8 @@ 2008-07-23 Vincent Belaïche <vincent.b.1@hotmail.fr> - * calc.texi (Editing Stack Entries): - (Algebraic Entry): Rewrite introductory sentences so it can be used by + * calc.texi (Editing Stack Entries, Algebraic Entry): + Rewrite introductory sentences so it can be used by Calc's help functions. Mention fixing typos. (Customizing Calc): Fix typo. @@ -5556,6 +7119,12 @@ * org.texi: Massive changes, in many parts of the file. +2008-04-27 Jason Riedy <jason@acm.org> + + * org.texi (A LaTeX example): Note that fmt may be a + one-argument function, and efmt may be a two-argument function. + (Radio tables): Document multiple destinations. + 2008-04-13 Reiner Steib <Reiner.Steib@gmx.de> * gnus.texi (Oort Gnus): Add message-fill-column. @@ -5788,6 +7357,10 @@ * tramp.texi (Remote processes): Add `shell-command'. +2008-02-02 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi: Use new FSF's Back-Cover Text. + 2008-01-28 Michael Sperber <sperber@deinprogramm.de> * gnus.texi (Mail Source Specifiers): Document `group' specifier. @@ -5888,7 +7461,7 @@ 2007-12-29 Jay Belanger <jay.p.belanger@gmail.com> - * calc.tex (Yacas Language, Maxima Language, Giac Language): + * calc.texi (Yacas Language, Maxima Language, Giac Language): New sections. 2007-12-29 Reiner Steib <Reiner.Steib@gmx.de> @@ -5906,6 +7479,10 @@ * trampver.texi: Update release number. +2007-12-22 Richard Stallman <rms@gnu.org> + + * cc-mode.texi (Getting Started): Change @ref to @pxref. + 2007-12-22 Michael Albinus <michael.albinus@gmx.de> * dbus.texi (Type Conversion): Correct input parameters mapping. @@ -6450,7 +8027,7 @@ 2007-10-28 Reiner Steib <Reiner.Steib@gmx.de> - * gnusref.tex: Mention `gnus-summary-limit-to-recipient' and + * gnus.texi: Mention `gnus-summary-limit-to-recipient' and `gnus-summary-sort-by-recipient'. 2007-10-28 Romain Francoise <romain@orebokech.com> @@ -7167,11 +8744,6 @@ * gnus.texi (Batching Agents): Fix example. Reported by Tassilo Horn <tassilo@member.fsf.org>. -2007-01-27 Eli Zaretskii <eliz@gnu.org> - - * msdog.texi (ls in Lisp): Document ls-lisp-format-time-list and - ls-lisp-use-localized-time-format. - 2007-01-20 Markus Triska <markus.triska@gmx.at> * flymake.texi (Flymake mode): find-file-hook instead of ...-hooks. @@ -7467,7 +9039,6 @@ * faq.texi (Escape sequences in shell output): EMACS is now set to Emacs's absolute file name, not to "t". (^M in the shell buffer): Likewise. - * misc.texi (Interactive Shell): Likewise. 2006-09-11 Reiner Steib <Reiner.Steib@gmx.de> @@ -7485,6 +9056,10 @@ * smtpmail.texi (Authentication): Mention SSL. +2006-09-03 Diane Murray <disumu@x3y2z1.net> + + * erc.texi (Getting Started, Connecting): Change erc-select to erc. + 2006-09-01 Eli Zaretskii <eliz@gnu.org> * rcirc.texi (Internet Relay Chat, Useful IRC commands): @@ -7504,7 +9079,7 @@ * org.texi (Installation, Activation): Split from Installation and Activation. - (Clocking work time): Documented new features. + (Clocking work time): Document new features. 2006-08-13 Alex Schroeder <alex@gnu.org> @@ -7931,6 +9506,10 @@ * gnus.texi (Security): Improve. +2006-04-02 Karl Berry <karl@gnu.org> + + * texinfo.tex: Update to current version (2006-03-21.13). + 2006-04-02 Bill Wohler <wohler@newt.com> * mh-e.texi (Getting Started, Junk, Bug Reports) @@ -8101,22 +9680,22 @@ * emacs-mime.texi (Flowed text): Add mm-fill-flowed. (Sync 2004-01-27 from the trunk). -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi: Rename c-hungry-backspace to c-hungry-delete-backwards, at the request of RMS. Leave the old name as an alias. -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi: Correct the definition of c-beginning-of-defun, to include the function header within the defun. -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi: Correct two typos. -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi (Comment Commands): State that C-u M-; kills any existing comment. @@ -8430,7 +10009,7 @@ (MIME with Emacs mail packages): Delete section about the Emacs MIME FAQ (it's not reachable anymore). -2005-12-08 Alan Mackenzie <bug-cc-mode@gnu.org> +2005-12-08 Alan Mackenzie <acm@muc.de> * cc-mode.texi: The manual has been extensively revised: the information about using CC Mode has been separated from the larger @@ -8658,7 +10237,7 @@ 2005-10-10 Carsten Dominik <dominik@science.uva.nl> - * org.texi (Workflow states): Documented that change in keywords + * org.texi (Workflow states): Document that change in keywords becomes active only after restart of Emacs. 2005-10-08 Michael Albinus <michael.albinus@gmx.de> @@ -8882,11 +10461,9 @@ * info.texi (Help-Xref): * message.texi (Message Headers): * org.texi (Remember): - * reftex.texi (Options (Defining Label Environments)): - (Options (Index Support)): - (Options (Viewing Cross-References)): - (Options (Misc)): - (Changes): + * reftex.texi (Options (Defining Label Environments)) + (Options (Index Support), Options (Viewing Cross-References)) + (Options (Misc), Changes): * speedbar.texi (Creating a display): * tramp.texi (Customizing Completion, Auto-save and Backup): Texinfo usage fix. @@ -9336,7 +10913,7 @@ 2004-11-03 Jan Djärv <jan.h.d@swipnet.se> * idlwave.texi (Continued Statement Indentation): - * reftex.texi (Options (Index Support)): + * reftex.texi (Options (Index Support)) (Displaying and Editing the Index, Table of Contents): * speedbar.texi (Creating a display, Major Display Modes): Replace non-nil with non-@code{nil}. @@ -9535,7 +11112,7 @@ * Makefile.in (../info/tramp, tramp.dvi): Depend on trampver.texi. -2004-08-11 Martin Stjernholm <bug-cc-mode@gnu.org> +2004-08-11 Martin Stjernholm <mast@lysator.liu.se> * cc-mode.texi: Various updates for CC Mode 5.30.9. @@ -9764,7 +11341,7 @@ (Top): More description for the `Default Method' menu entry. (Default Method): Use @code, not @var, for Lisp variables. (Default Method): New subsection `Which method is the right one - for me?' Suggested by Christian Kirsch. + for me?'. Suggested by Christian Kirsch. (Configuration): Pointer to new subsection added. (Default Method): Too many "use" in one sentence. Rephrase. Reported by Christian Kirsch. @@ -9783,7 +11360,7 @@ * eshell.texi (Known Problems): Add doc item. -2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org> +2003-11-22 Martin Stjernholm <mast@lysator.liu.se> * cc-mode.texi: Update for CC Mode 5.30. @@ -9793,8 +11370,8 @@ 2003-11-02 Jesper Harder <harder@ifa.au.dk> (tiny change) - * man/ediff.texi, man/tramp.texi, man/vip.texi, man/viper.texi: - * man/widget.texi, man/woman.texi: Replace @sc{ascii} and ASCII with + * ediff.texi, tramp.texi, vip.texi, viper.texi: + * widget.texi, woman.texi: Replace @sc{ascii} and ASCII with @acronym{ASCII}. 2003-10-26 Karl Berry <karl@gnu.org> @@ -10016,6 +11593,11 @@ `tramp-set-completion-function', because parsing of ssh config files looks more natural. +2003-01-15 Kevin Ryde <user42@zip.com.au> + + * gnus.texi (Using MIME): Mention auto-compression-mode with + gnus-mime-copy-part. + 2003-01-15 ShengHuo ZHU <zsh@cs.rochester.edu> * gnus.texi: Do not use `path' in several locations. @@ -10037,11 +11619,12 @@ 2002-10-02 Karl Berry <karl@gnu.org> - * (ada-mode.texi autotype.texi calc.texi cc-mode.texi cl.texi - dired-x.texi ebrowse.texi ediff.texi emacs-mime.texi - eshell.texi eudc.texi faq.texi forms.texi idlwave.texi info.texi - message.texi mh-e.texi pcl-cvs.texi reftex.texi sc.texi ses.texi - speedbar.texi vip.texi viper.texi widget.texi woman.texi): + * ada-mode.texi, autotype.texi, calc.texi, cc-mode.texi, cl.texi: + * dired-x.texi, ebrowse.texi, ediff.texi, emacs-mime.texi: + * eshell.texi, eudc.texi, faq.texi, forms.texi, idlwave.texi: + * info.texi, message.texi, mh-e.texi, pcl-cvs.texi, reftex.texi: + * sc.texi, ses.texi, speedbar.texi, vip.texi, viper.texi: + * widget.texi, woman.texi: Per rms, update all manuals to use @copying instead of @ifinfo. Also use @ifnottex instead of @ifinfo around the top node, where needed for the sake of the HTML output. @@ -10063,6 +11646,12 @@ * reftex.texi: Update to RefTeX 4.19. +2002-07-21 Jesper Harder <harder@ifa.au.dk> + + * gnus.texi (Sorting Groups): Add key bindings for + gnus-group-sort-groups-by-real-name and + gnus-group-sort-selected-groups-by-real-name. + 2002-06-17 Kai Großjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE> * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add Tramp. @@ -10095,6 +11684,12 @@ * Makefile.in (mostlyclean, maintainer-clean): Delete more files. +2001-02-12 Michael Kifer <kifer@cs.sunysb.edu> + + * ediff.texi: Added ediff-coding-system-for-read. + + * viper.texi: Fix typos. + 2000-12-20 Eli Zaretskii <eliz@is.elta.co.il> * Makefile.in (../info/idlwave): Use --no-split. @@ -10192,6 +11787,12 @@ * reftex.texi: Update for RefTeX version 3.22. +1998-03-01 Kim-Minh Kaplan <KimMinh.Kaplan@utopia.eunet.fr> + + * gnus.texi (Easy Picons): Remove references to + `gnus-group-display-picons'. + (Hard Picons): Ditto. + 1998-02-08 Richard Stallman <rms@psilocin.gnu.org> * Makefile.in (reftex.dvi, ../info/reftex): New targets. @@ -10214,6 +11815,10 @@ * Makefile (../info/viper, viper.dvi): Delete viper-cmd.texi dep. +1997-04-12 Per Abrahamsen <abraham@dina.kvl.dk> + + * widget.texi (push-button): Document it. + 1996-08-11 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> * Version 19.33 released. @@ -10379,7 +11984,7 @@ 1993-11-15 Paul Eggert (eggert@twinsun.com) - * man/Makefile (../info/cl.info): Rename from ../info/cl. + * Makefile (../info/cl.info): Rename from ../info/cl. 1993-11-15 Richard Stallman (rms@mole.gnu.ai.mit.edu) @@ -10395,9 +12000,6 @@ * forms.texi: Fix forms.texi so that it will format correctly. Add missing `@end iftex', fix bad reference. - * info.texi, info-stn.texi: New files implement texinfo version of - `info' file. - 1993-10-20 Brian J. Fox (bfox@ai.mit.edu) * Makefile: Fix targets for texindex, new info.texi files. @@ -10486,7 +12088,7 @@ 1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. + * texindex.c: If USG, include sys/types.h and sys/fcntl.h. 1989-01-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu) @@ -10514,7 +12116,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1993-1999, 2001-2013 Free Software Foundation, Inc. + Copyright (C) 1993-1999, 2001-2015 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 6618e125d7c..aa35002e85e 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1994, 1996-2013 Free Software Foundation, Inc. +# Copyright (C) 1994, 1996-2015 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -17,18 +17,19 @@ # 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 +SHELL = @SHELL@ -# 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. +# Where to find the source code. $(srcdir) will be the doc/misc subdirectory +# of the source tree. This is set by configure's '--srcdir' option. srcdir=@srcdir@ -version=@version@ - ## Where the output files go. +## Note that all the Info targets build the Info files in srcdir. +## There is no provision for Info files to exist in the build directory. +## In a tarfile of Emacs, the Info files should be up to date. buildinfodir = $(srcdir)/../../info -## Directory with emacsver.texi. + +## Directory with docstyle.texi and emacsver.texi. emacsdir = $(srcdir)/../emacs prefix = @prefix@ @@ -47,278 +48,74 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +# (Note that idlwave, info used --nosplit even without the .info extension.) +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ # The makeinfo program is part of the Texinfo distribution. # Use --force so that it generates output even if there are errors. +# (TODO? Why is this appropriate?) MAKEINFO = @MAKEINFO@ MAKEINFO_OPTS = --force -I$(emacsdir) -INFO_TARGETS = ada-mode auth autotype bovine calc ccmode cl \ +## On MS Windows, efaq-w32; otherwise blank. +DOCMISC_W32 = @DOCMISC_W32@ + +## Info files to build and install on all platforms. +INFO_COMMON = ada-mode auth autotype bovine calc ccmode cl \ dbus dired-x ebrowse ede ediff edt eieio \ - emacs-mime epa erc ert eshell eudc efaq \ + emacs-mime epa erc ert eshell eudc efaq eww \ flymake forms gnus emacs-gnutls htmlfontify idlwave ido info.info \ - mairix-el message mh-e newsticker nxml-mode \ + mairix-el message mh-e newsticker nxml-mode octave-mode \ org pcl-cvs pgg rcirc remember reftex sasl \ sc semantic ses sieve smtpmail speedbar srecode todo-mode tramp \ - url vip viper widget wisent woman - -DVI_TARGETS = \ - ada-mode.dvi \ - auth.dvi \ - autotype.dvi \ - bovine.dvi \ - calc.dvi \ - cc-mode.dvi \ - cl.dvi \ - dbus.dvi \ - dired-x.dvi \ - ebrowse.dvi \ - ede.dvi \ - ediff.dvi \ - edt.dvi \ - eieio.dvi \ - emacs-mime.dvi \ - epa.dvi \ - erc.dvi \ - ert.dvi \ - eshell.dvi \ - eudc.dvi \ - faq.dvi \ - flymake.dvi \ - forms.dvi \ - gnus.dvi \ - emacs-gnutls.dvi \ - htmlfontify.dvi \ - idlwave.dvi \ - ido.dvi \ - info.dvi \ - mairix-el.dvi \ - message.dvi \ - mh-e.dvi \ - newsticker.dvi \ - nxml-mode.dvi \ - org.dvi \ - pcl-cvs.dvi \ - pgg.dvi \ - rcirc.dvi \ - reftex.dvi \ - remember.dvi \ - sasl.dvi \ - sc.dvi \ - semantic.dvi \ - ses.dvi \ - sieve.dvi \ - smtpmail.dvi \ - speedbar.dvi \ - srecode.dvi \ - todo-mode.dvi \ - tramp.dvi \ - url.dvi \ - vip.dvi \ - viper.dvi \ - widget.dvi \ - wisent.dvi \ - woman.dvi - -HTML_TARGETS = \ - ada-mode.html \ - auth.html \ - autotype.html \ - bovine.html \ - calc.html \ - cc-mode.html \ - cl.html \ - dbus.html \ - dired-x.html \ - ebrowse.html \ - ede.html \ - ediff.html \ - edt.html \ - eieio.html \ - emacs-mime.html \ - epa.html \ - erc.html \ - ert.html \ - eshell.html \ - eudc.html \ - faq.html \ - flymake.html \ - forms.html \ - gnus.html \ - emacs-gnutls.html \ - htmlfontify.html \ - idlwave.html \ - ido.html \ - info.html \ - mairix-el.html \ - message.html \ - mh-e.html \ - newsticker.html \ - nxml-mode.html \ - org.html \ - pcl-cvs.html \ - pgg.html \ - rcirc.html \ - reftex.html \ - remember.html \ - sasl.html \ - sc.html \ - semantic.html \ - ses.html \ - sieve.html \ - smtpmail.html \ - speedbar.html \ - srecode.html \ - todo-mode.html \ - tramp.html \ - url.html \ - vip.html \ - viper.html \ - widget.html \ - wisent.html \ - woman.html - -PDF_TARGETS = \ - ada-mode.pdf \ - auth.pdf \ - autotype.pdf \ - bovine.pdf \ - calc.pdf \ - cc-mode.pdf \ - cl.pdf \ - dbus.pdf \ - dired-x.pdf \ - ebrowse.pdf \ - ede.pdf \ - ediff.pdf \ - edt.pdf \ - eieio.pdf \ - emacs-mime.pdf \ - epa.pdf \ - erc.pdf \ - ert.pdf \ - eshell.pdf \ - eudc.pdf \ - faq.pdf \ - flymake.pdf \ - forms.pdf \ - gnus.pdf \ - htmlfontify.pdf \ - emacs-gnutls.pdf \ - idlwave.pdf \ - ido.pdf \ - info.pdf \ - mairix-el.pdf \ - message.pdf \ - mh-e.pdf \ - newsticker.pdf \ - nxml-mode.pdf \ - org.pdf \ - pcl-cvs.pdf \ - pgg.pdf \ - rcirc.pdf \ - reftex.pdf \ - remember.pdf \ - sasl.pdf \ - sc.pdf \ - semantic.pdf \ - ses.pdf \ - sieve.pdf \ - smtpmail.pdf \ - speedbar.pdf \ - srecode.pdf \ - todo-mode.pdf \ - tramp.pdf \ - url.pdf \ - vip.pdf \ - viper.pdf \ - widget.pdf \ - wisent.pdf \ - woman.pdf - -PS_TARGETS = \ - ada-mode.ps \ - auth.ps \ - autotype.ps \ - bovine.ps \ - calc.ps \ - cc-mode.ps \ - cl.ps \ - dbus.ps \ - dired-x.ps \ - ebrowse.ps \ - ede.ps \ - ediff.ps \ - edt.ps \ - eieio.ps \ - emacs-mime.ps \ - epa.ps \ - erc.ps \ - ert.ps \ - eshell.ps \ - eudc.ps \ - faq.ps \ - flymake.ps \ - forms.ps \ - gnus.ps \ - htmlfontify.ps \ - emacs-gnutls.ps \ - idlwave.ps \ - ido.ps \ - info.ps \ - mairix-el.ps \ - message.ps \ - mh-e.ps \ - newsticker.ps \ - nxml-mode.ps \ - org.ps \ - pcl-cvs.ps \ - pgg.ps \ - rcirc.ps \ - reftex.ps \ - remember.ps \ - sasl.ps \ - sc.ps \ - semantic.ps \ - ses.ps \ - sieve.ps \ - smtpmail.ps \ - speedbar.ps \ - srecode.ps \ - todo-mode.ps \ - tramp.ps \ - url.ps \ - vip.ps \ - viper.ps \ - widget.ps \ - wisent.ps \ - woman.ps + url vhdl-mode vip viper widget wisent woman + +## Info files to install on current platform. +INFO_INSTALL = $(INFO_COMMON) $(DOCMISC_W32) + +## Info files to build on current platform. +## This is all of them, even though they might not all get installed, +## because the info files are pre-built in release tarfiles. +INFO_TARGETS = $(INFO_COMMON) efaq-w32 + +# There are some naming differences between the info targets and the other +# targets, so let's resolve them here. +TARGETS_1 = $(INFO_INSTALL:ccmode=cc-mode) +TARGETS = $(TARGETS_1:info.info=info) + +DVI_TARGETS = $(TARGETS:=.dvi) +HTML_TARGETS = $(TARGETS:=.html) +PDF_TARGETS = $(TARGETS:=.pdf) +PS_TARGETS = $(TARGETS:=.ps) TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = -mkinfodir = @${MKDIR_P} ${buildinfodir} +ENVADD = $(AM_V_GEN)TEXINPUTS="$(srcdir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" gfdl = ${srcdir}/doclicense.texi +style = ${emacsdir}/docstyle.texi -.PHONY: info dvi html pdf ps echo-info +.PHONY: info dvi html pdf ps echo-info $(INFO_TARGETS) ## Prevent implicit rule triggering for foo.info. .SUFFIXES: -.SUFFIXES: .ps .dvi - -.dvi.ps: - $(DVIPS) -o $@ $< +## Disable implicit rules. +%.texi: ; # Default. info: $(INFO_TARGETS) @@ -326,12 +123,8 @@ info: $(INFO_TARGETS) ## Used by top-level Makefile. ## Base file names of output info files. echo-info: - @echo "$(INFO_TARGETS) " | \ - sed -e 's|[^ ]*/||g' -e 's/\.info//g' -e "s/ */$(INFO_EXT) /g" - -# please modify this for all the web manual targets -webhack: clean - $(MAKE) pdf MAKEINFO_OPTS="-DWEBHACKDEVEL $(MAKEINFO_OPTS)" + @echo "$(INFO_INSTALL) " | \ + sed -e 's|[^ ]*/||g' -e 's/\.info//g' -e "s/ */.info /g" dvi: $(DVI_TARGETS) @@ -341,758 +134,138 @@ pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) -# Note that all the Info targets build the Info files in srcdir. -# There is no provision for Info files to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -# Note: "<" is not portable in ordinary make rules. - -ada_mode_deps = ${srcdir}/ada-mode.texi ${gfdl} -ada-mode : $(buildinfodir)/ada-mode$(INFO_EXT) -$(buildinfodir)/ada-mode$(INFO_EXT): $(ada_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ada-mode.texi -ada-mode.dvi: $(ada_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ada-mode.texi -ada-mode.pdf: $(ada_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ada-mode.texi -ada-mode.html: $(ada_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ada-mode.texi - -auth_deps = ${srcdir}/auth.texi ${gfdl} -auth : $(buildinfodir)/auth$(INFO_EXT) -$(buildinfodir)/auth$(INFO_EXT): $(auth_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/auth.texi -auth.dvi: $(auth_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/auth.texi -auth.pdf: $(auth_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/auth.texi -auth.html: $(auth_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/auth.texi - -autotype_deps = ${srcdir}/autotype.texi ${gfdl} -autotype : $(buildinfodir)/autotype$(INFO_EXT) -$(buildinfodir)/autotype$(INFO_EXT): $(autotype_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/autotype.texi -autotype.dvi: $(autotype_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/autotype.texi -autotype.pdf: $(autotype_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/autotype.texi -autotype.html: $(autotype_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/autotype.texi - -bovine_deps = ${srcdir}/bovine.texi ${gfdl} -bovine : $(buildinfodir)/bovine$(INFO_EXT) -$(buildinfodir)/bovine$(INFO_EXT): $(bovine_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/bovine.texi -bovine.dvi: $(bovine_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/bovine.texi -bovine.pdf: $(bovine_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/bovine.texi -bovine.html: $(bovine_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/bovine.texi - -calc_deps = ${srcdir}/calc.texi $(emacsdir)/emacsver.texi ${gfdl} -calc : $(buildinfodir)/calc$(INFO_EXT) -$(buildinfodir)/calc$(INFO_EXT): $(calc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/calc.texi -calc.dvi: $(calc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/calc.texi -calc.pdf: $(calc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/calc.texi -calc.html: $(calc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/calc.texi - -ccmode_deps = ${srcdir}/cc-mode.texi ${gfdl} -ccmode : $(buildinfodir)/ccmode$(INFO_EXT) -$(buildinfodir)/ccmode$(INFO_EXT): $(cc_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/cc-mode.texi -cc-mode.dvi: $(cc_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/cc-mode.texi -cc-mode.pdf: $(cc_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/cc-mode.texi -cc-mode.html: $(cc_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/cc-mode.texi - -cl_deps = ${srcdir}/cl.texi $(emacsdir)/emacsver.texi ${gfdl} -cl : $(buildinfodir)/cl$(INFO_EXT) -$(buildinfodir)/cl$(INFO_EXT): $(cl_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/cl.texi -cl.dvi: $(cl_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/cl.texi -cl.pdf: $(cl_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/cl.texi -cl.html: $(cl_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/cl.texi - -dbus_deps = ${srcdir}/dbus.texi ${gfdl} -dbus : $(buildinfodir)/dbus$(INFO_EXT) -$(buildinfodir)/dbus$(INFO_EXT): $(dbus_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/dbus.texi -dbus.dvi: $(dbus_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/dbus.texi -dbus.pdf: $(dbus_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/dbus.texi -dbus.html: $(dbus_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/dbus.texi - -dired_x_deps = ${srcdir}/dired-x.texi $(emacsdir)/emacsver.texi ${gfdl} -dired-x : $(buildinfodir)/dired-x$(INFO_EXT) -$(buildinfodir)/dired-x$(INFO_EXT): $(dired_x_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/dired-x.texi -dired-x.dvi: $(dired_x_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/dired-x.texi -dired-x.pdf: $(dired_x_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/dired-x.texi -dired-x.html: $(dired_x_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/dired-x.texi - -ebrowse_deps = ${srcdir}/ebrowse.texi ${gfdl} -ebrowse : $(buildinfodir)/ebrowse$(INFO_EXT) -$(buildinfodir)/ebrowse$(INFO_EXT): $(ebrowse_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ebrowse.texi -ebrowse.dvi: $(ebrowse_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ebrowse.texi -ebrowse.pdf: $(ebrowse_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ebrowse.texi -ebrowse.html: $(ebrowse_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ebrowse.texi - -ede_deps = ${srcdir}/ede.texi ${gfdl} -ede : $(buildinfodir)/ede$(INFO_EXT) -$(buildinfodir)/ede$(INFO_EXT): $(ede_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ede.texi -ede.dvi: $(ede_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ede.texi -ede.pdf: $(ede_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ede.texi -ede.html: $(ede_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ede.texi - -ediff_deps = ${srcdir}/ediff.texi ${gfdl} -ediff : $(buildinfodir)/ediff$(INFO_EXT) -$(buildinfodir)/ediff$(INFO_EXT): $(ediff_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ediff.texi -ediff.dvi: $(ediff_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi -ediff.pdf: $(ediff_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ediff.texi -ediff.html: $(ediff_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ediff.texi - -edt_deps = ${srcdir}/edt.texi ${gfdl} -edt : $(buildinfodir)/edt$(INFO_EXT) -$(buildinfodir)/edt$(INFO_EXT): $(edt_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/edt.texi -edt.dvi: $(edt_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/edt.texi -edt.pdf: $(edt_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/edt.texi -edt.html: $(edt_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/edt.texi - -eieio_deps = ${srcdir}/eieio.texi ${gfdl} -eieio : $(buildinfodir)/eieio$(INFO_EXT) -$(buildinfodir)/eieio$(INFO_EXT): $(eieio_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/eieio.texi -eieio.dvi: $(eieio_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/eieio.texi -eieio.pdf: $(eieio_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/eieio.texi -eieio.html: $(eieio_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/eieio.texi - -emacs_gnutls_deps = ${srcdir}/emacs-gnutls.texi ${gfdl} -emacs-gnutls : $(buildinfodir)/emacs-gnutls$(INFO_EXT) -$(buildinfodir)/emacs-gnutls$(INFO_EXT): $(emacs_gnutls_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs-gnutls.texi -emacs-gnutls.dvi: $(emacs_gnutls_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-gnutls.texi -emacs-gnutls.pdf: $(emacs_gnutls_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-gnutls.texi -emacs-gnutls.html: $(emacs_gnutls_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs-gnutls.texi - -emacs_mime_deps = ${srcdir}/emacs-mime.texi ${gfdl} -emacs-mime : $(buildinfodir)/emacs-mime$(INFO_EXT) -$(buildinfodir)/emacs-mime$(INFO_EXT): $(emacs_mime_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) --enable-encoding -o $@ ${srcdir}/emacs-mime.texi -emacs-mime.dvi: $(emacs_mime_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-mime.texi -emacs-mime.pdf: $(emacs_mime_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-mime.texi -emacs-mime.html: $(emacs_mime_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) --enable-encoding -o $@ ${srcdir}/emacs-mime.texi - -epa_deps = ${srcdir}/epa.texi ${gfdl} -epa : $(buildinfodir)/epa$(INFO_EXT) -$(buildinfodir)/epa$(INFO_EXT): $(epa_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/epa.texi -epa.dvi: $(epa_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/epa.texi -epa.pdf: $(epa_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/epa.texi -epa.html: $(epa_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/epa.texi - -erc_deps = ${srcdir}/erc.texi $(emacsdir)/emacsver.texi ${gfdl} -erc : $(buildinfodir)/erc$(INFO_EXT) -$(buildinfodir)/erc$(INFO_EXT): $(erc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/erc.texi -erc.dvi: $(erc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/erc.texi -erc.pdf: $(erc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/erc.texi -erc.html: $(erc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/erc.texi - -ert_deps = ${srcdir}/ert.texi ${gfdl} -ert : $(buildinfodir)/ert$(INFO_EXT) -$(buildinfodir)/ert$(INFO_EXT): $(ert_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ert.texi -ert.dvi: $(ert_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ert.texi -ert.pdf: $(ert_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ert.texi -ert.html: $(ert_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ert.texi - -eshell_deps = ${srcdir}/eshell.texi ${gfdl} -eshell : $(buildinfodir)/eshell$(INFO_EXT) -$(buildinfodir)/eshell$(INFO_EXT): $(eshell_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/eshell.texi -eshell.dvi: $(eshell_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi -eshell.pdf: $(eshell_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/eshell.texi -eshell.html: $(eshell_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/eshell.texi - -eudc_deps = ${srcdir}/eudc.texi ${gfdl} -eudc : $(buildinfodir)/eudc$(INFO_EXT) -$(buildinfodir)/eudc$(INFO_EXT): $(eudc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/eudc.texi -eudc.dvi: $(eudc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/eudc.texi -eudc.pdf: $(eudc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/eudc.texi -eudc.html: $(eudc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/eudc.texi - -## No gfdl dependency. -faq_deps = ${srcdir}/faq.texi $(emacsdir)/emacsver.texi -efaq : $(buildinfodir)/efaq$(INFO_EXT) -$(buildinfodir)/efaq$(INFO_EXT): $(faq_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/faq.texi -faq.dvi: $(faq_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/faq.texi -faq.pdf: $(faq_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/faq.texi -faq.html: $(faq_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/faq.texi - -flymake_deps = ${srcdir}/flymake.texi ${gfdl} -flymake : $(buildinfodir)/flymake$(INFO_EXT) -$(buildinfodir)/flymake$(INFO_EXT): $(flymake_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/flymake.texi -flymake.dvi: $(flymake_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/flymake.texi -flymake.pdf: $(flymake_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/flymake.texi -flymake.html: $(flymake_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/flymake.texi - -forms_deps = ${srcdir}/forms.texi ${gfdl} -forms : $(buildinfodir)/forms$(INFO_EXT) -$(buildinfodir)/forms$(INFO_EXT): $(forms_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/forms.texi -forms.dvi: $(forms_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/forms.texi -forms.pdf: $(forms_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/forms.texi -forms.html: $(forms_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/forms.texi - -## gnus/message/emacs-mime/sieve/pgg are part of Gnus. -gnus_deps = ${srcdir}/gnus.texi ${srcdir}/gnus-faq.texi ${gfdl} -gnus : $(buildinfodir)/gnus$(INFO_EXT) -$(buildinfodir)/gnus$(INFO_EXT): $(gnus_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/gnus.texi +${buildinfodir}: + ${MKDIR_P} $@ + +### The general case. + +EXTRA_OPTS = + +${buildinfodir}/%.info: ${srcdir}/%.texi ${gfdl} ${style} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) $(EXTRA_OPTS) \ + -o $@ $< + +## The short aliases, eg efaq = $(buildinfodir)/efaq.info. +define info_template + $(1): $$(buildinfodir)/$(1).info +endef + +## "info" is already taken. +info.info: $(buildinfodir)/info.info + +$(foreach ifile,$(filter-out info.info,$(INFO_TARGETS)),$(eval $(call info_template,$(ifile)))) + + +%.dvi: ${srcdir}/%.texi ${gfdl} ${style} + $(ENVADD) $(TEXI2DVI) $< + +%.pdf: ${srcdir}/%.texi ${gfdl} ${style} + $(ENVADD) $(TEXI2PDF) $< + +%.html: ${srcdir}/%.texi ${gfdl} ${style} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) $(EXTRA_OPTS) \ + -o $@ $< + +%.ps: %.dvi + $(DVIPS) -o $@ $< + + +### The exceptions. + +## Extra dependencies. + +need_emacsver = calc cl dired-x efaq efaq-w32 erc ido reftex woman +need_emacsver_prefix = $(addprefix ${buildinfodir}/,${need_emacsver}) + +$(need_emacsver_prefix:=.info) $(need_emacsver:=.dvi) $(need_emacsver:=.pdf) $(need_emacsver:=.html) : ${emacsdir}/emacsver.texi + +$(buildinfodir)/gnus.info gnus.html: ${srcdir}/gnus-faq.texi + +$(buildinfodir)/semantic.info semantic.dvi semantic.pdf semantic.html: ${srcdir}/sem-user.texi + + +## Please can we just rename cc-mode.texi to ccmode.texi... +${buildinfodir}/ccmode.info: \ + ${srcdir}/cc-mode.texi ${gfdl} ${style} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< + +## efaq, efaq_w32 do not depend on gfdl. +## Maybe we can use .SECONDEXPANSION for this. +${buildinfodir}/efaq%.info: ${srcdir}/efaq%.texi ${style} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< + +efaq%.dvi: ${srcdir}/efaq%.texi + $(ENVADD) $(TEXI2DVI) $< + +efaq%.pdf: ${srcdir}/efaq%.texi + $(ENVADD) $(TEXI2PDF) $< + +efaq%.html: ${srcdir}/efaq%.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< + +${buildinfodir}/emacs-mime.info emacs-mime.html: EXTRA_OPTS = --enable-encoding + +gnus_deps = ${srcdir}/gnus.texi ${srcdir}/gnus-faq.texi ${gfdl} ${style} gnus.dvi: $(gnus_deps) - sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi - $(ENVADD) $(TEXI2DVI) gnustmp.texi - cp gnustmp.dvi $@ - rm gnustmp.* + sed -e '/@iflatex/,/@end iflatex/d' $< > gnustmpdvi.texi + $(ENVADD) $(TEXI2DVI) gnustmpdvi.texi + cp gnustmpdvi.dvi $@ + rm gnustmpdvi.* + gnus.pdf: $(gnus_deps) - sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi - $(ENVADD) $(TEXI2PDF) gnustmp.texi - cp gnustmp.pdf $@ - rm gnustmp.* -gnus.html: $(gnus_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/gnus.texi - -htmlfontify_deps = ${srcdir}/htmlfontify.texi ${gfdl} -htmlfontify : $(buildinfodir)/htmlfontify$(INFO_EXT) -$(buildinfodir)/htmlfontify$(INFO_EXT): $(htmlfontify_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/htmlfontify.texi -htmlfontify.dvi: $(htmlfontify_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/htmlfontify.texi -htmlfontify.pdf: $(htmlfontify_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/htmlfontify.texi -htmlfontify.html: $(htmlfontify_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/htmlfontify.texi - -idlwave_deps = ${srcdir}/idlwave.texi ${gfdl} -idlwave : $(buildinfodir)/idlwave$(INFO_EXT) -# NB this one needs --no-split even without a .info extension. -$(buildinfodir)/idlwave$(INFO_EXT): $(idlwave_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/idlwave.texi -idlwave.dvi: $(idlwave_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/idlwave.texi -idlwave.pdf: $(idlwave_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/idlwave.texi -idlwave.html: $(idlwave_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/idlwave.texi - -ido_deps = ${srcdir}/ido.texi $(emacsdir)/emacsver.texi ${gfdl} -ido : $(buildinfodir)/ido$(INFO_EXT) -$(buildinfodir)/ido$(INFO_EXT): $(ido_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ido.texi -ido.dvi: $(ido_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ido.texi -ido.pdf: $(ido_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ido.texi -ido.html: $(ido_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ido.texi - -info_deps = ${srcdir}/info.texi ${gfdl} -# Avoid name clash with overall "info" target. -info.info : $(buildinfodir)/info$(INFO_EXT) -# NB this one needs --no-split even without a .info extension. -$(buildinfodir)/info$(INFO_EXT): $(info_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/info.texi -info.dvi: $(info_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/info.texi -info.pdf: $(info_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/info.texi -info.html: $(info_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/info.texi - -mairix_el_deps = ${srcdir}/mairix-el.texi ${gfdl} -mairix-el : $(buildinfodir)/mairix-el$(INFO_EXT) -$(buildinfodir)/mairix-el$(INFO_EXT): $(mairix_el_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/mairix-el.texi -mairix-el.dvi: $(mairix_el_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/mairix-el.texi -mairix-el.pdf: $(mairix_el_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/mairix-el.texi -mairix-el.html: $(mairix_el_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/mairix-el.texi - -message_deps = ${srcdir}/message.texi ${gfdl} -message : $(buildinfodir)/message$(INFO_EXT) -$(buildinfodir)/message$(INFO_EXT): $(message_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/message.texi -message.dvi: $(message_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/message.texi -message.pdf: $(message_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/message.texi -message.html: $(message_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/message.texi - -mh_e_deps = ${srcdir}/mh-e.texi ${gfdl} -mh-e : $(buildinfodir)/mh-e$(INFO_EXT) -$(buildinfodir)/mh-e$(INFO_EXT): $(mh_e_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/mh-e.texi -mh-e.dvi: $(mh_e_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/mh-e.texi -mh-e.pdf: $(mh_e_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/mh-e.texi -mh-e.html: $(mh_e_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/mh-e.texi - -newsticker_deps = ${srcdir}/newsticker.texi ${gfdl} -newsticker : $(buildinfodir)/newsticker$(INFO_EXT) -$(buildinfodir)/newsticker$(INFO_EXT): $(newsticker_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/newsticker.texi -newsticker.dvi: $(newsticker_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi -newsticker.pdf: $(newsticker_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/newsticker.texi -newsticker.html: $(newsticker_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/newsticker.texi - -nxml_mode_deps = ${srcdir}/nxml-mode.texi ${gfdl} -nxml-mode : $(buildinfodir)/nxml-mode$(INFO_EXT) -$(buildinfodir)/nxml-mode$(INFO_EXT): $(nxml_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/nxml-mode.texi -nxml-mode.dvi: $(nxml_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/nxml-mode.texi -nxml-mode.pdf: $(nxml_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/nxml-mode.texi -nxml-mode.html: $(nxml_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/nxml-mode.texi - -org_deps = ${srcdir}/org.texi ${gfdl} -org : $(buildinfodir)/org$(INFO_EXT) -$(buildinfodir)/org$(INFO_EXT): $(org_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/org.texi -org.dvi: $(org_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/org.texi -org.pdf: $(org_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/org.texi -org.html: $(org_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/org.texi - -pcl_cvs_deps = ${srcdir}/pcl-cvs.texi ${gfdl} -pcl-cvs : $(buildinfodir)/pcl-cvs$(INFO_EXT) -$(buildinfodir)/pcl-cvs$(INFO_EXT): $(pcl_cvs_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/pcl-cvs.texi -pcl-cvs.dvi: $(pcl_cvs_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi -pcl-cvs.pdf: $(pcl_cvs_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/pcl-cvs.texi -pcl-cvs.html: $(pcl_cvs_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/pcl-cvs.texi - -pgg_deps = ${srcdir}/pgg.texi ${gfdl} -pgg : $(buildinfodir)/pgg$(INFO_EXT) -$(buildinfodir)/pgg$(INFO_EXT): $(pgg_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/pgg.texi -pgg.dvi: $(pgg_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/pgg.texi -pgg.pdf: $(pgg_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/pgg.texi -pgg.html: $(pgg_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/pgg.texi - -rcirc_deps = ${srcdir}/rcirc.texi ${gfdl} -rcirc : $(buildinfodir)/rcirc$(INFO_EXT) -$(buildinfodir)/rcirc$(INFO_EXT): $(rcirc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/rcirc.texi -rcirc.dvi: $(rcirc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/rcirc.texi -rcirc.pdf: $(rcirc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/rcirc.texi -rcirc.html: $(rcirc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/rcirc.texi - -reftex_deps = ${srcdir}/reftex.texi $(emacsdir)/emacsver.texi ${gfdl} -reftex : $(buildinfodir)/reftex$(INFO_EXT) -$(buildinfodir)/reftex$(INFO_EXT): $(reftex_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/reftex.texi -reftex.dvi: $(reftex_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/reftex.texi -reftex.pdf: $(reftex_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/reftex.texi -reftex.html: $(reftex_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/reftex.texi - -remember_deps = ${srcdir}/remember.texi ${gfdl} -remember : $(buildinfodir)/remember$(INFO_EXT) -$(buildinfodir)/remember$(INFO_EXT): $(remember_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/remember.texi -remember.dvi: $(remember_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/remember.texi -remember.pdf: $(remember_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/remember.texi -remember.html: $(remember_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/remember.texi - -sasl_deps = ${srcdir}/sasl.texi ${gfdl} -sasl : $(buildinfodir)/sasl$(INFO_EXT) -$(buildinfodir)/sasl$(INFO_EXT): $(sasl_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/sasl.texi -sasl.dvi: $(sasl_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/sasl.texi -sasl.pdf: $(sasl_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/sasl.texi -sasl.html: $(sasl_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/sasl.texi - -sc_deps = ${srcdir}/sc.texi ${gfdl} -sc : $(buildinfodir)/sc$(INFO_EXT) -$(buildinfodir)/sc$(INFO_EXT): $(sc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/sc.texi -sc.dvi: $(sc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi -sc.pdf: $(sc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/sc.texi -sc.html: $(sc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/sc.texi - -semantic_deps = ${srcdir}/semantic.texi ${srcdir}/sem-user.texi ${gfdl} -semantic : $(buildinfodir)/semantic$(INFO_EXT) -$(buildinfodir)/semantic$(INFO_EXT): $(semantic_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/semantic.texi -semantic.dvi: $(semantic_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/semantic.texi -semantic.pdf: $(semantic_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/semantic.texi -semantic.html: $(semantic_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/semantic.texi - -ses_deps = ${srcdir}/ses.texi ${gfdl} -ses : $(buildinfodir)/ses$(INFO_EXT) -$(buildinfodir)/ses$(INFO_EXT): $(ses_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ses.texi -ses.dvi: $(ses_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ses.texi -ses.pdf: $(ses_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ses.texi -ses.html: $(ses_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ses.texi - -sieve_deps = ${srcdir}/sieve.texi ${gfdl} -sieve : $(buildinfodir)/sieve$(INFO_EXT) -$(buildinfodir)/sieve$(INFO_EXT): $(sieve_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/sieve.texi -sieve.dvi: $(sieve_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/sieve.texi -sieve.pdf: $(sieve_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/sieve.texi -sieve.html: $(sieve_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/sieve.texi - -smtpmail_deps = ${srcdir}/smtpmail.texi ${gfdl} -smtpmail : $(buildinfodir)/smtpmail$(INFO_EXT) -$(buildinfodir)/smtpmail$(INFO_EXT): $(smtpmail_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/smtpmail.texi -smtpmail.dvi: $(smtpmail_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/smtpmail.texi -smtpmail.pdf: $(smtpmail_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/smtpmail.texi -smtpmail.html: $(smtpmail_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/smtpmail.texi - -speedbar_deps = ${srcdir}/speedbar.texi ${gfdl} -speedbar : $(buildinfodir)/speedbar$(INFO_EXT) -$(buildinfodir)/speedbar$(INFO_EXT): $(speedbar_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/speedbar.texi -speedbar.dvi: $(speedbar_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/speedbar.texi -speedbar.pdf: $(speedbar_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/speedbar.texi -speedbar.html: $(speedbar_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/speedbar.texi - -srecode_deps = ${srcdir}/srecode.texi ${gfdl} -srecode : $(buildinfodir)/srecode$(INFO_EXT) -$(buildinfodir)/srecode$(INFO_EXT): $(srecode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/srecode.texi -srecode.dvi: $(srecode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/srecode.texi -srecode.pdf: $(srecode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/srecode.texi -srecode.html: $(srecode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/srecode.texi - -todo_mode_deps = ${srcdir}/todo-mode.texi ${gfdl} -todo-mode : $(buildinfodir)/todo-mode$(INFO_EXT) -$(buildinfodir)/todo-mode$(INFO_EXT): $(todo_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/todo-mode.texi -todo-mode.dvi: $(todo_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/todo-mode.texi -todo-mode.pdf: $(todo_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/todo-mode.texi -todo-mode.html: $(todo_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/todo-mode.texi - -tramp_deps = ${srcdir}/tramp.texi ${srcdir}/trampver.texi ${gfdl} -tramp : $(buildinfodir)/tramp$(INFO_EXT) -$(buildinfodir)/tramp$(INFO_EXT): $(tramp_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ -D emacs ${srcdir}/tramp.texi -tramp.dvi: $(tramp_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/tramp.texi -tramp.pdf: $(tramp_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/tramp.texi -tramp.html: $(tramp_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ -D emacs ${srcdir}/tramp.texi - -url_deps = ${srcdir}/url.texi ${gfdl} -url : $(buildinfodir)/url$(INFO_EXT) -$(buildinfodir)/url$(INFO_EXT): $(url_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/url.texi -url.dvi: $(url_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/url.texi -url.pdf: $(url_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/url.texi -url.html: $(url_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/url.texi - -vip_deps = ${srcdir}/vip.texi ${gfdl} -vip : $(buildinfodir)/vip$(INFO_EXT) -$(buildinfodir)/vip$(INFO_EXT): $(vip_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/vip.texi -vip.dvi: $(vip_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/vip.texi -vip.pdf: $(vip_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/vip.texi -vip.html: $(vip_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/vip.texi - -viper_deps = ${srcdir}/viper.texi ${gfdl} -viper : $(buildinfodir)/viper$(INFO_EXT) -$(buildinfodir)/viper$(INFO_EXT): $(viper_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/viper.texi -viper.dvi: $(viper_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/viper.texi -viper.pdf: $(viper_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/viper.texi -viper.html: $(viper_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/viper.texi - -widget_deps = ${srcdir}/wisent.texi ${gfdl} -widget : $(buildinfodir)/widget$(INFO_EXT) -$(buildinfodir)/widget$(INFO_EXT): $(widget_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/widget.texi -widget.dvi: $(widget_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/widget.texi -widget.pdf: $(widget_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/widget.texi -widget.html: $(widget_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/widget.texi - -wisent_deps = ${srcdir}/wisent.texi ${gfdl} -wisent : $(buildinfodir)/wisent$(INFO_EXT) -$(buildinfodir)/wisent$(INFO_EXT): $(wisent_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/wisent.texi -wisent.dvi: $(wisent_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/wisent.texi -wisent.pdf: $(wisent_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/wisent.texi -wisent.html: $(wisent_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/wisent.texi - -woman_deps = ${srcdir}/woman.texi $(emacsdir)/emacsver.texi ${gfdl} -woman : $(buildinfodir)/woman$(INFO_EXT) -$(buildinfodir)/woman$(INFO_EXT): $(woman_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/woman.texi -woman.dvi: $(woman_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/woman.texi -woman.pdf: $(woman_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/woman.texi -woman.html: $(woman_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/woman.texi - -.PHONY: mostlyclean clean distclean maintainer-clean + sed -e '/@iflatex/,/@end iflatex/d' $< > gnustmppdf.texi + $(ENVADD) $(TEXI2PDF) gnustmppdf.texi + cp gnustmppdf.pdf $@ + rm gnustmppdf.* + +${buildinfodir}/tramp.info tramp.html: EXTRA_OPTS = -D emacs +${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi + + +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean mostlyclean: rm -f *.aux *.log *.toc *.c[mp] *.c[mp]s *.fn *.fns \ *.ky *.kys *.op *.ops *.p[gj] *.p[gj]s *.sc *.scs *.ss \ *.t[gp] *.t[gp]s *.vr *.vrs - rm -f gnustmp.* + rm -f gnustmp* clean: mostlyclean - rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f emacs-misc-${version}.tar* + rm -f *.dvi *.html *.pdf *.ps distclean: clean -# rm -f Makefile + rm -f Makefile ## buildinfodir is relative to srcdir. infoclean: - cd $(buildinfodir); for file in $(INFO_TARGETS); do \ - file=`echo $${file} | sed 's/\.info$$//'`${INFO_EXT}; \ - rm -f $${file} $${file}-[1-9] $${file}-[1-9][0-9]; \ + for file in $(INFO_TARGETS); do \ + file=`echo $${file} | sed 's/\.info$$//'`.info; \ + rm -f \ + $(buildinfodir)/$${file} \ + $(buildinfodir)/$${file}-[1-9] \ + $(buildinfodir)/$${file}-[1-9][0-9]; \ done -maintainer-clean: distclean infoclean - -dist: - rm -rf emacs-misc-${version} - mkdir emacs-misc-${version} - cp ${srcdir}/*.texi ${srcdir}/texinfo.tex \ - $(emacsdir)/emacsver.texi ${srcdir}/ChangeLog* \ - emacs-misc-${version}/ - sed -e 's/@sr[c]dir@/./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - ${srcdir}/Makefile.in > emacs-misc-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-misc-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-misc-${version}.tar emacs-misc-${version} - rm -rf emacs-misc-${version} - +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc install-dvi: dvi - umask 022; $(MKDIR_P) $(DESTDIR)$(dvidir) - $(INSTALL_DATA) $(DVI_TARGETS) $(DESTDIR)$(dvidir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" + $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" install-html: html - umask 022; $(MKDIR_P) $(DESTDIR)$(htmldir) - $(INSTALL_DATA) $(HTML_TARGETS) $(DESTDIR)$(htmldir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" + $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" install-pdf: pdf - umask 022;$(MKDIR_P) $(DESTDIR)$(pdfdir) - $(INSTALL_DATA) $(PDF_TARGETS) $(DESTDIR)$(pdfdir) + umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" + $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" install-ps: ps - umask 022; $(MKDIR_P) $(DESTDIR)$(psdir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} $(DESTDIR)$(psdir); \ + $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ [ -n "${GZIP_PROG}" ] || continue; \ - rm -f $(DESTDIR)$(psdir)/$${file}.gz; \ - ${GZIP_PROG} -9n $(DESTDIR)$(psdir)/$${file}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ + ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ done ## Top-level Makefile installs the info pages. @@ -1104,20 +277,20 @@ install-doc: install-dvi install-html install-pdf install-ps uninstall-dvi: for file in $(DVI_TARGETS); do \ - rm -f $(DESTDIR)$(dvidir)/$${file}; \ + rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ done uninstall-html: for file in $(HTML_TARGETS); do \ - rm -f $(DESTDIR)$(htmldir)/$${file}; \ + rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ done uninstall-ps: ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ for file in $(PS_TARGETS); do \ - rm -f $(DESTDIR)$(psdir)/$${file}$${ext}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ done uninstall-pdf: for file in $(PDF_TARGETS); do \ - rm -f $(DESTDIR)$(pdfdir)/$${file}; \ + rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ done uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi index b5a640e13e0..e84ef6eb512 100644 --- a/doc/misc/ada-mode.texi +++ b/doc/misc/ada-mode.texi @@ -1,15 +1,16 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/ada-mode +@setfilename ../../info/ada-mode.info @settitle Ada Mode +@include docstyle.texi @copying -Copyright @copyright{} 1999--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2015 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'', +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''. @@ -351,7 +352,7 @@ Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code The @code{Check file}, @code{Compile file}, and @code{Build} commands all place compilation errors in a separate buffer named -@code{*compilation*}. +@file{*compilation*}. Each line in this buffer will become active: you can simply click on it with the middle button of the mouse, or move point to it and press @@ -373,8 +374,8 @@ An Emacs Ada mode project file specifies what directories hold sources for your project, and allows you to customize the compilation commands and other things on a per-project basis. -Note that Ada mode project files @samp{*.adp} are different than GNAT -compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a +Note that Ada mode project files @file{*.adp} are different than GNAT +compiler project files @file{*.gpr}. However, Emacs Ada mode can use a GNAT project file to specify the project directories. If no other customization is needed, a GNAT project file can be used without an Emacs Ada mode project file. @@ -727,7 +728,7 @@ Yes, this is missing the keyword @code{body}; another compiler error example. In buffer @file{hello.adb}, invoke @samp{Ada | Check file}. You should -get a @code{*compilation*} buffer containing something like (the +get a @file{*compilation*} buffer containing something like (the directory paths will be different): @smallexample @@ -814,7 +815,7 @@ Emacs has remembered the main file, in the project variable @code{main}, and used it for the Build command. Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Run}. -The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}. +The @file{*run*} buffer displays @code{Hello from hello_pkg.adb}. One final point. If you switch back to buffer @file{hello.adb}, and invoke @samp{Ada | Run}, @file{hello_2.exe} will be run. That is @@ -875,7 +876,7 @@ In buffer @file{hello.adb}, invoke @samp{Ada | Project | Load...}, and select @file{Example_2/hello.adp}. Then, again in buffer @file{hello.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing +Build}. You should get a @file{*compilation*} buffer containing something like (the directory paths will be different): @example @@ -959,7 +960,7 @@ In buffer @file{hello_3.adb}, invoke @samp{Ada | Project | Load...}, and select @file{Example_3/Other/other.adp}. Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing +Build}. You should get a @file{*compilation*} buffer containing something like (the directory paths will be different): @example @@ -1042,7 +1043,7 @@ In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and select @file{Example_4/Gnat_Project/hello_4.gpr}. Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing +Build}. You should get a @file{*compilation*} buffer containing something like (the directory paths will be different): @smallexample @@ -1109,7 +1110,7 @@ In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Load...}, and select @file{Example_5/hello_5.adp}. Then, again in @file{hello_5.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing +Build}. You should get a @file{*compilation*} buffer containing something like (the directory paths will be different): @smallexample diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index 36ee400acca..082dc1dacdf 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -4,19 +4,20 @@ @set VERSION 0.3 -@setfilename ../../info/auth +@setfilename ../../info/auth.info @settitle Emacs auth-source Library @value{VERSION} +@include docstyle.texi @copying This file describes the Emacs auth-source library. -Copyright @copyright{} 2008--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2008--2015 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,'' +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''. @@ -58,6 +59,7 @@ It is a way for multiple applications to share a single configuration @menu * Overview:: Overview of the auth-source library. * Help for users:: +* Multiple GMail accounts with Gnus:: * Secret Service API:: * Help for developers:: * GnuPG and EasyPG Assistant Configuration:: @@ -105,12 +107,17 @@ 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 @samp{\}. +You can use spaces inside a password or other token by surrounding the +token with either single or double quotes. -All these are optional. You could just say (but we don't recommend -it, we're just showing that it's possible) +You can use apostrophes inside a password or other token by +surrounding it with double quotes, e.g., @code{"he'llo"}. Similarly you +can use double quotes inside a password or other token by surrounding +it with apostrophes, e.g., @code{'he"llo'}. You can't mix both (so a +password or other token can't have both apostrophes and double quotes). + +All this is optional. You could just say (but we don't recommend it, +we're just showing that it's possible) @example password @var{mypassword} @@ -126,7 +133,7 @@ later. 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 @samp{*Messages*} buffer. Ditto for any other +checking in the @file{*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. @@ -223,6 +230,27 @@ 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 Multiple GMail accounts with Gnus +@chapter Multiple GMail accounts with Gnus + +For multiple GMail accounts with Gnus, you have to make two nnimap +entries in your @code{gnus-secondary-select-methods} with distinct +names: + +@example +(setq gnus-secondary-select-methods '((nnimap "gmail" + (nnimap-address "imap.gmail.com")) + (nnimap "gmail2" + (nnimap-address "imap.gmail.com")))) +@end example + +Your netrc entries will then be: + +@example +machine gmail login account@@gmail.com password "account password" port imap +machine gmail2 login account2@@gmail.com password "account2 password" port imap +@end example + @node Secret Service API @chapter Secret Service API @@ -381,7 +409,7 @@ The auth-source library lets you control logging output easily. @defvar auth-source-debug Set this variable to @code{'trivia} to see lots of output in -@samp{*Messages*}, or set it to a function that behaves like +@file{*Messages*}, or set it to a function that behaves like @code{message} to do your own logging. @end defvar @@ -469,10 +497,10 @@ It returns the number of items forgotten. @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 @file{~/.authinfo.gpg}, which is a GnuPG encrypted file. Then -it will check @file{~/.authinfo} but it's not recommended to use such -an unencrypted file. +If the @code{auth-sources} variable contains @file{~/.authinfo.gpg} +before @file{~/.authinfo}, the auth-source library will try to +read the GnuPG encrypted @file{.gpg} file first, before +the unencrypted file. In Emacs 23 or later there is an option @code{auto-encryption-mode} to automatically decrypt @file{*.gpg} files. It is enabled by default. diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index 137ed6b43e8..f7c1fa1a9e0 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -1,23 +1,24 @@ \input texinfo @c This is an annex of the Emacs manual. -@c Author: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389 -@setfilename ../../info/autotype +@c Author: Daniel Pfeiffer <Daniel.Pfeiffer@Informatik.START.dbp.de> +@setfilename ../../info/autotype.info @c @node Autotypist, Picture, Abbrevs, Top @c @chapter Features for Automatic Typing @settitle Features for Automatic Typing +@include docstyle.texi @c @cindex text @c @cindex selfinserting text @c @cindex autotypist @copying -Copyright @copyright{} 1994--1995, 1999, 2001--2013 +Copyright @copyright{} 1994--1995, 1999, 2001--2015 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'', +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''. @@ -28,8 +29,8 @@ modify this GNU manual.'' @dircategory Emacs misc features @direntry -* Autotype: (autotype). Convenient features for text that you - enter frequently in Emacs. +* Autotype: (autotype). Convenient features for text that you enter + frequently in Emacs. @end direntry @titlepage @@ -199,7 +200,7 @@ the output from @kbd{M-x list-abbrevs} to make it look like this: @example (c-mode-abbrev-table) -"if" 0 "" c-if +"ifst" 0 "" c-if @end example @noindent @@ -231,8 +232,12 @@ Insert string or character. Literal strings and characters are passed through @code{skeleton-transformation} when that is non-@code{nil}. @item @code{?\n} @c ??? something seems very wrong here. -Insert a newline and align under current line. Use newline character -@code{?\n} to prevent alignment. +Insert a newline and align under current line, but not if this is the +last element of a skeleton and the newline would be inserted at end of +line, or this is the first element and the newline would be inserted +at beginning of line. Use newline character @code{?\n} to prevent +alignment. Use @code{"\n"} as the first or last string element of a +skeleton to insert a newline unconditionally. @item @code{_} Interesting point. When wrapping skeletons around successive regions, they are put at these places. Point is left at first @code{_} where nothing is wrapped. @@ -240,10 +245,10 @@ put at these places. Point is left at first @code{_} where nothing is wrapped. Indent line according to major mode. When following element is @code{_}, and there is a interregion that will be wrapped here, indent that interregion. @item @code{&} -Logical and. Iff preceding element moved point, i.e., usually inserted +Logical and. If preceding element moved point, i.e., usually inserted something, do following element. @item @code{|} -Logical xor. Iff preceding element didn't move point, i.e., usually inserted +Logical xor. If preceding element didn't move point, i.e., usually inserted nothing, do following element. @item @code{-@var{number}} Delete preceding number characters. Depends on value of @@ -301,7 +306,7 @@ of the same name as the command and can thus be overridden from your Various characters usually appear in pairs. When, for example, you insert an open parenthesis, no matter whether you are programming or writing prose, you will surely enter a closing one later. By entering both at the same time -and leaving the cursor inbetween, Emacs can guarantee you that such +and leaving the cursor in between, Emacs can guarantee you that such parentheses are always balanced. And if you have a non-qwerty keyboard, where typing some of the stranger programming language symbols makes you bend your fingers backwards, this can be quite relieving too. @@ -326,8 +331,9 @@ character is part of a word. If you want pairing to occur even then, set @vindex skeleton-pair-alist Pairing is possible for all visible characters. By default the parenthesis @samp{(}, the square bracket @samp{[}, the brace -@samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all -pair with the symmetrical character. All other characters pair +@samp{@{} and the pointed bracket @samp{<} all +pair with the symmetrical character, and the grave accent @samp{`} +pairs with the apostrophe @samp{'}. All other characters pair themselves. This behavior can be modified by the variable @code{skeleton-pair-alist}. This is in fact an alist of skeletons (@pxref{Skeleton Language}), with the first part of each sublist @@ -336,8 +342,8 @@ but since pairs don't need the @code{str} element, this is ignored. Some modes have bound the command @code{skeleton-pair-insert-maybe} to relevant keys. These modes also configure the pairs as -appropriate. For example, when typing english prose, you'd expect the -backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell +appropriate. For example, when typing @TeX{} input, you'd expect the +grave accent (@samp{`}) to pair with the apostrophe (@samp{'}), while in Shell script mode it must pair to itself. They can also inhibit pairing in certain contexts. For example an escaped character stands for itself. @@ -511,12 +517,6 @@ is only done with @kbd{M-x executable-set-magic}. When this is called as a function, such as when Emacs puts a buffer in Shell script mode. Otherwise you are always queried. -@findex executable-self-display - @kbd{M-x executable-self-display} adds a magic number to the buffer, which -will turn it into a self displaying text file, when called as a Un*x command. -The ``interpreter'' used is @code{executable-self-display} with argument -@samp{+2}. - @node Timestamps @chapter Maintaining Timestamps in Modified Files @cindex timestamps @@ -621,7 +621,7 @@ See the commentary in @file{tempo.el} for more information on using the Tempo package. @node Hippie Expand -@chapter `Hippie' Expansion +@chapter ``Hippie'' Expansion @findex hippie-expand @kindex M-/ diff --git a/doc/misc/bovine.texi b/doc/misc/bovine.texi index 81ec2eb80ec..ec11aa896ff 100644 --- a/doc/misc/bovine.texi +++ b/doc/misc/bovine.texi @@ -1,9 +1,10 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/bovine +@setfilename ../../info/bovine.info @set TITLE Bovine parser development @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE} +@include docstyle.texi @c ************************************************************************* @c @ Header @@ -23,13 +24,13 @@ @c %**end of header @copying -Copyright @copyright{} 1999--2004, 2012--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2004, 2012--2015 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,'' +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''. diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index b2b054ec1ea..8579d0f16f5 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -1,9 +1,10 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header (This is for running Texinfo on a region.) @c smallbook -@setfilename ../../info/calc +@setfilename ../../info/calc.info @c [title] @settitle GNU Emacs Calc Manual +@include docstyle.texi @setchapternewpage odd @comment %**end of header (This is for running Texinfo on a region.) @@ -11,9 +12,9 @@ @c The following macros are used for conditional output for single lines. @c @texline foo -@c `foo' will appear only in TeX output +@c 'foo' will appear only in TeX output @c @infoline foo -@c `foo' will appear only in non-TeX output +@c 'foo' will appear only in non-TeX output @c @expr{expr} will typeset an expression; @c $x$ in TeX, @samp{x} otherwise. @@ -94,14 +95,14 @@ This file documents Calc, the GNU Emacs calculator, included with GNU Emacs @value{EMACSVER}. @end ifnotinfo -Copyright @copyright{} 1990--1991, 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1990--1991, 2001--2015 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover +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.'' @@ -140,7 +141,7 @@ modify this GNU manual.'' @c [begin] @ifnottex @node Top, Getting Started, (dir), (dir) -@chapter The GNU Emacs Calculator +@top The GNU Emacs Calculator @noindent @dfn{Calc} is an advanced desk calculator and mathematical tool @@ -348,25 +349,12 @@ program by Donald Knuth at Stanford University) as well as the @file{texindex} program and @file{texinfo.tex} file, both of which can be obtained from the FSF as part of the @code{texinfo} package. To print the Calc manual in one huge tome, you will need the -source code to this manual, @file{calc.texi}, available as part of the -Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}. -Alternatively, change to the @file{man} subdirectory of the Emacs -source distribution, and type @kbd{make calc.dvi}. (Don't worry if you -get some ``overfull box'' warnings while @TeX{} runs.) -The result will be a device-independent output file called -@file{calc.dvi}, which you must print in whatever way is right -for your system. On many systems, the command is - -@example -lpr -d calc.dvi -@end example - -@noindent -or - -@example -dvips calc.dvi -@end example +Emacs source, which contains the source code to this manual, +@file{calc.texi}. Change to the @file{doc/misc} subdirectory of the +Emacs source distribution, which contains source code for this manual, +and type @kbd{make calc.pdf}. (Don't worry if you get some ``overfull +box'' warnings while @TeX{} runs.) The result will be this entire +manual as a pdf file. @end ifnottex @c Printed copies of this manual are also available from the Free Software @c Foundation. @@ -443,7 +431,7 @@ Type @kbd{2 @key{RET} 3 + Q} to compute @noindent Type @kbd{P 2 ^} to compute @texline @math{\pi^2 = 9.86960440109}. -@infoline the value of `pi' squared, 9.86960440109. +@infoline the value of @cpi{} squared, 9.86960440109. @noindent Type @key{TAB} to exchange the order of these two results. @@ -467,7 +455,7 @@ Type @kbd{' sqrt(2+3) @key{RET}} to compute @noindent Type @kbd{' pi^2 @key{RET}} to enter @texline @math{\pi^2}. -@infoline `pi' squared. +@infoline @cpi{} squared. To evaluate this symbolic formula as a number, type @kbd{=}. @noindent @@ -1215,9 +1203,7 @@ algebra system for microcomputers. Many people have contributed to Calc by reporting bugs and suggesting features, large and small. A few deserve special mention: Tim Peters, who helped develop the ideas that led to the selection commands, rewrite -rules, and many other algebra features; -@texline Fran\c{c}ois -@infoline Francois +rules, and many other algebra features; François Pinard, who contributed an early prototype of the Calc Summary appendix as well as providing valuable suggestions in many other areas of Calc; Carl Witty, whose eagle eyes discovered many typographical and factual @@ -1253,7 +1239,7 @@ finished in two weeks. @c [tutorial] @ifinfo -@c This node is accessed by the `C-x * t' command. +@c This node is accessed by the 'C-x * t' command. @node Interactive Tutorial, Tutorial, Getting Started, Top @chapter Tutorial @@ -2176,7 +2162,7 @@ the prefix. One more way to correct an error is by editing the stack entries. The actual Stack buffer is marked read-only and must not be edited -directly, but you can press @kbd{`} (the backquote or accent grave) +directly, but you can press @kbd{`} (grave accent) to edit a stack entry. Try entering @samp{3.141439} now. If this is supposed to represent @@ -2483,7 +2469,7 @@ We don't have enough space here to show all the zeros! They won't fit on a typical screen, either, so you will have to use horizontal scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the stack window left and right by half its width. Another way to view -something large is to press @kbd{`} (back-quote) to edit the top of +something large is to press @kbd{`} (grave accent) to edit the top of stack in a separate window. (Press @kbd{C-c C-c} when you are done.) You can enter non-decimal numbers using the @kbd{#} symbol, too. @@ -3670,7 +3656,7 @@ fast! (But of course if you use @kbd{t .} you will lose the ability to get old vectors back using the @kbd{t y} command.) An easy way to view a full vector when @kbd{v .} mode is active is -to press @kbd{`} (back-quote) to edit the vector; editing always works +to press @kbd{`} (grave accent) to edit the vector; editing always works with the full, unabbreviated value. @cindex Least-squares for fitting a straight line @@ -3959,7 +3945,7 @@ Next, let's add the line we got from our least-squares fit. @ifinfo (If you are reading this tutorial on-line while running Calc, typing @kbd{g a} may cause the tutorial to disappear from its window and be -replaced by a buffer named @samp{*Gnuplot Commands*}. The tutorial +replaced by a buffer named @file{*Gnuplot Commands*}. The tutorial will reappear when you terminate GNUPLOT by typing @kbd{g q}.) @end ifinfo @@ -6024,7 +6010,7 @@ fix, though: @end smallexample @noindent -When we type @kbd{Z `} (that's a back-quote character), Calc saves +When we type @kbd{Z `} (that's a grave accent), Calc saves its mode settings and the contents of the ten ``quick variables'' for later reference. When we type @kbd{Z '} (that's an apostrophe now), Calc restores those saved values. Thus the @kbd{p 4} and @@ -7230,9 +7216,7 @@ so that the mapping operation works; no prime factor will ever be zero, so adding zeros on the left and right is safe. From then on the job is pretty straightforward. -Incidentally, Calc provides the -@texline @dfn{M@"obius} @math{\mu} -@infoline @dfn{Moebius mu} +Incidentally, Calc provides the @dfn{Möbius μ} function which is zero if and only if its argument is square-free. It would be a much more convenient way to do the above test in practice. @@ -8110,7 +8094,7 @@ argument is exactly what we want to map over: @end smallexample @noindent -Et voil@`a, September 13, 1991 is a Friday. +Et voilà, September 13, 1991 is a Friday. @smallexample @group @@ -9054,7 +9038,7 @@ matrix (or other value) to the power @expr{n} in only @texline @math{\log_2 n} @infoline @expr{log(n,2)} steps. For example, this program can compute the 1000th Fibonacci -number (a 209-digit integer!) in about 10 steps; even though the +number (a 209-digit integer!)@: in about 10 steps; even though the @kbd{Z < ... Z >} solution had much simpler steps, it would have required so many steps that it would not have been practical. @@ -9616,8 +9600,8 @@ numeric entry, undo, numeric prefix arguments, etc. @cindex Starting the Calculator @cindex Running the Calculator To start the Calculator in its standard interface, type @kbd{M-x calc}. -By default this creates a pair of small windows, @samp{*Calculator*} -and @samp{*Calc Trail*}. The former displays the contents of the +By default this creates a pair of small windows, @file{*Calculator*} +and @file{*Calc Trail*}. The former displays the contents of the Calculator stack and is manipulated exclusively through Calc commands. It is possible (though not usually necessary) to create several Calc mode buffers each of which has an independent stack, undo list, and @@ -9625,7 +9609,7 @@ mode settings. There is exactly one Calc Trail buffer; it records a list of the results of all calculations that have been done. The Calc Trail buffer uses a variant of Calc mode, so Calculator commands still work when the trail buffer's window is selected. It is possible -to turn the trail window off, but the @samp{*Calc Trail*} buffer itself +to turn the trail window off, but the @file{*Calc Trail*} buffer itself still exists and is updated silently. @xref{Trail Commands}. @kindex C-x * c @@ -10041,7 +10025,7 @@ this would be to fix a typo, as the full Emacs cursor motion and editing keys are available during algebraic entry but not during numeric entry. In the same vein, during either numeric or algebraic entry you can -press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where +press @kbd{`} (grave accent) to switch to @code{calc-edit} mode, where you complete your half-finished entry in a separate buffer. @xref{Editing Stack Entries}. @@ -10149,10 +10133,10 @@ forget what it was, just run @code{C-x * q} again and enter @samp{$} as the formula. If this is the first time you have used the Calculator in this Emacs -session, the @kbd{C-x * q} command will create the @code{*Calculator*} +session, the @kbd{C-x * q} command will create the @file{*Calculator*} buffer and perform all the usual initializations; it simply will refrain from putting that buffer up in a new window. The Quick -Calculator refers to the @code{*Calculator*} buffer for all mode +Calculator refers to the @file{*Calculator*} buffer for all mode settings. Thus, for example, to set the precision that the Quick Calculator uses, simply run the full Calculator momentarily and use the regular @kbd{p} command. @@ -10167,9 +10151,10 @@ to yank the result into the next @kbd{C-x * q} input line as a more explicit alternative to @kbd{$} notation, or to yank the result into the Calculator stack after typing @kbd{C-x * c}. -If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead -of @key{RET}, the result is inserted immediately into the current -buffer rather than going into the kill ring. +If you give a prefix argument to @kbd{C-x * q} or finish your formula +by typing @key{LFD} (or @kbd{C-j}) instead of @key{RET}, the result is +inserted immediately into the current buffer rather than going into +the kill ring. Quick Calculator results are actually evaluated as if by the @kbd{=} key (which replaces variable names by their stored values, if any). @@ -10185,7 +10170,7 @@ an ASCII character. For example, the quoted character @samp{"x"} produces the vector result @samp{[120]} (because 120 is the ASCII code of the lower-case -`x'; @pxref{Strings}). Since this is a vector, not an integer, it +``x''; @pxref{Strings}). Since this is a vector, not an integer, it is displayed only according to the current mode settings. But running Quick Calc again and entering @samp{120} will produce the result @samp{120 (16#78, 8#170, x)} which shows the number in its @@ -10340,9 +10325,9 @@ that you must always press @kbd{w} yourself to see the messages). @pindex another-calc It is possible to have any number of Calc mode buffers at once. Usually this is done by executing @kbd{M-x another-calc}, which -is similar to @kbd{C-x * c} except that if a @samp{*Calculator*} +is similar to @kbd{C-x * c} except that if a @file{*Calculator*} buffer already exists, a new, independent one with a name of the -form @samp{*Calculator*<@var{n}>} is created. You can also use the +form @file{*Calculator*<@var{n}>} is created. You can also use the command @code{calc-mode} to put any buffer into Calculator mode, but this would ordinarily never be done. @@ -10357,7 +10342,7 @@ global default values of these variables are used only when a new Calculator buffer is created. The @code{calc-quit} command saves the stack and mode settings of the buffer being quit as the new defaults. -There is only one trail buffer, @samp{*Calc Trail*}, used by all +There is only one trail buffer, @file{*Calc Trail*}, used by all Calculator buffers. @node Troubleshooting Commands, , Multiple Calculators, Introduction @@ -11109,12 +11094,12 @@ noon GMT@.) Julian day numbering is largely used in astronomy. @cindex Unix time format The Unix operating system measures time as an integer number of seconds since midnight, Jan 1, 1970. To convert a Calc date -value into a Unix time stamp, first subtract 719164 (the code +value into a Unix time stamp, first subtract 719163 (the code for @samp{<Jan 1, 1970>}), then multiply by 86400 (the number of seconds in a day) and press @kbd{R} to round to the nearest integer. If you have a date form, you can simply subtract the day @samp{<Jan 1, 1970>} instead of unpacking and subtracting -719164. Likewise, divide by 86400 and add @samp{<Jan 1, 1970>} +719163. Likewise, divide by 86400 and add @samp{<Jan 1, 1970>} to convert from Unix time to a Calc date form. (Note that Unix normally maintains the time in the GMT time zone; you may need to subtract five hours to get New York time, or eight hours @@ -11801,6 +11786,18 @@ Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element, leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes the third stack element. +The above commands do not depend on the location of the cursor. +If the customizable variable @code{calc-context-sensitive-enter} is +non-@code{nil} (@pxref{Customizing Calc}), these commands will become +context sensitive. For example, instead of duplicating the top of the stack, +@key{RET} will copy the element at the cursor to the top of the +stack. With a positive numeric prefix, a copy of the element at the +cursor and the appropriate number of preceding elements will be placed +at the top of the stack. A negative prefix will still duplicate the +specified element of the stack regardless of the cursor position. +Similarly, @key{DEL} will remove the corresponding elements from the +stack. + @kindex @key{TAB} @pindex calc-roll-down To exchange the top two elements of the stack, press @key{TAB} @@ -11869,11 +11866,11 @@ the stack objects at the levels determined by the point and the mark. @pindex calc-edit-finish @cindex Editing the stack with Emacs The @kbd{`} (@code{calc-edit}) command creates a temporary buffer -(@samp{*Calc Edit*}) for editing the top-of-stack value using regular -Emacs commands. Note that @kbd{`} is a backquote, not a quote. With a -numeric prefix argument, it edits the specified number of stack entries -at once. (An argument of zero edits the entire stack; a negative -argument edits one specific stack entry.) +(@file{*Calc Edit*}) for editing the top-of-stack value using regular +Emacs commands. Note that @kbd{`} is a grave accent, not an apostrophe. +With a numeric prefix argument, it edits the specified number of stack +entries at once. (An argument of zero edits the entire stack; a +negative argument edits one specific stack entry.) When you are done editing, press @kbd{C-c C-c} to finish and return to Calc. The @key{RET} and @key{LFD} keys also work to finish most @@ -11882,9 +11879,9 @@ usual meaning (``insert a newline'') if it's a situation where you might want to insert new lines into the editing buffer. When you finish editing, the Calculator parses the lines of text in -the @samp{*Calc Edit*} buffer as numbers or formulas, replaces the +the @file{*Calc Edit*} buffer as numbers or formulas, replaces the original stack elements in the original buffer with these new values, -then kills the @samp{*Calc Edit*} buffer. The original Calculator buffer +then kills the @file{*Calc Edit*} buffer. The original Calculator buffer continues to exist during editing, but for best results you should be careful not to change it until you have finished the edit. You can also cancel the edit by killing the buffer with @kbd{C-x k}. @@ -11895,7 +11892,7 @@ For example, editing @samp{a + 2} to @samp{3 + 2} and pressing finish, Calc will put the result on the stack without evaluating it. If you give a prefix argument to @kbd{C-c C-c}, -Calc will not kill the @samp{*Calc Edit*} buffer. You can switch +Calc will not kill the @file{*Calc Edit*} buffer. You can switch back to that buffer and continue editing if you wish. However, you should understand that if you initiated the edit with @kbd{`}, the @kbd{C-c C-c} operation will be programmed to replace the top of the @@ -11905,13 +11902,13 @@ with other editing commands, though, such as @kbd{s e} (@code{calc-edit-variable}; @pxref{Operations on Variables}). If the @code{calc-edit} command involves more than one stack entry, -each line of the @samp{*Calc Edit*} buffer is interpreted as a +each line of the @file{*Calc Edit*} buffer is interpreted as a separate formula. Otherwise, the entire buffer is interpreted as one formula, with line breaks ignored. (You can use @kbd{C-o} or @kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.) The @kbd{`} key also works during numeric or algebraic entry. The -text entered so far is moved to the @code{*Calc Edit*} buffer for +text entered so far is moved to the @file{*Calc Edit*} buffer for more extensive editing than is convenient in the minibuffer. @node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail @@ -13608,11 +13605,11 @@ Weekday: ``Sunday'' for Sunday. @item Iww Week number: ISO 8601 week number, ``W01'' for week 1. @item d -Day of year: ``34'' for Feb. 3. +Day of year: ``34'' for Feb.@: 3. @item ddd -Day of year: ``034'' for Feb. 3. +Day of year: ``034'' for Feb.@: 3. @item bdd -Day of year: `` 34'' for Feb. 3. +Day of year: `` 34'' for Feb.@: 3. @item T Letter: Literal ``T''. @item h @@ -19227,7 +19224,7 @@ non-empty sets, respectively. The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on the top of the stack is prime. For integers less than eight million, the answer is always exact and reasonably fast. For larger integers, a -probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P). +probabilistic method is used (see Knuth vol.@: II, section 4.5.4, algorithm P). The number is first checked against small prime factors (up to 13). Then, any number of iterations of the algorithm are performed. Each step either discovers that the number is non-prime, or substantially increases the @@ -19303,9 +19300,7 @@ are relatively prime to @expr{n}. @pindex calc-moebius @tindex moebius The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the -@texline M@"obius @math{\mu} -@infoline Moebius ``mu'' -function. If the input number is a product of @expr{k} +Möbius μ function. If the input number is a product of @expr{k} distinct factors, this is @expr{(-1)^k}. If the input number has any duplicate factors (i.e., can be divided by the same prime more than once), the result is zero. @@ -20743,9 +20738,13 @@ mean, then repeating until the two values converge. $$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$ @end tex +@kindex u R @cindex Root-mean-square -Another commonly used mean, the RMS (root-mean-square), can be computed -for a vector of numbers simply by using the @kbd{A} command. +@tindex rms +The @kbd{u R} (@code{calc-vector-rms}) [@code{rms}] +command computes the RMS (root-mean-square) of the data values. +As its name suggests, this is the square root of the mean of the +squares of the data values. @kindex u S @pindex calc-vector-sdev @@ -21611,7 +21610,7 @@ to @noindent Every character not part of the sub-formula @samp{b} has been changed to a dot. (If the customizable variable -@code{calc-highlight-selections-with-faces} is non-nil, then the characters +@code{calc-highlight-selections-with-faces} is non-@code{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 @@ -21845,7 +21844,7 @@ by @samp{#} signs: @end group @end smallexample If the customizable variable -@code{calc-highlight-selections-with-faces} is non-nil, then the +@code{calc-highlight-selections-with-faces} is non-@code{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 @@ -23591,7 +23590,7 @@ of 3 is used. The lower this limit is, the greater the chance that Calc will be unable to integrate a function it could otherwise handle. Raising this limit allows the Calculator to solve more integrals, though the time it takes may grow exponentially. You can monitor the integrator's actions -by creating an Emacs buffer called @code{*Trace*}. If such a buffer +by creating an Emacs buffer called @file{*Trace*}. If such a buffer exists, the @kbd{a i} command will write a log of its actions there. If you want to manipulate integrals in a purely symbolic way, you can @@ -27640,17 +27639,17 @@ only during integration by @kbd{a i}. @subsection Debugging Rewrites @noindent -If a buffer named @samp{*Trace*} exists, the rewrite mechanism will +If a buffer named @file{*Trace*} exists, the rewrite mechanism will record some useful information there as it operates. The original formula is written there, as is the result of each successful rewrite, and the final result of the rewriting. All phase changes are also noted. -Calc always appends to @samp{*Trace*}. You must empty this buffer +Calc always appends to @file{*Trace*}. You must empty this buffer yourself periodically if it is in danger of growing unwieldy. Note that the rewriting mechanism is substantially slower when the -@samp{*Trace*} buffer exists, even if the buffer is not visible on +@file{*Trace*} buffer exists, even if the buffer is not visible on the screen. Once you are done, you will probably want to kill this buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in existence and forget about it, all your future rewrite commands will @@ -27697,9 +27696,7 @@ the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies @code{tri} to the value on the top of the stack. @xref{Programming}. @cindex Quaternions -The following rule set, contributed by -@texline Fran\c cois -@infoline Francois +The following rule set, contributed by François Pinard, implements @dfn{quaternions}, a generalization of the concept of complex numbers. Quaternions have four components, and are here represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y}, @@ -27859,14 +27856,20 @@ while typing @kbd{u c au/yr @key{RET}} produces If the units you request are inconsistent with the original units, the number will be converted into your units times whatever ``remainder'' -units are left over. (This can be disabled; @pxref{Customizing Calc}.) -For example, converting @samp{55 mph} into acres -produces @samp{6.08e-3 acre / m s}. (Recall that multiplication binds -more strongly than division in Calc formulas, so the units here are -acres per meter-second.) Remainder units are expressed in terms of +units are left over. For example, converting @samp{55 mph} into acres +produces @samp{6.08e-3 acre / (m s)}. Remainder units are expressed in terms of ``fundamental'' units like @samp{m} and @samp{s}, regardless of the input units. +@kindex u n +@pindex calc-convert-exact-units +If you intend that your new units be consistent with the original +units, the @kbd{u n} (@code{calc-convert-exact-units}) command will +check the units before the conversion. For example, to change +@samp{mi/hr} to @samp{km/hr}, you could type @kbd{u c km @key{RET}}, +but @kbd{u n km @key{RET}} would signal an error. +You would need to type @kbd{u n km/hr @key{RET}}. + One special exception is that if you specify a single unit name, and a compatible unit appears somewhere in the units expression, then that compatible unit will be converted to the new unit and the @@ -27973,7 +27976,7 @@ be considered a ``femto-ton,'' but it is written as @samp{1000 at} @kindex u v @pindex calc-enter-units-table The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table -in another buffer called @code{*Units Table*}. Each entry in this table +in another buffer called @file{*Units Table*}. Each entry in this table gives the unit name as it would appear in an expression, the definition of the unit in terms of simpler units, and a full name or description of the unit. Fundamental units are defined as themselves; these are the @@ -28040,8 +28043,8 @@ radiation related to the cesium-133 atom. The only SI unit that is not based on a fundamental physical process (although there are efforts to change this) is the kilogram, which was originally defined as the mass of one liter of water, but is now defined as the mass of the -International Prototype Kilogram (IPK), a cylinder of platinum-iridium -kept at the Bureau International des Poids et Mesures in S@`evres, +international prototype of the kilogram (IPK), a cylinder of platinum-iridium +kept at the Bureau international des poids et mesures in Sèvres, France. (There are several copies of the IPK throughout the world.) The British imperial units, once defined in terms of physical objects, were redefined in 1963 in terms of SI units. The US customary units, @@ -29254,7 +29257,7 @@ result is a surface plot where is the height of the point at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will be displayed from a certain default viewpoint; you can change this -viewpoint by adding a @samp{set view} to the @samp{*Gnuplot Commands*} +viewpoint by adding a @samp{set view} to the @file{*Gnuplot Commands*} buffer as described later. See the GNUPLOT documentation for a description of the @samp{set view} command. @@ -29317,7 +29320,7 @@ you give the @kbd{g p} command, all the curves will be drawn superimposed on the same axes. The @kbd{g a} command (and many others that affect the current graph) -will cause a special buffer, @samp{*Gnuplot Commands*}, to be displayed +will cause a special buffer, @file{*Gnuplot Commands*}, to be displayed in another window. This buffer is a template of the commands that will be sent to GNUPLOT when it is time to draw the graph. The first @kbd{g a} command adds a @code{plot} command to this buffer. Succeeding @@ -29328,7 +29331,7 @@ directly, but you can if you wish. The only constraint is that there must be only one @code{plot} command, and it must be the last command in the buffer. If you want to save and later restore a complete graph configuration, you can use regular Emacs commands to save and restore -the contents of the @samp{*Gnuplot Commands*} buffer. +the contents of the @file{*Gnuplot Commands*} buffer. @vindex PlotData1 @vindex PlotData2 @@ -29380,10 +29383,10 @@ separate ``z''s). With a zero prefix, it takes three stack entries but the ``z'' entry is a vector of curve values. With a negative prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}. The @kbd{g A} command works by adding a @code{splot} (surface-plot) -command to the @samp{*Gnuplot Commands*} buffer. +command to the @file{*Gnuplot Commands*} buffer. (Although @kbd{g a} adds a 2D @code{plot} command to the -@samp{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} +@file{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} before sending it to GNUPLOT if it notices that the data points are evaluating to @code{xyz} calls. It will not work to mix 2D and 3D @kbd{g a} curves in a single graph, although Calc does not currently @@ -29415,7 +29418,7 @@ affect the last curve in the list. @kindex g p @pindex calc-graph-plot The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw -the graph described in the @samp{*Gnuplot Commands*} buffer. Any +the graph described in the @file{*Gnuplot Commands*} buffer. Any GNUPLOT parameters which are not defined by commands in this buffer are reset to their default values. The variables named in the @code{plot} command are written to a temporary data file and the variable names @@ -29449,7 +29452,7 @@ the current graph is three-dimensional. The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p}, except that it sends the output to a printer instead of to the screen. More precisely, @kbd{g p} looks for @samp{set terminal} -or @samp{set output} commands in the @samp{*Gnuplot Commands*} buffer; +or @samp{set output} commands in the @file{*Gnuplot Commands*} buffer; lacking these it uses the default settings. However, @kbd{g P} ignores @samp{set terminal} and @samp{set output} commands and uses a different set of default values. All of these values are @@ -29468,7 +29471,7 @@ The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid'' on and off. It is off by default; tick marks appear only at the edges of the graph. With the grid turned on, dotted lines appear across the graph at each tick mark. Note that this command only -changes the setting in @samp{*Gnuplot Commands*}; to see the effects +changes the setting in @file{*Gnuplot Commands*}; to see the effects of the change you must give another @kbd{g p} command. @kindex g b @@ -29506,7 +29509,7 @@ time. This is usually more than adequate, but there are cases where it will not be. For example, plotting @expr{1 + x} with @expr{x} in the interval @samp{[0 ..@: 1e-6]} will round all the data points down to 1.0! Putting the command @samp{set precision @var{n}} in the -@samp{*Gnuplot Commands*} buffer will cause the data to be computed +@file{*Gnuplot Commands*} buffer will cause the data to be computed at precision @var{n} instead of 5. Since this is such a rare case, there is no keystroke-based command to set the precision. @@ -29521,9 +29524,9 @@ The default title is blank (no title). The @kbd{g n} (@code{calc-graph-name}) command sets the title of an individual curve. Like the other curve-manipulating commands, it affects the most recently added curve, i.e., the last curve on the -list in the @samp{*Gnuplot Commands*} buffer. To set the title of +list in the @file{*Gnuplot Commands*} buffer. To set the title of the other curves you must first juggle them to the end of the list -with @kbd{g j}, or edit the @samp{*Gnuplot Commands*} buffer by hand. +with @kbd{g j}, or edit the @file{*Gnuplot Commands*} buffer by hand. Curve titles appear in the key; if the key is turned off they are not used. @@ -29536,7 +29539,7 @@ The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T} and ``y'' axes, respectively. These titles appear next to the tick marks on the left and bottom edges of the graph, respectively. Calc does not have commands to control the tick marks themselves, -but you can edit them into the @samp{*Gnuplot Commands*} buffer if +but you can edit them into the @file{*Gnuplot Commands*} buffer if you wish. See the GNUPLOT documentation for details. @kindex g r @@ -29650,7 +29653,7 @@ value. The @code{dumb} device is an interface to ``dumb terminals,'' i.e., terminals with no special graphics facilities. It writes a crude picture of the graph composed of characters like @code{-} and @code{|} -to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays. +to a buffer called @file{*Gnuplot Trail*}, which Calc then displays. The graph is made the same size as the Emacs screen, which on most dumb terminals will be @texline @math{80\times24} @@ -29665,7 +29668,7 @@ spaces. These are the desired width and height of the graph in characters. Also, the device name @code{big} is like @code{dumb} but creates a graph four times the width and height of the Emacs screen. You will then have to scroll around to view the entire -graph. In the @samp{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, +graph. In the @file{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, @kbd{<}, and @kbd{>} are defined to scroll by one screenful in each of the four directions. @@ -29684,7 +29687,7 @@ used. Many other ``devices'' are really file formats like @code{postscript}; in these cases the output in the desired format goes into the file you name with @kbd{g O}. Type @kbd{g O stdout @key{RET}} to set GNUPLOT to write to its standard output stream, -i.e., to @samp{*Gnuplot Trail*}. This is the default setting. +i.e., to @file{*Gnuplot Trail*}. This is the default setting. Another special output name is @code{tty}, which means that GNUPLOT is going to write graphics commands directly to its standard output, @@ -29708,7 +29711,7 @@ permanently by the @kbd{m m} (@code{calc-save-modes}) command. The default number of data points (see @kbd{g N}) and the X geometry (see @kbd{g X}) are also saved. Other graph information is @emph{not} saved; you can save a graph's configuration simply by saving the contents -of the @samp{*Gnuplot Commands*} buffer. +of the @file{*Gnuplot Commands*} buffer. @vindex calc-gnuplot-plot-command @vindex calc-gnuplot-default-device @@ -29749,7 +29752,7 @@ Entering @samp{800x500+0+0} would create an 800-by-500 pixel window in the upper-left corner of the screen. This command has no effect if the current device is @code{windows}. -The buffer called @samp{*Gnuplot Trail*} holds a transcript of the +The buffer called @file{*Gnuplot Trail*} holds a transcript of the session with GNUPLOT@. This shows the commands Calc has ``typed'' to GNUPLOT and the responses it has received. Calc tries to notice when an error message has appeared here and display the buffer for you when @@ -29766,7 +29769,7 @@ usage of GNUPLOT. @pindex calc-graph-command The @kbd{g C} (@code{calc-graph-command}) command prompts you to enter any line of text, then simply sends that line to the current -GNUPLOT process. The @samp{*Gnuplot Trail*} buffer looks deceptively +GNUPLOT process. The @file{*Gnuplot Trail*} buffer looks deceptively like a Shell buffer but you can't type commands in it yourself. Instead, you must use @kbd{g C} for this purpose. @@ -29775,21 +29778,21 @@ Instead, you must use @kbd{g C} for this purpose. @pindex calc-graph-view-commands @pindex calc-graph-view-trail The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V} -(@code{calc-graph-view-trail}) commands display the @samp{*Gnuplot Commands*} -and @samp{*Gnuplot Trail*} buffers, respectively, in another window. +(@code{calc-graph-view-trail}) commands display the @file{*Gnuplot Commands*} +and @file{*Gnuplot Trail*} buffers, respectively, in another window. This happens automatically when Calc thinks there is something you will want to see in either of these buffers. If you type @kbd{g v} or @kbd{g V} when the relevant buffer is already displayed, the -buffer is hidden again. (Note that on MS-Windows, the @samp{*Gnuplot +buffer is hidden again. (Note that on MS-Windows, the @file{*Gnuplot Trail*} buffer will usually show nothing of interest, because GNUPLOT's responses are not communicated back to Calc.) One reason to use @kbd{g v} is to add your own commands to the -@samp{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use +@file{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use @kbd{C-x o} to switch into that window. For example, GNUPLOT has @samp{set label} and @samp{set arrow} commands that allow you to annotate your plots. Since Calc doesn't understand these commands, -you have to add them to the @samp{*Gnuplot Commands*} buffer +you have to add them to the @file{*Gnuplot Commands*} buffer yourself, then use @w{@kbd{g p}} to replot using these new commands. Note that your commands must appear @emph{before} the @code{plot} command. To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}. @@ -29813,7 +29816,7 @@ exit Emacs if you haven't killed it manually by then. @kindex g K @pindex calc-graph-kill The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q} -except that it also views the @samp{*Gnuplot Trail*} buffer so that +except that it also views the @file{*Gnuplot Trail*} buffer so that you can see the process being killed. This is better if you are killing GNUPLOT because you think it has gotten stuck. @@ -29900,6 +29903,19 @@ number in its displayed form, 3.142. (Since the default display modes show all objects to their full precision, this feature normally makes no difference.) +The @kbd{C-y} command can be given a prefix, which will interpret the +text being yanked with a different radix. If the text being yanked can be +interpreted as a binary, octal, hexadecimal, or decimal number, then a +prefix of @kbd{2}, @kbd{8}, @kbd{6} or @kbd{0} will have Calc +interpret the yanked text as a number in the appropriate base. For example, +if @samp{111} has just been killed and is yanked into Calc with a command +of @kbd{C-2 C-y}, then the number @samp{7} will be put on the stack. +If you use the plain prefix @kbd{C-u}, then you will be prompted for a +base to use, which can be any integer from 2 to 36. If Calc doesn't +allow the text being yanked to be read in a different base (such as if +the text is an algebraic expression), then the prefix will have no +effect. + @node Saving Into Registers, Inserting From Registers, Yanking Into Stack, Kill and Yank @section Saving into Registers @@ -30168,7 +30184,7 @@ trail all at once. This mode would normally be used when running Calc standalone (@pxref{Standalone Operation}). If you aren't using the X window system, you must switch into -the @samp{*Calc Keypad*} window, place the cursor on the desired +the @file{*Calc Keypad*} window, place the cursor on the desired ``key,'' and type @key{SPC} or @key{RET}. If you think this is easier than using Calc normally, go right ahead. @@ -31841,7 +31857,7 @@ local variables inside the macro should not affect any variables outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '} (@code{calc-kbd-pop}) commands give you both of these capabilities. -When you type @kbd{Z `} (with a backquote or accent grave character), +When you type @kbd{Z `} (with a grave accent), the values of various mode settings are saved away. The ten ``quick'' variables @code{q0} through @code{q9} are also saved. When you type @w{@kbd{Z '}} (with an apostrophe), these values are restored. @@ -32300,7 +32316,7 @@ after Calc itself is loaded. The properties of @code{calc-define} are evaluated in the same order that they were added. They can assume that the Calc modules @file{calc.el}, @file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and -that the @samp{*Calculator*} buffer will be the current buffer. +that the @file{*Calculator*} buffer will be the current buffer. If your @code{calc-define} property only defines algebraic functions, you can be sure that it will have been evaluated before Calc tries to @@ -32387,9 +32403,9 @@ the function with code that looks roughly like this: @end smallexample @findex calc-select-buffer -The @code{calc-select-buffer} function selects the @samp{*Calculator*} +The @code{calc-select-buffer} function selects the @file{*Calculator*} buffer if necessary, say, because the command was invoked from inside -the @samp{*Calc Trail*} window. +the @file{*Calc Trail*} window. @findex calc-set-command-flag You can call, for example, @code{(calc-set-command-flag 'no-align)} to @@ -32419,7 +32435,7 @@ Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag}, and @code{calc-keep-args-flag} at the end of this command. @item do-edit -Switch to buffer @samp{*Calc Edit*} after this command. +Switch to buffer @file{*Calc Edit*} after this command. @item hold-trail Do not move trail pointer to end of trail when something is recorded @@ -33141,7 +33157,7 @@ It is, of course, polite to put the Calc stack back the way you found it when you are done, unless the user of your program is actually expecting it to affect the stack. -Note that you do not actually have to switch into the @samp{*Calculator*} +Note that you do not actually have to switch into the @file{*Calculator*} buffer in order to use @code{calc-eval}; it temporarily switches into the stack buffer if necessary. @@ -33306,12 +33322,15 @@ Lisp integers. This is the only storage format for Calc data objects which is not a Lisp list. Large integers are stored as lists of the form @samp{(bigpos @var{d0} -@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or -@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers -@mathit{-1000000} or less. Each @var{d} is a base-1000 ``digit,'' a Lisp integer -from 0 to 999. The least significant digit is @var{d0}; the last digit, +@var{d1} @var{d2} @dots{})} for sufficiently large positive integers +(where ``sufficiently large'' depends on the machine), or +@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative +integers. Each @var{d} is a base-@expr{10^n} ``digit'' (where again, +@expr{n} depends on the machine), a Lisp integer from 0 to +99@dots{}9. The least significant digit is @var{d0}; the last digit, @var{dn}, which is always nonzero, is the most significant digit. For -example, the integer @mathit{-12345678} is stored as @samp{(bigneg 678 345 12)}. +example, the integer @mathit{-12345678} might be stored as +@samp{(bigneg 678 345 12)}. The distinction between small and large integers is entirely hidden from the user. In @code{defmath} definitions, the Lisp predicate @code{integerp} @@ -33673,7 +33692,7 @@ entries.) @end defun @defun calc-refresh -Erase the @code{*Calculator*} buffer and reformat its contents from memory. +Erase the @file{*Calculator*} buffer and reformat its contents from memory. This must be called after changing any parameter, such as the current display radix, which might change the appearance of existing stack entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing @@ -34274,7 +34293,7 @@ you can call it again with the same @var{n} to get a greater certainty; @defun to-simple-fraction f If @var{f} is a floating-point number which can be represented exactly -as a small rational number. return that number, else return @var{f}. +as a small rational number, return that number, else return @var{f}. For example, 0.75 would be converted to 3:4. This function is very fast. @end defun @@ -35680,17 +35699,14 @@ as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is of @code{calc-multiplication-has-precedence} is @code{t}. @end defvar -@defvar calc-ensure-consistent-units -When converting units, the variable @code{calc-ensure-consistent-units} -determines whether or not the target units need to be consistent with the -original units. If @code{calc-ensure-consistent-units} is @code{nil}, then -the target units don't need to have the same dimensions as the original units; -for example, converting @samp{100 ft/s} to @samp{m} will produce @samp{30.48 m/s}. -If @code{calc-ensure-consistent-units} is non-@code{nil}, then the target units -need to have the same dimensions as the original units; for example, converting -@samp{100 ft/s} to @samp{m} will result in an error, since @samp{ft/s} and @samp{m} -have different dimensions. The default value of @code{calc-ensure-consistent-units} -is @code{nil}. +@defvar calc-context-sensitive-enter +The commands @code{calc-enter} and @code{calc-pop} will typically +duplicate the top of the stack. If +@code{calc-context-sensitive-enter} is non-@code{nil}, then the +@code{calc-enter} will copy the element at the cursor to the +top of the stack and @code{calc-pop} will delete the element at the +cursor. The default value of @code{calc-context-sensitive-enter} is +@code{nil}. @end defvar @defvar calc-undo-length @@ -36483,6 +36499,7 @@ keystrokes are not listed in this summary. @r{ defn@: u d @:unit, descr @: @:calc-define-unit@:} @r{ @: u e @: @: @:calc-explain-units@:} @r{ @: u g @:unit @: @:calc-get-unit-definition@:} +@r{ @: u n @:units @: 18 @:calc-convert-exact-units@:} @r{ @: u p @: @: @:calc-permanent-units@:} @r{ a@: u r @: @: @:calc-remove-units@:} @r{ a@: u s @: @: @:usimplify@:(a)} @@ -36503,6 +36520,7 @@ keystrokes are not listed in this summary. @r{ v@: H u M @: @: 19 @:vmedian@:(v)} @r{ v@: I H u M @: @: 19 @:vhmean@:(v)} @r{ v@: u N @: @: 19 @:vmin@:(v)} +@r{ v@: u R @: @: @:rms@:(v)} @r{ v@: u S @: @: 19 @:vsdev@:(v)} @r{ v@: I u S @: @: 19 @:vpsdev@:(v)} @r{ v@: H u S @: @: 19 @:vvar@:(v)} @@ -36647,6 +36665,8 @@ keystrokes are not listed in this summary. @end format +@c Avoid '@:' from here on, as it now means \sumsep in tex mode. + @noindent NOTES @@ -36785,9 +36805,9 @@ The @expr{op} prompt can be answered with the key sequence for the desired function, or with @kbd{x} or @kbd{z} followed by a function name, or with @kbd{$} to take a formula from the top of the stack, or with @kbd{'} and a typed formula. In the last two cases, the formula may -be a nameless function like @samp{<#1+#2>} or @samp{<x, y : x+y>}, or it -may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the -last argument of the created function), or otherwise you will be +be a nameless function like @samp{<#1+#2>} or @samp{<x, y : x+y>}; or it +may include @kbd{$}, @kbd{$$}, etc., where @kbd{$} will correspond to the +last argument of the created function; or otherwise you will be prompted for an argument list. The number of vectors popped from the stack by @kbd{V M} depends on the number of arguments of the function. diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index c62d7026541..b93bc8f679f 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -81,13 +81,14 @@ the second with them pointing to the XEmacs manuals. @comment No overfull hbox marks in the dvi file. @finalout -@setfilename ../../info/ccmode +@setfilename ../../info/ccmode.info @settitle CC Mode Manual +@include docstyle.texi @footnotestyle end @c The following four macros generate the filenames and titles of the @c main (X)Emacs manual and the Elisp/Lispref manual. Leave the -@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it +@c Texinfo variable 'XEMACS' unset to generate a GNU Emacs version, set it @c to generate an XEmacs version, e.g., with @c "makeinfo -DXEMACS cc-mode.texi". @ifset XEMACS @@ -156,13 +157,13 @@ CC Mode @copying This manual is for CC Mode in Emacs. -Copyright @copyright{} 1995--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1995--2015 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'', +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''. @@ -176,7 +177,7 @@ modify this GNU manual.'' @dircategory Emacs editing modes @direntry * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, - Java, Pike, AWK, and CORBA IDL code. + Java, Pike, AWK, and CORBA IDL code. @end direntry @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -377,7 +378,7 @@ This manual describes @ccmode{} version 5.32. @comment Release.py script can update the version number automatically -@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, +@ccmode{} supports the editing of C, C++, Objective-C, Java, CORBA's Interface Definition Language, Pike@footnote{A C-like scripting language with its roots in the LPC language used in some MUD engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this @@ -750,12 +751,6 @@ very useful in this case. @end itemize @table @asis -@item @kbd{C-j} (@code{newline-and-indent}) -@kindex C-j -@findex newline-and-indent -Inserts a newline and indents the new blank line, ready to start -typing. This is a standard (X)Emacs command. - @item @kbd{C-M-q} (@code{c-indent-exp}) @kindex C-M-q @findex c-indent-exp @@ -1043,7 +1038,7 @@ Movement}. They might be removed from a future release of @ccmode{}. Since there's a lot of normal text in comments and string literals, @ccmode{} provides features to edit these like in text mode. The goal is to do it seamlessly, i.e., you can use auto fill mode, sentence and -paragraph movement, paragraph filling, adaptive filling etc. wherever +paragraph movement, paragraph filling, adaptive filling etc.@: wherever there's a piece of normal text without having to think much about it. @ccmode{} keeps the indentation, fixes suitable comment line prefixes, and so on. @@ -1161,7 +1156,7 @@ When this is enabled (which it normally is), indentation commands such as @kbd{C-j} indent lines of code according to their syntactic structure. Otherwise, a line is simply indented to the same level as the previous one and @kbd{@key{TAB}} adjusts the indentation in steps -of `c-basic-offset'. +of @code{c-basic-offset}. @end table Full details on how these minor modes work are at @ref{Electric Keys}, @@ -1172,7 +1167,7 @@ You can toggle each of these minor modes on and off, and you can configure @ccmode{} so that it starts up with your favorite combination of them (@pxref{Sample Init File}). By default, when you initialize a buffer, electric mode and syntactic-indentation mode -are enabled but the other two modes are disabled. +are enabled but the other three modes are disabled. @ccmode{} displays the current state of the first four of these minor modes on the modeline by appending letters to the major mode's name, @@ -2050,7 +2045,7 @@ conflict). The value may also be an association list to specify different comment styles for different languages. The symbol for the major mode is then looked up in the alist, and the value of that element is interpreted as -above if found. If it isn't found then the symbol `other' is looked up +above if found. If it isn't found then the symbol @code{other} is looked up and its value is used instead. The default value for @code{c-doc-comment-style} is @@ -3304,7 +3299,7 @@ only the symbol @code{after}, then the brace hangs on the right side of the line, as in: @example -// here, open braces always `hang' +// here, open braces always 'hang' void spam( int i ) @{ if( i == 7 ) @{ dosomething(i); @@ -3920,7 +3915,7 @@ Conceptually, a line of code is always indented relative to some position higher up in the buffer (typically the indentation of the previous line). That position is the @dfn{anchor position} in the syntactic element. If there is an entry after the syntactic symbol in -the syntactic element list then it's either nil or that anchor position. +the syntactic element list then it's either @code{nil} or that anchor position. Here is an example. Suppose we had the following code as the only thing in a C++ buffer @footnote{The line numbers in this and future examples @@ -3997,7 +3992,7 @@ Hitting @kbd{C-c C-s} on line 4 gives us: @cindex substatement block @noindent which tells us that this is a brace that @emph{opens} a substatement -block. @footnote{A @dfn{substatement} is the line after a +block.@footnote{A @dfn{substatement} is the line after a conditional statement, such as @code{if}, @code{else}, @code{while}, @code{do}, @code{switch}, etc. A @dfn{substatement block} is a brace block following one of these conditional statements.} @@ -4770,10 +4765,10 @@ covered are illustrated by this C++ example: 2: const 3: @{ 4: /* this line starts a multiline - 5: * comment. This line should get `c' syntax */ + 5: * comment. This line should get 'c' syntax */ 6: 7: char* a_multiline_string = "This line starts a multiline \ - 8: string. This line should get `string' syntax."; + 8: string. This line should get 'string' syntax."; 9: 10: note: 11: @{ @@ -6072,7 +6067,7 @@ suggestion to get a consistent style): @defun c-lineup-assignments @findex lineup-assignments (c-) Line up the current line after the assignment operator on the first line -in the statement. If there isn't any, return nil to allow stacking with +in the statement. If there isn't any, return @code{nil} to allow stacking with other line-up functions. If the current line contains an assignment operator too, try to align it with the first one. @@ -6537,7 +6532,7 @@ Return the syntactic symbol in @var{langelem}. @defun c-langelem-pos langelem @findex langelem-pos (c-) -Return the anchor position in @var{langelem}, or nil if there is none. +Return the anchor position in @var{langelem}, or @code{nil} if there is none. @end defun @defun c-langelem-col langelem &optional preserve-point @@ -7052,18 +7047,20 @@ Set the variable @code{c-basic-offset}. @xref{Getting Started}. @item @kindex RET @kindex C-j -@emph{Why doesn't the @kbd{RET} key indent the new line?} +@emph{Why does/doesn't the @kbd{RET} key indent the new line?} + +Emacs's convention used to be that @kbd{RET} just adds a newline, and that +@kbd{C-j} adds a newline and indents it. In Emacs-24.4, this convention was +reversed. -Emacs's convention is that @kbd{RET} just adds a newline, and that -@kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this -too by adding this to your @code{c-initialization-hook}: +If you use an older Emacs and you want @kbd{RET} do this +too, add this to your @code{c-initialization-hook}: @example (define-key c-mode-base-map "\C-m" 'c-context-line-break) @end example -@xref{Getting Started}. This is a very common question. If you want -this to be the default behavior, don't lobby us, lobby RMS@! @t{:-)} +@xref{Getting Started}. This was a very common question. @item @emph{How do I stop my code jumping all over the place when I type?} @@ -7143,7 +7140,7 @@ of XEmacs since 19.16. Due to release schedule skew, it is likely that all of these Emacsen have old versions of @ccmode{} and so should be upgraded. Access to the @ccmode{} source code, as well as more detailed information on Emacsen -compatibility, etc. are all available on the web site: +compatibility, etc.@: are all available on the web site: @quotation @uref{http://cc-mode.sourceforge.net/} @@ -7176,11 +7173,12 @@ configuration. In that case, we'd appreciate it if you isolate the Emacs Lisp code that triggers the bug and include it in your report. @cindex bug report mailing list -Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can -also send other questions and suggestions (kudos? @t{;-)} to that -address. It's a mailing list which you can join or browse an archive -of; see the web site at @uref{http://cc-mode.sourceforge.net/} for -further details. +Reporting a bug using @code{c-submit-bug-report} files it in +the GNU Bug Tracker at @url{http://debbugs.gnu.org}, then sends it on +to @email{bug-cc-mode@@gnu.org}. You can also send reports, other +questions, and suggestions (kudos?@: @t{;-)} to that address. It's a +mailing list which you can join or browse an archive of; see the web site at +@uref{http://cc-mode.sourceforge.net/} for further details. @cindex announcement mailing list If you want to get announcements of new @ccmode{} releases, send the diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 6dfc41d83f3..1f38ca98c62 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1,18 +1,19 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/cl +@setfilename ../../info/cl.info @settitle Common Lisp Extensions +@include docstyle.texi @include emacsver.texi @copying This file documents the GNU Emacs Common Lisp emulation package. -Copyright @copyright{} 1993, 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001--2015 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'', +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''. @@ -273,6 +274,8 @@ and the @code{cl-eval-when} construct. @node Argument Lists @section Argument Lists +@cindex &key +@cindex &aux @noindent Emacs Lisp's notation for argument lists of functions is a subset of @@ -293,6 +296,13 @@ list. Also, the function body is enclosed in an implicit block called @var{name}; @pxref{Blocks and Exits}. @end defmac +@defmac cl-iter-defun name arglist body@dots{} +This form is identical to the regular @code{iter-defun} form, except +that @var{arglist} is allowed to be a full Common Lisp argument +list. Also, the function body is enclosed in an implicit block +called @var{name}; @pxref{Blocks and Exits}. +@end defmac + @defmac cl-defsubst name arglist body@dots{} This is just like @code{cl-defun}, except that the function that is defined is automatically proclaimed @code{inline}, i.e., @@ -560,20 +570,20 @@ When @file{foo.el} is compiled, these variables will be set during the compilation itself: @example -foo1 foo3 foo5 foo7 ; `compile' +foo1 foo3 foo5 foo7 ; 'compile' @end example When @file{foo.elc} is loaded, these variables will be set: @example -foo2 foo3 foo6 foo7 ; `load' +foo2 foo3 foo6 foo7 ; 'load' @end example And if @file{foo.el} is loaded uncompiled, these variables will be set: @example -foo4 foo5 foo6 foo7 ; `eval' +foo4 foo5 foo6 foo7 ; 'eval' @end example If these seven @code{cl-eval-when}s had been, say, inside a @code{defun}, @@ -968,7 +978,7 @@ a The generalized variable @code{buffer-substring}, listed above, also works in this way by replacing a portion of the current buffer. -@c FIXME? Also `eq'? (see cl-lib.el) +@c FIXME? Also 'eq'? (see cl-lib.el) @c Currently commented out in cl.el. @ignore @@ -1279,13 +1289,8 @@ cells of symbols rather than on the value cells. Each @var{binding} must be a list of the form @samp{(@var{name} @var{arglist} @var{forms}@dots{})}, which defines a function exactly as if it were a @code{cl-defun} form. The function @var{name} is defined -accordingly for the duration of the body of the @code{cl-flet}; then -the old function definition, or lack thereof, is restored. - -You can use @code{cl-flet} to disable or modify the behavior of -functions (including Emacs primitives) in a temporary, localized fashion. -(Compare this with the idea of advising functions. -@xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.) +accordingly but only within the body of the @code{cl-flet}, hiding any external +definition if applicable. The bindings are lexical in scope. This means that all references to the named functions must appear physically within the body of the @@ -1493,7 +1498,7 @@ simply returning @code{nil}. @node Blocks and Exits @section Blocks and Exits -@cindex block +@cindex block @noindent Common Lisp @dfn{blocks} provide a non-local exit mechanism very @@ -1558,6 +1563,19 @@ Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose themselves in @code{nil} blocks. @end defmac +@c FIXME? Maybe this should be in a separate section? +@defmac cl-tagbody &rest labels-or-statements +This macro executes statements while allowing for control transfer to +user-defined labels. Each element of @var{labels-or-statements} can +be either a label (an integer or a symbol), or a cons-cell +(a statement). This distinction is made before macroexpansion. +Statements are executed in sequence, discarding any return value. +Any statement can transfer control at any time to the statements that follow +one of the labels with the special form @code{(go @var{label})}. +Labels have lexical scope and dynamic extent. +@end defmac + + @node Iteration @section Iteration @@ -2226,6 +2244,11 @@ This clause is like @code{always}, except that the loop returns This clause stops the loop when the specified form is non-@code{nil}; in this case, it returns that non-@code{nil} value. If all the values were @code{nil}, the loop returns @code{nil}. + +@item iter-by @var{iterator} +This clause iterates over the values from the specified form, an +iterator object. See (@pxref{Generators,,,elisp,GNU Emacs Lisp +Reference Manual}). @end table @node Accumulation Clauses @@ -2616,10 +2639,10 @@ In this package, @code{cl-locally} is no different from @code{progn}. @end defmac @defmac cl-the type form -Type information provided by @code{cl-the} is ignored in this package; -in other words, @code{(cl-the @var{type} @var{form})} is equivalent to -@var{form}. Future byte-compiler optimizations may make use of this -information. +@code{cl-the} returns the value of @code{form}, first checking (if +optimization settings permit) that it is of type @code{type}. Future +byte-compiler optimizations may also make use of this information to +improve runtime efficiency. For example, @code{mapcar} can map over both lists and arrays. It is hard for the compiler to expand @code{mapcar} into an in-line loop @@ -2854,14 +2877,8 @@ their names will not conflict with ``real'' variables in the user's code. (Internally, the variable @code{cl--gensym-counter} holds the counter -used to generate names. It is incremented after each use. In Common -Lisp this is initialized with 0, but this package initializes it with -a random time-dependent value to avoid trouble when two files that -each used @code{cl-gensym} in their compilation are loaded together. -Uninterned symbols become interned when the compiler writes them out -to a file and the Emacs loader loads them, so their names have to be -treated a bit more carefully than in Common Lisp where uninterned -symbols remain uninterned after loading.) +used to generate names. It is initialized with zero and incremented +after each use.) @end defun @defun cl-gentemp &optional x @@ -2918,6 +2935,12 @@ This predicate tests whether @var{integer} is even. It is an error if the argument is not an integer. @end defun +@defun cl-digit-char-p char radix +Test if @var{char} is a digit in the specified @var{radix} (default is +10). If true return the decimal value of digit @var{char} in +@var{radix}. +@end defun + @node Numerical Functions @section Numerical Functions @@ -3000,6 +3023,15 @@ This function returns the same value as the second return value of @code{cl-truncate}. @end defun +@defun cl-parse-integer string &key start end radix junk-allowed +This function implements the Common Lisp @code{parse-integer} +function. It parses an integer in the specified @var{radix} from the +substring of @var{string} between @var{start} and @var{end}. Any +leading and trailing whitespace chars are ignored. It signals an error +if the substring between @var{start} and @var{end} cannot be parsed as +an integer unless @var{junk-allowed} is non-nil. +@end defun + @node Random Numbers @section Random Numbers @@ -3668,10 +3700,8 @@ This function is a synonym for @code{(cdr @var{x})}. @end defun @defun cl-endp x -Common Lisp defines this function to act like @code{null}, but -signaling an error if @code{x} is neither a @code{nil} nor a -cons cell. This package simply defines @code{cl-endp} as a synonym -for @code{null}. +This function acts like @code{null}, but signals an error if @code{x} +is neither a @code{nil} nor a cons cell. @end defun @defun cl-list-length x @@ -4236,6 +4266,40 @@ of the included type and the first new slot. Except as noted, the @code{cl-defstruct} facility of this package is entirely compatible with that of Common Lisp. +The @code{cl-defstruct} package also provides a few structure +introspection functions. + +@defun cl-struct-sequence-type struct-type +This function returns the underlying data structure for +@code{struct-type}, which is a symbol. It returns @code{vector} or +@code{list}, or @code{nil} if @code{struct-type} is not actually a +structure. +@end defun + +@defun cl-struct-slot-info struct-type +This function returns a list of slot descriptors for structure +@code{struct-type}. Each entry in the list is @code{(name . opts)}, +where @code{name} is the name of the slot and @code{opts} is the list +of slot options given to @code{defstruct}. Dummy entries represent +the slots used for the struct name and that are skipped to implement +@code{:initial-offset}. +@end defun + +@defun cl-struct-slot-offset struct-type slot-name +Return the offset of slot @code{slot-name} in @code{struct-type}. The +returned zero-based slot index is relative to the start of the +structure data type and is adjusted for any structure name and +:initial-offset slots. Signal error if struct @code{struct-type} does +not contain @code{slot-name}. +@end defun + +@defun cl-struct-slot-value struct-type slot-name inst +Return the value of slot @code{slot-name} in @code{inst} of +@code{struct-type}. @code{struct} and @code{slot-name} are symbols. +@code{inst} is a structure instance. This routine is also a +@code{setf} place. Can signal the same errors as @code{cl-struct-slot-offset}. +@end defun + @node Assertions @chapter Assertions and Errors @@ -4404,12 +4468,11 @@ supposed to arise in complying programs; implementations are strongly encouraged but not required to signal an error in these situations. This package sometimes omits such error checking in the interest of compactness and efficiency. For example, @code{cl-do} variable -specifiers are supposed to be lists of one, two, or three forms; -extra forms are ignored by this package rather than signaling a -syntax error. The @code{cl-endp} function is simply a synonym for -@code{null} in this package. Functions taking keyword arguments -will accept an odd number of arguments, treating the trailing -keyword as if it were followed by the value @code{nil}. +specifiers are supposed to be lists of one, two, or three forms; extra +forms are ignored by this package rather than signaling a syntax +error. Functions taking keyword arguments will accept an odd number +of arguments, treating the trailing keyword as if it were followed by +the value @code{nil}. Argument lists (as processed by @code{cl-defun} and friends) @emph{are} checked rigorously except for the minor point just @@ -4474,10 +4537,7 @@ example, local @code{special} declarations, which are purely advisory in Emacs Lisp, do not rigorously obey the scoping rules set down in Steele's book. -The variable @code{cl--gensym-counter} starts out with a pseudo-random -value rather than with zero. This is to cope with the fact that -generated symbols become interned when they are written to and -loaded back from a file. +The variable @code{cl--gensym-counter} starts out with zero. The @code{cl-defstruct} facility is compatible, except that structures are of type @code{:type vector :named} by default rather than some @@ -4650,9 +4710,8 @@ exactly the same thing, so this package has not bothered to implement a Common Lisp-style @code{make-list}. @item -A few more notable Common Lisp features not included in this -package: @code{compiler-let}, @code{tagbody}, @code{prog}, -@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. +A few more notable Common Lisp features not included in this package: +@code{compiler-let}, @code{prog}, @code{ldb/dpb}, @code{cerror}. @item Recursion. While recursion works in Emacs Lisp just like it @@ -4858,7 +4917,7 @@ through the Lisp @code{message} function. For those cases where the dynamic scoping of @code{flet} is desired, @code{cl-flet} is clearly not a substitute. The most direct replacement would be instead to use @code{cl-letf} to temporarily rebind @code{(symbol-function -'@var{fun})}. But in most cases, a better substitute is to use an advice, such +'@var{fun})}. But in most cases, a better substitute is to use advice, such as: @example @@ -4874,7 +4933,7 @@ binding of @code{my-fun-advice-enable}. @c Bug#411. Note that many primitives (e.g., @code{+}) have special byte-compile handling. -Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or an +Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or advice will fail when byte-compiled. @c Or cl-flet. @c In such cases, use @code{labels} instead. diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 52c3c883cc8..5dd8bf21c13 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -1,7 +1,8 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/dbus +\input texinfo @c -*- coding: utf-8 -*- +@setfilename ../../info/dbus.info @c %**start of header @settitle Using of D-Bus +@include docstyle.texi @c @setchapternewpage odd @c %**end of header @@ -9,13 +10,13 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 2007--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2015 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'', +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''. @@ -29,6 +30,14 @@ modify this GNU manual.'' * D-Bus: (dbus). Using D-Bus in Emacs. @end direntry +@titlepage +@title Using D-Bus in Emacs +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + + @contents @@ -760,7 +769,7 @@ If there are no properties, @code{nil} is returned. Example: @end defun @defun dbus-get-all-managed-objects bus service path -This functions returns all objects at @var{bus}, @var{service}, +This function returns all objects at @var{bus}, @var{service}, @var{path}, and the children of @var{path}. The result is a list of objects. Every object is a cons of an existing path name, and the list of available interface objects. An interface object is another @@ -1051,11 +1060,11 @@ elements of this array. Example: "" ;; No icon. "Notification summary" ;; Summary. (format ;; Body. - "This is a test notification, raised from %s" (emacs-version)) + "This is a test notification, raised from\n%S" (emacs-version)) '(:array) ;; No actions (empty array of strings). '(:array :signature "@{sv@}") ;; No hints ;; (empty array of dictionary entries). - :int32 -1) ;; Default timeout. + :int32 -1) ;; Default timeout. @result{} 3 @end lisp @@ -1138,10 +1147,11 @@ The signal @code{PropertyModified}, discussed as example in (@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 +@defun dbus-byte-array-to-string byte-array &optional multibyte If a D-Bus method or signal returns an array of bytes, which are known to represent an UTF8 string, this function converts @var{byte-array} -to the corresponding string. Example: +to the corresponding string. The string is unibyte encoded, unless +@var{multibyte} is non-@code{nil}. Example: @lisp (dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115)) @@ -1151,20 +1161,30 @@ to the corresponding string. Example: @end defun @defun dbus-unescape-from-identifier string -Retrieve the original string from the encoded @var{string}. -@var{string} must have been coded with +Retrieve the original string from the encoded @var{string} as unibyte +string. @var{string} must have been encoded with @code{dbus-escape-as-identifier}. Example: @lisp (dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff") -@ifinfo -@result{} "0123abc_xyz^Aÿ" -@end ifinfo -@ifnotinfo -@result{} "0123abc_xyz^A@"y" -@end ifnotinfo +@result{} "0123abc_xyz\x01\xff" @end lisp + +If the original string used in @code{dbus-escape-as-identifier} is a +multibyte string, it cannot be expected that this function returns +that string: + +@lisp +(string-equal + (dbus-unescape-from-identifier + (dbus-escape-as-identifier "Grüß Göttin")) + "Grüß Göttin") + +@result{} nil +@end lisp + + @end defun diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 1e3d11f6dc6..e6370f3d80b 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -7,8 +7,9 @@ @c [Dodd's address no longer valid.] @comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/dired-x +@setfilename ../../info/dired-x.info @settitle Dired Extra User's Manual +@include docstyle.texi @include emacsver.texi @@ -19,14 +20,14 @@ @comment %**end of header (This is for running Texinfo on a region.) @copying -Copyright @copyright{} 1994--1995, 1999, 2001--2013 +Copyright @copyright{} 1994--1995, 1999, 2001--2015 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'', +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''. @@ -282,8 +283,8 @@ Marked files are never omitted. @end itemize @table @kbd -@item M-o -@kindex M-o +@item C-x M-o +@kindex C-x M-o @findex dired-omit-mode (@code{dired-omit-mode}) Toggle between displaying and omitting ``uninteresting'' files. @@ -323,7 +324,7 @@ Default: @code{nil} If non-@code{nil}, ``uninteresting'' files are not listed. Uninteresting files are those whose files whose names match regexp @code{dired-omit-files}, plus those ending with extensions in -@code{dired-omit-extensions}. @kbd{M-o} (@code{dired-omit-mode}) +@code{dired-omit-extensions}. @kbd{C-x M-o} (@code{dired-omit-mode}) toggles its value, which is buffer-local. Put @example @@ -332,8 +333,8 @@ toggles its value, which is buffer-local. Put @noindent inside your @code{dired-mode-hook} to have omitting initially turned on in -@emph{every} Dired buffer (@pxref{Installation}). You can then use @kbd{M-o} to -unomit in that buffer. +@emph{every} Dired buffer (@pxref{Installation}). You can then use +@kbd{C-x M-o} to unomit in that buffer. To enable omitting automatically only in certain directories you can add a directory local setting @@ -560,7 +561,7 @@ of marked files. @vindex dired-guess-shell-alist-default Predefined rules for shell commands. Set this to @code{nil} to turn guessing off. The elements of @code{dired-guess-shell-alist-user} (defined by the -user) will override these rules.@refill +user) will override these rules. @item dired-guess-shell-alist-user @vindex dired-guess-shell-alist-user @@ -568,7 +569,6 @@ If non-@code{nil}, a user-defined alist of file regexps and their suggested commands. These rules take precedence over the predefined rules in the variable @code{dired-guess-shell-alist-default} (to which they are prepended) when @code{dired-do-shell-command} is run). -@refill Each element of the alist looks like diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi index c7f3e3b1a61..74183a4d6a8 100644 --- a/doc/misc/ebrowse.texi +++ b/doc/misc/ebrowse.texi @@ -1,8 +1,9 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/ebrowse +@setfilename ../../info/ebrowse.info @settitle A Class Browser for C++ +@include docstyle.texi @setchapternewpage odd @syncodeindex fn cp @comment %**end of header @@ -10,13 +11,13 @@ @copying This file documents Ebrowse, a C++ class browser for GNU Emacs. -Copyright @copyright{} 2000--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2000--2015 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,'' +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''. @@ -138,7 +139,7 @@ list of the pseudo-class @samp{*Globals*}; @item Types (@code{enum}s, and @code{typedef}s defined with class -scope).@refill +scope). @end itemize You can switch member buffers from one list to another, or to another @@ -210,7 +211,7 @@ per line. @findex --help When invoked with option @samp{--help}, @command{ebrowse} prints a list of -available command line options.@refill +available command line options. @menu * Input files:: Specifying which files to parse @@ -474,16 +475,16 @@ You can view or find a class declaration when the cursor is on a class name. @table @kbd -@item SPC +@item @key{SPC} This command views the class declaration if the database contains information about it. If you don't parse the entire source you are working on, some classes will only be known to exist but the -location of their declarations and definitions will not be known.@refill +location of their declarations and definitions will not be known. -@item RET +@item @key{RET} Works like @kbd{SPC}, except that it finds the class declaration rather than viewing it, so that it is ready for -editing.@refill +editing. @end table The same functionality is available from the menu opened with @@ -494,7 +495,7 @@ The same functionality is available from the menu opened with @node Member Display @section Displaying Members -@cindex @samp{*Members*} buffer +@cindex @file{*Members*} buffer @cindex @samp{*Globals*} @cindex freezing a member buffer @cindex member lists, in tree buffers @@ -570,7 +571,7 @@ positions the cursor on the class in the class tree. If the branch of the class tree containing the class searched for is currently collapsed, the class itself and all its base classes are recursively made visible. (See also @ref{Expanding and -Collapsing}.)@refill +Collapsing}.) This function is also available from the tree buffer's context menu. @@ -634,7 +635,7 @@ Here is an example of a tree buffer with file names displayed. You can expand and collapse parts of a tree to reduce the complexity of large class hierarchies. Expanding or collapsing branches of a tree has no impact on the functionality of other commands, like @kbd{/}. (See -also @ref{Go to Class}.)@refill +also @ref{Go to Class}.) Collapsed branches are indicated with an ellipsis following the class name like in the example below. @@ -734,7 +735,7 @@ context menu. Classes can be marked for operations similar to the standard Emacs commands @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} (see -also @xref{Tags-like Functions}.)@refill +also @xref{Tags-like Functions}.) @table @kbd @cindex toggle mark @@ -875,7 +876,7 @@ context menu. @cindex declaration of a member, in member buffers @table @kbd -@item RET +@item @key{RET} This command finds the definition of the member the cursor is on. Finding involves roughly the same as the standard Emacs tags facility does---loading the file and searching for a regular expression matching @@ -884,7 +885,7 @@ the member. @item f This command finds the declaration of the member the cursor is on. -@item SPC +@item @key{SPC} This is the same command as @kbd{RET}, but views the member definition instead of finding the member's source file. @@ -972,7 +973,7 @@ displayed in the member buffer. @cindex @code{public} members @item F a u This command toggles the display of @code{public} members. The -@samp{a} stands for `access'. +@samp{a} stands for ``access''. @cindex @code{protected} members @item F a o @@ -1292,7 +1293,7 @@ When jumping to a member declaration or definition with one of Ebrowse's commands, the position from where you performed the jump and the position where you jumped to are recorded in a @dfn{position stack}. There are several ways in which you can quickly -move to positions in the stack:@refill +move to positions in the stack: @table @kbd @cindex return to original position diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index f2e787fd588..7a824acfed5 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1,18 +1,19 @@ \input texinfo -@setfilename ../../info/ede +@setfilename ../../info/ede.info @settitle Emacs Development Environment +@include docstyle.texi @copying This file describes EDE, the Emacs Development Environment. -Copyright @copyright{} 1998--2001, 2004--2005, 2008--2013 +Copyright @copyright{} 1998--2001, 2004--2005, 2008--2015 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,'' +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.'' @@ -30,6 +31,9 @@ modify this GNU manual.'' @center @titlefont{EDE (The Emacs Development Environment)} @sp 4 @center by Eric Ludlam +@page +@vskip 0pt plus 1filll +@insertcopying @end titlepage @page @@ -594,17 +598,6 @@ the format is an association list. For example: (compile-command . "make -f MyCustomMakefile all"))) @end example -The same is true when you use project-local variables with -@ref{ede-java-root}. For example: - -@example -(ede-java-root-project "SOMENAME" - :file "/dir/to/some/file" - :local-variables - '((grep-command . "grep -nHi -e ") - (compile-command . "ant"))) -@end example - @node EDE Project Features, , Project Local Variables, Modifying your project @section EDE Project Features @@ -720,12 +713,10 @@ To activate the speedbar in this mode, type @kbd{C-c . s} @menu * Make and Automake projects:: Project types of @samp{ede-project} * Automake direct projects:: Project interface on hand-written automake files. -* Android projects:: Projects for Android development -* Arduino projects:: Projects for Arduino sketches * Simple projects:: Projects @ede{} doesn't manage. @end menu -@node Make and Automake projects +@node Make and Automake projects, Automake direct projects, Miscellaneous commands, Miscellaneous commands @section Make and Automake projects A project of @samp{ede-project} type creates a file called @@ -737,7 +728,7 @@ in @samp{Makefile} mode, then this project will autogenerate a routines will also import and maintain a configure.am script and a host of other files required by Automake. -@node Automake direct projects +@node Automake direct projects, Simple projects, Make and Automake projects, Miscellaneous commands @section Automake direct projects The project type that reads @file{Makefile.am} directly is derived @@ -747,39 +738,7 @@ distributed independently. This mode eventually became @ede{}. The not generate them automatically, or create new ones. As such, it is useful as a browsing tool, or as maintenance in managing file lists. -@node Android projects -@section Android projects - -An Android project of type @samp{ede-android-project} will detect and -support development of Android apps. Android projects use an -@file{AndroidManifest.xml} file. Always load your Manifest first in a -running Emacs to make sure the project is identified correctly. - -Android projects can be created with @code{ede-new} but depend on a -correctly configured Android SDK via @cedet{} support. - -@defun cedet-android-sdk-root -@anchor{cedet-android-sdk-root} -The root to the android @var{SDK}. -@end defun - -Android projects support different configurations including compile, -and install, which will upload a program to your Android device. It -also supports several debugging tools via @file{android.el}. - -@node Arduino projects -@section Arduino projects - -An arduino project of type @samp{ede-arduino-project} will read your -@file{~/.arduino/preferences.txt} file, and identify your sketches. -You will still need the Arduino IDE to set up your preferences and -locate your arduino. After quitting the IDE, Emacs will be able to -find your sketches, compile them, and upload them to your arduino. - -If you have the @file{arduino} command on your path, @ede{} will be -able to find your SDK and compile your programs. - -@node Simple projects +@node Simple projects, , Automake direct projects, Miscellaneous commands @section Simple Projects There is a wide array of simple projects. In this case a simple @@ -791,14 +750,13 @@ belonging to a project, but doesn't provide many features of a typical @menu * ede-cpp-root:: This project marks the root of a C/C++ code project. -* ede-java-root:: This project marks the root of a Java project. * ede-emacs:: A project for working with Emacs. * ede-linux:: A project for working with Linux kernels. * ede-generic-project:: A project type for wrapping build systems with EDE. * Custom Locate:: Customizing how to locate files in a simple project @end menu -@node ede-cpp-root, ede-java-root, Simple projects, Simple projects +@node ede-cpp-root, ede-emacs, Simple projects, Simple projects @subsection ede-cpp-root The @code{ede-cpp-root} project type allows you to create a single @@ -834,6 +792,7 @@ override the default include path and system include path like this: (ede-cpp-root-project "NAME" :file "FILENAME" :include-path '( "/include" "../include" "/c/include" ) :system-include-path '( "/usr/include/c++/3.2.2/" ) + :compile-command "make compile" :spp-table '( ("MOOSE" . "") ("CONST" . "const") ) ) @end example @@ -851,6 +810,9 @@ The @code{:system-include-path} allows you to specify full directory names to include directories where system header files can be found. These will be applied to files in this project only. +With @code{:compile-command} you can provide a command which should be +run when calling @code{ede-compile-project}. + The @code{:spp-table} provides a list of project specific #define style macros that are unique to this project, passed in to the compiler on the command line, or are in special headers. @@ -906,7 +868,7 @@ It would look like this: (defun MY-ROOT-FCN () "Return the root fcn for `default-directory'" - ;; You might be able to use `ede-cpp-root-project-root' + ;; You might be able to use 'ede-cpp-root-project-root' ;; and not write this at all. ) @@ -935,90 +897,7 @@ of project. @xref{ede-cpp-root-project}, for details about the class that defines the @code{ede-cpp-root} project type. -@node ede-java-root, ede-emacs, ede-cpp-root, Simple projects -@subsection ede-java-root - -Much like the project type @ref{ede-cpp-root}, the java variant is -can be setup in your @file{.emacs} file and just marks a directory as -the root of a java source tree. - -The @code{ede-java-root} project class knows a few things about Java -projects. In particular, you can use it to control your classpath at -both the system level, and for your project. If it is insufficient, -you can subclass @code{ede-java-root-project} and add your own tweaks -in just a few lines. See @ref{ede-cpp-root} for an example using the -C++ variant. - -In the most basic case, add this to your @file{.emacs} file, modifying -appropriate bits as needed. - -@example -(ede-java-root-project "SOMENAME" :file "/dir/to/some/file" :srcroot '("src")) -@end example - -Replace @var{SOMENAME} with whatever name you want, and the filename -to an actual file at the root of your project. It might be a -Makefile, a README file. Whatever. It doesn't matter. It's just a -key to hang the rest of @ede{} off of. - -Replace the value of :srcroot with a list of directories under the -project root which contains Java sources. For example, if you have: - -@example -~/myprojects/P1/ -~/myprojects/P1/src/ -~/myprojects/P1/src/com/ericsoft/MyCode.java -~/myprojects/P1/doc/ -@end example - -Then @file{src} represents the directory under which all your Java -code is. It is important that @file{src} is one step above the -directory that is the base of your package name, such as -@file{com/ericsoft} in the example above so that new files can be -discovered via fully qualified name. You can have multiple such -directories in one project, and each will be accessible. - -You can specify your classpath like this: - -@example -(ede-java-root-project "NAME" :file "FILENAME" - :srcroot '("src") - :classpath '("/absolute/path.jar") - :localclasspath '( "/relative/path.jar" )) -@end example - -In this example, @code{:classpath} specifies absolute paths somewhere -on your system, and the explicit jar or source root directories -@semantic{} will search when performing completions. - -The @code{:localclasspath} is like @code{:classpath}, but it will -contain path names relative to the root of your project. - -If you want to override the file-finding tool with your own -function you can do this: - -@example -(ede-java-root-project "NAME" :file "FILENAME" :locate-fcn 'MYFCN) -@end example - -Where @var{MYFCN} is a symbol for a function. The locate function can -be used in place of @code{ede-expand-filename} so you can quickly -customize your custom target to use specialized local routines instead -of the default @ede{} routines. The function symbol must take two -arguments: - -@table @var -@item NAME -The name of the file to find. -@item DIR -The directory root for this java-root project. -@end table - -If you would like to create your Java projects dynamically, instead of -putting them all in your @file{.emacs}, you can do that too. See -@ref{ede-cpp-root} for details that can be applied to this project type. - -@node ede-emacs, ede-linux, ede-java-root, Simple projects +@node ede-emacs, ede-linux, ede-cpp-root, Simple projects @subsection ede-emacs The @code{ede-emacs} project automatically identifies an Emacs source @@ -1036,6 +915,12 @@ Kernel source tree, and enable EDE project mode for it. It pre-populates the C Preprocessor symbol map for reasonable parsing, and has an optimized include file identification function. +Through the variables @code{project-linux-build-directory-default} and +@code{project-linux-architecture-default}, you can set the build +directory and its architecture, respectively. The default is to assume that +the build happens in the source directory and to auto-detect the +architecture; if the auto-detection fails, you will be asked. + @node ede-generic-project, Custom Locate, ede-linux, Simple projects @subsection ede-generic-project @@ -1315,7 +1200,7 @@ until one of them returns true. The method from the autoload. If it is a string (i.e., a project file name), it checks to see if that exists in BUFFER's directory. If it is a function, then it calls that function and expects it to return a file -name or nil. If the file exists, then this directory is assumed to be +name or @code{nil}. If the file exists, then this directory is assumed to be part of a project, and @code{ede-directory-project-p} returns the instance of @code{ede-project-autoload} that matched. @@ -1390,11 +1275,11 @@ Return a string that is the name of the target used by a Make system. A brief description of the project or target. This is currently used by the @samp{ede-speedbar} interface. @item ede-want-file-p -Return non-nil if a target will accept a given file. +Return non-@code{nil} if a target will accept a given file. It is generally unnecessary to override this. See the section on source code. @item ede-buffer-mine -Return non-nil if a buffer belongs to this target. Used during +Return non-@code{nil} if a buffer belongs to this target. Used during association when a file is loaded. It is generally unnecessary to override this unless you keep auxiliary files. @end table @@ -1564,26 +1449,22 @@ Type: @code{string} @* Default Value: @code{"Untitled"} The name used when generating distribution files. -@refill @item :version Type: @code{string} @* Default Value: @code{"1.0"} The version number used when distributing files. -@refill @item :directory Type: @code{string} Directory this project is associated with. -@refill @item :file Type: @code{string} File name where this project is stored. -@refill @end table @@ -1656,35 +1537,30 @@ Make sure placeholder @var{THIS} is replaced with the real thing, and pass throu Type: @code{list} List of top level targets in this project. -@refill @item :tool-cache Type: @code{list} List of tool cache configurations in this project. This allows any tool to create, manage, and persist project-specific settings. -@refill @item :web-site-url Type: @code{string} @* URL to this projects web site. This is a URL to be sent to a web site for documentation. -@refill @item :web-site-directory @* A directory where web pages can be found by Emacs. For remote locations use a path compatible with ange-ftp or EFS@. You can also use TRAMP for use with rcp & scp. -@refill @item :web-site-file @* A file which contains the home page for this project. This file can be relative to slot @code{web-site-directory}. This can be a local file, use ange-ftp, EFS, or TRAMP. -@refill @item :ftp-site Type: @code{string} @* @@ -1692,7 +1568,6 @@ Type: @code{string} @* FTP site where this project's distribution can be found. This FTP site should be in Emacs form, as needed by @code{ange-ftp}, but can also be of a form used by TRAMP for use with scp, or rcp. -@refill @item :ftp-upload-site Type: @code{string} @* @@ -1700,7 +1575,6 @@ Type: @code{string} @* FTP Site to upload new distributions to. This FTP site should be in Emacs form as needed by @code{ange-ftp}. If this slot is @code{nil}, then use @code{ftp-site} instead. -@refill @item :configurations Type: @code{list} @* @@ -1709,19 +1583,16 @@ Default Value: @code{("debug" "release")} List of available configuration types. Individual target/project types can form associations between a configuration, and target specific elements such as build variables. -@refill @item :configuration-default @* Default Value: @code{"debug"} The default configuration. -@refill @item :local-variables @* Default Value: @code{nil} Project local variables -@refill @end table @@ -1743,7 +1614,7 @@ Provide a speedbar description for @var{OBJ}. @end deffn @deffn Method ede-map-any-target-p :AFTER this proc -For project @var{THIS}, map @var{PROC} to all targets and return if any non-nil. +For project @var{THIS}, map @var{PROC} to all targets and return if any non-@code{nil}. Return the first non-@code{nil} value returned by @var{PROC}. @end deffn @@ -1897,7 +1768,7 @@ If @var{TARGET} belongs to a subproject, return that project file. @end deffn @deffn Method ede-find-target :AFTER proj buffer -Fetch the target in @var{PROJ} belonging to @var{BUFFER} or nil. +Fetch the target in @var{PROJ} belonging to @var{BUFFER} or @code{nil}. @end deffn @deffn Method ede-add-subproject :AFTER proj-a proj-b @@ -1966,7 +1837,6 @@ buffer's @code{default-directory} (not starting with a /). Directories that are relative to the project's root should start with a /, such as "/include", meaning the directory @code{include} off the project root directory. -@refill @item :system-include-path Type: @code{list} @* @@ -1976,7 +1846,6 @@ The system include path for files in this project. C files initialized in an ede-cpp-root-project have their semantic system include path set to this value. If this is @code{nil}, then the semantic path is not modified. -@refill @item :spp-table Type: @code{list} @* @@ -1987,8 +1856,7 @@ Preprocessor symbols will be used while parsing your files. These macros might be passed in through the command line compiler, or are critical symbols derived from header files. Providing header files macro values through this slot improves accuracy and performance. -Use `:spp-files' to use these files directly. -@refill +Use @code{:spp-files} to use these files directly. @item :spp-files Type: @code{list} @* @@ -1998,14 +1866,12 @@ C header file with Preprocessor macros for your files. The PreProcessor symbols appearing in these files will be used while parsing files in this project. See @code{semantic-lex-c-preprocessor-symbol-map} for more on how this works. -@refill @item :header-match-regexp Type: @code{string} @* Default Value: @code{"\\.\\(h\\(h\\|xx\\|pp\\|\\+\\+\\)?\\|H\\)$\\|\\<\\w+$"} Regexp used to identify C/C++ header files. -@refill @item :locate-fcn Type: @code{(or null function)} @* @@ -2018,9 +1884,8 @@ The function symbol must take two arguments: NAME - The name of the file to find. DIR - The directory root for this cpp-root project. -It should return the fully qualified file name passed in from NAME@. If that file does not -exist, it should return nil. -@refill +It should return the fully qualified file name passed in from NAME@. +If that file does not exist, it should return @code{nil}. @end table @@ -2144,14 +2009,12 @@ The type of Makefile to generate. Can be one of @code{'Makefile}, 'Makefile.in, or 'Makefile.am. If this value is NOT @code{'Makefile}, then that overrides the @code{:makefile} slot in targets. -@refill @item :variables Type: @code{list} @* Default Value: @code{nil} Variables to set in this Makefile. -@refill @item :configuration-variables Type: @code{list} @* @@ -2159,27 +2022,23 @@ Default Value: @code{("debug" (("DEBUG" . "1")))} Makefile variables to use in different configurations. These variables are used in the makefile when a configuration becomes active. -@refill @item :inference-rules @* Default Value: @code{nil} Inference rules to add to the makefile. -@refill @item :include-file @* Default Value: @code{nil} Additional files to include. These files can contain additional rules, variables, and customizations. -@refill @item :automatic-dependencies Type: @code{boolean} @* Default Value: @code{t} Non-@code{nil} to do implement automatic dependencies in the Makefile. -@refill @item :metasubproject Type: @code{boolean} @* @@ -2188,9 +2047,8 @@ Default Value: @code{nil} Non-@code{nil} if this is a metasubproject. Usually, a subproject is determined by a parent project. If multiple top level projects are grouped into a large project not maintained by EDE, then you need -to set this to non-nil. The only effect is that the @code{dist} rule will then avoid +to set this to non-@code{nil}. The only effect is that the @code{dist} rule will then avoid making a tar file. -@refill @end table @@ -2380,7 +2238,6 @@ Type: @code{list} @* Default Value: @code{nil} Variables to set in this Makefile, at top of file. -@refill @item :additional-variables Type: @code{(or null list)} @* @@ -2388,7 +2245,6 @@ Default Value: @code{nil} Arbitrary variables needed from this project. It is safe to leave this blank. -@refill @item :additional-rules Type: @code{(or null list)} @* @@ -2396,7 +2252,6 @@ Default Value: @code{nil} Arbitrary rules and dependencies needed to make this target. It is safe to leave this blank. -@refill @item :installation-domain Type: @code{symbol} @* @@ -2404,7 +2259,6 @@ Default Value: @code{user} Installation domain specification. The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value. -@refill @item :preamble Type: @code{(or null list)} @* @@ -2412,7 +2266,6 @@ Default Value: @code{(quote ("GNUmakefile.preamble"))} The auxiliary makefile for additional variables. Included just before the specific target files. -@refill @item :postamble Type: @code{(or null list)} @* @@ -2420,7 +2273,6 @@ Default Value: @code{(quote ("GNUmakefile.postamble"))} The auxiliary makefile for additional rules. Included just after the specific target files. -@refill @item :metasubproject Type: @code{boolean} @* @@ -2429,9 +2281,8 @@ Default Value: @code{nil} Non-@code{nil} if this is a metasubproject. Usually, a subproject is determined by a parent project. If multiple top level projects are grouped into a large project not maintained by EDE, then you need -to set this to non-nil. The only effect is that the @code{dist} rule will then avoid +to set this to non-@code{nil}. The only effect is that the @code{dist} rule will then avoid making a tar file. -@refill @end table @@ -2536,21 +2387,18 @@ Commit change to local variables in @var{PROJ}. Type: @code{string} Name of this target. -@refill @item :path Type: @code{string} The path to the sources of this target. Relative to the path of the project it belongs to. -@refill @item :source Type: @code{list} @* Default Value: @code{nil} Source files in this target. -@refill @item :versionsource Type: @code{list} @* @@ -2560,7 +2408,6 @@ Source files with a version string in them. These files are checked for a version string whenever the EDE version of the master project is changed. When strings are found, the version previously there is updated. -@refill @end table @@ -2752,14 +2599,12 @@ Retrieves the slot @code{menu} from an object of class @code{ede-target} Type: @code{string} Name of this target. -@refill @item :path Type: @code{string} The path to the sources of this target. Relative to the path of the project it belongs to. -@refill @item :auxsource Type: @code{list} @* @@ -2768,7 +2613,6 @@ Default Value: @code{nil} Auxiliary source files included in this target. Each of these is considered equivalent to a source file, but it is not distributed, and each should have a corresponding rule to build it. -@refill @item :compiler Type: @code{(or null symbol)} @* @@ -2778,7 +2622,6 @@ The compiler to be used to compile this object. This should be a symbol, which contains the object defining the compiler. This enables save/restore to do so by name, permitting the sharing of these compiler resources, and global customization thereof. -@refill @item :linker Type: @code{(or null symbol)} @* @@ -2788,7 +2631,6 @@ The linker to be used to link compiled sources for this object. This should be a symbol, which contains the object defining the linker. This enables save/restore to do so by name, permitting the sharing of these linker resources, and global customization thereof. -@refill @end table @@ -2950,7 +2792,6 @@ Type: @code{string} @* Default Value: @code{"Makefile"} File name of generated Makefile. -@refill @item :partofall Type: @code{boolean} @* @@ -2958,8 +2799,7 @@ Default Value: @code{t} Non @code{nil} means the rule created is part of the all target. Setting this to @code{nil} creates the rule to build this item, but does not -include it in the ALL`all:' rule. -@refill +include it in the @code{all:} rule. @item :configuration-variables Type: @code{list} @* @@ -2969,7 +2809,6 @@ Makefile variables appended to use in different configurations. These variables are used in the makefile when a configuration becomes active. Target variables are always renamed such as foo_CFLAGS, then included into commands where the variable would usually appear. -@refill @item :rules Type: @code{list} @* @@ -2977,7 +2816,6 @@ Default Value: @code{nil} Arbitrary rules and dependencies needed to make this target. It is safe to leave this blank. -@refill @end table @@ -3221,7 +3059,6 @@ The linker flag "-l" is automatically prepended. Do not include a "lib" prefix, or a ".so" suffix. Note: Currently only used for Automake projects. -@refill @item :ldflags Type: @code{list} @* @@ -3232,7 +3069,6 @@ Use ldlibs to add addition libraries. Use this to specify specific options to the linker. Note: Not currently used. This bug needs to be fixed. -@refill @end table @@ -3358,7 +3194,6 @@ Additional packages needed. There should only be one toplevel package per auxiliary tool needed. These packages location is found, and added to the compile time load path. -@refill @end table @@ -3439,7 +3274,6 @@ Default Value: @code{"loaddefs.el"} The file that autoload definitions are placed in. There should be one load defs file for a given package. The load defs are created for all Emacs Lisp sources that exist in the directory of the created target. -@refill @item :autoload-dirs Type: @code{list} @* @@ -3447,7 +3281,6 @@ Default Value: @code{nil} The directories to scan for autoload definitions. If @code{nil} defaults to the current directory. -@refill @end table @@ -3547,7 +3380,6 @@ Default Value: @code{""} Miscellaneous sources which have a specialized makefile. The sub-makefile is used to build this target. -@refill @end table @@ -3604,7 +3436,6 @@ Default Value: @code{""} The main menu resides in this file. All other sources should be included independently. -@refill @end table @@ -3626,7 +3457,7 @@ Return the variable name for @var{THIS}'s sources. @deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this Insert any symbols that the DIST rule should depend on. -Texinfo files want to insert generated `.info' files. +Texinfo files want to insert generated @file{.info} files. Argument @var{THIS} is the target which needs to insert an info file. @end deffn @@ -3642,7 +3473,7 @@ files in the project. @deffn Method ede-proj-makefile-insert-dist-filepatterns :AFTER this Insert any symbols that the DIST rule should depend on. -Texinfo files want to insert generated `.info' files. +Texinfo files want to insert generated @file{.info} files. Argument @var{THIS} is the target which needs to insert an info file. @end deffn @@ -3687,7 +3518,6 @@ Type: @code{string} @* Default Value: @code{"guile"} The preferred interpreter for this code. -@refill @end table @@ -3817,7 +3647,6 @@ No children Default Value: @code{nil} Additional LD args. -@refill @end table @end table @@ -3949,7 +3778,6 @@ No children Default Value: @code{nil} Additional texinfo included in this one. -@refill @end table @end table @@ -4036,21 +3864,18 @@ Type: @code{eieio-instance-inheritor-child} The parent of this instance. If a slot of this class is reference, and is unbound, then the parent is checked for a value. -@refill @item :name Type: @code{string} The name of this type of source code. Such as "C" or "Emacs Lisp" -@refill @item :sourcepattern Type: @code{string} @* Default Value: @code{".*"} Emacs regex matching sourcecode this target accepts. -@refill @item :auxsourcepattern Type: @code{(or null string)} @* @@ -4059,7 +3884,6 @@ Default Value: @code{nil} Emacs regex matching auxiliary source code this target accepts. Aux source are source code files needed for compilation, which are not compiled themselves. -@refill @item :enable-subdirectories Type: @code{boolean} @* @@ -4069,7 +3893,6 @@ Non @code{nil} if this sourcecode type uses subdirectores. If sourcecode always lives near the target creating it, this should be nil. If sourcecode can, or typically lives in a subdirectory of the owning target, set this to t. -@refill @item :garbagepattern Type: @code{list} @* @@ -4078,7 +3901,6 @@ Default Value: @code{nil} Shell file regex matching files considered as garbage. This is a list of items added to an @code{rm} command when executing a @code{clean} type directive. -@refill @end table @@ -4158,13 +3980,11 @@ Type: @code{eieio-instance-inheritor-child} The parent of this instance. If a slot of this class is reference, and is unbound, then the parent is checked for a value. -@refill @item :name Type: @code{string} Name of this type of compiler. -@refill @item :variables Type: @code{list} @@ -4173,7 +3993,6 @@ Variables needed in the Makefile for this compiler. An assoc list where each element is (VARNAME . VALUE) where VARNAME is a string, and VALUE is either a string, or a list of strings. For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. -@refill @item :sourcetype Type: @code{list} @@ -4181,7 +4000,6 @@ Type: @code{list} A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. This is used to match target objects with the compilers and linkers they can use, and which files this object is interested in. -@refill @item :rules Type: @code{list} @* @@ -4189,7 +4007,6 @@ Default Value: @code{nil} Auxiliary rules needed for this compiler to run. For example, yacc/lex files need additional chain rules, or inferences. -@refill @item :commands Type: @code{list} @@ -4197,7 +4014,6 @@ Type: @code{list} The commands used to execute this compiler. The object which uses this compiler will place these commands after it's rule definition. -@refill @item :autoconf Type: @code{list} @* @@ -4208,14 +4024,12 @@ When a project is in Automake mode, this defines the autoconf function to call to initialize automake to use this compiler. For example, there may be multiple C compilers, but they all probably use the same autoconf form. -@refill @item :objectextention Type: @code{string} A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc. -@refill @end table @@ -4285,13 +4099,11 @@ Type: @code{eieio-instance-inheritor-child} The parent of this instance. If a slot of this class is reference, and is unbound, then the parent is checked for a value. -@refill @item :name Type: @code{string} Name of this type of compiler. -@refill @item :variables Type: @code{list} @@ -4300,7 +4112,6 @@ Variables needed in the Makefile for this compiler. An assoc list where each element is (VARNAME . VALUE) where VARNAME is a string, and VALUE is either a string, or a list of strings. For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. -@refill @item :sourcetype Type: @code{list} @@ -4308,7 +4119,6 @@ Type: @code{list} A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. This is used to match target objects with the compilers and linkers they can use, and which files this object is interested in. -@refill @item :commands Type: @code{list} @@ -4316,21 +4126,18 @@ Type: @code{list} The commands used to execute this compiler. The object which uses this compiler will place these commands after it's rule definition. -@refill @item :objectextention Type: @code{string} A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc. -@refill @item :makedepends Type: @code{boolean} @* Default Value: @code{nil} Non-@code{nil} if this compiler can make dependencies. -@refill @item :uselinker Type: @code{boolean} @* @@ -4339,7 +4146,6 @@ Default Value: @code{nil} Non-@code{nil} if this compiler creates code that can be linked. This requires that the containing target also define a list of available linkers that can be used. -@refill @end table @@ -4399,7 +4205,6 @@ Default Value: @code{t} Type: @code{list} A variable dedicated to dependency generation. -@refill @end table @end table @@ -4439,7 +4244,6 @@ No children Type: @code{string} Name of this type of compiler. -@refill @item :variables Type: @code{list} @@ -4448,7 +4252,6 @@ Variables needed in the Makefile for this compiler. An assoc list where each element is (VARNAME . VALUE) where VARNAME is a string, and VALUE is either a string, or a list of strings. For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. -@refill @item :sourcetype Type: @code{list} @@ -4456,7 +4259,6 @@ Type: @code{list} A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. This is used to match target objects with the compilers and linkers they can use, and which files this object is interested in. -@refill @item :commands Type: @code{list} @@ -4464,19 +4266,17 @@ Type: @code{list} The commands used to execute this compiler. The object which uses this compiler will place these commands after it's rule definition. -@refill @item :objectextention Type: @code{string} A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc. -@refill @end table @end table -@node GNU Free Documentation License, , Extending EDE, Top +@node GNU Free Documentation License, , Extending EDE, Top @appendix GNU Free Documentation License @include doclicense.texi diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 378eee08c51..f7876a336f6 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1,4 +1,4 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @c documentation for Ediff @c Written by Michael Kifer @@ -7,9 +7,10 @@ @comment Using ediff.info instead of ediff in setfilename breaks DOS. @comment @setfilename ediff @comment @setfilename ediff.info -@setfilename ../../info/ediff +@setfilename ../../info/ediff.info @settitle Ediff User's Manual +@include docstyle.texi @synindex vr cp @synindex fn cp @synindex pg cp @@ -25,13 +26,13 @@ This file documents Ediff, a comprehensive visual interface to Unix diff and patch utilities. -Copyright @copyright{} 1995--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1995--2015 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'', +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''. @@ -42,7 +43,8 @@ modify this GNU manual.'' @dircategory Emacs misc features @direntry -* Ediff: (ediff). A visual interface for comparing and merging programs. +* Ediff: (ediff). A visual interface for comparing and + merging programs. @end direntry @titlepage @@ -348,8 +350,7 @@ All the above functions use the POSIX @code{diff} or @code{diff3} programs to find differences between two files. They process the @code{diff} output and display it in a convenient form. At present, Ediff understands only the plain output from diff. Options such as @samp{-c} are not supported, -nor is the format produced by incompatible file comparison programs such as -the VMS version of @code{diff}. +nor is the format produced by incompatible file comparison programs. The functions @code{ediff-files}, @code{ediff-buffers}, @code{ediff-files3}, @code{ediff-buffers3} first display the coarse, @@ -555,9 +556,9 @@ Makes the next difference region current. @kindex j Makes the very first difference region current. -@kbd{-j} makes the last region current. Typing a number, N, and then `j' +@kbd{-j} makes the last region current. Typing a number, N, and then @kbd{j} makes the difference region N current. Typing @minus{}N (a negative number) then -`j' makes current the region Last @minus{} N. +@kbd{j} makes current the region Last @minus{} N. @item ga @kindex ga @@ -614,8 +615,8 @@ no longer current, due to user editing. @item m @kindex m Displays the current Ediff session in a frame as wide as the physical -display. This is useful when comparing files side-by-side. Typing `m' again -restores the original size of the frame. +display. This is useful when comparing files side-by-side. +Typing @kbd{m} again restores the original size of the frame. @item | @kindex | @@ -674,7 +675,7 @@ Tell Ediff to skip over regions that disagree among themselves only in the amount of white space and line breaks. Even though such regions will be skipped over, you can still jump to any -one of them by typing the region number and then `j'. Typing @kbd{##} +one of them by typing the region number and then @kbd{j}. Typing @kbd{##} again puts Ediff back in the original state. @item #c @@ -694,7 +695,8 @@ and @code{ediff-ignore-case}, which are explained elsewhere. Ediff works hard to ameliorate the effects of boredom in the workplace... Quite often differences are due to identical replacements (e.g., the word -`foo' is replaced with the word `bar' everywhere). If the number of regions +``foo'' is replaced with the word ``bar'' everywhere). If the number +of regions with such boring differences exceeds your tolerance threshold, you may be tempted to tell Ediff to skip these regions altogether (you will still be able to jump to them via the command @kbd{j}). The above commands, @kbd{#h} @@ -749,7 +751,7 @@ 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 lose -track of them completely... The `R' command is designed to save these +track of them completely... The @kbd{R} command is designed to save these people from the recently discovered Ediff Proficiency Syndrome.) Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff @@ -799,8 +801,8 @@ is that this difference region in buffer A is as old as that in the ancestor buffer, so the contents of that region in buffer B represents real change. -You may want to ignore such `obvious' merges and concentrate on difference -regions where both files `clash' with the ancestor, since this means that +You may want to ignore such ``obvious'' merges and concentrate on difference +regions where both files ``clash'' with the ancestor, since this means that two different people have been changing this region independently and they had different ideas on how to do this. @@ -817,10 +819,10 @@ precisely this. To be more precise, this toggles the check for whether the current merge is identical to its default setting, as originally decided by Ediff. For -instance, if Ediff is merging according to the `combined' policy, then the +instance, if Ediff is merging according to the ``combined'' policy, then the merge region is skipped over if it is different from the combination of the regions in buffers A and B@. (Warning: swapping buffers A and B will confuse -things in this respect.) If the merge region is marked as `prefer-A' then +things in this respect.) If the merge region is marked as ``prefer-A'' then this region will be skipped if it differs from the current difference region in buffer A, etc. @@ -850,7 +852,7 @@ corresponding region from buffer B. @item s @kindex s Causes the merge window shrink to its minimum size, thereby exposing as much -of the variant buffers as possible. Typing `s' again restores +of the variant buffers as possible. Typing @kbd{s} again restores the original size of that window. With a positive prefix argument, this command enlarges the merge window. @@ -1163,7 +1165,7 @@ customization and faces) can be done by putting appropriate lines in @file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use. With respect to the latter, please note that the X resource -for Ediff customization is `Ediff', @emph{not} `emacs'. +for Ediff customization is ``Ediff'', @emph{not} ``emacs''. @xref{Window and Frame Configuration}, @xref{Highlighting Difference Regions}, for further details. Please also refer to Emacs manual for the information on how to set Emacs X resources. @@ -1386,7 +1388,7 @@ different frames. Ediff respects these arrangements, automatically adapting itself to the multi-frame mode. Ediff uses the following variables to set up its control panel -(a.k.a.@: control buffer, a.k.a.@: quick help window): +(a.k.a.@: ``control buffer'', a.k.a.@: ``quick help window''): @table @code @item ediff-control-frame-parameters @@ -1509,7 +1511,7 @@ We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and @var{regexp-C}. Ediff will then start stepping through only those difference regions where the region in buffer A matches @var{regexp-A} and/or the region in -buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used +buffer B matches @var{regexp-B}, etc. Whether ``and'' or ``or'' will be used depends on how you respond to a question. When scanning difference regions for the aforesaid regular expressions, @@ -1887,10 +1889,11 @@ Otherwise, you may have to tune the values of the variables @item ediff-patch-options Options to pass to @code{ediff-patch-program}. -Note: the `-b' and `-z' options should be specified in -`ediff-backup-specs', not in @code{ediff-patch-options}. +Note: the @option{-b} and @option{-z} options should be specified in +@code{ediff-backup-specs}, not in @code{ediff-patch-options}. -It is recommended to pass the `-f' option to the patch program, so it won't +It is recommended to pass the @option{-f} option to the patch program, +so it won't ask questions. However, some implementations don't accept this option, in which case the default value of this variable should be changed. @@ -1900,19 +1903,23 @@ Backup extension used by the patch program. Must be specified, even if @item ediff-backup-specs Backup directives to pass to the patch program. Ediff requires that the old version of the file (before applying the patch) -is saved in a file named @file{the-patch-file.extension}. Usually -`extension' is `.orig', but this can be changed by the user, and may also be +is saved in a file named @file{the-patch-file.@var{extension}}. +Usually @var{extension} is @file{.orig}, but this can be changed by +the user, and may also be system-dependent. Therefore, Ediff needs to know the backup extension used by the patch program. -Some versions of the patch program let the user specify `-b backup-extension'. -Other versions only permit `-b', which (usually) assumes the extension `.orig'. -Yet others force you to use `-z<backup-extension>'. +Some versions of the patch program let the user specify @option{-b +@var{extension}} to specify a backup file name extension. Other +versions only permit @option{-b}, which (usually) assumes the +extension @file{.orig}. Yet others force you to use +@option{-z@var{extension}}. -Note that both `ediff-backup-extension' and `ediff-backup-specs' must be -properly set. If your patch program takes the option `-b', but not -`-b extension', the variable `ediff-backup-extension' must still -be set so Ediff will know which extension to use. +Both @code{ediff-backup-extension} and @var{ediff-backup-specs} must +be properly set. If your patch program takes the option @option{-b}, +but not @option{-b @var{extension}}, the variable +@code{ediff-backup-extension} must still be set so Ediff will know +which extension to use. @item ediff-custom-diff-program @itemx ediff-custom-diff-options @@ -1943,11 +1950,6 @@ Specifies the default directory to look for patches. @end table -@noindent -@strong{Warning:} Ediff does not support the output format of VMS -@code{diff}. Instead, make sure you are using some implementation of POSIX -@code{diff}, such as @code{gnudiff}. - @node Merging and diff3 @section Merging and diff3 @@ -2109,7 +2111,7 @@ typing @kbd{s}. This change is temporary, until Ediff finds a reason to redraw the screen. Typing @kbd{s} again restores the original window size. With a positive prefix argument, the @kbd{s} command will make the merge -window slightly taller. This change is persistent. With `@kbd{-}' or +window slightly taller. This change is persistent. With ``@kbd{-}'' or with a negative prefix argument, the command @kbd{s} makes the merge window slightly shorter. This change also persistent. @@ -2483,7 +2485,7 @@ Ray Nickson (nickson at cs.uq.oz.au), Dan Nicolaescu (dann at ics.uci.edu), David Petchey (petchey_david at jpmorgan.com), Benjamin Pierce (benjamin.pierce at cl.cam.ac.uk), -Francois Pinard (pinard at iro.umontreal.ca), +François Pinard (pinard at iro.umontreal.ca), Tibor Polgar (tlp00 at spg.amdahl.com), David Prince (dave0d at fegs.co.uk), Paul Raines (raines at slac.stanford.edu), diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi index 40aeae836ef..91f36e6c538 100644 --- a/doc/misc/edt.texi +++ b/doc/misc/edt.texi @@ -1,18 +1,19 @@ \input texinfo -@setfilename ../../info/edt +@setfilename ../../info/edt.info @settitle EDT Emulation for Emacs +@include docstyle.texi @copying This file documents the EDT emulation package for Emacs. -Copyright @copyright{} 1986, 1992, 1994--1995, 1999--2013 +Copyright @copyright{} 1986, 1992, 1994--1995, 1999--2015 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,'' +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''. @@ -90,7 +91,7 @@ initiate an Emacs session, by adding the following line to your @file{.emacs} file: @example -(add-hook term-setup-hook 'edt-emulation-on) +(add-hook 'emacs-startup-hook 'edt-emulation-on) @end example @noindent @strong{Important:} Be sure to read the rest of this manual. @@ -294,7 +295,7 @@ initiate an Emacs session, by adding the following line to your @file{.emacs} file: @example -(add-hook term-setup-hook 'edt-emulation-on) +(add-hook 'emacs-startup-hook 'edt-emulation-on) @end example A reference sheet is included (later on) listing the default EDT @@ -709,7 +710,7 @@ functions are bound to @key{F7}, @key{F8}, @kbd{GOLD-F8}, @key{F9}, @item The original EDT emulation package set up many default regular and GOLD -bindings. We tried to preserve most (but not all!) of these, so users +bindings. We tried to preserve most (but not all!)@: of these, so users of the original emulation package will feel more at home. Nevertheless, there are still many GOLD key sequences which are not diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi new file mode 100644 index 00000000000..28cf68048ae --- /dev/null +++ b/doc/misc/efaq-w32.texi @@ -0,0 +1,2305 @@ +\input texinfo @c -*-coding:utf-8 -*- +@setfilename ../../info/efaq-w32.info +@settitle GNU Emacs FAQ For MS Windows +@include docstyle.texi +@setchapternewpage odd +@syncodeindex pg cp +@syncodeindex ky cp +@syncodeindex tp cp +@syncodeindex vr fn + +@documentdescription +Answers to Frequently asked Questions about using Emacs on Microsoft Windows. +@end documentdescription + +@include emacsver.texi + +@copying +Copyright @copyright{} 2008, 2010-2015 Free Software Foundation, Inc. + +@quotation +This list of frequently asked questions about GNU Emacs on MS Windows +with answers (``FAQ'') may be translated into other languages, +transformed into other formats (e.g., Texinfo, Info, WWW), and updated +with new information. + +The same conditions apply to any derivative of the FAQ as apply to the FAQ +itself. Every copy of the FAQ must include this notice or an approved +translation, information on who is currently maintaining the FAQ and how to +contact them (including their e-mail address), and information on where the +latest version of the FAQ is archived (including FTP information). + +The FAQ may be copied and redistributed under these conditions, except that +the FAQ may not be embedded in a larger literary work unless that work +itself allows free copying and redistribution. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Emacs W32 FAQ: (efaq-w32). FAQs about Emacs on MS Windows. +@end direntry + +@c The @titlepage stuff only appears in the printed version +@titlepage +@sp 10 +@center @titlefont{GNU Emacs FAQ for MS Windows} + +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@footnotestyle end + +@node Top +@top GNU Emacs FAQ for MS Windows + +This is the FAQ for using GNU Emacs on MS Windows, as distributed with +Emacs @value{EMACSVER}. + +This FAQ is maintained by the developers and users of Emacs on MS Windows. +If you find any errors, or have any suggestions, please send them to +the @url{http://lists.gnu.org/mailman/listinfo/help-emacs-windows, +help-emacs-windows} mailing list. + +At time of writing, the latest version of GNU Emacs is version @value{EMACSVER}. + +@c Links to ftp.gnu.org are given as http links, since Windows ftp clients +@c are notoriously bad at handling firewalls etc. + +@ifnottex +@insertcopying +@end ifnottex + +@contents + +@menu +* Introduction:: +* Getting Emacs:: +* Installing Emacs:: +* Display Settings:: +* Fonts and text translation:: +* Printing:: +* Sub-processes:: +* Network access:: +* Text and Utility modes:: +* Developing with Emacs:: +* Other useful ports:: +* Further information:: +* Indexes:: +@end menu + +@c ------------------------------------------------------------ +@node Introduction +@chapter Introduction +@cindex scope of FAQ + +This FAQ covers questions that are specific to running GNU Emacs on Windows. +For more general information, see the other Emacs manuals. +@xref{Further information}. + +@menu +* Why Emacs on Windows:: +* Which versions of Windows:: +* Other versions of Emacs:: +@end menu + +@node Why Emacs on Windows +@section Why support GNU Emacs on Windows? +@cindex Why Windows + +It is not our goal to ``help Windows users'' by making text editing +on Windows more convenient. We aim to replace proprietary software, +not to enhance it. So why support GNU Emacs on Windows? + +We hope that the experience of using GNU Emacs on Windows will give +programmers a taste of freedom, and that this will later inspire them +to move to a free operating system such as GNU/Linux. That is the +main valid reason to support free applications on nonfree operating +systems. + +@node Which versions of Windows +@section Which versions of Windows are supported? +@cindex Windows, versions +@cindex supported versions of Windows + +Emacs @value{EMACSVER} is known to run on all versions of Windows from +Windows 98 and Windows NT 4.0 through to Windows 8.1. The Windows +port is built using the Win32 API and supports most features of the X +version, including variable width fonts, images and tooltips. + +Emacs on Windows can be compiled as either a 32-bit or a 64-bit +executable, using the MinGW GCC compiler and development tools. + +@node Other versions of Emacs +@section What other versions of Emacs run on Windows? +@cindex other ports of Emacs + +@xref{Cygwin}. + +@cindex DOS port +@cindex Windows 3.11 port +Emacs can also be compiled for MSDOS. When run on recent MS Windows, +it supports long file names, and uses the Windows clipboard. +See the @file{msdos} directory in the Emacs sources for building +instructions (requires DJGPP). + +@c ------------------------------------------------------------ +@node Getting Emacs +@chapter Getting Emacs + +@menu +* Downloading:: +* Compiling:: +* Debugging:: +@end menu + +@node Downloading +@section Where can I download Emacs? + +@cindex getting Emacs +@cindex where to get sources +@cindex Emacs source code +@cindex source for Emacs +You can download Emacs releases from +@uref{http://ftpmirror.gnu.org/emacs/, ftp.gnu.org mirrors}. They +are distributed as compressed tar files, digitally signed by the +maintainer who made the release. + +@cindex precompiled binaries +@cindex where to get Emacs binaries +Pre-compiled binaries for MS Windows may be made available on a +best-effort basis in the @file{windows} subdirectory of the above ftp +site (as zip files digitally signed by the person who built them). +See the @file{README} file in that directory for more information. +Building Emacs from source yourself should be straightforward, +following the instructions in @file{nt/INSTALL}, so we encourage you +to give it a try. @xref{Compiling}. + +@cindex latest development version of Emacs +@cindex Emacs Development +The development version of Emacs is available from +@uref{http://savannah.gnu.org/projects/emacs, Savannah}, the GNU +development site. + +@node Compiling +@section How can I compile Emacs myself? +@cindex compiling Emacs + +To compile Emacs on Windows, you will need the MinGW port of GCC and +Binutils, the MinGW runtime and development environment, and the MSYS +suite of tools. For the details, see the file @file{nt/INSTALL} in +the Emacs source distribution. + +Support for displaying images, as well as XML/HTML rendering and TLS +networking requires external libraries, the headers and import +libraries for which will need to be installed where your compiler can +find them. Again, the details, including URLs of sites where you can +download these libraries are in @file{nt/INSTALL}. @xref{Other useful +ports}, for auxiliary tools you may wish to install and use in +conjunction with Emacs. + +After unpacking the source, or checking out of the repository, be sure +to read the instructions in @file{nt/README} and @file{nt/INSTALL}. + +@node Debugging +@section How do I use a debugger on Emacs? +@cindex debugging Emacs +@cindex bugs in Emacs, how to debug +@cindex Emacs debugging + +By default, Emacs is compiled with debugging on, and optimizations enabled. +The optimizations may interfere with some types of debugging; the debugger +may not show clearly where it is, or may not be able to inspect certain +variables. If this is the case, reconfigure with @kbd{CFLAGS='-O0 -g3'} + +The file @file{etc/DEBUG} contains general debugging hints, as well as +specific notes about debugging Emacs. + +@cindex debugging Emacs with GDB +GDB is the GNU debugger, which can be used to debug Emacs when it has +been compiled with MinGW GCC. The best results will be obtained if +you start gdb from the @file{src} directory as @kbd{gdb ./emacs.exe}. +This will load the init file @file{.gdbinit}@footnote{ +Latest versions of GDB might refuse to load the init file for security +reasons, unless you customize GDB; alternatively, use an explicit +@kbd{source ./gdbinit} command after entering GDB. +} in that directory, to define some extra commands for working with +lisp while debugging, and set up breakpoints to catch abnormal +aborts. + +A Windows port of GDB can be found on MinGW download sites and on some +others. + +@c ------------------------------------------------------------ +@node Installing Emacs +@chapter Installing Emacs + +@menu +* Unpacking:: +* Installing binaries:: +* Image support:: +* Init file:: +* Location of init file:: +* Troubleshooting init file:: +* Associate files with Emacs:: +* Find-file and the Desktop:: +* Make Windows more like X:: +* Make Emacs like a Windows app:: +* Window operations:: +* Uninstall:: +* Does not run:: +* Virus:: +* Anti-virus:: +@end menu + +@node Unpacking +@section How do I unpack the distributions? +@cindex unpacking Emacs distribution +@cindex extracting Emacs distribution +@cindex unzipping Emacs distribution +@cindex untarring Emacs distribution +@cindex zip files, how to unpack Emacs binaries +@cindex tar.gz files, how to unpack Emacs sources + +The binary distributions are distributed as zip files, which are handled +natively by Windows XP and later. For earlier versions, there are many +tools that can handle the zip format, from InfoZip's command line unzip +tool, to 7zip's multi-format graphical archive explorer. (Although +popular, WinZip has caused problems with line-ends in the past, and is not +Free software, so we do not recommend it.) + +Source distributions are distributed as @file{.tar.gz} or +@file{.tar.xz} files. 7zip and similar multi-format graphical tools +can handle these, or you can get Windows ports of the command line +gzip and tar tools from multiple sources, or use @command{bsdtar}. +@xref{Other useful ports}. + +The command to unpack a source distribution from the command line is: + +@example +tar xzf emacs-@value{EMACSVER}.tar.gz +@end example + +If this does not work with the versions of tar and gzip that you have, +you may need to try a two step process: + +@example +gzip -dc emacs-@value{EMACSVER}.tar.gz | tar xf - +@end example + +You may see many messages from tar complaining about being unable to change +the modification time on directories, and from gzip complaining about a +broken pipe. These messages are usually harmless, caused by incomplete ports +that are not fully aware of the limitations of Windows. + +And here's an example of using @command{bsdtar} (from the +@samp{libarchive} package) to unpack a @file{.tar.xz} archive: + +@example +bsdtar -xf emacs-@value{EMACSVER}.tar.xz +@end example + +Expect @command{bsdtar} to unpack the whole distribution without any +complaints. + +Once you unpack the source distribution, look in @file{nt/INSTALL} +file for build instructions. + +@node Installing binaries +@section How do I install Emacs after unpacking the binary zip? +@cindex installing Emacs +@pindex addpm +@cindex Start Menu, creating icons for Emacs + +You can run Emacs without any extra steps, but if you want icons in your +Start Menu, or for Emacs to detect the image libraries that are already +installed on your system as part of GTK, then you should run the program +@file{addpm.exe}, which is usually installed into the same @file{bin} +directory with @file{emacs.exe}. + +@node Image support +@section How do I get image support? +@cindex images, installing libraries for +@cindex jpeg, installing image support in Emacs +@cindex png, installing image support in Emacs +@cindex gif, installing image support in Emacs +@cindex tiff, installing image support in Emacs +@cindex xpm, installing image support in Emacs +@cindex rsvg, installing image support in Emacs +@cindex toolbar, installing color icons in +@cindex color images, installing support for images in Emacs +@cindex monochrome images, getting color images in Emacs +@cindex black and white images, getting color images in Emacs + +Emacs has built in support for XBM and PBM/PGM/PPM images. This is +sufficient to see the monochrome splash screen and tool-bar icons. +Since v22.2, the official precompiled binaries for Windows have bundled +libXpm, which is required to display the color versions of those images. + +Emacs is compiled to recognize JPEG, PNG, GIF, TIFF, and RSVG images +also, but displaying these image types require external DLLs which are +not bundled with Emacs. @xref{Other useful ports}. + +@node Init file +@section What is my init file? +@cindex .emacs +@cindex init file + +When Emacs starts up, it attempts to load and execute the contents of +a file commonly called @file{.emacs} (though it may have other names, +@pxref{Location of init file,,Where do I put my init file?}) which +contains any customizations you have made. You can manually add lisp +code to your .emacs, or you can use the Customization interface +accessible from the @emph{Options} menu. If the file does not exist, +Emacs will start with the default settings. + +@node Location of init file +@section Where do I put my init file? +@cindex HOME directory +@cindex .emacs.d +@cindex _emacs +@cindex init.el +@cindex registry, setting the HOME directory in + +On Windows, the @file{.emacs} file may be called @file{_emacs} for +backward compatibility with DOS and FAT filesystems where filenames +could not start with a dot. Some users prefer to continue using such +a name due to historical problems various Windows tools had in the +past with file names that begin with a dot. In Emacs 22 and later, +the init file may also be called @file{.emacs.d/init.el}. Many of the +other files that are created by lisp packages are now stored in the +@file{.emacs.d} directory too, so this keeps all your Emacs related +files in one place. + +All the files mentioned above should go in your @env{HOME} directory. +The @env{HOME} directory is determined by following the steps below: + +@enumerate +@item +If the environment variable @env{HOME} is set, use the directory it indicates. +@item +If the registry entry @code{HKCU\SOFTWARE\GNU\Emacs\HOME} is set, use the +directory it indicates. +@item +If the registry entry @code{HKLM\SOFTWARE\GNU\Emacs\HOME} is set, use the +directory it indicates. Not recommended, as it results in users sharing +the same HOME directory. +@item +If @file{C:\.emacs} exists, then use @file{C:/}. This is for +backward compatibility, as previous versions defaulted to @file{C:/} +if @env{HOME} was not set. +@item +Use the user's AppData directory, usually a directory called +@file{AppData} under the user's profile directory, the location +of which varies according to Windows version and whether the computer is +part of a domain. +@end enumerate + +Within Emacs, @key{~} at the beginning of a file name is expanded to your +@env{HOME} directory, so you can always find your @file{.emacs} file +by typing the command @kbd{C-x C-f ~/.emacs}. + +@node Troubleshooting init file +@section Troubleshooting init file problems +@cindex troubleshooting init problems +@cindex debugging init problems +@cindex checking that HOME is set correctly + +If you've set @env{HOME} to a directory using one of the above +methods, and Emacs still doesn't load your init file, the first +thing you should do is check to see what Emacs thinks @env{HOME} is set +to. You can do this by evaluating the following expression in the +@file{*scratch*} buffer using @kbd{C-x C-e}: + +@example +(getenv "HOME") +@end example + +Look carefully at what is printed in the echo area, and make sure the +value is valid. For example, if the value has trailing whitespace, +Emacs won't be able to find the directory. Also, be sure that the +value isn't a relative drive letter (e.g., @file{d:} without a +backslash or a forward slash after the colon); if it is, then +@env{HOME} is going to be whatever the current directory on that drive +is, which is likely not what you want to happen. + +@node Associate files with Emacs +@section How do I associate files with Emacs? +@cindex Explorer, associating Emacs with files in +@cindex emacsclient, associating files with +@cindex file associations +@cindex associating files with Emacs +@cindex ALTERNATE_EDITOR +@findex server-start + +The recommended way to associate files is to associate them with +@command{emacsclientw.exe}. In order for this to work when Emacs is +not yet started, you will also need to set the environment variable +@env{ALTERNATE_EDITOR} to @command{runemacs.exe}. To open files +in a running instance of Emacs, you will need to add the following +to your init file: +@example +(server-start) +@end example + +@menu +* Using with Explorer:: +@end menu + +@node Using with Explorer +@subsection For use with Internet Explorer +@cindex Internet Explorer, view source in Emacs +@cindex mailto urls, associating with Emacs +@cindex news urls, associating with Emacs +@cindex URLs, associating mail and news URLs with Emacs + +You can use Emacs as the editor for composing mail for +@indicateurl{mailto:} links, reading usenet for @indicateurl{news:} +links, and viewing source. The following registry entries control +this: + +@itemize @w{} +@item +Mail +@itemize +@item @strong{Key:} HKCR\mailto\shell\open\command\(Default) +@item @strong{Value:} emacsclientw -e "(message-mail (substring \"%1\" 7))" +@end itemize + +@item +News +@itemize +@item @strong{Key:} HKCR\news\shell\open\command\(Default) +@item @strong{Value:} emacsclientw -e "(gnus-fetch-group (substring \"%1\" 5)" +@end itemize + +@item +View Source +@itemize +@item @strong{Key:} HKCR\htmlfile\shell\edit\command\(Default) +@item @strong{Value:} emacsclientw "%1" +@end itemize + +@end itemize + +Thanks to Jason Rumney and Sigbjorn Finne for these tips. + +@node Find-file and the Desktop +@section How do I use find-file to open files that are on the Desktop? +@cindex Desktop, finding where it is +@cindex finding the Desktop +@cindex locating files on the Desktop + +The location of the Desktop varies between different versions of +Windows, and in a corporate environment can be moved around by the +network administrator. On latest Windows versions, you can use the +value of the @env{USERPROFILE} environment variable to find where the +desktop might be: + +@example +@kbd{C-x C-f $USERPROFILE/Desktop} +@end example + +If this doesn't work, then you probably have to forgo the keyboard +just this once, and either drag a file onto the Emacs frame from the +desktop, or use the file dialog (displayed when you use the toolbar or +menu by default). Once you have a file from the Desktop inside Emacs, +@kbd{C-x C-f} will quickly reveal where your desktop is kept. + +@node Make Windows more like X +@section How can I modify Windows to act more like X? +@cindex X, making Windows behave like + +@menu +* Focus follows mouse:: +* Swap CapsLock and Control:: +@end menu + +@node Focus follows mouse +@subsection How do I make the active window follow the mouse? +@vindex focus-follows-mouse +@cindex point to focus +@cindex mouse over to focus + +Customize the variables @code{focus-follows-mouse} and +@code{mouse-autoselect-window}. The former can be used to mislead +Emacs into giving focus to other frames when the mouse is over them, +even though Windows has a click to focus policy by default (there is +software available to change that though). The latter can be used to +make Emacs use a focus-follow-mouse policy within its own frames. + +You can also change the Windows click-to-focus policy by changing +settings in the Registry. The details vary according to your Windows +version; look on the Internet for instructions to enable ``active +window tracking'' for your version of Windows. + +@node Swap CapsLock and Control +@subsection How do I swap CapsLock and Control? +@cindex scan codes, modifying +@cindex key layout, customizing +@cindex caps-lock, swapping with control key +@cindex control key, swapping with caps-lock +@cindex windows key, use as alt +@cindex alt key, using windows keys as additional + +This cannot be done within Emacs, but you can modify the scan code +mappings in the registry or define a new keyboard layout to swap the +keys on a system wide basis. + +@menu +* Swap Caps NT:: +* Swap Caps 98:: +@end menu + +@node Swap Caps NT +@subsubsection Windows NT/2000/XP/Vista? + +@itemize +@item +From Chris McMahon. To make CapsLock a Control key (leaving your +original control keys as they were), use this registry file: +@example +REGEDIT4 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Keyboard Layout] +"Scancode Map"=hex:00,00,00,00,00,00,00,00,02,00,00,00,1d,00,3a,00,00,00,00,00 +@end example +To swap CapsLock and the left Control key, use: +@example +REGEDIT4 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Keyboard Layout] +"Scancode Map"=hex:00,00,00,00,00,00,00,00,03,00,00,00,1d,00,3a,00,3a,00,1d,00,00,00,00,00 +@end example +Save these as files with a @file{.reg} extension, and double-click on +them in Explorer, or ``run'' them from a command prompt to have them +update your registry (you may need to reboot). +@item +Shane Holder gives some background on how "Scancode Map" is used +by the system: +@ignore +http://ftp.gnu.org/old-gnu/emacs/windows/docs/ntemacs/contrib/caps-ctrl-registry.txt +From: Shane Holder <holder@@mordor.rsn.hp.com> +To: ntemacs-users@@cs.washington.edu +Date: 04 Dec 1996 14:36:21 -0600 +Message-ID: <fawg21mm4hm.fsf@@mordor.rsn.hp.com> +Subject: Re: Re[2]: problem with caps/ctrl swap on NT 4.0 +@end ignore +@smallexample +It's a binary value that lets you map keystrokes in the low-level keyboard +drivers in NT. As a result you don't have to worry about applications +bypassing mappings that you've done at a higher level (i.e., it just works). + +Here's the format of the value: + + DWORD: 0x00000000 header + DWORD: 0x00000000 header + DWORD: length (in DWORDs) of remaining data, including terminating DWORD + DWORD: mapping 1 + ... + DWORD: mapping n + DWORD: 0x00000000 terminating null DWORD + +Each mapping DWORD has two parts: the input scancode, and an output +scancode. To map scancode 0x1d (left control) to scancode 0x3a (caps +lock), you want a value of 0x003a001d. Note that this does not swap the +keys. Using just this mapping value, both the left control and the caps +lock key will behave as caps-lock. To swap, you also need to map 0x3a to +0x1d, using 0x001d003a. + +This registry value is system wide, and can't be made user-specific. It +also only takes affect on reboot. +@end smallexample +@item +Ulfar Erlingsson has provided a registry file that sets the CapsLock key +to be a Control key and the Windows key to be an Alt key: +@example +REGEDIT4 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Keyboard Layout] +"Scancode Map"=hex:00,00,00,00,00,00,00,00,03,00,00,00,1d,00,3a,00,38,00,5b,e0,00,00,00,00 +@end example +@end itemize + +@node Swap Caps 98 +@subsubsection Windows 95/98/ME + +Microsoft has a tool called keyremap that is part of their Kernel Toys add ons +for Windows 95. The tool has also been confirmed to work on Windows 98. + +@node Make Emacs like a Windows app +@section How can I modify Emacs to act more like a Windows app? +@cindex Windows, making Emacs act more like +@cindex UI, making Emacs more like other Windows apps + +Many beginning users find Emacs difficult to use because its user +interface is different in many ways. Emacs predates most UI +standards, and experienced Emacs users are used to the way things are, +so changing the defaults is difficult. Most of the ``standard'' +behavior can be approximated in Emacs after some configuring though. + +@menu +* Highlight selection:: +* CUA:: +@end menu + +@node Highlight selection +@subsection Highlighting the selection +@cindex transient-mark-mode +@cindex selection, highlighting +@cindex region, highlighting +@cindex highlighting the selected region +@cindex marked region, highlighting +@cindex point and mark, highlighting the region between +@cindex delete-selection-mode +@cindex overwriting the selected region + +Emacs has a concept of a mark and point that is similar to selections +in other programs. But the mark in Emacs is used for more than just +defining the selected region, it lives on while you continue to edit +and move around the buffer so it can also be a kind of bookmark. The +history of marks is saved so you can pop previous marks back to the +top of the stack to go back to somewhere you were some time ago. +Because of this dual purpose, the region between mark and point is not +highlighted by default unless you select a region by clicking and +dragging the mouse. + +The minor mode @code{transient-mark-mode} changes the behavior of +the mark in two ways. First, it distinguishes between an active mark +that has just been defined or reactivated, and an inactive mark. When +the mark is active, some commands that normally act on lines, words, +buffers, etc., will instead act on the region. An inactive mark needs +to be reactivated to operate on it, unless @code{mark-even-if-inactive} +is set. Secondly, @code{transient-mark-mode} also highlights the +region when it is active, providing the same visual clue that you get +in other programs. This mode is turned on by default in latest +versions of Emacs. + +In addition to seeing the highlighting, new Emacs users often expect +editing commands to replace the region when it is active. This behavior +can be obtained with @code{delete-selection-mode}, but see the following +question also. + +@node CUA +@subsection Standard Windows key bindings +@findex cua-mode +@cindex CUA keybindings +@cindex shift key, selecting with +@cindex standard Windows keybindings +@cindex paste with C-v +@cindex cut with C-x +@cindex copy with C-c +@cindex C-c to copy +@cindex C-x to cut +@cindex C-v to paste + +The keybindings of Emacs predate modern GUIs, and the keys that were +chosen by later GUIs for cut and copy were given important functions +as extended keymaps in Emacs. CUA mode attempts to let both bindings +co-exist by defining C-x and C-c as @code{kill-region} and +@code{copy-region-as-kill} when the region is active, and letting +them have their normal Emacs bindings when the region is not active. +Many people find this to be an acceptable compromise. CUA mode also +defines a number of other keys (C-v, Shift selection), and can be turned +on from the @emph{Options} menu. + +@node Window operations +@section Window operations +@cindex maximize frames from lisp +@cindex minimize frames from lisp +@cindex WM_SYSCOMMAND, sending system commands from lisp +@cindex system menu, simulating from lisp + +The function @code{w32-send-sys-command} can be used to simulate +choosing commands from the system menu (in the top left corner of the +Window) and a few other system wide functions. It takes an integer +argument, the value of which should be a valid @code{WM_SYSCOMMAND} +message as documented in Microsoft's API documentation. + +@node Uninstall +@section How do I uninstall Emacs? +@cindex uninstall Emacs +@cindex remove Emacs +@cindex clean Emacs registry settings +@cindex registry, cleaning the Emacs settings +@cindex Start Menu, removing Emacs from +@cindex upgrading Emacs +@cindex delete Emacs directory + +Emacs does not come with an uninstall program. No files are installed +outside of the directories you find in the binary zip archive, so +deleting those directories is sufficient to clean away the files. If +you ran @command{addpm}, you'll need to delete the Start Menu group +too. The registry entries inserted by @command{addpm} will not cause +any problems if you leave them there, but for the sake of +completeness, you can use @command{regedit} to remove the keys under +@code{HKEY_LOCAL_MACHINE} or @code{HKEY_CURRENT_USER}: +@code{SOFTWARE\GNU\Emacs}, and the key +@code{HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App +Paths\emacs.exe} if it exists. + +@node Does not run +@section When I run Emacs nothing happens +@cindex troubleshooting installation problems +@cindex window not appearing, Emacs +@cindex failure to run, Emacs +@cindex 8.3 filenames, problems caused + +Emacs could have failed to run for a number of reasons. The most +common symptom is that, when Emacs is started, the cursor changes for +a second but nothing happens. If this happens to you, it is quite +likely that the distribution was unpacked incorrectly. + +Check for the following to see if there was a problem during unpacking: +@enumerate +@item +Be sure to disable the CR/LF translation or the executables will be +unusable. Older versions of WinZipNT would enable this translation by +default. If you are using WinZipNT, disable it. +@item +Check that filenames were not truncated to 8.3. For example, there +should be a file CONTRIBUTE in the top level directory; if this has +been truncated to CONTRIBU or CONTRI~1, your distribution has been +corrupted while unpacking and Emacs will not start. +@end enumerate + +If it is still not working, send mail to the +@email{help-gnu-emacs@@gnu.org} mailing list, describing what you've +done, and what you are seeing. (The more information you send the more +likely it is that you'll receive a helpful response.) + +@node Virus +@section Does Emacs contain a virus? +@cindex virus reported in Emacs +@cindex anti-virus software reporting a virus in Emacs + +There have been reports in the past that some virus scanners claim +that the Emacs distribution has a virus. This is extremely unlikely if +you have downloaded Emacs from the GNU FTP site or one of its mirrors +and the GPG signature for it is valid and listed in the GNU keyring, +unless perhaps it is a new release made in the last few days, in which +case you should exercise more caution and report the problem. Past +problems seem to have been caused by virus checkers running into a +buffer size limit when unpacking large tar.gz files for scanning, and +reporting the failure as an ``unknown virus''. + +@node Anti-virus +@section What known problems are there with anti-virus software? +@cindex anti-virus software, bad interaction with +@cindex virus software, bad interaction with +@cindex firewall, bad interaction with +@cindex scan all files, anti-virus option causing problems +@cindex auto protect, anti-virus option causing problems +@cindex shell, interacting badly with anti-virus +@cindex subprocesses, interacting badly with anti-virus + +Anti-virus and firewall software can block Emacs from starting subprocesses +and opening network connections. Most such products have an Advanced +mode where they will prompt you rather than silently blocking. In some cases +the ``scan all files'' or ``auto protect'' option of anti-virus programs +has caused failures running shell related commands within Emacs. +@xref{Sub-processes,,Why is nothing happening when I enter shell commands?}. + +@c ------------------------------------------------------------ +@node Display Settings +@chapter Display Settings + +@menu +* Console window size:: +* Mouse trouble:: +* Cut and paste NUL:: +* Garbled clipboard:: +* Beep sound:: +@end menu + +@node Console window size +@section Emacs in console mode goes beyond the window size +@cindex console, window size +@cindex telnet, display size problems running emacs over +@cindex -nw, window size +@vindex w32-use-full-screen-buffer + +The variable @code{w32-use-full-screen-buffer} controls whether Emacs uses +the window size or buffer size to determine the number of lines on screen. +Normally the window size is correct, but when running Emacs over some +telnet servers, the buffer size needs to be used. Emacs tries to guess +the correct value at startup, but if it guesses wrong, you can customize +that variable yourself. + +@node Mouse trouble +@section What do I do if I have problems with my mouse buttons? +@cindex mouse buttons, problems with +@cindex 2 button mouse +@cindex two button mouse +@cindex third mouse button, simulating +@cindex middle mouse button, simulating +@cindex simulating three button mouse with two buttons +@cindex swap right and middle mouse buttons +@cindex exchange mouse-2 and mouse-3 buttons +@vindex w32-mouse-button-tolerance +@vindex w32-num-mouse-buttons +@vindex w32-swap-mouse-buttons + +Emacs assigns bindings assuming a three button mouse. On Windows, if +a two button mouse is detected, a hack is enabled which lets you +simulate the third button by pressing both mouse buttons +simultaneously. @code{w32-mouse-button-tolerance} defines the timeout +for what is considered ``simultaneous''. You can check how many +buttons Emacs thinks your mouse has with @kbd{C-h v} +@code{w32-num-mouse-buttons}. + +If you find yourself needing the mouse-3 bindings more often than mouse-2, +you can swap the buttons with the following code in your init file: +@example +(setq w32-swap-mouse-buttons t) +@end example + +@node Cut and paste NUL +@section How do I cut and paste text with NUL characters? +@cindex clipboard, NUL characters + +If you attempt to cut and paste text with NUL characters embedded in it, +then the text will be truncated at the first NUL character. This is a +limitation of the Windows clipboard, and does not affect killing and yanking +from the kill-ring within Emacs. + +@node Garbled clipboard +@section How can I fix garbled text yanked from the clipboard? +@cindex clipboard, corruption of +@cindex garbage on the clipboard +@cindex clipboard encoding +@cindex encoding, clipboard +@findex set-selection-coding-system + +You can try @code{set-selection-coding-system}, but generally such +corruption is a thing of the past, as Emacs uses Unicode for the clipboard +by default now. + +@node Beep sound +@section How do I change the sound of the Emacs beep? +@cindex beep, changing the sound +@cindex sound, changing the beep +@findex set-message-beep + +You can use the function @code{set-message-beep} to change the sound +that Emacs uses for its beep. This affects both console and GUI frames. +The doc string contains a list of the system sounds you can use. + +@c ------------------------------------------------------------ +@node Fonts and text translation +@chapter Fonts and text translation + +@menu +* Font names:: +* Bold and italic:: +* Multilingual fonts:: +* Font menu:: +* Line ends:: +@end menu + +@node Font names +@section Font names +@cindex XLFD font names +@cindex font XLFD name format +@cindex fontconfig font names in Emacs 23 +@cindex font dialog, using to find font names +@findex w32-select-font +@findex x-list-fonts + +Fonts in Emacs 22 and earlier are named using the X Logical Font +Description (XLFD) format. Emacs on Windows ignores many of the +fields, and populates them with * when listing fonts. Former +maintainer Andrew Innes wrote +@uref{http://www.gnu.org/software/emacs/windows/ntemacs/discuss/x-font-details, +this explanation} of what each field in the font string means and how +Emacs treated them back in 19.34. Since then, multilingual support and +a redisplay overhaul to support variable width fonts have changed things +slightly; more character sets are recognized (and the old pseudo character +sets are deprecated), and the resolution fields are used to calculate the +difference between point and pixel sizes, but normally you should leave +these at the system default. The foundry field is also populated with +an indication of whether the font is outline (.TTF, .ATM) or raster (.FON) +based when fonts are listed, which may let you differentiate between two +fonts with the same name and different technologies. + +Starting with Emacs 23, the preferred font name format will be moving +to the simpler and more flexible fontconfig format. XLFD names will +continue to be supported for backward compatibility. + +@example +XLFD: -*-Courier New-normal-r-*-*-13-*-*-*-c-*-iso8859-1 +Fontconfig: Courier New-13 +@end example + +To find the XFLD name for a font, you can execute the following in the +@file{*scratch*} buffer by pressing C-j at the end of the line: +@example +(w32-select-font nil t) +@end example + +To see a complete list of fonts, execute the following in the +@file{*scratch*} buffer by pressing C-x C-e at the end of the line: +@example +(insert (prin1-to-string (x-list-fonts "*"))) +@end example + +The command line options and frame-parameters for changing the default font +in Emacs are documented in the manual. Fonts can also be used when defining +faces, though family and size are generally specified individually there. +In addition, Emacs on Windows reads the registry to find X Resources. This +is also documented in the manual. + +@node Bold and italic +@section How can I get bold and italic fonts to work? +@cindex italic fonts +@cindex synthesized italic and bold fonts +@cindex bold fonts, synthesized +@findex set-face-font +@vindex w32-enable-synthesized-fonts + +Emacs will only use the italic (and bold) versions of a font automatically +if it has the same width as the normal version. Many fonts have italic +and bold versions that are slightly wider. It will also only use real +bold and italic fonts by default, where other applications may use +synthesized variations that are derived from the normal font. To enable +more italic and bold fonts to be displayed, you can enable synthesized fonts +and manually set the font for italic, bold and bold-italic as follows: + +@example +(setq w32-enable-synthesized-fonts t) +(set-face-font 'italic "-*-Courier New-normal-i-*-*-11-*-*-*-c-*-iso8859-1") +(set-face-font 'bold-italic "-*-Courier New-bold-i-*-*-11-*-*-*-c-*-iso8859-1") +@end example + +The @code{w32-enable-synthesized-fonts} variable is obsolete starting +from Emacs 24.4, as Emacs no longer has this limitation. + +@node Multilingual fonts +@section Multilingual font support +@cindex multilingual display, fonts +@cindex MULE, fonts + +@menu +* Language display:: +* Non-latin display:: +* International fonts:: +* Third-party multibyte:: +* Localized fonts:: +@end menu + +@node Language display +@subsection Is it possible to display all the supported languages? +@cindex HELLO file, displaying all +@cindex language support, fonts +@cindex GNU intlfonts, for displaying all languages +@cindex intlfonts, for displaying all languages + +To display all the languages that Emacs is capable of displaying, you will +require the BDF fonts from the GNU intlfonts package. +@xref{Fonts and text translation,,How do I use bdf fonts with Emacs?}. + +For many languages, native truetype fonts are sufficient, and in Emacs +23 the need for BDF fonts will disappear for almost all languages. At +the time of writing, all supported characters are able to be displayed +with appropriate truetype or opentype fonts. + +@node Non-latin display +@subsection How do I get Emacs to display non-latin characters? +@cindex fontsets, defining +@cindex language support, forcing Emacs to use specific fonts +@cindex MULE, fontsets +@cindex multilingual display, fontsets +@findex create-fontset-from-ascii-font +@findex create-fontset-from-fontset-spec + +Recent versions of Emacs display a large range of characters out of +the box, but if you are having problems with a particular character +set which you know you have fonts for, you can try defining a +new fontset with @code{create-fontset-from-ascii-font} or +@code{create-fontset-from-fontset-spec}. + +@example +(create-fontset-from-fontset-spec + "-*-Courier New-normal-r-*-*-12-*-*-*-c-*-fontset-most, + latin-iso8859-2:-*-Courier New-normal-r-*-*-12-*-*-*-c-*-iso8859-2, + latin-iso8859-3:-*-Courier New-normal-r-*-*-12-*-*-*-c-*-iso8859-3, + latin-iso8859-4:-*-Courier New-normal-r-*-*-12-*-*-*-c-*-iso8859-4, + cyrillic-iso8859-5:-*-Courier New-normal-r-*-*-12-*-*-*-c-*-iso8859-5, + greek-iso8859-7:-*-Courier New-normal-r-*-*-12-*-*-*-c-*-iso8859-7, + latin-iso8859-9:-*-Courier New-normal-r-*-*-12-*-*-*-c-*-iso8859-9, + japanese-jisx0208:-*-MS Gothic-normal-r-*-*-12-*-*-*-c-*-jisx0208-sjis, + katakana-jisx0201:-*-MS Gothic-normal-r-*-*-12-*-*-*-c-*-jisx0208-sjis, + latin-jisx0201:-*-MS Gothic-normal-r-*-*-12-*-*-*-c-*-jisx0208-sjis, + japanese-jisx0208-1978:-*-MS Gothic-normal-r-*-*-12-*-*-*-c-*-jisx0208-sjis, + korean-ksc5601:-*-Gulim-normal-r-*-*-12-*-*-*-c-*-ksc5601-*, + chinese-gb2312:-*-MS Song-normal-r-*-*-12-*-*-*-c-*-gb2312-*, + chinese-big5-1:-*-MingLiU-normal-r-*-*-12-*-*-*-c-*-big5-*, + chinese-big5-2:-*-MingLiU-normal-r-*-*-12-*-*-*-c-*-big5-*" t) +@end example + +Alternatively, you can augment the default fontset with information of +which fonts to use for certain ranges of characters or for specific +scripts/character sets. @xref{Modifying Fontsets,, Modifying +Fontsets, emacs, The GNU Emacs Manual}, for details and some useful +examples. + +@node International fonts +@subsection Where can I find fonts for other languages? +@cindex language support, finding fonts +@cindex fonts, where to find +@cindex MULE, finding fonts +@cindex multilingual display, finding fonts +@cindex GNU intlfonts, where to get +@cindex intlfonts, where to get + +In addition to the wide range of fonts that come with the language +support packages of various components of Windows itself, GNU/Linux +distributions these days come with a number of Free truetype fonts +that cover a wide range of languages. The GNU Unifont project +contains glyphs for most of the Unicode codespace, and can be +downloaded from @uref{http://ftpmirror.gnu.org/unifont, ftp.gnu.org +mirrors}. + +@node Third-party multibyte +@subsection How do I use third party programs to display multibyte characters? +@cindex multilingual display, third party programs on Windows 9x/ME +@cindex language support, third party programs on Windows 9x/ME +@vindex w32-enable-unicode-output + +You probably only need to do this on the non-Unicode versions of Windows +(95, 98 and ME), and even then, various Windows and Internet Explorer +updates have made third party software unnecessary in most cases. +If you are having trouble displaying text, try defining a fontset +with the font for the languages that the third party software handles +set to what that software expects (which may not be an appropriate font +for that language, but the third party software is intercepting it +and using a different font behind the scenes). +@xref{Non-latin display}. + +@node Localized fonts +@subsection Can I use a font with a name in my language? +@cindex fonts, localized font names +@vindex locale-coding-system + +Normally Emacs should initialize @code{locale-coding-system} appropriately +based on your locale, which will let Emacs use font names in your local +language successfully. + +@c This feature disappeared in Emacs 23, and was resurrected in 25.1. +@node Font menu +@section How can I have Emacs use a font menu like on X? +@cindex fonts, displaying a menu +@cindex fontsets, displaying a menu +@cindex font dialog, using a menu instead +@vindex w32-use-w32-font-dialog + +Place the following in your init file: + +@example +(setq w32-use-w32-font-dialog nil) +@end example + +@menu +* Add fonts to menu:: +@end menu + +@c This variable had no effect between v23 and v25.1, where +@c w32-use-w32-font-dialog support was resurrected, see above. +@node Add fonts to menu +@subsection How can I add my font to the font menu? +@cindex font menu, adding fonts +@vindex w32-fixed-font-alist + +If you have set w32-use-w32-font-dialog to @code{nil}, you can add fonts to +the font menu by changing @code{w32-fixed-font-alist}. For example: + +@example +(setq w32-fixed-font-alist + (append w32-fixed-font-alist + '(("Monotype.com" + ("8" "-*-Monotype.com-normal-r-*-*-11-*-*-*-c-iso8859-1") + ("9" "-*-Monotype.com-normal-r-*-*-12-*-*-*-c-iso8859-1") + ("10" "-*-Monotype.com-normal-r-*-*-13-*-*-*-c-iso8859-1") + ("11" "-*-Monotype.com-normal-r-*-*-15-*-*-*-c-iso8859-1"))))) +@end example + +@node Line ends +@section How can I control CR/LF translation? +@cindex DOS line ends +@cindex Unix line ends +@cindex Mac line ends + +There are a number of methods by which you can control automatic CR/LF +translation in Emacs, a situation that reflects the fact that the +default support was not very robust in the past. For a discussion of +this issue, take a look at +@uref{http://www.gnu.org/software/emacs/windows/ntemacs/todo/translate, +this collection of email messages} on the topic. + +@menu +* Automatic line ends:: +* Line ends by file system:: +@end menu + +@node Automatic line ends +@subsection Automatic CR/LF translation +@cindex line ends, automatic detection + +For existing files, Emacs scans the file to determine the line ending +convention as part of the same scan it does to determine the file +encoding. Embedded Ctrl-M (ASCII 13) characters and inconsistent line +ends can confuse the automatic scanning, and Emacs will present the +file in Unix (LF) mode with the Ctrl-M characters displayed as @samp{^M}. +It does this to be safe, as no data loss will occur if the file is really +binary and the Ctrl-M characters are significant. + +@node Line ends by file system +@subsection CR/LF translation by file system +@cindex line ends, determining by filesystem +@cindex binary files, determining by filesystem +@vindex untranslated-filesystem-list +@findex add-untranslated-filesystem +@findex remove-untranslated-filesystem + +The variable @code{untranslated-filesystem-list} defines whole +directory trees that should not have CR/LF autodetection performed on +them. The list can be manipulated with the functions +@code{add-untranslated-filesystem} and +@code{remove-untranslated-filesystem}. With auto-detection in +recent versions of Emacs, this is seldom useful for existing files, +but can still be used to influence the choice of line ends for newly +created files. + +@c ------------------------------------------------------------ +@node Printing +@chapter Printing +@cindex printing + +A lot of effort has gone into making it easier to print from Emacs on +MS Windows, but this has still been insufficient to keep up with +changes in printing technology from text and postscript based printers +connected via ports that can be accessed directly, to graphical +printers that are only accessible via USB. For details, see +@uref{http://www.emacswiki.org/emacs/PrintingFromEmacs, Emacs +Wiki}, @uref{http://www.emacswiki.org/emacs/PrintWithWebBrowser}, and +@uref{http://www.emacswiki.org/emacs/PrintFromWindowsExplorer}. + +@c ------------------------------------------------------------ +@node Sub-processes +@chapter Subprocesses +@cindex subprocesses + +@menu +* Quoting issues:: +* Subprocess hang:: +* Subprocess buffering:: +* Subprocesses and floppy drive:: +* Killing subprocesses:: +* Subprocess EOF:: +* Using shell:: +* Cygwin paths:: +* Dired ls:: +* Shell echo:: +* Shell completion forward slash:: +* Incorrect DOS version:: +* Shell commands do nothing:: +@end menu + +@node Quoting issues +@section Quoting issues +@cindex quoting arguments to subprocesses +@cindex sub-processes, quoting arguments to +@cindex cygwin, quoting arguments + +The quoting rules for native Windows shells and Cygwin shells have +some subtle differences. When Emacs spawns subprocesses, it tries to +determine whether the process is a Cygwin program and changes its +quoting mechanism appropriately. + +@node Subprocess hang +@section Programs reading input hang +@cindex subprocesses, hanging when reading input +@cindex full-screen console programs, as subprocesses +@cindex ftp, client hanging +@findex ftp + +Programs that explicitly use a handle to the console (@file{CON} or +@file{CON:}) instead of stdin and stdout cannot be used as +subprocesses to Emacs, and they will also not work in shell-mode. The +default ftp client on Windows is an example of such a program - this +ftp program is mostly fine for use with @code{ange-ftp} or +@code{tramp}, but not for @kbd{M-x ftp} (@pxref{Network access,,How do +I use FTP within Emacs}). There is no convenient way for either Emacs +or any shell used in @code{shell-mode} to redirect the input and +output of such processes from the console to input and output pipes. +The only workaround is to use a different implementation of the +program that does not use the console directly. Microsoft's new +PowerShell appears to be another such program, so that cannot be used +as a replacement shell for Emacs. + +@node Subprocess buffering +@section Buffering in shells and subprocesses +@cindex subprocesses, buffering output +@cindex output not displaying, subprocesses +@cindex SQL subprocess hanging +@cindex cvs hanging when login needed +@cindex ssh, password prompt not appearing when using with cvs +@findex sql-mode +@findex shell-mode +@cindex setbuf, using in subprocesses to prevent buffering +@cindex setvbuf, using in subprocesses to prevent buffering + +You may notice that some programs, when run in a shell in +@code{shell-mode}, +have their output buffered (e.g., people have found this happening to +them with @code{sql-mode}). When the program has a lot of output, it +overflows the buffering and gets printed to the shell buffer; however, +if the program only outputs a small amount of text, it will remain +buffered and won't appear in the shell buffer. The same can happen +in other subprocesses that themselves run other programs as +subprocesses, for example when using @command{cvs} from Emacs, which +is itself configured to use @command{ssh}, password prompts fail to +appear when expected, and @command{cvs} appears to hang. + +Although it may at first seem like the shell is buffering the output +from the program, it is actually the program that is buffering +output. The C runtime typically decides how to buffer output based +upon whether stdout is bound to a handle to a console window or +not. If bound to a console window, output is buffered line by line; if +bound to a block device, such as a file, output is buffered block by +block. + +In a shell buffer, stdout is a pipe handle and so is buffered in +blocks. If you would like the buffering behavior of your program to +behave differently, the program itself is going to have to be changed; +you can use @code{setbuf} and @code{setvbuf} to manipulate +the buffering semantics. + +Some programs handle this by having an explicit flag to control their +buffering behavior, typically @option{-i} for interactive, or by a +special environment variable. Other programs manage to detect that +they are running under Emacs, by using @samp{getenv("emacs")} +internally. Look in the program's documentation for the way around +this issue. + +@menu +* Perl script buffering:: +@end menu + +@node Perl script buffering +@subsection Perl script buffering +@cindex perl, avoiding buffering when used as a subprocess of Emacs + +A handy solution for Perl scripts to the above problem is to use: + +@example +# Turn all buffering off. +select((select(STDOUT), $| = 1)[0]); +select((select(STDERR), $| = 1)[0]); +select((select(STDIN), $| = 1)[0]); +@end example + +@node Subprocesses and floppy drive +@section 16-bit subprocesses accessing the floppy drive +@cindex floppy drive, access when subprocesses started +@cindex subprocess starting causes floppy drive access + +If you are finding the 16 bit DOS subprocesses cause your A: drive to +be accessed, hanging Emacs until the read times out if there is no +floppy in the drive, check to see if your virus software is causing +the problem. + +@node Killing subprocesses +@section Killing subprocesses on Windows 95/98/Me +@cindex subprocess, killing on Windows 95/98/ME +@cindex killing subprocesses, Windows 95/98/ME +@cindex shutdown, complaints about cmdproxy.exe running + +Emacs cannot guarantee that a subprocess gets killed on Windows 95 and +its descendants, and it is a difficult limitation to work around. To +avoid problems on these systems, you should let subprocesses run to +completion including explicitly exiting shells before killing the +associated buffer. + +If you find that while shutting down, Windows complains that there is +a running @command{cmdproxy.exe} even though you carefully exited all +shells and none were showing in Task Manager before the shutdown, this +could be due to buggy interaction with your virus scanner. + +@node Subprocess EOF +@section Sending EOF to subprocesses +@cindex EOF, sending to subprocesses +@cindex shell terminates when EOF sent to subprocess +@findex process-send-eof + +When an EOF is sent to a subprocess running in an interactive shell +with @code{process-send-eof}, the shell terminates unexpectedly as +if its input was closed. This affects the use of @kbd{C-c C-d} in +shell buffers. See +@uref{http://www.gnu.org/software/emacs/windows/ntemacs/todo/shell-ctrl-d, +this discussion} for more details. + +@node Using shell +@section How do I use a shell in Emacs? +@cindex interactive shell, using +@cindex shell within emacs, using +@findex shell +@findex shell-command +@vindex shell-file-name +@vindex explicit-shell-file-name + +You can start an interactive shell in Emacs by typing @kbd{M-x shell}. +By default, this will start the standard Windows shell @file{cmd.exe}. +Emacs uses the @env{SHELL} environment variable to determine which +program to use as the shell. To instruct Emacs to use a non-default +shell, you can either set this environment variable, or customize +@code{explicit-shell-file-name}. You can also customize +@code{shell-file-name} to change the shell that will be used by +subprocesses that are started with @code{shell-command} and +related non-interactive shell commands. + +@menu +* Bash:: +@end menu + +@node Bash +@subsection bash +@cindex cygwin bash as shell within Emacs +@cindex shell, using cygwin bash within Emacs +@cindex bash, using cygwin shell within Emacs +@vindex comint-scroll-show-maximum-output +@vindex comint-completion-addsuffix +@vindex comint-eol-on-send +@vindex w32-quote-process-args +@vindex shell-mode-hook + +Cygwin bash is a popular shell for use with Emacs. To use bash as the +default shell in Emacs, you can place the following in your init file: + +@example +(defun my-shell-setup () + "For Cygwin bash under Emacs 20" + (setq comint-scroll-show-maximum-output 'this) + (make-variable-buffer-local 'comint-completion-addsuffix)) + (setq comint-completion-addsuffix t) + ;; (setq comint-process-echoes t) ;; reported that this is no longer needed + (setq comint-eol-on-send t) + (setq w32-quote-process-args ?\") + +(add-hook 'shell-mode-hook 'my-shell-setup) +@end example + +WARNING: Some versions of bash set and use the environment variable +PID. For some as yet unknown reason, if @env{PID} is set and Emacs +passes it on to bash subshells, bash dies (Emacs can inherit the +@env{PID} variable if it's started from a bash shell). If you clear +the @env{PID} variable in your init file, you should be able to +continue to use bash as your subshell: +@example + (setenv "PID" nil) +@end example + +@node Cygwin paths +@section How do I use Cygwin style paths in Emacs? +@cindex cygwin paths, using within Emacs +@cindex mount points, cygwin +@cindex cygwin mount points, using within Emacs + +The package +@uref{http://www.emacswiki.org/emacs/cygwin-mount.el, +cygwin-mount.el} teaches Emacs about Cygwin mount points. + +@node Dired ls +@section How do I make dired use my ls program? +@cindex dired, using an external ls program +@cindex dired, interpreting symlinks the same way as cygwin +@cindex symlinks in dired, interpreting the same way as cygwin +@cindex cygwin symlinks in dired +@vindex ls-lisp-use-insert-directory-program +@vindex insert-directory-program + +Dired uses an internal lisp implementation of @command{ls} by default +on Windows. For consistent display of symbolic links and other +information with other programs (eg Cygwin) and performance reasons, +you may want to use a Windows port of @command{ls} instead. + +@example +(setq ls-lisp-use-insert-directory-program t) ;; use external ls +(setq insert-directory-program "c:/cygwin/bin/ls") ;; ls program name +@end example + +@node Shell echo +@section How do I prevent shell commands from being echoed? +@cindex echo, suppressing for shell input +@cindex shell commands, suppressing echo +@vindex comint-process-echoes +@vindex comint-mode-hook +@vindex explicit-cmd.exe-args +@vindex explicit-cmdproxy.exe-args +@vindex explicit-bash.exe-args +@vindex explicit-bash-args +@cindex shell specific arguments + +Some shells echo the commands that you send to them, and the echoed +commands appear in the output buffer. In particular, the default +shells, @command{command.com} and @command{cmd.exe}, have this behavior. + +To prevent echoed commands from being printed, you can place the +following in your init file: + +@example + (defun my-comint-init () + (setq comint-process-echoes t)) + (add-hook 'comint-mode-hook 'my-comint-init) +@end example + +If @code{shell-mode} still is not stripping echoed commands, then +you'll have to explicitly tell the shell to not echo commands. You can +do this by setting the @code{explicit-@var{SHELL}-args} variable +appropriately; where @var{SHELL} is the value of your @env{SHELL} +environment variable (do a @kbd{M-: (getenv "SHELL")} to see what it +is currently set to). Assuming that you are on NT and that your +@env{SHELL} environment variable is set to @command{cmd.exe}, +then placing the following in your init file will tell +@command{cmd.exe} to not echo commands: + +@example + (setq explicit-cmd.exe-args '("/q")) +@end example + +The comint package will use the value of this variable as an argument +to @command{cmd.exe} every time it starts up a new shell; the +@option{/q} is the argument to @command{cmd.exe} that stops the +echoing (invoking @samp{cmd /?} in a shell will show you all of the +command line arguments to @command{cmd.exe}). + +Note that this variable is case sensitive; if the value of your +@env{SHELL} environment variable is @command{CMD.EXE} instead, then +this variable needs to be named @code{explicit-CMD.EXE-args} instead. + +@node Shell completion forward slash +@section How can I make shell completion use forward slashes? +@cindex completion, using forward slashes in shell buffers +@cindex forward slashes for completion in shell buffers +@vindex comint-completion-addsuffix + +The character appended to directory names when completing in a shell +buffer is controlled by the variable @code{comint-completion-addsuffix}. +See its documentation (with @kbd{C-h v}) for details. + +@node Incorrect DOS version +@section Why do I get incorrect DOS version messages? +@cindex nmake, Incorrect DOS version messages +@cindex shell, Incorrect DOS version messages +@cindex COMSPEC, effect on subprocesses of subprocesses + +This might happen if, for example, you invoke @command{nmake} in a +shell and it tries to create sub-shells. The problem happens because +when the shell is initially created, the first argument to the shell +is not the directory in which the shell program resides. When this +happens, @command{command.com} fabricates a value for its +@env{COMSPEC} environment variable that is incorrect. Then, when +other programs go to use @env{COMSPEC} to find the shell, they are +given the wrong value. + +The fix for this is to either prevent any arguments from being sent to +the shell when it starts up (in which case @command{command.com} will +use a default, and correct, value for @env{COMSPEC}), or to have the +first argument be the directory in which the shell executable resides. + +@node Shell commands do nothing +@section Why is nothing happening when I enter shell commands? +@cindex shell commands not working +@cindex anti-virus software, bad interaction with +@cindex virus software, bad interaction with +@cindex firewall, bad interaction with +@cindex scan all files, anti-virus option causing problems +@cindex auto protect, anti-virus option causing problems +@cindex shell, interacting badly with anti-virus + +Some anti-virus software has been reported to cause problems with +shells in the past. Try turning off options such as ``Scan all +files''. @xref{Installing Emacs,,What known problems are there with anti-virus software?}. + +@c ------------------------------------------------------------ +@node Network access +@chapter Network access + +@menu +* Mail:: +* Attachments with Gnus:: +* Using FTP:: +* Tramp ssh:: +* telnet:: +@end menu + +@node Mail +@section How do I use mail in Emacs? + +Emacs comes with several options for reading and writing mail. These +are documented in the manual, and the choice of which method to use +depends on personal taste. There are some issues specific to Windows +however, related to the fact that Windows machines do not have the +mail infrastructure that is commonly installed on other platforms, so +mail will not work without some configuration. + +@menu +* Outgoing mail:: +* Incoming mail with Rmail:: +* Incoming mail with Gnus:: +* Incoming mail other:: +@end menu + +@node Outgoing mail +@subsection Outgoing mail +@cindex mail, outgoing +@cindex smtp server +@vindex user-full-name +@vindex user-mail-address +@vindex smtpmail-default-smtp-server +@vindex smtpmail-smtp-server +@vindex send-mail-command +@vindex message-send-mail-function +@findex smtpmail-send-it +@vindex smtpmail-debug-info + +For outgoing mail, you will need to use @file{smtpmail.el} which +allows Emacs to talk directly to SMTP mail servers. This is included +with Emacs, and can be set up as follows: + +@example +(setq user-full-name "@var{Your full name}") +(setq user-mail-address "@var{Your@@email.address}") +(setq smtpmail-default-smtp-server "@var{domain.name.of.your.smtp.server}") + +(setq send-mail-command 'smtpmail-send-it) ; For mail-mode (Rmail) +(setq message-send-mail-function 'smtpmail-send-it) ; For message-mode (Gnus) +@end example + +Note that if you want to change the name of the SMTP server after +smtpmail is loaded, then you'll need to change +@code{smtpmail-smtp-server}. + +If you are experiencing problems with sending large messages, check +the value of the variable @code{smtpmail-debug-info}. If it is +non-@code{nil}, you should set it to @code{nil}: + +@node Incoming mail with Rmail +@subsection Incoming mail with Rmail and POP3 +@cindex mail, incoming with rmail +@cindex pop3, using rmail +@cindex rmail, mail client +@cindex movemail, using pop3 +@cindex MAILHOST +@vindex rmail-primary-inbox-list +@vindex rmail-pop-password-required + +For incoming mail using the Rmail package and a POP3 server, you will +need the following configuration: + +@example +(setenv "MAILHOST" "@var{domain.name.of.your.pop3.server}") +(setq rmail-primary-inbox-list '("po:@var{your logon id}")) +(setq rmail-pop-password-required t) +@end example + +@node Incoming mail with Gnus +@subsection Incoming mail with Gnus +@cindex mail, incoming with Gnus +@cindex pop3, using Gnus +@cindex imap, using Gnus +@cindex gnus, mail and news client + +Although Gnus started life as a Usenet news reader, it also makes a +good mail reader, particularly if you subscribe to a lot of mailing +lists, or you want to use IMAP rather than POP3, which is not +supported by Rmail. @xref{Top,The Gnus manual,,gnus, The Gnus manual}. + +@node Incoming mail other +@subsection Other incoming mail options +@cindex mail, other options +@cindex wanderlust, mail and news client +@cindex vm, mail client +@cindex mh-e, mail client + +Other options for reading mail in Emacs include VM, MH-E and Wanderlust. +MH-E is included with Emacs. The others require lisp or executable code +that does not come with Emacs, so you should seek help where you +obtained the packages from if you want to use them. + +@node Attachments with Gnus +@section How do I open attachments in Gnus? +@cindex gnus, attachments +@cindex attachments, in gnus +@cindex mail, attachments in gnus +@cindex .mailcap +@cindex MIME, configuration for Gnus + +In your @env{HOME} directory create a file called @file{.mailcap}, +with contents like the following: +@example +application/zip "C:/Program Files/7-Zip/7zFM.exe" +video/* "C:/Program Files/VideoLAN/VLC/vlc.exe" +@end example + +@strong{Warning:} Associating MIME types with @command{start} or other +generic Windows commands to open arbitrary files might seem like a +good idea, but it leaves your system as open to attack as Outlook +Express was at its worst. Especially dangerous is associating +application/* or */* in this way. + +@node Using FTP +@section How do I use FTP within Emacs? +@cindex ftp, using within Emacs +@cindex ange-ftp +@cindex tramp, ftp +@cindex remote hosts via ftp +@vindex ange-ftp-ftp-program-name + +Windows built in FTP client can be used with ange-ftp. Ange-ftp is +the Emacs package that provides FTP connectivity to tramp, a +multi-protocol remote file access package for Emacs that is enabled by +default. + +The Windows FTP client does have problems with some firewalls, due to +lack of passive mode support, so you may want to try an alternative +ftp client instead. Make sure that the client you are trying is in +your @env{PATH} before the default Windows client, or rename the +default Windows client to avoid it getting in the way. Alternatively +you can customize @code{ange-ftp-ftp-program-name} to the full path to +the version you are trying. @xref{Other useful ports}. + +@node Tramp ssh +@section How do I use Tramp to work in Emacs via SSH? +@cindex tramp, ssh +@cindex ssh, accessing remote hosts within Emacs +@cindex remote hosts via ssh +@cindex openssh +@cindex PuTTY +@cindex plink +@vindex tramp-default-method +@vindex tramp-default-method-alist + +Tramp can use a number of protocols to connect to remote machines to +read files and even run commands on those files remotely. A popular +one is ssh. As well as Cygwin versions of openssh, you can use +PuTTY's command line plink program as the ssh client. The relevant +methods to use in @code{tramp-default-method} or +@code{tramp-default-method-alist} for these options are: +@itemize @w{} +@item +openssh +@itemize +@item @code{scp} Uses scp for copying, ssh for shell operations. +@item @code{ssh} Uses ssh with encoding on stdin/stdout for file transfer. +@end itemize + +@item +PuTTY +@itemize +@item @code{pscp} Uses pscp for copying, plink for shell operations. +@item @code{plink} Uses plink with encoding on stdin/stdout for file transfer. +@end itemize +@end itemize + +@node telnet +@section How do I use telnet with Emacs? +@cindex telnet, in Emacs +@findex telnet +@cindex telnet client, that works with Emacs + +To use telnet-mode on Windows, you need a telnet client that uses +stdin and stdout for input and output. The default Windows client is +a Windows application, and will not work as a subprocess. Several +options exist, but information that was formerly in this FAQ is out of +date now, so no concrete pointers are available. + +@c ------------------------------------------------------------ +@node Text and Utility modes +@chapter Text and Utility modes + +@menu +* TeX:: +* Spell check:: +* Encryption:: +* Mouse wheel:: +* Grep:: +@end menu + +@node TeX +@section How do I use TeX with Emacs? +@cindex tex +@cindex typesetting + +You will need an implementation of TeX for Windows. +A number of implementations are listed on the +@uref{http://www.tug.org/interest.html#free, TeX Users Group} website. + +@menu +* AUCTeX:: +@end menu + +@node AUCTeX +@subsection AUCTeX +@cindex auctex, precompiled for Windows +@cindex latex +@cindex preview-latex + +AUCTeX is an Emacs package for writing LaTeX files, which also +includes preview-latex, an Emacs mode for previewing the formatted +contents of LaTeX documents. Pre-compiled versions for Windows are +available from +@uref{http://www.gnu.org/software/auctex/download-for-windows.html, the +AUCTeX site}. + +@node Spell check +@section How do I perform spell checks? +@cindex spell checking +@cindex ispell +@cindex aspell +@cindex flyspell +@vindex ispell-program-name +@findex flyspell-mode + +Emacs has support for spell checking on demand (@code{ispell}) and as +your type (@code{flyspell}). Both packages depend on a copy of +@command{ispell} 3.2 or a compatible spell-checking program. +GNU Aspell is a popular choice these days, Windows installers are +available from the @uref{http://aspell.net/win32/, official site}. +Another possibility is Hunspell, which is available from +@uref{https://sourceforge.net/projects/ezwinports/files/?source=navbar, +the ezwinports site}. + +Once installed, you will need to configure @code{ispell-program-name} +to tell ispell and flyspell to use @command{aspell} or +@command{hunspell} as a replacement for ispell. You can include the +full path to the @file{aspell}/@file{hunspell} binary, which means you +do not need to add its installation directory to the @env{PATH}. + +@node Encryption +@section Emacs and encryption +@cindex encryption +@cindex gpg, Windows binaries +@cindex pgp encryption, with GNU Privacy Guard +@cindex signatures on Emacs distribution, checking +@cindex Emacs distribution, checking digital signatures + +GNU Privacy Guard is a Free replacement for PGP, with Windows binaries +available. See @uref{http://www.gnupg.org/}. + +@node Mouse wheel +@section Why doesn't my wheel mouse work in Emacs? +@cindex mouse wheel +@cindex wheel mouse +@cindex middle button, on wheel mouse +@cindex scrolling, with mouse wheel + +Some wheel mice ship with default settings that do not send the +standard wheel events to programs, but instead try to simulate scroll +bar events. Usually this is configurable from the hardware specific +pages on the mouse control panel. The middle button is often mapped +in the same settings to have some functionality other than sending +middle mouse button events. In some cases, uninstalling the +manufacturer's drivers and telling Windows to use the generic USB or +PS/2 drivers is the only way to make the mouse work properly. + +@node Grep +@section How do I use grep with Emacs? +@cindex searching through files with grep +@cindex grep +@cindex findstr +@findex grep + +The best way to use @kbd{M-x grep} with Emacs is to download a port of +GNU @command{grep}. @xref{Other useful ports}. + +If you want a quick solution without installing extra tools, a poor +substitute that works for simple text searches is to specify the built +in Windows command @command{findstr} as the command to run at the +@kbd{M-x grep} prompt. Normally you will want to use the @option{/n} +argument to @command{findstr}. + +@menu +* Recursive grep:: +@end menu + +@node Recursive grep +@subsection How do I do a recursive grep? +@cindex recursive searching with grep +@cindex grep, recursive through subdirectories +@cindex findstr, recursive +@cindex find, using with grep +@cindex find, the POSIX command +@findex rgrep +@findex grep-find +@findex find-grep-dired +@vindex find-program +@vindex grep-find-command + +The Emacs commands @code{rgrep}, @code{grep-find} +and @code{find-grep-dired} are all different interfaces for +grepping recursively into subdirectories. By default, they use the +command @command{find} to determine which files to work on, and either +run @command{grep} directly from find, or use @command{xargs} to batch +up files and reduce the number of invocations of @command{grep}. + +Windows also comes with a @command{find} command, but it is not in any +way compatible with the POSIX @command{find} that Emacs tries to use. +Emacs expects a @command{find} compatible with GNU findutils. +@xref{Other useful ports}. After you have installed it, you will need +to make sure that Emacs finds this version, not the standard Windows +@command{find} command. You can do this by either renaming the +Windows command, changing your @env{PATH} to ensure that the directory +containing the findutils @file{bin} directory comes before the Windows +system directory, or set the variable @code{find-program} to the full +path to the findutils @command{find} command. + +An alternative if you have a recent version of grep is to customize +@code{grep-find-command} to use @samp{grep -r} instead of both find +and grep. Another alternative if you don't need the full capabilities +of grep is to use @samp{findstr /n /r}. + +@c ------------------------------------------------------------ +@node Developing with Emacs +@chapter Developing with Emacs + +We recommend using the GNU Compiler Collection for developing C/C++ +code from Emacs. The MinGW development toolchain provides Windows +ports of GCC and other compilers. + +The rest of this chapter describes other alternatives which you may +need to use. + +@menu +* MSVC:: +* Borland C++ Builder:: +* Version control:: +* Perldb:: +@end menu + +@node MSVC +@section How do I use Emacs with Microsoft Visual C++ + +There are two ways you can use Emacs in conjunction with MSVC. You +can use Emacs as the editor, and do everything else in the DevStudio +IDE. Or you can use Emacs as an IDE, calling the MSVC command line +tools to build your project. + +@menu +* DevStudio:: +* MSVC command line:: +@end menu + +@node DevStudio +@subsection Emacs as the text editor for DevStudio +@cindex DevStudio, using Emacs as editor in +@cindex MSVC++, using Emacs as editor with +@cindex Visual Studio, using Emacs as editor in +@cindex VisEmacs, add in for MS Developer Studio + +Christopher Payne wrote a Visual Studio add-in that makes Emacs the +default text editor, this has now been taken over by Jeff Paquette. +See the following two URLs for details: +@itemize +@item @uref{http://sourceforge.net/projects/visemacs/} for the latest version. +@item @uref{http://www.smathers.net/VisEmacs.htm} for notes on usage. +@end itemize + +@node MSVC command line +@subsection Using MSVC command line tools from Emacs +@cindex MSVC++, compiling within Emacs +@findex compile + +This is an app note on how to use Microsoft Visual C++ with Emacs. The +experiments done below were done with Emacs 19.34.1 on Windows 95, +using Visual C++ 4.0 Standard Edition. Your mileage may vary. + +This writeup assumes minimal knowledge of Emacs hacking on the part of +the reader. + +@menu +* VC++ environment:: +* Default compile command:: +* Reverting buffers:: +* Edit MSVC:: +@end menu + +@node VC++ environment +@subsubsection VC++ Environment Variables +@cindex vcvars32.bat +@cindex MSVC++, environment variables + +There is a batch file in your VC++ installation's bin directory called +@file{vcvars32.bat}, which sets up the environment variables needed to +run the VC++ command line tools. Arrange for those same environment +variables to be set in your Emacs session. You can do this on Windows +9x by calling the @file{vcvars32.bat} script from @file{autoexec.bat}. +On other versions of Windows you can set the environment variables +globally using the System control panel. + +For all versions of Windows you can alternatively set the variables +just inside Emacs by using @code{setenv} calls in your init file. +@xref{Installing Emacs,,Where do I put my init file?}. + +You should now be able to compile from Emacs. Load a source file from +a VC++ project. Type @kbd{M-x compile}. Replace the proposed command line +with: +@example +nmake -f @var{ProjectName}.mak +@end example + +You will find that this defaults to a debug build. You can change it +to a release build with: +@example +nmake -f @var{ProjectName}.mak CFG="@var{ProjectName} - Win32 Release" +@end example + +@node Default compile command +@subsubsection Setting the default compile command +@cindex compile, setting default command +@cindex nmake, as default compile command +@vindex compile-command + +Now set the default value for the compile command line. Add the +following to your init file: + +@example +;; Set up for Visual C++ compiling +(setq compile-command "nmake -f ") +@end example + +If you work on the same project long term, you can add the project +makefile to the string. + +David Biesack suggests that perhaps it's +easy to write a @file{Makefile} in the project directory which does + +@example +PROJECT=MyProject +all: debug +debug: FORCE + nmake /f $(PROJECT).mak CFG="$(PROJECT) - Win32 Debug" +release: FORCE + nmake /f $(PROJECT).mak CFG="$(PROJECT) - Win32 Release" +FORCE: +@end example + +and then you can simply change compile-command to @command{nmake}. + +Caleb T. Deupree reports that on VC++ +5.0 and up, "You can also set an option in Options/Build to export a +makefile every time the project is saved, which you can then use to +compile with @samp{nmake -f project.mak}." VC++ 4.0 builds the make file +every time, and there is no option. + +@node Reverting buffers +@subsubsection Reverting Buffers +@cindex DevStudio, keeping source in sync +@cindex Visual Studio, keeping source in sync +@cindex MSVC++, keeping source in sync +@findex auto-revert-mode +@findex global-auto-revert-mode + +It is recommended that you use @code{auto-revert-mode} in buffers +that you have open in both Emacs and MSVC++ at the same time. Then if +you mistakenly edit the file in MSVC++, Emacs will pick up your +changes immediately, rather than after you have written lots more code +and attempt to save. + +@node Edit MSVC +@subsubsection Edit with Emacs function for MSVC +@cindex DevStudio, load in Emacs command +@cindex Visual Studio, load in Emacs command +@cindex MSVC++, load in Emacs command +@cindex emacsclient, calling from Visual Studio + +You can also set up VC++ to import a file into Emacs for you, all +ready for editing. In VC++, go to the @code{Tools} pull-down menu, and +click on @code{Customize...}. In the @code{Tools} tab, click on +@code{Add}. Use @code{Browse} to locate the +@file{emacsclientw.exe} file in your Emacs bin directory, and +select it. For arguments, use @option{+$(CurLine)} +@option{"$(FilePath)"} and for the directory use the @code{$(WkspDir)} +(the quotes around FilePath handle paths with spaces in them). Set the +Menu Text to say "Em&acs". The @option{+$(CurLine)} will set point in +Emacs to the same line as the cursor position in VC++. The ampersand +in the word @code{Em&acs} allows you to select emacs from the keyboard. +(E is already used for the OLE control test container.) + +You should now be able to go to any source file in your project. Then, +use the pull-down menu @code{Tools->Emacs}. The active file in your +VC++ IDE should now be front and center in Emacs, all ready to edit as +you wish. If you use keystrokes to work the menus, try @kbd{Alt-T A} to +move the file into Emacs. Binding this tool to a keystroke will be +left as an exercise for the student. + +If you have the option of saving files before running tools, make sure +this option is set. (I don't see it on VC++ 4.0.) + +@node Borland C++ Builder +@section Emacs and Borland C++ Builder +@cindex Borland C++, integration with Emacs + +Jonathan Arnold has written an +@uref{http://www.buddydog.org/C++Builder/c++builder.html, EmacsEdit +``expert''} for interfacing C++ Builder and Emacs. + +@node Version control +@section Is there a version of my VC software I can use with Emacs? +@cindex version control, integration with Emacs +@cindex revision control, integration with Emacs +@cindex source control, integration with Emacs +@cindex cvs, version control integration with Emacs +@cindex rcs, version control integration with Emacs +@cindex svn, version control integration with Emacs +@cindex git, version control integration with Emacs +@cindex bzr, version control integration with Emacs +@cindex arch, version control integration with Emacs +@cindex mercurial, version control integration with Emacs +@cindex hg, version control integration with Emacs +@cindex monotone, version control integration with Emacs +@cindex mcvs, version control integration with Emacs + +If you are using a graphical revision control tool already, check if +it comes with command-line tools. Many such GUI tools are just +wrappers for the same command line tools that Emacs requires for its +VC integration. Most of the supported VC systems have well supported +Free native Windows binaries. For those that don't Cygwin may be an option. +@xref{Other useful ports}. + +@node Perldb +@section How do I use the Perl debugger with Emacs? +@cindex perl, debugging within Emacs +@cindex perldb, using with Emacs + +From Jay Rogers: + +Some versions of the perl debugger itself need to be patched to work +with emacs. They are perl versions 5.001 and less, and version +5.004_01. To fix, locate and change the code similar to the following +code in lib/perl5db.pl +@example + if (-e "/dev/tty") @{ + $console = "/dev/tty"; + $rcfile=".perldb"; + @} + elsif (-e "con") @{ + $console = ""; <---- change "con" to "" + $rcfile="perldb.ini"; + @} + else @{ + $console = "sys\$command"; + $rcfile="perldb.ini"; + @} +@end example + +Doug Campbell also has some +@uref{http://www.gnu.org/software/emacs/windows/ntemacs/discuss/perldb, +suggestions} for improving the interaction of perldb and Emacs. + +@c ------------------------------------------------------------ +@node Other useful ports +@chapter Other useful ports +@cindex useful tools +@cindex subprocesses, useful tools + +@menu +* Cygwin:: +* MinGW:: +* EZWinPorts:: +* UWIN:: +* GnuWin32:: +* GTK:: +* Read man pages:: +@end menu + +@node Cygwin +@section Cygwin +@cindex cygwin environment +@cindex cygwin, library conflicts +@cindex library conflicts with cygwin +@cindex interoperability with cygwin +@cindex subprocesses, cygwin tools +@vindex exec-path + +@uref{http://www.cygwin.com/}. + +Cygwin is a popular complete POSIX emulation environment for Windows. +Most of its tools can be used with Emacs, and it covers a wide range +of ported software. The main shell used by Cygwin is GNU +@command{bash}, but other shells are also available. Some Cygwin +tools may not interoperate well with Emacs or other native Windows +tools, due to the total immersion aspect of Cygwin, including its +non-native filesystem mapping. + +If you choose to use Cygwin, then its tools will probably be all that +you need, but you will need to get image libraries from elsewhere, as +the Cygwin ones are not compatible with non-Cygwin software. In fact, +if Cygwin is on your PATH when you run Emacs, and Emacs does not find +other versions of the image libraries first, then the Cygwin ones can +cause problems. Cygwin developers recommend that you do not put +Cygwin on your system @env{PATH} for this reason. Instead you can +make the Cygwin tools available within Emacs by setting @code{exec-path} +in your init file. + +@node MinGW +@section MinGW and MSYS +@cindex mingw tools +@cindex msys environment +@cindex subprocesses, mingw and msys + +@uref{http://www.mingw.org/} + +MinGW is a set of development tools that produce native Windows +executables, not dependent on Cygwin's POSIX emulation DLLs. + +MSYS is a POSIX shell and minimal set of tools that are commonly used in +configure scripts. Like Cygwin, this environment uses a non-native +filesystem mapping to appear more POSIX like to the scripts that it +runs. This is intended to complement the MinGW tools to make it easier +to port software to Windows. + +@node EZWinPorts +@section EZWinPorts +@cindex ezwinports + +The @uref{https://sourceforge.net/projects/ezwinports/, EZWinPorts +project} provides many useful ports of recent versions of GNU and Unix +software. This includes all the optional libraries used by Emacs +(image libraries, libxml2, GnuTLS), RCS, Texinfo, a clone of +@command{man} command, Grep, xz, bzip2, bsdtar, ID Utils, Findutils, +Hunspell, Gawk, GNU Make, Groff, GDB. + +@node UWIN +@section UWIN +@cindex uwin environment +@cindex subprocesses, uwin + +@uref{http://www.research.att.com/sw/tools/uwin/} + +UWIN is another POSIX emulation environment, like Cygwin and MSYS, +that provides a large number of ported tools. The shell used by UWIN +is @command{ksh}, the Korn shell. + +@node GnuWin32 +@section GnuWin32 +@cindex gnuwin32 tools +@cindex subprocesses, gnuwin32 +@cindex image libraries, gnuwin32 +@cindex image libraries, development + +@uref{http://gnuwin32.sourceforge.net/} + +GnuWin32 provides precompiled native Windows ports of a wide selection +of Free software and libraries. Unfortunately, the ports are +outdated. Tools available here that are useful for Emacs include: + +@itemize +@item Arc - used by @code{archive-mode} to edit .arc files. +@item Bzip2 - used by Emacs to automatically decompress .bz2 files. +@item CompFace - used by @code{gnus} to display XFace headers in messages. +@item CoreUtils - GNU file, shell and text utilities (also in MSYS) +@item DiffUtils - for @code{ediff} and producing patches +@item FindUtils - for @code{grep-find} and other file searches. +@item GifLib - library to support GIF images. +@item Grep - for searching through files with @code{grep}. +@item Gzip - used by Emacs to automatically decompress .gz files. +@item Jpeg - library to support JPEG images (also in GTK). +@item Lha - used by @code{archive-mode} to edit .lzh files. +@item LibPng - library to support PNG images (also in GTK). +@item LibTiff - library to support TIFF images (also in GTK). +@item Make - used by @code{compile} for building projects (also in MinGW) +@item OpenSSL - used by @code{gnus} to talk to servers over SSL. +@item Patch - used by @code{ediff-patch-file} and others to apply patches. +@item Tar - used by @code{tar-mode} to edit tar files. +@item TexInfo - used to build Emacs' manuals. +@item Unzip - used by @code{archive-mode} for extracting zip files. +@item Xpm - library to support XPM images (bundled with Emacs binaries) +@item Zip - used by @code{archive-mode} for editing zip files. +@item Zlib - required by LibPng (also in GTK). +@end itemize + +@node GTK +@section GTK +@cindex GTK image libraries +@cindex image libraries, GTK +@cindex addpm, using GTK image libraries + +GTK is a potential source for some of the image libraries that Emacs +requires. GTK is installed along with other ports of GUI software, +such as the GIMP image editor, and Pidgin instant messenger client. +If GTK is installed when you run @command{addpm}, Emacs will use the +image libraries that it provides, even if they are not on the +@env{PATH}. GTK ships with JPEG, PNG and TIFF support. + +@node Read man pages +@section How do I read man pages? +@cindex man pages +@findex woman +@findex man + +Man pages for Emacs and other ported programs that you have can be +read using Emacs' built-in manual reader @code{woman}. This +requires no external programs, but if you do have a port of +@command{man}, there is also an Emacs wrapper @code{man} that +which may be slightly faster. A Windows version of @command{man} is +available from the EZWinPorts site (@pxref{EZWinPorts}). + +@c ------------------------------------------------------------ +@node Further information +@chapter Further information + +@menu +* More information:: +* Mailing lists:: +@end menu + +@node More information +@section Where can I get more information about Emacs? +@cindex other sources of information +@cindex faqs, general +@cindex faqs, old +@cindex help, manuals and other sources +@cindex manuals +@cindex wiki + +If you have general questions about Emacs, the best places to start +looking are @ref{Top,,, emacs, The GNU Emacs Manual}, and +@ref{Top,,, efaq, the standard Emacs FAQ}. +In Emacs, you can browse the manual using Info by typing @kbd{C-h r}, +and you can view the FAQ by typing @kbd{C-h C-f}. Other resources include: + +@itemize +@item @uref{http://www.gnu.org/software/emacs/, The Emacs homepage} +@item @uref{http://www.gnu.org/software/emacs/manual/, Other Emacs manuals} +@item @uref{http://www.emacswiki.org/, Emacs Wiki} +@end itemize + +@node Mailing lists +@section What mailing lists are there for discussing Emacs on Windows? +@cindex mailing lists +@cindex help, mailing lists + +The official mailing list for Windows specific help and discussion is +@url{http://lists.gnu.org/mailman/listinfo/help-emacs-windows, +help-emacs-windows}. See that link for information on how to subscribe +or unsubscribe. The +@uref{http://lists.gnu.org/archive/html/help-emacs-windows/, list archives} +are available online. + +@c ------------------------------------------------------------ +@node Indexes +@unnumbered Indexes + +@unnumberedsec Function and Variable Index + +@printindex fn + +@unnumberedsec Concept Index + +@printindex cp + +@bye diff --git a/doc/misc/faq.texi b/doc/misc/efaq.texi index 1354f68cc9f..6557f4d017b 100644 --- a/doc/misc/faq.texi +++ b/doc/misc/efaq.texi @@ -1,7 +1,8 @@ \input texinfo @c -*- mode: texinfo; -*- @c %**start of header -@setfilename ../../info/efaq +@setfilename ../../info/efaq.info @settitle GNU Emacs FAQ +@include docstyle.texi @c %**end of header @include emacsver.texi @@ -11,7 +12,7 @@ @c appreciate a notice if you do). @copying -Copyright @copyright{} 2001--2013 Free Software Foundation, Inc.@* +Copyright @copyright{} 2001--2015 Free Software Foundation, Inc.@* Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 Reuven M. Lerner@* Copyright @copyright{} 1992, 1993 Steven Byrnes@* @@ -391,12 +392,9 @@ recipients the same freedom that you enjoyed. @cindex Posting messages to newsgroups @cindex GNU mailing lists -The file @file{etc/MAILINGLISTS} describes the purpose of each GNU -mailing list (@pxref{Informational files for Emacs}). For those lists -which are gatewayed with newsgroups, it lists both the newsgroup name -and the mailing list address. The Emacs mailing lists are also -described at @uref{http://savannah.gnu.org/mail/?group=emacs, the Emacs -Savannah page}. +The Emacs mailing lists are described at +@uref{http://savannah.gnu.org/mail/?group=emacs, the Emacs Savannah +page}. Some of them are gatewayed to newsgroups. The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs in general. The newsgroup @uref{news:gnu.emacs.help} is specifically @@ -561,6 +559,9 @@ common) invokes help. Emacs help works best if it is invoked by a single key whose value should be stored in the variable @code{help-char}. +Some Emacs slides and tutorials can be found at +@uref{http://web.psung.name/emacs/}. + @node Learning how to do something @section How do I find out how to do something in Emacs? @cindex Help for Emacs @@ -860,10 +861,7 @@ You can get Tkinfo at @cindex Files included with Emacs @cindex @file{COPYING}, description of file @cindex @file{DISTRIB}, description of file -@cindex @file{GNU}, description of file -@cindex @file{INTERVIEW}, description of file @cindex @file{MACHINES}, description of file -@cindex @file{MAILINGLISTS}, description of file @cindex @file{NEWS}, description of file This isn't a frequently asked question, but it should be! A variety of @@ -884,19 +882,9 @@ GNU General Public License @item DISTRIB Emacs Availability Information -@item GNU -The GNU Manifesto - -@item INTERVIEW -Richard Stallman discusses his public-domain UNIX-compatible software -system with BYTE editors - @item MACHINES Status of Emacs on Various Machines and Systems -@item MAILINGLISTS -GNU Project Electronic Mailing Lists - @item NEWS Emacs news, a history of recent user-visible changes @@ -994,10 +982,8 @@ version; three components indicate a development version (e.g., @samp{23.0.50} is what will eventually become @samp{23.1}). Emacs is under active development, hosted at -@uref{http://savannah.gnu.org/projects/emacs/, Savannah}. The source -code can be retrieved anonymously following the -@uref{http://savannah.gnu.org/bzr/?group=emacs, instructions}. -The repository is GNU Bazaar. +@uref{http://savannah.gnu.org/projects/emacs/, Savannah}. +Follow the instructions given there to clone the project repository. Because Emacs undergoes many changes before a release, the version number of a development version is not especially meaningful. It is @@ -1483,7 +1469,7 @@ machine at which Emacs was invoked. This is done by setting @code{frame-title-format} to the default value of @lisp -(multiple-frames "%b" ("" invocation-name "@@" system-name)) +(multiple-frames "%b" ("" invocation-name "@@" (system-name))) @end lisp To modify the behavior such that frame titlebars contain the buffer's @@ -1586,10 +1572,9 @@ According to the documentation string for @code{delete-selection-mode} delete-selection-mode @key{RET}}): @quotation -When Delete Selection mode is enabled, Transient Mark mode is also -enabled and typed text replaces the selection if the selection is -active. Otherwise, typed text is just inserted at point regardless of -any selection. +When Delete Selection mode is enabled, typed text replaces the selection +if the selection is active. Otherwise, typed text is just inserted at +point regardless of any selection. @end quotation This mode also allows you to delete (not kill) the highlighted region by @@ -1957,7 +1942,7 @@ automatically scrolls the display horizontally when point moves off the left or right edge of the window. Note that this is overridden by the variable -@code{truncate-partial-width-windows} if that variable is non-nil +@code{truncate-partial-width-windows} if that variable is non-@code{nil} and the current buffer is not full-frame width. In Emacs 20, use @code{hscroll-mode}. @@ -2104,8 +2089,8 @@ parenthesis, it simply inserts a % like normal. (defun match-paren (arg) "Go to the matching paren if on a paren; otherwise insert %." (interactive "p") - (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1)) - ((looking-at "\\s\)") (forward-char 1) (backward-list 1)) + (cond ((looking-at "\\s(") (forward-list 1) (backward-char 1)) + ((looking-at "\\s)") (forward-char 1) (backward-list 1)) (t (self-insert-command (or arg 1))))) @end lisp @@ -2419,12 +2404,12 @@ printed an error message? If so, compiling from within Emacs using the @kbd{M-x compile} and @kbd{M-x recompile} commands is a much more effective way of doing that. Emacs automatically intercepts the compile error messages, inserts them into a special buffer called -@code{*compilation*}, and lets you visit the locus of each message in +@file{*compilation*}, and lets you visit the locus of each message in the source. Type @kbd{C-x `} to step through the offending lines one by one (starting with Emacs 22, you can also use @kbd{M-g M-p} and @kbd{M-g M-n} to go to the previous and next matches directly). Click @kbd{Mouse-2} or press @key{RET} on a message text in the -@code{*compilation*} buffer to go to the line whose number is mentioned +@file{*compilation*} buffer to go to the line whose number is mentioned in that message. But if you indeed need to go to a certain text line, type @kbd{M-g M-g} @@ -2689,12 +2674,20 @@ variable in the environment. @cindex Maximize frame @cindex Fullscreen mode -Use the function @code{w32-send-sys-command}. For example, you can -put the following in your @file{.emacs} file: +Beginning with Emacs 24.4 either run Emacs with the @samp{--maximized} +command-line option or put the following form in your @file{.emacs} +file: @lisp -(add-hook 'term-setup-hook - #'(lambda () (w32-send-sys-command ?\xF030))) +(add-hook 'emacs-startup-hook 'toggle-frame-maximized) +@end lisp + +With older versions use the function @code{w32-send-sys-command}. For +example, you can put the following in your @file{.emacs} file: + +@lisp +(add-hook 'emacs-startup-hook + (lambda () (w32-send-sys-command ?\xF030))) @end lisp To avoid the slightly distracting visual effect of Emacs starting with @@ -2746,7 +2739,7 @@ type @kbd{C-h C-p} to read it. Old versions (i.e., anything before 19.29) of Emacs had problems editing files larger than 8 megabytes. In versions 19.29 and later, the maximum -buffer size is at least 2^27@minus{}1, or 134,217,727 bytes, or 132 MBytes. +buffer size is at least @math{2^{27}-1}, or 134,217,727 bytes, or 132 MBytes. The maximum buffer size on 32-bit machines increased to 256 MBytes in Emacs 22, and again to 512 MBytes in Emacs 23.2. @@ -2861,8 +2854,7 @@ To make a terminfo entry for @samp{emacs}, use @code{tic} or @file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}. Having a termcap/terminfo entry will not enable the use of full screen -programs in shell buffers. Use @kbd{M-x terminal-emulator} for that -instead. +programs in shell buffers. Use @kbd{M-x term} for that instead. A workaround to the problem of missing termcap/terminfo entries is to change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown} @@ -3278,8 +3270,8 @@ archive sites that make GNU software available. First of all, you should check to make sure that the package isn't already available. For example, typing @kbd{M-x apropos @key{RET} -wordstar @key{RET}} lists all functions and variables containing the -string @samp{wordstar}. +python @key{RET}} lists all functions and variables containing the +string @samp{python}. It is also possible that the package is on your system, but has not been loaded. To see which packages are available for loading, look through @@ -3295,6 +3287,7 @@ the constituent Emacs packages. For advice on how to find extra packages that are not part of Emacs, see @ref{Packages that do not come with Emacs}. +@c Note that M-x view-external-packages references this node. @node Packages that do not come with Emacs @section Where can I get Emacs Lisp packages that don't come with Emacs? @cindex Unbundled packages @@ -3304,31 +3297,41 @@ see @ref{Packages that do not come with Emacs}. @cindex Emacs Lisp List @cindex Emacs Lisp Archive -Your first port of call should be the @kbd{M-x list-packages} command. -This connects to the @uref{http:///elpa.gnu.org, GNU ELPA} (``Emacs -Lisp Package Archive'') server and fetches the list of additional -packages that it offers. These are GNU packages that are available -for use with Emacs, but are distributed separately. Select a package -to get more details about the features that it offers, and then if you -wish, Emacs can download and automatically install it for you. - -@uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs Lisp -List (ELL)}, maintained by Stephen Eglen, -aims to provide one compact list with links to all of the current Emacs -Lisp files on the Internet. The ELL can be browsed over the web, or -from Emacs with @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.el, -the @file{ell} package}. - -Many authors post their packages to the @uref{news:gnu.emacs.sources, -Emacs sources newsgroup}. You can search the archives of this -group with @uref{http://groups.google.com/group/gnu.emacs.sources, Google}, -or @uref{http://dir.gmane.org/gmane.emacs.sources, Gmane}, for example. - -Several packages are stored in -@uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}. - -Read the file @file{etc/MORE.STUFF} for more information about -external packages. +The easiest way to add more features to your Emacs is to use the +command @kbd{M-x list-packages}. This contacts the +@uref{http:///elpa.gnu.org, GNU ELPA} (``Emacs Lisp Package Archive'') +server and fetches the list of additional packages that it offers. +These are GNU packages that are available for use with Emacs, but are +distributed separately from Emacs itself, for reasons of space, etc. +You can browse the resulting @file{*Packages*} buffer to see what is +available, and then Emacs can automatically download and install the +packages that you select. @xref{Packages,,, emacs, The GNU Emacs Manual}. + +There are other, non-GNU, Emacs Lisp package servers, including: +@uref{http://melpa.milkbox.net, MELPA}; and +@uref{http://marmalade-repo.org, Marmalade}. To use additional +package servers, customize the @code{package-archives} variable. +Be aware that installing a package can run arbitrary code, so only add +sources that you trust. + +The @uref{https://lists.gnu.org/mailman/listinfo/gnu-emacs-sources, +GNU Emacs sources mailing list}, which is gatewayed to the +@uref{news:gnu.emacs.sources, Emacs sources newsgroup} (although the +connection between the two can be unreliable) is an official place +where people can post or announce their extensions to Emacs. + +The @uref{http://emacswiki.org, Emacs Wiki} contains pointers to some +additional extensions. @uref{http://wikemacs.org, WikEmacs} is an +alternative wiki for Emacs. + +@uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs +Lisp List (ELL)}, has pointers to many Emacs Lisp files, but at time +of writing it is no longer being updated. + +It is impossible for us to list here all the sites that offer Emacs +Lisp packages. If you are interested in a specific feature, then +after checking Emacs itself and GNU ELPA, a web search is often the +best way to find results. @node Spell-checkers @section Spell-checkers @@ -3452,8 +3455,9 @@ lack certain features, such as the Emacs Lisp extension language. @cindex Emacs for MS-Windows @cindex Microsoft Windows, Emacs for -There is a @uref{http://www.gnu.org/software/emacs/windows/ntemacs.html, -separate FAQ} for Emacs on MS-Windows. For MS-DOS, @pxref{Emacs for MS-DOS}. +There is a separate FAQ for Emacs on MS-Windows, +@pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}. +For MS-DOS, @pxref{Emacs for MS-DOS}. @node Emacs for GNUstep @@ -3592,12 +3596,12 @@ been executed but is not, then you will experience this problem (this code/file execution order is not enforced after startup). To postpone the execution of Emacs Lisp code until after terminal or -window-system setup, treat the code as a @dfn{lambda list} and set the -value of either the @code{term-setup-hook} or @code{window-setup-hook} -variable to this lambda function. For example, +window-system setup, treat the code as a @dfn{lambda list} and add it to +@code{emacs-startup-hook} (or @code{tty-setup-hook} in Emacs 24.4 and +newer). For example, @lisp -(add-hook 'term-setup-hook +(add-hook 'emacs-startup-hook (lambda () (when (string-match "\\`vt220" (or (getenv "TERM") "")) ;; Make vt220's "Do" key behave like M-x: @@ -3666,7 +3670,7 @@ for deleting the previous character outside of Emacs. On many Unix systems, this command will remap @key{DEL}: @example -stty erase `^?' +stty erase '^?' @end example @item @@ -3762,8 +3766,8 @@ You can swap two keys (or key sequences) by using the into @key{DEL} and @key{DEL} to @kbd{C-h}, use @lisp -(keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL -(keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'. +(keyboard-translate ?\C-h ?\C-?) ; translate 'C-h' to DEL +(keyboard-translate ?\C-? ?\C-h) ; translate DEL to 'C-h'. @end lisp @noindent @@ -4194,7 +4198,6 @@ fontset, or you can select it by setting the default font in your * Replying to the sender of a message:: * Automatically starting a mail or news reader:: * Reading news with Emacs:: -* Gnus does not work with NNTP:: * Making Gnus faster:: * Catching up in all newsgroups:: @end menu @@ -4388,27 +4391,6 @@ Manual, gnus, The Gnus Manual}, which includes @ref{Frequently Asked Questions,, the Gnus FAQ, gnus, The Gnus Manual}. -@node Gnus does not work with NNTP -@section Why doesn't Gnus work via NNTP? -@cindex Gnus and NNTP -@cindex NNTP, Gnus fails to work with - -There is a bug in NNTP version 1.5.10, such that when multiple requests -are sent to the NNTP server, the server only handles the first one -before blocking waiting for more input which never comes. NNTP version -1.5.11 claims to fix this. - -You can work around the bug inside Emacs like this: - -@lisp -(setq nntp-maximum-request 1) -@end lisp - -You can find out what version of NNTP your news server is running by -telnetting to the NNTP port (usually 119) on the news server machine -(i.e., @kbd{telnet server-machine 119}). The server should give its -version number in the welcome message. Type @kbd{quit} to get out. - @node Making Gnus faster @section How do I make Gnus faster? @cindex Faster, starting Gnus diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index e199417aa9d..fb4e1470016 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -1,8 +1,9 @@ \input texinfo -@setfilename ../../info/eieio +@setfilename ../../info/eieio.info @set TITLE Enhanced Implementation of Emacs Interpreted Objects @set AUTHOR Eric M. Ludlam @settitle @value{TITLE} +@include docstyle.texi @c ************************************************************************* @c @ Header @@ -11,13 +12,13 @@ @copying This manual documents EIEIO, an object framework for Emacs Lisp. -Copyright @copyright{} 2007--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2015 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,'' +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.'' @@ -35,15 +36,16 @@ modify this GNU manual.'' @center @titlefont{@value{TITLE}} @sp 4 @center by @value{AUTHOR} -@end titlepage @page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage @macro eieio{} @i{EIEIO} @end macro -@node Top, Quick Start, (dir), (dir) -@comment node-name, next, previous, up +@node Top @top EIEIO @eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') @@ -70,7 +72,6 @@ framework for writing object-oriented applications in Emacs. * Base Classes:: Additional classes you can inherit from. * Browsing:: Browsing your class lists. * Class Values:: Displaying information about a class or object. -* Documentation:: Automatically creating texinfo documentation. * Default Superclass:: The root superclasses. * Signals:: When you make errors. * Naming Conventions:: Name your objects in an Emacs friendly way. @@ -139,13 +140,13 @@ constructor. The constructor is a function with the same name as your class which returns a new instance of that class. Here is an example: @example -(setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555")) +(setq rec (record :name "Eric" :birthday "June" :phone "555-5555")) @end example @noindent -The first argument is the name given to this instance. Each instance -is given a name, so different instances can be easily distinguished -when debugging. +For backward compatibility reasons, the first argument can be a string (a name +given to this instance). Each instance used to be given a name, so different +instances could be easily distinguished when debugging. It can be a bit repetitive to also have a :name slot. To avoid doing this, it is sometimes handy to use the base class @code{eieio-named}. @@ -173,12 +174,19 @@ some other data type, Emacs signals a @code{no-method-definition} error. @ref{Signals}. @node Introduction -@comment node-name, next, previous, up @chapter Introduction -Due to restrictions in the Emacs Lisp language, CLOS cannot be -completely supported, and a few functions have been added in place of -setf. +First off, please note that this manual cannot serve as a complete +introduction to object oriented programming and generic functions in +LISP@. Although EIEIO is not a complete implementation of the Common +Lisp Object System (CLOS) and also differs from it in several aspects, +it follows the same basic concepts. Therefore, it is highly +recommended to learn those from a textbook or tutorial first, +especially if you only know OOP from languages like C++ or Java. If +on the other hand you are already familiar with CLOS, you should be +aware that @eieio{} does not implement the full CLOS specification and +also differs in some other aspects which are mentioned below (also +@pxref{CLOS compatibility}). @eieio{} supports the following features: @@ -210,7 +218,10 @@ Public and private classifications for slots (extensions to CLOS) Customization support in a class (extension to CLOS) @end enumerate -Here are some important CLOS features that @eieio{} presently lacks: +Due to restrictions in the Emacs Lisp language, CLOS cannot be +completely supported, and a few functions have been added in place of +setf. Here are some important CLOS features that @eieio{} presently +lacks: @table @asis @@ -222,10 +233,9 @@ first argument, and this one must be an @eieio{} type. @item Support for metaclasses There is just one default metaclass, @code{eieio-default-superclass}, and you cannot define your own. The @code{:metaclass} tag in -@code{defclass} is ignored. Also, functions like `class-of' and -`find-class', which should return instances of the metaclass, behave -differently in @eieio{} in that they return symbols or plain structures -instead. +@code{defclass} is ignored. Also, functions like @code{find-class}, which +should return instances of the metaclass, behave differently in +@eieio{} in that they return symbols or plain structures instead. @item EQL specialization EIEIO does not support it. @@ -234,7 +244,7 @@ EIEIO does not support it. This CLOS method tag is non-functional. @item :default-initargs in @code{defclass} -Each slot has an @code{:initarg} tag, so this is not really necessary. +Each slot can have an @code{:initform} tag, so this is not really necessary. @item Mock object initializers Each class contains a mock object used for fast initialization of @@ -245,20 +255,8 @@ should use a deep copy but currently does not. @end table @node Building Classes -@comment node-name, next, previous, up @chapter Building Classes -First off, please note that this manual cannot serve as a complete -introduction to object oriented programming and generic functions in -LISP. Although EIEIO is not a complete CLOS implementation and also -differs from CLOS in several aspects, it follows the same basic -concepts. Therefore, it is highly recommended to learn these from a -textbook or tutorial first, especially if you only know OOP from -languages like C++ or Java. If on the other hand you are already -familiar with CLOS, you should be aware that @eieio{} does not implement -the full CLOS specification and also differs in some other aspects -(@xref{Introduction}, and @ref{CLOS compatibility}). - A @dfn{class} is a definition for organizing data and methods together. An @eieio{} class has structures similar to the classes found in other object-oriented (OO) languages. @@ -268,10 +266,9 @@ To create a new class, use the @code{defclass} macro: @defmac defclass class-name superclass-list slot-list &rest options-and-doc Create a new class named @var{class-name}. The class is represented -by a self-referential symbol with the name @var{class-name}. @eieio{} -stores the structure of the class as a symbol property of -@var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp -Reference Manual}). +by a symbol with the name @var{class-name}. @eieio{} stores the structure of +the class as a symbol property of @var{class-name} (@pxref{Symbol +Components,,,elisp,GNU Emacs Lisp Reference Manual}). The @var{class-name} symbol's variable documentation string is a modified version of the doc string found in @var{options-and-doc}. @@ -294,21 +291,16 @@ or @code{:protection}. @end defmac @noindent -Whenever defclass is used to create a new class, two predicates are -created for it, named @code{@var{CLASS-NAME}-p} and -@code{@var{CLASS-NAME}-child-p}: +Whenever defclass is used to create a new class, a predicate is +created for it, named @code{@var{CLASS-NAME}-p}: @defun CLASS-NAME-p object -Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}. -@end defun - -@defun CLASS-NAME-child-p object -Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}, -or is of a subclass of @var{CLASS-NAME}. +Return non-@code{nil} if and only if @var{OBJECT} is of the class +@var{CLASS-NAME}. @end defun @defvar eieio-error-unsupported-class-tags -If non-nil, @code{defclass} signals an error if a tag in a slot +If non-@code{nil}, @code{defclass} signals an error if a tag in a slot specifier is unsupported. This option is here to support programs written with older versions of @@ -420,7 +412,7 @@ Valid tags are: @table @code @item :initarg A symbol that can be used in the argument list of the constructor to -specify a value for the new instance being created. +specify a value for this slot of the new instance being created. A good symbol to use for initarg is one that starts with a colon @code{:}. @@ -430,13 +422,13 @@ The slot specified like this: @end example could then be initialized to the number 1 like this: @example - (myobject "name" :myslot 1) + (myobject :myslot 1) @end example @xref{Making New Objects}. @item :initform -A expression used as the default value for this slot. +An expression used as the default value for this slot. If @code{:initform} is left out, that slot defaults to being unbound. It is an error to reference an unbound slot, so if you need @@ -447,19 +439,13 @@ Use @code{slot-boundp} to test if a slot is unbound (@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to being unbound after giving it a value (@pxref{Accessing Slots}). -The value passed to initform is automatically quoted. Thus, +The value passed to initform used to be automatically quoted. Thus, @example :initform (1 2 3) @end example -appears as the specified list in the default object. -A symbol that is a function like this: -@example -:initform + -@end example -will set the initial value as that symbol. - -After a class has been created with @code{defclass}, you can change -that default value with @code{oset-default}. @ref{Accessing Slots}. +will use the list as a value. This is incompatible with CLOS (which would +signal an error since 1 is not a valid function) and will likely change in the +future, so better quote your initforms if they're just values. @item :type An unquoted type specifier used to validate data set into this slot. @@ -473,7 +459,7 @@ Here are some examples: @item my-class-name An object of your class type. @item (or null symbol) - A symbol, or nil. + A symbol, or @code{nil}. @end table @item :allocation @@ -540,10 +526,15 @@ to quote the symbol. If you wanted to run a function on load, you can output the code to do the construction of the value. @item :protection +This is an old option that is not supported any more. + When using a slot referencing function such as @code{slot-value}, and the value behind @var{slot} is private or protected, then the current scope of operation must be within a method of the calling object. +This protection is not enforced by the code any more, so it's only useful +as documentation. + Valid values are: @table @code @@ -575,7 +566,7 @@ prefixed by the @code{:documentation} tag, and appears after the list of slots, and before the options. @item :allow-nil-initform -If this option is non-nil, and the @code{:initform} is @code{nil}, but +If this option is non-@code{nil}, and the @code{:initform} is @code{nil}, but the @code{:type} is specifies something such as @code{string} then allow this to pass. The default is to have this option be off. This is implemented as an alternative to unbound slots. @@ -612,7 +603,7 @@ This is the default. @item :depth-first Search for methods in the class hierarchy in a depth first order. @item :c3 -Searches for methods in in a linearized way that most closely matches +Searches for methods in a linearized way that most closely matches what CLOS does when a monotonic class structure is defined. @end table @@ -632,7 +623,6 @@ function of @code{:initform}. @eieio{}-specific tags. @node Making New Objects -@comment node-name, next, previous, up @chapter Making New Objects Suppose we have a simple class is defined, such as: @@ -647,7 +637,7 @@ It is now possible to create objects of that class type. Calling @code{defclass} has defined two new functions. One is the constructor @var{record}, and the other is the predicate, -@var{record-p}. +@var{record}-p. @defun record object-name &rest slots @@ -667,7 +657,7 @@ can do any valid Lispy thing you want with it, such as Example of creating an object from a class: @example -(record "test" :value 3 :reference nil) +(record :value 3 :reference nil) @end example @end defun @@ -690,19 +680,9 @@ for each slot. For example: (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN) @end example -Compatibility note: - -If the first element of @var{initargs} is a string, it is used as the -name of the class. - -In @eieio{}, the class' constructor requires a name for use when printing. -@dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the -class is used as the name slot instead when @var{initargs} doesn't start with -a string. @end defun @node Accessing Slots -@comment node-name, next, previous, up @chapter Accessing Slots There are several ways to access slot values in an object. The naming @@ -716,14 +696,9 @@ This macro sets the value behind @var{slot} to @var{value} in @end defmac @defmac oset-default class slot value -This macro sets the @code{:initform} for @var{slot} in @var{class} to +This macro sets the value for the class-allocated @var{slot} in @var{class} to @var{value}. -This allows the user to set both public and private defaults after the -class has been constructed, and provides a way to configure the -default behavior of packages built with classes (the same way -@code{setq-default} does for buffer-local variables). - For example, if a user wanted all @code{data-objects} (@pxref{Building Classes}) to inform a special object of his own devising when they changed, this can be arranged by simply executing this bit of code: @@ -736,16 +711,12 @@ changed, this can be arranged by simply executing this bit of code: @defmac oref obj slot @anchor{oref} Retrieve the value stored in @var{obj} in the slot named by @var{slot}. -Slot is the name of the slot when created by @dfn{defclass} or the label -created by the @code{:initarg} tag. +Slot is the name of the slot when created by @dfn{defclass}. @end defmac -@defmac oref-default obj slot +@defmac oref-default class slot @anchor{oref-default} -Gets the default value of @var{obj} (maybe a class) for @var{slot}. -The default value is the value installed in a class with the @code{:initform} -tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg} -tag in the @dfn{defclass} call. +Get the value of the class-allocated @var{slot} from @var{class}. @end defmac The following accessors are defined by CLOS to reference or modify @@ -759,8 +730,8 @@ Unlike @code{oref}, the symbol for @var{slot} must be quoted. @defun set-slot-value object slot value @anchor{set-slot-value} -This is not a CLOS function, but is meant to mirror @code{slot-value} if -you don't want to use the cl package's @code{setf} function. This +This is not a CLOS function, but is the setter for @code{slot-value} +used by the @code{setf} macro. This function sets the value of @var{slot} from @var{object}. Unlike @code{oset}, the symbol for @var{slot} must be quoted. @end defun @@ -794,7 +765,7 @@ This establishes a lexical environment for referring to the slots in the instance named by the given slot-names as though they were variables. Within such a context the value of the slot can be specified by using its slot name, as if it were a lexically bound -variable. Both setf and setq can be used to set the value of the +variable. Both @code{setf} and @code{setq} can be used to set the value of the slot. @var{spec-list} is of a form similar to @dfn{let}. For example: @@ -811,7 +782,7 @@ Where each @var{var} is the local variable given to the associated variable name of the same name as the slot. @example -(defclass myclass () (x :initarg 1)) +(defclass myclass () (x :initform 1)) (setq mc (make-instance 'myclass)) (with-slots (x) mc x) => 1 (with-slots ((something x)) mc something) => 1 @@ -819,7 +790,6 @@ variable name of the same name as the slot. @end defun @node Writing Methods -@comment node-name, next, previous, up @chapter Writing Methods Writing a method in @eieio{} is similar to writing a function. The @@ -986,15 +956,14 @@ allows the first argument to be cast. @section Static Methods Static methods do not depend on an object instance, but instead -operate on an object's class. You can create a static method by using +operate on a class. You can create a static method by using the @code{:static} key with @code{defmethod}. -Do not treat the first argument of a @code{:static} method as an -object unless you test it first. Use the functions -@code{oref-default} or @code{oset-default} which will work on a class, -or on the class of an object. +The first argument of a @code{:static} method will be a class rather than an +object. Use the functions @code{oref-default} or @code{oset-default} which +will work on a class. -A Class' @code{constructor} method is defined as a @code{:static} +A class's @code{make-instance} method is defined as a @code{:static} method. @b{Note:} The @code{:static} keyword is unique to @eieio{}. @@ -1027,8 +996,8 @@ This is the default. @item :depth-first Search for methods in the class hierarchy in a depth first order. @item :c3 -Searches for methods in in a linearized way that most closely matches -what CLOS does when CLOS when a monotonic class structure is defined. +Searches for methods in a linearized way that most closely matches +what CLOS does when a monotonic class structure is defined. This is derived from the Dylan language documents by Kim Barrett et al.: A Monotonic Superclass Linearization for Dylan @@ -1036,7 +1005,6 @@ Retrieved from: http://192.220.96.201/dylan/linearization-oopsla96.html @end table @node Predicates -@comment node-name, next, previous, up @chapter Predicates and Utilities Now that we know how to create classes, access slots, and define @@ -1069,7 +1037,7 @@ make a slot unbound. @var{object} can be an instance or a class. @end defun -@defun class-name class +@defun eieio-class-name class Return a string of the form @samp{#<class myclassname>} which should look similar to other Lisp objects like buffers and processes. Printing a class results only in a symbol. @@ -1086,14 +1054,7 @@ For example: Will fetch the documentation string for @code{eieio-default-superclass}. @end defun -@defun class-constructor class -Return a symbol used as a constructor for @var{class}. The -constructor is a function used to create new instances of -@var{CLASS}. This function provides a way to make an object of a class -without knowing what it is. This is not a part of CLOS. -@end defun - -@defun object-name obj +@defun eieio-object-name obj Return a string of the form @samp{#<object-class myobjname>} for @var{obj}. This should look like Lisp symbols from other parts of Emacs such as buffers and processes, and is shorter and cleaner than printing the @@ -1102,43 +1063,34 @@ and object's print form, as this allows the object to add extra display information into the symbol. @end defun -@defun object-class obj +@defun eieio-object-class obj Returns the class symbol from @var{obj}. @end defun -@defun class-of obj -CLOS symbol which does the same thing as @code{object-class} -@end defun - -@defun object-class-fast obj -Same as @code{object-class} except this is a macro, and no -type-checking is performed. -@end defun - -@defun object-class-name obj +@defun eieio-object-class-name obj Returns the symbol of @var{obj}'s class. @end defun -@defun class-parents class +@defun eieio-class-parents class Returns the direct parents class of @var{class}. Returns @code{nil} if it is a superclass. @end defun -@defun class-parents-fast class -Just like @code{class-parent} except it is a macro and no type checking +@defun eieio-class-parents-fast class +Just like @code{eieio-class-parents} except it is a macro and no type checking is performed. @end defun -@defun class-parent class +@defun eieio-class-parent class Deprecated function which returns the first parent of @var{class}. @end defun -@defun class-children class +@defun eieio-class-children class Return the list of classes inheriting from @var{class}. @end defun -@defun class-children-fast class -Just like @code{class-children}, but with no checks. +@defun eieio-class-children-fast class +Just like @code{eieio-class-children}, but with no checks. @end defun @defun same-class-p obj class @@ -1197,7 +1149,6 @@ all its subclasses. @end defun @node Customizing -@comment node-name, next, previous, up @chapter Customizing Objects @eieio{} supports the Custom facility through two new widget types. @@ -1273,13 +1224,12 @@ Return the list of public slots for @var{obj}. @end defun @defun class-slot-initarg class slot -For the given @var{class} return the :initarg associated with +For the given @var{class} return an :initarg associated with @var{slot}. Not all slots have initargs, so the return value can be -nil. +@code{nil}. @end defun @node Base Classes -@comment node-name, next, previous, up @chapter Base Classes All defined classes, if created with no specified parent class, @@ -1301,7 +1251,6 @@ even inherit from more than one of these classes at once.) @end menu @node eieio-instance-inheritor -@comment node-name, next, previous, up @section @code{eieio-instance-inheritor} This class is defined in the package @file{eieio-base}. @@ -1366,7 +1315,6 @@ list of objects to be searched. @end deffn @node eieio-singleton -@comment node-name, next, previous, up @section @code{eieio-singleton} This class is defined in the package @file{eieio-base}. @@ -1378,7 +1326,6 @@ only ever be one instance of this class. Multiple calls to @end deftp @node eieio-persistent -@comment node-name, next, previous, up @section @code{eieio-persistent} This class is defined in the package @file{eieio-base}. @@ -1430,7 +1377,6 @@ being pedantic. @end defun @node eieio-named -@comment node-name, next, previous, up @section @code{eieio-named} This class is defined in the package @file{eieio-base}. @@ -1442,7 +1388,6 @@ access to it. @end deftp @node eieio-speedbar -@comment node-name, next, previous, up @section @code{eieio-speedbar} This class is in package @file{eieio-speedbar}. @@ -1537,7 +1482,6 @@ on how speedbar modes work @end deffn @node Browsing -@comment node-name, next, previous, up @chapter Browsing class trees The command @kbd{M-x eieio-browse} displays a buffer listing all the @@ -1560,63 +1504,15 @@ Note: new classes are consed into the inheritance lists, so the tree comes out upside-down. @node Class Values -@comment node-name, next, previous, up @chapter Class Values -Details about any class or object can be retrieved using the function -@code{eieio-describe-class}. Interactively, type in the name of -a class. In a program, pass it a string with the name of a class, a -class symbol, or an object. The resulting buffer will display all slot -names. - -Additionally, all methods defined to have functionality on this class is -displayed. - -@node Documentation -@comment node-name, next, previous, up -@chapter Documentation - -It is possible to automatically create documentation for your classes in -texinfo format by using the tools in the file @file{eieio-doc.el} - -@deffn Command eieiodoc-class class indexstring &optional skiplist - -This will start at the current point, and create an indented menu of -all the child classes of, and including @var{class}, but skipping any -classes that might be in @var{skiplist}. It will then create nodes for -all these classes, subsection headings, and indexes. - -Each class will be indexed using the texinfo labeled index -@var{indexstring} which is a two letter description. -@xref{New Indices,,,texinfo,Texinfo manual}. - -To use this command, the texinfo macro - -@example -@@defindex @@var @{ indexstring @} -@end example - -@noindent -where @var{indexstring} is replaced with the two letter code. - -Next, an inheritance tree will be created listing all parents of that -section's class. - -Then, all the slots will be expanded in tables, and described -using the documentation strings from the code. Default values will also -be displayed. Only those slots with @code{:initarg} specified will be -expanded, others will be hidden. If a slot is inherited from a parent, -that slot will also be skipped unless the default value is different. -If there is a change, then the documentation part of the slot will be -replace with an @@xref back to the parent. - -This command can only display documentation for classes whose -definitions have been loaded in this Emacs session. - -@end deffn +You can use the normal @code{describe-function} command to retrieve +information about a class. Running it on constructors will show a +full description of the generated class. If you call it on a generic +function, all implementations of that generic function will be listed, +together with links through which you can directly jump to the source. @node Default Superclass -@comment node-name, next, previous, up @chapter Default Superclass All defined classes, if created with no specified parent class, will @@ -1625,7 +1521,6 @@ inherit from a special class stored in with it, certain default methods or attributes can be added to all objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that symbol is an alias to @code{eieio-default-superclass}. -@refill Currently, the default superclass is defined as follows: @@ -1674,7 +1569,7 @@ is a list of name/value pairs. These are actually just passed to Sets slots of @var{obj} with @var{slots} which is a list of name/value pairs. -This is called from the default @code{constructor}. +This is called from the default constructor. @end defun @node Basic Methods @@ -1692,9 +1587,9 @@ sure to call @dfn{call-next-method} first and modify the returned object. @defun object-print this &rest strings @anchor{object-print} -Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}. +Pretty printer for object @var{this}. Call function @dfn{eieio-object-name} with @var{strings}. The default method for printing object @var{this} is to use the -function @dfn{object-name}. +function @dfn{eieio-object-name}. It is sometimes useful to put a summary of the object into the default #<notation> string when using eieio browsing tools. @@ -1793,7 +1688,6 @@ return value of @dfn{call-next-method}. @end defun @node Signals -@comment node-name, next, previous, up @chapter Signals There are new condition names (signals) that can be caught when using @@ -1838,7 +1732,6 @@ This signal is called when an attempt to reference @var{slot} in @end deffn @node Naming Conventions -@comment node-name, next, previous, up @chapter Naming Conventions @xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference @@ -1867,7 +1760,6 @@ must ``require'' that library with the @code{require} command. @end itemize @node CLOS compatibility -@comment node-name, next, previous, up @chapter CLOS compatibility Currently, the following functions should behave almost as expected from @@ -1896,7 +1788,7 @@ It therefore has the same issues as that package. Extensions include the ability to provide object names. @end table -Defclass also supports class options, but does not currently use values +defclass also supports class options, but does not currently use values of @code{:metaclass}, and @code{:default-initargs}. @item make-instance @@ -1920,16 +1812,11 @@ for the given object. This is different than that found in CLOS because in @eieio{} this function accepts replacement arguments. This permits subclasses to modify arguments as they are passed up the tree. If no arguments are given, the expected CLOS behavior is used. -@item setf -If the common-lisp subsystem is loaded, the setf parameters are also -loaded so the form @code{(setf (slot-value object slot) t)} should -work. @end table -CLOS supports the @code{describe} command, but @eieio{} only provides -@code{eieio-describe-class}, and @code{eieio-describe-generic}. These -functions are adviced into @code{describe-variable}, and -@code{describe-function}. +CLOS supports the @code{describe} command, but @eieio{} provides +support for using the standard @code{describe-function} command on a +constructor or generic function. When creating a new class (@pxref{Building Classes}) there are several new keywords supported by @eieio{}. diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi index 740dfee41ed..4f6ef010ef3 100644 --- a/doc/misc/emacs-gnutls.texi +++ b/doc/misc/emacs-gnutls.texi @@ -2,19 +2,20 @@ @set VERSION 0.3 -@setfilename ../../info/emacs-gnutls +@setfilename ../../info/emacs-gnutls.info @settitle Emacs GnuTLS Integration @value{VERSION} +@include docstyle.texi @copying This file describes the Emacs GnuTLS integration. -Copyright @copyright{} 2012--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2012--2015 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,'' +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''. @@ -25,7 +26,7 @@ modify this GNU manual.'' @dircategory Emacs network features @direntry -* GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration. +* Emacs GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration. @end direntry @titlepage @@ -93,7 +94,7 @@ There's one way to find out if GnuTLS is available, by calling Zaretskii) in the same directory as Emacs, you should be OK. @defun gnutls-available-p -This function returns t if GnuTLS is available in this instance of Emacs. +This function returns @code{t} if GnuTLS is available in this instance of Emacs. @end defun Oh, but sometimes things go wrong. Budgets aren't balanced, @@ -103,7 +104,7 @@ properly. Well, there's something to be done in the last case. @defvar gnutls-log-level The @code{gnutls-log-level} variable sets the log level. 1 is verbose. 2 is very verbose. 5 is crazy. Crazy! Set it to 1 or 2 -and look in the @code{*Messages*} buffer for the debugging +and look in the @file{*Messages*} buffer for the debugging information. @end defvar @@ -132,6 +133,24 @@ know if you do, so we can make the change to benefit the other users of that platform. @end defvar +@defvar gnutls-verify-error +The @code{gnutls-verify-error} variable allows you to verify SSL/TLS +server certificates for all connections or by host name. It defaults +to @code{nil} for now but will likely be changed to @code{t} later, +meaning that all certificates will be verified. + +There are two checks available currently, that the certificate has +been issued by a trusted authority as defined by +@code{gnutls-trustfiles}, and that the hostname matches the +certificate. @code{t} enables both checks, but you can enable them +individually as well with @code{:trustfiles} and @code{:hostname} +instead. + +Because of the low-level interactions with the GnuTLS library, there +is no way currently to ask if a certificate can be accepted. You have +to look in the @file{*Messages*} buffer. +@end defvar + @defvar gnutls-min-prime-bits The @code{gnutls-min-prime-bits} variable is a pretty exotic customization for cases where you want to refuse handshakes with keys diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 2c0e929e532..3b3df0fa879 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -2,8 +2,9 @@ @include gnus-overrides.texi -@setfilename ../../info/emacs-mime +@setfilename ../../info/emacs-mime.info @settitle Emacs MIME Manual +@include docstyle.texi @synindex fn cp @synindex vr cp @synindex pg cp @@ -11,13 +12,13 @@ @copying This file documents the Emacs MIME interface functionality. -Copyright @copyright{} 1998--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1998--2015 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'', +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''. @@ -27,7 +28,6 @@ modify this GNU manual.'' @end copying @c Node ``Interface Functions'' uses non-ASCII characters -@documentencoding UTF-8 @dircategory Emacs lisp libraries @direntry @@ -405,7 +405,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{gnus-article-html}, @code{w3}, +renderers are selected by the symbols @code{gnus-article-html}, @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 @@ -418,11 +418,11 @@ Some @acronym{HTML} mails might have the trick of spammers using @samp{<img>} tags. It is likely to be intended to verify whether you have read the mail. You can prevent your personal information from leaking by setting this option to @code{nil} (which is the default). -It is currently ignored by Emacs/w3. For emacs-w3m, you may use the -command @kbd{t} on the image anchor to show an image even if it is -@code{nil}.@footnote{The command @kbd{T} will load all images. If you -have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i} -or @kbd{I} instead.} +For emacs-w3m, you may use the command @kbd{t} on the image anchor to +show an image even if it is @code{nil}.@footnote{The command @kbd{T} +will load all images. If you have set the option +@code{w3m-key-binding} to @code{info}, use @kbd{i} or @kbd{I} +instead.} @item mm-w3m-safe-url-regexp @vindex mm-w3m-safe-url-regexp @@ -648,6 +648,12 @@ The @acronym{MIME} type of the part (@code{Content-Type}). Use the contents of the file in the body of the part (@code{Content-Disposition}). +@item recipient-filename +Use this as the file name in the generated @acronym{MIME} message for +the recipient. That is, even if the file is called @file{foo.txt} +locally, use this name instead in the @code{Content-Disposition} in +the sent message. + @item charset The contents of the body of the part are to be encoded in the character set specified (@code{Content-Type}). @xref{Charset Translation}. @@ -1511,7 +1517,7 @@ Here's a bunch of time/date/second/day examples: (date-to-time "Sat Sep 12 12:21:54 1998 +0200") @result{} (13818 19266) -(time-to-seconds '(13818 19266)) +(float-time '(13818 19266)) @result{} 905595714.0 (seconds-to-time 905595714.0) @@ -1583,9 +1589,8 @@ These are the functions available: @item date-to-time Take a date and return a time. -@item time-to-seconds -Take a time and return seconds. Note that Emacs has a built-in -function, @code{float-time}, that does this. +@item float-time +Take a time and return seconds. (This is a built-in function.) @item seconds-to-time Take seconds and return a time. diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi index bdba071be55..3c9aa8ac5e2 100644 --- a/doc/misc/epa.texi +++ b/doc/misc/epa.texi @@ -1,7 +1,8 @@ \input texinfo @c -*- mode: texinfo -*- @c %**start of header -@setfilename ../../info/epa +@setfilename ../../info/epa.info @settitle EasyPG Assistant User's Manual +@include docstyle.texi @c %**end of header @set VERSION 1.0.0 @@ -9,13 +10,13 @@ @copying This file describes EasyPG Assistant @value{VERSION}. -Copyright @copyright{} 2007--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2015 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,'' +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''. @@ -62,6 +63,9 @@ called EasyPG Library. * Caching Passphrases:: * Bug Reports:: * GNU Free Documentation License:: The license for this documentation. +* Key Index:: +* Function Index:: +* Variable Index:: @end menu @node Overview @@ -93,7 +97,7 @@ EasyPG Assistant commands are prefixed by @samp{epa-}. For example, EasyPG Assistant provides several cryptographic features which can be integrated into other Emacs functionalities. For example, automatic -encryption/decryption of @samp{*.gpg} files. +encryption/decryption of @file{*.gpg} files. @node Commands @chapter Commands @@ -157,7 +161,7 @@ Show all keys matched with @var{name} from the private keyring. @end deffn @noindent -In @samp{*Keys*} buffer, several commands are available. The common +In @file{*Keys*} buffer, several commands are available. The common use case is to export some keys to a file. To do that, type @kbd{m} to select keys, type @kbd{o}, and then supply the filename. @@ -338,20 +342,23 @@ Compose a signed message from the current buffer. @kindex @kbd{C-c C-e C-e} @kindex @kbd{C-c C-e e} @findex epa-mail-encrypt +@vindex epa-mail-aliases Compose an encrypted message from the current buffer. By default it tries to build the recipient list from @samp{to}, @samp{cc}, and @samp{bcc} fields of the mail header. To include your key in the recipient list, use @samp{encrypt-to} option in -@file{~/.gnupg/gpg.conf}. +@file{~/.gnupg/gpg.conf}. This function translates recipient +addresses using the @code{epa-mail-aliases} list. You can also +use that option to ignore specific recipients for encryption purposes. @end table @node Encrypting/decrypting gpg files @section Encrypting/decrypting gpg files -By default, every file whose name ends with @samp{.gpg} will be +By default, every file whose name ends with @file{.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, +Similarly, when you save the buffer to a @file{foo.gpg} file, encrypted data is written. The file name pattern for encrypted files can be controlled by @@ -375,7 +382,7 @@ Enable automatic encryption/decryption of *.gpg files. @noindent 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 +instead, do @kbd{M-x epa-file-select-keys}, which pops up the key selection dialog. @deffn Command epa-file-select-keys @@ -396,7 +403,7 @@ which encryption method should be used through @xref{File Variables, , variable for this. @vindex epa-file-encrypt-to -For example, if you want an Elisp file should be encrypted with a +For example, if you want an Elisp file to 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. @@ -485,13 +492,25 @@ collect necessary information to fix the bug, such as: 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 +of the @file{ *epg-debug*} buffer. Note that the first letter of the buffer name is a whitespace. @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi +@node Key Index +@unnumbered Key Index +@printindex ky + +@node Function Index +@unnumbered Function Index +@printindex fn + +@node Variable Index +@unnumbered Variable Index +@printindex vr + @bye @c End: diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index abf0766ee8f..56aea0c3184 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -1,7 +1,8 @@ \input texinfo @c %**start of header -@setfilename ../../info/erc +@setfilename ../../info/erc.info @settitle ERC Manual +@include docstyle.texi @syncodeindex fn cp @include emacsver.texi @c %**end of header @@ -9,13 +10,13 @@ @copying This manual is for ERC as distributed with Emacs @value{EMACSVER}. -Copyright @copyright{} 2005--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2005--2015 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,'' +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''. @@ -149,7 +150,7 @@ then a bunch of other messages that describe the current IRC server. @item Join the #emacs channel -In that buffer, type ``/join SPC #emacs'' and hit @kbd{RET}. Depending +In that buffer, type ``/join @key{SPC} #emacs'' and hit @kbd{RET}. Depending on how you've set up ERC, either a new buffer for ``#emacs'' will be displayed, or a new buffer called ``#emacs'' will be created in the background. If the latter, switch to the ``#emacs'' buffer. You will @@ -265,54 +266,54 @@ This is a summary of keystrokes available in every ERC buffer. @table @kbd -@item C-a or <home> (`erc-bol') +@item C-a or <home> (@code{erc-bol}) Go to beginning of line or end of prompt. -@item RET (`erc-send-current-line') +@item RET (@code{erc-send-current-line}) Send the current line -@item TAB (`erc-complete-word') +@item TAB (@code{erc-complete-word}) If at prompt, complete the current word. Otherwise, move to the next link or button. -@item M-TAB (`ispell-complete-word') +@item M-TAB (@code{ispell-complete-word}) Complete the given word, using ispell. -@item C-c C-a (`erc-bol') +@item C-c C-a (@code{erc-bol}) Go to beginning of line or end of prompt. -@item C-c C-b (`erc-iswitchb') -Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to. +@item C-c C-b (@code{erc-iswitchb}) +Use @code{iswitchb-read-buffer} to prompt for a ERC buffer to switch to. -@item C-c C-c (`erc-toggle-interpret-controls') +@item C-c C-c (@code{erc-toggle-interpret-controls}) Toggle interpretation of control sequences in messages. -@item C-c C-d (`erc-input-action') +@item C-c C-d (@code{erc-input-action}) Interactively input a user action and send it to IRC. -@item C-c C-e (`erc-toggle-ctcp-autoresponse') +@item C-c C-e (@code{erc-toggle-ctcp-autoresponse}) Toggle automatic CTCP replies (like VERSION and PING). -@item C-c C-f (`erc-toggle-flood-control') +@item C-c C-f (@code{erc-toggle-flood-control}) Toggle use of flood control on sent messages. -@item C-c TAB (`erc-invite-only-mode') +@item C-c TAB (@code{erc-invite-only-mode}) Turn on the invite only mode (+i) for the current channel. -@item C-c C-j (`erc-join-channel') +@item C-c C-j (@code{erc-join-channel}) Join channel. If point is at the beginning of a channel name, use that as default. -@item C-c C-k (`erc-go-to-log-matches-buffer') +@item C-c C-k (@code{erc-go-to-log-matches-buffer}) Interactively open an erc-log-matches buffer -@item C-c C-l (`erc-save-buffer-in-logs') +@item C-c C-l (@code{erc-save-buffer-in-logs}) Append buffer contents to the log file, if logging is enabled. -@item C-c C-n (`erc-channel-names') +@item C-c C-n (@code{erc-channel-names}) Run "/names #channel" in the current channel. -@item C-c C-o (`erc-get-channel-mode-from-keypress') +@item C-c C-o (@code{erc-get-channel-mode-from-keypress}) Read a key sequence and call the corresponding channel mode function. After doing @kbd{C-c C-o}, type in a channel mode letter. @@ -320,22 +321,22 @@ After doing @kbd{C-c C-o}, type in a channel mode letter. @kbd{RET} lets you type more than one mode at a time. If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called. If @kbd{k} is pressed, @code{erc-set-channel-key} gets called. -Anything else will be sent to `erc-toggle-channel-mode'. +Anything else will be sent to @code{erc-toggle-channel-mode}. -@item C-c C-p (`erc-part-from-channel') +@item C-c C-p (@code{erc-part-from-channel}) Part from the current channel and prompt for a reason. -@item C-c C-q (`erc-quit-server') +@item C-c C-q (@code{erc-quit-server}) Disconnect from current server after prompting for reason. -@item C-c C-r (`erc-remove-text-properties-region') +@item C-c C-r (@code{erc-remove-text-properties-region}) Clears the region (start,end) in object from all colors, etc. -@item C-c C-t (`erc-set-topic') +@item C-c C-t (@code{erc-set-topic}) Prompt for a topic for the current channel. -@item C-c C-u (`erc-kill-input') -Kill current input line using `erc-bol' followed by `kill-line'. +@item C-c C-u (@code{erc-kill-input}) +Kill current input line using @code{erc-bol} followed by @code{kill-line}. @end table @@ -587,6 +588,16 @@ In the latter case, if the first nick in the list is already in use, other nicks are tried in the list order. @end defopt +@defopt erc-format-nick-function +A function to format a nickname for message display + +You can set this to @code{erc-format-@@nick} to display user mode prefix +@end defopt + +@example +(setq erc-format-nick-function 'erc-format-@@nick) +@end example + @defopt erc-nick-uniquifier The string to append to the nick if it is already in use. @end defopt @@ -656,13 +667,6 @@ your Emacs configuration file. Everything after the @code{(require @lisp ;;; Sample ERC configuration -;; Add the ERC directory to load path -- you don't need this if you are -;; using the version of ERC that comes with Emacs -(add-to-list 'load-path "~/elisp/erc") - -;; Load ERC -(require 'erc) - ;; Load authentication info from an external source. Put sensitive ;; passwords and the like in here. (load "~/.emacs.d/.erc-auth") @@ -711,6 +715,12 @@ stuff, to the current ERC buffer." ;; Join the #emacs and #erc channels whenever connecting to Freenode. (setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc"))) +;; Rename server buffers to reflect the current network name instead +;; of SERVER:PORT (e.g., "freenode" instead of "irc.freenode.net:6667"). +;; This is useful when using a bouncer like ZNC where you have multiple +;; connections to the same server. +(setq erc-rename-buffers t) + ;; Interpret mIRC-style color commands in IRC chats (setq erc-interpret-mirc-color t) @@ -743,12 +753,40 @@ If non, @code{nil}, this is a list of IRC message types to hide, e.g.: @end example @end defopt +@defopt erc-network-hide-list +If non, @code{nil}, this is a list of IRC networks and message types +to hide, e.g.: + +@example +(setq erc-network-hide-list (("freenode" "JOIN" "PART" "QUIT") +("OFTC" "JOIN" "PART"")) +@end example +@end defopt + +@defopt erc-channel-hide-list +If non, @code{nil}, this is a list of IRC channels and message types +to hide, e.g.: + +@example +(setq erc-channel-hide-list (("#erc" "JOIN" "PART" "QUIT") +("#emacs" "NICK")) +@end example +@end defopt + @defopt erc-lurker-hide-list Like @code{erc-hide-list}, but only applies to messages sent by lurkers. The function @code{erc-lurker-p} determines whether a given nickname is considered a lurker. @end defopt +@defopt erc-rename-buffers +If non, @code{nil}, this will rename server buffers to reflect the +current network name instead of IP:PORT + +@example +(setq erc-rename-buffers t) +@end example +@end defopt @node Getting Help and Reporting Bugs @chapter Getting Help and Reporting Bugs @@ -762,7 +800,7 @@ or if you have bugs to report, there are several places you can go. @item @uref{http://www.emacswiki.org/cgi-bin/wiki/ERC} is the -emacswiki.org page for ERC@. Anyone may add tips, hints, etc. to it. +emacswiki.org page for ERC@. Anyone may add tips, hints, etc.@: to it. @item You can ask questions about using ERC on the Emacs mailing list, diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index 8728d53ea27..35d315c64b8 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -1,22 +1,23 @@ \input texinfo @c %**start of header -@setfilename ../../info/ert +@setfilename ../../info/ert.info @settitle Emacs Lisp Regression Testing +@include docstyle.texi @c %**end of header @dircategory Emacs misc features @direntry -* ERT: (ert). Emacs Lisp regression testing tool. +* ERT: (ert). Emacs Lisp regression testing tool. @end direntry @copying -Copyright @copyright{} 2008, 2010--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2008, 2010--2015 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,'' +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''. @@ -25,9 +26,21 @@ modify this GNU manual.'' @end quotation @end copying +@titlepage +@title Emacs Lisp Regression Testing +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex @node Top @top ERT: Emacs Lisp Regression Testing +@insertcopying + 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. @@ -85,6 +98,7 @@ Appendix @end detailmenu @end menu +@end ifnottex @node Introduction @chapter Introduction @@ -125,8 +139,7 @@ An ERT test definition equivalent to the above comments is this: 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). +will pass if the three calls to @code{equal} all return non-@code{nil}. @code{should} is a macro with the same meaning as @code{cl-assert} but better error reporting. @xref{The @code{should} Macro}. @@ -183,9 +196,10 @@ tests run. It looks like this: @example Selector: t -Passed: 31 -Failed: 2 (2 unexpected) -Total: 33/33 +Passed: 31 +Skipped: 0 +Failed: 2 (2 unexpected) +Total: 33/33 Started at: 2008-09-11 08:39:25-0700 Finished. @@ -300,7 +314,8 @@ tests or symbols naming tests. @item @code{(tag TAG)} selects all tests that have TAG on their tags list. (Tags are optional labels you can apply to tests when you define them.) @item @code{(satisfies PREDICATE)} selects all tests that satisfy PREDICATE, -a function that takes a test as argument and returns non-nil if it is selected. +a function that takes a test as argument and returns non-@code{nil} if +it is selected. @end itemize Selectors that are frequently useful when selecting tests to run @@ -367,13 +382,13 @@ F addition-test @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 +reduced to (= 3 4) before it reduced to @code{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 predicate returns @code{nil}, and @code{should-error}, which checks that the form called within it signals an error. An example use of @code{should-error}: @@ -454,6 +469,19 @@ versions, specific architectures, etc.: @node Tests and Their Environment @section Tests and Their Environment +Sometimes, it doesn't make sense to run a test due to missing +preconditions. A required Emacs feature might not be compiled in, the +function to be tested could call an external binary which might not be +available on the test machine, you name it. In this case, the macro +@code{skip-unless} could be used to skip the test: + +@lisp +(ert-deftest test-dbus () + "A test that checks D-BUS functionality." + (skip-unless (featurep 'dbusbind)) + ...) +@end lisp + 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 @@ -485,7 +513,7 @@ 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 @file{*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 @@ -503,7 +531,7 @@ 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 to activate any desired mode by calling the corresponding function directly, after binding the -hook variables to nil. This avoids the above problems. +hook variables to @code{nil}. This avoids the above problems. @node Useful Techniques @@ -733,7 +761,7 @@ 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. +explanation function should return @code{nil}. To associate an explanation function with a predicate, add the property @code{ert-explainer} to the symbol that names the predicate. @@ -794,7 +822,7 @@ 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 +and @code{unwind-protect} are available. One way to implement and use a fixture in ERT is @lisp @@ -823,7 +851,7 @@ 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 +it impossible to establish dynamic @code{let} bindings as part of the fixture. So, blindly imitating the way fixtures are implemented in other languages would be counter-productive in Lisp.) @@ -833,7 +861,7 @@ 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. +selector @code{"^ert-"} selects ERT's self-tests. Other uses include grouping tests by their expected execution time, e.g., to run quick tests during interactive development and slow tests less diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 4604b262e72..60a1af0678d 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -1,7 +1,8 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/eshell +@setfilename ../../info/eshell.info @settitle Eshell: The Emacs Shell +@include docstyle.texi @defindex cm @synindex vr fn @c %**end of header @@ -9,13 +10,13 @@ @copying This manual is for Eshell, the Emacs shell. -Copyright @copyright{} 1999--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2015 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'', +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''. @@ -61,20 +62,19 @@ modify this GNU manual.'' @node Top @top Eshell -Eshell is a shell-like command interpreter -implemented in Emacs Lisp. It invokes no external processes except for -those requested by the user. It is intended to be a functional -replacement for command shells such as @command{bash}, @command{zsh}, -@command{rc}, or @command{4dos}; since Emacs itself is capable of -handling the sort of tasks accomplished by those tools. +Eshell is a shell-like command interpreter implemented in Emacs Lisp. +It invokes no external processes except for those requested by the +user. It is intended to be an alternative to the IELM (@pxref{Lisp Interaction, Emacs Lisp Interaction, , emacs, The Emacs Editor}) +REPL for Emacs @emph{and} with an interface similar to command shells +such as @command{bash}, @command{zsh}, @command{rc}, or +@command{4dos}. @c This manual is updated to release 2.4 of Eshell. @insertcopying @end ifnottex @menu -* What is Eshell?:: A brief introduction to the Emacs Shell. -* Command basics:: The basics of command usage. +* Introduction:: A brief introduction to the Emacs Shell. * Commands:: * Expansion:: * Input/Output:: @@ -87,8 +87,9 @@ handling the sort of tasks accomplished by those tools. * Key Index:: @end menu -@node What is Eshell? -@chapter What is Eshell? +@node Introduction +@chapter Introduction +@section What is Eshell? @cindex what is Eshell? @cindex Eshell, what it is @@ -139,6 +140,24 @@ Any tool you use often deserves the time spent learning to master it. looks like: But don't let it fool you; once you know what's going on, it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.} +@section What Eshell is not +@cindex Eshell, what it is not +@cindex what Eshell is not +@cindex what isn't Eshell? + +Eshell is @emph{not} a replacement for system shells such as +@command{bash} or @command{zsh}. Use Eshell when you want to move +text between Emacs and external processes; if you only want to pipe +output from one external process to another (and then another, and so +on), use a system shell, because Emacs's IO system is buffer oriented, +not stream oriented, and is very inefficient at such tasks. If you +want to write shell scripts in Eshell, don't; either write an elisp +library or use a system shell. + +Some things Eshell just doesn't do well. It fills the niche between +IELM and your system shell, where the peculiar use-cases lie, and it +is less than ideal outside that niche. + @menu * Contributors to Eshell:: People who have helped out! @end menu @@ -158,123 +177,31 @@ The following persons have made contributions to Eshell. @item Eli Zaretskii made it possible for Eshell to run without requiring asynchronous subprocess support. This is important for MS-DOS, which -does not have such support.@refill +does not have such support. @item -Miles Bader contributed many fixes during the port to Emacs 21.@refill +Miles Bader contributed many fixes during the port to Emacs 21. @item Stefan Monnier fixed the things which bothered him, which of course made -things better for all.@refill +things better for all. @item Gerd Moellmann also helped to contribute bug fixes during the initial -integration with Emacs 21.@refill +integration with Emacs 21. @item Alex Schroeder contributed code for interactively querying the user -before overwriting files.@refill +before overwriting files. @item -Sudish Joseph helped with some XEmacs compatibility issues.@refill +Sudish Joseph helped with some XEmacs compatibility issues. @end itemize Apart from these, a lot of people have sent suggestions, ideas, requests, bug reports and encouragement. Thanks a lot! Without you there would be no new releases of Eshell. -@node Command basics -@chapter Basic overview - -A command shell is a means of entering verbally-formed commands. This -is really all that it does, and every feature described in this manual -is a means to that end. Therefore, it's important to take firm hold on -exactly what a command is, and how it fits in the overall picture of -things. - -@menu -* Commands verbs:: Commands always begin with a verb. -* Command arguments:: Some verbs require arguments. -@end menu - -@node Commands verbs -@section Commands verbs - -Commands are expressed using @dfn{script}, a special shorthand language -computers can understand with no trouble. Script is an extremely simple -language; oddly enough, this is what makes it look so complicated! -Whereas normal languages use a variety of embellishments, the form of a -script command is always: - -@example -@var{verb} [@var{arguments}] -@end example - -The verb expresses what you want your computer to do. There are a fixed -number of verbs, although this number is usually quite large. On the -author's computer, it reaches almost 1400 in number. But of course, -only a handful of these are really necessary. - -Sometimes, the verb is all that's written. A verb is always a single -word, usually related to the task it performs. @command{reboot} is a -good example. Entering that on GNU/Linux will reboot the -computer---assuming you have sufficient privileges. - -Other verbs require more information. These are usually very capable -verbs, and must be told specifically what to do. The extra information -is given in the form of @dfn{arguments}. For example, the -@command{echo} verb prints back whatever arguments you type. It -requires these arguments to know what to echo. A proper use of -@command{echo} looks like this: - -@example -echo This is an example of using echo! -@end example - -This script command causes the computer to echo back: ``This is an -example of using echo!'' - -Although command verbs are always simple words, like @command{reboot} or -@command{echo}, arguments may have a wide variety of forms. There are -textual arguments, numerical arguments---even Lisp arguments. -Distinguishing these different types of arguments requires special -typing, for the computer to know exactly what you mean. - -@node Command arguments -@section Command arguments - -Eshell recognizes several different kinds of command arguments: - -@enumerate -@item Strings (also called textual arguments) -@item Numbers (floating point or integer) -@item Lisp lists -@item Lisp symbols -@item Emacs buffers -@item Emacs process handles -@end enumerate - -Most users need to worry only about the first two. The third, Lisp lists, -occur very frequently, but almost always behind the scenes. - -Strings are the most common type of argument, and consist of nearly any -character. Special characters---those used by Eshell -specifically---must be preceded by a backslash (@samp{\}). When in doubt, it -is safe to add backslashes anywhere and everywhere. - -Here is a more complicated @command{echo} example: - -@example -echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar -@end example - -Beyond this, things get a bit more complicated. While not beyond the -reach of someone wishing to learn, it is definitely beyond the scope of -this manual to present it all in a simplistic manner. Get comfortable -with Eshell as a basic command invocation tool, and learn more about the -commands on your system; then come back when it all sits more familiarly -on your mind. Have fun! - @node Commands @chapter Commands @@ -323,7 +250,7 @@ need to use a function that takes some other data type, you will need to call it in an Elisp expression (which can also be used with @ref{Expansion, expansions}). As with other shells, you can escape special characters and spaces with the backslash (@code{\}) and -the single (@code{''}) and double (@code{""}) quotes. +apostrophes (@code{''}) and double quotes (@code{""}). @node Built-ins @@ -353,9 +280,9 @@ sudo is an alias, defined as "*sudo $*" @vindex eshell-prefer-lisp-functions If you would prefer to use the built-in commands instead of the external -commands, set @var{eshell-prefer-lisp-functions} to @code{t}. +commands, set @code{eshell-prefer-lisp-functions} to @code{t}. -Some of the built-in commands have different behaviour from their +Some of the built-in commands have different behavior from their external counterparts, and some have no external counterpart. Most of these will print a usage message when given the @code{--help} option. @@ -371,6 +298,12 @@ with no arguments, prints the current paths in this variable. Define an alias (@pxref{Aliases}). This does not add it to the aliases file. +@item clear +@cmindex clear +Scrolls the contents of the eshell window out of sight, leaving a blank window. +If provided with an optional non-nil argument, the scrollback contents are +cleared instead. + @item date @cmindex date Similar to, but slightly different from, the GNU Coreutils @@ -515,7 +448,7 @@ Aliases are commands that expand to a longer input line. For example, with the command invocation @samp{alias ll ls -l}; with this defined, running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}. Aliases defined (or deleted) by the @command{alias} command are -automatically written to the file named by @var{eshell-aliases-file}, +automatically written to the file named by @code{eshell-aliases-file}, which you can also edit directly (although you will have to manually reload it). @@ -539,7 +472,7 @@ by @code{!foo:n}. The history ring is loaded from a file at the start of every session, and written back to the file at the end of every session. The file path -is specified in @var{eshell-history-file-name}. Unlike other shells, +is specified in @code{eshell-history-file-name}. Unlike other shells, such as Bash, Eshell can not be configured to keep a history ring of a different size than that of the history file. @@ -701,7 +634,7 @@ from Bash can still use Bash-style globbing, as there are no incompatibilities. Most globbing is pattern-based expansion, but there is also predicate-based expansion. See @ref{Filename Generation, , , zsh, The Z Shell Manual} -for full syntax. To customize the syntax and behaviour of globbing in +for full syntax. To customize the syntax and behavior of globbing in Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, The GNU Emacs Manual}.} groups ``eshell-glob'' and ``eshell-pred''. @@ -721,11 +654,21 @@ terminal emulator. Programs that need a terminal to display output properly are referred to in this manual as ``visual commands,'' because they are not simply line-oriented. You must tell Eshell which commands are visual, by -adding them to @var{eshell-visual-commands}; for commands that are -visual for only certain @emph{sub}-commands -- e.g. @samp{git log} but -not @samp{git status} -- use @var{eshell-visual-subcommands}; and for +adding them to @code{eshell-visual-commands}; for commands that are +visual for only certain @emph{sub}-commands -- e.g., @samp{git log} but +not @samp{git status} -- use @code{eshell-visual-subcommands}; and for commands that are visual only when passed certain options, use -@var{eshell-visual-options}. +@code{eshell-visual-options}. + +Caution: Some tools such as Git use the pager @samp{less} by default +to paginate their output but call it with its @samp{-F} option. This +option causes @samp{less} to echo the output instead of paginating it +if the output is less than one page long. This causes undesirable +behavior if, e.g., @samp{git diff}, is defined as a visual subcommand. +It'll work if the output is big enough and fail if it is less than one +page long. If that occurs to you, search for configuration options +for calling @samp{less} without the @samp{-F} option. For Git, you +can do that using @samp{git config --global core.pager 'less -+F'}. @section Redirection Redirection is mostly the same in Eshell as it is in other command @@ -738,19 +681,19 @@ virtual devices. The buffer redirection operator, @code{>>>}, expects a buffer object on the right-hand side, into which it inserts the output of the left-hand side. e.g., @samp{echo hello >>> #<buffer *scratch*>} -inserts the string @code{"hello"} into the @code{*scratch*} buffer. +inserts the string @code{"hello"} into the @file{*scratch*} buffer. -@var{eshell-virtual-targets} is a list of mappings of virtual device +@code{eshell-virtual-targets} is a list of mappings of virtual device names to functions. Eshell comes with two virtual devices: @file{/dev/kill}, which sends the text to the kill ring, and @file{/dev/clip}, which sends text to the clipboard. You can, of course, define your own virtual targets. They are defined -by adding a list of the form @code{("/dev/name" function mode)} to -@var{eshell-virtual-targets}. The first element is the device name; -@code{function} may be either a lambda or a function name. If -@code{mode} is nil, then the function is the output function; if it is -non-nil, then the function is passed the redirection mode as a +by adding a list of the form @samp{("/dev/name" @var{function} @var{mode})} to +@code{eshell-virtual-targets}. The first element is the device name; +@var{function} may be either a lambda or a function name. If +@var{mode} is @code{nil}, then the function is the output function; if it is +non-@code{nil}, then the function is passed the redirection mode as a symbol--@code{overwrite} for @code{>}, @code{append} for @code{>>}, or @code{insert} for @code{>>>}--and the function is expected to return the output function. @@ -774,7 +717,7 @@ Eshell module.} You also need to load the following as shown: @example (eval-when-compile - (require 'cl) + (require 'cl-lib) (require 'esh-mode) (require 'eshell)) @@ -1209,7 +1152,7 @@ auto-revert mode in that buffer at frequent intervals---and a @item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search} -@item Write mesh.c +@item Write @file{mesh.c} This would run Emacs with the appropriate arguments to invoke Eshell only. That way, it could be listed as a login shell. @@ -1218,7 +1161,8 @@ only. That way, it could be listed as a login shell. @item Auto-detect when a command is visual, by checking @code{TERMCAP} usage -@item The first keypress after @kbd{M-x watson} triggers `eshell-send-input' +@item The first keypress after @kbd{M-x watson} triggers +@code{eshell-send-input} @item Make @kbd{/} electric diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index 747494ffbde..33c9a0eb3a9 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -1,8 +1,11 @@ \input texinfo.tex @c %**start of header -@setfilename ../../info/eudc +@setfilename ../../info/eudc.info @settitle Emacs Unified Directory Client (EUDC) Manual +@include docstyle.texi @afourpaper +@syncodeindex fn cp +@syncodeindex vr cp @c %**end of header @copying @@ -12,13 +15,13 @@ 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--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1998, 2000--2015 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'', +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''. @@ -60,8 +63,7 @@ modify this GNU manual.'' * Usage:: The various usage possibilities explained * Credits:: Who's done what * GNU Free Documentation License:: The license for this documentation. -* Command and Function Index:: -* Variables Index:: +* Index:: @end menu @@ -136,7 +138,7 @@ location, etc@enddots{} More information about LDAP can be found at @url{http://www.openldap.org/}. EUDC requires external support to access LDAP directory servers -(@pxref{LDAP Requirements}) +(@pxref{LDAP Configuration}) @node CCSO PH/QI @@ -212,17 +214,200 @@ email composition buffers (@pxref{Inline Query Expansion}) @end lisp @menu -* LDAP Requirements:: EUDC needs external support for LDAP +* LDAP Configuration:: EUDC needs external support for LDAP @end menu -@node LDAP Requirements -@section LDAP Requirements +@node LDAP Configuration +@section LDAP Configuration -LDAP support is added by means of @file{ldap.el}, which is part of Emacs. -@file{ldap.el} needs an external command line utility named -@file{ldapsearch}, available as part of Open LDAP -(@url{http://www.openldap.org/}). +LDAP support is added by means of @file{ldap.el}, which is part of +Emacs. @file{ldap.el} needs an external program called +@command{ldapsearch}, available as part of OpenLDAP +(@url{http://www.openldap.org/}). The configurations in this section +were tested with OpenLDAP 2.4.23. +Most servers use LDAP-over-SSL these days; the examples here reflect +that. The other possibilities are: + +@vindex ldap-host-parameters-alist +@vindex ldap-ldapsearch-args +@itemize @bullet + +@item +Servers that do not require authentication or that do not encrypt +authentication traffic. + +Include @code{auth simple} in @code{ldap-host-parameters-alist}, which +causes the @code{-x} option to be passed to @command{ldapsearch}. + +@item +Servers that require SASL authentication. + +Pass any required extra options to @command{ldapsearch} using +@code{ldap-ldapsearch-args}. +@end itemize + +The following examples use a base of +@code{ou=people,dc=gnu,dc=org} and the host name +@code{ldap.gnu.org}, a server that supports LDAP-over-SSL (the +@code{ldaps} protocol, with default port @code{636}) and which +requires authentication by the user @code{emacsuser} with password +@code{s3cr3t}. + +These configurations are meant to be self-contained; that is, each +provides everything required for sensible TAB-completion of email +fields. BBDB lookups are attempted first; if a matching BBDB entry is +found then EUDC will not attempt any LDAP lookups. + +Wildcard LDAP lookups are supported using the @code{*} character. For +example, attempting to TAB-complete the following: + +@example +To: * Smith +@end example + +@noindent +will return all LDAP entries with surnames that begin with +@code{Smith}. In every LDAP query it makes, EUDC implicitly appends +the wildcard character to the end of the last word. + +@menu +* Emacs-only Configuration:: Configure with @file{.emacs} +* External Configuration:: Configure with @file{/etc/openldap/ldap.conf} +* Troubleshooting:: Debug @command{ldapsearch} failures +@end menu + +@node Emacs-only Configuration +@subsection Emacs-only Configuration + +Emacs can pass most required configuration options via the +@command{ldapsearch} command-line. One exception is certificate +configuration for LDAP-over-SSL, which must be specified in +@file{/etc/openldap/ldap.conf}. On systems that provide such +certificates as part of the @code{OpenLDAP} installation, this can be +as simple as one line: + +@example +TLS_CACERTDIR /etc/openldap/certs +@end example + +In @file{.emacs}, these expressions suffice to configure EUDC for +LDAP: + +@vindex message-mode-map +@findex eudc-expand-inline +@vindex eudc-server-hotlist +@vindex ldap-host-parameters-alist +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("ldaps://ldap.gnu.org" + base "ou=people,dc=gnu,dc=org" + binddn "gnu\\emacsuser" + passwd ldap-password-read))) +@end lisp + +@findex ldap-password-read +@vindex passwd +@vindex password-cache +@vindex password-cache-expiry +@findex password-reset +Specifying the function @code{ldap-password-read} for @code{passwd} +will cause Emacs to prompt interactively for the password. The +password will then be validated and cached, unless +@code{password-cache} is nil. You can customize +@code{password-cache-expiry} to control the duration for which the +password is cached. If you want to clear the cache, call +@code{password-reset}. + +@node External Configuration +@subsection External Configuration + +Your system may already be configured for a default LDAP server. For +example, @file{/etc/openldap/ldap.conf} might contain: + +@example +BASE ou=people,dc=gnu,dc=org +URI ldaps://ldap.gnu.org +TLS_CACERTDIR /etc/openldap/certs +@end example + +@cindex bind distinguished name +@cindex binddn +Authentication requires a password, and a @dfn{bind distinguished name +(binddn)} representing the user, in this case, +@code{gnu\emacsuser}. These can be specified in +@file{~/.authinfo.gpg} with the following line: + +@example +machine ldaps://ldap.gnu.org binddn gnu\emacsuser password s3cr3t +@end example + +Then in the @file{.emacs} init file, these expressions suffice to +configure EUDC for LDAP: + +@vindex message-mode-map +@findex eudc-expand-inline +@vindex eudc-server-hotlist +@vindex ldap-host-parameters-alist +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("ldaps://ldap.gnu.org" + auth-source t))) +@end lisp + +For this example where we only care about one server, the server name +can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which +case @command{ldapsearch} defaults to the host name in +@file{/etc/openldap/ldap.conf}. + +The @file{~/.authinfo.gpg} line becomes: + +@example +binddn gnu\emacsuser password s3cr3t +@end example + +@noindent +and the @file{.emacs} expressions become: + +@vindex message-mode-map +@findex eudc-expand-inline +@vindex eudc-server-hotlist +@vindex ldap-host-parameters-alist +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) ("" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("" auth-source t))) +@end lisp + +@node Troubleshooting +@subsection Troubleshooting + +If @command{ldapsearch} exits with an error, you'll see a message like +this in the @code{*Messages*} buffer (all on one line): + +@example +ldap-search-internal: Failed ldapsearch invocation: + ldapsearch "-Hldaps://ldap.gnu.org" "-bou=people,dc=gnu,dc=org" + "-Dgnu\emacsuser" "-W" "-LL" "-tt" "(&(mail=name*))" + "givenname" "sn" "mail" +@end example + +The @command{ldapsearch} command is formatted such that it can be +copied and pasted into a terminal. Set the @command{ldapsearch} debug +level to 5 by appending @code{-d 5} to the command line. @node Usage @chapter Usage @@ -282,7 +467,7 @@ may be specified by appending a colon and a number to the name of the server. You will not need this unless your server runs on a port other than the default (which depends on the protocol). If the directory server resides on your own computer (which is the case -if you use the BBDB back end) then `localhost' is a reasonable value but +if you use the BBDB back end) then @samp{localhost} is a reasonable value but it will be ignored anyway. @end defvar @@ -695,11 +880,11 @@ trying to perform an inline query. Possible values are: Only the current directory server is tried @item hotlist The servers in the hotlist are tried in order until one finds a match -for the query or `eudc-max-servers-to-query' is reached +for the query or @code{eudc-max-servers-to-query} is reached @item server-then-hotlist The current server then the servers in the hotlist are tried in the order they appear in the hotlist until one of them finds a match or -`eudc-max-servers-to-query' is reached. This is the default. +@code{eudc-max-servers-to-query} is reached. This is the default. @end table @end defvar @@ -928,14 +1113,9 @@ in testing and proofreading the code and docs of @file{ph.el}. @appendix GNU Free Documentation License @include doclicense.texi -@node Command and Function Index -@unnumbered Command and Function Index - -@printindex fn - -@node Variables Index -@unnumbered Variables Index +@node Index +@unnumbered Index -@printindex vr +@printindex cp @bye diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi new file mode 100644 index 00000000000..f1347b7b3bb --- /dev/null +++ b/doc/misc/eww.texi @@ -0,0 +1,318 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../../info/eww.info +@settitle Emacs Web Wowser +@include docstyle.texi +@c %**end of header + +@copying +This file documents the GNU Emacs Web Wowser (EWW) package. + +Copyright @copyright{} 2014--2015 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs misc features +@direntry +* EWW: (eww). Emacs Web Wowser +@end direntry + +@finalout + +@titlepage +@title Emacs Web Wowser (EWW) +@subtitle A web browser for GNU Emacs. + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top EWW + +@insertcopying +@end ifnottex + +@menu +* Overview:: +* Basics:: +* Advanced:: + +Appendices +* History and Acknowledgments:: +* GNU Free Documentation License:: The license for this documentation. + +Indices +* Key Index:: +* Variable Index:: +* Lisp Function Index:: +* Concept Index:: +@end menu + +@node Overview +@chapter Overview +@dfn{EWW}, the Emacs Web Wowser, is a web browser for GNU Emacs. It +can load, parse, and display various web pages using @dfn{shr.el}. +However a GNU Emacs with @code{libxml2} support is required. + +@node Basics +@chapter Basic Usage + +@findex eww +@findex eww-open-file +@vindex eww-search-prefix +@cindex eww +@cindex Web Browsing + You can open a URL or search the web with the command @kbd{M-x eww}. +If the input doesn't look like a URL or domain name the web will be +searched via @code{eww-search-prefix}. The default search engine is +@url{https://duckduckgo.com, DuckDuckGo}. If you want to open a file +either prefix the file name with @code{file://} or use the command +@kbd{M-x eww-open-file}. + +@findex eww-quit +@findex eww-reload +@findex eww-copy-page-url +@kindex q +@kindex w +@kindex g + If loading the URL was successful the buffer @file{*eww*} is opened +and the web page is rendered in it. You can leave EWW by pressing +@kbd{q} or exit the browser by calling @kbd{eww-quit}. To reload the +web page hit @kbd{g} (@code{eww-reload}). Pressing @kbd{w} +(@code{eww-copy-page-url}) will copy the current URL to the kill ring. + +@findex eww-readable +@kindex R + The @kbd{R} command (@code{eww-readable}) will attempt to determine +which part of the document contains the ``readable'' text, and will +only display this part. This usually gets rid of menus and the like. + +@findex eww-toggle-fonts +@findex shr-use-fonts +@kindex F + The @kbd{F} command (@code{eww-toggle-fonts}) toggles whether to use +variable-pitch fonts or not. This sets the @code{shr-use-fonts} variable. + +@findex eww-download +@vindex eww-download-directory +@kindex d +@cindex Download + A URL under the point can be downloaded with @kbd{d} +(@code{eww-download}). The file will be written to the directory +specified in @code{eww-download-directory} (Default: @file{~/Downloads/}). + +@findex eww-back-url +@findex eww-forward-url +@findex eww-list-histories +@kindex r +@kindex l +@kindex H +@cindex History + EWW remembers the URLs you have visited to allow you to go back and +forth between them. By pressing @kbd{l} (@code{eww-back-url}) you go +to the previous URL@. You can go forward again with @kbd{r} +(@code{eww-forward-url}). If you want an overview of your browsing +history press @kbd{H} (@code{eww-list-histories}) to open the history +buffer @file{*eww history*}. The history is lost when EWW is quit. +If you want to remember websites you can use bookmarks. + +@vindex eww-history-limit + Along with the URLs visited, EWW also remembers both the rendered +page (as it appears in the buffer) and its source. This can take a +considerable amount of memory, so EWW discards the history entries to +keep their number within a set limit, as specified by +@code{eww-history-limit}; the default being 50. This variable could +also be set to @code{nil} to allow for the history list to grow +indefinitely. + +@cindex PDF + PDFs are viewed inline, by default, with @code{doc-view-mode}, but +this can be customized by using the mailcap (@pxref{mailcap,,, +emacs-mime, Emacs MIME Manual}) +mechanism, in particular @code{mailcap-mime-data}. + +@findex eww-add-bookmark +@findex eww-list-bookmarks +@kindex b +@kindex B +@cindex Bookmarks + EWW allows you to @dfn{bookmark} URLs. Simply hit @kbd{b} +(@code{eww-add-bookmark}) to store a bookmark for the current website. +You can view stored bookmarks with @kbd{B} +(@code{eww-list-bookmarks}). This will open the bookmark buffer +@file{*eww bookmarks*}. + +@findex eww-list-buffers +@kindex S +@cindex Multiple Buffers + To get summary of currently opened EWW buffers, press @kbd{S} +(@code{eww-list-buffers}). The @file{*eww buffers*} buffer allows to +quickly kill, flip through and switch to specific EWW buffer. + +@findex eww-browse-with-external-browser +@vindex shr-external-browser +@vindex eww-use-external-browser-for-content-type +@kindex & +@cindex External Browser + Although EWW and shr.el do their best to render webpages in GNU +Emacs some websites use features which can not be properly represented +or are not implemented (E.g., JavaScript). If you have trouble +viewing a website with EWW then hit @kbd{&} +(@code{eww-browse-with-external-browser}) inside the EWW buffer to +open the website in the external browser specified by +@code{shr-external-browser}. Some content types, such as video or +audio content, do not make sense to display in GNU Emacs at all. You +can tell EWW to open specific content automatically in an external +browser by customizing +@code{eww-use-external-browser-for-content-type}. + +@node Advanced +@chapter Advanced + +@findex eww-view-source +@kindex v +@cindex Viewing Source + You can view the source of a website with @kbd{v} +(@code{eww-view-source}). This will open a new buffer +@file{*eww-source*} and insert the source. The buffer will be set to +@code{html-mode} if available. + +@findex url-cookie-list +@kindex C +@cindex Cookies + EWW handles cookies through the @ref{Top, url package, ,url}. +You can list existing cookies with @kbd{C} (@code{url-cookie-list}). +For details about the Cookie handling @xref{Cookies,,,url}. + +@vindex eww-header-line-format +@cindex Header + The header line of the EWW buffer can be changed by customizing +@code{eww-header-line-format}. The format replaces @code{%t} with the +title of the website and @code{%u} with the URL. + +@c @vindex shr-bullet +@c @vindex shr-hr-line +@c @vindex eww-form-checkbox-selected-symbol +@c @vindex eww-form-checkbox-symbol +@c EWW and the rendering engine shr.el use ASCII characters to +@c represent some graphical elements, such as bullet points +@c (@code{shr-bullet}), check boxes +@c (@code{eww-form-checkbox-selected-symbol} and +@c @code{eww-form-checkbox-symbol}), and horizontal rules +@c @code{shr-hr-line}). Depending on your fonts these characters can be +@c replaced by Unicode glyphs to achieve better looking results. + +@vindex shr-max-image-proportion +@vindex shr-blocked-images +@cindex Image Display + Loading random images from the web can be problematic due to their +size or content. By customizing @code{shr-max-image-proportion} you +can set the maximal image proportion in relation to the window they +are displayed in. E.g., 0.7 means an image is allowed to take up 70% +of the width and height. If Emacs supports image scaling (ImageMagick +support required) then larger images are scaled down. You can block +specific images completely by customizing @code{shr-blocked-images}. + +@vindex shr-color-visible-distance-min +@vindex shr-color-visible-luminance-min +@cindex Contrast + EWW (or rather its HTML renderer @code{shr}) uses the colors declared +in the HTML page, but adjusts them if needed to keep a certain minimum +contrast. If that is still too low for you, you can customize the +variables @code{shr-color-visible-distance-min} and +@code{shr-color-visible-luminance-min} to get a better contrast. + +@cindex Desktop Support +@cindex Saving Sessions + In addition to maintaining the history at run-time, EWW will also +save the partial state of its buffers (the URIs and the titles of the +pages visited) in the desktop file if one is used. @xref{Saving Emacs +Sessions, , emacs, The GNU Emacs Manual}. + +@vindex eww-desktop-remove-duplicates + EWW history may sensibly contain multiple entries for the same page +URI@. At run-time, these entries may still have different associated +point positions or the actual Web page contents. +The latter, however, tend to be overly large to preserve in the +desktop file, so they get omitted, thus rendering the respective +entries entirely equivalent. By default, such duplicate entries are +not saved. Setting @code{eww-desktop-remove-duplicates} to nil will +force EWW to save them anyway. + +@vindex eww-restore-desktop + Restoring EWW buffers' contents may prove to take too long to +finish. When the @code{eww-restore-desktop} variable is set to +@code{nil} (the default), EWW will not try to reload the last visited +Web page when the buffer is restored from the desktop file, thus +allowing for faster Emacs start-up times. When set to @code{t}, +restoring the buffers will also initiate the reloading of such pages. + +@vindex eww-restore-reload-prompt + The EWW buffer restored from the desktop file but not yet reloaded +will contain a prompt, as specified by the +@code{eww-restore-reload-prompt} variable. The value of this variable +will be passed through @code{substitute-command-keys} upon each use, +thus allowing for the use of the usual substitutions, such as +@code{\[eww-reload]} for the current key binding of the +@code{eww-reload} command. + +@node History and Acknowledgments +@appendix History and Acknowledgments + +EWW was originally written by Lars Ingebrigtsen, known for his work on +Gnus. He started writing an Emacs HTML rendering library, +@code{shr.el}, to read blogs in Gnus. He eventually added a web +browser front end and HTML form support. Which resulted in EWW, the +Emacs Web Wowser. EWW was announced on 16 June 2013: +@url{http://lars.ingebrigtsen.no/2013/06/16/eww/}. + +EWW was then moved from the Gnus repository to GNU Emacs and several +developers started contributing to it as well. + +@node GNU Free Documentation License +@chapter GNU Free Documentation License +@include doclicense.texi + +@node Key Index +@unnumbered Key Index + +@printindex ky + +@node Variable Index +@unnumbered Variable Index + +@vindex eww-after-render-hook +After eww has rendered the data in the buffer, +@code{eww-after-render-hook} is called. It can be used to alter the +contents, for instance. + +@printindex vr + +@node Lisp Function Index +@unnumbered Function Index + +@printindex fn + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + + +@bye diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index d1f3e21c20e..6c924cf9547 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,9 +1,10 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/flymake +@setfilename ../../info/flymake.info @set VERSION 0.3 @set UPDATED April 2004 @settitle GNU Flymake @value{VERSION} +@include docstyle.texi @syncodeindex pg cp @comment %**end of header @@ -11,13 +12,13 @@ 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--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2015 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,'' +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''. @@ -86,7 +87,7 @@ messages also contain a filename and a line number. Selecting such a menu item will automatically open the file and jump to the line with error. -Syntax check is done 'on-the-fly'. It is started whenever +Syntax check is done ``on-the-fly''. It is started whenever @itemize @bullet @item buffer is loaded @@ -254,7 +255,7 @@ syntax check tool). Flymake uses a simple logging facility for indicating important points in the control flow. The logging facility sends logging messages to -the @code{*Messages*} buffer. The information logged can be used for +the @file{*Messages*} buffer. The information logged can be used for resolving various problems related to Flymake. Logging output is controlled by the @code{flymake-log-level} @@ -325,7 +326,7 @@ started after @code{flymake-no-changes-timeout} seconds. @item flymake-gui-warnings-enabled A boolean flag indicating whether Flymake will show message boxes for non-recoverable errors. If @code{flymake-gui-warnings-enabled} is -@code{nil}, these errors will only be logged to the @code{*Messages*} +@code{nil}, these errors will only be logged to the @file{*Messages*} buffer. @item flymake-start-syntax-check-on-newline @@ -694,8 +695,8 @@ Buildfile values are also cached. The command line (command name and the list of arguments) for launching a process is returned by the initialization function. Flymake then just calls @code{start-process} -to start an asynchronous process and configures process filter and -sentinel which is used for processing the output of the syntax check +to start an asynchronous process and configures a process filter and +sentinel, which are used for processing the output of the syntax check tool. @node Parsing the output diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi index 17b117be961..487cebd6cc2 100644 --- a/doc/misc/forms.texi +++ b/doc/misc/forms.texi @@ -3,8 +3,9 @@ @c Written by Johan Vromans, and edited by Richard Stallman @comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/forms +@setfilename ../../info/forms.info @settitle Forms Mode User's Manual +@include docstyle.texi @syncodeindex vr cp @syncodeindex fn cp @syncodeindex ky cp @@ -18,13 +19,13 @@ @copying This file documents Forms mode, a form-editing major mode for GNU Emacs. -Copyright @copyright{} 1989, 1997, 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1997, 2001--2015 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,'' +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''. @@ -853,7 +854,7 @@ number of records actually present in the data file. @item Problem saving buffers? An error occurred while saving the data file buffer. Most likely, Emacs did ask to confirm deleting the buffer because it had been modified, and -you said `no'. +you said ``no''. @end table @node Long Example diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index 4e5855627b8..a3be0edb965 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -1,20 +1,21 @@ \input texinfo -@setfilename gnus-coding +@setfilename gnus-coding.info @settitle Gnus Coding Style and Maintenance Guide +@include docstyle.texi @syncodeindex fn cp @syncodeindex vr cp @syncodeindex pg cp @copying -Copyright @copyright{} 2004--2005, 2007--2013 Free Software +Copyright @copyright{} 2004--2005, 2007--2015 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'', +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''. @@ -312,17 +313,17 @@ 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 bzr access (or it's inconvenient), you can -change such a file in the v5-10 branch, and it should propagate to Emacs -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. +If you don't have Emacs repository access (or it's inconvenient), you +can change such a file in the v5-10 branch, and it should propagate to +the Emacs repository---however, it will get some extra scrutiny (by +Miles) to see if the changes are possibly controversial and need +discussion on the mailing list. Many changes are obvious bug-fixes +however, so often there won't be any problem. @item If it's to a Gnus file, and it's important enough that it should be part of Emacs and the v5-10 branch, then you can make the change on the v5-10 -branch, and it will go into Emacs bzr and the Gnus git trunk (a few days +branch, and it will go into Emacs and the Gnus git trunk (a few days later). The most prominent examples for such changes are bug-fixed including improvements on the documentation. diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 1a0469c14f4..26b9210b0dd 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1,10 +1,11 @@ @c \input texinfo @c -*-texinfo-*- @c Uncomment 1st line before texing this file alone. @c %**start of header -@c Copyright (C) 1995, 2001-2013 Free Software Foundation, Inc. +@c Copyright (C) 1995, 2001-2015 Free Software Foundation, Inc. @c @c @setfilename gnus-faq.info @c @settitle Frequently Asked Questions +@c @include docstyle.texi @c %**end of header @c @@ -376,7 +377,7 @@ but it only says "nntp (news) open error", what to do? You've got to tell Gnus where to fetch the news from. Read the documentation for information on how to do this. As a -first start, put those lines in ~/.gnus.el: +first start, put those lines in @file{~/.gnus.el}: @example (setq gnus-select-method '(nntp "news.yourprovider.net")) @@ -388,7 +389,7 @@ first start, put those lines in ~/.gnus.el: @node FAQ 3-2 @subsubheading Question 3.2 -I'm working under Windows and have no idea what ~/.gnus.el means. +I'm working under Windows and have no idea what @file{~/.gnus.el} means. @subsubheading Answer @@ -420,7 +421,7 @@ to Control Panel -> System -> Advanced). There you'll find the possibility to set environment variables. Create a new one with name HOME and value C:\myhome. Rebooting is not necessary. -Now to create ~/.gnus.el, say +Now to create @file{~/.gnus.el}, say @samp{C-x C-f ~/.gnus.el RET C-x C-s}. in Emacs. @@ -494,7 +495,7 @@ I want Gnus to fetch news from several servers, is this possible? Of course. You can specify more sources for articles in the variable gnus-secondary-select-methods. Add something like -this in ~/.gnus.el: +this in @file{~/.gnus.el}: @example (add-to-list 'gnus-secondary-select-methods @@ -565,7 +566,7 @@ commonly used one is nnml. It stores every mail in one file and is therefore quite fast. However you might prefer a one file per group approach if your file system has problems with many small files, the nnfolder back end is then probably the -choice for you. To use nnml add the following to ~/.gnus.el: +choice for you. To use nnml add the following to @file{~/.gnus.el}: @example (add-to-list 'gnus-secondary-select-methods '(nnml "")) @@ -590,7 +591,7 @@ it's a POP3 server, then you need something like this: @end example @noindent -Make sure ~/.gnus.el isn't readable to others if you store +Make sure @file{~/.gnus.el} isn't readable to others if you store your password there. If you want to read your mail from a traditional spool file on your local machine, it's @@ -629,7 +630,7 @@ OK, now you only need to tell Gnus how to send mail. If you want to send mail via sendmail (or whichever MTA is playing the role of sendmail on your system), you don't need to do anything. However, if you want to send your mail to an -SMTP Server you need the following in your ~/.gnus.el +SMTP Server you need the following in your @file{~/.gnus.el} @example (setq send-mail-function 'smtpmail-send-it) @@ -649,7 +650,7 @@ There are two ways of using IMAP with Gnus. The first one is to use IMAP like POP3, that means Gnus fetches the mail from the IMAP server and stores it on disk. If you want to do this (you don't really want to do this) add the following to -~/.gnus.el +@file{~/.gnus.el} @example (add-to-list 'mail-sources '(imap :server "mail.mycorp.com" @@ -722,7 +723,7 @@ POP3 mail source. See @pxref{Mail Source Specifiers} for VALUE. the top of the article buffer? * FAQ 4-6:: I'd like Gnus NOT to render HTML-mails but show me the text part if it's available. How to do it? -* FAQ 4-7:: Can I use some other browser than w3 to render my +* FAQ 4-7:: Can I use some other browser than shr to render my HTML-mails? * FAQ 4-8:: Is there anything I can do to make poorly formatted mails more readable? @@ -741,6 +742,7 @@ POP3 mail source. See @pxref{Mail Source Specifiers} for VALUE. * FAQ 4-14:: I don't like the way the Summary buffer looks, how to tweak it? * FAQ 4-15:: How to split incoming mails in several groups? +* FAQ 4-16:: How can I ensure more contrast when viewing HTML mail? @end menu @node FAQ 4-1 @@ -764,7 +766,7 @@ Loading only unread messages can be annoying if you have threaded view enabled, @end example @noindent -in ~/.gnus.el to load enough old articles to prevent teared threads, replace 'some with t to load +in @file{~/.gnus.el} to load enough old articles to prevent teared threads, replace 'some with @code{t} to load all articles (Warning: Both settings enlarge the amount of data which is fetched when you enter a group and slow down the process of entering a group). @@ -828,7 +830,7 @@ The variable gnus-visible-headers controls which headers are shown, its value is a regular expression, header lines which match it are shown. So if you want author, subject, date, and if the header exists, Followup-To and MUA / NUA -say this in ~/.gnus.el: +say this in @file{~/.gnus.el}: @example (setq gnus-visible-headers @@ -855,7 +857,7 @@ Say @end example @noindent -in ~/.gnus.el. If you don't want HTML rendered, even if there's no text alternative add +in @file{~/.gnus.el}. If you don't want HTML rendered, even if there's no text alternative add @example (setq mm-automatic-display (remove "text/html" mm-automatic-display)) @@ -867,12 +869,12 @@ too. @node FAQ 4-7 @subsubheading Question 4.7 -Can I use some other browser than w3 to render my HTML-mails? +Can I use some other browser than w3m to render my HTML-mails? @subsubheading Answer Only if you use Gnus 5.10 or younger. In this case you've got the -choice between w3, w3m, links, lynx and html2text, which +choice between shr, w3m, links, lynx and html2text, which one is used can be specified in the variable mm-text-html-renderer, so if you want links to render your mail say @@ -890,11 +892,11 @@ more readable? @subsubheading Answer -Gnus offers you several functions to "wash" incoming mail, you can +Gnus offers you several functions to ``wash'' incoming mail, you can find them if you browse through the menu, item -Article->Washing. The most interesting ones are probably "Wrap -long lines" (@samp{W w}), "Decode ROT13" -(@samp{W r}) and "Outlook Deuglify" which repairs +Article->Washing. The most interesting ones are probably ``Wrap +long lines'' (@samp{W w}), ``Decode ROT13'' +(@samp{W r}) and ``Outlook Deuglify'' which repairs the dumb quoting used by many users of Microsoft products (@samp{W Y f} gives you full deuglify. See @samp{W Y C-h} or have a look at the menus for @@ -969,7 +971,7 @@ adaptive scoring say @end example @noindent -in ~/.gnus.el. +in @file{~/.gnus.el}. @node FAQ 4-10 @subsubheading Question 4.10 @@ -984,7 +986,7 @@ While in group buffer move point over the group and hit can set options for the group. At the bottom of the buffer you'll find an item that allows you to set variables locally for the group. To disable threading enter -gnus-show-threads as name of variable and nil as +gnus-show-threads as name of variable and @code{nil} as value. Hit button done at the top of the buffer when you're ready. @@ -1014,8 +1016,8 @@ mail groups. Is this a bug? No, that's a matter of design of Gnus, fixing this would mean reimplementation of major parts of Gnus' -back ends. Gnus thinks "highest-article-number @minus{} -lowest-article-number = total-number-of-articles". This +back ends. Gnus thinks ``highest-article-number @minus{} +lowest-article-number = total-number-of-articles''. This works OK for Usenet groups, but if you delete and move many messages in mail groups, this fails. To cure the symptom, enter the group via @samp{C-u RET} @@ -1083,8 +1085,8 @@ You've got to play around with the variable gnus-summary-line-format. Its value is a string of symbols which stand for things like author, date, subject etc. A list of the available specifiers can be found in the -manual node "Summary Buffer Lines" and the often forgotten -node "Formatting Variables" and its sub-nodes. There +manual node ``Summary Buffer Lines'' and the often forgotten +node ``Formatting Variables'' and its sub-nodes. There you'll find useful things like positioning the cursor and tabulators which allow you a summary in table form, but sadly hard tabulators are broken in 5.8.8. @@ -1110,7 +1112,7 @@ resulting in: :O \-> ... | 115 |Raymond Scholz | 1:24 :O \-> ... | 19 |Lars Magne Ingebrigt |15:33 :O Slow mailing list | 13 |Lars Magne Ingebrigt |Sat 23:49 -:O Re: `@@' mark not documented | 13 |Lars Magne Ingebrigt |Sat 23:50 +:O Re: '@@' mark not documented | 13 |Lars Magne Ingebrigt |Sat 23:50 :R > Re: Gnus still doesn't count messages prope| 23 |Lars Magne Ingebrigt |Sat 23:57 :O \-> ... | 18 |Kai Grossjohann | 0:35 :O \-> ... | 13 |Lars Magne Ingebrigt | 0:56 @@ -1146,7 +1148,7 @@ don't want that (you probably don't want), say @end example @noindent -in ~/.gnus.el. +in @file{~/.gnus.el}. An example might be better than thousand words, so here's my nnmail-split-methods. Note that I send duplicates in a @@ -1184,6 +1186,21 @@ from using them): @end example @noindent +@node FAQ 4-16 +@subsubheading Question 4.16 + +How can I ensure more contrast when viewing HTML mail? + +@subsubheading Answer + +Gnus' built-in simple HTML renderer (you use it if the value of +@code{mm-text-html-renderer} is @code{shr}) uses the colors which are +declared in the HTML mail. However, it adjusts them in order to +prevent situations like dark gray text on black background. In case +the results still have a too low contrast for you, increase the values +of the variables @code{shr-color-visible-distance-min} and +@code{shr-color-visible-luminance-min}. + @node FAQ 5 - Composing messages @subsection Composing messages @@ -1268,7 +1285,7 @@ For other versions of Gnus, say @end example @noindent -in ~/.gnus.el. +in @file{~/.gnus.el}. You can reformat a paragraph by hitting @samp{M-q} (as usual). @@ -1302,7 +1319,7 @@ following lists are signature, signature-file, organization, address, name or body. The attribute name can also be a string. In that case, this will be used as a header name, and the value will be inserted in the -headers of the article; if the value is `nil', the header +headers of the article; if the value is @code{nil}, the header name will be removed. You can also say (eval (foo bar)), then the function foo will be evaluated with argument bar and the result will be thrown away. @@ -1394,7 +1411,7 @@ If you want your outgoing messages to be spell-checked, say @end example @noindent -In your ~/.gnus.el, if you prefer on-the-fly spell-checking say +In your @file{~/.gnus.el}, if you prefer on-the-fly spell-checking say @example (add-hook 'message-mode-hook (lambda () (flyspell-mode 1))) @@ -1422,7 +1439,7 @@ Yes, say something like @end example @noindent -in ~/.gnus.el. Change "^de\\." and "deutsch8" to something +in @file{~/.gnus.el}. Change "^de\\." and "deutsch8" to something that suits your needs. @node FAQ 5-7 @@ -1451,7 +1468,7 @@ details. However, what you really want is the Insidious Big Brother Database bbdb. Get it through the XEmacs package system or from @uref{http://bbdb.sourceforge.net/, bbdb's homepage}. -Now place the following in ~/.gnus.el, to activate bbdb for Gnus: +Now place the following in @file{~/.gnus.el}, to activate bbdb for Gnus: @example (require 'bbdb) @@ -1484,7 +1501,7 @@ entries. Say @samp{c} to create a new entry, @samp{b} to search your BBDB and @samp{C-o} to add a new field to an entry. If you want to add a sender to the BBDB you can -also just hit `:' on the posting in the summary buffer and +also just hit @kbd{:} on the posting in the summary buffer and you are done. When you now compose a new mail, hit @samp{TAB} to cycle through know recipients. @@ -1511,7 +1528,7 @@ and create the actual X-face by saying @example cat file.xbm | xbm2ikon | compface > file.face -cat file.face | sed 's/\\/\\\\/g;s/\"/\\\"/g;' > file.face.quoted +cat file.face | sed 's/["\\]/\\&/g' > file.face.quoted @end example @noindent @@ -1531,7 +1548,7 @@ Now you only have to tell Gnus to include the X-face in your postings by saying @end example @noindent -in ~/.gnus.el. If you use Gnus 5.10, you can simply add an entry +in @file{~/.gnus.el}. If you use Gnus 5.10, you can simply add an entry @example (x-face-file "~/.xface") @@ -1549,7 +1566,7 @@ newsgroups? @subsubheading Answer -Put this in ~/.gnus.el: +Put this in @file{~/.gnus.el}: @example (setq gnus-confirm-mail-reply-to-news t) @@ -1579,7 +1596,7 @@ How to tell Gnus not to generate a sender header? @subsubheading Answer Since 5.10 Gnus doesn't generate a sender header by -default. For older Gnus' try this in ~/.gnus.el: +default. For older Gnus' try this in @file{~/.gnus.el}: @example (eval-after-load "message" @@ -1632,7 +1649,7 @@ aren't they and how to fix it? @subsubheading Answer -The message-ID is an unique identifier for messages you +The message-ID is a unique identifier for messages you send. To make it unique, Gnus need to know which machine name to put after the "@@". If the name of the machine where Gnus is running isn't suitable (it probably isn't @@ -1644,7 +1661,7 @@ by saying: @end example @noindent -in ~/.gnus.el. If you use Gnus 5.9 or earlier, you can use this +in @file{~/.gnus.el}. If you use Gnus 5.9 or earlier, you can use this instead (works for newer versions as well): @example @@ -1744,7 +1761,7 @@ by saying @samp{O f}. However, wouldn't it be much more convenient to have more direct access to the archived message from Gnus? If you say yes, put this snippet by Frank Haun <pille3003@@fhaun.de> in -~/.gnus.el: +@file{~/.gnus.el}: @example (defun my-archive-article (&optional n) @@ -1897,7 +1914,7 @@ to another group. @subsubheading Answer -Say something like this in ~/.gnus.el: +Say something like this in @file{~/.gnus.el}: @example (setq nnmail-expiry-target "nnml:expired") @@ -1979,7 +1996,7 @@ The Gnus agent is part of Gnus, it allows you to fetch mail and news and store them on disk for reading them later when you're offline. It kind of mimics offline newsreaders like Forte Agent. If you want to use -the Agent place the following in ~/.gnus.el if you are +the Agent place the following in @file{~/.gnus.el} if you are still using 5.8.8 or 5.9 (it's the default since 5.10): @example @@ -2174,13 +2191,13 @@ Starting Gnus is really slow, how to speed it up? The reason for this could be the way Gnus reads its active file, see the node "The Active File" in the Gnus manual for things you might try to speed the process up. -An other idea would be to byte compile your ~/.gnus.el (say +An other idea would be to byte compile your @file{~/.gnus.el} (say @samp{M-x byte-compile-file RET ~/.gnus.el RET} to do it). Finally, if you have require statements in your .gnus, you could replace them with eval-after-load, which loads the stuff not at startup time, but when it's needed. Say you've got this in your -~/.gnus.el: +@file{~/.gnus.el}: @example (require 'message) @@ -2207,7 +2224,7 @@ How to speed up the process of entering a group? @subsubheading Answer A speed killer is setting the variable -gnus-fetch-old-headers to anything different from nil, +gnus-fetch-old-headers to anything different from @code{nil}, so don't do this if speed is an issue. To speed up building of summary say @@ -2216,7 +2233,7 @@ building of summary say @end example @noindent -at the bottom of your ~/.gnus.el, this will make gnus +at the bottom of your @file{~/.gnus.el}, this will make gnus byte-compile things like gnus-summary-line-format. then you could increase the value of gc-cons-threshold @@ -2236,7 +2253,7 @@ recent GNU Emacs, you should say @end example @noindent -in ~/.gnus.el (thanks to Jesper harder for the last +in @file{~/.gnus.el} (thanks to Jesper harder for the last two suggestions). Finally if you are still using 5.8.8 or 5.9 and experience speed problems with summary buffer generation, you definitely should update to @@ -2262,8 +2279,8 @@ to normal speed. @table @dfn @item ~/.gnus.el -When the term ~/.gnus.el is used it just means your Gnus -configuration file. You might as well call it ~/.gnus or +When the term @file{~/.gnus.el} is used it just means your Gnus +configuration file. You might as well call it @file{~/.gnus} or specify another name. @item Back End diff --git a/doc/misc/gnus-news.el b/doc/misc/gnus-news.el index ff082e4ecf0..ba8a4631261 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-2013 Free Software Foundation, Inc. +;; Copyright (C) 2004-2015 Free Software Foundation, Inc. ;; Author: Reiner Steib <Reiner.Steib@gmx.de> ;; Keywords: tools @@ -26,7 +26,7 @@ (defvar gnus-news-header-disclaimer "GNUS NEWS -- history of user-visible changes. -Copyright (C) 1999-2013 Free Software Foundation, Inc. +Copyright (C) 1999-2015 Free Software Foundation, Inc. See the end of the file for license conditions. Please send Gnus bug reports to bugs@gnus.org. @@ -85,7 +85,7 @@ paragraph-separate: \"[ ]*$\"\nend:\n") (infile (concat dir infile)) (buffer (find-file-noselect (concat dir outfile)))) (with-temp-buffer - ;; Could be done using `texinfmt' stuff as in `infohack.el'. + ;; Could be done using 'texinfmt' stuff as in 'infohack.el'. (insert (shell-command-to-string (concat gnus-news-makeinfo-command " " @@ -102,7 +102,7 @@ paragraph-separate: \"[ ]*$\"\nend:\n") (save-excursion (while (re-search-forward "^ " nil t) (replace-match ""))) - ;; Avoid `*' from @ref at beginning of line: + ;; Avoid '*' from @ref at beginning of line: (save-excursion (while (re-search-forward "^\\*Note" nil t) (replace-match " \\&"))) diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi index 9c1ecb19748..ef6573fc73e 100644 --- a/doc/misc/gnus-news.texi +++ b/doc/misc/gnus-news.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- -@c Copyright (C) 2004-2013 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 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 @@ -13,8 +13,8 @@ @c carry prominent notices stating who last changed them. @c This file contains a list of news features Gnus. It is supposed to be -@c included in `gnus.texi'. `GNUS-NEWS' is automatically generated from -@c this file (see `gnus-news.el'). +@c included in 'gnus.texi'. 'GNUS-NEWS' is automatically generated from +@c this file (see 'gnus-news.el'). @itemize @bullet diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index f7f373664c6..9093fa24f3d 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -2,22 +2,21 @@ @include gnus-overrides.texi -@setfilename ../../info/gnus +@setfilename ../../info/gnus.info @settitle Gnus Manual +@include docstyle.texi @syncodeindex fn cp @syncodeindex vr cp @syncodeindex pg cp -@documentencoding UTF-8 - @copying -Copyright @copyright{} 1995--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1995--2015 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'', +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''. @@ -461,7 +460,7 @@ Group Buffer * Selecting a Group:: Actually reading news. * Subscription Commands:: Unsubscribing, killing, subscribing. * Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? +* Group Levels:: Levels? What are those, then? * Group Score:: A mechanism for finding out what groups you like. * Marking Groups:: You can mark groups for later processing. * Foreign Groups:: Creating and editing groups. @@ -521,7 +520,7 @@ Summary Buffer * Charsets:: Character set issues. * Article Commands:: Doing various things with the article buffer. * Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. +* Finding the Parent:: No child support? Get the parent. * Alternative Approaches:: Reading using non-default summaries. * Tree Display:: A more visual display of threads. * Mail Group Commands:: Some commands can only be used in mail groups. @@ -618,6 +617,7 @@ Article Buffer * 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. @@ -704,7 +704,6 @@ Browsing the Web * Archiving Mail:: * Web Searches:: Creating groups from articles that match a string. * RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. Other Sources @@ -998,7 +997,7 @@ terminology section (@pxref{Terminology}). @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 +@file{*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 @@ -1095,7 +1094,7 @@ your mail without bothering with the server at all, you can use the if you're in a hurry as well. This command will not attempt to contact your primary server---instead, it will just activate all groups on level 1 and 2. (You should preferably keep no native groups on those two -levels.) Also @pxref{Group Levels}. +levels.) Also @pxref{Group Levels}. @node Slave Gnusae @@ -1678,7 +1677,7 @@ long as Gnus is active. * Selecting a Group:: Actually reading news. * Subscription Commands:: Unsubscribing, killing, subscribing. * Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? +* Group Levels:: Levels? What are those, then? * Group Score:: A mechanism for finding out what groups you like. * Marking Groups:: You can mark groups for later processing. * Foreign Groups:: Creating and editing groups. @@ -2854,7 +2853,7 @@ If the group parameter list has the element @code{(visible . t)}, that group will always be visible in the Group buffer, regardless of whether it has any unread articles. -This parameter cannot be set via @code{gnus-parameters}. See +This parameter cannot be set via @code{gnus-parameters}. See @code{gnus-permanently-visible-groups} as an alternative. @item broken-reply-to @@ -2881,12 +2880,17 @@ news group. @item gcc-self @cindex gcc-self If @code{(gcc-self . t)} is present in the group parameter list, newly -composed messages will be @code{Gcc}'d to the current group. If +composed messages will be @code{gcc}d to the current group. If @code{(gcc-self . none)} is present, no @code{Gcc:} header will be -generated, if @code{(gcc-self . "string")} is present, this string will -be inserted literally as a @code{gcc} header. This parameter takes -precedence over any default @code{Gcc} rules as described later -(@pxref{Archived Messages}), with the exception for messages to resend. +generated, if @code{(gcc-self . "group")} is present, this string will +be inserted literally as a @code{Gcc:} header. It should be a group +name. The @code{gcc-self} value may also be a list of strings and +@code{t}, e.g., @code{(gcc-self "group1" "group2" t)} means to +@code{gcc} the newly composed message into the groups @code{"group1"} +and @code{"group2"}, and into the current group. The @code{gcc-self} +parameter takes precedence over any default @code{Gcc} rules as +described later (@pxref{Archived Messages}), with the exception for +messages to resend. @strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of @code{nntp} groups (or the like) isn't valid. An @code{nntp} server @@ -3036,8 +3040,8 @@ like this in the group parameters: If you're using topics to organize your group buffer (@pxref{Group Topics}), note that posting styles can also be set in -the topics parameters. Posting styles in topic parameters apply to all -groups in this topic. More precisely, the posting-style settings for a +the topics parameters. Posting styles in topic parameters apply to all +groups in this topic. More precisely, the posting-style settings for a group result from the hierarchical merging of all posting-style entries in the parameters of this group and all the topics it belongs to. @@ -4750,7 +4754,7 @@ command or better use it as a prefix key. For example: * Charsets:: Character set issues. * Article Commands:: Doing various things with the article buffer. * Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. +* Finding the Parent:: No child support? Get the parent. * Alternative Approaches:: Reading using non-default summaries. * Tree Display:: A more visual display of threads. * Mail Group Commands:: Some commands can only be used in mail groups. @@ -5888,7 +5892,7 @@ have posted almost the same article twice. If you have just posted the article, and change your mind right away, there is a trick you can use to cancel/supersede the article without waiting for the article to appear on your site first. You simply return -to the post buffer (which is called @code{*sent ...*}). There you will +to the post buffer (which is called @file{*sent ...*}). There you will find the article you just posted, with all the headers intact. Change the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes} header by substituting one of those words for the word @@ -8508,7 +8512,7 @@ pseudo-articles when decoding. It is @code{t} by default. So; there you are, reading your @emph{pseudo-articles} in your @emph{virtual newsgroup} from the @emph{virtual server}; and you think: -Why isn't anything real anymore? How did we get here? +Why isn't anything real anymore? How did we get here? @node Article Treatment @@ -9078,7 +9082,7 @@ CRs into LF (this takes care of Mac line endings) Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}). Quoted-Printable is one common @acronym{MIME} encoding employed when sending non-@acronym{ASCII} (i.e., 8-bit) articles. It typically -makes strings like @samp{d@'ej@`a vu} look like @samp{d=E9j=E0 vu}, +makes strings like @samp{déjà vu} look like @samp{d=E9j=E0 vu}, which doesn't look very readable to me. Note that this is usually done automatically by Gnus if the message in question has a @code{Content-Transfer-Encoding} header that says that this encoding @@ -9140,9 +9144,6 @@ Use Gnus simple html renderer. @item gnus-w3m Use Gnus rendered based on w3m. -@item w3 -Use Emacs/W3. - @item w3m Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}. @@ -9546,7 +9547,7 @@ Display the original date (@code{gnus-article-date-original}). This can be useful if you normally use some other conversion function and are worried that it might be doing something totally wrong. Say, claiming that the article was posted in 1854. Although something like that is -@emph{totally} impossible. Don't you trust me? *titter* +@emph{totally} impossible. Don't you trust me? *titter* @end table @@ -9805,6 +9806,19 @@ Make all the @acronym{MIME} parts have buttons in front of them. This is mostly useful if you wish to save (or perform other actions) on inlined parts. +@item W M h +@kindex W M h (Summary) +@findex gnus-mime-buttonize-attachments-in-header +@vindex gnus-mime-display-attachment-buttons-in-header +Display @acronym{MIME} part buttons in the end of the header of an +article (@code{gnus-mime-buttonize-attachments-in-header}). This +command toggles the display. Note that buttons to be added to the +header are only the ones that aren't inlined in the body. If you want +those buttons always to be displayed, set +@code{gnus-mime-display-attachment-buttons-in-header} to non-@code{nil}. +The default is @code{t}. To change the appearance of buttons, customize +@code{gnus-header-face-alist}. + @item K m @kindex K m (Summary) @findex gnus-summary-repair-multipart @@ -10229,8 +10243,8 @@ summary buffer, point will just move to this article. If given a positive numerical prefix, fetch that many articles back into the ancestry. If given a negative numerical prefix, fetch just that ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the -grandparent and the grandgrandparent of the current article. If you say -@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current +grandparent and the great-grandparent of the current article. If you say +@kbd{-3 ^}, Gnus will only fetch the great-grandparent of the current article. @item A R (Summary) @@ -11139,7 +11153,7 @@ If you're in the habit of exiting groups, and then changing your mind about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}. If you do that, Gnus won't kill the summary buffer when you exit it. (Quelle surprise!) Instead it will change the name of the buffer to -something like @samp{*Dead Summary ... *} and install a minor mode +something like @file{*Dead Summary ... *} and install a minor mode called @code{gnus-dead-summary-mode}. Now, if you switch back to this buffer, you'll find that all keys are mapped to a function called @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead @@ -11467,7 +11481,7 @@ who wrote the article, the date it was written and the subject of the article. That's well and nice, but there's also lots of information most people do not want to see---what systems the article has passed through before reaching you, the @code{Message-ID}, the -@code{References}, etc. ad nauseam---and you'll probably want to get rid +@code{References}, etc.@: ad nauseam---and you'll probably want to get rid of some of those lines. If you want to keep all those lines in the article buffer, you can set @code{gnus-show-all-headers} to @code{t}. @@ -11747,20 +11761,30 @@ Also @pxref{MIME Commands}. @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. +Gnus can display @acronym{HTML} articles nicely formatted in the +article buffer. There are many methods for doing that, but two of +them are kind of default methods. + +If your Emacs copy has been built with libxml2 support, then Gnus uses +Emacs' built-in, plain elisp Simple HTML Renderer @code{shr} +@footnote{@code{shr} displays colors as declared in the @acronym{HTML} +article but tries to adjust them in order to be readable. If you +prefer more contrast, @xref{FAQ 4-16}.} which is also used by Emacs' +browser EWW (@pxref{EWW, ,EWW, emacs, The Emacs Manual}). -For a complete overview, consult @xref{Display Customization, -,Display Customization, emacs-mime, The Emacs MIME Manual}. This -section only describes the default method. +If your Emacs copy lacks libxml2 support but you have @code{w3m} +installed on your system, Gnus uses that to render @acronym{HTML} mail +and display the results in the article buffer (@code{gnus-w3m}). + +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}. +If set to @code{shr}, Gnus uses its own simple @acronym{HTML} +renderer. If set to @code{gnus-w3m}, it uses @code{w3m}. @item gnus-blocked-images @vindex gnus-blocked-images @@ -11888,8 +11912,8 @@ controlling variable is a predicate list, as described above. @ifinfo @c Avoid sort of redundant entries in the same section for the printed -@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or -@c `i foo-bar'. +@c manual, but add them in info to allow 'i gnus-treat-foo-bar RET' or +@c 'i foo-bar'. @vindex gnus-treat-buttonize @vindex gnus-treat-buttonize-head @vindex gnus-treat-capitalize-sentences @@ -12528,7 +12552,7 @@ you're in, you could say something like the following: Modify to suit your needs. @vindex gnus-message-highlight-citation -If @code{gnus-message-highlight-citation} is t, different levels of +If @code{gnus-message-highlight-citation} is @code{t}, different levels of citations are highlighted like in Gnus article buffers also in message mode buffers. @@ -12541,7 +12565,7 @@ Gnus provides a few different methods for storing the mail and news you send. The default method is to use the @dfn{archive virtual server} to store the messages. If you want to disable this completely, the @code{gnus-message-archive-group} variable should be @code{nil}. The -default is "sent.%Y-%m", which gives you one archive group per month. +default is @code{"sent.%Y-%m"}, which gives you one archive group per month. For archiving interesting messages in a group you read, see the @kbd{B c} (@code{gnus-summary-copy-article}) command (@pxref{Mail @@ -12804,10 +12828,12 @@ 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 Match,, -Replacing the Text that Matched, elisp, The Emacs Lisp Reference Manual}.) +expression, or if it takes the form @code{(header @var{match} +@var{regexp})}, 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 Match,, +Replacing the Text that Matched, elisp, The Emacs Lisp Reference +Manual}.) @vindex message-reply-headers @@ -12839,6 +12865,10 @@ So here's a new example: ;; @r{If I'm replying to Larsi, set the Organization header.} ((header "from" "larsi.*org") (Organization "Somewhere, Inc.")) + ;; @r{Reply to a message from the same subaddress the message} + ;; @r{was sent to.} + ((header "x-original-to" "me\\(\\+.+\\)@@example.org") + (address "me\\1@@example.org")) ((posting-from-work-p) ;; @r{A user defined function} (signature-file "~/.work-signature") (address "user@@bar.foo") @@ -13732,7 +13762,7 @@ A hook run before attempting to connect to an @acronym{NNTP} server. @item nntp-record-commands @vindex nntp-record-commands If non-@code{nil}, @code{nntp} will log all commands it sends to the -@acronym{NNTP} server (along with a timestamp) in the @samp{*nntp-log*} +@acronym{NNTP} server (along with a timestamp) in the @file{*nntp-log*} buffer. This is useful if you are debugging a Gnus/@acronym{NNTP} connection that doesn't seem to work. @@ -14151,6 +14181,7 @@ from different locations, or with different user agents. * 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. +* Support for IMAP Extensions:: Getting extensions and labels from servers. @end menu @@ -14221,6 +14252,10 @@ 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. +@item plain +Non-encrypted and unsafe straight socket connection. +@acronym{STARTTLS} will not be used even if it is available. + @end table @item nnimap-authenticator @@ -14297,12 +14332,35 @@ Here's a complete example @code{nnimap} backend with a client-side @end example +@node Support for IMAP Extensions +@subsection Support for IMAP Extensions + +@cindex Gmail +@cindex X-GM-LABELS +@cindex IMAP labels + +If you're using Google's Gmail, you may want to see your Gmail labels +when reading your mail. Gnus can give you this information if you ask +for @samp{X-GM-LABELS} in the variable @code{gnus-extra-headers}. For +example: + +@example +(setq gnus-extra-headers + '(To Newsgroups X-GM-LABELS)) +@end example + +This will result in Gnus storing your labels in message header +structures for later use. The content is always a parenthesized +(possible empty) list. + + + @node Getting Mail @section Getting Mail @cindex reading mail @cindex mail -Reading mail with a newsreader---isn't that just plain WeIrD@? But of +Reading mail with a newsreader---isn't that just plain WeIrD@? But of course. @menu @@ -14932,7 +14990,7 @@ this means @samp{gssapi}, @samp{kerberos4}, @samp{digest-md5}, @samp{cram-md5}, @samp{anonymous} or the default @samp{login}. @item :program -When using the `shell' :stream, the contents of this variable is +When using the @samp{shell} :stream, the contents of this variable is mapped into the @code{imap-shell-program} variable. This should be a @code{format}-like string (or list of strings). Here's an example: @@ -14960,7 +15018,8 @@ corresponding keywords. @item :mailbox The name of the mailbox to get mail from. The default is @samp{INBOX} -which normally is the mailbox which receives incoming mail. +which normally is the mailbox which receives incoming mail. Instead of +a single mailbox, this can be a list of mailboxes to fetch mail from. @item :predicate The predicate used to find articles to fetch. The default, @samp{UNSEEN @@ -16001,7 +16060,7 @@ this, it keeps a cache of old @code{Message-ID}s: default. The approximate maximum number of @code{Message-ID}s stored there is controlled by the @code{nnmail-message-id-cache-length} variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be -stored.) If all this sounds scary to you, you can set +stored.) If all this sounds scary to you, you can set @code{nnmail-treat-duplicates} to @code{warn} (which is what it is by default), and @code{nnmail} won't delete duplicate mails. Instead it will insert a warning into the head of the mail saying that it thinks @@ -16767,11 +16826,11 @@ 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 +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 +(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. @@ -16841,12 +16900,8 @@ interfaces to these sources. * Archiving Mail:: * Web Searches:: Creating groups from articles that match a string. * RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. @end menu -All the web sources require Emacs/W3 and the url library or those -alternatives to work. - The main caveat with all these web sources is that they probably won't work for a very long time. Gleaning information from the @acronym{HTML} data is guesswork at best, and when the layout is altered, the Gnus back end @@ -16917,15 +16972,11 @@ group as read. If the search engine changes its output substantially, @code{nnweb} won't be able to parse it and will fail. One could hardly fault the Web -providers if they were to do this---their @emph{raison d'@^etre} is to +providers if they were to do this---their @emph{raison d'être} is to make money off of advertisements, not to provide services to the community. Since @code{nnweb} washes the ads off all the articles, one might think that the providers might be somewhat miffed. We'll see. -You must have the @code{url} and @code{W3} package or those alternatives -(try @code{customize-group} on the @samp{mm-url} variable group) -installed to be able to use @code{nnweb}. - Virtual server variables: @table @code @@ -17123,38 +17174,6 @@ Parameters}) in order to display @samp{text/html} parts only in @end lisp -@node Customizing W3 -@subsection Customizing W3 -@cindex W3 -@cindex html -@cindex url -@cindex Netscape - -Gnus uses the url library to fetch web pages and Emacs/W3 (or those -alternatives) to display web pages. Emacs/W3 is documented in its own -manual, but there are some things that may be more relevant for Gnus -users. - -For instance, a common question is how to make Emacs/W3 follow links -using the @code{browse-url} functions (which will call some external web -browser like Netscape). Here's one way: - -@lisp -(eval-after-load "w3" - '(progn - (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) - (defun w3-fetch (&optional url target) - (interactive (list (w3-read-url-with-default))) - (if (eq major-mode 'gnus-article-mode) - (browse-url url) - (w3-fetch-orig url target))))) -@end lisp - -Put that in your @file{.emacs} file, and hitting links in W3-rendered -@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to -follow the link. - - @node Other Sources @section Other Sources @@ -17753,7 +17772,7 @@ So you send a ``reminder'' message (actually, a diary one) to yourself. @item You forget all about it and keep on getting and reading new mail, as usual. @item -From time to time, as you type `g' in the group buffer and as the date +From time to time, as you type @kbd{g} in the group buffer and as the date is getting closer, the message will pop up again to remind you of your appointment, just as if it were new and unread. @item @@ -18100,7 +18119,7 @@ sending the diary message to them as well. @item However, since @code{nndiary} also has a @code{request-post} method, you can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the -message won't actually be sent; just stored locally in the group. This +message won't actually be sent; just stored locally in the group. This comes in very handy for private appointments. @end itemize @@ -19438,7 +19457,7 @@ Display the score of the current article @kindex V t (Summary) @findex gnus-score-find-trace Display all score rules that have been used on the current article -(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you +(@code{gnus-score-find-trace}). In the @file{*Score Trace*} buffer, you may type @kbd{e} to edit score file corresponding to the score rule on current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the score file and edit it. @@ -19633,7 +19652,7 @@ Immediately scoring. @end table @item -If you are scoring on `e' (extra) headers, you will then be prompted for +If you are scoring on @samp{e} (extra) headers, you will then be prompted for the header name on which you wish to score. This must be a header named in gnus-extra-headers, and @samp{TAB} completion is available. @@ -20518,7 +20537,7 @@ matches. This takes a long time in big groups. You can inhibit this slow scoring on headers or body by setting the variable @code{gnus-inhibit-slow-scoring}. If @code{gnus-inhibit-slow-scoring} is regexp, slow scoring is inhibited if -the group matches the regexp. If it is t, slow scoring on it is +the group matches the regexp. If it is @code{t}, slow scoring on it is inhibited for all groups. Now, there's not much you can do about the slowness for news groups, but for @@ -20934,7 +20953,7 @@ very interesting: @end example Suppose you're reading a high volume group and you're only interested -in replies. The plan is to score down all articles that don't have +in replies. The plan is to score down all articles that don't have subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all parents of articles that have subjects that begin with reply marks. @@ -21065,7 +21084,7 @@ 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 +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}. @@ -21091,13 +21110,13 @@ within gnus. @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 +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 +configuration. Other engines require a local index that needs to be created and maintained outside of Gnus. @@ -21108,35 +21127,35 @@ 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 +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 +deleting, you can't act on the original article. But there is an alternative: you can @emph{warp} (i.e., jump) 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-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 +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. +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 +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 +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 +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 +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. @@ -21144,16 +21163,16 @@ 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, +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 +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 +don't have to do anything. But you might want to read the details of the query language anyway. @menu @@ -21173,9 +21192,9 @@ query language anyway. 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 +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 +name. For example to use the @code{namazu} engine to search the server named @code{home} you can use @lisp @@ -21186,14 +21205,14 @@ named @code{home} you can use @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 +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 +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 @@ -21215,10 +21234,10 @@ features (inspired by the Google search input language): @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 +operator precedence, e.g., (emacs OR xemacs) AND linux. Note that operators must be written with all capital letters to be -recognized. Also preceding a term with a @minus{} sign is equivalent to NOT -term. +recognized. Also preceding a term with a @minus{} sign is equivalent +to NOT term. @item Automatic AND queries If you specify multiple words then they will be treated as an AND @@ -21230,20 +21249,20 @@ 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 +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 +``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 +@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 +customize @code{nnir-imap-default-search-key}. For example to use @acronym{IMAP} queries by default @lisp @@ -21273,14 +21292,14 @@ 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 +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 +prefix-arg. After inputting the query this will prompt for an author name (or part of a name) to match. @node The swish++ Engine @@ -21294,15 +21313,15 @@ Documentation for swish++ may be found at the swish++ sourceforge page: @table @code @item nnir-swish++-program -The name of the swish++ executable. Defaults to @code{search} +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. +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}. +to get a group name. By default this is @code{$HOME/Mail}. @end table @@ -21317,15 +21336,15 @@ Documentation for swish-e may be found at the swish-e homepage @table @code @item nnir-swish-e-program -The name of the swish-e search program. Defaults to @code{swish-e}. +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. +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}. +to get a group name. By default this is @code{$HOME/Mail}. @end table @@ -21338,9 +21357,9 @@ 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 `.'). +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 @samp{/} +instead of @samp{.}). For example, suppose that Namazu returns file names such as @samp{/home/john/Mail/mail/misc/42}. For this example, use the @@ -21353,18 +21372,20 @@ 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 +output format. Good switches to use include @option{--sort}, +@option{--ascending}, @option{--early} and @option{--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: +Mail must first be indexed with the @command{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. + # Paths which will not be indexed. Don't use '^' or '$' anchors. $EXCLUDE_PATH = "spam|sent"; # Header fields which should be searchable. case-insensitive @@ -21423,8 +21444,8 @@ This engine is obsolete. @table @code @item nnir-method-default-engines -Alist of pairs of server backends and search engines. The default associations -are +Alist of pairs of server backends and search engines. The default +associations are @example (nnimap . imap) (nntp . gmane) @@ -21436,7 +21457,7 @@ 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 +All the items from @code{gnus-summary-line-format} are available, along with three items unique to nnir summary buffers: @example @@ -21445,18 +21466,19 @@ three items unique to nnir summary buffers: %g Article original short group name (string) @end example -If nil (the default) this will use @code{gnus-summary-line-format}. +If @code{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 +If non-@code{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} +group as arguments and populates the @code{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." +If this variable is @code{nil}, or if the provided function returns +@code{nil} for a search result, @code{gnus-retrieve-headers} will be +called instead." @end table @@ -21881,104 +21903,104 @@ tips and tricks}). @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 +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 +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 +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 +@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 +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 +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 +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 +automatically set for the original article. This is exactly what @emph{marks propagation} is about. -Marks propagation is inactive by default. You can activate it for a +Marks propagation is inactive 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 +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. +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, +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 +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 +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 +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, +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 +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. +marks this way, it might take some time. You can avoid this situation by +setting @code{nnmairix-only-use-registry} to @code{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 +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} +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 +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}. +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 @@ -21988,7 +22010,7 @@ back end using @kbd{G b d}. Checking Mail @findex nnmairix-update-groups -I put all my important mail groups at group level 1. The mairix 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}). @@ -22006,7 +22028,7 @@ I use the following to check for mails: @end lisp Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix} -server. See the doc string for @code{nnmairix-update-groups} for +server. See the doc string for @code{nnmairix-update-groups} for details. @item @@ -22018,13 +22040,13 @@ 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 +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 +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, @@ -22033,19 +22055,19 @@ 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 +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 +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, +@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 @@ -22103,25 +22125,25 @@ mairix does only support us-ascii characters. @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 +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 +(@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 +``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 +@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{zz_mairix-<NAME>-<NUMBER>}. You can change the prefix of @code{nnmairix} groups by changing the variable @code{nnmairix-group-prefix}. @@ -22132,14 +22154,14 @@ 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 +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 +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 +@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 +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 @@ -22998,7 +23020,7 @@ elements on the line is (i.e., the non-info part). If you put additional elements on the mode line (e.g., a clock), you should modify this variable: -@c Hook written by Francesco Potorti` <pot@cnuce.cnr.it> +@c Hook written by Francesco Potortì <pot@cnuce.cnr.it> @lisp (add-hook 'display-time-hook (lambda () (setq gnus-mode-non-string-length @@ -23479,7 +23501,7 @@ Using the last function would be something like this: @c #### FIXME: faces and x-faces' implementations should really be harmonized. @code{Face} headers are essentially a funkier version of @code{X-Face} -ones. They describe a 48x48 pixel colored image that's supposed to +ones. They describe a 48x48 pixel colored image that's supposed to represent the author of the message. @cindex face @@ -23511,7 +23533,7 @@ easier insertion of Face headers in outgoing messages. converts the file to Face format by using the @code{gnus-convert-image-to-face-command} shell command. -Here's how you would typically use this function. Put something like the +Here's how you would typically use this function. Put something like the following in your @file{~/.gnus.el} file: @lisp @@ -23690,7 +23712,7 @@ The following variables offer control over how things are displayed. @item gnus-gravatar-size @vindex gnus-gravatar-size -The size in pixels of gravatars. Gravatars are always square, so one +The size in pixels of gravatars. Gravatars are always square, so one number for the size is enough. @item gnus-gravatar-properties @@ -24905,7 +24927,7 @@ classified as spammers. While @code{spam-use-BBDB-exclusive} @emph{can} be used as an alias for @code{spam-use-BBDB} as far as @code{spam.el} is concerned, it is @emph{not} a separate back end. If you set -@code{spam-use-BBDB-exclusive} to t, @emph{all} your BBDB splitting +@code{spam-use-BBDB-exclusive} to @code{t}, @emph{all} your BBDB splitting will be exclusive. @end defvar @@ -25889,7 +25911,7 @@ Store custom flags and keywords The registry can store custom flags and keywords for a message. For instance, you can mark a message ``To-Do'' this way and the flag will persist whether the message is in the nnimap, nnml, nnmaildir, -etc. backends. +etc.@: backends. @item Store arbitrary data @@ -25919,7 +25941,7 @@ Fortunately, setting up the Gnus registry is pretty easy: @end lisp This adds registry saves to Gnus newsrc saves (which happen on exit -and when you press @kbd{s} from the @code{*Group*} buffer. It also +and when you press @kbd{s} from the @file{*Group*} buffer. It also adds registry calls to article actions in Gnus (copy, move, etc.)@: so it's not easy to undo the initialization. See @code{gnus-registry-initialize} for the gory details. @@ -25961,17 +25983,34 @@ the word ``archive'' is not followed. @defvar gnus-registry-max-entries The number (an integer or @code{nil} for unlimited) of entries the -registry will keep. +registry will keep. If the registry has reached or exceeded this +size, it will reject insertion of new entries. +@end defvar + +@defvar gnus-registry-prune-factor +This option (a float between 0 and 1) controls how much the registry +is cut back during pruning. In order to prevent constant pruning, the +registry will be pruned back to less than +@code{gnus-registry-max-entries}. This option controls exactly how +much less: the target is calculated as the maximum number of entries +minus the maximum number times this factor. The default is 0.1: +i.e., if your registry is limited to 50000 entries, pruning will try to +cut back to 45000 entries. Entries with keys marked as precious will +not be pruned. @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. +@defvar gnus-registry-default-sort-function +This option specifies how registry entries are sorted during pruning. +If a function is given, it should sort least valuable entries first, +as pruning starts from the beginning of the list. The default value +is @code{gnus-registry-sort-by-creation-time}, which proposes the +oldest entries for pruning. Set to nil to perform no sorting, which +will speed up the pruning process. @end defvar @defvar gnus-registry-cache-file The file where the registry will be stored between Gnus sessions. By -default the file name is @code{.gnus.registry.eioio} in the same +default the file name is @code{.gnus.registry.eieio} in the same directory as your @code{.newsrc.eld}. @end defvar @@ -26091,10 +26130,10 @@ 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'): +;; 'gnus-registry-marks'): ;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-chars) -;; show the marks by name (see `gnus-registry-marks'): +;; show the marks by name (see 'gnus-registry-marks'): ;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-names) @end lisp @@ -26204,8 +26243,8 @@ This variable controls whether to add timestamps to messages that are controlled by @code{gnus-verbose} and @code{gnus-verbose-backends} and are issued. The default value is @code{nil} which means never to add timestamp. If it is @code{log}, add timestamps to only the messages -that go into the @samp{*Messages*} buffer (in XEmacs, it is the -@w{@samp{ *Message-Log*}} buffer). If it is neither @code{nil} nor +that go into the @file{*Messages*} buffer (in XEmacs, it is the +@w{@file{ *Message-Log*}} buffer). If it is neither @code{nil} nor @code{log}, add timestamps not only to log messages but also to the ones displayed in the echo area. @@ -26338,7 +26377,7 @@ XEmacs is distributed as a collection of packages. You should install whatever packages the Gnus XEmacs package requires. The current requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base}, @samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils}, -@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{W3}, +@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}. @@ -26780,7 +26819,7 @@ David Moore---rewrite of @file{nnvirtual.el} and many other things. Kevin Davidson---came up with the name @dfn{ding}, so blame him. @item -Fran@,{c}ois Pinard---many, many interesting and thorough bug reports, as +François Pinard---many, many interesting and thorough bug reports, as well as autoconf support. @end itemize @@ -26888,7 +26927,7 @@ Gunnar Horrigmo, Richard Hoskins, Brad Howes, Miguel de Icaza, -Fran@,{c}ois Felix Ingrand, +François Felix Ingrand, Tatsuya Ichikawa, @c Ichikawa Ishikawa Ichiro, @c Ishikawa Lee Iverson, @@ -27784,7 +27823,7 @@ As a result of the following change, the @file{~/News/overview/} directory is not used any more. You can safely delete the entire hierarchy. -@c FIXME: `gnus-load' is mentioned in README, which is not included in +@c FIXME: 'gnus-load' is mentioned in README, which is not included in @c the repository. We should find a better place for this item. @item @code{(require 'gnus-load)} @@ -27874,7 +27913,7 @@ The estimated number of unread articles in the group buffer should now be correct for nnimap groups. This is achieved by calling @code{nnimap-fixup-unread-after-getting-new-news} from the @code{gnus-setup-news-hook} (called on startup) and -@code{gnus-after-getting-new-news-hook}. (called after getting new +@code{gnus-after-getting-new-news-hook} (called after getting new mail). If you have modified those variables from the default, you may want to add @code{nnimap-fixup-unread-after-getting-new-news} again. If you were happy with the estimate and want to save some (minimal) time @@ -28415,6 +28454,19 @@ New features in Ma Gnus: @itemize @bullet +@item Changes in summary and article mode +@c ************************************** + +@itemize @bullet + +@item +By default, @acronym{MIME} part buttons for attachments (if any) will +appear in the end of the article header in addition to the bottom of the +article body, so you can easily find them without scrolling the article +again and again. @xref{MIME Commands}. + +@end itemize + @item Changes in Message mode and related Gnus features @c **************************************************** @@ -28760,7 +28812,7 @@ specified by RFC 1153. @cindex splitting, terminology @cindex mail sorting @cindex mail filtering (splitting) -The action of sorting your emails according to certain rules. Sometimes +The action of sorting your emails according to certain rules. Sometimes incorrectly called mail filtering. @end table diff --git a/doc/misc/htmlfontify.texi b/doc/misc/htmlfontify.texi index 4bb6a9d6900..1b0afdd2e8d 100644 --- a/doc/misc/htmlfontify.texi +++ b/doc/misc/htmlfontify.texi @@ -1,7 +1,8 @@ \input texinfo @comment %**start of header -@setfilename ../../info/htmlfontify +@setfilename ../../info/htmlfontify.info @settitle Htmlfontify User Manual +@include docstyle.texi @exampleindent 2 @comment %**end of header @@ -9,13 +10,14 @@ This manual documents Htmlfontify, a source code -> crosslinked + formatted + syntax colorized html transformer. -Copyright @copyright{} 2002, 2003, 2013 Free Software Foundation, Inc. +Copyright @copyright{} 2002-2003, 2013-2015 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,'' +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''. @@ -26,7 +28,7 @@ modify this GNU manual.'' @dircategory Emacs misc features @direntry -* Htmlfontify: (htmlfontify). Convert source code to html. +* Htmlfontify: (htmlfontify). Convert source code to html. @end direntry @titlepage @@ -56,7 +58,7 @@ modify this GNU manual.'' @menu * Introduction:: About Htmlfontify. * Usage & Examples:: How to use Htmlfontify. -* Customization:: Fine-tuning Htmlfontify's behaviour. +* Customization:: Fine-tuning Htmlfontify's behavior. * Requirements:: External programs used by Htmlfontify. * GNU Free Documentation License:: The license for this documentation. * Index:: Index of contents. @@ -790,7 +792,7 @@ See: @ref{hfy-link-style-fun}. @end lisp Given @var{props}, a list of text-properties, return the value of the -face property, or nil. +face property, or @code{nil}. @item hfy-box-to-border-assoc @findex hfy-box-to-border-assoc @@ -819,10 +821,10 @@ which @emph{didn't} clash with @var{class} was returned. In versions from 0.18 onwards, each font attribute list is scored, and the non-conflicting list with the highest score is returned. (A specification with a class of @code{t} is considered to match any class you specify. -This matches Emacs's behaviour when deciding on which face attributes to +This matches Emacs's behavior when deciding on which face attributes to use, to the best of my understanding ). -If @var{class} is nil, then you just get get whatever +If @var{class} is @code{nil}, then you just get get whatever @code{face-attr-construct} returns; i.e., the current specification in effect for @var{face}. @@ -837,8 +839,8 @@ See @ref{hfy-display-class} for details of valid values for @var{class}. (hfy-face-at P) @end lisp -Find face in effect at point P. If overlays are to be considered -(see @ref{hfy-optimisations}) then this may return a @code{defface} style +Find face in effect at point P@. If overlays are to be considered +(see @ref{hfy-optimizations}) then this may return a @code{defface} style list of face properties instead of a face symbol. @item hfy-bgcol @@ -948,7 +950,7 @@ Is @var{srcdir}/@var{file} text? Uses @ref{hfy-istext-command} to determine thi (hfy-opt @var{symbol}) @end lisp -Is @ref{hfy-optimisations} member @var{symbol} set or not? +Is @ref{hfy-optimizations} member @var{symbol} set or not? @item hfy-dirname @findex hfy-dirname @@ -1151,8 +1153,8 @@ An assoc with elements of the form @samp{(face-name style-name . style-string)}. The actual stylesheet for each page is derived from one of these. @lisp -'((default "default" . "@{ background: black; color: white@}") - (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}")) +((default "default" . "@{ background: black; color: white@}") + (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}")) @end lisp @item hfy-facemap-assoc @@ -1171,24 +1173,24 @@ dealt with (and therefore no longer care about) will be invalid at any time. @lisp -'((64820 . end) - (64744 . font-lock-comment-face) - (64736 . end) - (64722 . font-lock-string-face) - (64630 . end) - (64623 . font-lock-string-face) - (64449 . end) - ;; Big similar section elided. You get the idea. - (5459 . end) - (5431 . (:inherit font-lock-keyword-face :background "7e7e7e")) - (5431 . end) - (4285 . font-lock-constant-face) - (4285 . end) - (4221 . font-lock-comment-face) - (4221 . end) - (4197 . font-lock-constant-face) - (4197 . end) - (1 . font-lock-comment-face)) +((64820 . end) + (64744 . font-lock-comment-face) + (64736 . end) + (64722 . font-lock-string-face) + (64630 . end) + (64623 . font-lock-string-face) + (64449 . end) + ;; Big similar section elided. You get the idea. + (5459 . end) + (5431 . (:inherit font-lock-keyword-face :background "7e7e7e")) + (5431 . end) + (4285 . font-lock-constant-face) + (4285 . end) + (4221 . font-lock-comment-face) + (4221 . end) + (4197 . font-lock-constant-face) + (4197 . end) + (1 . font-lock-comment-face)) @end lisp @end table @@ -1299,36 +1301,35 @@ access to the face spec you would use if you were connected to an X display. Some valid class specification elements are: @lisp - '(class color) - '(class grayscale) - '(background dark) - '(background light) - '(type x-toolkit) - '(type tty) - '(type motif) - '(type lucid) + (class color) + (class grayscale) + (background dark) + (background light) + (type x-toolkit) + (type tty) + (type motif) + (type lucid) @end lisp Multiple values for a tag may be combined, to indicate that any one or more -of these values in the specification key constitutes a match, eg: +of these values in the specification key constitutes a match. For +example, @code{((class color grayscale) (type tty))} would match any of: -'((class color grayscale) (type tty)) would match any of: @lisp - '((class color)) - '((class grayscale)) - '((class color grayscale))) - '((class color foo)) - '((type tty)) - '((type tty) (class color)) + ((class color)) + ((class grayscale)) + ((class color grayscale))) + ((class color foo)) + ((type tty)) + ((type tty) (class color)) @end lisp -and so on. @item hfy-page-header @vindex hfy-page-header @anchor{hfy-page-header} Function called with two arguments (the filename relative to the top -level source directory being etag'd and fontified), and a string containing +level source directory being etagged and fontified), and a string containing the @samp{<style>@dots{}</style>} text to embed in the document---the string returned will be used as the header for the htmlfontified version of the source file. @@ -1353,7 +1354,7 @@ be large and take a long time to render or be difficult to navigate. @vindex hfy-find-cmd @anchor{hfy-find-cmd} -``find'' command used to harvest a list of files to attempt to fontify. +The ``find'' command used to harvest a list of files to attempt to fontify. @item hfy-extn @vindex hfy-extn @@ -1393,9 +1394,9 @@ for the more complex shell interactions needed by Htmlfontify. Currently this is only required/used when using GNU etags, see @ref{hfy-etags-cmd-alist} for details. -@item hfy-optimisations -@vindex hfy-optimisations -@anchor{hfy-optimisations} +@item hfy-optimizations +@vindex hfy-optimizations +@anchor{hfy-optimizations} Optimizations to turn on. So far, the following have been implemented: @@ -1416,7 +1417,7 @@ Add @samp{<div class="default"> </div>} tags around the fontified body. a page with different colors than the fontified code.) @item keep-overlays -Preserve overlay highlighting (c.f. @code{ediff} or @code{goo-font-lock}) +Preserve overlay highlighting (cf.@: @code{ediff} or @code{goo-font-lock}) as well as basic faces. Can result in extremely verbose highlighting if there are many overlays (as is the case with @code{goo-font-lock}). @@ -1587,3 +1588,7 @@ A copy of the @code{file} command. @setchapternewpage odd @bye + +@c Local Variables: +@c coding: utf-8 +@c End: diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index a432d4dc14a..7fe8f51d986 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -1,7 +1,8 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/idlwave +@setfilename ../../info/idlwave.info @settitle IDLWAVE User Manual +@include docstyle.texi @synindex ky cp @syncodeindex vr cp @syncodeindex fn cp @@ -22,13 +23,13 @@ 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--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2015 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'', +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''. @@ -128,7 +129,7 @@ Completion Actions * Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc +* Padding Operators:: Enforcing space around @samp{=} etc * Case Changes:: Enforcing upper case keywords The IDLWAVE Shell @@ -238,24 +239,27 @@ Examining variables and expressions with a mouse click. And much, much more... @end itemize +@c Dead links, 2014/06. +@ignore @ifnottex @cindex Screenshots Here are a number of screenshots showing IDLWAVE in action: @itemize @bullet @item -@uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} +@uref{http://github.com/jdtsmith/idlwave/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} @item -@uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} +@uref{http://github.com/jdtsmith/idlwave/screenshots/emacs_21_keys.gif,A keyword being completed} @item -@uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} +@uref{http://github.com/jdtsmith/idlwave/screenshots/emacs_21_help.gif,Online help text.} @item -@uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} +@uref{http://github.com/jdtsmith/idlwave/screenshots/emacs_21_ri.gif,Routine information displayed} @item -@uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code +@uref{http://github.com/jdtsmith/idlwave/screenshots/emacs_21_bp.gif,Debugging code stopped at a breakpoint} @end itemize @end ifnottex +@end ignore IDLWAVE is the distant successor to the @file{idl.el} and @file{idl-shell.el} files written by Chris Chase. The modes and files @@ -497,7 +501,7 @@ plot_wday,1,1 @noindent and press @key{RET}. This fails with an error message telling you the @code{YT} keyword to plot is ambiguous. What are the allowed keywords again? Go back to the source window and put the cursor into -the `plot' line and press @kbd{C-c ?}. This shows the routine info +the ``plot'' line and press @kbd{C-c ?}. This shows the routine info window for the plot routine, which contains a list of keywords, along with the argument list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with @@ -590,7 +594,7 @@ slightly from the margin and use only 3 spaces as indentation between Restart Emacs, and re-indent the program we developed in the first part of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep -these lines in @file{.emacs}, with values adjusted to your likings. If +these lines in @file{.emacs}, with values adjusted to your liking. If you want to get more information about any of these variables, type, e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which variables can be customized, look for items marked @samp{User Option:} @@ -604,7 +608,7 @@ Group}. Here you'll be presented with all the various variables grouped into categories. You can navigate the hierarchy (e.g., @samp{IDLWAVE Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand Generic End} to turn on @code{END} expansion), read about the variables, -change them, and `Save for Future Sessions'. Few of these variables +change them, and ``Save for Future Sessions''. Few of these variables need customization, but you can exercise considerable control over IDLWAVE's functionality with them. @@ -688,8 +692,8 @@ you want; directories with existing library catalogs will not be selected by default) and click on the @samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE collects information for each and every IDL routine on your search path. All this information is -written to the file @file{.idlwave/idlusercat.el} in your home -directory and will from now on automatically load whenever you use +written to the file @file{~/.emacs.d/idlwave/idlusercat.el} +and will from now on automatically load whenever you use IDLWAVE@. You may find it necessary to rebuild the catalog on occasion as your local libraries change, or build a library catalog for those directories instead. Invoke routine info (@kbd{C-c ?}) or completion @@ -701,7 +705,7 @@ library: a=readf@key{M-@key{TAB}} @end example -expands to `readfits('. Then try +expands to ``readfits(''. Then try @example a=readfits(@key{C-c ?} @@ -1006,7 +1010,7 @@ Non-@code{nil} means use last match on line for @cindex Highlighting of syntax @cindex Font lock -Highlighting of keywords, comments, strings etc. can be accomplished +Highlighting of keywords, comments, strings etc.@: can be accomplished with @code{font-lock}. If you are using @code{global-font-lock-mode} (in Emacs), or have @code{font-lock} turned on in any other buffer in XEmacs, it should also automatically work in IDLWAVE buffers. If you'd @@ -1261,7 +1265,7 @@ directly with IDL, along with an XML-based catalog of routine information. By default, IDLWAVE automatically attempts to convert this XML catalog into a format Emacs can more easily understand, and caches this information in your @code{idlwave_config_directory} -(@file{~/.idlwave/}, by default). It also re-scans the XML catalog if +(@file{~/.emacs.d/idlwave/}, by default). It also re-scans the XML catalog if it is newer than the current cached version. You can force rescan with the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}. @@ -1595,7 +1599,7 @@ completed keywords. @defopt idlwave-function-completion-adds-paren (@code{t}) Non-@code{nil} means completion automatically adds @samp{(} after -completed function. A value of `2' means also add the closing +completed function. A value of 2 means also add the closing parenthesis and position the cursor between the two. @end defopt @@ -1644,7 +1648,7 @@ of completed words. @defopt idlwave-completion-force-default-case (@code{nil}) Non-@code{nil} means completion will always honor the settings in -@code{idlwave-completion-case}. When nil (the default), entirely lower +@code{idlwave-completion-case}. When @code{nil} (the default), entirely lower case strings will always be completed to lower case, no matter what the settings in @code{idlwave-completion-case}. @end defopt @@ -2117,7 +2121,7 @@ settings are described below and set separately. @menu * Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc +* Padding Operators:: Enforcing space around @samp{=} etc * Case Changes:: Enforcing upper case keywords @end menu @@ -2465,7 +2469,7 @@ Initial commands, separated by newlines, to send to IDL. Non-@code{nil} means preserve command history between sessions. @end defopt -@defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist}) +@defopt idlwave-shell-command-history-file (@file{~/.emacs.d/idlwave/.idlwhist}) The file in which the command history of the idlwave shell is saved. Unless it's an absolute path, it goes in @code{idlwave-config-directory}. @@ -2486,7 +2490,7 @@ The frame parameters for a dedicated idlwave-shell frame. @end defopt @defopt idlwave-shell-raise-frame (@code{t}) -Non-@code{nil} means `idlwave-shell' raises the frame showing the shell +Non-@code{nil} means @code{idlwave-shell} raises the frame showing the shell window. @end defopt @@ -3107,7 +3111,7 @@ window, but is useful for immediate stepping, etc. @kindex C-c C-d C-p Do you find yourself repeatedly typing, e.g., @code{print,n_elements(x)}, and similar statements to remind yourself of the -type/size/structure/value/etc. of variables and expressions in your code +type/size/structure/value/etc.@: of variables and expressions in your code or at the command line? IDLWAVE has a suite of special commands to automate these types of variable or expression examinations. They work by sending statements to the shell formatted to include the indicated @@ -3517,7 +3521,7 @@ information (e.g., Windows), a library path must be specified in to setup directories for user catalog scan (@pxref{User Catalog} for more on this variable). Note that, before the shell is running, IDLWAVE can only know about the IDL search path by consulting the file pointed -to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by +to by @code{idlwave-path-file} (@file{~/.emacs.d/idlwave/idlpath.el}, by default). If @code{idlwave-auto-write-path} is enabled (which is the default), the paths are written out whenever the IDLWAVE shell is started. @@ -3539,7 +3543,7 @@ locating HTML help and the IDL Assistant for IDL v6.2 and later. Under Unix/MacOSX, will be obtained from the Shell and recorded, if run. @end defopt -@defopt idlwave-config-directory (@file{~/.idlwave}) +@defopt idlwave-config-directory (@file{~/.emacs.d/idlwave}) Default path where IDLWAVE saves configuration information, a user catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and later). @@ -3628,7 +3632,7 @@ performance is a problem and/or the catalogs are not needed. The user catalog is the old routine catalog system. It is produced within Emacs, and stored in a single file in the user's home directory -(@file{.idlwave/idlusercat.el} by default). Although library catalogs +(@file{.emacs.d/idlwave/idlusercat.el} by default). Although library catalogs are more flexible, there may be reasons to prefer a user catalog instead, including: @@ -3796,31 +3800,25 @@ available, it is the preferred choice, and the default. The variable whether this help browser is used. If you use the IDL Assistant, the tips here are not relevant. -Since IDLWAVE runs on a many different system types, a single browser -configuration is not possible, but choices abound. On many systems, -the default browser configured in @code{browse-url-browser-function}, -and hence inherited by default by -@code{idlwave-help-browser-function}, is Netscape. Unfortunately, the -HTML manuals decompiled from the original source contain formatting -structures which Netscape 4.x does not handle well, though they are -still readable. A much better choice is Mozilla, or one of the -Mozilla-derived browsers such as -@uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), -@uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or -@uref{http://www.mozilla.org/projects/firebird/,Firebird} (all -platforms). Newer versions of Emacs provide a browser-function choice -@code{browse-url-gnome-moz} which uses the Gnome-configured browser. +Since IDLWAVE runs on many different system types, a single browser +configuration is not possible, but choices abound. The default +@code{idlwave-help-browser-function} inherits the browser configured +in @code{browse-url-browser-function}. Note that the HTML files decompiled from the help sources contain specific references to the @samp{Symbol} font, which by default is not permitted in normal encodings (it's invalid, technically). Though it only impacts a few symbols, you can trick Mozilla-based browsers into recognizing @samp{Symbol} by following the directions +@c This page is 11 years old. Is it still relevant? @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With this fix in place, HTML help pages look almost identical to their PDF equivalents (yet can be bookmarked, browsed as history, searched, etc.). +@c Not updated in over a decade. +@c Maybe you want to recommend eww these days. +@ignore @noindent Individual platform recommendations: @itemize @bullet @@ -3857,6 +3855,7 @@ following, to get consistent behavior with the @kbd{q} key: Note that you can open the file in an external browser from within @code{w3m} using @kbd{M}. @end itemize +@end ignore @node Configuration Examples @appendix Configuration Examples @@ -3944,7 +3943,7 @@ user is King! w3m-use-header-line nil w3m-use-toolbar nil) -;; Close my help window or frame when w3m closes with `q' +;; Close my help window or frame when w3m closes with 'q'. (defadvice w3m-close-window (after idlwave-close activate) (if (boundp 'idlwave-help-frame) (idlwave-help-quit))) @@ -3970,11 +3969,11 @@ user is King! (idlwave-action-and-binding "," '(idlwave-surround nil 1)) (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) - ;; Pad only after `->', remove any space before the arrow + ;; Pad only after '->', remove any space before the arrow (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) ;; Set some personal bindings - ;; (In this case, makes `,' have the normal self-insert behavior.) + ;; (In this case, makes ',' have the normal self-insert behavior.) (local-set-key "," 'self-insert-command) (local-set-key [f5] 'idlwave-shell-break-here) (local-set-key [f6] 'idlwave-shell-clear-current-bp) diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi index 623fb4bfa79..afc323888c3 100644 --- a/doc/misc/ido.texi +++ b/doc/misc/ido.texi @@ -1,18 +1,19 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/ido +@setfilename ../../info/ido.info @settitle Interactive Do +@include docstyle.texi @include emacsver.texi @copying This file documents the Ido package for GNU Emacs. -Copyright @copyright{} 2013 Free Software Foundation, Inc. +Copyright @copyright{} 2013-2015 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'', +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''. @@ -21,9 +22,9 @@ modify this GNU manual.'' @end quotation @end copying -@dircategory Emacs lisp libraries +@dircategory Emacs misc features @direntry -* Ido: (ido). Interactively do things with buffers and files. +* Ido: (ido). Interactively do things with buffers and files. @end direntry @finalout @@ -258,7 +259,7 @@ Buffer: 23@{123456 | 123@} At this point, you still have two matching buffers. If you want the first buffer in the list, you can simply press @key{RET}. If you want the second in the list, you can press @kbd{C-s} to move it to the top -of the list and then press @kbd{RET} to select it. +of the list and then press @key{RET} to select it. However, if you type @kbd{4}, you'll only have one match left: @@ -304,7 +305,7 @@ the files in that directory, simply move the directory to the head of the list and hit @key{RET}. To go up to the parent directory, delete any partial file name already -specified (e.g. using @key{DEL}) and hit @key{DEL}. +specified (e.g., using @key{DEL}) and hit @key{DEL}. @c @deffn Command ido-delete-backward-updir @@ -366,6 +367,7 @@ users Ido offers in addition to the default substring matching method the only difference to the description of the substring matching above. +@cindex toggle prefix matching You can toggle prefix matching with @kbd{C-p} (@code{ido-toggle-prefix}). @@ -575,7 +577,7 @@ enable it: Now you can customize @code{completion-ignored-extensions} as well. Go ahead and add all the useless object files, backup files, shared -library files and other computing flotsam you don’t want Ido to show. +library files and other computing flotsam you don't want Ido to show. @strong{Please notice:} Ido will still complete the ignored elements if it would otherwise not show any other matches. So if you type out diff --git a/doc/misc/info.texi b/doc/misc/info.texi index d17a65571f1..1439d30ccee 100644 --- a/doc/misc/info.texi +++ b/doc/misc/info.texi @@ -5,22 +5,23 @@ @comment %**start of header @setfilename info.info @settitle Info +@include docstyle.texi @syncodeindex fn cp @syncodeindex vr cp @syncodeindex ky cp @comment %**end of header @copying -This file describes how to use Info, the on-line, menu-driven GNU +This file describes how to use Info, the menu-driven GNU documentation system. -Copyright @copyright{} 1989, 1992, 1996--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1992, 1996--2015 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,'' +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''. @@ -50,7 +51,7 @@ modify this GNU manual.'' @node Top @top Info: An Introduction -The GNU Project distributes most of its on-line manuals in the +The GNU Project distributes most of its manuals in the @dfn{Info format}, which you read using an @dfn{Info reader}. You are probably using an Info reader to read this now. @@ -66,8 +67,10 @@ type the command @kbd{h} now. It brings you to a programmed instruction sequence. To read about advanced Info commands, type @kbd{n} twice. This -brings you to @cite{Advanced Info Commands}, skipping over the `Getting -Started' chapter. +brings you to @cite{Advanced Info Commands}, skipping over the ``Getting +Started'' chapter. + +Type @kbd{H} to see a summary of all available commands. @end ifinfo @end ifnottex @@ -76,20 +79,18 @@ Started' chapter. @menu * Getting Started:: Getting started using an Info reader. * Advanced:: Advanced Info commands. -* Expert Info:: Info commands for experts. +* Further Reading:: Where to learn more about Info files. * GNU Free Documentation License:: The license for this documentation. * Index:: An index of topics, commands, and variables. @end menu -@node Getting Started, Advanced, Top, Top -@comment node-name, next, previous, up +@node Getting Started @chapter Getting Started This first part of this Info manual describes how to get around inside of Info. The second part of the manual describes various advanced -Info commands. The third part briefly explains how to generate Info -files from Texinfo files, and describes how to write an Info file -by hand. +Info commands. The third part contains references to other sources, +which explain how to generate Info files from Texinfo files. @ifnotinfo This manual is primarily designed for browsing with an Info reader @@ -97,7 +98,7 @@ program on a computer, so that you can try Info commands while reading about them. Reading it on paper or with an HTML browser is less effective, since you must take it on faith that the commands described really do what the manual says. By all means go through this manual -now that you have it; but please try going through the on-line version +now that you have it; but please try going through the Info version as well. @cindex Info reader, how to invoke @@ -150,14 +151,17 @@ Since your terminal has a relatively small number of lines on its screen, it is necessary to give you special advice at the beginning. If the entire text you are looking at fits on the screen, the text -@samp{All} will be displayed at the bottom of the screen. In the -stand-alone Info reader, it is displayed at the bottom right corner of -the screen; in Emacs, it is displayed on the modeline. If you see the -text @samp{Top} instead, it means that there is more text below that -does not fit. To move forward through the text and see another screen -full, press @key{SPC}, the Space bar. To move back up, press the key +@samp{All} will be displayed near the bottom of the screen, on the +mode line (usually, the line in inverse video). If you see the text +@samp{Top} instead, it means that there is more text below that does +not fit. To move forward through the text and see another screenful, +press @key{SPC}, the Space bar. To move back up, press the key labeled @samp{Backspace} or @samp{DEL} (on some keyboards, this key -might be labeled @samp{Delete}). +might be labeled @samp{Delete}). In a graphical Emacs, you can also use +@kbd{S-@key{SPC}} (press and hold the @key{Shift} key and then press +@key{SPC}) to move backwards, but this does not work in the +stand-alone Info reader (nor in Emacs, if you are using it in a +text-mode terminal). @ifinfo Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and @@ -208,15 +212,14 @@ This is line 59 @end format If you have managed to get here, go back to the beginning with -@kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you -understand the about the @samp{Space} and @samp{Backspace} keys. So -now type an @kbd{n}---just one character; don't type the quotes and -don't type the Return key afterward---to get to the normal start of -the course. +@key{DEL} (or @key{BACKSPACE}), and come back here again, then you +understand about the @samp{Space} and @samp{Backspace} keys. So now +type an @kbd{n}---just one character; don't type the quotes and don't +type the Return key afterward---to get to the normal start of the +course. @end ifinfo -@node Help, Help-P, Help-Small-Screen, Getting Started -@comment node-name, next, previous, up +@node Help @section How to use Info You are talking to the program Info, for reading documentation. @@ -262,8 +265,7 @@ links. mouse button on the @samp{Next} link to do the same ``the mouse way''. @end format -@node Help-P, Help-^L, Help, Getting Started -@comment node-name, next, previous, up +@node Help-P @section Returning to the Previous node @kindex p @r{(Info mode)} @@ -295,8 +297,7 @@ coming up. the @samp{Next} link, to get to the node @samp{Help-^L} and learn more. @end format -@node Help-^L, Help-Inv, Help-P, Getting Started -@comment node-name, next, previous, up +@node Help-^L @section The Space, DEL, B and ^L commands This node's mode line tells you that you are now at node @@ -403,13 +404,10 @@ repeatedly. >> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of the list until finished. Then type @key{SPC} several times. If you are using Emacs, the help will then go away automatically. + If you are using the stand-alone Info reader, type @kbd{x} to + return here. @end format - (If you are using the stand-alone Info reader, type @kbd{C-x 0} to -return here, that is---press and hold @key{CTRL}, type an @kbd{x}, -then release @key{CTRL} and @kbd{x}, and press @kbd{0}; that's a zero, -not the letter ``o''.) - From now on, you will encounter large nodes without warning, and will be expected to know how to use @key{SPC} and @key{BACKSPACE} to move around in them without being told. Since not all terminals have @@ -420,8 +418,7 @@ the same size screen, it would be impossible to warn you anyway. to visit the next node. @end format -@node Help-Inv, Help-M, Help-^L, Getting Started -@comment node-name, next, previous, up +@node Help-Inv @section Invisible text in Emacs Info Before discussing menus, we need to make some remarks that are only @@ -491,8 +488,7 @@ For instance, typing this sequence will come back here in three steps: Now type @kbd{]} to go to the next node and learn about menus. -@node Help-M, Help-Xref, Help-Inv, Getting Started -@comment node-name, next, previous, up +@node Help-M @section Menus and the @kbd{m} command @cindex menus in an Info document @@ -730,8 +726,7 @@ pointer shown in the header line (provided that you have a mouse). >> Now type @kbd{u} to move back up to @samp{Help-M}. @end format -@node Help-Xref, Help-Int, Help-M, Getting Started -@comment node-name, next, previous, up +@node Help-Xref @section Following Cross-References @cindex cross references in Info documents @@ -813,8 +808,30 @@ set @code{Info-hide-note-references} to a value other than @code{t} >> Now type @kbd{n} to learn more commands. @end format -@node Help-Int, Help-Q, Help-Xref, Getting Started -@comment node-name, next, previous, up + +@menu +* Help-Cross:: Target of a cross-reference. +@end menu + + +@node Help-Cross, , , Help-Xref +@subsection The node reached by the cross reference in Info + + This is the node reached by the cross reference named @samp{Cross}. + + While this node is specifically intended to be reached by a cross +reference, most cross references lead to nodes that ``belong'' +someplace else far away in the structure of an Info document. So you +cannot expect this node to have a @samp{Next}, @samp{Previous} or +@samp{Up} links pointing back to where you came from. In general, the +@kbd{l} (el) command is the only way to get back there. + +@format +>> Type @kbd{l} to return to the node where the cross reference was. +@end format + + +@node Help-Int @section Some intermediate Info commands The introductory course is almost over; please continue @@ -903,8 +920,7 @@ is @code{Info-top-node}. @c If a menu appears at the end of this node, remove it. @c It is an accident of the menu updating command. -@node Help-Q, , Help-Int, Getting Started -@comment node-name, next, previous, up +@node Help-Q @section Quitting Info @kindex q @r{(Info mode)} @@ -963,8 +979,7 @@ an actual @samp{?} character, the simplest way is to insert it using @end menu -@node Search Text, Search Index, , Advanced -@comment node-name, next, previous, up +@node Search Text @section @kbd{s} searches Info documents @cindex searching Info documents @@ -1005,8 +1020,7 @@ emacs, The GNU Emacs Manual}. In Emacs, you can disable this behavior by setting the variable @code{Info-isearch-search} to @code{nil} (@pxref{Emacs Info Variables}). -@node Search Index, Go to node, Search Text, Advanced -@comment node-name, next, previous, up +@node Search Index @section @kbd{i} searches the indices for specific subjects @cindex searching Info indices @@ -1058,8 +1072,7 @@ index-apropos} command in the stand-alone reader. It prompts for a string and then looks up that string in all the indices of all the Info documents installed on your system. -@node Go to node, Choose menu subtopic, Search Index, Advanced -@comment node-name, next, previous, up +@node Go to node @section @kbd{g} goes to a node by name @kindex g @r{(Info mode)} @@ -1086,8 +1099,7 @@ top node of the Emacs manual. all of the current file by typing @kbd{g*@key{RET}} or all of any other file with @kbd{g(@var{filename})*@key{RET}}. -@node Choose menu subtopic, Create Info buffer, Go to node, Advanced -@comment node-name, next, previous, up +@node Choose menu subtopic @section @kbd{1}--@kbd{9} choose a menu subtopic by its number @kindex 1 @r{through} 9 @r{(Info mode)} @@ -1112,8 +1124,7 @@ underlining. If you need to actually count items, it is better to use @kbd{m} instead, and specify the name, or use @key{TAB} to quickly move between menu items. -@node Create Info buffer, Emacs Info Variables, Choose menu subtopic, Advanced -@comment node-name, next, previous, up +@node Create Info buffer @section @kbd{M-n} creates a new independent Info buffer in Emacs @kindex M-n @r{(Info mode)} @@ -1134,16 +1145,18 @@ select in another window. Another way to produce new Info buffers in Emacs is to use a numeric prefix argument for the @kbd{C-h i} command (@code{info}) which switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} -switches to the buffer @samp{*info*<2>}, creating it if necessary. +switches to the buffer @file{*info*<2>}, creating it if necessary. @findex info-display-manual If you have created many Info buffers in Emacs, you might find it difficult to remember which buffer is showing which manual. You can use the command @kbd{M-x info-display-manual} to show an Info manual -by name, reusing an existing buffer if there is one. +by name, reusing an existing buffer if there is one. When given a +prefix argument, this command limits the completion alternatives to +currently visited info files, thus giving a convenient way to switch +between several manuals. -@node Emacs Info Variables, , Create Info buffer, Advanced -@comment node-name, next, previous, up +@node Emacs Info Variables @section Emacs Info-mode Variables The following variables may modify the behavior of Info-mode in Emacs; @@ -1204,13 +1217,14 @@ all text that could potentially be useful. @item Info-scroll-prefer-subnodes If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or -@key{DEL}) keys in a menu visit subnodes of the current node before -scrolling to its end or beginning, respectively. For example, if the -node's menu appears on the screen, the next @key{SPC} moves to a -subnode indicated by the following menu item. Setting this option to -@code{nil} results in behavior similar to the stand-alone Info reader -program, which visits the first subnode from the menu only when you -hit the end of the current node. The default is @code{nil}. +@key{DEL}, or @kbd{S-@key{SPC}}) keys in a menu visit subnodes of the +current node before scrolling to its end or beginning, respectively. +For example, if the node's menu appears on the screen, the next +@key{SPC} moves to a subnode indicated by the following menu item. +Setting this option to @code{nil} results in behavior similar to the +stand-alone Info reader program, which visits the first subnode from +the menu only when you hit the end of the current node. The default +is @code{nil}. @item Info-isearch-search If non-@code{nil}, isearch in Info searches through multiple nodes. @@ -1228,14 +1242,13 @@ this: @end vtable -@node Expert Info -@chapter Info for Experts +@node Further Reading +@chapter Further Reading @cindex Texinfo - This chapter explains how to write an Info file by hand. However, -in most cases, writing a Texinfo file is better, since you can use it -to make a printed manual or produce other formats, such as HTML and -DocBook, as well as for generating Info files. + Info files are created from Texinfo source files. You can use the +same source file to make a printed manual or produce other formats, +such as HTML and DocBook. The @code{makeinfo} command converts a Texinfo file into an Info file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are GNU @@ -1251,254 +1264,6 @@ Format}, for how to create an Info file from a Texinfo file. Documentation Format}, for how to install an Info file after you have created one. -However, if you want to edit an Info file manually and install it manually, -here is how. - -@menu -* Add:: Describes how to add new nodes to the hierarchy. - Also tells what nodes look like. -* Menus:: How to add to or create menus in Info nodes. -* Cross-refs:: How to add cross-references to Info nodes. -* Tags:: How to make tags tables for Info files. -* Checking:: Checking an Info File. -@end menu - -@node Add, Menus, , Expert Info -@comment node-name, next, previous, up -@section Adding a new node to Info - -To add a new topic to the list in the Info directory, you must: - -@enumerate -@item -Create some nodes, in some file, to document that topic. -@item -Put that topic in the menu in the directory. @xref{Menus, Menu}. -@end enumerate - -@cindex node delimiters - The new node can live in an existing documentation file, or in a new -one. It must have a @samp{^_} character before it (invisible to the -user; this node has one but you cannot see it), and it ends with either -a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If -you put in a @samp{^L} to end a new node, be sure that there is a -@samp{^_} after it to start the next one, since @samp{^L} cannot -@emph{start} a node. Also, a nicer way to make a node boundary be a -page boundary as well is to put a @samp{^L} @emph{right after} the -@samp{^_}.} - - The @samp{^_} starting a node must be followed by a newline or a -@samp{^L} newline, after which comes the node's header line. The -header line must give the node's name (by which Info finds it), and -state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} -nodes (if there are any). As you can see, this node's @samp{Up} node -is the node @samp{Expert Info}. The @samp{Next} node is @samp{Menus}. - -@cindex node header line format -@cindex format of node headers - The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up} -may appear in any order, anywhere in the header line, but the -recommended order is the one in this sentence. Each keyword must be -followed by a colon, spaces and tabs, and then the appropriate name. -The name may be terminated with a tab, a comma, or a newline. A space -does not end it; node names may contain spaces. The case of letters -in the names is insignificant. - -@cindex node name format -@cindex Directory node - A node name has two forms. A node in the current file is named by -what appears after the @samp{Node: } in that node's first line. For -example, this node's name is @samp{Add}. A node in another file is -named by @samp{(@var{filename})@var{node-within-file}}, as in -@samp{(info)Add} for this node. If the file name starts with @samp{./}, -then it is relative to the current directory; otherwise, it is -relative starting from the standard directory for Info files of your -site. The name @samp{(@var{filename})Top} can be abbreviated to just -@samp{(@var{filename})}. By convention, the name @samp{Top} is used -for the ``highest'' node in any single file---the node whose @samp{Up} -points out of the file. The @samp{Directory} node is @file{(dir)}, it -points to a file @file{dir} which holds a large menu listing all the -Info documents installed on your site. The @samp{Top} node of a -document file listed in the @samp{Directory} should have an @samp{Up: -(dir)} in it. - -@cindex unstructured documents - The node name @kbd{*} is special: it refers to the entire file. -Thus, @kbd{g*} shows you the whole current file. The use of the -node @kbd{*} is to make it possible to make old-fashioned, -unstructured files into nodes of the tree. - - The @samp{Node:} name, in which a node states its own name, must not -contain a file name, since when Info searches for a node, it does not -expect a file name to be there. The @samp{Next}, @samp{Previous} and -@samp{Up} names may contain them. In this node, since the @samp{Up} -node is in the same file, it was not necessary to use one. - - Note that the nodes in this file have a file name in the header -line. The file names are ignored by Info, but they serve as comments -to help identify the node for the user. - -@node Menus, Cross-refs, Add, Expert Info -@comment node-name, next, previous, up -@section How to Create Menus - - Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. -The @kbd{m} command searches the current node's menu for the topic which it -reads from the terminal. - -@cindex menu and menu entry format - A menu begins with a line starting with @w{@samp{* Menu:}}. The -rest of the line is a comment. After the starting line, every line -that begins with a @samp{* } lists a single topic. The name of the -topic---what the user must type at the @kbd{m}'s command prompt to -select this topic---comes right after the star and space, and is -followed by a colon, spaces and tabs, and the name of the node which -discusses that topic. The node name, like node names following -@samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a -tab, comma, or newline; it may also be terminated with a period. - - If the node name and topic name are the same, then rather than -giving the name twice, the abbreviation @samp{* @var{name}::} may be -used (and should be used, whenever possible, as it reduces the visual -clutter in the menu). - - It is considerate to choose the topic names so that they differ -from each other very near the beginning---this allows the user to type -short abbreviations. In a long menu, it is a good idea to capitalize -the beginning of each item name which is the minimum acceptable -abbreviation for it (a long menu is more than 5 or so entries). - - The nodes listed in a node's menu are called its ``subnodes,'' and it -is their ``superior''. They should each have an @samp{Up:} pointing at -the superior. It is often useful to arrange all or most of the subnodes -in a sequence of @samp{Next} and @samp{Previous} pointers so that -someone who wants to see them all need not keep revisiting the Menu. - - The Info Directory is simply the menu of the node @samp{(dir)Top}---that -is, node @samp{Top} in file @file{.../info/dir}. You can put new entries -in that menu just like any other menu. The Info Directory is @emph{not} the -same as the file directory called @file{info}. It happens that many of -Info's files live in that file directory, but they do not have to; and -files in that directory are not automatically listed in the Info -Directory node. - - Also, although the Info node graph is claimed to be a ``hierarchy,'' -in fact it can be @emph{any} directed graph. Shared structures and -pointer cycles are perfectly possible, and can be used if they are -appropriate to the meaning to be expressed. There is no need for all -the nodes in a file to form a connected structure. In fact, this file -has two connected components. You are in one of them, which is under -the node @samp{Top}; the other contains the node @samp{Help} which the -@kbd{h} command goes to. In fact, since there is no garbage -collector on the node graph, nothing terrible happens if a substructure -is not pointed to, but such a substructure is rather useless since nobody -can ever find out that it exists. - -@node Cross-refs, Tags, Menus, Expert Info -@comment node-name, next, previous, up -@section Creating Cross References - -@cindex cross reference format - A cross reference can be placed anywhere in the text, unlike a menu -item which must go at the front of a line. A cross reference looks -like a menu item except that it has @samp{*note} instead of @samp{*}. -It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are -so often part of node names. If you wish to enclose a cross reference -in parentheses, terminate it with a period first. Here are two -examples of cross references pointers: - -@example -*Note details: commands. (See *note 3: Full Proof.) -@end example - -@noindent -@emph{These are just examples.} The places they ``lead to'' do not -really exist! - -@menu -* Help-Cross:: Target of a cross-reference. -@end menu - - -@node Help-Cross, , , Cross-refs -@subsection The node reached by the cross reference in Info - - This is the node reached by the cross reference named @samp{Cross}. - - While this node is specifically intended to be reached by a cross -reference, most cross references lead to nodes that ``belong'' -someplace else far away in the structure of an Info document. So you -cannot expect this node to have a @samp{Next}, @samp{Previous} or -@samp{Up} links pointing back to where you came from. In general, the -@kbd{l} (el) command is the only way to get back there. - -@format ->> Type @kbd{l} to return to the node where the cross reference was. -@end format - -@node Tags, Checking, Cross-refs, Expert Info -@comment node-name, next, previous, up -@section Tags Tables for Info Files - -@cindex tags tables in Info files - You can speed up the access to nodes of a large Info file by giving -it a tags table. Unlike the tags table for a program, the tags table for -an Info file lives inside the file itself and is used -automatically whenever Info reads in the file. - -@findex Info-tagify - To make a tags table, go to a node in the file using Emacs Info mode and type -@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the -file. Info files produced by the @code{makeinfo} command that is part -of the Texinfo package always have tags tables to begin with. - -@cindex stale tags tables -@cindex update Info tags table - Once the Info file has a tags table, you must make certain it is up -to date. If you edit an Info file directly (as opposed to editing its -Texinfo source), and, as a result of deletion of text, any node moves back -more than a thousand characters in the file from the position -recorded in the tags table, Info will no longer be able to find that -node. To update the tags table, use the @code{Info-tagify} command -again. - - An Info file tags table appears at the end of the file and looks like -this: - -@example -^_^L -Tag Table: -File: info, Node: Cross-refs^?21419 -File: info, Node: Tags^?22145 -^_ -End Tag Table -@end example - -@noindent -Note that it contains one line per node, and this line contains -the beginning of the node's header (ending just after the node name), -a @samp{DEL} character, and the character position in the file of the -beginning of the node. - -@node Checking, , Tags, Expert Info -@section Checking an Info File - -When creating an Info file, it is easy to forget the name of a node when -you are making a pointer to it from another node. If you put in the -wrong name for a node, this is not detected until someone tries to go -through the pointer using Info. Verification of the Info file is an -automatic process which checks all pointers to nodes and reports any -pointers which are invalid. Every @samp{Next}, @samp{Previous}, and -@samp{Up} is checked, as is every menu item and every cross reference. In -addition, any @samp{Next} which does not have a @samp{Previous} pointing -back is reported. Only pointers within the file are checked, because -checking pointers to other files would be terribly slow. But those are -usually few. - -@findex Info-validate -To check an Info file, do @kbd{M-x Info-validate} while looking at any -node of the file with Emacs Info mode. - @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index 210b709c1ea..ef253a0138c 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -1,18 +1,17 @@ \input texinfo.tex -@setfilename ../../info/mairix-el +@setfilename ../../info/mairix-el.info @settitle Emacs Interface for Mairix - -@documentencoding UTF-8 +@include docstyle.texi @copying -Copyright @copyright{} 2008--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2008--2015 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'', +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''. @@ -140,7 +139,7 @@ not tested (yet). You should make sure that you don't accidentally index the search results produced by mairix. This can be done by pointing -`mairix-file-path' to a directory which is surely not indexed by mairix. +@code{mairix-file-path} to a directory which is surely not indexed by mairix. Another possibility is to use something like @example @@ -222,12 +221,12 @@ Here's a description of the available interactive functions: @vindex mairix-search-options Call mairix with a search query. You will also be asked if you want to include whole threads. The results are saved by mairix in the default -mail file, which is set through the variable `mairix-search-file', which -again is prefixed by `mairix-file-path'. The results will then be +mail file, which is set through the variable @code{mairix-search-file}, which +again is prefixed by @code{mairix-file-path}. The results will then be displayed with the chosen mail program. The command used to call mairix -is specified by the variable `mairix-command', together with the options -`mairix-search-options'. The latter has the default ``-F'' for making -searching faster. +is specified by the variable @code{mairix-command}, together with the options +@code{mairix-search-options}. The latter has the default @option{-F} +for making searching faster. @item mairix-widget-search @kindex M-x mairix-widget-search @@ -239,7 +238,7 @@ how it works. You can then directly call mairix with the search term or save it for future use. Since mairix allows almost arbitrary combinations of search commands (like ``tc'' for ``to or cc''), you might want to include some other fields. This can be easily done by -modifying `mairix-widget-fields-list'. +modifying @code{mairix-widget-fields-list}. @item mairix-widget-search-based-on-article @kindex M-x mairix-widget-search-based-on-article @@ -270,7 +269,7 @@ for the search and will then be asked if you want to save your saved searches in your @file{.emacs}. If you answer with yes, the variable @code{mairix-saved-searches} will be saved in the customize section of your @file{.emacs}. You can also do this later by using -`mairix-edit-saved-searches'. +@code{mairix-edit-saved-searches}. @item mairix-use-saved-search @kindex M-x mairix-use-saved-search @@ -303,11 +302,12 @@ maybe you like it. @vindex mairix-update-options @vindex mairix-synchronous-update Call mairix to update the database. Mairix will be called with the -options `mairix-update-options'; the default is ``-F'' and ``-Q'' to +options @code{mairix-update-options}; the default is @option{-F} and +@option{-Q} to make updates as fast as possible. Note that by using these options, absolutely no integrity checking is done. If your database somehow gets -corrupted, simply delete it and update. If `mairix-synchronous-update' -is nil (the default), mairix will be called in a subprocess so Emacs +corrupted, simply delete it and update. If @code{mairix-synchronous-update} +is @code{nil} (the default), mairix will be called in a subprocess so Emacs will still be usable while the update is done. @end table diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in deleted file mode 100644 index 11c76dcfcf7..00000000000 --- a/doc/misc/makefile.w32-in +++ /dev/null @@ -1,431 +0,0 @@ -#### -*- Makefile -*- for documentation other than the Emacs manual. - -# Copyright (C) 2003-2013 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. - - -# Where to find the source code. The source code for Emacs's C kernel is -# expected to be in $(srcdir)/src, and the source code for Emacs's -# utility programs is expected to be in $(srcdir)/lib-src. This is -# set by the configure script's `--srcdir' option. -srcdir=. - -infodir = $(srcdir)/../../info - -## Directory with emacsver.texi. -## Currently only used by efaq; could be added to MAKEINFO. -emacsdir = $(srcdir)/../emacs - -INFO_EXT=.info -INFO_OPTS=--no-split - -# The makeinfo program is part of the Texinfo distribution. -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force -I$(emacsdir) -MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat -INFO_TARGETS = $(infodir)/ccmode$(INFO_EXT) \ - $(infodir)/cl$(INFO_EXT) $(infodir)/dbus$(INFO_EXT) $(infodir)/dired-x$(INFO_EXT) \ - $(infodir)/ediff$(INFO_EXT) $(infodir)/forms$(INFO_EXT) $(infodir)/gnus$(INFO_EXT) \ - $(infodir)/message$(INFO_EXT) $(infodir)/sieve$(INFO_EXT) $(infodir)/pgg$(INFO_EXT) \ - $(infodir)/emacs-mime$(INFO_EXT) $(infodir)/info$(INFO_EXT) $(infodir)/mh-e$(INFO_EXT) \ - $(infodir)/reftex$(INFO_EXT) $(infodir)/sc$(INFO_EXT) $(infodir)/vip$(INFO_EXT) \ - $(infodir)/viper$(INFO_EXT) $(infodir)/widget$(INFO_EXT) $(infodir)/efaq$(INFO_EXT) \ - $(infodir)/ada-mode$(INFO_EXT) $(infodir)/autotype$(INFO_EXT) $(infodir)/calc$(INFO_EXT) \ - $(infodir)/idlwave$(INFO_EXT) $(infodir)/eudc$(INFO_EXT) $(infodir)/ebrowse$(INFO_EXT) \ - $(infodir)/pcl-cvs$(INFO_EXT) $(infodir)/woman$(INFO_EXT) $(infodir)/eshell$(INFO_EXT) \ - $(infodir)/org$(INFO_EXT) $(infodir)/url$(INFO_EXT) $(infodir)/speedbar$(INFO_EXT) \ - $(infodir)/tramp$(INFO_EXT) $(infodir)/ses$(INFO_EXT) $(infodir)/smtpmail$(INFO_EXT) \ - $(infodir)/flymake$(INFO_EXT) $(infodir)/newsticker$(INFO_EXT) $(infodir)/rcirc$(INFO_EXT) \ - $(infodir)/erc$(INFO_EXT) $(infodir)/ert$(INFO_EXT) \ - $(infodir)/remember$(INFO_EXT) $(infodir)/nxml-mode$(INFO_EXT) \ - $(infodir)/epa$(INFO_EXT) $(infodir)/mairix-el$(INFO_EXT) $(infodir)/sasl$(INFO_EXT) \ - $(infodir)/auth$(INFO_EXT) $(infodir)/eieio$(INFO_EXT) $(infodir)/ede$(INFO_EXT) \ - $(infodir)/semantic$(INFO_EXT) $(infodir)/edt$(INFO_EXT) $(infodir)/emacs-gnutls$(INFO_EXT) \ - $(infodir)/srecode$(INFO_EXT) $(infodir)/bovine$(INFO_EXT) \ - $(infodir)/wisent$(INFO_EXT) $(infodir)/htmlfontify$(INFO_EXT) -DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \ - ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ - sieve.dvi pgg.dvi mh-e.dvi \ - reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \ - ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \ - pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \ - speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \ - newsticker.dvi rcirc.dvi erc.dvi ert.dvi \ - remember.dvi nxml-mode.dvi \ - epa.dvi mairix-el.dvi sasl.dvi auth.dvi eieio.dvi ede.dvi \ - semantic.dvi edt.dvi emacs-gnutls.dvi srecode.dvi bovine.dvi \ - wisent.dvi htmlfontify.dvi -INFOSOURCES = info.texi - -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - texi2dvi $< - -TEXI2DVI = texi2dvi -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - - -info: $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -# Note that all the Info targets build the Info files -# in srcdir. There is no provision for Info files -# to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -$(infodir)/dir: - $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -# The following target uses an explicit -o switch to work around -# the @setfilename directive in info.texi, which is required for -# the Texinfo distribution. -# Some Windows ports of makeinfo seem to require -o to come before the -# texi filename, contrary to GNU standards. - -$(infodir)/info$(INFO_EXT): $(INFOSOURCES) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ info.texi - -info.dvi: $(INFOSOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi - - -$(infodir)/ccmode$(INFO_EXT): cc-mode.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ cc-mode.texi -cc-mode.dvi: cc-mode.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/cc-mode.texi - -$(infodir)/ada-mode$(INFO_EXT): ada-mode.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ada-mode.texi -ada-mode.dvi: ada-mode.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ada-mode.texi - -$(infodir)/pcl-cvs$(INFO_EXT): pcl-cvs.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ pcl-cvs.texi -pcl-cvs.dvi: pcl-cvs.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/pcl-cvs.texi - -$(infodir)/eshell$(INFO_EXT): eshell.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ eshell.texi -eshell.dvi: eshell.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/eshell.texi - -$(infodir)/cl$(INFO_EXT): cl.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ cl.texi -cl.dvi: cl.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/cl.texi - -$(infodir)/dbus$(INFO_EXT): dbus.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ dbus.texi -dbus.dvi: dbus.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/dbus.texi - -$(infodir)/dired-x$(INFO_EXT): dired-x.texi $(emacsdir)/emacsver.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ dired-x.texi -dired-x.dvi: dired-x.texi $(emacsdir)/emacsver.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/dired-x.texi - -$(infodir)/ediff$(INFO_EXT): ediff.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ediff.texi -ediff.dvi: ediff.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ediff.texi - -$(infodir)/flymake$(INFO_EXT): flymake.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ flymake.texi -flymake.dvi: flymake.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/flymake.texi - -$(infodir)/forms$(INFO_EXT): forms.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ forms.texi -forms.dvi: forms.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/forms.texi - -# gnus/message/emacs-mime/sieve/pgg are part of Gnus: -$(infodir)/gnus$(INFO_EXT): gnus.texi gnus-overrides.texi message.texi emacs-mime.texi \ - sieve.texi pgg.texi sasl.texi gnus-news.texi gnus-faq.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ gnus.texi -gnus.dvi: gnus.texi gnus-overrides.texi message.texi emacs-mime.texi \ - sieve.texi pgg.texi sasl.texi gnus-news.texi gnus-faq.texi - sed -e "/@iflatex/,/@end iflatex/d" $(srcdir)/gnus.texi > gnustmp.texi - $(ENVADD) $(TEXI2DVI) gnustmp.texi - cp gnustmp.dvi $*.dvi - rm gnustmp.* -# -$(infodir)/message$(INFO_EXT): message.texi gnus-overrides.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ message.texi -message.dvi: message.texi gnus-overrides.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/message.texi -# -$(infodir)/emacs-mime$(INFO_EXT): emacs-mime.texi gnus-overrides.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ --enable-encoding emacs-mime.texi -emacs-mime.dvi: emacs-mime.texi gnus-overrides.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-mime.texi -# -$(infodir)/sieve$(INFO_EXT): sieve.texi gnus-overrides.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ sieve.texi -sieve.dvi: sieve.texi gnus-overrides.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/sieve.texi -# -$(infodir)/pgg$(INFO_EXT): pgg.texi gnus-overrides.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ pgg.texi -pgg.dvi: pgg.texi gnus-overrides.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/pgg.texi - -$(infodir)/mh-e$(INFO_EXT): mh-e.texi gpl.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ mh-e.texi -mh-e.dvi: mh-e.texi gpl.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/mh-e.texi - -$(infodir)/reftex$(INFO_EXT): reftex.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ reftex.texi -reftex.dvi: reftex.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/reftex.texi - -$(infodir)/remember$(INFO_EXT): remember.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ remember.texi -remember.dvi: remember.texix - $(ENVADD) $(TEXI2DVI) $(srcdir)/remember.texi - -$(infodir)/sasl$(INFO_EXT): sasl.texi gnus-overrides.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ sasl.texi -sasl.dvi: sasl.texi gnus-overrides.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/sasl.texi - -$(infodir)/sc$(INFO_EXT): sc.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ sc.texi -sc.dvi: sc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/sc.texi - -$(infodir)/vip$(INFO_EXT): vip.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ vip.texi -vip.dvi: vip.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/vip.texi - -$(infodir)/viper$(INFO_EXT): viper.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ viper.texi -viper.dvi: viper.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/viper.texi - -$(infodir)/widget$(INFO_EXT): widget.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ widget.texi -widget.dvi: widget.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/widget.texi - -$(infodir)/efaq$(INFO_EXT): faq.texi $(emacsdir)/emacsver.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ faq.texi -faq.dvi: faq.texi $(emacsdir)/emacsver.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/faq.texi - -$(infodir)/autotype$(INFO_EXT): autotype.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ autotype.texi -autotype.dvi: autotype.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/autotype.texi - -$(infodir)/calc$(INFO_EXT): calc.texi $(emacsdir)/emacsver.texi gpl.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ calc.texi -calc.dvi: calc.texi $(emacsdir)/emacsver.texi gpl.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$(INFO_EXT): idlwave.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ idlwave.texi -idlwave.dvi: idlwave.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/idlwave.texi - -$(infodir)/eudc$(INFO_EXT): eudc.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ eudc.texi -eudc.dvi: eudc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/eudc.texi - -$(infodir)/ebrowse$(INFO_EXT): ebrowse.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ebrowse.texi -ebrowse.dvi: ebrowse.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ebrowse.texi - -$(infodir)/woman$(INFO_EXT): woman.texi $(emacsdir)/emacsver.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ woman.texi -woman.dvi: woman.texi $(emacsdir)/emacsver.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/woman.texi - -$(infodir)/speedbar$(INFO_EXT): speedbar.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ speedbar.texi -speedbar.dvi: speedbar.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/speedbar.texi - -$(infodir)/tramp$(INFO_EXT): tramp.texi trampver.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ tramp.texi -tramp.dvi: tramp.texi trampver.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/tramp.texi - -$(infodir)/ses$(INFO_EXT): ses.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ses.texi -ses.dvi: ses.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ses.texi - -$(infodir)/smtpmail$(INFO_EXT): smtpmail.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ smtpmail.texi -smtpmail.dvi: smtpmail.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/smtpmail.texi - -$(infodir)/org$(INFO_EXT): org.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ org.texi -org.dvi: org.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/org.texi - -$(infodir)/url$(INFO_EXT): url.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ url.texi -url.dvi: url.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/url.texi - -$(infodir)/newsticker$(INFO_EXT): newsticker.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ newsticker.texi -newsticker.dvi: newsticker.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi - -$(infodir)/nxml-mode$(INFO_EXT): nxml-mode.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ nxml-mode.texi -nxml-mod.dvi: nxml-mode.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/nxml-mode.texi - -$(infodir)/rcirc$(INFO_EXT): rcirc.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ rcirc.texi -rcirc.dvi: rcirc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/rcirc.texi - -$(infodir)/erc$(INFO_EXT): erc.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ erc.texi -erc.dvi: erc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/erc.texi - -$(infodir)/ert$(INFO_EXT): ert.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ert.texi -ert.dvi: ert.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ert.texi - -$(infodir)/epa$(INFO_EXT): epa.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ epa.texi -epa.dvi: epa.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/epa.texi - -$(infodir)/mairix-el$(INFO_EXT): mairix-el.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ mairix-el.texi -mairix-el.dvi: mairix-el.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/mairix-el.texi - -$(infodir)/auth$(INFO_EXT): auth.texi gnus-overrides.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ auth.texi -auth.dvi: auth.texi gnus-overrides.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/auth.texi - -$(infodir)/eieio$(INFO_EXT): eieio.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ eieio.texi -eieio.dvi: eieio.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/eieio.texi - -$(infodir)/ede$(INFO_EXT): ede.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ede.texi -ede.dvi: ede.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ede.texi - -$(infodir)/semantic$(INFO_EXT): semantic.texi sem-user.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ semantic.texi -semantic.dvi: semantic.texi sem-user.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/semantic.texi - -$(infodir)/edt$(INFO_EXT): edt.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ edt.texi -edt.dvi: edt.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/edt.texi - -$(infodir)/emacs-gnutls$(INFO_EXT): emacs-gnutls.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ emacs-gnutls.texi -emacs-gnutls.dvi: emacs-gnutls.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-gnutls.texi - -$(infodir)/srecode$(INFO_EXT): srecode.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ srecode.texi -srecode.dvi: srecode.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/srecode.texi - -$(infodir)/bovine$(INFO_EXT): bovine.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ bovine.texi -bovine.dvi: bovine.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/bovine.texi - -$(infodir)/wisent$(INFO_EXT): wisent.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ wisent.texi -wisent.dvi: wisent.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/wisent.texi - -$(infodir)/htmlfontify$(INFO_EXT): htmlfontify.texi - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ htmlfontify.texi -htmlfontify.dvi: htmlfontify.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/htmlfontify.texi - - -$(INFO_TARGETS): doclicense.texi -$(DVI_TARGETS): doclicense.texi - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* - -clean: mostlyclean - - $(DEL) *.dvi - - $(DEL) $(infodir)/ccmode* $(infodir)/cl* \ - $(infodir)/dbus* $(infodir)/dired-x* \ - $(infodir)/ediff* $(infodir)/forms* \ - $(infodir)/gnus* $(infodir)/info* \ - $(infodir)/message* $(infodir)/mh-e* \ - $(infodir)/reftex* $(infodir)/sc* \ - $(infodir)/vip* $(infodir)/widget* \ - $(infodir)/efaq* $(infodir)/ada-mode* \ - $(infodir)/autotype* $(infodir)/calc* \ - $(infodir)/idlwave* $(infodir)/eudc* \ - $(infodir)/ebrowse* $(infodir)/pcl-cvs* \ - $(infodir)/woman* $(infodir)/eshell* \ - $(infodir)/speedbar* $(infodir)/tramp* \ - $(infodir)/ses* $(infodir)/smtpmail* \ - $(infodir)/url* $(infodir)/org* \ - $(infodir)/flymake* $(infodir)/newsticker* \ - $(infodir)/sieve* $(infodir)/pgg* \ - $(infodir)/erc* $(infodir)/ert* $(infodir)/rcirc* \ - $(infodir)/remember* $(infodir)/nxml-mode* \ - $(infodir)/epa* $(infodir)/sasl* \ - $(infodir)/mairix-el* $(infodir)/auth* \ - $(infodir)/eieio* $(infodir)/ede* \ - $(infodir)/semantic* $(infodir)edt* \ - $(infodir)/emacs-gnutls* $(infodir)/srecode* \ - $(infodir)/bovine* $(infodir)/wisent* \ - $(infodir)/htmlfontify* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc -# Don't delete these, because they are outside the current directory. -# for file in $(INFO_TARGETS); do rm -f $${file}*; done - - -# Formerly this directory had texindex.c and getopt.c in it -# and this makefile built them to make texindex. -# That caused trouble because this is run entirely in the source directory. -# Since we expect to get texi2dvi from elsewhere, -# it is ok to expect texindex from elsewhere also. diff --git a/doc/misc/message.texi b/doc/misc/message.texi index a98c7e48e53..d63f7e6a8f6 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -2,21 +2,22 @@ @include gnus-overrides.texi -@setfilename ../../info/message +@setfilename ../../info/message.info @settitle Message Manual +@include docstyle.texi @synindex fn cp @synindex vr cp @synindex pg cp @copying This file documents Message, the Emacs message composition mode. -Copyright @copyright{} 1996--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1996--2015 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'', +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''. @@ -309,7 +310,13 @@ news. @table @code @item message-forward-ignored-headers @vindex message-forward-ignored-headers -All headers that match this regexp will be deleted when forwarding a message. +In non-@code{nil}, all headers that match this regexp will be deleted +when forwarding a message. + +@item message-forward-included-headers +@vindex message-forward-included-headers +In non-@code{nil}, only headers that match this regexp will be kept +when forwarding a message. @item message-make-forward-subject-function @vindex message-make-forward-subject-function @@ -741,9 +748,8 @@ by the @code{message-cross-post-note-function} variable. @item C-c C-f t @kindex C-c C-f t @findex message-reduce-to-to-cc -Replace contents of @samp{To} header with contents of @samp{Cc} or -@samp{Bcc} header. (Iff @samp{Cc} header is not present, @samp{Bcc} -header will be used instead.) +Replace contents of @samp{To} header with contents of @samp{Cc} +header (or the @samp{Bcc} header, if there is no @samp{Cc} header). @item C-c C-f w @kindex C-c C-f w @@ -1450,7 +1456,7 @@ Look like @code{angles} if that doesn't require quoting, and Headers in this list that were previously generated by Message will be deleted before posting. Let's say you post an article. Then you decide to post it again to some other group, you naughty boy, so you jump back -to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and +to the @file{*post-buf*} buffer, edit the @code{Newsgroups} line, and ship it off again. By default, this variable makes sure that the old generated @code{Message-ID} is deleted, and a new one generated. If this isn't done, the entire empire would probably crumble, anarchy would @@ -2000,13 +2006,13 @@ that look like: Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes: @end example -@c FIXME: Add `message-insert-formatted-citation-line' and -@c `message-citation-line-format' +@c FIXME: Add 'message-insert-formatted-citation-line' and +@c 'message-citation-line-format'. Point will be at the beginning of the body of the message when this function is called. -Note that Gnus provides a feature where clicking on `writes:' hides the +Note that Gnus provides a feature where clicking on @samp{writes:} hides the cited text. If you change the citation line too much, readers of your messages will have to adjust their Gnus, too. See the variable @code{gnus-cite-attribution-suffix}. @xref{Article Highlighting, , @@ -2131,7 +2137,7 @@ translation process. @vindex message-fill-column @cindex auto-fill Local value for the column beyond which automatic line-wrapping should -happen for message buffers. If non-nil (the default), also turn on +happen for message buffers. If non-@code{nil} (the default), also turn on auto-fill in message buffers. @item message-signature-separator diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index a0ea0fe6de9..54f759118fa 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -3,8 +3,9 @@ @c Note: This document requires makeinfo version 4.6 or greater to build. @c @c %**start of header -@setfilename ../../info/mh-e +@setfilename ../../info/mh-e.info @settitle The MH-E Manual +@include docstyle.texi @c %**end of header @c Version of the software and manual. @@ -24,7 +25,7 @@ This is version @value{VERSION}@value{EDITION} of @cite{The MH-E Manual}, last updated @value{UPDATED}. -Copyright @copyright{} 1995, 2001--2003, 2005--2013 Free Software +Copyright @copyright{} 1995, 2001--2003, 2005--2015 Free Software Foundation, Inc. @c This dual license has been agreed upon by the FSF. @@ -37,7 +38,7 @@ under the terms of either: @item the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, -with the Front-Cover texts being ``A GNU Manual,'' and with the +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.'' @@ -226,7 +227,7 @@ have, see @ref{Getting Started}. @kindex C-h t If you don't already use GNU Emacs but want to learn more, you can -read an online tutorial by starting GNU Emacs and typing @kbd{C-h t} +read a built-in tutorial by starting GNU Emacs and typing @kbd{C-h t} (@code{help-with-tutorial}). (To learn about this notation, see @ref{Conventions}.) If you want to take the plunge, consult the @iftex @@ -245,7 +246,8 @@ If more information is needed, you can go to the Unix manual pages of the individual MH commands. When the name is not obvious, I'll guide you to a relevant MH manual page that describes the action more fully. -@cindex @cite{MH & nmh: Email for Users & Programmers} +@c ":" does not work in index entries in Info. +@cindex @cite{MH & nmh - Email for Users & Programmers} @cindex MH book @cindex info @kindex C-h i @@ -571,10 +573,10 @@ you need to know about MH to use MH-E, but the more you know about MH, the more you can leverage its power. See the @uref{@value{MH-BOOK-HOME}/../, MH book} to learn more about MH. -@cindex @samp{Path:} MH profile component +@cindex @samp{Path} MH profile component @cindex MH profile @cindex MH profile component -@cindex MH profile component, @samp{Path:} +@cindex MH profile component, @samp{Path} Your MH environment includes your @dfn{MH profile} which is found in the file @file{~/.mh_profile}, or the file named in the environment @@ -627,14 +629,14 @@ actually cause problems. @end quotation @sp 1 -@cindex MH profile component, @samp{Draft-Folder:} -@cindex MH profile component, @samp{Path:} -@cindex MH profile component, @samp{Previous-Sequence:} -@cindex MH profile component, @samp{Unseen-Sequence:} -@cindex @samp{Draft-Folder:} MH profile component -@cindex @samp{Path:} MH profile component -@cindex @samp{Previous-Sequence:} MH profile component -@cindex @samp{Unseen-Sequence:} MH profile component +@cindex MH profile component, @samp{Draft-Folder} +@cindex MH profile component, @samp{Path} +@cindex MH profile component, @samp{Previous-Sequence} +@cindex MH profile component, @samp{Unseen-Sequence} +@cindex @samp{Draft-Folder} MH profile component +@cindex @samp{Path} MH profile component +@cindex @samp{Previous-Sequence} MH profile component +@cindex @samp{Unseen-Sequence} MH profile component @findex mh-find-path @vindex mh-draft-folder @vindex mh-find-path-hook @@ -1064,9 +1066,9 @@ This chapter begins the meat of the manual which goes into more detail about every MH-E command and option. @cindex Emacs, info -@cindex Emacs, online help +@cindex Emacs, built-in help @cindex info -@cindex online help +@cindex built-in help @findex describe-mode @findex mh-help @kindex ? @@ -1081,12 +1083,12 @@ summaries at the beginning of each chapter. In case you have or would like to rebind the keys, the command summaries also list the associated Emacs Lisp function. Furthermore, even if you're stranded on a desert island with a laptop and are without your manuals, you can -get a summary of all these commands with GNU Emacs online help: use +get a summary of all these commands with GNU Emacs built-in help: use @kbd{C-h m} (@code{describe-mode}) for a brief summary of commands, @kbd{?} (@code{mh-help}) for an even briefer summary@footnote{This -help appears in a buffer called @samp{*MH-E Help*} +help appears in a buffer called @file{*MH-E Help*} (@pxref{Miscellaneous}).} (@kbd{C-c ?} in MH-Letter mode), or @kbd{C-h -i} to read this manual via Info. The online help is quite good; try +i} to read this manual via Info. The built-in help is quite good; try running @kbd{C-h C-h}. This brings up a list of available help topics, one of which displays the documentation for a given key (like @kbd{C-h k C-n}). Another useful help feature is to view the manual section @@ -1118,21 +1120,21 @@ exist, @c Yes, some of the stuff in the following sections is redundant, but @c TeX barfs if the @ifs are inside the @footnote. @iftex -@footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available -online in the Info system by typing @kbd{C-h i m Emacs Lisp +@footnote{The @cite{GNU Emacs Lisp Reference Manual} should be available +via the Info system by typing @kbd{C-h i m Emacs Lisp @key{RET}}. It is also available online at @* @uref{http://www.gnu.org/software/emacs/manual/elisp.html}.} @end iftex @ifinfo @footnote{@xref{Top, The GNU Emacs Lisp Reference Manual, , elisp, GNU -Emacs Lisp Reference Manual}, which may be available online in the +Emacs Lisp Reference Manual}, which should be available via the Info system. It is also available online at @uref{http://www.gnu.org/software/emacs/manual/elisp.html}.} @end ifinfo @ifhtml @footnote{The @uref{http://www.gnu.org/software/emacs/manual/elisp.html, -The GNU Emacs Lisp Reference Manual} may also be available online in +The GNU Emacs Lisp Reference Manual} should be available via the Info system by typing @kbd{C-h i m Emacs Lisp @key{RET}}.} @end ifhtml and you can look at the code itself for examples. Look in the Emacs @@ -1140,7 +1142,7 @@ Lisp directory on your system (such as @file{/usr/local/share/emacs/lisp/mh-e}) and find all the @file{mh-*.el} files there. When calling MH-E and other Emacs Lisp functions directly from Emacs Lisp code, you'll need to know the correct arguments. Use -the online help for this. For example, try @kbd{C-h f +the built-in help for this. For example, try @kbd{C-h f mh-execute-commands @key{RET}}. If you write your own functions, please do not prefix your symbols (variables and functions) with @samp{mh-}. This prefix is reserved for the MH-E package. To avoid @@ -2076,12 +2078,12 @@ entire class of fields that start with the same prefix. If you think a header field should be generally ignored, please update @uref{https://sourceforge.net/p/mh-e/bugs/245/, SF #245}. -@cindex header field, @samp{Face:} -@cindex header field, @samp{X-Face:} -@cindex header field, @samp{X-Image-URL:} -@cindex @samp{Face:} header field -@cindex @samp{X-Face:} header field -@cindex @samp{X-Image-URL:} header field +@cindex header field, @samp{Face} +@cindex header field, @samp{X-Face} +@cindex header field, @samp{X-Image-URL} +@cindex @samp{Face} header field +@cindex @samp{X-Face} header field +@cindex @samp{X-Image-URL} header field @vindex mh-show-use-xface-flag MH-E can display the content of @samp{Face:}, @samp{X-Face:}, and @@ -2452,9 +2454,9 @@ permanently by turning on the option MH-E cannot display all attachments inline however. It can display text (including @sc{html}) and images. -@cindex header field, @samp{Content-Disposition:} +@cindex header field, @samp{Content-Disposition} @cindex inline images -@cindex @samp{Content-Disposition:} header field +@cindex @samp{Content-Disposition} header field @vindex mh-max-inline-image-height @vindex mh-max-inline-image-width @@ -3157,13 +3159,13 @@ code to @file{~/.emacs}. @smalllisp @group (defvar my-mh-screen-saved nil - "Set to non-@code{nil} when MH-E window configuration shown.") + "Set to non-nil when MH-E window configuration shown.") (defvar my-normal-screen nil "Normal window configuration.") (defvar my-mh-screen nil "MH-E window configuration.") (defun my-mh-rmail (&optional arg) "Toggle between MH-E and normal screen configurations. -With non-@code{nil} or prefix argument, @i{inc} mailbox as well +With non-nil or prefix argument, include mailbox as well when going into mail." (interactive "P") ; @r{user callable function, P=prefix arg} (setq my-mh-screen-saved ; @r{save state} @@ -3472,7 +3474,7 @@ bindings, for example: @smalllisp @group (defvar my-mh-init-done nil - "Non-@code{nil} when one-time MH-E settings made.") + "Non-nil when one-time MH-E settings made.") (defun my-mh-folder-mode-hook () "Hook to set key bindings in MH-Folder mode." @@ -3690,8 +3692,8 @@ Set the options @code{mh-new-messages-folders} and folders. Otherwise, list the folders that should be searched with the @samp{Choose Folders} menu item. See @code{mh-recursive-folders-flag}. -@cindex buffers, @samp{*MH-E Folders*} -@cindex @samp{*MH-E Folders*} +@cindex buffers, @file{*MH-E Folders*} +@cindex @file{*MH-E Folders*} @findex mh-kill-folder @findex mh-list-folders @findex mh-pack-folder @@ -3705,7 +3707,7 @@ folders. Otherwise, list the folders that should be searched with the Other commands you can perform on folders include: @kbd{F l} (@code{mh-list-folders}), to place a listing of all the folders in -your mail directory in a buffer called @samp{*MH-E Folders*} +your mail directory in a buffer called @file{*MH-E Folders*} (@pxref{Miscellaneous}); @kbd{F k} (@code{mh-kill-folder}), to remove a folder; @kbd{F S} (@code{mh-sort-folder}), to sort the messages by date (see @command{sortm}(1) to see how to sort by other criteria); @@ -3737,7 +3739,7 @@ when you press @key{TAB} when prompted for a folder name. The hook @code{mh-kill-folder-suppress-prompt-functions} is an abnormal hook run at the beginning of the command @kbd{k}. The hook functions -are called with no arguments and should return a non-nil value to +are called with no arguments and should return a non-@code{nil} value to suppress the normal prompt when you remove a folder. This is useful for folders that are easily regenerated. The default value of @code{mh-search-p} suppresses the prompt on folders generated by @@ -3757,8 +3759,8 @@ Use this hook with care. If there is a bug in your hook which returns @cindex @file{.mh_profile} @cindex files, @file{.mh_profile} @cindex MH commands, @command{sortm} -@cindex MH profile component, @samp{sortm:} -@cindex @samp{sortm:} MH profile component +@cindex MH profile component, @samp{sortm} +@cindex @samp{sortm} MH profile component @kindex F S @vindex mh-sortm-args @@ -3779,7 +3781,7 @@ When you want to quit using MH-E and go back to editing, you can use the @kbd{q} (@code{mh-quit}) command. This buries the buffers of the current MH-E folder and restores the buffers that were present when you first ran @kbd{M-x mh-rmail}. It also removes any MH-E working -buffers whose name begins with @samp{ *mh-} or @samp{*MH-E } +buffers whose name begins with @samp{ *mh-} or @file{*MH-E } (@pxref{Miscellaneous}). You can later restore your MH-E session by selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail} again. @@ -4044,8 +4046,8 @@ If you prefer to be prompted for the recipient and subject fields before the MH-Letter buffer appears, turn on the option @code{mh-compose-prompt-flag}. -@cindex header field, @samp{X-Mailer:} -@cindex @samp{X-Mailer:} header field +@cindex header field, @samp{X-Mailer} +@cindex @samp{X-Mailer} header field @vindex mh-insert-x-mailer-flag MH-E adds an @samp{X-Mailer:} header field to the header that includes @@ -4173,8 +4175,8 @@ reply to a message, you can change the option @samp{Prompt} to one of the choices listed above. You can always edit the recipients in the draft. -@cindex @samp{repl:} MH profile component -@cindex MH profile component, @samp{repl:} +@cindex @samp{repl} MH profile component +@cindex MH profile component, @samp{repl} @cindex MH-Letter mode @cindex MH-Show mode @cindex draft @@ -4236,8 +4238,8 @@ hook @code{mh-forward-hook} is called on the draft. @cindex @file{.mh_profile} @cindex files, @file{.mh_profile} -@cindex MH profile component, @samp{forw:} -@cindex @samp{forw:} MH profile component +@cindex MH profile component, @samp{forw} +@cindex @samp{forw} MH profile component @vindex mh-compose-forward-as-mime-flag By default, the option @code{mh-compose-forward-as-mime-flag} is on @@ -4749,25 +4751,25 @@ detail in the following sections. @node Editing Message, Inserting Letter, Editing Drafts, Editing Drafts @section Editing the Message -@cindex @samp{Bcc:} header field -@cindex @samp{Cc:} header field -@cindex @samp{Dcc:} header field -@cindex @samp{From:} header field -@cindex @samp{Mail-Followup-To:} header field -@cindex @samp{Mail-Reply-To:} header field -@cindex @samp{Reply-To:} header field -@cindex @samp{Subject:} header field -@cindex @samp{To:} header field +@cindex @samp{Bcc} header field +@cindex @samp{Cc} header field +@cindex @samp{Dcc} header field +@cindex @samp{From} header field +@cindex @samp{Mail-Followup-To} header field +@cindex @samp{Mail-Reply-To} header field +@cindex @samp{Reply-To} header field +@cindex @samp{Subject} header field +@cindex @samp{To} header field @cindex editing header -@cindex header field, @samp{Bcc:} -@cindex header field, @samp{Cc:} -@cindex header field, @samp{Dcc:} -@cindex header field, @samp{From:} -@cindex header field, @samp{Mail-Followup-To:} -@cindex header field, @samp{Mail-Reply-To:} -@cindex header field, @samp{Reply-To:} -@cindex header field, @samp{Subject:} -@cindex header field, @samp{To:} +@cindex header field, @samp{Bcc} +@cindex header field, @samp{Cc} +@cindex header field, @samp{Dcc} +@cindex header field, @samp{From} +@cindex header field, @samp{Mail-Followup-To} +@cindex header field, @samp{Mail-Reply-To} +@cindex header field, @samp{Reply-To} +@cindex header field, @samp{Subject} +@cindex header field, @samp{To} @findex mh-to-field @kindex C-c C-f C-t @kindex C-c C-f t @@ -5141,12 +5143,12 @@ mail user agent is sophisticated enough. In MH-E, this is done by placing your image in the file named by the option @code{mh-x-face-file} which is @file{~/.face} by default. -@cindex @samp{Face:} header field -@cindex @samp{X-Face:} header field -@cindex @samp{X-Image-URL:} header field -@cindex header field, @samp{Face:} -@cindex header field, @samp{X-Face:} -@cindex header field, @samp{X-Image-URL:} +@cindex @samp{Face} header field +@cindex @samp{X-Face} header field +@cindex @samp{X-Image-URL} header field +@cindex header field, @samp{Face} +@cindex header field, @samp{X-Face} +@cindex header field, @samp{X-Image-URL} If the file starts with either of the strings @samp{X-Face:}, @samp{Face:} or @samp{X-Image-URL:} then the contents are added to the @@ -5604,8 +5606,8 @@ See @cite{The PGG Manual}}. @end ifhtml -@cindex header field, @samp{Fcc:} -@cindex @samp{Fcc:} header field +@cindex header field, @samp{Fcc} +@cindex @samp{Fcc} header field @vindex pgg-encrypt-for-me In particular, I turn on the option @code{pgg-encrypt-for-me} so that @@ -5616,10 +5618,10 @@ field, this setting is vital so that you can read the mail you write! @node Checking Recipients, Sending Message, Sending PGP, Editing Drafts @section Checking Recipients -@cindex @samp{*MH-E Recipients*} +@cindex @file{*MH-E Recipients*} @cindex @command{whom} @cindex MH commands, @command{whom} -@cindex buffers, @samp{*MH-E Recipients*} +@cindex buffers, @file{*MH-E Recipients*} @cindex checking recipients @cindex recipients, checking @findex mh-check-whom @@ -5627,7 +5629,7 @@ field, this setting is vital so that you can read the mail you write! The command @kbd{C-c C-w} (@code{mh-check-whom}) expands aliases so you can check the actual address(es) in the alias. A new buffer named -@samp{*MH-E Recipients*} is created with the output of @command{whom} +@file{*MH-E Recipients*} is created with the output of @command{whom} (@pxref{Miscellaneous})@footnote{See the section @uref{@value{MH-BOOK-HOME}/senove.html#WhaPro, What now?---and the whatnow Program} in the MH book.}. @@ -5635,8 +5637,8 @@ whatnow Program} in the MH book.}. @node Sending Message, Killing Draft, Checking Recipients, Editing Drafts @section Sending a Message -@cindex buffers, @samp{*MH-E Mail Delivery*} -@cindex @samp{*MH-E Mail Delivery*} +@cindex buffers, @file{*MH-E Mail Delivery*} +@cindex @file{*MH-E Mail Delivery*} @cindex sending mail @findex mh-send-letter @kindex C-c C-c @@ -5644,7 +5646,7 @@ whatnow Program} in the MH book.}. When you are all through editing a message, you send it with the command @kbd{C-c C-c} (@code{mh-send-letter}). You can give a prefix argument (as in @kbd{C-u C-c C-c}) to monitor the first stage of the -delivery; this output can be found in a buffer called @samp{*MH-E Mail +delivery; this output can be found in a buffer called @file{*MH-E Mail Delivery*} (@pxref{Miscellaneous}). @cindex sending mail @@ -5840,9 +5842,9 @@ Recipients}. @cindex @command{ali} @cindex @file{/etc/nmh/MailAliases} -@cindex @samp{Aliasfile:} MH profile component +@cindex @samp{Aliasfile} MH profile component @cindex MH commands, @command{ali} -@cindex MH profile component, @samp{Aliasfile:} +@cindex MH profile component, @samp{Aliasfile} @cindex files, @file{/etc/nmh/MailAliases} MH-E loads aliases for completion and folder name hints from various @@ -6084,8 +6086,8 @@ the @samp{INS} button with the label @samp{Add at least one item below}. The @samp{Value Menu} has the following menu items: @table @samp -@cindex header field, @samp{From:} -@cindex @samp{From:} header field +@cindex header field, @samp{From} +@cindex @samp{From} header field @item From Field Specify an alternate @samp{From:} header field. You must include a valid email address. A standard format is @samp{First Last @@ -6093,8 +6095,8 @@ valid email address. A standard format is @samp{First Last must quote your name as in @samp{"First I. Last" <login@@host.domain>}. @c ------------------------- -@cindex header field, @samp{Organization:} -@cindex @samp{Organization:} header field +@cindex header field, @samp{Organization} +@cindex @samp{Organization} header field @item Organization Field People usually list the name of the company where they work here. @c ------------------------- @@ -6172,15 +6174,15 @@ Select an identity from those configured in @code{mh-identity-list}. All of the information for that identity will be added if the recipient matches. @c ------------------------- -@cindex @samp{Fcc:} header field -@cindex header field, @samp{Fcc:} +@cindex @samp{Fcc} header field +@cindex header field, @samp{Fcc} @item Fcc Field Insert an @samp{Fcc:} header field with the folder you provide. When you send the message, MH will put a copy of your message in this folder. @c ------------------------- -@cindex @samp{Mail-Followup-To:} header field -@cindex header field, @samp{Mail-Followup-To:} +@cindex @samp{Mail-Followup-To} header field +@cindex header field, @samp{Mail-Followup-To} @item Mail-Followup-To Field Insert an @samp{Mail-Followup-To:} header field with the recipients you provide. If the recipient's mail user agent supports this header @@ -6403,7 +6405,7 @@ see the section The Menu Bar} in @cite{The GNU Emacs Manual}. @end ifhtml -The Emacs manual describes how to get online help for a particular +The Emacs manual describes how to get help for a particular menu item. You can also look up a menu item in the index of this manual in two ways: all of the menu items are listed alphabetically, and you can also browse all of the items under the index entry @@ -6792,8 +6794,8 @@ argument. @cindex @command{procmail} @cindex Unix commands, @command{procmail} -@cindex @samp{X-MHE-Checksum:} header field -@cindex header field, @samp{X-MHE-Checksum:} +@cindex @samp{X-MHE-Checksum} header field +@cindex header field, @samp{X-MHE-Checksum} Note: This command uses an @samp{X-MHE-Checksum:} header field to cache the MD5 checksum of a message. This means that if an incoming @@ -7155,7 +7157,7 @@ MH-E has been byte-compiled, you could try running @samp{locate mh-thread.elc} or otherwise find MH-E on your system and ensure that @file{mh-thread.elc} exists. If you have multiple versions and you find that one is compiled but the other is not, then go into your -@samp{*scratch*} buffer in Emacs, enter @kbd{load-path C-j}, and +@file{*scratch*} buffer in Emacs, enter @kbd{load-path C-j}, and ensure that the byte-compiled version appears first in the @code{load-path}. If you find that MH-E is not compiled and you installed MH-E yourself, please refer to the installation directions @@ -7441,8 +7443,8 @@ sequence, use @kbd{S '} (@code{mh-narrow-to-tick}). When you want to widen the view to all your messages again, use @kbd{S w} (@code{mh-widen}). -@cindex buffers, @samp{*MH-E Sequences*} -@cindex @samp{*MH-E Sequences*} +@cindex buffers, @file{*MH-E Sequences*} +@cindex @file{*MH-E Sequences*} @findex mh-list-sequences @findex mh-msg-is-in-seq @kindex S l @@ -7454,11 +7456,11 @@ display the sequences in which another message appears (as in @kbd{C-u 42 S s @key{RET}}). Or, you can list all sequences in a selected folder (default is current folder) with @kbd{S l} (@code{mh-list-sequences}). The list appears in a buffer named -@samp{*MH-E Sequences*} (@pxref{Miscellaneous}). +@file{*MH-E Sequences*} (@pxref{Miscellaneous}). -@cindex MH profile component, @samp{Previous-Sequence:} +@cindex MH profile component, @samp{Previous-Sequence} @cindex @samp{cur} sequence -@cindex @samp{Previous-Sequence:} MH profile component +@cindex @samp{Previous-Sequence} MH profile component @cindex sequence, @samp{cur} @cindex sequence, @samp{Previous-Sequence} @vindex mh-refile-preserves-sequences-flag @@ -7483,10 +7485,10 @@ this deletes only the sequence, not the messages in the sequence. If you want to delete the messages, use @kbd{C-u d} (@pxref{Reading Mail}). -@cindex @samp{Unseen-Sequence:} MH profile component +@cindex @samp{Unseen-Sequence} MH profile component @cindex @samp{cur} sequence @cindex @samp{tick} sequence -@cindex MH profile component, @samp{Unseen-Sequence:} +@cindex MH profile component, @samp{Unseen-Sequence} @cindex sequence, @samp{Unseen-Sequence} @cindex sequence, @samp{cur} @cindex sequence, @samp{tick} @@ -7662,9 +7664,9 @@ reclassifies a range of messages (@pxref{Ranges}) as ham if it were incorrectly classified as spam. It then refiles the message into the @file{+inbox} folder. -@cindex MH profile component, @samp{Previous-Sequence:} +@cindex MH profile component, @samp{Previous-Sequence} @cindex @samp{cur} sequence -@cindex @samp{Previous-Sequence:} MH profile component +@cindex @samp{Previous-Sequence} MH profile component @cindex sequence, @samp{cur} @cindex sequence, @samp{Previous-Sequence} @vindex mh-whitelist-preserves-sequences-flag @@ -7674,8 +7676,8 @@ If a message is in any sequence (except @samp{Previous-Sequence:} and sequences in the destination folder. If this behavior is not desired, then turn off the option @code{mh-whitelist-preserves-sequences-flag}. -@cindex @samp{*MH-E Log*} -@cindex buffers, @samp{*MH-E Log*} +@cindex @file{*MH-E Log*} +@cindex buffers, @file{*MH-E Log*} @findex call-process @vindex mh-junk-background @@ -7686,7 +7688,7 @@ turning on the option @code{mh-junk-background}. @footnote{Note that the option @code{mh-junk-background} is used as the @code{display} argument in the call to @code{call-process}. Therefore, turning on this option means setting its value to @samp{0}. You can also set its -value to @samp{t} to direct the programs' output to the @samp{*MH-E +value to @samp{t} to direct the programs' output to the @file{*MH-E Log*} buffer; this may be useful for debugging.} The following sections discuss the various counter-spam measures that @@ -7707,10 +7709,10 @@ it from your local distribution or from the To use SpamAssassin, add the following recipes to @file{~/.procmailrc}: @cindex @command{spamc} -@cindex @samp{X-Spam-Level:} header field -@cindex @samp{X-Spam-Status:} header field -@cindex header field, @samp{X-Spam-Level:} -@cindex header field, @samp{X-Spam-Status:} +@cindex @samp{X-Spam-Level} header field +@cindex @samp{X-Spam-Status} header field +@cindex header field, @samp{X-Spam-Level} +@cindex header field, @samp{X-Spam-Status} @smallexample PATH=$PATH:/usr/bin/mh @@ -7832,8 +7834,8 @@ each type of message to start doing a good job. To use bogofilter, add the following recipes to @file{~/.procmailrc}: -@cindex @samp{X-Bogosity:} header field -@cindex header field, @samp{X-Bogosity:} +@cindex @samp{X-Bogosity} header field +@cindex header field, @samp{X-Bogosity} @smallexample PATH=$PATH:/usr/bin/mh @@ -7885,8 +7887,8 @@ SpamProbe web site}. To use SpamProbe, add the following recipes to @file{~/.procmailrc}: @cindex @command{formail} -@cindex @samp{X-SpamProbe:} header field -@cindex header field, @samp{X-SpamProbe:} +@cindex @samp{X-SpamProbe} header field +@cindex header field, @samp{X-SpamProbe} @smallexample PATH=$PATH:/usr/bin/mh @@ -7921,12 +7923,12 @@ eliminate any message with a Windows executable (which is most likely a virus). The second is to eliminate mail in character sets that you can't read. -@cindex @samp{Content-Transfer-Encoding:} header field -@cindex @samp{Content-Type:} header field -@cindex @samp{Subject:} header field -@cindex header field, @samp{Content-Transfer-Encoding:} -@cindex header field, @samp{Content-Type:} -@cindex header field, @samp{Subject:} +@cindex @samp{Content-Transfer-Encoding} header field +@cindex @samp{Content-Type} header field +@cindex @samp{Subject} header field +@cindex header field, @samp{Content-Transfer-Encoding} +@cindex header field, @samp{Content-Type} +@cindex header field, @samp{Subject} @smallexample PATH=$PATH:/usr/bin/mh @@ -7974,16 +7976,16 @@ Display version information about MH-E and the MH mail handling system. @end ftable -@cindex buffers, @samp{*MH-E Info*} +@cindex buffers, @file{*MH-E Info*} @cindex MH-E version -@cindex @samp{*MH-E Info*} +@cindex @file{*MH-E Info*} @cindex version @kindex M-x mh-version One command worth noting is @kbd{M-x mh-version}. You can compare the version this command prints to the latest release (@pxref{Getting MH-E}). The output of @kbd{M-x mh-version}, found in a buffer named -@samp{*MH-E Info*}, should usually be included with any bug report you +@file{*MH-E Info*}, should usually be included with any bug report you submit (@pxref{Bug Reports}). @subheading MH-E Buffers @@ -7992,16 +7994,16 @@ Besides the MH-Folder, MH-Show, and MH-Letter buffers, MH-E creates several other buffers. They are: @table @samp -@cindex @samp{*MH-E Folders*} -@cindex buffers, @samp{*MH-E Folders*} +@cindex @file{*MH-E Folders*} +@cindex buffers, @file{*MH-E Folders*} @findex mh-list-folders @item *MH-E Folders* @kindex F l This buffer contains the output of @kbd{F l} (@code{mh-list-folders}). @xref{Folders}. @c ------------------------- -@cindex @samp{*MH-E Help*} -@cindex buffers, @samp{*MH-E Help*} +@cindex @file{*MH-E Help*} +@cindex buffers, @file{*MH-E Help*} @findex mh-help @item *MH-E Help* @kindex ? @@ -8009,25 +8011,25 @@ This buffer contains the output of @kbd{F l} (@code{mh-list-folders}). This buffer contains the output of @kbd{?} (@code{mh-help}) and @kbd{C-c ?} in MH-Letter mode. @xref{Using This Manual}. @c ------------------------- -@cindex @samp{*MH-E Info*} -@cindex buffers, @samp{*MH-E Info*} +@cindex @file{*MH-E Info*} +@cindex buffers, @file{*MH-E Info*} @item *MH-E Info* This buffer contains the output of @kbd{M-x mh-version @key{RET}}. @c ------------------------- -@cindex @samp{*MH-E Log*} -@cindex buffers, @samp{*MH-E Log*} +@cindex @file{*MH-E Log*} +@cindex buffers, @file{*MH-E Log*} @item *MH-E Log* This buffer contains the last 100 lines of the output of the various MH commands. @c ------------------------- -@cindex @samp{*MH-E Mail Delivery*} -@cindex buffers, @samp{*MH-E Mail Delivery*} +@cindex @file{*MH-E Mail Delivery*} +@cindex buffers, @file{*MH-E Mail Delivery*} @item *MH-E Mail Delivery* This buffer contains the transcript of a mail delivery. @xref{Sending Message}. @c ------------------------- -@cindex @samp{*MH-E Recipients*} -@cindex buffers, @samp{*MH-E Recipients*} +@cindex @file{*MH-E Recipients*} +@cindex buffers, @file{*MH-E Recipients*} @findex mh-check-whom @item *MH-E Recipients* @kindex C-c C-w @@ -8035,14 +8037,14 @@ This buffer contains the output of @kbd{C-c C-w} (@code{mh-check-whom}) and is killed when draft is sent. @xref{Checking Recipients}. @c ------------------------- -@cindex @samp{*MH-E Sequences*} -@cindex buffers, @samp{*MH-E Sequences*} +@cindex @file{*MH-E Sequences*} +@cindex buffers, @file{*MH-E Sequences*} @item *MH-E Sequences* This buffer contains the output of @kbd{S l} (@code{mh-list-sequences}). @xref{Sequences}. @c ------------------------- -@cindex @samp{*mh-temp*} -@cindex buffers, @samp{*mh-temp*} +@cindex @file{*mh-temp*} +@cindex buffers, @file{*mh-temp*} @item *mh-temp* This is a scratch, ephemeral, buffer used by MH-E functions. Note that it is hidden because the first character in the name is a space. @@ -8578,8 +8580,8 @@ anything to my knowledge@footnote{See Savannah issue #4361} to see if @command{rcvstore} locking is still an issue.}. -@cindex @samp{Unseen-Sequence:} MH profile component -@cindex MH profile component, @samp{Unseen-Sequence:} +@cindex @samp{Unseen-Sequence} MH profile component +@cindex MH profile component, @samp{Unseen-Sequence} Line 16 uses the following script, @code{myrcvstore}, to massage the message as described in the comment and file the message in the given diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi index afb44a6a396..9f7b6df1ab5 100644 --- a/doc/misc/newsticker.texi +++ b/doc/misc/newsticker.texi @@ -1,25 +1,27 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/newsticker -@set VERSION 1.99 -@set UPDATED June 2008 +@setfilename ../../info/newsticker.info +@include emacsver.texi +@set VERSION @value{EMACSVER} @settitle Newsticker @value{VERSION} +@include docstyle.texi @syncodeindex vr cp @syncodeindex fn cp @syncodeindex pg cp @comment %**end of header @copying -This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). +This manual documents Newsticker, a feed reader for Emacs. It +corresponds to Emacs version @value{EMACSVER}. @noindent -Copyright @copyright{} 2004--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2015 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'', +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''. @@ -30,12 +32,11 @@ modify this GNU manual.'' @dircategory Emacs network features @direntry -* Newsticker: (newsticker). A Newsticker for Emacs. +* Newsticker: (newsticker). A feed reader for Emacs. @end direntry @titlepage -@title Newsticker---a Newsticker for Emacs -@subtitle for version @value{VERSION}, @value{UPDATED} +@title Newsticker---a feed reader for Emacs @author Ulf Jasper @author @email{ulf.jasper@@web.de} @author @uref{http://ulf.epplejasper.de/} @@ -55,136 +56,419 @@ modify this GNU manual.'' @end ifnottex @menu -* Overview:: General description of newsticker. -* Requirements:: Requirements for using newsticker. -* Installation:: Installing newsticker on your system. -* Usage:: Basic newsticker instructions. -* Configuration:: Customizable newsticker settings. -* Remarks:: Remarks about newsticker. +* Overview:: What is Newsticker? +* Installation:: Things to do before starting Newsticker the first time. +* Retrieving News:: How Newsticker fetches headlines. +* Headline Management:: How Newsticker stores headlines. +* Reading News:: How to read RSS and Atom feeds with Newsticker. +* Automatic Processing:: Automatically process news items. +* Configuration:: Customize Newsticker to your liking. +* Supported Formats:: RSS and Atom formats supported by Newsticker. + * GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function, and concept index. +* Index:: Variable, function, and concept index. @end menu @node Overview @chapter Overview -Newsticker provides a newsticker for Emacs. A newsticker is a thing -that asynchronously retrieves headlines from a list of news sites, -prepares these headlines for reading, and allows for loading the -corresponding articles in a web browser. +Newsticker provides a @b{Feed Reader} for Emacs. It retrieves +headlines from a list of news sites, processes them, and provides +frontends for reading and managing them. (Standard headline formats +are RSS and Atom which makes Newsticker an ``RSS Reader'', ``Atom +Reader'' or ``Feed Aggregator''.) +Headlines (or news items) consist of a title, (mostly) a description, +and a link to the full story. The description may be a brief summary +in plain text or a full HTML-formatted article. A headline may carry +enclosed data such as images, audio or video files, typically in the +case of so ``podcast feeds''. -Headlines consist of a title and (possibly) a small description. They -are contained in ``RSS'' (RDF Site Summary) or ``Atom'' files. Newsticker -works with the following RSS formats: +Newsticker downloads headlines asynchronously at configurable times, +processes and stores them so that you can read them later. The list +of subscribed feeds, the headline processing, the presentation of the +headlines and almost all other aspects of Newsticker can be +customized to your liking. -@itemize -@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or -@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}), -@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}), -@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec} -@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}), -@end itemize -@itemize -as well as the following Atom formats: -@item Atom 0.3 -@item Atom 1.0 (see -@uref{https://datatracker.ietf.org/doc/rfc4287/}). -@end itemize +@node Installation +@chapter Installation -That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed -aggregator'', or ``Feed reader''. +As Newsticker is part of GNU Emacs there is no need to perform any +installation steps in order to use it. -Newsticker provides several commands for reading headlines, navigating -through them, marking them as read/unread, hiding old headlines etc. -Headlines can be displayed as plain text or as rendered HTML. +Newsticker is highly customizable. All options have reasonable default +values, so that (in most cases) it is not necessary to customize +anything before you start Newsticker for the first time. -Headlines can be displayed in the echo area, either scrolling like -messages in a stock-quote ticker, or just changing. - -Newsticker allows for automatic processing of headlines by providing -hooks and (sample) functions for automatically downloading images and -enclosed files (as delivered by, e.g., podcasts). - -@ignore -@ifhtml -Here are screen shots of the @uref{newsticker-1.7.png, version 1.7 -(current version)} and some older screen shots: -@uref{newsticker-1.6.png, version 1.6}, -@uref{newsticker-1.5.png, version 1.5}, -@uref{newsticker-1.4.png, version 1.4} -@uref{newsticker-1.3.png, version 1.3}, -@uref{newsticker-1.0.png, version 1.0}. -@end ifhtml -@end ignore - -@node Requirements -@chapter Requirements - -Newsticker can be used with -@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version -21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It -requires an XML-parser (@file{xml.el}), which is part of GNU Emacs. If -you are using XEmacs you want to get the @file{net-utils} package -which contains @file{xml.el} for XEmacs. - -Newsticker retrieves headlines either via Emacs's built-in retrieval -functions, by an arbitrary external program that retrieves files via -http and prints them to stdout (like -@uref{http://www.gnu.org/software/wget/wget.html, wget}, or---on a -per feed basis---via an arbitrary Lisp command. +@node Retrieving News +@chapter Retrieving News +Newsticker downloads news periodically in the background. This is +triggered as soon as you start reading news (@ref{Reading News}). -@node Installation -@chapter Installation +@findex newsticker-start +@findex newsticker-stop +Alternatively you may use the command @code{newsticker-start} +(@code{newsticker-stop}) in order to start (stop) the periodic +download of news without opening the reader. -As Newsticker is part of GNU Emacs there is no need to perform any -installation steps in order to use Newsticker. +The following variables define which feeds are fetched and how this is +done. + +@table @code +@vindex newsticker-url-list-defaults +@item newsticker-url-list-defaults +You may select any number of feeds from this list of (sample) news feeds. + +@vindex newsticker-url-list +@item newsticker-url-list +All your personal news feeds are defined here. Each feed is +identified by its name and an URL@. You may set the start-time and the +retrieval interval for each feed as well as the retrieval command +arguments in case that the default values do not fit a certain feed. + +@vindex newsticker-retrieval-method +@vindex newsticker-wget-name +@vindex newsticker-wget-arguments +@item newsticker-retrieval-method +By default Newsticker uses Emacs's built-in download capabilities for +fetching headlines. You may change this to use an external tool like +@code{wget}. In this case you need to set @code{newsticker-wget-name} +and possibly @code{newsticker-wget-arguments}. + +@vindex newsticker-retrieval-interval +@item newsticker-retrieval-interval +The number of seconds between headline retrievals. +@end table + +@node Headline Management +@chapter Headline Management + +@cindex Age +@cindex Status + +Newsticker assigns a status (or ``age'') to each headline which you +can modify manually. This makes it easy to distinguish new headlines +from old ones, to keep important headlines, to hide boring headlines +etc. An item is ``new'' when it has just arrived and has not been +read. You can mark it as ``old'' when you have read it or -- if you +want to keep it -- you can mark it as ``immortal''. You can do that +manually and you can define filters which do that automatically, see +below. When a headline has vanished from the feed it is automatically +marked as ``obsolete'' unless it has the status ``immortal''. +``Obsolete'' headlines get removed automatically after a certain time. + +@table @code +@cindex Filter +@vindex newsticker-auto-mark-filter-list +@item newsticker-auto-mark-filter-list +You may define any number of filters for automatically marking newly +arrived headlines as ``immortal'' or ``old''. A filter looks for a +regular expression in either the title or the description of a +headline and then, if the expression matches, marks the headline as +``immortal'' or as ``old''. This is done only once, when a headline +is fetched for the very first time. + +@vindex newsticker-keep-obsolete-items +@vindex newsticker-obsolete-item-max-age +@item newsticker-keep-obsolete-items +Obsolete headlines are removed immediately unless +@code{newsticker-keep-obsolete-items} is non-nil in which case they +are kept until @code{newsticker-obsolete-item-max-age} is reached. + +@vindex newsticker-automatically-mark-items-as-old +@item newsticker-automatically-mark-items-as-old +If this is set to @code{t} then a ``new'' item becomes ``old'' as soon as +it is retrieved a second time. + +@end table + +@node Reading News +@chapter Reading News + +@findex newsticker-show-news +Start Newsticker with the command @kbd{M-x newsticker-show-news}. This +will start the asynchronous news download and displays all available +headlines. + +@menu +* Frontends:: Select the way headlines are displayed. +* Navigation:: Move to the next unread headline etc. +* Marking:: Mark important headlines. +* More Actions:: Add new feeds etc.. +@end menu + +@node Frontends +@section Frontends +@cindex Frontends + +@vindex newsticker-frontend +Newsticker provides two different @i{views} for browsing, marking and +reading news. The variable @code{newsticker-frontend} determines the +actual headline reader. + +@subheading Treeview +@cindex Treeview + +In this view separate windows are used for displaying feeds, headlines +and their descriptions. The feeds are shown as a tree on the left +hand side, headlines of the currently selected feed are shown on the +upper right side, and the full contents of the currently selected +headline is shown on the lower right side. + +Feeds can be placed into groups, which themselves can be placed in +groups and so on. This results in the tree which is displayed on the +left. A node represents either a feed or a group of feeds holding a +subtree. The following commands allow for managing groups. + +@table @kbd +@item M-a +@kindex M-a +@findex newsticker-group-add-group +Add a new feed group. Name of the new group and of the parent group +must be entered. If The name of the parent group is the new group +becomes a top-level group. (@code{newsticker-group-add-group}) +@item M-m +@kindex M-m +@findex newsticker-group-move-feed +Moves a feed into a group. The name of the group must be +entered. (@code{newsticker-group-move-feed}) +@end table + +The position of groups and feeds within the tree can be changed with these +commands: + +@table @kbd +@item M-up +@itemx M-down +@kindex M-up +@kindex M-down +@findex newsticker-group-shift-feed-up +@findex newsticker-group-shift-feed-down +Shift the currently selected feed up and down within its group. +@item M-S-up +@itemx M-S-down +@kindex M-S-up +@kindex M-S-down +@findex newsticker-group-shift-group-up +@findex newsticker-group-shift-group-down +Shift the currently selected group up and down within its parent group. +@end table + +The group settings are saved to a file either automatically when +newsticker is being quit or manually when the following command is +executed. + +@table @kbd +@item s +@kindex s +@findex newsticker-treeview-save +Save treeview group settings. +@end table + +The Treeview is updated automatically as soon as new headlines have +arrived. + +The Treeview is used when the variable @code{newsticker-frontend} is +set to the value @code{newsticker-treeview}. (Alternatively it can be +started with the command @code{newsticker-treeview}.) + +@subheading Plainview +@cindex Plainview -However, if you are using imenu, which allows for navigating with the -help of a menu, you should add the following to your Emacs startup file -(@file{~/.emacs}). +In this view all headlines of all feeds are displayed in a single +buffer (@file{*newsticker*}). The modeline in the @file{*newsticker*} +buffer informs you whenever new headlines have arrived. + +You may want to use imenu with Plainview, which allows for navigating +with the help of a menu. In this case add the following to your Emacs +startup file (@file{~/.emacs}). @lisp (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index) @end lisp -That's it. +(Note that preparing the Plainview takes significantly more time than +starting the Treeview because all headlines are displayed in a single +buffer. When you have subscribed to a large amount of feeds you may +find that Newsticker's efforts of minimizing rendering times, caching +rendered items and so on you may find However, when you have +subscribed to a large amount of feeds you may want to give the +Treeview a try.) -@node Usage -@chapter Usage +The Plainview is used when the variable @code{newsticker-frontend} is +set to the value @code{newsticker-plainview}. (Alternatively it can be +started with the command @code{newsticker-plainview}.) -@findex newsticker-show-news -The command @code{newsticker-show-news} will display all available -headlines. It will also start the asynchronous download of headlines. +@subheading Ticker +@cindex Ticker -You can choose between two different frontends for reading headlines: -@itemize -@item Newsticker's @emph{treeview} uses separate windows for the -feeds (in tree form), a list of headlines for the current feed, and -the content of the current headline. Feeds can be placed into groups, -which themselves can be placed in groups and so on. -@item Newsticker's @emph{plainview} displays all headlines in a -single buffer, called @samp{*newsticker*}. The modeline in the -@samp{*newsticker*} buffer informs you whenever new headlines have -arrived. -@end itemize -In both views clicking mouse-button 2 or pressing @key{RET} on a -headline will call @code{browse-url} to load the corresponding news -story in your favorite web browser. +Additionally, headlines can be displayed in the echo area in the style of a +news ticker. @findex newsticker-start-ticker @findex newsticker-stop-ticker -The scrolling, or flashing of headlines in the echo area, can be +Headlines can be displayed in the echo area, either scrolling like +messages in a stock-quote ticker, or just changing. This can be started with the command @code{newsticker-start-ticker}. It can be stopped with @code{newsticker-stop-ticker}. -@findex newsticker-start -@findex newsticker-stop -If you just want to start the periodic download of headlines use the -command @code{newsticker-start}. Calling @code{newsticker-stop} will -stop the periodic download, but will call -@code{newsticker-stop-ticker} as well. + +@node Navigation +@section Navigation +@cindex Navigation + +Navigating through the list of feeds and headlines is rather +straightforward. You may do this either with the mouse or with the +keyboard. The following key bindings are provided in both, the +Treeview as well as the Plainview. + +@table @kbd +@item f +@findex newsticker-next-feed +@findex newsticker-treeview-next-feed +Move to next feed (@code{newsticker-next-feed}, +@code{newsticker-treeview-next-feed}). +@item F +@findex newsticker-previous-feed +@findex newsticker-treeview-prev-feed +Move to previous feed (@code{newsticker-previous-feed}, +@code{newsticker-treeview-prev-feed}). +@item n +@findex newsticker-next-item +@findex newsticker-treeview-next-item +Move to next item (@code{newsticker-next-item}, +@code{newsticker-treeview-next-item}). +@item N +@findex newsticker-next-new-item +@findex newsticker-treeview-next-new-item +Move to next new item (possibly in another feed) +(@code{newsticker-next-new-item}, +@code{newsticker-treeview-next-new-item}). +@item p +@findex newsticker-previous-item +@findex newsticker-treeview-prev-item +Move to previous item (@code{newsticker-previous-item}, +@code{newsticker-treeview-prev-item}). +@item P +@findex newsticker-previous-new-item +@findex newsticker-treeview-prev-new-item +Move to previous new item (possibly in another feed) +(@code{newsticker-previous-new-item}, +@code{newsticker-treeview-prev-new-item}). +@end table + +@subheading Treeview +@table @kbd +@item j +@findex newsticker-treeview-jump +Enter the name of a feed and jump to it +(@code{newsticker-treeview-jump}). +@end table + + +@node Marking +@section Marking +@cindex Marking + +The following key bindings are provided in both, the Treeview as well +as the Plainview. + +@table @kbd +@item o +@findex newsticker-mark-item-at-point-as-read +@findex newsticker-treeview-mark-item-old +Mark current item as old. +(@code{newsticker-mark-item-at-point-as-read}, +@code{newsticker-treeview-mark-item-old}). +@item i +@findex newsticker-mark-item-at-point-as-immortal +@findex newsticker-treeview-mark-item-immortal +Mark current item as immortal. Immortal items are kept forever. +(@code{newsticker-mark-item-at-point-as-immortal}, +@code{newsticker-treeview-mark-item-immortal}). +@end table + +@node More Actions +@section More Actions +@cindex More Actions + +@subheading View full article +@table @kbd +@cindex Get News +@item v +@itemx RET +@itemx <mouse-1> +@findex newsticker-treeview-browse-url +Open the link to the full article (as contained in the current +headline) in your web browser @code{newsticker-treeview-browse-url}). +@end table + +@subheading Get News +@cindex Get News + +You can force immediate download of news with the following commands. + +@table @kbd +@item g +@findex newsticker-treeview-get-news +Get news for currently shown feed (@code{newsticker-treeview-get-news}). +@item G +@findex newsticker-get-all-news +Get news for all feeds (@code{newsticker-get-all-news}). +@end table + +@subheading Add More Feeds +@cindex Add More Feeds + +@table @kbd +@item a +@findex newsticker-add-url +The command @code{newsticker-add-url} prompts for an URL and a name of +a new feed. It then prepares a customization buffer where the details +of the new feed can be set. +@end table + + +@node Automatic Processing +@chapter Automatic Processing +@cindex Automatic Processing + +Apart from automatic marking of headlines (by means of filters) +Newsticker provides the possibility to fully process newly arrived +headlines. Instead of reading headlines yourself you can tell +Newsticker to do that for you. + +@vindex newsticker-new-item-functions +In order to do so write a function which takes three arguments + +@table @var +@item FEED +the name of the corresponding news feed, +@item TITLE +the title of the headline, +@item DESC +the decoded description of the headline. +@end table + +and add it to @code{newsticker-new-item-functions}. Each function +contained in this list is called once for each new headline. +Depending on the feed, the title and the description of a headline you +can + +@itemize +@item +automatically download images referenced in HTML-formatted +descriptions (for which a function already exists, see +@code{newsticker-download-images}), +@item +automatically save enclosed audio and video files (for which another +function exists as well, see @code{newsticker-download-images}), +@item +flash the screen while playing some sound, +@item +whatever you want. +@end itemize @node Configuration @chapter Configuration @@ -194,11 +478,8 @@ Emacs customization methods. Call the command @code{customize-group} and enter @samp{newsticker} for the customization group. -All Newsticker options have reasonable default values, so that in most -cases it is not necessary to customize settings before starting Newsticker -for the first time. - -The following list shows the available groups of newsticker options +@noindent +The following list shows the available groups of Newsticker options and some of the most important options. @itemize @@ -295,13 +576,34 @@ treeview reader. @end itemize +@noindent For the complete list of options please have a look at the customization buffers. -@node Remarks -@chapter Remarks +@node Supported Formats +@appendix Supported Formats +@cindex Supported Formats + +Newsticker works with the standard RSS and Atom formats listed below +(being lenient with feeds which break the specifications). + +@subheading RSS formats + +@itemize +@item RSS 0.91 (see @uref{http://backend.userland.com/rss091}) +@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}) +@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec}) +@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}) +@end itemize + +@subheading Atom formats + +@itemize +@item Atom 0.3 +@item Atom 1.0 (see +@uref{https://datatracker.ietf.org/doc/rfc4287/}) +@end itemize -Byte-compiling newsticker.el is recommended. @node GNU Free Documentation License @appendix GNU Free Documentation License @@ -309,7 +611,7 @@ Byte-compiling newsticker.el is recommended. @node Index @unnumbered Index - @printindex cp + @bye diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi index 8c81b6fbd20..e87e6a05619 100644 --- a/doc/misc/nxml-mode.texi +++ b/doc/misc/nxml-mode.texi @@ -1,20 +1,21 @@ \input texinfo @c -*- texinfo -*- @c %**start of header -@setfilename ../../info/nxml-mode +@setfilename ../../info/nxml-mode.info @settitle nXML Mode +@include docstyle.texi @c %**end of header @copying This manual documents nXML mode, an Emacs major mode for editing XML with RELAX NG support. -Copyright @copyright{} 2007--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2015 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,'' +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''. @@ -28,6 +29,17 @@ modify this GNU manual.'' * nXML Mode: (nxml-mode). XML editing mode with RELAX NG support. @end direntry + +@titlepage +@title nXML mode +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + + @node Top @top nXML Mode diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi new file mode 100644 index 00000000000..34499c2d58c --- /dev/null +++ b/doc/misc/octave-mode.texi @@ -0,0 +1,446 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../../info/octave-mode.info +@settitle Octave Mode +@include docstyle.texi +@c %**end of header + +@copying +Copyright @copyright{} 1996--2015 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs editing modes +@direntry +* Octave mode: (octave-mode). Emacs mode for editing GNU Octave files. +@end direntry + +@finalout + +@titlepage +@title Octave Mode +@subtitle An Emacs mode for programming in GNU Octave + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Octave Mode + +@insertcopying +@end ifnottex + +@menu +* Overview:: +* Using Octave Mode:: +* Running Octave from Within Emacs:: +* GNU Free Documentation License:: +* Key Index:: +* Variable Index:: +* Lisp Function Index:: +* Concept Index:: +@end menu + +@node Overview +@chapter Overview + +The development of Octave code can greatly be facilitated using Emacs +with Octave mode, a major mode for editing Octave files which can +e.g.@: automatically indent the code, do some of the typing (with +Abbrev mode) and show keywords, comments, strings, etc.@: in different +faces (with Font-lock mode on devices that support it). + +It is also possible to run Octave from within Emacs, either by +directly entering commands at the prompt in a buffer in Inferior +Octave mode, or by interacting with Octave from within a file with +Octave code. This is useful in particular for debugging Octave code. + +@node Using Octave Mode +@chapter Using Octave Mode +@cindex Using Octave Mode + +In Octave mode, the following special Emacs commands can be used in +addition to the standard Emacs commands. + +@table @kbd +@item C-M-j +@kindex C-M-j +@findex octave-indent-new-comment-line +@vindex octave-continuation-string +Break Octave line at point, continuing comment if within one. Insert +@code{octave-continuation-string} before breaking the line unless +inside a list. Signal an error if within a single-quoted string. + +@item C-c ; +@kindex C-c ; +@findex octave-update-function-file-comment +Query replace function names in function file comment. + +@item C-c C-p +@kindex C-c C-p +@findex octave-previous-code-line +Move one line of Octave code backward, skipping empty and comment +lines (@code{octave-previous-code-line}). With numeric prefix +argument @var{n}, move that many code lines backward (forward if +@var{n} is negative). + +@item C-c C-n +@kindex C-c C-n +@findex octave-next-code-line +Move one line of Octave code forward, skipping empty and comment lines +(@code{octave-next-code-line}). With numeric prefix argument @var{n}, +move that many code lines forward (backward if @var{n} is negative). + +@item C-c C-a +@kindex C-c C-a +@findex octave-beginning-of-line +Move to the beginning of the physical line +(@code{octave-beginning-of-line}). If point is in an empty or comment +line, simply go to its beginning; otherwise, move backwards to the +beginning of the first code line which is not inside a continuation +statement, i.e., which does not follow a code line ending in +@samp{...} or @samp{\}, or is inside an open parenthesis list. + +@item C-c C-e +@kindex C-c C-e +@findex octave-end-of-line +Move to the end of the physical line (@code{octave-end-of-line}). If +point is in a code line, move forward to the end of the first Octave +code line which does not end in @samp{...} or @samp{\} or is inside an +open parenthesis list. Otherwise, simply go to the end of the current +line. + +@item C-c M-C-h +@kindex C-c M-C-h +@findex octave-mark-block +Put point at the beginning of this block, mark at the end +(@code{octave-mark-block}). The block marked is the one that contains +point or follows point. + +@item C-c ] +@kindex C-c ] +Close the current block on a separate line (@code{smie-close-block}). +An error is signaled if no block to close is found. + +@item C-c C-f +@kindex C-c C-f +@findex octave-insert-defun +Insert a function skeleton, prompting for the function's name, arguments +and return values which have to be entered without parentheses +(@code{octave-insert-defun}). +@noindent +in one of your Emacs startup files. +@end table + +The following variables can be used to customize Octave mode. + +@vtable @code +@item octave-blink-matching-block +Non-@code{nil} means show matching begin of block when inserting a space, +newline or @samp{;} after an else or end keyword. Default is @code{t}. +This is an extremely useful feature for automatically verifying that the +keywords match---if they don't, an error message is displayed. + +@item octave-block-offset +Extra indentation applied to statements in block structures. +Default is 2. + +@item octave-continuation-offset +Extra indentation applied to Octave continuation lines. +Default is 4. + +@item octave-font-lock-texinfo-comment +Highlight texinfo comment blocks. The default value is @code{t}. +@end vtable + +If Font Lock mode is enabled, Octave mode will display + +@itemize @bullet +@item +strings in @code{font-lock-string-face} + +@item +comments in @code{font-lock-comment-face} + +@item +the Octave reserved words (such as all block keywords) and the text +functions (such as @samp{cd} or @samp{who}) which are also reserved +using @code{font-lock-keyword-face} + +@item +the built-in operators (@samp{&&}, @samp{==}, @dots{}) using +@code{font-lock-reference-face} + +@item +and the function names in function declarations in +@code{font-lock-function-name-face}. + +@item +Function comments blocks in @code{octave-function-comment-block} +@end itemize + +@cindex Imenu Support +There is also rudimentary support for Imenu (@pxref{Imenu,,, emacs, +The GNU Emacs Manual}). Currently, function names can be indexed. + +@cindex ElDoc Mode Support +@vindex octave-eldoc-message-style +ElDoc mode (@pxref{Lisp Doc,,, emacs, The GNU Emacs Manual}) is +supported. By customizing @code{octave-eldoc-message-style} it can be +changed from displaying one or multi line hints. + +@c @cindex TAGS +@c @cindex Emacs TAGS files +@c @cindex @file{octave-tags} +@c You can generate TAGS files for Emacs from Octave @file{.m} files using +@c the shell script @file{octave-tags} that is installed alongside your copy of +@c Octave. +@c +@vindex octave-mode-hook +Customization of Octave mode can be performed by modification of the +variable @code{octave-mode-hook}. + +@node Running Octave from Within Emacs +@chapter Running Octave from Within Emacs +@cindex Inferior Octave Mode + +Octave mode provides commands for running an inferior +Octave process in a special Emacs buffer. Use +@lisp +M-x run-octave +@end lisp +@noindent +to directly start an inferior Octave process. + +@vindex inferior-octave-buffer +This will start Octave in a special buffer the name of which is +specified by the variable @code{inferior-octave-buffer} and defaults +to @file{*Inferior Octave*}. From within this buffer, you can +interact with the inferior Octave process ``as usual'', i.e., by +entering Octave commands at the prompt. The buffer is in Inferior +Octave mode, which is derived from the standard Comint mode, a major +mode for interacting with an inferior interpreter. See the +documentation for @code{comint-mode} for more details, and use +@kbd{C-h b} to find out about available special keybindings. + +You can also communicate with an inferior Octave process from within +files with Octave code (i.e., buffers in Octave mode), using the +following commands. + +@table @kbd +@item C-c C-i l +@kindex C-c C-i l +@findex octave-send-line +@vindex octave-send-line-auto-forward +Send the current line to the inferior Octave process +(@code{octave-send-line}). With positive prefix argument @var{n}, +send that many lines. If @code{octave-send-line-auto-forward} is +non-@code{nil}, go to the next unsent code line. + +@item C-c C-i b +@kindex C-c C-i b +@findex octave-send-block +Send the current block to the inferior Octave process +(@code{octave-send-block}). + +@item C-c C-i f +@kindex C-c C-i f +@findex octave-send-defun +Send the current function to the inferior Octave process +(@code{octave-send-defun}). + +@item C-c C-i r +@kindex C-c C-i r +@findex octave-send-region +Send the region to the inferior Octave process +(@code{octave-send-region}). + +@item C-c C-i a +@kindex C-c C-i a +@findex octave-send-buffer +Send the entire buffer to the inferior Octave process +(@code{octave-send-buffer}). If the buffer is associated with a file +then sourcing the buffer by using @kbd{C-c C-l} +(@code{octave-source-file}) should be preferred. + +@item C-c C-i s +@kindex C-c C-i s +@findex octave-show-process-buffer +Make sure that @code{inferior-octave-buffer} is displayed +(@code{octave-show-process-buffer}). + +@item C-c C-i q +@kindex C-c C-i q +@findex octave-hide-process-buffer +Delete all windows that display the inferior Octave buffer +(@code{octave-hide-process-buffer}). + +@item C-c C-i k +@kindex C-c C-i k +@findex octave-kill-process +Kill the inferior Octave process and its buffer +(@code{octave-kill-process}). + +@item C-c C-l +@kindex C-c C-l +@findex octave-source-file +Parse and execute the current file in the inferior Octave buffer +(@code{octave-source-file}). This is done using Octave's +@code{source} function. + +@item M-. +@kindex M-. +@findex octave-find-definition +@vindex octave-source-directories +Find the definition of a function or variable. Functions implemented +in C++ can be found if variable @code{octave-source-directories} is +set correctly (@code{octave-find-definition}). + +@item C-h d +@kindex C-h d +@findex octave-help +@vindex octave-help-buffer +Display the documentation for function (@code{octave-help}). The +buffer name can be changed by customizing @code{octave-help-buffer}. + +@item C-h a +@kindex C-h a +@findex octave-lookfor +Search for a given string in all the first sentence of function help +strings (@code{octave-lookfor}). With a @code{universal-argument} the +entire help string is searched. + +@end table + +The effect of the commands which send code to the Octave process can be +customized by the following variables. + +@vtable @code +@item octave-send-echo-input +Non-@code{nil} means echo input sent to the inferior Octave process. +Default is @code{t}. + +@item octave-send-show-buffer +Non-@code{nil} means display the buffer running the Octave process after +sending a command (but without selecting it). +Default is @code{t}. +@end vtable + +If you send code and there is no inferior Octave process yet, it will +be started automatically. + +@vindex inferior-octave-startup-args +The startup of the inferior Octave process is highly customizable. +The variable @code{inferior-octave-startup-args} can be used for +specifying command lines arguments to be passed to Octave on startup +as a list of strings. For example, to suppress the startup message +and use ``traditional'' mode, set this to @code{("-q" "--traditional")}. +You can also specify a startup file of Octave commands to be loaded on +startup; note that these commands will not produce any visible output +in the process buffer. Which file to use is controlled by the +variable @code{inferior-octave-startup-file}. The default is +@file{~/.emacs-octave} or if this file is not found +@file{~/.emacs.d/init_octave.m}. + +@vindex inferior-octave-prompt-read-only +By customizing @code{inferior-octave-prompt-read-only} the prompt can +be changed to be read only. The default value is the same as +@code{comint-prompt-read-only}. + +@vindex inferior-octave-mode-hook +And finally, @code{inferior-octave-mode-hook} is run after starting +the process and putting its buffer into Inferior Octave mode. Hence, +if you like the up and down arrow keys to behave in the interaction +buffer as in the shell, and you want this buffer to use nice colors, +add +@lisp +(add-hook 'inferior-octave-mode-hook + (lambda () + (define-key inferior-octave-mode-map [up] + 'comint-previous-input) + (define-key inferior-octave-mode-map [down] + 'comint-next-input))) +@end lisp +@noindent +to your @file{.emacs} or @file{init.el} file. You could also swap the +roles of @kbd{C-a} (@code{beginning-of-line}) and @code{C-c C-a} +(@code{comint-bol}) using this hook. + +@vindex inferior-octave-prompt +@quotation +@strong{Note} that if you set your Octave prompts to something different +from the defaults, make sure that @code{inferior-octave-prompt} matches +them. Otherwise, @emph{nothing} will work, because Emacs will not know +when Octave is waiting for input, or done sending output. +@end quotation + +@node GNU Free Documentation License +@chapter GNU Free Documentation License +@include doclicense.texi + +@node Key Index +@unnumbered Key Index + +@printindex ky + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + +@node Lisp Function Index +@unnumbered Function Index + +@printindex fn + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + + +@bye + +@c TODO Update + +@c @node Using the Emacs Info Reader for Octave +@c @chapter Using the Emacs Info Reader for Octave + +@c You may also use the Emacs Info reader with Octave's @code{doc} function. + +@c If @file{gnuserv} is installed, add the lines +@c @lisp +@c (autoload 'octave-help "octave-hlp" nil t) +@c (require 'gnuserv) +@c (gnuserv-start) +@c @end lisp +@c @noindent +@c to your @file{.emacs} file. + +@c You can use either 'plain' Emacs Info or the function @code{octave-help} +@c as your Octave info reader (for @samp{help -i}). In the former case, +@c use @code{info_program ("info-emacs-info")}. +@c The latter is perhaps more attractive because it allows to look up keys +@c in the indices of @emph{several} info files related to Octave (provided +@c that the Emacs variable @code{octave-help-files} is set correctly). In +@c this case, use @code{info_program ("info-emacs-octave-help")}. + +@c If you use Octave from within Emacs, it is best to add these settings to +@c your @file{~/.emacs-octave} startup file (or the file pointed to by the +@c Emacs variable @code{inferior-octave-startup-file}). diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 832976e9ea0..71572f72d7a 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -1,16 +1,13 @@ -\input texinfo +\input texinfo @c -*- coding: utf-8 -*- @c %**start of header -@setfilename ../../info/org +@setfilename ../../info/org.info @settitle The Org Manual -@set VERSION 7.9.3f (GNU Emacs 24.3) +@include docstyle.texi -@c Use proper quote and backtick for code sections in PDF output -@c Cf. Texinfo manual 14.2 -@set txicodequoteundirected -@set txicodequotebacktick +@set VERSION 8.2.9 @c Version and Contact Info -@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} +@set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page} @set AUTHOR Carsten Dominik @set MAINTAINER Carsten Dominik @set MAINTAINEREMAIL @email{carsten at orgmode dot org} @@ -262,13 +259,13 @@ @copying This manual is for Org version @value{VERSION}. -Copyright @copyright{} 2004--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2015 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,'' +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.'' @@ -287,7 +284,8 @@ modify this GNU manual.'' @subtitle Release @value{VERSION} @author by Carsten Dominik -with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K. +with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan +Davison, Eric Schulte, Thomas Dye, Jambunathan K and Nicolas Goaziou. @c The following two commands start the copyright page. @page @@ -320,7 +318,7 @@ with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, * Capture - Refile - Archive:: The ins and outs for projects * Agenda Views:: Collecting information into views * Markup:: Prepare text for rich export -* Exporting:: Sharing and publishing of notes +* Exporting:: Sharing and publishing 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 @@ -357,6 +355,18 @@ Document structure * Blocks:: Folding blocks * Footnotes:: How footnotes are defined in Org's syntax * Orgstruct mode:: Structure editing outside Org +* Org syntax:: Formal description of Org's syntax + +Visibility cycling + +* Global and local cycling:: Cycling through various visibility states +* Initial visibility:: Setting the initial visibility state +* Catching invisible edits:: Preventing mistakes when editing invisible parts + +Global and local cycling + +* Initial visibility:: Setting the initial visibility state +* Catching invisible edits:: Preventing mistakes when editing invisible parts Tables @@ -375,6 +385,7 @@ The spreadsheet * Durations and time values:: How to compute durations and time values * Field and range formulas:: Formula for specific (ranges of) fields * Column formulas:: Formulas valid for an entire column +* Lookup functions:: Lookup functions for searching tables * Editing and debugging formulas:: Fixing formulas * Updating the table:: Recomputing all dependent fields * Advanced features:: Field and column names, parameters and automatic recalc @@ -423,6 +434,7 @@ Tags * Tag inheritance:: Tags use the tree structure of the outline * Setting tags:: How to assign tags to a headline +* Tag groups:: Use one tag to search for several tags * Tag searches:: Searching for combinations of tags Properties and columns @@ -477,7 +489,7 @@ Capture - Refile - Archive * 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 +* Refile and copy:: Moving/copying a tree from one place to another * Archiving:: What to do with finished projects Capture @@ -521,7 +533,8 @@ Presentation and sorting * Categories:: Not all tasks are equal * Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things +* Sorting agenda items:: The order of things +* Filtering/limiting agenda items:: Dynamically narrow the agenda Custom agenda views @@ -532,19 +545,19 @@ Custom agenda views Markup for rich export * Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included +* Images and tables:: Images, tables and caption mechanism * 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 +* Macro replacement:: Use macros to create templates * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents +* Special blocks:: Containers targeted at export back-ends Structural markup elements * Document title:: Where the title is taken from * Headings and sections:: The document structure as seen by the exporter * Table of contents:: The if and where of the table of contents -* Initial text:: Text before the first heading? * Lists:: Lists * Paragraphs:: Paragraphs * Footnote markup:: Footnotes @@ -562,22 +575,26 @@ Embedded @LaTeX{} Exporting -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands +* The Export Dispatcher:: The main exporter interface +* Export back-ends:: Built-in export formats +* Export settings:: Generic export settings * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* Beamer export:: Exporting as a Beamer presentation * HTML export:: Exporting to HTML * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF -* DocBook export:: Exporting to DocBook +* Markdown export:: Exporting to Markdown * OpenDocument Text export:: Exporting to OpenDocument Text -* TaskJuggler export:: Exporting to TaskJuggler -* Freemind export:: Exporting to Freemind mind maps -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format +* Org export:: Exporting to Org +* Texinfo export:: Exporting to Texinfo +* iCalendar export:: Exporting to iCalendar +* Other built-in back-ends:: Exporting to a man page +* Export in foreign buffers:: Author tables and lists in Org syntax +* Advanced configuration:: Fine-tuning the export output HTML export * HTML Export commands:: How to invoke HTML export +* HTML doctypes:: Org can export to various (X)HTML flavors * HTML preamble and postamble:: How to insert a preamble and a postamble * Quoting HTML tags:: Using direct HTML in Org mode * Links in HTML export:: How links will be interpreted and formatted @@ -590,21 +607,10 @@ HTML export @LaTeX{} and PDF export -* @LaTeX{}/PDF export commands:: +* @LaTeX{} export commands:: How to export to LaTeX and PDF * 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 - -* DocBook export commands:: How to invoke DocBook export -* Quoting DocBook code:: Incorporating DocBook code in Org files -* Recursive sections:: Recursive sections in DocBook -* Tables in DocBook export:: Tables are exported as HTML tables -* Images in DocBook export:: How to insert figures into DocBook output -* Special characters:: How to handle special characters +* @LaTeX{} specific attributes:: Controlling @LaTeX{} output OpenDocument Text export @@ -633,6 +639,16 @@ Advanced topics in ODT export * Customizing tables in ODT export:: How to define and use Table templates * Validating OpenDocument XML:: How to debug corrupt OpenDocument files +Texinfo export + +* Texinfo export commands:: How to invoke Texinfo export +* Document preamble:: File header, title and copyright page +* Headings and sectioning structure:: Building document structure +* Indices:: Creating indices +* Quoting Texinfo code:: Incorporating literal Texinfo code +* Texinfo specific attributes:: Controlling Texinfo output +* An example:: + Publishing * Configuration:: Defining projects @@ -680,8 +696,8 @@ 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 +* Language-specific header arguments in Org mode properties:: Set language-specific 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 @@ -714,8 +730,12 @@ Specific header arguments * colnames:: Handle column names in tables * rownames:: Handle row names in tables * shebang:: Make tangled files executable +* tangle-mode:: Set permission of tangled files * eval:: Limit evaluation of specific code blocks * wrap:: Mark source block evaluation results +* post:: Post processing of code block results +* prologue:: Text to prepend to code block body +* epilogue:: Text to append to code block body Miscellaneous @@ -729,7 +749,7 @@ Miscellaneous * Clean view:: Getting rid of leading stars in the outline * TTY keys:: Using Org on a tty * Interaction:: Other Emacs packages -* org-crypt.el:: Encrypting Org files +* org-crypt:: Encrypting Org files Interaction with other packages @@ -741,11 +761,13 @@ Hacking * Hooks:: How to reach into Org's internals * Add-on packages:: Available extensions * Adding hyperlink types:: New custom link types +* Adding export back-ends:: How to write new export back-ends * Context-sensitive commands:: How to add functionality to such commands * 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 +* Speeding up your agendas:: Tips on how to speed up your agendas +* Extracting agenda information:: Post-processing of agenda information * Using the property API:: Writing programs that use entry properties * Using the mapping API:: Mapping over all or selected entries @@ -754,7 +776,7 @@ Tables and lists in arbitrary syntax * Radio tables:: Sending and receiving radio tables * A @LaTeX{} example:: Step by step, almost a tutorial * Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists +* Radio lists:: Sending and receiving lists MobileOrg @@ -794,7 +816,7 @@ timestamps, and scheduling. It dynamically compiles entries into an agenda that utilizes and smoothly integrates much of the Emacs calendar and diary. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects. -For printing and sharing of notes, an Org file can be exported as a +For printing and sharing notes, an Org file can be exported as a structured ASCII file, as HTML, or (TODO and agenda items only) as an iCalendar file. It can also serve as a publishing tool for a set of linked web pages. @@ -828,7 +850,7 @@ ends, for example: @pindex GTD, Getting Things Done @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{} a publishing tool to create a set of interlinked web pages} @r{@bullet{} an environment for literate programming} @end example @@ -867,10 +889,15 @@ We @b{strongly recommend} to stick to a single installation method. Recent Emacs distributions include a packaging system which lets you install Elisp libraries. You can install Org with @kbd{M-x package-install RET org}. -To make sure your Org configuration is well taken into account, initialize -the package system with @code{(package-initialize)} before setting any Org -option. If you want to use Org's package repository, check out the -@uref{http://orgmode.org/elpa.html, Org ELPA page}. + +@noindent @b{Important}: you need to do this in a session where no @code{.org} file has +been visited, i.e., where no Org built-in function have been loaded. +Otherwise autoload Org functions will mess up the installation. + +Then, to make sure your Org configuration is taken into account, initialize +the package system with @code{(package-initialize)} in your @file{.emacs} +before setting any Org option. If you want to use Org's package repository, +check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}. @subsubheading Downloading Org as an archive @@ -878,17 +905,17 @@ You can download Org latest release from @uref{http://orgmode.org/, Org's website}. In this case, make sure you set the load-path correctly in your @file{.emacs}: -@example +@lisp (add-to-list 'load-path "~/path/to/orgdir/lisp") -@end example +@end lisp The downloaded archive contains contributed libraries that are not included in Emacs. If you want to use them, add the @file{contrib} directory to your load-path: -@example +@lisp (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) -@end example +@end lisp Optionally, you can compile the files and/or install them in your system. Run @code{make help} to list compilation and installation options. @@ -1001,10 +1028,10 @@ 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 +(@kbd{M-x org-version RET}), as well as the Org related setup in @file{.emacs}. The easiest way to do this is to use the command @example -@kbd{M-x org-submit-bug-report} +@kbd{M-x org-submit-bug-report RET} @end example @noindent which will put all this information into an Emacs mail buffer so that you only need to add your description. If you re not sending the Email @@ -1025,8 +1052,8 @@ is not necessary. In that case it is sufficient to start Emacs as @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as shown below. -@example -;;; Minimal setup to load latest `org-mode' +@lisp +;;; Minimal setup to load latest 'org-mode' ;; activate debugging (setq debug-on-error t @@ -1036,7 +1063,7 @@ shown below. ;; add latest org-mode to load path (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) (add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t)) -@end example +@end lisp If an error occurs, a backtrace can be very useful (see below on how to create one). Often a small example file helps, along with clear information @@ -1064,7 +1091,7 @@ Reload uncompiled versions of all Org mode Lisp files. The backtrace contains much more information if it is produced with uncompiled code. To do this, use @example -C-u M-x org-reload RET +@kbd{C-u M-x org-reload RET} @end example @noindent or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the @@ -1109,7 +1136,7 @@ and @i{environment keywords} (like @code{#+BEGIN_HTML} to start a @code{HTML} environment). They are written in uppercase in the manual to enhance its readability, but you can use lowercase in your Org files@footnote{Easy templates insert lowercase keywords and Babel dynamically inserts -@code{#+results}.} +@code{#+results}.}. @subsubheading Keybindings and commands @kindex C-c a @@ -1152,6 +1179,7 @@ edit the structure of the document. * Blocks:: Folding blocks * Footnotes:: How footnotes are defined in Org's syntax * Orgstruct mode:: Structure editing outside Org +* Org syntax:: Formal description of Org's syntax @end menu @node Outlines, Headlines, Document Structure, Document Structure @@ -1213,6 +1241,15 @@ variable @code{org-cycle-separator-lines} to modify this behavior. @cindex show hidden text @cindex hide text +@menu +* Global and local cycling:: Cycling through various visibility states +* Initial visibility:: Setting the initial visibility state +* Catching invisible edits:: Preventing mistakes when editing invisible parts +@end menu + +@node Global and local cycling, Initial visibility, Visibility cycling, Visibility cycling +@subsection Global and local cycling + Outlines make it possible to hide parts of the text in the buffer. Org uses just two commands, bound to @key{TAB} and @kbd{S-@key{TAB}} to change the visibility in the buffer. @@ -1258,6 +1295,9 @@ When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the CONTENTS view up to headlines of level N will be shown. Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field. +@cindex set startup visibility, command +@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility} +Switch back to the startup visibility of the buffer (@pxref{Initial visibility}). @cindex show all, command @orgcmd{C-u C-u C-u @key{TAB},show-all} Show all, including drawers. @@ -1295,6 +1335,15 @@ the previously used indirect buffer. Copy the @i{visible} text in the region into the kill ring. @end table +@menu +* Initial visibility:: Setting the initial visibility state +* Catching invisible edits:: Preventing mistakes when editing invisible parts +@end menu + +@node Initial visibility, Catching invisible edits, Global and local cycling, Visibility cycling +@subsection Initial visibility + +@cindex visibility, initialize @vindex org-startup-folded @vindex org-agenda-inhibit-startup @cindex @code{overview}, STARTUP keyword @@ -1302,11 +1351,13 @@ Copy the @i{visible} text in the region into the kill ring. @cindex @code{showall}, STARTUP keyword @cindex @code{showeverything}, STARTUP keyword -When Emacs first visits an Org file, the global state is set to -OVERVIEW, i.e., only the top level headlines are visible. This can be -configured through the variable @code{org-startup-folded}, or on a -per-file basis by adding one of the following lines anywhere in the -buffer: +When Emacs first visits an Org file, the global state is set to OVERVIEW, +i.e., only the top level headlines are visible@footnote{When +@code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default +visibility state when first opening a file for the agenda (@pxref{Speeding up +your agendas}).}. This can be configured through the variable +@code{org-startup-folded}, or on a per-file basis by adding one of the +following lines anywhere in the buffer: @example #+STARTUP: overview @@ -1317,7 +1368,7 @@ buffer: The startup visibility options are ignored when the file is open for the first time during the agenda generation: if you want the agenda to honor -the startup visibility, set @code{org-agenda-inhibit-startup} to nil. +the startup visibility, set @code{org-agenda-inhibit-startup} to @code{nil}. @cindex property, VISIBILITY @noindent @@ -1325,6 +1376,7 @@ 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 @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 @@ -1332,6 +1384,17 @@ requested by startup options and @samp{VISIBILITY} properties in individual entries. @end table +@node Catching invisible edits, , Initial visibility, Visibility cycling +@subsection Catching invisible edits + +@vindex org-catch-invisible-edits +@cindex edits, catching invisible +Sometimes you may inadvertently edit an invisible part of the buffer and be +confused on what has been edited and how to undo the mistake. Setting +@code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the +docstring of this option on how Org should catch invisible edits and process +them. + @node Motion, Structure editing, Visibility cycling, Document Structure @section Motion @cindex motion, between headlines @@ -1369,7 +1432,7 @@ q @r{Quit} @end example @vindex org-goto-interface @noindent -See also the variable @code{org-goto-interface}. +See also the option @code{org-goto-interface}. @end table @node Structure editing, Sparse trees, Motion, Document Structure @@ -1388,17 +1451,20 @@ See also the variable @code{org-goto-interface}. @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 creation of -a new headline, use a prefix argument. When this command is used in the -middle of a line, the line is split and the rest of the line becomes the new -headline@footnote{If you do not want the line to be split, customize the -variable @code{org-M-RET-may-split-line}.}. If the command is used at the -beginning of a headline, the new headline is created before the current line. -If at the beginning of any other line, the content of that line is made the -new heading. If the command is used at the end of a folded subtree (i.e., -behind the ellipses at the end of a headline), then a headline like the -current one will be inserted after the end of the subtree. +Insert a new heading/item with the same level than the one at point. +If the cursor is in a plain list item, a new item is created +(@pxref{Plain lists}). To prevent this behavior in lists, call the +command with a prefix argument. When this command is used in the +middle of a line, the line is split and the rest of the line becomes +the new item or headline@footnote{If you do not want the line to be +split, customize the variable @code{org-M-RET-may-split-line}.}. If +the command is used at the @emph{beginning} of a headline, the new +headline is created before the current line. If the command is used +at the @emph{end} of a folded subtree (i.e., behind the ellipses at +the end of a headline), then a headline will be +inserted after the end of the subtree. Calling this command with +@kbd{C-u C-u} will unconditionally respect the headline's content and +create a new item at the end of the parent subtree. @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 @@ -1450,7 +1516,7 @@ headline marker like @samp{****}. @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 +Depending on the options @code{org-yank-adjusted-subtrees} and @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will paste subtrees folded and in a clever way, using the same command as @kbd{C-c C-x C-y}. With the default settings, no level adjustment will take place, @@ -1468,7 +1534,7 @@ 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}. @orgcmd{C-c C-w,org-refile} -Refile entry or region to a different location. @xref{Refiling notes}. +Refile entry or region to a different location. @xref{Refile and copy}. @orgcmd{C-c ^,org-sort} 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 @@ -1550,11 +1616,10 @@ Jump to the next sparse tree match in this buffer. Jump to the previous sparse tree match in this buffer. @end table - @noindent @vindex org-agenda-custom-commands For frequently used sparse trees of specific search strings, you can -use the variable @code{org-agenda-custom-commands} to define fast +use the option @code{org-agenda-custom-commands} to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). For example: @@ -1570,15 +1635,15 @@ a sparse tree matching the string @samp{FIXME}. The other sparse tree commands select headings based on TODO keywords, tags, or properties and will be discussed later in this manual. -@kindex C-c C-e v +@kindex C-c C-e C-v @cindex printing sparse trees @cindex visible text, printing To print a sparse tree, you can use the Emacs command @code{ps-print-buffer-with-faces} which does not print invisible parts of the document @footnote{This does not work under XEmacs, because XEmacs uses selective display for outlining, not text properties.}. -Or you can use the command @kbd{C-c C-e v} to export only the visible -part of the document and print the resulting file. +Or you can use @kbd{C-c C-e C-v} to export only the visible part of +the document and print the resulting file. @node Plain lists, Drawers, Sparse trees, Document Structure @section Plain lists @@ -1604,12 +1669,12 @@ is supported, it may be better to not use it for plain list items.} as bullets. @item @vindex org-plain-list-ordered-item-terminator -@vindex org-alphabetical-lists +@vindex org-list-allow-alphabetical @emph{Ordered} list items start with a numeral followed by either a period or 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)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and -@samp{A)} by configuring @code{org-alphabetical-lists}. To minimize +@samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize confusion with normal text, those are limited to one character only. Beyond that limit, bullets will automatically fallback to numbers.}. If you want a list to start with a different value (e.g., 20), start the text of the item @@ -1629,11 +1694,11 @@ line. In particular, if an ordered list reaches number @samp{10.}, then the list. An item ends before the next line that is less or equally indented than its bullet/number. -@vindex org-empty-line-terminates-plain-lists +@vindex org-list-empty-line-terminates-plain-lists A list ends whenever every item has ended, which means before any line less or equally indented than items at top level. It also ends before two blank -lines@footnote{See also @code{org-empty-line-terminates-plain-lists}.}. In -that case, all items are closed. Here is an example: +lines@footnote{See also @code{org-list-empty-line-terminates-plain-lists}.}. +In that case, all items are closed. Here is an example: @example @group @@ -1705,7 +1770,7 @@ one. @table @kbd @kindex M-S-@key{RET} -@item M-S-RET +@item M-S-@key{RET} Insert a new item with a checkbox (@pxref{Checkboxes}). @kindex S-@key{down} @item S-up @@ -1724,7 +1789,7 @@ similar effect. @item M-up @itemx M-down Move the item including subitems up/down@footnote{See -@code{org-liste-use-circular-motion} for a cyclic behavior.} (swap with +@code{org-list-use-circular-motion} for a cyclic behavior.} (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic. @kindex M-@key{left} @@ -1734,8 +1799,8 @@ is automatic. Decrease/increase the indentation of an item, leaving children alone. @kindex M-S-@key{left} @kindex M-S-@key{right} -@item M-S-left -@itemx M-S-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 @@ -1781,9 +1846,11 @@ This command also cycles bullet styles when the cursor in on the bullet or anywhere in an item line, details depending on @code{org-support-shift-select}. @kindex C-c ^ +@cindex sorting, of plain list @item C-c ^ Sort the plain list. You will be prompted for the sorting method: -numerically, alphabetically, by time, or by custom function. +numerically, alphabetically, by time, by checked status for check lists, +or by a custom function. @end table @node Drawers, Blocks, Plain lists, Document Structure @@ -1797,10 +1864,9 @@ numerically, alphabetically, by time, or by custom function. @kindex C-c C-x d Sometimes you want to keep information associated with an entry, but you normally don't want to see it. For this, Org mode has @emph{drawers}. -Drawers need to be configured with the variable -@code{org-drawers}@footnote{You can define additional drawers on a -per-file basis with a line like @code{#+DRAWERS: HIDDEN STATE}}. Drawers -look like this: +Drawers need to be configured with the option @code{org-drawers}@footnote{You +can define additional drawers on a per-file basis with a line like +@code{#+DRAWERS: HIDDEN STATE}}. Drawers look like this: @example ** This is a headline @@ -1833,6 +1899,12 @@ want to store a quick note in the LOGBOOK drawer, in a similar way to state chan Add a time-stamped note to the LOGBOOK drawer. @end table +@vindex org-export-with-drawers +You can select the name of the drawers which should be exported with +@code{org-export-with-drawers}. In that case, drawer contents will appear in +export output. Property drawers are not affected by this variable and are +never exported. + @node Blocks, Footnotes, Drawers, Document Structure @section Blocks @@ -1842,7 +1914,7 @@ Org mode uses begin...end blocks for various purposes from including source code examples (@pxref{Literal examples}) to capturing time logging information (@pxref{Clocking work time}). These blocks can be folded and unfolded by pressing TAB in the begin line. You can also get all blocks -folded at startup by configuring the variable @code{org-hide-block-startup} +folded at startup by configuring the option @code{org-hide-block-startup} or on a per-file basis by using @cindex @code{hideblocks}, STARTUP keyword @@ -1857,13 +1929,13 @@ or on a per-file basis by using @cindex footnotes Org mode supports the creation of footnotes. In contrast to the -@file{footnote.el} package, Org mode's footnotes are designed for work on a -larger document, not only for one-off documents like emails. The basic -syntax is similar to the one used by @file{footnote.el}, i.e., a footnote is -defined in a paragraph that is started by a footnote marker in square -brackets in column 0, no indentation allowed. If you need a paragraph break -inside a footnote, use the @LaTeX{} idiom @samp{\par}. The footnote reference -is simply the marker in square brackets, inside text. For example: +@file{footnote.el} package, Org mode's footnotes are designed for work on +a larger document, not only for one-off documents like emails. + +A footnote is started by a footnote marker in square brackets in column 0, no +indentation allowed. It ends at the next footnote definition, headline, or +after two consecutive empty lines. The footnote reference is simply the +marker in square brackets, inside text. For example: @example The Org homepage[fn:1] now looks a lot better than it used to. @@ -1913,11 +1985,11 @@ is at a definition, jump to the (first) reference. @vindex org-footnote-define-inline @vindex org-footnote-section @vindex org-footnote-auto-adjust -Otherwise, create a new footnote. Depending on the variable +Otherwise, create a new footnote. Depending on the option @code{org-footnote-define-inline}@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the definition will be placed right into the text as part of the reference, or -separately into the location determined by the variable +separately into the location determined by the option @code{org-footnote-section}. When this command is called with a prefix argument, a menu of additional @@ -1928,17 +2000,16 @@ s @r{Sort the footnote definitions by reference sequence. During editing,} @r{sequence. If you want them sorted, use this command, which will} @r{also move entries according to @code{org-footnote-section}. Automatic} @r{sorting after each insertion/deletion can be configured using the} - @r{variable @code{org-footnote-auto-adjust}.} + @r{option @code{org-footnote-auto-adjust}.} r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering} - @r{after each insertion/deletion can be configured using the variable} + @r{after each insertion/deletion can be configured using the option} @r{@code{org-footnote-auto-adjust}.} S @r{Short for first @code{r}, then @code{s} action.} n @r{Normalize the footnotes by collecting all definitions (including} @r{inline definitions) into a special section, and then numbering them} @r{in sequence. The references will then also be numbers. This is} @r{meant to be the final step before finishing a document (e.g., sending} - @r{off an email). The exporters do this automatically, and so could} - @r{something like @code{message-send-hook}.} + @r{off an email).} d @r{Delete the footnote at point, and all definitions of and references} @r{to it.} @end example @@ -1960,7 +2031,7 @@ Footnote labels are also links to the corresponding definition/reference, and you can use the usual commands to follow these links. @end table -@node Orgstruct mode, , Footnotes, Document Structure +@node Orgstruct mode, Org syntax, Footnotes, Document Structure @section The Orgstruct minor mode @cindex Orgstruct mode @cindex minor mode for structure editing @@ -1968,7 +2039,7 @@ you can use the usual commands to follow these links. 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 +this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or turn it on by default, for example in Message mode, with one of: @lisp @@ -1980,10 +2051,42 @@ 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 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. +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. + +@vindex orgstruct-heading-prefix-regexp +You can also use Org structure editing to fold and unfold headlines in +@emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}: +the regular expression must match the local prefix to use before Org's +headlines. For example, if you set this variable to @code{";; "} in Emacs +Lisp files, you will be able to fold and unfold headlines in Emacs Lisp +commented lines. Some commands like @code{org-demote} are disabled when the +prefix is set, but folding/unfolding will work correctly. + +@node Org syntax, , Orgstruct mode, Document Structure +@section Org syntax +@cindex Org syntax + +A reference document providing a formal description of Org's syntax is +available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on +Worg}, written and maintained by Nicolas Goaziou. It defines Org's core +internal concepts such as @code{headlines}, @code{sections}, @code{affiliated +keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org +file falls into one of the categories above. + +To explore the abstract structure of an Org buffer, run this in a buffer: + +@lisp +M-: (org-element-parse-buffer) RET +@end lisp + +It will output a list containing the buffer's content represented as an +abstract structure. The export engine relies on the information stored in +this list. Most interactive commands (e.g., for structure editing) also +rely on the syntactic meaning of the surrounding context. @node Tables, Hyperlinks, Document Structure, Top @chapter Tables @@ -2046,7 +2149,7 @@ inserting and deleting avoids shifting other fields. Also, when typing @emph{immediately after the cursor was moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the field is automatically made blank. If this behavior is too -unpredictable for you, configure the variables +unpredictable for you, configure the options @code{org-enable-table-editor} and @code{org-table-auto-blank-field}. @table @kbd @@ -2066,7 +2169,7 @@ table. But it is easier just to start typing, like @tsubheading{Re-aligning and field motion} @orgcmd{C-c C-c,org-table-align} -Re-align the table without moving the cursor. +Re-align the table and don't move to another field. @c @orgcmd{<TAB>,org-table-next-field} Re-align the table, move to the next field. Creates a new row if @@ -2165,7 +2268,7 @@ be inserted with @kbd{C-y}. @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. -Depending on the variable @code{org-table-copy-increment}, integer field +Depending on the option @code{org-table-copy-increment}, integer field values will be incremented during copy. Integers that are too large will not be incremented. Also, a @code{0} prefix argument temporarily disables the increment. This key is also used by shift-selection and related modes @@ -2181,7 +2284,7 @@ window follow the cursor through the table and always show the current field. The follow mode exits automatically when the cursor leaves the table, or when you repeat this command with @kbd{C-u C-u C-c `}. @c -@item M-x org-table-import +@item M-x org-table-import RET Import a file as a table. The table should be TAB or whitespace separated. Use, for example, to import a spreadsheet table or data from a database, because these programs generally can write @@ -2194,12 +2297,12 @@ 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 +@item M-x org-table-export RET @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 -used to export the file can be configured in the variable +used to export the file can be configured in the option @code{org-table-export-default-format}. You may also use properties @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file name and the format for table export in a subtree. Org supports quite @@ -2253,7 +2356,7 @@ Fields that are wider become clipped and end in the string @samp{=>}. 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 +@kbd{C-c `} (that is @kbd{C-c} followed by the grave accent). This will open a new window with the full field. Edit it and finish with @kbd{C-c C-c}. @@ -2274,7 +2377,7 @@ 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 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>}. +also combine alignment and field width like this: @samp{<r10>}. Lines which only contain these formatting cookies will be removed automatically when exporting the document. @@ -2323,7 +2426,7 @@ every vertical line you would like to have: If you like the intuitive way the Org table editor works, you might also want to use it in other modes like Text mode or Mail mode. The minor mode Orgtbl mode makes this possible. You can always toggle -the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for +the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for example in Message mode, use @lisp @@ -2359,6 +2462,7 @@ formula, moving these references by arrow keys * Durations and time values:: How to compute durations and time values * Field and range formulas:: Formula for specific (ranges of) fields * Column formulas:: Formulas valid for an entire column +* Lookup functions:: Lookup functions for searching tables * Editing and debugging formulas:: Fixing formulas * Updating the table:: Recomputing all dependent fields * Advanced features:: Field and column names, parameters and automatic recalc @@ -2384,8 +2488,8 @@ combination like @code{B3}, meaning the 2nd field in the 3rd row. @vindex org-table-use-standard-references However, Org prefers@footnote{Org will understand references typed by the user as @samp{B4}, but it will not use this syntax when offering a formula -for editing. You can customize this behavior using the variable -@code{org-table-use-standard-references}.} to use another, more general +for editing. You can customize this behavior using the option +@code{org-table-use-standard-references}.} to use another, more general representation that looks like this: @example @@@var{row}$@var{column} @@ -2452,15 +2556,15 @@ $1..$3 @r{first three fields in the current row} $P..$Q @r{range, using column names (see under Advanced)} $<<<..$>> @r{start in third column, continue to the one but last} @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})} -@@-1$-2..@@-1 @r{in the first row up, 3 fields from 2 columns on the left} +@@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left} @@I..II @r{between first and second hline, short for @code{@@I..@@II}} @end example @noindent Range references return a vector of values that can be fed -into Calc vector functions. Empty fields in ranges are normally -suppressed, so that the vector contains only the non-empty fields (but -see the @samp{E} mode switch below). If there are no non-empty fields, -@samp{[0]} is returned to avoid syntax errors in formulas. +into Calc vector functions. Empty fields in ranges are normally suppressed, +so that the vector contains only the non-empty fields. For other options +with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax +for Calc}. @subsubheading Field coordinates in formulas @cindex field coordinates @@ -2493,7 +2597,7 @@ number of rows. @vindex org-table-formula-constants @samp{$name} is interpreted as the name of a column, parameter or -constant. Constants are defined globally through the variable +constant. Constants are defined globally through the option @code{org-table-formula-constants}, and locally (for the file) through a line like @@ -2526,7 +2630,7 @@ numbers. @cindex references, to a different table @cindex name, of column or field @cindex constants, in calculations -@cindex #+TBLNAME +@cindex #+NAME, for table You may also reference constants, fields and ranges from a different table, either in the current file or even in a different file. The syntax is @@ -2537,7 +2641,7 @@ remote(NAME-OR-ID,REF) @noindent where NAME can be the name of a table in the current file as set by a -@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an +@code{#+NAME: Name} line before the table. It can also be the ID of an entry, even in a different file, and the reference then refers to the first table in that entry. REF is an absolute field or range reference as described above for example @code{@@3$3} or @code{$somename}, valid in the @@ -2548,14 +2652,13 @@ referenced table. @cindex formula syntax, Calc @cindex syntax, of formulas -A formula can be any algebraic expression understood by the Emacs -@file{Calc} package. @b{Note that @file{calc} has the -non-standard convention that @samp{/} has lower precedence than -@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before -evaluation by @code{calc-eval} (@pxref{Calling Calc from -Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc, GNU -Emacs Calc Manual}), -variable substitution takes place according to the rules described above. +A formula can be any algebraic expression understood by the Emacs @file{Calc} +package. Note that @file{calc} has the non-standard convention that @samp{/} +has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as +@samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc +from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc, +GNU Emacs Calc Manual}), variable substitution takes place according to the +rules described above. @cindex vectors, in table calculations The range vectors can be directly fed into the Calc vector functions like @samp{vmean} and @samp{vsum}. @@ -2568,33 +2671,52 @@ string consists of flags to influence Calc and other modes during execution. By default, Org uses the standard Calc modes (precision 12, angular units degrees, fraction and symbolic modes off). The display format, however, has been changed to @code{(float 8)} to keep tables -compact. The default settings can be configured using the variable +compact. The default settings can be configured using the option @code{org-calc-default-modes}. -@example -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} -E @r{keep empty fields in ranges} -L @r{literal} -@end example +@noindent List of modes: + +@table @asis +@item @code{p20} +Set the internal Calc calculation precision to 20 digits. +@item @code{n3}, @code{s3}, @code{e2}, @code{f4} +Normal, scientific, engineering or fixed format of the result of Calc passed +back to Org. Calc formatting is unlimited in precision as long as the Calc +calculation precision is greater. +@item @code{D}, @code{R} +Degree and radian angle modes of Calc. +@item @code{F}, @code{S} +Fraction and symbolic modes of Calc. +@item @code{T}, @code{t} +Duration computations in Calc or Lisp, @pxref{Durations and time values}. +@item @code{E} +If and how to consider empty fields. Without @samp{E} empty fields in range +references are suppressed so that the Calc vector or Lisp list contains only +the non-empty fields. With @samp{E} the empty fields are kept. For empty +fields in ranges or empty field references the value @samp{nan} (not a +number) is used in Calc formulas and the empty string is used for Lisp +formulas. Add @samp{N} to use 0 instead for both formula types. For the +value of a field the mode @samp{N} has higher precedence than @samp{E}. +@item @code{N} +Interpret all fields as numbers, use 0 for non-numbers. See the next section +to see how this is essential for computations with Lisp formulas. In Calc +formulas it is used only occasionally because there number strings are +already interpreted as numbers without @samp{N}. +@item @code{L} +Literal, for Lisp formulas only. See the next section. +@end table @noindent -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 +Unless you use large integer numbers or high-precision-calculation and +-display for floating point numbers you may alternatively provide a +@samp{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: +formatting@footnote{The @samp{printf} reformatting is limited in precision +because the value passed to it is converted into an @samp{integer} or +@samp{double}. The @samp{integer} is limited in size by truncating the +signed value to 32 bits. The @samp{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} @@ -2605,19 +2727,40 @@ $0;%.1f @r{Reformat current cell to 1 decimal} $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}} tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1} sin($1);Dp3%.1e @r{Same, but use printf specifier for display} -vmean($2..$7) @r{Compute column range mean, using vector function} -vmean($2..$7);EN @r{Same, but treat empty fields as 0} taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree} @end example -Calc also contains a complete set of logical operations. For example +Calc also contains a complete set of logical operations, (@pxref{Logical +Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example -@example -if($1<20,teen,string("")) @r{"teen" if age $1 less than 20, else empty} -@end example +@table @code +@item if($1 < 20, teen, string("")) +"teen" if age $1 is less than 20, else the Org table result field is set to +empty with the empty string. +@item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1 +Sum of the first two columns. When at least one of the input fields is empty +the Org table result field is set to empty. @samp{E} is required to not +convert empty fields to 0. @samp{f-1} is an optional Calc format string +similar to @samp{%.1f} but leaves empty results empty. +@item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E +Mean value of a range unless there is any empty field. Every field in the +range that is empty is replaced by @samp{nan} which lets @samp{vmean} result +in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from +@samp{vmean} and the Org table result field is set to empty. Use this when +the sample set is expected to never have missing values. +@item if("$1..$7" == "[]", string(""), vmean($1..$7)) +Mean value of a range with empty fields skipped. Every field in the range +that is empty is skipped. When all fields in the range are empty the mean +value is not defined and the Org table result field is set to empty. Use +this when the sample set can have a variable size. +@item vmean($1..$7); EN +To complete the example before: Mean value of a range with empty fields +counting as samples with value 0. Use this only when incomplete sample sets +should be padded with 0 to the full size. +@end table -Note that you can also use two org-specific flags @code{T} and @code{t} for -durations computations @ref{Durations and time values}. +You can add your own Calc functions defined in Emacs Lisp with @code{defmath} +and use them in formula syntax for Calc. @node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet @subsection Emacs Lisp forms as formulas @@ -2627,7 +2770,7 @@ 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, +If a formula starts with an apostrophe 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. @@ -2646,14 +2789,14 @@ 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} - '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) -@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}} - '(+ $1 $2);N -@r{Compute the sum of columns 1--4, like Calc's @code{vsum($1..$4)}} - '(apply '+ '($1..$4));N -@end example +@table @code +@item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) +Swap the first two characters of the content of column 1. +@item '(+ $1 $2);N +Add columns 1 and 2, equivalent to Calc's @code{$1+$2}. +@item '(apply '+ '($1..$4));N +Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}. +@end table @node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet @subsection Durations and time values @@ -2677,7 +2820,7 @@ formulas or Elisp formulas: Input duration values must be of the form @code{[HH:MM[:SS]}, where seconds are optional. With the @code{T} flag, computed durations will be displayed as @code{HH:MM:SS} (see the first formula above). With the @code{t} flag, -computed durations will be displayed according to the value of the variable +computed durations will be displayed according to the value of the option @code{org-table-duration-custom-format}, which defaults to @code{'hours} and will display the result as a fraction of hours (see the second formula in the example above). @@ -2741,7 +2884,7 @@ can also be used to assign a formula to some but not all fields in a row. Named field, see @ref{Advanced features}. @end table -@node Column formulas, Editing and debugging formulas, Field and range formulas, The spreadsheet +@node Column formulas, Lookup functions, Field and range formulas, The spreadsheet @subsection Column formulas @cindex column formula @cindex formula, for table column @@ -2749,10 +2892,13 @@ Named field, see @ref{Advanced features}. When you assign a formula to a simple column reference like @code{$3=}, the same formula will be used in all fields of that column, with the following very convenient exceptions: (i) If the table contains horizontal separator -hlines, everything before the first such line is considered part of the table -@emph{header} and will not be modified by column formulas. (ii) Fields that -already get a value from a field/range formula will be left alone by column -formulas. These conditions make column formulas very easy to use. +hlines with rows above and below, everything before the first such hline is +considered part of the table @emph{header} and will not be modified by column +formulas. Therefore a header is mandatory when you use column formulas and +want to add hlines to group rows, like for example to separate a total row at +the bottom from the summand rows above. (ii) Fields that already get a value +from a field/range formula will be left alone by column formulas. These +conditions make column formulas very easy to use. To assign a formula to a column, type it directly into any field in the column, preceded by an equal sign, like @samp{=$1+$2}. When you press @@ -2777,19 +2923,62 @@ stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command will apply it to that many consecutive fields in the current column. @end table -@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet +@node Lookup functions, Editing and debugging formulas, Column formulas, The spreadsheet +@subsection Lookup functions +@cindex lookup functions in tables +@cindex table lookup functions + +Org has three predefined Emacs Lisp functions for lookups in tables. +@table @code +@item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE) +@findex org-lookup-first +Searches for the first element @code{S} in list @code{S-LIST} for which +@lisp +(PREDICATE VAL S) +@end lisp +is @code{t}; returns the value from the corresponding position in list +@code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the +parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same +order as the corresponding parameters are in the call to +@code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If +@code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST} +is returned. +@item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE) +@findex org-lookup-last +Similar to @code{org-lookup-first} above, but searches for the @i{last} +element for which @code{PREDICATE} is @code{t}. +@item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE) +@findex org-lookup-all +Similar to @code{org-lookup-first}, but searches for @i{all} elements for +which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding +values. This function can not be used by itself in a formula, because it +returns a list of values. However, powerful lookups can be built when this +function is combined with other Emacs Lisp functions. +@end table + +If the ranges used in these functions contain empty fields, the @code{E} mode +for the formula should usually be specified: otherwise empty fields will not be +included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result +in an incorrect mapping from an element of @code{S-LIST} to the corresponding +element of @code{R-LIST}. + +These three functions can be used to implement associative arrays, count +matching cells, rank results, group data etc. For practical examples +see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this +tutorial on Worg}. + +@node Editing and debugging formulas, Updating the table, Lookup functions, The spreadsheet @subsection Editing and debugging formulas @cindex formula editing @cindex editing, of table formulas @vindex org-table-use-standard-references -You can edit individual formulas in the minibuffer or directly in the -field. Org can also prepare a special buffer with all active -formulas of a table. When offering a formula for editing, Org -converts references to the standard format (like @code{B3} or @code{D&}) -if possible. If you prefer to only work with the internal format (like -@code{@@3$2} or @code{$4}), configure the variable -@code{org-table-use-standard-references}. +You can edit individual formulas in the minibuffer or directly in the field. +Org can also prepare a special buffer with all active formulas of a table. +When offering a formula for editing, Org converts references to the standard +format (like @code{B3} or @code{D&}) if possible. If you prefer to only work +with the internal format (like @code{@@3$2} or @code{$4}), configure the +option @code{org-table-use-standard-references}. @table @kbd @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula} @@ -2821,6 +3010,7 @@ active formula, the cursor in the formula editor will mark it. While inside the special buffer, Org will automatically highlight any field or range reference at the cursor position. You may edit, remove and add formulas, and use the following commands: + @table @kbd @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} @@ -2872,6 +3062,52 @@ You may edit the @samp{#+TBLFM} directly and re-apply the changed equations with @kbd{C-c C-c} in that line or with the normal recalculation commands in the table. +@anchor{Using multiple #+TBLFM lines} +@subsubheading Using multiple #+TBLFM lines +@cindex #+TBLFM line, multiple +@cindex #+TBLFM +@cindex #+TBLFM, switching +@kindex C-c C-c + +You may apply the formula temporarily. This is useful when you +switch the formula. Place multiple @samp{#+TBLFM} lines right +after the table, and then press @kbd{C-c C-c} on the formula to +apply. Here is an example: + +@example +| x | y | +|---+---| +| 1 | | +| 2 | | +#+TBLFM: $2=$1*1 +#+TBLFM: $2=$1*2 +@end example + +@noindent +Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields: + +@example +| x | y | +|---+---| +| 1 | 2 | +| 2 | 4 | +#+TBLFM: $2=$1*1 +#+TBLFM: $2=$1*2 +@end example + +@noindent +Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you +will get the following result of applying only the first @samp{#+TBLFM} line. + +@example +| x | y | +|---+---| +| 1 | 1 | +| 2 | 2 | +#+TBLFM: $2=$1*1 +#+TBLFM: $2=$1*2 +@end example + @subsubheading Debugging formulas @cindex formula debugging @cindex debugging, of table formulas @@ -2910,10 +3146,10 @@ hline are left alone, assuming that these are part of the table header. 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 +@item M-x org-table-recalculate-buffer-tables RET @findex org-table-recalculate-buffer-tables Recompute all tables in the current buffer. -@item M-x org-table-iterate-buffer-tables +@item M-x org-table-iterate-buffer-tables RET @findex org-table-iterate-buffer-tables Iterate all tables in the current buffer, in order to converge table-to-table dependencies. @@ -2966,6 +3202,7 @@ empty first field. @cindex marking characters, tables The marking characters have the following meaning: + @table @samp @item ! The fields in this line define names for the columns, so that you may @@ -3167,10 +3404,8 @@ internal structure of all links, use the menu entry If the link does not look like a URL, it is considered to be internal in the current file. The most important case is a link like @samp{[[#my-custom-id]]} which will link to the entry with the -@code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very good -for HTML export (@pxref{HTML export}) where they produce pretty section -links. You are responsible yourself to make sure these custom IDs are unique -in a file. +@code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself +to make sure these custom IDs are unique in a file. Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} lead to a text search in the current file. @@ -3178,27 +3413,48 @@ lead to a text search in the current file. The link can be followed with @kbd{C-c C-o} when the cursor is on the link, or with a mouse click (@pxref{Handling links}). Links to custom IDs will point to the corresponding headline. The preferred match for a text link is -a @i{dedicated target}: the same string in double angular brackets. Targets -may be located anywhere; sometimes it is convenient to put them into a -comment line. For example +a @i{dedicated target}: the same string in double angular brackets, like +@samp{<<My Target>>}. + +@cindex #+NAME +If no dedicated target exists, the link will then try to match the exact name +of an element within the buffer. Naming is done with the @code{#+NAME} +keyword, which has to be put the line before the element it refers to, as in +the following example @example -# <<My Target>> +#+NAME: My Target +| a | table | +|----+------------| +| of | four cells | @end example -@noindent In HTML export (@pxref{HTML export}), such targets will become -named anchors for direct access through @samp{http} links@footnote{Note that -text before the first headline is usually not exported, so the first such -target should be after the first headline, or in the line directly before the -first headline.}. - -If no dedicated target exists, Org will search for a headline that is exactly +If none of the above succeeds, 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 +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}. +completions.}. + +During export, internal links will be used to mark objects and assign them +a number. Marked objects will then be referenced by links pointing to them. +In particular, links without a description will appear as the number assigned +to the marked object@footnote{When targeting a @code{#+NAME} keyword, +@code{#+CAPTION} keyword is mandatory in order to get proper numbering +(@pxref{Images and tables}).}. In the following excerpt from an Org buffer + +@example +- one item +- <<target>>another item +Here we refer to item [[target]]. +@end example + +@noindent +The last sentence will appear as @samp{Here we refer to item 2} when +exported. + +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 @@ -3229,26 +3485,23 @@ cursor on or at a target. @section External links @cindex links, external @cindex external links -@cindex links, external @cindex Gnus links @cindex BBDB links @cindex IRC links @cindex URL links @cindex file links -@cindex VM links @cindex RMAIL links -@cindex WANDERLUST links @cindex MH-E links @cindex USENET links @cindex SHELL links @cindex Info links @cindex Elisp links -Org supports links to files, websites, Usenet and email messages, -BBDB database entries and links to both IRC conversations and their -logs. External links are URL-like locators. They start with a short -identifying string followed by a colon. There can be no space after -the colon. The following list shows examples for each link type. +Org supports links to files, websites, Usenet and email messages, BBDB +database entries and links to both IRC conversations and their logs. +External links are URL-like locators. They start with a short identifying +string followed by a colon. There can be no space after the colon. The +following list shows examples for each link type. @example http://www.astro.uva.nl/~dominik @r{on the web} @@ -3263,8 +3516,8 @@ file:sometextfile::NNN @r{file, jump to line number} file:projects.org @r{another Org file} file:projects.org::some words @r{text search in Org file}@footnote{ The actual behavior of the search will depend on the value of -the variable @code{org-link-search-must-match-exact-headline}. If its value -is nil, then a fuzzy text search will be done. If it is t, then only the +the option @code{org-link-search-must-match-exact-headline}. If its value +is @code{nil}, then a fuzzy text search will be done. If it is t, then only the exact headline will be matched. If the value is @code{'query-to-create}, then an exact headline will be searched; if it is not found, then the user will be queried to create it.} @@ -3275,13 +3528,6 @@ docview:papers/last.pdf::NNN @r{open in doc-view mode at page} id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} news:comp.emacs @r{Usenet link} mailto:adent@@galaxy.net @r{Mail link} -vm:folder @r{VM folder link} -vm:folder#id @r{VM message link} -vm://myself@@some.where.org/folder#id @r{VM on remote machine} -vm-imap:account:folder @r{VM IMAP folder link} -vm-imap:account:folder#id @r{VM IMAP message link} -wl:folder @r{WANDERLUST folder link} -wl:folder#id @r{WANDERLUST message link} mhe:folder @r{MH-E folder link} mhe:folder#id @r{MH-E message link} rmail:folder @r{RMAIL folder link} @@ -3296,11 +3542,27 @@ elisp:org-agenda @r{Interactive Elisp command} elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} @end example +@cindex VM links +@cindex WANDERLUST links +On top of these built-in link types, some are available through the +@code{contrib/} directory (@pxref{Installation}). For example, these links +to VM or Wanderlust messages are available when you load the corresponding +libraries from the @code{contrib/} directory: + +@example +vm:folder @r{VM folder link} +vm:folder#id @r{VM message link} +vm://myself@@some.where.org/folder#id @r{VM on remote machine} +vm-imap:account:folder @r{VM IMAP folder link} +vm-imap:account:folder#id @r{VM IMAP message link} +wl:folder @r{WANDERLUST folder link} +wl:folder#id @r{WANDERLUST message link} +@end example + For customizing Org to add new link types @ref{Adding hyperlink types}. -A link should be enclosed in double brackets and may contain a -descriptive text to be displayed instead of the URL (@pxref{Link -format}), for example: +A link should be enclosed in double brackets and may contain a descriptive +text to be displayed instead of the URL (@pxref{Link format}), for example: @example [[http://www.gnu.org/software/emacs/][GNU Emacs]] @@ -3349,14 +3611,13 @@ timestamp in the headline.}. If the headline has a @code{CUSTOM_ID} property, a link to this custom ID will be stored. In addition or alternatively (depending on the value of @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will -be created and/or used to construct a link@footnote{The library @code{org-id} -must first be loaded, either through @code{org-customize} by enabling -@code{id} in @code{org-modules} , or by adding @code{(require 'org-id)} in -your @file{.emacs}.}. So using this command in Org -buffers will potentially create two links: a human-readable from the custom -ID, and one that is globally unique and works even if the entry is moved from -file to file. Later, when inserting the link, you need to decide which one -to use. +be created and/or used to construct a link@footnote{The library +@file{org-id.el} must first be loaded, either through @code{org-customize} by +enabling @code{org-id} in @code{org-modules}, or by adding @code{(require +'org-id)} in your @file{.emacs}.}. So using this command in Org buffers will +potentially create two links: a human-readable from the custom ID, and one +that is globally unique and works even if the entry is moved from file to +file. Later, when inserting the link, you need to decide which one to use. @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@* Pretty much all Emacs mail clients are supported. The link will point to the @@ -3371,10 +3632,10 @@ Links created in a BBDB buffer will point to the current entry. @b{Chat: IRC}@* @vindex org-irc-link-to-logs -For IRC links, if you set the variable @code{org-irc-link-to-logs} to -@code{t}, a @samp{file:/} style link to the relevant point in the logs for -the current conversation is created. Otherwise an @samp{irc:/} style link to -the user/channel/server under the point will be stored. +For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t}, +a @samp{file:/} style link to the relevant point in the logs for the current +conversation is created. Otherwise an @samp{irc:/} style link to the +user/channel/server under the point will be stored. @b{Other files}@* For any other files, the link will point to the file, with a search string @@ -3476,7 +3737,7 @@ would. Under Emacs 22 and later, @kbd{mouse-1} will also follow a link. @vindex org-display-internal-link-with-indirect-buffer 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}}. +option @code{org-display-internal-link-with-indirect-buffer}}. @c @orgcmd{C-c C-x C-v,org-toggle-inline-images} @cindex inlining images @@ -3490,7 +3751,7 @@ 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}}. +@code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}. @orgcmd{C-c %,org-mark-ring-push} @cindex mark ring Push the current position onto the mark ring, to be able to return @@ -3631,7 +3892,7 @@ Jump to line 255. Search for a link target @samp{<<My Target>>}, or do a text search for @samp{my target}, similar to the search in internal links, see @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file -link will become a HTML reference to the corresponding named anchor in +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. @@ -3728,7 +3989,7 @@ Rotate the TODO state of the current item among If TODO keywords have fast access keys (see @ref{Fast access to TODO states}), you will be prompted for a TODO keyword through the fast selection interface; this is the default behavior when -@var{org-use-fast-todo-selection} is @code{non-nil}. +@code{org-use-fast-todo-selection} is non-@code{nil}. The same rotation can also be done ``remotely'' from the timeline and agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). @@ -3736,7 +3997,7 @@ buffers with the @kbd{t} command key (@pxref{Agenda commands}). @orgkey{C-u C-c C-t} When TODO keywords have no selection keys, select a specific keyword using completion; otherwise force cycling through TODO states with no prompt. When -@var{org-use-fast-todo-selection} is set to @code{prefix}, use the fast +@code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast selection interface. @kindex S-@key{right} @@ -3754,12 +4015,11 @@ with @code{shift-selection-mode}. See also the variable View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the 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 +/ 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 a 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. +N, show the tree for the Nth keyword in the option @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 @@ -3930,7 +4190,7 @@ each keyword, in parentheses@footnote{All characters are allowed except @vindex org-fast-tag-selection-include-todo If you then press @kbd{C-c C-t} followed by the selection key, the entry will be switched to this state. @kbd{SPC} can be used to remove any TODO -keyword from an entry.@footnote{Check also the variable +keyword from an entry.@footnote{Check also the option @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO state through the tags interface (@pxref{Setting tags}), in case you like to mingle the two concepts. Note that this means you need to come up with @@ -3994,7 +4254,7 @@ Org mode highlights TODO keywords with special faces: @code{org-todo} for keywords indicating that an item still has to be acted upon, and @code{org-done} for keywords indicating that an item is finished. If you are using more than 2 different states, you might want to use -special faces for some of them. This can be done using the variable +special faces for some of them. This can be done using the option @code{org-todo-keyword-faces}. For example: @lisp @@ -4007,7 +4267,7 @@ special faces for some of them. This can be done using the variable While using a list with face properties as shown for CANCELED @emph{should} work, this does not always seem to be the case. If necessary, define a -special face and use that. A string is interpreted as a color. The variable +special face and use that. A string is interpreted as a color. The option @code{org-faces-easy-properties} determines if that color is interpreted as a foreground or a background color. @@ -4023,7 +4283,7 @@ dependencies. Usually, a parent TODO task should not be marked DONE until all subtasks (defined as children tasks) are marked as DONE@. And sometimes there is a logical sequence to a number of (sub)tasks, so that one task cannot be acted upon before all siblings above it are done. If you customize -the variable @code{org-enforce-todo-dependencies}, Org will block entries +the option @code{org-enforce-todo-dependencies}, Org will block entries from changing state to DONE while they have children that are not DONE@. Furthermore, if an entry has a property @code{ORDERED}, each of its children will be blocked until all earlier siblings are marked DONE@. Here is an @@ -4050,21 +4310,21 @@ example: Toggle the @code{ORDERED} property of the current entry. A property is used 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 +this property with a tag for better visibility, customize the option @code{org-track-ordered-property-with-tag}. @orgkey{C-u C-u C-u C-c C-t} Change TODO state, circumventing any state blocking. @end table @vindex org-agenda-dim-blocked-tasks -If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries +If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries that cannot be closed because of such dependencies will be shown in a dimmed font or even made invisible in agenda views (@pxref{Agenda Views}). @cindex checkboxes and TODO dependencies @vindex org-enforce-todo-dependencies You can also block changes of TODO states by looking at checkboxes -(@pxref{Checkboxes}). If you set the variable +(@pxref{Checkboxes}). If you set the option @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked checkboxes will be blocked from switching to DONE. @@ -4102,13 +4362,17 @@ in-buffer setting is: @code{#+STARTUP: logdone}} (setq org-log-done 'time) @end lisp +@vindex org-closed-keep-when-no-todo @noindent -Then each time you turn an entry from a TODO (not-done) state into any -of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted -just after the headline. If you turn the entry back into a TODO item -through further state cycling, that line will be removed again. If you -want to record a note along with the timestamp, use@footnote{The -corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}} +Then each time you turn an entry from a TODO (not-done) state into any of the +DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after +the headline. If you turn the entry back into a TODO item through further +state cycling, that line will be removed again. If you turn the entry back +to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line +will also be removed, unless you set @code{org-closed-keep-when-no-todo} to +non-@code{nil}. If you want to record a note along with the timestamp, +use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: +lognotedone}.} @lisp (setq org-log-done 'note) @@ -4134,11 +4398,11 @@ When TODO keywords are used as workflow states (@pxref{Workflow states}), you might want to keep track of when a state change occurred and maybe take a note about this change. You can either record just a timestamp, or a time-stamped note for a change. These records will be inserted after the -headline as an itemized list, newest first@footnote{See the variable +headline as an itemized list, newest first@footnote{See the option @code{org-log-states-order-reversed}}. When taking a lot of notes, you might want to get the notes out of the way into a drawer (@pxref{Drawers}). -Customize the variable @code{org-log-into-drawer} to get this behavior---the -recommended drawer for this is called @code{LOGBOOK}@footnote{Note that the +Customize @code{org-log-into-drawer} to get this behavior---the recommended +drawer for this is called @code{LOGBOOK}@footnote{Note that the @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to show an entry---use @key{C-u SPC} to keep it folded here}. You can also overrule the setting of this variable for a subtree by setting a @@ -4160,7 +4424,7 @@ To record a timestamp without a note for TODO keywords configured with @noindent @vindex org-log-done -you not only define global TODO keywords and fast access keys, but also +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 when you are using both @code{org-log-done} and state change logging. @@ -4186,7 +4450,7 @@ to a buffer: @cindex property, LOGGING In order to define logging settings that are local to a subtree or a single item, define a LOGGING property in this entry. Any non-empty -LOGGING property resets all logging settings to nil. You may then turn +LOGGING property resets all logging settings to @code{nil}. You may then turn on logging for this specific tree using STARTUP keywords like @code{lognotedone} or @code{logrepeat}, as well as adding state specific settings like @code{TODO(!)}. For example @@ -4215,8 +4479,7 @@ called ``habits''. A habit has the following properties: @enumerate @item -You have enabled the @code{habits} module by customizing the variable -@code{org-modules}. +You have enabled the @code{habits} module by customizing @code{org-modules}. @item The habit is a TODO item, with a TODO keyword representing an open state. @item @@ -4298,7 +4561,7 @@ The amount of history, in days before today, to appear in consistency graphs. @item org-habit-following-days The number of days after today that will appear in consistency graphs. @item org-habit-show-habits-only-for-today -If non-nil, only show habits in today's agenda view. This is set to true by +If non-@code{nil}, only show habits in today's agenda view. This is set to true by default. @end table @@ -4326,7 +4589,7 @@ By default, Org mode supports three priorities: @samp{A}, @samp{B}, and 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}. +special faces by customizing @code{org-priority-faces}. Priorities can be attached to any outline node; they do not need to be TODO items. @@ -4353,7 +4616,7 @@ also used to modify timestamps (@pxref{Creating timestamps}). See also @vindex org-highest-priority @vindex org-lowest-priority @vindex org-default-priority -You can change the range of allowed priorities by setting the variables +You can change the range of allowed priorities by setting the options @code{org-highest-priority}, @code{org-lowest-priority}, and @code{org-default-priority}. For an individual buffer, you may set these values (highest, lowest, default) like this (please make sure that @@ -4397,7 +4660,7 @@ this issue. @vindex org-hierarchical-todo-statistics If you would like to have the statistics cookie count any TODO entries in the -subtree (not just direct children), configure the variable +subtree (not just direct children), configure @code{org-hierarchical-todo-statistics}. To do this for a single subtree, include the word @samp{recursive} into the value of the @code{COOKIE_DATA} property. @@ -4462,15 +4725,15 @@ checked. @cindex statistics, for checkboxes @cindex checkbox statistics @cindex property, COOKIE_DATA -@vindex org-hierarchical-checkbox-statistics +@vindex org-checkbox-hierarchical-statistics The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies indicating how many checkboxes present in this entry have been checked off, and the total number of checkboxes present. This can give you an idea on how many checkboxes remain, even without opening a folded entry. The cookies can be placed into a headline or into (the first line of) a plain list item. Each cookie covers checkboxes of direct children structurally below the -headline/item on which the cookie appears@footnote{Set the variable -@code{org-hierarchical-checkbox-statistics} if you want such cookies to +headline/item on which the cookie appears@footnote{Set the option +@code{org-checkbox-hierarchical-statistics} if you want such cookies to count all checkboxes below the cookie, not just those belonging to direct children.}. You have to insert the cookie yourself by typing either @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m} @@ -4522,8 +4785,7 @@ Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must be checked off in sequence. A property is used 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}. +for better visibility, customize @code{org-track-ordered-property-with-tag}. @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 @@ -4550,13 +4812,14 @@ headline. Tags are normal words containing letters, numbers, @samp{_}, and @samp{@@}. Tags must be preceded and followed by a single colon, e.g., @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. Tags will by default be in bold face with the same color as the headline. -You may specify special faces for specific tags using the variable +You may specify special faces for specific tags using the option @code{org-tag-faces}, in much the same way as you can for TODO keywords (@pxref{Faces for TODO keywords}). @menu * Tag inheritance:: Tags use the tree structure of the outline * Setting tags:: How to assign tags to a headline +* Tag groups:: Use one tag to search for several tags * Tag searches:: Searching for combinations of tags @end menu @@ -4602,8 +4865,8 @@ on, all the sublevels in the same tree will (for a simple match form) match as well@footnote{This is only true if the search does not involve more complex tests including properties (@pxref{Property searches}).}. The list of matches may then become very long. If you only want to see the first tags -match in a subtree, configure the variable -@code{org-tags-match-list-sublevels} (not recommended). +match in a subtree, configure @code{org-tags-match-list-sublevels} (not +recommended). @vindex org-agenda-use-tag-inheritance Tag inheritance is relevant when the agenda search tries to match a tag, @@ -4611,10 +4874,10 @@ either in the @code{tags} or @code{tags-todo} agenda types. In other agenda types, @code{org-use-tag-inheritance} has no effect. Still, you may want to have your tags correctly set in the agenda, so that tag filtering works fine, with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control -this: the default value includes all agenda types, but setting this to nil +this: the default value includes all agenda types, but setting this to @code{nil} can really speed up agenda generation. -@node Setting tags, Tag searches, Tag inheritance, Tags +@node Setting tags, Tag groups, Tag inheritance, Tags @section Setting tags @cindex setting tags @cindex tags, setting @@ -4635,6 +4898,7 @@ 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}). + @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 @@ -4722,7 +4986,7 @@ and @samp{@@tennisclub} should be selected. Multiple such groups are allowed. these lines to activate any changes. @noindent -To set these mutually exclusive groups in the variable @code{org-tags-alist}, +To set these mutually exclusive groups in the variable @code{org-tag-alist}, you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead of the braces. Similarly, you can use @code{:newline} to indicate a line break. The previous example would be set globally by the following @@ -4785,17 +5049,58 @@ alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag @vindex org-fast-tag-selection-single-key If you find that most of the time you need only a single key press to -modify your list of tags, set the variable -@code{org-fast-tag-selection-single-key}. Then you no longer have to -press @key{RET} to exit fast tag selection---it will immediately exit -after the first change. If you then occasionally need more keys, press -@kbd{C-c} to turn off auto-exit for the current tag selection process -(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c -C-c}). If you set the variable to the value @code{expert}, the special -window is not even shown for single-key tag selection, it comes up only -when you press an extra @kbd{C-c}. - -@node Tag searches, , Setting tags, Tags +modify your list of tags, set @code{org-fast-tag-selection-single-key}. +Then you no longer have to press @key{RET} to exit fast tag selection---it +will immediately exit after the first change. If you then occasionally +need more keys, press @kbd{C-c} to turn off auto-exit for the current tag +selection process (in effect: start selection with @kbd{C-c C-c C-c} +instead of @kbd{C-c C-c}). If you set the variable to the value +@code{expert}, the special window is not even shown for single-key tag +selection, it comes up only when you press an extra @kbd{C-c}. + +@node Tag groups, Tag searches, Setting tags, Tags +@section Tag groups + +@cindex group tags +@cindex tags, groups +In a set of mutually exclusive tags, the first tag can be defined as a +@emph{group tag}. When you search for a group tag, it will return matches +for all members in the group. In an agenda view, filtering by a group tag +will display headlines tagged with at least one of the members of the +group. This makes tag searches and filters even more flexible. + +You can set group tags by inserting a colon between the group tag and other +tags---beware that all whitespaces are mandatory so that Org can parse this +line correctly: + +@example +#+TAGS: @{ @@read : @@read_book @@read_ebook @} +@end example + +In this example, @samp{@@read} is a @emph{group tag} for a set of three +tags: @samp{@@read}, @samp{@@read_book} and @samp{@@read_ebook}. + +You can also use the @code{:grouptags} keyword directly when setting +@code{org-tag-alist}: + +@lisp +(setq org-tag-alist '((:startgroup . nil) + ("@@read" . nil) + (:grouptags . nil) + ("@@read_book" . nil) + ("@@read_ebook" . nil) + (:endgroup . nil))) +@end lisp + +You cannot nest group tags or use a group tag as a tag in another group. + +@kindex C-c C-x q +@vindex org-group-tags +If you want to ignore group tags temporarily, toggle group tags support +with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you +want to disable tag groups completely, set @code{org-group-tags} to @code{nil}. + +@node Tag searches, , Tag groups, Tags @section Tag searches @cindex tag searches @cindex searching for tags @@ -4805,15 +5110,16 @@ information into special lists. @table @kbd @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. -@orgcmd{C-c a m,org-tags-view} -Create a global list of tag matches from all agenda files. +Create a sparse tree with all headlines matching a tags/property/TODO search. +With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line. @xref{Matching tags and properties}. +@orgcmd{C-c a m,org-tags-view} +Create a global list of tag matches from all agenda files. @xref{Matching +tags and properties}. @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 +only TODO items and force checking subitems (see the option @code{org-tags-match-list-sublevels}). @end table @@ -4908,6 +5214,9 @@ file, use a line like #+PROPERTY: NDisks_ALL 1 2 3 4 @end example +Contrary to properties set from a special drawer, you have to refresh the +buffer with @kbd{C-c C-c} to activate this changes. + If you want to add to the value of an existing property, append a @code{+} to the property name. The following results in the property @code{var} having the value ``foo=1 bar=2''. @@ -4954,7 +5263,7 @@ in the current file will be offered as possible completions. @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 C-u M-x org-insert-drawer +@item C-u M-x org-insert-drawer RET @cindex org-insert-drawer Insert a property drawer into the current entry. The drawer will be inserted early in the entry, but after the lines with planning @@ -5033,6 +5342,7 @@ FILE @r{The filename the entry is located in.} 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 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree} Create a sparse tree with all matching entries. With a @@ -5043,7 +5353,7 @@ Create a global list of tag/property matches from all agenda files. @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 +only TODO items and force checking of subitems (see the option @code{org-tags-match-list-sublevels}). @end table @@ -5077,7 +5387,7 @@ 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. If a property has the value @samp{nil}, this is +inherited properties. If a property has the value @code{nil}, this is interpreted as an explicit undefine of the property, so that inheritance search will stop at this value and return @code{nil}. @@ -5233,6 +5543,9 @@ 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. +Numbers are right-aligned when a format specifier with an explicit width like +@code{%5d} or @code{%5.1f} is used. + Here is an example for a complete columns definition, along with allowed values. @@ -5351,7 +5664,7 @@ global @r{make a global view, including all headings in the file} @r{run column view at the top of this file} "@var{ID}" @r{call column view in the tree that has an @code{:ID:}} @r{property with the value @i{label}. You can use} - @r{@kbd{M-x org-id-copy} to create a globally unique ID for} + @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for} @r{the current entry and copy it to the kill-ring.} @end example @item :hlines @@ -5604,10 +5917,9 @@ the following column). @vindex org-read-date-prefer-future 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 +format. But it will in fact accept date/time information in a variety of +formats. Generally, the information should start at the beginning of the +string. 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 @@ -5630,24 +5942,23 @@ in @b{bold}. 14 @result{} @b{2006}-@b{06}-14 12 @result{} @b{2006}-@b{07}-12 2/5 @result{} @b{2007}-02-05 -Fri @result{} nearest Friday (default date or later) +Fri @result{} nearest Friday after the default date sep 15 @result{} @b{2006}-09-15 feb 15 @result{} @b{2007}-02-15 sep 12 9 @result{} 2009-09-12 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45 -22 sept 0:34 @result{} @b{2006}-09-22 0:34 +22 sept 0:34 @result{} @b{2006}-09-22 00:34 w4 @result{} ISO week for of the current year @b{2006} 2012 w4 fri @result{} Friday of ISO week 4 in 2012 2012-w04-5 @result{} Same as above @end example -Furthermore you can specify a relative date by giving, as the -@emph{first} thing in the input: a plus/minus sign, a number and a -letter ([dwmy]) to indicate change in days, weeks, months, 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.: +Furthermore you can specify a relative date by giving, as the @emph{first} +thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to +indicate change in hours, 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.: @example +0 @result{} today @@ -5656,7 +5967,8 @@ the Nth such day, e.g.: +4 @result{} same as above +2w @result{} two weeks from today ++5 @result{} five days from default date -+2tue @result{} second Tuesday from now. ++2tue @result{} second Tuesday from now +-wed @result{} last Wednesday @end example @vindex parse-time-months @@ -5720,7 +6032,7 @@ The actions of the date/time prompt may seem complex, but I assure you they will grow on you, and you will start getting annoyed by pretty much any other way of entering a date/time out there. To help you understand what is going on, the current interpretation of your input will be displayed live in the -minibuffer@footnote{If you find this distracting, turn the display of with +minibuffer@footnote{If you find this distracting, turn the display off with @code{org-read-date-display-live}.}. @node Custom time format, , The date/time prompt, Creating timestamps @@ -5734,7 +6046,7 @@ minibuffer@footnote{If you find this distracting, turn the display of with 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 +customizing the options @code{org-display-custom-times} and @code{org-time-stamp-custom-formats}. @table @kbd @@ -5784,6 +6096,7 @@ Meaning: the task (most likely a TODO item, though not necessarily) is supposed to be finished on that date. @vindex org-deadline-warning-days +@vindex org-agenda-skip-deadline-prewarning-if-scheduled On the deadline date, the task will be listed in the agenda. In addition, the agenda for @emph{today} will carry a warning about the approaching or missed deadline, starting @@ -5798,7 +6111,9 @@ until the entry is marked DONE@. An example: You can specify a different lead time for warnings for a specific deadlines using the following syntax. Here is an example with a warning -period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. +period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is +deactivated if the task get scheduled and you set +@code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}. @item SCHEDULED @cindex SCHEDULED keyword @@ -5819,6 +6134,17 @@ the task will automatically be forwarded until completed. SCHEDULED: <2004-12-25 Sat> @end example +@vindex org-scheduled-delay-days +@vindex org-agenda-skip-scheduled-delay-if-deadline +If you want to @emph{delay} the display of this task in the agenda, use +@code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the +25th but will appear two days later. In case the task contains a repeater, +the delay is considered to affect all occurrences; if you want the delay to +only affect the first scheduled occurrence of the task, use @code{--2d} +instead. See @code{org-scheduled-delay-days} and +@code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to +control this globally or per agenda. + @noindent @b{Important:} Scheduling an item in Org mode should @i{not} be understood in the same way that we understand @i{scheduling a meeting}. @@ -5979,8 +6305,14 @@ special repeaters @samp{++} and @samp{.+}. For example: today. @end example -You may have both scheduling and deadline information for a specific -task---just make sure that the repeater intervals on both are the same. +@vindex org-agenda-skip-scheduled-if-deadline-is-shown +You may have both scheduling and deadline information for a specific task. +If the repeater is set for the scheduling information only, you probably want +the repeater to be ignored after the deadline. If so, set the variable +@code{org-agenda-skip-scheduled-if-deadline-is-shown} to +@code{repeated-after-deadline}. If you want both scheduling and deadline +information to repeat after the same interval, set the same repeater for both +timestamps. An alternative to using a repeater is to create a number of copies of a task subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was @@ -5998,7 +6330,8 @@ you stop working on that task, or when you mark the task done, the clock is stopped and the corresponding time interval is recorded. It also computes the total time spent on each subtree@footnote{Clocking only works if all headings are indented with less than 30 stars. This is a hardcoded -limitation of `lmax' in `org-clock-sum'.} of a project. And it remembers a +limitation of @code{lmax} in @code{org-clock-sum}.} of a project. And it +remembers a history or tasks recently clocked, to that you can jump quickly between a number of tasks absorbing your time. @@ -6192,7 +6525,14 @@ be selected: thisyear, lastyear, thisyear-@var{N} @r{a relative year} @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.} :tstart @r{A time string specifying when to start considering times.} + @r{Relative times like @code{"<-2w>"} can also be used. See} + @r{@ref{Matching tags and properties} for relative time syntax.} :tend @r{A time string specifying when to stop considering times.} + @r{Relative times like @code{"<now>"} can also be used. See} + @r{@ref{Matching tags and properties} for relative time syntax.} +:wstart @r{The starting day of the week. The default is 1 for monday.} +:mstart @r{The starting day of the month. The default 1 is for the first} + @r{day of the month.} :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.} @@ -6243,6 +6583,11 @@ only to fit it into the manual.} :tend "<2006-08-10 Thu 12:00>" #+END: clocktable @end example +A range starting a week ago and ending right now could be written as +@example +#+BEGIN: clocktable :tstart "<-1w>" :tend "<now>" +#+END: clocktable +@end example A summary of the current subtree with % times would be @example #+BEGIN: clocktable :scope subtree :link t :formula % @@ -6260,6 +6605,7 @@ would be @subsubheading Resolving idle time @cindex resolve idle time +@vindex org-clock-x11idle-program-name @cindex idle, resolve, dangling If you clock in on a work item, and then walk away from your @@ -6273,12 +6619,14 @@ as 10 or 15, Emacs can alert you when you get back to your computer after being idle for that many minutes@footnote{On computers using Mac OS X, idleness is based on actual user idleness, not just Emacs' idle time. For X11, you can install a utility program @file{x11idle.c}, available in the -@code{contrib/scripts} directory of the Org git distribution, to get the same -general treatment of idleness. On other systems, idle time refers to Emacs -idle time only.}, and ask what you want to do with the idle time. There will -be a question waiting for you when you get back, indicating how much idle -time has passed (constantly updated with the current amount), as well as a -set of choices to correct the discrepancy: +@code{contrib/scripts} directory of the Org git distribution, or install the +@file{xprintidle} package and set it to the variable +@code{org-clock-x11idle-program-name} if you are running Debian, to get the +same general treatment of idleness. On other systems, idle time refers to +Emacs idle time only.}, and ask what you want to do with the idle time. +There will be a question waiting for you when you get back, indicating how +much idle time has passed (constantly updated with the current amount), as +well as a set of choices to correct the discrepancy: @table @kbd @item k @@ -6470,7 +6818,7 @@ trees to an archive file keeps the system compact and fast. * 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 +* Refile and copy:: Moving/copying a tree from one place to another * Archiving:: What to do with finished projects @end menu @@ -6478,25 +6826,22 @@ trees to an archive file keeps the system compact and fast. @section Capture @cindex capture -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}. +Capture lets you quickly store notes with little interruption of your work +flow. Org's method for capturing new items is heavily inspired by John +Wiegley excellent @file{remember.el} package. Up to version 6.36, Org +used a special setup for @file{remember.el}, then replaced it with +@file{org-remember.el}. As of version 8.0, @file{org-remember.el} has +been completely replaced by @file{org-capture.el}. -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 +If your configuration depends on @file{org-remember.el}, you need to update +it and use the setup described below. To convert your +@code{org-remember-templates}, run the command @example -@kbd{M-x org-capture-import-remember-templates @key{RET}} +@kbd{M-x org-capture-import-remember-templates 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. - -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. +customization. @menu * Setting up capture:: Where notes will be stored @@ -6512,10 +6857,12 @@ 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 +@smalllisp +@group (setq org-default-notes-file (concat org-directory "/notes.org")) (define-key global-map "\C-cc" 'org-capture) -@end example +@end group +@end smalllisp @node Using capture, Capture templates, Setting up capture, Capture @subsection Using capture @@ -6537,7 +6884,7 @@ 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 +Finalize the capture process by refiling (@pxref{Refile and copy}) 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 @@ -6594,13 +6941,15 @@ 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 +@smalllisp +@group (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 +@end group +@end smalllisp @noindent If you then press @kbd{C-c c t}, Org will prepare the template for you like this: @@ -6613,7 +6962,7 @@ for you like this: 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 +the task definition, press @kbd{C-c C-c} and Org returns you to the same place where you started the capture process. To define special keys to capture to a particular template without going @@ -6645,9 +6994,9 @@ 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 +@smalllisp ("b" "Templates for marking stuff to buy") -@end example +@end smalllisp @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. @@ -6657,6 +7006,7 @@ 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 @@ -6685,6 +7035,7 @@ the empty string, it defaults to @code{org-default-notes-file}. A file can also be given as a variable, function, or Emacs Lisp form. Valid values are: + @table @code @item (file "path/to/file") Text will be placed at the beginning or end of that file. @@ -6702,7 +7053,10 @@ For non-unique headings, the full path is safer. 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. +Will create a heading in a date tree for today's date@footnote{Datetree +headlines for years accept tags, so if you use both @code{* 2013 :noexport:} +and @code{* 2013} in your file, the capture will refile the note to the first +one matched.}. @item (file+datetree+prompt "path/to/file") Will create a heading in a date tree, but will prompt for the date. @@ -6729,6 +7083,7 @@ 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 @@ -6782,7 +7137,9 @@ dynamic insertion of content. The templates are expanded in the order given her @smallexample %[@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{The sexp must return a string.} + @r{For convenience, %:keyword (see below) placeholders} + @r{within the expression will be expanded prior to this.} + @r{The sexp must return a string.} %<...> @r{The result of format-time-string on the ... format specification.} %t @r{Timestamp, date only.} %T @r{Timestamp, with date and time.} @@ -6855,22 +7212,22 @@ To place the cursor after template expansion use: @vindex org-capture-templates-contexts To control whether a capture template should be accessible from a specific -context, you can customize @var{org-capture-templates-contexts}. Let's say +context, you can customize @code{org-capture-templates-contexts}. Let's say for example that you have a capture template @code{"p"} for storing Gnus emails containing patches. Then you would configure this option like this: -@example +@smalllisp (setq org-capture-templates-contexts '(("p" (in-mode . "message-mode")))) -@end example +@end smalllisp You can also tell that the command key @code{"p"} should refer to another template. In that case, add this command key like this: -@example +@smalllisp (setq org-capture-templates-contexts '(("p" "q" (in-mode . "message-mode")))) -@end example +@end smalllisp See the docstring of the variable for more information. @@ -6901,7 +7258,6 @@ directory. @noindent The following commands deal with attachments: @table @kbd - @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 must press an additional key @@ -6975,12 +7331,14 @@ 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 +@smalllisp +@group (setq org-feed-alist '(("Slashdot" "http://rss.slashdot.org/Slashdot/slashdot" "~/txt/org/feeds.org" "Slashdot Entries"))) -@end example +@end group +@end smalllisp @noindent will configure that new items from the feed provided by @@ -7009,7 +7367,7 @@ list of drawers in that file: 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 +@node Protocols, Refile and copy, RSS Feeds, Capture - Refile - Archive @section Protocols for external access @cindex protocols, for external access @cindex emacsserver @@ -7023,17 +7381,22 @@ a remote website you are looking at with the browser. See @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed documentation and setup instructions. -@node Refiling notes, Archiving, Protocols, Capture - Refile - Archive -@section Refiling notes +@node Refile and copy, Archiving, Protocols, Capture - Refile - Archive +@section Refile and copy @cindex refiling notes +@cindex copying notes -When reviewing the captured data, you may want to refile some of the entries -into a different list, for example into a project. Cutting, finding the -right location, and then pasting the note is cumbersome. To simplify this -process, you can use the following special command: +When reviewing the captured data, you may want to refile or to copy some of +the entries into a different list, for example into a project. Cutting, +finding the right location, and then pasting the note is cumbersome. To +simplify this process, you can use the following special command: @table @kbd +@orgcmd{C-c M-w,org-copy} +@findex org-copy +Copying works like refiling, except that the original note is not deleted. @orgcmd{C-c C-w,org-refile} +@findex org-refile @vindex org-reverse-note-order @vindex org-refile-targets @vindex org-refile-use-outline-path @@ -7041,6 +7404,7 @@ process, you can use the following special command: @vindex org-refile-allow-creating-parent-nodes @vindex org-log-refile @vindex org-refile-use-cache +@vindex org-refile-keep 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. @@ -7064,13 +7428,17 @@ Use the refile interface to jump to a heading. 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-3 C-c C-w +Refile and keep the entry in place. Also see @code{org-refile-keep} to make +this the default behavior, and beware that this may result in duplicated +@code{ID} properties. @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 +@node Archiving, , Refile and copy, Capture - Refile - Archive @section Archiving @cindex archiving @@ -7307,7 +7675,7 @@ Remove current file from the list of 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 +@item M-x org-iswitchb RET Command to use an @code{iswitchb}-like interface to switch to and between Org buffers. @end table @@ -7338,6 +7706,7 @@ Remove the permanent restriction created by @kbd{C-c C-x <}. @noindent When working with @file{speedbar.el}, you can use the following commands in the Speedbar frame: + @table @kbd @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 @@ -7358,6 +7727,7 @@ following we will assume that @kbd{C-c a} is indeed how the dispatcher is accessed and list keyboard access to commands accordingly. After pressing @kbd{C-c a}, an additional letter is required to execute a command. The dispatcher offers the following default commands: + @table @kbd @item a Create the calendar-like agenda (@pxref{Weekly/daily agenda}). @@ -7446,11 +7816,16 @@ C-c a a}) you may set the number of days to be displayed. @vindex org-agenda-span @vindex org-agenda-ndays +@vindex org-agenda-start-day +@vindex org-agenda-start-on-weekday 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}. +agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or +@code{year}. For weekly agendas, the default is to start on the previous +monday (see @code{org-agenda-start-on-weekday}). You can also set the start +date using a date shift: @code{(setq org-agenda-start-day "+10d")} will +start the agenda ten days from today in the future. Remote editing from the agenda buffer means, for example, that you can change the dates of deadlines and appointments from the agenda buffer. @@ -7656,16 +8031,21 @@ commands}. @subsubheading Match syntax @cindex Boolean logic, for tag/property searches -A search string can use Boolean operators @samp{&} for AND and @samp{|} for -OR@. @samp{&} binds more strongly than @samp{|}. Parentheses are currently -not implemented. Each element in the search is either a tag, a regular -expression matching tags, or an expression like @code{PROPERTY OPERATOR -VALUE} with a comparison operator, accessing a property value. Each element -may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic -sugar for positive selection. The AND operator @samp{&} is optional when -@samp{+} or @samp{-} is present. Here are some examples, using only tags. +A search string can use Boolean operators @samp{&} for @code{AND} and +@samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}. +Parentheses are not implemented. Each element in the search is either a +tag, a regular expression matching tags, or an expression like +@code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a +property value. Each element may be preceded by @samp{-}, to select +against it, and @samp{+} is syntactic sugar for positive selection. The +@code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is +present. Here are some examples, using only tags. @table @samp +@item work +Select headlines tagged @samp{:work:}. +@item work&boss +Select headlines tagged @samp{:work:} and @samp{:boss:}. @item +work-boss Select headlines tagged @samp{:work:}, but discard those also tagged @samp{:boss:}. @@ -7682,6 +8062,13 @@ braces. For example, @samp{work+@{^boss.*@}} matches headlines that contain the tag @samp{:work:} and any tag @i{starting} with @samp{boss}. +@cindex group tags, as regular expressions +Group tags (@pxref{Tag groups}) are expanded as regular expressions. E.g., +if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then +searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}} +and searching for @samp{-work} will search for all headlines but those with +one of the tag in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}). + @cindex TODO keyword matching, with tags search @cindex level, require for tags/property match @cindex category, require for tags/property match @@ -7690,16 +8077,20 @@ You may also test for properties (@pxref{Properties and Columns}) at the same time as matching tags. The properties may be real properties, or special properties that represent other metadata (@pxref{Special properties}). For example, the ``property'' @code{TODO} represents the TODO keyword of the -entry. Or, the ``property'' @code{LEVEL} represents the level of an entry. -So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines -that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword -DONE@. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not -count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc. -The ITEM special property cannot currently be used in tags/property +entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of +the entry. The ITEM special property cannot currently be used in tags/property searches@footnote{But @pxref{x-agenda-skip-entry-regexp, ,skipping entries based on regexp}.}. +Except the @pxref{Special properties}, one other ``property'' can also be +used. @code{LEVEL} represents the level of an entry. So a search +@samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines that have +the tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE@. +In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not count +the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc. + Here are more examples: + @table @samp @item work+TODO="WAITING" Select @samp{:work:}-tagged TODO lines with the specific TODO @@ -7732,7 +8123,7 @@ brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are assumed to be date/time specifications in the standard Org way, and the comparison will be done accordingly. Special values that will be recognized are @code{"<now>"} for now (including time), and @code{"<today>"}, and -@code{"<tomorrow>"} for these days at 0:00 hours, i.e., without a time +@code{"<tomorrow>"} for these days at 00:00 hours, i.e., without a time specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year, respectively, can be used. @@ -7899,7 +8290,8 @@ associated with the item. @menu * Categories:: Not all tasks are equal * Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things +* Sorting agenda items:: The order of things +* Filtering/limiting agenda items:: Dynamically narrow the agenda @end menu @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting @@ -7936,7 +8328,7 @@ longer than 10 characters. 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 +@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting @subsection Time-of-day specifications @cindex time-of-day specification @@ -7987,8 +8379,8 @@ The time grid can be turned on and off with the variable @code{org-agenda-use-time-grid}, and can be configured with @code{org-agenda-time-grid}. -@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting -@subsection Sorting of agenda items +@node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting +@subsection Sorting agenda items @cindex sorting, of agenda items @cindex priorities, of agenda items Before being inserted into a view, the items are sorted. How this is @@ -8021,6 +8413,189 @@ Sorting can be customized using the variable @code{org-agenda-sorting-strategy}, and may also include criteria based on the estimated effort of an entry (@pxref{Effort estimates}). +@node Filtering/limiting agenda items, , Sorting agenda items, Presentation and sorting +@subsection Filtering/limiting agenda items + +Agenda built-in or customized commands are statically defined. Agenda +filters and limits provide two ways of dynamically narrowing down the list of +agenda entries: @emph{fitlers} and @emph{limits}. Filters only act on the +display of the items, while limits take effect before the list of agenda +entries is built. Filter are more often used interactively, while limits are +mostly useful when defined as local variables within custom agenda commands. + +@subsubheading Filtering in the agenda +@cindex filtering, by tag, category, top headline and effort, in agenda +@cindex tag filtering, in agenda +@cindex category filtering, in agenda +@cindex top headline filtering, in agenda +@cindex effort filtering, in agenda +@cindex query editing, in agenda + +@table @kbd +@orgcmd{/,org-agenda-filter-by-tag} +@vindex org-agenda-tag-filter-preset +Filter the 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 +binding the variable @code{org-agenda-tag-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. 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; @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 +with prefix arg, remove the entries that @emph{do} have the tag. A second +@kbd{/} at the prompt will turn off the filter and unhide any hidden entries. +If the first key you press is either @kbd{+} or @kbd{-}, the previous filter +will be narrowed by requiring or forbidding the selected additional tag. +Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also +immediately use the @kbd{\} command. + +@vindex org-sort-agenda-noeffort-is-high +In order to filter for effort estimates, you should set up allowed +efforts globally, for example +@lisp +(setq org-global-properties + '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) +@end lisp +You can then filter for an effort by first typing an operator, one of +@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort +estimate in your array of allowed values, where @kbd{0} means the 10th value. +The filter will then restrict to entries with effort smaller-or-equal, equal, +or larger-or-equal than the selected value. If the digits 0--9 are not used +as fast access keys to tags, you can also simply press the index digit +directly without an operator. In this case, @kbd{<} will be assumed. For +application of the operator, entries without a defined effort will be treated +according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter +for tasks without effort definition, press @kbd{?} as the operator. + +Org also supports automatic, context-aware tag filtering. If the variable +@code{org-agenda-auto-exclude-function} is set to a user-defined function, +that function can decide which tags should be excluded from the agenda +automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET} +as a sub-option key and runs the auto exclusion logic. For example, let's +say you use a @code{Net} tag to identify tasks which need network access, an +@code{Errand} tag for errands in town, and a @code{Call} tag for making phone +calls. You could auto-exclude these tags based on the availability of the +Internet, and outside of business hours, with something like this: + +@smalllisp +@group +(defun org-my-auto-exclude-function (tag) + (and (cond + ((string= tag "Net") + (/= 0 (call-process "/sbin/ping" nil nil nil + "-c1" "-q" "-t1" "mail.gnu.org"))) + ((or (string= tag "Errand") (string= tag "Call")) + (let ((hour (nth 2 (decode-time)))) + (or (< hour 8) (> hour 21))))) + (concat "-" tag))) + +(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function) +@end group +@end smalllisp + +@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 @{ +@kindex @} +@item [ ] @{ @} +@table @i +@item @r{in} search view +add new search words (@kbd{[} and @kbd{]}) or new regular expressions +(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will +add a positive search term prefixed by @samp{+}, indicating that this search +term @i{must} occur/match in the entry. The closing bracket/brace will add a +negative search term which @i{must not} occur/match in the entry for it to be +selected. +@end table + +@orgcmd{<,org-agenda-filter-by-category} +@vindex org-agenda-category-filter-preset + +Filter the current agenda view with respect to the category of the item at +point. Pressing @code{<} another time will remove this filter. You can add +a filter preset through the option @code{org-agenda-category-filter-preset} +(see below.) + +@orgcmd{^,org-agenda-filter-by-top-headline} +Filter the current agenda view and only display the siblings and the parent +headline of the one at point. + +@orgcmd{=,org-agenda-filter-by-regexp} +@vindex org-agenda-regexp-filter-preset + +Filter the agenda view by a regular expression: only show agenda entries +matching the regular expression the user entered. When called with a prefix +argument, it will filter @emph{out} entries matching the regexp. With two +universal prefix arguments, it will remove all the regexp filters, which can +be accumulated. You can add a filter preset through the option +@code{org-agenda-category-filter-preset} (see below.) + +@orgcmd{|,org-agenda-filter-remove-all} +Remove all filters in the current agenda view. +@end table + +@subsubheading Setting limits for the agenda +@cindex limits, in agenda +@vindex org-agenda-max-entries +@vindex org-agenda-max-effort +@vindex org-agenda-max-todos +@vindex org-agenda-max-tags + +Here is a list of options that you can set, either globally, or locally in +your custom agenda views@pxref{Custom agenda views}. + +@table @var +@item org-agenda-max-entries +Limit the number of entries. +@item org-agenda-max-effort +Limit the duration of accumulated efforts (as minutes). +@item org-agenda-max-todos +Limit the number of entries with TODO keywords. +@item org-agenda-max-tags +Limit the number of tagged entries. +@end table + +When set to a positive integer, each option will exclude entries from other +categories: for example, @code{(setq org-agenda-max-effort 100)} will limit +the agenda to 100 minutes of effort and exclude any entry that as no effort +property. If you want to include entries with no effort property, use a +negative value for @code{org-agenda-max-effort}. + +One useful setup is to use @code{org-agenda-max-entries} locally in a custom +command. For example, this custom command will display the next five entries +with a @code{NEXT} TODO keyword. + +@smalllisp +(setq org-agenda-custom-commands + '(("n" todo "NEXT" + ((org-agenda-max-entries 5))))) +@end smalllisp + +Once you mark one of these five entry as @code{DONE}, rebuilding the agenda +will again the next five entries again, including the first entry that was +excluded so far. + +You can also dynamically set temporary limits@footnote{Those temporary limits +are lost when rebuilding the agenda.}: + +@table @kbd +@orgcmd{~,org-agenda-limit-interactively} +This prompts for the type of limit to apply and its value. +@end table + @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views @section Commands in the agenda buffer @cindex commands, in agenda buffer @@ -8088,6 +8663,7 @@ Delete other windows. @c @orgcmdkskc{v d,d,org-agenda-day-view} @xorgcmdkskc{v w,w,org-agenda-week-view} +@xorgcmd{v t,org-agenda-fortnight-view} @xorgcmd{v m,org-agenda-month-view} @xorgcmd{v y,org-agenda-year-view} @xorgcmd{v SPC,org-agenda-reset-view} @@ -8134,7 +8710,7 @@ entries that have been clocked on that day. You can configure the entry types that should be included in log mode using the variable @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show all possible logbook entries, including state changes. When called with two -prefix args @kbd{C-u C-u}, show only logging information, nothing else. +prefix arguments @kbd{C-u C-u}, show only logging information, nothing else. @kbd{v L} is equivalent to @kbd{C-u v l}. @c @orgcmdkskc{v [,[,org-agenda-manipulate-query-add} @@ -8152,7 +8728,7 @@ press @kbd{v a} again. @vindex org-agenda-start-with-clockreport-mode @vindex org-clock-report-include-clocking-task 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 +always show a table with the clocked times for the time span 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}. By using a prefix argument @@ -8212,108 +8788,39 @@ Remove the restriction lock on the agenda, if it is currently restricted to a file or subtree (@pxref{Agenda files}). @tsubheading{Secondary filtering and query editing} -@cindex filtering, by tag category and effort, in agenda -@cindex tag filtering, in agenda -@cindex category filtering, in agenda -@cindex effort filtering, in agenda -@cindex query editing, in agenda -@orgcmd{<,org-agenda-filter-by-category} -@vindex org-agenda-category-filter-preset - -Filter the current agenda view with respect to the category of the item at -point. Pressing @code{<} another time will remove this filter. You can add -a filter preset through the option @code{org-agenda-category-filter-preset} -(see below.) +For a detailed description of these commands, see @pxref{Filtering/limiting +agenda items}. @orgcmd{/,org-agenda-filter-by-tag} @vindex org-agenda-tag-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 -binding the variable @code{org-agenda-tag-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. 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.} +Filter the agenda view with respect to a tag and/or effort estimates. -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 -with prefix arg, remove the entries that @emph{do} have the tag. A second -@kbd{/} at the prompt will turn off the filter and unhide any hidden entries. -If the first key you press is either @kbd{+} or @kbd{-}, the previous filter -will be narrowed by requiring or forbidding the selected additional tag. -Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also -immediately use the @kbd{\} command. +@orgcmd{\\,org-agenda-filter-by-tag-refine} +Narrow the current agenda filter by an additional condition. -@vindex org-sort-agenda-noeffort-is-high -In order to filter for effort estimates, you should set up allowed -efforts globally, for example -@lisp -(setq org-global-properties - '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) -@end lisp -You can then filter for an effort by first typing an operator, one of -@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort -estimate in your array of allowed values, where @kbd{0} means the 10th value. -The filter will then restrict to entries with effort smaller-or-equal, equal, -or larger-or-equal than the selected value. If the digits 0--9 are not used -as fast access keys to tags, you can also simply press the index digit -directly without an operator. In this case, @kbd{<} will be assumed. For -application of the operator, entries without a defined effort will be treated -according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter -for tasks without effort definition, press @kbd{?} as the operator. +@orgcmd{<,org-agenda-filter-by-category} +@vindex org-agenda-category-filter-preset -Org also supports automatic, context-aware tag filtering. If the variable -@code{org-agenda-auto-exclude-function} is set to a user-defined function, -that function can decide which tags should be excluded from the agenda -automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET} -as a sub-option key and runs the auto exclusion logic. For example, let's -say you use a @code{Net} tag to identify tasks which need network access, an -@code{Errand} tag for errands in town, and a @code{Call} tag for making phone -calls. You could auto-exclude these tags based on the availability of the -Internet, and outside of business hours, with something like this: +Filter the current agenda view with respect to the category of the item at +point. Pressing @code{<} another time will remove this filter. -@lisp -@group -(defun org-my-auto-exclude-function (tag) - (and (cond - ((string= tag "Net") - (/= 0 (call-process "/sbin/ping" nil nil nil - "-c1" "-q" "-t1" "mail.gnu.org"))) - ((or (string= tag "Errand") (string= tag "Call")) - (let ((hour (nth 2 (decode-time)))) - (or (< hour 8) (> hour 21))))) - (concat "-" tag))) +@orgcmd{^,org-agenda-filter-by-top-headline} +Filter the current agenda view and only display the siblings and the parent +headline of the one at point. -(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function) -@end group -@end lisp +@orgcmd{=,org-agenda-filter-by-regexp} +@vindex org-agenda-regexp-filter-preset -@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. +Filter the agenda view by a regular expression: only show agenda entries +matching the regular expression the user entered. When called with a prefix +argument, it will filter @emph{out} entries matching the regexp. With two +universal prefix arguments, it will remove all the regexp filters, which can +be accumulated. You can add a filter preset through the option +@code{org-agenda-category-filter-preset} (see below.) -@c -@kindex [ -@kindex ] -@kindex @{ -@kindex @} -@item [ ] @{ @} -@table @i -@item @r{in} search view -add new search words (@kbd{[} and @kbd{]}) or new regular expressions -(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will -add a positive search term prefixed by @samp{+}, indicating that this search -term @i{must} occur/match in the entry. The closing bracket/brace will add a -negative search term which @i{must not} occur/match in the entry for it to be -selected. -@end table +@orgcmd{|,org-agenda-filter-remove-all} +Remove all filters in the current agenda view. @tsubheading{Remote editing} @cindex remote editing, from agenda @@ -8440,29 +8947,50 @@ Jump to the running clock in another window. @c @orgcmd{k,org-agenda-capture} Like @code{org-capture}, but use the date at point as the default date for -the capture template. See @var{org-capture-use-agenda-date} to make this +the capture template. See @code{org-capture-use-agenda-date} to make this the default behavior of @code{org-capture}. @cindex capturing, from agenda @vindex org-capture-use-agenda-date +@tsubheading{Dragging agenda lines forward/backward} +@cindex dragging, agenda lines + +@orgcmd{M-<up>,org-agenda-drag-line-backward} +Drag the line at point backward one line@footnote{Moving agenda lines does +not persist after an agenda refresh and does not modify the contributing +@file{.org} files}. With a numeric prefix argument, drag backward by that +many lines. + +@orgcmd{M-<down>,org-agenda-drag-line-forward} +Drag the line at point forward one line. With a numeric prefix argument, +drag forward by that many lines. + @tsubheading{Bulk remote editing selected entries} @cindex remote editing, bulk, from agenda -@vindex org-agenda-bulk-persistent-marks @vindex org-agenda-bulk-custom-functions @orgcmd{m,org-agenda-bulk-mark} -Mark the entry at point for bulk action. With prefix arg, mark that many -successive entries. +Mark the entry at point for bulk action. With numeric prefix argument, mark +that many successive entries. @c -@orgcmd{%,org-agenda-bulk-mark-regexp} -Mark entries matching a regular expression for bulk action. +@orgcmd{*,org-agenda-bulk-mark-all} +Mark all visible agenda entries for bulk action. @c @orgcmd{u,org-agenda-bulk-unmark} -Unmark entry for bulk action. +Unmark entry at point for bulk action. @c @orgcmd{U,org-agenda-bulk-remove-all-marks} Unmark all marked entries for bulk action. @c +@orgcmd{M-m,org-agenda-bulk-toggle} +Toggle mark of the entry at point for bulk action. +@c +@orgcmd{M-*,org-agenda-bulk-toggle-all} +Toggle marks of all visible entries for bulk action. +@c +@orgcmd{%,org-agenda-bulk-mark-regexp} +Mark entries matching a regular expression for bulk action. +@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. The prefix arg to @kbd{B} @@ -8471,40 +8999,55 @@ these special timestamps. By default, marks are removed after the bulk. If you want them to persist, set @code{org-agenda-bulk-persistent-marks} to @code{t} or hit @kbd{p} at the prompt. -@example -* @r{Toggle persistent marks.} -$ @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} - @r{changes the state of all selected entries, bypassing blocking and} - @r{suppressing logging notes (but not timestamps).} -+ @r{Add a tag to all selected entries.} -- @r{Remove a tag from all selected entries.} -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}.} -d @r{Set deadline to a specific date.} -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.} -S @r{Reschedule randomly into the coming N days. N will be prompted for.} - @r{With prefix arg (@kbd{C-u B S}), scatter only across weekdays.} -f @r{Apply a function@footnote{You can also create persistent custom functions through@code{org-agenda-bulk-custom-functions}.} to marked entries.} - @r{For example, the function below sets the CATEGORY property of the} - @r{entries to web.} - @r{(defun set-category ()} - @r{ (interactive "P")} - @r{ (let* ((marker (or (org-get-at-bol 'org-hd-marker)} - @r{ (org-agenda-error)))} - @r{ (buffer (marker-buffer marker)))} - @r{ (with-current-buffer buffer} - @r{ (save-excursion} - @r{ (save-restriction} - @r{ (widen)} - @r{ (goto-char marker)} - @r{ (org-back-to-heading t)} - @r{ (org-set-property "CATEGORY" "web"))))))} -@end example +@table @kbd +@item * +Toggle persistent marks. +@item $ +Archive all selected entries. +@item A +Archive entries by moving them to their respective archive siblings. +@item t +Change TODO state. This prompts for a single TODO keyword and changes the +state of all selected entries, bypassing blocking and suppressing logging +notes (but not timestamps). +@item + +Add a tag to all selected entries. +@item - +Remove a tag from all selected entries. +@item s +Schedule all items to a new date. To shift existing schedule dates by a +fixed number of days, use something starting with double plus at the prompt, +for example @samp{++8d} or @samp{++2w}. +@item d +Set deadline to a specific date. +@item r +Prompt for a single refile target and move all entries. The entries will no +longer be in the agenda; refresh (@kbd{g}) to bring them back. +@item S +Reschedule randomly into the coming N days. N will be prompted for. With +prefix arg (@kbd{C-u B S}), scatter only across weekdays. +@item f +Apply a function@footnote{You can also create persistent custom functions +through @code{org-agenda-bulk-custom-functions}.} to marked entries. For +example, the function below sets the CATEGORY property of the entries to web. +@lisp +@group +(defun set-category () + (interactive "P") + (let* ((marker (or (org-get-at-bol 'org-hd-marker) + (org-agenda-error))) + (buffer (marker-buffer marker))) + (with-current-buffer buffer + (save-excursion + (save-restriction + (widen) + (goto-char marker) + (org-back-to-heading t) + (org-set-property "CATEGORY" "web")))))) +@end group +@end lisp +@end table @tsubheading{Calendar commands} @cindex calendar commands, from agenda @@ -8551,7 +9094,7 @@ calendars. @orgcmd{H,org-agenda-holidays} Show holidays for three months around the cursor date. -@item M-x org-export-icalendar-combine-agenda-files +@item M-x org-icalendar-combine-agenda-files RET Export a single iCalendar file containing entries from all agenda files. This is a globally available command, and also available in the agenda menu. @@ -8561,12 +9104,13 @@ This is a globally available command, and also available in the agenda menu. @cindex agenda views, exporting @vindex org-agenda-exporter-settings Write the agenda view to a file. Depending on the extension of the selected -file name, the view will be exported as HTML (extension @file{.html} or -@file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}), -and plain text (any other extension). When called with a @kbd{C-u} prefix -argument, immediately open the newly created file. Use the variable -@code{org-agenda-exporter-settings} to set options for @file{ps-print} and -for @file{htmlize} to be used during export. +file name, the view will be exported as HTML (@file{.html} or @file{.htm}), +Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text +(any other extension). When exporting to Org, only the body of original +headlines are exported, not subtrees or inherited tags. When called with a +@kbd{C-u} prefix argument, immediately open the newly created file. Use the +variable @code{org-agenda-exporter-settings} to set options for +@file{ps-print} and for @file{htmlize} to be used during export. @tsubheading{Quit and Exit} @orgcmd{q,org-agenda-quit} @@ -8606,6 +9150,8 @@ buffer). @kindex C-c a C @vindex org-agenda-custom-commands @cindex agenda views, main example +@cindex agenda, as an agenda views +@cindex agenda*, as an agenda views @cindex tags, as an agenda view @cindex todo, as an agenda view @cindex tags-todo @@ -8616,13 +9162,15 @@ buffer). Custom commands are configured in the variable @code{org-agenda-custom-commands}. You can customize this variable, for example by pressing @kbd{C-c a C}. You can also directly set it with Emacs -Lisp in @file{.emacs}. The following example contains all valid search -types: +Lisp in @file{.emacs}. The following example contains all valid agenda +views: @lisp @group (setq org-agenda-custom-commands - '(("w" todo "WAITING") + '(("x" agenda) + ("y" agenda*) + ("w" todo "WAITING") ("W" todo-tree "WAITING") ("u" tags "+boss-urgent") ("v" tags-todo "+boss-urgent") @@ -8648,6 +9196,15 @@ expression to be used for the matching. The example above will therefore define: @table @kbd +@item C-c a x +as a global search for agenda entries planned@footnote{@emph{Planned} means +here that these entries have some planning information attached to them, like +a time-stamp, a scheduled or a deadline string. See +@code{org-agenda-entry-types} on how to set what planning information will be +taken into account.} this week/day. +@item C-c a y +as a global search for agenda entries planned this week/day, but only those +with an hour specification like @code{[h]h:mm}---think of them as appointments. @item C-c a w as a global search for TODO entries with @samp{WAITING} as the TODO keyword @@ -8782,23 +9339,23 @@ yourself. @vindex org-agenda-custom-commands-contexts To control whether an agenda command should be accessible from a specific -context, you can customize @var{org-agenda-custom-commands-contexts}. Let's +context, you can customize @code{org-agenda-custom-commands-contexts}. Let's say for example that you have an agenda commands @code{"o"} displaying a view that you only need when reading emails. Then you would configure this option like this: -@example +@lisp (setq org-agenda-custom-commands-contexts '(("o" (in-mode . "message-mode")))) -@end example +@end lisp You can also tell that the command key @code{"o"} should refer to another command key @code{"r"}. In that case, add this command key like this: -@example +@lisp (setq org-agenda-custom-commands-contexts '(("o" "r" (in-mode . "message-mode")))) -@end example +@end lisp See the docstring of the variable for more information. @@ -9009,19 +9566,20 @@ spent (via @code{CLOCKSUM}) and with the planned total effort for it. @chapter Markup for rich export 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, @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. +structure of the document as accurately as possible in the back-end. Since +export targets like HTML, @LaTeX{} 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 * Structural markup elements:: The basic structure as seen by the exporter -* Images and tables:: Tables and Images will be included +* Images and tables:: Images, tables and caption mechanism * 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 +* Macro replacement:: Use macros to create templates * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents +* Special blocks:: Containers targeted at export back-ends @end menu @node Structural markup elements, Images and tables, Markup, Markup @@ -9031,7 +9589,6 @@ summarizes the markup rules used in an Org mode buffer. * Document title:: Where the title is taken from * Headings and sections:: The document structure as seen by the exporter * Table of contents:: The if and where of the table of contents -* Initial text:: Text before the first heading? * Lists:: Lists * Paragraphs:: Paragraphs * Footnote markup:: Footnotes @@ -9053,15 +9610,13 @@ The title of the exported document is taken from the special line @end example @noindent -If this line does not exist, the title is derived from the first non-empty, -non-comment line in the buffer. If no such line exists, or if you have -turned off exporting of the text before the first headline (see below), the -title will be the file name without extension. +If this line does not exist, the title will be the name of the file +associated to buffer, without extension, or the buffer name. @cindex property, EXPORT_TITLE -If you are exporting only a subtree by marking is as the region, the heading -of the subtree will become the title of the document. If the subtree has a -property @code{EXPORT_TITLE}, that will take precedence. +If you are exporting only a subtree, its heading will become the title of the +document. If the subtree has a property @code{EXPORT_TITLE}, that will take +precedence. @node Headings and sections, Table of contents, Document title, Structural markup elements @subheading Headings and sections @@ -9081,58 +9636,55 @@ per-file basis with a line #+OPTIONS: H:4 @end example -@node Table of contents, Initial text, Headings and sections, Structural markup elements +@node Table of contents, Lists, Headings and sections, Structural markup elements @subheading Table of contents @cindex table of contents, markup rules +@cindex #+TOC @vindex org-export-with-toc The table of contents is normally inserted directly before the first headline -of the file. If you would like to get it to a different location, insert the -string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired -location. The depth of the table of contents is by default the same as the -number of headline levels, but you can choose a smaller number, or turn off -the table of contents entirely, by configuring the variable -@code{org-export-with-toc}, or on a per-file basis with a line like +of the file. The depth of the table is by default the same as the number of +headline levels, but you can choose a smaller number, or turn off the table +of contents entirely, by configuring the variable @code{org-export-with-toc}, +or on a per-file basis with a line like @example #+OPTIONS: toc:2 (only to two levels in TOC) -#+OPTIONS: toc:nil (no TOC at all) +#+OPTIONS: toc:nil (no default TOC at all) @end example -@node Initial text, Lists, Table of contents, Structural markup elements -@subheading Text before the first headline -@cindex text before first headline, markup rules -@cindex #+TEXT +If you would like to move the table of contents to a different location, you +should turn off the default table using @code{org-export-with-toc} or +@code{#+OPTIONS} and insert @code{#+TOC: headlines N} at the desired +location(s). -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, @LaTeX{}, or DocBook code, use the special -constructs described below in the sections for the individual exporters. +@example +#+OPTIONS: toc:nil (no default TOC) +... +#+TOC: headlines 2 (insert TOC here, with two headline levels) +@end example -@vindex org-export-skip-text-before-1st-heading -Some people like to use the space before the first headline for setup and -internal links and therefore would like to control the exported text before -the first headline in a different way. You can do so by setting the variable -@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file -basis, you can get the same effect with @samp{#+OPTIONS: skip:t}. - -@noindent -If you still want to have some text before the first headline, use the -@code{#+TEXT} construct: +Multiple @code{#+TOC: headline} lines are allowed. The same @code{TOC} +keyword can also generate a list of all tables (resp.@: all listings) with a +caption in the buffer. @example -#+OPTIONS: skip:t -#+TEXT: This text will go before the *first* headline. -#+TEXT: [TABLE-OF-CONTENTS] -#+TEXT: This goes between the table of contents and the *first* headline +#+TOC: listings (build a list of listings) +#+TOC: tables (build a list of tables) @end example -@node Lists, Paragraphs, Initial text, Structural markup elements +@cindex property, ALT_TITLE +The headline's title usually determines its corresponding entry in a table of +contents. However, it is possible to specify an alternative title by +setting @code{ALT_TITLE} property accordingly. It will then be used when +building the table. + +@node Lists, Paragraphs, Table of contents, Structural markup elements @subheading Lists @cindex lists, markup rules -Plain lists as described in @ref{Plain lists}, are translated to the backend's -syntax for such lists. Most backends support unordered, ordered, and +Plain lists as described in @ref{Plain lists}, are translated to the back-end's +syntax for such lists. Most back-ends support unordered, ordered, and description lists. @node Paragraphs, Footnote markup, Lists, Structural markup elements @@ -9184,7 +9736,7 @@ but not any simpler @cindex @file{footnote.el} Footnotes defined in the way described in @ref{Footnotes}, will be exported -by all backends. Org allows multiple references to the same note, and +by all back-ends. Org allows multiple references to the same note, and multiple footnotes side by side. @node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements @@ -9196,16 +9748,27 @@ multiple footnotes side by side. @cindex verbatim text, markup rules @cindex code text, markup rules @cindex strike-through text, markup rules -You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} -and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text +@vindex org-fontify-emphasized-text +@vindex org-emphasis-regexp-components +@vindex org-emphasis-alist +You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=verbatim=} +and @code{~code~}, 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. + +To turn off fontification for marked up text, you can set +@code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of +available markup syntax, you can customize @code{org-emphasis-alist}. To fine +tune what characters are allowed before and after the markup characters, you +can tweak @code{org-emphasis-regexp-components}. Beware that changing one of +the above variables will no take effect until you reload Org, for which you +may need to restart Emacs. @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements @subheading Horizontal rules @cindex horizontal rules, markup rules A line consisting of only dashes, and at least 5 of them, will be exported as -a horizontal line (@samp{<hr/>} in HTML and @code{\hrule} in @LaTeX{}). +a horizontal line. @node Comment lines, , Horizontal rules, Structural markup elements @subheading Comment lines @@ -9231,45 +9794,48 @@ Toggle the COMMENT keyword at the beginning of an entry. @cindex tables, markup rules @cindex #+CAPTION -@cindex #+LABEL +@cindex #+NAME 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, and in the text you can refer to -the object with @code{\ref@{tab:basic-data@}}: +the object with @code{[[tab:basic-data]]} (@pxref{Internal links}): @example #+CAPTION: This is the caption for the next table (or link) -#+LABEL: tab:basic-data +#+NAME: tab:basic-data | ... | ...| |-----|----| @end example Optionally, the caption can take the form: @example -#+CAPTION: [Caption for list of figures]@{Caption for table (or link).@} +#+CAPTION[Caption for list of tables]: Caption for table. @end example @cindex inlined images, markup rules -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, make sure that the link is on a line by itself and precede -it with @code{#+CAPTION} and @code{#+LABEL} as follows: +Some back-ends 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, make sure that the link is on a line by itself and precede it +with @code{#+CAPTION} and @code{#+NAME} as follows: @example #+CAPTION: This is the caption for the next figure link (or table) -#+LABEL: fig:SED-HR4049 +#+NAME: fig:SED-HR4049 [[./img/a.jpg]] @end example -You may also define additional attributes for the figure. As this is -backend-specific, see the sections about the individual backends for more -information. +@noindent +Such images can be displayed within the buffer. @xref{Handling links,the +discussion of image links}. -@xref{Handling links,the discussion of image links}. +Even though images and tables are prominent examples of captioned structures, +the same caption mechanism can apply to many others (e.g., @LaTeX{} +equations, source code blocks). Depending on the export back-end, those may +or may not be handled. @node Literal examples, Include files, Images and tables, Markup @section Literal examples @@ -9302,11 +9868,11 @@ Here is an example 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{This works automatically for -the HTML backend (it requires version 1.34 of the @file{htmlize.el} package, +the HTML back-end (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. Refer to -@code{org-export-latex-listings} documentation for details.}. This is done +@code{org-latex-listings} documentation for 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@footnote{Code in @samp{src} blocks may also be evaluated either interactively or on export. @@ -9344,7 +9910,7 @@ Here is an example: @example #+BEGIN_SRC emacs-lisp -n -r (save-excursion (ref:sc) - (goto-char (point-min)) (ref:jump) + (goto-char (point-min))) (ref:jump) #+END_SRC In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] jumps to point-min. @@ -9398,20 +9964,23 @@ include your @file{.emacs} file, you could use: @example #+INCLUDE: "~/.emacs" src emacs-lisp @end example + @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 -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, @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 +The optional second and third parameter are the markup (i.e., @samp{example} +or @samp{src}), and, if the markup is @samp{src}, the language for formatting +the contents. The markup is optional; if it is not given, the text will be +assumed to be in Org mode format and will be processed normally. + +Contents of the included file will belong to the same structure (headline, +item) containing the @code{INCLUDE} keyword. In particular, headlines within +the file will become children of the current section. That behavior can be +changed by providing an additional keyword parameter, @code{:minlevel}. In +that case, all headlines in the included file will be shifted so the one with +the lowest level reaches that specified level. For example, to make a file +become a sibling of the current top-level headline, use @example -#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " " +#+INCLUDE: "~/my-book/chapter2.org" :minlevel 1 @end example You can also include a portion of a file by specifying a lines range using @@ -9460,21 +10029,24 @@ You can define text snippets with #+MACRO: name replacement text $1, $2 are arguments @end example -@noindent which can be referenced anywhere in the document (even in -code examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}. In addition to -defined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., -will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and -similar lines. Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and +@noindent which can be referenced in +paragraphs, verse blocks, table cells and some keywords with +@code{@{@{@{name(arg1,arg2)@}@}@}}@footnote{Since commas separate arguments, +commas within arguments have to be escaped with a backslash character. +Conversely, backslash characters before a comma, and only them, need to be +escaped with another backslash character.}. In addition to defined macros, +@code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., will reference +information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and similar lines. +Also, @code{@{@{@{time(@var{FORMAT})@}@}@}} and @code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time and to the modification time of the file being exported, respectively. @var{FORMAT} should be a format string understood by @code{format-time-string}. -Macro expansion takes place during export, and some people use it to -construct complex HTML code. +Macro expansion takes place during export. -@node Embedded @LaTeX{}, , Macro replacement, Markup +@node Embedded @LaTeX{}, Special blocks, Macro replacement, Markup @section Embedded @LaTeX{} @cindex @TeX{} interpretation @cindex @LaTeX{} interpretation @@ -9487,7 +10059,7 @@ Donald E. Knuth's @TeX{} system. Many of the features described here as 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. +readily processed to produce pretty output for a number of export back-ends. @menu * Special symbols:: Greek letters and other symbols @@ -9506,11 +10078,11 @@ readily processed to produce pretty output for a number of export backends. @cindex HTML entities @cindex @LaTeX{} entities -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, +You can use @LaTeX{}-like syntax to insert special symbols like @samp{\alpha} +to indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion +for these symbols is available, just type @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{} -code, Org mode allows these macros to be present without surrounding math +code, Org mode allows these symbols to be present without surrounding math delimiters, for example: @example @@ -9519,7 +10091,7 @@ Angles are written as Greek letters \alpha, \beta and \gamma. @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 +the exporter back-end. Strings like @code{\alpha} will be exported as @code{α} in the HTML output, and as @code{$\alpha$} in the @LaTeX{} output. Similarly, @code{\nbsp} will become @code{ } in HTML and @code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it @@ -9531,12 +10103,13 @@ A large number of entities is provided, with names taken from both HTML 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 +If you would like to see entities displayed as UTF-8 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 +@cindex @code{entitiespretty}, STARTUP keyword @kindex C-c C-x \ @item C-c C-x \ Toggle display of entities as UTF-8 characters. This does not change the @@ -9549,31 +10122,23 @@ for display purposes only. @cindex subscript @cindex superscript -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 +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 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 -@vindex org-export-with-sub-superscripts -To avoid interpretation as raised or lowered text, you can quote @samp{^} and -@samp{_} with a backslash: @samp{\^} and @samp{\_}. If you write a text -where the underscore is often used in a different context, Org's convention -to always interpret these as subscripts can get in your way. Configure the -variable @code{org-export-with-sub-superscripts} to globally change this -convention, or use, on a per-file basis: - -@example -#+OPTIONS: ^:@{@} -@end example - -@noindent With this setting, @samp{a_b} will not be interpreted as a -subscript, but @samp{a_@{b@}} will. +@vindex org-use-sub-superscripts +If you write a text where the underscore is often used in a different +context, Org's convention to always interpret these as subscripts can get in +your way. Configure the variable @code{org-use-sub-superscripts} to change +this convention. For example, when setting this variable to @code{@{@}}, +@samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will. @table @kbd @kindex C-c C-x \ @@ -9589,31 +10154,31 @@ format sub- and superscripts in a WYSIWYM way. @vindex org-format-latex-header 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{}, +to process these for several export back-ends. 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 or the @file{convert}, respectively available -at @url{http://sourceforge.net/projects/dvipng/} and from the -@file{imagemagick} suite. 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. +@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 or the +@file{convert}, respectively available at +@url{http://sourceforge.net/projects/dvipng/} and from the @file{imagemagick} +suite. 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. @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@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. +environments recognized by @file{MathJax} will be processed. When +@file{dvipng} program or @file{imagemagick} suite is used to create images, +any @LaTeX{} environment will be handled.}. The only requirement is that the +@code{\begin} and @code{\end} statements appear on a new line, at the +beginning of the line or after whitespaces only. @item Text within the usual @LaTeX{} math delimiters. To avoid conflicts with currency specifications, single @samp{$} characters are only recognized as @@ -9627,40 +10192,44 @@ For the other delimiters, there is no such restriction, so when in doubt, use @noindent For example: @example -\begin@{equation@} % arbitrary environments, -x=\sqrt@{b@} % even tables, figures -\end@{equation@} % etc +\begin@{equation@} +x=\sqrt@{b@} +\end@{equation@} If $a^2=b$ and \( b=2 \), then the solution must be either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. @end example -@noindent -@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 @LaTeX{} converter. +@c FIXME +@c @noindent +@c @vindex org-format-latex-options +@c If you need any of the delimiter ASCII sequences for other purposes, you +@c can configure the option @code{org-format-latex-options} to deselect the +@c ones you do not wish to have interpreted by the @LaTeX{} converter. -@vindex org-export-with-LaTeX-fragments +@vindex org-export-with-latex @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: +@code{org-export-with-latex}. The default setting is @code{t} which means +@file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} back-ends. +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} +#+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)} +#+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all} +#+OPTIONS: tex: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 -If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to -produce preview images of the typeset expressions: +@vindex org-latex-create-formula-image-program +If you have @file{dvipng} or @file{imagemagick} installed@footnote{Choose the +converter by setting the variable +@code{org-latex-create-formula-image-program} accordingly.}, @LaTeX{} +fragments can be processed to produce preview images of the typeset +expressions: @table @kbd @kindex C-c C-x C-l @@ -9682,6 +10251,19 @@ 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. +@vindex org-startup-with-latex-preview +You can turn on the previewing of all @LaTeX{} fragments in a file with + +@example +#+STARTUP: latexpreview +@end example + +To disable it, simply use + +@example +#+STARTUP: nolatexpreview +@end example + @node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{} @subsection Using CD@LaTeX{} to enter math @cindex CD@LaTeX{} @@ -9694,7 +10276,7 @@ some of the features of CD@LaTeX{} mode. You need to install AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. Don't use CD@LaTeX{} 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 +on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all Org files with @lisp @@ -9719,7 +10301,7 @@ the second brace. Even outside fragments, @key{TAB} will expand environment abbreviations at the beginning of a line. For example, if you write @samp{equ} at the beginning of a line and press @key{TAB}, this abbreviation will be expanded to an @code{equation} environment. -To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. +To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}. @item @kindex _ @kindex ^ @@ -9731,247 +10313,420 @@ macro, they are removed again (depending on the variable @code{cdlatex-simplify-sub-super-scripts}). @item @kindex ` -Pressing the backquote @kbd{`} followed by a character inserts math +Pressing the grave accent @kbd{`} followed by a character inserts math macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds -after the backquote, a help window will pop up. +after the grave accent, a help window will pop up. @item @kindex ' -Pressing the single-quote @kbd{'} followed by another character modifies +Pressing the apostrophe @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 single-quote, a help window will pop up. Character +1.5 seconds after the apostrophe, a help window will pop up. Character modification will work only inside @LaTeX{} fragments; outside the quote is normal. @end itemize +@node Special blocks, , Embedded @LaTeX{}, Markup +@section Special blocks +@cindex Special blocks + +Org syntax includes pre-defined blocks (@pxref{Paragraphs} and @ref{Literal +examples}). It is also possible to create blocks containing raw code +targeted at a specific back-ends (e.g., @samp{#+BEGIN_LATEX}). + +Any other block is a @emph{special block}. + +For example, @samp{#+BEGIN_ABSTRACT} and @samp{#+BEGIN_VIDEO} are special +blocks. The first one is useful when exporting to @LaTeX{}, the second one +when exporting to HTML5. + +Each export back-end decides if they should be exported, and how. When the +block is ignored, its contents are still exported, as if the opening and +closing block lines were not there. For example, when exporting a +@samp{#+BEGIN_TEST} block, HTML back-end wraps its contents within a +@samp{<div name="test">} tag. + +Refer to back-end specific documentation for more information. + @node Exporting, Publishing, Markup, Top @chapter Exporting @cindex exporting -Org mode documents can be exported into a variety of other formats. For -printing and sharing of notes, ASCII export produces a readable and simple -version of an Org file. HTML export allows you to publish a notes file on -the web, while the XOXO format provides a solid base for exchange with a -broad range of other applications. @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. OpenDocument Text (ODT) export allows seamless -collaboration across organizational boundaries. 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). +The Org mode export facilities can be used to export Org documents or parts +of Org documents to a variety of other formats. In addition, these +facilities can be used with @code{orgtbl-mode} and/or @code{orgstruct-mode} +in foreign buffers so you can author tables and lists in Org syntax and +convert them in place to the target language. + +ASCII export produces a readable and simple version of an Org file for +printing and sharing notes. HTML export allows you to easily publish notes +on the web, or to build full-fledged websites. @LaTeX{} export lets you use +Org mode and its structured editing functions to create arbitrarily complex +@LaTeX{} files for any kind of document. OpenDocument Text (ODT) export +allows seamless collaboration across organizational boundaries. Markdown +export lets you seamlessly collaborate with other developers. Finally, iCal +export can extract entries with deadlines or appointments to produce a file +in the iCalendar format. @menu -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands +* The Export Dispatcher:: The main exporter interface +* Export back-ends:: Built-in export formats +* Export settings:: Generic export settings * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* Beamer export:: Exporting as a Beamer presentation * HTML export:: Exporting to HTML * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF -* DocBook export:: Exporting to DocBook +* Markdown export:: Exporting to Markdown * OpenDocument Text export:: Exporting to OpenDocument Text -* TaskJuggler export:: Exporting to TaskJuggler -* Freemind export:: Exporting to Freemind mind maps -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format +* Org export:: Exporting to Org +* Texinfo export:: Exporting to Texinfo +* iCalendar export:: Exporting to iCalendar +* Other built-in back-ends:: Exporting to a man page +* Export in foreign buffers:: Author tables and lists in Org syntax +* Advanced configuration:: Fine-tuning the export output @end menu -@node Selective export, Export options, Exporting, Exporting -@section Selective export -@cindex export, selective by tags or TODO keyword +@node The Export Dispatcher, Export back-ends, Exporting, Exporting +@section The Export Dispatcher +@vindex org-export-dispatch-use-expert-ui +@cindex Export, dispatcher + +The main entry point for export related tasks is the dispatcher, a +hierarchical menu from which it is possible to select an export format and +toggle export options@footnote{It is also possible to use a less intrusive +interface by setting @code{org-export-dispatch-use-expert-ui} to a +non-@code{nil} value. In that case, only a prompt is visible from the +minibuffer. From there one can still switch back to regular menu by pressing +@key{?}.} from which it is possible to select an export format and to toggle +export options. + +@c @quotation +@table @asis +@orgcmd{C-c C-e,org-export-dispatch} -@vindex org-export-select-tags -@vindex org-export-exclude-tags -@cindex org-export-with-tasks -You may use tags to select the parts of a document that should be exported, -or to exclude parts from export. This behavior is governed by two variables: -@code{org-export-select-tags} and @code{org-export-exclude-tags}, -respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}. +Dispatch for export and publishing commands. When called with a @kbd{C-u} +prefix argument, repeat the last export command on the current buffer while +preserving toggled options. If the current buffer hasn't changed and subtree +export was activated, the command will affect that same subtree. +@end table +@c @end quotation -@enumerate -@item -Org first checks if any of the @emph{select} tags is present in the -buffer. If yes, all trees that do not carry one of these tags will be -excluded. If a selected tree is a subtree, the heading hierarchy above it -will also be selected for export, but not the text below those headings. +Normally the entire buffer is exported, but if there is an active region +only that part of the buffer will be exported. -@item -If none of the select tags is found, the whole buffer will be selected for -export. +Several export options (@pxref{Export settings}) can be toggled from the +export dispatcher with the following key combinations: -@item -Finally, all subtrees that are marked by any of the @emph{exclude} tags will -be removed from the export buffer. -@end enumerate +@table @kbd +@item C-a +@vindex org-export-async-init-file +Toggle asynchronous export. Asynchronous export uses an external Emacs +process that is configured with a specified initialization file. -The variable @code{org-export-with-tasks} can be configured to select which -kind of tasks should be included for export. See the docstring of the -variable for more information. +While exporting asynchronously, the output is not displayed, but stored in +a place called ``the export stack''. This stack can be displayed by calling +the dispatcher with a double @kbd{C-u} prefix argument, or with @kbd{&} key +from the dispatcher menu. -@node Export options, The export dispatcher, Selective export, Exporting -@section Export options -@cindex options, for export +@vindex org-export-in-background +To make this behavior the default, customize the variable +@code{org-export-in-background}. -@cindex completion, of option keywords -The exporter recognizes special lines in the buffer which provide -additional information. These lines may be put anywhere in the file. -The whole set of lines can be inserted into the buffer with @kbd{C-c -C-e t}. For individual lines, a good way to make sure the keyword is -correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion -(@pxref{Completion}). For a summary of other in-buffer settings not -specifically related to export, see @ref{In-buffer settings}. -In particular, note that you can place commonly-used (export) options in -a separate file which can be included using @code{#+SETUPFILE}. +@item C-b +Toggle body-only export. Its effect depends on the back-end used. +Typically, if the back-end has a header section (like @code{<head>...</head>} +in the HTML back-end), a body-only export will not include this header. + +@item C-s +@vindex org-export-initial-scope +Toggle subtree export. The top heading becomes the document title. + +You can change the default state of this option by setting +@code{org-export-initial-scope}. + +@item C-v +Toggle visible-only export. Only export the text that is currently +visible, i.e., not hidden by outline visibility in the buffer. -@table @kbd -@orgcmd{C-c C-e t,org-insert-export-options-template} -Insert template with export options, see example below. @end table -@cindex #+TITLE -@cindex #+AUTHOR -@cindex #+DATE -@cindex #+EMAIL -@cindex #+DESCRIPTION -@cindex #+KEYWORDS -@cindex #+LANGUAGE -@cindex #+TEXT -@cindex #+OPTIONS -@cindex #+BIND -@cindex #+LINK_UP -@cindex #+LINK_HOME -@cindex #+EXPORT_SELECT_TAGS -@cindex #+EXPORT_EXCLUDE_TAGS -@cindex #+XSLT -@cindex #+LaTeX_HEADER +@vindex org-export-copy-to-kill-ring +With the exception of asynchronous export, a successful export process writes +its output to the kill-ring. You can configure this behavior by altering the +option @code{org-export-copy-to-kill-ring}. + +@node Export back-ends, Export settings, The Export Dispatcher, Exporting +@section Export back-ends +@cindex Export, back-ends + +An export back-end is a library that translates Org syntax into a foreign +format. An export format is not available until the proper back-end has been +loaded. + +@vindex org-export-backends +By default, the following four back-ends are loaded: @code{ascii}, +@code{html}, @code{icalendar} and @code{latex}. It is possible to add more +(or remove some) by customizing @code{org-export-backends}. + +Built-in back-ends include: + +@itemize +@item ascii (ASCII format) +@item beamer (@LaTeX{} Beamer format) +@item html (HTML format) +@item icalendar (iCalendar format) +@item latex (@LaTeX{} format) +@item man (Man page format) +@item md (Markdown format) +@item odt (OpenDocument Text format) +@item org (Org format) +@item texinfo (Texinfo format) +@end itemize + +Other back-ends might be found in the @code{contrib/} directory +(@pxref{Installation}). + +@node Export settings, ASCII/Latin-1/UTF-8 export, Export back-ends, Exporting +@section Export settings +@cindex Export, settings + +Export options can be set: globally with variables; for an individual file by +making variables buffer-local with in-buffer settings (@pxref{In-buffer +settings}), by setting individual keywords, or by specifying them in a +compact form with the @code{#+OPTIONS} keyword; or for a tree by setting +properties (@pxref{Properties and Columns}). Options set at a specific level +override options set at a more general level. + +@cindex #+SETUPFILE +In-buffer settings may appear anywhere in the file, either directly or +indirectly through a file included using @samp{#+SETUPFILE: filename} syntax. +Option keyword sets tailored to a particular back-end can be inserted from +the export dispatcher (@pxref{The Export Dispatcher}) using the @code{Insert +template} command by pressing @key{#}. To insert keywords individually, +a good way to make sure the keyword is correct is to type @code{#+} and then +to use @kbd{M-<TAB>} for completion. + +The export keywords available for every back-end, and their equivalent global +variables, include: + +@table @samp +@item AUTHOR @vindex user-full-name +The document author (@code{user-full-name}). + +@item CREATOR +@vindex org-export-creator-string +Entity responsible for output generation (@code{org-export-creator-string}). + +@item DATE +@vindex org-export-date-timestamp-format +A date or a time-stamp@footnote{The variable +@code{org-export-date-timestamp-format} defines how this time-stamp will be +exported.}. + +@item DESCRIPTION +The document description. Back-ends handle it as they see fit (e.g., for the +XHTML meta tag), if at all. You can use several such keywords for long +descriptions. + +@item EMAIL @vindex user-mail-address +The email address (@code{user-mail-address}). + +@item KEYWORDS +The keywords defining the contents of the document. Back-ends handle it as +they see fit (e.g., for the XHTML meta tag), if at all. You can use several +such keywords if the list is long. + +@item LANGUAGE @vindex org-export-default-language -@vindex org-export-date-timestamp-format -@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, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, 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 -#+LANGUAGE: language for HTML, e.g., @samp{en} (@code{org-export-default-language}) -#+TEXT: Some descriptive text to be inserted at the beginning. -#+TEXT: Several lines may be given. -#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... -#+BIND: lisp-var lisp-val, e.g., @code{org-export-latex-low-levels itemize} - @r{You need to confirm using these, or configure @code{org-export-allow-BIND}} -#+LINK_UP: the ``up'' link of an exported page -#+LINK_HOME: the ``home'' link of an exported page -#+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 +The language used for translating some strings +(@code{org-export-default-language}). E.g., @samp{#+LANGUAGE: fr} will tell +Org to translate @emph{File} (english) into @emph{Fichier} (french) in the +clocktable. -@noindent -The @code{#+OPTIONS} line is a compact@footnote{If you want to configure many options -this way, you can use several @code{#+OPTIONS} lines.} form to specify export -settings. Here you can: -@cindex headline levels -@cindex section-numbers -@cindex table of contents -@cindex line-break preservation -@cindex quoted HTML tags -@cindex fixed-width sections -@cindex tables -@cindex @TeX{}-like syntax for sub- and superscripts -@cindex footnotes -@cindex special strings -@cindex emphasized text -@cindex @TeX{} macros -@cindex @LaTeX{} fragments -@cindex author info, in export -@cindex time info, in export -@vindex org-export-plist-vars -@vindex org-export-author-info -@vindex org-export-creator-info -@vindex org-export-email-info +@item SELECT_TAGS +@vindex org-export-select-tags +The tags that select a tree for export (@code{org-export-select-tags}). The +default value is @code{:export:}. Within a subtree tagged with +@code{:export:}, you can still exclude entries with @code{:noexport:} (see +below). When headlines are selectively exported with @code{:export:} +anywhere in a file, text before the first headline is ignored. + +@item EXCLUDE_TAGS +The tags that exclude a tree from export (@code{org-export-exclude-tags}). +The default value is @code{:noexport:}. Entries with the @code{:noexport:} +tag will be unconditionally excluded from the export, even if they have an +@code{:export:} tag. + +@item TITLE +The title to be shown (otherwise derived from buffer's name). You can use +several such keywords for long titles. +@end table + +The @code{#+OPTIONS} keyword is a compact@footnote{If you want to configure +many options this way, you can use several @code{#+OPTIONS} lines.} form that +recognizes the following arguments: + +@table @code +@item ': +@vindex org-export-with-smart-quotes +Toggle smart quotes (@code{org-export-with-smart-quotes}). + +@item *: +Toggle emphasized text (@code{org-export-with-emphasize}). + +@item -: +@vindex org-export-with-special-strings +Toggle conversion of special strings +(@code{org-export-with-special-strings}). + +@item :: +@vindex org-export-with-fixed-width +Toggle fixed-width sections +(@code{org-export-with-fixed-width}). + +@item <: +@vindex org-export-with-timestamps +Toggle inclusion of any time/date active/inactive stamps +(@code{org-export-with-timestamps}). + +@item : +@vindex org-export-preserve-breaks +Toggle line-break-preservation (@code{org-export-preserve-breaks}). + +@item ^: +@vindex org-export-with-sub-superscripts +Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}", +@samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as +it is (@code{org-export-with-sub-superscripts}). + +@item arch: +@vindex org-export-with-archived-trees +Configure export of archived trees. Can be set to @code{headline} to only +process the headline, skipping its contents +(@code{org-export-with-archived-trees}). + +@item author: +@vindex org-export-with-author +Toggle inclusion of author name into exported file +(@code{org-export-with-author}). + +@item c: +@vindex org-export-with-clocks +Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}). + +@item creator: +@vindex org-export-with-creator +Configure inclusion of creator info into exported file. It may be set to +@code{comment} (@code{org-export-with-creator}). + +@item d: +@vindex org-export-with-drawers +Toggle inclusion of drawers, or list drawers to include +(@code{org-export-with-drawers}). + +@item e: +@vindex org-export-with-entities +Toggle inclusion of entities (@code{org-export-with-entities}). + +@item email: +@vindex org-export-with-email +Toggle inclusion of the author's e-mail into exported file +(@code{org-export-with-email}). + +@item f: +@vindex org-export-with-footnotes +Toggle the inclusion of footnotes (@code{org-export-with-footnotes}). + +@item H: +@vindex org-export-headline-levels +Set the number of headline levels for export +(@code{org-export-headline-levels}). Below that level, headlines are treated +differently. In most back-ends, they become list items. + +@item inline: +@vindex org-export-with-inlinetasks +Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}). + +@item num: +@vindex org-export-with-section-numbers +Toggle section-numbers (@code{org-export-with-section-numbers}). It can also +be set to a number @samp{n}, so only headlines at that level or above will be +numbered. + +@item p: +@vindex org-export-with-planning +Toggle export of planning information (@code{org-export-with-planning}). +``Planning information'' is the line containing the @code{SCHEDULED:}, the +@code{DEADLINE:} or the @code{CLOSED:} cookies or a combination of them. + +@item pri: +@vindex org-export-with-priority +Toggle inclusion of priority cookies (@code{org-export-with-priority}). + +@item stat: +@vindex org-export-with-statistics-cookies +Toggle inclusion of statistics cookies +(@code{org-export-with-statistics-cookies}). + +@item tags: +@vindex org-export-with-tags +Toggle inclusion of tags, may also be @code{not-in-toc} +(@code{org-export-with-tags}). + +@item tasks: +@vindex org-export-with-tasks +Toggle inclusion of tasks (TODO items), can be @code{nil} to remove all +tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep +(@code{org-export-with-tasks}). + +@item tex: +@vindex org-export-with-latex +Configure export of @LaTeX{} fragments and environments. It may be set to +@code{verbatim} (@code{org-export-with-latex}). + +@item timestamp: @vindex org-export-time-stamp-file -@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 (DOES NOT WORK)} -@@: @r{turn on/off quoted HTML tags} -:: @r{turn on/off fixed-width sections} -|: @r{turn on/off tables} -^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} - @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} - @r{the simple @code{a_b} will be left as it is.} --: @r{turn on/off conversion of special strings.} -f: @r{turn on/off footnotes like this[1].} -todo: @r{turn on/off inclusion of TODO keywords into exported text} -tasks: @r{turn on/off inclusion of tasks (TODO items), can be nil to remove} - @r{all tasks, @code{todo} to remove DONE tasks, or list of kwds to keep} -pri: @r{turn on/off priority cookies} -tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}} -<: @r{turn on/off inclusion of any time/date stamps like DEADLINES} -*: @r{turn on/off emphasized text (bold, italic, underlined)} -TeX: @r{turn on/off simple @TeX{} macros in plain text} -LaTeX: @r{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, or list drawers to include} -@end example -@noindent -These options take effect in both the HTML and @LaTeX{} export, except for -@code{TeX} and @code{LaTeX} options, 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 -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/Latin-1/UTF-8 export, Export options, Exporting -@section The export dispatcher -@cindex dispatcher, for export commands - -All export commands can be reached using the export dispatcher, which is a -prefix key that prompts for an additional key specifying the command. -Normally the entire file is exported, but if there is an active region that -contains one outline tree, the first heading is used as document title and -the subtrees are exported. +Toggle inclusion of the creation time into exported file +(@code{org-export-time-stamp-file}). -@table @kbd -@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 -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}.}. -@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). -@orgcmd{C-u C-u C-c C-e,org-export} -@vindex org-export-run-in-background -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. +@item toc: +@vindex org-export-with-toc +Toggle inclusion of the table of contents, or set the level limit +(@code{org-export-with-toc}). + +@item todo: +@vindex org-export-with-todo-keywords +Toggle inclusion of TODO keywords into exported text +(@code{org-export-with-todo-keywords}). + +@item |: +@vindex org-export-with-tables +Toggle inclusion of tables (@code{org-export-with-tables}). @end table -@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting +When exporting only a subtree, each of the previous keywords@footnote{With +the exception of @samp{SETUPFILE}.} can be overridden locally by special node +properties. These begin with @samp{EXPORT_}, followed by the name of the +keyword they supplant. For example, @samp{DATE} and @samp{OPTIONS} keywords +become, respectively, @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS} +properties. + +@cindex #+BIND +@vindex org-export-allow-bind-keywords +If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables +can become buffer-local during export by using the BIND keyword. Its syntax +is @samp{#+BIND: variable value}. This is particularly useful for in-buffer +settings that cannot be changed using specific keywords. + +@cindex property, EXPORT_FILE_NAME +The name of the output file to be generated is taken from the file associated +to the buffer, when possible, or asked to you otherwise. For subtree export, +you can also set @samp{EXPORT_FILE_NAME} property. In all cases, only the +base name of the file is retained, and a back-end specific extension is +added. + +@node ASCII/Latin-1/UTF-8 export, Beamer export, Export settings, Exporting @section ASCII/Latin-1/UTF-8 export @cindex ASCII export @cindex Latin-1 export @@ -9981,67 +10736,287 @@ ASCII export produces a simple and very readable version of an Org mode 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 +@vindex org-ascii-links-to-notes +Links are 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-ascii-links-to-notes} for details and other options. + +@subheading ASCII export commands + @table @kbd -@orgcmd{C-c C-e a,org-export-as-ascii} -@cindex property, EXPORT_FILE_NAME +@orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii} Export as an ASCII file. For an Org file, @file{myfile.org}, the ASCII file -will be @file{myfile.txt}. The file will be overwritten without -warning. If there is an active region@footnote{This requires -@code{transient-mark-mode} be turned on.}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will -become the document title. If the tree head entry has or inherits an -@code{EXPORT_FILE_NAME} property, that name will be used for the -export. -@orgcmd{C-c C-e A,org-export-as-ascii-to-buffer} +will be @file{myfile.txt}. The file will be overwritten without warning. +When the original file is @file{myfile.txt}, the resulting file becomes +@file{myfile.txt.txt} in order to prevent data loss. +@orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii} 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 -@cindex headline levels, for exporting -In the exported version, the first 3 outline levels will become -headlines, defining a general document structure. Additional levels -will be exported as itemized lists. If you want that transition to occur -at a different level, specify it with a prefix argument. For example, +@subheading Header and sectioning structure +In the exported version, the first three outline levels become headlines, +defining a general document structure. Additional levels are exported as +lists. The transition can also occur at a different level (@pxref{Export +settings}). + +@subheading Quoting ASCII text + +You can insert text that will only appear when using @code{ASCII} back-end +with the following constructs: + +@cindex #+ASCII +@cindex #+BEGIN_ASCII @example -@kbd{C-1 C-c C-e a} +Text @@@@ascii:and additional text@@@@ within a paragraph. + +#+ASCII: Some text + +#+BEGIN_ASCII +All lines in this block will appear only when using this back-end. +#+END_ASCII @end example -@noindent -creates only top level headlines and exports the rest as items. When -headlines are converted to items, the indentation of the text following -the headline is changed to fit nicely under the item. This is done with -the assumption that the first body line indicates the base indentation of -the body text. Any indentation larger than this is adjusted to preserve -the layout relative to the first line. Should there be lines with less -indentation than the first one, these are left alone. - -@vindex org-export-ascii-links-to-notes -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/Latin-1/UTF-8 export, Exporting +@subheading ASCII specific attributes +@cindex #+ATTR_ASCII +@cindex horizontal rules, in ASCII export + +@code{ASCII} back-end only understands one attribute, @code{:width}, which +specifies the length, in characters, of a given horizontal rule. It must be +specified using an @code{ATTR_ASCII} line, directly preceding the rule. + +@example +#+ATTR_ASCII: :width 10 +----- +@end example + +@node Beamer export, HTML export, ASCII/Latin-1/UTF-8 export, Exporting +@section Beamer export +@cindex Beamer export + +The @LaTeX{} class @emph{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 Beamer presentation. + +@subheading Beamer export commands + +@table @kbd +@orgcmd{C-c C-e l b,org-beamer-export-to-latex} +Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{} +file will be @file{myfile.tex}. The file will be overwritten without +warning. +@orgcmd{C-c C-e l B,org-beamer-export-as-latex} +Export to a temporary buffer. Do not create a file. +@orgcmd{C-c C-e l P,org-beamer-export-to-pdf} +Export as @LaTeX{} and then process to PDF. +@item C-c C-e l O +Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. +@end table + +@subheading Sectioning, Frames and Blocks + +Any tree with not-too-deep level nesting should in principle be exportable as +a Beamer presentation. Headlines fall into three categories: sectioning +elements, frames and blocks. + +@itemize @minus +@item +@vindex org-beamer-frame-level +Headlines become frames when their level is equal to +@code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line +(@pxref{Export settings}). + +@cindex property, BEAMER_ENV +Though, if a headline in the current tree has a @code{BEAMER_ENV} property +set to either to @code{frame} or @code{fullframe}, its level overrides the +variable. A @code{fullframe} is a frame with an empty (ignored) title. + +@item +@vindex org-beamer-environments-default +@vindex org-beamer-environments-extra +All frame's children become @code{block} environments. Special block types +can be enforced by setting headline's @code{BEAMER_ENV} property@footnote{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.} to an appropriate value (see @code{org-beamer-environments-default} for +supported values and @code{org-beamer-environments-extra} for adding more). + +@item +@cindex property, BEAMER_REF +As a special case, if the @code{BEAMER_ENV} property is set to either +@code{appendix}, @code{note}, @code{noteNH} or @code{againframe}, the +headline will become, respectively, an appendix, a note (within frame or +between frame, depending on its level), a note with its title ignored or an +@code{\againframe} command. In the latter case, a @code{BEAMER_REF} property +is mandatory in order to refer to the frame being resumed, and contents are +ignored. + +Also, a headline with an @code{ignoreheading} environment will have its +contents only inserted in the output. This special value is useful to have +data between frames, or to properly close a @code{column} environment. +@end itemize + +@cindex property, BEAMER_ACT +@cindex property, BEAMER_OPT +Headlines also support @code{BEAMER_ACT} and @code{BEAMER_OPT} properties. +The former is translated as an overlay/action specification, or a default +overlay specification when enclosed within square brackets. The latter +specifies options@footnote{The @code{fragile} option is added automatically +if it contains code that requires a verbatim environment, though.} for the +current frame or block. The export back-end will automatically wrap +properties within angular or square brackets when appropriate. + +@cindex property, BEAMER_COL +Moreover, headlines handle the @code{BEAMER_COL} property. Its value should +be a decimal number representing the width of the column as a fraction of the +total text width. If the headline has no specific environment, its title +will be ignored and its contents will fill the column created. Otherwise, +the block will fill the whole column and the title will be preserved. Two +contiguous headlines with a non-@code{nil} @code{BEAMER_COL} value share the same +@code{columns} @LaTeX{} environment. It will end before the next headline +without such a property. This environment is generated automatically. +Although, it can also be explicitly created, with a special @code{columns} +value for @code{BEAMER_ENV} property (if it needs to be set up with some +specific options, for example). + +@subheading Beamer specific syntax + +Beamer back-end is an extension of @LaTeX{} back-end. As such, all @LaTeX{} +specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is +recognized. See @ref{@LaTeX{} and PDF export} for more information. + +@cindex #+BEAMER_THEME +@cindex #+BEAMER_COLOR_THEME +@cindex #+BEAMER_FONT_THEME +@cindex #+BEAMER_INNER_THEME +@cindex #+BEAMER_OUTER_THEME +Beamer export introduces a number of keywords to insert code in the +document's header. Four control appearance of the presentation: +@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME}, +@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and +@code{#+BEAMER_OUTER_THEME}. All of them accept optional arguments +within square brackets. The last one, @code{#+BEAMER_HEADER}, is more +generic and allows you to append any line of code in the header. + +@example +#+BEAMER_THEME: Rochester [height=20pt] +#+BEAMER_COLOR_THEME: spruce +@end example + +Table of contents generated from @code{toc:t} @code{OPTION} keyword are +wrapped within a @code{frame} environment. Those generated from a @code{TOC} +keyword (@pxref{Table of contents}) are not. In that case, it is also +possible to specify options, enclosed within square brackets. + +@example +#+TOC: headlines [currentsection] +@end example + +Beamer specific code can be inserted with the following constructs: + +@cindex #+BEAMER +@cindex #+BEGIN_BEAMER +@example +#+BEAMER: \pause + +#+BEGIN_BEAMER +All lines in this block will appear only when using this back-end. +#+END_BEAMER + +Text @@@@beamer:some code@@@@ within a paragraph. +@end example + +In particular, this last example can be used to add overlay specifications to +objects whose type is among @code{bold}, @code{item}, @code{link}, +@code{radio-target} and @code{target}, when the value is enclosed within +angular brackets and put at the beginning the object. + +@example +A *@@@@beamer:<2->@@@@useful* feature +@end example + +@cindex #+ATTR_BEAMER +Eventually, every plain list has support for @code{:environment}, +@code{:overlay} and @code{:options} attributes through +@code{ATTR_BEAMER} affiliated keyword. The first one allows the use +of a different environment, the second sets overlay specifications and +the last one inserts optional arguments in current list environment. + +@example +#+ATTR_BEAMER: :overlay +- +- item 1 +- item 2 +@end example + +@subheading Editing support + +You can turn on a special minor mode @code{org-beamer-mode} for faster +editing 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 + +Also, a template for useful in-buffer settings or properties can be inserted +into the buffer with @kbd{M-x org-beamer-insert-options-template}. Among +other things, this will install a column view format which is very handy for +editing special properties used by Beamer. + +@subheading An example + +Here is a simple example Org document that is intended for Beamer export. + +@smallexample +#+TITLE: Example Presentation +#+AUTHOR: Carsten Dominik +#+OPTIONS: H:2 +#+LATEX_CLASS: beamer +#+LATEX_CLASS_OPTIONS: [presentation] +#+BEAMER_THEME: Madrid +#+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt) + +* This is the first structural section + +** Frame 1 +*** Thanks to Eric Fraga :B_block:BMCOL: + :PROPERTIES: + :BEAMER_COL: 0.48 + :BEAMER_ENV: block + :END: + for the first viable Beamer setup in Org +*** Thanks to everyone else :B_block:BMCOL: + :PROPERTIES: + :BEAMER_COL: 0.48 + :BEAMER_ACT: <2-> + :BEAMER_ENV: block + :END: + for contributing to the discussion +**** This will be formatted as a beamer note :B_note: + :PROPERTIES: + :BEAMER_env: note + :END: +** Frame 2 (where we will not use columns) +*** Request + Please test this stuff! +@end smallexample + +@node HTML export, @LaTeX{} and PDF export, Beamer export, Exporting @section HTML export @cindex HTML export -Org mode contains a 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 +* HTML doctypes:: Org can export to various (X)HTML flavors * HTML preamble and postamble:: How to insert a preamble and a postamble * Quoting HTML tags:: Using direct HTML in Org mode * Links in HTML export:: How links will be interpreted and formatted @@ -10053,100 +11028,161 @@ language, but with additional support for tables. * JavaScript support:: Info and Folding in a web browser @end menu -@node HTML Export commands, HTML preamble and postamble, HTML export, HTML export +@node HTML Export commands, HTML doctypes, HTML export, HTML export @subsection HTML export commands -@cindex region, active -@cindex active region -@cindex transient-mark-mode @table @kbd -@orgcmd{C-c C-e h,org-export-as-html} -@cindex property, EXPORT_FILE_NAME -Export as a HTML file. For an Org file @file{myfile.org}, +@orgcmd{C-c C-e h h,org-html-export-to-html} +Export as an HTML file. For an Org file @file{myfile.org}, the HTML file will be @file{myfile.html}. The file will be overwritten -without warning. If there is an active region@footnote{This requires -@code{transient-mark-mode} be turned on.}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. -@orgcmd{C-c C-e b,org-export-as-html-and-open} -Export as a HTML file and immediately open it with a browser. -@orgcmd{C-c C-e H,org-export-as-html-to-buffer} +without warning. +@kbd{C-c C-e h o} +Export as an HTML file and immediately open it with a browser. +@orgcmd{C-c C-e h H,org-html-export-as-html} 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. -@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 in Org mode -syntax before. This is a global command that can be invoked in any -buffer. -@item M-x org-replace-region-by-HTML -Replace the active region (assumed to be in Org mode syntax) by HTML -code. @end table -@cindex headline levels, for exporting -In the exported version, the first 3 outline levels will become headlines, -defining a general document structure. Additional levels will be exported as -itemized lists. If you want that transition to occur at a different level, -specify it with a numeric prefix argument. For example, +@c FIXME Exporting sublevels +@c @cindex headline levels, for exporting +@c In the exported version, the first 3 outline levels will become headlines, +@c defining a general document structure. Additional levels will be exported as +@c itemized lists. If you want that transition to occur at a different level, +@c specify it with a numeric prefix argument. For example, + +@c @example +@c @kbd{C-2 C-c C-e b} +@c @end example + +@c @noindent +@c creates two levels of headings and does the rest as items. + +@node HTML doctypes, HTML preamble and postamble, HTML Export commands, HTML export +@subsection HTML doctypes +@vindex org-html-doctype +@vindex org-html-doctype-alist + +Org can export to various (X)HTML flavors. + +Setting the variable @code{org-html-doctype} allows you to export to different +(X)HTML variants. The exported HTML will be adjusted according to the syntax +requirements of that variant. You can either set this variable to a doctype +string directly, in which case the exporter will try to adjust the syntax +automatically, or you can use a ready-made doctype. The ready-made options +are: + +@itemize +@item +``html4-strict'' +@item +``html4-transitional'' +@item +``html4-frameset'' +@item +``xhtml-strict'' +@item +``xhtml-transitional'' +@item +``xhtml-frameset'' +@item +``xhtml-11'' +@item +``html5'' +@item +``xhtml5'' +@end itemize + +See the variable @code{org-html-doctype-alist} for details. The default is +``xhtml-strict''. + +@subsubheading Fancy HTML5 export +@vindex org-html-html5-fancy +@vindex org-html-html5-elements + +HTML5 introduces several new element types. By default, Org will not make +use of these element types, but you can set @code{org-html-html5-fancy} to +@code{t} (or set @code{html5-fancy} item in an @code{OPTIONS} line), to +enable a few new block-level elements. These are created using arbitrary +#+BEGIN and #+END blocks. For instance: @example -@kbd{C-2 C-c C-e b} +#+BEGIN_ASIDE +Lorem ipsum +#+END_ASIDE @end example -@noindent -creates two levels of headings and does the rest as items. +Will export to: +@example +<aside> + <p>Lorem ipsum</p> +</aside> +@end example + +While this: + +@example +#+ATTR_HTML: :controls controls :width 350 +#+BEGIN_VIDEO +#+HTML: <source src="movie.mp4" type="video/mp4"> +#+HTML: <source src="movie.ogg" type="video/ogg"> +Your browser does not support the video tag. +#+END_VIDEO +@end example + +Becomes: + +@example +<video controls="controls" width="350"> + <source src="movie.mp4" type="video/mp4"> + <source src="movie.ogg" type="video/ogg"> + <p>Your browser does not support the video tag.</p> +</video> +@end example -@node HTML preamble and postamble, Quoting HTML tags, HTML Export commands, HTML export +Special blocks that do not correspond to HTML5 elements (see +@code{org-html-html5-elements}) will revert to the usual behavior, i.e., +@code{#+BEGIN_LEDERHOSEN} will still export to @samp{<div class="lederhosen">}. + +Headlines cannot appear within special blocks. To wrap a headline and its +contents in e.g., @samp{<section>} or @samp{<article>} tags, set the +@code{HTML_CONTAINER} property on the headline itself. + +@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export @subsection HTML preamble and postamble -@vindex org-export-html-preamble -@vindex org-export-html-postamble -@vindex org-export-html-preamble-format -@vindex org-export-html-postamble-format -@vindex org-export-html-validation-link -@vindex org-export-author-info -@vindex org-export-email-info -@vindex org-export-creator-info +@vindex org-html-preamble +@vindex org-html-postamble +@vindex org-html-preamble-format +@vindex org-html-postamble-format +@vindex org-html-validation-link +@vindex org-export-creator-string @vindex org-export-time-stamp-file The HTML exporter lets you define a preamble and a postamble. -The default value for @code{org-export-html-preamble} is @code{t}, which -means that the preamble is inserted depending on the relevant format string -in @code{org-export-html-preamble-format}. - -Setting @code{org-export-html-preamble} to a string will override the default -format string. Setting it to a function, will insert the output of the -function, which must be a string; such a function takes no argument but you -can check against the value of @code{opt-plist}, which contains the list of -publishing properties for the current file. Setting to @code{nil} will not -insert any preamble. - -The default value for @code{org-export-html-postamble} is @code{'auto}, which -means that the HTML exporter will look for the value of -@code{org-export-author-info}, @code{org-export-email-info}, -@code{org-export-creator-info} and @code{org-export-time-stamp-file}, -@code{org-export-html-validation-link} and build the postamble from these -values. Setting @code{org-export-html-postamble} to @code{t} will insert the -postamble from the relevant format string found in -@code{org-export-html-postamble-format}. Setting it to @code{nil} will not -insert any postamble. +The default value for @code{org-html-preamble} is @code{t}, which means +that the preamble is inserted depending on the relevant format string in +@code{org-html-preamble-format}. + +Setting @code{org-html-preamble} to a string will override the default format +string. If you set it to a function, it will insert the output of the +function, which must be a string. Setting to @code{nil} will not insert any +preamble. + +The default value for @code{org-html-postamble} is @code{'auto}, which means +that the HTML exporter will look for information about the author, the email, +the creator and the date, and build the postamble from these values. Setting +@code{org-html-postamble} to @code{t} will insert the postamble from the +relevant format string found in @code{org-html-postamble-format}. Setting it +to @code{nil} will not insert any postamble. @node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export @subsection Quoting HTML tags Plain @samp{<} and @samp{>} are always transformed to @samp{<} and -@samp{>} in HTML export. If you want to include simple HTML tags -which should be interpreted as such, mark them with @samp{@@} as in -@samp{@@<b>bold text@@</b>}. Note that this really works only for -simple tags. For more extensive HTML that should be copied verbatim to -the exported file use either +@samp{>} in HTML export. If you want to include raw HTML code, which +should only appear in HTML export, mark it with @samp{@@@@html:} as in +@samp{@@@@html:<b>@@@@bold text@@@@html:</b>@@@@}. For more extensive HTML +that should be copied verbatim to the exported file use either @cindex #+HTML @cindex #+BEGIN_HTML @@ -10175,7 +11211,7 @@ includes automatic links created by radio targets (@pxref{Radio targets}). Links to external files will still work if the target file is on the same @i{relative} path as the published Org file. Links to other @file{.org} files will be translated into HTML links under the assumption -that a HTML version also exists of the linked file, at the same relative +that an HTML version also exists of the linked file, at the same relative path. @samp{id:} links can then be used to jump to specific entries across files. For information related to linking files while publishing them to a publishing directory see @ref{Publishing links}. @@ -10187,37 +11223,42 @@ and @code{style} attributes for a link: @cindex #+ATTR_HTML @example -#+ATTR_HTML: title="The Org mode homepage" style="color:red;" +#+ATTR_HTML: :title The Org mode homepage :style color:red; [[http://orgmode.org]] @end example @node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export @subsection Tables @cindex tables, in HTML -@vindex org-export-html-table-tag +@vindex org-html-table-default-attributes -Org mode tables are exported to HTML using the table tag defined in -@code{org-export-html-table-tag}. The default setting makes tables without -cell borders and frame. If you would like to change this for individual -tables, place something like the following before the table: +Org mode tables are exported to HTML using the table attributes defined in +@code{org-html-table-default-attributes}. The default setting makes tables +without cell borders and frame. If you would like to change this for +individual tables, place something like the following before the table: @cindex #+CAPTION @cindex #+ATTR_HTML @example #+CAPTION: This is a table with lines around and between cells -#+ATTR_HTML: border="2" rules="all" frame="border" +#+ATTR_HTML: :border 2 :rules all :frame border @end example +@vindex org-html-table-row-tags +You can also modify the default tags used for each row by setting +@code{org-html-table-row-tags}. See the docstring for an example on +how to use this option. + @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 @cindex inlining images in HTML -@vindex org-export-html-inline-images +@vindex org-html-inline-images HTML export can inline images given as links in the Org file, and it can make an image the clickable part of a link. By default@footnote{But see the variable -@code{org-export-html-inline-images}.}, images are inlined if a link does +@code{org-html-inline-images}.}, images are inlined if a link does not have a description. So @samp{[[file:myimg.jpg]]} will be inlined, while @samp{[[file:myimg.jpg][the image]]} will just produce a link @samp{the image} that points to the image. If the description part @@ -10238,7 +11279,7 @@ support text viewers and accessibility, and align it to the right. @cindex #+ATTR_HTML @example #+CAPTION: A black cat stalking a spider -#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right" +#+ATTR_HTML: :alt cat/spider image :title Action! :align right [[./img/a.jpg]] @end example @@ -10249,36 +11290,43 @@ You could use @code{http} addresses just as well. @subsection Math formatting in HTML export @cindex MathJax @cindex dvipng +@cindex imagemagick @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 +box with Org mode installation because @uref{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 +@file{MathJax}, use the variable @code{org-html-mathjax-options} or insert something like the following into the buffer: @example -#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js" +#+HTML_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 +@code{org-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 +method requires that the @file{dvipng} program or @file{imagemagick} suite is +available on your system. You can still get this processing with + +@example +#+OPTIONS: tex:dvipng +@end example + +or: @example -#+OPTIONS: LaTeX:dvipng +#+OPTIONS: tex:imagemagick @end example @node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export @@ -10287,15 +11335,16 @@ You can still get this processing with @cindex text areas, in HTML An alternative way to publish literal code examples in HTML is to use text areas, where the example can even be edited before pasting it into an -application. It is triggered by a @code{-t} switch at an @code{example} or -@code{src} block. Using this switch disables any options for syntax and -label highlighting, and line numbering, which may be present. You may also -use @code{-h} and @code{-w} switches to specify the height and width of the -text area, which default to the number of lines in the example, and 80, -respectively. For example +application. It is triggered by @code{:textarea} attribute at an +@code{example} or @code{src} block. + +You may also use @code{:height} and @code{:width} attributes to specify the +height and width of the text area, which default to the number of lines in +the example, and 80, respectively. For example @example -#+BEGIN_EXAMPLE -t -w 40 +#+ATTR_HTML: :textarea t :width 40 +#+BEGIN_EXAMPLE (defun org-xor (a b) "Exclusive or." (if a (not b) b)) @@ -10308,15 +11357,15 @@ respectively. For example @cindex CSS, for HTML export @cindex HTML export, CSS -@vindex org-export-html-todo-kwd-class-prefix -@vindex org-export-html-tag-class-prefix -You can also give style information for the exported file. The HTML exporter -assigns the following special CSS classes@footnote{If the classes on TODO -keywords and tags lead to conflicts, use the variables -@code{org-export-html-todo-kwd-class-prefix} and -@code{org-export-html-tag-class-prefix} to make them unique.} to appropriate -parts of the document---your style specifications may change these, in -addition to any of the standard classes like for headlines, tables, etc. +@vindex org-html-todo-kwd-class-prefix +@vindex org-html-tag-class-prefix +You can modify the CSS style definitions for the exported file. The HTML +exporter assigns the following special CSS classes@footnote{If the classes on +TODO keywords and tags lead to conflicts, use the variables +@code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to +make them unique.} to appropriate parts of the document---your style +specifications may change these, in addition to any of the standard classes +like for headlines, tables, etc. @example p.author @r{author information, including email} p.date @r{publishing date} @@ -10336,6 +11385,9 @@ p.creator @r{creator info, about org mode version} div.outline-N @r{div for outline level N (headline plus text))} div.outline-text-N @r{extra div for text at outline level N} .section-number-N @r{section number in headlines, different for each level} +.figure-number @r{label like "Figure 1:"} +.table-number @r{label like "Table 1:"} +.listing-number @r{label like "Listing 1:"} div.figure @r{how to format an inlined image} pre.src @r{formatted source code} pre.example @r{normal example} @@ -10346,24 +11398,26 @@ p.footnote @r{footnote definition paragraph, containing a footnote} .footnum @r{footnote number in footnote definition (always <sup>)} @end example -@vindex org-export-html-style-default -@vindex org-export-html-style-include-default -@vindex org-export-html-style -@vindex org-export-html-extra -@vindex org-export-html-style-default +@vindex org-html-style-default +@vindex org-html-head-include-default-style +@vindex org-html-head +@vindex org-html-head-extra +@cindex #+HTML_INCLUDE_STYLE Each exported file contains a compact default style that defines these classes in a basic way@footnote{This style is defined in the constant -@code{org-export-html-style-default}, which you should not modify. To turn +@code{org-html-style-default}, which you should not modify. To turn inclusion of these defaults off, customize -@code{org-export-html-style-include-default}}. You may overwrite these -settings, or add to them by using the variables @code{org-export-html-style} -(for Org-wide settings) and @code{org-export-html-style-extra} (for more -fine-grained settings, like file-local settings). To set the latter variable -individually for each file, you can use +@code{org-html-head-include-default-style} or set @code{html-style} to +@code{nil} in an @code{OPTIONS} line.}. You may overwrite these settings, or +add to them by using the variables @code{org-html-head} and +@code{org-html-head-extra}. You can override the global values of these +variables for each file by using these keywords: -@cindex #+STYLE +@cindex #+HTML_HEAD +@cindex #+HTML_HEAD_EXTRA @example -#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" /> +#+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" /> @end example @noindent @@ -10392,15 +11446,12 @@ as well, press @kbd{?} for an overview of the available keys). The second view type is a @emph{folding} view much like Org provides inside Emacs. The script is available at @url{http://orgmode.org/org-info.js} and you can find the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}. -We host the script at our site, but if you use it a lot, you might -not want to be dependent on @url{http://orgmode.org} and prefer to install a local +We host the script at our site, but if you use it a lot, you might not want +to be dependent on @url{http://orgmode.org} and prefer to install a local copy on your own web server. -To use the script, you need to make sure that the @file{org-jsinfo.el} module -gets loaded. It should be loaded by default, but you can try @kbd{M-x -customize-variable @key{RET} org-modules @key{RET}} to convince yourself that -this is indeed the case. All it then takes to make use of the program is -adding a single line to the Org file: +All it then takes to use this program is adding a single line to the Org +file: @cindex #+INFOJS_OPT @example @@ -10440,92 +11491,61 @@ buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the} @r{default), only one such button will be present.} @end example @noindent -@vindex org-infojs-options -@vindex org-export-html-use-infojs +@vindex org-html-infojs-options +@vindex org-html-use-infojs You can choose default values for these options by customizing the variable -@code{org-infojs-options}. If you always want to apply the script to your -pages, configure the variable @code{org-export-html-use-infojs}. +@code{org-html-infojs-options}. If you always want to apply the script to your +pages, configure the variable @code{org-html-use-infojs}. -@node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting +@node @LaTeX{} and PDF export, Markdown export, HTML export, Exporting @section @LaTeX{} and PDF export @cindex @LaTeX{} export @cindex PDF export -@cindex Guerry, Bastien - -Org mode contains a @LaTeX{} exporter written by Bastien Guerry. With -further processing@footnote{The default @LaTeX{} output is designed for -processing with @code{pdftex} or @LaTeX{}. It includes packages that are not -compatible with @code{xetex} and possibly @code{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. Beware of the fact that your @code{org} file has to be properly -structured in order to be correctly exported: respect the hierarchy of -sections. + +@LaTeX{} export can produce an arbitrarily complex LaTeX document of any +standard or custom document class. With further processing@footnote{The +default @LaTeX{} output is designed for processing with @code{pdftex} or +@LaTeX{}. It includes packages that are not compatible with @code{xetex} and +possibly @code{luatex}. The @LaTeX{} exporter can be configured to support +alternative TeX engines, see the options +@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.}, +which the @LaTeX{} exporter is able to control, this back-end is able to +produce PDF output. Because the @LaTeX{} exporter can be configured to use +the @code{hyperref} package, the default setup produces fully-linked PDF +output. + +As in @LaTeX{}, blank lines are meaningful for this back-end: a paragraph +will not be started if two contiguous syntactical elements are not separated +by an empty line. + +This back-end also offers enhanced support for footnotes. Thus, it handles +nested footnotes, footnotes in tables and footnotes in a list item's +description. @menu -* @LaTeX{}/PDF export commands:: +* @LaTeX{} export commands:: How to export to LaTeX and PDF * 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 +* @LaTeX{} specific attributes:: Controlling @LaTeX{} output @end menu -@node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export +@node @LaTeX{} 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 -@orgcmd{C-c C-e l,org-export-as-latex} -@cindex property EXPORT_FILE_NAME -Export as a @LaTeX{} file. For an Org file -@file{myfile.org}, the @LaTeX{} 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 -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. -@orgcmd{C-c C-e L,org-export-as-latex-to-buffer} +@orgcmd{C-c C-e l l,org-latex-export-to-latex} +Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{} +file will be @file{myfile.tex}. The file will be overwritten without +warning. +@orgcmd{C-c C-e l L,org-latex-export-as-latex} 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 @LaTeX{} under the assumption that it was in 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 @LaTeX{} -code. -@orgcmd{C-c C-e p,org-export-as-pdf} +@orgcmd{C-c C-e l p,org-latex-export-to-pdf} Export as @LaTeX{} and then process to PDF. -@orgcmd{C-c C-e d,org-export-as-pdf-and-open} +@item C-c C-e l o Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. @end table -@cindex headline levels, for exporting -@vindex org-latex-low-levels -In the exported version, the first 3 outline levels will become -headlines, defining a general document structure. Additional levels -will be exported as description lists. The exporter can ignore them or -convert them to a custom string depending on -@code{org-latex-low-levels}. - -If you want that transition to occur at a different level, specify it -with a numeric prefix argument. For example, - -@example -@kbd{C-2 C-c C-e l} -@end example - -@noindent -creates two levels of headings and does the rest as items. - -@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{}/PDF export commands, @LaTeX{} and PDF export +@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{} export commands, @LaTeX{} and PDF export @subsection Header and sectioning structure @cindex @LaTeX{} class @cindex @LaTeX{} sectioning structure @@ -10533,493 +11553,377 @@ creates two levels of headings and does the rest as items. @cindex header, for @LaTeX{} files @cindex sectioning structure, for @LaTeX{} export +By default, the first three outline levels become headlines, defining a +general document structure. Additional levels are exported as @code{itemize} +or @code{enumerate} lists. The transition can also occur at a different +level (@pxref{Export settings}). + 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 +@vindex org-latex-default-class +@vindex org-latex-classes +@vindex org-latex-default-packages-alist +@vindex org-latex-packages-alist 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. The -options to documentclass have to be provided, as expected by @LaTeX{}, within -square brackets. 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. An example is shown -below. - -@example -#+LaTeX_CLASS: article -#+LaTeX_CLASS_OPTIONS: [a4paper] -#+LaTeX_HEADER: \usepackage@{xyz@} +@code{org-latex-default-class} or locally by adding an option like +@code{#+LATEX_CLASS: myclass} in your file, or with +a @code{EXPORT_LATEX_CLASS} property that applies when exporting a region +containing only this (sub)tree. The class must be listed in +@code{org-latex-classes}. This variable defines a header template for each +class@footnote{Into which the values of +@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist} +are spliced.}, and allows you to define the sectioning structure for each +class. You can also define your own classes there. + +@cindex #+LATEX_CLASS +@cindex #+LATEX_CLASS_OPTIONS +@cindex property, EXPORT_LATEX_CLASS +@cindex property, EXPORT_LATEX_CLASS_OPTIONS +The @code{LATEX_CLASS_OPTIONS} keyword or @code{EXPORT_LATEX_CLASS_OPTIONS} +property can specify the options for the @code{\documentclass} macro. These +options have to be provided, as expected by @LaTeX{}, within square brackets. + +@cindex #+LATEX_HEADER +@cindex #+LATEX_HEADER_EXTRA +You can also use the @code{LATEX_HEADER} and +@code{LATEX_HEADER_EXTRA}@footnote{Unlike @code{LATEX_HEADER}, contents +from @code{LATEX_HEADER_EXTRA} keywords will not be loaded when previewing +@LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).} keywords in order +to add lines to the header. See the docstring of @code{org-latex-classes} for +more information. + +An example is shown below. + +@example +#+LATEX_CLASS: article +#+LATEX_CLASS_OPTIONS: [a4paper] +#+LATEX_HEADER: \usepackage@{xyz@} * Headline 1 some text @end example -@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export +@node Quoting @LaTeX{} code, @LaTeX{} specific attributes, Header and sectioning, @LaTeX{} and PDF export @subsection Quoting @LaTeX{} code 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 @LaTeX{} export with -the following constructs: +inserted into the @LaTeX{} file. Furthermore, you can add special code that +should only be present in @LaTeX{} export with the following constructs: -@cindex #+LaTeX -@cindex #+BEGIN_LaTeX +@cindex #+LATEX +@cindex #+BEGIN_LATEX @example -#+LaTeX: Literal @LaTeX{} code for export -@end example +Code within @@@@latex:some code@@@@ a paragraph. -@noindent or -@cindex #+BEGIN_LaTeX +#+LATEX: Literal @LaTeX{} code for export -@example -#+BEGIN_LaTeX +#+BEGIN_LATEX All lines between these markers are exported literally -#+END_LaTeX +#+END_LATEX @end example +@node @LaTeX{} specific attributes, , Quoting @LaTeX{} code, @LaTeX{} and PDF export +@subsection @LaTeX{} specific attributes +@cindex #+ATTR_LATEX + +@LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line. They +affect tables, images, plain lists, special blocks and source blocks. -@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export -@subsection Tables in @LaTeX{} export +@subsubheading Tables in @LaTeX{} export @cindex tables, in @LaTeX{} export -For @LaTeX{} export of a table, you can specify a label, a caption and -placement options (@pxref{Images and tables}). You can also use the -@code{ATTR_LaTeX} line to request a @code{longtable} environment for the -table, so that it may span several pages, or to change the default table -environment from @code{table} to @code{table*} or to change the default inner -tabular environment to @code{tabularx} or @code{tabulary}. Finally, you can -set the alignment string, and (with @code{tabularx} or @code{tabulary}) the -width: +For @LaTeX{} export of a table, you can specify a label and a caption +(@pxref{Images and tables}). You can also use attributes to control table +layout and contents. Valid @LaTeX{} attributes include: + +@table @code +@item :mode +@vindex org-latex-default-table-mode +Nature of table's contents. It can be set to @code{table}, @code{math}, +@code{inline-math} or @code{verbatim}. In particular, when in @code{math} or +@code{inline-math} mode, every cell is exported as-is, horizontal rules are +ignored and the table will be wrapped in a math environment. Also, +contiguous tables sharing the same math mode will be wrapped within the same +environment. Default mode is determined in +@code{org-latex-default-table-mode}. +@item :environment +@vindex org-latex-default-table-environment +Environment used for the table. It can be set to any @LaTeX{} table +environment, like @code{tabularx}@footnote{Requires adding the +@code{tabularx} package to @code{org-latex-packages-alist}.}, +@code{longtable}, @code{array}, @code{tabu}@footnote{Requires adding the +@code{tabu} package to @code{org-latex-packages-alist}.}, +@code{bmatrix}@enddots{} It defaults to +@code{org-latex-default-table-environment} value. +@item :caption +@code{#+CAPTION} keyword is the simplest way to set a caption for a table +(@pxref{Images and tables}). If you need more advanced commands for that +task, you can use @code{:caption} attribute instead. Its value should be raw +@LaTeX{} code. It has precedence over @code{#+CAPTION}. +@item :float +@itemx :placement +Float environment for the table. Possible values are @code{sidewaystable}, +@code{multicolumn}, @code{t} and @code{nil}. When unspecified, a table with +a caption will have a @code{table} environment. Moreover, @code{:placement} +attribute can specify the positioning of the float. +@item :align +@itemx :font +@itemx :width +Set, respectively, the alignment string of the table, its font size and its +width. They only apply on regular tables. +@item :spread +Boolean specific to the @code{tabu} and @code{longtabu} environments, and +only takes effect when used in conjunction with the @code{:width} attribute. +When @code{:spread} is non-@code{nil}, the table will be spread or shrunk by the +value of @code{:width}. +@item :booktabs +@itemx :center +@itemx :rmlines +@vindex org-latex-tables-booktabs +@vindex org-latex-tables-centered +They toggle, respectively, @code{booktabs} usage (assuming the package is +properly loaded), table centering and removal of every horizontal rule but +the first one (in a "table.el" table only). In particular, +@code{org-latex-tables-booktabs} (respectively @code{org-latex-tables-centered}) +activates the first (respectively second) attribute globally. +@item :math-prefix +@itemx :math-suffix +@itemx :math-arguments +A string that will be inserted, respectively, before the table within the +math environment, after the table within the math environment, and between +the macro name and the contents of the table. The @code{:math-arguments} +attribute is used for matrix macros that require more than one argument +(e.g., @code{qbordermatrix}). +@end table + +Thus, attributes can be used in a wide array of situations, like writing +a table that will span over multiple pages, or a matrix product: -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX @example -#+CAPTION: A long table -#+LABEL: tbl:long -#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l +#+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l | ..... | ..... | | ..... | ..... | + +#+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times +| a | b | +| c | d | +#+ATTR_LATEX: :mode math :environment bmatrix +| 1 | 2 | +| 3 | 4 | @end example -or to specify a multicolumn table with @code{tabulary} +In the example below, @LaTeX{} command +@code{\bicaption@{HeadingA@}@{HeadingB@}} will set the caption. -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX @example -#+CAPTION: A wide table with tabulary -#+LABEL: tbl:wide -#+ATTR_LaTeX: table* tabulary width=\textwidth +#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@} | ..... | ..... | | ..... | ..... | @end example -@node Images in @LaTeX{} export, Beamer class export, Tables in @LaTeX{} export, @LaTeX{} and PDF export -@subsection Images in @LaTeX{} export + +@subsubheading 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 @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 -element. You can use an @code{#+ATTR_LaTeX:} line to specify various other -options. You can ask org to export an image as a float without specifying -a label or a caption by using the keyword @code{float} in this line. Various -optional arguments to the @code{\includegraphics} macro can also be specified -in this fashion. To modify the placement option of the floating environment, -add something like @samp{placement=[h!]} to the attributes. It is to be noted -this option can be used with tables as well@footnote{One can also take -advantage of this option to pass other, unrelated options into the figure or -table environment. For an example see the section ``Exporting org files'' in -@url{http://orgmode.org/worg/org-hacks.html}}. - -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}. +@code{\includegraphics} macro to insert the image@footnote{In the case of +TikZ (@url{http://sourceforge.net/projects/pgf/}) images, it will become an +@code{\input} macro wrapped within a @code{tikzpicture} environment.}. + +You can specify specify image width or height with, respectively, +@code{:width} and @code{:height} attributes. It is also possible to add any +other option with the @code{:options} attribute, as shown in the following +example: -@cindex #+CAPTION -@cindex #+LABEL -@cindex #+ATTR_LaTeX @example -#+CAPTION: The black-body emission of the disk around HR 4049 -#+LABEL: fig:SED-HR4049 -#+ATTR_LaTeX: width=5cm,angle=90 +#+ATTR_LATEX: :width 5cm :options angle=90 [[./img/sed-hr4049.pdf]] - -#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@} -[[./img/hst.png]] @end example -If you wish to include an image which spans multiple columns in a page, you -can use the keyword @code{multicolumn} in the @code{#+ATTR_LaTeX} line. This -will export the image wrapped in a @code{figure*} environment. - -If you need references to a label created in this way, write -@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. +If you need a specific command for the caption, use @code{:caption} +attribute. It will override standard @code{#+CAPTION} value, if any. -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: +@example +#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@} +[[./img/sed-hr4049.pdf]] +@end example -@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} +If you have specified a caption as described in @ref{Images and tables}, the +picture will be wrapped into a @code{figure} environment and thus become +a floating element. You can also ask Org to export an image as a float +without specifying caption by setting the @code{:float} attribute. You may +also set it to: +@itemize @minus +@item +@code{t}: if you want to use the standard @samp{figure} environment. It is +used by default if you provide a caption to the image. +@item +@code{multicolumn}: if you wish to include an image which spans multiple +columns in a page. This will export the image wrapped in a @code{figure*} 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 +@item +@code{wrap}: if you would like to let text flow around the image. It will +make the figure occupy the left half of the page. +@item +@code{nil}: if you need to avoid any floating environment, even when +a caption is provided. +@end itemize +@noindent +To modify the placement option of any floating environment, set the +@code{placement} attribute. @example -#+STARTUP: beamer +#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@} +[[./img/hst.png]] @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. - -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 +If the @code{:comment-include} attribute is set to a non-@code{nil} value, +the @LaTeX{} @code{\includegraphics} macro will be commented out. -For more information, see the documentation on Worg. +@subsubheading Plain lists in @LaTeX{} export +@cindex plain lists, in @LaTeX{} export -@node DocBook export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting -@section DocBook export -@cindex DocBook export -@cindex PDF export -@cindex Cui, Baoqiu +Plain lists accept two optional attributes: @code{:environment} and +@code{:options}. The first one allows the use of a non-standard environment +(e.g., @samp{inparaenum}). The second one specifies additional arguments for +that environment. -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 -formats, including PDF, HTML, man pages, etc., using many available DocBook -tools and stylesheets. +@example +#+ATTR_LATEX: :environment compactitem :options [$\circ$] +- you need ``paralist'' package to reproduce this example. +@end example -Currently DocBook exporter only supports DocBook V5.0. +@subsubheading Source blocks in @LaTeX{} export +@cindex source blocks, in @LaTeX{} export -@menu -* DocBook export commands:: How to invoke DocBook export -* Quoting DocBook code:: Incorporating DocBook code in Org files -* Recursive sections:: Recursive sections in DocBook -* Tables in DocBook export:: Tables are exported as HTML tables -* Images in DocBook export:: How to insert figures into DocBook output -* Special characters:: How to handle special characters -@end menu - -@node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export -@subsection DocBook export commands +In addition to syntax defined in @ref{Literal examples}, names and captions +(@pxref{Images and tables}), source blocks also accept a @code{:float} +attribute. You may set it to: +@itemize @minus +@item +@code{t}: if you want to make the source block a float. It is the default +value when a caption is provided. +@item +@code{multicolumn}: if you wish to include a source block which spans multiple +columns in a page. +@item +@code{nil}: if you need to avoid any floating environment, even when a caption +is provided. It is useful for source code that may not fit in a single page. +@end itemize -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@orgcmd{C-c C-e D,org-export-as-docbook} -@cindex property EXPORT_FILE_NAME -Export as a DocBook file. For an Org file, @file{myfile.org}, the DocBook XML -file will be @file{myfile.xml}. The file will be overwritten without -warning. If there is an active region@footnote{This requires -@code{transient-mark-mode} to be turned on}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. -@orgcmd{C-c C-e V,org-export-as-docbook-pdf-and-open} -Export as a DocBook file, process to PDF, then open the resulting PDF file. - -@vindex org-export-docbook-xslt-proc-command -@vindex org-export-docbook-xsl-fo-proc-command -Note that, in order to produce PDF output based on an exported DocBook file, -you 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}. - -@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 +@example +#+ATTR_LATEX: :float nil +#+BEGIN_SRC emacs-lisp +Code that may not fit in a single page. +#+END_SRC +@end example -@node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export -@subsection Quoting DocBook code +@subsubheading Special blocks in @LaTeX{} export +@cindex special blocks, in @LaTeX{} export +@cindex abstract, in @LaTeX{} export +@cindex proof, in @LaTeX{} export -You can quote DocBook code in Org files and copy it verbatim into exported -DocBook file with the following constructs: +In @LaTeX{} back-end, special blocks become environments of the same name. +Value of @code{:options} attribute will be appended as-is to that +environment's opening string. For example: -@cindex #+DOCBOOK -@cindex #+BEGIN_DOCBOOK @example -#+DOCBOOK: Literal DocBook code for export +#+BEGIN_ABSTRACT +We demonstrate how to solve the Syracuse problem. +#+END_ABSTRACT + +#+ATTR_LATEX: :options [Proof of important theorem] +#+BEGIN_PROOF +... +Therefore, any even number greater than 2 is the sum of two primes. +#+END_PROOF @end example -@noindent or -@cindex #+BEGIN_DOCBOOK +@noindent +becomes @example -#+BEGIN_DOCBOOK -All lines between these markers are exported by DocBook exporter -literally. -#+END_DOCBOOK +\begin@{abstract@} +We demonstrate how to solve the Syracuse problem. +\end@{abstract@} + +\begin@{proof@}[Proof of important theorem] +... +Therefore, any even number greater than 2 is the sum of two primes. +\end@{proof@} @end example -For example, you can use the following lines to include a DocBook warning -admonition. As to what this warning says, you should pay attention to the -document context when quoting DocBook code in Org files. You may make -exported DocBook XML files invalid by not quoting DocBook code correctly. +If you need to insert a specific caption command, use @code{:caption} +attribute. It will override standard @code{#+CAPTION} value, if any. For +example: @example -#+BEGIN_DOCBOOK -<warning> - <para>You should know what you are doing when quoting DocBook XML code - in your Org file. Invalid DocBook XML may be generated by - DocBook exporter if you are not careful!</para> -</warning> -#+END_DOCBOOK +#+ATTR_LATEX: :caption \MyCaption@{HeadingA@} +#+BEGIN_PROOF +... +#+END_PROOF @end example -@node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export -@subsection Recursive sections -@cindex DocBook recursive sections - -DocBook exporter exports Org files as articles using the @code{article} -element in DocBook. Recursive sections, i.e., @code{section} elements, are -used in exported articles. Top level headlines in Org files are exported as -top level sections, and lower level headlines are exported as nested -sections. The entire structure of Org files will be exported completely, no -matter how many nested levels of headlines there are. - -Using recursive sections makes it easy to port and reuse exported DocBook -code in other DocBook document types like @code{book} or @code{set}. - -@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export -@subsection Tables in DocBook export -@cindex tables, in DocBook export - -Tables in Org files are exported as HTML tables, which have been supported since -DocBook V4.3. +@subsubheading Horizontal rules +@cindex horizontal rules, in @LaTeX{} export -If a table does not have a caption, an informal table is generated using the -@code{informaltable} element; otherwise, a formal table will be generated -using the @code{table} element. +Width and thickness of a given horizontal rule can be controlled with, +respectively, @code{:width} and @code{:thickness} attributes: -@node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export -@subsection Images in DocBook export -@cindex images, inline in DocBook -@cindex inlining images in DocBook - -Images that are linked to without a description part in the link, like -@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook -using @code{mediaobject} elements. Each @code{mediaobject} element contains -an @code{imageobject} that wraps an @code{imagedata} element. If you have -specified a caption for an image as described in @ref{Images and tables}, a -@code{caption} element will be added in @code{mediaobject}. If a label is -also specified, it will be exported as an @code{xml:id} attribute of the -@code{mediaobject} element. - -@vindex org-export-docbook-default-image-attributes -Image attributes supported by the @code{imagedata} element, like @code{align} -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 overridden by image -attributes specified in @code{#+ATTR_DOCBOOK:} lines). - -The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image -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 -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 -#+LABEL: unicorn-svg -#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" -[[./img/org-mode-unicorn.svg]] +#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt +----- @end example -@vindex org-export-docbook-inline-image-extensions -By default, DocBook exporter recognizes the following image file types: -@file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}. You can -customize variable @code{org-export-docbook-inline-image-extensions} to add -more types to this list as long as DocBook supports them. +@node Markdown export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting +@section Markdown export +@cindex Markdown export -@node Special characters, , Images in DocBook export, DocBook export -@subsection Special characters in DocBook export -@cindex Special characters in DocBook export +@code{md} export back-end generates Markdown syntax@footnote{Vanilla flavor, +as defined at @url{http://daringfireball.net/projects/markdown/}.} for an Org +mode buffer. -@vindex org-export-docbook-doctype -@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-entities}. As long as the generated DocBook file includes the -corresponding entities, these special characters are recognized. +It is built over HTML back-end: any construct not supported by Markdown +syntax (e.g., tables) will be controlled and translated by @code{html} +back-end (@pxref{HTML export}). -You can customize variable @code{org-export-docbook-doctype} to include the -entities you need. For example, you can set variable -@code{org-export-docbook-doctype} to the following value to recognize all -special characters included in XHTML entities: +@subheading Markdown export commands -@example -"<!DOCTYPE article [ -<!ENTITY % xhtml1-symbol PUBLIC -\"-//W3C//ENTITIES Symbol for HTML//EN//XML\" -\"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\" -> -%xhtml1-symbol; -]> -" -@end example +@table @kbd +@orgcmd{C-c C-e m m,org-md-export-to-markdown} +Export as a text file written in Markdown syntax. For an Org file, +@file{myfile.org}, the resulting file will be @file{myfile.md}. The file +will be overwritten without warning. +@orgcmd{C-c C-e m M,org-md-export-as-markdown} +Export to a temporary buffer. Do not create a file. +@item C-c C-e m o +Export as a text file with Markdown syntax, then open it. +@end table + +@subheading Header and sectioning structure + +@vindex org-md-headline-style +Markdown export can generate both @code{atx} and @code{setext} types for +headlines, according to @code{org-md-headline-style}. The former introduces +a hard limit of two levels, whereas the latter pushes it to six. Headlines +below that limit are exported as lists. You can also set a soft limit before +that one (@pxref{Export settings}). @c begin opendocument -@node OpenDocument Text export, TaskJuggler export, DocBook export, Exporting +@node OpenDocument Text export, Org export, Markdown export, Exporting @section OpenDocument Text export -@cindex K, Jambunathan @cindex ODT @cindex OpenDocument @cindex export, OpenDocument @cindex LibreOffice -@cindex org-odt.el -@cindex org-modules -Org Mode@footnote{Versions 7.8 or later} supports export to OpenDocument Text -(ODT) format using the @file{org-odt.el} module. Documents created -by this exporter use the @cite{OpenDocument-v1.2 +Org mode@footnote{Versions 7.8 or later} supports export to OpenDocument Text +(ODT) format. Documents created by this exporter use the +@cite{OpenDocument-v1.2 specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, Open Document Format for Office Applications (OpenDocument) Version 1.2}} and are compatible with LibreOffice 3.4. @@ -11054,14 +11958,14 @@ output. Check the availability of this program before proceeding further. @cindex active region @cindex transient-mark-mode @table @kbd -@orgcmd{C-c C-e o,org-export-as-odt} +@orgcmd{C-c C-e o o,org-odt-export-to-odt} @cindex property EXPORT_FILE_NAME Export as OpenDocument Text file. -@vindex org-export-odt-preferred-output-format -If @code{org-export-odt-preferred-output-format} is specified, automatically -convert the exported file to that format. @xref{x-export-to-other-formats, , +@vindex org-odt-preferred-output-format +If @code{org-odt-preferred-output-format} is specified, automatically convert +the exported file to that format. @xref{x-export-to-other-formats, , Automatically exporting to other formats}. For an Org file @file{myfile.org}, the ODT file will be @@ -11073,13 +11977,13 @@ 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. -@orgcmd{C-c C-e O,org-export-as-odt-and-open} +@kbd{C-c C-e o O} Export as an OpenDocument Text file and open the resulting file. -@vindex org-export-odt-preferred-output-format -If @code{org-export-odt-preferred-output-format} is specified, open the -converted file instead. @xref{x-export-to-other-formats, , Automatically -exporting to other formats}. +@vindex org-odt-preferred-output-format +If @code{org-odt-preferred-output-format} is specified, open the converted +file instead. @xref{x-export-to-other-formats, , Automatically exporting to +other formats}. @end table @node Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export @@ -11095,7 +11999,7 @@ one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}). If you have a working installation of LibreOffice, a document converter is pre-configured for you and you can use it right away. If you would like to use @file{unoconv} as your preferred converter, customize the variable -@code{org-export-odt-convert-process} to point to @code{unoconv}. You can +@code{org-odt-convert-process} to point to @code{unoconv}. You can also use your own favorite converter or tweak the default settings of the @file{LibreOffice} and @samp{unoconv} converters. @xref{Configuring a document converter}. @@ -11103,12 +12007,12 @@ document converter}. @subsubsection Automatically exporting to other formats @anchor{x-export-to-other-formats} -@vindex org-export-odt-preferred-output-format +@vindex org-odt-preferred-output-format Very often, you will find yourself exporting to ODT format, only to immediately save the exported document to other formats like @samp{doc}, @samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your preferred output format by customizing the variable -@code{org-export-odt-preferred-output-format}. This way, the export commands +@code{org-odt-preferred-output-format}. This way, the export commands (@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a format that is of immediate interest to you. @@ -11121,10 +12025,10 @@ ODT format. LibreOffice converter, mentioned above, is one such converter. Once a converter is configured, you can interact with it using the following command. -@vindex org-export-odt-convert +@vindex org-odt-convert @table @kbd -@item M-x org-export-odt-convert +@item M-x org-odt-convert RET Convert an existing document from one format to another. With a prefix argument, also open the newly produced file. @end table @@ -11161,8 +12065,8 @@ OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file. @item @cindex #+ODT_STYLES_FILE -@vindex org-export-odt-styles-file -Customize the variable @code{org-export-odt-styles-file} and point it to the +@vindex org-odt-styles-file +Customize the variable @code{org-odt-styles-file} and point it to the newly created file. For additional configuration options @pxref{x-overriding-factory-styles,,Overriding factory styles}. @@ -11192,7 +12096,7 @@ the factory settings. @node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export @subsection Links in ODT export -@cindex tables, in DocBook export +@cindex links, in ODT export ODT exporter creates native cross-references for internal links. It creates Internet-style links for all other links. @@ -11200,13 +12104,13 @@ Internet-style links for all other links. A link with no description and destined to a regular (un-itemized) outline heading is replaced with a cross-reference and section number of the heading. -A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced +A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced with a cross-reference and sequence number of the labeled entity. @xref{Labels and captions in ODT export}. @node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export @subsection Tables in ODT export -@cindex tables, in DocBook export +@cindex tables, in ODT export Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el} tables is supported. However, export of complex @file{table.el} tables---tables @@ -11285,17 +12189,17 @@ You can control the size and scale of the embedded images using the @code{#+ATTR_ODT} attribute. @cindex identify, ImageMagick -@vindex org-export-odt-pixels-per-inch +@vindex org-odt-pixels-per-inch The exporter specifies the desired size of the image in the final document in units of centimeters. In order to scale the embedded images, the exporter queries for pixel dimensions of the images using one of a) ImageMagick's -@file{identify} program or b) Emacs `create-image' and `image-size' -APIs.@footnote{Use of @file{ImageMagick} is only desirable. However, if you +@file{identify} program or b) Emacs @code{create-image} and @code{image-size} +APIs@footnote{Use of @file{ImageMagick} is only desirable. However, if you routinely produce documents that have large images or you export your Org files that has images using a Emacs batch script, then the use of -@file{ImageMagick} is mandatory.} The pixel dimensions are subsequently +@file{ImageMagick} is mandatory.}. The pixel dimensions are subsequently converted in to units of centimeters using -@code{org-export-odt-pixels-per-inch}. The default value of this variable is +@code{org-odt-pixels-per-inch}. The default value of this variable is set to @code{display-pixels-per-inch}. You can tweak this variable to achieve the best results. @@ -11342,7 +12246,7 @@ height:width ratio, do the following @cindex #+ATTR_ODT You can control the manner in which an image is anchored by setting the @code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one -of the the following three values for the @code{:anchor} property: +of the following three values for the @code{:anchor} property: @samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}. To create an image that is anchored to a page, do the following: @@ -11404,27 +12308,34 @@ You can use the following commands to quickly verify the reliability of the @LaTeX{}-to-MathML converter. @table @kbd - -@item M-x org-export-as-odf +@item M-x org-odt-export-as-odf RET Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file. -@item M-x org-export-as-odf-and-open +@item M-x org-odt-export-as-odf-and-open RET Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file and open the formula file with the system-registered application. @end table @cindex dvipng +@cindex imagemagick @item PNG images This option is activated on a per-file basis with @example -#+OPTIONS: LaTeX:dvipng +#+OPTIONS: tex:dvipng +@end example + +or: + +@example +#+OPTIONS: tex:imagemagick @end example With this option, @LaTeX{} fragments are processed into PNG images and the resulting images are embedded in the exported document. This method requires -that the @file{dvipng} program be available on your system. +that the @file{dvipng} program or @file{imagemagick} suite be available on +your system. @end enumerate @node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in ODT export @@ -11471,15 +12382,15 @@ It could be rendered as shown below in the exported document. Figure 2: Bell curve @end example -@vindex org-export-odt-category-strings +@vindex org-odt-category-map-alist You can modify the category component of the caption by customizing the -variable @code{org-export-odt-category-strings}. For example, to tag all -embedded images with the string @samp{Illustration} (instead of the default -@samp{Figure}) use the following setting. +option @code{org-odt-category-map-alist}. For example, to tag all embedded +images with the string @samp{Illustration} (instead of the default +@samp{Figure}) use the following setting: @lisp -(setq org-export-odt-category-strings - '(("en" "Table" "Illustration" "Equation" "Equation"))) +(setq org-odt-category-map-alist + (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p))) @end lisp With this, previous image will be captioned as below in the exported @@ -11500,14 +12411,14 @@ fontification to be turned on.} The auto-generated styles have @samp{OrgSrc} as prefix and inherit their color from the faces used by Emacs @code{font-lock} library for the source language. -@vindex org-export-odt-fontify-srcblocks -If you prefer to use your own custom styles for fontification, you can do so -by customizing the variable -@code{org-export-odt-create-custom-styles-for-srcblocks}. +@vindex org-odt-fontify-srcblocks +If you prefer to use your own custom styles for fontification, you can do +so by customizing the option +@code{org-odt-create-custom-styles-for-srcblocks}. -@vindex org-export-odt-create-custom-styles-for-srcblocks +@vindex org-odt-create-custom-styles-for-srcblocks You can turn off fontification of literal examples by customizing the -variable @code{org-export-odt-fontify-srcblocks}. +option @code{org-odt-fontify-srcblocks}. @node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export @subsection Advanced topics in ODT export @@ -11538,27 +12449,27 @@ like to tweak the default converter settings, proceed as below. @enumerate @item Register the converter -@vindex org-export-odt-convert-processes -Name your converter and add it to the list of known converters by customizing -the variable @code{org-export-odt-convert-processes}. Also specify how the -converter can be invoked via command-line to effect the conversion. +@vindex org-odt-convert-processes +Name your converter and add it to the list of known converters by +customizing the option @code{org-odt-convert-processes}. Also specify how +the converter can be invoked via command-line to effect the conversion. @item Configure its capabilities -@vindex org-export-odt-convert-capabilities -@anchor{x-odt-converter-capabilities} -Specify the set of formats the converter can handle by customizing the -variable @code{org-export-odt-convert-capabilities}. Use the default value -for this variable as a guide for configuring your converter. As suggested by -the default setting, you can specify the full set of formats supported by the +@vindex org-odt-convert-capabilities +@anchor{x-odt-converter-capabilities} Specify the set of formats the +converter can handle by customizing the variable +@code{org-odt-convert-capabilities}. Use the default value for this +variable as a guide for configuring your converter. As suggested by the +default setting, you can specify the full set of formats supported by the converter and not limit yourself to specifying formats that are related to just the OpenDocument Text format. @item Choose the converter -@vindex org-export-odt-convert-process +@vindex org-odt-convert-process Select the newly added converter as the preferred one by customizing the -variable @code{org-export-odt-convert-process}. +option @code{org-odt-convert-process}. @end enumerate @node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export @@ -11626,9 +12537,9 @@ customize these variables to override the factory styles used by the exporter. @itemize -@anchor{x-org-export-odt-styles-file} +@anchor{x-org-odt-styles-file} @item -@code{org-export-odt-styles-file} +@code{org-odt-styles-file} Use this variable to specify the @file{styles.xml} that will be used in the final output. You can specify one of the following values: @@ -11657,9 +12568,9 @@ like header and footer images. Use the default @file{styles.xml} @end enumerate -@anchor{x-org-export-odt-content-template-file} +@anchor{x-org-odt-content-template-file} @item -@code{org-export-odt-content-template-file} +@code{org-odt-content-template-file} Use this variable to specify the blank @file{content.xml} that will be used in the final output. @@ -11675,13 +12586,13 @@ file. The use of this feature is better illustrated with couple of examples. @enumerate @item Embedding ODT tags as part of regular text -You can include simple OpenDocument tags by prefixing them with -@samp{@@}. For example, to highlight a region of text do the following: +You can inline OpenDocument syntax by enclosing it within +@samp{@@@@odt:...@@@@} markup. For example, to highlight a region of text do +the following: @example -@@<text:span text:style-name="Highlight">This is a -highlighted text@@</text:span>. But this is a -regular text. +@@@@odt:<text:span text:style-name="Highlight">This is a highlighted +text</text:span>@@@@. But this is a regular text. @end example @strong{Hint:} To see the above example in action, edit your @@ -11709,7 +12620,7 @@ custom @samp{PageBreak} style as shown below. @example <style:style style:name="PageBreak" style:family="paragraph" - style:parent-style-name="Text_20_body"> + style:parent-style-name="Text_20_body"> <style:paragraph-properties fo:break-before="page"/> </style:style> @end example @@ -11746,22 +12657,21 @@ OpenDocument-v1.2 specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, OpenDocument-v1.2 Specification}} - - @subsubheading Custom table styles: an illustration -To have a quick preview of this feature, install the below setting and export -the table that follows. +@vindex org-odt-table-styles +To have a quick preview of this feature, install the below setting and +export the table that follows: @lisp -(setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) +(setq org-odt-table-styles + (append org-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) @end lisp @example @@ -11774,9 +12684,9 @@ the table that follows. In the above example, you used a template named @samp{Custom} and installed two table styles with the names @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument -styles needed for producing the above template have been pre-defined for you. -These styles are available under the section marked @samp{Custom Table -Template} in @file{OrgOdtContentTemplate.xml} +styles needed for producing the above template have been pre-defined for +you. These styles are available under the section marked @samp{Custom +Table Template} in @file{OrgOdtContentTemplate.xml} (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need additional templates you have to define these styles yourselves. @@ -11860,9 +12770,9 @@ Define a table style@footnote{See the attributes @code{table:template-name}, @code{table:use-banding-column-styles} of the @code{<table:table>} element in the OpenDocument-v1.2 specification} -@vindex org-export-odt-table-styles +@vindex org-odt-table-styles To define a table style, create an entry for the style in the variable -@code{org-export-odt-table-styles} and specify the following: +@code{org-odt-table-styles} and specify the following: @itemize @minus @item the name of the table template created in step (1) @@ -11875,14 +12785,14 @@ based on the same template @samp{Custom}. The styles achieve their intended effect by selectively activating the individual cell styles in that template. @lisp -(setq org-export-odt-table-styles - (append org-export-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) +(setq org-odt-table-styles + (append org-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) @end lisp @item @@ -11913,173 +12823,353 @@ nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For general help with validation (and schema-sensitive editing) of XML files: @inforef{Introduction,,nxml-mode}. -@vindex org-export-odt-schema-dir +@vindex org-odt-schema-dir If you have ready access to OpenDocument @file{.rnc} files and the needed schema-locating rules in a single folder, you can customize the variable -@code{org-export-odt-schema-dir} to point to that directory. The -ODT exporter will take care of updating the -@code{rng-schema-locating-files} for you. +@code{org-odt-schema-dir} to point to that directory. The ODT exporter +will take care of updating the @code{rng-schema-locating-files} for you. @c end opendocument -@node TaskJuggler export, Freemind export, OpenDocument Text export, Exporting -@section TaskJuggler export -@cindex TaskJuggler export -@cindex Project management +@node Org export +@section Org export +@cindex Org export -@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. +@code{org} export back-end creates a normalized version of the Org document +in current buffer. In particular, it evaluates Babel code (@pxref{Evaluating +code blocks}) and removes other back-ends specific contents. -The TaskJuggler exporter is a bit different from other exporters, such as the -@code{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. +@subheading Org export commands + +@table @kbd +@orgcmd{C-c C-e O o,org-org-export-to-org} +Export as an Org document. For an Org file, @file{myfile.org}, the resulting +file will be @file{myfile.org.org}. The file will be overwritten without +warning. +@orgcmd{C-c C-e O O,org-org-export-as-org} +Export to a temporary buffer. Do not create a file. +@item C-c C-e O v +Export to an Org file, then open it. +@end table -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. +@node Texinfo export, iCalendar export, Org export, Exporting +@section Texinfo export +@cindex Texinfo export -@subsection TaskJuggler export commands +@samp{texinfo} export back-end generates Texinfo code and can compile it into +an Info file. -@table @kbd -@orgcmd{C-c C-e j,org-export-as-taskjuggler} -Export as a TaskJuggler file. +@menu +* Texinfo export commands:: How to invoke Texinfo export +* Document preamble:: File header, title and copyright page +* Headings and sectioning structure:: Building document structure +* Indices:: Creating indices +* Quoting Texinfo code:: Incorporating literal Texinfo code +* Texinfo specific attributes:: Controlling Texinfo output +* An example:: +@end menu + +@node Texinfo export commands, Document preamble, Texinfo export, Texinfo export +@subsection Texinfo export commands -@orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open} -Export as a TaskJuggler file and then open the file with TaskJugglerUI. +@vindex org-texinfo-info-process +@table @kbd +@orgcmd{C-c C-e i t,org-texinfo-export-to-texinfo} +Export as a Texinfo file. For an Org file, @file{myfile.org}, the resulting +file will be @file{myfile.texi}. The file will be overwritten without +warning. +@orgcmd{C-c C-e i i,org-texinfo-export-to-info} +Export to Texinfo and then process to an Info file@footnote{By setting +@code{org-texinfo-info-process}, it is possible to generate other formats, +including DocBook.}. @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 is 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. +@node Document preamble, Headings and sectioning structure, Texinfo export commands, Texinfo export +@subsection Document preamble -@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 +When processing a document, @samp{texinfo} back-end generates a minimal file +header along with a title page, a copyright page, and a menu. You control +the latter through the structure of the document (@pxref{Headings and +sectioning structure}). Various keywords allow to tweak the other parts. It +is also possible to give directions to install the document in the @samp{Top} +node. + +@subsubheading File header + +@cindex #+TEXINFO_FILENAME +Upon creating the header of a Texinfo file, the back-end guesses a name for +the Info file to be compiled. This may not be a sensible choice, e.g., if +you want to produce the final document in a different directory. Specify an +alternate path with @code{#+TEXINFO_FILENAME} keyword to override the default +destination. + +@vindex org-texinfo-coding-system +@vindex org-texinfo-classes +@cindex #+TEXINFO_HEADER +@cindex #+TEXINFO_CLASS +Along with the output file name, the header contains information about the +language (@pxref{Export settings}) and current encoding used@footnote{See +@code{org-texinfo-coding-system} for more information.}. Insert +a @code{#+TEXINFO_HEADER} keyword for each additional command needed, e.g., +@@code@{@@synindex@}. + +If you happen to regularly install the same set of commands, it may be easier +to define your own class in @code{org-texinfo-classes}, which see. Set +@code{#+TEXINFO_CLASS} keyword accordingly in your document to activate it. + +@subsubheading Title and copyright page + +@cindex #+TEXINFO_PRINTED_TITLE +@cindex #+SUBTITLE +The default template includes a title page for hard copy output. The title +and author displayed on this page are extracted from, respectively, +@code{#+TITLE} and @code{#+AUTHOR} keywords (@pxref{Export settings}). It is +also possible to print a different, more specific, title with +@code{#+TEXINFO_PRINTED_TITLE} keyword, and add subtitles with +@code{#+SUBTITLE} keyword. Both expect raw Texinfo code in their value. + +@cindex #+SUBAUTHOR +Likewise, information brought by @code{#+AUTHOR} may not be enough. You can +include other authors with several @code{#+SUBAUTHOR} keywords. Values are +also expected to be written in Texinfo code. + +@example +#+AUTHOR: Jane Smith +#+SUBAUTHOR: John Doe +#+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@} +@end example + +@cindex property, COPYING +Copying material is defined in a dedicated headline with a non-nil +@code{:COPYING:} property. The contents are inserted within +a @code{@@copying} command at the beginning of the document whereas the +heading itself does not appear in the structure of the document. + +Copyright information is printed on the back of the title page. + +@example +* Copying :PROPERTIES: - :task_id: preparation - :ORDERED: t + :COPYING: t :END: -* Training material + + This is a short example of a complete Texinfo file, version 1.0. + + Copyright \copy 2015 Free Software Foundation, Inc. +@end example + +@subsubheading The Top node + +@cindex #+TEXINFO_DIR_CATEGORY +@cindex #+TEXINFO_DIR_TITLE +@cindex #+TEXINFO_DIR_DESC +You may ultimately want to install your new Info file to your system. You +can write an appropriate entry in the top level directory specifying its +category and title with, respectively, @code{#+TEXINFO_DIR_CATEGORY} and +@code{#+TEXINFO_DIR_TITLE}. Optionally, you can add a short description +using @code{#+TEXINFO_DIR_DESC}. The following example would write an entry +similar to Org's in the @samp{Top} node. + +@example +#+TEXINFO_DIR_CATEGORY: Emacs +#+TEXINFO_DIR_TITLE: Org Mode: (org) +#+TEXINFO_DIR_DESC: Outline-based notes management and organizer +@end example + +@node Headings and sectioning structure, Indices, Document preamble, Texinfo export +@subsection Headings and sectioning structure + +@vindex org-texinfo-classes +@vindex org-texinfo-default-class +@cindex #+TEXINFO_CLASS +@samp{texinfo} uses a pre-defined scheme, or class, to convert headlines into +Texinfo structuring commands. For example, a top level headline appears as +@code{@@chapter} if it should be numbered or as @code{@@unnumbered} +otherwise. If you need to use a different set of commands, e.g., to start +with @code{@@part} instead of @code{@@chapter}, install a new class in +@code{org-texinfo-classes}, then activate it with @code{#+TEXINFO_CLASS} +keyword. Export process defaults to @code{org-texinfo-default-class} when +there is no such keyword in the document. + +If a headline's level has no associated structuring command, or is below +a certain threshold @pxref{Export settings}, that headline becomes a list in +Texinfo output. + +@cindex property, APPENDIX +As an exception, a headline with a non-nil @code{:APPENDIX:} property becomes +an appendix, independently on its level and the class used. + +@cindex property, DESCRIPTION +Each regular sectioning structure creates a menu entry, named after the +heading. You can provide a different, e.g., shorter, title in +@code{:ALT_TITLE:} property (@pxref{Table of contents}). Optionally, you can +specify a description for the item in @code{:DESCRIPTION:} property. E.g., + +@example +* Controlling Screen Display :PROPERTIES: - :task_id: training_material - :ORDERED: t + :ALT_TITLE: Display + :DESCRIPTION: Controlling Screen Display :END: -** Markup Guidelines - :PROPERTIES: - :Effort: 2d - :END: -** Workflow Guidelines - :PROPERTIES: - :Effort: 2d - :END: -* Presentation +@end example + +@node Indices, Quoting Texinfo code, Headings and sectioning structure, Texinfo export +@subsection Indices + +@cindex #+CINDEX +@cindex #+FINDEX +@cindex #+KINDEX +@cindex #+PINDEX +@cindex #+TINDEX +@cindex #+VINDEX +Index entries are created using dedicated keywords. @samp{texinfo} back-end +provides one for each predefined type: @code{#+CINDEX}, @code{#+FINDEX}, +@code{#+KINDEX}, @code{#+PINDEX}, @code{#+TINDEX} and @code{#+VINDEX}. For +custom indices, you can write raw Texinfo code (@pxref{Quoting Texinfo +code}). + +@example +#+CINDEX: Defining indexing entries +@end example + +@cindex property, INDEX +To generate an index, you need to set the @code{:INDEX:} property of +a headline to an appropriate abbreviation (e.g., @samp{cp} or @samp{vr}). +The headline is then exported as an unnumbered chapter or section command and +the index is inserted after its contents. + +@example +* Concept Index :PROPERTIES: - :Effort: 2d - :BLOCKER: training_material @{ gapduration 1d @} preparation + :INDEX: cp :END: @end example -@subsection Reports +@node Quoting Texinfo code, Texinfo specific attributes, Indices, Texinfo export +@subsection Quoting Texinfo code -@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}}. +It is possible to insert raw Texinfo code using any of the following +constructs -For more information and examples see the Org-taskjuggler tutorial at -@uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.html}. +@cindex #+TEXINFO +@cindex #+BEGIN_TEXINFO +@example +Richard @@@@texinfo:@@sc@{@@@@Stallman@@@@texinfo:@}@@@@ commence' GNU. -@node Freemind export, XOXO export, TaskJuggler export, Exporting -@section Freemind export -@cindex Freemind export -@cindex mind map +#+TEXINFO: @@need800 +This paragraph is preceded by... -The Freemind exporter was written by Lennart Borgman. +#+BEGIN_TEXINFO +@@auindex Johnson, Mark +@@auindex Lakoff, George +#+END_TEXINFO +@end example -@table @kbd -@orgcmd{C-c C-e m,org-export-as-freemind} -Export as a Freemind mind map. For an Org file @file{myfile.org}, the Freemind -file will be @file{myfile.mm}. -@end table +@node Texinfo specific attributes, An example, Quoting Texinfo code, Texinfo export +@subsection Texinfo specific attributes -@node XOXO export, iCalendar export, Freemind export, Exporting -@section XOXO export -@cindex XOXO export +@cindex #+ATTR_TEXINFO +@samp{texinfo} back-end understands several attributes in plain lists and +tables. They must be specified using an @code{#+ATTR_TEXINFO} keyword, +written just above the list or table. -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. +@subsubheading Plain lists -@table @kbd -@orgcmd{C-c C-e x,org-export-as-xoxo} -Export as an XOXO file. For an Org file @file{myfile.org}, the XOXO file will be -@file{myfile.html}. -@orgkey{C-c C-e v x} -Export only the visible part of the document. -@end table +In Texinfo output, description lists appear as two-column tables, using the +default command @code{@@table}. You can use @code{@@ftable} or +@code{@@vtable}@footnote{For more information, @inforef{Two-column +Tables,,texinfo}.} instead with @code{:table-type} attribute. + +@vindex org-texinfo-def-table-markup +In any case, these constructs require a highlighting command for entries in +the list. You can provide one with @code{:indic} attribute. If you do not, +it defaults to the value stored in @code{org-texinfo-def-table-markup}, which +see. + +@example +#+ATTR_TEXINFO: :indic @@asis +- foo :: This is the text for /foo/, with no highlighting. +@end example + +@subsubheading Tables + +When exporting a table, column widths are deduced from the longest cell in +each column. You can also define them explicitly as fractions of the line +length, using @code{:columns} attribute. -@node iCalendar export, , XOXO export, Exporting +@example +#+ATTR_TEXINFO: :columns .5 .5 +| a cell | another cell | +@end example + +@node An example, , Texinfo specific attributes, Texinfo export +@subsection An example + +Here is a thorough example, taken from @inforef{GNU Sample Texts,,texinfo}. + +@smallexample +#+MACRO: version 2.0 +#+MACRO: updated last updated 4 March 2014 + +#+OPTIONS: ':t toc:t author:t email:t +#+TITLE: GNU Sample @{@{@{version@}@}@} +#+AUTHOR: A.U. Thor +#+EMAIL: bug-sample@@gnu.org +#+LANGUAGE: en + +#+TEXINFO_FILENAME: sample.info +#+TEXINFO_HEADER: @@syncodeindex pg cp + +#+TEXINFO_DIR_CATEGORY: Texinfo documentation system +#+TEXINFO_DIR_TITLE: sample: (sample) +#+TEXINFO_DIR_DESC: Invoking sample + +#+TEXINFO_PRINTED_TITLE: GNU Sample +#+SUBTITLE: for version 2.0, last updated 4 March 2014 + +* Copying + :PROPERTIES: + :COPYING: t + :END: + + This manual is for GNU Sample (version @{@{@{version@}@}@}, + @{@{@{updated@}@}@}), which is an example in the Texinfo documentation. + + Copyright @@@@texinfo:@@copyright@{@}@@@@ 2013 Free Software Foundation, + Inc. + + #+BEGIN_QUOTE + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, with no Front-Cover Texts, + and with no Back-Cover Texts. A copy of the license is included in + the section entitled "GNU Free Documentation License". + #+END_QUOTE + +* Invoking sample + + #+PINDEX: sample + #+CINDEX: invoking @@command@{sample@} + + This is a sample manual. There is no sample program to invoke, but + if there were, you could see its basic usage and command line + options here. + +* GNU Free Documentation License + :PROPERTIES: + :APPENDIX: t + :END: + + #+TEXINFO: @@include fdl.texi + +* Index + :PROPERTIES: + :INDEX: cp + :END: +@end smallexample + +@node iCalendar export, Other built-in back-ends, Texinfo export, Exporting @section iCalendar export @cindex iCalendar export @@ -12118,19 +13208,19 @@ 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 -@orgcmd{C-c C-e i,org-export-icalendar-this-file} -Create iCalendar entries for the current file and store them in the same +@orgcmd{C-c C-e c f,org-icalendar-export-to-ics} +Create iCalendar entries for the current buffer and store them in the same directory, using a file extension @file{.ics}. -@orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files} +@orgcmd{C-c C-e c a, org-icalendar-export-agenda-files} @vindex org-agenda-files -Like @kbd{C-c C-e i}, but do this for all files in +Like @kbd{C-c C-e c f}, but do this for all files in @code{org-agenda-files}. For each of these files, a separate iCalendar file will be written. -@orgcmd{C-c C-e c,org-export-icalendar-combine-agenda-files} -@vindex org-combined-agenda-icalendar-file +@orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files} +@vindex org-icalendar-combined-agenda-file Create a single large iCalendar file from all files in @code{org-agenda-files} and write it to the file given by -@code{org-combined-agenda-icalendar-file}. +@code{org-icalendar-combined-agenda-file}. @end table @vindex org-use-property-inheritance @@ -12148,6 +13238,231 @@ 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 Other built-in back-ends, Export in foreign buffers, iCalendar export, Exporting +@section Other built-in back-ends +@cindex export back-ends, built-in +@vindex org-export-backends + +On top of the aforementioned back-ends, Org comes with other built-in ones: + +@itemize +@item @file{ox-man.el}: export to a man page. +@end itemize + +To activate these export back-end, customize @code{org-export-backends} or +load them directly with e.g., @code{(require 'ox-man)}. This will add new +keys in the export dispatcher (@pxref{The Export Dispatcher}). + +See the comment section of these files for more information on how to use +them. + +@node Export in foreign buffers, Advanced configuration, Other built-in back-ends, Exporting +@section Export in foreign buffers + +Most built-in back-ends come with a command to convert the selected region +into a selected format and replace this region by the exported output. Here +is a list of such conversion commands: + +@table @code +@item org-html-convert-region-to-html +Convert the selected region into HTML. +@item org-latex-convert-region-to-latex +Convert the selected region into @LaTeX{}. +@item org-texinfo-convert-region-to-texinfo +Convert the selected region into @code{Texinfo}. +@item org-md-convert-region-to-md +Convert the selected region into @code{MarkDown}. +@end table + +This is particularly useful for converting tables and lists in foreign +buffers. E.g., in an HTML buffer, you can turn on @code{orgstruct-mode}, then +use Org commands for editing a list, and finally select and convert the list +with @code{M-x org-html-convert-region-to-html RET}. + +@node Advanced configuration, , Export in foreign buffers, Exporting +@section Advanced configuration + +@subheading Hooks + +@vindex org-export-before-processing-hook +@vindex org-export-before-parsing-hook +Two hooks are run during the first steps of the export process. The first +one, @code{org-export-before-processing-hook} is called before expanding +macros, Babel code and include keywords in the buffer. The second one, +@code{org-export-before-parsing-hook}, as its name suggests, happens just +before parsing the buffer. Their main use is for heavy duties, that is +duties involving structural modifications of the document. For example, one +may want to remove every headline in the buffer during export. The following +code can achieve this: + +@lisp +@group +(defun my-headline-removal (backend) + "Remove all headlines in the current buffer. +BACKEND is the export back-end being used, as a symbol." + (org-map-entries + (lambda () (delete-region (point) (progn (forward-line) (point)))))) + +(add-hook 'org-export-before-parsing-hook 'my-headline-removal) +@end group +@end lisp + +Note that functions used in these hooks require a mandatory argument, +a symbol representing the back-end used. + +@subheading Filters + +@cindex Filters, exporting +Filters are lists of functions applied on a specific part of the output from +a given back-end. More explicitly, each time a back-end transforms an Org +object or element into another language, all functions within a given filter +type are called in turn on the string produced. The string returned by the +last function will be the one used in the final output. + +There are filters sets for each type of element or object, for plain text, +for the parse tree, for the export options and for the final output. They +are all named after the same scheme: @code{org-export-filter-TYPE-functions}, +where @code{TYPE} is the type targeted by the filter. Valid types are: + +@multitable @columnfractions .33 .33 .33 +@item bold +@tab babel-call +@tab center-block +@item clock +@tab code +@tab comment +@item comment-block +@tab diary-sexp +@tab drawer +@item dynamic-block +@tab entity +@tab example-block +@item export-block +@tab export-snippet +@tab final-output +@item fixed-width +@tab footnote-definition +@tab footnote-reference +@item headline +@tab horizontal-rule +@tab inline-babel-call +@item inline-src-block +@tab inlinetask +@tab italic +@item item +@tab keyword +@tab latex-environment +@item latex-fragment +@tab line-break +@tab link +@item node-property +@tab options +@tab paragraph +@item parse-tree +@tab plain-list +@tab plain-text +@item planning +@tab property-drawer +@tab quote-block +@item quote-section +@tab radio-target +@tab section +@item special-block +@tab src-block +@tab statistics-cookie +@item strike-through +@tab subscript +@tab superscript +@item table +@tab table-cell +@tab table-row +@item target +@tab timestamp +@tab underline +@item verbatim +@tab verse-block +@tab +@end multitable + +For example, the following snippet allows me to use non-breaking spaces in +the Org buffer and get them translated into @LaTeX{} without using the +@code{\nbsp} macro (where @code{_} stands for the non-breaking space): + +@lisp +@group +(defun my-latex-filter-nobreaks (text backend info) + "Ensure \"_\" are properly handled in LaTeX export." + (when (org-export-derived-backend-p backend 'latex) + (replace-regexp-in-string "_" "~" text))) + +(add-to-list 'org-export-filter-plain-text-functions + 'my-latex-filter-nobreaks) +@end group +@end lisp + +Three arguments must be provided to a filter: the code being changed, the +back-end used, and some information about the export process. You can safely +ignore the third argument for most purposes. Note the use of +@code{org-export-derived-backend-p}, which ensures that the filter will only +be applied when using @code{latex} back-end or any other back-end derived +from it (e.g., @code{beamer}). + +@subheading Extending an existing back-end + +This is obviously the most powerful customization, since the changes happen +at the parser level. Indeed, some export back-ends are built as extensions +of other ones (e.g., Markdown back-end an extension of HTML back-end). + +Extending a back-end means that if an element type is not transcoded by the +new back-end, it will be handled by the original one. Hence you can extend +specific parts of a back-end without too much work. + +As an example, imagine we want the @code{ascii} back-end to display the +language used in a source block, when it is available, but only when some +attribute is non-@code{nil}, like the following: + +@example +#+ATTR_ASCII: :language t +@end example + +Because that back-end is lacking in that area, we are going to create a new +back-end, @code{my-ascii} that will do the job. + +@lisp +@group +(defun my-ascii-src-block (src-block contents info) + "Transcode a SRC-BLOCK element from Org to ASCII. +CONTENTS is nil. INFO is a plist used as a communication +channel." + (if (not (org-export-read-attribute :attr_ascii src-block :language)) + (org-export-with-backend 'ascii src-block contents info) + (concat + (format ",--[ %s ]--\n%s`----" + (org-element-property :language src-block) + (replace-regexp-in-string + "^" "| " + (org-element-normalize-string + (org-export-format-code-default src-block info))))))) + +(org-export-define-derived-backend 'my-ascii 'ascii + :translate-alist '((src-block . my-ascii-src-block))) +@end group +@end lisp + +The @code{my-ascii-src-block} function looks at the attribute above the +element. If it isn't true, it gives hand to the @code{ascii} back-end. +Otherwise, it creates a box around the code, leaving room for the language. +A new back-end is then created. It only changes its behavior when +translating @code{src-block} type element. Now, all it takes to use the new +back-end is calling the following from an Org buffer: + +@smalllisp +(org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*") +@end smalllisp + +It is obviously possible to write an interactive function for this, install +it in the export dispatcher menu, and so on. + @node Publishing, Working With Source Code, Exporting, Top @chapter Publishing @cindex publishing @@ -12227,7 +13542,7 @@ and where to put published files. @tab Directory containing publishing source files @item @code{:publishing-directory} @tab Directory where output files will be published. You can directly -publish to a webserver using a file name syntax appropriate for +publish to a web server 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} @@ -12266,7 +13581,7 @@ extension. and @code{:exclude}. @item @code{:recursive} -@tab Non-nil means, check base-directory recursively for files to publish. +@tab non-@code{nil} means, check base-directory recursively for files to publish. @end multitable @node Publishing action, Publishing options, Selecting files, Configuration @@ -12276,201 +13591,171 @@ and @code{:exclude}. Publishing means that a file is copied to the destination directory and possibly transformed in the process. The default transformation is to export Org files as HTML files, and this is done by the function -@code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML +@code{org-html-publish-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}, 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 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: +@code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc., +using the corresponding functions. + +If you want to publish the Org file as an @code{.org} file but with the +@i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the +function @code{org-org-publish-to-org}. This will produce @file{file.org} +and put it in the publishing directory. If you want a htmlized version of +this file, set the parameter @code{:htmlized-source} to @code{t}, it will +produce @file{file.org.html} in the publishing directory@footnote{If the +publishing directory is the same than the source directory, @file{file.org} +will be exported as @file{file.org.org}, so probably don't want to do this.}. + +Other files like images only need to be copied to the publishing destination. +For this you can 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} @tab Function executing the publication of a file. This may also be a list of functions, which will all be called in turn. -@item @code{:plain-source} -@tab Non-nil means, publish plain source. @item @code{:htmlized-source} -@tab Non-nil means, publish htmlized source. +@tab non-@code{nil} means, publish htmlized source. @end multitable 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. +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/@LaTeX{} exporters +@subsection Options for the exporters @cindex options, for publishing -The property list can be used to set many export options for the HTML -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. +The property list can be used to set many export options for the exporters. +In most cases, these properties correspond to user variables in Org. The +first table below lists these properties along with the variable they belong +to. The second table list HTML specific properties. See the documentation +string of these options for details. -@vindex org-export-html-link-up -@vindex org-export-html-link-home -@vindex org-export-default-language @vindex org-display-custom-times +@vindex org-export-default-language +@vindex org-export-exclude-tags @vindex org-export-headline-levels -@vindex org-export-with-section-numbers -@vindex org-export-section-number-format -@vindex org-export-with-toc @vindex org-export-preserve-breaks +@vindex org-export-publishing-directory +@vindex org-export-select-tags @vindex org-export-with-archived-trees +@vindex org-export-with-author +@vindex org-export-with-creator +@vindex org-export-with-drawers +@vindex org-export-with-email @vindex org-export-with-emphasize -@vindex org-export-with-sub-superscripts -@vindex org-export-with-special-strings +@vindex org-export-with-fixed-width @vindex org-export-with-footnotes -@vindex org-export-with-drawers +@vindex org-export-with-latex +@vindex org-export-with-planning +@vindex org-export-with-priority +@vindex org-export-with-section-numbers +@vindex org-export-with-special-strings +@vindex org-export-with-sub-superscripts +@vindex org-export-with-tables @vindex org-export-with-tags -@vindex org-export-with-todo-keywords @vindex org-export-with-tasks -@vindex org-export-with-done-tasks -@vindex org-export-with-priority -@vindex org-export-with-TeX-macros -@vindex org-export-with-LaTeX-fragments -@vindex org-export-skip-text-before-1st-heading -@vindex org-export-with-fixed-width @vindex org-export-with-timestamps -@vindex org-export-author-info -@vindex org-export-email-info -@vindex org-export-creator-info -@vindex org-export-time-stamp-file -@vindex org-export-with-tables -@vindex org-export-highlight-first-table-line -@vindex org-export-html-style-include-default -@vindex org-export-html-style-include-scripts -@vindex org-export-html-style -@vindex org-export-html-style-extra -@vindex org-export-html-link-org-files-as-html -@vindex org-export-html-inline-images -@vindex org-export-html-extension -@vindex org-export-html-table-tag -@vindex org-export-html-expand -@vindex org-export-html-with-timestamp -@vindex org-export-publishing-directory -@vindex org-export-html-preamble -@vindex org-export-html-postamble -@vindex user-full-name +@vindex org-export-with-toc +@vindex org-export-with-todo-keywords @vindex user-mail-address -@vindex org-export-select-tags -@vindex org-export-exclude-tags @multitable @columnfractions 0.32 0.68 -@item @code{:link-up} @tab @code{org-export-html-link-up} -@item @code{:link-home} @tab @code{org-export-html-link-home} -@item @code{:language} @tab @code{org-export-default-language} -@item @code{:customtime} @tab @code{org-display-custom-times} +@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} +@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} @item @code{:headline-levels} @tab @code{org-export-headline-levels} -@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} -@item @code{:section-number-format} @tab @code{org-export-section-number-format} -@item @code{:table-of-contents} @tab @code{org-export-with-toc} +@item @code{:language} @tab @code{org-export-default-language} @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} -@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} -@item @code{:emphasize} @tab @code{org-export-with-emphasize} -@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} -@item @code{:special-strings} @tab @code{org-export-with-special-strings} -@item @code{:footnotes} @tab @code{org-export-with-footnotes} -@item @code{:drawers} @tab @code{org-export-with-drawers} -@item @code{:tags} @tab @code{org-export-with-tags} -@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords} -@item @code{:tasks} @tab @code{org-export-with-tasks} -@item @code{:priority} @tab @code{org-export-with-priority} -@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} -@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} -@item @code{:latex-listings} @tab @code{org-export-latex-listings} -@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading} -@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} -@item @code{:timestamps} @tab @code{org-export-with-timestamps} -@item @code{:author} @tab @code{user-full-name} -@item @code{:email} @tab @code{user-mail-address} : @code{addr;addr;..} -@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} -@item @code{:style-include-default} @tab @code{org-export-html-style-include-default} -@item @code{:style-include-scripts} @tab @code{org-export-html-style-include-scripts} -@item @code{:style} @tab @code{org-export-html-style} -@item @code{:style-extra} @tab @code{org-export-html-style-extra} -@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html} -@item @code{:inline-images} @tab @code{org-export-html-inline-images} -@item @code{:html-extension} @tab @code{org-export-html-extension} -@item @code{:html-preamble} @tab @code{org-export-html-preamble} -@item @code{:html-postamble} @tab @code{org-export-html-postamble} -@item @code{:xml-declaration} @tab @code{org-export-html-xml-declaration} -@item @code{:html-table-tag} @tab @code{org-export-html-table-tag} -@item @code{:expand-quoted-html} @tab @code{org-export-html-expand} -@item @code{:timestamp} @tab @code{org-export-html-with-timestamp} -@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} +@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} @item @code{:select-tags} @tab @code{org-export-select-tags} -@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} -@item @code{:latex-image-options} @tab @code{org-export-latex-image-default-option} +@item @code{:with-author} @tab @code{org-export-with-author} +@item @code{:with-creator} @tab @code{org-export-with-creator} +@item @code{:with-drawers} @tab @code{org-export-with-drawers} +@item @code{:with-email} @tab @code{org-export-with-email} +@item @code{:with-emphasize} @tab @code{org-export-with-emphasize} +@item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width} +@item @code{:with-footnotes} @tab @code{org-export-with-footnotes} +@item @code{:with-latex} @tab @code{org-export-with-latex} +@item @code{:with-planning} @tab @code{org-export-with-planning} +@item @code{:with-priority} @tab @code{org-export-with-priority} +@item @code{:with-special-strings} @tab @code{org-export-with-special-strings} +@item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts} +@item @code{:with-tables} @tab @code{org-export-with-tables} +@item @code{:with-tags} @tab @code{org-export-with-tags} +@item @code{:with-tasks} @tab @code{org-export-with-tasks} +@item @code{:with-timestamps} @tab @code{org-export-with-timestamps} +@item @code{:with-toc} @tab @code{org-export-with-toc} +@item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords} @end multitable -Most of the @code{org-export-with-*} variables have the same effect in -both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and -@code{:LaTeX-fragments} options, respectively @code{nil} and @code{t} in the -@LaTeX{} export. See @code{org-export-plist-vars} to check this list of -options. - +@vindex org-html-doctype +@vindex org-html-container-element +@vindex org-html-html5-fancy +@vindex org-html-xml-declaration +@vindex org-html-link-up +@vindex org-html-link-home +@vindex org-html-link-org-files-as-html +@vindex org-html-link-use-abs-url +@vindex org-html-head +@vindex org-html-head-extra +@vindex org-html-inline-images +@vindex org-html-extension +@vindex org-html-preamble +@vindex org-html-postamble +@vindex org-html-table-default-attributes +@vindex org-html-table-row-tags +@vindex org-html-head-include-default-style +@vindex org-html-head-include-scripts +@multitable @columnfractions 0.32 0.68 +@item @code{:html-doctype} @tab @code{org-html-doctype} +@item @code{:html-container} @tab @code{org-html-container-element} +@item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy} +@item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration} +@item @code{:html-link-up} @tab @code{org-html-link-up} +@item @code{:html-link-home} @tab @code{org-html-link-home} +@item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html} +@item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url} +@item @code{:html-head} @tab @code{org-html-head} +@item @code{:html-head-extra} @tab @code{org-html-head-extra} +@item @code{:html-inline-images} @tab @code{org-html-inline-images} +@item @code{:html-extension} @tab @code{org-html-extension} +@item @code{:html-preamble} @tab @code{org-html-preamble} +@item @code{:html-postamble} @tab @code{org-html-postamble} +@item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes} +@item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags} +@item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style} +@item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts} +@end multitable +Most of the @code{org-export-with-*} variables have the same effect in each +exporter. @vindex org-publish-project-alist -When a property is given a value in @code{org-publish-project-alist}, -its setting overrides the value of the corresponding user variable (if -any) during publishing. Options set within a file (@pxref{Export -options}), however, override everything. +When a property is given a value in @code{org-publish-project-alist}, its +setting overrides the value of the corresponding user variable (if any) +during publishing. Options set within a file (@pxref{Export settings}), +however, override everything. @node Publishing links, Sitemap, Publishing options, Configuration @subsection Links between published files @cindex links, publishing -To create a link from one Org file to another, you would use -something like @samp{[[file:foo.org][The foo]]} or simply -@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this link -becomes a link to @file{foo.html}. In this way, you can interlink the -pages of your "org web" project and the links will work as expected when -you publish them to HTML@. If you also publish the Org source file and want -to link to that, use an @code{http:} link instead of a @code{file:} link, -because @code{file:} links are converted to link to the corresponding -@file{html} file. +To create a link from one Org file to another, you would use something like +@samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org.} +(@pxref{Hyperlinks}). When published, this link becomes a link to +@file{foo.html}. You can thus interlink the pages of your "org web" project +and the links will work as expected when you publish them to HTML@. If you +also publish the Org source file and want to link to it, use an @code{http:} +link instead of a @code{file:} link, because @code{file:} links are converted +to link to the corresponding @file{html} file. You may also link to related files, such as images. Provided you are careful with relative file names, and provided you have also configured Org to upload the related files, these links will work too. See @ref{Complex example}, for an example of this usage. -Sometimes an Org file to be published may contain links that are -only valid in your production environment, but not in the publishing -location. In this case, use the property - -@multitable @columnfractions 0.4 0.6 -@item @code{:link-validation-function} -@tab Function to validate links -@end multitable - -@noindent -to define a function for checking link validity. This function must -accept two arguments, the file name and a directory relative to which -the file name is interpreted in the production environment. If this -function returns @code{nil}, then the HTML generator will only insert a -description into the HTML file, but no link. One option for this -function is @code{org-publish-validate-link} which checks if the given -file is part of any project in @code{org-publish-project-alist}. - @node Sitemap, Generating an index, Publishing links, Configuration @subsection Generating a sitemap @cindex sitemap, of published pages @@ -12480,7 +13765,7 @@ a map of files for a given project. @multitable @columnfractions 0.35 0.65 @item @code{:auto-sitemap} -@tab When non-nil, publish a sitemap during @code{org-publish-current-project} +@tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project} or @code{org-publish-all}. @item @code{:sitemap-filename} @@ -12525,7 +13810,7 @@ a sitemap entry's date is to be formatted. This property bypasses @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}. @item @code{:sitemap-sans-extension} -@tab When non-nil, remove filenames' extensions from the generated sitemap. +@tab When non-@code{nil}, remove filenames' extensions from the generated sitemap. Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}). Defaults to @code{nil}. @@ -12539,7 +13824,7 @@ 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 +@tab When non-@code{nil}, generate in index in the file @file{theindex.org} and publish it as @file{theindex.html}. @end multitable @@ -12605,10 +13890,10 @@ directory on the local machine. :base-directory "~/org/" :publishing-directory "~/public_html" :section-numbers nil - :table-of-contents nil - :style "<link rel=\"stylesheet\" - href=\"../other/mystyle.css\" - type=\"text/css\"/>"))) + :with-toc nil + :html-head "<link rel=\"stylesheet\" + href=\"../other/mystyle.css\" + type=\"text/css\"/>"))) @end lisp @node Complex example, , Simple example, Sample configuration @@ -12638,12 +13923,12 @@ right place on the web server, and publishing images to it. :base-directory "~/org/" :base-extension "org" :publishing-directory "/ssh:user@@host:~/html/notebook/" - :publishing-function org-publish-org-to-html + :publishing-function org-html-publish-to-html :exclude "PrivatePage.org" ;; regexp :headline-levels 3 :section-numbers nil - :table-of-contents nil - :style "<link rel=\"stylesheet\" + :with-toc nil + :html-head "<link rel=\"stylesheet\" href=\"../other/mystyle.css\" type=\"text/css\"/>" :html-preamble t) @@ -12667,13 +13952,13 @@ right place on the web server, and publishing images to it. Once properly configured, Org can publish with the following commands: @table @kbd -@orgcmd{C-c C-e X,org-publish} +@orgcmd{C-c C-e P x,org-publish} Prompt for a specific project and publish all files that belong to it. -@orgcmd{C-c C-e P,org-publish-current-project} +@orgcmd{C-c C-e P p,org-publish-current-project} Publish the project containing the current file. -@orgcmd{C-c C-e F,org-publish-current-file} +@orgcmd{C-c C-e P f,org-publish-current-file} Publish only the current file. -@orgcmd{C-c C-e E,org-publish-all} +@orgcmd{C-c C-e P a,org-publish-all} Publish every project. @end table @@ -12770,7 +14055,7 @@ src_<language>[<header arguments>]@{<body>@} @table @code @item <#+NAME: name> This line associates a name with the code block. This is similar to the -@code{#+TBLNAME: NAME} lines that can be used to name tables in Org mode +@code{#+NAME: Name} 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, from other files, or from Org mode table formulas (see @ref{The spreadsheet}). Names are assumed to be unique @@ -12802,11 +14087,16 @@ Source code in the specified language. @cindex code block, editing @cindex source code, editing +@vindex org-edit-src-auto-save-idle-delay +@vindex org-edit-src-turn-on-auto-save @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. +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. Manually +saving this buffer with @key{C-x C-s} will write the contents back to the Org +buffer. You can also set @code{org-edit-src-auto-save-idle-delay} to save the +base buffer after some idle delay, or @code{org-edit-src-turn-on-auto-save} +to auto-save this buffer into a separate file using @code{auto-save-mode}. +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 @@ -12822,11 +14112,16 @@ 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. +By default, the value is @code{nil}, which means that when code blocks are +evaluated during export or tangled, they are re-inserted into the code block, +which may replace sequences of spaces with tab characters. When non-nil, +whitespace in code blocks will be preserved during export or tangling, +exactly as it appears. 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. +variable to @code{nil} to switch without asking. @end table To turn on native code fontification in the @emph{Org} buffer, configure the @@ -12851,6 +14146,7 @@ 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 @@ -12872,7 +14168,12 @@ 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. +markup language for a wiki. It is also possible to set this variable to +@code{'inline-only}. In that case, only inline code blocks will be +evaluated, in order to insert their results. Non-inline code blocks are +assumed to have their results already inserted in the buffer by manual +evaluation. This setting is useful to avoid expensive recalculations during +export, not to provide security. @comment node-name, next, previous, up @comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code @@ -12889,6 +14190,7 @@ 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. @@ -12902,14 +14204,18 @@ Include the code block in the tangled output to file @samp{filename}. @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}. + +With prefix argument only tangle the current code block. @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}. @@ -12917,6 +14223,21 @@ Example applications could include post-processing, compilation or evaluation of tangled code files. @end table +@subsubheading Jumping between code and Org + +When tangling code from an Org-mode buffer to a source code file, you'll +frequently find yourself viewing the file of tangled source code (e.g., many +debuggers point to lines of the source code file). It is useful to be able +to navigate from the tangled source to the Org-mode buffer from which the +code originated. + +The @code{org-babel-tangle-jump-to-org} function provides this jumping from +code to Org-mode functionality. Two header arguments are required for +jumping to work, first the @code{padline} (@ref{padline}) option must be set +to true (the default setting), second the @code{comments} (@ref{comments}) +header argument must be set to @code{links}, which will insert comments into +the source code buffer which point back to the original Org-mode file. + @node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code @section Evaluating code blocks @cindex code block, evaluating @@ -12943,7 +14264,7 @@ 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 +option @code{org-babel-no-eval-on-ctrl-c-ctrl-c} 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. @@ -13054,10 +14375,10 @@ Language-specific documentation is available for some languages. If available, it can be found at @uref{http://orgmode.org/worg/org-contrib/babel/languages.html}. -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. +The option @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 @@ -13099,13 +14420,16 @@ describes each header argument in detail. @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. +The values of header arguments can be set in several way. When the header +arguments in each layer have been determined, they are combined in order from +the first, least specific (having the lowest priority) up to the last, most +specific (having the highest priority). A header argument with a higher +priority replaces the same header argument specified at lower priority. @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 +* Language-specific header arguments in Org mode properties:: Set language-specific 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 @@ -13114,7 +14438,7 @@ specific (and having higher priority) than the last. @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 +System-wide values of header arguments can be specified by adapting the @code{org-babel-default-header-args} variable: @example @@ -13125,20 +14449,6 @@ System-wide values of header arguments can be specified by customizing the :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 @@ -13147,64 +14457,88 @@ blocks. @lisp (setq org-babel-default-header-args (cons '(:noweb . "yes") - (assq-delete-all :noweb org-babel-default-header-args))) + (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 +@node Language-specific header arguments, Header arguments in Org mode properties, 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 +Each language can define its own set of default header arguments in variable +@code{org-babel-default-header-args:<lang>}, where @code{<lang>} is the name +of the language. 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 +@node Header arguments in Org mode properties, Language-specific header arguments in Org mode properties, Language-specific header arguments, Using header arguments +@subsubheading Header arguments in Org mode properties + Buffer-wide header arguments may be specified as properties through the use of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see @ref{Property 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. +For example the following would set @code{session} to @code{*R*} (only for R +code blocks), 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 -#+PROPERTY: session *R* -#+PROPERTY: 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 +#+PROPERTY: header-args:R :session *R* +#+PROPERTY: header-args :results silent @end example +Header arguments read from Org mode properties can also be set on a +per-subtree basis using property drawers (see @ref{Property syntax}). @vindex org-use-property-inheritance -When properties are used to set default header arguments, they are looked up -with inheritance, regardless of the value of -@code{org-use-property-inheritance}. In the following example the value of +When properties are used to set default header arguments, they are always +looked up with inheritance, regardless of the value of +@code{org-use-property-inheritance}. Properties are evaluated as seen by the +outermost call or source block.@footnote{The deprecated syntax for default +header argument properties, using the name of the header argument as a +property name directly, evaluates the property as seen by the corresponding +source block definition. This behavior has been kept for backwards +compatibility.} + +In the following example 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 + :header-args: :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. +@code{org-babel-default-header-args} and are applied for all activated +languages. 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 Language-specific header arguments in Org mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments +@subsubheading Language-specific header arguments in Org mode properties + +Language-specific header arguments are also read from properties +@code{header-args:<lang>} where @code{<lang>} is the name of the language +targeted. As an example + +@example +* Heading + :PROPERTIES: + :header-args:clojure: :session *clojure-1* + :header-args:R: :session *R* + :END: +** Subheading + :PROPERTIES: + :header-args:clojure: :session *clojure-2* + :END: +@end example -@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org mode properties, Using header arguments +would independently set a default session header argument for R and clojure +for calls and source blocks under subtree ``Heading'' and change to a +different clojure setting for evaluations under subtree ``Subheading'', while +the R session is inherited from ``Heading'' and therefore unchanged. + +@node Code block specific header arguments, Header arguments in function calls, Language-specific 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 @@ -13318,8 +14652,12 @@ argument in lowercase letters. The following header arguments are defined: * colnames:: Handle column names in tables * rownames:: Handle row names in tables * shebang:: Make tangled files executable +* tangle-mode:: Set permission of tangled files * eval:: Limit evaluation of specific code blocks * wrap:: Mark source block evaluation results +* post:: Post processing of code block results +* prologue:: Text to prepend to code block body +* epilogue:: Text to append to code block body @end menu Additional header arguments are defined on a language-specific basis, see @@ -13334,11 +14672,13 @@ syntax used to specify arguments is the same across all languages. In every case, variables require a default value when they are declared. The values passed to arguments can either be literal values, references, or -Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References -include anything in the Org mode file that takes a @code{#+NAME:}, -@code{#+TBLNAME:}, or @code{#+RESULTS:} line. This includes tables, lists, -@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other -code blocks. +Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). +References include anything in the Org mode file that takes a @code{#+NAME:} +or @code{#+RESULTS:} line: tables, lists, @code{#+BEGIN_EXAMPLE} blocks, +other code blocks and the results of other code blocks. + +Note: When a reference is made to another code block, the referenced block +will be evaluated unless it has current cached results (see @ref{cache}). Argument values can be indexed in a manner similar to arrays (see @ref{var, Indexable variable values}). @@ -13360,10 +14700,10 @@ Here are examples of passing values by reference: @table @dfn @item table -an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line +an Org mode table named with either a @code{#+NAME:} line @example -#+TBLNAME: example-table +#+NAME: example-table | 1 | | 2 | | 3 | @@ -13456,19 +14796,6 @@ on two lines @end table -@subsubheading Alternate argument syntax -It is also possible to specify arguments in a potentially more natural way -using the @code{#+NAME:} line of a code block. As in the following -example, arguments can be packed inside of parentheses, separated by commas, -following the source name. - -@example -#+NAME: 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 @@ -13593,7 +14920,7 @@ Emacs Lisp, as shown in the following example. @node results, file, var, Specific header arguments @subsubsection @code{:results} -There are three classes of @code{:results} header argument. Only one option +There are four classes of @code{:results} header argument. Only one option per class may be supplied per code block. @itemize @bullet @@ -13602,6 +14929,10 @@ per class may be supplied per code block. 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 processed before +insertion into the Org mode buffer +@item +@b{format} 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 @@ -13647,6 +14978,15 @@ 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}. +@end itemize + +@subsubheading Format + +The following options are mutually exclusive and specify what type of results +the code block will return. By default, results are inserted according to the +type as specified above. + +@itemize @bullet @item @code{raw} 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 @@ -13728,7 +15068,7 @@ 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 +the same effect as changing the current directory with @kbd{M-x cd path RET}, and then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets the value of the Emacs variable @code{default-directory}. @@ -13853,7 +15193,6 @@ original Org file from which the code was tangled. 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} @@ -13925,7 +15264,7 @@ references will not be expanded when the code block is exported. @item @code{strip-export} ``Noweb'' syntax references in the body of the code block will be expanded before the block is evaluated or tangled. However, ``noweb'' syntax -references will not be removed when the code block is exported. +references will be removed when the code block is exported. @item @code{eval} ``Noweb'' syntax references in the body of the code block will only be expanded before the block is evaluated. @@ -14085,7 +15424,7 @@ variable and raises an error. Setting @code{:hlines no} or relying on the default value yields the following results. @example -#+TBLNAME: many-cols +#+NAME: many-cols | a | b | c | |---+---+---| | d | e | f | @@ -14107,7 +15446,7 @@ default value yields the following results. Leaves hlines in the table. Setting @code{:hlines yes} has this effect. @example -#+TBLNAME: many-cols +#+NAME: many-cols | a | b | c | |---+---+---| | d | e | f | @@ -14134,9 +15473,7 @@ Leaves hlines in the table. Setting @code{:hlines yes} has this effect. The @code{:colnames} header argument accepts the values @code{yes}, @code{no}, or @code{nil} for unassigned. The default value is @code{nil}. Note that the behavior of the @code{:colnames} header argument may differ -across languages. For example Emacs Lisp code blocks ignore the -@code{:colnames} header argument entirely given the ease with which tables -with column names may be handled directly in Emacs Lisp. +across languages. @itemize @bullet @item @code{nil} @@ -14146,7 +15483,7 @@ names will be removed from the table before processing, then reapplied to the results. @example -#+TBLNAME: less-cols +#+NAME: less-cols | a | |---| | b | @@ -14179,8 +15516,10 @@ hline) @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}. +The @code{:rownames} header argument can take on the values @code{yes} or +@code{no}, with a default value of @code{no}. Note that Emacs Lisp code +blocks ignore the @code{:rownames} header argument entirely given the ease +with which tables with row names may be handled directly in Emacs Lisp. @itemize @bullet @item @code{no} @@ -14191,7 +15530,7 @@ The first column of the table is removed from the table before processing, and is then reapplied to the results. @example -#+TBLNAME: with-rownames +#+NAME: with-rownames | one | 1 | 2 | 3 | 4 | 5 | | two | 6 | 7 | 8 | 9 | 10 | @@ -14210,7 +15549,7 @@ variable indexing @xref{var, Indexable variable values}. @end itemize -@node shebang, eval, rownames, Specific header arguments +@node shebang, tangle-mode, rownames, Specific header arguments @subsubsection @code{:shebang} Setting the @code{:shebang} header argument to a string value @@ -14218,7 +15557,21 @@ Setting the @code{:shebang} header argument to a string value 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, wrap, shebang, Specific header arguments + +@node tangle-mode, eval, shebang, Specific header arguments +@subsubsection @code{:tangle-mode} + +The @code{tangle-mode} header argument controls the permission set on tangled +files. The value of this header argument will be passed to +@code{set-file-modes}. For example, to set a tangled file as read only use +@code{:tangle-mode (identity #o444)}, or to set a tangled file as executable +use @code{:tangle-mode (identity #o755)}. Blocks with @code{shebang} +(@ref{shebang}) header arguments will automatically be made executable unless +the @code{tangle-mode} header argument is also used. The behavior is +undefined if multiple code blocks with different values for the +@code{tangle-mode} header argument are tangled to the same file. + +@node eval, wrap, tangle-mode, Specific header arguments @subsubsection @code{:eval} The @code{:eval} header argument can be used to limit the evaluation of specific code blocks. The @code{:eval} header argument can be useful for @@ -14243,7 +15596,7 @@ If this header argument is not set then evaluation is determined by the value of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation security}. -@node wrap, , eval, Specific header arguments +@node wrap, post, eval, Specific header arguments @subsubsection @code{:wrap} The @code{:wrap} header argument is used to mark the results of source block evaluation. The header argument can be passed a string that will be appended @@ -14251,6 +15604,59 @@ to @code{#+BEGIN_} and @code{#+END_}, which will then be used to wrap the results. If not string is specified then the results will be wrapped in a @code{#+BEGIN/END_RESULTS} block. +@node post, prologue, wrap, Specific header arguments +@subsubsection @code{:post} +The @code{:post} header argument is used to post-process the results of a +code block execution. When a post argument is given, the results of the code +block will temporarily be bound to the @code{*this*} variable. This variable +may then be included in header argument forms such as those used in @ref{var} +header argument specifications allowing passing of results to other code +blocks, or direct execution via Emacs Lisp. + +The following example illustrates the usage of the @code{:post} header +argument. + +@example +#+name: attr_wrap +#+begin_src sh :var data="" :var width="\\textwidth" :results output + echo "#+ATTR_LATEX :width $width" + echo "$data" +#+end_src + +#+header: :file /tmp/it.png +#+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer + digraph@{ + a -> b; + b -> c; + c -> a; + @} +#+end_src + +#+RESULTS: +:RESULTS: +#+ATTR_LATEX :width 5cm +[[file:/tmp/it.png]] +:END: +@end example + +@node prologue, epilogue, post, Specific header arguments +@subsubsection @code{:prologue} +The value of the @code{prologue} header argument will be prepended to the +code block body before execution. For example, @code{:prologue "reset"} may +be used to reset a gnuplot session before execution of a particular code +block, or the following configuration may be used to do this for all gnuplot +code blocks. Also see @ref{epilogue}. + +@lisp +(add-to-list 'org-babel-default-header-args:gnuplot + '((:prologue . "reset"))) +@end lisp + +@node epilogue, , prologue, Specific header arguments +@subsubsection @code{:epilogue} +The value of the @code{epilogue} header argument will be appended to the code +block body before execution. Also see @ref{prologue}. + @node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code @section Results of evaluation @cindex code block, results of evaluation @@ -14325,7 +15731,7 @@ process. For example, compare the following two blocks: : bye @end example -In non-session mode, the `2' is not printed and does not appear. +In non-session mode, the ``2'' is not printed and does not appear. @example #+BEGIN_SRC python :results output :session @@ -14340,8 +15746,8 @@ In non-session mode, the `2' is not printed and does not appear. : 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 +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 @@ -14380,7 +15786,7 @@ syntactically valid in languages that you use, then please consider setting the default value. Note: if noweb tangling is slow in large Org mode files consider setting the -@code{*org-babel-use-quick-and-dirty-noweb-expansion*} variable to true. +@code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}. This will result in faster noweb reference resolution at the expense of not correctly resolving inherited values of the @code{:noweb-ref} header argument. @@ -14400,10 +15806,10 @@ are active: @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block} @kindex C-c C-o @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result} -@kindex C-up -@item @kbd{C-@key{up}} @tab @code{org-babel-load-in-session} +@kindex M-up +@item @kbd{M-@key{up}} @tab @code{org-babel-load-in-session} @kindex M-down -@item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session} +@item @kbd{M-@key{down}} @tab @code{org-babel-switch-to-session} @end multitable In an Org mode buffer, the following key bindings are active: @@ -14540,7 +15946,7 @@ emacs -Q --batch \ * Clean view:: Getting rid of leading stars in the outline * TTY keys:: Using Org on a tty * Interaction:: Other Emacs packages -* org-crypt.el:: Encrypting Org files +* org-crypt:: Encrypting Org files @end menu @@ -14694,19 +16100,19 @@ which take off the default security brakes. @defopt org-confirm-babel-evaluate When t (the default), the user is asked before every code block evaluation. -When nil, the user is not asked. When set to a function, it is called with +When @code{nil}, the user is not asked. When set to a function, it is called with two arguments (language and body of the code block) and should return t to -ask and nil not to ask. +ask and @code{nil} not to ask. @end defopt For example, here is how to execute "ditaa" code (which is considered safe) without asking: -@example +@lisp (defun my-org-confirm-babel-evaluate (lang body) (not (string= lang "ditaa"))) ; don't ask for ditaa (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate) -@end example +@end lisp @item Following @code{shell} and @code{elisp} links Org has two link types that can directly evaluate code (@pxref{External @@ -14734,7 +16140,7 @@ either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter. There are more than 500 variables that can be used to customize Org. For the sake of compactness of the manual, I am not describing the variables here. A structured overview of customization -variables is available with @kbd{M-x org-customize}. Or select +variables is available with @kbd{M-x org-customize RET}. Or select @code{Browse Org Group} from the @code{Org->Customization} menu. Many settings can also be activated on a per-file basis, by putting special lines into the buffer (@pxref{In-buffer settings}). @@ -14765,7 +16171,7 @@ The corresponding variable is @code{org-archive-location}. This line sets the category for the agenda file. The category applies for all subsequent lines until the next @samp{#+CATEGORY} line, or the end of the file. The first such line also applies to any entries before it. -@item #+COLUMNS: %25ITEM ..... +@item #+COLUMNS: %25ITEM ... @cindex property, COLUMNS Set the default format for columns view. This format applies when columns view is invoked in locations where no @code{COLUMNS} property @@ -14780,11 +16186,11 @@ The global version of this variable is @item #+FILETAGS: :tag1:tag2:tag3: Set tags that can be inherited by any entry in the file, including the top-level entries. -@item #+DRAWERS: NAME1 ..... +@item #+DRAWERS: NAME1 ... @vindex org-drawers Set the file-local set of additional drawers. The corresponding global variable is @code{org-drawers}. -@item #+LINK: linkword replace +@item #+LINK: linkword replace @vindex org-link-abbrev-alist These lines (several are allowed) specify link abbreviations. @xref{Link abbreviations}. The corresponding variable is @@ -14809,7 +16215,7 @@ as if they had been included in the buffer. In particular, the file can be any other Org mode file with internal setup. You can visit the file the cursor is in the line with @kbd{C-c '}. @item #+STARTUP: -@cindex #+STARTUP: +@cindex #+STARTUP This line sets options to be used at startup of Org mode, when an Org file is being visited. @@ -14862,6 +16268,18 @@ inlineimages @r{show inline images} noinlineimages @r{don't show inline images on startup} @end example +@vindex org-startup-with-latex-preview +When visiting a file, @LaTeX{} fragments can be converted to images +automatically. The variable @code{org-startup-with-latex-preview} which +controls this behavior, is set to @code{nil} by default to avoid delays on +startup. +@cindex @code{latexpreview}, STARTUP keyword +@cindex @code{nolatexpreview}, STARTUP keyword +@example +latexpreview @r{preview @LaTeX{} fragments} +nolatexpreview @r{don't preview @LaTeX{} fragments} +@end example + @vindex org-log-done @vindex org-log-note-clock-out @vindex org-log-repeat @@ -14885,25 +16303,34 @@ configured using these options (see variables @code{org-log-done}, @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} -nologdone @r{don't record when items are marked DONE} -logrepeat @r{record a time when reinstating a repeating item} -lognoterepeat @r{record a note when reinstating a repeating item} -nologrepeat @r{do not record when reinstating repeating item} -lognoteclock-out @r{record a note when clocking out} -nolognoteclock-out @r{don't record a note when clocking out} -logreschedule @r{record a timestamp when scheduling time changes} -lognotereschedule @r{record a note when scheduling time changes} -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} +@cindex @code{logdrawer}, STARTUP keyword +@cindex @code{nologdrawer}, STARTUP keyword +@cindex @code{logstatesreversed}, STARTUP keyword +@cindex @code{nologstatesreversed}, STARTUP keyword +@example +logdone @r{record a timestamp when an item is marked DONE} +lognotedone @r{record timestamp and a note when DONE} +nologdone @r{don't record when items are marked DONE} +logrepeat @r{record a time when reinstating a repeating item} +lognoterepeat @r{record a note when reinstating a repeating item} +nologrepeat @r{do not record when reinstating repeating item} +lognoteclock-out @r{record a note when clocking out} +nolognoteclock-out @r{don't record a note when clocking out} +logreschedule @r{record a timestamp when scheduling time changes} +lognotereschedule @r{record a note when scheduling time changes} +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} +logdrawer @r{store log into drawer} +nologdrawer @r{store log outside of drawer} +logstatesreversed @r{reverse the order of states notes} +nologstatesreversed @r{do not reverse the order of states notes} @end example + @vindex org-hide-leading-stars @vindex org-odd-levels-only Here are the options for hiding leading stars in outline headings, and for @@ -14922,6 +16349,7 @@ noindent @r{no virtual indentation according to outline level} odd @r{allow only odd outline levels (1,3,...)} oddeven @r{allow all outline levels} @end example + @vindex org-put-time-stamp-overlays @vindex org-time-stamp-overlay-formats To turn on custom format overlays over timestamps (variables @@ -14931,6 +16359,7 @@ To turn on custom format overlays over timestamps (variables @example customtime @r{overlay custom time format} @end example + @vindex constants-unit-system The following options influence the table spreadsheet (variable @code{constants-unit-system}). @@ -14940,6 +16369,7 @@ The following options influence the table spreadsheet (variable constcgs @r{@file{constants.el} should use the c-g-s unit system} constSI @r{@file{constants.el} should use the SI unit system} @end example + @vindex org-footnote-define-inline @vindex org-footnote-auto-label @vindex org-footnote-auto-adjust @@ -14966,6 +16396,7 @@ fnplain @r{create @code{[1]}-like labels automatically} fnadjust @r{automatically renumber and sort footnotes} nofnadjust @r{do not renumber and sort automatically} @end example + @cindex org-hide-block-startup To hide blocks on startup, use these keywords. The corresponding variable is @code{org-hide-block-startup}. @@ -14975,6 +16406,7 @@ 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 @@ -14984,20 +16416,29 @@ The display of entities as UTF-8 characters is governed by the variable 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 this file, and (potentially) the corresponding @emph{fast tag selection} keys. The corresponding variable is @code{org-tag-alist}. +@cindex #+TBLFM @item #+TBLFM: This line contains the formulas for the table directly above the line. -@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:, -@itemx #+OPTIONS:, #+BIND:, #+XSLT:, + +Table can have multiple lines containing @samp{#+TBLFM:}. Note +that only the first line of @samp{#+TBLFM:} will be applied when +you recalculate the table. For more details see @ref{Using +multiple #+TBLFM lines} in @ref{Editing and debugging formulas}. + +@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:, +@itemx #+OPTIONS:, #+BIND:, @itemx #+DESCRIPTION:, #+KEYWORDS:, -@itemx #+LaTeX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:, -@itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS: +@itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:, +@itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:, +@itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS: These lines provide settings for exporting files. For more details see -@ref{Export options}. +@ref{Export settings}. @item #+TODO: #+SEQ_TODO: #+TYP_TODO: @vindex org-todo-keywords These lines set the TODO keywords and their interpretation in the @@ -15042,7 +16483,7 @@ If the cursor is in a property line or at the start or end of a property drawer, offer property commands. @item If the cursor is at a footnote reference, go to the corresponding -definition, and vice versa. +definition, and @emph{vice versa}. @item If the cursor is on a statistics cookie, update it. @item @@ -15221,7 +16662,7 @@ tty you would rather use @kbd{C-c .} to re-insert the timestamp. @end multitable -@node Interaction, org-crypt.el, TTY keys, Miscellaneous +@node Interaction, org-crypt, TTY keys, Miscellaneous @section Interaction with other packages @cindex packages, interaction with other Org lives in the world of GNU Emacs and interacts in various ways @@ -15367,6 +16808,18 @@ Yes, these are unfortunately more difficult to remember. If you want to have other replacement keys, look at the variable @code{org-disputed-keys}. +@item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org} +@cindex @file{ecomplete.el} + +Ecomplete provides ``electric'' address completion in address header +lines in message buffers. Sadly Orgtbl mode cuts ecompletes power +supply: No completion happens when Orgtbl mode is enabled in message +buffers while entering text in address header lines. If one wants to +use ecomplete one should @emph{not} follow the advice to automagically +turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but +instead---after filling in the message headers---turn on Orgtbl mode +manually when needed in the messages body. + @item @file{filladapt.el} by Kyle Jones @cindex @file{filladapt.el} @@ -15381,7 +16834,7 @@ this: @item @file{yasnippet.el} @cindex @file{yasnippet.el} -The way Org mode binds the TAB key (binding to @code{[tab]} instead of +The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of @code{"\t"}) overrules YASnippet's access to this key. The following code fixed this problem: @@ -15406,10 +16859,10 @@ Then, tell Org mode what to do with the new function: @lisp (add-hook 'org-mode-hook (lambda () - (make-variable-buffer-local 'yas/trigger-key) - (setq yas/trigger-key [tab]) - (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) - (define-key yas/keymap [tab] 'yas/next-field))) + (make-variable-buffer-local 'yas/trigger-key) + (setq yas/trigger-key [tab]) + (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) + (define-key yas/keymap [tab] 'yas/next-field))) @end lisp @item @file{windmove.el} by Hovav Shacham @@ -15440,9 +16893,11 @@ another key for this command, or override the key in (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree) @end lisp + + @end table -@node org-crypt.el, , Interaction, Miscellaneous +@node org-crypt, , Interaction, Miscellaneous @section org-crypt.el @cindex @file{org-crypt.el} @cindex @code{org-decrypt-entry} @@ -15458,7 +16913,7 @@ customize the @code{org-crypt-tag-matcher} setting. To use org-crypt it is suggested that you have the following in your @file{.emacs}: -@example +@lisp (require 'org-crypt) (org-crypt-use-before-save-magic) (setq org-tags-exclude-from-inheritance (quote ("crypt"))) @@ -15476,7 +16931,7 @@ To use org-crypt it is suggested that you have the following in your ;; To turn it off only locally, you can insert this: ;; ;; # -*- buffer-auto-save-file-name: nil; -*- -@end example +@end lisp Excluding the crypt tag from inheritance prevents already encrypted text being encrypted again. @@ -15492,11 +16947,13 @@ Org. * Hooks:: How to reach into Org's internals * Add-on packages:: Available extensions * Adding hyperlink types:: New custom link types +* Adding export back-ends:: How to write new export back-ends * Context-sensitive commands:: How to add functionality to such commands * 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 +* Speeding up your agendas:: Tips on how to speed up your agendas +* Extracting agenda information:: Post-processing of agenda information * Using the property API:: Writing programs that use entry properties * Using the mapping API:: Mapping over all or selected entries @end menu @@ -15516,15 +16973,14 @@ maintained by the Worg project and can be found at @cindex add-on packages 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 -@uref{http://orgmode.org}. The list of contributed packages, along with -documentation about each package, is maintained by the Worg project at +packages with the separate release available at @uref{http://orgmode.org}. +See the @file{contrib/README} file in the source code directory for a list of +contributed files. You may also find some more information on the Worg page: @uref{http://orgmode.org/worg/org-contrib/}. - - -@node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking +@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking @section Adding hyperlink types @cindex hyperlinks, adding new types @@ -15627,7 +17083,37 @@ When it makes sense for your new link type, you may also define a function 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. -@node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking +@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking +@section Adding export back-ends +@cindex Export, writing back-ends + +Org 8.0 comes with a completely rewritten export engine which makes it easy +to write new export back-ends, either from scratch, or from deriving them +from existing ones. + +Your two entry points are respectively @code{org-export-define-backend} and +@code{org-export-define-derived-backend}. To grok these functions, you +should first have a look at @file{ox-latex.el} (for how to define a new +back-end from scratch) and @file{ox-beamer.el} (for how to derive a new +back-end from an existing one. + +When creating a new back-end from scratch, the basic idea is to set the name +of the back-end (as a symbol) and an an alist of elements and export +functions. On top of this, you will need to set additional keywords like +@code{:menu-entry} (to display the back-end in the export dispatcher), +@code{:export-block} (to specify what blocks should not be exported by this +back-end), and @code{:options-alist} (to let the user set export options that +are specific to this back-end.) + +Deriving a new back-end is similar, except that you need to set +@code{:translate-alist} to an alist of export functions that should be used +instead of the parent back-end functions. + +For a complete reference documentation, see +@url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export +Reference on Worg}. + +@node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking @section Context-sensitive commands @cindex context-sensitive commands, hooks @cindex add-ons, context-sensitive commands @@ -15696,7 +17182,7 @@ can use Org's facilities to edit and structure lists by turning * Radio tables:: Sending and receiving radio tables * A @LaTeX{} example:: Step by step, almost a tutorial * Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists +* Radio lists:: Sending and receiving lists @end menu @node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax @@ -15704,9 +17190,10 @@ can use Org's facilities to edit and structure lists by turning @cindex radio tables To define the location of the target table, you first need to create two -lines that are comments in the current mode, but contain magic words for -Orgtbl mode to find. Orgtbl mode will insert the translated table -between these lines, replacing whatever was there before. For example: +lines that are comments in the current mode, but contain magic words +@code{BEGIN/END RECEIVE ORGTBL} for Orgtbl mode to find. Orgtbl mode will +insert the translated table between these lines, replacing whatever was there +before. For example in C mode where comments are between @code{/* ... */}: @example /* BEGIN RECEIVE ORGTBL table_name */ @@ -15719,7 +17206,7 @@ Orgtbl mode how to translate this table and where to install it. For example: @cindex #+ORGTBL @example -#+ORGTBL: SEND table_name translation_function arguments.... +#+ORGTBL: SEND table_name translation_function arguments... @end example @noindent @@ -15744,8 +17231,8 @@ removal of these columns, the function never knows that there have been additional columns. @item :no-escape t -When non-nil, do not escape special characters @code{&%#_^} when exporting -the table. The default value is nil. +When non-@code{nil}, do not escape special characters @code{&%#_^} when exporting +the table. The default value is @code{nil}. @end table @noindent @@ -15766,7 +17253,7 @@ 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 -only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment} +only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment RET} makes this comment-toggling very easy, in particular if you bind it to a key. @end itemize @@ -15780,8 +17267,8 @@ The best way to wrap the source table in @LaTeX{} is to use the 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 @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 +variable @code{orgtbl-radio-table-templates} to install templates for other +modes.} with the command @kbd{M-x orgtbl-insert-radio-table RET}. You will be prompted for a table name, let's say we use @samp{salesfigures}. You will then get the following template: @@ -15860,7 +17347,7 @@ interprets the following parameters (see also @pxref{Translator functions}): @table @code @item :splice nil/t When set to t, return only table body lines, don't wrap them into a -tabular environment. Default is nil. +tabular environment. Default is @code{nil}. @item :fmt fmt A format to be used to wrap each field, it should contain @code{%s} for the @@ -16052,7 +17539,7 @@ The corresponding block writer function could look like this: (defun org-dblock-write:block-update-time (params) (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) (insert "Last block update at: " - (format-time-string fmt (current-time))))) + (format-time-string fmt)))) @end lisp If you want to make sure that all dynamic blocks are always up-to-date, @@ -16064,21 +17551,25 @@ written in a way such that it does nothing in buffers that are not in You can narrow the current buffer to the current dynamic block (like any other block) with @code{org-narrow-to-block}. -@node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking +@node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking @section Special agenda views @cindex agenda views, user-defined @vindex org-agenda-skip-function @vindex org-agenda-skip-function-global Org provides a special hook that can be used to narrow down the selection -made by these agenda views: @code{agenda}, @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. You can specify a -global condition that will be applied to all agenda views, this condition -would be stored in the variable @code{org-agenda-skip-function-global}. More -commonly, such a definition is applied only to specific custom searches, -using @code{org-agenda-skip-function}. +made by these agenda views: @code{agenda}, @code{agenda*}@footnote{The +@code{agenda*} view is the same than @code{agenda} except that it only +considers @emph{appointments}, i.e., scheduled and deadline items that have a +time specification @code{[h]h:mm} in their time-stamps.}, @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. +You can specify a global condition that will be applied to all agenda views, +this condition would be stored in the variable +@code{org-agenda-skip-function-global}. More commonly, such a definition is +applied only to specific custom searches, using +@code{org-agenda-skip-function}. 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 @@ -16165,7 +17656,48 @@ like this, even without defining a special function: (org-agenda-overriding-header "Projects waiting for something: ")))) @end lisp -@node Extracting agenda information, Using the property API, Special agenda views, Hacking +@node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking +@section Speeding up your agendas +@cindex agenda views, optimization + +When your Org files grow in both number and size, agenda commands may start +to become slow. Below are some tips on how to speed up the agenda commands. + +@enumerate +@item +Reduce the number of Org agenda files: this will reduce the slowness caused +by accessing a hard drive. +@item +Reduce the number of DONE and archived headlines: this way the agenda does +not need to skip them. +@item +@vindex org-agenda-dim-blocked-tasks +Inhibit the dimming of blocked tasks: +@lisp +(setq org-agenda-dim-blocked-tasks nil) +@end lisp +@item +@vindex org-startup-folded +@vindex org-agenda-inhibit-startup +Inhibit agenda files startup options: +@lisp +(setq org-agenda-inhibit-startup nil) +@end lisp +@item +@vindex org-agenda-show-inherited-tags +@vindex org-agenda-use-tag-inheritance +Disable tag inheritance in agenda: +@lisp +(setq org-agenda-use-tag-inheritance nil) +@end lisp +@end enumerate + +You can set these options for specific agenda views only. See the docstrings +of these variables for details on why they affect the agenda generation, and +this @uref{http://orgmode.org/worg/agenda-optimization.html, dedicated Worg +page} for further explanations. + +@node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking @section Extracting agenda information @cindex agenda, pipe @cindex Scripts, for agenda processing @@ -16282,27 +17814,27 @@ This includes the TODO keyword, the tags, time strings for deadline, scheduled, and clocking, and any additional properties defined in the entry. The return value is an alist. Keys may occur multiple times if the property key was used several times.@* -POM may also be nil, in which case the current entry is used. -If WHICH is nil or `all', get all properties. If WHICH is -`special' or `standard', only get that subclass. +POM may also be @code{nil}, in which case the current entry is used. +If WHICH is @code{nil} or @code{all}, get all properties. If WHICH is +@code{special} or @code{standard}, only get that subclass. @end defun @vindex org-use-property-inheritance @findex org-insert-property-drawer @defun org-entry-get pom property &optional inherit -Get value of PROPERTY for entry at point-or-marker POM@. By default, -this only looks at properties defined locally in the entry. If INHERIT -is non-nil and the entry does not have the property, then also check -higher levels of the hierarchy. If INHERIT is the symbol +Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By default, +this only looks at properties defined locally in the entry. If @code{INHERIT} +is non-@code{nil} and the entry does not have the property, then also check +higher levels of the hierarchy. If @code{INHERIT} is the symbol @code{selective}, use inheritance if and only if the setting of -@code{org-use-property-inheritance} selects PROPERTY for inheritance. +@code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance. @end defun @defun org-entry-delete pom property -Delete the property PROPERTY from entry at point-or-marker POM. +Delete the property @code{PROPERTY} from entry at point-or-marker POM. @end defun @defun org-entry-put pom property value -Set PROPERTY to VALUE for entry at point-or-marker POM. +Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM. @end defun @defun org-buffer-property-keys &optional include-specials @@ -16314,28 +17846,29 @@ Insert a property drawer for the current entry. Also @end defun @defun org-entry-put-multivalued-property pom property &rest values -Set PROPERTY at point-or-marker POM to VALUES@. VALUES should be a list of -strings. They will be concatenated, with spaces as separators. +Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@. +@code{VALUES} should be a list of strings. They will be concatenated, with +spaces as separators. @end defun @defun org-entry-get-multivalued-property pom property -Treat the value of the property PROPERTY as a whitespace-separated list of -values and return the values as a list of strings. +Treat the value of the property @code{PROPERTY} as a whitespace-separated +list of values and return the values as a list of strings. @end defun @defun org-entry-add-to-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and make sure that VALUE is in this list. +Treat the value of the property @code{PROPERTY} as a whitespace-separated +list of values and make sure that @code{VALUE} is in this list. @end defun @defun org-entry-remove-from-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and make sure that VALUE is @emph{not} in this list. +Treat the value of the property @code{PROPERTY} as a whitespace-separated +list of values and make sure that @code{VALUE} is @emph{not} in this list. @end defun @defun org-entry-member-in-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and check if VALUE is in this list. +Treat the value of the property @code{PROPERTY} as a whitespace-separated +list of values and check if @code{VALUE} is in this list. @end defun @defopt org-property-allowed-value-functions @@ -16359,30 +17892,29 @@ functions for each or selected entries. The main entry point for this API is: @defun org-map-entries func &optional match scope &rest skip -Call FUNC at each headline selected by MATCH in SCOPE. +Call @code{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}. -FUNC is a function or a Lisp form. The function will be called without -arguments, with the cursor positioned at the beginning of the headline. -The return values of all calls to the function will be collected and -returned as a list. +@code{FUNC} is a function or a Lisp form. The function will be called +without arguments, with the cursor positioned at the beginning of the +headline. The return values of all calls to the function will be collected +and returned as a list. -The call to FUNC will be wrapped into a save-excursion form, so FUNC -does not need to preserve point. After evaluation, the cursor will be -moved to the end of the line (presumably of the headline of the -processed entry) and search continues from there. Under some -circumstances, this may not produce the wanted results. For example, -if you have removed (e.g., archived) the current (sub)tree it could -mean that the next entry will be skipped entirely. In such cases, you -can specify the position from where search should continue by making -FUNC set the variable `org-map-continue-from' to the desired buffer -position. +The call to @code{FUNC} will be wrapped into a save-excursion form, so +@code{FUNC} does not need to preserve point. After evaluation, the cursor +will be moved to the end of the line (presumably of the headline of the +processed entry) and search continues from there. Under some circumstances, +this may not produce the wanted results. For example, if you have removed +(e.g., archived) the current (sub)tree it could mean that the next entry will +be skipped entirely. In such cases, you can specify the position from where +search should continue by making @code{FUNC} set the variable +@code{org-map-continue-from} to the desired buffer position. -MATCH is a tags/property/todo match as it is used in the agenda match view. -Only headlines that are matched by this query will be considered during -the iteration. When MATCH is nil or t, all headlines will be -visited by the iteration. +@code{MATCH} is a tags/property/todo match as it is used in the agenda match +view. Only headlines that are matched by this query will be considered +during the iteration. When @code{MATCH} is @code{nil} or @code{t}, all +headlines will be visited by the iteration. -SCOPE determines the scope of this command. It can be any of: +@code{SCOPE} determines the scope of this command. It can be any of: @example nil @r{the current buffer, respecting the restriction if any} @@ -16420,17 +17952,18 @@ Here are a couple of functions that might be handy: @defun org-todo &optional arg Change the TODO state of the entry. See the docstring of the functions for -the many possible values for the argument ARG. +the many possible values for the argument @code{ARG}. @end defun @defun org-priority &optional action Change the priority of the entry. See the docstring of this function for the -possible values for ACTION. +possible values for @code{ACTION}. @end defun @defun org-toggle-tag tag &optional onoff -Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on} -or @code{off} will not toggle tag, but ensure that it is either on or off. +Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to +either @code{on} or @code{off} will not toggle tag, but ensure that it is +either on or off. @end defun @defun org-promote @@ -16466,10 +17999,10 @@ The following example counts the number of entries with TODO keyword @i{MobileOrg} is the name of the mobile companion app for Org mode, currently available for iOS and for Android. @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. -The @uref{http://mobileorg.ncogni.to/, iOS implementation} for the -@i{iPhone/iPod Touch/iPad} series of devices, was developed by Richard -Moreland. Android users should check out +does also allow you to record changes to existing entries. The +@uref{https://github.com/MobileOrg/, iOS implementation} for the +@i{iPhone/iPod Touch/iPad} series of devices, was started by Richard Moreland +and is now in the hands Sean Escriva. Android users should check out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} by Matt Jones. The two implementations are not identical but offer similar features. @@ -16479,7 +18012,7 @@ format that can be displayed by @i{MobileOrg}, and for integrating notes 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 +customization variables @code{org-todo-keywords} and @code{org-tag-alist} to 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 @@ -16580,6 +18113,7 @@ should then go through these entries and do whatever actions are necessary. If a note has been stored while flagging an entry in @i{MobileOrg}, that note will be displayed in the echo area when the cursor is on the corresponding agenda line. + @table @kbd @kindex ? @item ? @@ -16596,11 +18130,11 @@ this flagged entry is finished. @kindex C-c a ? If you are not able to process all flagged entries directly, you can always 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 ?}. +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.} using @kbd{C-c a ?}. @node History and Acknowledgments, GNU Free Documentation License, MobileOrg, Top @appendix History and acknowledgments @@ -16660,7 +18194,7 @@ of his great @file{remember.el}. 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 +web pages derived from Org using an Info-like or a folding interface with single-key navigation. @end table @@ -16674,8 +18208,8 @@ would not be complete without adding a few more acknowledgements and thanks to Carsten's ones above. I am first grateful to Carsten for his trust while handing me over the -maintainership of Org. His support as been great since day one of this new -adventure, and it helped a lot. +maintainership of Org. His unremitting support is what really helped me +getting more confident over time, with both the community and the code. When I took over maintainership, I knew I would have to make Org more collaborative than ever, as I would have to rely on people that are more @@ -16689,15 +18223,13 @@ Eric is maintaining the Babel parts of Org. His reactivity here kept me away from worrying about possible bugs here and let me focus on other parts. @item Nicolas Goaziou -Nicolas is maintaining the consistency of the deepest parts of Org. His work -on @file{org-element.el} and @file{org-export.el} has been outstanding, and -opened the doors for many new ideas and features. - -@item Jambunathan K -Jambunathan contributed the ODT exporter, definitely a killer feature of -Org mode. He also contributed the new HTML exporter, which is another core -feature of Org. Here too, I knew I could rely on him to fix bugs in these -areas and to patiently explain the users what was the problems and solutions. +Nicolas is maintaining the consistency of the deepest parts of Org. His +work on @file{org-element.el} and @file{ox.el} has been outstanding, and +opened the doors for many new ideas and features. He rewrote many of the +old exporters to use the new export engine, and helped with documenting +this major change. More importantly (if that's possible), he has been more +than reliable during all the work done for Org 8.0, and always very +reactive on the mailing list. @item Achim Gratz Achim rewrote the building process of Org, turning some @emph{ad hoc} tools @@ -16721,8 +18253,17 @@ complete if the ones above were not mentioned in this manual. @item @i{Russel Adams} came up with the idea for drawers. @item +@i{Suvayu Ali} has steadily helped on the mailing list, providing useful +feedback on many features and several patches. +@item +@i{Luis Anaya} wrote @file{ox-man.el}. +@item @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. @item +@i{Michael Brand} helped by reporting many bugs and testing many features. +He also implemented the distinction between empty fields and 0-value fields +in Org's spreadsheets. +@item @i{Christophe Bataillon} created the great unicorn logo that we use on the Org mode website. @item @@ -16746,7 +18287,11 @@ calculations and improved XEmacs compatibility, in particular by porting @item @i{Sacha Chua} suggested copying some linking code from Planner. @item -@i{Baoqiu Cui} contributed the DocBook exporter. +@i{Toby S. Cubitt} contributed to the code for clock formats. +@item +@i{Baoqiu Cui} contributed the DocBook exporter. It has been deleted from +Org 8.0: you can now export to Texinfo and export the @file{.texi} file to +DocBook using @code{makeinfo}. @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 @@ -16758,16 +18303,23 @@ them. inspired some of the early development, including HTML export. He also asked for a way to narrow wide table columns. @item +@i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for +several years now. He also sponsored the hosting costs until Rackspace +started to host us for free. +@item @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}. +@file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as +@file{ox-taskjuggler.el} for Org 8.0. @item @i{David Emery} provided a patch for custom CSS support in exported HTML agendas. @item +@i{Sean Escriva} took over MobileOrg development on the iPhone platform. +@item @i{Nic Ferrier} contributed mailcap and XOXO support. @item @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes. @@ -16789,7 +18341,9 @@ publication through Network Theory Ltd. @item @i{Niels Giesen} had the idea to automatically archive DONE trees. @item -@i{Nicolas Goaziou} rewrote much of the plain list code. +@i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote +@file{org-element.el} and @file{org-export.el}, which was a huge step forward +in implementing a clean framework for Org exporters. @item @i{Kai Grossjohann} pointed out key-binding conflicts with other packages. @item @@ -16812,6 +18366,8 @@ folded entries, and column view for properties. @item @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}. @item +@i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}. +@item @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also provided frequent feedback and some patches. @item @@ -16824,7 +18380,7 @@ 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. +@i{Max Mikhanosha} came up with the idea of refiling and sticky agendas. @item @i{Dmitri Minaev} sent a patch to set priority limits on a per-file basis. @@ -16858,9 +18414,14 @@ links, among other things. @i{Pete Phillips} helped during the development of the TAGS feature, and provided frequent feedback. @item +@i{Francesco Pizzolante} provided patches that helped speeding up the agenda +generation. +@item @i{Martin Pohlack} provided the code snippet to bundle character insertion into bundles of 20 for undo. @item +@i{Rackspace.com} is hosting our website for free. Thank you Rackspace! +@item @i{T.V. Raman} reported bugs and suggested improvements. @item @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality @@ -16883,6 +18444,9 @@ of feedback, developed and applied standards to the Org documentation. @i{Christian Schlauer} proposed angular brackets around links, among other things. @item +@i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can +enjoy folding in non-org buffers by using Org headlines in comments. +@item @i{Paul Sexton} wrote @file{org-ctags.el}. @item Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s @@ -16914,7 +18478,7 @@ with links transformation to Org syntax. @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual chapter about publishing. @item -@i{Jambunathan K} contributed the ODT exporter. +@i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter. @item @i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and enabled source code highlighting in Gnus. @@ -16923,7 +18487,7 @@ enabled source code highlighting in Gnus. 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 +@i{Jürgen Vollmer} contributed code generating the table of contents in HTML output. @item @i{Samuel Wales} has provided important feedback and bug reports. diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index 1276eb95aa8..dd2ba388348 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -1,18 +1,19 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/pcl-cvs +@setfilename ../../info/pcl-cvs.info @settitle PCL-CVS---Emacs Front-End to CVS +@include docstyle.texi @syncodeindex vr fn @c %**end of header @copying -Copyright @copyright{} 1991--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1991--2015 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'', +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''. @@ -115,7 +116,7 @@ Commands * Removing handled entries:: Uninteresting lines can easily be removed. * Ignoring files:: Telling CVS to ignore generated files. * Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. +* Invoking Ediff:: Running @samp{ediff} from @file{*cvs*} buffer. * Updating files:: Updating files that Need-update. * Tagging files:: Tagging files. * Miscellaneous commands:: Miscellaneous commands. @@ -176,18 +177,18 @@ PCL-CVS as well as all the documentation. Inge Wallin wrote the skeleton of @file{pcl-cvs.texi}, and gave useful comments on it. He also wrote the files @file{elib-node.el} and @file{compile-all.el}. The file -@file{cookie.el} was inspired by Inge.@refill +@file{cookie.el} was inspired by Inge. @item @c linus@@lysator.liu.se Linus Tolke contributed useful comments -on both the functionality and the documentation.@refill +on both the functionality and the documentation. @item @c jwz@@jwz.com Jamie Zawinski contributed @file{pcl-cvs-lucid.el}, which was later renamed to -@file{pcl-cvs-xemacs.el}.@refill +@file{pcl-cvs-xemacs.el}. @item Leif Lonnblad contributed RCVS support (since superseded by the new @@ -263,7 +264,7 @@ The function @code{cvs-examine} will ask for a directory. The command @samp{cvs -n update} will be run in that directory. (It should contain files that have been checked out from a CVS archive.) The output from @code{cvs} will be parsed and presented in a table in a buffer called -@samp{*cvs*}. It might look something like this: +@file{*cvs*}. It might look something like this: @example Repository : /usr/CVSroot @@ -297,7 +298,7 @@ You can move the cursor up and down in the buffer with @kbd{C-n} and repository. @xref{Committing changes}. You can also press @kbd{O} to update any of the files that are marked @samp{Need-Update}. You can also run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the -@samp{*cvs*} buffer) to update all the files.@refill +@file{*cvs*} buffer) to update all the files. You can then press @kbd{=} to easily get a @samp{diff} between your modified file and the base version that you started from, or you can @@ -308,7 +309,7 @@ about files}). @node Buffer contents @chapter Buffer contents @cindex Buffer contents -@cindex @code{*cvs*} buffer contents +@cindex @file{*cvs*} buffer contents The display contains several columns, some of which are optional. These columns are, from left to right: @@ -324,7 +325,7 @@ how we got to the current state, for example @samp{patched}, @item An asterisk when the file is @dfn{marked} (@pxref{Selected -files}).@refill +files}). @item The actual status of the file wrt the repository. See below. @@ -350,7 +351,7 @@ the following substatus: @item merged The file was modified in your working directory, and there were modifications in the repository as well, but they were merged -successfully, without conflict, in your working directory.@refill +successfully, without conflict, in your working directory. @end table @item Conflict @@ -360,7 +361,7 @@ working directory) is now the output of the @code{rcsmerge} command on the two versions; an unmodified copy of your file is also in your working directory, with the name @file{.#@var{file}.@var{version}}, where @var{version} is the RCS revision that your modified file started -from. @xref{Viewing differences}, for more details.@refill +from. @xref{Viewing differences}, for more details. A conflict can also come from a disagreement on the existence of the file rather than on its content. This case is indicated by the following @@ -382,17 +383,17 @@ repository. @item Added The file has been added by you, but it still needs to be checked in to -the repository.@refill +the repository. @item Removed The file has been removed by you, but it still needs to be checked in to the repository. You can resurrect it by typing @kbd{a} (@pxref{Adding -and removing files}).@refill +and removing files}). @item Unknown A file that was detected in your directory, but that neither appears in the repository, nor is present on the list of files that CVS should -ignore.@refill +ignore. @item Up-to-date The file is up to date with respect to the version in the repository. @@ -400,29 +401,29 @@ This status can have a substatus of: @table @samp @item added -You have just added the file to the repository.@refill +You have just added the file to the repository. @item updated The file was brought up to date with respect to the repository. This is done for any file that exists in the repository but not in your source, and for files that you haven't changed but are not the most recent -versions available in the repository.@refill +versions available in the repository. @item patched The file was brought up to date with respect to the remote repository by way of fetching and applying a patch to the file in your source. This is equivalent to @samp{updated} except that CVS decided to use a hopefully -more efficient method.@refill +more efficient method. @item committed -You just committed the file.@refill +You just committed the file. @end table @item Need-Update Either a newer version than the one in your source is available in the repository and you have not modified your checked out version, or the file exists in the repository but not in your source. Use -@samp{cvs-mode-update} bound to @kbd{O} to update the file.@refill +@samp{cvs-mode-update} bound to @kbd{O} to update the file. @item Need-Merge You have modified the checked out version of the file, and a newer @@ -448,7 +449,7 @@ marks are not ignored) or whichever file or directory the cursor is on. If a directory is selected but the command cannot be applied to a directory, then it will be applied to the set of files under this -directory which are in the @samp{*cvs*} buffer. +directory which are in the @file{*cvs*} buffer. @findex cvs-mode-force-command @findex cvs-allow-dir-commit @@ -503,7 +504,7 @@ you can use in PCL-CVS@. They are grouped together by type. * Removing handled entries:: Uninteresting lines can easily be removed. * Ignoring files:: Telling CVS to ignore generated files. * Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. +* Invoking Ediff:: Running @samp{ediff} from @file{*cvs*} buffer. * Updating files:: Updating files that Need-update. * Tagging files:: Tagging files. * Miscellaneous commands:: Miscellaneous commands. @@ -519,10 +520,10 @@ you can use in PCL-CVS@. They are grouped together by type. @findex cvs-quickdir @cindex Creating the *cvs* buffer -Most commands in PCL-CVS require that you have a @samp{*cvs*} +Most commands in PCL-CVS require that you have a @file{*cvs*} buffer. The commands that you use to get one are listed below. For each, a @samp{cvs} process will be run, the output will be parsed by -PCL-CVS, and the result will be printed in the @samp{*cvs*} buffer (see +PCL-CVS, and the result will be printed in the @file{*cvs*} buffer (see @ref{Buffer contents}, for a description of the buffer's contents). @table @kbd @@ -546,7 +547,7 @@ in which the @samp{cvs update} will be run and the module to be checked out. @item M-x cvs-quickdir -Populate the @samp{*cvs*} buffer by just looking at the @file{CVS/Entries} +Populate the @file{*cvs*} buffer by just looking at the @file{CVS/Entries} files. This is very much like @code{cvs-examine} except that it does not access the CVS repository, which is a major advantage when the repository is far away. But of course, it will not be able to detect @@ -610,11 +611,11 @@ explicitly. The special prefixes are: @table @kbd @item T -Toggles whether or not marks will be active in the next command.@refill +Toggles whether or not marks will be active in the next command. @item b Provide the next command with a branch (can be any version -specifier) to work on.@refill +specifier) to work on. @item B Secondary branch argument. Only meaningful if @kbd{b} is also used. @@ -627,7 +628,7 @@ to the ones PCL-CVS thinks are relevant. @end table @node Updating the buffer -@section Updating the @samp{*cvs*} buffer +@section Updating the @file{*cvs*} buffer @findex cvs-update @findex cvs-examine @findex cvs-status @@ -635,18 +636,18 @@ to the ones PCL-CVS thinks are relevant. @findex cvs-mode-examine @findex cvs-mode-status -The following commands can be used from within the @samp{*cvs*} buffer +The following commands can be used from within the @file{*cvs*} buffer to update the display: @table @kbd @item M-u -Runs the command @samp{cvs-update}.@refill +Runs the command @samp{cvs-update}. @item M-e -Runs the command @samp{cvs-examine}.@refill +Runs the command @samp{cvs-examine}. @item M-s -Runs the command @samp{cvs-status}.@refill +Runs the command @samp{cvs-status}. @end table In addition to the above commands which operate on the whole module, @@ -656,18 +657,18 @@ files/directories with these keys: @table @kbd @item O Runs @code{cvs-mode-update} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-u}.@refill +top-level directory, this is equivalent to @kbd{M-u}. @item e Runs @code{cvs-mode-examine} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-e}.@refill +top-level directory, this is equivalent to @kbd{M-e}. @findex cvs-status-mode @item s Runs @code{cvs-mode-status} on the selected files. When run on the top-level directory, this is equivalent to @kbd{M-s}, except that -CVS output will be shown in a @samp{*cvs-info*} buffer that will be -put in @samp{cvs-status-mode}.@refill +CVS output will be shown in a @file{*cvs-info*} buffer that will be +put in @samp{cvs-status-mode}. @end table @@ -689,7 +690,7 @@ the fact that the buffer is a PCL-CVS buffer: @item @key{SPC} @itemx n These keys move the cursor one file forward, towards the end of the -buffer (@code{cvs-mode-next-line}).@refill +buffer (@code{cvs-mode-next-line}). @item p This key moves one file backward, towards the beginning of the buffer @@ -725,12 +726,12 @@ You can mark and unmark files with these commands: @item m This marks the file that the cursor is positioned on. If the cursor is positioned on a directory all files in that directory are marked -(@code{cvs-mode-mark}).@refill +(@code{cvs-mode-mark}). @item u Unmark the file that the cursor is positioned on. If the cursor is on a directory, all files in that directory are unmarked -(@code{cvs-mode-unmark}).@refill +(@code{cvs-mode-unmark}). @item M Mark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}). @@ -774,7 +775,7 @@ Committing changes basically works as follows: @item After having selected the files you want to commit, you type either @kbd{c} or @kbd{C} which brings up a special buffer -@samp{*cvs-commit*}.@refill +@file{*cvs-commit*}. @item You type in the log message describing the changes you're about to @@ -782,7 +783,7 @@ commit (@pxref{Log Edit Mode}). @item When you're happy with it, you type @kbd{C-c C-c} to do the actual -commit.@refill +commit. @end enumerate There's no hidden state, so you can abort the process or pick it up @@ -799,8 +800,8 @@ change this last detail with @code{log-edit-confirm}. As for the difference between @kbd{c} (i.e., @code{cvs-mode-commit}) and @kbd{C} (i.e., @code{cvs-mode-commit-setup}) is that the first gets you -straight to @samp{*cvs-commit*} without erasing it or changing anything -to its content, while the second first erases @samp{*cvs-commit*} +straight to @file{*cvs-commit*} without erasing it or changing anything +to its content, while the second first erases @file{*cvs-commit*} and tries to initialize it with a sane default (it does that by either using a template provided by the CVS administrator or by extracting a relevant log message from a @file{ChangeLog} file). @@ -841,13 +842,13 @@ the cursor points to a directory, run @code{dired} on that directory; @item o Like @kbd{f}, but use another window -(@code{cvs-mode-find-file-other-window}).@refill +(@code{cvs-mode-find-file-other-window}). @item A Invoke @samp{add-change-log-entry-other-window} to edit a @file{ChangeLog} file. The @file{ChangeLog} file will be found in the directory of the file the cursor points to, or in a parent of that -directory (@code{cvs-mode-add-change-log-entry-other-window}).@refill +directory (@code{cvs-mode-add-change-log-entry-other-window}). @end table @@ -865,12 +866,12 @@ directory (@code{cvs-mode-add-change-log-entry-other-window}).@refill @item l Call the command @code{cvs-mode-log} which runs @samp{cvs log} on all selected files, and show the result in a temporary buffer -@samp{*cvs-info*} (@pxref{Log View Mode}). +@file{*cvs-info*} (@pxref{Log View Mode}). @item s Call the command @code{cvs-mode-status} which runs @samp{cvs status} on all selected files, and show the result in a temporary buffer -@samp{*cvs-info*}. +@file{*cvs-info*}. @c Fixme: reinstate when node is written: @c (@pxref{CVS Status Mode}). @end table @@ -897,7 +898,7 @@ Add all selected files. This command can be used on @samp{Unknown} files (@pxref{Buffer contents}). The status of the file will change to @samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit} @pxref{Committing changes}), to really add the file to the -repository.@refill +repository. This command can also be used on @samp{Removed} files (before you commit them) to resurrect them. @@ -911,7 +912,7 @@ confirmation). The files are deleted from your directory and also be @samp{cvs remove}d. If the files' status was @samp{Unknown} they will disappear from the buffer. Otherwise their status will change to @samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit}, -@pxref{Committing changes}) to commit the removal.@refill +@pxref{Committing changes}) to commit the removal. The command that is run is @code{cvs-mode-remove-file}. @end table @@ -957,7 +958,7 @@ get an overview of what needs to be done. @vindex cvs-mode-remove-handled@r{ (variable)} @kbd{x} invokes @code{cvs-mode-remove-handled}. If @samp{cvs-auto-remove-handled} is set to non-@code{nil}, this will -automatically be performed after every commit.@refill +automatically be performed after every commit. @item C-k This command can be used for lines that @samp{cvs-mode-remove-handled} would @@ -1008,22 +1009,22 @@ This runs @code{cvs-mode-ignore}. @item = @itemx d = Display a @samp{cvs diff} between the selected files and the version -that they are based on (@code{cvs-mode-diff}).@refill +that they are based on (@code{cvs-mode-diff}). @item d b If CVS finds a conflict while merging two versions of a file (during a @samp{cvs update}, @pxref{Updating the buffer}) it will save the original file in a file called @file{.#@var{file}.@var{version}} where @var{file} is the name of the file, and @var{version} is the revision -number that @var{file} was based on.@refill +number that @var{file} was based on. With the @kbd{d b} command you can run a @samp{diff} on the files -@file{.#@var{file}.@var{version}} and @file{@var{file}}.@refill +@file{.#@var{file}.@var{version}} and @file{@var{file}}. @item d h Display a @samp{cvs diff} between the selected files and the head revision (the most recent version on the current -branch) in the repository (@code{cvs-mode-diff-head}).@refill +branch) in the repository (@code{cvs-mode-diff-head}). @item d r Display a @samp{cvs diff} between the base revision of the selected @@ -1035,12 +1036,12 @@ a checkout, update or commit operation @item d v Display a @samp{cvs diff} between the selected files and the head revision of the vendor branch in the repository -(@code{cvs-mode-diff-vendor}).@refill +(@code{cvs-mode-diff-vendor}). @item d y Display a @samp{cvs diff} between the selected files and yesterday's head revision in the repository -(@code{cvs-mode-diff-yesterday}).@refill +(@code{cvs-mode-diff-yesterday}). @end table By default, @samp{diff} commands ignore the marks. This can be changed @@ -1075,7 +1076,7 @@ to do an interactive 3-way merge. CVS has already performed a merge. The resulting file is not used in any way if you use this command. If you use the @kbd{q} command inside @samp{ediff} (to successfully terminate a merge) the file that CVS -created will be overwritten.@refill +created will be overwritten. @end table @node Updating files @@ -1141,11 +1142,11 @@ Byte compile all selected files that end in @file{.el}. @item M-x cvs-mode-delete-lock This command deletes the lock files that -the @samp{*cvs*} buffer informs you about. You should normally never have to +the @file{*cvs*} buffer informs you about. You should normally never have to use this command, since CVS tries very carefully to always remove the lock files itself. -You can only use this command when a message in the @samp{*cvs*} buffer tells +You can only use this command when a message in the @file{*cvs*} buffer tells you so. You should wait a while before using this command in case someone else is running a @code{cvs} command. @@ -1160,7 +1161,7 @@ area (@code{cvs-help}). Bury the PCL-CVS buffer (@code{cvs-bury-buffer}). @item M-x cvs-mode-quit -Quit PCL-CVS, killing the @samp{*cvs*} buffer. +Quit PCL-CVS, killing the @file{*cvs*} buffer. @end table @node Log Edit Mode @@ -1247,24 +1248,24 @@ argument, these commands move that many messages of files. If you have an idea about any customization that would be handy but isn't present in this list, please tell us! -For info on how to reach us, see @ref{Bugs}.@refill +For info on how to reach us, see @ref{Bugs}. @table @samp @item cvs-auto-remove-handled If this variable is set to any non-@code{nil} value, @samp{cvs-mode-remove-handled} will be called every time you check in files, after the check-in is ready. @xref{Removing handled -entries}.@refill +entries}. @item cvs-auto-remove-directories If this variable is set to any non-@code{nil} value, directories that do not contain any files to be checked in will not be listed in the -@samp{*cvs*} buffer.@refill +@file{*cvs*} buffer. @item cvs-auto-revert If this variable is set to any non-@samp{nil} value any buffers you have that visit a file that is committed will be automatically reverted. -This variable defaults to @samp{t}. @xref{Committing changes}.@refill +This variable defaults to @samp{t}. @xref{Committing changes}. @item cvs-update-prog-output-skip-regexp The @samp{-u} flag in the @file{modules} file can be used to run a command @@ -1283,7 +1284,7 @@ useful if your site has several repositories. @item log-edit-require-final-newline @c wordy to avoid underfull hbox When you enter a log message by typing into the -@samp{*cvs-commit-message*} buffer, PCL-CVS normally automatically +@file{*cvs-commit-message*} buffer, PCL-CVS normally automatically inserts a trailing newline, unless there already is one. This behavior can be controlled via @samp{cvs-commit-buffer-require-final-newline}. If it is @samp{t} (the default behavior), a newline will always be @@ -1339,7 +1340,7 @@ default. @vindex cvs-msg (face) PCL-CVS adds a few extra features, including menus, mouse bindings, and -fontification of the @samp{*cvs*} buffer. The faces defined for +fontification of the @file{*cvs*} buffer. The faces defined for fontification are listed below: @table @samp @@ -1401,10 +1402,10 @@ Below is a partial list of currently known problems with PCL-CVS. @table @asis @item Unexpected output from CVS Unexpected output from CVS may confuse PCL-CVS@. It will create -warning messages in the @samp{*cvs*} buffer alerting you to any parse errors. +warning messages in the @file{*cvs*} buffer alerting you to any parse errors. If you get these messages, please send a bug report to the email -addresses listed above. Include the contents of the @samp{*cvs*} buffer, the -output of the CVS process (which should be found in the @samp{ *cvs-tmp*} +addresses listed above. Include the contents of the @file{*cvs*} buffer, the +output of the CVS process (which should be found in the @file{ *cvs-tmp*} buffer), and the versions of Emacs, PCL-CVS and CVS you are using. @end table diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index 370998c855a..49a2cfd1851 100644 --- a/doc/misc/pgg.texi +++ b/doc/misc/pgg.texi @@ -2,22 +2,23 @@ @include gnus-overrides.texi -@setfilename ../../info/pgg +@setfilename ../../info/pgg.info @set VERSION 0.1 @settitle PGG @value{VERSION} +@include docstyle.texi @copying This file describes PGG @value{VERSION}, an Emacs interface to various PGP implementations. -Copyright @copyright{} 2001, 2003--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2001, 2003--2015 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,'' +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.'' @@ -80,7 +81,7 @@ communication. Even though Mailcrypt has similar feature, it does not deal with detached PGP messages, normally used in PGP/MIME infrastructure. This was the main reason why I wrote the new library. -Note that the PGG library is now obsolete, replaced by EasyPG. +Note that the PGG library is now obsolete, replaced by EasyPG@. @xref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}. PGP/MIME is an application of MIME Object Security Services (RFC1848). diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index 3bce0c7c24b..a707ba5f03e 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -1,17 +1,18 @@ \input texinfo @c %**start of header -@setfilename ../../info/rcirc +@setfilename ../../info/rcirc.info @settitle rcirc Manual +@include docstyle.texi @c %**end of header @copying -Copyright @copyright{} 2006--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2006--2015 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'', +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''. @@ -211,7 +212,7 @@ Emacs, or join @code{#rcirc}, the channel about @code{rcirc}. @cindex server buffer When you have answered these questions, @code{rcirc} will create a server -buffer, which will be named something like @code{*irc.freenode.net*}, +buffer, which will be named something like @file{*irc.freenode.net*}, and a channel buffer for each of the channels you wanted to join. @kindex RET @@ -295,7 +296,7 @@ send it to a channel. @cindex quotes @cindex double-quotes Many commands take parameters. IRC commands usually ignore string -delimiters. Neither quote nor double-quote have special meanings in +delimiters. Neither apostrophe nor double-quote have special meanings in IRC. @example diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index ba83d8129a8..01d5ad7b022 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -1,7 +1,8 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/reftex +@setfilename ../../info/reftex.info @settitle RefTeX User Manual +@include docstyle.texi @synindex ky cp @syncodeindex vr cp @syncodeindex fn cp @@ -45,13 +46,13 @@ This manual documents @RefTeX{} (version @value{VERSION}), a package to do labels, references, citations and indices for LaTeX documents with Emacs. -Copyright @copyright{} 1997--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1997--2015 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'', +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''. @@ -98,6 +99,8 @@ modify this GNU manual.'' @node Top @top @RefTeX{} +@insertcopying + @RefTeX{} is a package for managing Labels, References, Citations and index entries with GNU Emacs. @@ -605,7 +608,7 @@ Show calling point in another window. This is the point from where @item < Promote the current section. This will convert @code{\section} to -@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is +@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is an active region, all sections in the region will be promoted, including the one at point. To avoid mistakes, @RefTeX{} requires a fresh document scan before executing this command; if necessary, it will @@ -997,7 +1000,7 @@ In eqs. (1), (2), (3)--(4), (5) and (6) @item u Unmark a marked entry. -@c FIXME: Do we need `A' as well for consistency? +@c FIXME: Do we need 'A' as well for consistency? @cindex LaTeX packages, @code{saferef} @cindex @code{saferef}, LaTeX package @item a @@ -1564,7 +1567,7 @@ Here is the setup: @cindex @code{linguex}, LaTeX package @cindex LaTeX packages, @code{linguex} A more complex example is the @file{linguex.sty} package which defines -list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are +list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc.@: for lists which are terminated by @samp{\z.} or by an empty line. @example @@ -2890,6 +2893,9 @@ default. If you want to have these key bindings available, set in your (setq reftex-extra-bindings t) @end lisp +Note that this variable has to be set before @RefTeX{} is loaded to +have an effect. + @vindex reftex-load-hook Changing and adding to @RefTeX{}'s key bindings is best done in the hook @code{reftex-load-hook}. For information on the keymaps @@ -2958,6 +2964,12 @@ label itself in order to be processed correctly by @RefTeX{}. The only exception is that section labels referring to a section statement outside the current file can still use that section title as context. + +@item +@vindex reftex-include-file-commands +@RefTeX{} knows about the @code{\include} and @code{\input} macros. +In case you use different commands to include files in a multifile +document, customize the variable @code{reftex-include-file-commands}. @end itemize @node Language Support @@ -3890,6 +3902,10 @@ Lisp (and even if you are) you might find it more comfortable to use @code{customize} to look at and change these variables. @kbd{M-x reftex-customize} will get you there. +In case you don't use the @code{customize} interface, here's a caveat: +Changing (mostly parsing-related) options might require a call to +@code{reftex-compile-variables} in order to become effective. + @menu * Options - Table of Contents:: * Options - Defining Label Environments:: @@ -4075,7 +4091,7 @@ group which contains all labels. This may also be a function to do local parsing and identify point to be in a non-standard label environment. The function must take an argument @var{bound} and limit backward searches to this value. It -should return either nil or a cons cell @code{(@var{function} +should return either @code{nil} or a cons cell @code{(@var{function} . @var{position})} with the function symbol and the position where the special environment starts. See the Info documentation for an example. @@ -4179,7 +4195,7 @@ List of magic words which identify a reference to be of this type. If the word before point is equal to one of these words when calling @code{reftex-reference}, the label list offered will be automatically restricted to labels of the correct type. If the first element of this -word list is the symbol `regexp', the strings are interpreted as regular +word list is the symbol @code{regexp}, the strings are interpreted as regular expressions. @item @var{toc-level} @@ -4232,9 +4248,9 @@ special packages like fancyref) are being used. RefTeX can and by default does parse around each label to detect the correct label type, but this process can be slow when a document contains thousands of labels. If you use label prefixes consistently, you may speed up -document parsing by setting this variable to a non-nil value. RefTeX +document parsing by setting this variable to a non-@code{nil} value. RefTeX will then compare the label prefix with the prefixes found in -`reftex-label-alist' and derive the correct label type in this way. +@code{reftex-label-alist} and derive the correct label type in this way. Possible values for this option are: @example @@ -4819,7 +4835,7 @@ case. @defopt reftex-index-verify-function A function which is called at each match during global indexing. -If the function returns nil, the current match is skipped. +If the function returns @code{nil}, the current match is skipped. @end defopt @defopt reftex-index-phrases-skip-indexed-matches @@ -4900,7 +4916,7 @@ The keymap which is active in the @file{*Index*} buffer @defopt reftex-view-crossref-extra Macros which can be used for the display of cross references. -This is used when `reftex-view-crossref' is called with point in an +This is used when @code{reftex-view-crossref} is called with point in an argument of a macro. Note that crossref viewing for citations, references (both ways) and index entries is hard-coded. This variable is only to configure additional structures for which crossreference @@ -4939,7 +4955,7 @@ escapes. @defopt reftex-revisit-to-echo Non-@code{nil} means, automatic citation display will revisit files if -necessary. When nil, citation display in echo area will only be active +necessary. When @code{nil}, citation display in echo area will only be active for cached echo strings (see @code{reftex-cache-cite-echo}), or for @BibTeX{} database files which are already visited by a live associated buffers. @@ -5272,8 +5288,8 @@ will - supply arguments for macros like @code{\index} (flag 5) @end example -You may also set the variable itself to t or nil in order to turn all -options on or off, respectively.@* +You may also set the variable itself to @code{t} or @code{nil} in +order to turn all options on or off, respectively.@* Supplying labels in new sections and environments applies when creating sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* Supplying macro arguments applies when you insert such a macro @@ -5283,7 +5299,7 @@ See the @AUCTeX{} documentation for more information. @defopt reftex-revisit-to-follow Non-@code{nil} means, follow-mode will revisit files if necessary. -When nil, follow-mode will be suspended for stuff in unvisited files. +When @code{nil}, follow-mode will be suspended for stuff in unvisited files. @end defopt @defopt reftex-allow-detached-macro-args @@ -5392,8 +5408,8 @@ if you'd like RefTeX to base its classification of labels on prefixes. This can speed-up document parsing, but may in some cases reduce the quality of the context used by RefTeX to describe a label. @item -Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations} -is non-nil. +Fixed bug in @code{reftex-create-bibtex-file} when +@code{reftex-comment-citations} is non-@code{nil}. @item Fixed bugs in indexing: Case-sensitive search, quotes before and/or after words. Disabled indexing in comment lines. @@ -5434,7 +5450,7 @@ deleted from the toc buffer with the @kbd{d} key. @noindent @b{Version 4.19} @itemize @bullet @item -New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current +New command @code{reftex-toc-recenter} (@kbd{C-c -}) which shows the current section in the TOC buffer without selecting the TOC window. @item Recentering happens automatically in idle time when the option @@ -5446,7 +5462,7 @@ buffer. The highlight in the TOC buffer stays when the focus moves to a different window. @item -New command `reftex-goto-label'. +New command @code{reftex-goto-label}. @item Part numbers are no longer included in chapter numbers, and a new part does not reset the chapter counter. See new option @@ -5740,7 +5756,7 @@ New option @code{reftex-cache-cite-echo}. @kbd{M-x reftex-reset-mode} now also removes the file with parsing info. @item -Default of @code{reftex-revisit-to-follow} changed to nil. +Default of @code{reftex-revisit-to-follow} changed to @code{nil}. @end itemize @noindent @b{Version 3.24} @@ -5893,7 +5909,7 @@ When no BibTeX database files are specified, citations can also use @noindent @b{Version 3.11} @itemize @bullet @item -Fixed bug which led to naked label in (e.g.@:) footnotes. +Fixed bug which led to naked label in (e.g.)@: footnotes. @item Added scroll-other-window functions to RefTeX-Select. @end itemize diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi index 290c18a7b47..d5a03b63f22 100644 --- a/doc/misc/remember.texi +++ b/doc/misc/remember.texi @@ -1,21 +1,22 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @c %**start of header -@setfilename ../../info/remember +@setfilename ../../info/remember.info @settitle Remember Manual +@include docstyle.texi @syncodeindex fn cp @c %**end of header @copying -This manual is for Remember Mode, version 1.9 +This manual is for Remember Mode, version 2.0 -Copyright @copyright{} 2001, 2004--2005, 2007--2013 +Copyright @copyright{} 2001, 2004--2005, 2007--2015 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'', +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''. @@ -53,7 +54,6 @@ modify this GNU manual.'' @menu * Preface:: About the documentation. * Introduction:: What is Remember Mode? -* Installation:: How to install Remember. * Implementation:: How Remember came into existence. * Quick Start:: Get started using Remember. * Function Reference:: Interactive functions in remember.el. @@ -68,6 +68,7 @@ modify this GNU manual.'' Backends * Text File:: Saving to a text file. +* Separate Text Files:: Saving to separate text files. * Diary:: Saving to a Diary file. * Mailbox:: Saving to a mailbox. * Org:: Saving to an Org Mode file. @@ -78,7 +79,7 @@ Backends @node Preface @chapter Preface -This document describes remember-el, which was written by John Wiegley, +This document describes remember.el, which was written by John Wiegley, was once maintained by Sacha Chua, and is now maintained by the Emacs developers. @@ -95,8 +96,8 @@ to remember what our conscious mind may not currently have access to. There are many different databases out there---and good ones---which this mode is not trying to replace. Rather, it's how that data gets there that's the question. Most of the time, we just want to say -"Remember so-and-so's phone number, or that I have to buy dinner for the -cats tonight." That's the FACT@. How it's stored is really the +``Remember so-and-so's phone number, or that I have to buy dinner for the +cats tonight.'' That's the FACT@. How it's stored is really the computer's problem. But at this point in time, it's most definitely also the user's problem, and sometimes so laboriously so that people just let data slip, rather than expend the effort to record it. @@ -114,8 +115,8 @@ Have you ever noticed that having a laptop to write on doesn't @emph{actually} increase the amount of quality material that you turn out, in the long run? Perhaps it's because the time we save electronically in one way, we're losing electronically in another; the -tool should never dominate one's focus. As the mystic Faridu'd-Din -`Attar wrote: ``Be occupied as little as possible with things of the +tool should never dominate one's focus. As the mystic Farīd ud-Dīn +ʿAṭṭār wrote: ``Be occupied as little as possible with things of the outer world but much with things of the inner world; then right action will overcome inaction.'' @@ -127,18 +128,6 @@ in order to record them---it would map much more closely to how the mind manual-ness which computers from the very beginning have been championed as being able to reduce. -@node Installation -@chapter Installation - -Installing Remember Mode is as simple as adding the following lines to -your Emacs configuration file (usually @file{~/.emacs.d/init.el} or -@file{~/.emacs}). - -@lisp -(add-to-list 'load-path "/path/to/remember") -(require 'remember) -@end lisp - @node Implementation @chapter Implementation @@ -186,62 +175,58 @@ feedback will help to make this as intuitive a tool as possible. @itemize @item -Load @file{remember.el}. - -@item -Type @kbd{M-x remember}. The @samp{*Remember*} buffer should be +Type @kbd{M-x remember}. The @file{*Remember*} buffer should be displayed. @item -Type in what you want to remember. The first line will be treated as +Type in what you want to remember. The first line will be treated as the headline, and the rest of the buffer will contain the body of the note. @item Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close -the @samp{*Remember*} buffer. +the @file{*Remember*} buffer. @end itemize -By default, @code{remember-finalize} saves the note in @file{~/.notes}. -You can edit it now to see the remembered and timestamped note. You -can edit this file however you want. New entries will always be added +By default, @code{remember-finalize} saves the note in @file{~/emacs.d/notes}. +You can edit it now to see the remembered and timestamped note. You +can edit this file however you want. New entries will always be added to the end. -To remember a region of text, use the universal prefix. @kbd{C-u M-x -remember} displays a @samp{*Remember*} buffer with the region as the +To remember a region of text, use the universal prefix. @kbd{C-u M-x +remember} displays a @file{*Remember*} buffer with the region as the initial contents. As a simple beginning, you can start by using the Text File backend, -keeping your @file{~/.notes} file in outline-mode format, with a final -entry called @samp{* Raw data}. Remembered data will be added to the -end of the file. Every so often, you can move the data that gets +keeping your @file{~/.emacs.d/notes} file in outline-mode format, with a final +entry called @samp{* Raw data}. Remembered data will be added to the +end of the file. Every so often, you can move the data that gets appended there into other files, or reorganize your document. -You can also store remembered data in other backends. -(@pxref{Backends}) +You can also store remembered data in other backends. @xref{Backends}. -Here is one way to map the remember functions in your @file{.emacs} to -very accessible keystrokes facilities using the mode: +Here is one way to map the remember functions in your init file +(@pxref{Init File, , The Emacs Initialization File, emacs, GNU Emacs +Manual}) to very accessible keystrokes facilities using the mode: @lisp -(autoload 'remember ``remember'' nil t) -(autoload 'remember-region ``remember'' nil t) - (define-key global-map (kbd "<f9> r") 'remember) (define-key global-map (kbd "<f9> R") 'remember-region) @end lisp +@cindex annotation By default, remember uses the first annotation returned by -@code{remember-annotation-functions}. To include all of the annotations, -set @code{remember-run-all-annotation-functions-flag} to non-nil. +@code{remember-annotation-functions}. To include all of the annotations, +set @code{remember-run-all-annotation-functions-flag} to a +non-@code{nil} value. @defopt remember-run-all-annotation-functions-flag -Non-nil means use all annotations returned by +Non-@code{nil} means use all annotations returned by @code{remember-annotation-functions}. @end defopt You can write custom functions that use a different set of -remember-annotation-functions. For example: +remember-annotation-functions. For example: @lisp (defun my/remember-with-filename () @@ -251,17 +236,32 @@ remember-annotation-functions. For example: (call-interactively 'remember))) @end lisp +@cindex notes +The @code{remember-notes} command creates a @dfn{notes} buffer that +visits the file specified by the option @code{remember-data-file}. +The option @code{remember-notes-buffer-name} specifies the name of the +buffer. The buffer uses @code{remember-notes-initial-major-mode} and +@code{remember-notes-mode} minor mode. Use @kbd{C-c C-c} to save +and bury the buffer. The command @code{save-some-buffers} saves this +buffer without asking. This function is a suitable setting for +@code{initial-buffer-choice}. + + @node Function Reference @chapter Function Reference @file{remember.el} defines the following interactive functions: -@defun remember initial -Remember an arbitrary piece of data. With a prefix, it will use the +@defun remember &optional initial +Remember an arbitrary piece of data. With a prefix, it will use the region as @var{initial}. @end defun -@defun remember-region beg end +@defun remember-other-frame &optional initial +Like @code{remember}, but uses a new frame. +@end defun + +@defun remember-region &optional beg end If called from within the remember buffer, @var{beg} and @var{end} are ignored, and the entire buffer will be remembered. If called from any other buffer, that region, plus any context information specific to @@ -270,18 +270,43 @@ that region, will be remembered. @defun remember-clipboard Remember the contents of the current clipboard. This is most useful -for remembering things from Netscape or other X Windows applications. +for remembering things from a web browser or other X Windows applications. @end defun @defun remember-finalize Remember the contents of the current buffer. @end defun +@defun remember-destroy +Destroy the current remember buffer. +@end defun + @defun remember-mode -This enters the major mode for output from @command{remember}. This -buffer is used to collect data that you want remember. Just hit -@kbd{C-c C-c} when you're done entering, and it will go ahead and file -the data for latter retrieval, and possible indexing. +This enters the major mode (@pxref{Major Modes, , Major Modes, emacs, +GNU Emacs Manual}) for output from @code{remember}. This buffer is +used to collect data that you want remember. Just hit @kbd{C-c C-c} +when you're done entering, and it will go ahead and file the data for +latter retrieval, and possible indexing. +@end defun + +@defun remember-notes &optional switch-to +This returns the notes buffer, creating it if needed, and switches +to it if called interactively (or if @var{switch-to} is non-@code{nil}). +The notes buffer visits @code{remember-data-file}, and +is named @code{remember-notes-buffer-name}. It uses +@code{remember-notes-initial-major-mode} and @code{remember-notes-mode} +minor mode. +@end defun + +@defun remember-notes-mode &optional arg +This is a minor mode for the notes buffer. It sets +@code{buffer-save-without-query} so that @code{save-some-buffers} will +save the notes buffer without asking. Use @kbd{C-c C-c} to +run the command @code{remember-notes-save-and-bury-buffer}. +@end defun + +@defun remember-notes-save-and-bury-buffer +Save (if it is modified) and bury the current buffer. @end defun @node Keystrokes @@ -291,14 +316,12 @@ the data for latter retrieval, and possible indexing. @table @kbd -@item C-c C-c (`remember-finalize') -Remember the contents of the current buffer. +@item C-c C-c +@itemx C-x C-s +Remember the contents of the current buffer (@code{remember-finalize}). -@item C-c C-k (`remember-destroy') -Destroy the current *Remember* buffer. - -@item C-x C-s (`remember-finalize') -Remember the contents of the current buffer. +@item C-c C-k +Destroy the current @file{*Remember*} buffer (@code{remember-destroy}). @end table @@ -309,6 +332,7 @@ You can save remembered notes to a variety of backends. @menu * Text File:: Saving to a text file. +* Separate Text Files:: Saving to separate text files. * Diary:: Saving to a Diary file. * Mailbox:: Saving to a mailbox. * Org:: Saving to an Org Mode file. @@ -334,6 +358,30 @@ The file in which to store unprocessed data. The text used to begin each remember item. @end defopt + +@node Separate Text Files +@section Saving to Separate Text Files +@cindex text files, saving to separate + +@subheading Insinuation + +@lisp +(setq remember-handler-functions '(remember-store-in-files)) +@end lisp + +@subheading Options + +@defopt remember-data-directory +The directory in which to store remember data as files. +@end defopt + +@defopt remember-directory-file-name-format +A format string to use for naming files in the remember directory. +File names are formed by calling @code{format-time-string} at the time +of saving, using this format string. +@end defopt + + @node Diary @section Saving to a Diary file @cindex diary, integration @@ -348,7 +396,7 @@ The text used to begin each remember item. @defopt remember-diary-file File for extracted diary entries. -If this is nil, then @code{diary-file} will be used instead." +If this is @code{nil}, then @code{diary-file} will be used instead. @end defopt @node Mailbox diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi index dcb25ec805a..86bcd1a0a6a 100644 --- a/doc/misc/sasl.texi +++ b/doc/misc/sasl.texi @@ -2,21 +2,22 @@ @include gnus-overrides.texi -@setfilename ../../info/sasl +@setfilename ../../info/sasl.info @set VERSION 0.2 @settitle Emacs SASL Library @value{VERSION} +@include docstyle.texi @copying This file describes the Emacs SASL library, version @value{VERSION}. -Copyright @copyright{} 2000, 2004--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2000, 2004--2015 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,'' +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''. diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index aa0752c80cd..ba366722758 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi @@ -1,8 +1,9 @@ \input texinfo @comment -*-texinfo-*- @comment 3.48 @comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/sc +@setfilename ../../info/sc.info @settitle Supercite User's Manual +@include docstyle.texi @iftex @finalout @end iftex @@ -14,13 +15,13 @@ This document describes Supercite, an Emacs package for citing and attributing replies to mail and news messages. -Copyright @copyright{} 1993, 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001--2015 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'', +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''. @@ -146,7 +147,7 @@ Supercite should provide them. For example, many people would like to be able to yank (and cite) only a portion of the original message. Since Supercite only modifies the text it finds in the reply buffer as set up by the MUA, it is the MUA's responsibility to do partial yanking. -@xref{Reply Buffer Initialization}.@refill +@xref{Reply Buffer Initialization}. @vindex mail-header-separator Another potentially useful thing would be for Supercite to set up the @@ -156,7 +157,7 @@ But by previously agreed upon convention, any text above the bodies cannot be modified by Supercite. Supercite, in fact, doesn't know anything about the meaning of these headers, and never ventures outside the designated region. @xref{Hints to MUA Authors}, for more -details.@refill +details. @node What Supercite Does @section What Supercite Does @@ -168,14 +169,14 @@ by calling a hook variable to which Supercite's top-level function @code{sc-cite-original} has been added. When @code{sc-cite-original} is executed, the original message must be set up in a very specific way, but this is handled automatically by the MUA@. @xref{Hints to MUA -Authors}.@refill +Authors}. @cindex info alist The first thing Supercite does, via @code{sc-cite-original}, is to parse through the original message's mail headers. It saves this data in an @dfn{information association list}, or @dfn{info alist}. The information in this list is used in a number of places throughout Supercite. -@xref{Information Keys and the Info Alist}.@refill +@xref{Information Keys and the Info Alist}. @cindex nuking mail headers @cindex reference header @@ -207,7 +208,7 @@ Supercited text and will fill them appropriately. Emacs's built-in filling routines, e.g., @code{fill-paragraph}, do not recognize cited text and will not re-fill them properly because it cannot guess the @code{fill-prefix} being used. -@xref{Post-yank Formatting Commands}, for details.@refill +@xref{Post-yank Formatting Commands}, for details. As mentioned above, Supercite provides commands to recite or uncite regions of text in the reply buffer, and commands to perform other @@ -216,7 +217,7 @@ informative citations throughout. Supercite tries to be as configurable as possible to allow for a wide range of personalized citation styles, but it is also immediately useful with the default configuration, once it has been properly connected to your MUA@. @xref{Getting Connected}, -for more details.@refill +for more details. @node Citations @chapter Citations @@ -304,7 +305,7 @@ string containing four spaces. The @dfn{attribution string}. This element is supplied automatically by Supercite, based on your preferences and the original message's mail headers, though you may be asked to confirm Supercite's choice. -@xref{Selecting an Attribution}, for more details.@refill +@xref{Selecting an Attribution}, for more details. @cindex citation delimiter @vindex sc-citation-delimiter @@ -330,7 +331,7 @@ In this case, the composed, non-nested citation string used might be something like @code{@asis{" Jane> "}}. This citation string will be inserted in front of -every line in the original message that is not already cited.@refill +every line in the original message that is not already cited. Nested citations, being simpler than non-nested citations, are composed of the same elements, sans the attribution string. Supercite is smart @@ -379,7 +380,7 @@ non-nested citation. Thus the variable @code{sc-citation-nonnested-root-regexp} is used to describe only non-nested citation roots. It is important to remember that if you change @code{sc-citation-root-regexp} you should always also change -@code{sc-citation-nonnested-root-regexp}.@refill +@code{sc-citation-nonnested-root-regexp}. @node Information Keys and the Info Alist @chapter Information Keys and the Info Alist @@ -400,7 +401,7 @@ In the case of mail fields, the key is the name of the field, omitting the trailing colon. Info keys are always case insensitive (as are mail headers), and the value for a corresponding key can be retrieved from the alist with the @code{sc-mail-field} function. Thus, if the -following fields were present in the original article:@refill +following fields were present in the original article: @example Date:@: 08 April 1991, 17:32:09 EST @@ -489,7 +490,7 @@ the author's first middle name. If the author's name has more than one middle name, they will appear as info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, -@dots{}). @xref{Selecting an Attribution}.@refill +@dots{}). @xref{Selecting an Attribution}. @node Reference Headers @chapter Reference Headers @@ -540,7 +541,7 @@ examples below as @var{infokey} indicates that the corresponding value of the info key from the info alist will be inserted there. (@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} below, @var{date} and @var{from} correspond to the values of the -@samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill +@samp{Date:@:} and @samp{From:@:} mail headers respectively. @vindex sc-reference-tag-string @vindex reference-tag-string (sc-) @@ -650,7 +651,7 @@ The following commands are available while in electric reference mode Displays the next reference header in the electric reference buffer. If the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking @code{sc-eref-next} while viewing the last reference header in the list -will wrap around to the first header.@refill +will wrap around to the first header. @item @code{sc-eref-prev} (@kbd{p}) @findex sc-eref-prev @@ -658,7 +659,7 @@ will wrap around to the first header.@refill @kindex p Displays the previous reference header in the electric reference buffer. If the variable @code{sc-electric-circular-p} is non-@code{nil}, -invoking @code{sc-eref-prev} will wrap around to the last header.@refill +invoking @code{sc-eref-prev} will wrap around to the last header. @item @code{sc-eref-goto} (@kbd{g}) @findex sc-eref-goto @@ -667,7 +668,7 @@ invoking @code{sc-eref-prev} will wrap around to the last header.@refill Goes to a specified reference header. The index (into the @code{sc-rewrite-header-list}) can be specified as a numeric argument to the command. Otherwise, Supercite will query you for the index in the -minibuffer.@refill +minibuffer. @item @code{sc-eref-jump} (@kbd{j}) @findex sc-eref-jump @@ -681,7 +682,7 @@ value of @code{sc-preferred-header-style}. @findex eref-setn (sc-) @kindex s Set the preferred reference header (i.e., -@code{sc-preferred-header-style}) to the currently displayed header.@refill +@code{sc-preferred-header-style}) to the currently displayed header. @item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c}) @kindex RET @@ -690,7 +691,7 @@ Set the preferred reference header (i.e., @findex sc-eref-exit @findex eref-exit (sc-) Exit from electric reference mode and insert the current header into the -reply buffer.@refill +reply buffer. @item @code{sc-eref-abort} (@kbd{q}, @kbd{x}) @findex sc-eref-abort @@ -729,7 +730,7 @@ hook variable has a @code{nil} value, which the MUA recognizes to mean, ``use your default citation function.'' When you add Supercite's citation function to the hook, thereby giving the variable a non-@code{nil} value, it tells the MUA to run the hook via -@code{run-hooks} instead of using the default citation.@refill +@code{run-hooks} instead of using the default citation. Early in Supercite's development, the Supercite author, a few MUA authors, and some early Supercite users got together and agreed upon a @@ -767,7 +768,7 @@ expects the original article's mail headers to be present within this region. Note that Supercite @emph{never} touches any text outside this region. Note further that the region need not be active for @code{sc-cite-original} to do its job. -@xref{Hints to MUA Authors}.@refill +@xref{Hints to MUA Authors}. The other step in the getting connected process is to make sure your MUA calls @code{sc-cite-original} at the right time. As mentioned @@ -784,7 +785,7 @@ this hook since it is only run once. This will not work, however, if your Emacs maintainer has put Supercite into your dumped Emacs image. In that case, you can use the @code{sc-pre-hook} variable, but this will get executed every time @code{sc-cite-original} is called. @xref{Reply -Buffer Initialization}.@refill +Buffer Initialization}. @node Replying and Yanking @chapter Replying and Yanking @@ -814,7 +815,7 @@ This hook variable is run before @code{sc-cite-original} does any other work. You could conceivably use this hook to set certain Supercite variables based on the reply buffer's mode or name (i.e., to do something different based on whether you are replying or following up to -an article).@refill +an article). @item @emph{Inserts Supercite's keymap.} @@ -942,7 +943,7 @@ there as people on the net, or just about! It would be impossible for Supercite to anticipate every style in existence, and you probably wouldn't encounter them all anyway. But you can configure Supercite to recognize those styles you see often. -@xref{Configuring the Citation Engine}, for details.@refill +@xref{Configuring the Citation Engine}, for details. @item @emph{Runs @code{sc-post-hook}.} @@ -951,7 +952,7 @@ recognize those styles you see often. This variable is very similar to @code{sc-pre-hook}, except that it runs after @code{sc-cite-original} is finished. This hook is provided mostly for completeness and backward compatibility. Perhaps it could be used to -reset certain variables set in @code{sc-pre-hook}.@refill +reset certain variables set in @code{sc-pre-hook}. @end enumerate @node Filling Cited Text @@ -987,7 +988,7 @@ setup. Also, Supercite will collapse leading whitespace between the citation string and the text on a line when the variable @code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for -this variable is @code{nil}.@refill +this variable is @code{nil}. @vindex fill-prefix Its important to understand that Supercite's automatic filling (during @@ -1005,7 +1006,7 @@ When Supercite's automatic filling breaks on a particular message, I will use Emacs's undo feature to undo back before the citation was applied to the original message. Then I'll toggle the variables and manually cite those paragraphs that I don't want to fill or collapse -whitespace on. @xref{Variable Toggling Shortcuts}.@refill +whitespace on. @xref{Variable Toggling Shortcuts}. @kindex C-c C-p C-p If you find that Supercite's automatic filling is just too fragile for @@ -1013,7 +1014,7 @@ your tastes, you might consider one of these alternate approaches. Also, to make life easier, a shortcut function to toggle the state of both of these variables is provided on the key binding @kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix}; -@pxref{Post-yank Formatting Commands}).@refill +@pxref{Post-yank Formatting Commands}). You will noticed that the minor mode string will show the state of these variables as qualifier characters. When both @@ -1025,7 +1026,7 @@ string will display @samp{SC:f}, and when just display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for the default bindings of the toggling function for each respective variable. -@xref{Variable Toggling Shortcuts}.@refill +@xref{Variable Toggling Shortcuts}. Why are these variables not set to @code{nil} by default? It is because many users won't manually fill paragraphs that are Supercited, and there @@ -1088,7 +1089,7 @@ the author's first middle name. @item "sc-lastchoice" the last attribution string you have selected. This is useful when you -recite paragraphs in the reply.@refill +recite paragraphs in the reply. @item "sc-consult" @vindex sc-attrib-selection-list @@ -1099,7 +1100,7 @@ key. See below for details. @item "x-attribution" the original author's suggestion for attribution string choice. See below -for details.@refill +for details. @end table Middle name indexes can be any positive integer greater than zero, @@ -1184,7 +1185,7 @@ case. If the variable's value is non-@code{nil}, then @code{sc-default-author-name} and @code{sc-default-attribution} are used, otherwise, the following steps are taken to find a valid attribution string, and the first step to return a non-@code{nil}, -non-empty string becomes the attribution:@refill +non-empty string becomes the attribution: @enumerate @item @@ -1244,7 +1245,7 @@ variables in your hook functions, you change the attribution and citation strings used by Supercite. One possible use of this would be to override any automatically derived attribution string when it is only one character long; e.g., you prefer to use @code{"initials"} but the -author only has one name.@refill +author only has one name. @node Author Names @section Author Names @@ -1376,7 +1377,7 @@ matched against the current line, from the beginning, using @code{looking-at}. This match folds case if the optional @var{case-fold-search} is non-@code{nil}. If @var{pred} is not a string, or does not @code{eval}uate to a string, it is interpreted as a -binary value (@code{nil} or non-@code{nil}).@refill +binary value (@code{nil} or non-@code{nil}). The four special symbol values for @var{pred} are recognized: @@ -1405,7 +1406,7 @@ processing. By default, if your @var{func} returns @code{nil} (as it should be careful to do explicitly), Regi will reset the frame to the first entry, and advance @samp{point} to the beginning of the next line. If a list is returned from your function, it can contain any combination -of the following elements:@refill +of the following elements: @table @asis @item the symbol @code{continue} @@ -1422,16 +1423,16 @@ entry is still processed. This tells Regi to substitute @var{newframe} as the frame it is interpreting. In other words, your @var{func} can modify the Regi frame on the fly. @var{newframe} can be a variable containing a frame, or it -can be the frame in-lined.@refill +can be the frame in-lined. @item the list @code{(step . @var{step})} Tells Regi to move @var{step} number of lines forward as it continues processing. By default, Regi moves forward one line. @var{step} can be -zero or negative of course, but watch out for infinite loops.@refill +zero or negative of course, but watch out for infinite loops. @end table During execution of your @var{func}, the following variables will be -temporarily bound to some useful information:@refill +temporarily bound to some useful information: @table @code @item curline @@ -1471,7 +1472,7 @@ preferred style. In a similar vein, there are default frames for @dfn{unciting} and @dfn{reciting}, contained in the variables @code{sc-default-uncite-frame} and @code{sc-default-recite-frame} -respectively.@refill +respectively. As mentioned earlier (@pxref{Recognizing Citations}), citations are recognized through the values of the regular expressions @@ -1500,7 +1501,7 @@ Where @var{infokey} is a key suitable for @code{sc-mail-field}, @var{regexp} is a regular expression which is @code{string-match}'d against the value of the @code{sc-mail-field} key, and @var{frame} is the frame to use if a match occurred. @var{frame} can be a variable -containing a frame or a frame in-lined.@refill +containing a frame or a frame in-lined. When Supercite is about to cite, uncite, or recite a region, it consults the appropriate alist and attempts to find a frame to use. If one @@ -1524,7 +1525,7 @@ variable @code{sc-mode-map-prefix}. By default, the @code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, but unfortunately the best general solution so far. In the rest of this chapter, we'll assume you've installed Supercite's keymap on the default -prefix.@refill +prefix. @menu * Citing Commands:: @@ -1546,7 +1547,7 @@ paragraph to use a nickname, or manually cite a message when setting perform these functions on the region of text between @samp{point} and @samp{mark}. Each of them sets the @dfn{undo boundary} before modifying the region so that the command can be undone in the standard Emacs -way.@refill +way. Here is the list of Supercite citing commands: @@ -1567,7 +1568,7 @@ frame @code{sc-default-cite-frame}. It runs the hook universal argument (@kbd{C-u}), it temporarily sets @code{sc-confirm-always-p} to @code{t} so you can confirm the attribution string for a single manual citing. -@xref{Configuring the Citation Engine}.@refill +@xref{Configuring the Citation Engine}. @findex sc-uncite-region @findex uncite-region (sc-) @@ -1578,7 +1579,7 @@ cited line in the region by interpreting the selected frame from @code{sc-uncite-frame-alist}, or the default unciting frame @code{sc-default-uncite-frame}. It runs the hook @code{sc-pre-uncite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}.@refill +@xref{Configuring the Citation Engine}. @findex sc-recite-region @findex recite-region (sc-) @@ -1588,7 +1589,7 @@ This command recites each line the region by interpreting the selected frame from @code{sc-recite-frame-alist}, or the default reciting frame @code{sc-default-recite-frame}. It runs the hook @code{sc-pre-recite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}.@refill +@xref{Configuring the Citation Engine}. @vindex sc-confirm-always-p @vindex confirm-always-p (sc-) @@ -1612,7 +1613,7 @@ Inserts a reference header into the reply buffer at @samp{point}. With no arguments, the header indexed by @code{sc-preferred-header-style} is inserted. An optional numeric argument is the index into @code{sc-rewrite-header-list} indicating which reference header to -write.@refill +write. With just the universal argument (@kbd{C-u}), electric reference mode is entered, regardless of the value of @code{sc-electric-references-p}. @@ -1640,7 +1641,7 @@ this easy to do. Like Supercite commands in general, the toggling commands are placed on a keymap prefix within the greater Supercite keymap. For the default value of @code{sc-mode-map-prefix}, this will be -@kbd{C-c C-p C-t}.@refill +@kbd{C-c C-p C-t}. The following commands toggle the value of certain Supercite variables which take only a binary value: @@ -1700,7 +1701,7 @@ One special command is provided to toggle both @code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together. This is because you typically want to run Supercite with either variable as @code{nil} or non-@code{nil}. The command to toggle these variables -together is bound on @kbd{C-c C-p C-p}.@refill +together is bound on @kbd{C-c C-p C-p}. Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) brings up a Help message on the toggling keymap. @@ -1711,7 +1712,7 @@ brings up a Help message on the toggling keymap. These commands allow you to view, modify, add, and delete various bits of information from the info alist. -@xref{Information Keys and the Info Alist}.@refill +@xref{Information Keys and the Info Alist}. @table @asis @kindex C-c C-p f @@ -1753,7 +1754,7 @@ This function is especially useful for replying to digest messages where Supercite will initially set up its information for the digest originator, but you want to cite each component article with the real message author. Note that unless an error during processing occurs, any -old information is lost.@refill +old information is lost. @end table @node Miscellaneous Commands @@ -1767,7 +1768,7 @@ old information is lost.@refill @item @code{sc-open-line} (@kbd{C-c C-p o}) Similar to Emacs's standard @code{open-line} commands, but inserts the citation string in front of the new line. As with @code{open-line}, -an optional numeric argument inserts that many new lines.@refill +an optional numeric argument inserts that many new lines. @end table @node Hints to MUA Authors @@ -1789,7 +1790,7 @@ a mail message to the Supercite mailing list: Martin> tends to be a "full blown" version rather than to be Martin> stripped down. - Martin> 2: `point' is at the start of the header, `mark' at the + Martin> 2: 'point' is at the start of the header, 'mark' at the Martin> end of the message body. Martin> 3: (run-hooks 'mail-yank-hooks) @@ -1810,7 +1811,7 @@ the release of Emacs 19. Instead of the variable @code{mail-yank-hooks}, the hook variable that the MUA should provide is @code{mail-citation-hook}. Richard Stallman suggests that the MUAs should @code{defvar} @code{mail-citation-hook} to @code{nil} and perform -some default citing when that is the case.@refill +some default citing when that is the case. If you are writing a new MUA package, or maintaining an existing MUA package, you should make it conform to this interface so that your users @@ -1826,7 +1827,7 @@ buffer. At this point you should not modify the raw text in any way you should place all the original headers into the body of the reply. This means that many of the mail headers will be duplicated, one copy above the @code{mail-header-separator} line and one copy below, however -there will probably be more headers below this line.@refill +there will probably be more headers below this line. @item Set @samp{point} to the beginning of the line containing the first mail @@ -1835,7 +1836,7 @@ message text. It is very important that the region be set around the text Supercite is to modify and that the mail headers are within this region. Supercite will not venture outside the region for any reason, and anything within the region is fair game, so don't put anything that -@strong{must} remain unchanged inside the region.@refill +@strong{must} remain unchanged inside the region. @item Run the hook @code{mail-citation-hook}. You will probably want to @@ -1846,7 +1847,7 @@ yanking function, check its value. If it finds @code{mail-citation-hook} to be @code{nil}, it should perform some default citing behavior. User who want to connect to Supercite then need only add @code{sc-cite-original} to this list of hooks using -@code{add-hook}.@refill +@code{add-hook}. @end enumerate If you do all this your MUA will join the ranks of those that conform to diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index 82af6c8f494..2d9eac2dd72 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -1,5 +1,5 @@ @c This is part of the Semantic manual. -@c Copyright (C) 1999-2005, 2007, 2009-2013 Free Software Foundation, +@c Copyright (C) 1999-2005, 2007, 2009-2015 Free Software Foundation, @c Inc. @c See file semantic.texi for copying conditions. @@ -416,11 +416,11 @@ Customize the system include path for the current major mode (or @var{mode}). @end deffn -@defun semanticdb-implied-include-tags +@defvar semanticdb-implied-include-tags Include tags implied for all files of a given mode. You can set this variable with @code{defvar-mode-local} for a particular mode so that any symbols that exist for all files for that mode are included. -@end defun +@end defvar @c @xref{Search Optimization}, for more information on include paths. @@ -483,9 +483,9 @@ for them once, which will be used over and over for tools such as summary-mode, or the analyzer. @deffn Command semanticdb-create-ebrowse-database dir -Create an @var{ebrowse} database for directory @var{dir}. -The database file is stored in ~/.semanticdb, or whichever directory -is specified by @code{semanticdb-default-system-save-directory}. +Create an Ebrowse database for directory @var{dir}. The database file +is stored in ~/.semanticdb, or whichever directory is specified by +@code{semanticdb-default-system-save-directory}. @end deffn @node Idle Scheduler @@ -903,12 +903,12 @@ at a given buffer position. The return value is an EIEIO object describing the context at @var{pos} (@pxref{Top,,,eieio,EIEIO manual}). -When called interactively, this displays a @samp{*Semantic Context +When called interactively, this displays a @file{*Semantic Context Analysis*} buffer containing a summary of the context at point. @end deffn @noindent -The Prefix section of the @samp{*Semantic Context Analysis*} buffer +The Prefix section of the @file{*Semantic Context Analysis*} buffer lists the tags based on the text at point. If it shows only a simple string, the Semantic was unable to identify what the data type was. @@ -983,7 +983,7 @@ If your symbol should be in the scope, but you cannot find it, then you may have found a language support bug in the local-variable parser, or using statement parser. -Calling @kbd{M-x bovinte} should force a reset on the scope in case +Calling @kbd{M-x bovinate} should force a reset on the scope in case there is merely some bad state. @example @@ -1014,7 +1014,7 @@ fully qualified names. You can examine the typecache with @kbd{M-x semanticdb-typecache-dump}. If your data types are not in the typecache, there may be some parsing -error or other bug. Calling @kbd{M-x bovinte} should force a reset on +error or other bug. Calling @kbd{M-x bovinate} should force a reset on the typecache in case there is merely some bad state. @example @@ -1303,7 +1303,7 @@ You can create new types of decorations using the following function: Define a new decoration style with @var{name}. @var{doc} is a documentation string describing the decoration style @var{name}. It is appended to auto-generated doc strings. -An Optional list of @var{flags} can also be specified. Flags are: +An optional list of @var{flags} can also be specified. Flags are: @code{:enabled} <value> - specify the default enabled value for @var{name}. diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi index f43316f5012..71b81e76f9f 100644 --- a/doc/misc/semantic.texi +++ b/doc/misc/semantic.texi @@ -1,8 +1,9 @@ \input texinfo -@setfilename ../../info/semantic +@setfilename ../../info/semantic.info @set TITLE Semantic Manual @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE} +@include docstyle.texi @c ************************************************************************* @c @ Header @@ -24,14 +25,14 @@ @copying This manual documents the Semantic library and utilities. -Copyright @copyright{} 1999--2005, 2007, 2009--2013 Free Software +Copyright @copyright{} 1999--2005, 2007, 2009--2015 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,'' +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.'' @@ -49,6 +50,9 @@ modify this GNU manual.'' @center @titlefont{Semantic} @sp 4 @center by @value{AUTHOR} +@page +@vskip 0pt plus 1filll +@insertcopying @end titlepage @page @@ -223,12 +227,12 @@ grammar developers; it is useful mostly for the hackers who would like to learn more about how @semantic{} works. @menu -* Parser code :: Code used for the parsers -* Tag handling :: Code used for manipulating tags -* Semanticdb Internals :: Code used in the semantic database -* Analyzer Internals :: Code used in the code analyzer -* Tools :: Code used in user tools -* Tests :: Code used for testing +* Parser code:: Code used for the parsers +* Tag handling:: Code used for manipulating tags +* Semanticdb Internals:: Code used in the semantic database +* Analyzer Internals:: Code used in the code analyzer +* Tools:: Code used in user tools +* Tests:: Code used for testing @end menu @node Parser code @@ -351,7 +355,7 @@ tags are @emph{saved} while a buffer is not in memory. The database and tables both also provide applicable cache information, and cache flushing system. The semanticdb search routines use caches -to save datastructures that are complex to calculate. +to save data structures that are complex to calculate. Lastly, it provides the concept of @dfn{project root}. It is a system by which a file can be associated with the root of a project, so if @@ -600,14 +604,14 @@ Emacs Lisp. It is an LALR parser suitable for complex languages. @c Following comments are for the benefit of ispell. @c LocalWords: alist API APIs arg argc args argv asis assoc autoload Wisent -@c LocalWords: backquote bnf bovinate bovinates LALR +@c LocalWords: bnf bovinate bovinates LALR @c LocalWords: bovinating bovination bovinator bucketize @c LocalWords: cb cdr charquote checkcache cindex CLOS -@c LocalWords: concat concocting const constantness ctxt Decl defcustom +@c LocalWords: concat concocting const ctxt Decl defcustom @c LocalWords: deffn deffnx defun defvar destructor's dfn diff dir @c LocalWords: doc docstring EDE EIEIO elisp emacsman emph enum @c LocalWords: eq Exp EXPANDFULL expression fn foo func funcall -@c LocalWords: ia ids iff ifinfo imenu imenus init int isearch itemx java kbd +@c LocalWords: ia ids ifinfo imenu imenus init int isearch itemx java kbd @c LocalWords: keymap keywordtable lang languagemode lexer lexing Ludlam @c LocalWords: menubar metaparent metaparents min minibuffer Misc mode's @c LocalWords: multitable NAvigaTOR noindent nomedian nonterm noselect diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index a44d790781d..2f92e3ea836 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -1,7 +1,8 @@ \input texinfo @c -*- mode: texinfo; coding: utf-8; -*- @c %**start of header -@setfilename ../../info/ses +@setfilename ../../info/ses.info @settitle @acronym{SES}: Simple Emacs Spreadsheet +@include docstyle.texi @setchapternewpage off @syncodeindex fn cp @syncodeindex vr cp @@ -11,13 +12,13 @@ @copying This file documents @acronym{SES}: the Simple Emacs Spreadsheet. -Copyright @copyright{} 2002--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2002--2015 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,'' +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.'' @@ -66,6 +67,7 @@ To report bugs, use @kbd{M-x report-emacs-bug}. @menu * Sales Pitch:: Why use @acronym{SES}? +* Quick Tutorial:: A quick introduction * The Basics:: Basic spreadsheet commands * Advanced Features:: Want to know more? * For Gurus:: Want to know @emph{even more}? @@ -98,6 +100,95 @@ To report bugs, use @kbd{M-x report-emacs-bug}. @c =================================================================== +@node Quick Tutorial +@chapter Quick Tutorial +@cindex introduction +@cindex tutorial + +If you want to get started quickly and think that you know what to +expect from a simple spreadsheet, this chapter may be all that you +need. + +First, visit a new file with the @file{.ses} extension. +Emacs presents you with an empty spreadsheet containing a single cell. + +Begin by inserting a headline: @kbd{"Income"@key{RET}}. The double +quotes indicate that this is a text cell. (Notice that Emacs +automatically inserts the closing quotation mark.) + +To insert your first income value, you must first resize the +spreadsheet. Press @key{TAB} to add a new cell and navigate back up +to it. Enter a number, such as @samp{2.23}. Then proceed to add a +few more income entries, e.g.: + +@example +@group +A + Income + 2.23 + 0.02 + 15.76 + -4.00 +@end group +@end example + +To add up the values, enter a Lisp expression: + +@example +(+ A2 A3 A4 A5) +@end example + +Perhaps you want to add a cell to the right of cell A4 to explain +why you have a negative entry. Pressing @kbd{TAB} in that cell +adds an entire new column @samp{B}, where you can add such a note. + +The column is fairly narrow by default, but pressing @kbd{w} allows +you to resize it as needed. Make it 20 characters wide. You can +now add descriptive legends for all the entries, e.g.: + +@example +@group +A B + Income + 2.23 Consulting fee + 0.02 Informed opinion + 15.76 Lemonade stand + -4 Loan to Joe + 14.01 Total +@end group +@end example + +By default, the labels in column B are right-justified. To change +that, you can enter a printer function for the whole column, using +e.g., @kbd{M-p ("%s")}. You can override a column's printer function +in any individual cell using @kbd{p}. + +If Joe pays back his loan, you might blank that entry; e.g., by +positioning the cursor in cell A5 and pressing @kbd{C-d} twice. +If you do that, the total cell will display @samp{######}. That is +because the regular @code{+} operator does not handle a range that +contains some empty cells. Instead of emptying the cell, you could +enter a literal @samp{0}, or delete the entire row using @kbd{C-k}. +An alternative is to use the special function @code{ses+} instead of +the regular @code{+}: + +@example +(ses+ A2 A3 A4 A5) +@end example + +To make a formula robust against changes in the spreadsheet geometry, +you can use the @code{ses-range} macro to refer to a range of cells by +the end-points, e.g.: + +@example +(apply 'ses+ (ses-range A2 A5)) +@end example + +(The @code{apply} is necessary because @code{ses-range} produces a +@emph{list} of values. This allows for more complex possibilities.) + +@c =================================================================== + @node The Basics @comment node-name, next, previous, up @chapter The Basics @@ -117,6 +208,7 @@ A @dfn{cell identifier} is a symbol with a column letter and a row number. Cell B7 is the 2nd column of the 7th row. For very wide spreadsheets, there are two column letters: cell AB7 is the 28th column of the 7th row. Super wide spreadsheets get AAA1, etc. +You move around with the regular Emacs movement commands. @table @kbd @item j @@ -131,7 +223,7 @@ range A1-A2. Many @acronym{SES} commands operate only on single cells, not ranges. @table @kbd -@item C-SPC +@item C-@key{SPC} @itemx C-@@ Set mark at point (@code{set-mark-command}). @@ -161,13 +253,17 @@ Highlight all cells (@code{mark-whole-buffer}). @section Cell formulas @cindex formulas @cindex formulas, entering +@cindex values +@cindex cell values +@cindex editing cells @findex ses-read-cell @findex ses-read-symbol @findex ses-edit-cell @findex ses-recalculate-cell @findex ses-recalculate-all -To enter a number into the current cell, just start typing: +To insert a value into a cell, simply type a numeric expression, +@samp{"double-quoted text"}, or a Lisp expression. @table @kbd @item 0..9 @@ -213,6 +309,13 @@ Recalculate the entire spreadsheet (@code{ses-recalculate-all}). @node Resizing @section Resizing the spreadsheet @cindex resizing spreadsheets +@cindex dimensions +@cindex row, adding or removing +@cindex column, adding or removing +@cindex adding rows or columns +@cindex inserting rows or columns +@cindex removing rows or columns +@cindex deleting rows or columns @findex ses-insert-row @findex ses-insert-column @findex ses-delete-row @@ -269,6 +372,8 @@ Undo previous action (@code{(undo)}). @node Printer functions @section Printer functions @cindex printer functions +@cindex cell formatting +@cindex formatting cells @findex ses-read-cell-printer @findex ses-read-column-printer @findex ses-read-default-printer @@ -330,6 +435,13 @@ Centering with dashes and spill-over. Centering with tildes (~) and spill-over. @end table +You can define printer function local to a sheet with command +@code{ses-define-local-printer}. For instance define printer +@samp{foo} to @code{"%.2f"} and then use symbol @samp{foo} as a +printer function. Then, if you call again +@code{ses-define-local-printer} on @samp{foo} to redefine it as +@code{"%.3f"} all the cells using printer @samp{foo} will be reprinted +accordingly. @node Clearing cells @section Clearing cells @@ -934,7 +1046,7 @@ the data area, such as hidden constants you want to refer to in your formulas. You can override the variable @code{ses--symbolic-formulas} to be a list of -symbols (as parenthesized strings) to show as completions for the ' +symbols (as parenthesized strings) to show as completions for the @kbd{'} command. This initial completions list is used instead of the actual set of symbols-as-formulas in the spreadsheet. diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi index f69e2b9b948..e9cd9acb881 100644 --- a/doc/misc/sieve.texi +++ b/doc/misc/sieve.texi @@ -2,8 +2,9 @@ @include gnus-overrides.texi -@setfilename ../../info/sieve +@setfilename ../../info/sieve.info @settitle Emacs Sieve Manual +@include docstyle.texi @synindex fn cp @synindex vr cp @synindex pg cp @@ -11,13 +12,13 @@ @copying This file documents the Emacs Sieve package, for server-side mail filtering. -Copyright @copyright{} 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2001--2015 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'', +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''. diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index dce90d06012..2d4e7f94b16 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -1,15 +1,16 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/smtpmail +@setfilename ../../info/smtpmail.info @settitle Emacs SMTP Library +@include docstyle.texi @syncodeindex vr fn @copying -Copyright @copyright{} 2003--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2003--2015 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'', +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''. @@ -367,7 +368,7 @@ implement support for common requirements. @vindex smtpmail-local-domain The variable @code{smtpmail-local-domain} controls the hostname sent in the first @code{EHLO} or @code{HELO} command sent to the server. -It should only be set if the @code{system-name} function returns a +It should be set only if the @code{system-name} function returns a name that isn't accepted by the server. Do not set this variable unless your server complains. @@ -408,7 +409,7 @@ clues to the reason for the error. @vindex smtpmail-debug-info The variable @code{smtpmail-debug-info} controls whether to print the SMTP protocol exchange in the minibuffer, and retain the entire -exchange in a buffer @samp{*trace of SMTP session to @var{server}*}, +exchange in a buffer @file{*trace of SMTP session to @var{server}*}, where @var{server} is the name of the mail server to which you send mail. diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 3cb0ec3aed8..6ad369c8609 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -1,16 +1,17 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/speedbar +@setfilename ../../info/speedbar.info @settitle Speedbar: File/Tag summarizing utility +@include docstyle.texi @syncodeindex fn cp @copying -Copyright @copyright{} 1999--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2015 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'', +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''. @@ -42,16 +43,16 @@ modify this GNU manual.'' Speedbar is a program for Emacs which can be used to summarize information related to the current buffer. Its original inspiration -is the `explorer' often used in modern development environments, office +is the ``explorer'' often used in modern development environments, office packages, and web browsers. Speedbar displays a narrow frame in which a tree view is shown. This tree view defaults to containing a list of files and directories. Files -can be `expanded' to list tags inside. Directories can be expanded to +can be ``expanded'' to list tags inside. Directories can be expanded to list the files within itself. Each file or tag can be jumped to immediately. -Speedbar expands upon `explorer' windows by maintaining context with the +Speedbar expands upon ``explorer'' windows by maintaining context with the user. For example, when using the file view, the current buffer's file is highlighted. Speedbar also mimics the explorer windows by providing multiple display modes. These modes come in two flavors. Major display @@ -60,8 +61,8 @@ only when a buffer of the applicable type is shown. This allows authors of other packages to provide speedbar summaries customized to the needs of that mode. -Throughout this manual, activities are defined as `clicking on', or -`expanding' items. Clicking means using @kbd{Mouse-2} on a +Throughout this manual, activities are defined as ``clicking on'', or +``expanding'' items. Clicking means using @kbd{Mouse-2} on a button. Expanding refers to clicking on an expansion button to display an expanded summary of the entry the expansion button is on. @xref{Basic Navigation}. @@ -230,9 +231,9 @@ Groups summarize information in a single line, and provide a high level view of more complex systems, like a directory tree, or manual chapters. Groups appear at different indentation levels, and are prefixed with a -@samp{+} in some sort of `box'. The group name will summarize the +@samp{+} in some sort of ``box''. The group name will summarize the information within it, and the expansion box will display that -information inline. In File mode, directories and files are `groups' +information inline. In File mode, directories and files are ``groups'' where the @samp{+} is surrounded by brackets like this: @example @@ -245,7 +246,7 @@ In this example, we see both open and closed directories, in addition to a file. The directories have a box consisting of angle brackets, and a file uses square brackets. -In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a +In all modes, a group can be ``edited'' by pressing @kbd{RET}, meaning a file will be opened, or a directory explicitly opened in speedbar. A group can be expanded or contracted using @kbd{+} or @kbd{-}. @xref{Basic Key Bindings}. @@ -291,7 +292,7 @@ Unadorned text will generally be colorless, and not clickable. Each type of Group, item indicator, and label is given a different color. The colors chosen are dependent on whether the background color is light or dark. -Of important note is that the `current item', which may be a buffer or +Of important note is that the ``current item'', which may be a buffer or file name, is highlighted red, and underlined. Colors can be customized from the group @code{speedbar-faces}. Some @@ -1127,7 +1128,7 @@ The conventions allow almost anything to be inserted, but several helper functions are provided to make it easy to create the standardized buttons. -To understand the built in functions, each `button' in speedbar consists +To understand the built in functions, each ``button'' in speedbar consists of four important pieces of data. The text to be displayed, token data to be associated with the text, a function to call, and some face to display it in. diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi index d76f9e09184..98fab5ceafa 100644 --- a/doc/misc/srecode.texi +++ b/doc/misc/srecode.texi @@ -1,9 +1,10 @@ \input texinfo @c %**start of header -@setfilename ../../info/srecode +@setfilename ../../info/srecode.info @set TITLE SRecoder Manual @set AUTHOR Eric M. Ludlam @settitle @value{TITLE} +@include docstyle.texi @c Merge all indexes into a single index for now. @c We can always separate them later into two or more as needed. @@ -15,13 +16,13 @@ @c %**end of header @copying -Copyright @copyright{} 2007--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2015 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,'' +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''. @@ -32,7 +33,7 @@ modify this GNU manual.'' @dircategory Emacs misc features @direntry -* SRecode: (srecode). Template code generator. +* SRecode: (srecode). Semantic template code generator. @end direntry @titlepage @@ -40,6 +41,9 @@ modify this GNU manual.'' @center @titlefont{SRecode} @vskip 0pt plus 1 fill @center by @value{AUTHOR} +@page +@vskip 0pt plus 1filll +@insertcopying @end titlepage @macro semantic{} @@ -247,7 +251,6 @@ features of the current file name, user name, time, etc. Some arguments are major-mode specific, such as the @code{:el} or @code{:cpp} arguments. -@refill @section Template Insertion Context A context can be provided for templates in a file. This helps @@ -257,7 +260,6 @@ contexts to have the same name. Some standard contexts are A context can be automatically derived as well based on the parsing state from @i{Semantic}. @inforef{Top, Semantic Manual, semantic}. -@refill @section Applications Commands that do a particular user task which involves also writing @@ -340,7 +342,7 @@ area will modify the other linked areas. Pressing TAB will move between editable fields in the template. Once the cursor moves out of the are inserted by the template, all the -fields are cancelled. +fields are canceled. @b{NOTE}: Some conveniences in templates, such as completion, or character restrictions are lost when using field editing mode. @@ -781,7 +783,6 @@ All the text and macros within a section are either not shown at all (if that section is not 'visible') or the section is shown one time for each dictionary added to that symbol. @xref{Developing Template Functions}. -@refill Macros prefixed with ``>'' will include another template. Include macros would look like this: @@ -821,7 +822,7 @@ from the name, like this: @node Contexts @section Context -Each template belongs to a context. When promting for a template by +Each template belongs to a context. When prompting for a template by name, such as with @kbd{C-c / /}, the name is prefixed by the current context. If there is no context, it defaults to @code{declaration}. @@ -1174,7 +1175,7 @@ The following built-in simple arguments are available: @subsubsection Argument :indent -Supplies the @code{INDENT} macro. When @code{INDENT} is non-nil, then +Supplies the @code{INDENT} macro. When @code{INDENT} is non-@code{nil}, then each line is individually indented with @code{indent-according-to-mode} during macro processing. @@ -1190,7 +1191,7 @@ If there is an active region via @code{transient-mark-mode}, or @code{mouse-drag-region}, then the @code{REGION} section will be enabled. -In addition, @code{REGIONTEXT} will be set the the text in the region, +In addition, @code{REGIONTEXT} will be set to the text in the region, and that region of text will be ``killed'' from the current buffer. If standard-output is NOT the current buffer, then the region will not @@ -1576,7 +1577,7 @@ start with the main entry point. @defun srecode-insert-fcn template dictionary &optional stream @anchor{srecode-insert-fcn} Insert @var{template} using @var{dictionary} into @var{stream}. -If @var{stream} is nil, then use the current buffer. +If @var{stream} is @code{nil}, then use the current buffer. @end defun @node Template Naming Conventions diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index e8fed290734..c75ddd6e0df 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,11 +3,12 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2013-08-09.09} +\def\texinfoversion{2015-10-17.11} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -% 2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc. +% 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 +% 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 @@ -96,7 +97,9 @@ \let\ptexraggedright=\raggedright \let\ptexrbrace=\} \let\ptexslash=\/ +\let\ptexsp=\sp \let\ptexstar=\* +\let\ptexsup=\sup \let\ptext=\t \let\ptextop=\top {\catcode`\'=\active \global\let\ptexquoteright'}% active in plain's math mode @@ -193,17 +196,6 @@ wide-spread wrap-around } -% Margin to add to right of even pages, to left of odd pages. -\newdimen\bindingoffset -\newdimen\normaloffset -\newdimen\pagewidth \newdimen\pageheight - -% For a final copy, take out the rectangles -% that mark overfull boxes (in case you have decided -% that the text looks ok even though it passes the margin). -% -\def\finalout{\overfullrule=0pt } - % Sometimes it is convenient to have everything in the transcript file % and nothing on the terminal. We don't just call \tracingall here, % since that produces some useless output on the terminal. We also make @@ -248,6 +240,15 @@ \def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount \removelastskip\penalty-200\bigskip\fi\fi} +% Output routine +% + +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt } + % Do @cropmarks to get crop marks. % \newif\ifcropmarks @@ -274,6 +275,7 @@ % described on page 260 of The TeXbook. It involves outputting two % marks for the sectioning macros, one before the section break, and % one after. I won't pretend I can describe this better than DEK... +% \def\domark{% \toks0=\expandafter{\lastchapterdefs}% \toks2=\expandafter{\lastsectiondefs}% @@ -281,11 +283,14 @@ \toks6=\expandafter{\prevsectiondefs}% \toks8=\expandafter{\lastcolordefs}% \mark{% - \the\toks0 \the\toks2 - \noexpand\or \the\toks4 \the\toks6 - \noexpand\else \the\toks8 + \the\toks0 \the\toks2 % 0: top marks (\last...) + \noexpand\or \the\toks4 \the\toks6 % 1: bottom marks (default, \prev...) + \noexpand\else \the\toks8 % 2: color marks }% } + +% \gettopheadingmarks, \getbottomheadingmarks - extract needed part of mark. +% % \topmark doesn't work for the very first chapter (after the title % page or the contents), so we use \firstmark there -- this gets us % the mark with the chapter defs, unless the user sneaks in, e.g., @@ -301,33 +306,74 @@ % Avoid "undefined control sequence" errors. \def\lastchapterdefs{} \def\lastsectiondefs{} +\def\lastsection{} \def\prevchapterdefs{} \def\prevsectiondefs{} \def\lastcolordefs{} +% Margin to add to right of even pages, to left of odd pages. +\newdimen\bindingoffset +\newdimen\normaloffset +\newdimen\pagewidth \newdimen\pageheight + % Main output routine. +% \chardef\PAGE = 255 \output = {\onepageout{\pagecontents\PAGE}} \newbox\headlinebox \newbox\footlinebox -% \onepageout takes a vbox as an argument. Note that \pagecontents -% does insertions, but you have to call it yourself. +% \onepageout takes a vbox as an argument. +% \shipout a vbox for a single page, adding an optional header, footer, +% cropmarks, and footnote. This also causes index entries for this page +% to be written to the auxiliary files. +% \def\onepageout#1{% \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi % \ifodd\pageno \advance\hoffset by \bindingoffset \else \advance\hoffset by -\bindingoffset\fi % + % Common context changes for both heading and footing. % Do this outside of the \shipout so @code etc. will be expanded in % the headline as they should be, not taken literally (outputting ''code). + \def\commmonheadfootline{\let\hsize=\pagewidth \texinfochars} + % + % Retrieve the information for the headings from the marks in the page, + % and call Plain TeX's \makeheadline and \makefootline, which use the + % values in \headline and \footline. + % + % This is used to check if we are on the first page of a chapter. + \ifcase0\topmark\fi + \ifx\thischapter\empty + % See comment for \gettopheadingmarks + \ifcase0\firstmark\fi + \let\curchaptername\thischaptername + \ifcase1\firstmark\fi + \let\prevchaptername\thischaptername + \else + \let\curchaptername\thischaptername + \ifcase1\topmark\fi + \let\prevchaptername\thischaptername + \fi + % \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi - \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi - \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + % + \ifx\curchaptername\prevchaptername + \else + % If on the first page of a chapter, clear @thischapter so it + % doesn't appear in the headline, because the chapter is already + % shown in the chapter heading. + \def\thischapter{}% + \fi + % + \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}% + \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}% % {% + % Set context for writing to auxiliary files like index files. % Have to do this stuff outside the \shipout because we want it to % take effect in \write's, yet the group defined by the \vbox ends % before the \shipout runs. @@ -336,10 +382,10 @@ \normalturnoffactive % \ in index entries must not stay \, e.g., if % the page break happens to be in the middle of an example. % We don't want .vr (or whatever) entries like this: - % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} + % \entry{{\indexbackslash }acronym}{32}{\code {\acronym}} % "\acronym" won't work when it's read back in; % it needs to be - % {\code {{\tt \backslashcurfont }acronym} + % {\code {{\backslashcurfont }acronym} \shipout\vbox{% % Do this early so pdf references go to the beginning of the page. \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi @@ -397,6 +443,7 @@ \newinsert\margin \dimen\margin=\maxdimen +% Main part of page, including any footnotes \def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} {\catcode`\@ =11 \gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi @@ -419,9 +466,13 @@ \def\nsbot{\vbox {\hrule height\cornerlong depth\cornerthick width\cornerthick}} + +% Argument parsing + % Parse an argument, then pass it to #1. The argument is the rest of % the input line (except we remove a trailing comment). #1 should be a % macro which expects an ordinary undelimited TeX argument. +% For example, \def\foo{\parsearg\fooxxx}. % \def\parsearg{\parseargusing{}} \def\parseargusing#1#2{% @@ -440,9 +491,11 @@ }% } -% First remove any @comment, then any @c comment. +% First remove any @comment, then any @c comment. Also remove a @texinfoc +% comment (see \scanmacro for details). Pass the result on to \argcheckspaces. \def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} -\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} +\def\argremovec#1\c#2\ArgTerm{\argremovetexinfoc #1\texinfoc\ArgTerm} +\def\argremovetexinfoc#1\texinfoc#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} % Each occurrence of `\^^M' or `<space>\^^M' is replaced by a single space. % @@ -477,14 +530,13 @@ % \def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} + +% \parseargdef - define a command taking an argument on the line +% % \parseargdef\foo{...} % is roughly equivalent to % \def\foo{\parsearg\Xfoo} % \def\Xfoo#1{...} -% -% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my -% favourite TeX trick. --kasal, 16nov03 - \def\parseargdef#1{% \expandafter \doparseargdef \csname\string#1\endcsname #1% } @@ -674,6 +726,12 @@ \endgraf % Not \par, as it may have been set to \lisppar. \global\dimen1 = \prevdepth \egroup % End the \vtop. + \addgroupbox + \prevdepth = \dimen1 + \checkinserts +} + +\def\addgroupbox{ % \dimen0 is the vertical size of the group's box. \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox % \dimen2 is how much space is left on the page (more or less). @@ -686,9 +744,8 @@ \fi \fi \box\groupbox - \prevdepth = \dimen1 - \checkinserts } + % % TeX puts in an \escapechar (i.e., `@') at the beginning of the help % message, so this ends up printing `@group can only ...'. @@ -931,12 +988,20 @@ where each line of input produces a line of output.} % @c is the same as @comment % @ignore ... @end ignore is another way to write a comment % -\def\comment{\begingroup \catcode`\^^M=\other% +\def\comment{\begingroup \catcode`\^^M=\active% +\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other\commentxxx}% + +{\catcode`\^^M=\active% +\gdef\commentxxx#1^^M{\endgroup% +\futurelet\nexttoken\commentxxxx}% +\gdef\commentxxxx{\ifx\nexttoken\aftermacro\expandafter\comment\fi}% +} + +\def\c{\begingroup \catcode`\^^M=\active% \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% -\commentxxx} -{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} -% -\let\c=\comment +\cxxx} +{\catcode`\^^M=\active \gdef\cxxx#1^^M{\endgroup}} +% See comment in \scanmacro about why the definitions of @c and @comment differ % @paragraphindent NCHARS % We'll use ems for NCHARS, close enough. @@ -1007,69 +1072,23 @@ where each line of input produces a line of output.} % paragraph. % \gdef\dosuppressfirstparagraphindent{% - \gdef\indent{% - \restorefirstparagraphindent - \indent - }% - \gdef\noindent{% - \restorefirstparagraphindent - \noindent - }% - \global\everypar = {% - \kern -\parindent - \restorefirstparagraphindent - }% + \gdef\indent {\restorefirstparagraphindent \indent}% + \gdef\noindent{\restorefirstparagraphindent \noindent}% + \global\everypar = {\kern -\parindent \restorefirstparagraphindent}% } - +% \gdef\restorefirstparagraphindent{% - \global \let \indent = \ptexindent - \global \let \noindent = \ptexnoindent - \global \everypar = {}% + \global\let\indent = \ptexindent + \global\let\noindent = \ptexnoindent + \global\everypar = {}% } % @refill is a no-op. \let\refill=\relax -% If working on a large document in chapters, it is convenient to -% be able to disable indexing, cross-referencing, and contents, for test runs. -% This is done with @novalidate (before @setfilename). -% -\newif\iflinks \linkstrue % by default we want the aux files. -\let\novalidate = \linksfalse - -% @setfilename is done at the beginning of every texinfo file. -% So open here the files we need to have open while reading the input. -% This makes it possible to make a .fmt file for texinfo. -\def\setfilename{% - \fixbackslash % Turn off hack to swallow `\input texinfo'. - \iflinks - \tryauxfile - % Open the new aux file. TeX will close it automatically at exit. - \immediate\openout\auxfile=\jobname.aux - \fi % \openindices needs to do some work in any case. - \openindices - \let\setfilename=\comment % Ignore extra @setfilename cmds. - % - % If texinfo.cnf is present on the system, read it. - % Useful for site-wide @afourpaper, etc. - \openin 1 texinfo.cnf - \ifeof 1 \else \input texinfo.cnf \fi - \closein 1 - % - \comment % Ignore the actual filename. -} - -% Called from \setfilename. -% -\def\openindices{% - \newindex{cp}% - \newcodeindex{fn}% - \newcodeindex{vr}% - \newcodeindex{tp}% - \newcodeindex{ky}% - \newcodeindex{pg}% -} +% @setfilename INFO-FILENAME - ignored +\let\setfilename=\comment % @bye. \outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} @@ -1087,6 +1106,7 @@ where each line of input produces a line of output.} \newtoks\toksC \newtoks\toksD \newbox\boxA +\newbox\boxB \newcount\countA \newif\ifpdf \newif\ifpdfmakepagedest @@ -1135,10 +1155,12 @@ output) for that.)} \ifpdf % - % Color manipulation macros based on pdfcolor.tex, + % Color manipulation macros using ideas from pdfcolor.tex, % except using rgb instead of cmyk; the latter is said to render as a % very dark gray on-screen and a very dark halftone in print, instead - % of actual black. + % of actual black. The dark red here is dark enough to print on paper as + % nearly black, but still distinguishable for online viewing. We use + % black by default, though. \def\rgbDarkRed{0.50 0.09 0.12} \def\rgbBlack{0 0 0} % @@ -1248,10 +1270,9 @@ output) for that.)} % used to mark target names; must be expandable. \def\pdfmkpgn#1{#1} % - % by default, use a color that is dark enough to print on paper as - % nearly black, but still distinguishable for online viewing. - \def\urlcolor{\rgbDarkRed} - \def\linkcolor{\rgbDarkRed} + % by default, use black for everything. + \def\urlcolor{\rgbBlack} + \def\linkcolor{\rgbBlack} \def\endlink{\setcolor{\maincolor}\pdfendlink} % % Adding outlines to PDF; macros for calculating structure of outlines @@ -1395,6 +1416,7 @@ output) for that.)} \normalturnoffactive \def\@{@}% \let\/=\empty + \let\xprocessmacroarg=\eatspaces % in case we are in a macro expansion \makevalueexpandable % do we want to go so far as to use \indexnofonts instead of just % special-casing \var here? @@ -1822,8 +1844,10 @@ end % A few fonts for @defun names and args. \setfont\defbf\bfshape{10}{\magstep1}{OT1} \setfont\deftt\ttshape{10}{\magstep1}{OT1TT} +\setfont\defsl\slshape{10}{\magstep1}{OT1TT} \setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf +\let\tenttsl=\defttsl \let\tensl=\defsl \bf} % Fonts for indices, footnotes, small examples (9pt). \def\smallnominalsize{9pt} @@ -1884,6 +1908,7 @@ end % Section fonts (14.4pt). \def\secnominalsize{14pt} \setfont\secrm\rmbshape{12}{\magstep1}{OT1} +\setfont\secrmnotbold\rmshape{12}{\magstep1}{OT1} \setfont\secit\itbshape{10}{\magstep2}{OT1IT} \setfont\secsl\slbshape{10}{\magstep2}{OT1} \setfont\sectt\ttbshape{12}{\magstep1}{OT1TT} @@ -1953,8 +1978,10 @@ end % A few fonts for @defun names and args. \setfont\defbf\bfshape{10}{\magstephalf}{OT1} \setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} +\setfont\defsl\slshape{10}{\magstephalf}{OT1TT} \setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf +\let\tensl=\defsl \let\tenttsl=\defttsl \bf} % Fonts for indices, footnotes, small examples (9pt). \def\smallnominalsize{9pt} @@ -2086,12 +2113,9 @@ end \endgroup } - % In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. Since -% texinfo doesn't allow for producing subscripts and superscripts except -% in the main text, we don't bother to reset \scriptfont and -% \scriptscriptfont (which would also require loading a lot more fonts). +% we have to define the \textfont of the standard families. We don't +% bother to reset \scriptfont and \scriptscriptfont; awaiting user need. % \def\resetmathfonts{% \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy @@ -2105,8 +2129,8 @@ end % \tenSTYLE to set the current font. % % Each font-changing command also sets the names \lsize (one size lower) -% and \lllsize (three sizes lower). These relative commands are used in -% the LaTeX logo and acronyms. +% and \lllsize (three sizes lower). These relative commands are used +% in, e.g., the LaTeX logo and acronyms. % % This all needs generalizing, badly. % @@ -2142,7 +2166,7 @@ end \let\tenttsl=\secttsl \def\curfontsize{sec}% \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{16pt}} + \resetmathfonts \setleading{17pt}} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc @@ -2571,37 +2595,21 @@ end \let\file=\code \let\option=\code -% @uref (abbreviation for `urlref') takes an optional (comma-separated) -% second argument specifying the text to display and an optional third -% arg as text to display instead of (rather than in addition to) the url -% itself. First (mandatory) arg is the url. -% (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}% - \ifdim\wd0 > 0pt - \unhbox0 % third arg given, show only that - \else - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it - \else - \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url - \fi - \else - \code{#1}% only url given, so show it - \fi - \fi - \endlink -\endgroup} +% @uref (abbreviation for `urlref') aka @url takes an optional +% (comma-separated) second argument specifying the text to display and +% an optional third arg as text to display instead of (rather than in +% addition to) the url itself. First (mandatory) arg is the url. -% This \urefbreak definition is the active one. +% TeX-only option to allow changing PDF output to show only the second +% arg (if given), and not the url (which is then just the link target). +\newif\ifurefurlonlylink + +% The main macro is \urefbreak, which allows breaking at expected +% places within the url. (There used to be another version, which +% didn't support automatic breaking.) \def\urefbreak{\begingroup \urefcatcodes \dourefbreak} \let\uref=\urefbreak +% \def\dourefbreak#1{\urefbreakfinish #1,,,\finish} \def\urefbreakfinish#1,#2,#3,#4\finish{% doesn't work in @example \unsepspaces @@ -2610,12 +2618,19 @@ end \ifdim\wd0 > 0pt \unhbox0 % third arg given, show only that \else - \setbox0 = \hbox{\ignorespaces #2}% + \setbox0 = \hbox{\ignorespaces #2}% look for second arg \ifdim\wd0 > 0pt \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it + \ifurefurlonlylink + % PDF plus option to not display url, show just arg + \unhbox0 + \else + % PDF, normally display both arg and url for consistency, + % visibility, if the pdf is eventually used to print, etc. + \unhbox0\ (\urefcode{#1})% + \fi \else - \unhbox0\ (\urefcode{#1})% DVI: 2nd arg given, show both it and url + \unhbox0\ (\urefcode{#1})% DVI, always show arg and url \fi \else \urefcode{#1}% only url given, so show it @@ -2655,8 +2670,10 @@ end % 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\urefprestretchamount{.13em} +\def\urefpoststretchamount{.1em} +\def\urefprestretch{\urefprebreak \hskip0pt plus\urefprestretchamount\relax} +\def\urefpoststretch{\urefpostbreak \hskip0pt plus\urefprestretchamount\relax} % \def\urefcodeamp{\urefprestretch \&\urefpoststretch} \def\urefcodedot{\urefprestretch .\urefpoststretch} @@ -2783,11 +2800,6 @@ end % \def\dmn#1{\thinspace #1} -% @l was never documented to mean ``switch to the Lisp font'', -% and it is not used as such in any manual I can find. We need it for -% Polish suppressed-l. --karl, 22sep96. -%\def\l#1{{\li #1}\null} - % @acronym for "FBI", "NATO", and the like. % We print this one point size smaller, since it's intended for % all-uppercase. @@ -2854,6 +2866,8 @@ end \let\v=\check \let\~=\tilde \let\dotaccent=\dot + % have to provide another name for sup operator + \let\mathopsup=\sup $\finishmath } \def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. @@ -2877,8 +2891,17 @@ end } } -% ctrl is no longer a Texinfo command, but leave this definition for fun. -\def\ctrl #1{{\tt \rawbackslash \hat}#1} +% for @sub and @sup, if in math mode, just do a normal sub/superscript. +% If in text, use math to place as sub/superscript, but switch +% into text mode, with smaller fonts. This is a different font than the +% one used for real math sub/superscripts (8pt vs. 7pt), but let's not +% fix it (significant additions to font machinery) until someone notices. +% +\def\sub{\ifmmode \expandafter\sb \else \expandafter\finishsub\fi} +\def\finishsub#1{$\sb{\hbox{\selectfonts\lllsize #1}}$}% +% +\def\sup{\ifmmode \expandafter\ptexsp \else \expandafter\finishsup\fi} +\def\finishsup#1{$\ptexsp{\hbox{\selectfonts\lllsize #1}}$}% % @inlinefmt{FMTNAME,PROCESSED-TEXT} and @inlineraw{FMTNAME,RAW-TEXT}. % Ignore unless FMTNAME == tex; then it is like @iftex and @tex, @@ -2891,6 +2914,15 @@ end \def\inlinefmtname{#1}% \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\fi } +% +% @inlinefmtifelse{FMTNAME,THEN-TEXT,ELSE-TEXT} expands THEN-TEXT if +% FMTNAME is tex, else ELSE-TEXT. +\long\def\inlinefmtifelse#1{\doinlinefmtifelse #1,,,\finish} +\long\def\doinlinefmtifelse#1,#2,#3,#4,\finish{% + \def\inlinefmtname{#1}% + \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\else \ignorespaces #3\fi +} +% % For raw, must switch into @tex before parsing the argument, to avoid % setting catcodes prematurely. Doing it this way means that, for % example, @inlineraw{html, foo{bar} gets a parse error instead of being @@ -2907,6 +2939,23 @@ end \endgroup % close group opened by \tex. } +% @inlineifset{VAR, TEXT} expands TEXT if VAR is @set. +% +\long\def\inlineifset#1{\doinlineifset #1,\finish} +\long\def\doinlineifset#1,#2,\finish{% + \def\inlinevarname{#1}% + \expandafter\ifx\csname SET\inlinevarname\endcsname\relax + \else\ignorespaces#2\fi +} + +% @inlineifclear{VAR, TEXT} expands TEXT if VAR is not @set. +% +\long\def\inlineifclear#1{\doinlineifclear #1,\finish} +\long\def\doinlineifclear#1,#2,\finish{% + \def\inlinevarname{#1}% + \expandafter\ifx\csname SET\inlinevarname\endcsname\relax \ignorespaces#2\fi +} + \message{glyphs,} % and logos. @@ -2994,11 +3043,16 @@ end \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} +% Some math mode symbols. Define \ensuremath to switch into math mode +% unless we are already there. Expansion tricks may not be needed here, +% but safer, and can't hurt. +\def\ensuremath{\ifmmode \expandafter\asis \else\expandafter\ensuredmath \fi} +\def\ensuredmath#1{$\relax#1$} +% +\def\bullet{\ensuremath\ptexbullet} +\def\geq{\ensuremath\ge} +\def\leq{\ensuremath\le} +\def\minus{\ensuremath-} % @dots{} outputs an ellipsis using the current font. % We do .5em per period so that it has the same spacing in the cm @@ -3162,8 +3216,15 @@ end \def\Eogonek{{\ecfont \char"86}}\def\macrocharE{E} \def\eogonek{{\ecfont \char"A6}}\def\macrochare{e} % -% Use the ec* fonts (cm-super in outline format) for non-CM glyphs. -\def\ecfont{% +% Use the European Computer Modern fonts (cm-super in outline format) +% for non-CM glyphs. That is ec* for regular text and tc* for the text +% companion symbols (LaTeX TS1 encoding). Both are part of the ec +% package and follow the same conventions. +% +\def\ecfont{\etcfont{e}} +\def\tcfont{\etcfont{t}} +% +\def\etcfont#1{% % We can't distinguish serif/sans and italic/slanted, but this % is used for crude hacks anyway (like adding French and German % quotes to documents typeset with CM, where we lose kerning), so @@ -3172,14 +3233,14 @@ end \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}% \ifmonospace % typewriter: - \font\thisecfont = ectt\ecsize \space at \nominalsize + \font\thisecfont = #1ctt\ecsize \space at \nominalsize \else \ifx\curfontstyle\bfstylename % bold: - \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize + \font\thisecfont = #1cb\ifusingit{i}{x}\ecsize \space at \nominalsize \else % regular: - \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize + \font\thisecfont = #1c\ifusingit{ti}{rm}\ecsize \space at \nominalsize \fi \fi \thisecfont @@ -3349,7 +3410,7 @@ end \newtoks\evenfootline % footline on even pages \newtoks\oddfootline % footline on odd pages -% Now make TeX use those variables +% Now make \makeheadline and \makefootline in Plain TeX use those variables \headline={{\textfonts\rm \ifodd\pageno \the\oddheadline \else \the\evenheadline \fi}} \footline={{\textfonts\rm \ifodd\pageno \the\oddfootline @@ -3405,6 +3466,10 @@ end % @everyheadingmarks % @everyfootingmarks +% These define \getoddheadingmarks, \getevenheadingmarks, +% \getoddfootingmarks, and \getevenfootingmarks, each to one of +% \gettopheadingmarks, \getbottomheadingmarks. +% \def\evenheadingmarks{\headingmarks{even}{heading}} \def\oddheadingmarks{\headingmarks{odd}{heading}} \def\evenfootingmarks{\headingmarks{even}{footing}} @@ -3662,7 +3727,7 @@ end \parskip=\smallskipamount \ifdim\parskip=0pt \parskip=2pt \fi % - % Try typesetting the item mark that if the document erroneously says + % Try typesetting the item mark so that if the document erroneously says % something like @itemize @samp (intending @table), there's an error % right away at the @itemize. It's not the best error message in the % world, but it's better than leaving it to the @item. This means if @@ -3694,7 +3759,12 @@ end \noindent \hbox to 0pt{\hss \itemcontents \kern\itemmargin}% % - \vadjust{\penalty 1200}}% not good to break after first line of item. + \ifinner\else + \vadjust{\penalty 1200}% not good to break after first line of item. + \fi + % We can be in inner vertical mode in a footnote, although an + % @itemize looks awful there. + }% \flushcr } @@ -3912,19 +3982,23 @@ end } % multitable-only commands. -% -% @headitem starts a heading row, which we typeset in bold. -% Assignments have to be global since we are inside the implicit group -% of an alignment entry. \everycr resets \everytab so we don't have to +% +% @headitem starts a heading row, which we typeset in bold. Assignments +% have to be global since we are inside the implicit group of an +% alignment entry. \everycr below resets \everytab so we don't have to % undo it ourselves. \def\headitemfont{\b}% for people to use in the template row; not changeable \def\headitem{% \checkenv\multitable \crcr + \gdef\headitemcrhook{\nobreak}% attempt to avoid page break after headings \global\everytab={\bf}% can't use \headitemfont since the parsing differs \the\everytab % for the first item }% % +% default for tables with no headings. +\let\headitemcrhook=\relax +% % A \tab used to include \hskip1sp. But then the space in a template % line is not enough. That is bad. So let's go back to just `&' until % we again encounter the problem the 1sp was intended to solve. @@ -3955,15 +4029,15 @@ end % \everycr = {% \noalign{% - \global\everytab={}% + \global\everytab={}% Reset from possible headitem. \global\colcount=0 % Reset the column counter. - % Check for saved footnotes, etc. + % + % Check for saved footnotes, etc.: \checkinserts - % Keeps underfull box messages off when table breaks over pages. - %\filbreak - % Maybe so, but it also creates really weird page breaks when the - % table breaks over pages. Wouldn't \vfil be better? Wait until the - % problem manifests itself, so it can be fixed for real --karl. + % + % Perhaps a \nobreak, then reset: + \headitemcrhook + \global\let\headitemcrhook=\relax }% }% % @@ -4202,7 +4276,7 @@ end \def\value{\begingroup\makevalueexpandable\valuexxx} \def\valuexxx#1{\expandablevalue{#1}\endgroup} { - \catcode`\- = \active \catcode`\_ = \active + \catcode`\-=\active \catcode`\_=\active % \gdef\makevalueexpandable{% \let\value = \expandablevalue @@ -4222,7 +4296,12 @@ end % variable's value contains other Texinfo commands, it's almost certain % it will fail (although perhaps we could fix that with sufficient work % to do a one-level expansion on the result, instead of complete). -% +% +% Unfortunately, this has the consequence that when _ is in the *value* +% of an @set, it does not print properly in the roman fonts (get the cmr +% dot accent at position 126 instead). No fix comes to mind, and it's +% been this way since 2003 or earlier, so just ignore it. +% \def\expandablevalue#1{% \expandafter\ifx\csname SET#1\endcsname\relax {[No value for ``#1'']}% @@ -4307,19 +4386,16 @@ end % except not \outer, so it can be used within macros and \if's. \edef\newwrite{\makecsname{ptexnewwrite}} -% \newindex {foo} defines an index named foo. -% It automatically defines \fooindex such that -% \fooindex ...rest of line... puts an entry in the index foo. -% It also defines \fooindfile to be the number of the output channel for -% the file that accumulates this index. The file's extension is foo. +% \newindex {foo} defines an index named IX. +% It automatically defines \IXindex such that +% \IXindex ...rest of line... puts an entry in the index IX. +% It also defines \IXindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is IX. % The name of an index should be no more than 2 characters long % for the sake of vms. % \def\newindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 % Open the file - \fi + \expandafter\chardef\csname#1indfile\endcsname=0 \expandafter\xdef\csname#1index\endcsname{% % Define @#1index \noexpand\doindex{#1}} } @@ -4333,14 +4409,19 @@ end \def\defcodeindex{\parsearg\newcodeindex} % \def\newcodeindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 - \fi + \expandafter\chardef\csname#1indfile\endcsname=0 \expandafter\xdef\csname#1index\endcsname{% \noexpand\docodeindex{#1}}% } +% The default indices: +\newindex{cp}% concepts, +\newcodeindex{fn}% functions, +\newcodeindex{vr}% variables, +\newcodeindex{tp}% types, +\newcodeindex{ky}% keys +\newcodeindex{pg}% and programs. + % @synindex foo bar makes index foo feed into index bar. % Do this instead of @defindex foo if you don't want it as a separate index. @@ -4369,26 +4450,19 @@ end \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% } -% Define \doindex, the driver for all \fooindex macros. +% Define \doindex, the driver for all index macros. % Argument #1 is generated by the calling \fooindex macro, -% and it is "foo", the name of the index. +% and it the two-letter name of the index. -% \doindex just uses \parsearg; it calls \doind for the actual work. -% This is because \doind is more useful to call from other macros. - -% There is also \dosubind {index}{topic}{subtopic} -% which makes an entry in a two-level index such as the operation index. - -\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} -\def\singleindexer #1{\doind{\indexname}{#1}} +\def\doindex#1{\edef\indexname{#1}\parsearg\doindexxxx} +\def\doindexxxx #1{\doind{\indexname}{#1}} % like the previous two, but they put @code around the argument. -\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} -\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} +\def\docodeindex#1{\edef\indexname{#1}\parsearg\docodeindexxxx} +\def\docodeindexxxx #1{\doind{\indexname}{\code{#1}}} -% Take care of Texinfo commands that can appear in an index entry. -% Since there are some commands we want to expand, and others we don't, -% we have to laboriously prevent expansion for those that we don't. +% Used when writing an index entry out to an index file, to prevent +% expansion of Texinfo commands that can appear in an index entry. % \def\indexdummies{% \escapechar = `\\ % use backslash in output files. @@ -4400,36 +4474,10 @@ end % 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. + % should use @lbracechar and @rbracechar? \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 - % causes processing to be prematurely terminated. This is, - % apparently, because \indexsorttmp is fully expanded, and \endinput - % is an expandable command. The redefinition below makes \endinput - % disappear altogether for that purpose -- although logging shows that - % processing continues to some further point. On the other hand, it - % seems \endinput does not hurt in the printed index arg, since that - % is still getting written without apparent harm. - % - % Sample source (mac-idx3.tex, reported by Graham Percival to - % help-texinfo, 22may06): - % @macro funindex {WORD} - % @findex xyz - % @end macro - % ... - % @funindex commtest - % - % The above is not enough to reproduce the bug, but it gives the flavor. - % - % Sample whatsit resulting: - % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} - % - % So: - \let\endinput = \empty - % % Do the redefinitions. \commondummies } @@ -4453,7 +4501,6 @@ end % Called from \indexdummies and \atdummies. % \def\commondummies{% - % % \definedummyword defines \#1 as \string\#1\space, thus effectively % preventing its expansion. This is used only for control words, % not control letters, because the \space would be incorrect for @@ -4530,6 +4577,7 @@ end \definedummyword\guilsinglright \definedummyword\lbracechar \definedummyword\leq + \definedummyword\mathopsup \definedummyword\minus \definedummyword\ogonek \definedummyword\pounds @@ -4543,6 +4591,8 @@ end \definedummyword\quotesinglbase \definedummyword\rbracechar \definedummyword\result + \definedummyword\sub + \definedummyword\sup \definedummyword\textdegree % % We want to disable all macros so that they are not expanded by \write. @@ -4556,6 +4606,8 @@ end } % \commondummiesnofonts: common to \commondummies and \indexnofonts. +% Define \definedumyletter, \definedummyaccent and \definedummyword before +% using. % \def\commondummiesnofonts{% % Control letters and accents. @@ -4617,14 +4669,72 @@ end \definedummyword\samp \definedummyword\strong \definedummyword\tie + \definedummyword\U \definedummyword\uref \definedummyword\url \definedummyword\var \definedummyword\verb \definedummyword\w \definedummyword\xref + % + % Consider: + % @macro mkind{arg1,arg2} + % @cindex \arg2\ + % @end macro + % @mkind{foo, bar} + % The space after the comma will end up in the temporary definition + % that we make for arg2 (see \parsemargdef ff.). We want all this to be + % expanded for the sake of the index, so we end up just seeing "bar". + \let\xeatspaces = \eatspaces + \let\xprocessmacroarg\eatspaces +} + +% For testing: output @{ and @} in index sort strings as \{ and \}. +\newif\ifusebracesinindexes + +\let\indexlbrace\relax +\let\indexrbrace\relax + +{\catcode`\@=0 +\catcode`\\=13 + @gdef@backslashdisappear{@def\{}} } +{ +\catcode`\<=13 +\catcode`\-=13 +\catcode`\`=13 + \gdef\indexnonalnumdisappear{% + \expandafter\ifx\csname SETtxiindexlquoteignore\endcsname\relax\else + % @set txiindexlquoteignore makes us ignore left quotes in the sort term. + % (Introduced for FSFS 2nd ed.) + \let`=\empty + \fi + % + \expandafter\ifx\csname SETtxiindexbackslashignore\endcsname\relax\else + \backslashdisappear + \fi + % + \expandafter\ifx\csname SETtxiindexhyphenignore\endcsname\relax\else + \def-{}% + \fi + \expandafter\ifx\csname SETtxiindexlessthanignore\endcsname\relax\else + \def<{}% + \fi + \expandafter\ifx\csname SETtxiindexatsignignore\endcsname\relax\else + \def\@{}% + \fi + } + + \gdef\indexnonalnumreappear{% + \useindexbackslash + \let-\normaldash + \let<\normalless + \def\@{@}% + } +} + + % \indexnofonts is used when outputting the strings to sort the index % by, and when constructing control sequence names. It eliminates all % control sequences and just writes whatever the best ASCII sort string @@ -4637,7 +4747,6 @@ end \def\definedummyletter##1{\let##1\empty}% % All control words become @asis by default; overrides below. \let\definedummyword\definedummyaccent - % \commondummiesnofonts % % Don't no-op \tt, since it isn't a user-level command @@ -4650,14 +4759,11 @@ end \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\lbracechar{|a}% + \def\lbracechar{{\indexlbrace}}% + \def\rbracechar{{\indexrbrace}}% + \let\{=\lbracechar + \let\}=\rbracechar % - \def\}{|b}% - \def\rbracechar{|b}% % % Non-English letters. \def\AA{AA}% @@ -4666,7 +4772,7 @@ end \def\L{L}% \def\OE{OE}% \def\O{O}% - \def\TH{ZZZ}% + \def\TH{TH}% \def\aa{aa}% \def\ae{ae}% \def\dh{dzz}% @@ -4678,7 +4784,7 @@ end \def\o{o}% \def\questiondown{?}% \def\ss{ss}% - \def\th{zzz}% + \def\th{th}% % \def\LaTeX{LaTeX}% \def\TeX{TeX}% @@ -4715,9 +4821,6 @@ 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 @@ -4731,19 +4834,18 @@ 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)? % Most index entries go through here, but \dosubind is the general case. % #1 is the index name, #2 is the entry text. \def\doind#1#2{\dosubind{#1}{#2}{}} -% Workhorse for all \fooindexes. +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. +% TODO: Two-level index? Operation index? + +% Workhorse for all indexes. % #1 is name of index, #2 is stuff to put there, #3 is subentry -- % empty if called from \doind, as we usually are (the main exception % is with most defuns, which call us directly). @@ -4751,6 +4853,7 @@ end \def\dosubind#1#2#3{% \iflinks {% + \requireopenindexfile{#1}% % Store the main index entry text (including the third arg). \toks0 = {#2}% % If third arg is present, precede it with a space. @@ -4766,7 +4869,49 @@ end \fi } -% Write the entry in \toks0 to the index file: +% Check if an index file has been opened, and if not, open it. +\def\requireopenindexfile#1{% +\ifnum\csname #1indfile\endcsname=0 + \expandafter\newwrite \csname#1indfile\endcsname + \edef\suffix{#1}% + % A .fls suffix would conflict with the file extension for the output + % of -recorder, so use .f1s instead. + \ifx\suffix\indexisfl\def\suffix{f1}\fi + % Open the file + \immediate\openout\csname#1indfile\endcsname \jobname.\suffix + % Using \immediate here prevents an object entering into the current box, + % which could confound checks such as those in \safewhatsit for preceding + % skips. +\fi} +\def\indexisfl{fl} + +% Output \ as {\indexbackslash}, because \ is an escape character in +% the index files. +\let\indexbackslash=\relax +{\catcode`\@=0 \catcode`\\=\active + @gdef@useindexbackslash{@def\{{@indexbackslash}}} +} + +% Definition for writing index entry text. +\def\sortas#1{\ignorespaces}% + +% Definition for writing index entry sort key. Should occur at the at +% the beginning of the index entry, like +% @cindex @sortas{september} \september +% The \ignorespaces takes care of following space, but there's no way +% to remove space before it. +{ +\catcode`\-=13 +\gdef\indexwritesortas{% + \begingroup + \indexnonalnumreappear + \indexwritesortasxxx} +\gdef\indexwritesortasxxx#1{% + \xdef\indexsortkey{#1}\endgroup} +} + + +% Write the entry in \toks0 to the index file. % \def\dosubindwrite{% % Put the index entry in the margin if desired. @@ -4776,14 +4921,20 @@ end % % Remember, we are within a group. \indexdummies % Must do this here, since \bf, etc expand at this stage - \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now - % so it will be output as is; and it will print as backslash. - % - % Process the index entry with all font commands turned off, to - % get the string to sort by. + \useindexbackslash % \indexbackslash isn't defined now so it will be output + % as is; and it will print as backslash. + % Get the string to sort by, by processing the index entry with all + % font commands turned off. {\indexnofonts - \edef\temp{\the\toks0}% need full expansion - \xdef\indexsorttmp{\temp}% + \indexnonalnumdisappear + \xdef\indexsortkey{}% + \let\sortas=\indexwritesortas + \edef\temp{\the\toks0}% + \setbox\dummybox = \hbox{\temp}% Make sure to execute any \sortas + \ifx\indexsortkey\empty + \xdef\indexsortkey{\temp}% + \ifx\indexsortkey\empty\xdef\indexsortkey{ }\fi + \fi }% % % Set up the complete index entry, with both the sort key and @@ -4793,10 +4944,11 @@ end % sorted result. \edef\temp{% \write\writeto{% - \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% + \string\entry{\indexsortkey}{\noexpand\folio}{\the\toks0}}% }% \temp } +\newbox\dummybox % used above % Take care of unwanted page breaks/skips around a whatsit: % @@ -4922,7 +5074,9 @@ end % as its first line, TeX doesn't complain about mismatched braces % (because it thinks @} is a control sequence). \catcode`\@ = 11 - \openin 1 \jobname.#1s + % See comment in \requireopenindexfile. + \def\indexname{#1}\ifx\indexname\indexisfl\def\indexname{f1}\fi + \openin 1 \jobname.\indexname s \ifeof 1 % \enddoublecolumns gets confused if there is no text in the index, % and it loses the chapter title and the aux file entries for the @@ -4930,43 +5084,96 @@ end % there is some text. \putwordIndexNonexistent \else + \catcode`\\ = 0 + \escapechar = `\\ % % If the index file exists but is empty, then \openin leaves \ifeof % false. We have to make TeX try to read something from the file, so % it can discover if there is anything in it. - \read 1 to \temp + \read 1 to \thisline \ifeof 1 \putwordIndexIsEmpty \else % Index files are almost Texinfo source, but we use \ as the escape % character. It would be better to use @, but that's too big a change % to make right now. - \def\indexbackslash{\backslashcurfont}% - \catcode`\\ = 0 - \escapechar = `\\ + \def\indexbackslash{\ttbackslash}% + \let\indexlbrace\{ % Likewise, set these sequences for braces + \let\indexrbrace\} % used in the sort key. \begindoublecolumns - \input \jobname.#1s + \let\entryorphanpenalty=\indexorphanpenalty + % + % Read input from the index file line by line. + \loopdo + \ifeof1 + \let\firsttoken\relax + \else + \read 1 to \nextline + \edef\act{\gdef\noexpand\firsttoken{\getfirsttoken\nextline}}% + \act + \fi + \thisline + % + \ifeof1\else + \let\thisline\nextline + \repeat + %% \enddoublecolumns \fi \fi \closein 1 \endgroup} +\def\getfirsttoken#1{\expandafter\getfirsttokenx#1\endfirsttoken} +\long\def\getfirsttokenx#1#2\endfirsttoken{\noexpand#1} + +\def\loopdo#1\repeat{\def\body{#1}\loopdoxxx} +\def\loopdoxxx{\let\next=\relax\body\let\next=\loopdoxxx\fi\next} + % These macros are used by the sorted index file itself. % Change them to control the appearance of the index. -\def\initial#1{{% - % Some minor font changes for the special characters. - \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt - % +{\catcode`\/=13 \catcode`\-=13 \catcode`\^=13 \catcode`\~=13 \catcode`\_=13 +\catcode`\|=13 \catcode`\<=13 \catcode`\>=13 \catcode`\+=13 \catcode`\"=13 +\catcode`\$=3 +\gdef\initialglyphs{% + % Some changes for non-alphabetic characters. Using the glyphs from the + % math fonts looks more consistent than the typewriter font used elsewhere + % for these characters. + \def\indexbackslash{\math{\backslash}}% + \let\\=\indexbackslash + % + % Can't get bold backslash so don't use bold forward slash + \catcode`\/=13 + \def/{{\secrmnotbold \normalslash}}% + \def-{{\normaldash\normaldash}}% en dash `--' + \def^{{\chapbf \normalcaret}}% + \def~{{\chapbf \normaltilde}}% + \def\_{% + \leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }% + \def|{$\vert$}% + \def<{$\less$}% + \def>{$\gtr$}% + \def+{$\normalplus$}% +}} + +\def\initial{% + \bgroup + \initialglyphs + \initialx +} + +\def\initialx#1{% % Remove any glue we may have, we'll be inserting our own. \removelastskip % % We like breaks before the index initials, so insert a bonus. + % The glue before the bonus allows a little bit of space at the + % bottom of a column to reduce an increase in inter-line spacing. \nobreak - \vskip 0pt plus 3\baselineskip - \penalty 0 - \vskip 0pt plus -3\baselineskip + \vskip 0pt plus 5\baselineskip + \penalty -300 + \vskip 0pt plus -5\baselineskip % % Typeset the initial. Making this add up to a whole number of % baselineskips increases the chance of the dots lining up from column @@ -4974,24 +5181,24 @@ end % we need before each entry, but it's better. % % No shrink because it confuses \balancecolumns. - \vskip 1.67\baselineskip plus .5\baselineskip - \leftline{\secbf #1}% + \vskip 1.67\baselineskip plus 1\baselineskip + \leftline{\secfonts \kern-0.05em \secbf #1}% + % \secfonts is inside the argument of \leftline so that the change of + % \baselineskip will not affect any glue inserted before the vbox that + % \leftline creates. % Do our best not to break after the initial. \nobreak \vskip .33\baselineskip plus .1\baselineskip -}} + \egroup % \initialglyphs +} + +\newdimen\entryrightmargin +\entryrightmargin=0pt % \entry typesets a paragraph consisting of the text (#1), dot leaders, and % then page number (#2) flushed to the right margin. It is used for index % and table of contents entries. The paragraph is indented by \leftskip. % -% A straightforward implementation would start like this: -% \def\entry#1#2{... -% 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{% \begingroup % @@ -4999,84 +5206,157 @@ end % affect previous text. \par % - % Do not fill out the last line with white space. - \parfillskip = 0in - % % No extra space above this paragraph. \parskip = 0in % - % Do not prefer a separate line ending with a hyphen to fewer lines. - \finalhyphendemerits = 0 - % - % \hangindent is only relevant when the entry text and page number - % don't both fit on one line. In that case, bob suggests starting the - % dots pretty far over on the line. Unfortunately, a large - % indentation looks wrong when the entry text itself is broken across - % lines. So we use a small indentation and put up with long leaders. - % - % \hangafter is reset to 1 (which is the value we want) at the start - % of each paragraph, so we need not do anything with that. - \hangindent = 2em - % - % When the entry text needs to be broken, just fill out the first line - % with blank space. - \rightskip = 0pt plus1fil - % - % A bit of stretch before each entry for the benefit of balancing - % columns. - \vskip 0pt plus1pt - % % 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}% % + % A bit of stretch before each entry for the benefit of balancing + % columns. + \vskip 0pt plus0.5pt + % + % Badness calculation for paragraph affected by - + % How much \indexdotfill is stretched, or how much \parfillskip is shrunk + % Number of lines (\linepenalty) + % % Swallow the left brace of the text (first parameter): \afterassignment\doentry \let\temp = } \def\entrybreak{\unskip\space\ignorespaces}% \def\doentry{% + % Save the text of the entry in a \vtop. + \global\setbox\boxA=\hbox\bgroup \bgroup % Instead of the swallowed brace. \noindent \aftergroup\finishentry % And now comes the text of the entry. + % Not absorbing as a macro argument reduces the chance of problems + % with catcodes occurring. } -\def\finishentry#1{% +{\catcode`\@=11 +\gdef\finishentry#1{% + \egroup % end box A + \dimen@ = \wd\boxA % Length of text of entry + \global\setbox\boxA=\hbox\bgroup\unhbox\boxA % #1 is the page number. % % The following is kludged to not output a line of dots in the index if % there are no page numbers. The next person who breaks this will be % cursed by a Unix daemon. - \setbox\boxA = \hbox{#1}% - \ifdim\wd\boxA = 0pt - \ % + \setbox\boxB = \hbox{#1}% + \ifdim\wd\boxB = 0pt + \null\nobreak\hfill\ % \else % - % If we must, put the page number on a line of its own, and fill out - % this line with blank space. (The \hfil is overwhelmed with the - % fill leaders glue in \indexdotfill if the page number does fit.) - \hfil\penalty50 \null\nobreak\indexdotfill % Have leaders before the page number. % - % The `\ ' here is removed by the implicit \unskip that TeX does as - % part of (the primitive) \par. Without it, a spurious underfull - % \hbox ensues. \ifpdf - \pdfgettoks#1.% - \ \the\toksA + \pdfgettoks#1.% + \hskip\skip\thinshrinkable\the\toksA \else - \ #1% + \hskip\skip\thinshrinkable #1% \fi \fi - \par + \egroup % end \boxA + \global\setbox\entryindexbox=\vtop\bgroup\noindent + % We want the text of the entries to be aligned to the left, and the + % page numbers to be aligned to the right. + % + \advance\leftskip by 0pt plus 1fil + \advance\leftskip by 0pt plus -1fill + \rightskip = 0pt plus -1fil + \advance\rightskip by 0pt plus 1fill + % Cause last line, which could consist of page numbers on their own if the + % list of page numbers is long, to be aligned to the right. + \parfillskip=0pt plus -1fill + % + \hangindent=1em + % + \advance\rightskip by \entryrightmargin + % Determine how far we can stretch into the margin. + % This allows, e.g., "Appendix H GNU Free Documentation License" to fit + % on one line. + \advance \parfillskip by 0pt minus .6\entryrightmargin + % + \ifdim\wd\boxA > \hsize % If the entry doesn't fit in one line + \ifdim\dimen@ > 0.9\hsize % due to long index text + \dimen@ = 0.6\dimen@ % Try to split the text roughly evenly + \dimen@ii = \hsize + \advance \dimen@ii by -1em + \ifnum\dimen@>\dimen@ii + % If the entry is too long, use the whole line + \dimen@ = \dimen@ii + \else + % Cause stretch of 1fill at the end of the first line, to avoid + % extra spacing in a short first line. + \hskip 0pt plus 1fill + \fi + \parshape = 2 0pt \dimen@ 1em \dimen@ii + % Ideally we'd add a finite glue at the end of the first line only, but + % TeX doesn't seem to provide a way to do such a thing. + \fi\fi + \unhbox\boxA + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % Word spacing - no stretch + \spaceskip=\fontdimen2\font minus \fontdimen4\font + % + \linepenalty=1000 % Discourage line breaks. + \hyphenpenalty=10000 % Discourage hyphenation. + % + \par % format the paragraph + \egroup % The \vtop \endgroup + % delay text of entry until after penalty + \bgroup\aftergroup\insertindexentrybox + \entryorphanpenalty +}} + +\newskip\thinshrinkable +\skip\thinshrinkable=.15em minus .15em + +\newbox\entryindexbox +\def\insertindexentrybox{% +\lineskip=.8ex plus .6ex % This comes into effect when the \vtop has a large + % depth due to the paragraph in it having several + % lines. +\box\entryindexbox} + +% Default is no penalty +\let\entryorphanpenalty\egroup + +% Used from \printindex. \firsttoken should be the first token +% after the \entry. If it's not another \entry, we are at the last +% line of a group of index entries, so insert a penalty to discourage +% orphaned index entries. +\long\def\indexorphanpenalty{% + \def\isentry{\entry}% + \ifx\firsttoken\isentry + \else + \unskip\penalty 9000 + % The \unskip here stops breaking before the glue. It relies on the + % \vskip above being there, otherwise there is an error + % "You can't use `\unskip' in vertical mode". There has to be glue + % in the current vertical list that hasn't been added to the + % "current page". See Chapter 24 of the TeXbook. This contradicts + % Section 8.3.7 in "TeX by Topic," though. + \fi + \egroup % now comes the box added with \aftergroup } % Like plain.tex's \dotfill, except uses up at least 1 em. +% The filll stretch here overpowers both the fil and fill stretch to push +% the page number to the right. \def\indexdotfill{\cleaders - \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill} + \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1filll} + \def\primary #1{\line{#1\hfil}} @@ -5103,6 +5383,9 @@ end \newbox\partialpage \newdimen\doublecolumnhsize +\newtoks\savedtopmark % Used in \begindoublecolumns +\newtoks\savedfirstmark + \def\begindoublecolumns{\begingroup % ended by \enddoublecolumns % Grab any single-column material above us. \output = {% @@ -5123,9 +5406,23 @@ end \unvbox\PAGE \kern-\topskip \kern\baselineskip }% + % Save \topmark and \firstmark + \global\savedtopmark=\expandafter{\topmark}% + \global\savedfirstmark=\expandafter{\firstmark}% }% \eject % run that output routine to set \partialpage % + % We recover the two marks that the last output routine saved in order + % to propagate the information in marks added around a chapter heading, + % which could be otherwise be lost by the time the final page is output. + % + \mark{\the\savedtopmark}% Only mark in page passed to following \output. + \output = {% + \setbox0=\box\PAGE % clear box 255 + }abc\eject + % + \mark{\the\savedfirstmark}% + % % Use the double-column output routine for subsequent pages. \output = {\doublecolumnout}% % @@ -5156,7 +5453,7 @@ end } % The double-column output routine for all double-column pages except -% the last. +% the last, which is done by \balancecolumns. % \def\doublecolumnout{% \splittopskip=\topskip \splitmaxdepth=\maxdepth @@ -5238,28 +5535,47 @@ end \pagegoal = \vsize } % -% Called at the end of the double column material. +% Only called for the last of the double column material. \doublecolumnout +% does the others. \def\balancecolumns{% \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. \dimen@ = \ht0 \advance\dimen@ by \topskip \advance\dimen@ by-\baselineskip - \divide\dimen@ by 2 % target to split to - %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% - \splittopskip = \topskip - % Loop until we get a decent breakpoint. - {% - \vbadness = 10000 - \loop - \global\setbox3 = \copy0 - \global\setbox1 = \vsplit3 to \dimen@ - \ifdim\ht3>\dimen@ - \global\advance\dimen@ by 1pt - \repeat - }% - %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% - \setbox0=\vbox to\dimen@{\unvbox1}% - \setbox2=\vbox to\dimen@{\unvbox3}% + \ifdim\dimen@<14\baselineskip + % Don't split a short final column in two. + \setbox2=\vbox{}% + \else + \divide\dimen@ by 2 % target to split to + \dimen@ii = \dimen@ + \splittopskip = \topskip + % Loop until the second column is no higher than the first + {% + \vbadness = 10000 + \loop + \global\setbox3 = \copy0 + \global\setbox1 = \vsplit3 to \dimen@ + % Remove glue from bottom of first column to + % make sure it is higher than the second. + \global\setbox1 = \vbox{\unvbox1\unpenalty\unskip}% + \ifdim\ht3>\ht1 + \global\advance\dimen@ by 1pt + \repeat + }% + \multiply\dimen@ii by 4 + \divide\dimen@ii by 5 + \ifdim\ht3<\dimen@ii + % Column heights are too different, so don't make their bottoms + % flush with each other. The glue at the end of the second column + % allows a second column to stretch, reducing the difference in + % height between the two. + \setbox0=\vbox to\dimen@{\unvbox1\vfill}% + \setbox2=\vbox to\dimen@{\unvbox3\vskip 0pt plus 0.3\ht0}% + \else + \setbox0=\vbox to\dimen@{\unvbox1}% + \setbox2=\vbox to\dimen@{\unvbox3}% + \fi + \fi % \pagesofar } @@ -5280,6 +5596,10 @@ end \let\lastnode=\empty % no node to associate with \writetocentry{part}{#1}{}% but put it in the toc \headingsoff % no headline or footline on the part page + % This outputs a mark at the end of the page that clears \thischapter + % and \thissection, as is done in \startcontents. + \let\pchapsepmacro\relax + \chapmacro{}{Yomitfromtoc}{}% \chapoddpage \endgroup } @@ -5524,9 +5844,6 @@ end % @centerchap is like @unnumbered, but the heading is centered. \outer\parseargdef\centerchap{% - % Well, we could do the following in a group, but that would break - % an assumption that \chapmacro is called at the outermost level. - % Thus we are safer this way: --kasal, 24feb04 \let\centerparametersmaybe = \centerparameters \unnmhead0{#1}% \let\centerparametersmaybe = \relax @@ -5650,7 +5967,11 @@ end % Define plain chapter starts, and page on/off switching for it. \def\chapbreak{\dobreak \chapheadingskip {-4000}} + +% Start a new page \def\chappager{\par\vfill\supereject} + +% \chapoddpage - start on an odd page for a new chapter % Because \domark is called before \chapoddpage, the filler page will % get the headings for the next chapter, which is wrong. But we don't % care -- we just disable all headings on the filler page. @@ -5686,17 +6007,20 @@ end \CHAPPAGon -% Chapter opening. +% \chapmacro - Chapter opening. % % #1 is the text, #2 is the section type (Ynumbered, Ynothing, % Yappendix, Yomitfromtoc), #3 the chapter number. +% Not used for @heading series. % % To test against our argument. \def\Ynothingkeyword{Ynothing} -\def\Yomitfromtockeyword{Yomitfromtoc} \def\Yappendixkeyword{Yappendix} +\def\Yomitfromtockeyword{Yomitfromtoc} % \def\chapmacro#1#2#3{% + \checkenv{}% chapters, etc., should not start inside an environment. + % % Insert the first mark before the heading break (see notes for \domark). \let\prevchapterdefs=\lastchapterdefs \let\prevsectiondefs=\lastsectiondefs @@ -5749,6 +6073,7 @@ end % {% \chapfonts \rmisbold + \let\footnote=\errfootnoteheading % give better error message % % Have to define \lastsection before calling \donoderef, because the % xref code eventually uses it. On the other hand, it has to be called @@ -5842,22 +6167,29 @@ end % Print any size, any type, section title. % -% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is -% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the -% section number. +% #1 is the text of the title, +% #2 is the section level (sec/subsec/subsubsec), +% #3 is the section type (Ynumbered, Ynothing, Yappendix, Yomitfromtoc), +% #4 is the section number. % \def\seckeyword{sec} % \def\sectionheading#1#2#3#4{% {% - \checkenv{}% should not be in an environment. + \def\sectionlevel{#2}% + \def\temptype{#3}% + % + % It is ok for the @heading series commands to appear inside an + % environment (it's been historically allowed, though the logic is + % dubious), but not the others. + \ifx\temptype\Yomitfromtockeyword\else + \checkenv{}% non-@*heading should not be in an environment. + \fi + \let\footnote=\errfootnoteheading % % Switch to the right set of fonts. \csname #2fonts\endcsname \rmisbold % - \def\sectionlevel{#2}% - \def\temptype{#3}% - % % Insert first mark before the heading break (see notes for \domark). \let\prevsectiondefs=\lastsectiondefs \ifx\temptype\Ynothingkeyword @@ -5909,7 +6241,7 @@ end % % Now the second mark, after the heading break. No break points % between here and the heading. - \let\prevsectiondefs=\lastsectiondefs + \global\let\prevsectiondefs=\lastsectiondefs \domark % % Only insert the space after the number if we have a section number. @@ -6069,7 +6401,7 @@ end \savepageno = \pageno \begingroup % Set up to handle contents files properly. \raggedbottom % Worry more about breakpoints than the bottom. - \advance\hsize by -\contentsrightmargin % Don't use the full line length. + \entryrightmargin=\contentsrightmargin % Don't use the full line length. % % Roman numerals for page numbers. \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi @@ -6174,7 +6506,7 @@ end % Chapters, in the main contents. \def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} -% + % Chapters, in the short toc. % See comments in \dochapentry re vbox and related settings. \def\shortchapentry#1#2#3#4{% @@ -6189,7 +6521,7 @@ end \setbox0 = \hbox{\putwordAppendix{} M}% \hbox to \wd0{\putwordAppendix{} #1\hss}} % -\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} +\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\hskip.7em#1}{#4}} % Unnumbered chapters. \def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} @@ -6222,6 +6554,8 @@ end \def\dochapentry#1#2{% \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip \begingroup + % Move the page numbers slightly to the right + \advance\entryrightmargin by -0.05em \chapentryfonts \tocentry{#1}{\dopageno\bgroup#2\egroup}% \endgroup @@ -6276,14 +6610,15 @@ end \catcode `\|=\other \catcode `\<=\other \catcode `\>=\other - \catcode`\`=\other - \catcode`\'=\other + \catcode `\`=\other + \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 % + % Inverse of the list at the beginning of the file. \let\b=\ptexb \let\bullet=\ptexbullet \let\c=\ptexc @@ -6299,9 +6634,11 @@ end \let\+=\tabalign \let\}=\ptexrbrace \let\/=\ptexslash + \let\sp=\ptexsp \let\*=\ptexstar + %\let\sup=\ptexsup % do not redefine, we want @sup to work in math mode \let\t=\ptext - \expandafter \let\csname top\endcsname=\ptextop % outer + \expandafter \let\csname top\endcsname=\ptextop % we've made it outer \let\frenchspacing=\plainfrenchspacing % \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% @@ -6338,6 +6675,24 @@ end \endgraf \ifdim\lastskip<\envskipamount \removelastskip + \ifnum\lastpenalty<10000 + % Penalize breaking before the environment, because preceding text + % often leads into it. + \penalty100 + \fi + \vskip\envskipamount + \fi + \fi +}} + +\def\afterenvbreak{{% + % =10000 instead of <10000 because of a special case in \itemzzz and + % \sectionheading, q.v. + \ifnum \lastpenalty=10000 \else + \advance\envskipamount by \parskip + \endgraf + \ifdim\lastskip<\envskipamount + \removelastskip % it's not a good place to break if the last penalty was \nobreak % or better ... \ifnum\lastpenalty<10000 \penalty-50 \fi @@ -6346,8 +6701,6 @@ end \fi }} -\let\afterenvbreak = \aboveenvbreak - % \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will % also clear it, so that its embedded environments do the narrowing again. \let\nonarrowing=\relax @@ -6385,15 +6738,13 @@ end % side, and for 6pt waste from % each corner char, and rule thickness \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing = t% % % If this cartouche directly follows a sectioning command, we need the % \parskip glue (backspaced over by default) or the cartouche can % collide with the section heading. \ifnum\lastpenalty>10000 \vskip\parskip \penalty\lastpenalty \fi % - \vbox\bgroup + \setbox\groupbox=\vbox\bgroup \baselineskip=0pt\parskip=0pt\lineskip=0pt \carttop \hbox\bgroup @@ -6417,6 +6768,7 @@ end \egroup \cartbot \egroup + \addgroupbox \checkinserts } @@ -6553,9 +6905,13 @@ end % @raggedright does more-or-less normal line breaking but no right -% justification. From plain.tex. +% justification. From plain.tex. Don't stretch around special +% characters in urls in this environment, since the stretch at the right +% should be enough. \envdef\raggedright{% - \rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax + \rightskip0pt plus2.4em \spaceskip.3333em \xspaceskip.5em\relax + \def\urefprestretchamount{0pt}% + \def\urefpoststretchamount{0pt}% } \let\Eraggedright\par @@ -6795,7 +7151,7 @@ end % typesetting commands (@smallbook, font changes, etc.) have to be done % beforehand -- and a) we want @copying to be done first in the source % file; b) letting users define the frontmatter in as flexible order as -% possible is very desirable. +% possible is desirable. % \def\copying{\checkenv{}\begingroup\scanargctxt\docopying} \def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} @@ -6890,7 +7246,7 @@ end \temp } -% \domakedefun \deffn \deffnx \deffnheader +% \domakedefun \deffn \deffnx \deffnheader { (defn. of \deffnheader) } % % Define \deffn and \deffnx, without parameters. % \deffnheader has to be defined explicitly. @@ -7228,34 +7584,44 @@ end } \fi -\def\scanmacro#1{\begingroup +\let\aftermacroxxx\relax +\def\aftermacro{\aftermacroxxx} + +% alias because \c means cedilla in @tex or @math +\let\texinfoc=\c + +% Used at the time of macro expansion. +% Argument is macro body with arguments substituted +\def\scanmacro#1{% \newlinechar`\^^M \let\xeatspaces\eatspaces + % Reduce doubled backslashes to one + \def\xprocessmacroarg{\passargtomacro\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 + % Process the macro body under the current catcode regime. + \scantokens{#1\texinfoc}\aftermacro% % - % 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} + % The \c is to remove the \newlinechar added by \scantokens, and + % can be noticed by \parsearg. + % The \aftermacro allows a \comment at the end of the macro definition + % to duplicate itself past the final \newlinechar added by \scantokens: + % this is used in the definition of \group to comment out a newline. We + % don't do the same for \c to support Texinfo files with macros that ended + % with a @c, which should no longer be necessary. + % We avoid surrounding the call to \scantokens with \bgroup and \egroup + % to allow macros to open or close groups themselves. +} \def\scanexp#1{% + \bgroup + % Undo catcode changes of \startcontents and \printindex + % When called from @insertcopying or (short)caption, we need active + % backslash to get it printed correctly. + % FIXME: This may not be needed. + %\catcode`\@=0 \catcode`\\=\active \escapechar=`\@ \edef\temp{\noexpand\scanmacro{#1}}% \temp + \egroup } \newcount\paramno % Count of parameters @@ -7321,7 +7687,6 @@ end \catcode`\+=\other \catcode`\<=\other \catcode`\>=\other - \catcode`\@=\other \catcode`\^=\other \catcode`\_=\other \catcode`\|=\other @@ -7331,38 +7696,35 @@ end \def\scanargctxt{% used for copying and captions, not macros. \scanctxt + \catcode`\@=\other \catcode`\\=\other \catcode`\^^M=\other } \def\macrobodyctxt{% used for @macro definitions \scanctxt + \catcode`\ =\other + \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other \catcode`\^^M=\other \usembodybackslash } -\def\macroargctxt{% used when scanning invocations +% Used when scanning braced macro arguments. Note, however, that catcode +% changes here are ineffectual if the macro invocation was nested inside +% an argument to another Texinfo command. +\def\macroargctxt{% \scanctxt - \catcode`\\=0 + \catcode`\^^M=\other + \catcode`\\=\active } -% 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. +\def\macrolineargctxt{% used for whole-line arguments without braces + \scanctxt + \catcode`\{=\other + \catcode`\}=\other +} % \mbodybackslash is the definition of \ in @macro bodies. % It maps \foo\ => \csname macarg.foo\endcsname => #N @@ -7434,57 +7796,36 @@ end \fi } -% This makes use of the obscure feature that if the last token of a -% <parameter list> is #, then the preceding argument is delimited by -% an opening brace, and that opening brace is not consumed. +% \getargs -- Parse the arguments to a @macro line. Set \macname to +% the name of the macro, and \argl to the braced argument list. \def\getargs#1{\getargsxxx#1{}} \def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} \def\getmacname#1 #2\relax{\macname={#1}} \def\getmacargs#1{\def\argl{#1}} +% This made use of the feature that if the last token of a +% <parameter list> is #, then the preceding argument is delimited by +% an opening brace, and that opening brace is not consumed. -% For macro processing make @ a letter so that we can make Texinfo private macro names. -\edef\texiatcatcode{\the\catcode`\@} -\catcode `@=11\relax - -% 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 some hook where the argument si to be expanded. If -% there are less than 10 arguments that hook is to be replaced by ##N where N +% Parse the optional {params} list to @macro or @rmacro. +% Set \paramno to the number of arguments, +% and \paramlist to a parameter text for the macro (e.g. #1,#2,#3 for a +% three-param macro.) Define \macarg.BLAH for each BLAH in the params +% list to some hook where the argument is to be expanded. If there are +% less than 10 arguments that hook is to be replaced by ##N where N % is the position in that list, that is to say the macro arguments are to be % defined `a la TeX in the macro body. % % That gets used by \mbodybackslash (above). % -% We need to get `macro parameter char #' into several definitions. -% The technique used is stolen from LaTeX: let \hash be something -% unexpandable, insert that wherever you need a #, and then redefine -% it to # just before using the token list produced. -% -% The same technique is used to protect \eatspaces till just before -% the macro is used. -% -% If there are 10 or more arguments, a different technique is used, where the -% hook remains in the body, and when macro is to be expanded the body is -% processed again to replace the arguments. -% -% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the -% argument N value and then \edef the body (nothing else will expand because of -% the catcode regime underwhich the body was input). +% If there are 10 or more arguments, a different technique is used: see +% \parsemmanyargdef. % -% If you compile with TeX (not eTeX), and you have macros with 10 or more -% arguments, you need that no macro has more than 256 arguments, otherwise an -% error is produced. \def\parsemargdef#1;{% \paramno=0\def\paramlist{}% \let\hash\relax - \let\xeatspaces\relax + % \hash is redefined to `#' later to get it into definitions + \let\processmacroarg\relax \parsemargdefxxx#1,;,% - % In case that there are 10 or more arguments we parse again the arguments - % list to set new definitions for the \macarg.BLAH macros corresponding to - % each BLAH argument. It was anyhow needed to parse already once this list - % in order to count the arguments, and as macros with at most 9 arguments - % are by far more frequent than macro with 10 or more arguments, defining - % twice the \macarg.BLAH macros does not cost too much processing power. \ifnum\paramno<10\relax\else \paramno0\relax \parsemmanyargdef@@#1,;,% 10 or more arguments @@ -7495,10 +7836,47 @@ end \else \let\next=\parsemargdefxxx \advance\paramno by 1 \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname - {\xeatspaces{\hash\the\paramno}}% + {\processmacroarg{\hash\the\paramno}}% \edef\paramlist{\paramlist\hash\the\paramno,}% \fi\next} +% \parsemacbody, \parsermacbody +% +% Read recursive and nonrecursive macro bodies. (They're different since +% rec and nonrec macros end differently.) +% +% We are in \macrobodyctxt, and the \xdef causes backslashshes in the macro +% body to be transformed. +% Set \macrobody to the body of the macro, and call \defmacro. +% +{\catcode`\ =\other\long\gdef\parsemacbody#1@end macro{% +\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}% +{\catcode`\ =\other\long\gdef\parsermacbody#1@end rmacro{% +\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}% + +% Make @ a letter, so that we can make private-to-Texinfo macro names. +\edef\texiatcatcode{\the\catcode`\@} +\catcode `@=11\relax + +%%%%%%%%%%%%%% Code for > 10 arguments only %%%%%%%%%%%%%%%%%% + +% If there are 10 or more arguments, a different technique is used, where the +% hook remains in the body, and when macro is to be expanded the body is +% processed again to replace the arguments. +% +% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the +% argument N value and then \edef the body (nothing else will expand because of +% the catcode regime under which the body was input). +% +% If you compile with TeX (not eTeX), and you have macros with 10 or more +% arguments, no macro can have more than 256 arguments (else error). +% +% In case that there are 10 or more arguments we parse again the arguments +% list to set new definitions for the \macarg.BLAH macros corresponding to +% each BLAH argument. It was anyhow needed to parse already once this list +% in order to count the arguments, and as macros with at most 9 arguments +% are by far more frequent than macro with 10 or more arguments, defining +% twice the \macarg.BLAH macros does not cost too much processing power. \def\parsemmanyargdef@@#1,{% \if#1;\let\next=\relax \else @@ -7514,16 +7892,6 @@ end \advance\paramno by 1\relax \fi\next} -% These two commands read recursive and nonrecursive macro bodies. -% (They're different since rec and nonrec macros end differently.) -% - -\catcode `\@\texiatcatcode -\long\def\parsemacbody#1@end macro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% -\long\def\parsermacbody#1@end rmacro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% -\catcode `\@=11\relax \let\endargs@\relax \let\nil@\relax @@ -7531,7 +7899,7 @@ end \long\def\nillm@{\nil@}% % This macro is expanded during the Texinfo macro expansion, not during its -% definition. It gets all the arguments values and assigns them to macros +% definition. It gets all the arguments' values and assigns them to macros % macarg.ARGNAME % % #1 is the macro name @@ -7552,8 +7920,6 @@ end \getargvals@@ \fi } - -% \def\getargvals@@{% \ifx\paramlist\nilm@ % Some sanity check needed here that \argvaluelist is also empty. @@ -7597,7 +7963,8 @@ end } % Replace arguments by their values in the macro body, and place the result -% in macro \@tempa +% in macro \@tempa. +% \def\macvalstoargs@{% % To do this we use the property that token registers that are \the'ed % within an \edef expand only once. So we are going to place all argument @@ -7621,8 +7988,9 @@ end \expandafter\def\expandafter\@tempa\expandafter{\@tempc}% } +% Define the named-macro outside of this group and then close this group. +% \def\macargexpandinbody@{% - %% Define the named-macro outside of this group and then close this group. \expandafter \endgroup \macargdeflist@ @@ -7659,14 +8027,8 @@ end \next } -% Save the token stack pointer into macro #1 -\def\texisavetoksstackpoint#1{\edef#1{\the\@cclvi}} -% Restore the token stack pointer from number in macro #1 -\def\texirestoretoksstackpoint#1{\expandafter\mathchardef\expandafter\@cclvi#1\relax} -% newtoks that can be used non \outer . -\def\texinonouternewtoks{\alloc@ 5\toks \toksdef \@cclvi} - -% Tailing missing arguments are set to empty +% Trailing missing arguments are set to empty. +% \def\setemptyargvalues@{% \ifx\paramlist\nilm@ \let\next\macargexpandinbody@ @@ -7696,99 +8058,204 @@ end \long\def#2{#4}% } -% This defines a Texinfo @macro. There are eight cases: recursive and -% nonrecursive macros of zero, one, up to nine, and many arguments. -% Much magic with \expandafter here. + +%%%%%%%%%%%%%% End of code for > 10 arguments %%%%%%%%%%%%%%%%%% + + + +% Remove following spaces at the expansion stage. +% This works because spaces are discarded before each argument when TeX is +% getting the arguments for a macro. +% This must not be immediately followed by a }. +\long\def\gobblespaces#1{#1} + +% This defines a Texinfo @macro or @rmacro, called by \parsemacbody. +% \macrobody has the body of the macro in it, with placeholders for +% its parameters, looking like "\processmacroarg{\hash 1}". +% \paramno is the number of parameters +% \paramlist is a TeX parameter text, e.g. "#1,#2,#3," +% There are eight cases: recursive and nonrecursive macros of zero, one, +% up to nine, and many arguments. % \xdef is used so that macro definitions will survive the file -% they're defined in; @include reads the file inside a group. +% they're defined in: @include reads the file inside a group. % \def\defmacro{% \let\hash=##% convert placeholders to macro parameter chars - \ifrecursive + \ifnum\paramno=1 + \def\processmacroarg{\gobblespaces}% + % This removes the pair of braces around the argument. We don't + % use \eatspaces, because this can cause ends of lines to be lost + % when the argument to \eatspaces is read, leading to line-based + % commands like "@itemize" not being read correctly. + \else + \def\processmacroarg{\xprocessmacroarg}% + \let\xprocessmacroarg\relax + \fi + \ifrecursive %%%%%%%%%%%%%% Recursive %%%%%%%%%%%%%%%%%%%%%%%%%%%%% \ifcase\paramno % 0 \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\scanmacro{\temp}}% + \noexpand\scanmacro{\macrobody}}% \or % 1 \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt + \bgroup \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% - \egroup\noexpand\scanmacro{\temp}}% + \expandafter\noexpand\csname\the\macname @@@\endcsname}% + \expandafter\xdef\csname\the\macname @@@\endcsname##1{% + \expandafter\noexpand\csname\the\macname @@@@\endcsname{% + \noexpand\gobblespaces##1\empty}% + % The \empty is for \gobblespaces in case #1 is empty + }% + \expandafter\xdef\csname\the\macname @@@@\endcsname##1{% + \egroup\noexpand\scanmacro{\macrobody}}% \else \ifnum\paramno<10\relax % at most 9 \expandafter\xdef\csname\the\macname\endcsname{% \bgroup\noexpand\macroargctxt - \noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \noexpand\csname\the\macname @@\endcsname}% + \expandafter\xdef\csname\the\macname @@\endcsname##1{% + \expandafter\noexpand\csname\the\macname @@@\endcsname ##1,}% \expandafter\expandafter \expandafter\xdef \expandafter\expandafter - \csname\the\macname xxx\endcsname - \paramlist{\egroup\noexpand\scanmacro{\temp}}% + \csname\the\macname @@@\endcsname + \paramlist{\egroup\noexpand\scanmacro{\macrobody}}% \else % 10 or more \expandafter\xdef\csname\the\macname\endcsname{% \noexpand\getargvals@{\the\macname}{\argl}% }% - \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp + \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble \fi \fi - \else + \else %%%%%%%%%%%%%%%%%%%%%% Non-recursive %%%%%%%%%%%%%%%%%%%%%%%%%% \ifcase\paramno % 0 \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% + \noexpand\scanmacro{\macrobody}}% \or % 1 \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt + \bgroup \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% + \expandafter\noexpand\csname\the\macname @@@\endcsname}% + \expandafter\xdef\csname\the\macname @@@\endcsname##1{% + \expandafter\noexpand\csname\the\macname @@@@\endcsname{% + \noexpand\gobblespaces##1\empty}% + % The \empty is for \gobblespaces in case #1 is empty + }% + \expandafter\xdef\csname\the\macname @@@@\endcsname##1{% \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% + \noexpand\scanmacro{\macrobody}% + }% \else % at most 9 \ifnum\paramno<10\relax \expandafter\xdef\csname\the\macname\endcsname{% \bgroup\noexpand\macroargctxt - \expandafter\noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \expandafter\noexpand\csname\the\macname @@\endcsname}% + \expandafter\xdef\csname\the\macname @@\endcsname##1{% + \expandafter\noexpand\csname\the\macname @@@\endcsname ##1,}% \expandafter\expandafter \expandafter\xdef \expandafter\expandafter - \csname\the\macname xxx\endcsname + \csname\the\macname @@@\endcsname \paramlist{% \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% + \noexpand\scanmacro{\macrobody}% + }% \else % 10 or more: \expandafter\xdef\csname\the\macname\endcsname{% \noexpand\getargvals@{\the\macname}{\argl}% }% - \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp + \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\norecurse \fi \fi \fi} -\catcode `\@\texiatcatcode\relax +\catcode `\@\texiatcatcode\relax % end private-to-Texinfo catcodes \def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} -% \braceorline decides whether the next nonwhitespace character is a -% {. If so it reads up to the closing }, if not, it reads the whole -% line. Whatever was read is then fed to the next control sequence -% as an argument (by \parsebrace or \parsearg). + +{\catcode`\@=0 \catcode`\\=13 +@catcode`@_=11 + +% Call #1 with a list of tokens #2, with any doubled backslashes in #2 +% compressed to one. +@gdef@passargtomacro#1#2{% + @def@the_macro{#1}% + @def@pending_backslash{}% + @def@finish{@finish}% + @def@arg_result{}% + @let@next_token=@relax + @add_segment#2\@finish\% +} + +% Input stream is just after a backslash. If the next token is not a +% backslash, process the rest of the argument; otherwise, remove the next +% token. +@gdef@look_ahead{% + @futurelet@next_token@look_aheadzzz} +@gdef@look_aheadzzz{% + @ifx@next_token\% + @let@next=@gobble_and_check_finish + @else + @let@next=@add_segment + @fi@next +} + +% Double backslash found. Add a single backslash here. +@gdef@gobble_and_check_finish#1{% + @add_the_backslash + @def@pending_backslash{}% + @futurelet@next_token@add_segment +} + +% append a backslash to \arg_result +@gdef@add_the_backslash{% + @expandafter@gdef@expandafter@arg_result@expandafter{@arg_result\}% +} + +% Input stream is either at the start of the argument, or just after a +% backslash sequence, either a lone backslash, or a doubled backslash. +% \next_token contains the first token in the input stream: if it is \finish, +% finish; otherwise, append to \arg_result the segment of the argument up until +% the next backslash. \pending_backslash contains a backslash to represent +% a backslash just before the start of the input stream that has not been +% added to \arg_result. +@gdef@add_segment#1\{% +@ifx@next_token@finish + @let@next=@call_the_macro% +@else + @let@next=@look_ahead + % + % append to @arg_result + % token list registers might be better + @expandafter@expandafter@expandafter@gdef + @expandafter@expandafter@expandafter@arg_result + @expandafter@expandafter@expandafter{% + @expandafter@arg_result + @pending_backslash#1}% + @def@pending_backslash{\}% +@fi@next} + +@gdef@call_the_macro{@expandafter@the_macro@expandafter{@arg_result}} + +} + +% \braceorline MAC is used for a one-argument macro MAC. It checks +% whether the next non-whitespace character is a {. It sets the context +% for reading the argument (slightly different in the two cases). Then, +% to read the argument, in the whole-line case, it then calls the regular +% \parsearg MAC; in the lbrace case, it calls \passargtomacro MAC. % \def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} \def\braceorlinexxx{% - \ifx\nchar\bgroup\else - \expandafter\parsearg + \ifx\nchar\bgroup + \macroargctxt + \expandafter\passargtomacro + \else + \macrolineargctxt\expandafter\parsearg \fi \macnamexxx} @@ -7870,6 +8337,7 @@ end \pdfmkdest{#1}% \iflinks {% + \requireauxfile \atdummies % preserve commands, but don't expand them \edef\writexrdef##1##2{% \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef @@ -7909,9 +8377,12 @@ end % node name, #4 the name of the Info file, #5 the name of the printed % manual. All but the node name can be omitted. % -\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} -\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} -\def\ref#1{\xrefX[#1,,,,,,,]} +\def\pxref{\putwordsee{} \xrefXX} +\def\xref{\putwordSee{} \xrefXX} +\def\ref{\xrefXX} + +\def\xrefXX#1{\def\xrefXXarg{#1}\futurelet\tokenafterxref\xrefXXX} +\def\xrefXXX{\expandafter\xrefX\expandafter[\xrefXXarg,,,,,,,]} % \newbox\toprefbox \newbox\printedrefnamebox @@ -8055,6 +8526,12 @@ end % % output the `page 3'. \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \ifx,\tokenafterxref + \else\ifx.\tokenafterxref + \else\ifx;\tokenafterxref + \else\ifx)\tokenafterxref + \else,% add a , if xref not followed by punctuation + \fi\fi\fi\fi \fi\fi \fi \endlink @@ -8125,6 +8602,7 @@ end % If its value is nonempty, SUFFIX is output afterward. % \def\refx#1#2{% + \requireauxfile {% \indexnofonts \otherbackslash @@ -8188,6 +8666,23 @@ end \fi } +% If working on a large document in chapters, it is convenient to +% be able to disable indexing, cross-referencing, and contents, for test runs. +% This is done with @novalidate at the beginning of the file. +% +\newif\iflinks \linkstrue % by default we want the aux files. +\let\novalidate = \linksfalse + +% Used when writing to the aux file, or when using data from it. +\def\requireauxfile{% + \iflinks + \tryauxfile + % Open the new aux file. TeX will close it automatically at exit. + \immediate\openout\auxfile=\jobname.aux + \fi + \global\let\requireauxfile=\relax % Only do this once. +} + % Read the last existing aux file, if any. No error if none exists. % \def\tryauxfile{% @@ -8267,14 +8762,7 @@ end \catcode`\\=\other % % Make the characters 128-255 be printing characters. - {% - \count1=128 - \def\loop{% - \catcode\count1=\other - \advance\count1 by 1 - \ifnum \count1<256 \loop \fi - }% - }% + {\setnonasciicharscatcodenonglobal\other}% % % @ is our escape character in .aux files, and we need braces. \catcode`\{=1 @@ -8308,8 +8796,6 @@ end % % Auto-number footnotes. Otherwise like plain. \gdef\footnote{% - \let\indent=\ptexindent - \let\noindent=\ptexnoindent \global\advance\footnoteno by \@ne \edef\thisfootno{$^{\the\footnoteno}$}% % @@ -8333,6 +8819,11 @@ end % \gdef\dofootnote{% \insert\footins\bgroup + % + % Nested footnotes are not supported in TeX, that would take a lot + % more work. (\startsavinginserts does not suffice.) + \let\footnote=\errfootnotenest + % % We want to typeset this text as a normal paragraph, even if the % footnote reference occurs in (for example) a display environment. % So reset some parameters. @@ -8370,13 +8861,24 @@ end } }%end \catcode `\@=11 +\def\errfootnotenest{% + \errhelp=\EMsimple + \errmessage{Nested footnotes not supported in texinfo.tex, + even though they work in makeinfo; sorry} +} + +\def\errfootnoteheading{% + \errhelp=\EMsimple + \errmessage{Footnotes in chapters, sections, etc., are not supported} +} + % In case a @footnote appears in a vbox, save the footnote text and create % the real \insert just after the vbox finished. Otherwise, the insertion % would be lost. % Similarly, if a @footnote appears inside an alignment, save the footnote % text to a box and make the \insert when a row of the table is finished. % And the same can be done for other insert classes. --kasal, 16nov03. - +% % Replace the \insert primitive by a cheating macro. % Deeper inside, just make sure that the saved insertions are not spilled % out prematurely. @@ -8474,6 +8976,7 @@ end \def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup \catcode`\^^M = 5 % in case we're inside an example \normalturnoffactive % allow _ et al. in names + \def\xprocessmacroarg{\eatspaces}% in case we are being used via a macro % If the image is by itself, center it. \ifvmode \imagevmodetrue @@ -8654,6 +9157,7 @@ end % \floatlabel-lof. Besides \floatident, we include the short % caption if specified, else the full caption if specified, else nothing. {% + \requireauxfile \atdummies % % since we read the caption text in the macro world, where ^^M @@ -8793,20 +9297,20 @@ end { \catcode`\_ = \active \globaldefs=1 -\parseargdef\documentlanguage{\begingroup - \let_=\normalunderscore % normal _ character for filenames +\parseargdef\documentlanguage{% \tex % read txi-??.tex file in plain TeX. % Read the file by the name they passed if it exists. + \let_ = \normalunderscore % normal _ character for filename test \openin 1 txi-#1.tex \ifeof 1 - \documentlanguagetrywithoutunderscore{#1_\finish}% + \documentlanguagetrywithoutunderscore #1_\finish \else \globaldefs = 1 % everything in the txi-LL files needs to persist \input txi-#1.tex \fi \closein 1 \endgroup % end raw TeX -\endgroup} +} % % If they passed de_DE, and txi-de_DE.tex doesn't exist, % try txi-de.tex. @@ -8876,7 +9380,8 @@ directory should work if nowhere else does.} % @documentencoding sets the definition of non-ASCII characters % according to the specified encoding. % -\parseargdef\documentencoding{% +\def\documentencoding{\parseargusing\filenamecatcodes\documentencodingzzz} +\def\documentencodingzzz#1{% % Encoding being declared for the document. \def\declaredencoding{\csname #1.enc\endcsname}% % @@ -8905,10 +9410,12 @@ directory should work if nowhere else does.} % \else \ifx \declaredencoding \utfeight \setnonasciicharscatcode\active - \utfeightchardefs + % since we already invoked \utfeightchardefs at the top level + % (below), do not re-invoke it, then our check for duplicated + % definitions triggers. Making non-ascii chars active is enough. % \else - \message{Unknown document encoding #1, ignoring.}% + \message{Ignoring unknown document encoding: #1.}% % \fi % utfeight \fi % latnine @@ -8917,10 +9424,11 @@ directory should work if nowhere else does.} \fi % ascii } +% emacs-page % A message to be logged when using a character that isn't available % the default font encoding (OT1). % -\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}} +\def\missingcharmsg#1{\message{Character missing, sorry: #1.}} % Take account of \c (plain) vs. \, (Texinfo) difference. \def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi} @@ -8934,17 +9442,17 @@ directory should work if nowhere else does.} \def\latonechardefs{% \gdef^^a0{\tie} \gdef^^a1{\exclamdown} - \gdef^^a2{\missingcharmsg{CENT SIGN}} - \gdef^^a3{{\pounds}} - \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} - \gdef^^a5{\missingcharmsg{YEN SIGN}} - \gdef^^a6{\missingcharmsg{BROKEN BAR}} + \gdef^^a2{{\tcfont \char162}} % cent + \gdef^^a3{\pounds} + \gdef^^a4{{\tcfont \char164}} % currency + \gdef^^a5{{\tcfont \char165}} % yen + \gdef^^a6{{\tcfont \char166}} % broken bar \gdef^^a7{\S} \gdef^^a8{\"{}} \gdef^^a9{\copyright} \gdef^^aa{\ordf} \gdef^^ab{\guillemetleft} - \gdef^^ac{$\lnot$} + \gdef^^ac{\ensuremath\lnot} \gdef^^ad{\-} \gdef^^ae{\registeredsymbol} \gdef^^af{\={}} @@ -8956,12 +9464,10 @@ directory should work if nowhere else does.} \gdef^^b4{\'{}} \gdef^^b5{$\mu$} \gdef^^b6{\P} - % - \gdef^^b7{$^.$} + \gdef^^b7{\ensuremath\cdot} \gdef^^b8{\cedilla\ } \gdef^^b9{$^1$} \gdef^^ba{\ordm} - % \gdef^^bb{\guillemetright} \gdef^^bc{$1\over4$} \gdef^^bd{$1\over2$} @@ -9216,6 +9722,18 @@ directory should work if nowhere else does.} \UTFviiiLoop \endgroup +\def\globallet{\global\let} % save some \expandafter's below + +% @U{xxxx} to produce U+xxxx, if we support it. +\def\U#1{% + \expandafter\ifx\csname uni:#1\endcsname \relax + \errhelp = \EMsimple + \errmessage{Unicode character U+#1 not supported, sorry}% + \else + \csname uni:#1\endcsname + \fi +} + \begingroup \catcode`\"=12 \catcode`\<=12 @@ -9224,7 +9742,6 @@ directory should work if nowhere else does.} \catcode`\;=12 \catcode`\!=12 \catcode`\~=13 - \gdef\DeclareUnicodeCharacter#1#2{% \countUTFz = "#1\relax %\wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% @@ -9239,6 +9756,13 @@ directory should work if nowhere else does.} \expandafter\expandafter\expandafter\expandafter \expandafter\expandafter\expandafter \gdef\UTFviiiTmp{#2}% + % + \expandafter\ifx\csname uni:#1\endcsname \relax \else + \errmessage{Internal error, already defined: #1}% + \fi + % + % define an additional control sequence for this code point. + \expandafter\globallet\csname uni:#1\endcsname \UTFviiiTmp \endgroup} \gdef\parseXMLCharref{% @@ -9276,23 +9800,53 @@ directory should work if nowhere else does.} \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} \endgroup +% https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_M +% U+0000..U+007F = https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block) +% U+0080..U+00FF = https://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block) +% U+0100..U+017F = https://en.wikipedia.org/wiki/Latin_Extended-A +% U+0180..U+024F = https://en.wikipedia.org/wiki/Latin_Extended-B +% +% Many of our renditions are less than wonderful, and all the missing +% characters are available somewhere. Loading the necessary fonts +% awaits user request. We can't truly support Unicode without +% reimplementing everything that's been done in LaTeX for many years, +% plus probably using luatex or xetex, and who knows what else. +% We won't be doing that here in this simple file. But we can try to at +% least make most of the characters not bomb out. +% \def\utfeightchardefs{% \DeclareUnicodeCharacter{00A0}{\tie} \DeclareUnicodeCharacter{00A1}{\exclamdown} + \DeclareUnicodeCharacter{00A2}{{\tcfont \char162}}% 0242=cent \DeclareUnicodeCharacter{00A3}{\pounds} + \DeclareUnicodeCharacter{00A4}{{\tcfont \char164}}% 0244=currency + \DeclareUnicodeCharacter{00A5}{{\tcfont \char165}}% 0245=yen + \DeclareUnicodeCharacter{00A6}{{\tcfont \char166}}% 0246=brokenbar + \DeclareUnicodeCharacter{00A7}{\S} \DeclareUnicodeCharacter{00A8}{\"{ }} \DeclareUnicodeCharacter{00A9}{\copyright} \DeclareUnicodeCharacter{00AA}{\ordf} \DeclareUnicodeCharacter{00AB}{\guillemetleft} + \DeclareUnicodeCharacter{00AC}{\ensuremath\lnot} \DeclareUnicodeCharacter{00AD}{\-} \DeclareUnicodeCharacter{00AE}{\registeredsymbol} \DeclareUnicodeCharacter{00AF}{\={ }} \DeclareUnicodeCharacter{00B0}{\ringaccent{ }} + \DeclareUnicodeCharacter{00B1}{\ensuremath\pm} + \DeclareUnicodeCharacter{00B2}{$^2$} + \DeclareUnicodeCharacter{00B3}{$^3$} \DeclareUnicodeCharacter{00B4}{\'{ }} + \DeclareUnicodeCharacter{00B5}{$\mu$} + \DeclareUnicodeCharacter{00B6}{\P} + \DeclareUnicodeCharacter{00B7}{\ensuremath\cdot} \DeclareUnicodeCharacter{00B8}{\cedilla{ }} + \DeclareUnicodeCharacter{00B9}{$^1$} \DeclareUnicodeCharacter{00BA}{\ordm} \DeclareUnicodeCharacter{00BB}{\guillemetright} + \DeclareUnicodeCharacter{00BC}{$1\over4$} + \DeclareUnicodeCharacter{00BD}{$1\over2$} + \DeclareUnicodeCharacter{00BE}{$3\over4$} \DeclareUnicodeCharacter{00BF}{\questiondown} \DeclareUnicodeCharacter{00C0}{\`A} @@ -9319,6 +9873,7 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{00D4}{\^O} \DeclareUnicodeCharacter{00D5}{\~O} \DeclareUnicodeCharacter{00D6}{\"O} + \DeclareUnicodeCharacter{00D7}{\ensuremath\times} \DeclareUnicodeCharacter{00D8}{\O} \DeclareUnicodeCharacter{00D9}{\`U} \DeclareUnicodeCharacter{00DA}{\'U} @@ -9352,6 +9907,7 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{00F4}{\^o} \DeclareUnicodeCharacter{00F5}{\~o} \DeclareUnicodeCharacter{00F6}{\"o} + \DeclareUnicodeCharacter{00F7}{\ensuremath\div} \DeclareUnicodeCharacter{00F8}{\o} \DeclareUnicodeCharacter{00F9}{\`u} \DeclareUnicodeCharacter{00FA}{\'u} @@ -9371,20 +9927,23 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{0107}{\'c} \DeclareUnicodeCharacter{0108}{\^C} \DeclareUnicodeCharacter{0109}{\^c} - \DeclareUnicodeCharacter{0118}{\ogonek{E}} - \DeclareUnicodeCharacter{0119}{\ogonek{e}} \DeclareUnicodeCharacter{010A}{\dotaccent{C}} \DeclareUnicodeCharacter{010B}{\dotaccent{c}} \DeclareUnicodeCharacter{010C}{\v{C}} \DeclareUnicodeCharacter{010D}{\v{c}} \DeclareUnicodeCharacter{010E}{\v{D}} + \DeclareUnicodeCharacter{010F}{d'} + \DeclareUnicodeCharacter{0110}{\DH} + \DeclareUnicodeCharacter{0111}{\dh} \DeclareUnicodeCharacter{0112}{\=E} \DeclareUnicodeCharacter{0113}{\=e} \DeclareUnicodeCharacter{0114}{\u{E}} \DeclareUnicodeCharacter{0115}{\u{e}} \DeclareUnicodeCharacter{0116}{\dotaccent{E}} \DeclareUnicodeCharacter{0117}{\dotaccent{e}} + \DeclareUnicodeCharacter{0118}{\ogonek{E}} + \DeclareUnicodeCharacter{0119}{\ogonek{e}} \DeclareUnicodeCharacter{011A}{\v{E}} \DeclareUnicodeCharacter{011B}{\v{e}} \DeclareUnicodeCharacter{011C}{\^G} @@ -9394,14 +9953,20 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{0120}{\dotaccent{G}} \DeclareUnicodeCharacter{0121}{\dotaccent{g}} + \DeclareUnicodeCharacter{0122}{\cedilla{G}} + \DeclareUnicodeCharacter{0123}{\cedilla{g}} \DeclareUnicodeCharacter{0124}{\^H} \DeclareUnicodeCharacter{0125}{\^h} + \DeclareUnicodeCharacter{0126}{\missingcharmsg{H WITH STROKE}} + \DeclareUnicodeCharacter{0127}{\missingcharmsg{h WITH STROKE}} \DeclareUnicodeCharacter{0128}{\~I} \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}} \DeclareUnicodeCharacter{012A}{\=I} \DeclareUnicodeCharacter{012B}{\={\dotless{i}}} \DeclareUnicodeCharacter{012C}{\u{I}} \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}} + \DeclareUnicodeCharacter{012E}{\ogonek{I}} + \DeclareUnicodeCharacter{012F}{\ogonek{i}} \DeclareUnicodeCharacter{0130}{\dotaccent{I}} \DeclareUnicodeCharacter{0131}{\dotless{i}} @@ -9409,15 +9974,29 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{0133}{ij} \DeclareUnicodeCharacter{0134}{\^J} \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}} + \DeclareUnicodeCharacter{0136}{\cedilla{K}} + \DeclareUnicodeCharacter{0137}{\cedilla{k}} + \DeclareUnicodeCharacter{0138}{\ensuremath\kappa} \DeclareUnicodeCharacter{0139}{\'L} \DeclareUnicodeCharacter{013A}{\'l} + \DeclareUnicodeCharacter{013B}{\cedilla{L}} + \DeclareUnicodeCharacter{013C}{\cedilla{l}} + \DeclareUnicodeCharacter{013D}{L'}% should kern + \DeclareUnicodeCharacter{013E}{l'}% should kern + \DeclareUnicodeCharacter{013F}{L\U{00B7}} + \DeclareUnicodeCharacter{0140}{l\U{00B7}} \DeclareUnicodeCharacter{0141}{\L} \DeclareUnicodeCharacter{0142}{\l} \DeclareUnicodeCharacter{0143}{\'N} \DeclareUnicodeCharacter{0144}{\'n} + \DeclareUnicodeCharacter{0145}{\cedilla{N}} + \DeclareUnicodeCharacter{0146}{\cedilla{n}} \DeclareUnicodeCharacter{0147}{\v{N}} \DeclareUnicodeCharacter{0148}{\v{n}} + \DeclareUnicodeCharacter{0149}{'n} + \DeclareUnicodeCharacter{014A}{\missingcharmsg{ENG}} + \DeclareUnicodeCharacter{014B}{\missingcharmsg{eng}} \DeclareUnicodeCharacter{014C}{\=O} \DeclareUnicodeCharacter{014D}{\=o} \DeclareUnicodeCharacter{014E}{\u{O}} @@ -9429,6 +10008,8 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{0153}{\oe} \DeclareUnicodeCharacter{0154}{\'R} \DeclareUnicodeCharacter{0155}{\'r} + \DeclareUnicodeCharacter{0156}{\cedilla{R}} + \DeclareUnicodeCharacter{0157}{\cedilla{r}} \DeclareUnicodeCharacter{0158}{\v{R}} \DeclareUnicodeCharacter{0159}{\v{r}} \DeclareUnicodeCharacter{015A}{\'S} @@ -9440,10 +10021,12 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{0160}{\v{S}} \DeclareUnicodeCharacter{0161}{\v{s}} - \DeclareUnicodeCharacter{0162}{\cedilla{t}} - \DeclareUnicodeCharacter{0163}{\cedilla{T}} + \DeclareUnicodeCharacter{0162}{\cedilla{T}} + \DeclareUnicodeCharacter{0163}{\cedilla{t}} \DeclareUnicodeCharacter{0164}{\v{T}} - + \DeclareUnicodeCharacter{0165}{\v{t}} + \DeclareUnicodeCharacter{0166}{\missingcharmsg{H WITH STROKE}} + \DeclareUnicodeCharacter{0167}{\missingcharmsg{h WITH STROKE}} \DeclareUnicodeCharacter{0168}{\~U} \DeclareUnicodeCharacter{0169}{\~u} \DeclareUnicodeCharacter{016A}{\=U} @@ -9455,6 +10038,8 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{0170}{\H{U}} \DeclareUnicodeCharacter{0171}{\H{u}} + \DeclareUnicodeCharacter{0172}{\ogonek{U}} + \DeclareUnicodeCharacter{0173}{\ogonek{u}} \DeclareUnicodeCharacter{0174}{\^W} \DeclareUnicodeCharacter{0175}{\^w} \DeclareUnicodeCharacter{0176}{\^Y} @@ -9466,6 +10051,7 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{017C}{\dotaccent{z}} \DeclareUnicodeCharacter{017D}{\v{Z}} \DeclareUnicodeCharacter{017E}{\v{z}} + \DeclareUnicodeCharacter{017F}{\missingcharmsg{LONG S}} \DeclareUnicodeCharacter{01C4}{D\v{Z}} \DeclareUnicodeCharacter{01C5}{D\v{z}} @@ -9522,6 +10108,9 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{02DB}{\ogonek{ }} + % Greek letters + \DeclareUnicodeCharacter{03C0}{\ensuremath\pi} + \DeclareUnicodeCharacter{1E02}{\dotaccent{B}} \DeclareUnicodeCharacter{1E03}{\dotaccent{b}} \DeclareUnicodeCharacter{1E04}{\udotaccent{B}} @@ -9649,6 +10238,7 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{1EF8}{\~Y} \DeclareUnicodeCharacter{1EF9}{\~y} + % Punctuation \DeclareUnicodeCharacter{2013}{--} \DeclareUnicodeCharacter{2014}{---} \DeclareUnicodeCharacter{2018}{\quoteleft} @@ -9657,26 +10247,95 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{201C}{\quotedblleft} \DeclareUnicodeCharacter{201D}{\quotedblright} \DeclareUnicodeCharacter{201E}{\quotedblbase} + \DeclareUnicodeCharacter{2020}{\ensuremath\dagger} + \DeclareUnicodeCharacter{2021}{\ensuremath\ddagger} \DeclareUnicodeCharacter{2022}{\bullet} + \DeclareUnicodeCharacter{202F}{\thinspace} \DeclareUnicodeCharacter{2026}{\dots} \DeclareUnicodeCharacter{2039}{\guilsinglleft} \DeclareUnicodeCharacter{203A}{\guilsinglright} + \DeclareUnicodeCharacter{20AC}{\euro} \DeclareUnicodeCharacter{2192}{\expansion} \DeclareUnicodeCharacter{21D2}{\result} + % Mathematical symbols + \DeclareUnicodeCharacter{2200}{\ensuremath\forall} + \DeclareUnicodeCharacter{2203}{\ensuremath\exists} + \DeclareUnicodeCharacter{2208}{\ensuremath\in} \DeclareUnicodeCharacter{2212}{\minus} \DeclareUnicodeCharacter{2217}{\point} + \DeclareUnicodeCharacter{221E}{\ensuremath\infty} + \DeclareUnicodeCharacter{2225}{\ensuremath\parallel} + \DeclareUnicodeCharacter{2227}{\ensuremath\wedge} + \DeclareUnicodeCharacter{2229}{\ensuremath\cap} \DeclareUnicodeCharacter{2261}{\equiv} -}% end of \utfeightchardefs + \DeclareUnicodeCharacter{2264}{\ensuremath\leq} + \DeclareUnicodeCharacter{2265}{\ensuremath\geq} + \DeclareUnicodeCharacter{2282}{\ensuremath\subset} + \DeclareUnicodeCharacter{2287}{\ensuremath\supseteq} + \global\mathchardef\checkmark="1370 % actually the square root sign + \DeclareUnicodeCharacter{2713}{\ensuremath\checkmark} +}% end of \utfeightchardefs % US-ASCII character definitions. \def\asciichardefs{% nothing need be done \relax } +% Latin1 (ISO-8859-1) character definitions. +\def\nonasciistringdefs{% + \setnonasciicharscatcode\active + \def\defstringchar##1{\def##1{\string##1}}% + % + \defstringchar^^80\defstringchar^^81\defstringchar^^82\defstringchar^^83% + \defstringchar^^84\defstringchar^^85\defstringchar^^86\defstringchar^^87% + \defstringchar^^88\defstringchar^^89\defstringchar^^8a\defstringchar^^8b% + \defstringchar^^8c\defstringchar^^8d\defstringchar^^8e\defstringchar^^8f% + % + \defstringchar^^90\defstringchar^^91\defstringchar^^92\defstringchar^^93% + \defstringchar^^94\defstringchar^^95\defstringchar^^96\defstringchar^^97% + \defstringchar^^98\defstringchar^^99\defstringchar^^9a\defstringchar^^9b% + \defstringchar^^9c\defstringchar^^9d\defstringchar^^9e\defstringchar^^9f% + % + \defstringchar^^a0\defstringchar^^a1\defstringchar^^a2\defstringchar^^a3% + \defstringchar^^a4\defstringchar^^a5\defstringchar^^a6\defstringchar^^a7% + \defstringchar^^a8\defstringchar^^a9\defstringchar^^aa\defstringchar^^ab% + \defstringchar^^ac\defstringchar^^ad\defstringchar^^ae\defstringchar^^af% + % + \defstringchar^^b0\defstringchar^^b1\defstringchar^^b2\defstringchar^^b3% + \defstringchar^^b4\defstringchar^^b5\defstringchar^^b6\defstringchar^^b7% + \defstringchar^^b8\defstringchar^^b9\defstringchar^^ba\defstringchar^^bb% + \defstringchar^^bc\defstringchar^^bd\defstringchar^^be\defstringchar^^bf% + % + \defstringchar^^c0\defstringchar^^c1\defstringchar^^c2\defstringchar^^c3% + \defstringchar^^c4\defstringchar^^c5\defstringchar^^c6\defstringchar^^c7% + \defstringchar^^c8\defstringchar^^c9\defstringchar^^ca\defstringchar^^cb% + \defstringchar^^cc\defstringchar^^cd\defstringchar^^ce\defstringchar^^cf% + % + \defstringchar^^d0\defstringchar^^d1\defstringchar^^d2\defstringchar^^d3% + \defstringchar^^d4\defstringchar^^d5\defstringchar^^d6\defstringchar^^d7% + \defstringchar^^d8\defstringchar^^d9\defstringchar^^da\defstringchar^^db% + \defstringchar^^dc\defstringchar^^dd\defstringchar^^de\defstringchar^^df% + % + \defstringchar^^e0\defstringchar^^e1\defstringchar^^e2\defstringchar^^e3% + \defstringchar^^e4\defstringchar^^e5\defstringchar^^e6\defstringchar^^e7% + \defstringchar^^e8\defstringchar^^e9\defstringchar^^ea\defstringchar^^eb% + \defstringchar^^ec\defstringchar^^ed\defstringchar^^ee\defstringchar^^ef% + % + \defstringchar^^f0\defstringchar^^f1\defstringchar^^f2\defstringchar^^f3% + \defstringchar^^f4\defstringchar^^f5\defstringchar^^f6\defstringchar^^f7% + \defstringchar^^f8\defstringchar^^f9\defstringchar^^fa\defstringchar^^fb% + \defstringchar^^fc\defstringchar^^fd\defstringchar^^fe\defstringchar^^ff% +} + + +% define all the unicode characters we know about, for the sake of @U. +\utfeightchardefs + + % Make non-ASCII characters printable again for compatibility with % existing Texinfo documents that may use them, even without declaring a % document encoding. @@ -9944,11 +10603,9 @@ directory should work if nowhere else does.} \catcode`\"=\active \def\activedoublequote{{\tt\char34}} \let"=\activedoublequote -\catcode`\~=\active -\def~{{\tt\char126}} -\chardef\hat=`\^ -\catcode`\^=\active -\def^{{\tt \hat}} +\catcode`\~=\active \def\activetilde{{\tt\char126}} \let~ = \activetilde +\chardef\hatchar=`\^ +\catcode`\^=\active \def\activehat{{\tt \hatchar}} \let^ = \activehat \catcode`\_=\active \def_{\ifusingtt\normalunderscore\_} @@ -9958,22 +10615,28 @@ directory should work if nowhere else does.} \catcode`\|=\active \def|{{\tt\char124}} + \chardef \less=`\< -\catcode`\<=\active -\def<{{\tt \less}} +\catcode`\<=\active \def\activeless{{\tt \less}}\let< = \activeless \chardef \gtr=`\> -\catcode`\>=\active -\def>{{\tt \gtr}} -\catcode`\+=\active -\def+{{\tt \char 43}} -\catcode`\$=\active -\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix +\catcode`\>=\active \def\activegtr{{\tt \gtr}}\let> = \activegtr +\catcode`\+=\active \def+{{\tt \char 43}} +\catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix +\catcode`\-=\active \let-=\normaldash -% If a .fmt file is being used, characters that might appear in a file -% name cannot be active until we have parsed the command line. -% So turn them off again, and have \everyjob (or @setfilename) turn them on. -% \otherifyactive is called near the end of this file. -\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} + +% used for headline/footline in the output routine, in case the page +% breaks in the middle of an @tex block. +\def\texinfochars{% + \let< = \activeless + \let> = \activegtr + \let~ = \activetilde + \let^ = \activehat + \markupsetuplqdefault \markupsetuprqdefault + \let\b = \strong + \let\i = \smartitalic + % in principle, all other definitions in \tex have to be undone too. +} % Used sometimes to turn off (effectively) the active characters even after % parsing them. @@ -9993,23 +10656,22 @@ directory should work if nowhere else does.} % \doublebackslash is two of them (for the pdf outlines). {\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} -% In texinfo, backslash is an active character; it prints the backslash +% In Texinfo, backslash is an active character; it prints the backslash % in fixed width font. \catcode`\\=\active % @ for escape char from now on. -% The story here is that in math mode, the \char of \backslashcurfont -% ends up printing the roman \ from the math symbol font (because \char -% in math mode uses the \mathcode, and plain.tex sets -% \mathcode`\\="026E). It seems better for @backslashchar{} to always -% print a typewriter backslash, hence we use an explicit \mathchar, +% Print a typewriter backslash. For math mode, we can't simply use +% \backslashcurfont: the story here is that in math mode, the \char +% of \backslashcurfont ends up printing the roman \ from the math symbol +% font (because \char in math mode uses the \mathcode, and plain.tex +% sets \mathcode`\\="026E). Hence we use an explicit \mathchar, % which is the decimal equivalent of "715c (class 7, e.g., use \fam; % ignored family value; char position "5C). We can't use " for the % usual hex value because it has already been made active. -@def@normalbackslash{{@tt @ifmmode @mathchar29020 @else @backslashcurfont @fi}} -@let@backslashchar = @normalbackslash % @backslashchar{} is for user documents. -% On startup, @fixbackslash assigns: -% @let \ = @normalbackslash +@def@ttbackslash{{@tt @ifmmode @mathchar29020 @else @backslashcurfont @fi}} +@let@backslashchar = @ttbackslash % @backslashchar{} is for user documents. + % \rawbackslash defines an active \ to do \backslashcurfont. % \otherbackslash defines an active \ to be a literal `\' character with % catcode other. We switch back and forth between these. @@ -10017,51 +10679,77 @@ directory should work if nowhere else does.} @gdef@otherbackslash{@let\=@realbackslash} % Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of -% the literal character `\'. Also revert - to its normal character, in -% case the active - from code has slipped in. +% the literal character `\'. % {@catcode`- = @active @gdef@normalturnoffactive{% + @nonasciistringdefs @let-=@normaldash @let"=@normaldoublequote @let$=@normaldollar %$ font-lock fix @let+=@normalplus @let<=@normalless @let>=@normalgreater - @let\=@normalbackslash @let^=@normalcaret @let_=@normalunderscore @let|=@normalverticalbar @let~=@normaltilde + @let\=@ttbackslash @markupsetuplqdefault @markupsetuprqdefault @unsepspaces } } -% Make _ and + \other characters, temporarily. -% This is canceled by @fixbackslash. -@otherifyactive +% If a .fmt file is being used, characters that might appear in a file +% name cannot be active until we have parsed the command line. +% So turn them off again, and have @fixbackslash turn them back on. +@catcode`+=@other @catcode`@_=@other +% \enablebackslashhack - allow file to begin `\input texinfo' +% % If a .fmt file is being used, we don't want the `\input texinfo' to show up. % That is what \eatinput is for; after that, the `\' should revert to printing % a backslash. -% -@gdef@eatinput input texinfo{@fixbackslash} -@global@let\ = @eatinput +% If the file did not have a `\input texinfo', then it is turned off after +% the first line; otherwise the first `\' in the file would cause an error. +% This is used on the very last line of this file, texinfo.tex. +% We also use @c to call @fixbackslash, in case ends of lines are hidden. +{ +@catcode`@^=7 +@catcode`@^^M=13@gdef@enablebackslashhack{% + @global@let\ = @eatinput% + @catcode`@^^M=13% + @def@c{@fixbackslash@c}% + @def ^^M{@let^^M@secondlinenl}% + @gdef @secondlinenl{@let^^M@thirdlinenl}% + @gdef @thirdlinenl{@fixbackslash}% +}} + +{@catcode`@^=7 @catcode`@^^M=13% +@gdef@eatinput input texinfo#1^^M{@fixbackslash}} -% On the other hand, perhaps the file did not have a `\input texinfo'. Then -% the first `\' in the file would cause an error. This macro tries to fix -% that, assuming it is called before the first `\' could plausibly occur. -% Also turn back on active characters that might appear in the input -% file name, in case not using a pre-dumped format. -% @gdef@fixbackslash{% - @ifx\@eatinput @let\ = @normalbackslash @fi + @ifx\@eatinput @let\ = @ttbackslash @fi + @catcode13=5 % regular end of line + @let@c=@texinfoc + % Also turn back on active characters that might appear in the input + % file name, in case not using a pre-dumped format. @catcode`+=@active @catcode`@_=@active + % + % If texinfo.cnf is present on the system, read it. + % Useful for site-wide @afourpaper, etc. This macro, @fixbackslash, gets + % called at the beginning of every Texinfo file. Not opening texinfo.cnf + % directly in this file, texinfo.tex, makes it possible to make a format + % file for Texinfo. + % + @openin 1 texinfo.cnf + @ifeof 1 @else @input texinfo.cnf @fi + @closein 1 } + % Say @foo, not \foo, in error messages. @escapechar = `@@ @@ -10090,7 +10778,7 @@ directory should work if nowhere else does.} @c Local variables: @c eval: (add-hook 'write-file-hooks 'time-stamp) -@c page-delimiter: "^\\\\message" +@c page-delimiter: "^\\\\message\\|emacs-page" @c time-stamp-start: "def\\\\texinfoversion{" @c time-stamp-format: "%:y-%02m-%02d.%02H" @c time-stamp-end: "}" @@ -10101,3 +10789,4 @@ directory should work if nowhere else does.} @ignore arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 @end ignore +@enablebackslashhack diff --git a/doc/misc/todo-mode.texi b/doc/misc/todo-mode.texi index a622298ba12..69656da8880 100644 --- a/doc/misc/todo-mode.texi +++ b/doc/misc/todo-mode.texi @@ -1,20 +1,21 @@ \input texinfo.tex @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/todo-mode +@setfilename ../../info/todo-mode.info @settitle Todo Mode User Manual +@include docstyle.texi @syncodeindex fn cp @syncodeindex vr cp @syncodeindex ky cp @c %**end of header @copying -Copyright @copyright{} 2013 Free Software Foundation, Inc. +Copyright @copyright{} 2013-2015 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'', +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''. @@ -25,7 +26,7 @@ modify this GNU manual.'' @dircategory Emacs misc features @direntry -* Todo Mode: (todo-mode). Make and maintain todo lists. +* Todo Mode: (todo-mode). Make and maintain todo lists. @end direntry @titlepage @@ -157,11 +158,10 @@ you want. All todo files reside in a single directory, whose location is specified by the user option @code{todo-directory}. This directory may also contain other types of Todo files, which are discussed later -(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}). Emacs -recognizes Todo files by their extension, so when you visit the files -the buffer is in the appropriate mode and the current category is -correctly displayed. - +(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}). +@c Emacs recognizes Todo files by their extension, so when you visit +@c the files the buffer is in the appropriate mode and the current +@c category is correctly displayed. When you use a Todo mode command to create a todo file, the extension @samp{.todo} is automatically added to the base name you choose (as a rule, this name is also used for the other types of Todo files, which @@ -187,13 +187,15 @@ diary, date and time stamps, whether it is done or still to do. @node Todo Items as Diary Entries, , Levels of Organization, Overview @section Todo Items as Diary Entries -Each todo item is also a potential diary item: if you include a todo -file in the Emacs diary file (@pxref{Fancy Diary Display,,, emacs}), the -Fancy Diary display will show those todo items that are not marked with -@code{todo-nondiary-marker}. This effectively augments the Emacs diary -with categorized diary entries. For the various options available for -making a todo item a diary entry, see @ref{Inserting New Items} and -@ref{Editing Item Headers and Text}. +You can have todo items show up in the Emacs Fancy Diary display by +including the todo file in your diary file (@pxref{Fancy Diary +Display,,, emacs}). This effectively augments the Emacs diary with +categorized diary entries. All items in an included todo file will +appear in the Fancy Diary display except for those that are marked +with @code{todo-nondiary-marker}. You can add or omit this marking +upon creating a new todo item, or you can do so by editing an existing +item, see @ref{Inserting New Items} and @ref{Editing Item Headers and +Text} for details. To ensure the proper display of todo items in the Fancy Diary display, they must have the format of diary entries, i.e., they have to begin @@ -244,30 +246,26 @@ default todo file. If you want to enter Todo mode and go directly to a specific category instead the first or current category in the current or default todo -file, use the command @code{todo-jump-to-category}; @ref{Navigation}, for -details. You can also enter Todo mode by invoking a todo item insertion -command; @ref{Inserting New Items}, for details. +file, use the command @code{todo-jump-to-category}; @ref{Navigation}, +for details. You can also enter Todo mode by invoking the command +@code{todo-insert-item}; @ref{Inserting New Items}, for details. The most convenient way to use these commands to enter Todo mode is to -define global key bindings for them in your init file. Good choices are -for @code{todo-show} and @code{todo-jump-to-category} are @kbd{C-c t} -and @kbd{C-c j}, since these commands are bound to @kbd{t} and @kbd{j}, -respectively, in Todo mode. For invoking item insertion from outside of -Todo mode, it is useful to bind @code{todo-insertion-map}, which is the -key map containing the bindings of all Todo item insertion commands, to -@kbd{C-c i}, since it is bound to @kbd{i} in Todo mode; to complete the -invocation, supply the rest of the key sequence (@pxref{Inserting New -Items}). - -You can also visit a Todo file via @code{find-file} or Dired, like any -other file, and since Emacs recognizes it, the buffer will automatically -be in the appropriate Todo mode. Moreover, as long as the command you -use to visit the file is listed in the option -@code{todo-visit-files-commands} (which by default contains -@code{find-file} and @code{dired-find-file}), it will also correctly -display the file's first category on first visiting the file (otherwise -you have to use one of the commands for navigating between categories in -order to get a proper display). +define global key bindings for them in your init file. Good choices +are @kbd{C-c t} for @code{todo-show}, @kbd{C-c j} for +@code{todo-jump-to-category} and @kbd{C-c i} for +@code{todo-insert-item}, since these commands are bound to @kbd{t}, +@kbd{j} and @kbd{i}, respectively, in Todo mode. + +@c You can also visit a Todo file via @code{find-file} or Dired, like any +@c other file, and since Emacs recognizes it, the buffer will automatically +@c be in the appropriate Todo mode. Moreover, as long as the command you +@c use to visit the file is listed in the option +@c @code{todo-visit-files-commands} (which by default contains +@c @code{find-file} and @code{dired-find-file}), it will also correctly +@c display the file's first category on first visiting the file (otherwise +@c you have to use one of the commands for navigating between categories in +@c order to get a proper display). You can leave Todo mode by typing @kbd{q} (@code{todo-quit}), which buries the current todo file buffer. Doing this also saves any changes @@ -296,12 +294,12 @@ for the shift key for capitalization and the raw prefix argument number key. The predefined key bindings in Todo are more or less mnemonic. As a -rule, key sequences beginning with @kbd{C} are bound to commands -applying to categories, sequences beginning with @kbd{F} apply to -(non-archive) file-level commands, and those beginning with @kbd{A} -apply to archives (a special type of Todo file; @ref{Todo Archive -Mode}). Todo commands applying to items, which constitute the majority, -are bound to lower case key sequences. +rule, key sequences beginning with @kbd{C} (capital @samp{C}, not the +control key) are bound to commands applying to categories, sequences +beginning with @kbd{F} apply to (non-archive) file-level commands, and +those beginning with @kbd{A} apply to archives (a special type of Todo +file; @ref{Todo Archive Mode}). Todo commands applying to items, +which constitute the majority, are bound to lower case key sequences. @node Navigation, Editing, Key Binding Conventions, Top @chapter Navigation @@ -314,8 +312,8 @@ commands are likely to be used frequently and repetitively, it is convenient for their key bindings to be single lower case keys, even for navigation commands applying to categories and files. -Two of the navigation commands were already mentioned in the section on -Todo mode entry points: +Two of the navigation commands were already mentioned in @ref{Todo +Mode Entry Points}: @table @kbd @@ -396,11 +394,17 @@ sections below. Editing in Todo mode means making structural or textual changes at one of the levels of organization (file, category, or item). Structural -editing includes adding, relocating and removing, textual editing includes -renaming files or categories and changing an item's content or date, or -adding certain kinds of marks or tags to items. To save changes you -make to the current todo file, type @kbd{s} (@code{todo-save}). Changes -are also saved on quitting Todo mode with @kbd{q}. +editing includes adding, relocating and removing units of information +at a level; textual editing includes renaming files or categories and +changing an item's content or date/time stamp, or adding certain kinds +of marks or tags to items. Todo mode provides commands, detailed in +the following sections, which enable you to quickly and safely make +changes to your todo lists, without having to worry about preserving +the file format. + +To save changes you make to the current todo file, +type @kbd{s} (@code{todo-save}). Changes are also saved on quitting +Todo mode with @kbd{q}. @menu * File Editing:: @@ -416,12 +420,12 @@ There are four file-level editing commands: @table @kbd @item F a -Add a new todo file (@code{todo-add-file}). This command prompts for a -name and creates the file in @code{todo-directory}, adding the +Add a new todo file (@code{todo-add-file}). This command prompts for +a name and creates the file in @code{todo-directory}, adding the @samp{.todo} extension (so you should not include the extension in the -name you enter). The command also prompts for the file's first category and, if -option @code{todo-add-item-if-new-category} is enabled (the default), -for that category's first item. +name you enter). The command also prompts for the file's first +category and, if option @code{todo-add-item-if-new-category} is +enabled (the default), for that category's first item. @item F r Rename the current todo file (@code{todo-rename-file}). If called with @@ -429,20 +433,20 @@ a prefix argument, prompt for a todo file and rename it. If the todo file has an archive (@pxref{Todo Archive Mode}) or there are corresponding filtered items files (@pxref{Todo Filtered Items Mode}), this command renames these accordingly. If there are live buffers -visiting any of these files, the command also rename them accordingly. +visiting any of these files, the command also renames them accordingly. @item F k Delete the current todo file (@code{todo-delete-file}).@footnote{The key binding of this command is mnemonic for ``kill'' to parallel the binding @kbd{k} for item deletion, since @kbd{d} is bound to another item editing command (@pxref{Done Items}).} If the todo file has an archive -(@pxref{Todo Archive Mode}), prompt whether to delete that as well. -This command also kill the buffers visiting the deleted files. +(@pxref{Todo Archive Mode}), prompt for whether to delete that as well. +This command also kills the buffers visiting the deleted files. @item F e This command (@code{todo-edit-file}) changes the buffer's major mode to Todo Edit mode. In this mode the entire file is visible, the buffer is -writeable and you can use the self-insertion keys and standard Emacs +writable and you can use the self-insertion keys and standard Emacs editing commands to make changes. To return to Todo mode, type @kbd{C-x C-q} (@code{todo-edit-quit}). @@ -457,20 +461,21 @@ text that occurs in different categories throughout the file. The other use case is to recover from a mistake, such as accidentally deleting an item, since this cannot be undone in Todo mode. -Using @kbd{C-x C-q} to quit Todo Edit mode provides a measure of safety, -since it runs a file format check, signaling an error if the format has -become invalid. However, this check cannot tell if the number of items -changed, which could result in the file containing inconsistent -information (see the cautionary note in @ref{Reordering Categories}, for -more details). For this reason @kbd{F e} should be used with caution. +Using @kbd{C-x C-q} to quit Todo Edit mode provides a measure of +safety, since it runs a file format check, signaling an error if the +format has become invalid. However, this check cannot tell if the +number of items or categories changed, which could result in the file +containing inconsistent information (see the cautionary note in +@ref{Reordering Categories}, for more details). Invoking @kbd{F e} +displays a warning to this effect. @end table @node Category Editing, Item Editing, File Editing, Editing @section Category Editing -The following commands are available for editing at the category level -(for additional category-editing commands, which are extensions of item -commands, @pxref{Editing Item Headers and Text}): +The following commands are available for editing specifically at the +category level (for two other category-editing commands, which are +extensions of item commands, @pxref{Editing Item Headers and Text}): @table @kbd @@ -518,8 +523,10 @@ category in that file. @node Item Editing, , Category Editing, Editing @section Item Editing -Todo mode provides a wide variety of commands for adding and textually -changing items, as well as for deleting and relocating items. +Todo mode provides commands for adding new items as well as textually +changing, deleting and relocating existing items. The commands and +associated options for adding and editing items, in particular, offer +you a lot of flexibility to fine-tune these operations to your needs. @menu * Inserting New Items:: @@ -530,282 +537,388 @@ changing items, as well as for deleting and relocating items. @node Inserting New Items, Editing Item Headers and Text, , Item Editing @subsection Inserting New Items -There are many commands for adding new todo items. The command names -contain the word ``insert'' instead of ``add'' and their key bindings are -sequences beginning with @kbd{i}. The motivation for this terminology is -that speaking of adding an item to a category suggests appending it to -the top or bottom, whereas you can insert an item into the category -anywhere, giving each new item any priority in the list. +To add a new todo item to a category, type @kbd{i}, which is bound to +the command @code{todo-insert-item}. @table @kbd -@item i i -This is the basic command for inserting new items into a category -(@code{todo-insert-item}). Called without a prefix argument, it prompts -for the text of the item and its priority (a number between 1 and one -more than the number of items already in the category), both of which -you enter in the minibuffer, and inserts the item into the current -category of the current todo file at the position in the list -corresponding to the priority you chose. Called with one prefix +@item i +This command is the entry point for inserting new items into a +category (@code{todo-insert-item}). It prompts for additional keys +until reaching a complete key sequence, which specifies the insertion +parameters you wish to apply (see below). It then prompts for the +text of the item, which you enter in the minibuffer.@footnote{There +are two insertion parameters that override prompting for and manually +entering the new item's text, see below.} Called with one prefix argument, it also prompts for a category, and called with two prefix -arguments, it prompts for both a file and a category from that file, and -inserts the item accordingly. Category name completion works as with -the navigation command @kbd{j}. +arguments, it prompts for both a file and a category from that file, +and inserts the item accordingly; category name completion works as +with the navigation command @kbd{j}. Finally, it inserts the item +into the current or selected category of the current or selected todo +file at the position in the list corresponding to the priority you +choose, which also depends on the insertion parameters. @end table -Each invocation of @kbd{i i} adds a header string to the item, which +@noindent +The name of this command reflects the fact that you can insert a new +item into the category at any position, giving each new item any +priority in the list, whereas speaking of adding an item to a category +suggests appending it to the top or bottom. + +In addition to its file and category, each newly inserted todo item +has a priority in the category and begins with a header string, which includes at least the current date in the same format used by @code{diary-insert-entry} (@pxref{Date Formats,,, emacs}). You can -control what other information is included in the header by customizing -the following options: +specify the priority and the content of the header string in two ways. +First, you can set the following item insertion options, which apply +on every invocation of @code{todo-insert-item}. @itemize @bullet @item +@code{todo-default-priority} is for automatically assigning a new item +the highest or lowest priority in the category, if you do not +explicitly assign it a priority on invoking @code{todo-insert-item}. +By default, such new items are given highest priority, i.e., inserted +at the top of the list. + +@item @code{todo-always-add-time-string} is for including or omitting the -current time. The time string is omitted by default. +current time in the new item's header. By default, this time string +is omitted. @item -@code{todo-include-in-diary} is for specifying whether the item appears -in the Fancy Diary display by adding or omitting -@code{todo-nondiary-marker}. By default, new todo items are marked for -exclusion from the diary. +@code{todo-include-in-diary} is for specifying whether the item +appears in the Fancy Diary display (when the todo file is included in +the Emacs diary file) by adding or omitting +@code{todo-nondiary-marker}. By default, new todo items are so +marked, thus excluded from the diary. @item @code{todo-diary-nonmarking} is for adding or omitting @code{diary-nonmarking-symbol} to items displayed in the diary, to -control whether they are marked in the calendar (@pxref{Format of Diary -File,,, emacs}). By default, todo items that are diary entries are -marked in the calendar. +control whether they are marked in the calendar (@pxref{Format of +Diary File,,, emacs}). By default, todo items that are diary entries +lack this symbol, thus are marked in the calendar. @end itemize -Instead of always adding the same header information to a new item, you -can use more specific insertion commands that let you decide what to -include in the item header each time you insert a new item. And instead -of always being prompted to choose the new item's priority, you can -invoke a command to insert it at the position (hence with the priority) -of the item at point. Finally, instead of always typing the text of the -new item in the minibuffer, you can invoke a command that makes the -selected region in an Emacs buffer automatically become the new item's -text. The following paragraphs discuss how to invoke these commands by -typing certain key sequences. - -There are eight parameters of item insertion in Todo mode, six -concerning the item header, and one each concerning its priority and its -text. Each unique combination of these parameters produces a different -insertion command. The command @kbd{i i} realizes one of these -combinations. For the commands that realize the remaining combinations -it is convenient to associate each parameter with a mnemonically chosen -key. Then by typing certain sequences of these keys, you complete the -insertion command invocation that realizes the specified combination. -As with @kbd{i i}, the effect of many of these commands also depends on -the values of the item insertion options mentioned above (see the -examples below). - -Here is a list of the parameters and their associated keys, in the order -in which you must type them when building a key sequence (this order -roughly reflects the order in which the corresponding parts of the item -occur in a category listing): +Beside setting these options, for more flexibility you can also pass +certain parameters on each invocation of @code{todo-insert-item}. +These parameters concern not only the new item's priority and header, +but also its textual content. You pass these parameters by typing a +sequence of one or more keys after the initial @kbd{i}. + +Here is a list of the item insertion parameters together with their +mnemonically associated keys@footnote{The non-mnemonic choice of +@kbd{i} for the parameter @samp{default} is motivated by the +convenience of repeating the @kbd{i} used to invoke +@code{todo-insert-item}.} and descriptions of their effect in +@code{todo-insert-item}: @enumerate @item -@kbd{y} for diary (non)inclusion; +@samp{default} (@kbd{i}): Prompt for the new item's priority +(a number between 1 and one more than the number of items already in +the category) and add a header string conforming to the values of the +above options. + +@samp{copy} (@kbd{p}): Make an exact copy of the item at point, +including its header string, and prompt for its priority. (This is +useful for quickly making a new todo item whose text or header you +want to differ only partly from that of an existing item: after +inserting the copy, you can quickly edit it as needed by using +operations described in the next section.) + @item -@kbd{k} for adding or omitting `diary-nonmarking-symbol'; +@samp{diary} (@kbd{y}): Override the option +@code{todo-include-in-diary}; that is, add @code{todo-nondiary-marker} +if the option is non-@code{nil}, omit this marker if the option is @code{nil}. + +@samp{nonmarking} (@kbd{k}): Override the option +@code{todo-diary-nonmarking}; that is, add +@code{diary-nonmarking-symbol} if the option is non-@code{nil}, omit this +symbol if the option is @code{nil}. Since this symbol only applies to diary +items, the new item is automatically marked as such, i.e., lacks +@code{todo-nondiary-marker}. + @item -@kbd{c} for adding the date header by clicking a date in the Emacs -calendar, or@* -@kbd{d} for interactively entering the date header as a string of year, -month and day number components in the minibuffer, or@* -@kbd{n} for interactively entering the date header as a weekday name in -the minibuffer; +@samp{calendar} (@kbd{c}): Pop up the Emacs calendar and click a date +in it to use that date in the new todo item's header. + +@samp{date} (@kbd{d}): Prompt for entering in the minibuffer +the year, month (with completion) and day number components of the +header. + +@samp{dayname} (@kbd{n}): Prompt for entering in the minibuffer +a weekday name as the date header instead of a year-month-day string. + @item -@kbd{t} for adding a time string to the header in the minibuffer -(including the empty string, which amounts to omitting the time); +@samp{time} (@kbd{t}): Prompt for entering a time string in +the minibuffer instead of automatically inserting the current time; +however, typing @key{RET} at the prompt enters the current time if +@code{todo-always-add-time-string} is non-@code{nil}, otherwise it enters the +empty string (i.e., no time string). + @item -@kbd{h} for inserting the new item in the position of the item at point -(``here''), or@* -@kbd{r} to use the text of the selected region as the item's text. +@samp{here} (@kbd{h}): Insert the new item in the position of +the item at point, pushing that and all lower items in the category +down, i.e., lowering their priority, by one. + +@samp{region} (@kbd{r}): Use the text of the selected region as the +text of the new item, and insert this in accordance with the item +insertion options and other parameters passed. If the option +@code{todo-use-only-highlighted-region} is non-@code{nil}, then use the +region only when it is highlighted; otherwise, use the region +regardless of highlighting. @end enumerate -Each insertion command key sequence begins (disregarding prefix -arguments) with @kbd{i}, followed by one or more of these eight keys, in -the order listed. But as you can see in the above table, since some of -the insertion parameters are mutually exclusive, they occupy only five -positions, so the complete (unprefixed) sequences are maximally six keys -long. Shorter sequences are also possible, since a parameter may be -omitted. But since the order in any key sequence is fixed, if the last -key in the sequence could be followed by another insertion key, i.e., if -the last key is not @kbd{h} or @kbd{r}, it has to be doubled to complete -the sequence, otherwise it would be interpreted as a prefix sequence -(this is why the binding for the basic item insertion command is @kbd{i -i} and not @kbd{i}). - -Here are some examples of item insertion command key sequences: +Note that the parameters are divided into five numbered groups; within +a group, the parameters are mutually exclusive. Hence, to build a +complete insertion operation, you select at most one parameter from at +least one of these groups, by typing the corresponding key. If you +want to apply more than one parameter, you must type the corresponding +keys in the order of the numbered groups, subject to the following +constraints. + +The keys of groups 2-4 are continuation keys, that is, each can be +followed by a key from a following group. If you want to finish the +sequence with a continuation key, you must double the final key. For +example, @kbd{i y} is not a complete key sequence; rather, you must +type @kbd{i y y}. + +By contrast, the keys of groups 1 and 5 are final keys; for example, +@kbd{i i} and @kbd{i h} are complete sequences. The reason for making +two separate groups of the final keys is that the parameters +@samp{default} and @samp{copy} cannot be combined with any other +parameters, while @samp{here} and @samp{region} can be combined with +any of the parameters from groups 2-4. + +To aid you in building item insertion key sequences, when you type an +insertion key, this displays a prompt in the echo area showing pairs +of the remaining possible keys and their associated parameters, +grouped and ordered in accordance with the above list. The initial +prompt, after typing @kbd{i} to invoke @code{todo-insert-item}, looks +like this: + +@example +Press a key (so far @kbd{i}): @{ i=>default p=>copy @} @{ y=>diary k=>nonmarking @} @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @} +@end example + +@noindent If you now type @kbd{y}, the prompt changes to this: + +@example +Press a key (so far @kbd{i y}): y=>diary:GO! @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @} +@end example + +@noindent Notice that the pair @samp{k=>nonmarking} is now absent, since it +belongs to the same group as the selected pair @samp{y=>diary}, hence +is no longer available for this sequence. Since @kbd{y} is a +continuation key, it is still available, but now the string +@samp{:GO!} is appended to the pair to remind you that pressing this +key again will complete the sequence. + + + +@c Here are some examples of item insertion command key sequences: + +@c @itemize @bullet + +@c @item +@c @kbd{i h} inserts a new item at the position of the item at point (pushing +@c the latter down) with a header containing the current date and, +@c depending on the values of the mentioned options, possibly the current +@c time and diary-related markings. +@c @item +@c @kbd{i y h} does the same as the preceding command, except that +@c @code{todo-nondiary-marker} is added if @code{todo-include-in-diary} is +@c non-@code{nil} and omitted if that option is @code{nil}; that is, +@c the diary key @kbd{y} @c overrides the setting of this option. +@c @item +@c @kbd{i y t h} does the same as the preceding command, except that it +@c prompts for a time string instead of automatically inserting the +@c current time; however, typing @key{RET} at the prompt returns the +@c current time if @code{todo-always-add-time-string} is non-@code{nil}, +@c otherwise the empty string (i.e., no time string). +@c @item +@c @kbd{i y t t} does the same as the preceding command, except that it +@c prompts for the item's priority and inserts it accordingly. +@c @end itemize + + +An alternative to the key sequence @kbd{i c c} for choosing the item's +date from the calendar is also available: when point is already on a +date in the calendar, typing @kbd{i t} +(@code{todo-insert-item-from-calendar}) prompts for a new item and its +priority and inserts it in the current category. This command, like +@code{todo-insert-item}, also accepts one or two prefix arguments for +choosing the category via minibuffer completion. Note, however, that +the key sequence @kbd{i t} is not defined in Todo mode but in the +Calendar mode keymap. It is a convenient shortcut if you happen to be +using the calendar when you decide to make a new todo item. (Contrast +this with passing the @samp{calendar} parameter, which pops open the +calendar after you have entered the item's text, and then you can +choose a date from the calendar.) -@itemize @bullet -@item -@kbd{i h} inserts a new item at the position of the item at point (pushing -the latter down) with a header containing the current date and, -depending on the values of the mentioned options, possibly the current -time and diary-related markings. -@item -@kbd{i y h} does the same as the preceding command, except that -@code{todo-nondiary-marker} is added if @code{todo-include-in-diary} is -non-nil and omitted if that option is nil; that is, the diary key @kbd{y} -overrides the setting of this option. -@item -@kbd{i y t h} does the same as the preceding command, except that it -prompts for a time string instead of automatically inserting the -current time; however, typing @key{RET} at the prompt returns the -current time if @code{todo-always-add-time-string} is non-nil, otherwise -the empty string (i.e., no time string). -@item -@kbd{i y t t} does the same as the preceding command, except that it -prompts for the item's priority and inserts it accordingly. -@end itemize +@node Editing Item Headers and Text, Relocating and Removing Items, Inserting New Items, Item Editing +@subsection Editing Item Headers and Text -Note that the commands whose key sequences include @kbd{y}, @kbd{k} or @kbd{t} -reverse the effect of the options @code{todo-include-in-diary}, -@code{todo-diary-nonmarking} and @code{todo-always-add-time-string}, -respectively, thus temporarily overriding their values. - -The names of the item insertion commands correspond to their key -bindings, e.g., @kbd{i h} is bound to @code{todo-insert-item-here}, @kbd{i y h} to -@code{todo-insert-item-diary-here}, etc. But since there are so many -combinations, instead of trying to memorize either the names or the key -sequences, you can, as usual, just type an initial part of a key -sequence (minimally @kbd{i}), followed by @kbd{C-h} to see the valid -completions. - -An alternative to using the key @kbd{c} for choosing the item's date -from the calendar is also available: if point is on a date in the -calendar, typing @kbd{i t} (@code{todo-insert-item-from-calendar}) will -prompt for a new item and its priority and insert it in the current -category. Like @kbd{i i} and the other item insertion commands, this -also accepts one or two prefix arguments for choosing the category via -minibuffer completion. Note, however, that the key sequence @kbd{i t} -is not defined in Todo mode but in the Calendar mode keymap. It is a -convenient shortcut if you happen to be using the calendar when you -decide to make a new todo item. (Contrast this with a command like -@kbd{i c c}, which pops open the calendar after you have entered the -item's text, and then you can choose a date from the calendar.) - -There is one more item insertion command, which does not derive from the -item insertion parameters: +To make changes to an existing item's content or header, type @kbd{e}, +which is bound to the command @code{todo-edit-item}. @table @kbd -@item i p -This command (@code{todo-copy-item}) makes a complete copy of the item -at point, including its header, prompts for its priority in the current -category and inserts it accordingly. +@item e +This command is the entry point for textually editing existing items +in a category (@code{todo-edit-item}). It prompts for additional keys +until reaching a complete key sequence, which specifies the editing +parameters you wish to apply (see below), and then executes the +editing operation accordingly. @end table -@noindent -This command is useful for quickly adding a todo item whose text or -header you want to differ only partly from that of an existing item: -after inserting the copy, you can quickly edit it as needed by using -commands described in the next section. +Here is a list of the item editing parameters together with their +mnemonically associated keys and descriptions of their effect in +@code{todo-edit-item}. The list is divided into three groups, for +reasons explained below. -@node Editing Item Headers and Text, Relocating and Removing Items, Inserting New Items, Item Editing -@subsection Editing Item Headers and Text +@enumerate 1 -There are a number of commands for editing an existing item's text or -header; these commands are bound to key sequences with @kbd{e}. +@item +@samp{edit} (@kbd{e}): Edit the text of the current item in the +minibuffer; the item's header is omitted. -There are two commands for editing an item's text (and manually editing -its header), one appropriate for short items and simple edits and one -better suited for more complex changes or for editing lengthy items: +@samp{header} (@kbd{h}): Edit the text and header of the current item +in the minibuffer. -@table @kbd - -@item e e -Edit the text of the current item in the minibuffer -(@code{todo-edit-item}). If called with a prefix argument (@kbd{C-u e -e}), the item's header is also included in the minibuffer and so can be -edited manually. - -@item e m -Edit the text of the current item in a special buffer in Todo Edit mode -(@code{todo-edit-multiline-item}). When you have finished editing, type -@kbd{C-x C-q} to return to Todo mode; this runs a format check to ensure -the item is well-formed.@footnote{Unlike the command @kbd{F e} +@samp{multiline} (@kbd{m}): Edit the text of the current item in a +special buffer in Todo Edit mode. After editing, type @kbd{C-x C-q} +to return to Todo mode.@footnote{This runs a format check to ensure +the item is well-formed. However, unlike the command @kbd{F e} (@pxref{File Editing}), @kbd{e m} does not expose you to the risk of putting the file in an inconsistent state, since it puts only the current item in Todo Edit mode.} -@end table -A number of commands are available for interactively editing all or part -of the item header, permitting quick edits and helping avoid formatting -errors. +@samp{diary} (@kbd{y}): Change the current item's diary inclusion +status by adding @code{todo-nondiary-marker} if the item lacks this, +or by removing it if present. -The following three commands are for editing any or all of the year, -month and day components of a date header: +@samp{nonmarking} (@kbd{k}): Change the current item's calendar +marking status by adding @code{diary-nonmarking-symbol} if the item +lacks this, or by removing it if present. Since this symbol only +applies to diary items, the item is automatically marked as such, +i.e., if @code{todo-nondiary-marker} is present, it is removed. -@table @kbd +@samp{date} (@kbd{d}): Prompt for a final key from the second group +of item editing parameters to edit the current item's date string. + +@samp{time} (@kbd{t}): Edit the current item's time string, if +present; otherwise, add one. Typing @key{RET} at the prompt enters +the current time if @code{todo-always-add-time-string} is non-@code{nil}, +otherwise it enters the empty string (i.e., no time string). +@end enumerate + +@noindent +Editing the text of a lengthy item in the minibuffer can be +inconvenient; therefore, if you type @kbd{e e} or @kbd{e h} on an item +whose text contains more than one logical line, the effect is the same +as if you had typed @kbd{e m}, that is, you switch a special buffer in +Todo Edit mode. -@item e d t -Successively prompt for changes to the date's year, month and -day number, and if the option @code{todo-always-add-time-string} is -non-nil, also for editing the time string (see also @kbd{e t} below). +When you pass any of the parameters of the preceding group, except for +the @samp{date} parameter, this completes the item editing invocation +begun by typing @kbd{e}. Pressing @kbd{d} to pass the @samp{date} +parameter, however, prompts you with the following parameters and +their associated keys, and pressing any of these completes the +invocation. -@item e d a -Change the date to today's date. +@enumerate 2 -@item e d c -This command pops up the Emacs calendar, and after you type @key{RET} on -a date in the calendar makes that date the item's date. -@end table +@item +@samp{full} (@kbd{f}): Successively prompt for editing the year, month +(with completion) and day number parts of the current item's date +string, and, if the option @code{todo-always-add-time-string} is +non-@code{nil}, also for editing its time string. + +@samp{calendar} (@kbd{c}): This pops up the Emacs calendar, and after +you type @key{RET} on a date in the calendar makes that date the +item's date. + +@samp{today} (@kbd{a}): Make the item's date today's date. + +@samp{dayname} (@kbd{n}): Prompt for a weekday name (with completion) +and make it the item's date header. Note that this replaces an +existing date string, it does not add the day name to the date string. + +@samp{year} (@kbd{y}): Edit just the year component of the current +item's date string. + +@samp{month} (@kbd{m}): Edit just the month component of the current +item's date string (with completion). + +@samp{daynum} (@kbd{d}): Edit just the day number component of the +current item's date string. +@end enumerate @noindent -You can also use these commands on items whose date header consists of a -weekday name, which then changes to a header with year, month and day -components. +With the latter three parameters you can add a positive or negative +numeric prefix argument to the invocation: this increments or +decrements the selected date component by the given number and +automatically adjusts the other date components if necessary. For +example, if the item's date string is ``January 1, 2013'', then typing +@kbd{- 3 e d d} results in ``December 29, 2012''. + +The first two groups of parameters apply only to todo items that are +not marked as done (@pxref{Done Items}); the two parameters of the +third group, in contrast, apply only to done todo items. You cannot +edit the text of such items, but you can edit or delete the comment +you may have added on marking the item as done (@pxref{Done Items, +@code{todo-item-done}},), or retroactively add a comment, by passing +either of these parameters. + +@enumerate 3 -Each of the following three commands, in contrast to the preceding -three, changes only a single date component and has no effect on a date -header consisting of a weekday name: +@item +@samp{add/edit comment} (@kbd{c}): Edit the current done item's +comment, if it has one; otherwise, prompt for and add a comment. -@table @kbd -@item e d y -@itemx e d m -@itemx e d d -Prompt for changing just the year, month or day number, respectively; if -invoked with a positive or negative numeric prefix argument, directly -increment or decrement the date component accordingly and automatically -adjust the other date component if necessary. For example, if the date -string is ``January 1, 2013'', typing @kbd{- 3 e d d} results in -``December 29, 2012''. -@end table +@samp{delete comment} (@kbd{d}): Delete the current done item's +comment, if it has one. +@end enumerate -@table @kbd -@item e d n -Prompt for a weekday name and make it the item's date header. Note that -this replaces an existing date string, it does not add the day name to -the date string. - -@item e t -Edit just the item's time string. A time string can be added both to a -date string and to a weekday name. If you type @key{RET} at the -prompt, this omits a time string from the header, or deletes an existing -time string. - -@item e y y -Change the item's diary inclusion status by adding or removing -@code{todo-nondiary-marker}. +The command @code{todo-edit-item} is sensitive to the distinction +between not done and done todo items. If you type @kbd{e} when point +is on a done item, this displays the following prompt in the echo +area: -@item e y k -Change the item's diary marking status by adding or removing -@code{diary-nonmarking-symbol} (this command has an effect only if the -item is not marked for exclusion from the diary). -@end table +@example +Press a key (so far @kbd{e}): c=>add/edit comment d=>delete comment +@end example @noindent -Parallel to the latter two item-level commands are the -following category-level commands: +Only by typing @kbd{c} or @kbd{d} in response to this prompt can you +complete the invocation. In contrast, if you type @kbd{e} when point +is on a non-done todo item, this displays the following prompt in the +echo area, and you can continue or complete the invocation only by +typing one of the listed keys: + +@example +Press a key (so far @kbd{e}): e=>edit h=>header m=>multiline y=>diary k=>nonmarking d=>date t=>time +@end example + +As noted above, passing the @samp{date} parameter does not complete +the invocation of @code{todo-edit-item}; rather, it displays the +following prompt, and typing any of these keys does complete the +invocation: + +@example +Press a key (so far @kbd{e d}): f=>full c=>calendar a=>today n=>dayname y=>year m=>month d=>daynum +@end example + +In addition to the item-level invocations @kbd{e y}, to change the +current item's diary inclusion status, and @kbd{e k}, to change the +current item's calendar marking status, Todo mode also has two related +category-level commands: @table @kbd @@ -817,6 +930,21 @@ a prefix argument, these markings are removed from all items in the category. @end table +@noindent +Like @kbd{e k}, @kbd{C e k} automatically removes @code{todo-nondiary-marker} +from all items it is present on, since only diary items can bear +@code{diary-nonmarking-symbol}. + +Since categories often contain a mix of items marked for diary +inclusion and exclusion, and of the former, a mix of those to be +marked and those not to be marked in the calendar, it is more useful +for these category-level commands, unlike the item-level commands, not +to be toggles, but to have the same effect on all items in the +category, and take a prefix argument to reverse the effect. (If you +really want to toggle the diary-inclusion and calendar-marking status +of all items in the category, you can do this by marking all the items +and then invoking @kbd{e y} or @kbd{e k}, @pxref{Marked Items}). + @node Relocating and Removing Items, , Editing Item Headers and Text, Item Editing @subsection Relocating and Removing Items @@ -848,10 +976,11 @@ Lower the current item's priority by one, exchanging its position in the list with that of the item directly below it (@code{todo-lower-item-priority}). @item # -Prompt for a number and relocate the item to the corresponding position -in the list (@code{todo-set-item-priority}). For example, entering -@kbd{3} at the prompt makes the item the third in the category, i.e., -gives it third highest priority. You can also pass the desired priority +Prompt for a number and relocate the item to the corresponding +position in the list (@code{todo-set-item-priority}). For example, +entering @kbd{3} at the prompt makes the item the third in the +category, i.e., gives it third highest priority; all lower priority +items are pushed down by one. You can also pass the desired priority as a numeric prefix argument, e.g., @kbd{3 #} gives the item third highest priority without prompting. (Prefix arguments have no effect with @kbd{r} or @kbd{l}.) @@ -876,7 +1005,8 @@ enter is new, then you are asked whether to add the category to the file, and if you affirm, the item is moved to the new category. @end table -You delete an item, thereby permanently removing it: +You can delete an item, thereby permanently (and, as far as Todo mode +is concerned, irrevocably) removing it from the todo file: @table @kbd @@ -898,7 +1028,7 @@ modified form of @code{y-or-n-p}, which by default only accepts @kbd{y} or @kbd{Y}, but not @key{SPC}, as an affirmative answer. This is to diminish the risk of unintentionally executing the command, which is especially important with commands that do deletion, since there is no -Todo command to undo a deletion. If you want to be able to use SPC for +Todo command to undo a deletion. If you want to be able to use @key{SPC} for confirmation, enable the option @code{todo-y-with-space}. @end quotation @@ -917,15 +1047,17 @@ Archive Mode}). @table @kbd +@anchor{todo-item-done} @item d -This command (@code{todo-item-done}) removes the todo item at point from -the todo list, appends to the original header a header consisting of -@code{todo-done-string} (by default ``DONE '') and the current date, and -if @code{todo-always-add-time-string} is enabled, also the current time, -and adds the resulting done item to the top of the done items section of -the category. Invoked with a prefix argument, it also prompts you to -enter a comment, which is appended to the end of the done item, prefixed -with @code{todo-comment-string} (by default ``COMMENT: ''). +This command (@code{todo-item-done}) removes the todo item at point +from the todo list, appends to the original header a header consisting +of @code{todo-done-string} (by default @samp{DONE }) and the current +date, and if @code{todo-always-add-time-string} is enabled, also the +current time, and adds the resulting done item to the top of the done +items section of the category. Invoked with a prefix argument, it +also prompts you to enter a comment, which is appended to the end of +the done item, prefixed with @code{todo-comment-string} (by default +@samp{COMMENT: }). @end table A category's done items section is located below the last todo (i.e., @@ -953,23 +1085,30 @@ this is visible, hide it again and display only the todo items section (@code{todo-toggle-view-done-only}). @end table -Three editing commands for done items are available: +Since done items are meant to be a record of your finished todo items, +you cannot apply to them the same kinds of editing operations +available to unfinished todo items. However, as explained in +@ref{Editing Item Headers and Text} and repeated below for +convenience, you can edit or delete a done item's comment, or +retroactively add a comment. You can also relocate a done item, and +you can revert its done status, making it an unfinished item again. @table @kbd @item e c -If you type this command (@code{todo-edit-done-item-comment}) when point is -on a done item that has a comment, you can edit the text of the -comment. If you invoke it with a prefix argument (@kbd{C-u e c}), the -comment is deleted on confirmation. If the done item does not have a -comment, this command allows you to add one. +Edit the current done item's comment, if it has one; otherwise, prompt +for and add a comment. + +@item e d +Delete the current done item's comment, if it has one. @item m Move the done item at point to the top of the done items section of -another category (@code{todo-move-item}). This is useful in case, after -having relocated an item to its category's done items section, you -create a category that is better suited to the content of the done item -than its current category, so you can recategorize the done item. +another category (@code{todo-move-item}). This is useful in case, +after having finished a todo item and relocated it to its category's +done items section, you create a category that is better suited to the +content of the done item than its current category; in other words, +you can retroactively recategorize the done item. @item u If you decide the done item at point is not done after all, this command @@ -1034,7 +1173,7 @@ of putting the todo file out of synch with the archive file. You may find it preferable not to delete empty todo categories but to enable the option @code{todo-skip-archived-categories}. When this is -non-nil, such empty todo categories are skipped over by the sequential +non-@code{nil}, such empty todo categories are skipped over by the sequential category navigation commands @kbd{f} and @kbd{b}, so they don't distract you while navigating and you maintain the structural correspondence between todo and archive files (you can also still jump to empty todo categories @@ -1116,7 +1255,7 @@ category in the archive, the archive file is also automatically deleted. Since it is natural to visit an archive from the corresponding todo file, it would be convenient to easily return to the todo file when you -have finished browsing the archive. If you type `q' to quit Todo +have finished browsing the archive. If you type @kbd{q} to quit Todo Archive mode, this switches to the corresponding todo file and shows the todo category corresponding to the archive category you were just visiting. @@ -1155,30 +1294,47 @@ You can also use the last two commands to mark or unmark all done items in the category, but only when only the done items section is being displayed, i.e., after invoking @kbd{C V} or @kbd{V}. -The following commands operate on marked items: @kbd{k} (deleting), @kbd{m} -(moving to another category), @kbd{d} (moving to the done items section; -note that @kbd{C-u d} adds the same comment to all marked items), @kbd{A d} -(archiving), @kbd{u} (both in Todo mode for undoing a done item and in -Todo Archive mode for unarchiving an item), as well as the commands for -editing the item header (those beginning with the prefix @kbd{e d} as well -as @kbd{e t}, @kbd{e y y} and @kbd{e y k}). The item insertion, textual editing and -priority changing commands do not operate on marked items. +The following commands operate on marked items: -If you use @kbd{m}, @kbd{d}, @kbd{A d} or @kbd{u} on multiple noncontiguous marked -items, the relocated items retain their relative order but are now -listed consecutively en bloc. +@itemize @bullet -You can mark both todo and done items, but note that only @kbd{m} can apply -to both; other commands only affect either marked todo or marked done -items, so if both types of items are marked, invoking these commands -has no effect and informs you of your erroneous attempt. +@item +@kbd{k} (deleting) +@item +@kbd{m} (moving to another category) +@item +@kbd{d} (moving to the done items section; note that @kbd{C-u d} adds +the same comment to all marked items) +@item +@kbd{A d} (archiving) +@item +@kbd{u} (both in Todo mode for undoing a done item and in Todo Archive +mode for unarchiving an item) +@item +the commands for editing the item header (those beginning with the +prefix @kbd{e d} as well as @kbd{e t}, @kbd{e y} and @kbd{e k}) +@end itemize + +@noindent +The item insertion, textual editing and priority changing commands do +not operate on marked items. + +If you use @kbd{m}, @kbd{d}, @kbd{A d} or @kbd{u} on multiple +noncontiguous marked items, the relocated items retain their relative +order but are now listed consecutively en bloc. + +You can mark both todo and done items, but note that only @kbd{m} and +@kbd{k} can apply to both; other commands only affect either marked +todo or marked done items, so if both types of items are marked, +invoking these commands has no effect and informs you of your +erroneous attempt. @node Todo Categories Mode, Searching for Items, Marked Items, Top @chapter Todo Categories Mode -It can be helpful to have a compact overview of the categories in a todo -file and the types of items it contains; Todo provides a tabular view -of this information. +It can be helpful to have a compact overview of the categories in a +todo file and the types of items it contains; the Todo package +provides a tabular view of this information. @table @kbd @@ -1241,16 +1397,16 @@ to sort by archived item counts. Each row of the table is also buttonized; pressing one of these exits the buffer (killing it), returns to the buffer of the file from which -you had invoked `F c', and displays the category that was named in the -row button you pressed (i.e., pressing this button jumps to that -category). However, if the category named in the row is in a todo file -and all of its items have been archived, and you have enabled the option -@code{todo-skip-archived-categories}, then pressing the button jumps to -the archive category instead of the empty todo category. You can -recognize such categories by their items counts in the table---all +you had invoked @kbd{F c}, and displays the category that was named in +the row button you pressed (i.e., pressing this button jumps to that +category). However, if the category named in the row is in a todo +file and all of its items have been archived, and you have enabled the +option @code{todo-skip-archived-categories}, then pressing the button +jumps to the archive category instead of the empty todo category. You +can recognize such categories by their items counts in the table---all columns but the archived one have counts of zero---and in addition, their lines in the table are also distinguished from the others by a -different face. +different face (@pxref{Faces}). You can navigate around the table: @@ -1265,7 +1421,7 @@ Advance point to the next button. Put point on the previous button. @end table -These commands are cyclic, e.g. when point is on the last button, +These commands are cyclic, e.g., when point is on the last button, pressing @kbd{n} moves it to the first button. Typing @kbd{q} exits Todo Categories mode, killing the buffer and returning @@ -1312,14 +1468,15 @@ or archive file after reordering, in subsequent sessions as well. It is important to be aware that renumbering the categories does not change the textual order of the categories in the file. This is significant if you should invoke @kbd{F e} to edit the entire file -manually and in so doing alter the number of items in a category: this -will make the item count shown in the table of categories of this file -inconsistent with the actual number. You can repair this inconsistency -by invoking the command @code{todo-repair-categories-sexp} (which lacks -a key binding, since it is meant to be a rarely needed rescue -operation). But this will revert any renumbering of the categories you -have made, so you will have to renumber them again. This is the reason -why you should exercise caution when using @kbd{F e}. +manually and in so doing alter the number of categories or the number +of items in a category: this will make the information shown in the +table of categories of this file inconsistent with its actual state. +You can repair this inconsistency by invoking the command +@code{todo-repair-categories-sexp} (which lacks a key binding, since +it is meant to be a rarely needed rescue operation). But this will +revert any renumbering of the categories you have made, so you will +have to renumber them again. This is one reason why you should +exercise caution when using @kbd{F e}. @end quotation @node Searching for Items, Todo Filtered Items Mode, Todo Categories Mode, Top @@ -1430,7 +1587,7 @@ todo file, and the latter sets the number of top priorities for the current category. To exclude a category or file from filtering by @kbd{F t t} and @kbd{F t m}, set the number to @samp{0}. @item -You can invoke `F t t' and `F t m' with a numeric prefix argument, +You can invoke @kbd{F t t} and @kbd{F t m} with a numeric prefix argument, which specifies the number of top priorities in each category just for this invocation, overriding both @code{todo-top-priorities-overrides} and @code{todo-top-priorities}. @@ -1524,7 +1681,8 @@ use the values of @code{todo-top-priorities-overrides} or Aside from explicitly invoking an item filtering command to display a saved list of items filtered by a given method from given todo files, -there are two other ways to visit a saved file of filtered items: +there are two other ways to visit a saved file of filtered items. You +can invoke a command similar to @code{find-file}: @table @kbd @item F f @@ -1532,15 +1690,13 @@ Visit a saved file of filtered items, which you choose via minibuffer completion (@code{todo-find-filtered-items-file}). @end table -@itemize @bullet -@item -As with tables of categories, by customizing @code{todo-show-first} you -can have the first invocation of @code{todo-show} for a given todo file -display the corresponding saved file of filtered items. If there is -no saved filtered items list for the file, @code{todo-show} simply -defaults to visiting the file and displaying its first category, as -usual. -@end itemize +@noindent +Alternatively, as with tables of categories, by customizing +@code{todo-show-first} you can have the first invocation of +@code{todo-show} for a given todo file display the corresponding saved +file of filtered items. If there is no saved filtered items list for +the file, @code{todo-show} simply defaults to visiting the file and +displaying its first category, as usual. The command @kbd{F k} (@pxref{File Editing}) is also available in Todo Filtered Items mode. It deletes the current filtered items file. @@ -1559,20 +1715,23 @@ You can change the appearance of Todo mode buffers in a variety of ways. @node Faces, Item Prefix, , Todo Display Features @section Faces -Each of the Todo modes uses faces to distinguish various aspects of the -display, both structural and informational. For example, the faces for -the date and time strings of todo item headers by default inherit the -attributes of the corresponding faces used by the Emacs diary; but when -the date and time of a Todo diary item (i.e., an item lacking -@code{todo-nondiary-marker}) is earlier than the current date and time, -they are displayed in a different face. In this way, you can readily -recognize diary items that have ``expired'' and act accordingly (e.g., -by tagging them as done or by updating the deadlines). - -Another example of an informational face is the face used to distinguish -top priority items. A third case is the face used in Todo Categories -mode to mark rows of the table containing categories with only archived -items. +Each of the Todo modes uses faces to distinguish various aspects of +the display, both structural and informational. For example, the +faces for the date and time strings of todo item headers +(@code{todo-date} and @code{todo-time}, respectively) by default +inherit the attributes of the corresponding faces used by the Emacs +diary; but when the date and time of a Todo diary item (i.e., an item +lacking @code{todo-nondiary-marker}) is earlier than the current date +and time, they are displayed in a different face +(@code{todo-diary-expired}). In this way, you can readily recognize +diary items that have ``expired'' and act accordingly (e.g., by +tagging them as done or by updating the deadlines). + +Another example of an informational face is the face used to +distinguish top priority items (@code{todo-top-priority}). A third +case is the face used in Todo Categories mode to mark rows of the +table containing categories with only archived items +(@code{todo-archived-only}). The @code{todo-faces} customization group contains a complete list of Todo mode faces and brief descriptions of their use. @@ -1606,15 +1765,16 @@ temporarily hide the item numbering: @itemx N Toggle between displaying item numbering and displaying the @code{todo-prefix} string in the current Todo file (todo, archive, or -saved virtual category of filtered items. This command also works in +saved virtual category of filtered items). (This command also works in buffers of filtered items that have not yet been written to a file.) @end table In the todo items section of each Todo mode category, the item prefix -(whether a priority number or a fixed string) of the top priority items -(determined as specified in @pxref{Filtering Items}) is displayed in a -different face from the prefix of the other items, so you see at a -glance how many items in the category are top priorities. +(whether a priority number or a fixed string) of the top priority +items (determined as specified in @pxref{Filtering Items}) is +displayed in a face (@code{todo-top-priority}) different from the face +of the prefix of non-top-priority items, so you see at a glance how +many items in the category are top priorities. @node Other Display Commands and Options, , Item Prefix, Todo Display Features @section Other Display Commands and Options @@ -1627,18 +1787,19 @@ current file: @item F h @itemx h Hide the item headers if visible, or show them if they are hidden. -With done items, only the done header (i.e. the done tag and date-time +With done items, only the done header (i.e., the done tag and date-time string inserted when the item was marked done) is hidden, the original date-time string is not. With filtered items, the category (or category-file) tag is not hidden. @item F H @itemx H -Highlight the current item if unhighlighted, or remove its highlighting. -When item highlighting is enabled, it follows navigation by @kbd{n} or -@kbd{p}. If you want to have current item highlighting by default, -enable the option @code{todo-highlight-item}. @kbd{F H} or @kbd{H} will -still toggle it. +Highlight the current item (with the face @code{hl-line}) if +unhighlighted, or remove its highlighting. When item highlighting is +enabled, it follows navigation by @kbd{n} or @kbd{p}. If you want to +have current item highlighting by default, enable the option +@code{todo-highlight-item}. @kbd{F H} or @kbd{H} will still toggle +it. @end table There are two options which affect the display of items whose content is @@ -1674,7 +1835,7 @@ By default, the todo and done items sections of a todo category are visually separated by a line as wide as the window the buffer is displayed in. You can change the appearance and width of the separator by customizing @code{todo-done-separator-string}; you can also change the -face of the separator string. +face of the separator string (@code{todo-done-sep}). There are also several options for changing the appearance in Todo Categories mode and Todo Filtered Items mode, beyond those mentioned @@ -1749,7 +1910,7 @@ do so later by invoking the command @code{todo-convert-legacy-files} (there is no key binding for it, since it shouldn't be necessary to use it often). (A delicate part of the conversion concerns the customizable format of item date/time headers in the old-style; see the documentation -string of @code{todo-todo-mode-date-time-regexp} for details.) +string of @code{todo-legacy-date-time-regexp} for details.) @node GNU Free Documentation License, , Legacy Todo Mode Files, Top @appendix GNU Free Documentation License diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 03c6da3b73f..07d34bd4d2f 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -1,7 +1,8 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/tramp +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- +@setfilename ../../info/tramp.info @c %**start of header @settitle TRAMP User Manual +@include docstyle.texi @c %**end of header @c This is *so* much nicer :) @@ -16,7 +17,7 @@ @include trampver.texi -@c Macro for formatting a filename according to the respective syntax. +@c Macro for formatting a file name according to the respective syntax. @c xxx and yyy are auxiliary macros in order to omit leading and @c trailing whitespace. Not very elegant, but I don't know it better. @@ -65,13 +66,13 @@ @end ifclear @copying -Copyright @copyright{} 1999--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2015 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'', +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''. @@ -84,13 +85,13 @@ copy and modify this GNU manual.'' @dircategory @value{emacsname} network features @direntry * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol - @value{emacsname} remote file access via rsh and rcp. + @value{emacsname} remote file access via ssh and scp. @end direntry @titlepage @title @value{tramp} version @value{trampver} User Manual @author by Daniel Pittman -@author based on documentation by Kai Gro@ss{}johann +@author based on documentation by Kai Großjohann @page @insertcopying @end titlepage @@ -104,8 +105,8 @@ copy and modify this GNU manual.'' This file documents @value{tramp} version @value{trampver}, a remote file editing package for @value{emacsname}. -@value{tramp} stands for `Transparent Remote (file) Access, Multiple -Protocol'. This package provides remote file editing, similar to +@value{tramp} stands for ``Transparent Remote (file) Access, Multiple +Protocol''. This package provides remote file editing, similar to @value{ftppackagename}. The difference is that @value{ftppackagename} uses FTP to transfer @@ -197,7 +198,7 @@ Installing @value{tramp} with your @value{emacsname} Configuring @value{tramp} for use -* Connection types:: Types of connections made to remote machines. +* Connection types:: Types of connections made to remote hosts. * Inline methods:: Inline methods. * External methods:: External methods. @ifset emacsgvfs @@ -216,7 +217,7 @@ Configuring @value{tramp} for use * Connection caching:: Reusing connection related information. * Predefined connection information:: Setting own connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. +* Remote programs:: How @value{tramp} finds and uses programs on the remote host. * Remote shell setup:: Remote shell setup hints. * Android shell setup:: Android shell setup hints. * Auto-save and Backup:: Auto-save and Backup. @@ -224,9 +225,8 @@ Configuring @value{tramp} for use Using @value{tramp} -* Filename Syntax:: @value{tramp} filename conventions. -* Alternative Syntax:: URL-like filename syntax. -* Filename completion:: Filename completion. +* File name Syntax:: @value{tramp} file name conventions. +* File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other @value{emacsname} packages. * Cleanup remote connections:: Cleanup remote connections. @@ -241,23 +241,24 @@ How file names, directories and localnames are mangled and managed @end detailmenu @end menu + @node Overview @chapter An overview of @value{tramp} @cindex overview After the installation of @value{tramp} into your @value{emacsname}, you -will be able to access files on remote machines as though they were +will be able to access files on remote hosts as though they were local. Access to the remote file system for editing files, version control, and @code{dired} are transparently enabled. -Your access to the remote machine can be with the @command{rsh}, +Your access to the remote host can be with the @command{rsh}, @command{rlogin}, @command{telnet} programs or with any similar connection method. This connection must pass @acronym{ASCII} successfully to be usable but need not be 8-bit clean. The package provides support for @command{ssh} connections out of the box, one of the more common uses of the package. This allows -relatively secure access to machines, especially if @command{ftp} +relatively secure access to hosts, especially if @command{ftp} access is disabled. Under Windows, @value{tramp} is integrated with the PuTTY package, @@ -266,11 +267,11 @@ using the @command{plink} program. The majority of activity carried out by @value{tramp} requires only that the remote login is possible and is carried out at the terminal. In order to access remote files @value{tramp} needs to transfer their content -to the local machine temporarily. +to the local host temporarily. -@value{tramp} can transfer files between the machines in a variety of ways. +@value{tramp} can transfer files between the hosts in a variety of ways. The details are easy to select, depending on your needs and the -machines in question. +hosts in question. The fastest transfer methods for large files rely on a remote file transfer package such as @command{rcp}, @command{scp}, @command{rsync} @@ -279,7 +280,7 @@ or (under Windows) @command{pscp}. If the remote copy methods are not suitable for you, @value{tramp} also supports the use of encoded transfers directly through the shell. This requires that the @command{mimencode} or @command{uuencode} tools -are available on the remote machine. These methods are generally +are available on the remote host. These methods are generally faster for small files. @value{tramp} is still under active development and any problems you encounter, @@ -350,7 +351,7 @@ shell prompt, and a few other things. @item Now the remote shell is up and it good working order. Remember, what was supposed to happen is that @value{tramp} tries to find out what files exist -on the remote host so that it can do filename completion. +on the remote host so that it can do file name completion. So, @value{tramp} basically issues @command{cd} and @command{ls} commands and also sometimes @command{echo} with globbing. Another command that is @@ -359,7 +360,7 @@ directory or the like. The output of each command is parsed for the necessary operation. @item -Suppose you are finished with filename completion, have entered @kbd{C-x +Suppose you are finished with file name completion, have entered @kbd{C-x C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to transfer the file contents from the remote host to the local host so that you can edit them. @@ -428,6 +429,14 @@ Or follow the example session below: @end example @noindent +If you reside behind a firewall, you could use + +@example +] @strong{git config --global http.proxy http://user:pwd@@proxy.server.com:8080} +] @strong{git clone http://git.savannah.gnu.org/r/tramp.git} +@end example + +@noindent Tramp developers use instead @example @@ -469,7 +478,7 @@ many more methods for getting a remote shell and for transferring the file contents were added. Support for VC was added. After that, there were added the multi-hop methods in April 2000 and -the unification of @value{tramp} and Ange-FTP filenames in July 2002. +the unification of @value{tramp} and Ange-FTP file names in July 2002. In July 2004, multi-hop methods have been replaced by proxy hosts. Running commands on remote hosts was introduced in December 2005. @ifset emacsgw @@ -498,6 +507,7 @@ the first release including @value{tramp} was Emacs 22.1. @include trampinst.texi @end ifset + @node Configuration @chapter Configuring @value{tramp} for use @cindex configuration @@ -506,8 +516,8 @@ the first release including @value{tramp} was Emacs 22.1. @value{tramp} is (normally) fully functional when it is initially installed. It is initially configured to use the @command{scp} program to connect to the remote host. So in the easiest case, you -just type @kbd{C-x C-f} and then enter the filename -@file{@trampfn{, user, machine, /path/to.file}}. +just type @kbd{C-x C-f} and then enter the file name +@file{@trampfn{, user, host, /path/to.file}}. On some hosts, there are problems with opening a connection. These are related to the behavior of the remote shell. See @xref{Remote shell @@ -516,15 +526,24 @@ setup}, for details on this. If you do not wish to use these commands to connect to the remote host, you should change the default connection and transfer method that @value{tramp} uses. There are several different methods that @value{tramp} -can use to connect to remote machines and transfer files +can use to connect to remote hosts and transfer files (@pxref{Connection types}). If you don't know which method is right for you, see @xref{Default Method}. +@strong{Note} that the following descriptions reference the setting of +user options or variables, not all of which are autoloaded by +@value{emacsname}. All examples assume that you have loaded +@value{tramp} first: + +@lisp +(require 'tramp) +@end lisp + @menu -* Connection types:: Types of connections made to remote machines. +* Connection types:: Types of connections made to remote hosts. * Inline methods:: Inline methods. * External methods:: External methods. @ifset emacsgvfs @@ -546,7 +565,7 @@ Method}. * Connection caching:: Reusing connection related information. * Predefined connection information:: Setting own connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. +* Remote programs:: How @value{tramp} finds and uses programs on the remote host. * Remote shell setup:: Remote shell setup hints. * Android shell setup:: Android shell setup hints. * Auto-save and Backup:: Auto-save and Backup. @@ -555,17 +574,17 @@ Method}. @node Connection types -@section Types of connections made to remote machines +@section Types of connections made to remote hosts @cindex connection types, overview There are two basic types of transfer methods, each with its own advantages and limitations. Both types of connection make use of a remote shell access program such as @command{rsh}, @command{ssh} or -@command{telnet} to connect to the remote machine. +@command{telnet} to connect to the remote host. This connection is used to perform many of the operations that @value{tramp} requires to make the remote file system transparently accessible from -the local machine. It is only when visiting files that the methods +the local host. It is only when visiting files that the methods differ. @cindex inline methods @@ -573,9 +592,9 @@ differ. @cindex methods, inline @cindex methods, external Loading or saving a remote file requires that the content of the file -be transferred between the two machines. The content of the file can +be transferred between the two hosts. The content of the file can be transferred using one of two methods: the @dfn{inline method} over -the same connection used to log in to the remote machine, or the +the same connection used to log in to the remote host, or the @dfn{external method} through another connection using a remote copy program such as @command{rcp}, @command{scp} or @command{rsync}. @@ -603,14 +622,13 @@ action. @cindex methods, inline The inline methods in @value{tramp} are quite powerful and can work in -situations where you cannot use an external transfer program to connect. -Inline methods are the only methods that work when connecting to the -remote machine via telnet. (There are also strange inline methods which -allow you to transfer files between @emph{user identities} rather than -hosts, see below.) +situations where you cannot use an external transfer program to +connect. There are also strange inline methods which allow you to +transfer files between @emph{user identities} rather than hosts, see +below. These methods depend on the existence of a suitable encoding and -decoding command on remote machine. Locally, @value{tramp} may be able to +decoding command on remote host. Locally, @value{tramp} may be able to use features of @value{emacsname} to decode and encode the files or it may require access to external commands to perform that task. @@ -621,7 +639,7 @@ it may require access to external commands to perform that task. @command{mimencode} (part of the @command{metamail} package) or @command{uuencode} on the remote host. The first reliable command will be used. The search path can be customized, see @ref{Remote -Programs}. +programs}. If both commands aren't available on the remote host, @value{tramp} transfers a small piece of Perl code to the remote host, and tries to @@ -703,7 +721,7 @@ the remote host, this option uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh} to open a connection. This is useful for users where the normal login shell is set up to ask them a number of questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work +just gives @value{tramp} a more-or-less ``standard'' login shell to work with. Note that this procedure does not eliminate questions asked by @@ -746,7 +764,10 @@ This method is mostly interesting for Windows users using the PuTTY implementation of SSH@. It uses @samp{plink -ssh} to log in to the remote host. -This supports the @samp{-P} argument. +With a recent PuTTY, it is recommended to check the @samp{Share SSH +connections if possible} control for that session. + +This method supports the @samp{-P} argument. @item @option{plinkx} @@ -755,9 +776,10 @@ This supports the @samp{-P} argument. Another method using PuTTY on Windows. Instead of host names, it expects PuTTY session names, calling @samp{plink -load @var{session} --t"}. User names are relevant only in case the corresponding session -hasn't defined a user name. Different port numbers must be defined in -the session. +-t}. User names and port numbers must be defined in the session. + +With a recent PuTTY, it is recommended to check the @samp{Share SSH +connections if possible} control for that session. @end table @@ -787,11 +809,11 @@ fair trade-off between both approaches. @cindex rsh (with rcp method) This method uses the @command{rsh} and @command{rcp} commands to connect -to the remote machine and transfer files. This is probably the fastest +to the remote host and transfer files. This is probably the fastest connection method available. The alternative method @option{remcp} uses the @command{remsh} and -@command{rcp} commands. It should be applied on machines where +@command{rcp} commands. It should be applied on hosts where @command{remsh} is used instead of @command{rsh}. @@ -802,8 +824,8 @@ The alternative method @option{remcp} uses the @command{remsh} and @cindex ssh (with scp method) Using @command{ssh} to connect to the remote host and @command{scp} to -transfer files between the machines is the best method for securely -connecting to a remote machine and accessing files. +transfer files between the hosts is the best method for securely +connecting to a remote host and accessing files. The performance of this option is also quite good. It may be slower than the inline methods when you often open and close small files however. @@ -818,22 +840,6 @@ specify @samp{-p 42} in the argument list for @command{ssh}, and to specify @samp{-P 42} in the argument list for @command{scp}. -@item @option{sftp}---@command{ssh} and @command{sftp} -@cindex method sftp -@cindex sftp method -@cindex sftp (with sftp method) -@cindex ssh (with sftp method) - -That is mostly the same method as @option{scp}, but using -@command{sftp} as transfer command. So the same remarks are valid. - -This command does not work like @value{ftppackagename}, where -@command{ftp} is called interactively, and all commands are send from -within this session. Instead of, @command{ssh} is used for login. - -This method supports the @samp{-p} argument. - - @item @option{rsync}---@command{ssh} and @command{rsync} @cindex method rsync @cindex rsync method @@ -841,7 +847,7 @@ This method supports the @samp{-p} argument. @cindex ssh (with rsync method) Using the @command{ssh} command to connect securely to the remote -machine and the @command{rsync} command to transfer files is almost +host and the @command{rsync} command to transfer files is almost identical to the @option{scp} method. While @command{rsync} performs much better than @command{scp} when @@ -867,7 +873,7 @@ the remote host, this option uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh} to open a connection. This is useful for users where the normal login shell is set up to ask them a number of questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work +just gives @value{tramp} a more-or-less ``standard'' login shell to work with. This is also useful for Windows users where @command{ssh}, when @@ -879,33 +885,27 @@ This method supports the @samp{-p} argument. @item @option{pscp}---@command{plink} and @command{pscp} +@item @option{psftp}---@command{plink} and @command{psftp} @cindex method pscp @cindex pscp method @cindex pscp (with pscp method) @cindex plink (with pscp method) @cindex PuTTY (with pscp method) - -This method is similar to @option{scp}, but it uses the -@command{plink} command to connect to the remote host, and it uses -@command{pscp} for transferring the files. These programs are part -of PuTTY, an SSH implementation for Windows. - -This method supports the @samp{-P} argument. - - -@item @option{psftp}---@command{plink} and @command{psftp} @cindex method psftp @cindex psftp method -@cindex psftp (with psftp method) +@cindex pscp (with psftp method) @cindex plink (with psftp method) @cindex PuTTY (with psftp method) -As you would expect, this method is similar to @option{sftp}, but it -uses the @command{plink} command to connect to the remote host, and it -uses @command{psftp} for transferring the files. These programs are -part of PuTTY, an SSH implementation for Windows. +These methods are similar to @option{scp} or @option{sftp}, but they +use the @command{plink} command to connect to the remote host, and +they use @command{pscp} or @command{psftp} for transferring the files. +These programs are part of PuTTY, an SSH implementation for Windows. -This method supports the @samp{-P} argument. +With a recent PuTTY, it is recommended to configure the @samp{Share +SSH connections if possible} control for that session. + +These methods support the @samp{-P} argument. @item @option{fcp}---@command{fsh} and @command{fcp} @@ -936,6 +936,19 @@ opens just one connection to the remote host and then keeps it open, anyway. +@item @option{nc}---@command{telnet} and @command{nc} +@cindex method nc +@cindex nc method +@cindex nc (with nc method) +@cindex telnet (with nc method) + +Using @command{telnet} to connect to the remote host and @command{nc} +for file transfer is often the only possibility to access dumb +devices, like routers or NAS hosts. Those hosts have just a +restricted @command{busybox} as local shell, and there is no program +to encode and decode files for transfer. + + @item @option{ftp} @cindex method ftp @cindex ftp method @@ -943,7 +956,7 @@ anyway. 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}. +This works only for unified file names, see @ref{Issues}. @end ifset @@ -972,15 +985,15 @@ 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 -the machine @code{melancholia} as user @code{daniel} of the domain +the host @code{melancholia} as user @code{daniel} of the domain @code{BIZARRE}, and edit @file{.emacs} in the home directory (share -@code{daniel$}) I would specify the filename @file{@trampfn{smb, +@code{daniel$}) I would specify the file name @file{@trampfn{smb, daniel%BIZARRE, melancholia, /daniel$$/.emacs}}. Depending on the Windows domain configuration, a Windows user might be considered as domain user per default. In order to connect as local -user, the WINS name of that machine must be given as domain name. -Usually, it is the machine name in capital letters. In the example +user, the WINS name of that host must be given as domain name. +Usually, it is the host name in capital letters. In the example above, the local user @code{daniel} would be specified as @file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}. @@ -1005,16 +1018,17 @@ name. This special method uses the Android Debug Bridge for accessing Android devices. The Android Debug Bridge must be installed locally. Some GNU/Linux distributions offer it for installation, otherwise it -can be installed as part of the Android SDK. If the @command{adb} -program is not found via the @code{$PATH} environment variable, the +can be installed as part of the Android SDK@. If the @command{adb} +program is not found via the @env{PATH} environment variable, the variable @var{tramp-adb-program} must point to its absolute path. -Tramp does not connect Android devices to @command{adb}. This must be -performed outside @value{emacsname}. If there is exactly one Android -device connected to @command{adb}, a host name is not needed in the -remote file name. The default @value{tramp} name to be used is -@file{@trampfn{adb, , ,}} therefore. Otherwise, one could find -potential host names with the command @command{adb devices}. +@value{tramp} does not connect Android devices to @command{adb}, +unless the custom option @option{tramp-adb-connect-if-not-connected} +is non-@code{nil}. If there is exactly one Android device connected +to @command{adb}, a host name is not needed in the remote file name. +The default @value{tramp} name to be used is @file{@trampfn{adb, , ,}}, +therefore. Otherwise, one could find potential host names with the +command @command{adb devices}. Usually, the @command{adb} method does not need any user name. It runs under the permissions of the @command{adbd} process on the @@ -1023,6 +1037,11 @@ Android device. If a user name is specified, @value{tramp} applies an devices, especially with unrooted ones. In that case, an error message is displayed. +If a device shall be connected via TCP/IP, it is possible to declare +the port number to be used like @file{device#42}. Without a port +number, the default value as declared in @command{adb} will be used. +Port numbers are not applicable to Android devices connected via USB. + @end table @@ -1043,6 +1062,16 @@ Therefore, your @value{emacsname} must have D-Bus integration, @pxref{Top, , D-Bus, dbus}. @table @asis +@item @option{afp} +@cindex method afp +@cindex afp method + +Access to Mac OS X volumes via the Apple Filing Protocol is offered by +this method. The access must always be performed with a leading +volume (share) name, like @file{@trampfn{afp, user, host, /volume}}. + + + @item @option{dav} @cindex method dav @cindex method davs @@ -1064,6 +1093,17 @@ OBEX is an FTP-like access protocol for simple devices, like cell phones. For the time being, @value{tramp} only supports OBEX over Bluetooth. +@item @option{sftp} +@cindex method sftp +@cindex sftp method + +As you might expect, this method uses @command{sftp} in order to +access the remote host. Contrary to the @option{ssh} and @option{scp} +methods, it doesn't open an @command{ssh} session for login. +Therefore, it could be used to access to remote hosts which refuse +@command{ssh} for security reasons. + + @item @option{synce} @cindex method synce @cindex synce method @@ -1074,11 +1114,13 @@ FUSE, it also needs the SYNCE-GVFS plugin. @end table +@vindex tramp-gvfs-methods @defopt tramp-gvfs-methods -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}. +This custom option, a list, defines the external methods which shall +be used with GVFS@. Per default, these are @option{afp}, +@option{dav}, @option{davs}, @option{obex}, @option{sftp} and +@option{synce}. Other possible values are @option{ftp} and +@option{smb}. @end defopt @end ifset @@ -1154,7 +1196,7 @@ example, the following two lines specify to use the @option{ssh} method for all user names matching @samp{john} and the @option{rsync} method for all host names matching @samp{lily}. The third line specifies to use the @option{su} method for the user @samp{root} on -the machine @samp{localhost}. +the host @samp{localhost}. @lisp (add-to-list 'tramp-default-method-alist '("" "john" "ssh")) @@ -1178,9 +1220,9 @@ environment you will use them in and, especially when used over the Internet, the security implications of your preferred method. The @option{rsh} and @option{telnet} methods send your password as -plain text as you log in to the remote machine, as well as +plain text as you log in to the remote host, as well as transferring the files in such a way that the content can easily be -read from other machines. +read from other hosts. If you need to connect to remote systems that are accessible from the Internet, you should give serious thought to using @option{ssh} based @@ -1205,7 +1247,7 @@ want to edit mostly small files. And if you access large text files, compression (driven by @var{tramp-inline-compress-start-size}) shall still result in good performance. -I guess that these days, most people can access a remote machine by +I guess that these days, most people can access a remote host by using @command{ssh}. So I suggest that you use the @option{ssh} method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost, /etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other @@ -1348,8 +1390,8 @@ bastion host. @vindex tramp-default-proxies-alist @defopt tramp-default-proxies-alist In order to specify multiple hops, it is possible to define a proxy -host to pass through, via the variable -@code{tramp-default-proxies-alist}. This variable keeps a list of +host to pass through, via the custom option +@option{tramp-default-proxies-alist}. This variable keeps a list of triples (@var{host} @var{user} @var{proxy}). The first matching item specifies the proxy host to be passed for a @@ -1357,7 +1399,7 @@ file name located on a remote target matching @var{user}@@@var{host}. @var{host} and @var{user} are regular expressions or @code{nil}, which is interpreted as a regular expression which always matches. -@var{proxy} must be a Tramp filename which localname part is ignored. +@var{proxy} must be a Tramp file name which localname part is ignored. Method and user name on @var{proxy} are optional, which is interpreted with the default values. @ifset emacsgw @@ -1463,9 +1505,9 @@ Sometimes they offer limited features only, like running @command{rbash} @vindex tramp-restricted-shell-hosts-alist @defopt tramp-restricted-shell-hosts-alist -This variable keeps a list of regular expressions, which denote hosts -running a registered shell like "rbash". Those hosts can be used as -proxies only. +This custom option keeps a list of regular expressions, which denote +hosts running a registered shell like @command{rbash}. Those hosts +can be used as proxies only. If the bastion host from the example above runs a restricted shell, you shall apply @@ -1498,10 +1540,10 @@ variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. The variable @code{tramp-completion-function-alist} is intended to customize which files are taken into account for user and host name -completion (@pxref{Filename completion}). For every method, it keeps +completion (@pxref{File name completion}). For every method, it keeps a set of configuration files, accompanied by a Lisp function able to parse that file. Entries in @code{tramp-completion-function-alist} -have the form (@var{method} @var{pair1} @var{pair2} ...). +have the form (@var{method} @var{pair1} @var{pair2} @dots{}). Each @var{pair} is composed of (@var{function} @var{file}). @var{function} is responsible to extract user names and host names @@ -1712,10 +1754,10 @@ Using such persistent information can be disabled by setting @code{tramp-persistency-file-name} to @code{nil}. Once consequence of reusing connection related information is that -@var{tramp} needs to distinguish hosts. If you, for example, run a +@value{tramp} needs to distinguish hosts. If you, for example, run a local @code{sshd} on port 3001, which tunnels @command{ssh} to another host, you could access both @file{@trampfn{ssh, , localhost,}} and -@file{@trampfn{ssh, , localhost#3001,}}. @var{tramp} would use the +@file{@trampfn{ssh, , localhost#3001,}}. @value{tramp} would use the same host related information (like paths, Perl variants, etc) for both connections, although the information is valid only for one of them. @@ -1734,10 +1776,11 @@ connection again. @node Predefined connection information @section Setting own connection related information -Sometimes, @var{tramp} is not able to detect correct connection -related information. In such cases, you could tell @var{tramp} which -value it has to take. Since this could result in errors, it has to be -used with care. +Sometimes, method specific arguments in @code{tramp-methods} do not +fit your needs. Sometimes, @value{tramp} is not able to detect +correct connection related information. In such cases, you could tell +@value{tramp} which value it has to take. Since this could result in +errors, it has to be used with care. @vindex tramp-connection-properties Such settings can be performed via the list @@ -1745,13 +1788,35 @@ Such settings can be performed via the list form @code{(@var{regexp} @var{property} @var{value})}. @var{regexp} matches remote file names for which a property shall be predefined. It can be @code{nil}. @var{property} is a string, and @var{value} the -corresponding value. @var{property} could be any property found in -the file @code{tramp-persistency-file-name}. +corresponding value. -A special property is @code{"busybox"}. This must be set, if the -remote host runs a very restricted busybox as shell, which closes the +@var{property} could be any method specific parameter found in +@code{tramp-methods}. The parameter key in @code{tramp-methods} is a +symbol name @code{tramp-<foo>}. In order to overwrite it, +@var{property} must be the string @samp{<foo>}. If you, for example, +want to change the remote shell to be used on a remote machine, you +could apply + +@lisp +(add-to-list 'tramp-connection-properties + (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}") + "remote-shell" "/bin/ksh")) +(add-to-list 'tramp-connection-properties + (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}") + "remote-shell-login" '("-"))) +@end lisp + +This would overwrite the @code{tramp-remote-shell} and +@code{tramp-remote-shell-login} parameters in @code{tramp-methods}, to +be used on that remote host. + +@var{property} could also be any property found in the file +@code{tramp-persistency-file-name}. + +A special property is @samp{busybox}. This must be set, if the remote +host runs a very restricted busybox as shell, which closes the connection at will. Since there is no reliable test for this, -@var{tramp} must be indicated this way. Example: +@value{tramp} must be indicated this way. Example: @lisp (add-to-list 'tramp-connection-properties @@ -1760,8 +1825,8 @@ connection at will. Since there is no reliable test for this, @end lisp -@node Remote Programs -@section How @value{tramp} finds and uses programs on the remote machine +@node Remote programs +@section How @value{tramp} finds and uses programs on the remote host @value{tramp} depends on a number of programs on the remote host in order to function, including @command{ls}, @command{test}, @command{find} and @@ -1780,18 +1845,19 @@ remote file access. @vindex tramp-default-remote-path @vindex tramp-own-remote-path @defopt tramp-remote-path -When @value{tramp} connects to the remote machine, it searches for the -programs that it can use. The variable @code{tramp-remote-path} -controls the directories searched on the remote machine. +When @value{tramp} connects to the remote host, it searches for the +programs that it can use. The custom option +@option{tramp-remote-path} controls the directories searched on the +remote host. By default, this is set to a reasonable set of defaults for most -machines. The symbol @code{tramp-default-remote-path} is a place +hosts. The symbol @code{tramp-default-remote-path} is a place holder, it is replaced by the list of directories received via the -command @command{getconf PATH} on your remote machine. For example, +command @command{getconf PATH} on your remote host. For example, on Debian GNU/Linux this is @file{/bin:/usr/bin}, whereas on Solaris this is @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is recommended to apply this symbol on top of -@code{tramp-remote-path}. +@option{tramp-remote-path}. It is possible, however, that your local (or remote ;) system administrator has put the tools you want in some obscure local @@ -1806,9 +1872,6 @@ To add a directory to the remote search path, you could use code such as: @lisp -@i{;; We load @value{tramp} to define the variable.} -(require 'tramp) -@i{;; We have @command{perl} in "/usr/local/perl/bin"} (add-to-list 'tramp-remote-path "/usr/local/perl/bin") @end lisp @@ -1877,7 +1940,7 @@ to be set correctly to recognize the shell prompt on the remote host. Note that @value{tramp} requires the match for @code{shell-prompt-pattern} to be at the end of the buffer. Many people have something like the -following as the value for the variable: @code{"^[^>$][>$] *"}. Now +following as the value for the variable: @samp{^[^>$][>$] *}. Now suppose your shell prompt is @code{a <b> c $ }. In this case, @value{tramp} recognizes the @code{>} character as the end of the prompt, but it is not at the end of the buffer. @@ -1920,7 +1983,7 @@ of your (local or remote) host, you might need to adapt this. Example: "password" "Password" ;; Deutsch "passwort" "Passwort" - ;; Fran@,{c}ais + ;; Français "mot de passe" "Mot de passe") t) ".*:\0? *")) @end lisp @@ -2055,6 +2118,33 @@ fi @end ifset @end ifinfo +@item @command{busybox} / @command{nc} +@cindex Unix command nc +@cindex nc Unix command + +The @command{nc} command will be used with the @option{nc} method. On +the remote host, a listener will be installed. Unfortunately, the +command line syntax for this has been changed with the different +@command{busybox} versions. @value{tramp} uses the following syntax +(see @code{tramp-methods}): + +@example +# nc -l -p 42 +@end example + +If your remote @command{nc} refuses to accept the @command{-p} +parameter, you could overwrite the syntax with the following form: + +@lisp +(add-to-list + 'tramp-connection-properties + `(,(regexp-quote "192.168.0.1") "remote-copy-args" (("-l") ("%r")))) +@end lisp + +@noindent +with @samp{192.168.0.1} being the IP address of your remote host +(@pxref{Predefined connection information}). + @end table @@ -2065,7 +2155,7 @@ fi Android devices use a restricted shell. They can be accessed via the @option{adb} method. However, this restricts the access to a USB connection, and it requires the installation of the Android SDK on the -local machine. +local host. When an @command{sshd} process runs on the Android device, like provided by the @code{SSHDroid} app, any @option{ssh}-based method can @@ -2084,7 +2174,7 @@ You can instruct @value{tramp} by this form: with @samp{192.168.0.26} being the IP address of your Android device (@pxref{Predefined connection information}). -The user settings for the @code{$PATH} environment variable must be +The user settings for the @env{PATH} environment variable must be preserved. It has also been reported, that the commands in @file{/system/xbin} are better suited than the ones in @file{/system/bin}. Add these setting: @@ -2168,7 +2258,7 @@ When is @code{nil} (the default), such problems do not occur. Therefore, it is useful to set special values for @value{tramp} -files. For example, the following statement effectively `turns off' +files. For example, the following statement effectively ``turns off'' the effect of @ifset emacs @code{backup-directory-alist} @@ -2291,7 +2381,7 @@ This section needs a lot of work! Please help. @cindex sshx method with Cygwin The recent Cygwin installation of @command{ssh} works only with a Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x -eshell}, and starting @kbd{ssh test.machine}. The problem is evident +eshell}, and starting @kbd{ssh test.host}. The problem is evident if you see a message like this: @example @@ -2307,12 +2397,12 @@ can find information about setting up Cygwin in their FAQ at @cindex scpx method with Cygwin If you wish to use the @option{scpx} connection method, then you might have the problem that @value{emacsname} calls @command{scp} with a -Windows filename such as @code{c:/foo}. The Cygwin version of -@command{scp} does not know about Windows filenames and interprets -this as a remote filename on the host @code{c}. +Windows file name such as @code{c:/foo}. The Cygwin version of +@command{scp} does not know about Windows file names and interprets +this as a remote file name on the host @code{c}. One possible workaround is to write a wrapper script for @option{scp} -which converts the Windows filename to a Cygwinized filename. +which converts the Windows file name to a Cygwinized file name. @cindex Cygwin and ssh-agent @cindex SSH_AUTH_SOCK and @value{emacsname} on Windows @@ -2336,7 +2426,7 @@ know anything at all about Windows@dots{} @cindex using @value{tramp} Once you have installed @value{tramp} it will operate fairly -transparently. You will be able to access files on any remote machine +transparently. You will be able to access files on any remote host that you can log in to as though they were local. Files are specified to @value{tramp} using a formalized syntax specifying the @@ -2355,53 +2445,52 @@ minute when a connection needs to be opened. Maybe after half a minute you have already forgotten that you hit that key! @menu -* Filename Syntax:: @value{tramp} filename conventions. -* Alternative Syntax:: URL-like filename syntax. -* Filename completion:: Filename completion. +* File name Syntax:: @value{tramp} file name conventions. +* File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other @value{emacsname} packages. * Cleanup remote connections:: Cleanup remote connections. @end menu -@node Filename Syntax -@section @value{tramp} filename conventions -@cindex filename syntax -@cindex filename examples +@node File name Syntax +@section @value{tramp} file name conventions +@cindex file name syntax +@cindex file name examples -To access the file @var{localname} on the remote machine @var{machine} -you would specify the filename @file{@trampfn{, , machine, -localname}}. This will connect to @var{machine} and transfer the file +To access the file @var{localname} on the remote host @var{host} +you would specify the file name @file{@trampfn{, , host, +localname}}. This will connect to @var{host} and transfer the file using the default method. @xref{Default Method}. -Some examples of @value{tramp} filenames are shown below. +Some examples of @value{tramp} file names are shown below. @table @file @item @value{prefix}melancholia@value{postfix}.emacs -Edit the file @file{.emacs} in your home directory on the machine +Edit the file @file{.emacs} in your home directory on the host @code{melancholia}. @item @value{prefix}melancholia.danann.net@value{postfix}.emacs This edits the same file, using the fully qualified domain name of -the machine. +the host. @item @value{prefix}melancholia@value{postfix}~/.emacs This also edits the same file; the @file{~} is expanded to your -home directory on the remote machine, just like it is locally. +home directory on the remote host, just like it is locally. @item @value{prefix}melancholia@value{postfix}~daniel/.emacs This edits the file @file{.emacs} in the home directory of the user -@code{daniel} on the machine @code{melancholia}. The @file{~<user>} +@code{daniel} on the host @code{melancholia}. The @file{~<user>} construct is expanded to the home directory of that user on the remote -machine. +host. @item @value{prefix}melancholia@value{postfix}/etc/squid.conf -This edits the file @file{/etc/squid.conf} on the machine +This edits the file @file{/etc/squid.conf} on the host @code{melancholia}. @end table -@var{machine} can also be an IPv4 or IPv6 address, like in +@var{host} can also be an IPv4 or IPv6 address, like in @file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, , @value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}. @ifset emacs @@ -2412,17 +2501,17 @@ brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. Unless you specify a different name to use, @value{tramp} will use the current local user name as the remote user name to log in with. If you need to log in as a different user, you can specify the user name as -part of the filename. +part of the file name. -To log in to the remote machine as a specific user, you use the syntax -@file{@trampfn{, user, machine, path/to.file}}. That means that +To log in to the remote host as a specific user, you use the syntax +@file{@trampfn{, user, host, path/to.file}}. That means that connecting to @code{melancholia} as @code{daniel} and editing @file{.emacs} in your home directory you would specify @file{@trampfn{, daniel, melancholia, .emacs}}. It is also possible to specify other file transfer methods (@pxref{Inline methods}, @pxref{External methods}) as part of the -filename. +file name. @ifset emacs This is done by putting the method before the user and host name, as in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the @@ -2433,15 +2522,15 @@ This is done by replacing the initial @file{@value{prefix}} with @file{@value{prefix}<method>@value{postfixhop}}. (Note the trailing slash!). @end ifset -The user, machine and file specification remain the same. +The user, host and file specification remain the same. -So, to connect to the machine @code{melancholia} as @code{daniel}, +So, to connect to the host @code{melancholia} as @code{daniel}, using the @option{ssh} method to transfer files, and edit -@file{.emacs} in my home directory I would specify the filename +@file{.emacs} in my home directory I would specify the file name @file{@trampfn{ssh, daniel, melancholia, .emacs}}. @ifset emacs -A remote filename containing a host name only, which is equal to a +A remote file name containing a host name only, which is equal to a method name, is not allowed. If such a host name is used, it must always be preceded by an explicit method name, like @file{@value{prefix}ssh@value{postfixhop}ssh@value{postfix}}. @@ -2453,53 +2542,13 @@ by adding @file{#<port>} to the host name, like in @file{@trampfn{ssh, daniel, melancholia#42, .emacs}}. -@node Alternative Syntax -@section URL-like filename syntax -@cindex filename syntax -@cindex filename examples - -Additionally to the syntax described in the previous chapter, it is -possible to use a URL-like syntax for @value{tramp}. This can be -switched on by customizing the variable @code{tramp-syntax}. Please -note that this feature is experimental for the time being. - -The variable @code{tramp-syntax} must be set before requiring @value{tramp}: - -@lisp -(setq tramp-syntax 'url) -(require 'tramp) -@end lisp - -Then, a @value{tramp} filename would look like this: -@file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}. -@file{/@var{method}://} is mandatory, all other parts are optional. -@file{:@var{port}} is useful for methods only who support this. - -The last example from the previous section would look like this: -@file{/ssh://daniel@@melancholia/.emacs}. - -For the time being, @code{tramp-syntax} can have the following values: - -@itemize @w{} -@ifset emacs -@item @code{ftp}---That is the default syntax -@item @code{url}---URL-like syntax -@end ifset -@ifset xemacs -@item @code{sep}---That is the default syntax -@item @code{url}---URL-like syntax -@item @code{ftp}---EFS-like syntax -@end ifset -@end itemize - - -@node Filename completion -@section Filename completion -@cindex filename completion +@node File name completion +@section File name completion +@cindex file name completion -Filename completion works with @value{tramp} for completion of method -names, of user names and of machine names as well as for completion of -file names on remote machines. +File name completion works with @value{tramp} for completion of method +names, of user names and of host names as well as for completion of +file names on remote hosts. @ifset emacs In order to enable this, partial completion must be activated in your @file{.emacs}. @@ -2527,8 +2576,7 @@ If you, for example, type @kbd{C-x C-f @value{prefix}t @samp{@value{prefixhop}telnet@value{postfixhop}} is a possible completion for the respective method, @ifset emacs -@samp{tmp/} stands for the directory @file{/tmp} on your local -machine, +@samp{tmp/} stands for the directory @file{/tmp} on your local host, @end ifset and @samp{@value{prefixhop}toto@value{postfix}} might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts} @@ -2536,7 +2584,7 @@ file (given you're using default method @option{ssh}). If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to @samp{@value{prefix}telnet@value{postfixhop}}. -Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in +Next @kbd{@key{TAB}} brings you all host names @value{tramp} detects in your @file{/etc/hosts} file, let's say @example @@ -2548,21 +2596,21 @@ your @file{/etc/hosts} file, let's say @end multitable @end example -Now you can choose the desired machine, and you can continue to -complete file names on that machine. +Now you can choose the desired host, and you can continue to +complete file names on that host. 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 +Remote hosts 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 +Once the remote host identification is completed, it comes to +file name completion on the remote host. This works pretty much like for files on the local host, with the exception that minibuffer -killing via a double-slash works only on the filename part, except -that filename part starts with @file{//}. +killing via a double-slash works only on the file name part, except +that file name part starts with @file{//}. @ifset emacs A triple-slash stands for the default behavior. @end ifset @@ -2596,15 +2644,16 @@ 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 +files by other processes. Therefore, during file name completion, the remote directory contents are reread regularly in order to detect such changes, which would be invisible otherwise (@pxref{Connection caching}). +@vindex tramp-completion-reread-directory-timeout @defopt tramp-completion-reread-directory-timeout -This variable defines the number of seconds since last remote command -before rereading a directory contents. A value of 0 would require an -immediate reread during filename completion, @code{nil} means to use -always cached values for the directory contents. +This custom option defines the number of seconds since last remote +command before rereading a directory contents. A value of 0 would +require an immediate reread during file name completion, @code{nil} +means to use always cached values for the directory contents. @end defopt @@ -2642,9 +2691,10 @@ remotehost, /path}} would be sufficient from now on. @vindex tramp-save-ad-hoc-proxies @defopt tramp-save-ad-hoc-proxies -This customer option controls whether ad-hoc definitions are kept -persistently in @code{tramp-default-proxies-alist}. That means, those -definitions are available also for future @value{emacsname} sessions. +This custom option controls whether ad-hoc definitions are kept +persistently in @option{tramp-default-proxies-alist}. That means, +those definitions are available also for future @value{emacsname} +sessions. @end defopt @@ -2671,7 +2721,7 @@ host when the variable @code{default-directory} is remote: @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 -remote processes; all processes run still locally on your machine with +remote processes; all processes run still locally on your host with an adapted @code{default-directory}. This section does not apply for such connection methods. @end ifset @@ -2684,9 +2734,9 @@ integrated. Integration of further packages is planned, any help for this is welcome! When your program is not found in the default search path -@value{tramp} sets on the remote machine, you should either use an +@value{tramp} sets on the remote host, you should either use an absolute path, or extend @code{tramp-remote-path} (see @ref{Remote -Programs}): +programs}): @lisp (add-to-list 'tramp-remote-path "~/bin") @@ -2696,8 +2746,8 @@ Programs}): The environment for your program can be adapted by customizing @code{tramp-remote-process-environment}. This variable is a list of strings. It is structured like @code{process-environment}. Each -element is a string of the form @code{"ENVVARNAME=VALUE"}. An entry -@code{"ENVVARNAME="} disables the corresponding environment variable, +element is a string of the form @samp{ENVVARNAME=VALUE}. An entry +@samp{ENVVARNAME=} disables the corresponding environment variable, which might have been set in your init file like @file{~/.profile}. @noindent @@ -2720,6 +2770,21 @@ following code in your @file{.emacs}: (setq tramp-remote-process-environment process-environment)) @end lisp +When running @code{process-file} or @code{start-file-process} on a +remote @code{default-directory}, the default settings in +@code{process-environment} are not used as it is the case for local +processes. However, if you need environment variables other than set +in @code{tramp-remote-process-environment}, you can let-bind them to +@code{process-environment}. Only those variables will be set then: + +@lisp +(let ((process-environment (cons "HGPLAIN=1" process-environment))) + (process-file @dots{})) +@end lisp + +This works only for environment variables which are not set already in +@code{process-environment}. + If you use other @value{emacsname} packages which do not run out-of-the-box on a remote host, please let us know. We will try to integrate them as well. @xref{Bug Reports}. @@ -2752,18 +2817,18 @@ that host. Calling @kbd{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, +also a valid file 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 +shell file 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 +file name, if you are on a remote buffer, and if @option{explicit-shell-file-name} is equal to @code{nil}. @end ifset @@ -2784,7 +2849,7 @@ You will see the buffer @file{*Async Shell Command*}, containing the continuous output of the @command{tail} command. @ifset emacs -A similar behaviour can be reached by @kbd{M-x auto-revert-tail-mode}, +A similar behavior can be reached by @kbd{M-x auto-revert-tail-mode}, if available. @end ifset @@ -2837,7 +2902,7 @@ uid=0(root) gid=0(root) groups=0(root) @cindex gdb @cindex perldb -@file{gud.el} offers an unified interface to several symbolic +@file{gud.el} offers a unified interface to several symbolic debuggers @ifset emacs @ifinfo @@ -2960,6 +3025,13 @@ Subscribing to the list is performed via @uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, the @value{tramp} Mail Subscription Page}. +@ifset emacs +@ifset installchapter +Before sending a bug report, you could check whether @value{tramp} +works at all. Run the test suite on your local host, @ref{Testing}. +@end ifset +@end ifset + @findex tramp-bug To report a bug in @value{tramp}, you should execute @kbd{M-x tramp-bug}. This will automatically generate a buffer with the details @@ -2967,7 +3039,7 @@ of your system and @value{tramp} version. When submitting a bug report, please try to describe in excruciating detail the steps required to reproduce the problem, the setup of the -remote machine and any special conditions that exist. You should also +remote host and any special conditions that exist. You should also check that your problem is not described already in @xref{Frequently Asked Questions}. @@ -3041,7 +3113,7 @@ information about remote hosts is kept in the file specified in confident that files on remote hosts are not changed out of @value{emacsname}' control, set @code{remote-file-name-inhibit-cache} to @code{nil}. Set also @code{tramp-completion-reread-directory-timeout} -to @code{nil}, @ref{Filename completion}. +to @code{nil}, @ref{File name completion}. Disable version control. If you access remote files which are not under version control, a lot of check operations can be avoided by @@ -3069,7 +3141,7 @@ reasons heading the bug mailing list: @item Unknown characters in the prompt -@value{tramp} needs to recognize the prompt on the remote machine +@value{tramp} needs to recognize the prompt on the remote host 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 @@ -3086,22 +3158,35 @@ setting the cursor at the top of the buffer, and applying the expression If it fails, or the cursor is not moved at the end of the buffer, your prompt is not recognized correctly. -A special problem is the zsh, which uses left-hand side and right-hand -side prompts in parallel. Therefore, it is necessary to disable the -zsh line editor on the remote host. You shall add to @file{~/.zshrc} -the following command: +A special problem is the zsh shell, which uses left-hand side and +right-hand side prompts in parallel. Therefore, it is necessary to +disable the zsh line editor on the remote host. You shall add to +@file{~/.zshrc} the following command: @example [ $TERM = "dumb" ] && unsetopt zle && PS1='$ ' @end example +Similar fancy prompt settings are known from the fish shell. Here you +must add in @file{~/.config/fish/config.fish}: + +@example +function fish_prompt + if test $TERM = "dumb" + echo "\$ " + else + @dots{} + end +end +@end example + Furthermore it has been reported, that @value{tramp} (like sshfs, incidentally) doesn't work with WinSSHD due to strange prompt settings. @item Echoed characters after login -When the remote machine opens an echoing shell, there might be control +When the remote host opens an echoing shell, there might be control characters in the welcome message. @value{tramp} tries to suppress such echoes via the @command{stty -echo} command, but sometimes this command is not reached, because the echoed output has confused @@ -3199,7 +3284,7 @@ your @file{~/.ssh/config}: @item File name completion does not work with @value{tramp} -When you log in to the remote machine, do you see the output of +When you log in to the remote host, do you see the output of @command{ls} in color? If so, this may be the cause of your problems. @command{ls} outputs @acronym{ANSI} escape sequences that your terminal @@ -3207,19 +3292,19 @@ emulator interprets to set the colors. These escape sequences will confuse @value{tramp} however. In your @file{.bashrc}, @file{.profile} or equivalent on the remote -machine you probably have an alias configured that adds the option +host you probably have an alias configured that adds the option @option{--color=yes} or @option{--color=auto}. You should remove that alias and ensure that a new login @emph{does not} display the output of @command{ls} in color. If you still cannot use -filename completion, report a bug to the @value{tramp} developers. +file name completion, report a bug to the @value{tramp} developers. @item File name completion does not work in large directories @value{tramp} uses globbing for some operations. (Globbing means to use the -shell to expand wildcards such as `*.c'.) This might create long +shell to expand wildcards such as @samp{*.c}.) This might create long command lines, especially in directories with many files. Some shells choke on long command lines, or don't cope well with the globbing itself. @@ -3371,6 +3456,13 @@ if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then fi @end example +Furthermore, if you use an @option{ssh}-based method, you could add +the following line to your @file{~/.ssh/environment} file: + +@example +HISTFILE=/dev/null +@end example + @item There are longish file names to type. How to shorten this? @@ -3618,6 +3710,24 @@ I would like to thank all @value{tramp} users who have contributed to the different recipes! +@item I have saved @value{tramp} file names as indicated. But it +doesn't work in a new @value{emacsname} session! + +If you have saved an ad-hoc multi-hop @value{tramp} file name +(@pxref{Ad-hoc multi-hops}) via bookmarks, recent files, +@ifset emacs +filecache, bbdb, +@end ifset +or another package, you must use the full ad-hoc file name including +all hops, like @file{@trampfn{ssh, bird, +bastion|ssh@value{postfixhop}news.my.domain, /opt/news/etc}}. + +Alternatively, if you save only the abbreviated multi-hop file name +@file{@trampfn{ssh, news, news.my.domain, /opt/news/etc}}, the custom +option @code{tramp-save-ad-hoc-proxies} must be set to a to a +non-@code{nil} value. + + @ifset emacs @item How can I use @value{tramp} to connect to a remote @value{emacsname} @@ -3758,7 +3868,7 @@ names. As such, the lisp functions @code{file-name-directory} and package. Their replacements are reasonably simplistic in their approach. They -dissect the filename, call the original handler on the localname and +dissect the file name, call the original handler on the localname and then rebuild the @value{tramp} file name with the result. This allows the platform specific hacks in the original handlers to take @@ -3768,27 +3878,26 @@ effect while preserving the @value{tramp} file name information. @ifset emacs @node External packages @section Integration with external Lisp packages -@subsection Filename completion. +@subsection File name completion. -While reading filenames in the minibuffer, @value{tramp} must decide -whether it completes possible incomplete filenames, or not. Imagine +While reading file names in the minibuffer, @value{tramp} must decide +whether it completes possible incomplete file names, or not. Imagine there is the following situation: You have typed @kbd{C-x C-f @value{prefix}ssh@value{postfixhop} @key{TAB}}. @value{tramp} cannot know, whether @option{ssh} is a method or a host name. It checks therefore the last input character you have typed. If this is @key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are -still in filename completion, and it does not connect to the possible +still in file name completion, and it does not connect to the possible remote host @option{ssh}. -@vindex tramp-completion-mode -External packages, which use other characters for completing filenames +External packages, which use other characters for completing file names in the minibuffer, must signal this to @value{tramp}. For this case, -the variable @code{tramp-completion-mode} can be bound temporarily to +the variable @code{non-essential} can be bound temporarily to a non-@code{nil} value. @lisp -(let ((tramp-completion-mode t)) - ...) +(let ((non-essential t)) + @dots{}) @end lisp @@ -3800,21 +3909,21 @@ 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 where 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. +should let-bind the variable @code{process-file-side-effects} to +@code{nil}. Then @value{tramp} won't flush the file attributes cache. @lisp (let (process-file-side-effects) - ...) + @dots{}) @end lisp For asynchronous processes, @value{tramp} flushes the file attributes cache via a process sentinel. If the caller of @code{start-file-process} knows that there are no file attribute -changes, it shall set the process sentinel to @code{nil}. In case the -caller defines an own process sentinel, @value{tramp}'s process +changes, it should set the process sentinel to the default. In cases +where the caller defines its own process sentinel, @value{tramp}'s process sentinel is overwritten. The caller can still flush the file attributes cache in its process sentinel with this code: @@ -3887,7 +3996,6 @@ Sometimes, it might be even necessary to step through @value{tramp} function call traces. Such traces are enabled by the following code: @lisp -(require 'tramp) (require 'trace) (dolist (elt (all-completions "tramp-" obarray 'functionp)) (trace-function-background (intern elt))) @@ -3924,16 +4032,16 @@ printed and deleted. But I have decided that this is too fragile to reliably work, so on some systems you'll have to do without the uuencode methods. -@item The @value{tramp} filename syntax differs between Emacs and XEmacs. +@item The @value{tramp} file name syntax differs between Emacs and XEmacs. -The Emacs maintainers wish to use a unified filename syntax for +The Emacs maintainers wish to use a unified file name syntax for Ange-FTP and @value{tramp} so that users don't have to learn a new syntax. It is sufficient to learn some extensions to the old syntax. For the XEmacs maintainers, the problems caused from using a unified -filename syntax are greater than the gains. The XEmacs package system +file name syntax are greater than the gains. The XEmacs package system uses EFS for downloading new packages. So, obviously, EFS has to be -installed from the start. If the filenames were unified, @value{tramp} +installed from the start. If the file names were unified, @value{tramp} would have to be installed from the start, too. @ifset xemacs @@ -3948,30 +4056,34 @@ file: The autoload of the @value{emacsname} @value{tramp} package must be disabled. This can be achieved by setting file permissions @code{000} -to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}. +to the files @file{@dots{}/xemacs-packages/lisp/tramp/auto-autoloads.el*}. -In case of unified filenames, all @value{emacsname} download sites are +In case of unified file names, all @value{emacsname} download sites are added to @code{tramp-default-method-alist} with default method @option{ftp} @xref{Default Method}. These settings shouldn't be touched for proper working of the @value{emacsname} package system. -The syntax for unified filenames is described in the @value{tramp} manual +The syntax for unified file names is described in the @value{tramp} manual for @value{emacsothername}. @end ifset @end itemize + @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi + @node Function Index @unnumbered Function Index @printindex fn + @node Variable Index @unnumbered Variable Index @printindex vr + @node Concept Index @unnumbered Concept Index @printindex cp @@ -3984,7 +4096,5 @@ for @value{emacsothername}. @c shells. @c * Explain how tramp.el works in principle: open a shell on a remote @c host and then send commands to it. -@c * Use `filename' resp. `file name' consistently. -@c * Use `host' resp. `machine' consistently. @c * Consistent small or capitalized words especially in menus. @c * Make a unique declaration of @trampfn. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index c22141335e1..dccf3175386 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -2,13 +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-2013 Free Software Foundation, Inc. +@c Copyright (C) 2003-2015 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 In the Tramp GIT, 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.2.8-pre +@set trampver 2.2.13-pre @c Other flags from configuration @set instprefix /usr/local diff --git a/doc/misc/url.texi b/doc/misc/url.texi index fdec68b1c61..95fe5eabc33 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -1,6 +1,7 @@ \input texinfo -@setfilename ../../info/url +@setfilename ../../info/url.info @settitle URL Programmer's Manual +@include docstyle.texi @iftex @c @finalout @@ -20,14 +21,14 @@ @copying This is the manual for the @code{url} Emacs Lisp library. -Copyright @copyright{} 1993--1999, 2002, 2004--2013 Free Software +Copyright @copyright{} 1993--1999, 2002, 2004--2015 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,'' +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''. @@ -408,6 +409,13 @@ ignored; any other value means to ask the user on each request. @node Cookies @subsection Cookies +@findex url-cookie-delete +@defun url-cookie-list +This command creates a @file{*url cookies*} buffer listing the current +cookies, if there are any. You can remove a cookie using the +@kbd{C-k} (@code{url-cookie-delete}) command. +@end defun + @defopt url-cookie-file The file in which cookies are stored, defaulting to @file{cookies} in the directory specified by @code{url-configuration-directory}. @@ -585,7 +593,7 @@ sending a message to @samp{foo@@bar.com}. The ``retrieval method'' for such URLs is to open a mail composition buffer in which the appropriate content (e.g., the recipient address) has been filled in. - As defined in RFC 2368, a @code{mailto} URL has the form + As defined in RFC 6068, a @code{mailto} URL can have the form @example @samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]} @@ -863,7 +871,7 @@ more likely to conflict with other files. @end defun @defun url-cache-expired -This function returns non-nil if a cache entry has expired (or is absent). +This function returns non-@code{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 @@ -1107,7 +1115,7 @@ This the @samp{nslookup} program. It is @code{"nslookup"} by default. @cindex network connections, suppressing @cindex suppressing network connections @cindex bugs, HTML -@cindex HTML `bugs' +@cindex HTML ``bugs'' In some circumstances it is desirable to suppress making network connections. A typical case is when rendering HTML in a mail user agent, when external URLs should not be activated, particularly to @@ -1240,7 +1248,7 @@ if it exists. @defopt url-debug @cindex debugging Specifies the types of debug messages which are logged to -the @code{*URL-DEBUG*} buffer. +the @file{*URL-DEBUG*} buffer. @code{t} means log all messages. A number means log all messages and show them with @code{message}. It may also be a list of the types of messages to be logged. diff --git a/doc/misc/vhdl-mode.texi b/doc/misc/vhdl-mode.texi new file mode 100644 index 00000000000..b8b3850c55a --- /dev/null +++ b/doc/misc/vhdl-mode.texi @@ -0,0 +1,1022 @@ +\input texinfo @c -*- texinfo -*- + +@setfilename ../../info/vhdl-mode.info +@settitle VHDL Mode, an Emacs mode for editing VHDL code +@include docstyle.texi + +@c Adapted from the VHDL Mode texinfo manual version 2 by Rodney J. Whitby. +@c Adapted from the CC Mode texinfo manual by Barry A. Warsaw. + +@copying +This file documents VHDL Mode, an Emacs mode for editing VHDL code. + +Copyright @copyright{} 1995--2008, 2010, 2012, 2015 Free Software +Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs editing modes +@direntry +* VHDL Mode: (vhdl-mode). Emacs mode for editing VHDL code. +@end direntry + +@finalout + +@titlepage +@title VHDL Mode +@sp 2 +@subtitle A GNU Emacs mode for editing VHDL code. +@sp 2 +@author Reto Zimmermann +@author @email{reto@@gnu.org} +@author Rod Whitby +@author @email{software.vhdl-mode@@rwhitby.net} + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top VHDL Mode, an Emacs mode for editing VHDL code + +@insertcopying +@end ifnottex + +@menu +* Introduction:: +* Getting Connected:: +* New Indentation Engine:: +* Customizing Indentation:: +* Syntactic Symbols:: +* Frequently Asked Questions:: +* Getting the latest VHDL Mode release:: +* Sample .emacs File:: +* Limitations and Known Bugs:: +* Mailing Lists and Submitting Bug Reports:: +* GNU Free Documentation License:: The license for this documentation. +* Concept Index:: +* Command Index:: Command Index +* Key Index:: Key Index +* Variable Index:: Variable Index +@end menu + +@node Introduction +@chapter Introduction +@cindex Introduction + +Welcome to VHDL Mode. This is a GNU Emacs mode for editing files +containing VHDL code. + +This manual will describe the following: + +@itemize @bullet +@item +How to get started using VHDL Mode. + +@item +How the indentation engine works. + +@item +How to customize the indentation engine. + +@end itemize + +@findex vhdl-version +The major version number was incremented to 3 with the addition of +many new features for editing VHDL code to the new indentation engine, +which was introduced in major version 2. To find the minor revision +number of this release, use @kbd{M-x vhdl-version RET}. + +A special word of thanks goes to Rod Whitby, who wrote the +VHDL Mode indentation engine, and to Barry Warsaw, who wrote +the CC Mode indentation engine that formed the basis +thereof. Their manuals were also the basis for this manual. + +This manual is not very up-to-date. It basically contains the +indentation machine documentation by Rod Whitby with only minor +adaptions. A short documentation of the entire VHDL Mode is available +within the mode itself by typing @kbd{C-c C-h}. Also, all commands and +customization of most variables are available through the menu, which +makes everything highly self-explaining. + +@node Getting Connected +@chapter Getting Connected +@cindex Getting Connected + +To get started, simply visit a @file{.vhd} file in Emacs; or type +@kbd{M-x vhdl-mode RET}. + +@node New Indentation Engine +@chapter New Indentation Engine +@cindex New Indentation Engine + +VHDL Mode has a new indentation engine, providing a simplified, yet +flexible and general mechanism for customizing indentation. It breaks +indentation calculation into two steps. First for the line of code being +indented, VHDL Mode analyzes what kind of language construct it's +looking at, then it applies user defined offsets to the current line +based on this analysis. + +This section will briefly cover how indentation is calculated in +VHDL Mode. It is important to understand the indentation model +being used so that you will know how to customize VHDL Mode for +your personal coding style. + +@menu +* Syntactic Analysis:: Step 1 -- Syntactic Analysis +* Indentation Calculation:: Step 2 -- Indentation Calculation +@end menu + +@node Syntactic Analysis +@section Syntactic Analysis +@cindex Syntactic Analysis + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +@cindex relative buffer position +@cindex syntactic symbol +@cindex syntactic component +@cindex syntactic component list +@cindex relative buffer position +The first thing VHDL Mode does when indenting a line of code, is +to analyze the line, determining the @dfn{syntactic component list} of +the construct on that line. A @dfn{syntactic component} consists of a +pair of information (in lisp parlance, a @emph{cons cell}), where the +first part is a @dfn{syntactic symbol}, and the second part is a +@dfn{relative buffer position}. Syntactic symbols describe elements of +VHDL code, e.g., @code{statement}, @code{comment}, @code{block-open}, +@code{block-close}, etc. @xref{Syntactic Symbols}, for a complete list +of currently recognized syntactic symbols and their semantics. Also, +the variable @code{vhdl-offsets-alist} contains the list of currently +supported syntactic symbols. + +Conceptually, a line of VHDL code is always indented relative to the +indentation of some line higher up in the buffer. This is represented +by the relative buffer position in the syntactic component. + +It might help to see an example. Suppose we had the following code as +the only thing in a VHDL Mode buffer @footnote{The line numbers +in this and future examples don't actually appear in the buffer.}: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +@kindex C-c C-x +@findex vhdl-show-syntactic-information +@findex show-syntactic-information (vhdl-) +We can use the command @kbd{C-c C-x} +(@code{vhdl-show-syntactic-information}) to simply report what the +syntactic analysis is for the current line. Running this command on +line 4 of example 1, we'd see in the echo area: +@example + +((statement . 28)) + +@end example + +This tells us that the line is a statement and it is indented relative +to buffer position 28, which happens to be the @samp{q} on line 3. If +you were to move point to line 3 and hit @kbd{C-c C-x}, you would see: +@example + +((statement-block-intro . 20)) + +@end example + +This indicates that line 3 is the first statement in a block, and is +indented relative to buffer position 20, which is the @samp{b} in the +@code{begin} keyword on line 2. + +@cindex comment only line +Syntactic component lists can contain more than one component, and +individual syntactic components need not have relative buffer positions. +The most common example of this is a line that contains a @dfn{comment +only line}. +@example +@group + +%%% TBD %%% + +@end group +@end example + +@noindent +Hitting @kbd{C-c C-x} on line 3 of the example gives us: +@example + +((comment-intro) (block-intro . 46)) + +@end example + +@noindent +so you can see that the syntactic component list contains two syntactic +components. Also notice that the first component, +@samp{(comment-intro)} has no relative buffer position. + +@node Indentation Calculation +@section Indentation Calculation +@cindex Indentation Calculation + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +Indentation for the current line is calculated using the syntactic +component list derived in step 1 above (see @ref{Syntactic +Analysis}). Each component contributes to the final total indentation +of the line in two ways. + +First, the syntactic symbols are looked up in the @code{vhdl-offsets-alist} +variable, which is an association list of syntactic symbols and the +offsets to apply for those symbols. These offsets are added to the +running total. + +Second, if the component has a relative buffer position, VHDL Mode +adds the column number of that position to the running total. By adding +up the offsets and columns for every syntactic component on the list, +the final total indentation for the current line is computed. + +Let's use our code example above to see how this works. Here is our +example again. +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +@kindex TAB +Let's say point is on line 3 and we hit the @key{TAB} key to re-indent +the line. Remember that the syntactic component list for that +line is: +@example + +((statement-block-intro . 20)) + +@end example + +@noindent +VHDL Mode looks up @code{statement-block-intro} in the +@code{vhdl-offsets-alist} variable. Let's say it finds the value @samp{2}; +it adds this to the running total (initialized to zero), yielding a +running total indentation of 2 spaces. + +Next VHDL Mode goes to buffer position 20 and asks for the +current column. Since the @code{begin} keyword at buffer position 20 is +in column zero, it adds @samp{0} to the running total. Since there is +only one syntactic component on the list for this line, indentation +calculation is complete, and the total indentation for the line is 2 +spaces. +Simple, huh? + +Actually, the mode usually just does The Right Thing without you having +to think about it in this much detail. But when customizing +indentation, it's helpful to understand the general indentation model +being used. + +@vindex vhdl-echo-syntactic-information-p +@vindex echo-syntactic-information-p (vhdl-) +@cindex TAB +To help you configure VHDL Mode, you can set the variable +@code{vhdl-echo-syntactic-information-p} to non-@code{nil} so that the +syntactic component list and calculated offset will always be echoed in +the minibuffer when you hit @kbd{TAB}. + + +@ignore +@node Indentation Commands +@chapter Indentation Commands +@cindex Indentation Commands + +@strong{<TBD>} +@end ignore + + +@node Customizing Indentation +@chapter Customizing Indentation +@cindex Customizing Indentation + +@cindex vhdl-set-offset +@cindex set-offset (vhdl-) +The @code{vhdl-offsets-alist} variable is where you customize all your +indentations. You simply need to decide what additional offset you want +to add for every syntactic symbol. You can use the command @kbd{C-c +O} (@code{vhdl-set-offset}) as the way to set offsets, both +interactively and from your mode hook. Also, you can set up +@emph{styles} of indentation. Most likely, you'll find one of the +pre-defined styles will suit your needs, but if not, this section will +describe how to set up basic editing configurations. @xref{Styles}, for +an explanation of how to set up named styles. + +@cindex vhdl-basic-offset +@cindex basic-offset (vhdl-) +As mentioned previously, the variable @code{vhdl-offsets-alist} is an +association list between syntactic symbols and the offsets to be applied +for those symbols. In fact, these offset values can be an integer, a +function or variable name, or one of the following symbols: @code{+}, +@code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The symbol +values have the following meanings: + +@itemize @bullet + +@item +@code{+} -- 1 x @code{vhdl-basic-offset} +@item +@code{-} -- -1 x @code{vhdl-basic-offset} +@item +@code{++} -- 2 x @code{vhdl-basic-offset} +@item +@code{--} -- -2 x @code{vhdl-basic-offset} +@item +@code{*} -- 0.5 x @code{vhdl-basic-offset} +@item +@code{/} -- -0.5 x @code{vhdl-basic-offset} + +@end itemize + +@noindent +So, for example, because most of the default offsets are defined in +terms of @code{+}, @code{-}, and @code{0}, if you like the general +indentation style, but you use 2 spaces instead of 4 spaces per level, +you can probably achieve your style just by changing +@code{vhdl-basic-offset} like so (in your @file{.emacs} file): +@example + +(setq vhdl-basic-offset 2) + +@end example + +To change indentation styles more radically, you will want to change the +value associated with the syntactic symbols in the +@code{vhdl-offsets-alist} variable. First, I'll show you how to do that +interactively, then I'll describe how to make changes to your +@file{.emacs} file so that your changes are more permanent. + +@menu +* Interactive Customization:: +* Permanent Customization:: +* Styles:: +* Advanced Customizations:: +@end menu + +@node Interactive Customization +@section Interactive Customization +@cindex Interactive Customization + +As an example of how to customize indentation, let's change the +style of the example above from: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example +@noindent +to: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +In other words, we want to change the indentation of the statements +inside the inverter process. Notice that the construct we want to +change starts on line 3. To change the indentation of a line, we need +to see which syntactic component affect the offset calculations for that +line. Hitting @kbd{C-c C-x} on line 3 yields: +@example + +((statement-block-intro . 20)) + +@end example + +@findex vhdl-set-offset +@findex set-offset (vhdl-) +@kindex C-c O +@noindent +So we know that to change the offset of the first signal assignment, we need to +change the indentation for the @code{statement-block-intro} syntactic +symbol. To do this interactively, just hit @kbd{C-c O} +(@code{vhdl-set-offset}). This prompts you for the syntactic symbol to +change, providing a reasonable default. In this case, the default is +@code{statement-block-intro}, which is just the syntactic symbol we want to +change! + +After you hit return, VHDL Mode will then prompt you for the new +offset value, with the old value as the default. The default in this +case is @samp{+}, so hit backspace to delete the @samp{+}, then hit +@samp{++} and @kbd{RET}. This will associate an offset of twice the +basic indent with the syntactic symbol @code{statement-block-intro} in +the @code{vhdl-offsets-alist} variable. + +@findex vhdl-indent-defun +@findex indent-defun (vhdl-) +To check your changes quickly, just enter @kbd{M-x vhdl-indent-defun} to +reindent the entire function. The example should now look like: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +Notice how just changing the offset on line 3 is all we needed to do. +Since the other affected lines are indented relative to line 3, they are +automatically indented the way you'd expect. For more complicated +examples, this may not always work. The general approach to take is to +always start adjusting offsets for lines higher up in the file, then +re-indent and see if any following lines need further adjustments. + +@node Permanent Customization +@section Permanent Indentation +@cindex Permanent Indentation + +@vindex vhdl-mode-hook +@cindex hooks +To make this change permanent, you need to add some lisp code to your +@file{.emacs} file. VHDL Mode provides a @code{vhdl-mode-hook} +that you can use to customize your language editing styles. This hook +gets run as the last thing when you enter VHDL Mode. + +Here's a simplified example of what you can add to your @file{.emacs} +file to make the changes described in the previous section +(@ref{Interactive Customization}) more permanent. See the Emacs +manuals for more information on customizing Emacs via hooks. +@xref{Sample .emacs File}, for a more complete sample @file{.emacs} file. + +@example +@group + +(defun my-vhdl-mode-hook () + ;; my customizations for all of vhdl-mode + (vhdl-set-offset 'statement-block-intro '++) + ;; other customizations can go here + ) +(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) + +@end group +@end example + +For complex customizations, you will probably want to set up a +@emph{style} that groups all your customizations under a single +name. @xref{Styles}. + +The offset value can also be a function, and this is how power users +gain enormous flexibility in customizing indentation. @xref{Advanced +Customizations}. + +@node Styles +@section Styles +@cindex Styles + +Most people only need to edit code formatted in just a few well-defined +and consistent styles. For example, their organization might impose a +``blessed'' style that all its programmers must conform to. Similarly, +people who work on GNU software will have to use the GNU coding style on +C code. Some shops are more lenient, allowing some variety of coding +styles, and as programmers come and go, there could be a number of +styles in use. For this reason, VHDL Mode makes it convenient for +you to set up logical groupings of customizations called @dfn{styles}, +associate a single name for any particular style, and pretty easily +start editing new or existing code using these styles. This chapter +describes how to set up styles and how to edit your C code using styles. + +@menu +* Built-in Styles:: +* Adding Styles:: +* File Styles:: +@end menu + + +@node Built-in Styles +@subsection Built-in Styles +@cindex Built-in Styles + +If you're lucky, one of VHDL Mode's built-in styles might be just +what you're looking for. Some of the most common VHDL styles are +already built-in. These include: + +@itemize @bullet +@item +@cindex IEEE style +@code{GNU} -- the coding style in the IEEE Language Reference Manual. + +@end itemize + +@findex vhdl-set-style +@findex set-style (vhdl-) +If you'd like to experiment with these built-in styles you can simply +type @kbd{M-x vhdl-set-style RET} in a VHDL Mode buffer. + +You will be prompted for one of the above styles (with completion). +Enter one of the styles and hit @kbd{RET}. Note however that setting a +style in this way does @emph{not} automatically re-indent your file. +@ignore +For commands that you can use to view the effect of your changes, see +@ref{Indentation Commands}. +@end ignore + +Once you find a built-in style you like, you can make the change +permanent by adding a call to your @file{.emacs} file. Let's say for +example that you want to use the @code{IEEE} style in all your +files. You would add this: +@example +@group + +(defun my-vhdl-mode-hook () + ;; use IEEE style for all VHDL code + (vhdl-set-style "IEEE") + ;; other customizations can go here + ) +(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) + +@end group +@end example + +@noindent +@xref{Permanent Customization}. + +@node Adding Styles +@subsection Adding Styles +@cindex Adding Styles + +@vindex vhdl-style-alist +@vindex style-alist (vhdl-) +@findex vhdl-add-style +@findex add-style (vhdl-) +If none of the built-in styles is appropriate, you'll probably want to +add a new style definition. Styles are kept in the @code{vhdl-style-alist} +variable, but you probably won't want to modify this variable directly. +VHDL Mode provides a function, called @code{vhdl-add-style}, that you +can use to easily add new styles or update existing styles. This +function takes two arguments, a @var{stylename} string, and an +association list @var{description} of style customizations. If +@var{stylename} is not already in @code{vhdl-style-alist}, the new style is +added, otherwise the style already associated with @var{stylename} is +changed to the new @var{description}. This function also takes an +optional third argument, which if non-@code{nil}, automatically +institutes the new style in the current buffer. + +The sample @file{.emacs} file provides a concrete example of how a new +style can be added and automatically set. @xref{Sample .emacs File}. + +@node File Styles +@subsection File Styles +@cindex File Styles + +@cindex local variables +The Emacs manual describes how you can customize certain variables on a +per-file basis by including a @dfn{Local Variable} block at the end of +the file. So far, you've only seen a functional interface to +VHDL Mode, which is highly inconvenient for use in a Local Variable +block. VHDL Mode provides two variables that make it easier for +you to customize your style on a per-file basis. + +@vindex vhdl-file-style +@vindex file-style (vhdl-) +@vindex vhdl-file-offsets +@vindex file-offsets (vhdl-) + +The variable @code{vhdl-file-style} can be set to a style name string as +described in @ref{Built-in Styles}. When the file is visited, +VHDL Mode will automatically set the file's style to this style +using @code{vhdl-set-style}. + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +@findex vhdl-set-offset +@findex set-offset (vhdl-) +Another variable, @code{vhdl-file-offsets}, takes an association list +similar to what is allowed in @code{vhdl-offsets-alist}. When the file is +visited, VHDL Mode will automatically institute these offsets using +@code{vhdl-set-offset}. @xref{Customizing Indentation}. + +Note that file style settings (i.e., @code{vhdl-file-style}) are applied +before file offset settings (i.e., @code{vhdl-file-offsets}). + + +@node Advanced Customizations +@section Advanced Customizations +@cindex Advanced Customizations + +@vindex vhdl-style-alist +@vindex style-alist (vhdl-) +@vindex vhdl-basic-offset +@vindex basic-offset (vhdl-) +For most users, VHDL Mode will support their coding styles with +very little need for customizations. Usually, one of the standard +styles defined in @code{vhdl-style-alist} will do the trick. Sometimes, +one of the syntactic symbol offsets will need to be tweaked slightly, or +perhaps @code{vhdl-basic-offset} will need to be changed. However, some +styles require a more advanced ability for customization, and one of the +real strengths of VHDL Mode is that the syntactic analysis model +provides a very flexible framework for customizing indentation. This +allows you to perform special indentation calculations for situations +not handled by the mode directly. + +@menu +* Custom Indentation Functions:: +* Other Special Indentations:: +@end menu + +@node Custom Indentation Functions +@subsection Custom Indentation Functions +@cindex Custom Indentation Functions + +@cindex custom indentation functions +One of the most common ways to customize VHDL Mode is by writing +@dfn{custom indentation functions} and associating them with specific +syntactic symbols (see @ref{Syntactic Symbols}). VHDL Mode itself +uses custom indentation functions to provide more sophisticated +indentation, for example when lining up selected signal assignments: +@example +@group + +%%% TBD %%% + +@end group +@end example + +In this example, the @code{statement-cont} syntactic symbol has an +offset of @code{+}, and @code{vhdl-basic-offset} is 2, so lines 4 +through 6 are simply indented two spaces to the right of line 3. But +perhaps we'd like VHDL Mode to be a little more intelligent so +that it offsets the waveform descriptions relative to the signal +assignment operator in line 3. To do this, we have to write a custom +indentation function which finds the column of signal assignment +operator on the first line of the statement. Here is the lisp code +(from the @file{vhdl-mode.el} source file) that implements this: +@example +@group + +(defun vhdl-lineup-statement-cont (langelem) + ;; line up statement-cont after the assignment operator + (save-excursion + (let* ((relpos (cdr langelem)) + (assignp (save-excursion + (goto-char (vhdl-point 'boi)) + (and (re-search-forward "\\(<\\|:\\)=" + (vhdl-point 'eol) t) + (- (point) (vhdl-point 'boi))))) + (curcol (progn + (goto-char relpos) + (current-column))) + foundp) + (while (and (not foundp) + (< (point) (vhdl-point 'eol))) + (re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move) + (if (vhdl-in-literal (cdr langelem)) + (forward-char) + (if (= (preceding-char) ?\() + ;; skip over any parenthesized expressions + (goto-char (min (vhdl-point 'eol) + (scan-lists (point) 1 1))) + ;; found an assignment operator (not at eol) + (setq foundp (not (looking-at "\\s-*$")))))) + (if (not foundp) + ;; there's no assignment operator on the line + vhdl-basic-offset + ;; calculate indentation column after assign and ws, unless + ;; our line contains an assignment operator + (if (not assignp) + (progn + (forward-char) + (skip-chars-forward " \t") + (setq assignp 0))) + (- (current-column) assignp curcol)) + ))) + +@end group +@end example +@noindent +Custom indent functions take a single argument, which is a syntactic +component cons cell (see @ref{Syntactic Analysis}). The +function returns an integer offset value that will be added to the +running total indentation for the lne. Note that what actually gets +returned is the difference between the column that the signal assignment +operator is on, and the column of the buffer relative position passed in +the function's argument. Remember that VHDL Mode automatically +adds in the column of the component's relative buffer position and we +don't want that value added into the final total twice. + +@cindex statement-cont syntactic symbol +@findex vhdl-lineup-statement-cont +@findex lineup-statement-cont (vhdl-) +Now, to associate the function @code{vhdl-lineup-statement-cont} with the +@code{statement-cont} syntactic symbol, we can add something like the +following to our @code{vhdl-mode-hook}: +@example + +(vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont) + +@end example + +@findex vhdl-indent-defun +Now the function looks like this after re-indenting (using @kbd{M-x +vhdl-indent-defun}): +@example +@group + +%%% TBD %%% + +@end group +@end example + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +Custom indentation functions can be as simple or as complex as you like, +and any syntactic symbol that appears in @code{vhdl-offsets-alist} can have +a custom indentation function associated with it. Note however that +using many custom indentation functions may have a performance impact on +VHDL Mode. + +@node Other Special Indentations +@subsection Other Special Indentations +@cindex Other Special Indentations + +@vindex vhdl-special-indent-hook +@vindex special-indent-hook (vhdl-) +One other variable is available for you to customize VHDL Mode: +@code{vhdl-special-indent-hook}. This is a standard hook variable that +is called after every line is indented by VHDL Mode. You can use +it to do any special indentation or line adjustments your style +dictates, such as adding extra indentation to the port map clause in a +component instantiation, etc. Note however, that you should not change +@code{point} or @code{mark} inside your @code{vhdl-special-indent-hook} +functions. + + +@node Syntactic Symbols +@chapter Syntactic Symbols +@cindex Syntactic Symbols + +@vindex vhdl-offsets-alist +The complete list of recognized syntactic symbols is described in the +@code{vhdl-offsets-alist} variable. This chapter will provide some +examples to help clarify these symbols. + +@cindex -open syntactic symbols +@cindex -close syntactic symbols +Most syntactic symbol names follow a general naming convention. When a +line begins with a @code{begin} or @code{end} keyword, the syntactic +symbol will contain the suffix @code{-open} or @code{-close} +respectively. + +@cindex -intro syntactic symbols +@cindex -cont syntactic symbols +@cindex -block-intro syntactic symbols +Usually, a distinction is made between the first line that introduces a +construct and lines that continue a construct, and the syntactic symbols +that represent these lines will contain the suffix @code{-intro} or +@code{-cont} respectively. As a sub-classification of this scheme, a +line which is the first of a particular block construct will contain the +suffix @code{-block-intro}. + +@strong{<TBD> include the name and a brief example of every syntactic +symbol currently recognized} + +@node Frequently Asked Questions +@chapter Frequently Asked Questions +@cindex Frequently Asked Questions + +@kindex C-x h +@kindex ESC C-\ +@kindex ESC C-q +@kindex ESC C-u +@kindex RET +@kindex LFD +@findex newline-and-indent +@quotation + +@strong{Q.} @emph{How do I re-indent the whole file?} + +@strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole +buffer. Then hit @kbd{@key{ESC} C-\} to re-indent the entire region +which you've just marked. Or just enter @kbd{M-x vhdl-indent-buffer}. +@sp 2 + +@strong{Q.} @emph{How do I re-indent the entire function?} + +@strong{A.} Hit @kbd{@key{ESC} C-h} to mark the entire function. Then +hit @kbd{@key{ESC} C-\} to re-indent the entire region which you've just +marked. +@sp 2 + +@strong{Q.} @emph{How do I re-indent the current block?} + +@strong{A.} First move to the brace which opens the block with +@kbd{@key{ESC} C-u}, then re-indent that expression with +@kbd{@key{ESC} C-q}. +@sp 2 + +@strong{Q.} @emph{How do I re-indent the current statement?} + +@strong{A.} First move to the beginning of the statement with +@kbd{@key{ESC} a}, then re-indent that expression with @kbd{@key{ESC} +C-q}. +@sp 2 + +@strong{Q.} @emph{I put @code{(vhdl-set-offset 'statement-cont 0)} +in my @file{.emacs} file but I get an error saying that +@code{vhdl-set-offset}'s function definition is void.} + +@strong{A.} This means that VHDL Mode wasn't loaded into your +Emacs session by the time the @code{vhdl-set-offset} call was reached, +mostly likely because VHDL Mode is being autoloaded. Instead +of putting the @code{vhdl-set-offset} line in your top-level +@file{.emacs} file, put it in your @code{vhdl-mode-hook}, or +simply add the following to the top of your @file{.emacs} file: +@example + +(require 'vhdl-mode) + +@end example + +See the sample @file{.emacs} file @ref{Sample .emacs File} for +details. + +@end quotation + + +@node Getting the latest VHDL Mode release +@chapter Getting the latest VHDL Mode release +@cindex Getting the latest VHDL Mode release + +The best way to be sure you always have the latest VHDL Mode release +is to join the @code{vhdl-mode-announce} mailing list. If you are a +brave soul, and wish to participate in beta testing of new releases of +VHDL Mode, you may also join the @code{vhdl-mode-victims} mailing +list. Send email to the maintainer @email{reto@@gnu.org} to join +either of these lists. + +The official Emacs VHDL Mode Home Page can be found at +@uref{http://www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html}. + +@node Sample .emacs File +@chapter Sample @file{.emacs} file +@cindex Sample @file{.emacs} file + +Most customizations can be done using the ``Customize'' entry in the +VHDL Mode menu, which requires no editing of the .emacs file. +If you want to customize indentation, here you go: + +@example +;; Here's a sample .emacs file that might help you along the way. Just +;; copy this region and paste it into your .emacs file. You may want to +;; change some of the actual values. + +(defconst my-vhdl-style + '((vhdl-tab-always-indent . t) + (vhdl-comment-only-line-offset . 4) + (vhdl-offsets-alist . ((arglist-close . vhdl-lineup-arglist) + (statement-cont . 0) + (case-alternative . 4) + (block-open . 0))) + (vhdl-echo-syntactic-information-p . t) + ) + "My VHDL Programming Style") + +;; Customizations for vhdl-mode +(defun my-vhdl-mode-hook () + ;; add my personal style and set it for the current buffer + (vhdl-add-style "PERSONAL" my-vhdl-style t) + ;; offset customizations not in my-vhdl-style + (vhdl-set-offset 'statement-case-intro '++) + ;; other customizations + (setq tab-width 8 + ;; this will make sure spaces are used instead of tabs + indent-tabs-mode nil) + ;; keybindings for VHDL are put in vhdl-mode-map + (define-key vhdl-mode-map "\C-m" 'newline-and-indent) + ) + +(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) +@end example + +@node Limitations and Known Bugs +@chapter Limitations and Known Bugs +@cindex Limitations and Known Bugs + +@itemize @bullet +@item +Re-indenting large regions or expressions can be slow. + +@ignore +@item +The index menu does not work on my XEmacs installation (don't know why). +@end ignore + +@end itemize + +@node Mailing Lists and Submitting Bug Reports +@chapter Mailing Lists and Submitting Bug Reports +@cindex Mailing Lists and Submitting Bug Reports + +@kindex C-c C-b +@findex vhdl-submit-bug-report +@findex submit-bug-report (vhdl-) +@cindex beta testers mailing list +@cindex announcement mailing list +To report bugs, use the @kbd{C-c C-b} (@code{vhdl-submit-bug-report}) +command. This provides vital information I need to reproduce your +problem. Make sure you include a concise, but complete code example. +Please try to boil your example down to just the essential code needed +to reproduce the problem, and include an exact recipe of steps needed to +expose the bug. Be especially sure to include any code that appears +@emph{before} your bug example. + +For other help or suggestions, send a message to @email{reto@@gnu.org}. + +Send an add message to @email{reto@@gnu.org} to get on the +@code{vhdl-mode-victims} beta testers list where beta releases of +VHDL Mode are posted. Note that you shouldn't expect beta +releases to be as stable as public releases. + +There is also an announce only list where the latest public releases +of VHDL Mode are posted. Send an add message to +@email{reto@@gnu.org} to be added to this list. + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include doclicense.texi + + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + + +@node Command Index +@unnumbered Command Index + +Since all VHDL Mode commands are prepended with the string +@samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its +@code{<thing> (vhdl-)} name. +@iftex +@sp 2 +@end iftex +@printindex fn + + +@node Key Index +@unnumbered Key Index + +@printindex ky + + +@node Variable Index +@unnumbered Variable Index + +Since all VHDL Mode variables are prepended with the string +@samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its +@code{<thing> (vhdl-)} name. +@iftex +@sp 2 +@end iftex +@printindex vr + +@bye diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi index 7c998b37010..4680a098f06 100644 --- a/doc/misc/vip.texi +++ b/doc/misc/vip.texi @@ -1,15 +1,16 @@ \input texinfo -@setfilename ../../info/vip +@setfilename ../../info/vip.info @settitle VIP +@include docstyle.texi @copying -Copyright @copyright{} 1987, 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1987, 2001--2015 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'', +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''. @@ -36,7 +37,7 @@ modify this GNU manual.'' @dircategory Emacs misc features @direntry -* VIP: (vip). An older VI-emulation for Emacs. +* VIP: (vip). An obsolete VI-emulation for Emacs. @end direntry @ifnottex @@ -51,12 +52,15 @@ are fairly accustomed to Vi but not so much with Emacs. Also we will concentrate mainly on differences from Vi, especially features unique to VIP. +VIP is obsolete since Emacs 24.5---consider using Viper instead. +@xref{Top, Viper,, viper, The Viper VI-emulation mode for Emacs}. + It is recommended that you read nodes on survey and on customization before you start using VIP@. Other nodes may be visited as needed. Comments and bug reports are welcome. Please send messages to @code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to -@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan.@refill +@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan. @insertcopying @@ -81,6 +85,9 @@ fairly accustomed to Vi but not so much with Emacs. Also we will concentrate mainly on differences from Vi, especially features unique to VIP. +VIP is obsolete since Emacs 24.5---consider using Viper instead. +@xref{Top, Viper,, viper, The Viper VI-emulation mode for Emacs}. + It is recommended that you read chapters on survey and on customization before you start using VIP@. Other chapters may be used as future references. @@ -128,14 +135,13 @@ the character; otherwise we say that point is @dfn{at the end of buffer}. @key{PNT} and @key{MRK} are used to indicate positions in a buffer and they are not part of the text of the buffer. If a buffer contains a @key{MRK} then the text between @key{MRK} -and @key{PNT} is called the @dfn{region} of the buffer.@refill +and @key{PNT} is called the @dfn{region} of the buffer. @cindex window Emacs provides (multiple) @dfn{windows} on the screen, and you can see the content of a buffer through the window associated with the buffer. The cursor of the screen is always positioned on the character after @key{PNT}. -@refill @cindex mode @cindex keymap @@ -149,7 +155,7 @@ buffers. Each buffer has its @dfn{local keymap} that determines the a function is bound to some key in the local keymap then that function will be executed when you type the key. If no function is bound to a key in the local map, however, the function bound to the key in the global map becomes -in effect.@refill +in effect. @node Loading VIP @section Loading VIP @@ -164,7 +170,7 @@ directory and it will be executed every time you invoke Emacs. If you wish to be in vi mode whenever Emacs starts up, you can include the following line in your @file{.emacs} file instead of the above line: @example -(setq term-setup-hook 'vip-mode) +(add-hook 'emacs-startup-hook 'vip-mode) @end example @noindent (@xref{Vi Mode}, for the explanation of vi mode.) @@ -187,7 +193,7 @@ Loading VIP has the effect of globally binding @kbd{C-z} (@kbd{Control-z}) to the function @code{vip-change-mode-to-vi}. The default binding of @kbd{C-z} in GNU Emacs is @code{suspend-emacs}, but, you can also call @code{suspend-emacs} by typing @kbd{C-x C-z}. Other than this, all the -key bindings of Emacs remain the same after loading VIP.@refill +key bindings of Emacs remain the same after loading VIP. @cindex vi mode @@ -198,12 +204,12 @@ called and you will be in @dfn{vi mode}. (Some major modes may locally bind invoked by @kbd{M-x}. Here @kbd{M-x} means @kbd{Meta-x}, and if your terminal does not have a @key{META} key you can enter it by typing @kbd{@key{ESC} x}. The same effect can also be achieve by typing -@kbd{M-x vip-mode}.)@refill +@kbd{M-x vip-mode}.) @cindex mode line You can observe the change of mode by looking at the @dfn{mode line}. For -instance, if the mode line is:@refill +instance, if the mode line is: @example -----Emacs: *scratch* (Lisp Interaction)----All------------ @end example @@ -219,7 +225,7 @@ Thus the word @samp{Emacs} in the mode line will change to @samp{Vi}. @cindex emacs mode You can go back to the original @dfn{emacs mode} by typing @kbd{C-z} in -vi mode. Thus @kbd{C-z} toggles between these two modes.@refill +vi mode. Thus @kbd{C-z} toggles between these two modes. Note that modes in VIP exist orthogonally to modes in Emacs. This means that you can be in vi mode and at the same time, say, shell mode. @@ -265,7 +271,7 @@ emacs mode vi mode insert mode You will be in this mode just after you loaded VIP@. You can do all normal Emacs editing in this mode. Note that the key @kbd{C-z} is globally bound to @code{vip-change-mode-to-vi}. So, if you type @kbd{C-z} in this mode -then you will be in vi mode.@refill +then you will be in vi mode. @node Vi Mode @subsection Vi Mode @@ -332,7 +338,7 @@ The major differences from Vi are explained below. You can repeat undoing by the @kbd{.} key. So, @kbd{u} will undo a single change, while @kbd{u .@: .@: .@:}, for instance, will undo 4 previous changes. Undo is undoable as in Vi. So the content of the buffer will -be the same before and after @kbd{u u}.@refill +be the same before and after @kbd{u u}. @node Changing @subsection Changing @@ -345,7 +351,7 @@ then VIP will prompt you for a new word in the minibuffer by the prompt @key{ESC} to complete the command. Before you enter @key{RET} or @key{ESC} you can abort the command by typing @kbd{C-g}. In general, @kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -you can abort a partially formed command by typing @kbd{C-g}.@refill +you can abort a partially formed command by typing @kbd{C-g}. @node Searching @subsection Searching @@ -361,7 +367,7 @@ A search for empty string will toggle the search mode between vanilla search and regular expression search. You cannot give an offset to the search string. (It is a limitation.) By default, search will wrap around the buffer as in Vi. You can change this by rebinding the variable -@code{vip-search-wrap-around}. @xref{Customization}, for how to do this.@refill +@code{vip-search-wrap-around}. @xref{Customization}, for how to do this. @node z Command @subsection z Command @@ -376,7 +382,7 @@ the buffer as in Vi. You can change this by rebinding the variable For those of you who cannot remember which of @kbd{z} followed by @key{RET}, @kbd{.}@: and @kbd{-} do what. You can also use @kbd{z} followed by @kbd{H}, @kbd{M} and @kbd{L} to place the current line in the Home (Middle, and -Last) line of the window.@refill +Last) line of the window. @node Counts @subsection Counts @@ -429,14 +435,14 @@ Jump to mark (and pop mark off the mark ring). @cindex region -Vi operators like @kbd{d}, @kbd{c} etc. are usually used in combination +Vi operators like @kbd{d}, @kbd{c} etc.@: are usually used in combination with motion commands. It is now possible to use current region as the argument to these operators. (A @dfn{region} is a part of buffer delimited by point and mark.) The key @kbd{r} is used for this purpose. Thus @kbd{d r} will delete the current region. If @kbd{R} is used instead of @kbd{r} the region will first be enlarged so that it will become the smallest region containing the original region and consisting of whole -lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}.@refill +lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}. @node New Commands @subsection Some New Commands @@ -478,7 +484,7 @@ can execute a single Emacs command. After executing the Emacs command you will be in vi mode again. You can give a count before typing @kbd{\}. Thus @kbd{5 \ *}, as well as @kbd{\ C-u 5 *}, will insert @samp{*****} before point. Similarly @kbd{1 0 \ C-p} will move the point 10 lines above -the current line.@refill +the current line. @item K @kindex 113 @kbd{K} (@code{vip-kill-buffer}) Kill current buffer if it is not modified. Useful when you selected a @@ -504,7 +510,7 @@ similar, but will use window different from the current window. If followed by a certain character @var{ch}, it becomes an operator whose argument is the region determined by the motion command that follows. Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q} and -@kbd{s}.@refill +@kbd{s}. @item # c @kindex 0432 @kbd{# c} (@code{downcase-region}) Change upper-case characters in the region to lower case @@ -517,7 +523,7 @@ Change lower-case characters in the region to upper case. For instance, @item # g @kindex 0432 @kbd{# g} (@code{vip-global-execute}) Execute last keyboard macro for each line in the region -(@code{vip-global-execute}).@refill +(@code{vip-global-execute}). @item # q @kindex 0432 @kbd{# q} (@code{vip-quote-region}) Insert specified string at the beginning of each line in the region @@ -568,7 +574,7 @@ in the current window, while @kbd{S} selects buffer in another window. @kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) These keys will exit from vi mode and return to emacs mode temporarily. If you type @kbd{C} (@kbd{X}), Emacs will be in emacs mode and will believe -that you have typed @kbd{C-c} (@kbd{C-x}, resp.) in emacs mode. Moreover, +that you have typed @kbd{C-c} (@kbd{C-x}) in emacs mode. Moreover, if the following character you type is an upper-case letter, then Emacs will believe that you have typed the corresponding control character. You will be in vi mode again after the command is executed. For example, @@ -577,7 +583,7 @@ mode. You get the same effect by typing @kbd{C-x C-s} in vi mode, but the idea here is that you can execute useful Emacs commands without typing control characters. For example, if you hit @kbd{X} (or @kbd{C-x}) followed by @kbd{2}, then the current window will be split into 2 and you will be in -vi mode again.@refill +vi mode again. @end table In addition to these, @code{ctl-x-map} is slightly modified: @@ -723,7 +729,7 @@ Most Vi commands accept a @dfn{numeric argument} which can be supplied as a prefix to the commands. A numeric argument is also called a @dfn{count}. In many cases, if a count is given, the command is executed that many times. For instance, @kbd{5 d d} deletes 5 lines while simple @kbd{d d} deletes a -line. In this manual the metavariable @var{n} will denote a count.@refill +line. In this manual the metavariable @var{n} will denote a count. @node Important Keys @section Important Keys @@ -742,7 +748,7 @@ Clear the screen and reprint everything (@code{recenter}). In Emacs many commands are bound to the key strokes that start with @kbd{C-x}, @kbd{C-c} and @key{ESC}. These commands can be -accessed from vi mode as easily as from emacs mode.@refill +accessed from vi mode as easily as from emacs mode. @table @kbd @item C-x @@ -772,7 +778,7 @@ Escape to emacs mode. Hitting the @kbd{\} key will take you to emacs mode, and you can execute a single Emacs command. After executing the Emacs command you will be in vi mode again. You can give a count before typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert -@samp{+++++} before point.@refill +@samp{+++++} before point. @end table @node Buffers and Windows @@ -784,7 +790,7 @@ typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert In Emacs the text you edit is stored in a @dfn{buffer}. See GNU Emacs Manual, for details. There is always one @dfn{current} -buffer, also called the @dfn{selected buffer}.@refill +buffer, also called the @dfn{selected buffer}. @cindex window @cindex modified (buffer) @@ -883,7 +889,7 @@ file in the current window, you can just type @kbd{v}. Emacs maintains the @dfn{default directory} which is specific to each buffer. Suppose, for instance, that the default directory of the current buffer is @file{/usr/masahiko/lisp/}. Then you will get the following prompt in the -minibuffer.@refill +minibuffer. @example visit file: /usr/masahiko/lisp/ @end example @@ -894,9 +900,9 @@ just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el} already exists in the directory, Emacs will visit that file, and if not, the file will be created. Emacs will use the file name (@file{vip.el}, in this case) as the name of the buffer visiting the file. In order to make -the buffer name unique, Emacs may append @samp{<2>}, @samp{<3>} etc., to -the buffer name. As the @dfn{file name completion} is provided here, you -can sometime save typing. For instance, suppose there is only one file in the +the buffer name unique, Emacs may add a suffix (@pxref{Uniquify,,, +emacs, The GNU Emacs Manual}). As @dfn{file name completion} is provided here, you +can sometimes save typing. For instance, suppose there is only one file in the default directory whose name starts with @samp{v}, that is @samp{vip.el}. Then if you just type @kbd{v @key{TAB}} then it will be completed to @samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB} @@ -911,7 +917,7 @@ window. You can verify which file you are editing by typing @kbd{g}. (You can also type @kbd{X B} to get information on other buffers too.) If you type -@kbd{g} you will get an information like below in the echo area:@refill +@kbd{g} you will get an information like below in the echo area: @example "/usr/masahiko/man/vip.texinfo" line 921 of 1949 @end example @@ -921,7 +927,7 @@ you may wish to save it in a file. If you wish to save it in the file associated with the buffer (@file{/usr/masahiko/man/vip.texinfo}, in this case), you can just say @kbd{X S}. If you wish to save it in another file, you can type @kbd{X W}. You will then get a similar prompt as you get for -@kbd{v}, to which you can enter the file name.@refill +@kbd{v}, to which you can enter the file name. @node Viewing the Buffer @section Viewing the Buffer @@ -1016,14 +1022,14 @@ Jump to mark (and pop mark off the mark ring). Emacs uses the @dfn{mark ring} to store marked positions. The commands @kbd{m <}, @kbd{m >} and @kbd{m .}@: not only set mark but also add it as the latest element of the mark ring (replacing the oldest one). By repeating -the command `@kbd{m ,}' you can visit older and older marked positions. You +the command @kbd{m ,} you can visit older and older marked positions. You will eventually be in a loop as the mark ring is a ring. @node Motion Commands @section Motion Commands Commands for moving around in the current buffer are collected here. These -commands are used as an `argument' for the delete, change and yank commands +commands are used as an ``argument'' for the delete, change and yank commands to be described in the next section. @table @kbd @@ -1106,7 +1112,7 @@ considered as a sequence of non-white characters (@code{vip-end-of-Word}). @end table @noindent @cindex syntax table -Here the meaning of the word `word' for the @kbd{w}, @kbd{b} and @kbd{e} +Here the meaning of the word ``word'' for the @kbd{w}, @kbd{b} and @kbd{e} commands is determined by the @dfn{syntax table} effective in the current buffer. Each major mode has its syntax mode, and therefore the meaning of a word also changes as the major mode changes. See GNU Emacs Manual for @@ -1373,7 +1379,7 @@ Delete a character before point. Given @var{n}, delete @var{n} characters @cindex yank Yank commands @dfn{yank} a text of buffer into a (usually anonymous) register. -Here the word `yank' is used in Vi's sense. Thus yank commands do not +Here the word ``yank'' is used in Vi's sense. Thus yank commands do not alter the content of the buffer, and useful only in combination with commands that put back the yanked text into the buffer. @@ -1453,7 +1459,7 @@ For example, if point is at the beginning of a word @samp{foo} and you wish to change it to @samp{bar}, you can type @kbd{c w}. Then, as @kbd{w} is a point command, you will get the prompt @samp{foo =>} in the minibuffer, for which you can type @kbd{b a r @key{RET}} to complete the change -command.@refill +command. @table @kbd @item c c @@ -1554,7 +1560,7 @@ assigned to a function that just beeps (@code{vip-nil}). @end example VIP uses a special local keymap to interpret key strokes you enter in vi -mode. The following keys are bound to @var{nil} in the keymap. Therefore, +mode. The following keys are bound to @code{nil} in the keymap. Therefore, these keys are interpreted by the global keymap of Emacs. We give below a short description of the functions bound to these keys in the global keymap. See GNU Emacs Manual for details. @@ -1567,8 +1573,8 @@ Set mark and push previous mark on mark ring (@code{set-mark-command}). @kindex 011 TAB (@code{indent-for-tab-command}) Indent line for current major mode (@code{indent-for-tab-command}). @item C-j -@kindex 012 @kbd{C-j} (@code{newline-and-indent}) -Insert a newline, then indent according to mode (@code{newline-and-indent}). +@kindex 012 @kbd{C-j} (@code{electric-newline-and-maybe-indent}) +Insert a newline, and maybe indent according to mode. @item C-k @kindex 013 @kbd{C-k} (@code{kill-line}) Kill the rest of the current line; before a newline, kill the newline. @@ -1862,7 +1868,7 @@ The following Ex commands are available in Vi, but not implemented in VIP. @node Customization @chapter Customization -If you have a file called @file{.vip} in your home directory, then it +If you have a file called @file{~/.emacs.d/vip} (or @file{~/.vip}), then it will also be loaded when VIP is loaded. This file is thus useful for customizing VIP. @@ -1902,7 +1908,7 @@ if @code{nil} then it sis bound to @code{delete-backward-char}. @end table @noindent You can reset these constants in VIP by the Ex command @kbd{set}. Or you -can include a line like this in your @file{.vip} file: +can include a line like this in your @file{~/.emacs.d/vip} file: @example (setq vip-case-fold-search t) @end example @@ -1915,8 +1921,8 @@ can include a line like this in your @file{.vip} file: VIP uses @code{vip-command-mode-map} as the @dfn{local keymap} for vi mode. For example, in vi mode, @key{SPC} is bound to the function @code{vip-scroll}. But, if you wish to make @key{SPC} and some other keys - behave like Vi, you can include the following lines in your @file{.vip} -file. + behave like Vi, you can include the following lines in your +@file{~/.emacs.d/vip} file. @example (define-key vip-command-mode-map "\C-g" 'vip-info-on-file) diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 8b4c9e93f7c..8f57e8c6bbe 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -4,16 +4,17 @@ @comment Using viper.info instead of viper in setfilename breaks DOS. @comment @setfilename viper @comment @setfilename viper.info -@setfilename ../../info/viper +@setfilename ../../info/viper.info +@include docstyle.texi @copying -Copyright @copyright{} 1995--1997, 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1995--1997, 2001--2015 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'', +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''. @@ -88,7 +89,7 @@ be visited as needed. Comments and bug reports are welcome. @code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose.@refill +Please use the Ex command @kbd{:submitReport} for this purpose. @insertcopying @end ifnottex @@ -147,7 +148,7 @@ comes with Emacs. This manual can be read as an Info file. Try the command Comments and bug reports are welcome. @code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose.@refill +Please use the Ex command @kbd{:submitReport} for this purpose. @end iftex @@ -168,8 +169,8 @@ world of Vi! These users are well familiar with Emacs bindings and prefer them in some cases, especially in the Vi Insert state. John Hawkins <jshawkin@@eecs.umich.edu> has provided a set of customizations, which enables additional Emacs bindings under Viper. These customizations can be -included in your @file{~/.viper} file and are found at the following URL: -@file{http://traeki.freeshell.org/files/viper-sample}. +included in your @file{~/.emacs.d/viper} file and are found at the +following URL: @file{http://traeki.freeshell.org/files/viper-sample}. @menu * Emacs Preliminaries:: Basic concepts in Emacs. @@ -197,21 +198,21 @@ Emacs can edit several files at once. A file in Emacs is placed in a @dfn{buffer} that usually has the same name as the file. Buffers are also used for other purposes, such as shell interfaces, directory editing, etc. @xref{Dired,,Directory Editor,emacs,The -GNU Emacs Manual}, for an example.@refill +GNU Emacs Manual}, for an example. A buffer has a distinguished position called the @dfn{point}. A @dfn{point} is always between 2 characters, and is @dfn{looking at} the right hand character. The cursor is positioned on the right hand character. Thus, when the @dfn{point} is looking at the end-of-line, the cursor is on the end-of-line character, i.e., beyond the last -character on the line. This is the default Emacs behavior.@refill +character on the line. This is the default Emacs behavior. The default settings of Viper try to mimic the behavior of Vi, preventing the cursor from going beyond the last character on the line. By using Emacs commands directly (such as those bound to arrow keys), it is possible to get the cursor beyond the end-of-line. However, this won't (or shouldn't) happen if you restrict yourself to standard Vi keys, unless you -modify the default editing style. @xref{Customization}.@refill +modify the default editing style. @xref{Customization}. In addition to the @dfn{point}, there is another distinguished buffer position called the @dfn{mark}. @xref{Mark,,Mark,emacs,The GNU Emacs @@ -232,7 +233,7 @@ assuming that the current region starts at line 123 and ends at line 135. There is no need to type the line numbers, since Viper inserts them automatically in front of the Ex command. -@xref{Basics}, for more info.@refill +@xref{Basics}, for more info. @cindex window @cindex mode line @@ -255,7 +256,7 @@ show the buffer name and current major and minor modes (see below). A special buffer called @dfn{Minibuffer} is displayed as the last line in a minibuffer window. The minibuffer window is used for command input output. Viper uses minibuffer window for @kbd{/} and @kbd{:} -commands.@refill +commands. @cindex mode @cindex keymap @@ -275,7 +276,7 @@ keymap then that function will be executed when you type the key. If no function is bound to a key in the local map, however, the function bound to the key in the global map will be executed. @xref{Major Modes,Major Modes,Major Modes,emacs,The -GNU Emacs Manual}, for more information.@refill +GNU Emacs Manual}, for more information. A buffer can also have a @dfn{minor mode}. Minor modes are options that you can use or not. A buffer in @code{text-mode} can have @@ -283,7 +284,7 @@ you can use or not. A buffer in @code{text-mode} can have any time. In Emacs, a minor mode may have it own keymap, which overrides the local keymap when the minor mode is turned on. For more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The -GNU Emacs Manual} @refill +GNU Emacs Manual}. @cindex Viper as minor mode @cindex Control keys @@ -293,7 +294,7 @@ Viper is implemented as a collection of minor modes. Different minor modes are involved when Viper emulates Vi command mode, Vi insert mode, etc. You can also turn Viper on and off at any time while in Vi command mode. @xref{States in Viper}, for -more information.@refill +more information. Emacs uses Control and Meta modifiers. These are denoted as C and M, e.g., @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}. The Meta key is @@ -303,7 +304,7 @@ holding the Meta key down. For keyboards that do not have a Meta key, @key{ESC} is used as Meta. Thus @kbd{M-x} is typed as @kbd{@key{ESC} x}. Viper uses @key{ESC} to switch from Insert state to Vi state. Therefore Viper defines @kbd{C-\} as its Meta key in Vi state. @xref{Vi State}, for -more info.@refill +more info. Emacs is structured as a Lisp interpreter around a C core. Emacs keys cause Lisp functions to be called. It is possible to call these @@ -327,14 +328,14 @@ the place where all general Emacs customization takes place. Beginning with version 20.0, Emacsen have an interactive interface, which simplifies the job of customization significantly. -Viper also uses the file @file{~/.viper} for Viper-specific customization. +Viper also uses the file @file{~/.emacs.d/viper} for Viper-specific customization. The location of Viper customization file can be changed by setting the variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading Viper. The latest versions of Emacs have an interactive customization facility, which allows you to (mostly) bypass the use of the @file{.emacs} and -@file{.viper} files. You can reach this customization +@code{viper-custom-file-name} files. You can reach this customization facility from within Viper's VI state by executing the Ex command @kbd{:customize}. @@ -352,12 +353,12 @@ M-x viper-mode @end lisp When Emacs first comes up, if you have not specified a file on the -command line, it will show the @samp{*scratch*} buffer, in the +command line, it will show the @file{*scratch*} buffer, in the @samp{Lisp Interaction} mode. After you invoke Viper, you can start editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands. (@xref{File and Buffer Handling}, for more information on @kbd{v} and other new commands that, in many cases, are more convenient than @kbd{:e}, -@kbd{:vi}, and similar old-style Vi commands.)@refill +@kbd{:vi}, and similar old-style Vi commands.) Finally, if at some point you would want to de-Viperize your running copy of Emacs after Viper has been loaded, the command @kbd{M-x @@ -386,7 +387,7 @@ This is the state plain vanilla Emacs is normally in. After you have loaded Viper, @kbd{C-z} will normally take you to Vi command state. Another @kbd{C-z} will take you back to Emacs state. This toggle key can be changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to -change to Vi state.@refill +change to Vi state. For users who chose to set their user level to 1 at Viper setup time, @@ -424,7 +425,7 @@ boundary of a replacement region (usually designated via a @samp{$} sign), it will automatically change to Insert state. You do not have to worry about it. The key bindings remain practically the same as in Insert state. If you type @key{ESC}, Viper will switch to Vi command mode, terminating the -replacement state.@refill +replacement state. @end table @cindex mode line @@ -488,7 +489,7 @@ for editing LaTeX documents, Dired for directory editing, etc. These are major modes, each with a different set of key-bindings. Viper states are orthogonal to these Emacs major modes. The presence of these language sensitive and other modes is a major win over Vi. @xref{Improvements over -Vi}, for more.@refill +Vi}, for more. The bindings for these modes can be made available in the Viper Insert state as well as in Emacs state. Unless you specify your user level as 1 (a @@ -541,7 +542,6 @@ functionality and no key-binding. Recursive edits are indicated by Edit,Recursive Edit,emacs,The GNU Emacs Manual}. At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file} function instead. -@refill @item C-\ @kindex @kbd{C-\} @cindex Meta key @@ -610,8 +610,8 @@ is slightly different from other programs. It is designed to minimize the need for deleting file names that Emacs provides in its prompts. (This is usually convenient, but occasionally the prompt may suggest a wrong file name for you.) If you see a prompt @kbd{/usr/foo/} and you wish to edit the -file @kbd{~/.viper}, you don't have to erase the prompt. Instead, simply -continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.viper} +file @kbd{~/.file}, you don't have to erase the prompt. Instead, simply +continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.file} correctly. Similarly, if the prompt is @kbd{~/foo/} and you need to get to @kbd{/bar/file}, keep typing. Emacs interprets @kbd{~/foo//bar/} as @kbd{/bar/file}, since when it sees @samp{//}, it understands that @@ -652,14 +652,14 @@ In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire command will appear in the history list. This is because having @kbd{:r} alone as a default is meaningless, since this command requires a file argument. -@refill @end table @noindent -As in Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'. +As in Vi, Viper's destructive commands can be re-executed by typing +a period (@kbd{.}). However, in addition, Viper keeps track of the history of such commands. This history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}. Having found the appropriate command, it can be then executed by typing -`@kbd{.}'. +a period. @xref{Improvements over Vi}, for more information. @node Insert State @@ -673,7 +673,7 @@ Emacs major modes cannot be used in Insert state. It is strongly recommended that as soon as you are comfortable, make the Emacs state bindings visible (by changing your user level to 3 or higher). @xref{Customization}, -to see how to do this.@refill +to see how to do this. Once this is done, it is possible to do quite a bit of editing in Insert state. For instance, Emacs has a @dfn{yank} command, @kbd{C-y}, @@ -795,8 +795,8 @@ between the Vi state and Insert state at will, and even use the replace mode. Initially, the minibuffer comes up in Insert state. Some users prefer plain Emacs bindings in the minibuffer. To this end, set -@code{viper-vi-style-in-minibuffer} to @code{nil} in @file{.viper}. -@xref{Customization}, to learn how to do this. +@code{viper-vi-style-in-minibuffer} to @code{nil} in +your Viper customization file. @xref{Customization}, to learn how to do this. When the minibuffer changes Viper states, you will notice that the appearance of the text there changes as well. This is useful because the minibuffer @@ -823,13 +823,13 @@ If you set marker @samp{a} in file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then @emph{YOU WILL SWITCH TO FILE @file{foo}}. You can see the contents of a textmarker using the Viper command @kbd{[<a-z>} where <a-z> are the -textmarkers, e.g., @kbd{[a} to view marker @samp{a} .@refill +textmarkers, e.g., @kbd{[a} to view marker @samp{a} . @item Repeated Commands Command repetitions are common over files. Typing @kbd{!!} will repeat the last @kbd{!} command whichever file it was issued from. Typing @kbd{.} will repeat the last command from any file, and searches will repeat the last search. Ex commands can be repeated by typing -@kbd{: @key{RET}}.@refill +@kbd{: @key{RET}}. Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous. However, usually its effect can be undone by typing @kbd{u}. @item Registers @@ -877,7 +877,8 @@ want to change this. @noindent Currently undisplayed files can be listed using the @kbd{:ar} command. The command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to -other files. For example, use `:n3' to move to the third file in that list. +other files. For example, use @samp{:n3} to move to the third file in +that list. @node Unimplemented Features @section Unimplemented Features @@ -897,7 +898,7 @@ more powerful facilities for defining abbreviations. it is not implemented. A useful alternative is @code{cat -t -e file}. Unfortunately, it cannot be used directly inside Emacs, since Emacs will obdurately change @samp{^I} -back to normal tabs.@refill +back to normal tabs. @end itemize @node Improvements over Vi @@ -928,7 +929,7 @@ The Vi command set is based on the idea of combining motion commands with other commands. The motion command is used as a text region specifier for other commands. We classify motion commands into @dfn{point commands} and -@dfn{line commands}.@refill +@dfn{line commands}. @cindex point commands @@ -989,8 +990,8 @@ In the Overview chapter, some Multiple File issues were discussed (@pxref{Multiple Files in Viper}). In addition to the files, Emacs has buffers. These can be seen in the @kbd{:args} list and switched using @kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or -specify @code{(setq ex-cycle-through-non-files t)} in your @file{.viper} -file. @xref{Customization}, for details. +specify @code{(setq ex-cycle-through-non-files t)} in your +Viper customization file. @xref{Customization}, for details. @node Undo and Backups @section Undo and Backups @@ -1010,7 +1011,7 @@ direction. Since the undo size is limited, Viper can create backup files and auto-save files. It will normally do this automatically. It is possible to have numbered backups, etc. For details, @pxref{Backup,,Backup and -Auto-Save,emacs,The GNU Emacs Manual} @refill +Auto-Save,emacs,The GNU Emacs Manual}. @comment [ balance parens @cindex viewing registers and markers @@ -1083,7 +1084,7 @@ where @samp{register} is any character from @samp{a} through @samp{z}. Then you can execute this macro using @kbd{@@register}. It is, of course, possible to yank some text into a register and execute it using @kbd{@@register}. Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will -execute the last macro that was executed using @kbd{@@register}.@refill +execute the last macro that was executed using @kbd{@@register}. Viper will automatically lowercase the register, so that pressing the @kbd{SHIFT} key for @kbd{@@} will not create problems. This is for @@ -1105,7 +1106,7 @@ The last keyboard macro can also be executed using This is useful for Emacs style keyboard macros defined using @kbd{C-x(} and @kbd{C-x)}. Emacs keyboard macros have more capabilities. @xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for -details.@refill +details. Keyboard Macros allow an interesting form of Query-Replace: @kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a @@ -1132,7 +1133,8 @@ of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as @cindex word search Viper provides buffer search, the ability to search the buffer for a region -under the cursor. You have to turn this on in @file{.viper} either by calling +under the cursor. You have to turn this on in your Viper customization file +either by calling @example (viper-buffer-search-enable) @@ -1161,7 +1163,7 @@ as you go along. Incremental Search is normally bound to @kbd{C-s} and @kbd{C-r}. @xref{Customization}, to find out how to change the bindings of @kbd{C-r or C-s}. For details, @pxref{Incremental Search,,Incremental -Search,emacs,The GNU Emacs Manual} @refill +Search,emacs,The GNU Emacs Manual}. @cindex query replace @@ -1182,10 +1184,10 @@ variable that controls how search patterns are highlighted is @end example @vindex @code{viper-search-face} @noindent -in @file{~/.viper}. If you want to change how patterns are highlighted, you -will have to change @code{viper-search-face} to your liking. The easiest -way to do this is to use Emacs customization widget, which is accessible -from the menubar. Viper customization group is located under the +in your Viper customization file. If you want to change how patterns are +highlighted, you will have to change @code{viper-search-face} to your liking. +The easiest way to do this is to use Emacs customization widget, which is +accessible from the menubar. Viper customization group is located under the @emph{Emulations} customization group, which in turn is under the @emph{Editing} group (or simply by typing @kbd{:customize}). All Viper faces are grouped together under Viper's @@ -1223,10 +1225,10 @@ Facilities like this make Vi's @kbd{:ab} command obsolete. @cindex Ex style motion @cindex line editor motion -Viper can be set free from the line--limited movements in Vi, such as @kbd{l} +Viper can be set free from the line-limited movements in Vi, such as @kbd{l} refusing to move beyond the line, @key{ESC} moving one character back, -etc. These derive from Ex, which is a line editor. If your @file{.viper} -contains +etc. These derive from Ex, which is a line editor. If your +Viper customization file contains @example @code{(setq viper-ex-style-motion nil)} @@ -1306,9 +1308,10 @@ These two keys invoke many important Emacs functions. For example, if you hit @kbd{C-x} followed by @kbd{2}, then the current window will be split into 2. Except for novice users, @kbd{C-c} is also set to execute an Emacs command from the current major mode. @key{ESC} will do the same, if you -configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to @code{nil} -in @file{.viper}. @xref{Customization}. @kbd{C-\} in Insert, Replace, or Vi -states will make Emacs think @kbd{Meta} has been hit.@refill +configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to +@code{nil} in your Viper customization file. @xref{Customization}. +@kbd{C-\} in Insert, Replace, or Vi states will make Emacs think +@kbd{Meta} has been hit. @item \ @kindex @kbd{\} Escape to Emacs to execute a single Emacs command. For instance, @@ -1339,7 +1342,7 @@ argument is the region determined by the motion command that follows (indicated as <move>). Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and @kbd{s}. For instance, @kbd{#qr} will prompt you for a string and then -prepend this string to each line in the buffer.@refill +prepend this string to each line in the buffer. @item # c @kindex @kbd{#c<move>} @cindex changing case @@ -1355,7 +1358,7 @@ Emacs command @kbd{M-u} does the same for words. @item # g @kindex @kbd{#g<move>} Execute last keyboard macro for each line in the region -(@code{viper-global-execute}).@refill +(@code{viper-global-execute}). @item # q @kindex @kbd{#q<move>} Insert specified string at the beginning of each line in the region @@ -1401,7 +1404,7 @@ Go to end of heading. @item g <@emph{movement command}> Search buffer for text delimited by movement command. The canonical example is @kbd{gw} to search for the word under the cursor. -@xref{Improved Search}, for details.@refill +@xref{Improved Search}, for details. @item C-g and C-] @kindex @kbd{C-g} @kindex @kbd{C-]} @@ -1455,18 +1458,18 @@ In Vi state, these commands let the user peruse the history of Vi-style destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc. By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper through the recent history of Vi commands, displaying the commands one by -one. Once -an appropriate command is found, it can be executed by typing `@kbd{.}'. +one. Once an appropriate command is found, it can be executed by +typing a period. Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an appropriate function to a function key on the keyboard and use that key. @xref{Viper Specials}, for details. @item Ex commands -@findex @kbd{:args} -@findex @kbd{:n} -@findex @kbd{:pwd} -@findex @kbd{:pre} +@findex @kbd{Ex args} +@findex @kbd{Ex n} +@findex @kbd{Ex pwd} +@findex @kbd{Ex pre} The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave differently. @kbd{:pwd} exists to get current directory. The commands @kbd{:b} and @kbd{:B} switch buffers around. @xref{File and @@ -1474,8 +1477,8 @@ Buffer Handling}, for details. There are also the new commands @kbd{:RelatedFile} and @kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P}, respectively. @xref{Viper Specials}, for details. -@findex @kbd{:RelatedFile} -@findex @kbd{:PreviousRelatedFile} +@findex @kbd{Ex RelatedFile} +@findex @kbd{Ex PreviousRelatedFile} @end table Apart from the new commands, many old commands have been enhanced. Most @@ -1560,7 +1563,7 @@ patches. @noindent Emacs Lisp archives exist on @samp{archive.cis.ohio-state.edu} -and @samp{wuarchive.wustl.edu}@refill +and @samp{wuarchive.wustl.edu} @node Customization @@ -1574,29 +1577,29 @@ Customization can be done in 2 ways. @item @cindex initialization @cindex .viper -Elisp code in a @file{.viper} file in your home directory. Viper -loads @file{.viper} just before it does the binding for mode -hooks. This is recommended for experts only. +Elisp code in a @file{~/.emacs.d/viper} (or @file{~/.viper}) file. +Viper loads this file just before it does the binding for mode hooks. +This is recommended for experts only. @item @cindex .emacs Elisp code in your @file{.emacs} file before and after the @code{(require 'viper)} line. This method is @emph{not} recommended, unless you know what you are doing. Only two variables, @code{viper-mode} and @code{viper-custom-file-name}, are supposed to be customized in @file{.emacs}, -prior to loading Viper (i.e., prior to @code{(require 'viper)} command.@refill +prior to loading Viper (i.e., prior to @code{(require 'viper)} command. @item -@cindex :customize +@cindex Ex customize By executing the @kbd{:customize} Ex command. This takes you to the Emacs customization widget, which lets you change the values of Viper customizable variables easily. This method is good for novice and experts alike. The customization code in the form of Lisp commands will be placed in @file{~/.emacs} or some other customization file depending on the -version of Emacs that you use. Still, it is recommended to separate +version of Emacs that you use. Still, it is recommended to separate Viper-related customization produced by the Emacs customization widget -and keep it in the @file{.viper} file. +and keep it in your Viper customization file. Some advanced customization cannot be accomplished this way, however, and -has to be done in Emacs Lisp in the @file{.viper} file. For the common +has to be done in Emacs Lisp in your Viper customization file. For the common cases, examples are provided that you can use directly. @end itemize @@ -1614,7 +1617,7 @@ cases, examples are provided that you can use directly. @cindex setting variables @cindex variables for customization -@findex @kbd{:set} +@findex @kbd{Ex set} An easy way to customize Viper is to change the values of constants used in Viper. Here is the list of the constants used in Viper and their default @@ -1624,7 +1627,7 @@ values. The corresponding :se command is also indicated. (The symbols Viper supports both the abbreviated Vi variable names and their full names. Variable completion is done on full names only. @key{TAB} and @key{SPC} complete -variable names. Typing `=' will complete the name and then will prompt for +variable names. Typing @kbd{=} will complete the name and then will prompt for a value, if applicable. For instance, @kbd{:se au @key{SPC}} will complete the command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command and prompt further like this: @kbd{:set tabstop = }. @@ -1753,10 +1756,10 @@ cases. @code{nil} means you either has to invoke @code{viper-mode} manually for each buffer (or you can add @code{viper-mode} to the appropriate major mode hooks using @code{viper-load-hook}). -This option must be set in the file @file{~/.viper}. -@item viper-custom-file-name "~/.viper" +This option must be set in your Viper customization file. +@item viper-custom-file-name "~/.emacs.d/viper" File used for Viper-specific customization. -Change this setting, if you want. Must be set in @file{.emacs} (not @file{.viper}!) +Change this setting, if you want. Must be set in @file{.emacs} before Viper is loaded. Note that you have to set it as a string inside double quotes. @item viper-spell-function 'ispell-region @@ -1798,8 +1801,8 @@ unless you are a novice, as this precludes the use of language-specific features provided by the major modes. @item viper-keep-point-on-repeat t If not @code{nil}, point is not moved when the user repeats the previous -command by typing `.' This is very useful for doing repeated changes with -the @kbd{.} key. +command by typing a period. This is very useful for doing repeated +changes with the @kbd{.} key. @item viper-repeat-from-history-key 'f12 Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat the second-last and the third-last destructive command. @@ -1807,8 +1810,8 @@ Both these macros are bound (as Viper macros) to @code{viper-repeat-from-history}, which checks the second key by which it is invoked to see which of the previous commands to invoke. Viper binds @kbd{f12 1} and @kbd{f12 2} only, -but the user can bind more in @file{~/.viper}. @xref{Vi Macros}, for how to do -this. +but the user can bind more in his/her Viper customization file. +@xref{Vi Macros}, for how to do this. @item viper-keep-point-on-undo nil If not @code{nil}, Viper tries to not move point when undoing commands. Instead, it will briefly move the cursor to the place where change has @@ -1838,7 +1841,7 @@ usually most effective: (set-face-background viper-replace-overlay-face "yellow") @end smallexample For a complete list of colors available to you, evaluate the expression -@code{(x-defined-colors)}. (Type it in the buffer @code{*scratch*} and then +@code{(x-defined-colors)}. (Type it in the buffer @file{*scratch*} and then hit the @kbd{C-j} key. @item viper-replace-overlay-cursor-color "Red" @@ -1873,7 +1876,7 @@ emulate the standard Vi behavior, which supports only intra-line replacement regions (and multi-line replacement regions are deleted). @item viper-toggle-key "\C-z" Specifies the key used to switch from Emacs to Vi and back. -Must be set in @file{.viper}. This variable can't be +Must be set in your Viper customization file. This variable can't be changed interactively after Viper is loaded. In Insert state, this key acts as a temporary escape to Vi state, i.e., it @@ -1906,7 +1909,7 @@ the last chance to do customization before Viper is up and running. @noindent You can reset some of these constants in Viper with the Ex command @kbd{:set} (when so indicated in the table). Or you -can include a line like this in your @file{.viper} file: +can include a line like this in your Viper customization file: @example (setq viper-case-fold-search t) @end example @@ -1958,7 +1961,7 @@ can include a line like this in your @file{.viper} file: Viper lets you define hot keys, i.e., you can associate keyboard keys such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already -exist or that you will write). Each key has a "preferred form" in +exist or that you will write). Each key has a ``preferred form'' in Emacs. For instance, the Up key's preferred form is [up], the Help key's preferred form is [help], and the Undo key has the preferred form [f14]. You can find out the preferred form of a key by typing @kbd{M-x @@ -2018,7 +2021,7 @@ state. If you want to bind a key, say @kbd{C-v}, to the function that scrolls page down and to make @kbd{0} display information on the current buffer, -putting this in @file{.viper} will do the trick in Vi state: +putting this in your Viper customization file will do the trick in Vi state: @example (define-key viper-vi-global-user-map "\C-v" 'scroll-down) @end example @@ -2067,11 +2070,12 @@ keys necessary in that keymap, and put @end example @noindent -in @file{~/.viper}. To do the same in Vi and Insert states, you should use -@code{vi-state} and @code{insert-state}. Changes in Insert state are also -in effect in Replace state. For instance, suppose that the user wants to -use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark -files, etc. The following code in @file{~/.viper} will then do the job: +in your Viper customization file. To do the same in Vi and Insert states, you +should use @code{vi-state} and @code{insert-state}. Changes in Insert state +are also in effect in Replace state. For instance, suppose that the user wants +to use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark +files, etc. The following code in the Viper customization file will then do +the job: @example (setq my-dired-modifier-map (make-sparse-keymap)) @@ -2108,7 +2112,7 @@ bound to, unless these keys are typed in quick succession. So, with macros, one can use the normal keys alongside with the macros. If per-mode modifications are needed, the user can try both ways and see which one is more convenient. -@findex @kbd{:map} +@findex @kbd{Ex map} @xref{Vi Macros}, for details. Note: in major modes that come up in @emph{Emacs state} by default, the @@ -2275,7 +2279,7 @@ can happen only in the beginning, when the minor mode kicks in. Typing several such minor modes and takes care of them, so the above trick is usually not necessary. If you find that some minor mode, e.g., @code{nasty-mode} interferes with Viper, putting the following in -@file{.viper} should fix the problem: +your Viper customization file should fix the problem: @lisp (viper-harness-minor-mode "nasty-mode") @end lisp @@ -2332,8 +2336,8 @@ document. Other features are explained here. @item viper-buffer-search-char nil Enable buffer search. Explicit call to @code{viper-buffer-search-enable} sets @code{viper-buffer-search-char} to @kbd{g}. Alternatively, the user can -set @code{viper-buffer-search-char} in @file{.viper} to a key sequence -to be used for buffer search. There is no need to call +set @code{viper-buffer-search-char} in his/her Viper customization file to a key +sequence to be used for buffer search. There is no need to call @code{viper-buffer-search-enable} in that case. @findex @code{viper-buffer-search-enable} @vindex @code{viper-buffer-search-char} @@ -2356,8 +2360,8 @@ If you hit something other than @kbd{/} after the first @kbd{/} or if the second @kbd{/} doesn't follow quickly enough, then Viper will issue the usual prompt @kbd{/} and will wait for input, as usual in Vi. If you don't like this behavior, you can ``unrecord'' these macros in your -@file{~/.viper} file. For instance, if you don't like the above feature, put -this in @file{~/.viper}: +Viper customization file. For instance, if you don't like the above +feature, put this in the file: @example (viper-set-searchstyle-toggling-macros 'undefine) @end example @@ -2372,23 +2376,24 @@ shown above, and then setting it in the desired major modes as follows: @end example @item Vi-isms in Emacs state -Some people find it useful to use the Vi-style search key, `/', to invoke +Some people find it useful to use the Vi-style search key, @kbd{/}, to invoke search in modes which Viper leaves in emacs-state. These modes are: @code{dired-mode}, @code{mh-folder-mode}, @code{Info-mode}, and @code{Buffer-menu-mode} -(more may be added in the future). So, in the above modes, Viper binds `/' +(more may be added in the future). So, in the above modes, Viper binds @kbd{/} so that it will behave Vi-style. Furthermore, in those major modes, Viper -binds `:' to invoke ex-style commands, like in vi-state. And, as described -above, `//' and `///' get bound to Vi-style macros that toggle +binds @kbd{:} to invoke ex-style commands, like in vi-state. And, as described +above, @kbd{//} and @kbd{///} get bound to Vi-style macros that toggle case-insensitivity and regexp-search. If you don't like these features---which I don't really understand---you -can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in -@code{viper-slash-and-colon-map}, for other modes. +can unbind @kbd{/} and @kbd{:} in @code{viper-dired-modifier-map} (for +Dired) or in @code{viper-slash-and-colon-map}, for other modes. @vindex @code{viper-slash-and-colon-map} @vindex @code{viper-dired-modifier-map} -To unbind the macros `//' and `///' for a major mode where you feel they +To unbind the macros @kbd{//} and @kbd{///} for a major mode where you +feel they are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a non-@code{nil} argument. This can be done either interactively, by supplying a prefix argument, or by placing @@ -2416,16 +2421,17 @@ Change your user level interactively. Viper supports Emacs-style file completion when it prompts the user for a file name. However, in many cases, the same directory may contain files with identical prefix but different suffixes, e.g., prog.c, prog.o, -paper.tex, paper.dvi. In such cases, completion will stop at the `.'. +paper.tex, paper.dvi. In such cases, completion will stop at the period. If the above variable is a list of strings representing suffixes, Viper will try these suffixes in the order listed and will check if the corresponding file exists. -For instance, if completion stopped at `paper.'@: and the user typed -@key{RET}, -then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist. +For instance, if completion stopped at @samp{paper.} and the user +typed @key{RET}, then Viper will check if the files @file{paper.}, +@file{paper.tex}, @file{paper.c}, etc., exist. It will take the first such file. If no file exists, Viper will give a chance -to complete the file name by typing the appropriate suffix. If `paper.'@: was +to complete the file name by typing the appropriate suffix. +If @file{paper.} was the intended file name, hitting return will accept it. To turn this feature off, set the above variable to @code{nil}. @@ -2444,7 +2450,7 @@ the direction of newer insertions. Hitting @kbd{C-c M-p} or @kbd{C-c M-n} in succession will undo the previous insertion from the ring and insert the next item on the ring. If a larger ring size is needed, change the value of the above -variable in the @file{~/.viper} file. +variable in the Viper customization file. Since typing these sequences of keys may be tedious, it is suggested that the user should bind a function key, such as @kbd{f31}, as follows: @@ -2470,9 +2476,9 @@ major modes. Viper keeps track of the recent history of destructive commands, such as @kbd{dw}, @kbd{i}, etc. In Vi state, -the most recent command can be re-executed by hitting `@kbd{.}', as in Vi. +the most recent command can be re-executed by hitting a period, as in Vi. However, repeated typing @kbd{C-c M-p} will cause Viper to show the -previous destructive commands in the minibuffer. Subsequent hitting `@kbd{.}' +previous destructive commands in the minibuffer. Subsequent hitting period will execute the command that was displayed last. The key @kbd{C-c M-n} will cycle through the command history in the opposite direction. @@ -2515,7 +2521,7 @@ putting (copy-face 'default 'viper-minibuffer-insert-face) (copy-face 'default 'viper-minibuffer-emacs-face) @end example -in the @file{~/.viper} file or through the customization widget, as +in their Viper customization file or through the customization widget, as described above. However, in that case, the user will not have any indication of the current Viper state in the minibuffer. (This is important if the user accidentally switches to another Viper state by typing @key{ESC} or @@ -2548,8 +2554,8 @@ be associated with the master file. Then, the new Ex command another, so you can edit them. If a file is not in any Emacs buffer, it will be visited. The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P}) goes through the file list in the opposite direction. -@findex @kbd{:RelatedFile} -@findex @kbd{:PreviousRelatedFile} +@findex @kbd{Ex RelatedFile} +@findex @kbd{Ex PreviousRelatedFile} These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to focus on relevant files only. @@ -2587,20 +2593,21 @@ Note: while loading initially, Viper binds this mouse action only if it is not already bound to something else. If you want to use the mouse-search feature, and the @kbd{Meta-Shift-Mouse-1} mouse action is already bound to something else, you can rebind the mouse-search feature by setting -@code{viper-mouse-search-key} to something else in your @code{~/.viper} -file: +@code{viper-mouse-search-key} to something else in +your Viper customization file: @lisp (setq viper-mouse-search-key '(meta 1)) @end lisp This would bind mouse search to the action invoked by pressing the Meta key and clicking mouse button 1. The allowed values of @code{viper-mouse-search-key} are lists that contain a mouse-button number -(1,2, or 3) and any combination of the words `control', `meta', and -`shift'. +(1,2, or 3) and any combination of the words ``control'', ``meta'', and +``shift''. If the requested mouse action (e.g., (meta 1)) is already taken for other purposes then you have to confirm your intention by placing the following -command in @code{~/.viper} after setting @code{viper-mouse-search-key}: +command in your Viper customization file after setting +@code{viper-mouse-search-key}: @lisp (viper-bind-mouse-search-key 'force) @end lisp @@ -2612,9 +2619,9 @@ The region that is chosen as a pattern to search for is determined as follows. If search is invoked via a single click, Viper chooses the region that lies between the beginning of the ``word'' under the pointer (``word'' is understood in Vi sense) and the end of that word. The only difference -with Vi's words is that in Lisp major modes `-' is considered an +with Vi's words is that in Lisp major modes @samp{-} is considered an alphanumeric symbol. This is done for the convenience of working with Lisp -symbols, which often have an `-' in them. Also, if you click on a +symbols, which often have an @samp{-} in them. Also, if you click on a non-alphanumeric character that is not a word separator (in Vi sense) then this character will also be considered alphanumeric, provided that it is adjacent (from either side) to an alphanumeric character. This useful @@ -2642,13 +2649,13 @@ case of a triple-click, the prefix argument is ignored.) Note: while loading initially, Viper binds this mouse action only if it not already bound to something else. If you want to use this feature and the default mouse action is already bound, you can rebind mouse-insert by -placing this command in @code{~/.viper}: +placing this command in your Viper customization file: @lisp (setq viper-mouse-insert-key '(meta 2)) @end lisp If you want to bind mouse-insert to an action even if this action is already taken for other purposes in Emacs, then you should add this command -to @code{~/.viper}, after setting @code{viper-mouse-insert-key}: +to your Viper customization file, after setting @code{viper-mouse-insert-key}: @lisp (viper-bind-mouse-insert-key 'force) @end lisp @@ -2780,12 +2787,12 @@ macros) lets the user define keyboard macros that ask for confirmation or even prompt the user for input and then continue. To do this, one should type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt). For details, @pxref{Keyboard Macro Query,,Customization,emacs,The GNU Emacs -Manual} @refill +Manual}. When the user finishes defining a macro (which is done by typing @kbd{C-x)}, a departure from Vi), you will be asked whether you want this macro to be global, mode-specific, or buffer-specific. You will also be -given a chance to save the macro in your @file{~/.viper} file. +given a chance to save the macro in your Viper customization file. This is the easiest way to save a macro and make it permanently available. If you work your startup files with bare hands, here is how Viper saves the above macro so that it will be @@ -2834,8 +2841,8 @@ the latter says that the macro is to be defined for all buffers For convenience, Viper also lets you define Vi-style macros in its Emacs state. There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing -this, but the user can include such a macro in the @file{~/.viper} file. The -only thing is that the @code{viper-record-kbd-macro} command should specify +this, but the user can include such a macro in the Viper customization file. +The only thing is that the @code{viper-record-kbd-macro} command should specify @code{emacs-state} instead of @code{vi-state} or @code{insert-state}. The user can get rid of a macro either by using the Ex commands @kbd{:unmap} @@ -2899,8 +2906,9 @@ Vi and Emacs commands, so that you could see what will happen each time the macro is executed. Suppose now we wanted to bind the key sequence @kbd{f13 f13} to the command @code{eval-last-sexp}. To accomplish this, we can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}. -If you answer positively to Viper's offer to save this macro in @file{~/.viper} -for future uses, the following will be inserted in that file: +If you answer positively to Viper's offer to save this macro in your +Viper customization file for future uses, the following will be inserted +in that file: @example (viper-record-kbd-macro [f16 f16] 'vi-state @@ -2972,8 +2980,8 @@ The rate at which the user must type keys in order for them to be recognized as a timeout macro is controlled by the variable @code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds. -For the most part, Viper macros defined in @file{~/.viper} can be shared -between X and TTY modes. +For the most part, Viper macros defined in the Viper customization file can +be shared between X and TTY modes. The problem with TTY may be that the function keys there generate sequences of events instead of a single event (as under a window system). Emacs maps some of these sequences back to the logical keys @@ -2994,7 +3002,7 @@ currently defined. To see all macros along with their definitions, type This section is a semi-automatically bowdlerized version of the Vi reference created by @* @samp{maart@@cs.vu.nl} and others. It can be -found on the Vi archives. This reference has been adapted for Viper.@refill +found on the Vi archives. This reference has been adapted for Viper. @menu * Groundwork:: Textual Conventions and Viper basics @@ -3015,7 +3023,7 @@ The VI command set is based on the idea of combining motion commands with other commands. The motion command is used as a text region specifier for other commands. We classify motion commands into @dfn{point commands} and -@dfn{line commands}.@refill +@dfn{line commands}. @cindex point commands @@ -3159,7 +3167,8 @@ By default, Viper syntax preference is @code{reformed-vi}, which means that Viper considers only those symbols to be part of a word that are specified as word-symbols by the current Emacs syntax table (which may be different for different major modes) plus the underscore symbol @kbd{_}, minus the -symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be +symbols that are not considered words in Vi (e.g., @samp{,}, @samp{;}, +etc.), but may be considered as word-symbols by various Emacs major modes. Reformed-Vi works very close to Vi, and it also recognizes words in other alphabets. Therefore, this is the most appropriate mode for editing text @@ -3359,7 +3368,8 @@ this function. Find the next bracket/parenthesis/brace and go to its match. By default, Viper ignores brackets/parentheses/braces that occur inside parentheses. You can change this by setting -@code{viper-parse-sexp-ignore-comments} to @code{nil} in your @file{.viper} file. +@code{viper-parse-sexp-ignore-comments} to @code{nil} in your Viper +customization file. This option can also be toggled interactively if you quickly hit @kbd{%%%}. This latter feature is implemented as a vi-style keyboard macro. If you @@ -3370,7 +3380,7 @@ don't want this macro, put @end example @findex @code{viper-set-parsing-style-toggling-macro} -in your @file{~/.viper} file. +in your Viper customization file. @end table @kindex @kbd{%} @@ -3474,8 +3484,8 @@ Go to specified Viper mark and go to the first CHAR on line. @kindex @kbd{m<} @kindex @kbd{m,} @kindex @kbd{m^} -@findex @kbd{:mark} -@findex @kbd{:k} +@findex @kbd{Ex mark} +@findex @kbd{Ex k} @kindex @kbd{''} @kindex @kbd{``} @kindex @kbd{`<a-z>} @@ -3540,11 +3550,11 @@ the direction of older commands, while hitting @kbd{C-c M-n} does so in reverse order. Each command in the history is displayed in the minibuffer. The displayed command can -then be executed by typing `@kbd{.}'. +then be executed by typing a period. Since typing the above sequences of keys may be tedious, the functions doing the perusing can be bound to unused keyboard keys in the -@file{~/.viper} file. @xref{Viper Specials}, for details. +Viper customization file. @xref{Viper Specials}, for details. @end table @kindex @kbd{C-c M-p} @kindex @kbd{C-c M-n} @@ -3724,11 +3734,11 @@ destructive Vi commands. @kindex @kbd{#c<move>} @kindex @kbd{&} @kindex @kbd{\&} -@findex @kbd{:substitute/<pat>/<repl>/<f>} -@findex @kbd{:s/<pat>/<repl>/<f>} -@findex @kbd{:copy [z]} -@findex @kbd{:t [z]} -@findex @kbd{:move [z]} +@findex @kbd{Ex substitute/<pat>/<repl>/<f>} +@findex @kbd{Ex s/<pat>/<repl>/<f>} +@findex @kbd{Ex copy [z]} +@findex @kbd{Ex t [z]} +@findex @kbd{Ex move [z]} @kindex @kbd{J} @kindex @kbd{~} @kindex @kbd{=<move>} @@ -3808,14 +3818,14 @@ Execute <ex-command> on all lines that match <pattern>. Execute <ex-command> on all lines that do not match <pattern>. @end table @kindex @kbd{&} -@findex @kbd{:substitute/<pat>/<repl>/<f>} +@findex @kbd{Ex substitute/<pat>/<repl>/<f>} @kindex @kbd{Q} @kindex @kbd{#g<move>} -@findex @kbd{:v} -@findex @kbd{:g} -@findex @kbd{:global} -@findex @kbd{:vglobal} -@findex @kbd{:tag <name>} +@findex @kbd{Ex v} +@findex @kbd{Ex g} +@findex @kbd{Ex global} +@findex @kbd{Ex vglobal} +@findex @kbd{Ex tag <name>} @kindex @kbd{%} @kindex @kbd{N} @kindex @kbd{n} @@ -3868,7 +3878,7 @@ Put the contents of the (default undo) buffer @kindex @kbd{"<a-z>y<move>} @kindex @kbd{y<move>} @kindex @kbd{yank} -@findex @kbd{:yank} +@findex @kbd{Ex yank} @node Undoing @subsection Undoing @@ -3889,9 +3899,9 @@ Re-edit a messed-up file. Recover file from autosave. Viper also creates backup files that have a @samp{~} appended to them. @end table -@findex @kbd{:rec} -@findex @kbd{:e!} -@findex @kbd{:q!} +@findex @kbd{Ex rec} +@findex @kbd{Ex e!} +@findex @kbd{Ex q!} @kindex @kbd{.} @kindex @kbd{U} @kindex @kbd{u} @@ -3984,7 +3994,7 @@ Write the file. Viper makes sure that a final newline is always added to any file where this newline is missing. This is done by setting Emacs variable @code{require-final-newline} to @code{t}. If you don't like this feature, use @code{setq-default} to set @code{require-final-newline} to -@code{nil}. This must be done in @file{.viper} file. +@code{nil}. This must be done in the Viper customization file. @item :[x,y] w <name> Write to the file <name>. @item :[x,y] w>> <name> @@ -4058,7 +4068,7 @@ switch in another window. Buffer completion is supported. The variable @var{viper-read-buffer-function} controls which function is actually used to read the buffer name. The default is @code{read-buffer}, but better alternatives are also available in Emacs (e.g., -@code{iswitchb-read-buffer}). +@code{ido-read-buffer}). @vindex @var{viper-read-buffer-function} @item :B Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed. @@ -4070,42 +4080,42 @@ is typed in minibuffer. File completion and history are supported. @end table @kindex @kbd{v} @kindex @kbd{V} -@findex @kbd{:args} -@findex @kbd{:rew} +@findex @kbd{Ex args} +@findex @kbd{Ex rew} @kindex @kbd{C-^} -@findex @kbd{:e!@: [<files>]} -@findex @kbd{:e [<files>]} -@findex @kbd{:edit [<files>]} -@findex @kbd{:edit!@: [<files>]} -@findex @kbd{:q!} -@findex @kbd{:q} -@findex @kbd{:quit} -@findex @kbd{:quit!} -@findex @kbd{:f} -@findex @kbd{:rec} -@findex @kbd{:r} -@findex @kbd{:read} -@findex @kbd{:pre} +@findex @kbd{Ex e!@: [<files>]} +@findex @kbd{Ex e [<files>]} +@findex @kbd{Ex edit [<files>]} +@findex @kbd{Ex edit!@: [<files>]} +@findex @kbd{Ex q!} +@findex @kbd{Ex q} +@findex @kbd{Ex quit} +@findex @kbd{Ex quit!} +@findex @kbd{Ex f} +@findex @kbd{Ex rec} +@findex @kbd{Ex r} +@findex @kbd{Ex read} +@findex @kbd{Ex pre} @kindex @kbd{ZZ} -@findex @kbd{:wq} -@findex @kbd{:w <file>} -@findex @kbd{:w!@: <file>} -@findex @kbd{:w >> <file>} -@findex @kbd{:write <file>} -@findex @kbd{:write!@: <file>} -@findex @kbd{:write >> <file>} -@findex @kbd{:W} -@findex @kbd{:WW} -@findex @kbd{:Write} -@findex @kbd{:WWrite} -@findex @kbd{:WWrite} -@findex @kbd{:x} -@findex @kbd{:x!} -@findex @kbd{:suspend} -@findex @kbd{:stop} -@findex @kbd{:n [<count> | <file>]} -@findex @kbd{:cd [<dir>]} -@findex @kbd{:pwd} +@findex @kbd{Ex wq} +@findex @kbd{Ex w <file>} +@findex @kbd{Ex w!@: <file>} +@findex @kbd{Ex w >> <file>} +@findex @kbd{Ex write <file>} +@findex @kbd{Ex write!@: <file>} +@findex @kbd{Ex write >> <file>} +@findex @kbd{Ex W} +@findex @kbd{Ex WW} +@findex @kbd{Ex Write} +@findex @kbd{Ex WWrite} +@findex @kbd{Ex WWrite} +@findex @kbd{Ex x} +@findex @kbd{Ex x!} +@findex @kbd{Ex suspend} +@findex @kbd{Ex stop} +@findex @kbd{Ex n [<count> | <file>]} +@findex @kbd{Ex cd [<dir>]} +@findex @kbd{Ex pwd} @node Mapping @section Mapping @@ -4169,10 +4179,10 @@ Show contents of register. @kindex @kbd{@@#} @kindex @kbd{@@@@} @kindex @kbd{@@<a-z>} -@findex @kbd{:unmap <char>} -@findex @kbd{:map <char> <seq>} -@findex @kbd{:unmap!@: <char>} -@findex @kbd{:map!@: <char> <seq>} +@findex @kbd{Ex unmap <char>} +@findex @kbd{Ex map <char> <seq>} +@findex @kbd{Ex unmap!@: <char>} +@findex @kbd{Ex map!@: <char> <seq>} @node Shell Commands @section Shell Commands @@ -4187,7 +4197,7 @@ the whole file. @cindex @samp{#} (Previous file) Similarly, @samp{#} expands to the previous file. The previous file is the first file in @kbd{:args} listing. This defaults to the previous file in -the VI sense if you have one window.@refill +the VI sense if you have one window. Symbols @samp{%} and @samp{#} are also used in the Ex commands @kbd{:e} and @kbd{:r <shell-cmd>}. The commands @kbd{:w} and the regular @kbd{:r @@ -4228,17 +4238,17 @@ current). @item :make Run the make command in the current directory. @end table -@findex @kbd{:<address>r <name>} -@findex @kbd{:<address>r !<cmd>} +@findex @kbd{Ex <address>r <name>} +@findex @kbd{Ex <address>r !<cmd>} @findex @kbd{!<cmd>} @findex @kbd{!!<cmd>} @findex @kbd{!<move><cmd>} -@findex @kbd{:w !<cmd>} -@findex @kbd{:x,y w !<cmd>} -@findex @kbd{:!!@: <args>} -@findex @kbd{:!<cmd>} -@findex @kbd{:sh} -@findex @kbd{:make} +@findex @kbd{Ex w !<cmd>} +@findex @kbd{Ex x,y w !<cmd>} +@findex @kbd{Ex !!@: <args>} +@findex @kbd{Ex !<cmd>} +@findex @kbd{Ex sh} +@findex @kbd{Ex make} @node Options @section Options @@ -4255,7 +4265,7 @@ character on the previous line. This setting affects the current buffer only. @item autoindent-global @itemx ai-global -Same as `autoindent', but affects all buffers. +Same as @code{autoindent}, but affects all buffers. @item noautoindent @itemx noai Cancel autoindent. @@ -4314,7 +4324,7 @@ their normal length (default 8 positions). This setting affects the current buffer only. @item tabstop-global @itemx ts-g -Same as `tabstop', but affects all buffers. +Same as @code{tabstop}, but affects all buffers. @item wrapmargin=<count> @itemx wm=<count> @cindex auto fill @@ -4337,29 +4347,29 @@ Turn <option> off. @item :set <option>=<value> Set <option> to <value>. @end table -@findex @kbd{:set <option>=<value>} -@findex @kbd{:set no<option>} -@findex @kbd{:set <option>} -@findex @kbd{:set ws} -@findex @kbd{:set wrapscan} -@findex @kbd{:set wm=<count>} -@findex @kbd{:set wrapmargin=<count>} -@findex @kbd{:set ts=<count>} -@findex @kbd{:set tabstop=<count>} -@findex @kbd{:set tab-stop-local=<count>} -@findex @kbd{:set sm} -@findex @kbd{:set showmatch} -@findex @kbd{:set sw=<count>} -@findex @kbd{:set shiftwidth=<count>} -@findex @kbd{:set sh=<string>} -@findex @kbd{:set shell=<string>} -@findex @kbd{:set ro} -@findex @kbd{:set readonly} -@findex @kbd{:set magic} -@findex @kbd{:set ic} -@findex @kbd{:set ignorecase} -@findex @kbd{:set ai} -@findex @kbd{:set autoindent} +@findex @kbd{Ex set <option>=<value>} +@findex @kbd{Ex set no<option>} +@findex @kbd{Ex set <option>} +@findex @kbd{Ex set ws} +@findex @kbd{Ex set wrapscan} +@findex @kbd{Ex set wm=<count>} +@findex @kbd{Ex set wrapmargin=<count>} +@findex @kbd{Ex set ts=<count>} +@findex @kbd{Ex set tabstop=<count>} +@findex @kbd{Ex set tab-stop-local=<count>} +@findex @kbd{Ex set sm} +@findex @kbd{Ex set showmatch} +@findex @kbd{Ex set sw=<count>} +@findex @kbd{Ex set shiftwidth=<count>} +@findex @kbd{Ex set sh=<string>} +@findex @kbd{Ex set shell=<string>} +@findex @kbd{Ex set ro} +@findex @kbd{Ex set readonly} +@findex @kbd{Ex set magic} +@findex @kbd{Ex set ic} +@findex @kbd{Ex set ignorecase} +@findex @kbd{Ex set ai} +@findex @kbd{Ex set autoindent} @node Emacs Related Commands @section Emacs Related Commands @@ -4425,7 +4435,7 @@ a region under the mouse pointer. This command can take a prefix argument. Note: Viper sets this binding only if this mouse action is not already bound to something else. -@xref{Viper Specials}, for more information.@refill +@xref{Viper Specials}, for more information. @item S-Mouse-2 Holding Shift and clicking button 2 of the mouse will @@ -4433,7 +4443,7 @@ insert a region surrounding the mouse pointer. This command can also take a prefix argument. Note: Viper sets this binding only if this mouse action is not already bound to something else. -@xref{Viper Specials}, for more details.@refill +@xref{Viper Specials}, for more details. @end table @kindex @kbd{S-Mouse-1} @kindex @kbd{S-Mouse-2} diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi index f2c403a2c14..ea785501698 100644 --- a/doc/misc/widget.texi +++ b/doc/misc/widget.texi @@ -1,20 +1,21 @@ \input texinfo.tex @c %**start of header -@setfilename ../../info/widget +@setfilename ../../info/widget.info @settitle The Emacs Widget Library +@include docstyle.texi @syncodeindex fn cp @syncodeindex vr cp @syncodeindex ky cp @c %**end of header @copying -Copyright @copyright{} 2000--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2000--2015 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'', +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''. @@ -29,6 +30,14 @@ modify this GNU manual.'' Customization facility. @end direntry + +@titlepage +@title The Emacs Widget Library +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + @contents @node Top @@ -57,7 +66,7 @@ modify this GNU manual.'' @chapter Introduction Most graphical user interface toolkits provide a number of standard -user interface controls (sometimes known as `widgets' or `gadgets'). +user interface controls (sometimes known as ``widgets'' or ``gadgets''). Emacs doesn't really support anything like this, except for an incredibly powerful text ``widget.'' On the other hand, Emacs does provide the necessary primitives to implement many other widgets @@ -431,7 +440,6 @@ Set up a buffer to support widgets. This should be called after creating all the widgets and before allowing the user to edit them. -@refill @end defun If you want to insert text outside the widgets in the form, the @@ -450,7 +458,7 @@ There is a standard widget keymap which you might find useful. @key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and @code{widget-backward}, respectively. @key{RET} and @kbd{Mouse-2} are bound to @code{widget-button-press} and -@code{widget-button-click}.@refill +@code{widget-button-click}. @end defvr @defvar widget-global-map @@ -1718,7 +1726,7 @@ Keymap used in @code{widget-minor-mode}. @defun widget-prompt-value widget prompt [ value unbound ] Prompt for a value matching @var{widget}, using @var{prompt}. The current value is assumed to be @var{value}, unless @var{unbound} is -non-@code{nil}.@refill +non-@code{nil}. @end defun @defun widget-get-sibling widget diff --git a/doc/misc/wisent.texi b/doc/misc/wisent.texi index c0f18f6363a..7bcc46d58f0 100644 --- a/doc/misc/wisent.texi +++ b/doc/misc/wisent.texi @@ -1,9 +1,10 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/wisent +@setfilename ../../info/wisent.info @set TITLE Wisent Parser Development @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE} +@include docstyle.texi @c ************************************************************************* @c @ Header @@ -23,7 +24,7 @@ @c %**end of header @copying -Copyright @copyright{} 1988--1993, 1995, 1998--2004, 2007, 2012--2013 +Copyright @copyright{} 1988--1993, 1995, 1998--2004, 2007, 2012--2015 Free Software Foundation, Inc. @c Since we are both GNU manuals, we do not need to ack each other here. @@ -38,7 +39,7 @@ of Bison version 1.49. 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,'' +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''. @@ -130,7 +131,7 @@ June 1985, Report No. UCB/CSD 85/251. @item For generating the lookahead sets, Wisent uses the well-known -technique of F. DeRemer and A. Pennello described in: +technique of F. DeRemer and T. Pennello described in: @quotation @cite{Efficient Computation of LALR(1) Look-Ahead Sets}@* October 1982, ACM TOPLAS Vol 4 No 4, 615--49, @@ -688,7 +689,7 @@ Toggle whether to report verbose information on generated parser. @end deffn The verbose report is printed in the temporary buffer -@code{*wisent-log*} when running interactively, or in file +@file{*wisent-log*} when running interactively, or in file @file{wisent.output} when running in batch mode. Different reports are separated from each other by a line like this: @@ -759,7 +760,7 @@ Grammar contains 7 shift/reduce conflicts @end group @end example -The @samp{*wisent-log*} buffer details things! +The @file{*wisent-log*} buffer details things! The first section reports conflicts that were solved using precedence and/or associativity: @@ -1442,7 +1443,7 @@ tokens (@pxref{Useful functions}). @defun wisent-skip-token @anchor{wisent-skip-token} Skip the lookahead token in order to resume parsing. -Return nil. +Return @code{nil}. Must be used in error recovery semantic actions. It typically looks like this: @@ -1462,7 +1463,7 @@ It typically looks like this: @findex wisent-skip-block @defun wisent-skip-block Safely skip a block in order to resume parsing. -Return nil. +Return @code{nil}. Must be used in error recovery semantic actions. A block is data between an open-delimiter (syntax class @code{(}) and diff --git a/doc/misc/woman.texi b/doc/misc/woman.texi index 8005d58ce8a..f1286fc3473 100644 --- a/doc/misc/woman.texi +++ b/doc/misc/woman.texi @@ -1,7 +1,8 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/woman +@setfilename ../../info/woman.info @settitle WoMan: Browse Unix Manual Pages ``W.O. (without) Man'' +@include docstyle.texi @include emacsver.texi @afourpaper @c With different size paper the printed page breaks will need attention! @@ -11,16 +12,16 @@ @c %**end of header @copying -This file documents WoMan: A program to browse Unix manual pages `W.O. -(without) man'. +This file documents WoMan: A program to browse Unix manual pages ``W.O. +(without) man''. -Copyright @copyright{} 2001--2013 Free Software Foundation, Inc. +Copyright @copyright{} 2001--2015 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,'' +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.'' @@ -171,7 +172,7 @@ is important I will refer to them both ambiguously as @code{roff}. @code{roff} markup consists of @dfn{requests} and @dfn{escape sequences}. A request occupies a complete line and begins with either a -period or a single forward quote. An escape sequences is embedded +period or an apostrophe. An escape sequence is embedded within the input text and begins (by default) with a backslash. The original man macro package defines 20 new @code{roff} requests implemented as macros, which were considered to be sufficient for @@ -629,7 +630,9 @@ the @code{man} key bindings. Scroll the man page up the window (@code{scroll-up}). @item @key{DEL} +@itemx @kbd{S-@key{SPC}} @kindex DEL +@kindex S-SPC @findex scroll-down Scroll the man page down the window (@code{scroll-down}). @@ -823,7 +826,7 @@ shows manual sections and subsections by default, but you can change this by customizing @code{woman-imenu-generic-expression}. WoMan is configured not to replace spaces in an imenu -@code{*Completion*} buffer. For further documentation on the use of +@file{*Completion*} buffer. For further documentation on the use of imenu, such as menu sorting, see the source file @file{imenu.el}, which is distributed with GNU Emacs. @@ -849,7 +852,7 @@ customization should be possible via existing user options. @vtable @code @item woman-show-log A boolean value that defaults to @code{nil}. If non-@code{nil} then show the -@code{*WoMan-Log*} buffer if appropriate, i.e., if any warning messages +@file{*WoMan-Log*} buffer if appropriate, i.e., if any warning messages are written to it. @xref{Log, , The *WoMan-Log* Buffer}. @item woman-pre-format-hook @@ -1138,7 +1141,7 @@ headings. Default is @code{t}. [Heading emboldening is @emph{not} standard @code{man} behavior.] @item woman-ignore -A boolean value. If non-@code{nil} then unrecognized requests etc. are +A boolean value. If non-@code{nil} then unrecognized requests etc.@: are ignored. Default is @code{t}. This gives the standard @code{roff} behavior. If @code{nil} then they are left in the buffer, which may aid debugging. @@ -1292,7 +1295,7 @@ on @uref{http://savannah.gnu.org/projects/emacs/}. If it still fails, please @item use @kbd{M-x report-emacs-bug} to send a bug report. Please include the entry from the -@code{*WoMan-Log*} buffer relating to the problem file, together with +@file{*WoMan-Log*} buffer relating to the problem file, together with a brief description of the problem. Please indicate where you got the man source file from, but do not send it unless asked to send it. @end enumerate |