From 049bcbcba62635103d4d212b3c3cf7dc0ef21f36 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 29 May 2011 13:18:46 -0400 Subject: Tweaks to lisp manual to remove over/underflows in printed version. * help.texi (Accessing Documentation): * display.texi (Pixel Specification): * processes.texi (Serial Ports, Serial Ports): * nonascii.texi (Character Properties, Default Coding Systems): * text.texi (Changing Properties, Special Properties): * windows.texi (Window Start and End): * modes.texi (SMIE Indentation Example, SMIE Tricks): * keymaps.texi (Searching Keymaps, Tool Bar): * minibuf.texi (Basic Completion): * compile.texi (Eval During Compile): * strings.texi (Formatting Strings): Tweaks to avoid overflowing 7x9 paper in printed manual. * lists.texi (Sets And Lists): Fix misplaced text. --- doc/lispref/ChangeLog | 17 +++++++++++++++++ doc/lispref/compile.texi | 2 +- doc/lispref/display.texi | 27 ++++++++++++++------------- doc/lispref/elisp.texi | 2 +- doc/lispref/help.texi | 6 +++--- doc/lispref/keymaps.texi | 27 ++++++++++++++------------- doc/lispref/lists.texi | 2 +- doc/lispref/minibuf.texi | 13 +++++++------ doc/lispref/modes.texi | 26 +++++++++++++++++--------- doc/lispref/nonascii.texi | 33 ++++++++++++++++++--------------- doc/lispref/processes.texi | 36 +++++++++--------------------------- doc/lispref/strings.texi | 8 ++++---- doc/lispref/text.texi | 13 +++---------- doc/lispref/tips.texi | 3 ++- doc/lispref/windows.texi | 8 ++++---- 15 files changed, 115 insertions(+), 108 deletions(-) (limited to 'doc') diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index c8a45ffc4d..fd8a9945cf 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,20 @@ +2011-05-29 Chong Yidong + + * help.texi (Accessing Documentation): + * display.texi (Pixel Specification): + * processes.texi (Serial Ports, Serial Ports): + * nonascii.texi (Character Properties, Default Coding Systems): + * text.texi (Changing Properties, Special Properties): + * windows.texi (Window Start and End): + * modes.texi (SMIE Indentation Example, SMIE Tricks): + * keymaps.texi (Searching Keymaps, Tool Bar): + * minibuf.texi (Basic Completion): + * compile.texi (Eval During Compile): + * strings.texi (Formatting Strings): Tweaks to avoid overflowing + 7x9 paper in printed manual. + + * lists.texi (Sets And Lists): Fix misplaced text. + 2011-05-06 Stefan Monnier * modes.texi (Region to Refontify): Rename from "Region to Fontify". diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 928955b023..b91e162623 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -452,7 +452,7 @@ used to load it for compiling, but not executing. For example, @lisp (eval-when-compile - (require 'my-macro-package)) ;; only macros needed from this + (require 'my-macro-package)) @end lisp The same sort of thing goes for macros and @code{defsubst} functions diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 8a88440154..4a647ef15a 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1443,9 +1443,9 @@ specify a particular attribute for certain text. @xref{Face Attributes}. @item -A cons cell, either of the form @code{(foreground-color . @var{color-name})} or -@code{(background-color . @var{color-name})}. These elements specify -just the foreground color or just the background color. +A cons cell, either of the form @code{(fg-color . @var{color-name})} +or @code{(bg-color . @var{color-name})}. These elements specify just +the foreground color or just the background color. @code{(foreground-color . @var{color-name})} has the same effect as @code{(:foreground @var{color-name})}; likewise for the background. @@ -3821,9 +3821,10 @@ pixels per inch, millimeter, and centimeter, respectively. The and height of the current face. An image specification @code{image} corresponds to the width or height of the image. - The @code{left-fringe}, @code{right-fringe}, @code{left-margin}, -@code{right-margin}, @code{scroll-bar}, and @code{text} elements -specify to the width of the corresponding area of the window. + The elements @code{left-fringe}, @code{right-fringe}, +@code{left-margin}, @code{right-margin}, @code{scroll-bar}, and +@code{text} specify to the width of the corresponding area of the +window. The @code{left}, @code{center}, and @code{right} positions can be used with @code{:align-to} to specify a position relative to the left @@ -4613,16 +4614,14 @@ If @var{no-error} is non-@code{nil} and a suitable path can't be found, don't signal an error. Instead, return a list of directories as before, except that @code{nil} appears in place of the image directory. -Here is an example that uses a common idiom to provide compatibility -with versions of Emacs that lack the variable @code{image-load-path}: +Here is an example of using @code{image-load-path-for-library}: @example (defvar image-load-path) ; shush compiler (let* ((load-path (image-load-path-for-library - "mh-e" "mh-logo.xpm")) + "mh-e" "mh-logo.xpm")) (image-load-path (cons (car load-path) - (when (boundp 'image-load-path) - image-load-path)))) + image-load-path))) (mh-tool-bar-folder-buttons-init)) @end example @end defun @@ -5351,8 +5350,10 @@ value) in various ways. (aref colorcomp-data 2))) (samp " (sample text) ")) (insert "Color\t: " - (propertize samp 'face `(foreground-color . ,cstr)) - (propertize samp 'face `(background-color . ,cstr)) + (propertize samp 'face + `(foreground-color . ,cstr)) + (propertize samp 'face + `(background-color . ,cstr)) "\n")))) (defun colorcomp (color) diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 93a8acdff0..b140a1343d 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -14,7 +14,7 @@ @c in general, keep the following line commented out, unless doing a @c copy of this manual that will be published. The manual should go @c onto the distribution in the full, 8.5 x 11" size. -@c set smallbook +@c @smallbook @ifset smallbook @smallbook diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 496ad6226f..f1db33582f 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -144,9 +144,9 @@ unless @var{verbatim} is non-@code{nil}. @end defun @defun documentation function &optional verbatim -This function returns the documentation string of @var{function}. -@code{documentation} handles macros, named keyboard macros, and -special forms, as well as ordinary functions. +This function returns the documentation string of @var{function}. It +handles macros, named keyboard macros, and special forms, as well as +ordinary functions. If @var{function} is a symbol, this function first looks for the @code{function-documentation} property of that symbol; if that has a diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 1d485ab67b..b1f02d6b26 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -720,17 +720,18 @@ pseudo-Lisp description of the order and conditions for searching them: @lisp -(or (if overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map) - (if overriding-local-map - (@var{find-in} overriding-local-map) - (or (@var{find-in} (get-char-property (point) 'keymap)) - (@var{find-in-any} emulation-mode-map-alists) - (@var{find-in-any} minor-mode-overriding-map-alist) - (@var{find-in-any} minor-mode-map-alist) - (if (get-text-property (point) 'local-map) - (@var{find-in} (get-char-property (point) 'local-map)) - (@var{find-in} (current-local-map)))))) +(or (cond + (overriding-terminal-local-map + (@var{find-in} overriding-terminal-local-map)) + (overriding-local-map + (@var{find-in} overriding-local-map)) + (or (@var{find-in} (get-char-property (point) 'keymap)) + (@var{find-in-any} emulation-mode-map-alists) + (@var{find-in-any} minor-mode-overriding-map-alist) + (@var{find-in-any} minor-mode-map-alist) + (if (get-text-property (point) 'local-map) + (@var{find-in} (get-char-property (point) 'local-map)) + (@var{find-in} (current-local-map))))) (@var{find-in} (current-global-map))) @end lisp @@ -2661,8 +2662,8 @@ using an indirection through @code{tool-bar-map}. By default, the global map binds @code{[tool-bar]} as follows: @example (global-set-key [tool-bar] - '(menu-item "tool bar" ignore - :filter (lambda (ignore) tool-bar-map))) + '(menu-item "tool bar" ignore + :filter (lambda (ignore) tool-bar-map))) @end example @noindent Thus the tool bar map is derived dynamically from the value of variable diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 4435af43c8..b45277acfb 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1356,10 +1356,10 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}: (delq '(4) sample-list) @result{} (a c (4)) @end group +@end example If you want to delete elements that are @code{equal} to a given value, use @code{delete} (see below). -@end example @defun remq object list This function returns a copy of @var{list}, with all elements removed diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 9b09a304bd..b2ffc5fede 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -839,12 +839,13 @@ variable as ``risky'' with a non-@code{nil} @code{risky-local-variable} property. @xref{File Local Variables}. @defvar completion-ignore-case -If the value of this variable is non-@code{nil}, Emacs does not -consider case significant in completion. Note, however, that this -variable is overridden by @code{read-file-name-completion-ignore-case} -within @code{read-file-name} (@pxref{Reading File Names}), and by -@code{read-buffer-completion-ignore-case} within @code{read-buffer} -(@pxref{High-Level Completion}). +If the value of this variable is non-@code{nil}, case is not +considered significant in completion. Within @code{read-file-name}, +this variable is overridden by +@code{read-file-name-completion-ignore-case} (@pxref{Reading File +Names}); within @code{read-buffer}, it is overridden by +@code{read-buffer-completion-ignore-case} (@pxref{High-Level +Completion}). @end defvar @defvar completion-regexp-list diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 1c72619c83..3f3eb2cd1f 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1024,8 +1024,8 @@ Turning on text-mode runs the hook `text-mode-hook'." @end group @group ;; @r{These four lines are absent from the current version} - ;; @r{not because this is done some other way, but rather} - ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} + ;; @r{not because this is done some other way, but because} + ;; @r{nowadays Text mode uses the normal definition of paragraphs.} (set (make-local-variable 'paragraph-start) (concat "[ \t]*$\\|" page-delimiter)) (set (make-local-variable 'paragraph-separate) paragraph-start) @@ -1117,12 +1117,15 @@ modes should understand the Lisp conventions for comments. The rest of @smallexample @group - (set (make-local-variable 'paragraph-start) (concat page-delimiter "\\|$" )) - (set (make-local-variable 'paragraph-separate) paragraph-start) + (set (make-local-variable 'paragraph-start) + (concat page-delimiter "\\|$" )) + (set (make-local-variable 'paragraph-separate) + paragraph-start) @dots{} @end group @group - (set (make-local-variable 'comment-indent-function) 'lisp-comment-indent)) + (set (make-local-variable 'comment-indent-function) + 'lisp-comment-indent)) @dots{} @end group @end smallexample @@ -3590,7 +3593,9 @@ natural to have a BNF grammar that looks like this: (inst ("IF" exp "THEN" insts "ELSE" insts "END") ("CASE" exp "OF" cases "END") ...) - (cases (cases "|" cases) (caselabel ":" insts) ("ELSE" insts)) + (cases (cases "|" cases) + (caselabel ":" insts) + ("ELSE" insts)) ... @end example @@ -3791,7 +3796,9 @@ block). Here is an example of an indentation function: @example -(eval-when-compile (require 'cl)) ;For the `case' macro. +;; For the `case' macro. +(eval-when-compile (require 'cl)) + (defun sample-smie-rules (kind token) (case kind (:elem (case token @@ -3872,9 +3879,10 @@ and is always at the beginning of a line, we can use a more efficient rule: @example ((equal token "if") - (and (not (smie-rule-bolp)) (smie-rule-prev-p "else") + (and (not (smie-rule-bolp)) + (smie-rule-prev-p "else") (save-excursion - (sample-smie-backward-token) ;Jump before the "else". + (sample-smie-backward-token) (cons 'column (current-column))))) @end example diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 3093613cca..b66a5446e4 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -378,17 +378,17 @@ properties that Emacs knows about: @table @code @item name -This property corresponds to the Unicode @code{Name} property. The -value is a string consisting of upper-case Latin letters A to Z, -digits, spaces, and hyphen @samp{-} characters. +Corresponds to the @code{Name} Unicode property. The value is a +string consisting of upper-case Latin letters A to Z, digits, spaces, +and hyphen @samp{-} characters. @item general-category -This property corresponds to the Unicode @code{General_Category} -property. The value is a symbol whose name is a 2-letter abbreviation -of the character's classification. +Corresponds to the @code{General_Category} Unicode property. The +value is a symbol whose name is a 2-letter abbreviation of the +character's classification. @item canonical-combining-class -Corresponds to the Unicode @code{Canonical_Combining_Class} property. +Corresponds to the @code{Canonical_Combining_Class} Unicode property. The value is an integer number. @item bidi-class @@ -469,15 +469,18 @@ This function returns the value of @var{char}'s @var{propname} property. @result{} Nd @end group @group -(get-char-code-property ?\u2084 'digit-value) ; subscript 4 +;; subscript 4 +(get-char-code-property ?\u2084 'digit-value) @result{} 4 @end group @group -(get-char-code-property ?\u2155 'numeric-value) ; one fifth +;; one fifth +(get-char-code-property ?\u2155 'numeric-value) @result{} 1/5 @end group @group -(get-char-code-property ?\u2163 'numeric-value) ; Roman IV +;; Roman IV +(get-char-code-property ?\u2163 'numeric-value) @result{} \4 @end group @end example @@ -1447,11 +1450,11 @@ for decoding (in case @var{operation} does decoding), and @var{encoding-system} is the coding system for encoding (in case @var{operation} does encoding). -The argument @var{operation} is a symbol, one of @code{write-region}, -@code{start-process}, @code{call-process}, @code{call-process-region}, -@code{insert-file-contents}, or @code{open-network-stream}. These are -the names of the Emacs I/O primitives that can do character code and -eol conversion. +The argument @var{operation} is a symbol; it should be one of +@code{write-region}, @code{start-process}, @code{call-process}, +@code{call-process-region}, @code{insert-file-contents}, or +@code{open-network-stream}. These are the names of the Emacs I/O +primitives that can do character code and eol conversion. The remaining arguments should be the same arguments that might be given to the corresponding I/O primitive. Depending on the primitive, one diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index d5598f5538..f3f68a7947 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1795,9 +1795,9 @@ nice values get scheduled more favorably.) The number of threads in the process. @item start -The time the process was started, in the @w{@code{(@var{high} -@var{low} @var{microsec})}} format used by @code{current-time} and -@code{file-attributes}. +The time when the process was started, in the same +@w{@code{(@var{high} @var{low} @var{microsec})}} format used by +@code{current-time} and @code{file-attributes}. @item etime The time elapsed since the process started, in the @w{@code{(@var{high} @@ -2483,25 +2483,17 @@ Install @var{plist} as the initial plist of the process. @itemx :parity @itemx :stopbits @itemx :flowcontrol -These arguments are handled by @code{serial-process-configure}, which -is called by @code{make-serial-process}. +These are handled by @code{serial-process-configure}, which is called +by @code{make-serial-process}. @end table The original argument list, possibly modified by later configuration, is available via the function @code{process-contact}. -Examples: +Here is an example: @example (make-serial-process :port "/dev/ttyS0" :speed 9600) - -(make-serial-process :port "COM1" :speed 115200 :stopbits 2) - -(make-serial-process :port "\\\\.\\COM13" :speed 1200 - :bytesize 7 :parity 'odd) - -(make-serial-process :port "/dev/tty.BlueConsole-SPP-1" - :speed nil) @end example @end defun @@ -2561,19 +2553,9 @@ flow control). If @var{flowcontrol} is not given, it defaults to no flow control. @end table -@code{serial-process-configure} is called by @code{make-serial-process} for the -initial configuration of the serial port. - -Examples: - -@example -(serial-process-configure :process "/dev/ttyS0" :speed 1200) - -(serial-process-configure :buffer "COM1" :stopbits 1 - :parity 'odd :flowcontrol 'hw) - -(serial-process-configure :port "\\\\.\\COM13" :bytesize 7) -@end example +@code{serial-process-configure} is called by +@code{make-serial-process} for the initial configuration of the serial +port. @end defun @node Byte Packing diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 925c92050e..87b9f4368f 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -829,12 +829,12 @@ is not truncated. @example @group -(format "The word `%7s' actually has %d letters in it." +(format "The word `%7s' has %d letters in it." "foo" (length "foo")) - @result{} "The word ` foo' actually has 3 letters in it." -(format "The word `%7s' actually has %d letters in it." + @result{} "The word ` foo' has 3 letters in it." +(format "The word `%7s' has %d letters in it." "specification" (length "specification")) - @result{} "The word `specification' actually has 13 letters in it." + @result{} "The word `specification' has 13 letters in it." @end group @end example diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index e11913e993..f4dce6a1bc 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -2810,9 +2810,9 @@ construct each part with @code{propertize} and then combine them with @end smallexample @end defun - See also the function @code{buffer-substring-no-properties} -(@pxref{Buffer Contents}) which copies text from the buffer -but does not copy its properties. + @xref{Buffer Contents}, for the function +@code{buffer-substring-no-properties}, which copies text from the +buffer but does not copy its properties. @node Property Search @subsection Text Property Search Functions @@ -2996,13 +2996,6 @@ face attribute name and @var{value} is a meaningful value for that attribute. With this feature, you do not need to create a face each time you want to specify a particular attribute for certain text. @xref{Face Attributes}. - -@item -A cons cell with the form @code{(foreground-color . @var{color-name})} -or @code{(background-color . @var{color-name})}. These are old, -deprecated equivalents for @code{(:foreground @var{color-name})} and -@code{(:background @var{color-name})}. Please convert code that uses -them. @end itemize It works to use the latter two forms directly as the value diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 5dd845efbd..9be6c061bf 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -256,7 +256,8 @@ file if you distribute copies. Use a notice like this one: ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License -;; along with this program. If not, see . +;; along with this program. If not, see +;; . @end smallexample If you have signed papers to assign the copyright to the Foundation, diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index f17fc3c718..ee9d1a8374 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1463,10 +1463,10 @@ to the current position of point in @var{window}; @var{window}, to the selected window. If @var{position} is @code{t}, that means to check the last visible position in @var{window}. -The @code{pos-visible-in-window-p} function considers only vertical -scrolling. If @var{position} is out of view only because @var{window} -has been scrolled horizontally, @code{pos-visible-in-window-p} returns -non-@code{nil} anyway. @xref{Horizontal Scrolling}. +This function considers only vertical scrolling. If @var{position} is +out of view only because @var{window} has been scrolled horizontally, +@code{pos-visible-in-window-p} returns non-@code{nil} anyway. +@xref{Horizontal Scrolling}. If @var{position} is visible, @code{pos-visible-in-window-p} returns @code{t} if @var{partially} is @code{nil}; if @var{partially} is -- cgit v1.2.3