It renders the same as @samp, so there is no visible change in most cases.
2012-04-10 Glenn Morris <rgm@gnu.org>
+ * 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 <cyd@gnu.org>
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
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
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
@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;
@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.
@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
@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
@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
@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.
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.
@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}.
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,
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.
@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:
@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.
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
@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
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.
@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:
@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
@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
@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.
@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}.
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.
@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
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.
@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{}
@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
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.
@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.
@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
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
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
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,
@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
(@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
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}.
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}.
@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
@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
@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
@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
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
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
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{}
projects / emacs.git / commitdiff