+2012-02-16 Kenichi Handa <handa@m17n.org>
+
+ * unidata/unidata-gen.el (unidata-prop-alist): Change the default
+ values of name and old-name to nil.
+ (unidata-get-name): Return nil for the default value.
+
2012-02-11 Glenn Morris <rgm@gnu.org>
* admin.el (cusver-find-files, cusver-scan, cusver-goto-xref)
are correct. You can use something like the following in the info
directory in the Emacs build tree:
-emacs -Q --eval "(setq Info-default-directory-list '(\".\"))" \
+emacs -Q --eval "(progn (require 'info) (setq Info-directory-list '(\".\")))" \
-f info-xref-check-all
make emacs.dvi, elisp.dvi, and deal with any errors (undefined
* BUGS
-** rms: gnus-dired.el is a mistake. Those features should not
-be part of Gnus. They should be moved to some other part of Emacs.
-rsteib: Gnus dependencies in `gnus-dired.el' (and `mailcap.el') have been
-minimized. I don't know what is left to do here.
-
** Check for modes which bind M-s that conflicts with a new global binding M-s
and change key bindings where necessary. The current list of modes:
`log-edit-comment-search-forward'. Perhaps search commands
on the global key binding `M-s' are useless in these modes.
-* DOCUMENTATION
+5. Rmail binds `\es' to `rmail-search'/`rmail-summary-search'.
-** Document XEmbed support
+
+* DOCUMENTATION
** Check the Emacs Tutorial.
** Check the manual.
abbrevs.texi cyd
-ack.texi
+ack.texi rgm
anti.texi cyd
arevert-xtra.texi cyd
basic.texi cyd
buffers.texi cyd
building.texi cyd
-calendar.texi
-cal-xtra.texi
+calendar.texi rgm
+cal-xtra.texi rgm
cmdargs.texi cyd
commands.texi cyd
custom.texi cyd
dired.texi cyd
-dired-xtra.texi
+dired-xtra.texi rgm
display.texi cyd
-emacs.texi
-emacs-xtra.texi
-emerge-xtra.texi
+emacs.texi rgm
+emacs-xtra.texi rgm
+emerge-xtra.texi rgm
entering.texi cyd
files.texi cyd
fixit.texi cyd
-fortran-xtra.texi
+fortran-xtra.texi rgm
frames.texi cyd
glossary.texi
help.texi cyd
indent.texi cyd
killing.texi cyd
kmacro.texi cyd
-macos.texi
+macos.texi rgm (can't actually test any of it though)
maintaining.texi cyd
mark.texi cyd
mini.texi
mule.texi
m-x.texi cyd
package.texi cyd
-picture-xtra.texi
+picture-xtra.texi rgm
programs.texi cyd
regs.texi cyd
-rmail.texi
+rmail.texi rgm
screen.texi cyd
search.texi cyd
sending.texi cyd
elisp.texi
errors.texi
eval.texi cyd
-files.texi
+files.texi cyd
frames.texi
functions.texi cyd
hash.texi cyd
-help.texi
+help.texi cyd
hooks.texi
index.texi
internals.texi
maps.texi
markers.texi
minibuf.texi
-modes.texi
+modes.texi cyd
nonascii.texi
numbers.texi cyd
objects.texi cyd
streams.texi cyd
strings.texi cyd
symbols.texi cyd
-syntax.texi
+syntax.texi cyd
text.texi
tips.texi
variables.texi cyd
windows.texi
-* PLANNED ADDITIONS
-* pov-mode (probably not for Emacs-23: waiting for a Free POV-Ray).
-** gas-mode ?
-
\f
Local variables:
mode: outline
'((name
1 unidata-gen-table-name "uni-name.el"
"Unicode character name.
-Property value is a string."
+Property value is a string or nil.
+The value nil stands for the default value \"null string\")."
nil
- "")
+ nil)
(general-category
2 unidata-gen-table-symbol "uni-category.el"
"Unicode general category.
(old-name
10 unidata-gen-table-name "uni-old-name.el"
"Unicode old names as published in Unicode 1.0.
-Property value is a string.")
+Property value is a string or nil.
+The value nil stands for the default value \"null string\").")
(iso-10646-comment
11 unidata-gen-table-name "uni-comment.el"
"Unicode ISO 10646 comment.
(aset table c name)
(if (= c char)
(setq val name))))
- (or val ""))))
+ val)))
((and (integerp val) (> val 0))
(let* ((symbol-table (aref (char-table-extra-slot table 4) 1))
((eq sym 'CJK\ COMPATIBILITY\ IDEOGRAPH)
(format "%s-%04X" sym char))
((eq sym 'VARIATION\ SELECTOR)
- (format "%s-%d" sym (+ (- char #xe0100) 17))))))
-
- (t "")))
+ (format "%s-%d" sym (+ (- char #xe0100) 17))))))))
;; Store VAL as the name of CHAR in TABLE.
+2012-02-22 Glenn Morris <rgm@gnu.org>
+
+ * macos.texi: Copyedits. Fix @key/@kbd usage.
+ (Mac / GNUstep Basics): Don't mention the panels, since the next
+ section covers them.
+ (Mac / GNUstep Customization): Merge some panel info from previous.
+
+2012-02-21 Glenn Morris <rgm@gnu.org>
+
+ * emerge-xtra.texi (Emerge, Submodes of Emerge, Combining in Emerge):
+ Small fixes.
+
+ * emacs-xtra.texi: Picture mode is no longer a chapter.
+
+ * picture-xtra.texi (Basic Picture): C-a does get remapped.
+
+ * ack.texi (Acknowledgments): Small changes, including resorting,
+ and removal of things no longer distributed.
+
+2012-02-20 Glenn Morris <rgm@gnu.org>
+
+ * emacs.texi (Top, Preface): Small rephrasings.
+ (menu, detailmenu): Update entries, and reformat some descriptions.
+ * building.texi, display.texi, emacs-xtra.texi, files.texi:
+ * frames.texi, kmacro.texi, msdog.texi, programs.texi, text.texi:
+ Reformat some menu descriptions.
+
+ * ack.texi (Acknowledgments): More updates.
+
+ * emacs.texi (Acknowledgments): Add several names from ack.texi,
+ and from Author: headers.
+ (Distrib): Small updates.
+
+2012-02-18 Glenn Morris <rgm@gnu.org>
+
+ * ack.texi (Acknowledgments): Add xref to Org manual.
+
+ * rmail.texi: Copyedits. Use 'mail composition buffer' in place
+ of '*mail*', since Message does not call it that.
+ (Rmail Reply): Rename rmail-dont-reply-to-names.
+ \\`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
+ not work for Message at the moment.
+
+ * cal-xtra.texi: Copyedits.
+
+ * emacs-xtra.texi: Set encoding to ISO-8859-1.
+
+2012-02-17 Glenn Morris <rgm@gnu.org>
+
+ * maintaining.texi (Old Revisions): Fix cross-refs to Ediff manual.
+
+ * ack.texi (Acknowledgments): Mention Gnulib.
+
+ * ack.texi, calendar.texi, cal-xtra.texi: Use "Bahá'í".
+
+ * calendar.texi: Misc small changes, including updating the dates
+ of examples.
+
+2012-02-16 Glenn Morris <rgm@gnu.org>
+
+ * calendar.texi: Misc small changes.
+
+ * vc1-xtra.texi (VC Delete/Rename, CVS Options):
+ * cal-xtra.texi (Diary Display): Fix TeX cross-refs to other manuals.
+
+ * dired-xtra.texi (Subdir Switches): Small fixes.
+
+ * fortran-xtra.texi: Tiny changes and some adjustments to line breaks.
+
2012-02-15 Glenn Morris <rgm@gnu.org>
* sending.texi (Mail Sending): smtpmail-auth-credentials was removed.
@c -*- coding: iso-latin-1 -*-
@c This is part of the Emacs manual.
-@c Copyright (C) 1994-1997, 1999-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1994-1997, 1999-2012 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@c
@node Acknowledgments, Screen, Concept Index, Top
from the keyboard; @file{xt-mouse.el}, which allows mouse commands
through Xterm; @file{gnus-cus.el}, which implements customization
commands for Gnus; @file{gnus-cite.el}, a citation-parsing facility for
-news articles); @file{gnus-score.el}, scoring for Gnus; @file{cpp.el},
+news articles; @file{gnus-score.el}, scoring for Gnus; @file{cpp.el},
which hides or highlights parts of C programs according to preprocessor
conditionals; and the widget library files @file{wid-browse.el},
@file{wid-edit.el}, @file{widget.el}. He also co-wrote
Joe Arceneaux wrote the original text property implementation, and
implemented support for X11.
+@item
+Emil Åström, Milan Zamaza, and Stefan Bruda wrote @file{prolog.el},
+a mode for editing Prolog (and Mercury) code.
+
@item
Miles Bader wrote @file{image-file.el}, support code for visiting image
files; @file{minibuf-eldef.el}, a minor mode that hides the minibuffer
@code{read-file-name} input; @file{mb-depth.el}, display of minibuffer
depth; @file{button.el}, the library that implements clickable buttons;
@file{face-remap.el}, a package for changing the default face in
-individual buffers; and @file{macroexp.el} for macro-expansion.
+individual buffers; and @file{macroexp.el} for macro-expansion. He
+also worked on an early version of the lexical binding code.
@item
David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by
@item
Bob Chassell wrote @file{texnfo-upd.el}, @file{texinfo.el}, and
@file{makeinfo.el}, modes and utilities for working with Texinfo files;
-and @file{page-ext.el}, commands for extended page handling.
+and @file{page-ext.el}, commands for extended page handling. He also
+wrote the ``Introduction to programming in Emacs Lisp'' manual.
@item
Jihyun Cho wrote @file{hanja-util.el} and @file{hangul.el}, utilities
prior to Emacs 23 for Mac OS.
@item
-Chong Yidong was the Emacs co-maintainer for Emacs 23. He made many
+Chong Yidong was the Emacs co-maintainer from Emacs 23 onwards. He made many
improvements to the Emacs display engine. He also wrote
-@file{tabulated-list.el}, a generic major mode for lists of data.
+@file{tabulated-list.el}, a generic major mode for lists of data;
+and improved support for themes and packages.
@item
James Clark wrote SGML mode, a mode for editing SGML documents; and
Andrew Cohen wrote @file{spam-wash.el}, to decode and clean email before
it is analyzed for spam.
+@item
+Edward O'Connor wrote @file{json.el}, a file for parsing and
+generating JSON files.
+
@item
Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a
package for easy definition of major and minor modes.
Vivek Dasmohapatra wrote @file{htmlfontify.el}, to convert a buffer or
source tree to HTML.
-@item
-Michael DeCorte wrote @file{emacs.csh}, a C-shell script that starts a
-new Emacs job, or restarts a paused Emacs if one exists.
-
@item
Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the
@file{/usr/uci/post} mailer.
@item
Carsten Dominik wrote Ref@TeX{}, a package for setting up labels and
cross-references in La@TeX{} documents; and co-wrote IDLWAVE mode
-(q.v.@:). He was the main author of Org mode, for maintaining notes,
-todo lists, and project planning. Thomas Baumann, Jan Böcker, Lennart
-Borgman, Baoqiu Cui, Daniel German, Bastien Guerry, Tassilo Horn, Philip
-Jackson, Tokuya Kameshima, Ross Patterson, Sebastian Rose, Eric Schulte,
-Paul Sexton, Ulf Stegemann, Andy Stewart, David O'Toole, John Wiegley,
-and Piotr Zielinski also wrote various Org mode components.
+(q.v.@:). He was the original author of Org mode, for maintaining notes,
+todo lists, and project planning. Bastien Guerry subsequently took
+over maintainership. Benjamin Andresen, Thomas Baumann, Joel Boehland, Jan Böcker, Lennart
+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.
+For more information, @pxref{History and Acknowledgments,,, org, The Org Manual}.
@item
Scott Draves wrote @file{tq.el}, help functions for maintaining
John Eaton and Kurt Hornik wrote Octave mode.
@item
-Rolf Ebert co-wrote Ada mode.
+Rolf Ebert, Markus Heritsch, and Emmanuel Briot wrote Ada mode.
+
+@item
+Paul Eggert integrated the Gnulib portability library, and made many
+other portability fixes to the C code; as well as his contributions
+to VC and the calendar.
@item
Stephen Eglen wrote @file{mspools.el}, which tells you which Procmail
@item
Bastien Guerry wrote @file{gnus-bookmark.el}, bookmark support for Gnus;
-as well as contributing to Org mode (q.v.@:).
+as well as helping to maintain Org mode (q.v.@:).
@item
Henry Guillaume wrote @file{find-file.el}, a package to visit files
Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation
format of Unicode.
-@item
-Markus Heritsch co-wrote Ada mode.
-
@item
Karl Heuer wrote the original blessmail script, implemented the
@code{intangible} text property, and rearranged the structure of the
@item
Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and
wrote many of its parts. Several of these are now general components of
-Emacs: @file{dns.el} for Domain Name Service lookups;
+Emacs, including: @file{dns.el} for Domain Name Service lookups;
@file{format-spec.el} for formatting arbitrary format strings;
@file{netrc.el} for parsing of @file{.netrc} files; and
@file{time-date.el} for general date and time handling.
He also wrote @file{network-stream.el}, for opening network processes;
-and @file{url-queue.el}, for controlling parallel downloads of URLs.
+@file{url-queue.el}, for controlling parallel downloads of URLs;
+and implemented libxml2 support.
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
@item
Michael Kifer wrote @code{ediff}, an interactive interface to the
@command{diff}, @command{patch}, and @command{merge} programs; and
-Viper, the newest emulation for VI.
+Viper, another emulator of the VI editor.
@item
Richard King wrote the first version of @file{userlock.el} and
@item
Shuhei Kobayashi wrote @file{hex-util.el}, for operating on hexadecimal
-strings; support for HMAC (Keyed-Hashing for Message Authentication);
-and a Lisp implementation of the SHA1 Secure Hash Algorithm.
+strings; and support for HMAC (Keyed-Hashing for Message Authentication).
@item
Pavel Kobyakov wrote @file{flymake.el}, a minor mode for performing
@item
Sebastian Kremer wrote @code{dired-mode}, with contributions by Lawrence
R.@: Dodd. He also wrote @file{ls-lisp.el}, a Lisp emulation of the
-@code{ls} command for platforms which don't have @code{ls} as a standard
+@code{ls} command for platforms that don't have @code{ls} as a standard
program.
@item
@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic
chart that can be printed to a PostScript printer; and
@file{whitespace.el}, a package that detects and cleans up excess
-whitespace in a file. The previous version of @file{whitespace.el},
-used prior to Emacs 23, was written by Rajesh Vaidheeswarran.
+whitespace in a file (building on an earlier version by Rajesh Vaidheeswarran).
@item
Frederic Lepied wrote @file{expand.el}, which uses the abbrev
Development Environment Tools) package. Portions were also written by
Jan Moringen, David Ponce, and Joakim Verona.
+@item
+Roland McGrath wrote @file{compile.el} (since updated by Daniel
+Pfeiffer), a package for running compilations in a buffer, and then
+visiting the locations reported in error messages; @file{etags.el}, a
+package for jumping to function definitions and searching or replacing
+in all the files mentioned in a @file{TAGS} file; with Sebastian
+Kremer @file{find-dired.el}, for using @code{dired} commands on output
+from the @code{find} program; @file{grep.el} for running the
+@code{grep} command; @file{map-ynp.el}, a general purpose boolean
+question-asker; @file{autoload.el}, providing semi-automatic
+maintenance of autoload files.
+
@item
Alan Mackenzie wrote the integrated AWK support in CC Mode, and
maintained CC Mode from Emacs 22 onwards.
+@item
+Michael McNamara and Wilson Snyder wrote Verilog mode.
+
@item
Christopher J.@: Madsen wrote @file{decipher.el}, a package for cracking
simple substitution ciphers.
Thomas May wrote @file{blackbox.el}, a version of the traditional
blackbox game.
-@item
-Roland McGrath wrote @file{compile.el} (since updated by Daniel
-Pfeiffer), a package for running compilations in a buffer, and then
-visiting the locations reported in error messages; @file{etags.el}, a
-package for jumping to function definitions and searching or replacing
-in all the files mentioned in a @file{TAGS} file; @file{find-dired.el},
-for using @code{dired} commands on output from the @code{find} program,
-with Sebastian Kremer; @file{grep.el} for running the @code{grep}
-command; @file{map-ynp.el}, a general purpose boolean question-asker;
-@file{autoload.el}, providing semi-automatic maintenance of autoload
-files.
-
-@item
-Michael McNamara and Wilson Snyder wrote Verilog mode.
-
@item
David Megginson wrote @file{derived.el}, which allows one to define new
major modes by inheriting key bindings and commands from existing major
and @file{rx.el}, a regular expression constructor.
@item
-Stefan Monnier was the Emacs co-maintainer for Emacs 23. He added
+Stefan Monnier was the Emacs co-maintainer from Emacs 23 onwards. 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},
diffs; @file{css-mode.el} for Cascading Style Sheets;
@file{bibtex-style.el} for BibTeX Style files; @file{mpc.el}, a
client for the ``Music Player Daemon''; and @file{pcase.el},
-implementing ML-style pattern matching.
+implementing ML-style pattern matching. He integrated the
+lexical binding code in Emacs 24.
@item
Morioka Tomohiko wrote several packages for MIME support in Gnus and
elsewhere.
-@item
-Takahashi Naoto co-wrote @file{quail.el} (q.v.@:), and wrote
-@file{robin.el}, another input method.
-
@item
Sen Nagata wrote @file{crm.el}, a package for reading multiple strings
with completion, and @file{rfc2368.el}, support for @code{mailto:}
@item
Erik Naggum wrote the time-conversion functions. He also wrote
-@file{disp-table.el}, a package for dealing with display tables;
-@file{mailheader.el}, a package for parsing email headers; and
-@file{parse-time.el}, a package for parsing time strings.
+@file{disp-table.el}, for dealing with display tables;
+@file{mailheader.el}, for parsing email headers; and
+@file{parse-time.el}, for parsing time strings.
+
+@item
+Takahashi Naoto co-wrote @file{quail.el} (q.v.@:), and wrote
+@file{robin.el}, another input method.
@item
Thomas Neumann and Eric Raymond wrote @file{make-mode.el},
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;
and @code{winterm} terminal emulators; and @file{vc-dir.el}, displaying
the status of version-controlled directories.
-@item
-Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation.
-
@item
Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer
history between Emacs sessions.
Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP
support.
-@item
-Edward O'Connor wrote @file{json.el}, a file for parsing and
-generating JSON files.
-
@item
Kentaro Ohkouchi created the Emacs icons used beginning with Emacs 23.
which each lisp function loaded into Emacs came.
@item
-Edward M.@: Reingold wrote the extensive calendar and diary support,
+Edward M.@: Reingold wrote the calendar and diary support,
with contributions from Stewart Clamen (@file{cal-mayan.el}), Nachum
Dershowitz (@file{cal-hebrew.el}), Paul Eggert (@file{cal-dst.el}),
Steve Fisk (@file{cal-tex.el}), Michael Kifer (@file{cal-x.el}), Lara
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.
+
@item
Ivar Rummelhoff wrote @file{winner.el}, which records recent window
configurations so you can move back to them.
@item
Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a mode for editing
Tcl/Tk source files and running a Tcl interpreter as an Emacs
-subprocess.
-
-@item
-Tom Tromey wrote @file{bug-reference.el}, providing clickable links to
-bug reports; and the first version of the Emacs package system.
+subprocess. Tom Tromey also wrote @file{bug-reference.el}, providing
+clickable links to bug reports; and the first version of the Emacs
+package system.
@item
Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL.
operations on rectangle regions of text. He also contributed to Gnus
(q.v.@:).
+@item
+Joakim Verona implemented ImageMagick support.
+
@item
Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code.
John Wiegley wrote @file{align.el}, a set of commands for aligning text
according to regular-expression based rules; @file{isearchb.el} for fast
buffer switching; @file{timeclock.el}, a package for keeping track of
-time spent on projects; the Baha'i calendar support;
+time spent on projects; the Bahá'í calendar support;
@file{pcomplete.el}, a programmable completion facility;
@file{remember.el}, a mode for jotting down things to remember;
@file{eudcb-mab.el}, an address book backend for the Emacs Unified
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}.
+@file{rxvt.el}. He implemented support for bidirectional text.
@item
Jamie Zawinski wrote much of the support for faces and X selections.
* Commands of GUD:: Key bindings for common commands.
* GUD Customization:: Defining your own commands for GUD.
* GDB Graphical Interface:: An enhanced mode that uses GDB features to
- implement a graphical debugging environment through
- Emacs.
+ implement a graphical debugging environment.
@end menu
@node Starting GUD
-@c This is part of the Emacs manual.
-@c Copyright (C) 2004-2012 Free Software Foundation, Inc.
+@c This is part of the Emacs manual. -*- coding: iso-latin-1 -*-
+@c Copyright (C) 2004-2012 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
@node Advanced Calendar/Diary Usage
@section Customizing the Calendar and Diary
- There are many customizations that you can use to make the calendar and
-diary suit your personal tastes.
+ There are many ways in which you can customize the calendar and
+diary to suit your personal tastes.
@menu
* Calendar Customizing:: Calendar layout and hooks.
@vindex diary-entry-marker
@vindex calendar-today-marker
The variable @code{calendar-holiday-marker} specifies how to mark a
-date as being a holiday. Its value may be a single-character string to
+date that is a holiday. Its value may be a single-character string to
insert next to the date, or a face name to use for displaying the date.
Likewise, the variable @code{diary-entry-marker} specifies how to mark a
-date that has diary entries, and @code{calendar-today-marker} is used by
-the function @code{calendar-mark-today} to mark today's date. By
-default, the calendar uses faces named @code{holiday}, @code{diary}, and
+date that has diary entries. The function @code{calendar-mark-today}
+uses @code{calendar-today-marker} to mark today's date. By default,
+the calendar uses faces named @code{holiday}, @code{diary}, and
@code{calendar-today} for these purposes.
@vindex calendar-load-hook
@vindex calendar-today-visible-hook
@findex calendar-star-date
The variable @code{calendar-today-visible-hook} is a normal hook run
-after the calendar buffer has been prepared with the calendar when the
+after the calendar buffer has been prepared with the calendar, when the
current date is visible in the window. One use of this hook is to
mark today's date; to do that use either of the functions
@code{calendar-mark-today} or @code{calendar-star-date}:
@vindex calendar-holidays
@vindex holiday-oriental-holidays
@vindex holiday-solar-holidays
- Emacs knows about holidays defined by entries on one of several lists.
-The lists of holidays that Emacs uses are for
-general holidays (@code{holiday-general-holidays}),
-local holidays (@code{holiday-local-holidays}),
-sun- and moon-related holidays (@code{holiday-solar-holidays}),
-Baha'i holidays (@code{holiday-bahai-holidays}),
-Christian holidays (@code{holiday-christian-holidays}),
-Hebrew (Jewish) holidays (@code{holiday-hebrew-holidays}),
-Islamic (Muslim) holidays (@code{holiday-islamic-holidays}),
-Oriental holidays (@code{holiday-oriental-holidays}),
-and other holidays (@code{holiday-other-holidays}).
+ There are several variables listing the default holidays that Emacs
+knows about. These are: @code{holiday-general-holidays},
+@code{holiday-local-holidays}, @code{holiday-solar-holidays},
+@code{holiday-bahai-holidays}, @code{holiday-christian-holidays},
+@code{holiday-hebrew-holidays}, @code{holiday-islamic-holidays},
+@code{holiday-oriental-holidays}, and @code{holiday-other-holidays}.
+The names should be self-explanatory; e.g.@: @code{holiday-solar-holidays}
+lists sun- and moon-related holidays.
You can customize these lists of holidays to your own needs, deleting or
adding holidays as described below. Set any of them to @code{nil} to
-eliminate the associated holidays.
+not show the associated holidays.
@vindex holiday-general-holidays
- The general holidays are, by default, holidays common throughout the
-United States.
-
@vindex holiday-local-holidays
- There are no default local holidays, but your site may supply some.
+@vindex holiday-other-holidays
+ The general holidays are, by default, holidays common throughout the
+United States. In contrast, @code{holiday-local-holidays} and
+@code{holiday-other-holidays} are both empty by default. These are
+intended for system-wide settings and your individual use,
+respectively.
@vindex holiday-bahai-holidays
@vindex holiday-christian-holidays
@code{calendar-hebrew-all-holidays-flag}, or
@code{calendar-islamic-all-holidays-flag} to @code{t}.
-@vindex holiday-other-holidays
- You can set the variable @code{holiday-other-holidays} to any list of
-holidays. This list, normally empty, is intended for individual use.
-
@cindex holiday forms
Each of the holiday variables is a list of @dfn{holiday forms}, each
-form describing a holiday (or sometimes a list of holidays).
-
- Here is a table of the possible kinds of holiday form. Day numbers
-and month numbers count starting from 1, but ``dayname'' numbers
-count Sunday as 0. The element @var{string} is always the
-description of the holiday, as a string.
+form describing a holiday (or sometimes a list of holidays). Here is
+a table of the possible kinds of holiday form. Day numbers and month
+numbers count starting from 1, but ``dayname'' numbers count Sunday as
+0. The argument @var{string} is always the description of the
+holiday, as a string.
@table @code
@item (holiday-fixed @var{month} @var{day} @var{string})
@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
so on).
- You can specify holidays that occur on fixed days of the Baha'i,
+ You can specify holidays that occur on fixed days of the Bahá'í,
Chinese, Hebrew, Islamic, and Julian calendars too. For example,
@smallexample
visible in the calendar window, with descriptive strings, like this:
@smallexample
-(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
+(((6 4 2012) "Lunar Eclipse") ((11 13 2012) "Solar Eclipse") ... )
@end smallexample
@node Date Display Format
@subsection Date Display Format
@vindex calendar-date-display-form
- You can customize the manner of displaying dates in the diary, in mode
-lines, and in messages by setting @code{calendar-date-display-form}.
+ You can customize the way dates are displayed in the diary, mode
+lines, and messages by setting @code{calendar-date-display-form}.
This variable holds a list of expressions that can involve the variables
@code{month}, @code{day}, and @code{year}, which are all numbers in
string form, and @code{monthname} and @code{dayname}, which are both
@end smallexample
@noindent
-This specifies a typical American format:
+Another typical American format is:
@smallexample
(month "/" day "/" (substring year -2))
Lisp Reference Manual}) or the symbols @code{month}, @code{day},
@code{year}, @code{monthname}, and @code{dayname}. All these elements
serve as patterns that match certain kinds of text in the diary file.
-In order for the date pattern, as a whole, to match, all of its elements
+In order for the date pattern as a whole to match, all of its elements
must match consecutively.
A regular expression in a date pattern matches in its usual fashion,
@end example
@noindent
-Other default styles are provided by @code{diary-european-date-forms}
-and @code{diary-iso-date-forms}.
+The variables @code{diary-european-date-forms} and
+@code{diary-iso-date-forms} provide other default styles.
The date patterns in the list must be @emph{mutually exclusive} and
must not match any portion of the diary entry itself, just the date and
@subsection Diary Entries Using non-Gregorian Calendars
As well as entries based on the standard Gregorian calendar, your
-diary can have entries based on Baha'i, Hebrew, or Islamic dates.
+diary can have entries based on Bahá'í, 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,
@end smallexample
@noindent
-Similarly, for Islamic and Baha'i entries, add
+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}.
@vindex diary-islamic-entry-symbol
These diary entries have the same formats as Gregorian-date diary
entries; except that @code{diary-bahai-entry-symbol} (default @samp{B})
-must precede a Baha'i date, @code{diary-hebrew-entry-symbol} (default
+must precede a Bahá'í 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).
Here is a table of commands used in the calendar to create diary
entries that match the selected date and other dates that are similar in
-the Baha'i, Hebrew, or Islamic calendars:
+the Bahá'í, Hebrew, or Islamic calendars:
@table @kbd
@item i h d
days to be shown in the fancy diary buffer, set the variable
@code{diary-list-include-blanks} to @code{t}.@refill
- The fancy diary buffer enables View mode (@pxref{View Mode}).
+ The fancy diary buffer enables View mode
+@iftex
+(@pxref{View Mode,,, emacs, the Emacs Manual}).
+@end iftex
+@ifnottex
+(@pxref{View Mode}).
+@end ifnottex
The alternative display method @code{diary-simple-display} shows the
actual diary buffer, and uses invisible text to hide entries that don't
hidden. After preparing the buffer, it runs the hook
@code{diary-print-entries-hook}. The default value of this hook sends
the data directly to the printer with the command @code{lpr-buffer}
-(@pxref{Printing}). If you want to use a different command to do the
+@iftex
+(@pxref{Printing,,, emacs, the Emacs Manual}).
+@end iftex
+@ifnottex
+(@pxref{Printing}).
+@end ifnottex
+If you want to use a different command to do the
printing, just change the value of this hook. Other uses might include,
for example, rearranging the lines into order by day and time.
variables @code{diary-comment-start} and @code{diary-comment-end} to
strings that delimit comments. The fancy display does not print
comments. You might want to put meta-data for the use of other packages
-(e.g. the appointment package,
+(e.g.@: the appointment package,
@iftex
@pxref{Appointments,,,emacs, the Emacs Manual})
@end iftex
@findex diary-cyclic
@smallexample
-%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
+%%(diary-cyclic 50 1 1 2012) Renew medication (%d%s time)
@end smallexample
@noindent
@end smallexample
@noindent
-in the fancy diary display on September 8, 1990.
+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
@item %%(diary-astro-day-number)
Make a diary entry with today's equivalent astronomical (Julian) day number.
@item %%(diary-bahai-date)
-Make a diary entry with today's equivalent Baha'i calendar date.
+Make a diary entry with today's equivalent Bahá'í calendar date.
@item %%(diary-chinese-date)
Make a diary entry with today's equivalent Chinese calendar date.
@item %%(diary-coptic-date)
-@c This is part of the Emacs manual.
+@c This is part of the Emacs manual. -*- coding: iso-latin-1 -*-
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
A week (or month, or year) is not just a quantity of days; we think of
weeks (months, years) as starting on particular dates. So Calendar mode
-provides commands to move to the beginning or end of a week, month or
-year:
+provides commands to move to the start or end of a week, month or year:
@table @kbd
@kindex C-a @r{(Calendar mode)}
Scroll calendar one month backward (@code{calendar-scroll-right}).
@item C-v
@itemx @key{next}
-Scroll calendar three months forward
-(@code{calendar-scroll-left-three-months}).
+Scroll three months forward (@code{calendar-scroll-left-three-months}).
@item M-v
@itemx @key{prior}
-Scroll calendar three months backward
-(@code{calendar-scroll-right-three-months}).
+Scroll three months backward (@code{calendar-scroll-right-three-months}).
@end table
@kindex > @r{(Calendar mode)}
@kindex M-= @r{(Calendar mode)}
@findex calendar-count-days-region
- To determine the number of days in the region, type @kbd{M-=}
+ 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-=}
(@code{calendar-count-days-region}). The numbers of days shown is
@emph{inclusive}; that is, it includes the days specified by mark and
point.
calendar deletes or iconifies that frame depending on the value of
@code{calendar-remove-frame-by-deleting}.)
+@c FIXME this mentions holidays and diary entries, albeit briefly, so
+@c should it be moved after those sections? Or at least xref them.
@node Writing Calendar Files
@section Writing Calendar Files
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
+argument, which specifies how many days, weeks, months or years to print
(starting always with the selected one).
If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
and can display them. You can add your own holidays to the default list.
@table @kbd
-@item h
+@item Mouse-3 Holidays
+@itemx h
Display holidays for the selected date
(@code{calendar-cursor-holidays}).
-@item Mouse-3 Holidays
-Display any holidays for the date you click on.
@item x
Mark holidays in the calendar window (@code{calendar-mark-holidays}).
@item u
holidays}, which prompts for the month and year.
The holidays known to Emacs include United States holidays and the
-major Baha'i, Chinese, Christian, Islamic, and Jewish holidays; also the
+major Bahá'í, Chinese, Christian, Islamic, and Jewish holidays; also the
solstices and equinoxes.
@findex list-holidays
times of sunrise and sunset for any date.
@table @kbd
-@item S
+@item Mouse-3 Sunrise/sunset
+@itemx S
Display times of sunrise and sunset for the selected date
(@code{calendar-sunrise-sunset}).
-@item Mouse-3 Sunrise/sunset
-Display times of sunrise and sunset for the date you click on.
@item M-x sunrise-sunset
Display times of sunrise and sunset for today's date.
@item C-u M-x sunrise-sunset
As a user, you might find it convenient to set the calendar location
variables for your usual physical location in your @file{.emacs} file.
-And when you install Emacs on a machine, you can create a
-@file{default.el} file which sets them properly for the typical location
-of most users of that machine. @xref{Init File}.
+If you are a system administrator, you may want to set these variables
+for all users in a @file{default.el} file. @xref{Init File}.
@node Lunar Phases
@section Phases of the Moon
it did not fully displace the Julian calendar and gain universal
acceptance until the early twentieth century. The Emacs calendar can
display any month since January, year 1 of the current era, but the
-calendar displayed is the Gregorian, even for a date at which the
-Gregorian calendar did not exist.
+calendar displayed is always the Gregorian, even for a date at which
+the Gregorian calendar did not exist.
While Emacs cannot display other calendars, it can convert dates to
and from several other calendars.
* Mayan Calendar:: Moving to a date specified in a Mayan calendar.
@end menu
+@c FIXME perhaps most of the details should be moved to cal-xtra.
+@c Just list the major supported systems here?
@node Calendar Systems
@subsection Supported Calendar Systems
@cindex ISO commercial calendar
- The ISO commercial calendar is used largely in Europe.
+ The ISO commercial calendar is often used in business.
@cindex Julian calendar
The Julian calendar, named after Julius Caesar, was the one used in Europe
the astronomical Persian calendar, which is based on astronomical
events. As of this writing the first future discrepancy is projected
to occur on March 20, 2025. It is currently not clear what the
-official calendar of Iran will be that far into the future.
+official calendar of Iran will be at that time.
+@c FIXME not so far in the future now.
@cindex Chinese calendar
The Chinese calendar is a complicated system of lunar months arranged
twelve ``terrestrial branches'' for a total of sixty names that are
repeated in a cycle of sixty.
-@cindex Baha'i calendar
- The Baha'i calendar system is based on a solar cycle of 19 months with
+@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
between the 18th and 19th months.
in various other calendar systems:
@table @kbd
-@item Mouse-3 Other calendars
-Display the date that you click on, expressed in various other calendars.
@kindex p @r{(Calendar mode)}
@findex calendar-print-other-dates
-@item p o
+@item Mouse-3 Other calendars
+@itemx p o
Display the selected date in various other calendars.
(@code{calendar-print-other-dates}).
@findex calendar-iso-print-date
(@code{calendar-french-print-date}).
@findex calendar-bahai-print-date
@item p b
-Display Baha'i date for selected day
+Display Bahá'í date for selected day
(@code{calendar-bahai-print-date}).
@findex calendar-chinese-print-date
@item p C
Display Mayan date for selected day (@code{calendar-mayan-print-date}).
@end table
- If you are using a graphic display, the easiest way to translate a
-date into other calendars is to click on it with @kbd{Mouse-3}, then
-choose @kbd{Other calendars} from the menu that appears. This displays
-the equivalent forms of the date in all the calendars Emacs understands,
-in the form of a menu. (Choosing an alternative from this menu doesn't
-actually do anything---the menu is used only for display.)
-
Otherwise, move point to the date you want to convert, then type the
appropriate command starting with @kbd{p} from the table above. The
prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the
equivalent date in the echo area. @kbd{p o} displays the
-date in all forms known to Emacs.
+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
+understands, in the form of a menu. (Choosing an alternative from
+this menu doesn't actually do anything---the menu is used only for
+display.)
@node From Other Calendar
@subsection Converting From Other Calendars
Move to a date specified with an astronomical (Julian) day number
(@code{calendar-astro-goto-day-number}).
@item g b
-Move to a date specified in the Baha'i calendar
+Move to a date specified in the Bahá'í calendar
(@code{calendar-bahai-goto-date}).
@item g h
Move to a date specified in the Hebrew calendar
@c FIXME move?
@findex calendar-hebrew-list-yahrzeits
@cindex yahrzeits
- One common question concerning the Hebrew calendar is the computation
+ One common issue concerning the Hebrew calendar is the computation
of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
calendar includes a facility for such calculations. If you are in the
calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for
this command first asks you for the date of death and the range of
years, and then displays the list of yahrzeit dates.
+@c FIXME move to emacs-xtra.
@node Mayan Calendar
@subsection Converting from the Mayan Calendar
@findex calendar-mayan-next-haab-date
@cindex Mayan haab calendar
The Mayan haab calendar is a cycle of 365 days arranged as 18 months
-of 20 days each, followed a 5-day monthless period. Like the tzolkin
+of 20 days each, followed by a 5-day monthless period. Like the tzolkin
cycle, this cycle repeats endlessly, and there are commands to move
backward and forward to the previous or next point in the cycle. Type
@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
showing what that file looks like:
@example
-12/22/1988 Twentieth wedding anniversary!!
+12/22/2012 Twentieth wedding anniversary!!
&1/1. Happy New Year!
10/22 Ruth's birthday.
* 21, *: Payday
1/13/89 Friday the thirteenth!!
&thu 4pm squash game with Lloyd.
mar 16 Dad's birthday
-April 15, 1989 Income tax due.
+April 15, 2013 Income tax due.
&* 15 time cards due.
@end example
@noindent
-This format is essentially the same as the one used by the system's
-@command{calendar} utility. This example uses extra spaces to align
-the event descriptions of most of the entries. Such formatting is
-purely a matter of taste.
+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.
Although you probably will start by creating a diary manually, Emacs
provides a number of commands to let you view, add, and change diary
following, key bindings refer to the Calendar buffer.
@table @kbd
-@item d
+@item Mouse-3 Diary
+@itemx d
Display all diary entries for the selected date
(@code{diary-view-entries}).
-@item Mouse-3 Diary
-Display all diary entries for the date you click on.
@item s
Display the entire diary file (@code{diary-show-all-entries}).
@item m
@xref{Calendar Customizing, diary-entry-marker}.
@end ifnottex
- The command applies both to the currently visible months and to
-other months that subsequently become visible by scrolling. To turn
+ This command applies both to the months that are currently visible
+and to those that subsequently become visible after scrolling. To turn
marking off and erase the current marks, type @kbd{u}, which also
turns off holiday marks (@pxref{Holidays}). If the variable
@code{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or
@end ifnottex
If you put @code{(diary)} in your @file{.emacs} file, this
-automatically displays a window with the day's diary entries, when you
-enter Emacs.
+automatically displays a window with the day's diary entries when you
+start Emacs.
@findex diary-mail-entries
@vindex diary-mail-days
- Many users like to receive notice of events in their diary as email.
-To send such mail to yourself, use the command @kbd{M-x
+ Some people like to receive email notifications of events in their
+diary. To send such mail to yourself, use the command @kbd{M-x
diary-mail-entries}. A prefix argument specifies how many days
(starting with today) to check; otherwise, the variable
@code{diary-mail-days} says how many days.
punctuation). For example:
@example
-02/11/1989
+02/11/2012
Bill B. visits Princeton today
2pm Cognitive Studies Committee meeting
2:30-5:30 Liz at Lawrenceville
@vindex diary-nonmarking-symbol
You can inhibit the marking of certain diary entries in the calendar
-window; to do this, insert an ampersand @code{diary-nonmarking-symbol}
-(default @samp{&}) at the beginning of the entry, before the date. This
-has no effect on display of the entry in the diary window; it affects
-only marks on dates in the calendar window. Nonmarking entries are
+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.
month, year) and ISO order (year, month, day) as options.
@example
-4/20/93 Switch-over to new tabulation system
+4/20/12 Switch-over to new tabulation system
apr. 25 Start tabulating annual results
4/30 Results for April are due
*/25 Monthly cycle finishes
Friday Don't leave without backing up files
@end example
- The first entry appears only once, on April 20, 1993. The second and
+ The first entry appears only once, on April 20, 2012. The second and
third appear every year on the specified dates, and the fourth uses a
wildcard (asterisk) for the month, so it appears on the 25th of every
month. The final entry appears every week on Friday.
This must be followed by a nondigit. In the date itself, @var{month}
and @var{day} are numbers of one or two digits. The optional @var{year}
is also a number, and may be abbreviated to the last two digits; that
-is, you can use @samp{11/12/1989} or @samp{11/12/89}.
+is, you can use @samp{11/12/2012} or @samp{11/12/12}.
Dates can also have the form @samp{@var{monthname} @var{day}} or
@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
A date may be @dfn{generic}; that is, partially unspecified. Then the
entry applies to all dates that match the specification. If the date
does not contain a year, it is generic and applies to any year.
-Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
+Alternatively, @var{month}, @var{day}, or @var{year} can be @samp{*};
this matches any month, day, or year, respectively. Thus, a diary entry
@samp{3/*/*} matches any day in March of any year; so does @samp{march
*}.
yearly diary entry with the @kbd{i y} command.
All of the above commands make marking diary entries by default. To
-make a nonmarking diary entry, give a numeric argument to the command.
+make a nonmarking diary entry, give a prefix argument to the command.
For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
When you modify the diary file, be sure to save the file before
A @dfn{block} diary entry applies to a specified range of consecutive
dates. Here is a block diary entry that applies to all dates from June
-24, 1990 through July 10, 1990:
+24, 2012 through July 10, 2012:
@findex diary-block
@example
-%%(diary-block 6 24 1990 7 10 1990) Vacation
+%%(diary-block 6 24 2012 7 10 2012) Vacation
@end example
@noindent
-The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
+The @samp{6 24 2012} indicates the starting date and the @samp{7 10 2012}
indicates the stopping date. (Again, if you are using the European or ISO
calendar style, the input order of month, day and year is different.)
@findex diary-cyclic
@example
-%%(diary-cyclic 50 3 1 1990) Renew medication
+%%(diary-cyclic 50 3 1 2012) Renew medication
@end example
@noindent
-This entry applies to March 1, 1990 and every 50th day following;
-@samp{3 1 1990} specifies the starting date. (If you are using the
+This entry applies to March 1, 2012 and every 50th day following;
+@samp{3 1 2012} specifies the starting date. (If you are using the
European or ISO calendar style, the input order of month, day and year
is different.)
All three of these commands make marking diary entries. To insert a
-nonmarking entry, give a numeric argument to the command. For example,
+nonmarking entry, give a prefix argument to the command. For example,
@kbd{C-u i a} makes a nonmarking anniversary diary entry.
- Marking sexp diary entries in the calendar is @emph{extremely}
-time-consuming, since every date visible in the calendar window must be
-individually checked. So it's a good idea to make sexp diary entries
-nonmarking (with @samp{&}) when possible.
+ Marking sexp diary entries in the calendar can be time-consuming,
+since every date visible in the calendar window must be individually
+checked. So it's a good idea to make sexp diary entries nonmarking
+(with @samp{&}) when possible.
Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
specifies a regularly occurring event by offsets specified in days,
@vindex appt-audible
@vindex appt-display-mode-line
If you have a diary entry for an appointment, and that diary entry
-begins with a recognizable time of day, Emacs can warn you several
-minutes beforehand that that appointment is pending. Emacs alerts you
+begins with a recognizable time of day, Emacs can warn you in advance
+that an appointment is pending. Emacs alerts you
to the appointment by displaying a message in your chosen format, as
specified by the variable @code{appt-display-format}. If the value of
@code{appt-audible} is non-@code{nil}, the warning includes an audible
recognize additional appointment message formats by customizing the
variable @code{diary-outlook-formats}.
+@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
@findex icalendar-import-buffer
The command @code{icalendar-import-buffer} extracts
-iCalendar data from the current buffer and adds it to your (default)
+iCalendar data from the current buffer and adds it to your
diary file. This function is also suitable for automatic extraction of
iCalendar data; for example with the Rmail mail client one could use:
Use @code{icalendar-export-file} to interactively export an entire
Emacs diary file to iCalendar format. To export only a part of a diary
file, mark the relevant area, and call @code{icalendar-export-region}.
-In both cases the result is appended to the target file.
+In both cases, Emacs appends the result to the target file.
@node Daylight Saving
@section Daylight Saving Time
@vindex timeclock-ask-before-exiting
Terminating the current Emacs session might or might not mean that
you have stopped working on the project and, by default, Emacs asks
-you. You can, however, set customize the value of the variable
+you. You can, however, customize the value of the variable
@code{timeclock-ask-before-exiting} to @code{nil} to avoid the question;
then, only an explicit @kbd{M-x timeclock-out} or @kbd{M-x
timeclock-change} will tell Emacs that the current interval is over.
@c This is part of the Emacs manual.
-@c Copyright (C) 2004-2012 Free Software Foundation, Inc.
+@c Copyright (C) 2004-2012 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
You can insert subdirectories with specified @command{ls} switches in
Dired buffers using @kbd{C-u i}. You can change the @command{ls}
-switches of an already inserted subdirectory using @kbd{C-u l}.
+switches of an already inserted subdirectory at point using @kbd{C-u l}.
Dired preserves the switches if you revert the buffer. Deleting a
subdirectory forgets about its switches.
-Using @code{dired-undo} (@pxref{Marks vs Flags}) to reinsert or delete
+Using @code{dired-undo}
+@iftex
+(@pxref{Marks vs Flags,,, emacs, the Emacs Manual})
+@end iftex
+@ifnottex
+(@pxref{Marks vs Flags})
+@end ifnottex
+to reinsert or delete
subdirectories that were inserted with explicit switches can bypass
Dired's machinery for remembering (or forgetting) switches. Deleting
a subdirectory using @code{dired-undo} does not forget its switches.
* Highlight Interactively:: Tell Emacs what text to highlight.
* Fringes:: Enabling or disabling window fringes.
* Displaying Boundaries:: Displaying top and bottom of the buffer.
-* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
+* Useless Whitespace:: Showing possibly spurious trailing whitespace.
* Selective Display:: Hiding lines with lots of indentation.
* Optional Mode Line:: Optional mode line display features.
* Text Display:: How text characters are normally displayed.
@copying
This manual describes specialized features of Emacs.
-Copyright @copyright{} 2004-2012
-Free Software Foundation, Inc.
+Copyright @copyright{} 2004-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
+@documentencoding ISO-8859-1
+
@dircategory Emacs
@direntry
* Emacs-Xtra: (emacs-xtra). Specialized Emacs features.
* Emerge:: A convenient way of merging two versions of a program.
* Advanced VC Usage:: Advanced VC (version control) features.
* Fortran:: Fortran mode and its special features.
-* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}).
+* MS-DOS:: Using Emacs on MS-DOS.
@end iftex
* Index::
@end menu
the Emacs manual.
@iftex
-@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections.
-@include picture-xtra.texi
@raisesections
+@include picture-xtra.texi
+
@include arevert-xtra.texi
@include dired-xtra.texi
This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@*
updated for Emacs version @value{EMACSVER}.
-Copyright @copyright{} 1985-1987, 1993-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 1985-1987, 1993-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
Emacs is the extensible, customizable, self-documenting real-time
display editor. This Info file describes how to edit with Emacs and
-some of how to customize it; it corresponds to GNU Emacs version
+some of the ways to customize it; it corresponds to GNU Emacs version
@value{EMACSVER}.
@ifinfo
-To learn more about the Info documentation system, type @kbd{h},
-to visit a programmed instruction sequence for the Info commands.
+If you are reading this in Emacs, type @kbd{h} to read a basic
+introduction to the Info documentation system.
@end ifinfo
For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The
@insertcopying
@end ifnottex
+@c Note that the TeX version generates its own TOC, so the ifnottex's
+@c here are not really necessary.
@menu
* Distrib:: How to get the latest Emacs distribution.
* Intro:: An introduction to Emacs concepts.
Important Text-Changing Commands
* Mark:: The mark: how to delimit a "region" of text.
-* Killing:: Killing (cutting) text.
-* Yanking:: Recovering killed text. Moving text. (Pasting.)
-* Cut and Paste:: Clipboard and selections on graphical displays.
-* Accumulating Text:: Other ways of copying text.
-* Rectangles:: Operating on text in rectangular areas.
-* CUA Bindings:: Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} to kill and yank.
+* Killing:: Killing (cutting) and yanking (copying) text.
* Registers:: Saving a text string or a location in the buffer.
* Display:: Controlling what text is displayed.
* Search:: Finding or replacing occurrences of a string.
Major Structures of Emacs
* Files:: All about handling files.
* Buffers:: Multiple buffers; editing several files at once.
-* Windows:: Viewing two pieces of text at once.
-* Frames:: Running the same Emacs session in multiple X windows.
+* Windows:: Viewing multiple pieces of text in one frame.
+* Frames:: Using multiple ``windows'' on your display.
* International:: Using non-@acronym{ASCII} character sets.
Advanced Features
* Programs:: Commands and modes for editing programs.
* Building:: Compiling, running and debugging programs.
* Maintaining:: Features for maintaining large programs.
-* Abbrevs:: Defining text abbreviations to reduce
- the number of characters you must type.
+* Abbrevs:: Defining text abbreviations to reduce typing.
* Dired:: Directory and file manager.
* Calendar/Diary:: Calendar and diary facilities.
* Sending Mail:: Sending mail in Emacs.
@ifnottex
* Picture Mode:: Editing pictures made up of text characters.
@end ifnottex
-* Editing Binary Files:: Editing binary files with Hexl mode.
+* 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.
Killing and Moving Text
+* Deletion and Killing:: Commands that remove text.
+* Yanking:: Recovering killed text. Moving text. (Pasting.)
+* Cut and Paste:: Clipboard and selections on graphical displays.
+* Accumulating Text:: Other ways of copying text.
+* Rectangles:: Operating on text in rectangular areas.
+* CUA Bindings:: Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} to kill and yank.
+
+Deletion and Killing
+
* Deletion:: Commands for deleting small amounts of text and
blank areas.
* Killing by Lines:: How to kill entire lines of text at one time.
* Highlight Interactively:: Tell Emacs what text to highlight.
* Fringes:: Enabling or disabling window fringes.
* Displaying Boundaries:: Displaying top and bottom of the buffer.
-* Useless Whitespace:: Showing possibly-spurious trailing whitespace.
+* Useless Whitespace:: Showing possibly spurious trailing whitespace.
* Selective Display:: Hiding lines with lots of indentation.
* Optional Mode Line:: Optional mode line display features.
* Text Display:: How text characters are normally displayed.
* Basic Keyboard Macro:: Defining and running keyboard macros.
* Keyboard Macro Ring:: Where previous keyboard macros are saved.
* Keyboard Macro Counter:: Inserting incrementing numbers in macros.
-* Keyboard Macro Query:: Making keyboard macros do different things each time.
-* Save Keyboard Macro:: Giving keyboard macros names; saving them in files.
+* Keyboard Macro Query:: Making keyboard macros do different things each
+ time.
+* Save Keyboard Macro:: Giving keyboard macros names; saving them in
+ files.
* Edit Keyboard Macro:: Editing keyboard macros.
* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard
macro.
* Visiting:: Visiting a file prepares Emacs to edit the file.
* Saving:: Saving makes your changes permanent.
* Reverting:: Reverting cancels all the changes not saved.
+@ifnottex
* Autorevert:: Auto Reverting non-file buffers.
+@end ifnottex
* Auto Save:: Auto Save periodically protects against loss of data.
* File Aliases:: Handling multiple names for one file.
* Directories:: Creating, deleting, and listing file directories.
* Misc File Ops:: Other things you can do on files.
* Compressed Files:: Accessing compressed files.
* File Archives:: Operating on tar, zip, jar etc. archive files.
-* Remote Files:: Accessing files on other sites.
+* Remote Files:: Accessing files on other machines.
* Quoted File Names:: Quoting special characters in file names.
* File Name Cache:: Completion against a list of files you often use.
* File Conveniences:: Convenience Features for Finding Files.
* Backup Deletion:: Emacs deletes excess numbered backups.
* Backup Copying:: Backups can be made by copying or renaming.
+@ifnottex
Auto Reverting Non-File Buffers
* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu.
* Auto Reverting Dired:: Auto Revert of Dired buffers.
* Supporting additional buffers:: How to add more Auto Revert support.
+@end ifnottex
Auto-Saving: Protection Against Disasters
* Displaying Buffers:: How Emacs picks a window for displaying a buffer.
* Window Convenience:: Convenience functions for window handling.
+Displaying Buffers
+
+* Window Choice:: How @code{display-buffer} works.
+
Frames and Graphical Displays
* Mouse Commands:: Moving, cutting, and pasting, with the mouse.
* Frame Commands:: Iconifying, deleting, and switching frames.
* Fonts:: Changing the frame font.
* Speedbar:: How to make and use a speedbar frame.
-* Multiple Displays:: How one Emacs job can talk to several displays.
+* 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.
* Drag and Drop:: Using drag and drop to open files and insert text.
* Unibyte Mode:: You can pick one European character set
to use without multibyte characters.
* Charsets:: How Emacs groups its internal character codes.
+* Bidirectional Editing:: Support for right-to-left scripts.
Modes
* Text Mode:: The major modes for editing text files.
* Outline Mode:: Editing outlines.
* Org Mode:: The Emacs organizer.
-* TeX Mode:: Editing input to the formatter TeX.
+* TeX Mode:: Editing TeX and LaTeX files.
* HTML Mode:: Editing HTML and SGML files.
-* Nroff Mode:: Editing input to the formatter nroff.
+* Nroff Mode:: Editing input to the nroff formatter.
* 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.
Outline Mode
* Outline Format:: What the text of an outline looks like.
-* Outline Motion:: Special commands for moving through
- outlines.
+* Outline Motion:: Special commands for moving through outlines.
* Outline Visibility:: Commands to control what is visible.
* Outline Views:: Outlines and multiple views.
* Foldout:: Folding means zooming in on outlines.
+Org Mode
+
+* Org Organizer:: Managing TODO lists and agendas.
+* Org Authoring:: Exporting Org buffers to various formats.
+
@TeX{} Mode
* TeX Editing:: Special commands for editing in TeX mode.
* 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, and Pike modes.
+ Java, IDL, Pike and AWK modes.
* Asm Mode:: Asm mode and its special features.
+@ifnottex
* Fortran:: Fortran mode and its special features.
+@end ifnottex
Top-Level Definitions, or Defuns
Documentation Lookup
-* Info Lookup:: Looking up library functions and commands
- in Info files.
-* Man Page:: Looking up man pages of library functions and commands.
-* Lisp Doc:: Looking up Emacs Lisp functions, etc.
+* Info Lookup:: Looking up library functions and commands in Info files.
+* Man Page:: Looking up man pages of library functions and commands.
+* Lisp Doc:: Looking up Emacs Lisp functions, etc.
C and Related Modes
* Other C Commands:: Filling comments, viewing expansion of macros,
and other neat features.
+@ifnottex
Fortran Mode
* Fortran Motion:: Moving point by statements or subprograms.
* ForIndent Num:: How line numbers auto-indent.
* ForIndent Conv:: Conventions you must obey to avoid trouble.
* ForIndent Vars:: Variables controlling Fortran indent style.
+@end ifnottex
Compiling and Testing Programs
* Commands of GUD:: Key bindings for common commands.
* GUD Customization:: Defining your own commands for GUD.
* GDB Graphical Interface:: An enhanced mode that uses GDB features to
- implement a graphical debugging environment through
- Emacs.
+ implement a graphical debugging environment.
GDB Graphical Interface
* Tags:: Go directly to any function in your program in one
command. Tags remembers which file it is in.
* EDE:: An integrated development environment for Emacs.
+@ifnottex
* Emerge:: A convenient way of merging two versions of a program.
+@end ifnottex
Version Control
* VC Undo:: Canceling changes before or after committing.
* VC Directory Mode:: Listing files managed by version control.
* Branches:: Multiple lines of development.
-* Revision Tags:: Symbolic names for revisions.
+@ifnottex
* Miscellaneous VC:: Various other commands and features of VC.
* Customizing VC:: Variables that change VC's behavior.
+@end ifnottex
Introduction to Version Control
* Merging:: Transferring changes between branches.
* Creating Branches:: How to start a new branch.
+@ifnottex
Miscellaneous Commands and Features of VC
* Change Logs and VC:: Generating a change log file from log entries.
* General VC Options:: Options that apply to multiple back ends.
* RCS and SCCS:: Options for RCS and SCCS.
* CVS Options:: Options for CVS.
+@end ifnottex
Change Logs
* Tags Search:: Using a tags table for searching and replacing.
* List Tags:: Listing and finding tags defined in a file.
+@ifnottex
Merging Files with Emerge
* Overview of Emerge:: How to start Emerge. Basic concepts.
* Exiting Emerge:: What to do when you've finished the merge.
* Combining in Emerge:: How to keep both alternatives for a difference.
* Fine Points of Emerge:: Miscellaneous issues.
+@end ifnottex
Abbrevs
* Transforming File Names:: Using patterns to rename multiple files.
* Comparison in Dired:: Running `diff' by way of Dired.
* Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
+@ifnottex
* Subdir Switches:: Subdirectory switches in Dired.
+@end ifnottex
* Subdirectory Motion:: Moving across subdirectories, and up and down.
* Hiding Subdirectories:: Making subdirectories visible or invisible.
* Dired Updating:: Discarding lines for files of no interest.
* Diary:: Displaying events from your diary.
* Appointments:: Reminders when it's time to do something.
* Importing Diary:: Converting diary events to/from other formats.
-* Daylight Saving:: How to specify when daylight saving time is active.
+* Daylight Saving:: How to specify when daylight saving time is active.
* Time Intervals:: Keeping track of time intervals.
+@ifnottex
* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
+@end ifnottex
Movement in the Calendar
* Adding to Diary:: Commands to create diary entries.
* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
+@ifnottex
Customizing the Calendar and Diary
* Calendar Customizing:: Calendar layout and hooks.
* Diary Display:: A choice of ways to display the diary.
* Fancy Diary Display:: Sorting diary entries, using included diary files.
* Sexp Diary Entries:: More flexible diary entries.
+@end ifnottex
Document Viewing
Rmail Summaries
-* Rmail Make Summary:: Making various sorts of summaries.
-* Rmail Summary Edit:: Manipulating messages from the summary.
+* Rmail Make Summary:: Making various sorts of summaries.
+* Rmail Summary Edit:: Manipulating messages from the summary.
Gnus
* Windows Printing:: How to specify the printer on MS-Windows.
* Windows Fonts:: Specifying fonts on MS-Windows.
* Windows Misc:: Miscellaneous Windows features.
-* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}).
+@ifnottex
+* MS-DOS:: Using Emacs on MS-DOS.
Emacs and MS-DOS
* MS-DOS Printing:: Printing specifics on MS-DOS.
* MS-DOS and MULE:: Support for internationalization on MS-DOS.
* MS-DOS Processes:: Running subprocesses on MS-DOS.
+@end ifnottex
@end detailmenu
@end menu
the integrated, learn-by-doing tutorial, before reading the manual. To
run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial
describes commands, tells you when to try them, and explains the
-results.
+results. The tutorial is available in several languages.
On first reading, just skim chapters 1 and 2, which describe the
notational conventions of the manual and the general appearance of the
Read the Common Problems chapter if Emacs does not seem to be
working properly. It explains how to cope with several common
-problems (@pxref{Lossage}), as well as when and how to report Emacs
-bugs (@pxref{Bugs}).
+problems (@pxref{Lossage,, Dealing with Emacs Trouble}), as well as
+when and how to report Emacs bugs (@pxref{Bugs}).
To find the documentation of a particular command, look in the index.
Keys (character commands) and command names have separate indexes.
There is also a glossary, with a cross reference for each term.
This manual is available as a printed book and also as an Info file.
-The Info file is for use with the Info program, which is the principal
-means of accessing on-line documentation in the GNU system. Both the
-Emacs Info file and an Info reader are included with GNU Emacs. The
-Info file and the printed book contain substantially the same text and
-are generated from the same source files, which are also distributed
-with GNU Emacs.
+The Info file is for reading from Emacs itself, or with the Info program.
+Info is the principal format for documentation in the GNU system.
+The Info file and the printed book contain substantially the same text
+and are generated from the same source files, which are also
+distributed with GNU Emacs.
GNU Emacs is a member of the Emacs editor family. There are many
Emacs editors, all sharing common principles of organization. For
Customizable Self-Documenting Display Editor}, available from
@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}.
-This edition of the manual is intended for use with GNU Emacs
+This version of the manual is mainly intended for use with GNU Emacs
installed on GNU and Unix systems. GNU Emacs can also be used on
-MS-DOS (also called MS-DOG), Microsoft Windows, and Macintosh systems.
-Those systems use different file name syntax; in addition
-MS-DOS does not support all GNU Emacs features. @xref{Microsoft
-Windows}, for information about using Emacs on Windows.
-@xref{Mac OS / GNUstep}, for information about using Emacs on
-Macintosh (and GNUstep).
+MS-DOS, Microsoft Windows, and Macintosh systems. The Info file
+version of this manual contains some more information about using
+Emacs on those systems. Those systems use different file name syntax;
+in addition MS-DOS does not support all GNU Emacs features.
+@xref{Microsoft Windows}, for information about using Emacs on
+Windows. @xref{Mac OS / GNUstep}, for information about using Emacs
+on Macintosh (and GNUstep).
@end iftex
@node Distrib, Intro, Top, Top
@unnumbered Distribution
GNU Emacs is @dfn{free software}; this means that everyone is free to
-use it and free to redistribute it on certain conditions. GNU Emacs
+use it and free to redistribute it under certain conditions. GNU Emacs
is not in the public domain; it is copyrighted and there are
restrictions on its distribution, but these restrictions are designed
to permit everything that a good cooperating citizen would want to do.
any version of GNU Emacs that they might get from you. The precise
conditions are found in the GNU General Public License that comes with
Emacs and also appears in this manual@footnote{This manual is itself
-covered by the GNU Free Documentation License (see the reverse title
-page in the printed manual or view the full source for online formats
-to see the precise conditions). This license is similar in spirit to
-the General Public License, but is more suitable for documentation.
-@xref{GNU Free Documentation License}.}. @xref{Copying}.
+covered by the GNU Free Documentation License. This license is
+similar in spirit to the General Public License, but is more suitable
+for documentation. @xref{GNU Free Documentation License}.}.
+@xref{Copying}.
One way to get a copy of GNU Emacs is from someone else who has it.
You need not ask for our permission to do so, or tell any one else;
General Public License. In other words, the program must be free for you
when you get it, not just free for the manufacturer.
-@c FIXME no longer true?
-You can also order copies of GNU Emacs from the Free Software
-Foundation. This is a convenient and reliable way to get a copy; it is
-also a good way to help fund our work. We also sell hardcopy versions
-of this manual and @cite{An Introduction to Programming in Emacs Lisp},
-by Robert J. Chassell. You can visit our online store at
-@url{http://shop.fsf.org/}. For further information,
-write to
+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
+@url{http://www.gnu.org/help/help.html}.
+
+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/}.
+The income from sales goes to support the foundation's purpose: the
+development of new free software, and improvements to our existing
+programs including GNU Emacs.
+
+If you need to contact the Free Software Foundation, see
+@url{http://www.fsf.org/about/contact/}, or write to
@display
Free Software Foundation
USA
@end display
-The income from sales goes to support the foundation's purpose: the
-development of new free software, and improvements to our existing
-programs including GNU Emacs.
-
-@c FIXME you can't order a CD any more.
-If you find GNU Emacs useful, please @strong{send a donation} to the
-Free Software Foundation to support our work. Donations to the Free
-Software Foundation are tax deductible in the US. If you use GNU Emacs
-at your workplace, please suggest that the company make a donation. If
-company policy is unsympathetic to the idea of donating to charity, you
-might instead suggest ordering a CD-ROM from the Foundation
-occasionally, or subscribing to periodic updates.
-
@iftex
@node Acknowledgments, Intro, Distrib, Top
@unnumberedsec Acknowledgments
Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas
-Abrahamsson, Jay K.@: Adams, Michael Albinus, Nagy Andras, Ralf
-Angeli, Joe Arceneaux, Miles Bader, David Bakhash, Juanma Barranquero,
-Eli Barzilay, Thomas Baumann, Steven L.@: Baur, Jay Belanger,
-Alexander L.@: Belikoff, Boaz Ben-Zvi, Karl Berry, Anna M.@: Bigatti,
-Ray Blaak, Jim Blandy, Johan Bockgård, Jan Böcker, Lennart Borgman,
-Per Bothner, Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel
-Briot, Kevin Broadey, Vincent Broman, David M.@: Brown, Georges
-Brun-Cottan, Joe Buehler, W@l{}odek Bzyl, Bill Carpenter, Per
-Cederqvist, Hans Chalupsky, Chong Yidong, Chris Chase, Bob Chassell,
-Andrew Choi, Sacha Chua, James Clark, Mike Clarkson, Glynn Clements,
-Daniel Colascione, Ludovic Courtès, Andrew Csillag, Baoqiu Cui, Doug
-Cutting, Mathias Dahl, Julien Danjou, Satyaki Das, Vivek Dasmohapatra,
-Michael DeCorte, Gary Delp, Matthieu Devin, Eri Ding, Jan Djärv,
-Carsten Dominik, Scott Draves, Benjamin Drieu, Viktor Dukhovni, Dmitry
-Dzhus, John Eaton, Rolf Ebert, Paul Eggert, Stephen Eglen, Torbjörn
-Einarsson, Tsugutomo Enami, Hans Henrik Eriksen, Michael Ernst, Ata
-Etemadi, Frederick Farnbach, Oscar Figueiredo, Fred Fish, Karl Fogel,
-Gary Foster, Romain Francoise, Noah Friedman, Andreas Fuchs, Hallvard
-Furuseth, Keith Gabryelski, Peter S.@: Galbraith, Kevin Gallagher,
-Kevin Gallo, Juan León Lahoz García, Howard Gayle, Daniel German,
-Stephen Gildea, Julien Gilles, David Gillespie, Bob Glickstein, Deepak
-Goel, Boris Goldowsky, Michelangelo Grigni, Odd Gripenstam, Kai
-Großjohann, Michael Gschwind, Bastien Guerry, Henry Guillaume, Doug
-Gwyn, Ken'ichi Handa, Lars Hansen, Chris Hanson, Jesper Harder,
-Alexandru Harsanyi, K.@: Shane Hartman, John Heidemann, Jon K.@:
-Hellan, Magnus Henoch, Markus Heritsch, Karl Heuer, Manabu Higashida,
-Anders Holst, Jeffrey C.@: Honig, Tassilo Horn, Kurt Hornik, Tom
-Houlder, Joakim Hove, Denis Howe, Lars Ingebrigtsen, Andrew Innes,
-Seiichiro Inoue, Philip Jackson, Pavel Janik, Paul Jarc, Ulf Jasper,
-Michael K.@: Johnson, Kyle Jones, Terry Jones, Simon Josefsson, Arne
-Jørgensen, Tomoji Kagatani, Brewster Kahle, Tokuya Kameshima, Lute
-Kamstra, David Kastrup, David Kaufman, Henry Kautz, Taichi Kawabata,
+Abrahamsson, Jay K.@: Adams, Alon Albert, Michael Albinus, Nagy
+Andras, Benjamin Andresen, Ralf Angeli, 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
+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
+Broadey, Vincent Broman, Michael Brouwer, David M.@: Brown, Stefan Bruda,
+Georges Brun-Cottan, Joe Buehler, Scott Byer, W@l{}odek Bzyl,
+Bill Carpenter, Per Cederqvist, Hans Chalupsky, Chris Chase, Bob
+Chassell, Andrew Choi, Chong Yidong, Sacha Chua, Stewart Clamen, James
+Clark, Mike Clarkson, Glynn Clements, Andrew Cohen, Daniel Colascione,
+Edward O'Connor, Christoph Conrad, Ludovic Courtès, Andrew Csillag,
+Toby Cubitt, Baoqiu Cui, Doug Cutting, Mathias Dahl, Julien Danjou, Satyaki
+Das, Vivek Dasmohapatra, Dan Davison, Michael DeCorte, Gary Delp, Nachum
+Dershowitz, Dave Detlefs, Matthieu Devin, Christophe de Dinechin, Eri
+Ding, Jan Djärv, Lawrence R.@: Dodd, Carsten Dominik, Scott Draves,
+Benjamin Drieu, Viktor Dukhovni, Jacques Duthen, Dmitry Dzhus, John
+Eaton, Rolf Ebert, Carl Edman, David Edmondson, Paul Eggert, Stephen
+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.@:
+Galbraith, Kevin Gallagher, 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
+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,
+Jeffrey C.@: Honig, Tassilo Horn, Kurt Hornik, Tom Houlder, Joakim
+Hove, Denis Howe, Lars Ingebrigtsen, Andrew Innes, Seiichiro Inoue,
+Philip Jackson, Martyn Jago, Pavel Janik, Paul Jarc, Ulf Jasper,
+Thorsten Jolitz, Michael K.@: Johnson, Kyle Jones, Terry Jones, Simon
+Josefsson, Alexandre Julliard, Arne Jørgensen, Tomoji Kagatani,
+Brewster Kahle, Tokuya Kameshima, Lute Kamstra, Ivan Kanis, David
+Kastrup, David Kaufman, Henry Kautz, Taichi Kawabata, Taro Kawagishi,
Howard Kaye, Michael Kifer, Richard King, Peter Kleiweg, Karel
-Klí@v{c}, Shuhei Kobayashi, Pavel Kobiakov, Larry K.@: Kolodney, David
+Klí@v{c}, Shuhei Kobayashi, Pavel Kobyakov, Larry K.@: Kolodney, David
M.@: Koppelman, Koseki Yoshinori, Robert Krawitz, Sebastian Kremer,
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, Lars
-Lindberg, Chris Lindblad, Anders Lindgren, Thomas Link, Juri Linkov,
-Francis Litterio, Emilio C.@: Lopes, Károly L@H{o}rentey, Dave Love,
-Sascha Lüdecke, Eric Ludlam, Alan Mackenzie, Christopher J.@: Madsen,
-Neil M.@: Mager, Ken Manheimer, Bill Mann, Brian Marick, Simon
-Marshall, Bengt Martensson, Charlie Martin, Thomas May, Roland
-McGrath, Will Mengarini, David Megginson, Ben A.@: Mesander, Wayne
-Mesard, Brad Miller, Lawrence Mitchell, Richard Mlynarik, Gerd
-Moellmann, Stefan Monnier, Morioka Tomohiko, Keith Moore, Jan
-Moringen, Glenn Morris, Diane Murray, Sen Nagata, Erik Naggum, Thomas
-Neumann, Thien-Thi Nguyen, Mike Newton, Jurgen Nickelsen, Dan
-Nicolaescu, Hrvoje Niksic, Jeff Norden, Andrew Norman, Christian
-Ohler, Alexandre Oliva, Bob Olson, Michael Olson, Takaaki Ota, Pieter
-E.@: J.@: Pareit, Ross Patterson, David Pearson, Jeff Peck, Damon
-Anton Permezel, Tom Perrine, William M.@: Perry, Per Persson, Jens
-Petersen, Daniel Pfeiffer, Richard L.@: Pieri, Fred Pierresteguy,
-Christian Plaunt, David Ponce, Francesco A.@: Potorti, Michael D.@:
-Prange, Mukesh Prasad, Ken Raeburn, Marko Rahamaa, Ashwin Ram, Eric
-S.@: Raymond, Paul Reilly, Edward M.@: Reingold, Alex Rezinsky, Rob
-Riepel, David Reitter, Adrian Robert, Nick Roberts, Roland B.@:
-Roberts, John Robinson, Danny Roozendaal, Sebastian Rose, William
-Rosenblatt, Guillermo J.@: Rozas, Martin Rudalics, Ivar Rummelhoff,
-Jason Rumney, Wolfgang Rupprecht, Kevin Ryde, James B.@: Salem,
-Masahiko Sato, Jorgen Schaefer, Holger Schauer, William Schelter,
-Ralph Schleicher, Gregor Schmid, Michael Schmidt, Ronald S.@: Schnell,
-Philippe Schnoebelen, Jan Schormann, Alex Schroeder, Stephen Schoef,
-Raymond Scholz, Eric Schulte, Andreas Schwab, Randal Schwartz, Oliver
-Seidel, Manuel Serrano, Paul Sexton, Hovav Shacham, Stanislav
-Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Espen Skoglund,
-Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul D.@: Smith,
-William Sommerfeld, Andre Spiegel, Michael Staats, Ulf Stegemann,
+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,
+Martin Lorentzon, Dave Love, Eric Ludlam, Károly L@H{o}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, David Maus, Thomas May, Will Mengarini, David
+Megginson, Stefan Merten, Ben A.@: Mesander, Wayne Mesard, Brad
+Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Moellmann, 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,
+Andrew Norman, 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,
+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
+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
+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
+Schwartz, Oliver Seidel, Manuel Serrano, Paul Sexton, Hovav Shacham,
+Stanislav Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Tibor
+@v{S}imko, Espen Skoglund, Rick Sladkey, Lynn Slater, Chris Smith,
+David Smith, Paul D.@: Smith, Wilson Snyder, William Sommerfeld, Simon
+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, Olaf Sylvester, Naoto Takahashi, Steven Tamm,
-Jean-Philippe Theberge, Jens T.@: Berger Thielemann, Spencer Thomas,
-Jim Thompson, Luc Teirlinck, David O'Toole, Tom Tromey, Enami
-Tsugutomo, Eli Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh
-Vaidheeswarran, Neil W.@: Van Dyke, Didier Verna, Joakim Verona, Ulrik
-Vieth, Geoffrey Voelker, Johan Vromans, Inge Wallin, John Paul
-Wallington, Colin Walters, Barry Warsaw, Morten Welinder, Joseph Brian
-Wells, Rodney Whitby, John Wiegley, Ed Wilkinson, Mike Williams, Bill
+Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto
+Takahashi, Steven Tamm, 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
+W.@: Van Dyke, Didier Verna, Joakim Verona, Ulrik Vieth, Geoffrey
+Voelker, Johan Vromans, Inge Wallin, John Paul Wallington, Colin
+Walters, Barry Warsaw, Christoph Wedler, Ilja Weis, Zhang Weize,
+Morten Welinder, Joseph Brian Wells, Rodney Whitby, John Wiegley,
+Sascha Wilde, Ed Wilkinson, Mike Williams, Roland Winkler, Bill
Wohler, Steven A.@: Wood, Dale R.@: Worley, Francis J.@: Wright, Felix
-S.@: T.@: Wu, Tom Wurgler, Katsumi Yamaoka, Yamamoto Mitsuharu,
+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, Shenghuo Zhu,
-Piotr Zielinski, Ian T.@: Zimmermann, Reto Zimmermann, Neal Ziring,
-Teodor Zlatanov, and Detlev Zundel.
+Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Andrew Zhilin,
+Shenghuo Zhu, Piotr Zielinski, Ian T.@: Zimmermann, Reto Zimmermann,
+Neal Ziring, Teodor Zlatanov, and Detlev Zundel.
@end iftex
@node Intro, Glossary, Distrib, Top
@c This is part of the Emacs manual.
-@c Copyright (C) 2004-2012 Free Software Foundation, Inc.
+@c Copyright (C) 2004-2012 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
@ifnottex
@ref{Comparing Files},
@end ifnottex
-and @ref{Top, Ediff,, ediff, The Ediff Manual}.
+and @ref{Top,, Ediff, ediff, The Ediff Manual}.
@menu
* Overview of Emerge:: How to start Emerge. Basic concepts.
indicates Skip Prefers mode with @samp{S}. This mode is only relevant
when there is an ancestor.
-@findex emerge-auto-advance-mode
-@findex emerge-skip-prefers-mode
- Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
-clear Auto Advance mode. Use @kbd{s s}
-(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
-These commands turn on the mode with a positive argument, turn it off
-with a negative or zero argument, and toggle the mode with no argument.
+@findex emerge-auto-advance
+@findex emerge-skip-prefers
+ Use the command @kbd{s a} (@code{emerge-auto-advance}) to set or clear
+Auto Advance mode. Use @kbd{s s} (@code{emerge-skip-prefers}) to set or
+clear Skip Prefers mode. These commands turn on the mode with a
+positive argument, turn it off with a negative or zero argument, and
+toggle the mode with no argument.
@node State of Difference
@subsection State of a Difference
@example
@group
#ifdef NEW
-@var{version from A buffer}
-#else /* not NEW */
@var{version from B buffer}
+#else /* not NEW */
+@var{version from A buffer}
#endif /* not NEW */
@end group
@end example
@example
@group
-"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
+"#ifdef NEW\n%b#else /* not NEW */\n%a#endif /* not NEW */\n"
@end group
@end example
* Misc File Ops:: Other things you can do on files.
* Compressed Files:: Accessing compressed files.
* File Archives:: Operating on tar, zip, jar etc. archive files.
-* Remote Files:: Accessing files on other sites.
+* Remote Files:: Accessing files on other machines.
* Quoted File Names:: Quoting special characters in file names.
* File Name Cache:: Completion against a list of files you often use.
* File Conveniences:: Convenience Features for Finding Files.
@c This is part of the Emacs manual.
-@c Copyright (C) 2004-2012 Free Software Foundation, Inc.
+@c Copyright (C) 2004-2012 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
@subsection Motion Commands
In addition to the normal commands for moving by and operating on
-``defuns'' (Fortran subprograms---functions and subroutines, using the
-commands @code{fortran-beginning-of-subprogram} and
-@code{fortran-end-of-subprogram}; as well as modules for F90 mode),
-Fortran mode provides special commands to move by statements and other
-program units.
+``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.
@table @kbd
@kindex C-c C-n @r{(Fortran mode)}
@findex f90-next-block
@item C-c C-e
Move point forward to the start of the next code block, or the end of
-the current block, whichever is encountered first.
-(@code{f90-next-block}). A code block is a subroutine,
-@code{if}--@code{endif} statement, and so forth. This command exists
-for F90 mode only, not Fortran mode. With a numeric argument, this
-moves forward that many blocks.
+the current one, whichever comes first (@code{f90-next-block}).
+A code block is a subroutine, @code{if}--@code{endif} statement, and
+so forth. This command exists for F90 mode only, not Fortran mode.
+With a numeric argument, it moves forward that many blocks.
@kindex C-c C-a @r{(F90 mode)}
@findex f90-previous-block
@item C-c C-a
-Move point backward to the previous code block
+Move point backward to the previous block
(@code{f90-previous-block}). This is like @code{f90-next-block}, but
moves backwards.
@item M-^
Join this line to the previous line (@code{fortran-join-line}).
@item C-M-q
-Indent all the lines of the subprogram point is in
+Indent all the lines of the subprogram that point is in
(@code{fortran-indent-subprogram}).
@item M-q
Fill a comment block or statement (using @code{fortran-fill-paragraph}
The setting of continuation style affects several other aspects of
editing in Fortran mode. In fixed form mode, the minimum column
number for the body of a statement is 6. Lines inside of Fortran
-blocks that are indented to larger column numbers always use only the
+blocks that are indented to larger column numbers must use only the
space character for whitespace. In tab format mode, the minimum
column number for the statement body is 8, and the whitespace before
-column 8 must always consist of one tab character.
+column 8 must consist of one tab character.
@node ForIndent Num
@subsubsection Line Numbers
If a number is the first non-whitespace in the line, Fortran
indentation assumes it is a line number and moves it to columns 0
-through 4. (Columns always count from 0 in GNU Emacs.)
+through 4. (Columns always count from 0 in Emacs.)
@vindex fortran-line-number-indent
Line numbers of four digits or less are normally indented one space.
@samp{do} that ends there. If you always end @samp{do} statements with
a @samp{continue} line (or if you use the more modern @samp{enddo}),
then you can speed up indentation by setting this variable to
-@code{nil}. The default is @code{nil}.
+@code{nil} (the default).
@item fortran-blink-matching-if
If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}
@item fortran-minimum-statement-indent-fixed
Minimum indentation for Fortran statements when using fixed form
-continuation line style. Statement bodies are never indented less than
-this much. The default is 6.
+continuation line style. Statement bodies are never indented by less than
+this. The default is 6.
@item fortran-minimum-statement-indent-tab
Minimum indentation for Fortran statements for tab format continuation line
-style. Statement bodies are never indented less than this much. The
+style. Statement bodies are never indented by less than this. The
default is 8.
@end table
-The variables controlling the indentation of comments are described in
-the following section.
+The following section describes the variables controlling the
+indentation of comments.
@node Fortran Comments
@subsection Fortran Comments
some Fortran 77 compilers accept this syntax, Fortran mode will not
insert such comments unless you have said in advance to do so. To do
this, set the variable @code{fortran-comment-line-start} to @samp{"!"}.
-If you use an unusual value, you may also need to adjust
+If you use an unusual value, you may need to change
@code{fortran-comment-line-start-skip}.
Align comment or insert new comment (@code{comment-dwim}).
@item C-x ;
-Applies to nonstandard @samp{!} comments only.
+Applies to nonstandard @samp{!} comments only (@code{comment-set-column}).
@item C-c ;
Turn all lines of the region into comments, or (with argument) turn them back
@code{fortran-comment-line-extra-indent} and the minimum statement
indentation. This is the default.
-The minimum statement indentation is
-@code{fortran-minimum-statement-indent-fixed} for fixed form
-continuation line style and @code{fortran-minimum-statement-indent-tab}
-for tab format style.
+The minimum indentation is
+@code{fortran-minimum-statement-indent-tab} for tab format
+continuation line style and @code{fortran-minimum-statement-indent-fixed}
+for fixed form style.
@item relative
Align the text as if it were a line of code, but with an additional
lines are directives. Matching lines are never indented, and receive
distinctive font-locking.
- The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
-you use @samp{!} comments, this command can be used with them. Otherwise
-it is useless in Fortran mode.
+ The normal Emacs comment command @kbd{C-x ;} (@code{comment-set-column})
+has not been redefined. If you use @samp{!} comments, this command
+can be used with them. Otherwise it is useless in Fortran mode.
@kindex C-c ; @r{(Fortran mode)}
@findex fortran-comment-region
@vindex fortran-comment-region
The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
-lines of the region into comments by inserting the string @samp{C$$$} at
+lines of the region into comments by inserting the string @samp{c$$$} at
the front of each one. With a numeric argument, it turns the region
-back into live code by deleting @samp{C$$$} from the front of each line
+back into live code by deleting @samp{c$$$} from the front of each line
in it. The string used for these comments can be controlled by setting
the variable @code{fortran-comment-region}. Note that here we have an
example of a command and a variable with the same name; these two uses
Split the current window horizontally temporarily so that it is
@code{fortran-line-length} columns wide
(@code{fortran-window-create-momentarily}). This may help you avoid
-making lines longer than the character limit imposed by your Fortran
-compiler.
+making lines longer than the limit imposed by your Fortran compiler.
@item C-u C-c C-w
Split the current window horizontally so that it is
@code{fortran-line-length} columns wide (@code{fortran-window-create}).
* Frame Commands:: Iconifying, deleting, and switching frames.
* Fonts:: Changing the frame font.
* Speedbar:: How to make and use a speedbar frame.
-* Multiple Displays:: How one Emacs job can talk to several displays.
+* 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.
* Drag and Drop:: Using drag and drop to open files and insert text.
* Basic Keyboard Macro:: Defining and running keyboard macros.
* Keyboard Macro Ring:: Where previous keyboard macros are saved.
* Keyboard Macro Counter:: Inserting incrementing numbers in macros.
-* Keyboard Macro Query:: Making keyboard macros do different things each time.
-* Save Keyboard Macro:: Giving keyboard macros names; saving them in files.
+* Keyboard Macro Query:: Making keyboard macros do different things each
+ time.
+* Save Keyboard Macro:: Giving keyboard macros names; saving them in
+ files.
* Edit Keyboard Macro:: Editing keyboard macros.
* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard
macro.
@c This is part of the Emacs manual.
-@c Copyright (C) 2000-2012 Free Software Foundation, Inc.
+@c Copyright (C) 2000-2012 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Mac OS / GNUstep, Microsoft Windows, Antinews, Top
@appendix Emacs and Mac OS / GNUstep
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. Emacs
-does not support earlier versions of Mac OS.
+Cocoa interface; this section only applies to the Cocoa build. This
+does not support versions of Mac OS X earlier than 10.4.
For various historical and technical reasons, Emacs uses the term
@samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for
was an application interface released by NeXT Inc during the 1980s, of
which Cocoa is a direct descendant. Apart from Cocoa, there is
another NeXTstep-style system: GNUstep, which is free software. As of
-this writing, the GNUstep support is alpha status (@pxref{GNUstep
+this writing, Emacs GNUstep support is alpha status (@pxref{GNUstep
Support}), but we hope to improve it in the future.
@menu
other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}). You
can change these bindings in the usual way (@pxref{Key Bindings}).
+@c FIXME mention ns-alternate-modifier?
The variable @code{ns-right-alternate-modifier} controls the
behavior of the right @key{alt} and @key{option} keys. These keys
behave like the left-hand keys if the value is @code{left} (the
@code{super}, or @code{hyper} makes them behave like the corresponding
modifier keys; a value of @code{none} tells Emacs to ignore them.
- The standard Mac / GNUstep font and color panels are accessible via
-Lisp commands. To use the color panel, drag from it to an Emacs frame
-to change the foreground color of the face at that position (if the
-@key{shift} key is held down, it changes the background color
-instead). To discard the settings, create a new frame and close the
-altered one.
-
- @key{S-Mouse-1} (i.e., clicking the left mouse button while holding
-down the @key{Shift} key) adjusts the region to the click position,
-just like @key{Mouse-3} (@code{mouse-save-then-kill}); it does not pop
-up a menu for changing the default face, as @key{S-Mouse-1} normally
+ @kbd{S-Mouse-1} adjusts the region to the click position,
+just like @kbd{Mouse-3} (@code{mouse-save-then-kill}); it does not pop
+up a menu for changing the default face, as @kbd{S-Mouse-1} normally
does (@pxref{Text Scale}). This change makes Emacs behave more like
other Mac / GNUstep applications.
When you open or save files using the menus, or using the
-@key{Cmd-o} and @key{Cmd-S} bindings, Emacs uses graphical file
+@kbd{Cmd-o} and @kbd{Cmd-S} bindings, Emacs uses graphical file
dialogs to read file names. However, if you use the regular Emacs key
-sequences, such as @key{C-x C-f}, Emacs uses the minibuffer to read
+sequences, such as @kbd{C-x C-f}, Emacs uses the minibuffer to read
file names.
- On GNUstep, in an X-windows environment you need to use @key{Cmd-c}
-instead of one of the @key{C-w} or @key{M-w} commands to transfer text
+ 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, @key{Cmd-y} (instead of @key{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.
@subsection Font and Color Panels
-The Font Panel may be accessed with M-x ns-popup-font-panel. It
-will set the default font in the frame most recently used or clicked
-on.
+The standard Mac / GNUstep font and color panels are accessible via
+Lisp commands. The Font Panel may be accessed with @kbd{M-x
+ns-popup-font-panel}. It will set the default font in the frame most
+recently used or clicked on.
@c To make the setting permanent, use @samp{Save Options} in the
@c Options menu, or run @code{menu-bar-options-save}.
-You can bring up a color panel with M-x ns-popup-color-panel. and
-drag the color you want over the emacs face you want to change. Normal
+You can bring up a color panel with @kbd{M-x ns-popup-color-panel} and
+drag the color you want over the Emacs face you want to change. Normal
dragging will alter the foreground color. Shift dragging will alter the
-background color.
+background color. To discard the settings, create a new frame and
+close the altered one.
@c To make the changes permanent select the "Save Options"
@c item in the "Options" menu, or run @code{menu-bar-options-save}.
-Useful in this context is the listing of all faces obtained by @key{M-x}
-@code{list-faces-display}.
+Useful in this context is the listing of all faces obtained by
+@kbd{M-x list-faces-display}.
@subsection Open files by dragging to an Emacs window
@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 OS X 10.6 or later.)
+move the mouse pointer over it. (Requires Mac OS X 10.6 or later.)
@end table
buffer is the @samp{*scratch*} buffer, Emacs visits the file in the
selected frame.
-You can change how Emacs responds to @key{ns-open-file} by changing
-the variable @code{ns-pop-up-frames}. Its default value,
-@code{'fresh}, is what we have just described. A value of @code{t}
+You can change how Emacs responds to a @code{ns-open-file} event by
+changing the variable @code{ns-pop-up-frames}. Its default value,
+@samp{fresh}, is what we have just described. A value of @code{t}
means to always visit the file in a new frame. A value of @code{nil}
means to always visit the file in an existing frame.
Emacs also allows users to make use of Nextstep services, via a set
of commands whose names begin with @samp{ns-service-} and end with the
-name of the service. Type @kbd{M-x ns-service-@key{TAB}@key{TAB}} to
+name of the service. Type @kbd{M-x ns-service-@key{TAB}} to
see a list of these commands. These functions either operate on
marked text (replacing it with the result) or take a string argument
and return the result as a string. You can also use the Lisp function
@node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep
@section GNUstep Support
-Emacs can be built and run under GNUstep, but there are still some
+Emacs can be built and run under GNUstep, but there are still
issues to be addressed. Interested developers should contact
@email{emacs-devel@@gnu.org}.
@ifnottex
@item M-x vc-ediff
-Like @kbd{C-x v =}, but using Ediff. @xref{Top, Ediff, ediff, The
+Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The
Ediff Manual}.
@end ifnottex
@ifnottex
@findex vc-ediff
@kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
-Ediff session. @xref{Top, Ediff, ediff, The Ediff Manual}.
+Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}.
@end ifnottex
@findex vc-root-diff
* Windows Fonts:: Specifying fonts on MS-Windows.
* Windows Misc:: Miscellaneous Windows features.
@ifnottex
-* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}).
+* MS-DOS:: Using Emacs on MS-DOS.
@end ifnottex
@end menu
@code{picture-move-up}, which can either insert spaces or convert tabs
as necessary to make sure that point stays in exactly the same column.
@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last
-nonblank character on the line. There is no need to change @kbd{C-a},
-as the choice of screen model does not affect beginnings of
-lines.
+nonblank character on the line. @kbd{C-a} runs
+@code{picture-beginning-of-line}. (The choice of screen model does not
+affect beginnings of lines; the only extra thing this command does is
+update the current picture column to 0.)
@findex picture-newline
Insertion of text is adapted to the quarter-plane screen model
use in your program.
@menu
-* Info Lookup:: Looking up library functions and commands
- in Info files.
+* Info Lookup:: Looking up library functions and commands in Info files.
* Man Page:: Looking up man pages of library functions and commands.
* Lisp Doc:: Looking up Emacs Lisp functions, etc.
@end menu
to save the Rmail file eventually (like any other file you have
changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save
Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the
-Rmail buffer and its summary buffer without expunging and saving the
-Rmail file.
+Rmail buffer and its summary without expunging and saving the Rmail file.
@node Rmail Scrolling
@section Scrolling Within a Message
@findex rmail-delete-forward
@findex rmail-delete-backward
There are two Rmail commands for deleting messages. Both delete the
-current message and select another message. @kbd{d}
+current message and select another. @kbd{d}
(@code{rmail-delete-forward}) moves to the following message, skipping
messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
moves to the previous nondeleted message. If there is no nondeleted
@vindex rmail-primary-inbox-list
@cindex @env{MAIL} environment variable
The variable @code{rmail-primary-inbox-list} contains a list of the
-files which are inboxes for your primary Rmail file. If you don't set
+files that are inboxes for your primary Rmail file. If you don't set
this variable explicitly, Rmail uses the @env{MAIL} environment
variable, or, as a last resort, a default inbox based on
@code{rmail-spool-directory}. The default inbox file depends on your
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.
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
the regular expression). If no files match, you cannot select this menu
item. These variables also apply to choosing a file for output
(@pxref{Rmail Output}).
+@c FIXME matches only checked when Rmail file first visited?
@ignore
@findex set-rmail-inbox-list
@kbd{o} converts the message to Babyl format (used by Rmail in Emacs
version 22 and before) if the file is in Babyl format; @kbd{C-o}
cannot output to Babyl files at all.
+@c FIXME remove BABYL mention in Emacs 25?
If the output file is currently visited in an Emacs buffer, the
output commands append the message to that buffer. It is up to you to
@cindex reply to a message
The most common reason to send a message while in Rmail is to reply
to the message you are reading. To do this, type @kbd{r}
-(@code{rmail-reply}). This displays the @samp{*mail*} buffer in
+(@code{rmail-reply}). This displays a mail composition buffer in
another window, much like @kbd{C-x 4 m}, but preinitializes the
@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and
@samp{References} header fields based on the message you are replying
sent the message you received, and the @samp{CC} field starts out with
all the other recipients of that message.
-@vindex rmail-dont-reply-to-names
+@vindex mail-dont-reply-to-names
You can exclude certain recipients from being included automatically
-in replies, using the variable @code{rmail-dont-reply-to-names}. Its
+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
-initialized to a default value that matches your own address, and any
-name starting with @samp{info-}. (Those names are excluded because
-there is a convention of using them for large mailing lists to broadcast
-announcements.)
+initialized to a default value that matches your own address.
To omit the @samp{CC} field completely for a particular reply, enter
the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
This means to reply only to the sender of the original message.
- Once the @samp{*mail*} buffer has been initialized, editing and
+ Once the mail composition buffer has been initialized, editing and
sending the mail goes as usual (@pxref{Sending Mail}). You can edit
the presupplied header fields if they are not what you want. You can
also use commands such as @kbd{C-c C-y}, which yanks in the message
send the failed message back to you, enclosed in a @dfn{failure
message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
prepares to send the same message a second time: it sets up a
-@samp{*mail*} buffer with the same text and header fields as before. If
+mail composition buffer with the same text and header fields as before. If
you type @kbd{C-c C-c} right away, you send the message again exactly
the same as the first time. Alternatively, you can edit the text or
headers and then send it. The variable
@cindex forwarding a message
Another frequent reason to send mail in Rmail is to @dfn{forward} the
current message to other users. @kbd{f} (@code{rmail-forward}) makes
-this easy by preinitializing the @samp{*mail*} buffer with the current
-message as the text, and a subject designating a forwarded message. All
-you have to do is fill in the recipients and send. When you forward a
-message, recipients get a message which is ``from'' you, and which has
-the original message in its contents.
-
+this easy by preinitializing the mail composition buffer with the current
+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
+its contents.
+
+@vindex rmail-enable-mime-composing
@findex unforward-rmail-message
- Forwarding a message encloses it between two delimiter lines. It also
-modifies every line that starts with a dash, by inserting @w{@samp{- }}
-at the start of the line. When you receive a forwarded message, if it
+ Rmail offers two formats for forwarded messages. The default is to
+use MIME (@pxref{Rmail Display}) format. This includes the original
+message as a separate part. You can use a simpler format if you
+prefer, by setting the variable @code{rmail-enable-mime-composing} to
+@code{nil}. In this case, Rmail just includes the original message
+enclosed between two delimiter lines. It also modifies every line
+that starts with a dash, by inserting @w{@samp{- }} at the start of
+the line. When you receive a forwarded message in this format, if it
contains something besides ordinary text---for example, program source
-code---you might find it useful to undo that transformation. You can do
-this by selecting the forwarded message and typing @kbd{M-x
-unforward-rmail-message}. This command extracts the original forwarded
-message, deleting the inserted @w{@samp{- }} strings, and inserts it
-into the Rmail file as a separate message immediately following the
-current one.
+code---you might find it useful to undo that transformation. You can
+do this by selecting the forwarded message and typing @kbd{M-x
+unforward-rmail-message}. This command extracts the original
+forwarded message, deleting the inserted @w{@samp{- }} strings, and
+inserts it into the Rmail file as a separate message immediately
+following the current one.
@findex rmail-resend
@dfn{Resending} is an alternative similar to forwarding; the
Use the @kbd{m} (@code{rmail-mail}) command to start editing an
outgoing message that is not a reply. It leaves the header fields empty.
Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
-accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be
-used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
-can do.
+accessible for @kbd{C-c C-y}, just as @kbd{r} does.
+@ignore
+@c Not a good idea, because it does not include Reply-To etc.
+Thus, @kbd{m} can be used to reply to or forward a message; it can do
+anything @kbd{r} or @kbd{f} can do.
+@end ignore
@kindex c @r{(Rmail)}
@findex rmail-continue
The @kbd{c} (@code{rmail-continue}) command resumes editing the
-@samp{*mail*} buffer, to finish editing an outgoing message you were
+mail composition buffer, to finish editing an outgoing message you were
already composing, or to alter a message you have sent.
@vindex rmail-mail-new-frame
If you set the variable @code{rmail-mail-new-frame} to a
non-@code{nil} value, then all the Rmail commands to start sending a
message create a new frame to edit it in. This frame is deleted when
-you send the message, or when you use the @samp{Cancel} item in the
-@samp{Mail} menu.
+you send the message.
+@ignore
+@c FIXME does not work with Message -> Kill Message
+, or when you use the @samp{Cancel} item in the @samp{Mail} menu.
+@end ignore
All the Rmail commands to send a message use the mail-composition
method that you have chosen (@pxref{Mail Methods}).
makes a partial summary mentioning only the messages that have one or
more recipients matching the regular expression @var{rcpts}. You can
use commas to separate multiple regular expressions. These are matched
-against the @samp{To}, @samp{From}, and @samp{CC} headers (with a prefix
-argument, this header is not included).
+against the @samp{To}, @samp{From}, and @samp{CC} headers (supply a prefix
+argument to exclude this header).
@kindex C-M-t @r{(Rmail)}
@findex rmail-summary-by-topic
(@code{rmail-mime-next-item}).
@findex rmail-mime-previous-item
-@item @key{BackTab}
+@item S-@key{TAB}
Move point to the previous @acronym{MIME} part
(@code{rmail-mime-previous-item}).
taglines, with their actual contents hidden. In either case, you can
toggle a @acronym{MIME} part between its ``displayed'' and ``hidden''
states by typing @key{RET} anywhere in the part---or anywhere in its
-tagline, apart from a tagline button for some other action. Type
+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.
@cindex encrypted mails (reading in Rmail)
If the current message is an encrypted one, use the command @kbd{M-x
rmail-epa-decrypt} to decrypt it, using the EasyPG library
-(@pxref{Top,,, epa, EasyPG Assistant User's Manual}).
+(@pxref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}).
You can highlight and activate URLs in the Rmail buffer using Goto
Address mode:
@cindex undigestify
A @dfn{digest message} is a message which exists to contain and carry
-several other messages. Digests are used on some moderated mailing
+several other messages. Digests are used on some mailing
lists; all the messages that arrive for the list during a period of time
such as one day are put inside a single digest which is then sent to the
-subscribers. Transmitting the single digest uses much less computer
+subscribers. Transmitting the single digest uses less computer
time than transmitting the individual messages even though the total
-size is the same, because the per-message overhead in network mail
-transmission is considerable.
+size is the same, because of the per-message overhead in network mail
+transmission.
@findex undigestify-rmail-message
When you receive a digest message, the most convenient way to read it is
@section Reading Rot13 Messages
@cindex rot13 code
- Mailing list messages that might offend some readers are sometimes
+ Mailing list messages that might offend or annoy some readers are sometimes
encoded in a simple code called @dfn{rot13}---so named because it
rotates the alphabet by 13 letters. This code is not for secrecy, as it
-provides none; rather, it enables those who might be offended to avoid
-seeing the real text of the message.
+provides none; rather, it enables those who wish to to avoid
+seeing the real text of the message. For example, a review of a film
+might use rot13 to hide important plot points.
@findex rot13-other-window
- To view a buffer which uses the rot13 code, use the command @kbd{M-x
+ To view a buffer that uses the rot13 code, use the command @kbd{M-x
rot13-other-window}. This displays the current buffer in another window
which applies the code when displaying the text.
* Text Mode:: The major modes for editing text files.
* Outline Mode:: Editing outlines.
* Org Mode:: The Emacs organizer.
-* TeX Mode:: Editing input to the formatter TeX.
+* TeX Mode:: Editing TeX and LaTeX files.
* HTML Mode:: Editing HTML and SGML files.
-* Nroff Mode:: Editing input to the formatter nroff.
+* Nroff Mode:: Editing input to the nroff formatter.
* 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.
it via the version control system. The file is removed from the
working tree, and in the VC Directory buffer
@iftex
-(@pxref{VC Directory Mode}),
+(@pxref{VC Directory Mode,,, emacs, the Emacs Manual}),
@end iftex
@ifnottex
(@pxref{VC Directory Mode}),
locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature;
see the CVS documentation for details. If that case, you can use
@kbd{C-x v v} in Emacs to toggle locking, as you would for a
-locking-based version control system (@pxref{VC With A Locking VCS}).
+locking-based version control system
+@iftex
+(@pxref{VC With A Locking VCS,,,emacs, the Emacs Manual}).
+@end iftex
+@ifnottex
+(@pxref{VC With A Locking VCS}).
+@end ifnottex
+2012-02-17 Glenn Morris <rgm@gnu.org>
+
+ * emacs-lisp-intro.texi (Design @value{COUNT-WORDS}, Syntax)
+ (count-words-in-defun): Fix cross-refs to Emacs manual.
+
2012-01-28 Andreas Schwab <schwab@linux-m68k.org>
* emacs-lisp-intro.texi (Top): Move setting of COUNT-WORDS outside
@noindent
The buffer's syntax table determines which characters are and are not
-word constituents. (@xref{Syntax, , What Constitutes a Word or
-Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The
-Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
-Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
+word constituents. For more information about syntax,
+@pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp
+Reference Manual}.
@need 800
The search expression looks like this:
one syntax category. Other syntax categories include the class of
punctuation characters, such as the period and the comma, and the
class of whitespace characters, such as the blank space and the tab
-character. (For more information, see @ref{Syntax, Syntax, The Syntax
-Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
+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.
jumps. The true-or-false-test for the @code{while} loop should test
true so long as point should jump forward, and false when point is at
the end of the definition. We have already redefined the regular
-expression for this (@pxref{Syntax}), so the loop is straightforward:
+expression for this, so the loop is straightforward:
@smallexample
@group
+2012-02-21 Chong Yidong <cyd@gnu.org>
+
+ * files.texi (Files): Mention magic file names as arguments.
+ (Reading from Files): Copyedits.
+ (File Attributes): Mention how to change file modes.
+ (Changing Files): Use standard "file permissions" terminology.
+ Add xref to File Attributes node.
+ (Locating Files): Document locate-user-emacs-file.
+ (Unique File Names): Recommend against using make-temp-name.
+
+2012-02-19 Chong Yidong <cyd@gnu.org>
+
+ * help.texi (Documentation, Documentation Basics, Help Functions):
+ Minor clarifications.
+ (Accessing Documentation): Clarify what documentation-property is
+ for. Add xref to Keys in Documentation.
+
+ * tips.texi (Documentation Tips): Don't recommend using * in
+ docstrings.
+
+ * macros.texi (Defining Macros):
+ * modes.texi (Derived Modes): Say "documentation string" instead
+ of docstring.
+
+2012-02-18 Chong Yidong <cyd@gnu.org>
+
+ * modes.texi (Tabulated List Mode): New node.
+ (Basic Major Modes): Add xref to it.
+
+ * processes.texi (Process Information): Mention Process Menu mode.
+
+2012-02-17 Chong Yidong <cyd@gnu.org>
+
+ * syntax.texi (Motion via Parsing): Doc fix for scan-lists.
+
+2012-02-17 Glenn Morris <rgm@gnu.org>
+
+ * hooks.texi (Standard Hooks): Fix cross-ref to Emacs manual.
+
+2012-02-16 Chong Yidong <cyd@gnu.org>
+
+ * syntax.texi (Syntax Tables, Syntax Descriptors)
+ (Syntax Table Functions): Copyedits.
+ (Syntax Basics): Don't repeat the material in the preceding node.
+ (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.
+ (Parser State): Update for the new "c" comment style. Fix
+ description of item 7 (comment style).
+
+ * modes.texi (Minor Modes): Update how mode commands should treat
+ arguments now.
+ (Mode Line Basics): Clarify force-mode-line-update.
+ (Mode Line Top): Note that the example is not realistic.
+ (Mode Line Variables, Mode Line Data, %-Constructs, Header Lines)
+ (Emulating Mode Line): Use "mode line" instead of "mode-line", and
+ "mode line construct" instead of "mode line specification".
+ (Syntactic Font Lock): Remove mention of obsolete variable
+ font-lock-syntactic-keywords.
+ (Setting Syntax Properties): Node deleted.
+ (Font Lock Mode): Note that Font Lock mode is a minor mode.
+ (Font Lock Basics): Note that syntactic fontification falls back
+ on `syntax-table'.
+ (Search-based Fontification): Emphasize that font-lock-keywords
+ should not be set directly.
+ (Faces for Font Lock): Avoid some confusing terminology.
+ (Syntactic Font Lock): Minor clarifications. Add xref to
+ Syntactic Font Lock node.
+
2012-02-15 Chong Yidong <cyd@gnu.org>
* minibuf.texi (Basic Completion): Define "completion table".
(Setting Hooks): Update minor mode usage example.
(Major Mode Conventions): Note that completion-at-point-functions
should be altered locally. Add xref to Completion in Buffers.
+ Remove duplicate tip about auto-mode-alist.
+ (Minor Modes): Rewrite introduction.
+ (Minor Mode Conventions): Copyedits. Don't recommend
+ variable-only minor modes since few minor modes are like that.
2012-02-15 Glenn Morris <rgm@gnu.org>
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: Providing a menu of definitions made in a buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
+* Auto-Indentation:: How to teach Emacs to indent for a major mode.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
+* Mode Hooks:: Hooks run at the end of major mode functions.
+* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
-* Mode Hooks:: Hooks run at the end of major mode functions.
* Example Major Modes:: Text mode and Lisp modes.
Minor Modes
contents can also specify how to fontify it.
* Faces for Font Lock:: Special faces specifically for Font Lock.
* Syntactic Font Lock:: Fontification based on syntax tables.
-* Setting Syntax Properties:: Defining character syntax based on context
- using the Font Lock mechanism.
* Multiline Font Lock:: How to coerce Font Lock into properly
highlighting multiline constructs.
Documentation
-* Documentation Basics:: Good style for doc strings.
- Where to put them. How Emacs stores them.
+* Documentation Basics:: Where doc strings are defined and stored.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
* Describing Characters:: Making printable descriptions of
* File Locks:: Locking and unlocking files, to prevent
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files:: Renaming files, changing protection, etc.
+* Changing Files:: Renaming files, changing permissions, etc.
* File Names:: Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs:: Creating and Deleting Directories.
-* Magic File Names:: Defining "magic" special handling
- for certain file names.
+* Magic File Names:: Special handling for certain file names.
* Format Conversion:: Conversion to and from various file formats.
Visiting Files
@comment node-name, next, previous, up
@chapter Files
- In Emacs, you can find, create, view, save, and otherwise work with
-files and file directories. This chapter describes most of the
-file-related functions of Emacs Lisp, but a few others are described in
+ This chapter describes the Emacs Lisp functions and variables to
+find, create, view, save, and otherwise work with files and file
+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}.
names. A file name is actually a string. Most of these functions
expand file name arguments by calling @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
-@samp{../}). These functions don't recognize environment variable
-substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
+@samp{../}). @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
+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.
When file I/O functions signal Lisp errors, they usually use the
condition @code{file-error} (@pxref{Handling Errors}). The error
* File Locks:: Locking and unlocking files, to prevent
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files:: Renaming files, changing protection, etc.
+* Changing Files:: Renaming files, changing permissions, etc.
* File Names:: Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs:: Creating and Deleting Directories.
-* Magic File Names:: Defining "magic" special handling
- for certain file names.
+* Magic File Names:: Special handling for certain file names.
* Format Conversion:: Conversion to and from various file formats.
@end menu
and the length of the data inserted. An error is signaled if
@var{filename} is not the name of a file that can be read.
-The function @code{insert-file-contents} checks the file contents
-against the defined file formats, and converts the file contents if
-appropriate and also calls the functions in
-the list @code{after-insert-file-functions}. @xref{Format Conversion}.
-Normally, one of the functions in the
+This function checks the file contents against the defined file
+formats, and converts the file contents if appropriate and also calls
+the functions in the list @code{after-insert-file-functions}.
+@xref{Format Conversion}. Normally, one of the functions in the
@code{after-insert-file-functions} list determines the coding system
(@pxref{Coding Systems}) used for decoding the file's contents,
including end-of-line conversion. However, if the file contains null
-bytes, it is by default visited without any code conversions; see
-@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
-control this behavior.
+bytes, it is by default visited without any code conversions.
+@xref{Lisp and Coding Systems, inhibit-null-byte-detection}.
If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
@end defun
@defun insert-file-contents-literally filename &optional visit beg end replace
-This function works like @code{insert-file-contents} except that it does
-not do format decoding (@pxref{Format Conversion}), does not do
-character code conversion (@pxref{Coding Systems}), does not run
-@code{find-file-hook}, does not perform automatic uncompression, and so
-on.
+This function works like @code{insert-file-contents} except that it
+does not run @code{find-file-hook}, and does not do format decoding,
+character code conversion, automatic uncompression, and so on.
@end defun
If you want to pass a file name to another process so that another
to exist. This does not mean you can necessarily read the file, only
that you can find out its attributes. (On Unix and GNU/Linux, this is
true if the file exists and you have execute permission on the
-containing directories, regardless of the protection of the file
+containing directories, regardless of the permissions of the file
itself.)
If the file does not exist, or if fascist access control policies
@subsection Truenames
@cindex truename (of file)
-@c Emacs 19 features
The @dfn{truename} of a file is the name that you get by following
symbolic links at all levels until none remain, then simplifying away
@samp{.}@: and @samp{..}@: appearing as name components. This results
because they eliminate symbolic links as a cause of name variation.
@defun file-truename filename
-The function @code{file-truename} returns the truename of the file
-@var{filename}. If the argument is not an absolute file name,
-this function first expands it against @code{default-directory}.
+This function returns the truename of the file @var{filename}. If the
+argument is not an absolute file name, this function first expands it
+against @code{default-directory}.
This function does not expand environment variables. Only
@code{substitute-in-file-name} does that. @xref{Definition of
@comment node-name, next, previous, up
@subsection Other Information about Files
- This section describes the functions for getting detailed information
-about a file, other than its contents. This information includes the
-mode bits that control access permission, the owner and group numbers,
-the number of names, the inode number, the size, and the times of access
-and modification.
+ 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.
@defun file-modes filename
-@cindex permission
+@cindex file permissions
+@cindex permissions, file
@cindex file attributes
-This function returns the mode bits of @var{filename}, as an integer.
-The mode bits are also called the file permissions, and they specify
-access control in the usual Unix fashion. If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order bit
-is 1, then the file is writable by all users, etc.
-
-The highest value returnable is 4095 (7777 octal), meaning that
-everyone has read, write, and execute permission, that the @acronym{SUID} bit
-is set for both others and group, and that the sticky bit is set.
-
-If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
-
-This function recursively follows symbolic links at all levels.
+@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}.
+
+@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.
@example
@group
-rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
@end group
@end example
+
+@xref{Changing Files}, for functions that change file permissions,
+such as @code{set-file-modes}.
@end defun
-If the @var{filename} argument to the next two functions is a symbolic
-link, then these function do @emph{not} replace it with its target.
-However, they both recursively follow symbolic links at all levels of
-parent directories.
+ If the @var{filename} argument to the next two functions is a
+symbolic link, then these function do @emph{not} replace it with its
+target. However, they both recursively follow symbolic links at all
+levels of parent directories.
@defun file-nlinks filename
This functions returns the number of names (i.e., hard links) that
@cindex find file in path
This section explains how to search for a file in a list of
-directories (a @dfn{path}). One example is when you need to look for
-a program's executable file, e.g., to find out whether a given program
-is installed on the user's system. Another example is the search for
-Lisp libraries (@pxref{Library Search}). Such searches generally need
-to try various possible file name extensions, in addition to various
-possible directories. Emacs provides a function for such a
-generalized search for a file.
+directories (a @dfn{path}), or for an executable file in the standard
+list of executable file directories, or for an Emacs-specific user
+configuration file.
@defun locate-file filename path &optional suffixes predicate
This function searches for a file whose name is @var{filename} in a
list of directories given by @var{path}, trying the suffixes in
-@var{suffixes}. If it finds such a file, it returns the full
-@dfn{absolute file name} of the file (@pxref{Relative File Names});
-otherwise it returns @code{nil}.
+@var{suffixes}. If it finds such a file, it returns the file's
+absolute file name (@pxref{Relative File Names}); otherwise it returns
+@code{nil}.
The optional argument @var{suffixes} gives the list of file-name
suffixes to append to @var{filename} when searching.
suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
are no suffixes, and @var{filename} is used only as-is. Typical
values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
-Creation, exec-suffixes}), @code{load-suffixes},
-@code{load-file-rep-suffixes} and the return value of the function
-@code{get-load-suffixes} (@pxref{Load Suffixes}).
+Creation}), @code{load-suffixes}, @code{load-file-rep-suffixes} and
+the return value of the function @code{get-load-suffixes} (@pxref{Load
+Suffixes}).
Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
-Creation, exec-path}) when looking for executable programs or
-@code{load-path} (@pxref{Library Search, load-path}) when looking for
-Lisp files. If @var{filename} is absolute, @var{path} has no effect,
-but the suffixes in @var{suffixes} are still tried.
-
-The optional argument @var{predicate}, if non-@code{nil}, specifies
-the predicate function to use for testing whether a candidate file is
-suitable. The predicate function is passed the candidate file name as
-its single argument. If @var{predicate} is @code{nil} or unspecified,
-@code{locate-file} uses @code{file-readable-p} as the default
-predicate. Useful non-default predicates include
-@code{file-executable-p}, @code{file-directory-p}, and other
-predicates described in @ref{Kinds of Files}.
+Creation}) when looking for executable programs, or @code{load-path}
+(@pxref{Library Search}) when looking for Lisp files. If
+@var{filename} is absolute, @var{path} has no effect, but the suffixes
+in @var{suffixes} are still tried.
+
+The optional argument @var{predicate}, if non-@code{nil}, specifies a
+predicate function for testing whether a candidate file is suitable.
+The predicate is passed the candidate file name as its single
+argument. If @var{predicate} is @code{nil} or omitted,
+@code{locate-file} uses @code{file-readable-p} as the predicate.
+@xref{Kinds of Files}, for other useful predicates, e.g.@:
+@code{file-executable-p} and @code{file-directory-p}.
For compatibility, @var{predicate} can also be one of the symbols
@code{executable}, @code{readable}, @code{writable}, @code{exists}, or
@defun executable-find program
This function searches for the executable file of the named
-@var{program} and returns the full absolute name of the executable,
+@var{program} and returns the absolute file name of the executable,
including its file-name extensions, if any. It returns @code{nil} if
the file is not found. The functions searches in all the directories
-in @code{exec-path} and tries all the file-name extensions in
-@code{exec-suffixes}.
+in @code{exec-path}, and tries all the file-name extensions in
+@code{exec-suffixes} (@pxref{Subprocess Creation}).
+@end defun
+
+@defun locate-user-emacs-file base-name &optional old-name
+This function returns an absolute file name for an Emacs-specific
+configuration or data file. The argument @file{base-name} should be a
+relative file name. The return value is the absolute name of a file
+in the directory specified by @code{user-emacs-directory}; if that
+directory does not exist, this function creates it.
+
+If the optional argument @var{old-name} is non-@code{nil}, it
+specifies a file in the user's home directory,
+@file{~/@var{old-name}}. If such a file exists, the return value is
+the absolute name of that file, instead of the file specified by
+@var{base-name}. This argument is intended to be used by Emacs
+packages to provide backward compatibility. For instance, prior to
+the introduction of @code{user-emacs-directory}, the abbrev file was
+located in @file{~/.abbrev_defs}, so the definition of
+@code{abbrev-file-name} is
+
+@example
+(defcustom abbrev-file-name
+ (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
+ "Default name of file from which to read abbrevs."
+ @dots{}
+ :type 'file)
+@end example
@end defun
@node Changing Files
@cindex linking files
@cindex setting modes of files
- The functions in this section rename, copy, delete, link, and set the
-modes of files.
+ The functions in this section rename, copy, delete, link, and set
+the modes (permissions) of files.
In the functions that have an argument @var{newname}, if a file by the
name of @var{newname} already exists, the actions taken depend on the
See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn
+@cindex file permissions, setting
+@cindex permissions, file
+@cindex file modes, setting
@deffn Command set-file-modes filename mode
-This function sets mode bits of @var{filename} to @var{mode} (which
-must be an integer when the function is called non-interactively).
-Only the low 12 bits of @var{mode} are used.
+This function sets the @dfn{file mode} (or @dfn{file permissions}) of
+@var{filename} to @var{mode}. It recursively follows symbolic links
+at all levels for @var{filename}.
+
+If called non-interactively, @var{mode} must be an integer. Only the
+lowest 12 bits of the integer are used; on most systems, only the
+lowest 9 bits are meaningful. You can use the Lisp construct for
+octal numbers to enter @var{mode}. For example,
+
+@example
+(set-file-modes #o644)
+@end example
+
+@noindent
+specifies that the file should be readable and writable for its owner,
+readable for group members, and readable for all other users.
+@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bit specifications.
Interactively, @var{mode} is read from the minibuffer using
-@code{read-file-modes}, which accepts mode bits either as a number or
-as a character string representing the mode bits symbolically. See
-the description of @code{read-file-modes} below for the supported
-forms of symbolic notation for mode bits.
+@code{read-file-modes} (see below), which lets the user type in either
+an integer or a string representing the permissions symbolically.
-This function recursively follows symbolic links at all levels for
-@var{filename}.
+@xref{File Attributes}, for the function @code{file-modes}, which
+returns the permissions of a file.
@end deffn
-@c Emacs 19 feature
@defun set-default-file-modes mode
@cindex umask
-This function sets the default file protection for new files created by
-Emacs and its subprocesses. Every file created with Emacs initially has
-this protection, or a subset of it (@code{write-region} will not give a
-file execute permission even if the default file protection allows
-execute permission). On Unix and GNU/Linux, the default protection is
-the bitwise complement of the ``umask'' value.
-
-The argument @var{mode} must be an integer. On most systems, only the
-low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
-for octal numbers to enter @var{mode}; for example,
-
-@example
-(set-default-file-modes #o644)
-@end example
-
-Saving a modified version of an existing file does not count as creating
-the file; it preserves the existing file's mode, whatever that is. So
-the default file protection has no effect.
+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.
+
+The argument @var{mode} should be an integer which specifies the
+permissions, similar to @code{set-file-modes} above. Only the lowest
+9 bits are meaningful.
+
+The default file permissions have no effect when you save a modified
+version of an existing file; saving a file preserves its existing
+permissions.
@end defun
@defun default-file-modes
-This function returns the current default protection value.
+This function returns the default file permissions, as an integer.
@end defun
@defun read-file-modes &optional prompt base-file
-This function reads file mode bits from the minibuffer. The optional
-argument @var{prompt} specifies a non-default prompt. Second optional
-argument @var{base-file} is the name of a file on whose permissions to
-base the mode bits that this function returns, if what the user types
-specifies mode bits relative to permissions of an existing file.
+This function reads a set of file mode bits from the minibuffer. The
+first optional argument @var{prompt} specifies a non-default prompt.
+Second second optional argument @var{base-file} is the name of a file
+on whose permissions to base the mode bits that this function returns,
+if what the user types specifies mode bits relative to permissions of
+an existing file.
If user input represents an octal number, this function returns that
number. If it is a complete symbolic specification of mode bits, as
@code{nil}, the function uses @code{0} as the base mode bits. The
complete and relative specifications can be combined, as in
@code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
-@sc{gnu} @code{Coreutils} Manual}, for detailed description of
-symbolic mode bits specifications.
+@sc{gnu} @code{Coreutils} Manual}, for a description of file mode
+specifications.
@end defun
@defun file-modes-symbolic-to-number modes &optional base-modes
-This subroutine converts a symbolic specification of file mode bits in
-@var{modes} into the equivalent numeric value. If the symbolic
+This function converts a symbolic file mode specification in
+@var{modes} into the equivalent integer value. If the symbolic
specification is based on an existing file, that file's mode bits are
taken from the optional argument @var{base-modes}; if that argument is
-omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
+omitted or @code{nil}, it defaults to 0, i.e.@: no access rights at
all.
@end defun
non-@code{nil}. To use it, you should expand the prefix against
the proper directory before calling @code{make-temp-file}.
- In older Emacs versions where @code{make-temp-file} does not exist,
-you should use @code{make-temp-name} instead:
-
-@example
-(make-temp-name
- (expand-file-name @var{name-of-application}
- temporary-file-directory))
-@end example
-
-@defun make-temp-name string
-This function generates a string that can be used as a unique file
-name. The name starts with @var{string}, and has several random
-characters appended to it, which are different in each Emacs job. It
-is like @code{make-temp-file} except that it just constructs a name,
-and does not create a file. Another difference is that @var{string}
-should be an absolute file name. On MS-DOS, this function can
-truncate the @var{string} prefix to fit into the 8+3 file-name limits.
-@end defun
-
@defopt temporary-file-directory
@cindex @code{TMPDIR} environment variable
@cindex @code{TMP} environment variable
@end example
@end defopt
+@defun make-temp-name base-name
+This function generates a string that can be used as a unique file
+name. The name starts with @var{base-name}, and has several random
+characters appended to it, which are different in each Emacs job. It
+is like @code{make-temp-file} except that (i) it just constructs a
+name, and does not create a file, and (ii) @var{base-name} should be
+an absolute file name (on MS-DOS, this function can truncate
+@var{base-name} to fit into the 8+3 file-name limits).
+
+@strong{Warning:} In most cases, you should not use this function; use
+@code{make-temp-file} instead! This function is susceptible to a race
+condition, between the @code{make-temp-name} call and the creation of
+the file, which in some cases may cause a security hole.
+@end defun
+
@node File Name Completion
@subsection File Name Completion
@cindex file name completion subroutines
@section Making Certain File Names ``Magic''
@cindex magic file names
-@c Emacs 19 feature
You can implement special handling for certain file names. This is
called making those names @dfn{magic}. The principal use for this
feature is in implementing remote file names (@pxref{Remote Files,,
To define a kind of magic file name, you must supply a regular
expression to define the class of names (all those that match the
regular expression), plus a handler that implements all the primitive
-Emacs file operations for file names that do match.
+Emacs file operations for file names that match.
@vindex file-name-handler-alist
The variable @code{file-name-handler-alist} holds a list of handlers,
@chapter Documentation
@cindex documentation strings
- GNU Emacs Lisp has convenient on-line help facilities, most of which
-derive their information from the documentation strings associated with
-functions and variables. This chapter describes how to write good
-documentation strings for your Lisp programs, as well as how to write
-programs to access documentation.
+ 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.
Note that the documentation strings for Emacs are not the same thing
as the Emacs manual. Manuals have their own source files, written in
topics of discussion.
For commands to display documentation strings, see @ref{Help, ,
-Help, emacs, The GNU Emacs Manual}. For the conventions for writing
-documentation strings, see @ref{Documentation Tips}.
+Help, emacs, The GNU Emacs Manual}.
@menu
-* Documentation Basics:: Good style for doc strings.
- Where to put them. How Emacs stores them.
+* Documentation Basics:: Where doc strings are defined and stored.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
* Describing Characters:: Making printable descriptions of
documentation string follows the initial value of the variable.
When you write a documentation string, make the first line a
-complete sentence (or two complete sentences) since some commands,
-such as @code{apropos}, show only the first line of a multi-line
-documentation string. Also, you should not indent the second line of
-a documentation string, if it has one, because that looks odd when you
+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 doc strings; see @ref{Documentation
-Tips}.
+are many other conventions for documentation strings; see
+@ref{Documentation Tips}.
Documentation strings can contain several special substrings, which
stand for key bindings to be looked up in the current keymaps when the
Emacs Lisp mode fills documentation strings to the width
specified by @code{emacs-lisp-docstring-fill-column}.
- In Emacs Lisp, a documentation string is accessible through the
-function or variable that it describes:
+ 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
-The documentation for a function is usually stored in the function
-definition itself (@pxref{Lambda Expressions} and @pxref{Function
-Documentation}). The function @code{documentation} knows how to
-extract it. You can also put function documentation in the
-@code{function-documentation} property of the function name. That is
-useful with definitions such as keyboard macros that can't hold a
-documentation string.
+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
-The documentation for a variable is stored in the variable's property
-list under the property name @code{variable-documentation}. The
-function @code{documentation-property} knows how to retrieve it.
-@end itemize
+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.
@cindex @file{DOC-@var{version}} (documentation) file
-To save space, the documentation for preloaded functions and variables
-(including primitive functions and autoloaded functions) is stored in
-the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
-documentation strings for functions and variables loaded during the
-Emacs session from byte-compiled files are stored in those files
-(@pxref{Docs and Compilation}).
-
-The data structure inside Emacs has an integer offset into the file, or
-a list containing a file name and an integer, in place of the
-documentation string. The functions @code{documentation} and
-@code{documentation-property} use that information to fetch the
-documentation string from the appropriate file; this is transparent to
-the user.
+@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-@var{version}}, where @var{version} is the Emacs
+version number (@pxref{Version Info}).
+
+@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
+
+@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.
@node Accessing Documentation
@section Access to Documentation Strings
@defun documentation-property symbol property &optional verbatim
-This function returns the documentation string that is recorded in
-@var{symbol}'s property list under property @var{property}. It
-retrieves the text from a file if the value calls for that. If the
-property value isn't @code{nil}, isn't a string, and doesn't refer to
-text in a file, then it is evaluated to obtain a string.
+This function returns the documentation string recorded in
+@var{symbol}'s property list under property @var{property}. It is
+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).
+
+If the value recorded in the property list refers to a documentation
+string stored in a @file{DOC-@var{version}} 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.
The last thing this function does is pass the string through
-@code{substitute-command-keys} to substitute actual key bindings,
-unless @var{verbatim} is non-@code{nil}.
+@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}.
@smallexample
@group
@end group
@end smallexample
-@defun Snarf-documentation filename
@anchor{Definition of Snarf-documentation}
-This function is used only during Emacs initialization, just before
-the runnable Emacs is dumped. It finds the file offsets of the
-documentation strings stored in the file @var{filename}, and records
-them in the in-core function definitions and variable property lists in
-place of the actual strings. @xref{Building Emacs}.
+@defun Snarf-documentation filename
+This function is used when building Emacs, just before the runnable
+Emacs is dumped. It finds the positions of the documentation strings
+stored in the file @var{filename}, and records those positions into
+memory in the function definitions and variable property lists.
+@xref{Building Emacs}.
Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
When the dumped Emacs is later executed, the same file will be looked
The function returns a list of elements that look like this:
@example
-(@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
+(@var{symbol} @var{score} @var{function-doc} @var{variable-doc}
@var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
@end example
Here, @var{score} is an integer measure of how important the symbol
-seems to be as a match, and the remaining elements are documentation
-strings for @var{symbol}'s various roles (or @code{nil}).
+seems to be as a match. Each of the remaining elements is a
+documentation string, or @code{nil}, for @var{symbol} as a function,
+variable, etc.
It also displays the symbols in a buffer named @samp{*Apropos*}, each
with a one-line description taken from the beginning of its
@item lisp-indent-function
@item mail-setup-hook
-@xref{Mail Mode Misc,, Mail Mode Miscellany, emacs, the GNU Emacs
-Manual}.
+@xref{Mail Misc,, Mail Miscellany, emacs, the GNU Emacs Manual}.
@item menu-bar-update-hook
@xref{Menu Bar}.
for more details.
@item (doc-string @var{number})
-Specify which element of the macro is the doc string, if any.
+Specify which element of the macro is the documentation string, if
+any.
@end table
A @code{declare} form only has its special effect in the body of a
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
+* Mode Hooks:: Hooks run at the end of major mode commands.
+* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
-* Mode Hooks:: Hooks run at the end of major mode commands.
* Example Major Modes:: Text mode and Lisp modes.
@end menu
more buffer-local entries to the special hook
@code{completion-at-point-functions}. @xref{Completion in Buffers}.
-@item
-Use @code{defvar} or @code{defcustom} to set mode-related variables, so
-that they are not reinitialized if they already have a value. (Such
-reinitialization could discard customizations made by the user.)
-
@item
@cindex buffer-local variables in modes
To make a buffer-local binding for an Emacs customization variable, use
not autoload the mode command, it is sufficient to add the element in
the file that contains the mode definition.
-@item
-In the comments that document the file, you should provide a sample
-@code{autoload} form and an example of how to add to
-@code{auto-mode-alist}, that users can include in their init files
-(@pxref{Init File}).
-
@item
@cindex mode loading
The top-level forms in the file defining the mode should be written so
that they may be evaluated more than once without adverse consequences.
+For instance, use @code{defvar} or @code{defcustom} to set mode-related
+variables, so that they are not reinitialized if they already have a
+value (@pxref{Defining Variables}).
+
@end itemize
@node Auto Major Mode
mode no parent. Then @code{define-derived-mode} behaves as described
above, but, of course, omits all actions connected with @var{parent}.
-The argument @var{docstring} specifies the documentation string for
-the new mode. @code{define-derived-mode} adds some general
-information about the mode's hook, followed by the mode's keymap, at
-the end of this docstring. If you omit @var{docstring},
+The argument @var{docstring} specifies the documentation string for the
+new mode. @code{define-derived-mode} adds some general information
+about the mode's hook, followed by the mode's keymap, at the end of this
+documentation string. If you omit @var{docstring},
@code{define-derived-mode} generates a documentation string.
The @var{keyword-args} are pairs of keywords and values. The values
@deffn Command special-mode
Special mode is a basic major mode for buffers containing text that is
-produced specially by Emacs, rather than from a file. Major modes
-derived from Special mode are given a @code{mode-class} property of
-@code{special} (@pxref{Major Mode Conventions}).
+produced specially by Emacs, rather than directly from a file. Major
+modes derived from Special mode are given a @code{mode-class} property
+of @code{special} (@pxref{Major Mode Conventions}).
Special mode sets the buffer to read-only. Its keymap defines several
common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
@end deffn
-@cindex tables of data
-@deffn Command tabulated-list-mode
-Tabulated List mode is another mode that derives from Special mode. It
-displays tabulated data, i.e. a series of rows and columns, where each
-row represents a particular entry, whose properties are displayed in the
-various columns. It provides a general mechanism for sorting on
-columns. You can use Tabulated List mode as the basis for other modes
-that need to display lists. For example, the @samp{*Packages*} buffer
-uses this (@pxref{Packages,,, emacs, The GNU Emacs Manual}). The
-documentation of the @code{tabulated-list-mode} function explains what
-you need to do to use it. At a minimum, specify the column format via
-the @code{tabulated-list-format} variable.
-@end deffn
-
-@node Generic Modes
-@subsection Generic Modes
-@cindex generic mode
-
- @dfn{Generic modes} are simple major modes with basic support for
-comment syntax and Font Lock mode. To define a generic mode, use the
-macro @code{define-generic-mode}. See the file @file{generic-x.el}
-for some examples of the use of @code{define-generic-mode}.
-
-@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
-This macro defines a generic mode command named @var{mode} (a symbol,
-not quoted). The optional argument @var{docstring} is the
-documentation for the mode command. If you do not supply it,
-@code{define-generic-mode} generates one by default.
-
-The argument @var{comment-list} is a list in which each element is
-either a character, a string of one or two characters, or a cons cell.
-A character or a string is set up in the mode's syntax table as a
-``comment starter.'' If the entry is a cons cell, the @sc{car} is set
-up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
-(Use @code{nil} for the latter if you want comments to end at the end
-of the line.) Note that the syntax table mechanism has limitations
-about what comment starters and enders are actually possible.
-@xref{Syntax Tables}.
-
-The argument @var{keyword-list} is a list of keywords to highlight
-with @code{font-lock-keyword-face}. Each keyword should be a string.
-Meanwhile, @var{font-lock-list} is a list of additional expressions to
-highlight. Each element of this list should have the same form as an
-element of @code{font-lock-keywords}. @xref{Search-based
-Fontification}.
-
-The argument @var{auto-mode-list} is a list of regular expressions to
-add to the variable @code{auto-mode-alist}. They are added by the execution
-of the @code{define-generic-mode} form, not by expanding the macro call.
-
-Finally, @var{function-list} is a list of functions for the mode
-command to call for additional setup. It calls these functions just
-before it runs the mode hook variable @code{@var{mode}-hook}.
-@end defmac
+ In addition, modes for buffers of tabulated data can inherit from
+Tabulated List mode, which is in turn derived from Special mode.
+@xref{Tabulated List Mode}.
@node Mode Hooks
@subsection Mode Hooks
very end of every properly-written major mode command.
@end defvar
+@node Tabulated List Mode
+@subsection Tabulated List mode
+@cindex Tabulated List mode
+
+ Tabulated List mode is a major mode for displaying tabulated data,
+i.e.@: data consisting of @dfn{entries}, each entry occupying one row of
+text with its contents divided into columns. Tabulated List mode
+provides facilities for pretty-printing rows and columns, and sorting
+the rows according to the values in each column. It is derived from
+Special mode (@pxref{Basic Major Modes}).
+
+ Tabulated List mode is intended to be used as a parent mode by a more
+specialized major mode. Examples include Process Menu mode
+(@pxref{Process Information}) and Package Menu mode (@pxref{Package
+Menu,,, emacs, The GNU Emacs Manual}).
+
+@findex tabulated-list-mode
+ Such a derived mode should use @code{define-derived-mode} in the usual
+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.
+
+ 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
+list-processes}). The listing command should create or switch to a
+buffer, turn on the derived mode, specify the tabulated data, and
+finally call @code{tabulated-list-print} to populate the buffer.
+
+@defvar tabulated-list-format
+This buffer-local variable specifies the format of the Tabulated List
+data. Its value should be a vector. Each element of the vector
+represents a data column, and should be a list @code{(@var{name}
+@var{width} @var{sort})}, where
+
+@itemize
+@item
+@var{name} is the column's name (a string).
+
+@item
+@var{width} is the width to reserve for the column (an integer). This
+is meaningless for the last column, which runs to the end of each line.
+
+@item
+@var{sort} specifies how to sort entries by the column. If @code{nil},
+the column cannot be used for sorting. If @code{t}, the column is
+sorted by comparing string values. Otherwise, this should be a
+predicate function for @code{sort} (@pxref{Rearrangement}), which
+accepts two arguments with the same form as the elements of
+@code{tabulated-list-entries} (see below).
+@end itemize
+@end defvar
+
+@defvar tabulated-list-entries
+This buffer-local variable specifies the entries displayed in the
+Tabulated List buffer. Its value should be either a list, or a
+function.
+
+If the value is a list, each list element corresponds to one entry, and
+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
+re-sorting entries. Comparison is done with @code{equal}.
+
+@item
+@var{contents} is a vector with the same number of elements as
+@code{tabulated-list-format}. Each vector element is either a string,
+which is inserted into the buffer as-is, or a list @code{(@var{label}
+. @var{properties})}, which means to insert a text button by calling
+@code{insert-text-button} with @var{label} and @var{properties} as
+arguments (@pxref{Making Buttons}).
+
+There should be no newlines in any of these strings.
+@end itemize
+
+Otherwise, the value should be a function which returns a list of the
+above form when called with no arguments.
+@end defvar
+
+@defvar tabulated-list-revert-hook
+This normal hook is run prior to reverting a Tabulated List buffer. A
+derived mode can add a function to this hook to recompute
+@code{tabulated-list-entries}.
+@end defvar
+
+@defvar tabulated-list-printer
+The value of this variable is the function called to insert an entry at
+point, including its terminating newline. The function should accept
+two arguments, @var{id} and @var{contents}, having the same meanings as
+in @code{tabulated-list-entries}. The default value is a function which
+inserts an entry in a straightforward way; a mode which uses Tabulated
+List mode in a more complex way can specify another function.
+@end defvar
+
+@defvar tabulated-list-sort-key
+The value of this variable specifies the current sort key for the
+Tabulated List buffer. If it is @code{nil}, no sorting is done.
+Otherwise, it should have the form @code{(@var{name} . @var{flip})},
+where @var{name} is a string matching one of the column names in
+@code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means
+to invert the sort order.
+@end defvar
+
+@defun tabulated-list-init-header
+This function computes and sets @code{header-line-format} for the
+Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
+the header line to allow sort entries by clicking on column headers.
+
+Modes derived from Tabulated List mode should call this after setting
+the above variables (in particular, only after setting
+@code{tabulated-list-format}).
+@end defun
+
+@defun tabulated-list-print &optional remember-pos
+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
+@code{tabulated-list-sort-key}, then calls the function specified by
+@code{tabulated-list-printer} to insert each entry.
+
+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.
+@end defun
+
+@node Generic Modes
+@subsection Generic Modes
+@cindex generic mode
+
+ @dfn{Generic modes} are simple major modes with basic support for
+comment syntax and Font Lock mode. To define a generic mode, use the
+macro @code{define-generic-mode}. See the file @file{generic-x.el}
+for some examples of the use of @code{define-generic-mode}.
+
+@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
+This macro defines a generic mode command named @var{mode} (a symbol,
+not quoted). The optional argument @var{docstring} is the
+documentation for the mode command. If you do not supply it,
+@code{define-generic-mode} generates one by default.
+
+The argument @var{comment-list} is a list in which each element is
+either a character, a string of one or two characters, or a cons cell.
+A character or a string is set up in the mode's syntax table as a
+``comment starter.'' If the entry is a cons cell, the @sc{car} is set
+up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
+(Use @code{nil} for the latter if you want comments to end at the end
+of the line.) Note that the syntax table mechanism has limitations
+about what comment starters and enders are actually possible.
+@xref{Syntax Tables}.
+
+The argument @var{keyword-list} is a list of keywords to highlight
+with @code{font-lock-keyword-face}. Each keyword should be a string.
+Meanwhile, @var{font-lock-list} is a list of additional expressions to
+highlight. Each element of this list should have the same form as an
+element of @code{font-lock-keywords}. @xref{Search-based
+Fontification}.
+
+The argument @var{auto-mode-list} is a list of regular expressions to
+add to the variable @code{auto-mode-alist}. They are added by the execution
+of the @code{define-generic-mode} form, not by expanding the macro call.
+
+Finally, @var{function-list} is a list of functions for the mode
+command to call for additional setup. It calls these functions just
+before it runs the mode hook variable @code{@var{mode}-hook}.
+@end defmac
+
@node Example Major Modes
@subsection Major Mode Examples
@section Minor Modes
@cindex minor mode
- A @dfn{minor mode} provides features that users may enable or disable
-independently of the choice of major mode. Minor modes can be enabled
-individually or in combination. Minor modes would be better named
-``generally available, optional feature modes,'' except that such a name
-would be unwieldy.
-
- A minor mode is not usually meant as a variation of a single major mode.
-Usually they are general and can apply to many major modes. For
-example, Auto Fill mode works with any major mode that permits text
-insertion. To be general, a minor mode must be effectively independent
-of the things major modes do.
+ A @dfn{minor mode} provides optional features that users may enable or
+disable independently of the choice of major mode. Minor modes can be
+enabled individually or in combination.
- A minor mode is often much more difficult to implement than a major
-mode. One reason is that you should be able to activate and deactivate
-minor modes in any order. A minor mode should be able to have its
-desired effect regardless of the major mode and regardless of the other
-minor modes in effect.
+ Most minor modes implement features that are independent of the major
+mode, and can thus be used with most major modes. For example, Auto
+Fill mode works with any major mode that permits text insertion. A few
+minor modes, however, are specific to a particular major mode. For
+example, Diff Auto Refine mode is a minor mode that is intended to be
+used only with Diff mode.
- Often the biggest problem in implementing a minor mode is finding a
-way to insert the necessary hook into the rest of Emacs. Minor mode
-keymaps make this easier than it used to be.
+ Ideally, a minor mode should have its desired effect regardless of the
+other minor modes in effect. It should be possible to activate and
+deactivate minor modes in any order.
@defvar minor-mode-list
The value of this variable is a list of all minor mode commands.
@cindex conventions for writing minor modes
There are conventions for writing minor modes just as there are for
-major modes. Several of the major mode conventions apply to minor
-modes as well: those regarding the name of the mode initialization
-function, the names of global symbols, the use of a hook at the end of
-the initialization function, and the use of keymaps and other tables.
-
- In addition, there are several conventions that are specific to
-minor modes. (The easiest way to follow all the conventions is to use
-the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
+major modes. These conventions are described below. The easiest way to
+follow them is to use the macro @code{define-minor-mode}.
+@xref{Defining Minor Modes}.
@itemize @bullet
@item
@cindex mode variable
-Make a variable whose name ends in @samp{-mode} to control the minor
-mode. We call this the @dfn{mode variable}. The minor mode command
-should set this variable (@code{nil} to disable; anything else to
-enable).
-
-If possible, implement the mode so that setting the variable
-automatically enables or disables the mode. Then the minor mode command
-does not need to do anything except set the variable.
+Define a variable whose name ends in @samp{-mode}. We call this the
+@dfn{mode variable}. The minor mode command should set this variable.
+The value will be @code{nil} is the mode is disabled, and non-@code{nil}
+if the mode is enabled. The variable should be buffer-local if the
+minor mode is buffer-local.
This variable is used in conjunction with the @code{minor-mode-alist} to
-display the minor mode name in the mode line. It can also enable
-or disable a minor mode keymap. Individual commands or hooks can also
-check the variable's value.
-
-If you want the minor mode to be enabled separately in each buffer,
-make the variable buffer-local.
+display the minor mode name in the mode line. It also determines
+whether the minor mode keymap is active, via @code{minor-mode-map-alist}
+(@pxref{Controlling Active Maps}). Individual commands or hooks can
+also check its value.
@item
-Define a command whose name is the same as the mode variable.
-Its job is to enable and disable the mode by setting the variable.
+Define a command, called the @dfn{mode command}, whose name is the same
+as the mode variable. Its job is to set the value of the mode variable,
+plus anything else that needs to be done to actually enable or disable
+the mode's features.
-The command should accept one optional argument. If the argument is
-@code{nil}, it should toggle the mode (turn it on if it is off, and
-off if it is on). It should turn the mode on if the argument is a
-positive integer, the symbol @code{t}, or a list whose @sc{car} is one
-of those. It should turn the mode off if the argument is a negative
-integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
-negative integer or zero. The meaning of other arguments is not
-specified.
+The mode command should accept one optional argument. If called
+interactively with no prefix argument, it should toggle the mode
+(i.e.@: enable if it is disabled, and disable if it is enabled). If
+called interactively with a prefix argument, it should enable the mode
+if the argument is positive and disable it otherwise.
-Here is an example taken from the definition of @code{transient-mark-mode}.
-It shows the use of @code{transient-mark-mode} as a variable that enables or
-disables the mode's behavior, and also shows the proper way to toggle,
-enable or disable the minor mode based on the raw prefix argument value.
+If the mode command is called from Lisp (i.e.@: non-interactively), it
+should enable the mode if the argument is omitted or @code{nil}; it
+should toggle the mode if the argument is the symbol @code{toggle};
+otherwise it should treat the argument in the same way as for an
+interactive call with a numeric prefix argument, as described above.
-@smallexample
-@group
-(setq transient-mark-mode
- (if (null arg) (not transient-mark-mode)
- (> (prefix-numeric-value arg) 0)))
-@end group
-@end smallexample
+The following example shows how to implement this behavior (it is
+similar to the code generated by the @code{define-minor-mode} macro):
+
+@example
+(interactive (list (or current-prefix-arg 'toggle)))
+(let ((enable (if (eq arg 'toggle)
+ (not foo-mode) ; @r{this mode's mode variable}
+ (> (prefix-numeric-value arg) 0))))
+ (if enable
+ @var{do-enable}
+ @var{do-disable}))
+@end example
+
+The reason for this somewhat complex behavior is that it lets users
+easily toggle the minor mode interactively, and also lets the minor mode
+be easily enabled in a mode hook, like this:
+
+@example
+(add-hook 'text-mode-hook 'foo-mode)
+@end example
+
+@noindent
+This behaves correctly whether or not @code{foo-mode} was already
+enabled, since the @code{foo-mode} mode command unconditionally enables
+the minor mode when it is called from Lisp with no argument. Disabling
+a minor mode in a mode hook is a little uglier:
+
+@example
+(add-hook 'text-mode-hook (lambda () (foo-mode -1)))
+@end example
+
+@noindent
+However, this is not very commonly done.
@item
Add an element to @code{minor-mode-alist} for each minor mode
@smallexample
@group
(unless (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
+ (push '(leif-mode " Leif") minor-mode-alist))
@end group
@end smallexample
@end smallexample
@end itemize
- Global minor modes distributed with Emacs should if possible support
-enabling and disabling via Custom (@pxref{Customization}). To do this,
-the first step is to define the mode variable with @code{defcustom}, and
-specify @code{:type 'boolean}.
+ In addition, several major mode conventions apply to minor modes as
+well: those regarding the names of global symbols, the use of a hook at
+the end of the initialization function, and the use of keymaps and other
+tables.
- If just setting the variable is not sufficient to enable the mode, you
+ The minor mode should, if possible, support enabling and disabling via
+Custom (@pxref{Customization}). To do this, the mode variable should be
+defined with @code{defcustom}, usually with @code{:type 'boolean}. If
+just setting the variable is not sufficient to enable the mode, you
should also specify a @code{:set} method which enables the mode by
-invoking the mode command. Note in the variable's documentation string that
-setting the variable other than via Custom may not take effect.
-
- Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
-and specify a @code{:require} so that customizing the variable will load
-the library that defines the mode. This will copy suitable definitions
-into @file{loaddefs.el} so that users can use @code{customize-option} to
-enable the mode. For example:
+invoking the mode command. Note in the variable's documentation string
+that setting the variable other than via Custom may not take effect.
+Also, mark the definition with an autoload cookie (@pxref{autoload
+cookie}), and specify a @code{:require} so that customizing the variable
+will load the library that defines the mode. For example:
@smallexample
@group
-
;;;###autoload
(defcustom msb-mode nil
"Toggle msb-mode.
@node Mode Line Format
-@section Mode-Line Format
+@section Mode Line Format
@cindex mode line
Each Emacs window (aside from minibuffer windows) typically has a mode
@node Mode Line Basics
@subsection Mode Line Basics
- @code{mode-line-format} is a buffer-local variable that holds a
-@dfn{mode line construct}, a kind of template, which controls what is
-displayed on the mode line of the current buffer. The value of
-@code{header-line-format} specifies the buffer's header line in the
-same way. All windows for the same buffer use the same
+ The contents of each mode line are specified by the buffer-local
+variable @code{mode-line-format} (@pxref{Mode Line Top}). This variable
+holds a @dfn{mode line construct}: a template that controls what is
+displayed on the buffer's mode line. The value of
+@code{header-line-format} specifies the buffer's header line in the same
+way. All windows for the same buffer use the same
@code{mode-line-format} and @code{header-line-format}.
- For efficiency, Emacs does not continuously recompute the mode
-line and header line of a window. It does so when circumstances
-appear to call for it---for instance, if you change the window
-configuration, switch buffers, narrow or widen the buffer, scroll, or
-change the buffer's modification status. If you modify any of the
-variables referenced by @code{mode-line-format} (@pxref{Mode Line
-Variables}), or any other variables and data structures that affect
-how text is displayed (@pxref{Display}), you may want to force an
-update of the mode line so as to display the new information or
-display it in the new way.
+ For efficiency, Emacs does not continuously recompute each window's
+mode line and header line. It does so when circumstances appear to call
+for it---for instance, if you change the window configuration, switch
+buffers, narrow or widen the buffer, scroll, or modify the buffer. If
+you alter any of the variables referenced by @code{mode-line-format} or
+@code{header-line-format} (@pxref{Mode Line Variables}), or any other
+data structures that affect how text is displayed (@pxref{Display}), you
+should use the function @code{force-mode-line-update} to update the
+display.
@defun force-mode-line-update &optional all
-Force redisplay of the current buffer's mode line and header line.
-The next redisplay will update the mode line and header line based on
-the latest values of all relevant variables. With optional
-non-@code{nil} @var{all}, force redisplay of all mode lines and header
-lines.
-
-This function also forces recomputation of the menu bar menus
-and the frame title.
+This function forces Emacs to update the current buffer's mode line and
+header line, based on the latest values of all relevant variables,
+during its next redisplay cycle. If the optional argument @var{all} is
+non-@code{nil}, it forces an update for all mode lines and header lines.
+
+This function also forces an update of the menu bar and frame title.
@end defun
The selected window's mode line is usually displayed in a different
-color using the face @code{mode-line}. Other windows' mode lines
-appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
+color using the face @code{mode-line}. Other windows' mode lines appear
+in the face @code{mode-line-inactive} instead. @xref{Faces}.
@node Mode Line Data
@subsection The Data Structure of the Mode Line
-@cindex mode-line construct
+@cindex mode line construct
- The mode-line contents are controlled by a data structure called a
-@dfn{mode-line construct}, made up of lists, strings, symbols, and
+ The mode line contents are controlled by a data structure called a
+@dfn{mode line construct}, made up of lists, strings, symbols, and
numbers kept in buffer-local variables. Each data type has a specific
-meaning for the mode-line appearance, as described below. The same
-data structure is used for constructing frame titles (@pxref{Frame
-Titles}) and header lines (@pxref{Header Lines}).
+meaning for the mode line appearance, as described below. The same data
+structure is used for constructing frame titles (@pxref{Frame Titles})
+and header lines (@pxref{Header Lines}).
- A mode-line construct may be as simple as a fixed string of text,
+ A mode line construct may be as simple as a fixed string of text,
but it usually specifies how to combine fixed strings with variables'
values to construct the text. Many of these variables are themselves
-defined to have mode-line constructs as their values.
+defined to have mode line constructs as their values.
- Here are the meanings of various data types as mode-line constructs:
+ Here are the meanings of various data types as mode line constructs:
@table @code
@cindex percent symbol in mode line
@item @var{string}
-A string as a mode-line construct appears verbatim except for
+A string as a mode line construct appears verbatim except for
@dfn{@code{%}-constructs} in it. These stand for substitution of
other data; see @ref{%-Constructs}.
special meanings. @xref{Properties in Mode}.
@item @var{symbol}
-A symbol as a mode-line construct stands for its value. The value of
-@var{symbol} is used as a mode-line construct, in place of @var{symbol}.
+A symbol as a mode line construct stands for its value. The value of
+@var{symbol} is used as a mode line construct, in place of @var{symbol}.
However, the symbols @code{t} and @code{nil} are ignored, as is any
symbol whose value is void.
Unless @var{symbol} is marked as ``risky'' (i.e., it has a
non-@code{nil} @code{risky-local-variable} property), all text
-properties specified in @var{symbol}'s value are ignored. This
-includes the text properties of strings in @var{symbol}'s value, as
-well as all @code{:eval} and @code{:propertize} forms in it. (The
-reason for this is security: non-risky variables could be set
-automatically from file variables without prompting the user.)
+properties specified in @var{symbol}'s value are ignored. This includes
+the text properties of strings in @var{symbol}'s value, as well as all
+@code{:eval} and @code{:propertize} forms in it. (The reason for this
+is security: non-risky variables could be set automatically from file
+variables without prompting the user.)
@item (@var{string} @var{rest}@dots{})
@itemx (@var{list} @var{rest}@dots{})
A list whose first element is a string or list means to process all the
elements recursively and concatenate the results. This is the most
-common form of mode-line construct.
+common form of mode line construct.
@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
@item (:propertize @var{elt} @var{props}@dots{})
A list whose first element is the symbol @code{:propertize} says to
-process the mode-line construct @var{elt} recursively, then add the text
+process the mode line construct @var{elt} recursively, then add the text
properties specified by @var{props} to the result. The argument
@var{props} should consist of zero or more pairs @var{text-property}
-@var{value}. (This feature is new as of Emacs 22.1.)
+@var{value}.
@item (@var{symbol} @var{then} @var{else})
A list whose first element is a symbol that is not a keyword specifies
a conditional. Its meaning depends on the value of @var{symbol}. If
@var{symbol} has a non-@code{nil} value, the second element,
-@var{then}, is processed recursively as a mode-line element.
+@var{then}, is processed recursively as a mode line element.
Otherwise, the third element, @var{else}, is processed recursively.
-You may omit @var{else}; then the mode-line element displays nothing
+You may omit @var{else}; then the mode line element displays nothing
if the value of @var{symbol} is @code{nil} or void.
@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
padding of the results of @var{rest}. The remaining elements
-@var{rest} are processed recursively as mode-line constructs and
+@var{rest} are processed recursively as mode line constructs and
concatenated together. When @var{width} is positive, the result is
space filled on the right if its width is less than @var{width}. When
@var{width} is negative, the result is truncated on the right to
@code{mode-line-format}.
@defopt mode-line-format
-The value of this variable is a mode-line construct that controls the
+The value of this variable is a mode line construct that controls the
contents of the mode-line. It is always buffer-local in all buffers.
-If you set this variable to @code{nil} in a buffer, that buffer does
-not have a mode line. (A window that is just one line tall never
-displays a mode line.)
+If you set this variable to @code{nil} in a buffer, that buffer does not
+have a mode line. (A window that is just one line tall also does not
+display a mode line.)
@end defopt
The default value of @code{mode-line-format} is designed to use the
the user or by Lisp programs (such as @code{display-time} and major
modes) via changes to those variables remain effective.
- Here is an example of a @code{mode-line-format} that might be
-useful for @code{shell-mode}, since it contains the host name and default
-directory.
+ Here is a hypothetical example of a @code{mode-line-format} that might
+be useful for Shell mode (in reality, Shell mode does not set
+@code{mode-line-format}):
@example
@group
@end group
@group
;; @r{Note that this is evaluated while making the list.}
- ;; @r{It makes a mode-line construct which is just a string.}
+ ;; @r{It makes a mode line construct which is just a string.}
(getenv "HOST")
@end group
":"
'(which-func-mode ("" which-func-format "--"))
'(line-number-mode "L%l--")
'(column-number-mode "C%c--")
- '(-3 "%p")
- "-%-"))
+ '(-3 "%p")))
@end group
@end example
@node Mode Line Variables
@subsection Variables Used in the Mode Line
- This section describes variables incorporated by the standard value
-of @code{mode-line-format} into the text of the mode line. There is
+ This section describes variables incorporated by the standard value of
+@code{mode-line-format} into the text of the mode line. There is
nothing inherently special about these variables; any other variables
-could have the same effects on the mode line if
-@code{mode-line-format}'s value were changed to use them. However,
-various parts of Emacs set these variables on the understanding that
-they will control parts of the mode line; therefore, practically
-speaking, it is essential for the mode line to use them.
+could have the same effects on the mode line if the value of
+@code{mode-line-format} is changed to use them. However, various parts
+of Emacs set these variables on the understanding that they will control
+parts of the mode line; therefore, practically speaking, it is essential
+for the mode line to use them.
@defvar mode-line-mule-info
-This variable holds the value of the mode-line construct that displays
+This variable holds the value of the mode line construct that displays
information about the language environment, buffer coding system, and
current input method. @xref{Non-ASCII Characters}.
@end defvar
@defvar mode-line-modified
-This variable holds the value of the mode-line construct that displays
+This variable holds the value of the mode line construct that displays
whether the current buffer is modified. Its default value displays
@samp{**} if the buffer is modified, @samp{--} if the buffer is not
modified, @samp{%%} if the buffer is read only, and @samp{%*} if the
@end defvar
@defvar mode-line-process
-This buffer-local variable contains the mode-line information on process
+This buffer-local variable contains the mode line information on process
status in modes used for communicating with subprocesses. It is
displayed immediately following the major mode name, with no intervening
space. For example, its value in the @samp{*shell*} buffer is
(@var{minor-mode-variable} @var{mode-line-string})
@end example
-More generally, @var{mode-line-string} can be any mode-line spec. It
-appears in the mode line when the value of @var{minor-mode-variable}
+More generally, @var{mode-line-string} can be any mode line construct.
+It appears in the mode line when the value of @var{minor-mode-variable}
is non-@code{nil}, and not otherwise. These strings should begin with
spaces so that they don't run together. Conventionally, the
-@var{minor-mode-variable} for a specific mode is set to a
-non-@code{nil} value when that minor mode is activated.
+@var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
+value when that minor mode is activated.
@code{minor-mode-alist} itself is not buffer-local. Each variable
mentioned in the alist should be buffer-local if its minor mode can be
@end defvar
@defvar global-mode-string
-This variable holds a mode-line spec that, by default, appears in the
-mode line just after the @code{which-func-mode} minor mode if set,
-else after @code{mode-line-modes}. The command @code{display-time}
-sets @code{global-mode-string} to refer to the variable
-@code{display-time-string}, which holds a string containing the time
-and load information.
+This variable holds a mode line construct that, by default, appears in
+the mode line just after the @code{which-func-mode} minor mode if set,
+else after @code{mode-line-modes}. The command @code{display-time} sets
+@code{global-mode-string} to refer to the variable
+@code{display-time-string}, which holds a string containing the time and
+load information.
The @samp{%M} construct substitutes the value of
@code{global-mode-string}, but that is obsolete, since the variable is
@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line
- Strings used as mode-line constructs can use certain
+ Strings used as mode line constructs can use certain
@code{%}-constructs to substitute various kinds of data. Here is a
list of the defined @code{%}-constructs, and what they mean. In any
construct except @samp{%%}, you can add a decimal integer after the
@item %p
The percentage of the buffer text above the @strong{top} of window, or
-@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
-mode-line specification truncates this to three characters.
+@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default mode
+line construct truncates this to three characters.
@item %P
The percentage of the buffer text that is above the @strong{bottom} of
@enumerate
@item
-Put a string with a text property directly into the mode-line data
+Put a string with a text property directly into the mode line data
structure.
@item
-Put a text property on a mode-line %-construct such as @samp{%12b}; then
+Put a text property on a mode line %-construct such as @samp{%12b}; then
the expansion of the %-construct will have that same text property.
@item
give @var{elt} a text property specified by @var{props}.
@item
-Use a list containing @code{:eval @var{form}} in the mode-line data
+Use a list containing @code{:eval @var{form}} in the mode line data
structure, and make @var{form} evaluate to a string that has a text
property.
@end enumerate
@cindex header line (of a window)
@cindex window header line
- A window can have a @dfn{header line} at the
-top, just as it can have a mode line at the bottom. The header line
-feature works just like the mode-line feature, except that it's
-controlled by different variables.
+ A window can have a @dfn{header line} at the top, just as it can have
+a mode line at the bottom. The header line feature works just like the
+mode line feature, except that it's controlled by
+@code{header-line-format}:
@defvar header-line-format
This variable, local in every buffer, specifies how to display the
header line.
@node Emulating Mode Line
-@subsection Emulating Mode-Line Formatting
+@subsection Emulating Mode Line Formatting
- You can use the function @code{format-mode-line} to compute
-the text that would appear in a mode line or header line
-based on a certain mode-line specification.
+ You can use the function @code{format-mode-line} to compute the text
+that would appear in a mode line or header line based on a certain
+mode line construct.
@defun format-mode-line format &optional face window buffer
This function formats a line of text according to @var{format} as if it
@section Font Lock Mode
@cindex Font Lock mode
- @dfn{Font Lock mode} is a feature that automatically attaches
-@code{face} properties to certain parts of the buffer based on their
-syntactic role. How it parses the buffer depends on the major mode;
-most major modes define syntactic criteria for which faces to use in
-which contexts. This section explains how to customize Font Lock for a
-particular major mode.
+ @dfn{Font Lock mode} is a buffer-local minor mode that automatically
+attaches @code{face} properties to certain parts of the buffer based on
+their syntactic role. How it parses the buffer depends on the major
+mode; most major modes define syntactic criteria for which faces to use
+in which contexts. This section explains how to customize Font Lock for
+a particular major mode.
Font Lock mode finds text to highlight in two ways: through
syntactic parsing based on the syntax table, and through searching
contents can also specify how to fontify it.
* Faces for Font Lock:: Special faces specifically for Font Lock.
* Syntactic Font Lock:: Fontification based on syntax tables.
-* Setting Syntax Properties:: Defining character syntax based on context
- using the Font Lock mechanism.
* Multiline Font Lock:: How to coerce Font Lock into properly
highlighting multiline constructs.
@end menu
Lock mode is enabled, to set all the other variables.
@defvar font-lock-defaults
-This variable is set by major modes, as a buffer-local variable, to
-specify how to fontify text in that mode. It automatically becomes
-buffer-local when you set it. If its value is @code{nil}, Font-Lock
-mode does no highlighting, and you can use the @samp{Faces} menu
-(under @samp{Edit} and then @samp{Text Properties} in the menu bar) to
-assign faces explicitly to text in the buffer.
+This variable is set by major modes to specify how to fontify text in
+that mode. It automatically becomes buffer-local when set. If its
+value is @code{nil}, Font Lock mode does no highlighting, and you can
+use the @samp{Faces} menu (under @samp{Edit} and then @samp{Text
+Properties} in the menu bar) to assign faces explicitly to text in the
+buffer.
If non-@code{nil}, the value should look like this:
The second element, @var{keywords-only}, specifies the value of the
variable @code{font-lock-keywords-only}. If this is omitted or
@code{nil}, syntactic fontification (of strings and comments) is also
-performed. If this is non-@code{nil}, such fontification is not
+performed. If this is non-@code{nil}, syntactic fontification is not
performed. @xref{Syntactic Font Lock}.
The third element, @var{case-fold}, specifies the value of
@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
-Font Lock mode ignores case when searching as directed by
-@code{font-lock-keywords}.
+Font Lock mode ignores case during search-based fontification.
-If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
-should be a list of cons cells of the form @code{(@var{char-or-string}
-. @var{string})}. These are used to set up a syntax table for
-syntactic fontification (@pxref{Syntax Table Functions}). The
-resulting syntax table is stored in @code{font-lock-syntax-table}.
+If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should
+be a list of cons cells of the form @code{(@var{char-or-string}
+. @var{string})}. These are used to set up a syntax table for syntactic
+fontification; the resulting syntax table is stored in
+@code{font-lock-syntax-table}. If @var{syntax-alist} is omitted or
+@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
@node Search-based Fontification
@subsection Search-based Fontification
- The most important variable for customizing Font Lock mode is
-@code{font-lock-keywords}. It specifies the search criteria for
-search-based fontification. You should specify the value of this
-variable with @var{keywords} in @code{font-lock-defaults}.
+ The variable which directly controls search-based fontification is
+@code{font-lock-keywords}, which is typically specified via the
+@var{keywords} element in @code{font-lock-defaults}.
@defvar font-lock-keywords
-This variable's value is a list of the keywords to highlight. Be
-careful when composing regular expressions for this list; a poorly
-written pattern can dramatically slow things down!
+The value of this variable is a list of the keywords to highlight. Lisp
+programs should not set this variable directly. Normally, the value is
+automatically set by Font Lock mode, using the @var{keywords} element in
+@code{font-lock-defaults}. The value can also be altered using the
+functions @code{font-lock-add-keywords} and
+@code{font-lock-remove-keywords} (@pxref{Customizing Keywords}).
@end defvar
Each element of @code{font-lock-keywords} specifies how to find
"\\<foo\\>"
@end example
-The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
-for calculating optimal regular expressions to match a number of
-different keywords.
+Be careful when composing these regular expressions; a poorly written
+pattern can dramatically slow things down! The function
+@code{regexp-opt} (@pxref{Regexp Functions}) is useful for calculating
+optimal regular expressions to match several keywords.
@item @var{function}
Find text by calling @var{function}, and highlight the matches
@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
and @code{java-font-lock-extra-types}, for example.
-@strong{Warning:} major mode commands must not call
+@strong{Warning:} Major mode commands must not call
@code{font-lock-add-keywords} under any circumstances, either directly
or indirectly, except through their mode hooks. (Doing so would lead to
incorrect behavior for some minor modes.) They should set up their
@code{font-lock-add-keywords} apply here too.
@end defun
- For example, this code
+ For example, the following code adds two fontification patterns for C
+mode: one to fontify the word @samp{FIXME}, even in comments, and
+another to fontify the words @samp{and}, @samp{or} and @samp{not} as
+keywords.
@smallexample
(font-lock-add-keywords 'c-mode
@end smallexample
@noindent
-adds two fontification patterns for C mode: one to fontify the word
-@samp{FIXME}, even in comments, and another to fontify the words
-@samp{and}, @samp{or} and @samp{not} as keywords.
-
-@noindent
-That example affects only C mode proper. To add the same patterns to
-C mode @emph{and} all modes derived from it, do this instead:
+This example affects only C mode proper. To add the same patterns to C
+mode @emph{and} all modes derived from it, do this instead:
@smallexample
(add-hook 'c-mode-hook
@node Levels of Font Lock
@subsection Levels of Font Lock
- Many major modes offer three different levels of fontification. You
+ Some major modes offer three different levels of fontification. You
can define multiple levels by using a list of symbols for @var{keywords}
in @code{font-lock-defaults}. Each symbol specifies one level of
fontification; it is up to the user to choose one of these levels,
normally by setting @code{font-lock-maximum-decoration} (@pxref{Font
-Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol
-value is used to initialize @code{font-lock-keywords}.
+Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol value
+is used to initialize @code{font-lock-keywords}.
Here are the conventions for how to define the levels of
fontification:
@cindex font lock faces
Font Lock mode can highlight using any face, but Emacs defines several
-faces specifically for syntactic highlighting. These @dfn{Font Lock
-faces} are listed below. They can also be used by major modes for
-syntactic highlighting outside of Font Lock mode (@pxref{Major Mode
-Conventions}).
+faces specifically for Font Lock to use to highlight text. These
+@dfn{Font Lock faces} are listed below. They can also be used by major
+modes for syntactic highlighting outside of Font Lock mode (@pxref{Major
+Mode Conventions}).
Each of these symbols is both a face name, and a variable whose
default value is the symbol itself. Thus, the default value of
@subsection Syntactic Font Lock
@cindex syntactic font lock
-Syntactic fontification uses the syntax table to find comments and
-string constants (@pxref{Syntax Tables}). It highlights them using
-@code{font-lock-comment-face} and @code{font-lock-string-face}
-(@pxref{Faces for Font Lock}), or whatever
-@code{font-lock-syntactic-face-function} chooses. There are several
-variables that affect syntactic fontification; you should set them by
-means of @code{font-lock-defaults} (@pxref{Font Lock Basics}).
+Syntactic fontification uses a syntax table (@pxref{Syntax Tables}) to
+find and highlight syntactically relevant text. If enabled, it runs
+prior to search-based fontification. The variable
+@code{font-lock-syntactic-face-function}, documented below, determines
+which syntactic constructs to highlight. There are several variables
+that affect syntactic fontification; you should set them by means of
+@code{font-lock-defaults} (@pxref{Font Lock Basics}).
+
+ Whenever Font Lock mode performs syntactic fontification on a stretch
+of text, it first calls the function specified by
+@code{syntax-propertize-function}. Major modes can use this to apply
+@code{syntax-table} text properties to override the buffer's syntax
+table in special cases. @xref{Syntax Properties}.
@defvar font-lock-keywords-only
-Non-@code{nil} means Font Lock should not do syntactic fontification;
-it should only fontify based on @code{font-lock-keywords}. The normal
-way for a mode to set this variable to @code{t} is with
-@var{keywords-only} in @code{font-lock-defaults}.
+If the value of this variable is non-@code{nil}, Font Lock does not do
+syntactic fontification, only search-based fontification based on
+@code{font-lock-keywords}. It is normally set by Font Lock mode based
+on the @var{keywords-only} element in @code{font-lock-defaults}.
@end defvar
@defvar font-lock-syntax-table
This variable holds the syntax table to use for fontification of
-comments and strings. Specify it using @var{syntax-alist} in
-@code{font-lock-defaults}. If this is @code{nil}, fontification uses
-the buffer's syntax table.
+comments and strings. It is normally set by Font Lock mode based on the
+@var{syntax-alist} element in @code{font-lock-defaults}. If this value
+is @code{nil}, syntactic fontification uses the buffer's syntax table
+(the value returned by the function @code{syntax-table}; @pxref{Syntax
+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. Font Lock uses this when necessary
-to get the right results for syntactic fontification.
-
-This function is called with no arguments. It should leave point at
-the beginning of any enclosing syntactic block. Typical values are
-@code{beginning-of-line} (used when the start of the line is known to
-be outside a syntactic block), or @code{beginning-of-defun} for
+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.
-
-If the value is @code{nil}, Font Lock uses
-@code{syntax-begin-function} to move back outside of any comment,
-string, or sexp. This variable is semi-obsolete; we recommend setting
-@code{syntax-begin-function} instead.
-
-Specify this variable using @var{syntax-begin} in
-@code{font-lock-defaults}.
@end defvar
@defvar font-lock-syntactic-face-function
-A function to determine which face to use for a given syntactic
-element (a string or a comment). The function is called with one
-argument, the parse state at point returned by
-@code{parse-partial-sexp}, and should return a face. The default
-value returns @code{font-lock-comment-face} for comments and
-@code{font-lock-string-face} for strings.
-
-This can be used to highlighting different kinds of strings or
-comments differently. It is also sometimes abused together with
-@code{font-lock-syntactic-keywords} to highlight constructs that span
-multiple lines, but this is too esoteric to document here.
-
-Specify this variable using @var{other-vars} in
+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).
+The value is normally set through an @var{other-vars} element in
@code{font-lock-defaults}.
-@end defvar
-@node Setting Syntax Properties
-@subsection Setting Syntax Properties
-
- Font Lock mode can be used to update @code{syntax-table} properties
-automatically (@pxref{Syntax Properties}). This is useful in
-languages for which a single syntax table by itself is not sufficient.
-
-@defvar font-lock-syntactic-keywords
-This variable enables and controls updating @code{syntax-table}
-properties by Font Lock. Its value should be a list of elements of
-this form:
-
-@example
-(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
-@end example
-
-The parts of this element have the same meanings as in the corresponding
-sort of element of @code{font-lock-keywords},
-
-@example
-(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
-@end example
-
-However, instead of specifying the value @var{facespec} to use for the
-@code{face} property, it specifies the value @var{syntax} to use for
-the @code{syntax-table} property. Here, @var{syntax} can be a string
-(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
-(as returned by @code{string-to-syntax}), or an expression whose value
-is one of those two types. @var{override} cannot be @code{prepend} or
-@code{append}.
-
-For example, an element of the form:
-
-@example
-("\\$\\(#\\)" 1 ".")
-@end example
-
-highlights syntactically a hash character when following a dollar
-character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
-Assuming that the buffer syntax table specifies hash characters to
-have comment start syntax, the element will only highlight hash
-characters that do not follow dollar characters as comments
-syntactically.
-
-An element of the form:
-
-@example
- ("\\('\\).\\('\\)"
- (1 "\"")
- (2 "\""))
-@end example
-
-highlights syntactically both single quotes which surround a single
-character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
-Assuming that the buffer syntax table does not specify single quotes
-to have quote syntax, the element will only highlight single quotes of
-the form @samp{'@var{c}'} as strings syntactically. Other forms, such
-as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
-strings.
-
-Major modes normally set this variable with @var{other-vars} in
-@code{font-lock-defaults}.
+The function is called with one argument, the parse state at point
+returned by @code{parse-partial-sexp}, and should return a face. The
+default value returns @code{font-lock-comment-face} for comments and
+@code{font-lock-string-face} for strings (@pxref{Faces for Font Lock}).
@end defvar
@node Multiline Font Lock
The @code{font-lock-multiline} property is meant to ensure proper
refontification; it does not automatically identify new multiline
-constructs. Identifying the requires that Font-Lock operate on large
-enough chunks at a time. This will happen by accident on many cases,
-which may give the impression that multiline constructs magically work.
-If you set the @code{font-lock-multiline} variable non-@code{nil},
-this impression will be even stronger, since the highlighting of those
-constructs which are found will be properly updated from then on.
-But that does not work reliably.
-
- To find multiline constructs reliably, you must either manually
-place the @code{font-lock-multiline} property on the text before
-Font-Lock looks at it, or use
-@code{font-lock-fontify-region-function}.
+constructs. Identifying the requires that Font Lock mode operate on
+large enough chunks at a time. This will happen by accident on many
+cases, which may give the impression that multiline constructs magically
+work. If you set the @code{font-lock-multiline} variable
+non-@code{nil}, this impression will be even stronger, since the
+highlighting of those constructs which are found will be properly
+updated from then on. But that does not work reliably.
+
+ To find multiline constructs reliably, you must either manually place
+the @code{font-lock-multiline} property on the text before Font Lock
+mode looks at it, or use @code{font-lock-fontify-region-function}.
@node Region to Refontify
@subsubsection Region to Fontify after a Buffer Change
the following variable:
@defvar font-lock-extend-after-change-region-function
-This buffer-local variable is either @code{nil} or a function for
-Font-Lock to call to determine the region to scan and fontify.
+This buffer-local variable is either @code{nil} or a function for Font
+Lock mode to call to determine the region to scan and fontify.
The function is given three parameters, the standard @var{beg},
@var{end}, and @var{old-len} from @code{after-change-functions}
@end defvar
@node Auto-Indentation
-@section Auto-indentation of code
+@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
indentation code will want to be somewhat friendly to syntactically
incorrect code.
-Good maintainable indentation functions usually fall into 2 categories:
+Good maintainable indentation functions usually fall into two categories:
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
it finally deletes any process whose status was @samp{Exited} or
@samp{Signaled}. It returns @code{nil}.
+The processes are shown in a buffer named @samp{*Process List*}, whose
+major mode is named Process Menu mode.
+
If @var{query-only} is non-@code{nil} then it lists only processes
whose query flag is non-@code{nil}. @xref{Query Before Exit}.
@end deffn
@cindex syntax table
@cindex text parsing
- A @dfn{syntax table} specifies the syntactic textual function of each
-character. This information is used by the @dfn{parsing functions}, the
-complex movement commands, and others to determine where words, symbols,
-and other syntactic constructs begin and end. The current syntax table
-controls the meaning of the word motion functions (@pxref{Word Motion})
-and the list motion functions (@pxref{List Motion}), as well as the
-functions in this chapter.
+ A @dfn{syntax table} specifies the syntactic role of each character
+in a buffer. It can be used to determine where words, symbols, and
+other syntactic constructs begin and end. This information is used by
+many Emacs facilities, including Font Lock mode (@pxref{Font Lock
+Mode}) and the various complex movement commands (@pxref{Motion}).
@menu
* Basics: Syntax Basics. Basic concepts of syntax tables.
-* Desc: Syntax Descriptors. How characters are classified.
+* Syntax Descriptors:: How characters are classified.
* Syntax Table Functions:: How to create, examine and alter syntax tables.
* Syntax Properties:: Overriding syntax with text properties.
* Motion and Syntax:: Moving over characters with certain syntaxes.
@node Syntax Basics
@section Syntax Table Concepts
-@ifnottex
- A @dfn{syntax table} provides Emacs with the information that
-determines the syntactic use of each character in a buffer. This
-information is used by the parsing commands, the complex movement
-commands, and others to determine where words, symbols, and other
-syntactic constructs begin and end. The current syntax table controls
-the meaning of the word motion functions (@pxref{Word Motion}) and the
-list motion functions (@pxref{List Motion}) as well as the functions in
-this chapter.
-@end ifnottex
-
A syntax table is a char-table (@pxref{Char-Tables}). The element at
index @var{c} describes the character with code @var{c}. The element's
value should be a list that encodes the syntax of the character in
feature out of Emacs Lisp for simplicity.)
Each buffer has its own major mode, and each major mode has its own
-idea of the syntactic class of various characters. For example, in Lisp
-mode, the character @samp{;} begins a comment, but in C mode, it
+idea of the syntactic class of various characters. For example, in
+Lisp mode, the character @samp{;} begins a comment, but in C mode, it
terminates a statement. To support these variations, Emacs makes the
-choice of syntax table local to each buffer. Typically, each major
-mode has its own syntax table and installs that table in each buffer
-that uses that mode. Changing this table alters the syntax in all
-those buffers as well as in any buffers subsequently put in that mode.
-Occasionally several similar modes share one syntax table.
-@xref{Example Major Modes}, for an example of how to set up a syntax
-table.
+syntax table local to each buffer. Typically, each major mode has its
+own syntax table and installs that table in each buffer that uses that
+mode. Changing this table alters the syntax in all those buffers as
+well as in any buffers subsequently put in that mode. Occasionally
+several similar modes share one syntax table. @xref{Example Major
+Modes}, for an example of how to set up a syntax table.
A syntax table can inherit the data for some characters from the
standard syntax table, while specifying other characters itself. The
@section Syntax Descriptors
@cindex syntax class
- This section describes the syntax classes and flags that denote the
-syntax of a character, and how they are represented as a @dfn{syntax
-descriptor}, which is a Lisp string that you pass to
-@code{modify-syntax-entry} to specify the syntax you want.
-
- The syntax table specifies a syntax class for each character. There
+ The syntactic role of a character is called its @dfn{syntax class}.
+Each syntax table specifies the syntax class of each character. There
is no necessary relationship between the class of a character in one
syntax table and its class in any other table.
- Each class is designated by a mnemonic character, which serves as the
-name of the class when you need to specify a class. Usually the
-designator character is one that is often assigned that class; however,
-its meaning as a designator is unvarying and independent of what syntax
-that character currently has. Thus, @samp{\} as a designator character
-always gives ``escape character'' syntax, regardless of what syntax
-@samp{\} currently has.
+ Each syntax class is designated by a mnemonic character, which
+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''
+syntax, regardless of whether the @samp{\} character actually has that
+syntax in the current syntax table.
+@ifnottex
+@xref{Syntax Class Table}, for a list of syntax classes.
+@end ifnottex
@cindex syntax descriptor
- A syntax descriptor is a Lisp string that specifies a syntax class, a
-matching character (used only for the parenthesis classes) and flags.
-The first character is the designator for a syntax class. The second
-character is the character to match; if it is unused, put a space there.
-Then come the characters for any desired flags. If no matching
-character or flags are needed, one character is sufficient.
+ A @dfn{syntax descriptor} is a Lisp string that describes the syntax
+classes and other syntactic properties of a character. When you want
+to modify the syntax of a character, that is done by calling the
+function @code{modify-syntax-entry} and passing a syntax descriptor as
+one of its arguments (@pxref{Syntax Table Functions}).
+
+ The first character in a syntax descriptor designates the syntax
+class. The second character specifies a matching character (e.g.@: in
+Lisp, the matching character for @samp{(} is @samp{)}); if there is no
+matching character, put a space there. Then come the characters for
+any desired flags.
+
+ If no matching character or flags are needed, only one character
+(specifying the syntax class) is sufficient.
For example, the syntax descriptor for the character @samp{*} in C
mode is @code{". 23"} (i.e., punctuation, matching character slot
@node Syntax Class Table
@subsection Table of Syntax Classes
- Here is a table of syntax classes, the characters that stand for them,
-their meanings, and examples of their use.
-
-@deffn {Syntax class} @w{whitespace character}
-@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-})
-separate symbols and words from each other. Typically, whitespace
-characters have no other syntactic significance, and multiple
-whitespace characters are syntactically equivalent to a single one.
-Space, tab, and formfeed are classified as whitespace in almost all
-major modes.
-@end deffn
-
-@deffn {Syntax class} @w{word constituent}
-@dfn{Word constituents} (designated by @samp{w}) are parts of words in
-human languages, and are typically used in variable and command names
-in programs. All upper- and lower-case letters, and the digits, are
-typically word constituents.
-@end deffn
+ Here is a table of syntax classes, the characters that designate
+them, their meanings, and examples of their use.
-@deffn {Syntax class} @w{symbol constituent}
-@dfn{Symbol constituents} (designated by @samp{_}) are the extra
-characters that are used in variable and command names along with word
-constituents. For example, the symbol constituents class is used in
-Lisp mode to indicate that certain characters may be part of symbol
-names even though they are not part of English words. These characters
-are @samp{$&*+-_<>}. In standard C, the only non-word-constituent
+@table @asis
+@item Whitespace characters: @samp{@ } or @samp{-}
+Characters that separate symbols and words from each other.
+Typically, whitespace characters have no other syntactic significance,
+and multiple whitespace characters are syntactically equivalent to a
+single one. Space, tab, and formfeed are classified as whitespace in
+almost all major modes.
+
+This syntax class can be designated by either @w{@samp{@ }} or
+@samp{-}. Both designators are equivalent.
+
+@item Word constituents: @samp{w}
+Parts of words in human languages. These are typically used in
+variable and command names in programs. All upper- and lower-case
+letters, and the digits, are typically word constituents.
+
+@item Symbol constituents: @samp{_}
+Extra characters used in variable and command names along with word
+constituents. Examples include the characters @samp{$&*+-_<>} in Lisp
+mode, which may be part of a symbol name even though they are not part
+of English words. In standard C, the only non-word-constituent
character that is valid in symbols is underscore (@samp{_}).
-@end deffn
-
-@deffn {Syntax class} @w{punctuation character}
-@dfn{Punctuation characters} (designated by @samp{.}) are those
-characters that are used as punctuation in English, or are used in some
-way in a programming language to separate symbols from one another.
-Some programming language modes, such as Emacs Lisp mode, have no
-characters in this class since the few characters that are not symbol or
-word constituents all have other uses. Other programming language modes,
-such as C mode, use punctuation syntax for operators.
-@end deffn
-@deffn {Syntax class} @w{open parenthesis character}
-@deffnx {Syntax class} @w{close parenthesis character}
-@cindex parenthesis syntax
-Open and close @dfn{parenthesis characters} are characters used in
-dissimilar pairs to surround sentences or expressions. Such a grouping
-is begun with an open parenthesis character and terminated with a close.
-Each open parenthesis character matches a particular close parenthesis
-character, and vice versa. Normally, Emacs indicates momentarily the
-matching open parenthesis when you insert a close parenthesis.
-@xref{Blinking}.
-
-The class of open parentheses is designated by @samp{(}, and that of
-close parentheses by @samp{)}.
-
-In English text, and in C code, the parenthesis pairs are @samp{()},
-@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and
-vectors (@samp{()} and @samp{[]}) are classified as parenthesis
-characters.
-@end deffn
-
-@deffn {Syntax class} @w{string quote}
-@dfn{String quote characters} (designated by @samp{"}) are used in
-many languages, including Lisp and C, to delimit string constants. The
-same string quote character appears at the beginning and the end of a
-string. Such quoted strings do not nest.
+@item Punctuation characters: @samp{.}
+Characters used as punctuation in a human language, or used in a
+programming language to separate symbols from one another. Some
+programming language modes, such as Emacs Lisp mode, have no
+characters in this class since the few characters that are not symbol
+or word constituents all have other uses. Other programming language
+modes, such as C mode, use punctuation syntax for operators.
+
+@item Open parenthesis characters: @samp{(}
+@itemx Close parenthesis characters: @samp{)}
+Characters used in dissimilar pairs to surround sentences or
+expressions. Such a grouping is begun with an open parenthesis
+character and terminated with a close. Each open parenthesis
+character matches a particular close parenthesis character, and vice
+versa. Normally, Emacs indicates momentarily the matching open
+parenthesis when you insert a close parenthesis. @xref{Blinking}.
+
+In human languages, and in C code, the parenthesis pairs are
+@samp{()}, @samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters
+for lists and vectors (@samp{()} and @samp{[]}) are classified as
+parenthesis characters.
+
+@item String quotes: @samp{"}
+Characters used to delimit string constants. The same string quote
+character appears at the beginning and the end of a string. Such
+quoted strings do not nest.
The parsing facilities of Emacs consider a string as a single token.
The usual syntactic meanings of the characters in the string are
double-quote for strings, and single-quote (@samp{'}) for character
constants.
-English text has no string quote characters because English is not a
-programming language. Although quotation marks are used in English,
-we do not want them to turn off the usual syntactic properties of
-other characters in the quotation.
-@end deffn
+Human text has no string quote characters. We do not want quotation
+marks to turn off the usual syntactic properties of other characters
+in the quotation.
-@deffn {Syntax class} @w{escape-syntax character}
-An @dfn{escape character} (designated by @samp{\}) starts an escape
-sequence such as is used in C string and character constants. The
-character @samp{\} belongs to this class in both C and Lisp. (In C, it
-is used thus only inside strings, but it turns out to cause no trouble
-to treat it this way throughout C code.)
+@item Escape-syntax characters: @samp{\}
+Characters that start an escape sequence, such as is used in string
+and character constants. The character @samp{\} belongs to this class
+in both C and Lisp. (In C, it is used thus only inside strings, but
+it turns out to cause no trouble to treat it this way throughout C
+code.)
Characters in this class count as part of words if
@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
-@end deffn
-@deffn {Syntax class} @w{character quote}
-A @dfn{character quote character} (designated by @samp{/}) quotes the
-following character so that it loses its normal syntactic meaning. This
-differs from an escape character in that only the character immediately
-following is ever affected.
+@item Character quotes: @samp{/}
+Characters used to quote the following character so that it loses its
+normal syntactic meaning. This differs from an escape character in
+that only the character immediately following is ever affected.
Characters in this class count as part of words if
@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
This class is used for backslash in @TeX{} mode.
-@end deffn
-
-@deffn {Syntax class} @w{paired delimiter}
-@dfn{Paired delimiter characters} (designated by @samp{$}) are like
-string quote characters except that the syntactic properties of the
-characters between the delimiters are not suppressed. Only @TeX{} mode
-uses a paired delimiter presently---the @samp{$} that both enters and
-leaves math mode.
-@end deffn
-
-@deffn {Syntax class} @w{expression prefix}
-An @dfn{expression prefix operator} (designated by @samp{'}) is used for
-syntactic operators that are considered as part of an expression if they
-appear next to one. In Lisp modes, these characters include the
-apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in
-macros), and @samp{#} (used in the read syntax for certain data types).
-@end deffn
-@deffn {Syntax class} @w{comment starter}
-@deffnx {Syntax class} @w{comment ender}
+@item Paired delimiters: @samp{$}
+Similar to string quote characters, except that the syntactic
+properties of the characters between the delimiters are not
+suppressed. Only @TeX{} mode uses a paired delimiter presently---the
+@samp{$} that both enters and leaves math mode.
+
+@item Expression prefixes: @samp{'}
+Characters used for syntactic operators that are considered as part of
+an expression if they appear next to one. In Lisp modes, these
+characters include the apostrophe, @samp{'} (used for quoting), the
+comma, @samp{,} (used in macros), and @samp{#} (used in the read
+syntax for certain data types).
+
+@item Comment starters: @samp{<}
+@itemx Comment enders: @samp{>}
@cindex comment syntax
-The @dfn{comment starter} and @dfn{comment ender} characters are used in
-various languages to delimit comments. These classes are designated
-by @samp{<} and @samp{>}, respectively.
+Characters used in various languages to delimit comments. Human text
+has no comment characters. In Lisp, the semicolon (@samp{;}) starts a
+comment and a newline or formfeed ends one.
-English text has no comment characters. In Lisp, the semicolon
-(@samp{;}) starts a comment and a newline or formfeed ends one.
-@end deffn
-
-@deffn {Syntax class} @w{inherit standard syntax}
-This syntax class does not specify a particular syntax. It says to look
-in the standard syntax table to find the syntax of this character. The
-designator for this syntax class is @samp{@@}.
-@end deffn
+@item Inherit standard syntax: @samp{@@}
+This syntax class does not specify a particular syntax. It says to
+look in the standard syntax table to find the syntax of this
+character.
-@deffn {Syntax class} @w{generic comment delimiter}
-A @dfn{generic comment delimiter} (designated by @samp{!}) starts
-or ends a special kind of comment. @emph{Any} generic comment delimiter
-matches @emph{any} generic comment delimiter, but they cannot match
-a comment starter or comment ender; generic comment delimiters can only
-match each other.
+@item Generic comment delimiters: @samp{!}
+Characters that start or end a special kind of comment. @emph{Any}
+generic comment delimiter matches @emph{any} generic comment
+delimiter, but they cannot match a comment starter or comment ender;
+generic comment delimiters can only match each other.
This syntax class is primarily meant for use with the
-@code{syntax-table} text property (@pxref{Syntax Properties}). You can
-mark any range of characters as forming a comment, by giving the first
-and last characters of the range @code{syntax-table} properties
+@code{syntax-table} text property (@pxref{Syntax Properties}). You
+can mark any range of characters as forming a comment, by giving the
+first and last characters of the range @code{syntax-table} properties
identifying them as generic comment delimiters.
-@end deffn
-@deffn {Syntax class} @w{generic string delimiter}
-A @dfn{generic string delimiter} (designated by @samp{|}) starts or ends
-a string. This class differs from the string quote class in that @emph{any}
-generic string delimiter can match any other generic string delimiter; but
-they do not match ordinary string quote characters.
+@item Generic string delimiters: @samp{|}
+Characters that start or end a string. This class differs from the
+string quote class in that @emph{any} generic string delimiter can
+match any other generic string delimiter; but they do not match
+ordinary string quote characters.
This syntax class is primarily meant for use with the
-@code{syntax-table} text property (@pxref{Syntax Properties}). You can
-mark any range of characters as forming a string constant, by giving the
-first and last characters of the range @code{syntax-table} properties
-identifying them as generic string delimiters.
-@end deffn
+@code{syntax-table} text property (@pxref{Syntax Properties}). You
+can mark any range of characters as forming a string constant, by
+giving the first and last characters of the range @code{syntax-table}
+properties identifying them as generic string delimiters.
+@end table
@node Syntax Flags
@subsection Syntax Flags
@deffn Command modify-syntax-entry char syntax-descriptor &optional table
This function sets the syntax entry for @var{char} according to
-@var{syntax-descriptor}. @var{char} can be a character, or a cons
+@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,
the function sets the syntax entries for all characters in the range
between @var{min} and @var{max}, inclusive.
The syntax is changed only for @var{table}, which defaults to the
-current buffer's syntax table, and not in any other syntax table. The
-argument @var{syntax-descriptor} specifies the desired syntax; this is
-a string beginning with a class designator character, and optionally
-containing a matching character and flags as well. @xref{Syntax
-Descriptors}.
+current buffer's syntax table, and not in any other syntax table.
+
+The argument @var{syntax-descriptor} is a syntax descriptor for the
+desired syntax (i.e.@: a string beginning with a class designator
+character, and optionally containing a matching character and syntax
+flags). An error is signaled if the first character is not one of the
+seventeen syntax class designators. @xref{Syntax Descriptors}.
This function always returns @code{nil}. The old syntax information in
the table for this character is discarded.
-An error is signaled if the first character of the syntax descriptor is not
-one of the seventeen syntax class designator characters. An error is also
-signaled if @var{char} is not a character.
-
@example
@group
@exdent @r{Examples:}
@kindex syntax-table @r{(text property)}
When the syntax table is not flexible enough to specify the syntax of
-a language, you can use @code{syntax-table} text properties to
-override the syntax table for specific character occurrences in the
-buffer. @xref{Text Properties}. You can use Font Lock mode to set
-@code{syntax-table} text properties. @xref{Setting Syntax
-Properties}.
+a language, you can override the syntax table for specific character
+occurrences in the buffer, by applying a @code{syntax-table} text
+property. @xref{Text Properties}, for how to apply text properties.
-The valid values of @code{syntax-table} text property are:
+ The valid values of @code{syntax-table} text property are:
@table @asis
@item @var{syntax-table}
If the property value is a syntax table, that table is used instead of
-the current buffer's syntax table to determine the syntax for this
-occurrence of the character.
+the current buffer's syntax table to determine the syntax for the
+underlying text character.
@item @code{(@var{syntax-code} . @var{matching-char})}
-A cons cell of this format specifies the syntax for this
-occurrence of the character. (@pxref{Syntax Table Internals})
+A cons cell of this format specifies the syntax for the underlying
+text character. (@pxref{Syntax Table Internals})
@item @code{nil}
If the property is @code{nil}, the character's syntax is determined from
@end table
@defvar parse-sexp-lookup-properties
-If this is non-@code{nil}, the syntax scanning functions pay attention
-to syntax text properties. Otherwise they use only the current syntax
-table.
+If this is non-@code{nil}, the syntax scanning functions, like
+@code{forward-sexp}, pay attention to syntax text properties.
+Otherwise they use only the current syntax table.
+@end defvar
+
+@defvar syntax-propertize-function
+This variable, if non-@code{nil}, should store a function for applying
+@code{syntax-table} properties to a specified stretch of text. It is
+intended to be used by major modes to install a function which applies
+@code{syntax-table} properties in some mode-appropriate way.
+
+The function is called by @code{syntax-ppss} (@pxref{Position Parse}),
+and by Font Lock mode during syntactic fontification (@pxref{Syntactic
+Font Lock}). It is called with two arguments, @var{start} and
+@var{end}, which are the starting and ending positions of the text on
+which it should act. It is allowed to call @code{syntax-ppss} on any
+position before @var{end}. However, it should not call
+@code{syntax-ppss-flush-cache}; so, it is not allowed to call
+@code{syntax-ppss} on some position and later modify the buffer at an
+earlier position.
+@end defvar
+
+@defvar syntax-propertize-extend-region-functions
+This abnormal hook is run by the syntax parsing code prior to calling
+@code{syntax-propertize-function}. Its role is to help locate safe
+starting and ending buffer positions for passing to
+@code{syntax-propertize-function}. For example, a major mode can add
+a function to this hook to identify multi-line syntactic constructs,
+and ensure that the boundaries do not fall in the middle of one.
+
+Each function in this hook should accept two arguments, @var{start}
+and @var{end}. It should return either a cons cell of two adjusted
+buffer positions, @code{(@var{new-start} . @var{new-end})}, or
+@code{nil} if no adjustment is necessary. The hook functions are run
+in turn, repeatedly, until they all return @code{nil}.
@end defvar
@node Motion and Syntax
on languages other than Lisp. Basically, a sexp is either a balanced
parenthetical grouping, a string, or a ``symbol'' (i.e.@: a sequence
of characters whose syntax is either word constituent or symbol
-constituent). However, characters whose syntax is expression prefix
-are treated as part of the sexp if they appear next to it.
+constituent). However, characters in the expression prefix syntax
+class (@pxref{Syntax Class Table}) are treated as part of the sexp if
+they appear next to it.
The syntax table controls the interpretation of characters, so these
functions can be used for Lisp expressions when in Lisp mode and for C
based on parsing expressions.
@defun scan-lists from count depth
-This function scans forward @var{count} balanced parenthetical groupings
-from position @var{from}. It returns the position where the scan stops.
-If @var{count} is negative, the scan moves backwards.
-
-If @var{depth} is nonzero, parenthesis depth counting begins from that
-value. The only candidates for stopping are places where the depth in
-parentheses becomes zero; @code{scan-lists} counts @var{count} such
-places and then stops. Thus, a positive value for @var{depth} means go
-out @var{depth} levels of parenthesis.
+This function scans forward @var{count} balanced parenthetical
+groupings from position @var{from}. It returns the position where the
+scan stops. If @var{count} is negative, the scan moves backwards.
+
+If @var{depth} is nonzero, treat the starting position as being
+@var{depth} parentheses deep. The scanner moves forward or backward
+through the buffer until the depth changes to zero @var{count} times.
+Hence, a positive value for @var{depth} has the effect of moving out
+@var{depth} levels of parenthesis from the starting position, while a
+negative @var{depth} has the effect of moving deeper by @var{-depth}
+levels of parenthesis.
Scanning ignores comments if @code{parse-sexp-ignore-comments} is
non-@code{nil}.
-If the scan reaches the beginning or end of the buffer (or its
-accessible portion), and the depth is not zero, an error is signaled.
-If the depth is zero but the count is not used up, @code{nil} is
-returned.
+If the scan reaches the beginning or end of the accessible part of the
+buffer before it has scanned over @var{count} parenthetical groupings,
+the return value is @code{nil} if the depth at that point is zero; if
+the depth is non-zero, a @code{scan-error} error is signaled.
@end defun
@defun scan-sexps from count
This function cannot tell whether the ``comments'' it traverses are
embedded within a string. If they look like comments, it treats them
as comments.
-@end defun
To move forward over all comments and whitespace following point, use
-@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good
-argument to use, because the number of comments in the buffer cannot
-exceed that many.
+@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a
+good argument to use, because the number of comments in the buffer
+cannot exceed that many.
+@end defun
@node Position Parse
@subsection Finding the Parse State for a Position
position. This function does that conveniently.
@defun syntax-ppss &optional pos
-This function returns the parser state (see next section) that the
-parser would reach at position @var{pos} starting from the beginning
-of the buffer. This is equivalent to @code{(parse-partial-sexp
-(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache
-to speed up the computation. Due to this optimization, the 2nd value
-(previous complete subexpression) and 6th value (minimum parenthesis
-depth) of the returned parser state are not meaningful.
-@end defun
-
- @code{syntax-ppss} automatically hooks itself to
-@code{before-change-functions} to keep its cache consistent. But
-updating can fail if @code{syntax-ppss} is called while
+This function returns the parser state that the parser would reach at
+position @var{pos} starting from the beginning of the buffer.
+@iftex
+See the next section for
+@end iftex
+@ifnottex
+@xref{Parser State},
+@end ifnottex
+for a description of the parser state.
+
+The return value is the same as if you call the low-level parsing
+function @code{parse-partial-sexp} to parse from the beginning of the
+buffer to @var{pos} (@pxref{Low-Level Parsing}). However,
+@code{syntax-ppss} uses a cache to speed up the computation. Due to
+this optimization, the second value (previous complete subexpression)
+and sixth value (minimum parenthesis depth) in the returned parser
+state are not meaningful.
+
+This function has a side effect: it adds a buffer-local entry to
+@code{before-change-functions} (@pxref{Change Hooks}) for
+@code{syntax-ppss-flush-cache} (see below). This entry keeps the
+cache consistent as the buffer is modified. However, the cache might
+not be updated if @code{syntax-ppss} is called while
@code{before-change-functions} is temporarily let-bound, or if the
-buffer is modified without obeying the hook, such as when using
-@code{inhibit-modification-hooks}. For this reason, it is sometimes
-necessary to flush the cache manually.
+buffer is modified without running the hook, such as when using
+@code{inhibit-modification-hooks}. In those cases, it is necessary to
+call @code{syntax-ppss-flush-cache} explicitly.
+@end defun
@defun syntax-ppss-flush-cache beg &rest ignored-args
This function flushes the cache used by @code{syntax-ppss}, starting
@subsection Parser State
@cindex parser state
- A @dfn{parser state} is a list of ten elements describing the final
-state of parsing text syntactically as part of an expression. The
-parsing functions in the following sections return a parser state as
-the value, and in some cases accept one as an argument also, so that
-you can resume parsing after it stops. Here are the meanings of the
-elements of the parser state:
+ A @dfn{parser state} is a list of ten elements describing the state
+of the syntactic parser, after it parses the text between a specified
+starting point and a specified end point in the buffer. Parsing
+functions such as @code{syntax-ppss}
+@ifnottex
+(@pxref{Position Parse})
+@end ifnottex
+return a parser state as the value. Some parsing functions accept a
+parser state as an argument, for resuming parsing.
+
+ Here are the meanings of the elements of the parser state:
@enumerate 0
@item
The depth in parentheses, counting from 0. @strong{Warning:} this can
be negative if there are more close parens than open parens between
-the start of the defun and point.
+the parser's starting point and end point.
@item
@cindex innermost containing parentheses
@item
@cindex inside comment
-@code{t} if inside a comment (of either style),
-or the comment nesting level if inside a kind of comment
-that can be nested.
+@code{t} if inside a non-nestable comment (of any comment style;
+@pxref{Syntax Flags}); or the comment nesting level if inside a
+comment that can be nested.
@item
@cindex quote character
-@code{t} if point is just after a quote character.
+@code{t} if the end point is just after a quote character.
@item
The minimum parenthesis depth encountered during this scan.
@item
-What kind of comment is active: @code{nil} for a comment of style
-``a'' or when not inside a comment, @code{t} for a comment of style
-``b,'' and @code{syntax-table} for a comment that should be ended by a
-generic comment delimiter character.
+What kind of comment is active: @code{nil} if not in a comment or in a
+comment of style @samp{a}; 1 for a comment of style @samp{b}; 2 for a
+comment of style @samp{c}; and @code{syntax-table} for a comment that
+should be ended by a generic comment delimiter character.
@item
The string or comment start position. While inside a comment, this is
Elements 1, 2, and 6 are ignored in a state which you pass as an
argument to continue parsing, and elements 8 and 9 are used only in
-trivial cases. Those elements serve primarily to convey information
-to the Lisp program which does the parsing.
+trivial cases. Those elements are mainly used internally by the
+parser code.
One additional piece of useful information is available from a
parser state using this function:
@item
When you define a variable that users ought to set interactively, you
-normally should use @code{defcustom}. However, if for some reason you
-use @code{defvar} instead, start the doc string with a @samp{*}.
-@xref{Defining Variables}.
+should use @code{defcustom}. @xref{Defining Variables}.
@item
The documentation string for a variable that is a yes-or-no flag should
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: Providing a menu of definitions made in a buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
+* Auto-Indentation:: How to teach Emacs to indent for a major mode.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
+* Mode Hooks:: Hooks run at the end of major mode commands.
+* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
-* Mode Hooks:: Hooks run at the end of major mode commands.
* Example Major Modes:: Text mode and Lisp modes.
Minor Modes
contents can also specify how to fontify it.
* Faces for Font Lock:: Special faces specifically for Font Lock.
* Syntactic Font Lock:: Fontification based on syntax tables.
-* Setting Syntax Properties:: Defining character syntax based on context
- using the Font Lock mechanism.
* Multiline Font Lock:: How to coerce Font Lock into properly
highlighting multiline constructs.
Documentation
-* Documentation Basics:: Good style for doc strings.
- Where to put them. How Emacs stores them.
+* Documentation Basics:: Where doc strings are defined and stored.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
* Describing Characters:: Making printable descriptions of
* File Locks:: Locking and unlocking files, to prevent
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files:: Renaming files, changing protection, etc.
+* Changing Files:: Renaming files, changing permissions, etc.
* File Names:: Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs:: Creating and Deleting Directories.
-* Magic File Names:: Defining "magic" special handling
- for certain file names.
+* Magic File Names:: Special handling for certain file names.
* Format Conversion:: Conversion to and from various file formats.
Visiting Files
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: Providing a menu of definitions made in a buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
+* Auto-Indentation:: How to teach Emacs to indent for a major mode.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
+* Mode Hooks:: Hooks run at the end of major mode commands.
+* Tabulated List Mode:: Parent mode for buffers containing tabulated data.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
-* Mode Hooks:: Hooks run at the end of major mode commands.
* Example Major Modes:: Text mode and Lisp modes.
Minor Modes
contents can also specify how to fontify it.
* Faces for Font Lock:: Special faces specifically for Font Lock.
* Syntactic Font Lock:: Fontification based on syntax tables.
-* Setting Syntax Properties:: Defining character syntax based on context
- using the Font Lock mechanism.
* Multiline Font Lock:: How to coerce Font Lock into properly
highlighting multiline constructs.
Documentation
-* Documentation Basics:: Good style for doc strings.
- Where to put them. How Emacs stores them.
+* Documentation Basics:: Where doc strings are defined and stored.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
* Describing Characters:: Making printable descriptions of
* File Locks:: Locking and unlocking files, to prevent
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files:: Renaming files, changing protection, etc.
+* Changing Files:: Renaming files, changing permissions, etc.
* File Names:: Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs:: Creating and Deleting Directories.
-* Magic File Names:: Defining "magic" special handling
- for certain file names.
+* Magic File Names:: Special handling for certain file names.
* Format Conversion:: Conversion to and from various file formats.
Visiting Files
+2012-02-17 Glenn Morris <rgm@gnu.org>
+
+ * gnus.texi (Posting Styles):
+ * remember.texi (Org): Fix cross-refs to other manuals.
+
2012-02-15 Glenn Morris <rgm@gnu.org>
* smtpmail.texi (Emacs Speaks SMTP): General update for 24.1.
In the case of a string value, if the @code{match} is a regular
expression, a @samp{gnus-match-substitute-replacement} is proceed on
the value to replace the positional parameters @samp{\@var{n}} by the
-corresponding parenthetical matches (see @xref{Replacing the Text that
-Matched, , Text Replacement, elisp, The Emacs Lisp Reference Manual}.)
+corresponding parenthetical matches (see @xref{Replacing Match,,
+Replacing the Text that Matched, elisp, The Emacs Lisp Reference Manual}.)
@vindex message-reply-headers
@section Saving to an Org Mode file
@cindex org mode, integration
+@ignore
+From org.texi:
+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}.
+@end ignore
For instructions on how to integrate Remember with Org Mode,
-consult @ref{Remember, , , org}.
+consult @ref{Capture, , , org}.
@node GNU Free Documentation License, Concept Index, Backends, Top
@appendix GNU Free Documentation License
+2012-02-20 Paul Eggert <eggert@cs.ucla.edu>
+
+ * emacs-buffer.gdb ($valmask): Don't assume EMACS_INT fits in 'long'.
+
2012-02-10 Leo Liu <sdl.web@gmail.com>
* NEWS: Change condition-case-no-debug to
---
** cl.el no longer provides `cl-19'.
++++
** The menu bar bindings's caches are not used any more.
Use (where-is-internal <def> nil t) instead.
(A version of this macro was actually added in Emacs 23.2 but was not
advertised at the time.)
+** Debugger changes
+++
-** New macro `condition-case-unless-debug' (this was actually added in
+*** New macro `condition-case-unless-debug' (this was actually added in
Emacs 23.1 as condition-case-no-debug, but not advertised)
-
+++
-** The macro `with-demoted-errors' was added in Emacs 23.1, but not advertised.
+*** The macro `with-demoted-errors' was added in Emacs 23.1, but not advertised.
+---
+*** Variable `stack-trace-on-error' removed.
++++
+*** The debugger can now "continue" from an error, which means it will
+jump to the error handler as if the debugger had not been invoked
+instead of jumping all the way to the top-level.
++++
+*** Set `debug-on-event' to enter the debugger on events like SIGUSR1.
+This can be useful when `inhibit-quit' is set.
+++
** The new function `server-eval-at' allows evaluation of Lisp forms on
** `call-process' and `call-process-region' allow a `(:file "file")' spec
to redirect STDOUT to a file.
----
-** Variable `stack-trace-on-error' removed.
-Also the debugger can now "continue" from an error, which means it will jump
-to the error handler as if the debugger had not been invoked instead of
-jumping all the way to the top-level.
-
+++
** The function format-time-string now supports the %N directive, for
higher-resolution time stamps.
+** New input reading functions
+++
-** New function `read-char-choice' reads a restricted set of characters,
-discarding any inputs not inside the set.
+*** New function `read-char-choice' reads a restricted set of
+characters, discarding any inputs not inside the set.
++++
+*** The command `read-color' now requires a match for a color name
+or RGB triplet, instead of signaling an error if the user provides
+invalid input.
+---
+**** `facemenu-read-color' is now an alias for `read-color'.
+++
** `image-library-alist' is renamed to `dynamic-library-alist'.
not just image libraries. The previous name is still available as an
obsolete alias.
-** New variable `syntax-propertize-function'.
+** Syntax parsing changes
++++
+*** New variable `syntax-propertize-function'.
This replaces `font-lock-syntactic-keywords' which is now obsolete.
This allows syntax-table properties to be set independently from font-lock:
just call syntax-propertize to make sure the text is propertized.
syntax-propertize-via-font-lock to reuse old font-lock-syntactic-keywords
as-is; and syntax-propertize-rules which provides a new way to specify
syntactic rules.
-
+++
-** New hook post-self-insert-hook run at the end of self-insert-command.
+*** Syntax tables support a new "comment style c" additionally to style b.
+++
-** Syntax tables support a new "comment style c" additionally to style b.
+** New hook post-self-insert-hook run at the end of self-insert-command.
---
** frame-local variables cannot be let-bound any more.
** Major and minor mode changes
+++
+*** `set-auto-mode' now respects mode: local variables at the end of files,
+as well as those in the -*- line.
++++
*** `prog-mode' is a new major mode from which programming modes
should be derived.
-
+++
**** `prog-mode-hook' can be used to enable features for programming
modes, e.g. (add-hook 'prog-mode-hook 'flyspell-prog-mode) to enable
on-the-fly spell checking for comments and strings.
-
+++
*** New hook `change-major-mode-after-body-hook', run by
`run-mode-hooks' just before any other mode hooks.
-
+++
*** Enabled globalized minor modes can be disabled in specific major modes.
If the global mode is global-FOO-mode, then run (FOO-mode -1) in the
major mode's hook, where FOO-mode toggles the mode on a per-buffer basis.
-
+++
*** `define-minor-mode' accepts a new keyword :variable.
both non-nil. Interactively, TRASH defaults to t, unless a prefix
argument is supplied (see Trash changes, above).
----
-** `facemenu-read-color' is now an alias for `read-color'.
-
-+++
-** The command `read-color' now requires a match for a color name
-or RGB triplet, instead of signaling an error if the user provides
-invalid input.
-
+++
** Tool-bars can display separators.
Tool-bar separators are handled like menu separators in menu-bar maps,
+++
*** Image mode can view any image type that ImageMagick supports.
This requires Emacs to be built with ImageMagick support.
-Then the function `imagemagick-types' returns a list of image file
+If your Emacs has ImageMagick support, then the function
+`imagemagick-types' is defined, and returns a list of image file
extensions that your installation of ImageMagick supports. The
function `imagemagick-register-types' enables ImageMagick support for
these image types, minus those listed in `imagemagick-types-inhibit'.
*** New library `gnutls.el'.
This requires Emacs to have been built with GnuTLS support.
-The main functions are `open-gnutls-stream' and `gnutls-negotiate'.
-It's easiest to use these functions through `open-network-stream'
-because it can upgrade connections through STARTTLS opportunistically
-or use plain SSL, depending on your needs. For debugging, set
-`gnutls-log-level' greater than 0.
+If your Emacs has GnuTLS support, the function gnutls-available-p is
+defined and returns non-nil. The main functions are `open-gnutls-stream'
+and `gnutls-negotiate'. It's easiest to use these functions through
+`open-network-stream' because it can upgrade connections through
+STARTTLS opportunistically or use plain SSL, depending on your needs.
+For debugging, set `gnutls-log-level' greater than 0.
** Isearch
startup, which might otherwise not be noticed. This uses the functions
display-delayed-warnings and collapse-delayed-warnings.
-
-+++
-** `set-auto-mode' now respects mode: local variables at the end of files,
-as well as those in the -*- line.
-
---
** rx.el has a new `group-n' construct for explicitly numbered groups.
inherits from multiple maps, eg:
(set-keymap-parent newmap (make-composed-keymap othermap parent))
-+++
-** Set `debug-on-event' to make Emacs enter the debugger e.g. on receipt
-of SIGUSR1. This can be useful when `inhibit-quit' is set.
-
+++
** New reader macro ## that stands for the empty symbol.
This means that the empty symbol can now be read back. Also, #: by itself
set $yfile_buffers_only = 0
set $tagmask = (((long)1 << gdb_gctypebits) - 1)
-set $valmask = gdb_use_lsb ? ~($tagmask) : ((long)1 << gdb_valbits) - 1
+# The consing_since_gc business widens the 1 to EMACS_INT,
+# a symbol not directly visible to GDB.
+set $valmask = gdb_use_lsb ? ~($tagmask) : ((consing_since_gc - consing_since_gc + 1) << gdb_valbits) - 1
define ygetptr
set $ptr = $arg0
+2012-02-22 Glenn Morris <rgm@gnu.org>
+
+ * ffap.el (ffap-c-path):
+ * man.el (Man-header-file-path): Handle multiarch. (Bug#10702)
+
+2012-02-22 Chong Yidong <cyd@gnu.org>
+
+ * custom.el (load-theme): Doc fix.
+
+2012-02-22 Glenn Morris <rgm@gnu.org>
+
+ * dired-x.el (dired-guess-shell-alist-default):
+ Remove escape sequences from nroff output. (Bug#172)
+
+2012-02-21 Glenn Morris <rgm@gnu.org>
+
+ * vc/emerge.el (emerge-defvar-local):
+ Set `permanent-local' property rather than unused `preserved'.
+
+ * textmodes/picture.el (picture-delete-char): New alias.
+ (picture-mode-map): Use it. (Bug#10860)
+ (picture-mode): Doc fix.
+
+2012-02-21 Juanma Barranquero <lekktu@gmail.com>
+
+ * newcomment.el (uncomment-region-default): Remove unused binding.
+
+2012-02-21 Glenn Morris <rgm@gnu.org>
+
+ * textmodes/picture.el (picture-motion, picture-motion-reverse)
+ (picture-self-insert, picture-tab-chars): Doc fix.
+ (picture-mode-map): Fix C-a, C-e.
+
+2012-02-20 Glenn Morris <rgm@gnu.org>
+
+ * emacs-lisp/authors.el (authors-aliases): Add another entry.
+
+2012-02-20 Leo Liu <sdl.web@gmail.com>
+
+ * icomplete.el (icomplete-completions): Check FROM arg before
+ passing to substring (Bug#10850).
+
+2012-02-19 Chong Yidong <cyd@gnu.org>
+
+ * comint.el: Require ansi-color.
+ (comint-output-filter-functions): Add ansi-color-process-output.
+
+ * ansi-color.el: Don't set comint-output-filter-functions; it is
+ now in the initial value defined in comint.el.
+ (ansi-color-apply-face-function): New variable.
+ (ansi-color-apply-on-region): Use it.
+ (ansi-color-apply-overlay-face): New function.
+
+ * shell.el (shell): No need to require ansi-color.
+ (shell-mode): Use ansi-color-apply-face-function to highlight
+ color escapes using font-lock-face property (Bug#10835).
+
+2012-02-19 Chong Yidong <cyd@gnu.org>
+
+ * vc/ediff-init.el (ediff-strip-mode-line-format): Handle non-list
+ mode-line formats (Bug#10839).
+
+2012-02-18 Glenn Morris <rgm@gnu.org>
+
+ * mail/rmail.el (rmail-dont-reply-to-names): Mark as obsolete.
+
+ * mail/undigest.el (unforward-rmail-message): Doc fix.
+
+ * saveplace.el (save-place-ignore-files-regexp): Add :version.
+
+2012-02-18 Eli Zaretskii <eliz@gnu.org>
+
+ * international/characters.el (script-list): Sync with the latest
+ Unicode Character Database.
+
+2012-02-18 Andreas Schwab <schwab@linux-m68k.org>
+
+ * international/titdic-cnv.el: Remove duplicate coding tag.
+ * language/cham.el: Likewise.
+ * language/tai-viet.el: Likewise.
+
+2012-02-18 Glenn Morris <rgm@gnu.org>
+
+ * calendar/cal-menu.el (cal-menu-diary-menu, cal-menu-goto-menu):
+ * calendar/calendar.el (diary-file, diary-bahai-entry-symbol)
+ (calendar-bahai-all-holidays-flag, calendar-other-dates):
+ * calendar/diary-lib.el (diary-abbreviated-year-flag):
+ * calendar/holidays.el (holiday-bahai-holidays)
+ (calendar-holidays, list-holidays):
+ Use utf-8 Bahá'í in doc-strings, menus, etc.
+
+2012-02-17 Tassilo Horn <tassilo@member.fsf.org>
+
+ * saveplace.el (save-place-ignore-files-regexp): New variable
+ allowing for excluding files from saving their location of point.
+ The default value matches the temporary commit message editing
+ files from Git, SVN, Bazaar, and Mercurial.
+ (save-place-to-alist): Use it.
+
+2012-02-17 Lawrence Mitchell <wence@gmx.li>
+ Stefan Monnier <monnier@iro.umontreal.ca>
+
+ * newcomment.el (uncomment-region-default): Don't leave extra space
+ when an arg is provided (bug#8150).
+
+2012-02-17 Teodor Zlatanov <tzz@lifelogs.com>
+
+ * net/gnutls.el (gnutls-trustfiles): Fix Cygwin bundle location.
+
+2012-02-17 Glenn Morris <rgm@gnu.org>
+
+ * net/socks.el: Require network-stream. (Bug#10599)
+
+2012-02-17 Kenichi Handa <handa@m17n.org>
+
+ * international/charprop.el:
+ * international/uni-name.el:
+ * international/uni-old-name.el:
+ * international/uni-comment.el: Regenerate.
+
+2012-02-16 Glenn Morris <rgm@gnu.org>
+
+ * calendar/cal-hebrew.el (calendar-hebrew-list-yahrzeits):
+ Interactively in calendar buffer, give an error if not on a date.
+
2012-02-15 Glenn Morris <rgm@gnu.org>
* shell.el (shell-delimiter-argument-list):
2012-02-07 Alan Mackenzie <acm@muc.de>
- * progmodes/cc-engine.el (c-forward-objc-directive): Prevent
- looping in "#pragma mark @implementation".
+ * progmodes/cc-engine.el (c-forward-objc-directive):
+ Prevent looping in "#pragma mark @implementation".
2012-02-07 Michael Albinus <michael.albinus@gmx.de>
(Bug#10254).
(bibtex-mode): Call bibtex-set-dialect via
hack-local-variables-hook.
- (bibtex-dialect): Update docstring. Add
- safe-local-variable predicate.
+ (bibtex-dialect): Update docstring.
+ Add safe-local-variable predicate.
(bibtex-entry-alist, bibtex-field-alist): Initialize via
bibtex-set-dialect.
(bibtex-mode-map): Define menu for each dialect.
2012-01-28 Phil Hagelberg <phil@hagelb.org>
- * emacs-lisp/package.el (package-install): Run
- package-refresh-contents if there is no archive yet (Bug#9798).
+ * emacs-lisp/package.el (package-install):
+ Run package-refresh-contents if there is no archive yet (Bug#9798).
2012-01-28 Chong Yidong <cyd@gnu.org>
2012-01-19 Martin Rudalics <rudalics@gmx.at>
* window.el (window--state-get-1, window-state-get): Do not use
- special state value for window-persistent-parameters. Rename
- argument IGNORE to WRITABLE. Rewrite doc-string.
+ special state value for window-persistent-parameters.
+ Rename argument IGNORE to WRITABLE. Rewrite doc-string.
(window--state-put-2): Reset all window parameters to nil before
assigning values of persistent parameters.
c-mask-paragraph, pass in `fill-paragraph' rather than
`fill-region-as-paragraph'. (This is a reversion of a previous
change.)
- * progmodes/cc-mode.el (c-basic-common-init): Make
- fill-paragraph-handle-comment buffer local and set it to nil.
+ * progmodes/cc-mode.el (c-basic-common-init):
+ Make fill-paragraph-handle-comment buffer local and set it to nil.
2012-01-13 Glenn Morris <rgm@gnu.org>
:group 'ansi-colors
:version "23.2")
+(defvar ansi-color-apply-face-function 'ansi-color-apply-overlay-face
+ "Function for applying an Ansi Color face to text in a buffer.
+This function should accept three arguments: BEG, END, and FACE,
+and it should apply face FACE to the text between BEG and END.")
+
;;;###autoload
(defun ansi-color-for-comint-mode-on ()
"Set `ansi-color-for-comint-mode' to t."
(t
(ansi-color-apply-on-region start-marker end-marker)))))
-(add-hook 'comint-output-filter-functions
- 'ansi-color-process-output)
-
(defalias 'ansi-color-unfontify-region 'font-lock-default-unfontify-region)
(make-obsolete 'ansi-color-unfontify-region "not needed any more" "24.1")
;; Find the next SGR sequence.
(while (re-search-forward ansi-color-regexp end-marker t)
;; Colorize the old block from start to end using old face.
- (when face
- (ansi-color-set-extent-face
- (ansi-color-make-extent start-marker (match-beginning 0))
- face))
+ (funcall ansi-color-apply-face-function
+ start-marker (match-beginning 0)
+ face)
;; store escape sequence and new start position
(setq escape-sequence (match-string 1)
start-marker (copy-marker (match-end 0)))
(if (re-search-forward "\033" end-marker t)
(progn
;; if the rest of the region should have a face, put it there
- (when face
- (ansi-color-set-extent-face
- (ansi-color-make-extent start-marker (point))
- face))
+ (funcall ansi-color-apply-face-function
+ start-marker (point) face)
;; save face and point
(setq ansi-color-context-region
(list face (copy-marker (match-beginning 0)))))
;; if the rest of the region should have a face, put it there
- (if face
- (progn
- (ansi-color-set-extent-face
- (ansi-color-make-extent start-marker end-marker)
- face)
- (setq ansi-color-context-region (list face)))
- ;; reset context
- (setq ansi-color-context-region nil))))))
+ (funcall ansi-color-apply-face-function
+ start-marker end-marker face)
+ (setq ansi-color-context-region (if face (list face)))))))
+
+(defun ansi-color-apply-overlay-face (beg end face)
+ "Make an overlay from BEG to END, and apply face FACE.
+If FACE is nil, do nothing."
+ (when face
+ (ansi-color-set-extent-face
+ (ansi-color-make-extent beg end)
+ face)))
;; This function helps you look for overlapping overlays. This is
;; useful in comint-buffers. Overlapping overlays should not happen!
(interactive
(let* ((death-date
(if (equal (current-buffer) (get-buffer calendar-buffer))
- (calendar-cursor-to-date)
+ (calendar-cursor-to-date t)
(let* ((today (calendar-current-date))
(year (calendar-read
"Year of death (>0): "
["Insert Anniversary" diary-insert-anniversary-entry]
["Insert Block" diary-insert-block-entry]
["Insert Cyclic" diary-insert-cyclic-entry]
- ("Insert Baha'i"
+ ("Insert Bahá'í"
["One time" diary-bahai-insert-entry]
["Monthly" diary-bahai-insert-monthly-entry]
["Yearly" diary-bahai-insert-yearly-entry])
["Astronomical Date" calendar-astro-goto-day-number]
["Hebrew Date" calendar-hebrew-goto-date]
["Persian Date" calendar-persian-goto-date]
- ["Baha'i Date" calendar-bahai-goto-date]
+ ["Bahá'í Date" calendar-bahai-goto-date]
["Islamic Date" calendar-islamic-goto-date]
["Julian Date" calendar-julian-goto-date]
["Chinese Date" calendar-chinese-goto-date]
(provide 'cal-menu)
+;; Local Variables:
+;; coding: utf-8
+;; End:
+
;;; cal-menu.el ends here
;; can be translated from the (usual) Gregorian calendar to the day of
;; the year/days remaining in year, to the ISO commercial calendar, to
;; the Julian (old style) calendar, to the Hebrew calendar, to the
-;; Islamic calendar, to the Baha'i calendar, to the French
+;; Islamic calendar, to the Bahá'í calendar, to the French
;; Revolutionary calendar, to the Mayan calendar, to the Chinese
;; calendar, to the Coptic calendar, to the Ethiopic calendar, and to
;; the astronomical (Julian) day number. Times of sunrise/sunset can
;; The following files are part of the calendar/diary code:
;; appt.el Appointment notification
-;; cal-bahai.el Baha'i calendar
+;; cal-bahai.el Bahá'í calendar
;; cal-china.el Chinese calendar
;; cal-coptic.el Coptic/Ethiopic calendars
;; cal-dst.el Daylight saving time rules
November 10, 1990. See the documentation for the function
`diary-list-sexp-entries' for more details.
-Diary entries based on the Hebrew, the Islamic and/or the Baha'i
+Diary entries based on the Hebrew, the Islamic and/or the Bahá'í
calendar are also possible, but because these are somewhat slow, they
are ignored unless you set the `diary-nongregorian-listing-hook' and
the `diary-nongregorian-marking-hook' appropriately. See the
'diary-bahai-entry-symbol "23.1")
(defcustom diary-bahai-entry-symbol "B"
- "Symbol indicating a diary entry according to the Baha'i calendar."
+ "Symbol indicating a diary entry according to the Bahá'í calendar."
:type 'string
:group 'diary)
'calendar-bahai-all-holidays-flag "23.1")
(defcustom calendar-bahai-all-holidays-flag nil
- "If nil, show only major holidays from the Baha'i calendar.
+ "If nil, show only major holidays from the Bahá'í calendar.
These are the days on which work and school must be suspended.
-Otherwise, show all the holidays that would appear in a complete Baha'i
+Otherwise, show all the holidays that would appear in a complete Bahá'í
calendar."
:type 'boolean
:group 'holidays)
(unless (string-equal
(setq odate (calendar-bahai-date-string date))
"")
- (format "Baha'i date: %s" odate))
+ (format "Bahá'í date: %s" odate))
(format "Chinese date: %s"
(calendar-chinese-date-string date))
(unless (string-equal
;; Local variables:
;; byte-compile-dynamic: t
+;; coding: utf-8
;; End:
;;; calendar.el ends here
(defcustom diary-abbreviated-year-flag t
"Interpret a two-digit year DD in a diary entry as either 19DD or 20DD.
-This applies to the Gregorian, Hebrew, Islamic, and Baha'i calendars.
+This applies to the Gregorian, Hebrew, Islamic, and Bahá'í calendars.
When the current century is added to a two-digit year, if the result
is more than 50 years in the future, the previous century is assumed.
If the result is more than 50 years in the past, the next century is assumed.
(provide 'diary-lib)
+;; Local Variables:
+;; coding: utf-8
+;; End:
+
;;; diary-lib.el ends here
(mapcar 'purecopy
'((holiday-bahai-new-year)
(holiday-bahai-ridvan) ; respects calendar-bahai-all-holidays-flag
- (holiday-fixed 5 23 "Declaration of the Bab")
- (holiday-fixed 5 29 "Ascension of Baha'u'llah")
- (holiday-fixed 7 9 "Martyrdom of the Bab")
- (holiday-fixed 10 20 "Birth of the Bab")
- (holiday-fixed 11 12 "Birth of Baha'u'llah")
+ (holiday-fixed 5 23 "Declaration of the Báb")
+ (holiday-fixed 5 29 "Ascension of Bahá'u'lláh")
+ (holiday-fixed 7 9 "Martyrdom of the Báb")
+ (holiday-fixed 10 20 "Birth of the Báb")
+ (holiday-fixed 11 12 "Birth of Bahá'u'lláh")
(if calendar-bahai-all-holidays-flag
(append
(holiday-fixed 11 26 "Day of the Covenant")
- (holiday-fixed 11 28 "Ascension of `Abdu'l-Baha")))))
- "Baha'i holidays.
+ (holiday-fixed 11 28 "Ascension of `Abdu'l-Bahá")))))
+ "Bahá'í holidays.
See the documentation for `calendar-holidays' for details."
:type 'sexp
:group 'holidays)
K>0, and MONTH's last day otherwise.
(holiday-hebrew MONTH DAY STRING) a fixed date on the Hebrew calendar
(holiday-islamic MONTH DAY STRING) a fixed date on the Islamic calendar
- (holiday-bahai MONTH DAY STRING) a fixed date on the Baha'i calendar
+ (holiday-bahai MONTH DAY STRING) a fixed date on the Bahá'í calendar
(holiday-julian MONTH DAY STRING) a fixed date on the Julian calendar
(holiday-sexp SEXP STRING) SEXP is a Gregorian-date-valued expression
in the variable `year'; if it evaluates to
(holiday-islamic 3 12 \"Mohammed's Birthday\")
since the Islamic months are numbered from 1 starting with Muharram.
-To add an entry for the Baha'i festival of Ridvan, use
+To add an entry for the Bahá'í festival of Ridvan, use
(holiday-bahai 2 13 \"Festival of Ridvan\")
-since the Baha'i months are numbered from 1 starting with Baha.
+since the Bahá'í months are numbered from 1 starting with Bahá.
To add Thomas Jefferson's birthday, April 2, 1743 (Julian), use
(holiday-julian 4 2 \"Jefferson's Birthday\")
(if holiday-islamic-holidays
(cons "Islamic" holiday-islamic-holidays))
(if holiday-bahai-holidays
- (cons "Baha'i" holiday-bahai-holidays))
+ (cons "Bahá'í" holiday-bahai-holidays))
(if holiday-oriental-holidays
(cons "Oriental" holiday-oriental-holidays))
(if holiday-solar-holidays
(provide 'holidays)
+;; Local Variables:
+;; coding: utf-8
+;; End:
+
;;; holidays.el ends here
(eval-when-compile (require 'cl))
(require 'ring)
+(require 'ansi-color)
\f
;; Buffer Local Variables:
;;============================================================================
These functions get one argument, a string containing the text to send.")
;;;###autoload
-(defvar comint-output-filter-functions '(comint-postoutput-scroll-to-bottom comint-watch-for-password-prompt)
+(defvar comint-output-filter-functions '(ansi-color-process-output comint-postoutput-scroll-to-bottom comint-watch-for-password-prompt)
"Functions to call after output is inserted into the buffer.
One possible function is `comint-postoutput-scroll-to-bottom'.
These functions get one argument, a string containing the text as originally
The theme file is named THEME-theme.el, in one of the directories
specified by `custom-theme-load-path'.
-If optional arg NO-CONFIRM is non-nil, and THEME is not
-considered safe according to `custom-safe-themes', prompt the
-user for confirmation.
+If the theme is not considered safe by `custom-safe-themes',
+prompt the user for confirmation before loading it. But if
+optional arg NO-CONFIRM is non-nil, load the theme without
+prompting.
Normally, this function also enables THEME; if optional arg
NO-ENABLE is non-nil, load the theme but don't enable it.
;; FIXME "man ./" does not work with dired-do-shell-command,
;; because there seems to be no way for us to modify the filename,
;; only the command. Hmph. `dired-man' works though.
- (list "\\.\\(?:[0-9]\\|man\\)\\'" '(let ((loc (Man-support-local-filenames)))
- (cond ((eq loc 'man-db) "man -l")
- ((eq loc 'man) "man ./")
- (t
- "cat * | tbl | nroff -man -h"))))
+ (list "\\.\\(?:[0-9]\\|man\\)\\'"
+ '(let ((loc (Man-support-local-filenames)))
+ (cond ((eq loc 'man-db) "man -l")
+ ((eq loc 'man) "man ./")
+ (t
+ "cat * | tbl | nroff -man -h | col -b"))))
(list "\\.\\(?:[0-9]\\|man\\)\\.g?z\\'"
'(let ((loc (Man-support-local-filenames)))
(cond ((eq loc 'man-db)
"man -l")
((eq loc 'man)
"man ./")
- (t "gunzip -qc * | tbl | nroff -man -h")))
+ (t "gunzip -qc * | tbl | nroff -man -h | col -b")))
;; Optional decompression.
'(concat "gunzip" (if dired-guess-shell-gzip-quiet " -q")))
- (list "\\.[0-9]\\.Z\\'" '(let ((loc (Man-support-local-filenames)))
- (cond ((eq loc 'man-db) "man -l")
- ((eq loc 'man) "man ./")
- (t "zcat * | tbl | nroff -man -h")))
+ (list "\\.[0-9]\\.Z\\'"
+ '(let ((loc (Man-support-local-filenames)))
+ (cond ((eq loc 'man-db) "man -l")
+ ((eq loc 'man) "man ./")
+ (t "zcat * | tbl | nroff -man -h | col -b")))
;; Optional conversion to gzip format.
'(concat "znew" (if dired-guess-shell-gzip-quiet " -q")
" " dired-guess-shell-znew-switches))
;;;***
\f
;;;### (autoloads (dired-do-relsymlink dired-jump-other-window dired-jump)
-;;;;;; "dired-x" "dired-x.el" "bc516591d881911d72b58eeed8816576")
+;;;;;; "dired-x" "dired-x.el" "2a39a8306a5541c304bc4ab602876f92")
;;; Generated autoloads from dired-x.el
(autoload 'dired-jump "dired-x" "\
;;; authors.el --- utility for maintaining Emacs' AUTHORS file -*-coding: utf-8;-*-
-;; Copyright (C) 2000-2012 Free Software Foundation, Inc.
+;; Copyright (C) 2000-2012 Free Software Foundation, Inc.
;; Author: Gerd Moellmann <gerd@gnu.org>
;; Maintainer: Kim F. Storm <storm@cua.dk>
("David M. Koppelman" "David M. Koppelman, Koppel@Ec?e.Lsu.Edu"
"David Koppelman")
("David M. Smith" "David Smith" "David M Smith")
+ ("David O'Toole" "David T. O'Toole")
("Deepak Goel" "D. Goel")
("Ed L. Cashin" "Ed L Cashin")
("Edward M. Reingold" "Ed Reingold" "Edward M Reingold"
(and (not (string-match "\\.el\\'" name))
(ffap-locate-file name '(".el") load-path)))
+;; FIXME this duplicates the logic of Man-header-file-path.
+;; There should be a single central variable or function for this.
+;; See also (bug#10702):
+;; cc-search-directories, semantic-c-dependency-system-include-path,
+;; semantic-gcc-setup
(defvar ffap-c-path
- ;; Need smarter defaults here! Suggestions welcome.
- '("/usr/include" "/usr/local/include"))
+ (let ((arch (with-temp-buffer
+ (when (eq 0 (ignore-errors
+ (call-process "gcc" nil '(t nil) nil
+ "-print-multiarch")))
+ (goto-char (point-min))
+ (buffer-substring (point) (line-end-position)))))
+ (base '("/usr/include" "/usr/local/include")))
+ (if (zerop (length arch))
+ base
+ (append base (list (expand-file-name arch "/usr/include")))))
+ "List of directories to search for include files.")
+
(defun ffap-c-mode (name)
(ffap-locate-file name t ffap-c-path))
+2012-02-20 Lars Ingebrigtsen <larsi@gnus.org>
+
+ * mm-decode.el (mm-shr): Remove "soft hyphens".
+
+ * nnimap.el (nnimap-request-list): Return the group names encoded as
+ utf8. Otherwise non-European group names don't work.
+ (nnimap-request-newgroups): Ditto.
+
+ * gnus-sum.el (gnus-summary-insert-old-articles): Fix the syntax for
+ the default in `read-string' (bug#10757).
+
+ * gnus-msg.el (gnus-group-post-news): Don't bug out on `C-u a' on
+ topics (bug#10843).
+
+ * nnimap.el (nnimap-log-command): Add the IMAP address to the log
+ buffer. Suggested by Herbert Valerio Riedel.
+ (nnimap-request-move-article): Delete the message from the correct IMAP
+ server.
+
+2012-02-19 Vida Gábor <vidagabor@gmail.com> (tiny change)
+
+ * gnus-demon.el (gnus-demon-init): Don't multiply time twice.
+ Reported by Peter Münster.
+
+2012-02-18 Lars Ingebrigtsen <larsi@gnus.org>
+
+ * shr.el (shr-image-fetched): Make sure we really kill the right
+ buffer.
+
+2012-02-16 Leo Liu <sdl.web@gmail.com>
+
+ * gnus-start.el (gnus-1): Avoid duplicate entries.
+
2012-02-15 Lars Ingebrigtsen <larsi@gnus.org>
* shr.el (shr-remove-trailing-whitespace): Really delete the padding on
;; (func nil number)
;; Only call when Emacs has been idle for `idle'
((and (null time) (numberp idle))
- (run-with-idle-timer (* idle gnus-demon-timestep) t
- 'gnus-demon-run-callback func))
+ (run-with-idle-timer idle t 'gnus-demon-run-callback func))
;; (func number any)
;; Call every `time'
((eq time-type 'integer)
(if (= 1 (prefix-numeric-value arg))
(gnus-group-completing-read "Newsgroup" nil
(gnus-read-active-file-p))
- (gnus-group-group-name))
+ (or (gnus-group-group-name) ""))
""))
;; make sure last viewed article doesn't affect posting styles:
(gnus-article-copy))
;; Add "native" to gnus-predefined-server-alist just to have a
;; name for the native select method.
(when gnus-select-method
- (push (cons "native" gnus-select-method)
- gnus-predefined-server-alist))
+ (add-to-list 'gnus-predefined-server-alist
+ (cons "native" gnus-select-method)))
(if gnus-agent
(gnus-agentize))
(if initial "max" "default")
len)
nil nil
- (if initial
- (cons (number-to-string initial)
- 0)))))
+ (and initial
+ (number-to-string initial)))))
(unless (string-match "^[ \t]*$" input)
(setq all (string-to-number input))
(if (< all len)
(string-to-number (match-string 2)))
mm-extra-numeric-entities)))
(replace-match (char-to-string char))))
+ ;; Remove "soft hyphens".
+ (goto-char (point-min))
+ (while (search-forward "" nil t)
+ (replace-match "" t t))
(libxml-parse-html-region (point-min) (point-max))))
(mm-handle-set-undisplayer
handle
;;; mml1991.el --- Old PGP message format (RFC 1991) support for MML
-;; Copyright (C) 1998-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1998-2012 Free Software Foundation, Inc.
;; Author: Sascha Lüdecke <sascha@meta-x.de>,
;; Simon Josefsson <simon@josefsson.org> (Mailcrypt interface, Gnus glue)
-;; Keywords PGP
+;; Keywords: PGP
;; This file is part of GNU Emacs.
;; Move the article to a different method.
(let ((result (eval accept-form)))
(when result
+ (nnimap-possibly-change-group group server)
(nnimap-delete-article article)
result)))))))
(dolist (response responses)
(let* ((sequence (car response))
(response (cadr response))
- (group (cadr (assoc sequence sequences))))
+ (group (cadr (assoc sequence sequences)))
+ (egroup (encode-coding-string group 'utf-8)))
(when (and group
(equal (caar response) "OK"))
(let ((uidnext (nnimap-find-parameter "UIDNEXT" response))
(setq highest (1- (string-to-number (car uidnext)))))
(cond
((null highest)
- (insert (format "%S 0 1 y\n" (utf7-decode group t))))
+ (insert (format "%S 0 1 y\n" egroup)))
((zerop exists)
;; Empty group.
- (insert (format "%S %d %d y\n"
- (utf7-decode group t)
+ (insert (format "%S %d %d y\n" egroup
highest (1+ highest))))
(t
;; Return the widest possible range.
- (insert (format "%S %d 1 y\n" (utf7-decode group t)
+ (insert (format "%S %d 1 y\n" egroup
(or highest exists)))))))))
t)))))
(nnimap-get-groups)))
(unless (assoc group nnimap-current-infos)
;; Insert dummy numbers here -- they don't matter.
- (insert (format "%S 0 1 y\n" (utf7-encode group)))))
+ (insert (format "%S 0 1 y\n" (encode-coding-string group 'utf-8)))))
t)))
(deffoo nnimap-retrieve-group-data-early (server infos)
(when nnimap-record-commands
(with-current-buffer (get-buffer-create "*imap log*")
(goto-char (point-max))
- (insert (format-time-string "%H:%M:%S") " "
+ (insert (format-time-string "%H:%M:%S")
+ " [" nnimap-address "] "
(if nnimap-inhibit-logging
"(inhibited)\n"
command))))
directory)))))
(defun shr-image-fetched (status buffer start end)
- (when (and (buffer-name buffer)
- (not (plist-get status :error)))
- (url-store-in-cache (current-buffer))
- (when (or (search-forward "\n\n" nil t)
- (search-forward "\r\n\r\n" nil t))
- (let ((data (buffer-substring (point) (point-max))))
- (with-current-buffer buffer
- (save-excursion
- (let ((alt (buffer-substring start end))
- (inhibit-read-only t))
- (delete-region start end)
- (goto-char start)
- (funcall shr-put-image-function data alt)))))))
- (kill-buffer (current-buffer)))
+ (let ((image-buffer (current-buffer)))
+ (when (and (buffer-name buffer)
+ (not (plist-get status :error)))
+ (url-store-in-cache image-buffer)
+ (when (or (search-forward "\n\n" nil t)
+ (search-forward "\r\n\r\n" nil t))
+ (let ((data (buffer-substring (point) (point-max))))
+ (with-current-buffer buffer
+ (save-excursion
+ (let ((alt (buffer-substring start end))
+ (inhibit-read-only t))
+ (delete-region start end)
+ (goto-char start)
+ (funcall shr-put-image-function data alt)))))))
+ (kill-buffer image-buffer)))
(defun shr-put-image (data alt)
"Put image DATA with a string ALT. Return image."
(setq prospects nil)
(while (and comps (not limit))
(setq comp
- (if prefix-len (substring (car comps) prefix-len) (car comps))
+ (if (and prefix-len (<= prefix-len (length (car comps))))
+ (substring (car comps) prefix-len)
+ (car comps))
comps (cdr comps))
(cond ((string-equal comp "") (setq most-is-exact t))
((member comp prospects))
\f
;; Setting char-script-table.
+;; The data is compiled from Blocks.txt and Scripts.txt in the
+;; "Unicode Character Database", simplified to lump together all the
+;; blocks belonging to the same language. E.g., "Basic Latin",
+;; "Latin-1 Supplement", "Latin Extended-A", etc. are all lumped
+;; together under "latin".
+;;
;; The Unicode blocks actually extend past some of these ranges with
;; undefined codepoints.
(let ((script-list nil))
(#x0370 #x03E1 greek)
(#x03E2 #x03EF coptic)
(#x03F0 #x03F3 greek)
- (#x0400 #x04FF cyrillic)
+ (#x0400 #x052F cyrillic)
(#x0530 #x058F armenian)
(#x0590 #x05FF hebrew)
(#x0600 #x06FF arabic)
(#x0700 #x074F syriac)
- (#x07C0 #x07FA nko)
+ (#x0750 #x077F arabic)
(#x0780 #x07BF thaana)
+ (#x07C0 #x07FF nko)
+ (#x0800 #x083F samaritan)
+ (#x0840 #x085F mandaic)
+ (#x08A0 #x08FF arabic)
(#x0900 #x097F devanagari)
(#x0980 #x09FF bengali)
(#x0A00 #x0A7F gurmukhi)
(#x0C80 #x0CFF kannada)
(#x0D00 #x0D7F malayalam)
(#x0D80 #x0DFF sinhala)
- (#x0E00 #x0E5F thai)
- (#x0E80 #x0EDF lao)
+ (#x0E00 #x0E7F thai)
+ (#x0E80 #x0EFF lao)
(#x0F00 #x0FFF tibetan)
- (#x1000 #x109F burmese)
+ (#x1000 #x109F burmese) ; according to Unicode 6.1, should be "myanmar"
(#x10A0 #x10FF georgian)
(#x1100 #x11FF hangul)
(#x1200 #x139F ethiopic)
(#x1400 #x167F canadian-aboriginal)
(#x1680 #x169F ogham)
(#x16A0 #x16FF runic)
+ (#x1700 #x171F tagalog)
+ (#x1720 #x173F hanunoo)
+ (#x1740 #x175F buhid)
+ (#x1760 #x177F tagbanwa)
(#x1780 #x17FF khmer)
(#x1800 #x18AF mongolian)
- (#x1D00 #x1DFF phonetic)
- (#x1E00 #x1EFF latin)
+ (#x18B0 #x18FF canadian-aboriginal)
+ (#x1900 #x194F limbu)
+ (#x1950 #x197F tai-le)
+ (#x1980 #x19DF tai-lue)
+ (#x19E0 #x19FF khmer)
+ (#x1A00 #x1A00 buginese)
+ (#x1A20 #x1AAF tai-tham)
+ (#x1B00 #x1B7F balinese)
+ (#x1B80 #x1BBF sundanese)
+ (#x1BC0 #x1BFF batak)
+ (#x1C00 #x1C4F lepcha)
+ (#x1C50 #x1C7F ol-chiki)
+ (#x1CC0 #x1CCF sundanese)
+ (#x1CD0 #x1CFF vedic)
+ (#x1D00 #x1DBF phonetic)
+ (#x1DC0 #x1EFF latin)
(#x1F00 #x1FFF greek)
(#x2000 #x27FF symbol)
(#x2800 #x28FF braille)
+ (#x2900 #x2BFF symbol)
+ (#x2C00 #x2C5F glagolitic)
+ (#x2C60 #x2C7F latin)
+ (#x2C80 #x2CFF coptic)
+ (#x2D00 #x2D2F georgian)
+ (#x2D30 #x2D7F tifinagh)
(#x2D80 #x2DDF ethiopic)
+ (#x2DE0 #x2DFF cyrillic)
+ (#x2E00 #x2E7F symbol)
(#x2E80 #x2FDF han)
(#x2FF0 #x2FFF ideographic-description)
(#x3000 #x303F cjk-misc)
(#x3130 #x318F hangul)
(#x3190 #x319F kanbun)
(#x31A0 #x31BF bopomofo)
- (#x3400 #x9FAF han)
+ (#x31C0 #x31EF cjk-misc)
+ (#x31F0 #x31FF kana)
+ (#x3200 #x9FAF han)
(#xA000 #xA4CF yi)
+ (#xA4D0 #xA4FF lisu)
+ (#xA500 #xA63F vai)
+ (#xA640 #xA69F cyrillic)
+ (#xA6A0 #xA6FF bamum)
+ (#xA700 #xA7FF latin)
+ (#xA800 #xA82F syloti-nagri)
+ (#xA830 #xA83F north-indic-number)
+ (#xA840 #xA87F phags-pa)
+ (#xA880 #xA8DF saurashtra)
+ (#xA8E0 #xA8FF devanagari)
+ (#xA900 #xA92F kayah-li)
+ (#xA930 #xA95F rejang)
+ (#xA960 #xA97F hangul)
+ (#xA980 #xA9DF javanese)
(#xAA00 #xAA5F cham)
- (#xAA60 #xAA7B burmese)
+ (#xAA60 #xAA7B burmese) ; Unicode 6.1: "myanmar"
(#xAA80 #xAADF tai-viet)
- (#xAC00 #xD7AF hangul)
+ (#xAAE0 #xAAFF meetei-mayek)
+ (#xAB00 #xAB2F ethiopic)
+ (#xABC0 #xABFF meetei-mayek)
+ (#xAC00 #xD7FF hangul)
(#xF900 #xFAFF han)
(#xFB1D #xFB4F hebrew)
(#xFB50 #xFDFF arabic)
- (#xFE70 #xFEFC arabic)
+ (#xFE30 #xFE4F han)
+ (#xFE70 #xFEFF arabic)
(#xFF00 #xFF5F cjk-misc)
(#xFF61 #xFF9F kana)
(#xFFE0 #xFFE6 cjk-misc)
(#x10000 #x100FF linear-b)
(#x10100 #x1013F aegean-number)
- (#x10140 #x1018A ancient-greek-number)
- (#x10190 #x1019B ancient-symbol)
+ (#x10140 #x1018F ancient-greek-number)
+ (#x10190 #x101CF ancient-symbol)
(#x101D0 #x101FF phaistos-disc)
(#x10280 #x1029F lycian)
(#x102A0 #x102DF carian)
(#x10300 #x1032F olt-italic)
+ (#x10330 #x1034F gothic)
(#x10380 #x1039F ugaritic)
(#x103A0 #x103DF old-persian)
(#x10400 #x1044F deseret)
(#x10450 #x1047F shavian)
(#x10480 #x104AF osmanya)
(#x10800 #x1083F cypriot-syllabary)
+ (#x10840 #x1085F aramaic)
(#x10900 #x1091F phoenician)
(#x10920 #x1093F lydian)
+ (#x10980 #x109FF meroitic)
(#x10A00 #x10A5F kharoshthi)
+ (#x10A60 #x10A7F old-south-arabian)
+ (#x10B00 #x10B3F avestan)
+ (#x10B40 #x10B5F inscriptional-parthian)
+ (#x10B60 #x10B7F inscriptional-pahlavi)
+ (#x10C00 #x10C4F old-turkic)
+ (#x10E60 #x10E7F rumi-number)
+ (#x11000 #x1107F brahmi)
+ (#x11080 #x110CF kaithi)
+ (#x110D0 #x110FF sora-sompeng)
+ (#x11100 #x1114F chakma)
+ (#x11180 #x111DF sharada)
+ (#x11680 #x116CF takri)
(#x12000 #x123FF cuneiform)
(#x12400 #x1247F cuneiform-numbers-and-punctuation)
+ (#x13000 #x1342F egyptian)
+ (#x16800 #x16A3F bamum)
+ (#x16F00 #x16F9F miao)
+ (#x1B000 #x1B0FF kana)
(#x1D000 #x1D0FF byzantine-musical-symbol)
(#x1D100 #x1D1FF musical-symbol)
(#x1D200 #x1D24F ancient-greek-musical-notation)
(#x1D300 #x1D35F tai-xuan-jing-symbol)
(#x1D360 #x1D37F counting-rod-numeral)
(#x1D400 #x1D7FF mathematical)
+ (#x1EE00 #x1EEFF arabic)
(#x1F000 #x1F02F mahjong-tile)
(#x1F030 #x1F09F domino-tile)
- (#x20000 #x2AFFF han)
+ (#x1F0A0 #x1F0FF playing-cards)
+ (#x1F100 #x1F1FF symbol)
+ (#x1F200 #x1F2FF han)
+ (#x1F300 #x1F64F symbol)
+ (#x1F680 #x1F77F symbol)
+ (#x20000 #x2B81F han)
(#x2F800 #x2FFFF han)))
(set-char-table-range char-script-table
(cons (car elt) (nth 1 elt)) (nth 2 elt))
;; FILE: uni-name.el
(define-char-code-property 'name "uni-name.el"
"Unicode character name.
-Property value is a string.")
+Property value is a string or nil.
+The value nil stands for the default value \"null string\").")
;; FILE: uni-category.el
(define-char-code-property 'general-category "uni-category.el"
"Unicode general category.
;; FILE: uni-old-name.el
(define-char-code-property 'old-name "uni-old-name.el"
"Unicode old names as published in Unicode 1.0.
-Property value is a string.")
+Property value is a string or nil.
+The value nil stands for the default value \"null string\").")
;; FILE: uni-comment.el
(define-char-code-property 'iso-10646-comment "uni-comment.el"
"Unicode ISO 10646 comment.
(miscdic-convert filename dir))))
(kill-emacs 0))
-;; Local Variables:
-;; coding: iso-2022-7bit
-;; End:
-
;;; titdic-cnv.el ends here
;;; cham.el --- support for Cham -*- coding: utf-8; no-byte-compile: t -*-
-;; Copyright (C) 2008, 2009, 2010, 2011
+;; Copyright (C) 2008, 2009, 2010, 2011, 2012
;; National Institute of Advanced Industrial Science and Technology (AIST)
;; Registration Number H13PRO009
(coding-priority utf-8)))
(provide 'cham)
-
-;; Local Variables:
-;; coding: utf-8
-;; End:
-
")))
(provide 'tai-viet)
-
-;; Local Variables:
-;; coding: utf-8
-;; End:
:version "21.1")
;;;###autoload
-(defvaralias 'rmail-dont-reply-to-names 'mail-dont-reply-to-names)
+(define-obsolete-variable-alias 'rmail-dont-reply-to-names
+ 'mail-dont-reply-to-names "24.1")
+;; Prior to 24.1, this used to contain "\\`info-".
;;;###autoload
(defvar rmail-default-dont-reply-to-names nil
"Regexp specifying part of the default value of `mail-dont-reply-to-names'.
;;;***
\f
;;;### (autoloads (unforward-rmail-message undigestify-rmail-message)
-;;;;;; "undigest" "undigest.el" "1be42b2d20b13004f0ad1b504630ed00")
+;;;;;; "undigest" "undigest.el" "a31a35802a2adbc51be42959c3043dbd")
;;; Generated autoloads from undigest.el
(autoload 'undigestify-rmail-message "undigest" "\
(autoload 'unforward-rmail-message "undigest" "\
Extract a forwarded message from the containing message.
-This puts the forwarded message into a separate rmail message
-following the containing message.
+This puts the forwarded message into a separate rmail message following
+the containing message. This command is only useful when messages are
+forwarded with `rmail-enable-mime-composing' set to nil.
\(fn)" t nil)
;;;###autoload
(defun unforward-rmail-message ()
"Extract a forwarded message from the containing message.
-This puts the forwarded message into a separate rmail message
-following the containing message."
+This puts the forwarded message into a separate rmail message following
+the containing message. This command is only useful when messages are
+forwarded with `rmail-enable-mime-composing' set to nil."
(interactive)
(set-buffer rmail-buffer)
(let ((buff (current-buffer))
(string :tag "Real Section")))
:group 'man)
+;; FIXME see comments at ffap-c-path.
(defcustom Man-header-file-path
- '("/usr/include" "/usr/local/include")
+ (let ((arch (with-temp-buffer
+ (when (eq 0 (ignore-errors
+ (call-process "gcc" nil '(t nil) nil
+ "-print-multiarch")))
+ (goto-char (point-min))
+ (buffer-substring (point) (line-end-position)))))
+ (base '("/usr/include" "/usr/local/include")))
+ (if (zerop (length arch))
+ base
+ (append base (list (expand-file-name arch "/usr/include")))))
"C Header file search path used in Man."
+ :version "24.1" ; add multiarch
:type '(repeat string)
:group 'man)
"/etc/ssl/certs/ca-certificates.crt" ; Debian, Ubuntu, Gentoo and Arch Linux
"/etc/pki/tls/certs/ca-bundle.crt" ; Fedora and RHEL
"/etc/ssl/ca-bundle.pem" ; Suse
- "/usr/ssl/cert/ca-bundle.crt" ; Cygwin
+ "/usr/ssl/certs/ca-bundle.crt" ; Cygwin
)
"List of CA bundle location filenames or a function returning said list.
The files may be in PEM or DER format, as per the GnuTLS documentation.
;;; rcompile.el --- run a compilation on a remote machine
-;; Copyright (C) 1993-1994, 2001-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1993-1994, 2001-2012 Free Software Foundation, Inc.
-;; Author: Al
bert <alon@milcse.rtsg.mot.com>
+;; Author: Al
on Albert <alon@milcse.rtsg.mot.com>
;; Maintainer: FSF
;; Created: 1993 Oct 6
;; Keywords: tools, processes
(require 'wid-edit))
(require 'custom)
+;; FIXME this is bad practice, and who is it for anyway, since Emacs
+;; has split-string since at least 21.1.
(if (not (fboundp 'split-string))
(defun split-string (string &optional pattern)
"Return a list of substrings of STRING which are separated by PATTERN.
(declare-function socks-original-open-network-stream "socks") ; fset
+;; FIXME this is a terrible idea.
+;; It is not even compatible with the argument spec of open-network-stream
+;; in 24.1. If this is really necessary, open-network-stream
+;; could get a wrapper hook, or defer to open-network-stream-function.
+
(defvar socks-override-functions nil
"*Whether to overwrite the open-network-stream function with the SOCKSified
version.")
+(require 'network-stream)
+
(if (fboundp 'socks-original-open-network-stream)
nil ; Do nothing, we've been here already
(defalias 'socks-original-open-network-stream
/* bli */
if `comment-end' is empty, this has no effect, unless EXTRA is also set,
in which case the comment gets wrapped in a box.
-
+
EXTRA specifies that an extra line should be used before and after the
region to comment (to put the `comment-end' and `comment-start').
e.g. in C it comments regions as
(when (and sre (looking-at (concat "\\s-*\n\\s-*" srei)))
(goto-char (match-end 0)))
(if (null arg) (delete-region (point-min) (point))
- (skip-syntax-backward " ")
- (delete-char (- numarg))
- (unless (or (bobp)
- (save-excursion (goto-char (point-min))
- (looking-at comment-start-skip)))
- ;; If there's something left but it doesn't look like
- ;; a comment-start any more, just remove it.
- (delete-region (point-min) (point))))
+ (let ((opoint (point-marker)))
+ (skip-syntax-backward " ")
+ (delete-char (- numarg))
+ (unless (and (not (bobp))
+ (save-excursion (goto-char (point-min))
+ (looking-at comment-start-skip)))
+ ;; If there's something left but it doesn't look like
+ ;; a comment-start any more, just remove it.
+ (delete-region (point-min) opoint))))
;; Remove the end-comment (and leading padding and such).
(goto-char (point-max)) (comment-enter-backward)
;;; org-protocol.el --- Intercept calls from emacsclient to trigger custom actions.
-;;
-;; Copyright (C) 2008-2012
-;; Free Software Foundation, Inc.
-;;
+
+;; Copyright (C) 2008-2012 Free Software Foundation, Inc.
+
;; Author: Bastien Guerry <bzg AT gnu DOT org>
-;; Author: Daniel M German <dmg AT uvic DOT org>
-;; Author: Sebastian Rose <sebastian_rose AT gmx DOT de>
-;; Author: Ross Patterson <me AT rpatterson DOT net>
+;; Daniel M German <dmg AT uvic DOT org>
+;; Sebastian Rose <sebastian_rose AT gmx DOT de>
+;; Ross Patterson <me AT rpatterson DOT net>
;; Maintainer: Sebastian Rose <sebastian_rose AT gmx DOT de>
;; Keywords: org, emacsclient, wp
;;; octave-inf.el --- running Octave as an inferior Emacs process
-;; Copyright (C) 1997, 2001-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1997, 2001-2012 Free Software Foundation, Inc.
;; Author: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
-;; Author: John Eaton <jwe@bevo.che.wisc.edu>
+;; John Eaton <jwe@bevo.che.wisc.edu>
;; Maintainer: FSF
;; Keywords: languages
;; Package: octave-mod
;;; octave-mod.el --- editing Octave source files under Emacs
-;; Copyright (C) 1997, 2001-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1997, 2001-2012 Free Software Foundation, Inc.
;; Author: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
-;; Author: John Eaton <jwe@octave.org>
+;; John Eaton <jwe@octave.org>
;; Maintainer: FSF
;; Keywords: languages
removable and network volumes."
:type 'regexp :group 'save-place)
+(defcustom save-place-ignore-files-regexp
+ "\\(?:COMMIT_EDITMSG\\|hg-editor-[[:alnum:]]+\\.txt\\|svn-commit\\.tmp\\|bzr_log\\.[[:alnum:]]+\\)$"
+ "Regexp matching files for which no location should be recorded.
+Useful for temporary file such as commit message files that are
+automatically created by the VCS."
+ :version "24.1"
+ :type 'regexp :group 'save-place)
+
(defun toggle-save-place (&optional parg)
"Toggle whether to save your place in this file between sessions.
If this mode is enabled, point is recorded when you kill the buffer
;; file. If not, do so, then feel free to modify the alist. It
;; will be saved again when Emacs is killed.
(or save-place-loaded (load-save-place-alist-from-file))
- (if buffer-file-name
- (progn
- (let ((cell (assoc buffer-file-name save-place-alist))
- (position (if (not (eq major-mode 'hexl-mode))
- (point)
- (with-no-warnings
- (1+ (hexl-current-address))))))
- (if cell
- (setq save-place-alist (delq cell save-place-alist)))
- (if (and save-place
- (not (= position 1))) ;; Optimize out the degenerate case.
- (setq save-place-alist
- (cons (cons buffer-file-name position)
- save-place-alist)))))))
+ (when (and buffer-file-name
+ (not (string-match save-place-ignore-files-regexp
+ buffer-file-name)))
+ (let ((cell (assoc buffer-file-name save-place-alist))
+ (position (if (not (eq major-mode 'hexl-mode))
+ (point)
+ (with-no-warnings
+ (1+ (hexl-current-address))))))
+ (if cell
+ (setq save-place-alist (delq cell save-place-alist)))
+ (if (and save-place
+ (not (= position 1))) ;; Optimize out the degenerate case.
+ (setq save-place-alist
+ (cons (cons buffer-file-name position)
+ save-place-alist))))))
(defun save-place-forget-unreadable-files ()
"Remove unreadable files from `save-place-alist'.
(set (make-local-variable 'shell-dirstack) nil)
(set (make-local-variable 'shell-last-dir) nil)
(shell-dirtrack-mode 1)
+
+ ;; By default, ansi-color applies faces using overlays. This is
+ ;; very inefficient in Shell buffers (e.g. Bug#10835). We use a
+ ;; custom `ansi-color-apply-face-function' to convert color escape
+ ;; sequences into `font-lock-face' properties.
+ (set (make-local-variable 'ansi-color-apply-face-function)
+ (lambda (beg end face)
+ (when face
+ (put-text-property beg end 'font-lock-face face))))
+
;; This is not really correct, since the shell buffer does not really
;; edit this directory. But it is useful in the buffer list and menus.
(setq list-buffers-directory (expand-file-name default-directory))
(read-directory-name
"Default directory: " default-directory default-directory
t nil))))))))
- (require 'ansi-color)
(setq buffer (if (or buffer (not (derived-mode-p 'shell-mode))
(comint-check-proc (current-buffer)))
(get-buffer-create (or buffer "*shell*"))
;;; picture.el --- "Picture mode" -- editing using quarter-plane screen model
-;; Copyright (C) 1985, 1994, 2001-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1985, 1994, 2001-2012 Free Software Foundation, Inc.
;; Author: K. Shane Hartman
;; Maintainer: FSF
"Move point in direction of current picture motion in Picture mode.
With ARG do it that many times. Useful for delineating rectangles in
conjunction with diagonal picture motion.
-Do \\[command-apropos] picture-movement to see commands which control motion."
+Use \"\\[command-apropos] picture-movement\" to see commands which control motion."
(interactive "^p")
(picture-move-down (* arg picture-vertical-step))
(picture-forward-column (* arg picture-horizontal-step)))
"Move point in direction opposite of current picture motion in Picture mode.
With ARG do it that many times. Useful for delineating rectangles in
conjunction with diagonal picture motion.
-Do \\[command-apropos] picture-movement to see commands which control motion."
+Use \"\\[command-apropos] picture-movement\" to see commands which control motion."
(interactive "^p")
(picture-motion (- arg)))
"Insert this character in place of character previously at the cursor.
The cursor then moves in the direction you previously specified
with the commands `picture-movement-right', `picture-movement-up', etc.
-Do \\[command-apropos] `picture-movement' to see those commands."
+Use \"\\[command-apropos] picture-movement\" to see those commands."
(interactive "p")
(picture-update-desired-column (not (eq this-command last-command)))
(picture-insert last-command-event arg)) ; Always a character in this case.
(defcustom picture-tab-chars "!-~"
"A character set which controls behavior of commands.
-\\[picture-set-tab-stops] and \\[picture-tab-search]. It is NOT a
-regular expression, any regexp special characters will be quoted.
+\\[picture-set-tab-stops] and \\[picture-tab-search].
+The syntax for this variable is like the syntax used inside of `[...]'
+in a regular expression--but without the `[' and the `]'.
+It is NOT a regular expression, any regexp special characters will be quoted.
It defines a set of \"interesting characters\" to look for when setting
\(or searching for) tab stops, initially \"!-~\" (all printing characters).
For example, suppose that you are editing a table which is formatted thus:
\f
;; Picture Keymap, entry and exit points.
+(defalias 'picture-delete-char 'delete-char)
+
(defvar picture-mode-map nil)
(defun picture-substitute (oldfun newfun)
(picture-substitute 'newline-and-indent 'picture-duplicate-line)
(picture-substitute 'next-line 'picture-move-down)
(picture-substitute 'previous-line 'picture-move-up)
- (picture-substitute 'beginning-of-line 'picture-beginning-of-line)
- (picture-substitute 'end-of-line 'picture-end-of-line)
+ (picture-substitute 'move-beginning-of-line 'picture-beginning-of-line)
+ (picture-substitute 'move-end-of-line 'picture-end-of-line)
(picture-substitute 'mouse-set-point 'picture-mouse-set-point)
- (define-key picture-mode-map "\C-c\C-d" 'delete-char)
+ (define-key picture-mode-map "\C-c\C-d" 'picture-delete-char)
(define-key picture-mode-map "\e\t" 'picture-toggle-tab-state)
(define-key picture-mode-map "\t" 'picture-tab)
(define-key picture-mode-map "\e\t" 'picture-tab-search)
You can manipulate text with these commands:
Clear ARG columns after point without moving: \\[picture-clear-column]
- Delete char at point: \\[delete-char]
+ Delete char at point: \\[picture-delete-char]
Clear ARG columns backward: \\[picture-backward-clear-column]
Clear ARG lines, advancing over them: \\[picture-clear-line]
(the cleared text is saved in the kill ring)
+2012-02-20 Lars Ingebrigtsen <larsi@gnus.org>
+
+ * url-queue.el (url-queue-kill-job): Delete the process sentinel
+ before killing the process to avoid a race condition between the
+ two processes killing off the process buffer.
+
+ * url.el (url-retrieve-internal): Warn about file errors when
+ pruning the cache instead of bugging out (bug#10831).
+
+2012-02-19 Lars Ingebrigtsen <larsi@gnus.org>
+
+ * url-queue.el (url-queue-callback-function): Remove the job from
+ the queue so that we don't kill the current buffer, which will
+ then make the callback function kill a random buffer.
+
2012-02-14 Lars Ingebrigtsen <larsi@gnus.org>
* url-queue.el (url-queue-kill-job): Refactored out code.
(url-queue-start-retrieve waiting))))
(defun url-queue-callback-function (status job)
+ (setq url-queue (delq job url-queue))
(when (and (eq (car status) :error)
(eq (cadr (cadr status)) 'connection-failed))
;; If we get a connection error, then flush all other jobs from
;; synchronously and totally halts Emacs.
(url-queue-remove-jobs-from-host
(plist-get (nthcdr 3 (cadr status)) :host)))
- (setq url-queue (delq job url-queue))
(url-queue-run-queue)
(apply (url-queue-callback job) (cons status (url-queue-cbargs job))))
(defun url-queue-kill-job (job)
(when (bufferp (url-queue-buffer job))
- (while (get-buffer-process (url-queue-buffer job))
- (ignore-errors
- (delete-process (get-buffer-process (url-queue-buffer job)))))
+ (let (process)
+ (while (setq process (get-buffer-process (url-queue-buffer job)))
+ (set-process-sentinel process 'ignore)
+ (ignore-errors
+ (delete-process process))))
(ignore-errors
(kill-buffer (url-queue-buffer job)))))
(setf (url-use-cookies url) (not inhibit-cookies))
;; Once in a while, remove old entries from the URL cache.
(when (zerop (% url-retrieve-number-of-calls 1000))
- (url-cache-prune-cache))
+ (condition-case error
+ (url-cache-prune-cache)
+ (file-error
+ (message "Error when expiring the cache: %s" error))))
(setq url-retrieve-number-of-calls (1+ url-retrieve-number-of-calls))
(let ((loader (url-scheme-get-property (url-type url) 'loader))
(url-using-proxy (if (url-host url)
;; If ediff modified mode line, strip the modification
(defsubst ediff-strip-mode-line-format ()
- (if (member (car mode-line-format) '(" A: " " B: " " C: " " Ancestor: "))
- (setq mode-line-format (nth 2 mode-line-format))))
+ (and (consp mode-line-format)
+ (member (car mode-line-format)
+ '(" A: " " B: " " C: " " Ancestor: "))
+ (setq mode-line-format (nth 2 mode-line-format))))
;; Verify that we have a difference selected.
(defsubst ediff-valid-difference-p (&optional n)
(defmacro emerge-defvar-local (var value doc)
"Defines SYMBOL as an advertised variable.
Performs a defvar, then executes `make-variable-buffer-local' on
-the variable. Also sets the `preserved' property, so that
+the variable. Also sets the `permanent-local' property, so that
`kill-all-local-variables' (called by major-mode setting commands)
won't destroy Emerge control variables."
`(progn
(defvar ,var ,value ,doc)
(make-variable-buffer-local ',var)
- (put ',var 'preserved t)))
+ (put ',var 'permanent-local t)))
;; Add entries to minor-mode-alist so that emerge modes show correctly
(defvar emerge-minor-modes-list
while ($i < $it->sp && $i < 4)
set $e = $it->stack[$i]
printf "stack[%d]: ", $i
- pitmethod $e->method
- printf "[%d]", $e->position.charpos
+ pitmethod $e.method
+ printf "[%d]", $e.position.charpos
printf "\n"
set $i = $i + 1
end
define xreload
set $tagmask = (((long)1 << gdb_gctypebits) - 1)
- set $valmask = gdb_use_lsb ? ~($tagmask) : ((long)1 << gdb_valbits) - 1
+ # The consing_since_gc business widens the 1 to EMACS_INT,
+ # a symbol not directly visible to GDB.
+ set $valmask = gdb_use_lsb ? ~($tagmask) : ((consing_since_gc - consing_since_gc + 1) << gdb_valbits) - 1
end
document xreload
When starting Emacs a second time in the same gdb session under
+2012-02-22 Chong Yidong <cyd@gnu.org>
+
+ * xterm.c (x_draw_image_relief): Add missing type check for
+ Vtool_bar_button_margin (Bug#10743).
+
+2012-02-21 Chong Yidong <cyd@gnu.org>
+
+ * fileio.c (Vfile_name_handler_alist): Doc fix.
+
+ * buffer.c (Fget_file_buffer): Protect against invalid file
+ handler return value.
+
+2012-02-20 Paul Eggert <eggert@cs.ucla.edu>
+
+ * .gdbinit (xreload): Don't assume EMACS_INT fits in 'long'
+ when computing $valmask.
+
+ Fix crash due to non-contiguous EMACS_INT (Bug#10780).
+ * lisp.h (VALBITS): Move definition up, so that USE_LSB_TAG can use it.
+ (USE_LSB_TAG): Do not define if UINTPTR_MAX >> VALBITS == 0.
+ It's useless in that case, and it can cause problems on hosts
+ that allocate halves of EMACS_INT values separately.
+ Reported by Dan Horák. Diagnosed by Andreas Schwab in
+ <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=10780#30>.
+ * mem-limits.h (EXCEEDS_LISP_PTR): Define to 0 on hosts where
+ UINTPTR_MAX >> VALBITS == 0. This is required by the above change;
+ it avoids undefined behavior on hosts where shifting right by more
+ than the word width has undefined behavior.
+
+2012-02-19 Chong Yidong <cyd@gnu.org>
+
+ * fileio.c (Ffile_name_directory, Ffile_name_nondirectory)
+ (Funhandled_file_name_directory, Ffile_name_as_directory)
+ (Fdirectory_file_name, Fexpand_file_name)
+ (Fsubstitute_in_file_name): Protect against invalid file handler
+ return values (Bug#10845).
+
+2012-02-18 Eli Zaretskii <eliz@gnu.org>
+
+ * .gdbinit (pitx): Fix incorrect references to fields of the
+ iterator stack.
+
+2012-02-17 Chong Yidong <cyd@gnu.org>
+
+ * syntax.c (Fscan_lists): Doc fix (Bug#10833).
+
2012-02-15 Paul Eggert <eggert@cs.ucla.edu>
* image.c (MAX_IMAGE_SIZE): Increase from 6.0 to 10.0; see
call the corresponding file handler. */
handler = Ffind_file_name_handler (filename, Qget_file_buffer);
if (!NILP (handler))
- return call2 (handler, Qget_file_buffer, filename);
+ {
+ Lisp_Object handled_buf = call2 (handler, Qget_file_buffer,
+ filename);
+ return BUFFERP (handled_buf) ? handled_buf : Qnil;
+ }
for (tail = Vbuffer_alist; CONSP (tail); tail = XCDR (tail))
{
call the corresponding file handler. */
handler = Ffind_file_name_handler (filename, Qfile_name_directory);
if (!NILP (handler))
- return call2 (handler, Qfile_name_directory, filename);
+ {
+ Lisp_Object handled_name = call2 (handler, Qfile_name_directory,
+ filename);
+ return STRINGP (handled_name) ? handled_name : Qnil;
+ }
filename = FILE_SYSTEM_CASE (filename);
#ifdef DOS_NT
call the corresponding file handler. */
handler = Ffind_file_name_handler (filename, Qfile_name_nondirectory);
if (!NILP (handler))
- return call2 (handler, Qfile_name_nondirectory, filename);
+ {
+ Lisp_Object handled_name = call2 (handler, Qfile_name_nondirectory,
+ filename);
+ if (STRINGP (handled_name))
+ return handled_name;
+ error ("Invalid handler in `file-name-handler-alist'");
+ }
beg = SSDATA (filename);
end = p = beg + SBYTES (filename);
call the corresponding file handler. */
handler = Ffind_file_name_handler (filename, Qunhandled_file_name_directory);
if (!NILP (handler))
- return call2 (handler, Qunhandled_file_name_directory, filename);
+ {
+ Lisp_Object handled_name = call2 (handler, Qunhandled_file_name_directory,
+ filename);
+ return STRINGP (handled_name) ? handled_name : Qnil;
+ }
return Ffile_name_directory (filename);
}
call the corresponding file handler. */
handler = Ffind_file_name_handler (file, Qfile_name_as_directory);
if (!NILP (handler))
- return call2 (handler, Qfile_name_as_directory, file);
+ {
+ Lisp_Object handled_name = call2 (handler, Qfile_name_as_directory,
+ file);
+ if (STRINGP (handled_name))
+ return handled_name;
+ error ("Invalid handler in `file-name-handler-alist'");
+ }
buf = (char *) alloca (SBYTES (file) + 10);
file_name_as_directory (buf, SSDATA (file));
call the corresponding file handler. */
handler = Ffind_file_name_handler (directory, Qdirectory_file_name);
if (!NILP (handler))
- return call2 (handler, Qdirectory_file_name, directory);
+ {
+ Lisp_Object handled_name = call2 (handler, Qdirectory_file_name,
+ directory);
+ if (STRINGP (handled_name))
+ return handled_name;
+ error ("Invalid handler in `file-name-handler-alist'");
+ }
buf = (char *) alloca (SBYTES (directory) + 20);
directory_file_name (SSDATA (directory), buf);
int is_escaped = 0;
#endif /* DOS_NT */
ptrdiff_t length;
- Lisp_Object handler, result;
+ Lisp_Object handler, result, handled_name;
int multibyte;
Lisp_Object hdir;
call the corresponding file handler. */
handler = Ffind_file_name_handler (name, Qexpand_file_name);
if (!NILP (handler))
- return call3 (handler, Qexpand_file_name, name, default_directory);
+ {
+ handled_name = call3 (handler, Qexpand_file_name,
+ name, default_directory);
+ if (STRINGP (handled_name))
+ return handled_name;
+ error ("Invalid handler in `file-name-handler-alist'");
+ }
+
/* Use the buffer's default-directory if DEFAULT_DIRECTORY is omitted. */
if (NILP (default_directory))
{
handler = Ffind_file_name_handler (default_directory, Qexpand_file_name);
if (!NILP (handler))
- return call3 (handler, Qexpand_file_name, name, default_directory);
+ {
+ handled_name = call3 (handler, Qexpand_file_name,
+ name, default_directory);
+ if (STRINGP (handled_name))
+ return handled_name;
+ error ("Invalid handler in `file-name-handler-alist'");
+ }
}
{
to be expanded again. */
handler = Ffind_file_name_handler (result, Qexpand_file_name);
if (!NILP (handler))
- return call3 (handler, Qexpand_file_name, result, default_directory);
+ {
+ handled_name = call3 (handler, Qexpand_file_name,
+ result, default_directory);
+ if (STRINGP (handled_name))
+ return handled_name;
+ error ("Invalid handler in `file-name-handler-alist'");
+ }
return result;
}
call the corresponding file handler. */
handler = Ffind_file_name_handler (filename, Qsubstitute_in_file_name);
if (!NILP (handler))
- return call2 (handler, Qsubstitute_in_file_name, filename);
+ {
+ Lisp_Object handled_name = call2 (handler, Qsubstitute_in_file_name,
+ filename);
+ if (STRINGP (handled_name))
+ return handled_name;
+ error ("Invalid handler in `file-name-handler-alist'");
+ }
/* Always work on a copy of the string, in case GC happens during
decode of environment variables, causing the original Lisp_String
make_pure_c_string ("Cannot set file date"));
DEFVAR_LISP ("file-name-handler-alist", Vfile_name_handler_alist,
- doc: /* *Alist of elements (REGEXP . HANDLER) for file names handled specially.
-If a file name matches REGEXP, then all I/O on that file is done by calling
-HANDLER.
-
-The first argument given to HANDLER is the name of the I/O primitive
-to be handled; the remaining arguments are the arguments that were
-passed to that primitive. For example, if you do
- (file-exists-p FILENAME)
-and FILENAME is handled by HANDLER, then HANDLER is called like this:
- (funcall HANDLER 'file-exists-p FILENAME)
-The function `find-file-name-handler' checks this list for a handler
-for its argument. */);
+ doc: /* Alist of elements (REGEXP . HANDLER) for file names handled specially.
+If a file name matches REGEXP, all I/O on that file is done by calling
+HANDLER. If a file name matches more than one handler, the handler
+whose match starts last in the file name gets precedence. The
+function `find-file-name-handler' checks this list for a handler for
+its argument.
+
+HANDLER should be a function. The first argument given to it is the
+name of the I/O primitive to be handled; the remaining arguments are
+the arguments that were passed to that primitive. For example, if you
+do (file-exists-p FILENAME) and FILENAME is handled by HANDLER, then
+HANDLER is called like this:
+
+ (funcall HANDLER 'file-exists-p FILENAME)
+
+Note that HANDLER must be able to handle all I/O primitives; if it has
+nothing special to do for a primitive, it should reinvoke the
+primitive to handle the operation \"the usual way\".
+See Info node `(elisp)Magic File Names' for more details. */);
Vfile_name_handler_alist = Qnil;
DEFVAR_LISP ("set-auto-coding-function",
#define GCTYPEBITS 3
#endif
+#ifndef VALBITS
+#define VALBITS (BITS_PER_EMACS_INT - GCTYPEBITS)
+#endif
+
#ifndef NO_DECL_ALIGN
# ifndef DECL_ALIGN
# if HAVE_ATTRIBUTE_ALIGNED
|| defined DARWIN_OS || defined __sun)
/* We also need to be able to specify mult-of-8 alignment on static vars. */
# if defined DECL_ALIGN
-# define USE_LSB_TAG
+/* mark_maybe_object assumes that EMACS_INT values are contiguous,
+ but this is not true on some hosts where EMACS_INT is wider than a pointer,
+ as they may allocate the halves of an EMACS_INT separately.
+ On these hosts USE_LSB_TAG is not needed because the top bits of an
+ EMACS_INT are unused, so define USE_LSB_TAG only on hosts where it
+ might be useful. */
+# if UINTPTR_MAX >> VALBITS != 0
+# define USE_LSB_TAG
+# endif
# endif
#endif
Lisp_Fwd_Kboard_Obj, /* Fwd to a Lisp_Object field of kboards. */
};
-/* These values are overridden by the m- file on some machines. */
-#ifndef VALBITS
-#define VALBITS (BITS_PER_EMACS_INT - GCTYPEBITS)
-#endif
-
#ifdef USE_LISP_UNION_TYPE
#ifndef WORDS_BIGENDIAN
#endif
extern char *start_of_data (void);
-#if defined USE_LSB_TAG
+#if defined USE_LSB_TAG || UINTPTR_MAX >> VALBITS == 0
#define EXCEEDS_LISP_PTR(ptr) 0
#elif defined DATA_SEG_BITS
#define EXCEEDS_LISP_PTR(ptr) \
DEFUN ("scan-lists", Fscan_lists, Sscan_lists, 3, 3, 0,
doc: /* Scan from character number FROM by COUNT lists.
-Returns the character number of the position thus found.
+Scan forward if COUNT is positive, backward if COUNT is negative.
+Return the character number of the position thus found.
+
+A \"list", in this context, refers to a balanced parenthetical
+grouping, as determined by the syntax table.
-If DEPTH is nonzero, paren depth begins counting from that value,
-only places where the depth in parentheses becomes zero
-are candidates for stopping; COUNT such places are counted.
-Thus, a positive value for DEPTH means go out levels.
+If DEPTH is nonzero, treat that as the nesting depth of the starting
+point (i.e. the starting point is DEPTH parentheses deep). This
+function scans over parentheses until the depth goes to zero COUNT
+times. Hence, positive DEPTH moves out that number of levels of
+parentheses, while negative DEPTH moves to a deeper level.
Comments are ignored if `parse-sexp-ignore-comments' is non-nil.
-If the beginning or end of (the accessible part of) the buffer is reached
-and the depth is wrong, an error is signaled.
-If the depth is right but the count is not used up, nil is returned. */)
+If we reach the beginning or end of the accessible part of the buffer
+before we have scanned over COUNT lists, return nil if the depth at
+that point is zero, and signal a error if the depth is nonzero. */)
(Lisp_Object from, Lisp_Object count, Lisp_Object depth)
{
CHECK_NUMBER (from);
static void
x_draw_image_relief (struct glyph_string *s)
{
- int x0, y0, x1, y1, thick, raised_p, extra;
+ int x0, y0, x1, y1, thick, raised_p;
+ int extra_x, extra_y;
XRectangle r;
int x = s->x;
int y = s->ybase - image_ascent (s->img, s->face, &s->slice);
raised_p = s->img->relief > 0;
}
- extra = s->face->id == TOOL_BAR_FACE_ID
- ? XINT (Vtool_bar_button_margin) : 0;
+ extra_x = extra_y = 0;
+ if (s->face->id == TOOL_BAR_FACE_ID)
+ {
+ if (CONSP (Vtool_bar_button_margin)
+ && INTEGERP (XCAR (Vtool_bar_button_margin))
+ && INTEGERP (XCDR (Vtool_bar_button_margin)))
+ {
+ extra_x = XINT (XCAR (Vtool_bar_button_margin));
+ extra_y = XINT (XCDR (Vtool_bar_button_margin));
+ }
+ else if (INTEGERP (Vtool_bar_button_margin))
+ extra_x = extra_y = XINT (Vtool_bar_button_margin);
+ }
- x0 = x - thick - extra;
- y0 = y - thick - extra;
- x1 = x + s->slice.width + thick - 1 + extra;
- y1 = y + s->slice.height + thick - 1 + extra;
+ x0 = x - thick - extra_x;
+ y0 = y - thick - extra_y;
+ x1 = x + s->slice.width + thick - 1 + extra_x;
+ y1 = y + s->slice.height + thick - 1 + extra_y;
x_setup_relief_colors (s);
get_glyph_string_clip_rect (s, &r);