+2012-04-26 Glenn Morris <rgm@gnu.org>
+
+ * ack.texi, basic.texi, buffers.texi, building.texi:
+ * calendar.texi, cmdargs.texi, commands.texi, custom.texi:
+ * dired.texi, display.texi, emerge-xtra.texi, files.texi:
+ * fortran-xtra.texi, help.texi, kmacro.texi, mini.texi, misc.texi:
+ * msdog-xtra.texi, picture-xtra.texi, programs.texi, rmail.texi:
+ * search.texi, trouble.texi, windows.texi:
+ Use Texinfo recommended convention for quotes+punctuation.
+
2012-04-25 Eli Zaretskii <eliz@gnu.org>
* mule.texi (Bidirectional Editing): Improve indexing. Minor
@item
Mathias Dahl wrote @file{image-dired.el}, a package for viewing image
-files as ``thumbnails.''
+files as ``thumbnails''.
@item
Julien Danjou wrote an implementation of ``Desktop Notifications''
@item
Danny Roozendaal implemented @file{handwrite.el}, which converts text
-into ``handwriting.''
+into ``handwriting''.
@item
Markus Rost wrote @file{cus-test.el}, a testing framework for customize.
@item
Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing
-image files as ``thumbnails.''
+image files as ``thumbnails''.
@item
Spencer Thomas wrote the original @file{dabbrev.el}, providing a command
@cindex arguments to commands
In the terminology of mathematics and computing, @dfn{argument}
-means ``data provided to a function or operation.'' You can give any
+means ``data provided to a function or operation''. You can give any
Emacs command a @dfn{numeric argument} (also called a @dfn{prefix
argument}). Some commands interpret the argument as a repetition
count. For example, giving @kbd{C-f} an argument of ten causes it to
more convenient, and they are documented in that command's
documentation string.
- We use the term ``prefix argument'' as well as ``numeric argument,''
+ We use the term ``prefix argument'' as well as ``numeric argument'',
to emphasize that you type these argument before the command, and to
distinguish them from minibuffer arguments that come after the
command.
@samp{.} in the first field of a line indicates that the buffer is
current. @samp{%} indicates a read-only buffer. @samp{*} indicates
-that the buffer is ``modified.'' If several buffers are modified, it
+that the buffer is ``modified''. If several buffers are modified, it
may be time to save some with @kbd{C-x s} (@pxref{Save Commands}).
Here is an example of a buffer list:
@table @kbd
@item ~
-Mark the buffer ``unmodified.'' The command @kbd{~} does this
+Mark the buffer ``unmodified''. The command @kbd{~} does this
immediately when you type it.
@item %
Toggle the buffer's read-only flag. The command @kbd{%} does
Iswitchb global minor mode provides convenient switching between
buffers using substrings of their names. It replaces the normal
definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x
-4 C-o} with alternative commands that are somewhat ``smarter.''
+4 C-o} with alternative commands that are somewhat ``smarter''.
When one of these commands prompts you for a buffer name, you can
type in just a substring of the name you want to choose. As you enter
Just as you can run a compiler from Emacs and then visit the lines
with compilation errors, you can also run @command{grep} and then
visit the lines on which matches were found. This works by treating
-the matches reported by @command{grep} as if they were ``errors.''
+the matches reported by @command{grep} as if they were ``errors''.
The output buffer uses Grep mode, which is a variant of Compilation
mode (@pxref{Compilation Mode}).
These calendar commands display the dates and times of the phases of
the moon (new moon, first quarter, full moon, last quarter). This
feature is useful for debugging problems that ``depend on the phase of
-the moon.''
+the moon''.
@table @kbd
@item M
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
+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. You can also use @kbd{Mouse-3} and
then choose @kbd{Other calendars} from the menu that appears. This
@findex calendar-hebrew-list-yahrzeits
@cindex yahrzeits
One common issue concerning the Hebrew calendar is the computation
-of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
+of the anniversary of a date of death, called a ``yahrzeit''. The Emacs
calendar includes a facility for such calculations. If you are in the
calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for
a range of years and then displays a list of the yahrzeit dates for those
@noindent
The 11 specifies November (the eleventh month), the 4 specifies Thursday
(the fourth day of the week, where Sunday is numbered zero), and the
-second 4 specifies the fourth Thursday (1 would mean ``first,'' 2 would
-mean ``second,'' @minus{}2 would mean ``second-to-last,'' and so on).
+second 4 specifies the fourth Thursday (1 would mean ``first'', 2 would
+mean ``second'', @minus{}2 would mean ``second-to-last'', and so on).
The month can be a single month or a list of months. Thus you could change
the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
Thursday of January, February, and March. If the month is @code{t}, the
Once you've collected data from a number of time intervals, you can use
@kbd{M-x timeclock-workday-remaining} to see how much time is left to
work today (assuming a typical average of 8 hours a day), and @kbd{M-x
-timeclock-when-to-leave} which will calculate when you're ``done.''
+timeclock-when-to-leave} which will calculate when you're ``done''.
@vindex timeclock-modeline-display
@findex timeclock-modeline-display
initialize the Lisp variable @code{doc-directory}.
@item EMACSLOADPATH
A colon-separated list of directories@footnote{ Here and below,
-whenever we say ``colon-separated list of directories,'' it pertains
+whenever we say ``colon-separated list of directories'', it pertains
to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, the
directories are separated by semi-colons instead, since DOS/Windows
file names might include a colon after a drive letter.} to search for
Usually we state the name of the command which really does the work in
parentheses after mentioning the key that runs it. For example, we
will say that ``The command @kbd{C-n} (@code{next-line}) moves point
-vertically down,'' meaning that the command @code{next-line} moves
+vertically down'', meaning that the command @code{next-line} moves
vertically down, and the key @kbd{C-n} is normally bound to it.
Since we are discussing customization, we should tell you about
This constrains what you can do with double clicks, but user interface
designers say that this constraint ought to be followed in any case. A
double click should do something similar to the single click, only
-``more so.'' The command for the double-click event should perform the
+``more so''. The command for the double-click event should perform the
extra work for the double click.
If a double-click event has no binding, it changes to the
A frame includes areas that don't show text from the buffer, such as
the mode line and the scroll bar. You can tell whether a mouse button
comes from a special area of the screen by means of dummy ``prefix
-keys.'' For example, if you click the mouse in the mode line, you get
+keys''. For example, if you click the mouse in the mode line, you get
the prefix key @code{mode-line} before the ordinary mouse-button symbol.
Thus, here is how to define the command for clicking the first button in
a mode line to run @code{scroll-up-command}:
Emacs commands to move around in this buffer, and special Dired
commands to operate on the listed files.
- The Dired buffer is ``read-only,'' and inserting text in it is not
+ The Dired buffer is ``read-only'', and inserting text in it is not
allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are
redefined for special Dired commands. Some Dired commands @dfn{mark}
or @dfn{flag} the @dfn{current file} (that is, the file on the current
@findex wdired-change-to-wdired-mode
Wdired is a special mode that allows you to perform file operations
by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands
-for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q}
+for ``writable''.) To enter Wdired mode, type @kbd{C-x C-q}
(@code{dired-toggle-read-only}) while in a Dired buffer.
Alternatively, use the @samp{Immediate / Edit File Names} menu item.
You can also enter Image-Dired directly by typing @kbd{M-x
image-dired}. This prompts for a directory; specify one that has
image files. This creates thumbnails for all the images in that
-directory, and displays them all in the ``thumbnail buffer.'' This
+directory, and displays them all in the ``thumbnail buffer''. This
takes a long time if the directory contains many image files, and it
asks for confirmation if the number of image files exceeds
@code{image-dired-show-all-from-dir-max-files}.
The default comparison method (used if you type @key{RET} at the
prompt) is to compare just the file names---each file name that does
-not appear in the other directory is ``different.'' You can specify
+not appear in the other directory is ``different''. You can specify
more stringent comparisons by entering a Lisp expression, which can
refer to the variables @code{size1} and @code{size2}, the respective
file sizes; @code{mtime1} and @code{mtime2}, the last modification
@code{fa2}, the respective file attribute lists (as returned by the
function @code{file-attributes}). This expression is evaluated for
each pair of like-named files, and if the expression's value is
-non-@code{nil}, those files are considered ``different.''
+non-@code{nil}, those files are considered ``different''.
For instance, the sequence @code{M-x dired-compare-directories
@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this
@cindex synchronizing windows
@dfn{Follow mode} is a minor mode that makes two windows, both
-showing the same buffer, scroll as a single tall ``virtual window.''
+showing the same buffer, scroll as a single tall ``virtual window''.
To use Follow mode, go to a frame with just one window, split it into
two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x
follow-mode}. From then on, you can edit the buffer in either of the
line (@pxref{Continuation Lines}). When one line of text is split
into multiple screen lines, the left fringe shows a curving arrow for
each screen line except the first, indicating that ``this is not the
-real beginning.'' The right fringe shows a curving arrow for each
+real beginning''. The right fringe shows a curving arrow for each
screen line except the last, indicating that ``this is not the real
-end.'' If the line's direction is right-to-left (@pxref{Bidirectional
+end''. If the line's direction is right-to-left (@pxref{Bidirectional
Editing}), the meanings of the curving arrows in the fringes are
swapped.
The fringes indicate line truncation with short horizontal arrows
meaning ``there's more text on this line which is scrolled
-horizontally out of view.'' Clicking the mouse on one of the arrows
+horizontally out of view''. Clicking the mouse on one of the arrows
scrolls the display horizontally in the direction of the arrow.
The fringes can also indicate other things, such as buffer
If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
skip over differences in states ``prefer-A'' and ``prefer-B''
(@pxref{State of Difference}). Thus you see only differences for
-which neither version is presumed ``correct.'' The mode line
+which neither version is presumed ``correct''. The mode line
indicates Skip Prefers mode with @samp{S}. This mode is only relevant
when there is an ancestor.
When typing a file name into the minibuffer, you can make use of a
couple of shortcuts: a double slash is interpreted as ``ignore
-everything before the second slash in the pair,'' and @samp{~/} is
+everything before the second slash in the pair'', and @samp{~/} is
interpreted as your home directory. @xref{Minibuffer File}.
@cindex environment variables in file names
remains ``correct''. To disable automatic line number correction,
change the variable @code{diff-update-on-the-fly} to @code{nil}.
- Diff mode treats each hunk as an ``error message,'' similar to
+ Diff mode treats each hunk as an ``error message'', similar to
Compilation mode. Thus, you can use commands such as @kbd{C-x '} to
visit the corresponding source locations. @xref{Compilation Mode}.
@code{fortran-continuation-string} specifies what character to put in
column 5. A line that starts with a tab character followed by any digit
except @samp{0} is also a continuation line. We call this style of
-continuation @dfn{tab format}. (Fortran 90 introduced ``free form,''
+continuation @dfn{tab format}. (Fortran 90 introduced ``free form'',
with another style of continuation lines).
@vindex indent-tabs-mode @r{(Fortran mode)}
@item C-h c @var{key}
Show the name of the command that the key sequence @var{key} is bound
to (@code{describe-key-briefly}). Here @kbd{c} stands for
-``character.'' For more extensive information on @var{key}, use
+``character''. For more extensive information on @var{key}, use
@kbd{C-h k}.
@item C-h d @var{topics} @key{RET}
Display the commands and variables whose documentation matches
ring head immediately, just type @kbd{C-k}.
Note that Emacs treats the head of the macro ring as the ``last
-defined keyboard macro.'' For instance, @key{F4} will execute that
+defined keyboard macro''. For instance, @key{F4} will execute that
macro, and @kbd{C-x C-k n} will give it a name.
@vindex kmacro-ring-max
@cindex slashes repeated in file name
@findex file-name-shadow-mode
Emacs interprets a double slash as ``ignore everything before the
-second slash in the pair.'' In the example above,
+second slash in the pair''. In the example above,
@file{/u2/emacs/src/} is ignored, so the argument you supplied is
@file{/etc/termcap}. The ignored part of the file name is dimmed if
the terminal allows it. (To disable this dimming, turn off File Name
line mode, Term basically acts like Shell mode (@pxref{Shell Mode}).
In char mode, each character is sent directly to the subshell, as
-``terminal input.'' Any ``echoing'' of your input is the
+``terminal input''. Any ``echoing'' of your input is the
responsibility of the subshell. The sole exception is the terminal
escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
Any ``terminal output'' from the subshell goes into the buffer,
Insert a byte with a code typed in hex.
@item C-x [
-Move to the beginning of a 1k-byte ``page.''
+Move to the beginning of a 1k-byte ``page''.
@item C-x ]
-Move to the end of a 1k-byte ``page.''
+Move to the end of a 1k-byte ``page''.
@item M-g
Move to an address specified in hex.
However, this may be slow if there are a lot of buffers in the
desktop. You can specify the maximum number of buffers to restore
immediately with the variable @code{desktop-restore-eager}; the
-remaining buffers are restored ``lazily,'' when Emacs is idle.
+remaining buffers are restored ``lazily'', when Emacs is idle.
@findex desktop-clear
@vindex desktop-globals-to-clear
@cindex inferior processes under MS-DOS
@findex compile @r{(MS-DOS)}
@findex grep @r{(MS-DOS)}
- Because MS-DOS is a single-process ``operating system,''
+ Because MS-DOS is a single-process ``operating system'',
asynchronous subprocesses are not available. In particular, Shell
mode and its variants do not work. Most Emacs features that use
asynchronous subprocesses also don't work on MS-DOS, including
With no argument, it moves to a point underneath the next
``interesting'' character that follows whitespace in the previous
nonblank line. ``Next'' here means ``appearing at a horizontal position
-greater than the one point starts out at.'' With an argument, as in
+greater than the one point starts out at''. With an argument, as in
@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting
character in the current line. @kbd{M-@key{TAB}} does not change the
text; it only moves point. ``Interesting'' characters are defined by
for a file name.
If you use @kbd{C-h S} in a major mode that does not support it,
-it asks you to specify the ``symbol help mode.'' You should enter
+it asks you to specify the ``symbol help mode''. You should enter
a command such as @code{c-mode} that would select a major
mode which @kbd{C-h S} does support.
This section gives a brief description of the special features
available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
-(These are called ``C mode and related modes.'')
+(These are called ``C mode and related modes''.)
@ifinfo
@xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
@end ifinfo
Rmail attempts to locate the @code{movemail} program and determine its
version. There are two versions of the @code{movemail} program: the
native one, shipped with GNU Emacs (the ``emacs version'') and the one
-included in GNU mailutils (the ``mailutils version,''
+included in GNU mailutils (the ``mailutils version'',
@pxref{movemail,,,mailutils,GNU mailutils}). They support the same
command line syntax and the same basic subset of options. However, the
Mailutils version offers additional features.
After exiting a search, you can search for the same string again by
typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that
invokes incremental search, and the second @kbd{C-s} means ``search
-again.'' Similarly, @kbd{C-r C-r} searches backward for the last
+again''. Similarly, @kbd{C-r C-r} searches backward for the last
search string. In determining the last search string, it doesn't
matter whether the string was searched for with @kbd{C-s} or
@kbd{C-r}.
@samp{ff}.) Likewise, @samp{o} is a regular expression that matches
only @samp{o}. (When case distinctions are being ignored, these regexps
also match @samp{F} and @samp{O}, but we consider this a generalization
-of ``the same string,'' rather than an exception.)
+of ``the same string'', rather than an exception.)
Any two regular expressions @var{a} and @var{b} can be concatenated.
The result is a regular expression which matches a string if @var{a}
the beginning and end of the text matched by that construct. Then,
later on in the regular expression, you can use @samp{\} followed by the
digit @var{d} to mean ``match the same text matched the @var{d}th time
-by the @samp{\( @dots{} \)} construct.''
+by the @samp{\( @dots{} \)} construct''.
The strings matching the first nine @samp{\( @dots{} \)} constructs
appearing in a regular expression are assigned numbers 1 through 9 in
@samp{\&} in @var{newstring} stands for the entire match being
replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a
digit, stands for whatever matched the @var{d}th parenthesized
-grouping in @var{regexp}. (This is called a ``back reference.'')
+grouping in @var{regexp}. (This is called a ``back reference''.)
@samp{\#} refers to the count of replacements already made in this
command, as a decimal number. In the first replacement, @samp{\#}
stands for @samp{0}; in the second, for @samp{1}; and so on. For
would need to provide all that information. You should not assume
that the problem is due to the size of the file and say, ``I visited a
large file, and Emacs displayed @samp{I feel pretty today}.'' This is
-what we mean by ``guessing explanations.'' The problem might be due
+what we mean by ``guessing explanations''. The problem might be due
to the fact that there is a @samp{z} in the file name. If this is so,
then when we got your report, we would try out the problem with some
-``large file,'' probably with no @samp{z} in its name, and not see any
+``large file'', probably with no @samp{z} in its name, and not see any
problem. There is no way we could guess that we should try visiting a
file with a @samp{z} in its name.
You should not even say ``visit a file'' instead of @kbd{C-x C-f}.
Similarly, rather than saying ``if I have three characters on the
-line,'' say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if
+line'', say ``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if
that is the way you entered the text.
If possible, try quickly to reproduce the bug by invoking Emacs with
@item
A description of what behavior you observe that you believe is
-incorrect. For example, ``The Emacs process gets a fatal signal,'' or,
+incorrect. For example, ``The Emacs process gets a fatal signal'', or,
``The resulting text is as follows, which I think is wrong.''
Of course, if the bug is that Emacs gets a fatal signal, then one can't
are available in the file @file{etc/DEBUG} in the Emacs distribution.
That file also includes instructions for investigating problems
whereby Emacs stops responding (many people assume that Emacs is
-``hung,'' whereas in fact it might be in an infinite loop).
+``hung'', whereas in fact it might be in an infinite loop).
To find the file @file{etc/DEBUG} in your Emacs installation, use the
directory name stored in the variable @code{data-directory}.
@kindex C-x o
@findex other-window
With the keyboard, you can switch windows by typing @kbd{C-x o}
-(@code{other-window}). That is an @kbd{o}, for ``other,'' not a zero.
+(@code{other-window}). That is an @kbd{o}, for ``other'', not a zero.
When there are more than two windows, this command moves through all the
windows in a cyclic order, generally top to bottom and left to right.
After the rightmost and bottommost window, it goes back to the one at
The Windmove package defines commands for moving directionally
between neighboring windows in a frame. @kbd{M-x windmove-right}
selects the window immediately to the right of the currently selected
-one, and similarly for the ``left,'' ``up,'' and ``down''
+one, and similarly for the ``left'', ``up'', and ``down''
counterparts. @kbd{M-x windmove-default-keybindings} binds these
commands to @kbd{S-right} etc.; doing so disables shift selection for
those keys (@pxref{Shift Selection}).
+2012-04-26 Glenn Morris <rgm@gnu.org>
+
+ * buffers.texi, commands.texi, compile.texi, control.texi:
+ * customize.texi, display.texi, eval.texi, files.texi, frames.texi:
+ * hash.texi, help.texi, intro.texi, keymaps.texi, lists.texi:
+ * modes.texi, numbers.texi, objects.texi, streams.texi:
+ * symbols.texi, syntax.texi, text.texi, tips.texi, variables.texi:
+ Use Texinfo recommended convention for quotes+punctuation.
+
2012-04-23 Chong Yidong <cyd@gnu.org>
* keymaps.texi (Scanning Keymaps): Fix description of NO-REMAP arg
use.
If @var{filename} is @code{nil} or the empty string, that stands for
-``no visited file.'' In this case, @code{set-visited-file-name} marks
+``no visited file''. In this case, @code{set-visited-file-name} marks
the buffer as having no visited file, without changing the buffer's
modified flag.
message when called from a keyboard macro.
The above method with the additional argument is usually best,
-because it allows callers to say ``treat this call as interactive.''
+because it allows callers to say ``treat this call as interactive''.
But you can also do the job by testing @code{called-interactively-p}.
@defun called-interactively-p kind
button and modifier keys. The information about the window part is kept
elsewhere in the event---in the coordinates. But
@code{read-key-sequence} translates this information into imaginary
-``prefix keys,'' all of which are symbols: @code{header-line},
+``prefix keys'', all of which are symbols: @code{header-line},
@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
@code{vertical-line}, and @code{vertical-scroll-bar}. You can define
meanings for mouse clicks in special window parts by defining key
@defvar unread-command-char
This variable holds a character to be read as command input.
-A value of -1 means ``empty.''
+A value of -1 means ``empty''.
This variable is mostly obsolete now that you can use
@code{unread-command-events} instead; it exists only to support programs
change the major mode of the current buffer temporarily to a special
major mode, which should have a command to go back to the previous mode.
(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
-give the user different text to edit ``recursively,'' create and select
+give the user different text to edit ``recursively'', create and select
a new buffer in a special mode. In this mode, define a command to
complete the processing and go back to the previous buffer. (The
@kbd{m} command in Rmail does this.)
use a special Lisp reader construct, @samp{#@@@var{count}}. This
construct skips the next @var{count} characters. It also uses the
@samp{#$} construct, which stands for ``the name of this file, as a
-string.'' It is usually best not to use these constructs in Lisp source
+string''. It is usually best not to use these constructs in Lisp source
files, since they are not designed to be clear to humans reading the
file.
@var{body-forms}, and the value of the last of @var{body-forms} becomes
the value of the @code{cond}. The remaining clauses are ignored.
-If the value of @var{condition} is @code{nil}, the clause ``fails,'' so
+If the value of @var{condition} is @code{nil}, the clause ``fails'', so
the @code{cond} moves on to the following clause, trying its
@var{condition}.
@subsection Examples of @code{catch} and @code{throw}
One way to use @code{catch} and @code{throw} is to exit from a doubly
-nested loop. (In most languages, this would be done with a ``goto.'')
+nested loop. (In most languages, this would be done with a ``goto''.)
Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
varying from 0 to 9:
@noindent
describes a variable for which @code{t} means yes, @code{nil} means no,
-and @code{foo} means ``ask.''
+and @code{foo} means ``ask''.
@item (other @var{value})
This alternative can match any Lisp value, but if the user chooses this
@noindent
describes a variable for which @code{t} means yes, @code{nil} means no,
-and anything else means ``ask.'' If the user chooses @samp{Ask} from
+and anything else means ``ask''. If the user chooses @samp{Ask} from
the menu of alternatives, that specifies the value @code{foo}; but any
other value (not @code{t}, @code{nil} or @code{foo}) displays as
@samp{Ask}, just like @code{foo}.
indicate truncated and continued lines (@pxref{Fringes}). On a text
terminal, a @samp{$} in the rightmost column of the window indicates
truncation; a @samp{\} on the rightmost column indicates a line that
-``wraps.'' (The display table can specify alternate characters to use
+``wraps''. (The display table can specify alternate characters to use
for this; @pxref{Display Tables}).
@defopt truncate-lines
echo area.
You should always call this function and not hope for
-@code{progress-reporter-update} to print ``100%.'' Firstly, it may
+@code{progress-reporter-update} to print ``100%''. Firstly, it may
never print it, there are many good reasons for this not to happen.
Secondly, ``done'' is more explicit.
@end defun
This is the only valid way to change the endpoints of an overlay. Do
not try modifying the markers in the overlay by hand, as that fails to
update other vital data structures and can cause some overlays to be
-``lost.''
+``lost''.
@end defun
@defun remove-overlays &optional start end name value
@end example
Emacs stores the overlays of each buffer in two lists, divided
-around an arbitrary ``center position.'' One list extends backwards
+around an arbitrary ``center position''. One list extends backwards
through the buffer from that center position, and the other extends
forwards from that center position. The center position can be anywhere
in the buffer.
@end ifnottex
@item disabled
-Specifies transforming the image so that it looks ``disabled.''
+Specifies transforming the image so that it looks ``disabled''.
@end table
@item :mask @var{mask}
@subsection Abstract Display Example
Here is a simple example using functions of the ewoc package to
-implement a ``color components display,'' an area in a buffer that
+implement a ``color components display'', an area in a buffer that
represents a vector of three integers (itself representing a 24-bit RGB
value) in various ways.
@strong{Warning:} if you use the display table to change the display
of newline characters, the whole buffer will be displayed as one long
-``line.''
+``line''.
The display table also has six ``extra slots'' which serve special
purposes. Here is a table of their meanings; @code{nil} in any slot
@defvar ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ``ring the
-bell.'' Its value should be a function of no arguments. If this is
+bell''. Its value should be a function of no arguments. If this is
non-@code{nil}, it takes precedence over the @code{visible-bell}
variable.
@end defvar
@section Window Systems
Emacs works with several window systems, most notably the X Window
-System. Both Emacs and X use the term ``window,'' but use it
+System. Both Emacs and X use the term ``window'', but use it
differently. An Emacs frame is a single window as far as X is
concerned; the individual Emacs windows are not known to X at all.
@dfn{form} (or an @dfn{expression}). How Emacs evaluates a form
depends on its data type. Emacs has three different kinds of form
that are evaluated differently: symbols, lists, and ``all other
-types.'' This section describes all three kinds, one by one, starting
+types''. This section describes all three kinds, one by one, starting
with the ``all other types'' which are self-evaluating forms.
@menu
In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa. Indeed, we say,
-``I am editing a file,'' rather than, ``I am editing a buffer that I
-will soon save as a file of the same name.'' Humans do not usually need
+``I am editing a file'', rather than, ``I am editing a buffer that I
+will soon save as a file of the same name''. Humans do not usually need
to make the distinction explicit. When dealing with a computer program,
however, it is good to keep the distinction in mind.
stored in the same directory as the file you are editing.
When you access files using NFS, there may be a small probability that
-you and another user will both lock the same file ``simultaneously.''
+you and another user will both lock the same file ``simultaneously''.
If this happens, it is possible for the two users to make changes
simultaneously, but Emacs will still warn the user who saves second.
Also, the detection of modification of a buffer visiting a file changed
@end defun
@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension,'' if any,
+This function returns @var{filename}'s final ``extension'', if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part. The extension, in a file name, is the part that
follows the last @samp{.} in the last name component (minus any
possibly others to be added in the future. It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
-operation ``in the usual way.'' It should always reinvoke the primitive
+operation ``in the usual way''. It should always reinvoke the primitive
for an operation it does not recognize. Here's one way to do this:
@smallexample
form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
type equals @var{on-state} (comparing using @code{equal}), the
corresponding @var{off-state} specifies what the cursor looks like
-when it blinks ``off.'' Both @var{on-state} and @var{off-state}
+when it blinks ``off''. Both @var{on-state} and @var{off-state}
should be suitable values for the @code{cursor-type} frame parameter.
There are various defaults for how to blink each type of cursor, if
Most window systems use a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest.'' Where two windows overlap, the one higher up covers
+to ``lowest''. Where two windows overlap, the one higher up covers
the one underneath. Even a window at the bottom of the stack can be
seen if no other window overlaps it.
@cindex lowering a frame
A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. @dfn{Raising} a window means moving
-it ``up,'' to the top of the stack. @dfn{Lowering} a window means
+it ``up'', to the top of the stack. @dfn{Lowering} a window means
moving it to the bottom of the stack. This motion is in the notional
third dimension only, and does not change the position of the window
on the screen.
A dialog box is a variant of a pop-up menu---it looks a little
different, it always appears in the center of a frame, and it has just
one level and one or more buttons. The main use of dialog boxes is
-for asking questions that the user can answer with ``yes,'' ``no,''
+for asking questions that the user can answer with ``yes'', ``no'',
and a few other alternatives. With a single button, they can also
force the user to acknowledge important information. The functions
@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
These functions provide a way to determine which color names are
valid, and what they look like. In some cases, the value depends on the
@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
-meaning of the term ``selected frame.''
+meaning of the term ``selected frame''.
To read user input of color names with completion, use
@code{read-color} (@pxref{High-Level Completion, read-color}).
server.
When the developers of X labeled software distributors as
-``vendors,'' they showed their false assumption that no system could
+``vendors'', they showed their false assumption that no system could
ever be developed and distributed noncommercially.
@end defun
Keys which are numbers are ``the same'' if they are @code{equal}, that
is, if they are equal in value and either both are integers or both
are floating point numbers; otherwise, two distinct objects are never
-``the same.''
+``the same''.
@item eq
Any two distinct Lisp objects are ``different'' as keys.
@item equal
-Two Lisp objects are ``the same,'' as keys, if they are equal
+Two Lisp objects are ``the same'', as keys, if they are equal
according to @code{equal}.
@end table
The default size is 65.
@item :rehash-size @var{rehash-size}
-When you add an association to a hash table and the table is ``full,''
+When you add an association to a hash table and the table is ``full'',
it grows automatically. This value specifies how to make the hash table
larger, at that time.
a ``hash code'' from a key value.
The function @var{test-fn} should accept two arguments, two keys, and
-return non-@code{nil} if they are considered ``the same.''
+return non-@code{nil} if they are considered ``the same''.
The function @var{hash-fn} should accept one argument, a key, and return
an integer that is the ``hash code'' of that key. For good results, the
@defopt help-event-list
The value of this variable is a list of event types that serve as
-alternative ``help characters.'' These events are handled just like the
+alternative ``help characters''. These events are handled just like the
event specified by @code{help-char}.
@end defopt
representations of Lisp objects into actual Lisp objects, and vice
versa. @xref{Printed Representation}, for more details. You, the
person reading this manual, are thought of as ``the programmer'' and are
-addressed as ``you.'' ``The user'' is the person who uses Lisp
+addressed as ``you''. ``The user'' is the person who uses Lisp
programs, including those you write.
@cindex typographic conventions
@end example
@noindent
-You can read this as ``@code{(car '(1 2))} evaluates to 1.''
+You can read this as ``@code{(car '(1 2))} evaluates to 1''.
When a form is a macro call, it expands into a new form for Lisp to
evaluate. We show the result of the expansion with
This feature permits you to define one key as an alias for another key.
For example, an entry whose @sc{car} is the keymap called @code{esc-map}
and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
-binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
+binding of @kbd{Meta-@key{SPC}}, whatever that may be''.
@end itemize
@item @var{symbol}
which toggles the variable @code{debug-on-error}.
@dfn{Radio buttons} are a group of menu items, in which at any time one
-and only one is ``selected.'' There should be a variable whose value
+and only one is ``selected''. There should be a variable whose value
says which one is selected at any time. The @var{selected} form for
each radio button in the group should check whether the variable has the
right value for selecting that button. Clicking on the button should
Note the symbols which the bindings are ``made for''; these appear
inside square brackets, in the key sequence being defined. In some
cases, this symbol is the same as the command name; sometimes it is
-different. These symbols are treated as ``function keys,'' but they are
+different. These symbols are treated as ``function keys'', but they are
not real function keys on the keyboard. They do not affect the
functioning of the menu itself, but they are ``echoed'' in the echo area
when the user selects from the menu, and they appear in the output of
and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object. One
slot is known as the @sc{car}, and the other is known as the @sc{cdr}.
(These names are traditional; see @ref{Cons Cell Type}.) @sc{cdr} is
-pronounced ``could-er.''
+pronounced ``could-er''.
We say that ``the @sc{car} of this cons cell is'' whatever object
its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
- A list is a series of cons cells ``chained together,'' so that each
+ A list is a series of cons cells ``chained together'', so that each
cell refers to the next one. There is one cons cell for each element
of the list. By convention, the @sc{car}s of the cons cells hold the
elements of the list, and the @sc{cdr}s are used to chain the list
@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
each @var{alist} association instead of the @sc{car}. You can think of
-this as ``reverse @code{assoc},'' finding the key for a given value.
+this as ``reverse @code{assoc}'', finding the key for a given value.
@end defun
@defun assq key alist
@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
each @var{alist} association instead of the @sc{car}. You can think of
-this as ``reverse @code{assq},'' finding the key for a given value.
+this as ``reverse @code{assq}'', finding the key for a given value.
For example:
A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
-be some kind of ``moving forward and backward,'' but this does not
+be some kind of ``moving forward and backward'', but this does not
necessarily mean cursor motion.
It is legitimate for a major mode to rebind a standard key sequence if
When you defined a major mode using @code{define-derived-mode}, it
automatically makes sure these conventions are followed. If you
-define a major mode ``by hand,'' not using @code{define-derived-mode},
+define a major mode ``by hand'', not using @code{define-derived-mode},
use the following functions to handle these conventions automatically.
@defun run-mode-hooks &rest hookvars
The argument @var{comment-list} is a list in which each element is
either a character, a string of one or two characters, or a cons cell.
A character or a string is set up in the mode's syntax table as a
-``comment starter.'' If the entry is a cons cell, the @sc{car} is set
-up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
+``comment starter''. If the entry is a cons cell, the @sc{car} is set
+up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''.
(Use @code{nil} for the latter if you want comments to end at the end
of the line.) Note that the syntax table mechanism has limitations
about what comment starters and enders are actually possible.
@end smallexample
@noindent
-This defines a minor mode named ``Hungry mode,'' a command named
+This defines a minor mode named ``Hungry mode'', a command named
@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
which indicates whether the mode is enabled, and a variable named
@code{hungry-mode-map} which holds the keymap that is active when the
sequence of @dfn{bits} (digits which are either zero or one). A bitwise
operation acts on the individual bits of such a sequence. For example,
@dfn{shifting} moves the whole sequence left or right one or more places,
-reproducing the same pattern ``moved over.''
+reproducing the same pattern ``moved over''.
The bitwise operations in Emacs Lisp apply only to integers.
@cindex atoms
Because cons cells are so central to Lisp, we also have a word for
-``an object which is not a cons cell.'' These objects are called
+``an object which is not a cons cell''. These objects are called
@dfn{atoms}.
@cindex parenthesis
A @dfn{primitive function} is a function callable from Lisp but
written in the C programming language. Primitive functions are also
called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
-derived from ``subroutine.'') Most primitive functions evaluate all
+derived from ``subroutine''.) Most primitive functions evaluate all
their arguments when they are called. A primitive function that does
not evaluate all its arguments is called a @dfn{special form}
(@pxref{Special Forms}).@refill
should save the argument and arrange to return it on the next call.
This is called @dfn{unreading} the character; it happens when the Lisp
reader reads one character too many and wants to ``put it back where it
-came from.'' In this case, it makes no difference what value
+came from''. In this case, it makes no difference what value
@var{function} returns.
@end itemize
@defun terpri &optional stream
@cindex newline in print
This function outputs a newline to @var{stream}. The name stands
-for ``terminate print.''
+for ``terminate print''.
@end defun
@defun write-char character &optional stream
@code{defun} defines a symbol as a function, creating a lambda
expression and storing it in the function cell of the symbol. This
lambda expression thus becomes the function definition of the symbol.
-(The term ``function definition,'' meaning the contents of the function
+(The term ``function definition'', meaning the contents of the function
cell, is derived from the idea that @code{defun} gives the symbol its
definition as a function.) @code{defsubst} and @code{defalias} are two
other ways of defining a function. @xref{Functions}.
A syntax table can inherit the data for some characters from the
standard syntax table, while specifying other characters itself. The
``inherit'' syntax class means ``inherit this character's syntax from
-the standard syntax table.'' Just changing the standard syntax for a
+the standard syntax table''. Just changing the standard syntax for a
character affects all syntax tables that inherit from it.
@defun syntax-table-p object
A character's syntax controls how it changes the state of the
parser, rather than describing the state itself. For example, a
string delimiter character toggles the parser state between
-``in-string'' and ``in-code,'' but the syntax of characters does not
+``in-string'' and ``in-code'', but the syntax of characters does not
directly say whether they are inside a string. For example (note that
15 is the syntax code for generic string delimiters),
asking for any confirmation. It returns @code{nil}.
Normally, deleting a large amount of text from a buffer inhibits further
-auto-saving of that buffer ``because it has shrunk.'' However,
+auto-saving of that buffer ``because it has shrunk''. However,
@code{erase-buffer} does not do this, the idea being that the future
text is not really related to the former text, and its size should not
be compared with that of the former text.
Some people think this use of the word ``kill'' is unfortunate, since
it refers to operations that specifically @emph{do not} destroy the
-entities ``killed.'' This is in sharp contrast to ordinary life, in
+entities ``killed''. This is in sharp contrast to ordinary life, in
which death is permanent and ``killed'' entities do not come back to
life. Therefore, other metaphors have been proposed. For example, the
term ``cut ring'' makes sense to people who, in pre-computer days, used
For yanking, one entry in the kill ring is designated the ``front'' of
the ring. Some yank commands ``rotate'' the ring by designating a
-different element as the ``front.'' But this virtual rotation doesn't
+different element as the ``front''. But this virtual rotation doesn't
change the list itself---the most recent entry always comes first in the
list.
@code{nil} or a function of no arguments.
If the value is a function, @code{current-kill} calls it to get the
-``most recent kill.'' If the function returns a non-@code{nil} value,
-then that value is used as the ``most recent kill.'' If it returns
+``most recent kill''. If the function returns a non-@code{nil} value,
+then that value is used as the ``most recent kill''. If it returns
@code{nil}, then the front of the kill ring is used.
To facilitate support for window systems that support multiple
If this variable's value is non-@code{nil}, it is a symbol which is used
as a text property name. A non-@code{nil} value for that text property
means, ``the other text properties for this character have already been
-computed.''
+computed''.
If all the characters in the range specified for @code{buffer-substring}
have a non-@code{nil} value for this property, @code{buffer-substring}
@var{new-pos} can be anywhere in the two adjacent fields.
Additionally, if two fields are separated by another field with the
special value @code{boundary}, then any point within this special
-field is also considered to be ``on the boundary.''
+field is also considered to be ``on the boundary''.
Commands like @kbd{C-a} with no argument, that normally move backward
to a specific kind of location and stay there once there, probably
@item
Never change the case of a Lisp symbol when you mention it in a doc
-string. If the symbol's name is @code{foo}, write ``foo,'' not
+string. If the symbol's name is @code{foo}, write ``foo'', not
``Foo'' (which is a different symbol).
This might appear to contradict the policy of writing function
@item
The documentation string for a function that is a yes-or-no predicate
-should start with words such as ``Return t if,'' to indicate
-explicitly what constitutes ``truth.'' The word ``return'' avoids
-starting the sentence with lower-case ``t,'' which could be somewhat
+should start with words such as ``Return t if'', to indicate
+explicitly what constitutes ``truth''. The word ``return'' avoids
+starting the sentence with lower-case ``t'', which could be somewhat
distracting.
@item
@item
Avoid using the word ``cause'' (or its equivalents) unnecessarily.
-Instead of, ``Cause Emacs to display text in boldface,'' write just
-``Display text in boldface.''
+Instead of, ``Cause Emacs to display text in boldface'', write just
+``Display text in boldface''.
@item
Avoid using ``iff'' (a mathematics term meaning ``if and only if''),
@item
The documentation string for a variable that is a yes-or-no flag should
-start with words such as ``Non-nil means,'' to make it clear that
+start with words such as ``Non-nil means'', to make it clear that
all non-@code{nil} values are equivalent and indicate explicitly what
@code{nil} and non-@code{nil} mean.
@end itemize
@code{setq} does not evaluate @var{symbol}; it sets the symbol that you
write. We say that this argument is @dfn{automatically quoted}. The
-@samp{q} in @code{setq} stands for ``quoted.''
+@samp{q} in @code{setq} stands for ``quoted''.
The value of the @code{setq} form is the value of the last @var{form}.