From 2bb0eca1ebe1ff1b9939b6350a2e5310c17a7e8c Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Tue, 10 Apr 2012 00:11:23 -0700 Subject: [PATCH] In doc/lispref, use @file for buffers, per the Texinfo manual. It renders the same as @samp, so there is no visible change in most cases. --- doc/lispref/ChangeLog | 5 +++++ doc/lispref/buffers.texi | 4 ++-- doc/lispref/compile.texi | 8 ++++---- doc/lispref/customize.texi | 2 +- doc/lispref/debugging.texi | 10 +++++----- doc/lispref/display.texi | 16 ++++++++-------- doc/lispref/edebug.texi | 18 +++++++++--------- doc/lispref/eval.texi | 2 +- doc/lispref/help.texi | 12 ++++++------ doc/lispref/intro.texi | 2 +- doc/lispref/keymaps.texi | 4 ++-- doc/lispref/minibuf.texi | 4 ++-- doc/lispref/modes.texi | 10 +++++----- doc/lispref/os.texi | 14 +++++++------- doc/lispref/processes.texi | 2 +- doc/lispref/text.texi | 2 +- 16 files changed, 60 insertions(+), 55 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index d53be2b57c6..256bbf6d20b 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,10 @@ 2012-04-10 Glenn Morris + * buffers.texi, compile.texi, customize.texi, debugging.texi: + * display.texi, edebug.texi, eval.texi, help.texi, intro.texi: + * keymaps.texi, minibuf.texi, modes.texi, os.texi, processes.texi: + * text.texi: Use @file for buffers, per the Texinfo manual. + * compile.texi (Compiler Errors): Add missing space in buffer name. 2012-04-08 Chong Yidong diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 125a886ecb2..433663b4260 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -863,7 +863,7 @@ a buffer visible in any window on any visible frame, except as a last resort. If @var{visible-ok} is non-@code{nil}, then it does not matter whether a buffer is displayed somewhere or not. -If no suitable buffer exists, the buffer @samp{*scratch*} is returned +If no suitable buffer exists, the buffer @file{*scratch*} is returned (and created, if necessary). @end defun @@ -874,7 +874,7 @@ selected frame's buffer list. The argument @var{visible-ok} is handled as with @code{other-buffer}, see above. If no suitable buffer can be found, the buffer -@samp{*scratch*} is returned. +@file{*scratch*} is returned. @end defun @deffn Command bury-buffer &optional buffer-or-name diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 1cc54bb2ac4..093c91f02b0 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -92,7 +92,7 @@ the @code{byte-compile} function. You can compile a whole file with Sometimes, the byte compiler produces warning and/or error messages (@pxref{Compiler Errors}, for details). These messages are recorded -in a buffer called @samp{*Compile-Log*}, which uses Compilation mode. +in a buffer called @file{*Compile-Log*}, which uses Compilation mode. @xref{Compilation Mode,,,emacs, The GNU Emacs Manual}. @cindex macro compilation @@ -443,14 +443,14 @@ to what @code{eval-when-compile} does. @cindex compiler errors Byte compilation outputs all errors and warnings into the buffer -@samp{*Compile-Log*}. The messages include file names and line +@file{*Compile-Log*}. The messages include file names and line numbers that identify the location of the problem. The usual Emacs commands for operating on compiler diagnostics work properly on these messages. When an error is due to invalid syntax in the program, the byte compiler might get confused about the errors' exact location. One way -to investigate is to switch to the buffer @w{@samp{ *Compiler Input*}}. +to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}. (This buffer name starts with a space, so it does not show up in @kbd{M-x list-buffers}.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read; @@ -602,7 +602,7 @@ the stack. @deffn Command disassemble object &optional buffer-or-name This command displays the disassembled code for @var{object}. In interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, -the output goes in a buffer named @samp{*Disassemble*}. If +the output goes in a buffer named @file{*Disassemble*}. If @var{buffer-or-name} is non-@code{nil}, it must be a buffer or the name of an existing buffer. Then the output goes there, at point, and point is left before the output. diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 4c3adee0db5..167dfe7d4c5 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -596,7 +596,7 @@ The value must be a coding-system name, and you can do completion with @item color The value must be a valid color name. The widget provides completion for color names, as well as a sample and a button for selecting a -color name from a list of color names shown in a @samp{*Colors*} +color name from a list of color names shown in a @file{*Colors*} buffer. @end table diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 6e7d0078e07..115d8ff42de 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -303,7 +303,7 @@ an implicit @code{progn} (@pxref{Sequencing}). @subsection Using the Debugger When the debugger is entered, it displays the previously selected -buffer in one window and a buffer named @samp{*Backtrace*} in another +buffer in one window and a buffer named @file{*Backtrace*} in another window. The backtrace buffer contains one line for each level of Lisp function execution currently going on. At the beginning of this buffer is a message describing the reason that the debugger was invoked (such @@ -412,7 +412,7 @@ the variable values within the debugger. @item R Like @kbd{e}, but also save the result of evaluation in the -buffer @samp{*Debugger-record*}. +buffer @file{*Debugger-record*}. @item q Terminate the program being debugged; return to top-level Emacs @@ -450,7 +450,7 @@ to invoke the debugger. @defun debug &rest debugger-args This function enters the debugger. It switches buffers to a buffer -named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second +named @file{*Backtrace*} (or @file{*Backtrace*<2>} if it is the second recursive entry to the debugger, etc.), and fills it with information about the stack of Lisp function calls. It then enters a recursive edit, showing the backtrace buffer in Debugger mode. @@ -461,7 +461,7 @@ buffer and returns to whatever called @code{debug}. This is the only way the function @code{debug} can return to its caller. The use of the @var{debugger-args} is that @code{debug} displays the -rest of its arguments at the top of the @samp{*Backtrace*} buffer, so +rest of its arguments at the top of the @file{*Backtrace*} buffer, so that the user can see them. Except as described below, this is the @emph{only} way these arguments are used. @@ -560,7 +560,7 @@ of @code{debug} (@pxref{Invoking the Debugger}). @cindex call stack This function prints a trace of Lisp function calls currently active. This is the function used by @code{debug} to fill up the -@samp{*Backtrace*} buffer. It is written in C, since it must have access +@file{*Backtrace*} buffer. It is written in C, since it must have access to the stack to determine which function calls are active. The return value is always @code{nil}. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 8382c2a1555..ee3ffd8d10c 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -268,7 +268,7 @@ objects for its format specifications, like in the @code{format} function (@pxref{Formatting Strings}). The resulting formatted string is displayed in the echo area; if it contains @code{face} text properties, it is displayed with the specified faces (@pxref{Faces}). -The string is also added to the @samp{*Messages*} buffer, but without +The string is also added to the @file{*Messages*} buffer, but without text properties (@pxref{Logging Messages}). In batch mode, the message is printed to the standard error stream, @@ -341,7 +341,7 @@ buffer is used, the window used to display it. If @var{message} is a string, then the optional argument @var{buffer-name} is the name of the buffer used to display it when a -pop-up buffer is used, defaulting to @samp{*Message*}. In the case +pop-up buffer is used, defaulting to @file{*Message*}. In the case where @var{message} is a string and displayed in the echo area, it is not specified whether the contents are inserted into the buffer anyway. @@ -474,16 +474,16 @@ this macro this way: @end defmac @node Logging Messages -@subsection Logging Messages in @samp{*Messages*} +@subsection Logging Messages in @file{*Messages*} @cindex logging echo-area messages Almost all the messages displayed in the echo area are also recorded -in the @samp{*Messages*} buffer so that the user can refer back to +in the @file{*Messages*} buffer so that the user can refer back to them. This includes all the messages that are output with @code{message}. @defopt message-log-max -This variable specifies how many lines to keep in the @samp{*Messages*} +This variable specifies how many lines to keep in the @file{*Messages*} buffer. The value @code{t} means there is no limit on how many lines to keep. The value @code{nil} disables message logging entirely. Here's how to display a message and prevent it from being logged: @@ -494,7 +494,7 @@ how to display a message and prevent it from being logged: @end example @end defopt - To make @samp{*Messages*} more convenient for the user, the logging + To make @file{*Messages*} more convenient for the user, the logging 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. @@ -624,7 +624,7 @@ and @var{type} as the warning type. @var{level} should be the severity level, with @code{:warning} being the default. @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer -for logging the warning. By default, it is @samp{*Warnings*}. +for logging the warning. By default, it is @file{*Warnings*}. @end defun @defun lwarn type level message &rest args @@ -2752,7 +2752,7 @@ For text matching a search command. @itemx warning @itemx success For text concerning errors, warnings, or successes. For example, -these are used for messages in @samp{*Compilation*} buffers. +these are used for messages in @file{*Compilation*} buffers. @end table @node Font Selection diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 245aaf94c6d..9d50f5fb31f 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -622,7 +622,7 @@ back to the stop point in the source code buffer from any buffer using saved outside window configuration---so that even if you turn saving back @emph{on}, the current window configuration remains unchanged when you next exit Edebug (by continuing the program). However, the -automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may +automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may conflict with the buffers you wish to see unless you have enough windows open. @@ -661,18 +661,18 @@ lexically bound symbols created by the following constructs in @node Eval List @subsection Evaluation List Buffer - You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to + You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to evaluate expressions interactively. You can also set up the @dfn{evaluation list} of expressions to be evaluated automatically each time Edebug updates the display. @table @kbd @item E -Switch to the evaluation list buffer @samp{*edebug*} +Switch to the evaluation list buffer @file{*edebug*} (@code{edebug-visit-eval-list}). @end table - In the @samp{*edebug*} buffer you can use the commands of Lisp + In the @file{*edebug*} buffer you can use the commands of Lisp Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs Manual}) as well as these special commands: @@ -699,7 +699,7 @@ Switch back to the source code buffer at the current stop point @end table You can evaluate expressions in the evaluation list window with -@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; +@kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*}; but they are evaluated in the context outside of Edebug. The expressions you enter interactively (and their results) are lost @@ -758,8 +758,8 @@ the expression at a suitable place, insert a new comment line, then type @kbd{C-c C-u}. You need not insert dashes in the comment line---its contents don't matter. -After selecting @samp{*edebug*}, you can return to the source code -buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when +After selecting @file{*edebug*}, you can return to the source code +buffer with @kbd{C-c C-w}. The @file{*edebug*} buffer is killed when you continue execution, and recreated next time it is needed. @node Printing in Edebug @@ -819,7 +819,7 @@ for details. @cindex trace buffer Edebug can record an execution trace, storing it in a buffer named -@samp{*edebug-trace*}. This is a log of function calls and returns, +@file{*edebug-trace*}. This is a log of function calls and returns, showing the function names and their arguments and values. To enable trace recording, set @code{edebug-trace} to a non-@code{nil} value. @@ -1567,7 +1567,7 @@ The default value is @code{step}. @defopt edebug-trace If this is non-@code{nil}, trace each function entry and exit. -Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one +Tracing output is displayed in a buffer named @file{*edebug-trace*}, one function entry or exit per line, indented by the recursion level. Also see @code{edebug-tracing}, in @ref{Trace Buffer}. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 429d999a2c8..7f25b33eb43 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -807,7 +807,7 @@ The value of this variable is a list of the values returned by all the expressions that were read, evaluated, and printed from buffers (including the minibuffer) by the standard Emacs commands which do this. (Note that this does @emph{not} include evaluation in -@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in +@file{*ielm*} buffers, nor evaluation using @kbd{C-j} in @code{lisp-interaction-mode}.) The elements are ordered most recent first. diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 537514d7fb9..2575f5e5bd6 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -180,7 +180,7 @@ face. @c Wordy to prevent overfull hboxes. --rjc 15mar92 Here is an example of using the two functions, @code{documentation} and @code{documentation-property}, to display the documentation strings for -several symbols in a @samp{*Help*} buffer. +several symbols in a @file{*Help*} buffer. @anchor{describe-symbols example} @smallexample @@ -535,7 +535,7 @@ seems to be as a match. Each of the remaining elements is a documentation string, or @code{nil}, for @var{symbol} as a function, variable, etc. -It also displays the symbols in a buffer named @samp{*Apropos*}, each +It also displays the symbols in a buffer named @file{*Apropos*}, each with a one-line description taken from the beginning of its documentation string. @@ -648,7 +648,7 @@ certain documentation and text files that come with Emacs. @defun help-buffer This function returns the name of the help buffer, which is normally -@samp{*Help*}; if such a buffer does not exist, it is first created. +@file{*Help*}; if such a buffer does not exist, it is first created. @end defun @defmac with-help-window buffer-name body@dots{} @@ -662,16 +662,16 @@ scroll the help window. @end defmac @defun help-setup-xref item interactive-p -This function updates the cross reference data in the @samp{*Help*} +This function updates the cross reference data in the @file{*Help*} buffer, which is used to regenerate the help information when the user clicks on the @samp{Back} or @samp{Forward} buttons. Most commands -that use the @samp{*Help*} buffer should invoke this function before +that use the @file{*Help*} buffer should invoke this function before clearing the buffer. The @var{item} argument should have the form @code{(@var{function} . @var{args})}, where @var{function} is a function to call, with argument list @var{args}, to regenerate the help buffer. The @var{interactive-p} argument is non-@code{nil} if the calling command was invoked interactively; in that case, the stack of items -for the @samp{*Help*} buffer's @samp{Back} buttons is cleared. +for the @file{*Help*} buffer's @samp{Back} buttons is cleared. @end defun @xref{describe-symbols example}, for an example of using diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 365c5f3122e..c963ba03545 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -247,7 +247,7 @@ indicated with @samp{@equiv{}}. Many of the examples in this manual print text when they are evaluated. If you execute example code in a Lisp Interaction buffer -(such as the buffer @samp{*scratch*}), the printed text is inserted into +(such as the buffer @file{*scratch*}), the printed text is inserted into the buffer. If you execute the example by other means (such as by evaluating the function @code{eval-region}), the printed text is displayed in the echo area. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 5dd57ccb4ac..000bb2cbb08 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -808,7 +808,7 @@ bindings. @defun current-local-map This function returns the current buffer's local keymap, or @code{nil} if it has none. In the following example, the keymap for the -@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap +@file{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse keymap. @@ -1922,7 +1922,7 @@ other command. However, if @var{no-remap} is non-@code{nil}. @deffn Command describe-bindings &optional prefix buffer-or-name This function creates a listing of all current key bindings, and -displays it in a buffer named @samp{*Help*}. The text is grouped by +displays it in a buffer named @file{*Help*}. The text is grouped by modes---minor modes first, then the major mode, then global bindings. If @var{prefix} is non-@code{nil}, it should be a prefix key; then the diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 4e11bc30d49..a6ef0f52cfb 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1062,7 +1062,7 @@ using the value of the variable @code{minibuffer-completion-table} as the @var{collection} argument, and the value of @code{minibuffer-completion-predicate} as the @var{predicate} argument. The list of completions is displayed as text in a buffer named -@samp{*Completions*}. +@file{*Completions*}. @end deffn @defun display-completion-list completions &optional common-substring @@ -1756,7 +1756,7 @@ completion behavior is overridden. @xref{Completion Variables}. The value should be a function for @dfn{annotating} completions. The function should take one argument, @var{string}, which is a possible completion. It should return a string, which is displayed after the -completion @var{string} in the @samp{*Completions*} buffer. +completion @var{string} in the @file{*Completions*} buffer. @item display-sort-function The value should be a function for sorting completions. The function diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 946dcb91317..12abc2fcd2b 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -628,7 +628,7 @@ have set. This function sets the major mode of @var{buffer} to the default value of @code{major-mode}; if that is @code{nil}, it uses the current buffer's major mode (if that is suitable). As an exception, -if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to +if @var{buffer}'s name is @file{*scratch*}, it sets the mode to @code{initial-major-mode}. The low-level primitives for creating buffers do not use this function, @@ -637,9 +637,9 @@ but medium-level commands such as @code{switch-to-buffer} and @end defun @defopt initial-major-mode -@cindex @samp{*scratch*} +@cindex @file{*scratch*} The value of this variable determines the major mode of the initial -@samp{*scratch*} buffer. The value should be a symbol that is a major +@file{*scratch*} buffer. The value should be a symbol that is a major mode command. The default value is @code{lisp-interaction-mode}. @end defopt @@ -908,7 +908,7 @@ common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for (@pxref{Reverting}). An example of a major mode derived from Special mode is Buffer Menu -mode, which is used by the @samp{*Buffer List*} buffer. @xref{List +mode, which is used by the @file{*Buffer List*} buffer. @xref{List Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}. @end deffn @@ -2016,7 +2016,7 @@ identify the mode name in the mode line, use @code{format-mode-line} This buffer-local variable contains the mode line information on process status in modes used for communicating with subprocesses. It is displayed immediately following the major mode name, with no intervening -space. For example, its value in the @samp{*shell*} buffer is +space. For example, its value in the @file{*shell*} buffer is @code{(":%s")}, which allows the shell to display its status along with the major mode as: @samp{(Shell:run)}. Normally this variable is @code{nil}. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 649b93e6082..7c49c9e04a0 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -170,7 +170,7 @@ measurement of how long it took. It runs the normal hook @code{after-init-hook}. @item -If the buffer @samp{*scratch*} exists and is still in Fundamental mode +If the buffer @file{*scratch*} exists and is still in Fundamental mode (as it should be by default), it sets its major mode according to @code{initial-major-mode}. @@ -196,7 +196,7 @@ It now exits if the option @code{--batch} was specified. @item If @code{initial-buffer-choice} is a string, it visits the file with -that name. If the @samp{*scratch*} buffer exists and is +that name. If the @file{*scratch*} buffer exists and is empty, it inserts @code{initial-scratch-message} into that buffer. @c To make things nice and confusing, the next three items can be @@ -254,7 +254,7 @@ The following options affect some aspects of the startup sequence. @defopt inhibit-startup-screen This variable, if non-@code{nil}, inhibits the startup screen. In -that case, Emacs typically displays the @samp{*scratch*} buffer; but +that case, Emacs typically displays the @file{*scratch*} buffer; but see @code{initial-buffer-choice}, below. Do not set this variable in the init file of a new user, or in a way @@ -274,7 +274,7 @@ startup screen. @ignore @c I do not think this should be mentioned. AFAICS it is just a dodge @c around inhibit-startup-screen not being settable on a site-wide basis. -If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. +If its value is @code{t}, Emacs displays the @file{*scratch*} buffer. @end ignore @end defopt @@ -299,8 +299,8 @@ file will not inhibit the message for someone else. @defopt initial-scratch-message This variable, if non-@code{nil}, should be a string, which is -inserted into the @samp{*scratch*} buffer when Emacs starts up. If it -is @code{nil}, the @samp{*scratch*} buffer is empty. +inserted into the @file{*scratch*} buffer when Emacs starts up. If it +is @code{nil}, the @file{*scratch*} buffer is empty. @end defopt @noindent @@ -2233,7 +2233,7 @@ non-@code{nil}, Emacs tells the session manager to cancel the shutdown. @end defvar -Here is an example that just inserts some text into @samp{*scratch*} when +Here is an example that just inserts some text into @file{*scratch*} when Emacs is restarted by the session manager. @example diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index f59937da15d..1b788684d4b 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -714,7 +714,7 @@ This command displays a listing of all living processes. In addition, it finally deletes any process whose status was @samp{Exited} or @samp{Signaled}. It returns @code{nil}. -The processes are shown in a buffer named @samp{*Process List*}, whose +The processes are shown in a buffer named @file{*Process List*}, whose major mode is named Process Menu mode. If @var{query-only} is non-@code{nil} then it lists only processes diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 770dd5b5777..bae145c1694 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -4345,7 +4345,7 @@ changed text, its length is simply the difference between the first two arguments. @end defvar - Output of messages into the @samp{*Messages*} buffer does not + Output of messages into the @file{*Messages*} buffer does not call these functions. @defmac combine-after-change-calls body@dots{} -- 2.39.2