diff options
author | Paul Eggert <eggert@cs.ucla.edu> | 2015-09-15 08:46:48 -0700 |
---|---|---|
committer | Paul Eggert <eggert@cs.ucla.edu> | 2015-09-15 08:48:44 -0700 |
commit | ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e (patch) | |
tree | 5b1d35e609ce4481816662709ac677db1468495b /doc/lispref | |
parent | c051487fcf379febf4ce5b38de7017609c84a106 (diff) | |
download | emacs-ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.tar.gz emacs-ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.tar.bz2 emacs-ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.zip |
Quote less in manuals
The manuals often used quotes ``...'' when it is better to use @dfn or
@code or capitalized words or no quoting at all. For example, there is
no need for the `` and '' in “if a variable has one effect for
@code{nil} values and another effect for ``non-@code{nil}'' values”.
Reword the Emacs, Lisp intro, and Lisp reference manuals to eliminate
unnecessary quoting like this, and to use @dfn etc. instead when called
for (Bug#21472).
Diffstat (limited to 'doc/lispref')
47 files changed, 482 insertions, 473 deletions
diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index 998f63ef279..bcbea87c04d 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -134,7 +134,7 @@ abbrev in an abbrev table. When a major mode defines a system abbrev, it should call @code{define-abbrev} and specify @code{t} for the @code{:system} -property. Be aware that any saved non-``system'' abbrevs are restored +property. Be aware that any saved non-system abbrevs are restored at startup, i.e., before some major modes are loaded. Therefore, major modes should not assume that their abbrev tables are empty when they are first loaded. @@ -145,13 +145,13 @@ This function defines an abbrev named @var{name}, in with properties @var{props} (@pxref{Abbrev Properties}). The return value is @var{name}. The @code{:system} property in @var{props} is treated specially here: if it has the value @code{force}, then it will -overwrite an existing definition even for a non-``system'' abbrev of +overwrite an existing definition even for a non-system abbrev of the same name. @var{name} should be a string. The argument @var{expansion} is normally the desired expansion (a string), or @code{nil} to undefine the abbrev. If it is anything but a string or @code{nil}, then the -abbreviation ``expands'' solely by running @var{hook}. +abbreviation expands solely by running @var{hook}. The argument @var{hook} is a function or @code{nil}. If @var{hook} is non-@code{nil}, then it is called with no arguments after the abbrev is diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi index 2784fd9b3b1..2fc43da8e53 100644 --- a/doc/lispref/anti.texi +++ b/doc/lispref/anti.texi @@ -66,7 +66,7 @@ Internal windows are no longer visible to Lisp; functions such as and window-local buffer lists have all been removed. Functions for resizing windows can delete windows if they become too small. -The ``action function'' feature for controlling buffer display has +The action-function feature for controlling buffer display has been removed, including @code{display-buffer-overriding-action} and related variables, as well as the @var{action} argument to @code{display-buffer} and other functions. The way to @@ -78,7 +78,7 @@ other variables. The standard completion interface has been simplified, eliminating the @code{completion-extra-properties} variable, the @code{metadata} action flag for completion functions, and the concept of -``completion categories''. Lisp programmers may now find the choice +completion categories. Lisp programmers may now find the choice of methods for tuning completion less bewildering, but if a package finds the streamlined interface insufficient for its needs, it must implement its own specialized completion feature. diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi index 3433277ca0f..c4f2b5eb852 100644 --- a/doc/lispref/back.texi +++ b/doc/lispref/back.texi @@ -17,7 +17,7 @@ Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming +than a mere extension language; it is a full computer programming language in its own right. You can use it as you would any other programming language. diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index 0a1b5a24e4f..d37df25d267 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -398,7 +398,7 @@ those versions by excluding them from the @sc{cdr} of the value. @xref{Numbered Backups}. In this example, the value says that @file{~rms/foo.~5~} is the name -to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' +to use for the new backup file, and @file{~rms/foo.~3~} is an excess version that the caller should consider deleting now. @smallexample diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 71261e08db7..45a21c8e806 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -23,7 +23,7 @@ not be displayed in any windows. * Buffer File Name:: The buffer file name indicates which file is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. + behind Emacs's back. * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. * Buffer List:: How to look at all the existing buffers. * Creating Buffers:: Functions that create buffers. @@ -893,7 +893,7 @@ another buffer is shown in it. More precisely, if the selected window is dedicated (@pxref{Dedicated Windows}) and there are other windows on its frame, the window is deleted. If it is the only window on its frame and that frame is not the only frame on its terminal, the frame is -``dismissed'' by calling the function specified by +dismissed by calling the function specified by @code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise, it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show another buffer in that window. If @var{buffer-or-name} is displayed in @@ -1032,7 +1032,7 @@ memory for other uses or to be returned to the operating system. If buffer. Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} (``hangup'') signal, which normally causes them +sent the @code{SIGHUP} (hangup) signal, which normally causes them to terminate. @xref{Signals to Processes}. If the buffer is visiting a file and contains unsaved changes, @@ -1139,7 +1139,7 @@ be a live buffer or the name (a string) of an existing buffer. If @var{name} is the name of an existing buffer, an error is signaled. If @var{clone} is non-@code{nil}, then the indirect buffer originally -shares the ``state'' of @var{base-buffer} such as major mode, minor +shares the state of @var{base-buffer} such as major mode, minor modes, buffer local variables and so on. If @var{clone} is omitted or @code{nil} the indirect buffer's state is set to the default state for new buffers. diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 593054013e6..8642f6ae956 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -132,7 +132,7 @@ byte compiler to warn if the command is called from Lisp. The output of @code{describe-function} will include similar information. The value of the property can be: a string, which the byte-compiler will use directly in its warning (it should end with a period, and not -start with a capital, e.g., ``use @dots{} instead.''); @code{t}; any +start with a capital, e.g., @code{"use (system-name) instead."}); @code{t}; any other symbol, which should be an alternative function to use in Lisp code. @@ -1557,8 +1557,8 @@ the command binding of the double click event to assume that the single-click command has already run. It must produce the desired results of a double click, starting from the results of a single click. -This is convenient, if the meaning of a double click somehow ``builds -on'' the meaning of a single click---which is recommended user interface +This is convenient, if the meaning of a double click somehow builds +on the meaning of a single click---which is recommended user interface design practice for double clicks. If you click a button, then press it down again and start moving the @@ -2444,7 +2444,7 @@ same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event---in the coordinates. But @code{read-key-sequence} translates this information into imaginary -``prefix keys'', all of which are symbols: @code{header-line}, +prefix keys, all of which are symbols: @code{header-line}, @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, @code{vertical-line}, and @code{vertical-scroll-bar}. You can define meanings for mouse clicks in special window parts by defining key @@ -2587,7 +2587,7 @@ If you wish to read a single key taking these translations into account, use the function @code{read-key}: @defun read-key &optional prompt -This function reads a single key. It is ``intermediate'' between +This function reads a single key. It is intermediate between @code{read-key-sequence} and @code{read-event}. Unlike the former, it reads a single key, not a key sequence. Unlike the latter, it does not return a raw event, but decodes and translates the user input @@ -2621,7 +2621,7 @@ then continues to wait for a valid input character, or keyboard-quit. from @code{read-event}. @defvar extra-keyboard-modifiers -This variable lets Lisp programs ``press'' the modifier keys on the +This variable lets Lisp programs press the modifier keys on the keyboard. The value is a character. Only the modifiers of the character matter. Each time the user types a keyboard key, it is altered as if those modifier keys were held down. For instance, if @@ -2633,7 +2633,7 @@ character for this purpose, but as a character with no modifiers. Thus, setting @code{extra-keyboard-modifiers} to zero cancels any modification. -When using a window system, the program can ``press'' any of the +When using a window system, the program can press any of the modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can be virtually pressed. @@ -2783,7 +2783,7 @@ What character @kbd{1 7 7}- @node Event Input Misc @subsection Miscellaneous Event Input Features -This section describes how to ``peek ahead'' at events without using +This section describes how to peek ahead at events without using them up, how to check for pending input, and how to discard pending input. See also the function @code{read-passwd} (@pxref{Reading a Password}). @@ -3048,7 +3048,7 @@ usual result of this---a quit---is prevented. Eventually, binding is unwound at the end of a @code{let} form. At that time, if @code{quit-flag} is still non-@code{nil}, the requested quit happens immediately. This behavior is ideal when you wish to make sure that -quitting does not happen within a ``critical section'' of the program. +quitting does not happen within a critical section of the program. @cindex @code{read-quoted-char} quitting In some functions (such as @code{read-quoted-char}), @kbd{C-g} is @@ -3311,7 +3311,7 @@ using the minibuffer. Usually it is more convenient for the user if you change the major mode of the current buffer temporarily to a special major mode, which should have a command to go back to the previous mode. (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively'', create and select +give the user different text to edit recursively, create and select a new buffer in a special mode. In this mode, define a command to complete the processing and go back to the previous buffer. (The @kbd{m} command in Rmail does this.) diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 4a246dd6b92..8c23086e8d1 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -140,7 +140,7 @@ definition of @var{symbol} (@pxref{Byte-Code Objects}). If @var{symbol}'s definition is a byte-code function object, @code{byte-compile} does nothing and returns @code{nil}. It does not -``compile the symbol's definition again'', since the original +compile the symbol's definition again, since the original (non-compiled) code has already been replaced in the symbol's function cell by the byte-compiled code. @@ -242,7 +242,7 @@ $ emacs -batch -f batch-byte-compile *.el When Emacs loads functions and variables from a byte-compiled file, it normally does not load their documentation strings into memory. -Each documentation string is ``dynamically'' loaded from the +Each documentation string is dynamically loaded from the byte-compiled file only when needed. This saves memory, and speeds up loading by skipping the processing of the documentation strings. @@ -280,7 +280,7 @@ Internally, the dynamic loading of documentation strings is accomplished by writing compiled files with a special Lisp reader construct, @samp{#@@@var{count}}. This construct skips the next @var{count} characters. It also uses the @samp{#$} construct, which -stands for ``the name of this file, as a string''. Do not use these +stands for the name of this file, as a string. Do not use these constructs in Lisp source files; they are not designed to be clear to humans reading the file. diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 421f5cc530f..fca16da5d3f 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -73,7 +73,7 @@ The value of the last form in the body becomes the value of the entire two or more forms in succession and use the value of the last of them. But programmers found they often needed to use a @code{progn} in the body of a function, where (at that time) only one form was allowed. So -the body of a function was made into an ``implicit @code{progn}'': +the body of a function was made into an implicit @code{progn}: several forms are allowed just as in the body of an actual @code{progn}. Many other control structures likewise contain an implicit @code{progn}. As a result, @code{progn} is not used as much as it was many years ago. @@ -220,11 +220,11 @@ list is the @var{condition}; the remaining elements, if any, the @code{cond} tries the clauses in textual order, by evaluating the @var{condition} of each clause. If the value of @var{condition} is -non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its +non-@code{nil}, the clause succeeds; then @code{cond} evaluates its @var{body-forms}, and returns the value of the last of @var{body-forms}. Any remaining clauses are ignored. -If the value of @var{condition} is @code{nil}, the clause ``fails'', so +If the value of @var{condition} is @code{nil}, the clause fails, so the @code{cond} moves on to the following clause, trying its @var{condition}. A clause may also look like this: @@ -571,7 +571,7 @@ The value of a @code{while} form is always @code{nil}. @end group @end example -To write a ``repeat...until'' loop, which will execute something on each +To write a repeat-until loop, which will execute something on each iteration and then do the end-test, put the body followed by the end-test in a @code{progn} as the first argument of @code{while}, as shown here: @@ -673,7 +673,7 @@ the iterator's final value. It's important to note that generator function bodies only execute inside calls to @code{iter-next}. A call to a function defined with -@code{iter-defun} produces an iterator; you must ``drive'' this +@code{iter-defun} produces an iterator; you must drive this iterator with @code{iter-next} for anything interesting to happen. Each call to a generator function produces a @emph{different} iterator, each with its own state. @@ -858,7 +858,7 @@ error is signaled with data @code{(@var{tag} @var{value})}. @subsection Examples of @code{catch} and @code{throw} One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``goto''.) +nested loop. (In most languages, this would be done with a @code{goto}.) Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} varying from 0 to 9: @@ -972,7 +972,7 @@ returns to a point that is set up to handle the error (@pxref{Processing of Errors}). Here we describe how to signal an error. - Most errors are signaled ``automatically'' within Lisp primitives + Most errors are signaled automatically within Lisp primitives which you call for other purposes, such as if you try to take the @sc{car} of an integer or move forward a character at the end of the buffer. You can also signal errors explicitly with the functions diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index f984dbe5870..51d729f665c 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -365,7 +365,7 @@ should describe how to do the same job in hand-written Lisp code. Specify @var{getfunction} as the way to extract the value of this option. The function @var{getfunction} should take one argument, a symbol, and should return whatever customize should use as the -``current value'' for that symbol (which need not be the symbol's Lisp +current value for that symbol (which need not be the symbol's Lisp value). The default is @code{default-value}. You have to really understand the workings of Custom to use @@ -441,7 +441,7 @@ those other variables already have their intended values. @end table It is useful to specify the @code{:require} keyword for an option -that ``turns on'' a certain feature. This causes Emacs to load the +that turns on a certain feature. This causes Emacs to load the feature, if it is not already loaded, whenever the option is set. @xref{Common Keywords}. Here is an example, from the library @file{saveplace.el}: @@ -723,7 +723,7 @@ simply atoms, which stand for themselves. For example: @end example @noindent -specifies that there are three ``known'' keys, namely @code{"foo"}, +specifies that there are three known keys, namely @code{"foo"}, @code{"bar"} and @code{"baz"}, which will always be shown first. You may want to restrict the value type for specific keys, for @@ -842,7 +842,7 @@ symbols, and symbols are not treated like other Lisp expressions. @item (radio @var{element-types}@dots{}) This is similar to @code{choice}, except that the choices are displayed -using ``radio buttons'' rather than a menu. This has the advantage of +using radio buttons rather than a menu. This has the advantage of displaying documentation for the choices when applicable and so is often a good choice for a choice between constant functions (@code{function-item} customization types). @@ -1378,8 +1378,8 @@ the theme; this is the description shown when the user invokes the Themes*} buffer. Two special theme names are disallowed (using them causes an error): -@code{user} is a ``dummy'' theme that stores the user's direct -customization settings, and @code{changed} is a ``dummy'' theme that +@code{user} is a dummy theme that stores the user's direct +customization settings, and @code{changed} is a dummy theme that stores changes made outside of the Customize system. @end defmac @@ -1422,7 +1422,7 @@ where the list entries have the same meanings as in @end defun In theory, a theme file can also contain other Lisp forms, which -would be evaluated when loading the theme, but that is ``bad form''. +would be evaluated when loading the theme, but that is bad form. To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time. @@ -1440,7 +1440,7 @@ it returns @code{nil}. @defvar custom-known-themes The value of this variable is a list of themes loaded into Emacs. Each theme is represented by a Lisp symbol (the theme name). The -default value of this variable is a list containing two ``dummy'' +default value of this variable is a list containing two dummy themes: @code{(user changed)}. The @code{changed} theme stores settings made before any Custom themes are applied (e.g., variables set outside of Customize). The @code{user} theme stores settings the diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 47b24997551..e82efbb0b72 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -684,11 +684,11 @@ If @var{frame-number} is out of range, @code{backtrace-frame} returns @cindex debugging invalid Lisp syntax The Lisp reader reports invalid syntax, but cannot say where the real -problem is. For example, the error ``End of file during parsing'' in +problem is. For example, the error @samp{End of file during parsing} in evaluating an expression indicates an excess of open parentheses (or square brackets). The reader detects this imbalance at the end of the file, but it cannot figure out where the close parenthesis should have -been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close +been. Likewise, @samp{Invalid read syntax: ")"} indicates an excess close parenthesis or missing open parenthesis, but does not say where the missing parenthesis belongs. How, then, to find what to change? diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b5ff9cb6e76..2ae2857afda 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -126,7 +126,7 @@ it waits for input, or when the function @code{redisplay} is called. @cindex @samp{\} in display When a line of text extends beyond the right edge of a window, Emacs -can @dfn{continue} the line (make it ``wrap'' to the next screen +can @dfn{continue} the line (make it wrap to the next screen line), or @dfn{truncate} the line (limit it to one screen line). The additional screen lines used to display a long text line are called @dfn{continuation} lines. Continuation is not the same as filling; @@ -138,7 +138,7 @@ boundary. @xref{Filling}. indicate truncated and continued lines (@pxref{Fringes}). On a text terminal, a @samp{$} in the rightmost column of the window indicates truncation; a @samp{\} on the rightmost column indicates a line that -``wraps''. (The display table can specify alternate characters to use +wraps. (The display table can specify alternate characters to use for this; @pxref{Display Tables}). @defopt truncate-lines @@ -380,13 +380,13 @@ function. The arguments @var{min-value} and @var{max-value} should be numbers standing for the starting and final states of the operation. For -instance, an operation that ``scans'' a buffer should set these to the +instance, an operation that scans a buffer should set these to the results of @code{point-min} and @code{point-max} correspondingly. @var{max-value} should be greater than @var{min-value}. Alternatively, you can set @var{min-value} and @var{max-value} to @code{nil}. In that case, the progress reporter does not report -process percentages; it instead displays a ``spinner'' that rotates a +process percentages; it instead displays a spinner that rotates a notch each time you update the progress reporter. If @var{min-value} and @var{max-value} are numbers, you can give the @@ -439,13 +439,13 @@ presented to the user. @defun progress-reporter-done reporter This function should be called when the operation is finished. It -prints the message of @var{reporter} followed by word ``done'' in the +prints the message of @var{reporter} followed by word @samp{done} in the echo area. You should always call this function and not hope for -@code{progress-reporter-update} to print ``100%''. Firstly, it may +@code{progress-reporter-update} to print @samp{100%}. Firstly, it may never print it, there are many good reasons for this not to happen. -Secondly, ``done'' is more explicit. +Secondly, @samp{done} is more explicit. @end defun @defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} @@ -500,13 +500,13 @@ facility combines successive identical messages. It also combines successive related messages for the sake of two cases: question followed by answer, and a series of progress messages. - A ``question followed by an answer'' means two messages like the + A question followed by an answer has two messages like the ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, and the second is @samp{@var{question}...@var{answer}}. The first message conveys no additional information beyond what's in the second, so logging the second message discards the first from the log. - A ``series of progress messages'' means successive messages like + A series of progress messages has successive messages like those produced by @code{make-progress-reporter}. They have the form @samp{@var{base}...@var{how-far}}, where @var{base} is the same each time, while @var{how-far} varies. Logging each message in the series @@ -1419,7 +1419,7 @@ The return value is @var{overlay}. This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be -``lost''. +lost. @end defun @defun remove-overlays &optional start end name value @@ -1496,7 +1496,7 @@ foo @end example Emacs stores the overlays of each buffer in two lists, divided -around an arbitrary ``center position''. One list extends backwards +around an arbitrary center position. One list extends backwards through the buffer from that center position, and the other extends forwards from that center position. The center position can be anywhere in the buffer. @@ -1796,10 +1796,9 @@ overlays that specify property @var{prop} for the character at point: @defun overlays-in beg end This function returns a list of the overlays that overlap the region -@var{beg} through @var{end}. ``Overlap'' means that at least one -character is contained within the overlay and also contained within the -specified region; however, empty overlays (@pxref{Managing Overlays, -empty overlay}) are included in the result if they are located at +@var{beg} through @var{end}. An overlay overlaps with a region if it +contains one or more characters in the region; empty overlays +(@pxref{Managing Overlays, empty overlay}) overlap if they are at @var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} when @var{end} denotes the position at the end of the buffer. @end defun @@ -2729,8 +2728,8 @@ Manual}. @item If the text lies within an overlay with a non-@code{nil} @code{face} property, Emacs applies the face(s) specified by that property. If -the overlay has a @code{mouse-face} property and the mouse is ``near -enough'' to the overlay, Emacs applies the face or face attributes +the overlay has a @code{mouse-face} property and the mouse is near +enough to the overlay, Emacs applies the face or face attributes specified by the @code{mouse-face} property instead. @xref{Overlay Properties}. @@ -2836,7 +2835,7 @@ remappings for face @var{face} in the current buffer. The remaining arguments, @var{specs}, should form either a list of face names, or a property list of attribute/value pairs. -The return value is a Lisp object that serves as a ``cookie''; you can +The return value is a Lisp object that serves as a cookie; you can pass this object as an argument to @code{face-remap-remove-relative} if you need to remove the remapping later. @@ -2967,7 +2966,7 @@ If your Emacs Lisp program needs to assign some faces to text, it is often a good idea to use certain existing faces or inherit from them, rather than defining entirely new faces. This way, if other users have customized the basic faces to give Emacs a certain look, your -program will ``fit in'' without additional customization. +program will fit in without additional customization. Some of the basic faces defined in Emacs are listed below. In addition to these, you might want to make use of the Font Lock faces @@ -2992,14 +2991,14 @@ has a bold @code{:weight} attribute), with all other attributes unspecified (and so given by @code{default}). @item shadow -For ``dimmed out'' text. For example, it is used for the ignored +For dimmed-out text. For example, it is used for the ignored part of a filename in the minibuffer (@pxref{Minibuffer File,, Minibuffers for File Names, emacs, The GNU Emacs Manual}). @item link @itemx link-visited For clickable text buttons that send the user to a different -buffer or ``location''. +buffer or location. @item highlight For stretches of text that should temporarily stand out. For example, @@ -3193,7 +3192,7 @@ encoding of the font. character codes. An individual font cannot display the whole range of characters that Emacs supports, but a fontset can. Fontsets have names, just as fonts do, and you can use a fontset name in place of a font name -when you specify the ``font'' for a frame or a face. Here is +when you specify the font for a frame or a face. Here is information about defining a fontset under Lisp program control. @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror @@ -3481,13 +3480,13 @@ frame on which the fonts are to be displayed. The optional argument maximum length of the returned list. The optional argument @var{prefer}, if non-@code{nil}, should be another font spec, which is used to control the order of the returned list; the returned font -entities are sorted in order of decreasing ``closeness'' to that font +entities are sorted in order of decreasing closeness to that font spec. @end defun If you call @code{set-face-attribute} and pass a font spec, font entity, or font name string as the value of the @code{:font} -attribute, Emacs opens the best ``matching'' font that is available +attribute, Emacs opens the best matching font that is available for display. It then stores the corresponding font object as the actual value of the @code{:font} attribute for that face. @@ -4230,21 +4229,21 @@ frames. @cindex right dividers @cindex bottom dividers -Window dividers are bars drawn between a frame's windows. A ``right'' +Window dividers are bars drawn between a frame's windows. A right divider is drawn between a window and any adjacent windows on the right. Its width (thickness) is specified by the frame parameter -@code{right-divider-width}. A ``bottom'' divider is drawn between a +@code{right-divider-width}. A bottom divider is drawn between a window and adjacent windows on the bottom or the echo area. Its width is specified by the frame parameter @code{bottom-divider-width}. In either case, specifying a width of zero means to not draw such dividers. @xref{Layout Parameters}. - Technically, a right divider ``belongs'' to the window on its left, + Technically, a right divider belongs to the window on its left, which means that its width contributes to the total width of that -window. A bottom divider ``belongs'' to the window above it, which +window. A bottom divider belongs to the window above it, which means that its width contributes to the total height of that window. @xref{Window Sizes}. When a window has both, a right and a bottom -divider, the bottom divider ``prevails''. This means that a bottom +divider, the bottom divider prevails. This means that a bottom divider is drawn over the full total width of its window while the right divider ends above the bottom divider. @@ -4332,8 +4331,8 @@ display specification, the first overrides the rest. Replacing display specifications make most other display specifications irrelevant, since those don't apply to the replacement. - For replacing display specifications, ``the text that has the -property'' means all the consecutive characters that have the same + For replacing display specifications, @dfn{the text that has the +property} means all the consecutive characters that have the same Lisp object as their @code{display} property; these characters are replaced as a single unit. If two characters have different Lisp objects as their @code{display} properties (i.e., objects which are @@ -4559,7 +4558,7 @@ Here are the possibilities for @var{height}: @table @asis @item @code{(+ @var{n})} @c FIXME: Add an index for "step"? --xfq -This means to use a font that is @var{n} steps larger. A ``step'' is +This means to use a font that is @var{n} steps larger. A @dfn{step} is defined by the set of available fonts---specifically, those that match what was otherwise specified for this text, in all attributes except height. Each size for which a suitable font is available counts as @@ -4645,7 +4644,7 @@ variables: @defvar left-margin-width This variable specifies the width of the left margin, in character -cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers. +cell (a.k.a.@: column) units. It is buffer-local in all buffers. A value of @code{nil} means no left marginal area. @end defvar @@ -4836,7 +4835,7 @@ which algorithm. Specifies the Laplace edge detection algorithm, which blurs out small differences in color while highlighting larger differences. People sometimes consider this useful for displaying the image for a -``disabled'' button. +disabled button. @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) @cindex edge detection, images @@ -4901,7 +4900,7 @@ $$\pmatrix{ 2 & -1 & 0 \cr @end ifnottex @item disabled -Specifies transforming the image so that it looks ``disabled''. +Specifies transforming the image so that it looks disabled. @end table @item :mask @var{mask} @@ -5365,8 +5364,8 @@ This function inserts @var{image} in the current buffer at point, like @code{insert-image}, but splits the image into @var{rows}x@var{cols} equally sized slices. -If an image is inserted ``sliced'', Emacs displays each slice as a -separate image, and allow more intuitive scrolling up/down, instead of +Emacs displays each slice as a +separate image, and allows more intuitive scrolling up/down, instead of jumping up/down the entire image when paging through a buffer that displays (large) images. @end defun @@ -5443,7 +5442,7 @@ are multiple ``frames'' in the image. At present, Emacs supports multiple frames for GIF, TIFF, and certain ImageMagick formats such as DJVM@. -The frames can be used either to represent multiple ``pages'' (this is +The frames can be used either to represent multiple pages (this is usually the case with multi-frame TIFF files, for example), or to create animation (usually the case with multi-frame GIF files). @@ -5666,7 +5665,7 @@ so that it's easy to define special-purpose types of buttons for specific tasks. @defun define-button-type name &rest properties -Define a ``button type'' called @var{name} (a symbol). +Define a button type called @var{name} (a symbol). The remaining arguments form a sequence of @var{property value} pairs, specifying default property values for buttons with this type (a button's type may be set @@ -5819,7 +5818,7 @@ Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. These are commands and functions for locating and operating on buttons in an Emacs buffer. -@code{push-button} is the command that a user uses to actually ``push'' +@code{push-button} is the command that a user uses to actually push a button, and is bound by default in the button itself to @key{RET} and to @key{mouse-2} using a local keymap in the button's overlay or text properties. Commands that are useful outside the buttons itself, @@ -5884,8 +5883,8 @@ in the search, instead of starting at the next button. The Ewoc package constructs buffer text that represents a structure of Lisp objects, and updates the text to follow changes in that -structure. This is like the ``view'' component in the -``model/view/controller'' design paradigm. Ewoc means ``Emacs's +structure. This is like the view component in the +model--view--controller design paradigm. Ewoc means ``Emacs's Widget for Object Collections''. An @dfn{ewoc} is a structure that organizes information required to @@ -5949,7 +5948,7 @@ new value in its place, like so: @noindent You can also use, as the data element value, a Lisp object (list or -vector) that is a container for the ``real'' value, or an index into +vector) that is a container for the real value, or an index into some other structure. The example (@pxref{Abstract Display Example}) uses the latter approach. @@ -5985,7 +5984,7 @@ Normally, a newline is automatically inserted after the header, the footer and every node's textual description. If @var{nosep} is non-@code{nil}, no newline is inserted. This may be useful for displaying an entire ewoc on a single line, for example, or for -making nodes ``invisible'' by arranging for @var{pretty-printer} +making nodes invisible by arranging for @var{pretty-printer} to do nothing for those nodes. An ewoc maintains its text in the buffer that is current when @@ -6105,7 +6104,7 @@ Any @var{args} are passed to @var{map-function}. @subsection Abstract Display Example Here is a simple example using functions of the ewoc package to -implement a ``color components display'', an area in a buffer that +implement a @dfn{color components} display, an area in a buffer that represents a vector of three integers (itself representing a 24-bit RGB value) in various ways. @@ -6164,10 +6163,10 @@ The buffer is in Color Components mode." @end example @cindex controller part, model/view/controller - This example can be extended to be a ``color selection widget'' (in -other words, the controller part of the ``model/view/controller'' + This example can be extended to be a color selection widget (in +other words, the controller part of the model--view--controller design paradigm) by defining commands to modify @code{colorcomp-data} -and to ``finish'' the selection process, and a keymap to tie it all +and to finish the selection process, and a keymap to tie it all together conveniently. @smallexample @@ -6417,9 +6416,9 @@ display the character @var{c} as those glyphs; @pxref{Glyphs}). @strong{Warning:} if you use the display table to change the display of newline characters, the whole buffer will be displayed as one long -``line''. +line. - The display table also has six ``extra slots'' which serve special + The display table also has six @dfn{extra slots} which serve special purposes. Here is a table of their meanings; @code{nil} in any slot means to use the default for that slot, as stated below. @@ -6686,7 +6685,7 @@ Non-@acronym{ASCII}, non-printing characters @code{U+0080} to @samp{\230}). @item format-control -Characters of Unicode General Category ``Cf'', such as @samp{U+200E} +Characters of Unicode General Category [Cf], such as @samp{U+200E} (Left-to-Right Mark), but excluding characters that have graphic images, such as @samp{U+00AD} (Soft Hyphen). @@ -6733,8 +6732,8 @@ capability (@samp{vb}). @end defopt @defvar ring-bell-function -If this is non-@code{nil}, it specifies how Emacs should ``ring the -bell''. Its value should be a function of no arguments. If this is +If this is non-@code{nil}, it specifies how Emacs should ring the +bell. Its value should be a function of no arguments. If this is non-@code{nil}, it takes precedence over the @code{visible-bell} variable. @end defvar @@ -6823,8 +6822,8 @@ positions do not increase monotonically with string or buffer position. In performing this @dfn{bidirectional reordering}, Emacs follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}), which is described in Annex #9 of the Unicode standard -(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full -Bidirectionality'' class implementation of the @acronym{UBA}, +(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a Full +Bidirectionality class implementation of the @acronym{UBA}, consistent with the requirements of the Unicode Standard v7.0. @defvar bidi-display-reordering @@ -6950,7 +6949,7 @@ The function returns the new buffer position as its value. when two strings with bidirectional content are juxtaposed in a buffer, or otherwise programmatically concatenated into a string of text. A typical problematic case is when a buffer consists of -sequences of text ``fields'' separated by whitespace or punctuation +sequences of text fields separated by whitespace or punctuation characters, like Buffer Menu mode or Rmail Summary Mode. Because the punctuation characters used as separators have @dfn{weak directionality}, they take on the directionality of surrounding text. diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 97bcf0db270..9080bf70ccf 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -363,7 +363,7 @@ at point, rather than at the stop point. If you want to execute one expression @emph{from the current stop point}, first type @kbd{w} (@code{edebug-where}) to move point there, and then type @kbd{f}. -The @kbd{o} command continues ``out of'' an expression. It places a +The @kbd{o} command continues out of an expression. It places a temporary breakpoint at the end of the sexp containing point. If the containing sexp is a function definition itself, @kbd{o} continues until just before the last sexp in the definition. If that is where you are @@ -875,7 +875,7 @@ lines inserted. frequency. Coverage testing works by comparing the result of each expression with -the previous result; each form in the program is considered ``covered'' +the previous result; each form in the program is considered covered if it has returned two different values since you began testing coverage in the current Emacs session. Thus, to do coverage testing on your program, execute it under various conditions and note whether it behaves @@ -908,7 +908,7 @@ earlier expression on the same line. The character @samp{=} following the count for an expression says that the expression has returned the same value each time it was evaluated. -In other words, it is not yet ``covered'' for coverage testing purposes. +In other words, it is not yet covered for coverage testing purposes. To clear the frequency count and coverage data for a definition, simply reinstrument it with @code{eval-defun}. @@ -978,14 +978,14 @@ unless @code{edebug-continue-kbd-macro} is non-@code{nil}. @c This paragraph is not filled, because LaLiberte's conversion script @c needs an xref to be on just one line. When Edebug needs to display something (e.g., in trace mode), it saves -the current window configuration from ``outside'' Edebug +the current window configuration from outside Edebug (@pxref{Window Configurations}). When you exit Edebug, it restores the previous window configuration. Emacs redisplays only when it pauses. Usually, when you continue execution, the program re-enters Edebug at a breakpoint or after stepping, without pausing or reading input in between. In such cases, -Emacs never gets a chance to redisplay the ``outside'' configuration. +Emacs never gets a chance to redisplay the outside configuration. Consequently, what you see is the same window configuration as the last time Edebug was active, with no interruption. @@ -1605,7 +1605,7 @@ and consider a macro of the form: If you instrument the @code{test} macro and step through it, then by default the result of the @code{symbol-function} call has numerous @code{edebug-after} and @code{edebug-before} forms, which can make it -difficult to see the ``actual'' result. If +difficult to see the actual result. If @code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove these forms from the result. @end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 7b2b68a4fa6..5ca518ecd5f 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -453,7 +453,7 @@ Kinds of Forms we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: ``Special forms'' are idiosyncratic primitives, +* Special Forms:: Special forms are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -485,7 +485,7 @@ Errors Variables * Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain ``variables'' have values that never change. +* Constant Variables:: Variables that never change. * Local Variables:: Variable values that exist only temporarily. * Void Variables:: Symbols that lack values. * Defining Variables:: A definition says a symbol is used as a variable. @@ -599,7 +599,7 @@ Loading * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to ``unload'' a library that was loaded. +* Unloading:: How to unload a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @@ -990,7 +990,7 @@ Buffers is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. + behind Emacs's back. * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. * Buffer List:: How to look at all the existing buffers. @@ -1117,8 +1117,8 @@ Markers * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. +* The Mark:: How the mark is implemented with a marker. +* The Region:: How to access the region. Text @@ -1152,7 +1152,7 @@ Text * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. * Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes ``atomically''. +* Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. The Kill Ring diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index f253e7007b4..a7c44c66ec3 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -104,9 +104,9 @@ interpretation. @xref{Command Loop}. A Lisp object that is intended to be evaluated is called a @dfn{form} (or an @dfn{expression}). How Emacs evaluates a form depends on its data type. Emacs has three different kinds of form -that are evaluated differently: symbols, lists, and ``all other -types''. This section describes all three kinds, one by one, starting -with the ``all other types'' which are self-evaluating forms. +that are evaluated differently: symbols, lists, and all other +types. This section describes all three kinds, one by one, starting +with the other types, which are self-evaluating forms. @menu * Self-Evaluating Forms:: Forms that evaluate to themselves. @@ -116,7 +116,7 @@ with the ``all other types'' which are self-evaluating forms. we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: ``Special forms'' are idiosyncratic primitives, +* Special Forms:: Special forms are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -146,7 +146,7 @@ contents unchanged. @result{} 123 @end group @group -(eval '123) ; @r{Evaluated ``by hand''---result is the same.} +(eval '123) ; @r{Evaluated by hand---result is the same.} @result{} 123 @end group @group diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 91b0c96071e..735e08eb324 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -55,7 +55,7 @@ to locale @code{system-messages-locale}, and decoded using coding system Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is @dfn{visiting} that file, and call the -file ``the visited file'' of the buffer. +file @dfn{the visited file} of the buffer. A file and a buffer are two different things. A file is information recorded permanently in the computer (unless you delete it). A @@ -692,7 +692,7 @@ stored in the same directory as the file you are editing. (On file systems that do not support symbolic links, a regular file is used.) When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously''. +you and another user will both lock the same file simultaneously. If this happens, it is possible for the two users to make changes simultaneously, but Emacs will still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed @@ -939,7 +939,7 @@ $ ls -l diffs @cindex MS-DOS and file modes @cindex file modes and MS-DOS @strong{MS-DOS note:} On MS-DOS, there is no such thing as an -``executable'' file mode bit. So @code{file-modes} considers a file +executable file mode bit. So @code{file-modes} considers a file executable if its name ends in one of the standard executable extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some others. Files that begin with the Unix-standard @samp{#!} signature, @@ -1089,7 +1089,7 @@ If you may need to follow symbolic links preceding @samp{..}@: appearing as a name component, call @code{file-truename} without prior direct or indirect calls to @code{expand-file-name}. Otherwise, the file name component immediately preceding @samp{..} will be -``simplified away'' before @code{file-truename} is called. To +simplified away before @code{file-truename} is called. To eliminate the need for a call to @code{expand-file-name}, @code{file-truename} handles @samp{~} in the same way that @code{expand-file-name} does. @xref{File Name Expansion,, Functions @@ -1358,7 +1358,7 @@ On some operating systems, each file can be associated with arbitrary and setting two specific sets of extended file attributes: Access Control Lists (ACLs) and SELinux contexts. These extended file attributes are used, on some systems, to impose more sophisticated -file access controls than the basic ``Unix-style'' permissions +file access controls than the basic Unix-style permissions discussed in the previous sections. @cindex access control list @@ -1509,8 +1509,8 @@ replaces it with its (recursive) target. @cindex file with multiple names @cindex file hard link This function gives the file named @var{oldname} the additional name -@var{newname}. This means that @var{newname} becomes a new ``hard -link'' to @var{oldname}. +@var{newname}. This means that @var{newname} becomes a new hard +link to @var{oldname}. In the first part of the following example, we list two files, @file{foo} and @file{foo3}. @@ -1603,7 +1603,7 @@ file. This works only on some operating systems, and only if you have the correct permissions to do so. If the optional argument @var{preserve-permissions} is non-@code{nil}, -this function copies the file modes (or ``permissions'') of +this function copies the file modes (or permissions) of @var{oldname} to @var{newname}, as well as the Access Control List and SELinux context (if any). @xref{Information about Files}. @@ -1687,7 +1687,7 @@ 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. +given by the bitwise complement of the @samp{umask} value. The argument @var{mode} should be an integer which specifies the permissions, similar to @code{set-file-modes} above. Only the lowest @@ -1908,7 +1908,7 @@ return value, but backup version numbers are kept. @end defun @defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension'', if any, +This function returns @var{filename}'s final extension, if any, after applying @code{file-name-sans-versions} to remove any version/backup part. The extension, in a file name, is the part that follows the last @samp{.} in the last name component (minus any @@ -1918,7 +1918,7 @@ This function returns @code{nil} for extensionless file names such as @file{foo}. It returns @code{""} for null extensions, as in @file{foo.}. If the last component of a file name begins with a @samp{.}, that @samp{.} doesn't count as the beginning of an -extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not +extension. Thus, @file{.emacs}'s extension is @code{nil}, not @samp{.emacs}. If @var{period} is non-@code{nil}, then the returned value includes @@ -2198,7 +2198,7 @@ In some cases, a leading @samp{..} component can remain in the output: @noindent This is for the sake of filesystems that have the concept of a -``superroot'' above the root directory @file{/}. On other filesystems, +superroot above the root directory @file{/}. On other filesystems, @file{/../} is interpreted exactly the same as @file{/}. Note that @code{expand-file-name} does @emph{not} expand environment @@ -2257,7 +2257,7 @@ This function replaces environment variable references in @var{filename} with the environment variable values. Following standard Unix shell syntax, @samp{$} is the prefix to substitute an environment variable value. If the input contains @samp{$$}, that is -converted to @samp{$}; this gives the user a way to ``quote'' a +converted to @samp{$}; this gives the user a way to quote a @samp{$}. The environment variable name is the series of alphanumeric characters @@ -2619,7 +2619,7 @@ that can be read. @defun directory-files-recursively directory match &optional include-directories Return all files under @var{directory} whose file names match -@var{match} recursively. The file names are returned ``depth first'', +@var{match} recursively. The file names are returned depth first, meaning that contents of sub-directories are returned before contents of the directories. If @var{include-directories} is non-@code{nil}, also return directory names that have matching names. @@ -2753,7 +2753,7 @@ no prefix argument is given, and @code{nil} otherwise. @end deffn @node Magic File Names -@section Making Certain File Names ``Magic'' +@section Making Certain File Names Magic @cindex magic file names You can implement special handling for certain file names. This is @@ -2943,7 +2943,7 @@ unlocking the buffer if it is locked. possibly others to be added in the future. It need not implement all these operations itself---when it has nothing special to do for a certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way''. It should always reinvoke the primitive +operation in the usual way. It should always reinvoke the primitive for an operation it does not recognize. Here's one way to do this: @smallexample @@ -2976,7 +2976,7 @@ each have handlers. Handlers that don't really do anything special for actual access to the file---such as the ones that implement completion of host names for remote file names---should have a non-@code{nil} @code{safe-magic} -property. For instance, Emacs normally ``protects'' directory names +property. For instance, Emacs normally protects directory names it finds in @code{PATH} from becoming magic, if they look like magic file names, by prefixing them with @samp{/:}. But if the handler that would be used for them has a non-@code{nil} @code{safe-magic} diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 1fcc7fd4ba1..db8ac756636 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -262,7 +262,7 @@ variable, or by the @samp{--display} option (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). Emacs can connect to other X displays via the command @code{make-frame-on-display}. Each X display has its own selected frame and its own minibuffer windows; however, only one -of those frames is ``@emph{the} selected frame'' at any given moment +of those frames is @emph{the} selected frame at any given moment (@pxref{Input Focus}). Emacs can even connect to other text terminals, by interacting with the @command{emacsclient} program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}. @@ -294,8 +294,8 @@ This function creates and returns a new frame on @var{display}, taking the other frame parameters from the alist @var{parameters}. @var{display} should be the name of an X display (a string). -Before creating the frame, this function ensures that Emacs is ``set -up'' to display graphics. For instance, if Emacs has not processed X +Before creating the frame, this function ensures that Emacs is set +up to display graphics. For instance, if Emacs has not processed X resources (e.g., if it was started on a text terminal), it does so at this time. In all other respects, this function behaves like @code{make-frame} (@pxref{Creating Frames}). @@ -336,7 +336,7 @@ on that display (@pxref{Deleting Frames}). @end defun @cindex multi-monitor - On some ``multi-monitor'' setups, a single X display outputs to more + On some multi-monitor setups, a single X display outputs to more than one physical monitor. You can use the functions @code{display-monitor-attributes-list} and @code{frame-monitor-attributes} to obtain information about such setups. @@ -358,7 +358,7 @@ that, if the monitor is not the primary monitor, some of the coordinates might be negative. @item workarea -Position of the top-left corner and size of the work area (``usable'' +Position of the top-left corner and size of the work area (usable space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}. This may be different from @samp{geometry} in that space occupied by various window manager features (docks, taskbars, etc.)@: may be @@ -489,7 +489,7 @@ of the frame. The @dfn{outer width} and @dfn{outer height} of the frame specify the size of that rectangle. @cindex outer position -The upper left corner of the outer frame (indicated by ``(0)'' in the +The upper left corner of the outer frame (indicated by @samp{(0)} in the drawing above) is the @dfn{outer position} or the frame. It is specified by and settable via the @code{left} and @code{top} frame parameters (@pxref{Position Parameters}) as well as the functions @@ -500,7 +500,7 @@ Position}). @cindex external border The @dfn{external border} is part of the decorations supplied by the window manager. It's typically used for resizing the frame with the -mouse. The external border is normally not shown on ``fullboth'' and +mouse. The external border is normally not shown on fullboth and maximized frames (@pxref{Size Parameters}) and doesn't exist for text terminal frames. @@ -514,7 +514,7 @@ on most platforms it is not covered here. The @dfn{title bar} is also part of the window manager's decorations and typically displays the title of the frame (@pxref{Frame Titles}) as well as buttons for minimizing, maximizing and deleting the frame. The title -bar is usually not displayed on ``fullboth'' (@pxref{Size Parameters}) +bar is usually not displayed on fullboth (@pxref{Size Parameters}) or tooltip frames. Title bars don't exist for text terminal frames. @item Menu Bar @@ -689,11 +689,11 @@ Optional argument @var{type} specifies the type of the edges to return: @var{frame}, @code{native-edges} (or @code{nil}) means to return its native edges and @code{inner-edges} means to return its inner edges. -Notice that the ``pixels at the positions'' @var{bottom} and @var{right} +Notice that the pixels at the positions @var{bottom} and @var{right} lie immediately outside the corresponding frame. This means that if you have, for example, two side-by-side frames positioned such that the right outer edge of the frame on the left equals the left outer edge of -the frame on the right, the pixels ``representing'' that edge are part +the frame on the right, the pixels representing that edge are part of the frame on the right. @end defun @@ -708,7 +708,7 @@ of the frame on the right. @cindex default height of character Each frame has a @dfn{default font} which specifies the default character size for that frame. This size is meant when retrieving or -changing the size of a frame in terms of ``columns'' or ``lines'' +changing the size of a frame in terms of columns or lines (@pxref{Size Parameters}). It is also used when resizing (@pxref{Window Sizes}) or splitting (@pxref{Splitting Windows}) windows. @@ -841,7 +841,7 @@ of its character size, however, may: be ignored, cause a rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows). With some window managers you may have to set this to non-@code{nil} in -order to make a frame appear truly ``maximized'' or ``fullscreen''. +order to make a frame appear truly maximized or fullscreen. @end defopt @defun set-frame-size frame width height pixelwise @@ -867,7 +867,7 @@ actual height of the frame. This is only useful on text terminals. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame -height ``for real'' does not always work, because knowing the correct +height directly does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on text terminals. @@ -1290,11 +1290,11 @@ the height shall be set to the size of the screen. The value The difference between @code{maximized} and @code{fullboth} is that a maximized frame usually keeps its title bar and the buttons for resizing and closing the frame. Also, maximized frames typically avoid hiding -any task bar or panels displayed on the desktop. ``Fullboth'' frames, -on the other hand, usually omit the title bar and occupy the entire +any task bar or panels displayed on the desktop. A fullboth frame, +on the other hand, usually omits the title bar and occupies the entire available screen space. -``Fullheight'' and ``fullwidth'' frames are more similar to maximized +Fullheight and fullwidth frames are more similar to maximized frames in this regard. However, these typically display an external border which might be absent with maximized frames. Hence the heights of maximized and fullheight frames and the widths of maximized and @@ -1302,16 +1302,16 @@ fullwidth frames often differ by a few pixels. With some window managers you may have to customize the variable @code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to -make a frame truly appear ``maximized'' or ``fullscreen''. Moreover, +make a frame truly appear maximized or fullscreen. Moreover, some window managers might not support smooth transition between the various fullscreen or maximization states. Customizing the variable @code{x-frame-normalize-before-maximize} can help to overcome that. @vindex fullscreen-restore, a frame parameter @item fullscreen-restore -This parameter specifies the desired ``fullscreen'' state of the frame +This parameter specifies the desired fullscreen state of the frame after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame -Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state. +Commands,,, emacs, The GNU Emacs Manual}) in the fullboth state. Normally this parameter is installed automatically by that command when toggling the state to fullboth. If, however, you start Emacs in the fullboth state, you have to specify the desired behavior in your initial @@ -1580,7 +1580,7 @@ This variable specifies how to blink the cursor. Each element has the form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor type equals @var{on-state} (comparing using @code{equal}), the corresponding @var{off-state} specifies what the cursor looks like -when it blinks ``off''. Both @var{on-state} and @var{off-state} +when it blinks off. Both @var{on-state} and @var{off-state} should be suitable values for the @code{cursor-type} frame parameter. There are various defaults for how to blink each type of cursor, if @@ -1631,7 +1631,7 @@ used instead. @vindex screen-gamma, a frame parameter @item screen-gamma @cindex gamma correction -If this is a number, Emacs performs ``gamma correction'' which adjusts +If this is a number, Emacs performs gamma correction which adjusts the brightness of all colors. The value should be the screen gamma of your display. @@ -1903,13 +1903,13 @@ internals of Emacs. @defun visible-frame-list This function returns a list of just the currently visible frames. @xref{Visibility of Frames}. Frames on text terminals always count as -``visible'', even though only the selected one is actually displayed. +visible, even though only the selected one is actually displayed. @end defun @defun next-frame &optional frame minibuf This function lets you cycle conveniently through all the frames on the current display from an arbitrary starting point. It returns the -``next'' frame after @var{frame} in the cycle. If @var{frame} is +next frame after @var{frame} in the cycle. If @var{frame} is omitted or @code{nil}, it defaults to the selected frame (@pxref{Input Focus}). @@ -1981,7 +1981,7 @@ window always resides on the selected frame. When Emacs displays its frames on several terminals (@pxref{Multiple Terminals}), each terminal has its own selected frame. But only one -of these is ``@emph{the} selected frame'': it's the frame that belongs +of these is @emph{the} selected frame: it's the frame that belongs to the terminal from which the most recent input came. That is, when Emacs runs a command that came from a certain terminal, the selected frame is the one of that terminal. Since Emacs runs only a single @@ -2001,7 +2001,7 @@ way, Emacs automatically keeps track of which frame has the focus. To explicitly switch to a different frame from a Lisp function, call @code{select-frame-set-input-focus}. -Lisp programs can also switch frames ``temporarily'' by calling the +Lisp programs can also switch frames temporarily by calling the function @code{select-frame}. This does not alter the window system's concept of focus; rather, it escapes from the window manager's control until that control is somehow reasserted. @@ -2130,7 +2130,7 @@ This function returns the visibility status of frame @var{frame}. The value is @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and @code{icon} if it is iconified. -On a text terminal, all frames are considered ``visible'' for the +On a text terminal, all frames are considered visible for the purposes of this function, even though only one frame is displayed. @xref{Raising and Lowering}. @end defun @@ -2891,7 +2891,7 @@ If you specify them, the key is @defvar x-resource-class This variable specifies the application name that @code{x-get-resource} should look up. The default value is @code{"Emacs"}. You can examine X -resources for application names other than ``Emacs'' by binding this +resources for other application names by binding this variable to some other string, around a call to @code{x-get-resource}. @end defvar @@ -2994,14 +2994,14 @@ way that's different in appearance than the default face, and @item -``close in spirit'' to what the attributes specify, if not exact. +close in spirit to what the attributes specify, if not exact. @end enumerate Point (2) implies that a @code{:weight black} attribute will be satisfied by any display that can display bold, as will @code{:foreground "yellow"} as long as some yellowish color can be displayed, but @code{:slant italic} will @emph{not} be satisfied by -the tty display code's automatic substitution of a ``dim'' face for +the tty display code's automatic substitution of a dim face for italic. @end defun @@ -3026,7 +3026,7 @@ This function returns the number of screens associated with the display. This function returns the height of the screen in pixels. On a character terminal, it gives the height in characters. -For graphical terminals, note that on ``multi-monitor'' setups this +For graphical terminals, note that on multi-monitor setups this refers to the pixel height for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun @@ -3035,7 +3035,7 @@ refers to the pixel height for all physical monitors associated with This function returns the width of the screen in pixels. On a character terminal, it gives the width in characters. -For graphical terminals, note that on ``multi-monitor'' setups this +For graphical terminals, note that on multi-monitor setups this refers to the pixel width for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun @@ -3044,7 +3044,7 @@ refers to the pixel width for all physical monitors associated with This function returns the height of the screen in millimeters, or @code{nil} if Emacs cannot get that information. -For graphical terminals, note that on ``multi-monitor'' setups this +For graphical terminals, note that on multi-monitor setups this refers to the height for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun @@ -3053,7 +3053,7 @@ refers to the height for all physical monitors associated with This function returns the width of the screen in millimeters, or @code{nil} if Emacs cannot get that information. -For graphical terminals, note that on ``multi-monitor'' setups this +For graphical terminals, note that on multi-monitor setups this refers to the width for all physical monitors associated with @var{display}. @xref{Multiple Terminals}. @end defun @@ -3120,7 +3120,7 @@ MS-Windows, this is the version of the Windows OS. @end defun @defun x-server-vendor &optional display -This function returns the ``vendor'' that provided the window system +This function returns the vendor that provided the window system software (as a string). On GNU and Unix systems this really means whoever distributes the X server. On MS-Windows this is the vendor ID string of the Windows OS (Microsoft). diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index a853d2fbab5..895dca02621 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -118,7 +118,7 @@ Components}); such a @dfn{named command} can be invoked with @item closure A function object that is much like a lambda expression, except that -it also encloses an ``environment'' of lexical variable bindings. +it also encloses an environment of lexical variable bindings. @xref{Closures}. @item byte-code function @@ -368,7 +368,7 @@ This is what @code{substring} does; @code{nil} as the third argument to @quotation @b{Common Lisp note:} Common Lisp allows the function to specify what default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' +always uses @code{nil}. Emacs Lisp does not support @code{supplied-p} variables that tell you whether an argument was explicitly passed. @end quotation @@ -660,7 +660,7 @@ already been evaluated. The argument @var{function} must be either a Lisp function or a primitive function. Special forms and macros are not allowed, because -they make sense only when given the ``unevaluated'' argument +they make sense only when given the unevaluated argument expressions. @code{funcall} cannot provide these because, as we saw above, it never knows them in the first place. @@ -912,7 +912,7 @@ This macro returns an anonymous function with argument list @var{args}, documentation string @var{doc} (if any), interactive spec @var{interactive} (if any), and body forms given by @var{body}. -In effect, this macro makes @code{lambda} forms ``self-quoting'': +In effect, this macro makes @code{lambda} forms self-quoting: evaluating a form whose @sc{car} is @code{lambda} yields the form itself: @@ -1133,7 +1133,7 @@ argument list and body forms as the remaining elements: @noindent However, the fact that the internal structure of a closure is -``exposed'' to the rest of the Lisp world is considered an internal +exposed to the rest of the Lisp world is considered an internal implementation detail. For this reason, we recommend against directly examining or altering the structure of closure objects. @@ -1720,7 +1720,7 @@ performed later on in the same file, just like macros. @section The @code{declare} Form @findex declare - @code{declare} is a special macro which can be used to add ``meta'' + @code{declare} is a special macro which can be used to add meta properties to a function or macro: for example, marking it as obsolete, or giving its forms a special @key{TAB} indentation convention in Emacs Lisp mode. @@ -1821,7 +1821,7 @@ example, byte-compiling @file{fortran.el} used to warn: @example In end of data: -fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not +fortran.el:2152:1:Warning: the function ‘gud-find-c-expr’ is not known to be defined. @end example @@ -1912,7 +1912,7 @@ list of buffer-local bindings. Being quick and simple, @code{unsafep} does a very light analysis and rejects many Lisp expressions that are actually safe. There are no known cases where @code{unsafep} returns @code{nil} for an unsafe -expression. However, a ``safe'' Lisp expression can return a string +expression. However, a safe Lisp expression can return a string with a @code{display} property, containing an associated Lisp expression to be executed after the string is inserted into a buffer. This associated expression can be a virus. In order to be safe, you diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 9d60cc38c25..22b7217506f 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -31,10 +31,10 @@ the way two alists can share a common tail. with a series of functions for operating on them. Hash tables have a special printed representation, which consists of @samp{#s} followed by a list specifying the hash table properties and contents. -@xref{Creating Hash}. (Note that the term ``hash notation'', which -refers to the initial @samp{#} character used in the printed +@xref{Creating Hash}. +(Hash notation, the initial @samp{#} character used in the printed representations of objects with no read representation, has nothing to -do with the term ``hash table''. @xref{Printed Representation}.) +do with hash tables. @xref{Printed Representation}.) Obarrays are also a kind of hash table, but they are a different type of object and are used only for recording interned symbols @@ -71,16 +71,16 @@ alternatives: @table @code @item eql -Keys which are numbers are ``the same'' if they are @code{equal}, that +Keys which are numbers are the same if they are @code{equal}, that is, if they are equal in value and either both are integers or both are floating point; otherwise, two distinct objects are never -``the same''. +the same. @item eq -Any two distinct Lisp objects are ``different'' as keys. +Any two distinct Lisp objects are different as keys. @item equal -Two Lisp objects are ``the same'', as keys, if they are equal +Two Lisp objects are the same, as keys, if they are equal according to @code{equal}. @end table @@ -128,7 +128,7 @@ doing that takes some extra time. The default size is 65. @item :rehash-size @var{rehash-size} -When you add an association to a hash table and the table is ``full'', +When you add an association to a hash table and the table is full, it grows automatically. This value specifies how to make the hash table larger, at that time. @@ -141,10 +141,10 @@ number. The default value is 1.5. @item :rehash-threshold @var{threshold} -This specifies the criterion for when the hash table is ``full'' (so +This specifies the criterion for when the hash table is full (so it should be made larger). The value, @var{threshold}, should be a positive floating-point number, no greater than 1. The hash table is -``full'' whenever the actual number of entries exceeds this fraction +full whenever the actual number of entries exceeds this fraction of the nominal size. The default for @var{threshold} is 0.8. @end table @end defun @@ -253,13 +253,13 @@ This function defines a new hash table test, named @var{name}. After defining @var{name} in this way, you can use it as the @var{test} argument in @code{make-hash-table}. When you do that, the hash table will use @var{test-fn} to compare key values, and @var{hash-fn} to compute -a ``hash code'' from a key value. +a hash code from a key value. The function @var{test-fn} should accept two arguments, two keys, and -return non-@code{nil} if they are considered ``the same''. +return non-@code{nil} if they are considered the same. The function @var{hash-fn} should accept one argument, a key, and return -an integer that is the ``hash code'' of that key. For good results, the +an integer that is the hash code of that key. For good results, the function should use the whole range of integers for hash codes, including negative integers. diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index b3042d747b4..fe7c457f57e 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -242,6 +242,11 @@ Semipermanent goal column for vertical motion, as set by @dots{} @c That makes them incorrect. @group +minibuffer-temporary-goal-position Variable +not documented +@end group + +@group set-goal-column Keys: C-x C-n Set the current horizontal position as a goal for C-n and C-p. @end group @@ -249,17 +254,26 @@ Set the current horizontal position as a goal for C-n and C-p. @group Those commands will move to this position in the line moved to rather than trying to keep the same horizontal position. -With a non-nil argument, clears out the goal column +With a non-nil argument ARG, clears out the goal column so that C-n and C-p resume vertical motion. -The goal column is stored in the variable `goal-column'. +The goal column is stored in the variable ‘goal-column’. + +(fn ARG) @end group @group temporary-goal-column Variable Current goal column for vertical motion. -It is the column where point was -at the start of current run of vertical motion commands. -When the `track-eol' feature is doing its job, the value is 9999. +It is the column where point was at the start of the current run +of vertical motion commands. + +When moving by visual lines via the function ‘line-move-visual’, it is a cons +cell (COL . HSCROLL), where COL is the x-position, in pixels, +divided by the default column width, and HSCROLL is the number of +columns by which window is scrolled from left margin. + +When the ‘track-eol’ feature is doing its job, the value is +‘most-positive-fixnum’. ---------- Buffer: *Help* ---------- @end group @end smallexample @@ -539,11 +553,11 @@ about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here we describe some program-level interfaces to the same information. @deffn Command apropos pattern &optional do-all -This function finds all ``meaningful'' symbols whose names contain a +This function finds all meaningful symbols whose names contain a match for the apropos pattern @var{pattern}. An apropos pattern is either a word to match, a space-separated list of words of which at least two must match, or a regular expression (if any special regular -expression characters occur). A symbol is ``meaningful'' if it has a +expression characters occur). A symbol is meaningful if it has a definition as a function, variable, or face, or has properties. The function returns a list of elements that look like this: @@ -608,7 +622,7 @@ subcommands of the prefix key. @defopt help-event-list The value of this variable is a list of event types that serve as -alternative ``help characters''. These events are handled just like the +alternative help characters. These events are handled just like the event specified by @code{help-char}. @end defopt @@ -643,7 +657,7 @@ sequence. (The last event is, presumably, the help character.) @end deffn The following two functions are meant for modes that want to provide -help without relinquishing control, such as the ``electric'' modes. +help without relinquishing control, such as the electric modes. Their names begin with @samp{Helper} to distinguish them from the ordinary help functions. diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 279e78ebe7b..eb2e34318fd 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -104,7 +104,7 @@ Hook run when the buffer list changes (@pxref{Buffer List}). @item buffer-quit-function @vindex buffer-quit-function -Function to call to ``quit'' the current buffer. +Function to call to quit the current buffer. @item change-major-mode-hook @xref{Creating Buffer-Local}. diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 2a314a596fb..20681c07d9a 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -258,7 +258,7 @@ accessible objects are also accessible. matter what the Lisp program or the user does, it is impossible to refer to them, since there is no longer a way to reach them. Their space might as well be reused, since no one will miss them. The second -(``sweep'') phase of the garbage collector arranges to reuse them. +(sweep) phase of the garbage collector arranges to reuse them. @c ??? Maybe add something describing weak hash tables here? @@ -1368,7 +1368,7 @@ The buffer's value of point, as of the last time a redisplay completed in this window. @item last_had_star -A non-@code{nil} value means the window's buffer was ``modified'' when the +A non-@code{nil} value means the window's buffer was modified when the window was last updated. @item vertical_scroll_bar @@ -1584,7 +1584,7 @@ fit in @code{int} range. Do not assume that signed integer arithmetic wraps around on overflow. This is no longer true of Emacs porting targets: signed integer overflow has undefined behavior in practice, and can dump core or -even cause earlier or later code to behave ``illogically''. Unsigned +even cause earlier or later code to behave illogically. Unsigned overflow does wrap around reliably, modulo a power of two. @item diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 6158bf5aa65..865c6984864 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -9,7 +9,7 @@ Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming +than a mere extension language; it is a full computer programming language in its own right. You can use it as you would any other programming language. @@ -148,8 +148,8 @@ manual. You may want to skip this section and refer back to it later. printer'' refer to those routines in Lisp that convert textual representations of Lisp objects into actual Lisp objects, and vice versa. @xref{Printed Representation}, for more details. You, the -person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you''. ``The user'' is the person who uses Lisp +person reading this manual, are thought of as the programmer and are +addressed as ``you''. The user is the person who uses Lisp programs, including those you write. @cindex typographic conventions @@ -287,7 +287,7 @@ the echo area. @cindex buffer text notation Some examples describe modifications to the contents of a buffer, by -showing the ``before'' and ``after'' versions of the text. These +showing the before and after versions of the text. These examples show the contents of the buffer in question between two lines of dashes containing the buffer name. In addition, @samp{@point{}} indicates the location of point. (The symbol for point, of course, is diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 7752bf0617c..d665587dbf3 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -634,7 +634,7 @@ the current buffer's local keymap, and (iv) the global keymap, in that order. Emacs searches for each input key sequence in all these keymaps. - Of these ``usual'' keymaps, the highest-precedence one is specified + Of these usual keymaps, the highest-precedence one is specified by the @code{keymap} text or overlay property at point, if any. (For a mouse input event, Emacs uses the event position instead of point; @iftex @@ -669,7 +669,7 @@ keymaps in other buffers with the same major mode. defined regardless of the current buffer, such as @kbd{C-f}. It is always active, and is bound to the variable @code{global-map}. - Apart from the above ``usual'' keymaps, Emacs provides special ways + Apart from the above usual keymaps, Emacs provides special ways for programs to make other keymaps active. Firstly, the variable @code{overriding-local-map} specifies a keymap that replaces the usual active keymaps, except for the global keymap. Secondly, the @@ -929,7 +929,7 @@ sequences entered using the menu bar, even if they do not affect the menu bar display. So if a menu bar key sequence comes in, you should clear the variables before looking up and executing that key sequence. Modes that use the variables would typically do this anyway; normally -they respond to events that they do not handle by ``unreading'' them and +they respond to events that they do not handle by unreading them and exiting. @end defvar @@ -944,7 +944,7 @@ This variable holds a list of keymap alists to use for emulation modes. It is intended for modes or packages using multiple minor-mode keymaps. Each element is a keymap alist which has the same format and meaning as @code{minor-mode-map-alist}, or a symbol with a variable -binding which is such an alist. The ``active'' keymaps in each alist +binding which is such an alist. The active keymaps in each alist are used before @code{minor-mode-map-alist} and @code{minor-mode-overriding-map-alist}. @end defvar @@ -983,7 +983,7 @@ not part of key lookup. the rest of the event is ignored. In fact, a key sequence used for key lookup may designate a mouse event with just its types (a symbol) instead of the entire event (a list). @xref{Input Events}. Such -a ``key sequence'' is insufficient for @code{command-execute} to run, +a key sequence is insufficient for @code{command-execute} to run, but it is sufficient for looking up or rebinding a key. When the key sequence consists of multiple events, key lookup @@ -1069,7 +1069,7 @@ thing that is done automatically for an undefined key: it rings the bell @cindex preventing prefix key @code{undefined} is used in local keymaps to override a global key -binding and make the key ``undefined'' locally. A local binding of +binding and make the key undefined locally. A local binding of @code{nil} would fail to do this because it would not override the global binding. @@ -1108,7 +1108,7 @@ the other functions described in this chapter that look up keys use @end example If the string or vector @var{key} is not a valid key sequence according -to the prefix keys specified in @var{keymap}, it must be ``too long'' +to the prefix keys specified in @var{keymap}, it must be too long and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of @var{key} that compose a complete key. @@ -1546,7 +1546,7 @@ and @code{key-translation-map} (in order of priority). are used differently: they specify translations to make while reading key sequences, rather than bindings for complete key sequences. As each key sequence is read, it is checked against each translation -keymap. If one of the translation keymaps ``binds'' @var{k} to a +keymap. If one of the translation keymaps binds @var{k} to a vector @var{v}, then whenever @var{k} appears as a sub-sequence @emph{anywhere} in a key sequence, that sub-sequence is replaced with the events in @var{v}. @@ -1554,7 +1554,7 @@ the events in @var{v}. For example, VT100 terminals send @kbd{@key{ESC} O P} when the keypad key @key{PF1} is pressed. On such terminals, Emacs must translate that sequence of events into a single event @code{pf1}. -This is done by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in +This is done by binding @kbd{@key{ESC} O P} to @code{[pf1]} in @code{input-decode-map}. Thus, when you type @kbd{C-c @key{PF1}} on the terminal, the terminal emits the character sequence @kbd{C-c @key{ESC} O P}, and @code{read-key-sequence} translates this back into @@ -1615,7 +1615,7 @@ to @code{self-insert-command}. @cindex key translation function You can use @code{input-decode-map}, @code{local-function-key-map}, and @code{key-translation-map} for more than simple aliases, by using -a function, instead of a key sequence, as the ``translation'' of a +a function, instead of a key sequence, as the translation of a key. Then this function is called to compute the translation of that key. @@ -2071,7 +2071,7 @@ the GTK+ toolkit). @end example @noindent -@var{help} specifies a ``help-echo'' string to display while the mouse +@var{help} specifies a help-echo string to display while the mouse is on that item in the same way as @code{help-echo} text properties (@pxref{Help display}). @@ -2088,7 +2088,7 @@ the menu but cannot be selected. controls whether the menu item is enabled. Every time the keymap is used to display a menu, Emacs evaluates the expression, and it enables the menu item only if the expression's value is non-@code{nil}. When a -menu item is disabled, it is displayed in a ``fuzzy'' fashion, and +menu item is disabled, it is displayed in a fuzzy fashion, and cannot be selected. The menu bar does not recalculate which items are enabled every time you @@ -2144,7 +2144,7 @@ does not appear, then the menu is displayed as if this item were not defined at all. @item :help @var{help} -The value of this property, @var{help}, specifies a ``help-echo'' string +The value of this property, @var{help}, specifies a help-echo string to display while the mouse is on that item. This is displayed in the same way as @code{help-echo} text properties (@pxref{Help display}). Note that this must be a constant string, unlike the @code{help-echo} @@ -2156,7 +2156,7 @@ The @sc{car}, @var{type}, says which: it should be @code{:toggle} or @code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the result of evaluating it says whether this button is currently selected. -A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off'' +A @dfn{toggle} is a menu item which is labeled as either on or off according to the value of @var{selected}. The command itself should toggle @var{selected}, setting it to @code{t} if it is @code{nil}, and to @code{nil} if it is @code{t}. Here is how the menu item @@ -2174,7 +2174,7 @@ This works because @code{toggle-debug-on-error} is defined as a command which toggles the variable @code{debug-on-error}. @dfn{Radio buttons} are a group of menu items, in which at any time one -and only one is ``selected''. There should be a variable whose value +and only one is selected. There should be a variable whose value says which one is selected at any time. The @var{selected} form for each radio button in the group should check whether the variable has the right value for selecting that button. Clicking on the button should @@ -2303,7 +2303,7 @@ displays a similar kind of separator that is supported. @node Alias Menu Items @subsubsection Alias Menu Items - Sometimes it is useful to make menu items that use the ``same'' + Sometimes it is useful to make menu items that use the same command but with different enable conditions. The best way to do this in Emacs now is with extended menu items; before that feature existed, it could be done by defining alias commands and using them in menu @@ -2318,7 +2318,7 @@ items. Here's an example that makes two aliases for @end example When using aliases in menus, often it is useful to display the -equivalent key bindings for the ``real'' command name, not the aliases +equivalent key bindings for the real command name, not the aliases (which typically don't have any key bindings except for the menu itself). To request this, give the alias symbol a non-@code{nil} @code{menu-alias} property. Thus, @@ -2427,19 +2427,19 @@ Next we define the menu items: @end smallexample @noindent -Note the symbols which the bindings are ``made for''; these appear +Note the symbols which the bindings are made for; these appear inside square brackets, in the key sequence being defined. In some cases, this symbol is the same as the command name; sometimes it is -different. These symbols are treated as ``function keys'', but they are +different. These symbols are treated as function keys, but they are not real function keys on the keyboard. They do not affect the -functioning of the menu itself, but they are ``echoed'' in the echo area +functioning of the menu itself, but they are echoed in the echo area when the user selects from the menu, and they appear in the output of @code{where-is} and @code{apropos}. The menu in this example is intended for use with the mouse. If a menu is intended for use with the keyboard, that is, if it is bound to a key sequence ending with a keyboard event, then the menu items -should be bound to characters or ``real'' function keys, that can be +should be bound to characters or real function keys, that can be typed with the keyboard. The binding whose definition is @code{("--")} is a separator line. @@ -2475,15 +2475,15 @@ can do it this way: Emacs usually shows a @dfn{menu bar} at the top of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu bar items are -subcommands of the fake ``function key'' @code{menu-bar}, as defined +subcommands of the fake function key @code{menu-bar}, as defined in the active keymaps. - To add an item to the menu bar, invent a fake ``function key'' of your + To add an item to the menu bar, invent a fake function key of your own (let's call it @var{key}), and make a binding for the key sequence @code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, so that pressing a button on the menu bar item leads to another menu. - When more than one active keymap defines the same ``function key'' + When more than one active keymap defines the same function key for the menu bar, the item appears just once. If the user clicks on that menu bar item, it brings up a single, combined menu containing all the subcommands of that item---the global subcommands, the local @@ -2574,7 +2574,7 @@ If the value is @code{grow-only}, the tool bar expands automatically, but does not contract automatically. The tool bar contents are controlled by a menu keymap attached to a -fake ``function key'' called @code{tool-bar} (much like the way the menu +fake function key called @code{tool-bar} (much like the way the menu bar is controlled). So you define a tool bar item using @code{define-key}, like this: @@ -2583,7 +2583,7 @@ bar is controlled). So you define a tool bar item using @end example @noindent -where @var{key} is a fake ``function key'' to distinguish this item from +where @var{key} is a fake function key to distinguish this item from other items, and @var{item} is a menu item key binding (@pxref{Extended Menu Items}), which says how to display this item and how it behaves. @@ -2593,7 +2593,7 @@ tool bar bindings and have their normal meanings. The @var{real-binding} in the item must be a command, not a keymap; in other words, it does not work to define a tool bar icon as a prefix key. - The @code{:help} property specifies a ``help-echo'' string to display + The @code{:help} property specifies a help-echo string to display while the mouse is on that item. This is displayed in the same way as @code{help-echo} text properties (@pxref{Help display}). diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi index 947beeca23c..04aabd814fc 100644 --- a/doc/lispref/lay-flat.texi +++ b/doc/lispref/lay-flat.texi @@ -21,9 +21,9 @@ We have bound this manual using a new @dfn{lay-flat} binding technology. This type of binding allows you to open a soft cover book -so that it ``lays flat'' on a table without creasing the binding. +so that it lays flat on a table without creasing the binding. -In order to make the book lay flat properly, you need to ``crack'' the +In order to make the book lay flat properly, you need to crack the binding. To do this, divide the book into two sections and bend it so that the front and back covers meet. Do not worry; the pages are sewn and glued to the binding, and will not fall out easily. diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index a2e70a680ea..48e1b57eede 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -41,7 +41,7 @@ pronounced ``could-er''. We say that ``the @sc{car} of this cons cell is'' whatever object its @sc{car} slot currently holds, and likewise for the @sc{cdr}. - A list is a series of cons cells ``chained together'', so that each + A list is a series of cons cells chained together, so that each cell refers to the next one. There is one cons cell for each element of the list. By convention, the @sc{car}s of the cons cells hold the elements of the list, and the @sc{cdr}s are used to chain the list @@ -799,7 +799,7 @@ foo ;; @r{@code{foo} was changed.} @cindex destructive list operations You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the -primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' +primitives @code{setcar} and @code{setcdr}. These are destructive operations because they change existing list structure. @cindex CL note---@code{rplaca} vs @code{setcar} @@ -1035,9 +1035,9 @@ x1 @cindex reordering, of elements in lists @cindex modification of lists - Here are some functions that rearrange lists ``destructively'' by -modifying the @sc{cdr}s of their component cons cells. We call these -functions ``destructive'' because they chew up the original lists passed + Here are some functions that rearrange lists destructively by +modifying the @sc{cdr}s of their component cons cells. These functions +are destructive because they chew up the original lists passed to them as arguments, relinking their cons cells to form a new list that is the returned value. @@ -1522,7 +1522,7 @@ a @sc{cdr} @code{equal} to @var{value}. @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc}'', finding the key for a given value. +this as reverse @code{assoc}, finding the key for a given value. @end defun @defun assq key alist @@ -1563,7 +1563,7 @@ a @sc{cdr} @code{eq} to @var{value}. @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq}'', finding the key for a given value. +this as reverse @code{assq}, finding the key for a given value. For example: diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 91dc9a95390..f5352da59f7 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -40,7 +40,7 @@ For on-demand loading of external libraries, @pxref{Dynamic Libraries}. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to ``unload'' a library that was loaded. +* Unloading:: How to unload a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @end menu @@ -456,7 +456,7 @@ Autoloading can also be triggered by looking up the documentation of the function or macro (@pxref{Documentation Basics}). There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the +@code{autoload}, and by writing a magic comment in the source before the real definition. @code{autoload} is the low-level primitive for autoloading; any Lisp program can call @code{autoload} at any time. Magic comments are the most convenient way to make a function @@ -668,7 +668,7 @@ value of this variable is @code{";;;###autoload"}. @defvar generated-autoload-file The value of this variable names an Emacs Lisp file where the autoload calls should go. The default value is @file{loaddefs.el}, but you can -override that, e.g., in the ``Local Variables'' section of a +override that, e.g., in the local variables section of a @file{.el} file (@pxref{File Local Variables}). The autoload file is assumed to contain a trailer starting with a formfeed character. @end defvar diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index 7bdfee0a4ad..a90c6f1da6f 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -307,7 +307,7 @@ program is actually run. When defining a macro you must pay attention to the number of times the arguments will be evaluated when the expansion is executed. The following macro (used to facilitate iteration) illustrates the -problem. This macro allows us to write a ``for'' loop construct. +problem. This macro allows us to write a for-loop construct. @findex for @example @@ -345,7 +345,7 @@ For example, (for i from 1 to 10 do (print i))." @noindent The arguments @code{from}, @code{to}, and @code{do} in this macro are -``syntactic sugar''; they are entirely ignored. The idea is that you +syntactic sugar; they are entirely ignored. The idea is that you will write noise words (such as @code{from}, @code{to}, and @code{do}) in those positions in the macro call. @@ -568,7 +568,7 @@ If @code{initialize} is interpreted, a new list @code{(nil)} is constructed each time @code{initialize} is called. Thus, no side effect survives between calls. If @code{initialize} is compiled, then the macro @code{empty-object} is expanded during compilation, producing a -single ``constant'' @code{(nil)} that is reused and altered each time +single constant @code{(nil)} that is reused and altered each time @code{initialize} is called. One way to avoid pathological cases like this is to think of diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index 4f25b91506e..3eaba419034 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -20,8 +20,8 @@ deleted, so that it stays with the two characters on either side of it. * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. +* The Mark:: How the mark is implemented with a marker. +* The Region:: How to access the region. @end menu @node Overview of Markers @@ -404,7 +404,7 @@ This is another name for @code{set-marker}. Each buffer has a special marker, which is designated @dfn{the mark}. When a buffer is newly created, this marker exists but does -not point anywhere; this means that the mark ``doesn't exist'' in that +not point anywhere; this means that the mark doesn't exist in that buffer yet. Subsequent commands can set the mark. The mark specifies a position to bound a range of text for many @@ -424,7 +424,7 @@ sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished. - Once the mark ``exists'' in a buffer, it normally never ceases to + Once the mark exists in a buffer, it normally never ceases to exist. However, it may become @dfn{inactive}, if Transient Mark mode is enabled. The buffer-local variable @code{mark-active}, if non-@code{nil}, means that the mark is active. A command can call the @@ -620,7 +620,7 @@ This piece of command_loop_1, run unless deactivating the mark: @end defvar @defun handle-shift-selection -This function implements the ``shift-selection'' behavior of +This function implements the shift-selection behavior of point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs Manual}. It is called automatically by the Emacs command loop whenever a command with a @samp{^} character in its @code{interactive} @@ -661,8 +661,8 @@ more marks than this are pushed onto the @code{mark-ring}, @node The Region @section The Region -@c The index entry must be just ``region'' to make it the first hit -@c when the user types ``i region RET'', because otherwise the Info +@c The index entry must be just "region" to make it the first hit +@c when the user types "i region RET", because otherwise the Info @c reader will present substring matches in alphabetical order, @c putting this one near the end, with something utterly unrelated as @c the first hit. diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 2aec149524d..a035459abdb 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -81,7 +81,7 @@ there is an active minibuffer; such a minibuffer is called a incrementing the number at the end of the name. (The names begin with a space so that they won't show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently -entered) is the active minibuffer. We usually call this ``the'' +entered) is the active minibuffer. We usually call this @emph{the} minibuffer. You can permit or forbid recursive minibuffers by setting the variable @code{enable-recursive-minibuffers}, or by putting properties of that name on command symbols (@xref{Recursive Mini}.) @@ -143,7 +143,7 @@ reads the text and returns the resulting Lisp object, unevaluated. The argument @var{default} specifies default values to make available through the history commands. It should be a string, a list of strings, or @code{nil}. The string or strings become the minibuffer's -``future history'', available to the user with @kbd{M-n}. +future history, available to the user with @kbd{M-n}. If @var{read} is non-@code{nil}, then @var{default} is also used as the input to @code{read}, if the user enters empty input. @@ -194,8 +194,8 @@ in @code{read-from-minibuffer} it should be a string, a list of strings, or @code{nil}, which is equivalent to an empty string. When @var{default} is a string, that string is the default value. When it is a list of strings, the first string is the default value. (All -these strings are available to the user in the ``future minibuffer -history''.) +these strings are available to the user in the future minibuffer +history.) This function works by calling the @code{read-from-minibuffer} function: @@ -262,8 +262,8 @@ The last string or pattern used in query-replace commands. The function now has a list of regular expressions that it passes to @code{read-from-minibuffer} to obtain the user's input. The first element of the list is the default result in case of empty input. All -elements of the list are available to the user as the ``future -minibuffer history list'' (@pxref{Minibuffer History, future list,, +elements of the list are available to the user as the future +minibuffer history list (@pxref{Minibuffer History, future list,, emacs, The GNU Emacs Manual}). The optional argument @var{history}, if non-@code{nil}, is a symbol @@ -895,7 +895,7 @@ pertains to the area after @code{"/usr/"} and before @code{"/doc"}. @end defun If you store a completion alist in a variable, you should mark the -variable as ``risky'' by giving it a non-@code{nil} +variable as risky by giving it a non-@code{nil} @code{risky-local-variable} property. @xref{File Local Variables}. @defvar completion-ignore-case @@ -1958,7 +1958,7 @@ the call. This function asks the user a question, expecting input in the echo area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like +and @key{DEL} to mean no. It accepts @kbd{C-]} to quit, like @kbd{C-g}, because the question might look like a minibuffer and for that reason the user might try to use @kbd{C-]} to get out. The answer is a single character, with no @key{RET} needed to terminate it. Upper @@ -2049,7 +2049,7 @@ Do you really want to remove everything? (yes or no) @cindex multiple yes-or-no questions When you have a series of similar questions to ask, such as ``Do you -want to save this buffer'' for each buffer in turn, you should use +want to save this buffer?'' for each buffer in turn, you should use @code{map-y-or-n-p} to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at @@ -2120,7 +2120,7 @@ answer); @var{function} is a function of one argument (an object from When the user responds with @var{char}, @code{map-y-or-n-p} calls @var{function}. If it returns non-@code{nil}, the object is considered -``acted upon'', and @code{map-y-or-n-p} advances to the next object in +acted upon, and @code{map-y-or-n-p} advances to the next object in @var{list}. If it returns @code{nil}, the prompt is repeated for the same object. diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index a8b6bb19c5f..cbc8b78a0e8 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -116,7 +116,7 @@ This function runs an abnormal hook by calling all the hook functions in @defun run-hook-with-args-until-failure hook &rest args This function runs an abnormal hook by calling each hook function in -turn, stopping if one of them ``fails'' by returning @code{nil}. Each +turn, stopping if one of them fails by returning @code{nil}. Each hook function is passed the arguments @var{args}. If this function stops because one of the hook functions fails, it returns @code{nil}; otherwise it returns a non-@code{nil} value. @@ -124,7 +124,7 @@ otherwise it returns a non-@code{nil} value. @defun run-hook-with-args-until-success hook &rest args This function runs an abnormal hook by calling each hook function, -stopping if one of them ``succeeds'' by returning a non-@code{nil} +stopping if one of them succeeds by returning a non-@code{nil} value. Each hook function is passed the arguments @var{args}. If this function stops because one of the hook functions returns a non-@code{nil} value, it returns that value; otherwise it returns @@ -305,7 +305,7 @@ which documentation to print. @item The major mode command should set the variable @code{mode-name} to the -``pretty'' name of the mode, usually a string (but see @ref{Mode Line +pretty name of the mode, usually a string (but see @ref{Mode Line Data}, for other possible forms). The name of the mode appears in the mode line. @@ -346,14 +346,14 @@ reserved for users. A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and @kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally -be some kind of ``moving forward and backward'', but this does not +be some kind of moving forward and backward, but this does not necessarily mean cursor motion. It is legitimate for a major mode to rebind a standard key sequence if -it provides a command that does ``the same job'' in a way better +it provides a command that does the same job in a way better suited to the text this mode is used for. For example, a major mode for editing a programming language might redefine @kbd{C-M-a} to -``move to the beginning of a function'' in a way that works better for +move to the beginning of a function in a way that works better for that language. It is also legitimate for a major mode to rebind a standard key @@ -901,7 +901,7 @@ such a major mode, please correct it to follow these conventions. 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 @@ -1003,7 +1003,7 @@ should have the form @w{@code{(@var{id} @var{contents})}}, where @itemize @item @var{id} is either @code{nil}, or a Lisp object that identifies the -entry. If the latter, the cursor stays on the ``same'' entry when +entry. If the latter, the cursor stays on the same entry when re-sorting entries. Comparison is done with @code{equal}. @item @@ -1092,8 +1092,8 @@ documentation for the mode command. If you do not supply it, The argument @var{comment-list} is a list in which each element is either a character, a string of one or two characters, or a cons cell. A character or a string is set up in the mode's syntax table as a -``comment starter''. If the entry is a cons cell, the @sc{car} is set -up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''. +comment starter. If the entry is a cons cell, the @sc{car} is set +up as a comment starter and the @sc{cdr} as a comment ender. (Use @code{nil} for the latter if you want comments to end at the end of the line.) Note that the syntax table mechanism has limitations about what comment starters and enders are actually possible. @@ -1782,7 +1782,7 @@ symbol whose value is void. There is one exception: if the value of @var{symbol} is a string, it is displayed verbatim: the @code{%}-constructs are not recognized. -Unless @var{symbol} is marked as ``risky'' (i.e., it has a +Unless @var{symbol} is marked as risky (i.e., it has a non-@code{nil} @code{risky-local-variable} property), all text properties specified in @var{symbol}'s value are ignored. This includes the text properties of strings in @var{symbol}'s value, as well as all @@ -1974,7 +1974,7 @@ This variable is used to identify @code{emacsclient} frames. The following three variables are used in @code{mode-line-modes}: @defvar mode-name -This buffer-local variable holds the ``pretty'' name of the current +This buffer-local variable holds the pretty name of the current buffer's major mode. Each major mode should set this variable so that the mode name will appear in the mode line. The value does not have to be a string, but can use any of the data types valid in a mode-line @@ -2408,10 +2408,10 @@ variables @code{imenu-prev-index-position-function} and @defvar imenu-prev-index-position-function If this variable is non-@code{nil}, its value should be a function that -finds the next ``definition'' to put in the buffer index, scanning +finds the next definition to put in the buffer index, scanning backward in the buffer from point. It should return @code{nil} if it -doesn't find another ``definition'' before point. Otherwise it should -leave point at the place it finds a ``definition'' and return any +doesn't find another definition before point. Otherwise it should +leave point at the place it finds a definition and return any non-@code{nil} value. Setting this variable makes it buffer-local in the current buffer. @@ -3026,7 +3026,7 @@ default value is the symbol itself. Thus, the default value of @code{font-lock-comment-face} is @code{font-lock-comment-face}. The faces are listed with descriptions of their typical usage, and in -order of greater to lesser ``prominence''. If a mode's syntactic +order of greater to lesser prominence. If a mode's syntactic categories do not fit well with the usage descriptions, the faces can be assigned using the ordering as a guide. @@ -3126,7 +3126,7 @@ Table Functions}). @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 +point back to a position that is syntactically at top level and outside of strings or comments. The value is normally set through an @var{other-vars} element in @code{font-lock-defaults}. If it is @code{nil}, Font Lock uses @code{syntax-begin-function} to move back @@ -3338,13 +3338,13 @@ indentation code will want to be somewhat friendly to syntactically incorrect code. Good maintainable indentation functions usually fall into two categories: -either parsing forward from some ``safe'' starting point until the +either parsing forward from some safe starting point until the position of interest, or parsing backward from the position of interest. Neither of the two is a clearly better choice than the other: parsing backward is often more difficult than parsing forward because programming languages are designed to be parsed forward, but for the purpose of indentation it has the advantage of not needing to -guess a ``safe'' starting point, and it generally enjoys the property +guess a safe starting point, and it generally enjoys the property that only a minimum of text will be analyzed to decide the indentation of a line, so indentation will tend to be less affected by syntax errors in some earlier unrelated piece of code. Parsing forward on the other hand @@ -3370,8 +3370,8 @@ of Lisp sexps and adapts it to non-Lisp languages. @cindex SMIE SMIE is a package that provides a generic navigation and indentation -engine. Based on a very simple parser using an ``operator precedence -grammar'', it lets major modes extend the sexp-based navigation of Lisp +engine. Based on a very simple parser using an operator precedence +grammar, it lets major modes extend the sexp-based navigation of Lisp to non-Lisp languages as well as provide a simple to use but reliable auto-indentation. diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 8781cd6d696..99d128c0535 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -483,7 +483,7 @@ Corresponds to the Unicode @code{Numeric_Value} property for characters whose @code{Numeric_Type} is @samp{Decimal}. The value is an integer, or @code{nil} if the character has no decimal digit value. For unassigned codepoints, the value is @code{nil}, which means -@acronym{NaN}, or ``not-a-number''. +@acronym{NaN}, or not a number. @item digit-value Corresponds to the Unicode @code{Numeric_Value} property for @@ -1956,7 +1956,7 @@ and @ref{Invoking the Input Method}. @section Locales @cindex locale - POSIX defines a concept of ``locales'' which control which language + In POSIX, locales control which language to use in language-related features. These Emacs variables control how Emacs interacts with these features. diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 7b4a0a6d407..b329a10b084 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -224,7 +224,7 @@ distinguish them. @cindex NaN The @acronym{IEEE} floating-point standard supports positive infinity and negative infinity as floating-point values. It also -provides for a class of values called NaN or ``not-a-number''; +provides for a class of values called NaN or not a number; numerical functions return such values in cases where there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. Although NaN values carry a sign, for practical purposes there is no other @@ -812,7 +812,7 @@ Rounding a value equidistant between two integers returns the even integer. 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. @@ -989,17 +989,16 @@ Here are other examples: @end defun @defun logand &rest ints-or-markers -This function returns the ``logical and'' of the arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in all the arguments. (``Set'' means that the value of the bit is 1 -rather than 0.) +This function returns the bitwise AND of the arguments: the @var{n}th +bit is 1 in the result if, and only if, the @var{n}th bit is 1 in all +the arguments. -For example, using 4-bit binary numbers, the ``logical and'' of 13 and +For example, using 4-bit binary numbers, the bitwise AND of 13 and 12 is 12: 1101 combined with 1100 produces 1100. -In both the binary numbers, the leftmost two bits are set (i.e., they -are 1's), so the leftmost two bits of the returned value are set. -However, for the rightmost two bits, each is zero in at least one of -the arguments, so the rightmost two bits of the returned value are 0's. +In both the binary numbers, the leftmost two bits are both 1 +so the leftmost two bits of the returned value are both 1. +However, for the rightmost two bits, each is 0 in at least one of +the arguments, so the rightmost two bits of the returned value are both 0. @noindent Therefore, @@ -1040,9 +1039,9 @@ because its binary representation consists entirely of ones. If @end defun @defun logior &rest ints-or-markers -This function returns the ``inclusive or'' of its arguments: the @var{n}th bit -is set in the result if, and only if, the @var{n}th bit is set in at least -one of the arguments. If there are no arguments, the result is zero, +This function returns the bitwise inclusive OR of its arguments: the @var{n}th +bit is 1 in the result if, and only if, the @var{n}th bit is 1 in at +least one of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If @code{logior} is passed just one argument, it returns that argument. @@ -1065,9 +1064,9 @@ passed just one argument, it returns that argument. @end defun @defun logxor &rest ints-or-markers -This function returns the ``exclusive or'' of its arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in an odd number of the arguments. If there are no arguments, the +This function returns the bitwise exclusive OR of its arguments: the +@var{n}th bit is 1 in the result if, and only if, the @var{n}th bit is +1 in an odd number of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If @code{logxor} is passed just one argument, it returns that argument. @@ -1090,7 +1089,7 @@ result is 0, which is an identity element for this operation. If @end defun @defun lognot integer -This function returns the logical complement of its argument: the @var{n}th +This function returns the bitwise complement of its argument: the @var{n}th bit is one in the result if, and only if, the @var{n}th bit is zero in @var{integer}, and vice-versa. @@ -1218,7 +1217,7 @@ fashion. The numbers are not truly random, but they have certain properties that mimic a random series. For example, all possible values occur equally often in a pseudo-random series. - Pseudo-random numbers are generated from a ``seed''. Starting from + Pseudo-random numbers are generated from a seed. Starting from any given seed, the @code{random} function always generates the same sequence of numbers. By default, Emacs initializes the random seed at startup, in such a way that the sequence of values of @code{random} diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index c4c74ec7556..4a0ccc86561 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -18,7 +18,7 @@ possible objects. have similar structures and may usually be used in the same contexts. Types can overlap, and objects can belong to two or more types. Consequently, we can ask whether an object belongs to a particular type, -but not for ``the'' type of an object. +but not for @emph{the} type of an object. @cindex primitive type A few fundamental object types are built into Emacs. These, from @@ -310,7 +310,7 @@ vertical tab, formfeed, space, return, del, and escape as @samp{?\a}, @samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively. (@samp{?\s} followed by a dash has a different meaning---it applies -the ``super'' modifier to the following character.) Thus, +the super modifier to the following character.) Thus, @example ?\a @result{} 7 ; @r{control-g, @kbd{C-g}} @@ -329,7 +329,7 @@ the ``super'' modifier to the following character.) Thus, @cindex escape sequence These sequences which start with backslash are also known as @dfn{escape sequences}, because backslash plays the role of an -``escape character''; this terminology has nothing to do with the +escape character; this has nothing to do with the character @key{ESC}. @samp{\s} is meant for use in character constants; in string constants, just write the space. @@ -556,7 +556,7 @@ do such a thing. @cindex CL note---case of letters @quotation @b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. In Emacs +folded to upper case, unless they are explicitly escaped. In Emacs Lisp, upper case and lower case letters are distinct. @end quotation @@ -644,7 +644,7 @@ same object, @code{nil}. A @dfn{cons cell} is an object that consists of two slots, called the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any -Lisp object. We also say that ``the @sc{car} of this cons cell is'' +Lisp object. We also say that the @sc{car} of this cons cell is whatever object its @sc{car} slot currently holds, and likewise for the @sc{cdr}. @@ -660,13 +660,13 @@ of lists, we refer to any structure made out of cons cells as a @quotation A note to C programmers: a Lisp list thus works as a @dfn{linked list} built up of cons cells. Because pointers in Lisp are implicit, we do -not distinguish between a cons cell slot ``holding'' a value versus -``pointing to'' the value. +not distinguish between a cons cell slot holding a value versus +pointing to the value. @end quotation @cindex atoms Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell''. These objects are called +an object which is not a cons cell. These objects are called @dfn{atoms}. @cindex parenthesis @@ -695,10 +695,10 @@ hold @code{nil}. The names @sc{car} and @sc{cdr} derive from the history of Lisp. The original Lisp implementation ran on an @w{IBM 704} computer which -divided words into two parts, called the ``address'' part and the -``decrement''; @sc{car} was an instruction to extract the contents of +divided words into two parts, the address and the +decrement; @sc{car} was an instruction to extract the contents of the address part of a register, and @sc{cdr} an instruction to extract -the contents of the decrement. By contrast, ``cons cells'' are named +the contents of the decrement. By contrast, cons cells are named for the function @code{cons} that creates them, which in turn was named for its purpose, the construction of cells. @@ -737,7 +737,7 @@ represents a reference to a Lisp object, either an atom or another cons cell. In this example, the first box, which holds the @sc{car} of the first -cons cell, refers to or ``holds'' @code{rose} (a symbol). The second +cons cell, refers to or holds @code{rose} (a symbol). The second box, holding the @sc{cdr} of the first cons cell, refers to the next pair of boxes, the second cons cell. The @sc{car} of the second cons cell is @code{violet}, and its @sc{cdr} is the third cons cell. The @@ -1176,7 +1176,7 @@ a whole character set. @cindex @samp{#^} read syntax The printed representation of a char-table is like a vector except that there is an extra @samp{#^} at the beginning.@footnote{You -may also encounter @samp{#^^}, used for ``sub-char-tables''.} +may also encounter @samp{#^^}, used for sub-char-tables.} @xref{Char-Tables}, for special functions to operate on char-tables. Uses of char-tables include: @@ -1204,7 +1204,7 @@ be @code{t} or @code{nil}. The printed representation of a bool-vector is like a string, except that it begins with @samp{#&} followed by the length. The string constant that follows actually specifies the contents of the bool-vector -as a bitmap---each ``character'' in the string contains 8 bits, which +as a bitmap---each character in the string contains 8 bits, which specify the next 8 elements of the bool-vector (1 stands for @code{t}, and 0 for @code{nil}). The least significant bits of the character correspond to the lowest indices in the bool-vector. @@ -1423,7 +1423,7 @@ buffer}. The contents of a buffer are much like a string, but buffers are not used like strings in Emacs Lisp, and the available operations are different. For example, you can insert text efficiently into an -existing buffer, altering the buffer's contents, whereas ``inserting'' +existing buffer, altering the buffer's contents, whereas inserting text into a string requires concatenating substrings, and the result is an entirely new string object. @@ -1715,7 +1715,7 @@ look alike but are not the same Lisp object. This shows the difference: @end example You can also use the same syntax to make a circular structure, which -appears as an ``element'' within itself. Here is an example: +appears as an element within itself. Here is an example: @example #1=(a #1#) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 6ef87dfbd53..ca4b1f07403 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -725,7 +725,7 @@ another application without doing anything special to Emacs. @c have SIGTSTP? @cindex SIGTSTP Some operating systems (those without @code{SIGTSTP}, or MS-DOS) do -not support suspension of jobs; on these systems, ``suspension'' +not support suspension of jobs; on these systems, suspension actually creates a new shell temporarily as a subprocess of Emacs. Then you would exit the shell to return to Emacs. @@ -1013,9 +1013,9 @@ process-environment @end group @end smallexample -If @code{process-environment} contains ``duplicate'' elements that +If @code{process-environment} contains multiple elements that specify the same environment variable, the first of these elements -specifies the variable, and the other ``duplicates'' are ignored. +specifies the variable, and the others are ignored. @end defvar @defvar initial-environment @@ -1167,7 +1167,7 @@ user-id or login name that isn't defined, it returns @code{nil}. The symbols @code{user-login-name}, @code{user-real-login-name} and @code{user-full-name} are variables as well as functions. The functions return the same values that the variables hold. These variables allow -you to ``fake out'' Emacs by telling the functions what to return. The +you to fake out Emacs by telling the functions what to return. The variables are also useful for constructing frame titles (@pxref{Frame Titles}). @@ -1545,13 +1545,13 @@ because that is how @samp{%S} normally pads to two positions. The characters @samp{E} and @samp{O} act as modifiers when used between @samp{%} and one of the letters in the table above. @samp{E} specifies -using the current locale's ``alternative'' version of the date and time. +using the current locale's alternative version of the date and time. In a Japanese locale, for example, @code{%Ex} might yield a date format based on the Japanese Emperors' reigns. @samp{E} is allowed in @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and @samp{%EY}. -@samp{O} means to use the current locale's ``alternative'' +@samp{O} means to use the current locale's alternative representation of numbers, instead of the ordinary decimal digits. This is allowed with most letters, all the ones that output numbers. @@ -1922,7 +1922,7 @@ This is a convenient way to test whether Emacs is idle. @end defun The main use of @code{current-idle-time} is when an idle timer -function wants to ``take a break'' for a while. It can set up another +function wants to take a break for a while. It can set up another idle timer to call the same function again, after a few seconds more idleness. Here's an example: @@ -2192,7 +2192,7 @@ To define system-specific X11 keysyms, set the variable This variable's value should be an alist with one element for each system-specific keysym. Each element has the form @code{(@var{code} . @var{symbol})}, where @var{code} is the numeric keysym code (not -including the ``vendor specific'' bit, +including the vendor-specific bit, @ifnottex @minus{}2**28), @end ifnottex diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 7136286f0ba..21a8ddd5d03 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -292,7 +292,7 @@ case for the default GNU archive). Otherwise, the base location should be a directory name. In this case, Emacs retrieves packages from this archive via ordinary file -access. Such ``local'' archives are mainly useful for testing. +access. Such local archives are mainly useful for testing. @end defopt A package archive is simply a directory in which the package files, diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index 200935d5c60..75b29c1d395 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -22,11 +22,11 @@ be a position (an integer), but accept a marker as a substitute, normally ignore which buffer the marker points into; they convert the marker to an integer, and use that integer, exactly as if you had passed the integer as the argument, even if the marker points to the -``wrong'' buffer. A marker that points nowhere cannot convert to an +wrong buffer. A marker that points nowhere cannot convert to an integer; using it instead of an integer causes an error. @xref{Markers}. - See also the ``field'' feature (@pxref{Fields}), which provides + See also the field feature (@pxref{Fields}), which provides functions that are used by many cursor-motion commands. @menu @@ -227,7 +227,7 @@ backward until encountering the front of a word, rather than forward. @c Emacs 19 feature This variable affects the behavior of @code{forward-word} and everything that uses it. If it is non-@code{nil}, then characters in the -``escape'' and ``character quote'' syntax classes count as part of +escape and character-quote syntax classes count as part of words. Otherwise, they do not. @end defopt @@ -409,7 +409,7 @@ mentioned here only for completeness. @deffn Command previous-line count @cindex goal column This function moves point up @var{count} lines (down if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' +is negative). In moving, it attempts to keep point in the goal column (normally the same column that it was at the beginning of the move). If there is no character in the target line exactly under the current @@ -434,7 +434,7 @@ to use and more reliable (no dependence on goal column, etc.). @deffn Command next-line count This function moves point down @var{count} lines (up if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' +is negative). In moving, it attempts to keep point in the goal column (normally the same column that it was at the beginning of the move). If there is no character in the target line exactly under the current @@ -827,7 +827,7 @@ is zero or less. @section Excursions @cindex excursion - It is often useful to move point ``temporarily'' within a localized + It is often useful to move point temporarily within a localized portion of the program. This is called an @dfn{excursion}, and it is done with the @code{save-excursion} special form. This construct remembers the initial identity of the current buffer, and its value @@ -862,7 +862,7 @@ consequences, so the byte compiler warns if you call @code{set-buffer} during an excursion: @example -Warning: Use `with-current-buffer' rather than +Warning: Use ‘with-current-buffer’ rather than save-excursion+set-buffer @end example diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index c9509b0f216..a62a8b6b4ad 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -734,7 +734,7 @@ Initialize the process query flag to @var{query-flag}. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the process in the -``stopped'' state. +stopped state. @item :filter @var{filter} Initialize the process filter to @var{filter}. @@ -786,7 +786,7 @@ Initialize the process query flag to @var{query-flag}. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the process in the -``stopped'' state. +stopped state. @item :filter @var{filter} Initialize the process filter to @var{filter}. @@ -1070,7 +1070,7 @@ This function sets the process plist of @var{process} to @var{plist}. Asynchronous subprocesses receive input when it is sent to them by Emacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. The -data appears on the ``standard input'' of the subprocess. +data appears on the standard input of the subprocess. @c FIXME which? Some operating systems have limited space for buffered input in a @@ -1189,10 +1189,10 @@ job-control shells won't work when a pipe is used. See @defun interrupt-process &optional process current-group This function interrupts the process @var{process} by sending the -signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt -character'' (normally @kbd{C-c} on some systems, and @key{DEL} on +signal @code{SIGINT}. Outside of Emacs, typing the interrupt +character (normally @kbd{C-c} on some systems, and @key{DEL} on others) sends this signal. When the argument @var{current-group} is -non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' +non-@code{nil}, you can think of this function as typing @kbd{C-c} on the terminal by which Emacs talks to the subprocess. @end defun @@ -1204,10 +1204,8 @@ and cannot be handled by the subprocess. @defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process -@var{process}. This signal is the one sent by the ``quit -@c FIXME? Never heard of C-b being used for this. In readline, e.g., -@c bash, that is backward-word. -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside +@var{process}. This signal is the one sent by the quit +character (usually @kbd{C-\}) when you are not inside Emacs. @end defun @@ -1216,10 +1214,10 @@ This function stops the process @var{process} by sending the signal @code{SIGTSTP}. Use @code{continue-process} to resume its execution. -Outside of Emacs, on systems with job control, the ``stop character'' +Outside of Emacs, on systems with job control, the stop character (usually @kbd{C-z}) normally sends this signal. When @var{current-group} is non-@code{nil}, you can think of this function as -``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the +typing @kbd{C-z} on the terminal Emacs uses to communicate with the subprocess. @end defun @@ -1849,7 +1847,7 @@ interruptible sleep (waiting for some event) @item "T" stopped, e.g., by a job control signal @item "Z" -``zombie'': a process that terminated, but was not reaped by its parent +zombie: a process that terminated, but was not reaped by its parent @end table @noindent @@ -2074,7 +2072,7 @@ server is stopped; a non-@code{nil} value means yes. @cindex @acronym{STARTTLS} network connections Emacs can create encrypted network connections, using either built-in or external support. The built-in support uses the GnuTLS -(``Transport Layer Security'') library; see +Transport Layer Security Library; see @uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}. If your Emacs was compiled with GnuTLS support, the function @code{gnutls-available-p} is defined and returns non-@code{nil}. For @@ -2118,7 +2116,7 @@ The type of connection. Options are: An ordinary, unencrypted connection. @item tls @itemx ssl -A @acronym{TLS} (``Transport Layer Security'') connection. +A @acronym{TLS} (Transport Layer Security) connection. @item nil @itemx network Start with a plain connection, and if parameters @samp{:success} @@ -2306,7 +2304,7 @@ necessary to make it unique. @item :type @var{type} Specify the communication type. A value of @code{nil} specifies a stream connection (the default); @code{datagram} specifies a datagram -connection; @code{seqpacket} specifies a ``sequenced packet stream'' +connection; @code{seqpacket} specifies a sequenced packet stream connection. Both connections and servers can be of these types. @item :server @var{server-flag} @@ -2373,7 +2371,7 @@ A local address is represented as a string, which specifies the address in the local address space. @item -An ``unsupported family'' address is represented by a cons +An unsupported-family address is represented by a cons @code{(@var{f} . @var{av})}, where @var{f} is the family number and @var{av} is a vector specifying the socket address using one element per address data byte. Do not rely on this format in portable code, @@ -2392,7 +2390,7 @@ has succeeded or failed. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the network connection or -server in the ``stopped'' state. +server in the stopped state. @item :buffer @var{buffer} Use @var{buffer} as the process buffer. @@ -2540,7 +2538,7 @@ Non-@code{nil} if non-blocking connect is supported. @item (:type datagram) Non-@code{nil} if datagrams are supported. @item (:family local) -Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported. +Non-@code{nil} if local (a.k.a.@: UNIX domain) sockets are supported. @item (:family ipv6) Non-@code{nil} if IPv6 is supported. @item (:service t) @@ -2700,7 +2698,7 @@ Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. The flags defaults to @code{nil} if unspecified. @item :stop @var{bool} -Start process in the ``stopped'' state if @var{bool} is +Start process in the stopped state if @var{bool} is non-@code{nil}. In the stopped state, a serial process does not accept incoming data, but you can send outgoing data. The stopped state is cleared by @code{continue-process} and set by @@ -2830,7 +2828,7 @@ specification}, a special nested list describing named and typed @dfn{fields}. This specification controls the length of each field to be processed, and how to pack or unpack it. We normally keep bindat specs in variables whose names end in @samp{-bindat-spec}; that kind of name -is automatically recognized as ``risky''. +is automatically recognized as risky. @cindex endianness @cindex big endian @@ -2839,8 +2837,8 @@ is automatically recognized as ``risky''. A field's @dfn{type} describes the size (in bytes) of the object that the field represents and, in the case of multibyte fields, how the bytes are ordered within the field. The two possible orderings -are ``big endian'' (also known as ``network byte ordering'') and -``little endian''. For instance, the number @code{#x23cd} (decimal +are big endian (also known as network byte ordering) and +little endian. For instance, the number @code{#x23cd} (decimal 9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; and in little endian, @code{#xcd} @code{#x23}. Here are the possible type values: diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 60360cb98a9..6dc4a16c765 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -113,7 +113,7 @@ match. @end deffn @deffn Command word-search-forward string &optional limit noerror repeat -This function searches forward from point for a ``word'' match for +This function searches forward from point for a word match for @var{string}. If it finds a match, it sets point to the end of the match found, and returns the new value of point. @@ -359,7 +359,7 @@ preceding expression either once or not at all. For example, @item @samp{*?}, @samp{+?}, @samp{??} @cindex non-greedy repetition characters in regexp -These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} +These are non-greedy variants of the operators @samp{*}, @samp{+} and @samp{?}. Where those operators match the largest possible substring (consistent with matching the entire containing expression), the non-greedy variants match the smallest possible substring @@ -1127,7 +1127,7 @@ avoids modifying the match data. @defun looking-at regexp This function determines whether the text in the current buffer directly following point matches the regular expression @var{regexp}. ``Directly -following'' means precisely that: the search is ``anchored'' and it can +following'' means precisely that: the search is anchored and it can succeed only starting with the first character following point. The result is @code{t} if so, @code{nil} otherwise. @@ -1759,18 +1759,18 @@ in two ways: @itemize @bullet @item -The ``key bindings'' are not commands, just symbols that are meaningful +The key bindings are not commands, just symbols that are meaningful to the functions that use this map. @item Prefix keys are not supported; each key binding must be for a single-event key sequence. This is because the functions don't use @code{read-key-sequence} to get the input; instead, they read a single -event and look it up ``by hand''. +event and look it up by hand. @end itemize @end defvar -Here are the meaningful ``bindings'' for @code{query-replace-map}. +Here are the meaningful bindings for @code{query-replace-map}. Several of them are meaningful only for @code{query-replace} and friends. @@ -1835,7 +1835,7 @@ Display some help, then ask again. @defvar multi-query-replace-map This variable holds a keymap that extends @code{query-replace-map} by providing additional keybindings that are useful in multi-buffer -replacements. The additional ``bindings'' are: +replacements. The additional bindings are: @table @code @item automatic-all diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 18120dad575..f38aa350963 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -342,7 +342,7 @@ order elements according to different criteria. The argument @var{predicate} must be a function that accepts two arguments. It is called with two elements of @var{sequence}. To get an increasing order sort, the @var{predicate} should return non-@code{nil} if the -first element is ``less than'' the second, or @code{nil} if not. +first element is less than the second, or @code{nil} if not. The comparison function @var{predicate} must give reliable results for any given pair of arguments, at least within a single call to @@ -1490,7 +1490,7 @@ deletion, rotation, and modulo-indexed reference and traversal. An efficient ring data structure is implemented by the @code{ring} package. It provides the functions listed in this section. - Note that several ``rings'' in Emacs, like the kill ring and the + Note that several rings in Emacs, like the kill ring and the mark ring, are actually implemented as simple lists, @emph{not} using the @code{ring} package; thus the following functions won't work on them. diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index dfad2d83d54..025b0e95c4e 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -113,8 +113,8 @@ When it is called with no arguments, it should return the next character. When it is called with one argument (always a character), @var{function} should save the argument and arrange to return it on the next call. This is called @dfn{unreading} the character; it happens when the Lisp -reader reads one character too many and wants to ``put it back where it -came from''. In this case, it makes no difference what value +reader reads one character too many and wants to put it back where it +came from. In this case, it makes no difference what value @var{function} returns. @end itemize @@ -701,7 +701,7 @@ returns @code{"The buffer is foo"}. @defun pp object &optional stream This function outputs @var{object} to @var{stream}, just like -@code{prin1}, but does it in a more ``pretty'' way. That is, it'll +@code{prin1}, but does it in a prettier way. That is, it'll indent and fill the object to make it more readable for humans. @end defun diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index f42250719e5..b2fe60c93cc 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -343,7 +343,7 @@ three previous examples are rarely relevant: @end example Somewhat odd, but predictable, behavior can occur for certain -``non-greedy'' values of @var{separators} that can prefer empty +non-greedy values of @var{separators} that can prefer empty matches over non-empty matches. Again, such values rarely occur in practice: @@ -644,7 +644,7 @@ string. Likewise, the specified part of @var{string2} runs from index @var{start2} up to index @var{end2}. The strings are compared by the numeric values of their characters. -For instance, @var{str1} is considered ``smaller than'' @var{str2} if +For instance, @var{str1} is considered less than @var{str2} if its first differing character has a smaller numeric value. If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case before comparing them. Unibyte strings are converted to @@ -685,7 +685,7 @@ against a string, can be used for a kind of string comparison; see strings and integers. @code{format} (@pxref{Formatting Strings}) and @code{prin1-to-string} (@pxref{Output Functions}) can also convert Lisp objects into strings. @code{read-from-string} (@pxref{Input -Functions}) can ``convert'' a string representation of a Lisp object +Functions}) can convert a string representation of a Lisp object into an object. The functions @code{string-to-multibyte} and @code{string-to-unibyte} convert the text representation of a string (@pxref{Converting Representations}). @@ -990,7 +990,7 @@ numbers and negative numbers use the same number of columns. They are ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if both flags are used, @samp{+} takes precedence. - The flag @samp{#} specifies an ``alternate form'' which depends on + The flag @samp{#} specifies an alternate form which depends on the format in use. For @samp{%o}, it ensures that the result begins with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, @@ -1245,8 +1245,8 @@ Exits}). Some language environments modify the case conversions of @acronym{ASCII} characters; for example, in the Turkish language -environment, the @acronym{ASCII} character @samp{I} is downcased into -a Turkish ``dotless i''. This can interfere with code that requires +environment, the @acronym{ASCII} capital I is downcased into +a Turkish dotless i (@samp{ı}). This can interfere with code that requires ordinary @acronym{ASCII} case conversion, such as implementations of @acronym{ASCII}-based network protocols. In that case, use the @code{with-case-table} macro with the variable @var{ascii-case-table}, diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index a6545eae732..e6dc4df629e 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -35,7 +35,7 @@ otherwise. @section Symbol Components @cindex symbol components - Each symbol has four components (or ``cells''), each of which + Each symbol has four components (or cells), each of which references another object: @table @asis @@ -176,7 +176,7 @@ cause complete confusion. @cindex obarray @cindex bucket (in obarray) When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it ``hashes'' those characters to find an index in a +of the name. Then it hashes those characters to find an index in a table called an @dfn{obarray}. Hashing is an efficient method of looking something up. For example, instead of searching a telephone book cover to cover when looking up Jan Jones, you start with the J's @@ -525,7 +525,7 @@ The value is an expression for determining whether the named menu item should be enabled in menus. @xref{Simple Menu Items}. @item mode-class -If the value is @code{special}, the named major mode is ``special''. +If the value is @code{special}, the named major mode is special. @xref{Major Mode Conventions}. @item permanent-local diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 5d9935dc556..7a984e3d87b 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -98,7 +98,7 @@ serves as the name of the class when you need to specify a class. Usually, this designator character is one that is often assigned that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has. Thus, -@samp{\} as a designator character always means ``escape character'' +@samp{\} as a designator character always stands for escape character syntax, regardless of whether the @samp{\} character actually has that syntax in the current syntax table. @ifnottex @@ -377,7 +377,7 @@ character does not have the @samp{b} flag. @end table @item -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. +@samp{p} identifies an additional prefix character for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled according to their usual syntax classes. @@ -640,7 +640,7 @@ expression prefix syntax class, and characters with the @samp{p} flag. expressions. We will refer to such expressions as @dfn{sexps}, following the terminology of Lisp, even though these functions can act on languages other than Lisp. Basically, a sexp is either a balanced -parenthetical grouping, a string, or a ``symbol'' (i.e., a sequence +parenthetical grouping, a string, or a symbol (i.e., a sequence of characters whose syntax is either word constituent or symbol constituent). However, characters in the expression prefix syntax class (@pxref{Syntax Class Table}) are treated as part of the sexp if @@ -654,7 +654,7 @@ higher-level functions for moving over balanced expressions. A character's syntax controls how it changes the state of the parser, rather than describing the state itself. For example, a string delimiter character toggles the parser state between -``in-string'' and ``in-code'', but the syntax of characters does not +in-string and in-code, but the syntax of characters does not directly say whether they are inside a string. For example (note that 15 is the syntax code for generic string delimiters), @@ -731,7 +731,7 @@ number of complete comments. If @var{count} comments are found as expected, with nothing except whitespace between them, it returns @code{t}; otherwise it returns @code{nil}. -This function cannot tell whether the ``comments'' it traverses are +This function cannot tell whether the comments it traverses are embedded within a string. If they look like comments, it treats them as comments. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 55e550a7b80..45e923218d7 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -58,7 +58,7 @@ the character after point. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. * Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes ``atomically''. +* Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -578,7 +578,7 @@ error; if some of the text in it is read-only, it signals a asking for any confirmation. It returns @code{nil}. Normally, deleting a large amount of text from a buffer inhibits further -auto-saving of that buffer ``because it has shrunk''. However, +auto-saving of that buffer because it has shrunk. However, @code{erase-buffer} does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text. @@ -825,7 +825,7 @@ buffer if the variable @code{delete-trailing-lines} is non-@code{nil}. it so that the user can reinsert it by @dfn{yanking}. Most of these functions have @samp{kill-} in their name. By contrast, the functions whose names start with @samp{delete-} normally do not save text for -yanking (though they can still be undone); these are ``deletion'' +yanking (though they can still be undone); these are deletion functions. Most of the kill commands are primarily for interactive use, and are @@ -846,8 +846,8 @@ that treat it as a ring. Some people think this use of the word ``kill'' is unfortunate, since it refers to operations that specifically @emph{do not} destroy the -entities ``killed''. This is in sharp contrast to ordinary life, in -which death is permanent and ``killed'' entities do not come back to +entities killed. This is in sharp contrast to ordinary life, in +which death is permanent and killed entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term ``cut ring'' makes sense to people who, in pre-computer days, used scissors and paste to cut up and rearrange manuscripts. However, it @@ -882,9 +882,9 @@ succession build up a single kill ring entry, which would be yanked as a unit; the second and subsequent consecutive kill commands add text to the entry made by the first one. - For yanking, one entry in the kill ring is designated the ``front'' of -the ring. Some yank commands ``rotate'' the ring by designating a -different element as the ``front''. But this virtual rotation doesn't + For yanking, one entry in the kill ring is designated the front of +the ring. Some yank commands rotate the ring by designating a +different element as the front. But this virtual rotation doesn't change the list itself---the most recent entry always comes first in the list. @@ -892,7 +892,7 @@ list. @subsection Functions for Killing @code{kill-region} is the usual subroutine for killing text. Any -command that calls this function is a ``kill command'' (and should +command that calls this function is a kill command (and should probably have @samp{kill} in its name). @code{kill-region} puts the newly killed text in a new element at the beginning of the kill ring or adds it to the most recent element. It determines automatically (using @@ -1101,7 +1101,7 @@ because they take care of interaction with window system selections @defun current-kill n &optional do-not-move The function @code{current-kill} rotates the yanking pointer, which -designates the ``front'' of the kill ring, by @var{n} places (from newer +designates the front of the kill ring, by @var{n} places (from newer kills to older ones), and returns the text at that place in the ring. If the optional second argument @var{do-not-move} is non-@code{nil}, @@ -1148,13 +1148,13 @@ programs, when you are using a window system. Its value should be @code{nil} or a function of no arguments. If the value is a function, @code{current-kill} calls it to get the -``most recent kill''. If the function returns a non-@code{nil} value, -then that value is used as the ``most recent kill''. If it returns +most recent kill. If the function returns a non-@code{nil} value, +then that value is used as the most recent kill. If it returns @code{nil}, then the front of the kill ring is used. To facilitate support for window systems that support multiple selections, this function may also return a list of strings. In that -case, the first string is used as the ``most recent kill'', and all +case, the first string is used as the most recent kill, and all the other strings are pushed onto the kill ring, for easy access by @code{yank-pop}. @@ -1186,7 +1186,7 @@ of the list. The @code{kill-ring-yank-pointer} variable points to a link in the kill ring list, whose @sc{car} is the text to yank next. We say it -identifies the ``front'' of the ring. Moving +identifies the front of the ring. Moving @code{kill-ring-yank-pointer} to a different link is called @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because the functions that move the yank pointer wrap around from the end of the @@ -1238,7 +1238,7 @@ killed first. @defvar kill-ring-yank-pointer This variable's value indicates which element of the kill ring is at the -``front'' of the ring for yanking. More precisely, the value is a tail +front of the ring for yanking. More precisely, the value is a tail of the value of @code{kill-ring}, and its @sc{car} is the kill string that @kbd{C-y} should yank. @end defvar @@ -1423,7 +1423,7 @@ cannot specify any other buffer. This function returns @code{nil}. As editing continues, undo lists get longer and longer. To prevent them from using up all available memory space, garbage collection trims -them back to size limits you can set. (For this purpose, the ``size'' +them back to size limits you can set. (For this purpose, the size of an undo list measures the cons cells that make up the list, plus the strings of deleted text.) Three variables control the range of acceptable sizes: @code{undo-limit}, @code{undo-strong-limit} and @@ -1648,8 +1648,8 @@ Manual}. @defvar use-hard-newlines If this variable is non-@code{nil}, the filling functions do not delete -newlines that have the @code{hard} text property. These ``hard -newlines'' act as paragraph separators. @xref{Hard and Soft +newlines that have the @code{hard} text property. These hard +newlines act as paragraph separators. @xref{Hard and Soft Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. @end defvar @@ -1823,7 +1823,7 @@ Used only in one-line paragraphs, this regular expression acts as an additional check of the validity of the one available candidate fill prefix: the candidate must match this regular expression, or match @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} -replaces the candidate with a string of spaces ``of the same width'' +replaces the candidate with a string of spaces of the same width as it. The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which @@ -1836,7 +1836,7 @@ whitespace. You can specify more complex ways of choosing a fill prefix automatically by setting this variable to a function. The function is called with point after the left margin (if any) of a line, and it -must preserve point. It should return either ``that line's'' fill +must preserve point. It should return either that line's fill prefix or @code{nil}, meaning it has failed to determine a prefix. @end defopt @@ -2382,7 +2382,7 @@ a different meaning and does not use this variable. @deffn Command indent-rigidly start end count This function indents all lines starting between @var{start} (inclusive) and @var{end} (exclusive) sideways by @var{count} columns. -This ``preserves the shape'' of the affected region, moving it as a +This preserves the shape of the affected region, moving it as a rigid unit. This is useful not only for indenting regions of unindented text, but @@ -2481,10 +2481,10 @@ column, this command does nothing. @end deffn @node Indent Tabs -@subsection Adjustable ``Tab Stops'' +@subsection Adjustable Tab Stops @cindex tabs stops for indentation - This section explains the mechanism for user-specified ``tab stops'' + This section explains the mechanism for user-specified tab stops and the mechanisms that use and set them. The name ``tab stops'' is used because the feature is similar to that of the tab stops on a typewriter. The feature works by inserting an appropriate number of @@ -3165,7 +3165,7 @@ This property says whether the text is ready for display. If @code{nil}, Emacs's redisplay routine calls the functions in @code{fontification-functions} (@pxref{Auto Faces}) to prepare this part of the buffer before it is displayed. It is used internally by -the ``just in time'' font locking code. +the just-in-time font locking code. @item display This property activates various features that change the @@ -3487,7 +3487,7 @@ are used for representing formatted text. @xref{Filling}, and @table @code @item hard -If a newline character has this property, it is a ``hard'' newline. +If a newline character has this property, it is a hard newline. The fill commands do not alter hard newlines and do not move words across them. However, this property takes effect only if the @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft @@ -3623,8 +3623,8 @@ once for the same part of the buffer, you can use the variable @defvar buffer-access-fontified-property If this variable's value is non-@code{nil}, it is a symbol which is used as a text property name. A non-@code{nil} value for that text property -means, ``the other text properties for this character have already been -computed''. +means the other text properties for this character have already been +computed. If all the characters in the range specified for @code{buffer-substring} have a non-@code{nil} value for this property, @code{buffer-substring} @@ -3742,10 +3742,10 @@ controlled by the user option @code{mouse-1-click-follows-link}. bind the @code{follow-link} event to a keymap (which can be a major mode keymap or a local keymap specified via the @code{keymap} text property). The value of the @code{follow-link} property, or the -binding for the @code{follow-link} event, acts as a ``condition'' for +binding for the @code{follow-link} event, acts as a condition for the link action. This condition tells Emacs two things: the circumstances under which a @kbd{Mouse-1} click should be regarded as -occurring ``inside'' the link, and how to compute an ``action code'' +occurring inside the link, and how to compute an action code that says what to translate the @kbd{Mouse-1} click into. The link action condition can be one of the following: @@ -3911,7 +3911,7 @@ This function deletes the text of the field specified by @var{pos}. @end defun @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property -This function ``constrains'' @var{new-pos} to the field that +This function constrains @var{new-pos} to the field that @var{old-pos} belongs to---in other words, it returns the position closest to @var{new-pos} that is in the same field as @var{old-pos}. @@ -3929,7 +3929,7 @@ after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, @var{new-pos} can be anywhere in the two adjacent fields. Additionally, if two fields are separated by another field with the special value @code{boundary}, then any point within this special -field is also considered to be ``on the boundary''. +field is also considered to be on the boundary. Commands like @kbd{C-a} with no argument, that normally move backward to a specific kind of location and stay there once there, probably @@ -3957,7 +3957,7 @@ You can cause @code{constrain-to-field} to ignore all field boundaries @cindex intervals Some editors that support adding attributes to text in the buffer do -so by letting the user specify ``intervals'' within the text, and adding +so by letting the user specify intervals within the text, and adding the properties to the intervals. Those editors permit the user or the programmer to determine where individual intervals start and end. We deliberately provided a different sort of interface in Emacs Lisp to @@ -3975,7 +3975,7 @@ Then if you yank back the killed text, you get two intervals with the same properties. Thus, editing does not preserve the distinction between one interval and two. - Suppose we ``fix'' this problem by coalescing the two intervals when + Suppose we attempt to fix this problem by coalescing the two intervals when the text is inserted. That works fine if the buffer originally was a single interval. But suppose instead that we have two adjacent intervals with the same properties, and we kill the text of one interval @@ -4277,7 +4277,7 @@ The decoding functions ignore newline characters in the encoded text. @cindex cryptographic hash Emacs has built-in support for computing @dfn{cryptographic hashes}. -A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint'' +A cryptographic hash, or @dfn{checksum}, is a digital fingerprint of a piece of data (e.g., a block of text) which can be used to check that you have an unaltered copy of that data. @@ -4286,7 +4286,7 @@ that you have an unaltered copy of that data. SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the oldest of these algorithms, and is commonly used in @dfn{message digests} to check the integrity of messages transmitted over a -network. MD5 is not ``collision resistant'' (i.e., it is possible to +network. MD5 is not collision resistant (i.e., it is possible to deliberately design different pieces of data which have the same MD5 hash), so you should not used it for anything security-related. A similar theoretical weakness also exists in SHA-1. Therefore, for @@ -4347,7 +4347,7 @@ are available to parse HTML or XML text into Lisp object trees. @defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as HTML, and returns a list representing the HTML @dfn{parse tree}. It -attempts to handle ``real world'' HTML by robustly coping with syntax +attempts to handle real-world HTML by robustly coping with syntax mistakes. The optional argument @var{base-url}, if non-@code{nil}, should be a @@ -4559,7 +4559,7 @@ lower-level functions that @code{atomic-change-group} uses. @defun prepare-change-group &optional buffer This function sets up a change group for buffer @var{buffer}, which -defaults to the current buffer. It returns a ``handle'' that +defaults to the current buffer. It returns a handle that represents the change group. You must use this handle to activate the change group and subsequently to finish it. @end defun diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 3bde0a877ab..aa78c735c3f 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -398,7 +398,7 @@ Enter the answer (default 42): @item In @code{interactive}, if you use a Lisp expression to produce a list -of arguments, don't try to provide the ``correct'' default values for +of arguments, don't try to provide the correct default values for region or position arguments. Instead, provide @code{nil} for those arguments if they were not specified, and have the function body compute the default value when the argument is @code{nil}. For @@ -772,7 +772,7 @@ is indicative and has a proper subject. @item The documentation string for a function that is a yes-or-no predicate should start with words such as ``Return t if'', to indicate -explicitly what constitutes ``truth''. The word ``return'' avoids +explicitly what constitutes truth. The word ``return'' avoids starting the sentence with lower-case ``t'', which could be somewhat distracting. @@ -883,7 +883,7 @@ strings, though. Comments that start with three semicolons, @samp{;;;}, should start at the left margin. We use them for comments which should be considered a -``heading'' by Outline minor mode. By default, comments starting with +heading by Outline minor mode. By default, comments starting with at least three semicolons (followed by a single space and a non-whitespace character) are considered headings, comments starting with two or fewer are not. Historically, triple-semicolon comments have diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 369e8ddfc30..76dc8e8a81e 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -25,7 +25,7 @@ representing the variable. @menu * Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain ``variables'' have values that never change. +* Constant Variables:: Variables that never change. * Local Variables:: Variable values that exist only temporarily. * Void Variables:: Symbols that lack values. * Defining Variables:: A definition says a symbol is used as a variable. @@ -131,7 +131,7 @@ starts with @samp{:}, interned in the standard obarray, and returns @code{nil} otherwise. @end defun -These constants are fundamentally different from the ``constants'' +These constants are fundamentally different from the constants defined using the @code{defconst} special form (@pxref{Defining Variables}). A @code{defconst} form serves to inform human readers that you do not intend to change the value of a variable, but Emacs @@ -178,7 +178,7 @@ It determines the value returned by evaluating the variable symbol, and it is the binding acted on by @code{setq}. For most purposes, you can think of the current binding as the -``innermost'' local binding, or the global binding if there is no +innermost local binding, or the global binding if there is no local binding. To be more precise, a rule called the @dfn{scoping rule} determines where in a program a local binding takes effect. The default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, @@ -263,7 +263,7 @@ Macro calls (@pxref{Macros}). Variables}); a few variables have terminal-local bindings (@pxref{Multiple Terminals}). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs. +where you are in Emacs. @defopt max-specpdl-size @anchor{Definition of max-specpdl-size} @@ -287,7 +287,7 @@ has room to execute. @end defopt @node Void Variables -@section When a Variable is ``Void'' +@section When a Variable is Void @cindex @code{void-variable} error @cindex void variable @@ -545,8 +545,7 @@ The value is a list of forms (expressions). @item @dots{}-predicate The value is a predicate---a function of one argument that returns -non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' -arguments. +non-@code{nil} for success and @code{nil} for failure. @item @dots{}-flag The value is significant only as to whether it is @code{nil} or not. @@ -564,7 +563,7 @@ The value specifies options for a command. @end table When you define a variable, always consider whether you should mark -it as ``safe'' or ``risky''; see @ref{File Local Variables}. +it as safe or risky; see @ref{File Local Variables}. When defining and initializing a variable that holds a complicated value (such as a keymap with bindings in it), it's best to put the @@ -831,7 +830,7 @@ following example: (defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + x) ; @r{@code{x} is used free in this function.} (let ((x 1)) ; @r{@code{x} is dynamically bound.} (getx)) @@ -846,7 +845,7 @@ following example: @end example @noindent -The function @code{getx} refers to @code{x}. This is a ``free'' +The function @code{getx} refers to @code{x}. This is a @dfn{free} reference, in the sense that there is no binding for @code{x} within that @code{defun} construct itself. When we call @code{getx} from within a @code{let} form in which @code{x} is (dynamically) bound, it @@ -957,7 +956,7 @@ construct. Here is an example @result{} 4 (defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} + x) ; @r{@code{x} is used free in this function.} (let ((x 1)) ; @r{@code{x} is lexically bound.} (getx)) @@ -992,7 +991,7 @@ environments in this way; only specialized programs like debuggers.) @cindex closures, example of using Lexical bindings have indefinite extent. Even after a binding construct has finished executing, its lexical environment can be -``kept around'' in Lisp objects called @dfn{closures}. A closure is +kept around in Lisp objects called @dfn{closures}. A closure is created when you define a named or anonymous function with lexical binding enabled. @xref{Closures}, for details. @@ -1094,10 +1093,10 @@ it is not inadvertently bound lexically. A simple way to find out which variables need a variable definition is to byte-compile the source file. @xref{Byte Compilation}. If a non-special variable is used outside of a @code{let} form, the -byte-compiler will warn about reference or assignment to a ``free -variable''. If a non-special variable is bound but not used within a -@code{let} form, the byte-compiler will warn about an ``unused lexical -variable''. The byte-compiler will also issue a warning if you use a +byte-compiler will warn about reference or assignment to a free +variable. If a non-special variable is bound but not used within a +@code{let} form, the byte-compiler will warn about an unused lexical +variable. The byte-compiler will also issue a warning if you use a special variable as a function argument. (To silence byte-compiler warnings about unused variables, just use @@ -1406,7 +1405,7 @@ buffer-local variables interactively. @cindex local variables, killed by major mode @defun kill-all-local-variables This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent'' and local +current buffer except for variables marked as permanent and local hook functions that have a non-@code{nil} @code{permanent-local-hook} property (@pxref{Setting Hooks}). As a result, the buffer will see the default values of most variables. @@ -1723,7 +1722,7 @@ values by files. Any value specified for one of these variables is completely ignored. @end defvar - The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs + The @samp{Eval:} variable is also a potential loophole, so Emacs normally asks for confirmation before handling it. @defopt enable-local-eval @@ -1736,7 +1735,7 @@ the user what to do for each file. The default value is @code{maybe}. @defopt safe-local-eval-forms This variable holds a list of expressions that are safe to -evaluate when found in the @samp{Eval:} ``variable'' in a file +evaluate when found in the @samp{Eval:} variable in a file local variables list. @end defopt @@ -1997,7 +1996,7 @@ a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values are stored. -Generalized variables are analogous to ``lvalues'' in the C +Generalized variables are analogous to lvalues in the C language, where @samp{x = a[i]} gets an element from an array and @samp{a[i] = x} stores an element using the same notation. Just as certain forms like @code{a[i]} can be lvalues in C, there @@ -2170,7 +2169,7 @@ of Common Lisp. Consult the source file @file{gv.el} for more details. @cindex CL note---no @code{setf} functions @quotation @b{Common Lisp note:} Common Lisp defines another way to specify the -@code{setf} behavior of a function, namely ``@code{setf} functions'', +@code{setf} behavior of a function, namely @code{setf} functions, whose names are lists @code{(setf @var{name})} rather than symbols. For example, @code{(defun (setf foo) @dots{})} defines the function that is used when @code{setf} is applied to @code{foo}. Emacs does diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 465693854eb..3479e180221 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -430,7 +430,7 @@ Format}); and the bottom divider (@pxref{Window Dividers}). width of a window. The return value of many of these functions can be specified either in units of pixels or in units of lines and columns. On a graphical display, the latter actually correspond to the height and -width of a ``default'' character specified by the frame's default font +width of a default character specified by the frame's default font as returned by @code{frame-char-height} and @code{frame-char-width} (@pxref{Frame Font}). Thus, if a window is displaying text with a different font or size, the reported line height and column width for @@ -1050,7 +1050,7 @@ This section describes functions for creating a new window by @defun split-window &optional window size side pixelwise This function creates a new live window next to the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. That window is ``split'', and reduced in +to the selected window. That window is split, and reduced in size. The space is taken up by the new window, which is returned. The optional second argument @var{size} determines the sizes of @@ -1075,7 +1075,7 @@ check whether the emanating windows are large enough to encompass all areas like a mode line or a scroll bar. The function @code{window-min-size} (@pxref{Window Sizes}) can be used to determine the minimum requirements of @var{window} in this regard. Since the new -window usually ``inherits'' areas like the mode line or the scroll bar +window usually inherits areas like the mode line or the scroll bar from @var{window}, that function is also a good guess for the minimum size of the new window. The caller should specify a smaller size only if it correspondingly removes an inherited area before the next @@ -1661,7 +1661,7 @@ internal routines often temporarily select a window in order to simplify coding. As a rule, such selections (including those made by the macros @code{save-selected-window} and @code{with-selected-window} below) are not recorded thus avoiding to pollute @code{buffer-list-update-hook}. -Selections that ``really count'' are those causing a visible change in +Selections that really count are those causing a visible change in the next redisplay of @var{window}'s frame and should be always recorded. This also means that to run a function each time a window gets selected, putting it on @code{buffer-list-update-hook} should be @@ -1729,12 +1729,12 @@ nor the buffer list. @cindex use time of window @cindex window order by time of last use @defun window-use-time &optional window -This functions returns the ``use time'' of window @var{window}. +This functions returns the use time of window @var{window}. @var{window} must be a live window and defaults to the selected one. The @dfn{use time} of a window is not really a time value, but it does increase monotonically with each window selection, so the window with -the lowest ``use time'' is the least recently selected one, and the -window with the highest ``use time'' is the most recently selected +the lowest use time is the least recently selected one, and the +window with the highest use time is the most recently selected one. @end defun @@ -1765,7 +1765,7 @@ if omitted or @code{nil}, it defaults to the selected window. The optional argument @var{minibuf} specifies whether minibuffer windows should be included in the cyclic ordering. Normally, when @var{minibuf} is @code{nil}, a minibuffer window is included only if it is currently -``active''; this matches the behavior of @kbd{C-x o}. (Note that a +active; this matches the behavior of @kbd{C-x o}. (Note that a minibuffer window is active as long as its minibuffer is in use; see @ref{Minibuffers}). @@ -1859,8 +1859,8 @@ criterion, without selecting it: @cindex least recently used window @defun get-lru-window &optional all-frames dedicated not-selected -This function returns a live window which is heuristically the ``least -recently used'' window. The optional argument @var{all-frames} has +This function returns a live window which is heuristically the least +recently used. The optional argument @var{all-frames} has the same meaning as in @code{next-window}. If any full-width windows are present, only those windows are @@ -1874,8 +1874,8 @@ function returns @code{nil} in that case. @cindex most recently used window @defun get-mru-window &optional all-frames dedicated not-selected -This function is like @code{get-lru-window}, but it returns the ``most -recently used'' window instead. The meaning of the arguments is the +This function is like @code{get-lru-window}, but it returns the most +recently used window instead. The meaning of the arguments is the same as described for @code{get-lru-window}. @end defun @@ -2293,7 +2293,7 @@ corresponding display action to display the buffer. @defopt display-buffer-base-action The value of this option should be a display action. This option can -be used to define a ``standard'' display action for calls to +be used to define a standard display action for calls to @code{display-buffer}. @end defopt @@ -2319,7 +2319,7 @@ to another buffer (@pxref{Dedicated Windows}). It also fails if @end defun @defun display-buffer-reuse-window buffer alist -This function tries to ``display'' @var{buffer} by finding a window +This function tries to display @var{buffer} by finding a window that is already displaying it. If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, @@ -2365,7 +2365,7 @@ is added to the newly created frame's parameters. @end defun @defun display-buffer-use-some-frame buffer alist -This function tries to ``display'' @var{buffer} by trying to find a +This function tries to display @var{buffer} by trying to find a frame that meets a predicate (by default any frame other than the current frame). @@ -2517,7 +2517,7 @@ buffer there. If all these steps fail, it will proceed using whatever (provided *foo* was put by @code{display-buffer} there before) or a popped-up window as follows: If the window is part of a vertical combination, it will set its height to ten lines. Note that if, instead -of the number ``10'', we specified the function +of the number 10, we specified the function @code{fit-window-to-buffer}, @code{display-buffer} would come up with a one-line window to fit the empty buffer. If the window is part of a horizontal combination, it sets its width to 40 columns. Whether a new @@ -2558,7 +2558,7 @@ window below the selected window. selected one is dedicated to its buffer, @code{display-buffer} will proceed as described in the previous example. Note, however, that when it tries to adjust the height of any reused or popped-up window, it will -in any case try to set its number of lines to ``5'' since that value +in any case try to set its number of lines to 5 since that value overrides the corresponding specification in the @var{action} argument of @code{display-buffer}. @@ -3025,7 +3025,7 @@ window's buffer) if that window were selected. The default for When @var{window} is the selected window, the value returned is the value of point in that window's buffer. Strictly speaking, it would be -more correct to return the ``top-level'' value of point, outside of any +more correct to return the top-level value of point, outside of any @code{save-excursion} forms. But that value is hard to find. @end defun @@ -3122,7 +3122,7 @@ screen. If this does place point off screen, the display routines move point to the left margin on the middle line in the window. For example, if point @w{is 1} and you set the start of the window -@w{to 37}, the start of the next line, point will be ``above'' the top +@w{to 37}, the start of the next line, point will be above the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example: @@ -3429,7 +3429,7 @@ only if point is already on that position do they signal an error. @cindex centering point This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does -not ``move point'' with respect to the text. +not move point with respect to the text. If @var{count} is a non-negative number, that puts the line containing point @var{count} lines down from the top of the window. If @@ -3564,8 +3564,8 @@ times the normal character width. How many characters actually disappear off to the left depends on their width, and could vary from line to line. - Because we read from side to side in the ``inner loop'', and from top -to bottom in the ``outer loop'', the effect of horizontal scrolling is + Because we read from side to side in the inner loop, and from top +to bottom in the outer loop, the effect of horizontal scrolling is not like that of textual or vertical scrolling. Textual scrolling involves selection of a portion of text to display, and vertical scrolling moves the window contents contiguously; but horizontal @@ -3697,12 +3697,12 @@ Most of these functions report positions relative to an origin at the native position of the window's frame (@pxref{Frame Geometry}). Some functions report positions relative to the origin of the display of the window's frame. In any case, the origin has the coordinates (0, 0) and -X and Y coordinates increase ``rightward'' and ``downward'' +X and Y coordinates increase rightward and downward respectively. For the following functions, X and Y coordinates are reported in integer character units, i.e., numbers of lines and columns -respectively. On a graphical display, each ``line'' and ``column'' +respectively. On a graphical display, each line and column corresponds to the height and width of a default character specified by the frame's default font (@pxref{Frame Font}). @@ -3840,7 +3840,7 @@ argument because it always uses the frame that @var{window} is on. The following functions return window positions in pixels, rather than character units. Though mostly useful on graphical displays, they can also be called on text terminals, where the screen area of -each text character is taken to be ``one pixel''. +each text character is taken to be one pixel. @defun window-pixel-edges &optional window This function returns a list of pixel coordinates for the edges of @@ -3903,7 +3903,7 @@ visible in some window: @end group @end example -On a graphical terminal this form ``warps'' the mouse cursor to the +On a graphical terminal this form warps the mouse cursor to the upper left corner of the glyph at the selected window's point. A position calculated this way can be also used to show a tooltip window there. |