-This is Info file ../info/cl.info, produced by Makeinfo version 1.68
-from the input file cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
mod* rem* random*
Internal function and variable names in the package are prefixed by
-`cl-'. Here is a complete list of functions *not* prefixed by `cl-'
+`cl-'. Here is a complete list of functions _not_ prefixed by `cl-'
which were not taken from Common Lisp:
member delete remove remq
Instead, this package defines alternates for several Lisp forms which
you must use if you need Common Lisp argument lists.
- - Special Form: defun* NAME ARGLIST BODY...
+ - Special Form: defun* name arglist body...
This form is identical to the regular `defun' form, except that
ARGLIST is allowed to be a full Common Lisp argument list. Also,
the function body is enclosed in an implicit block called NAME;
- *note Blocks and Exits::..
+ *note Blocks and Exits::.
- - Special Form: defsubst* NAME ARGLIST BODY...
+ - Special Form: defsubst* name arglist body...
This is just like `defun*', except that the function that is
defined is automatically proclaimed `inline', i.e., calls to it
may be expanded into in-line code by the byte compiler. This is
processing of keyword arguments, default values, etc., to be done
at compile-time whenever possible.
- - Special Form: defmacro* NAME ARGLIST BODY...
+ - Special Form: defmacro* name arglist body...
This is identical to the regular `defmacro' form, except that
ARGLIST is allowed to be a full Common Lisp argument list. The
`&environment' keyword is supported as described in Steele. The
Emacs Lisp interpreter. The macro expander body is enclosed in an
implicit block called NAME.
- - Special Form: function* SYMBOL-OR-LAMBDA
+ - Special Form: function* symbol-or-lambda
This is identical to the regular `function' form, except that if
the argument is a `lambda' form then that form may use a full
Common Lisp argument list.
package that include ARGLISTs in their syntax allow full Common Lisp
argument lists.
- Note that it is *not* necessary to use `defun*' in order to have
+ Note that it is _not_ necessary to use `defun*' in order to have
access to most "CL" features in your function. These features are
always present; `defun*''s only difference from `defun' is its more
flexible argument lists and its implicit block.
in a "rest" argument. Technically speaking, this is incorrect, since
`memq' looks at the odd-numbered values as well as the even-numbered
keywords. The net effect is that if you happen to pass a keyword symbol
-as the *value* of another keyword argument, where that keyword symbol
+as the _value_ of another keyword argument, where that keyword symbol
happens to equal the name of a valid keyword argument of the same
function, then the keyword parser will become confused. This minor bug
can only affect you if you use keyword symbols as general-purpose data
equivalent to `(a b &rest c)'.
If the optimization quality `safety' is set to 0 (*note
-Declarations::.), error checking for wrong number of arguments and
+Declarations::), error checking for wrong number of arguments and
invalid keyword arguments is disabled. By default, argument lists are
rigorously checked.
compiler effectively evaluates `defmacro' forms at compile-time so that
later parts of the file can refer to the macros that are defined.
- - Special Form: eval-when (SITUATIONS...) FORMS...
+ - Special Form: eval-when (situations...) forms...
This form controls when the body FORMS are evaluated. The
SITUATIONS list may contain any set of the symbols `compile',
`load', and `eval' (or their long-winded ANSI equivalents,
`(eval-when (compile load eval) ...)' and so is not itself defined by
this package.
- - Special Form: eval-when-compile FORMS...
+ - Special Form: eval-when-compile forms...
The FORMS are evaluated at compile-time; at execution time, this
form acts like a quoted constant of the resulting value. Used at
top-level, `eval-when-compile' is just like `eval-when (compile
This form is similar to the `#.' syntax of true Common Lisp.
- - Special Form: load-time-value FORM
+ - Special Form: load-time-value form
The FORM is evaluated at load-time; at execution time, this form
acts like a quoted constant of the resulting value.
This section describes a feature from GNU Emacs 19 which this package
makes available in other versions of Emacs.
- - Function: defalias SYMBOL FUNCTION
+ - Function: defalias symbol function
This function sets SYMBOL's function cell to FUNCTION. It is
equivalent to `fset', except that in GNU Emacs 19 it also records
the setting in `load-history' so that it can be undone by a later
The "CL" package defines a version of the Common Lisp `typep' predicate.
- - Function: typep OBJECT TYPE
+ - Function: typep object type
Check if OBJECT is of type TYPE, where TYPE is a (quoted) type
name of the sort used by Common Lisp. For example, `(typep foo
'integer)' is equivalent to `(integerp foo)'.
The following function and macro (not technically predicates) are
related to `typep'.
- - Function: coerce OBJECT TYPE
+ - Function: coerce object type
This function attempts to convert OBJECT to the specified TYPE.
If OBJECT is already of that type as determined by `typep', it is
simply returned. Otherwise, certain types of conversions will be
integers can be coerced in versions of Emacs that support floats.
In all other circumstances, `coerce' signals an error.
- - Special Form: deftype NAME ARGLIST FORMS...
+ - Special Form: deftype name arglist forms...
This macro defines a new type called NAME. It is similar to
`defmacro' in many ways; when NAME is encountered as a type name,
the body FORMS are evaluated and should return a type specifier
that is equivalent to the type. The ARGLIST is a Common Lisp
argument list of the sort accepted by `defmacro*'. The type
- specifier `(NAME ARGS...)' is expanded by calling the expander
+ specifier `(NAME ARGS...)' is expanded by calling the expander
with those arguments; the type symbol `NAME' is expanded by
calling the expander with no arguments. The ARGLIST is processed
the same as for `defmacro*' except that optional arguments without
This package defines two Common Lisp predicates, `eql' and `equalp'.
- - Function: eql A B
+ - Function: eql a b
This function is almost the same as `eq', except that if A and B
are numbers of the same type, it compares them for numeric
equality (as if by `equal' instead of `eq'). This makes a
fact the only known way to distinguish between the two zeros in
Emacs Lisp is to `format' them and check for a minus sign.
- - Function: equalp A B
+ - Function: equalp a b
This function is a more flexible version of `equal'. In
particular, it compares strings and characters case-insensitively,
and it compares numbers without regard to type (so that `(equalp 3
The `psetq' form is just like `setq', except that multiple assignments
are done in parallel rather than sequentially.
- - Special Form: psetq [SYMBOL FORM]...
+ - Special Form: psetq [symbol form]...
This special form (actually a macro) is used to assign to several
variables simultaneously. Given only one SYMBOL and FORM, it has
the same effect as `setq'. Given several SYMBOL and FORM pairs,
The simplest use of `psetq' is `(psetq x y y x)', which exchanges
the values of two variables. (The `rotatef' form provides an even
- more convenient way to swap two variables; *note Modify Macros::..)
+ more convenient way to swap two variables; *note Modify Macros::.)
`psetq' always returns `nil'.
The `setf' macro is the most basic way to operate on generalized
variables.
- - Special Form: setf [PLACE FORM]...
+ - Special Form: setf [place form]...
This macro evaluates FORM and stores it in PLACE, which must be a
valid generalized variable form. If there are several PLACE and
FORM pairs, the assignments are done sequentially just as with
-This is Info file ../info/cl.info, produced by Makeinfo version 1.68
-from the input file cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
operate on generalized variables. Many are interesting and useful even
when the PLACE is just a variable name.
- - Special Form: psetf [PLACE FORM]...
+ - Special Form: psetf [place form]...
This macro is to `setf' what `psetq' is to `setq': When several
PLACEs and FORMs are involved, the assignments take place in
parallel rather than sequentially. Specifically, all subforms are
evaluated from left to right, then all the assignments are done
(in an undefined order).
- - Special Form: incf PLACE &optional X
+ - Special Form: incf place &optional x
This macro increments the number stored in PLACE by one, or by X
if specified. The incremented value is returned. For example,
`(incf i)' is equivalent to `(setq i (1+ i))', and `(incf (car x)
appears to increment `i' once, then increment the element of `vec'
addressed by `i'; this is indeed exactly what it does, which means
- the above form is *not* equivalent to the "obvious" expansion,
+ the above form is _not_ equivalent to the "obvious" expansion,
(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
As a more Emacs-specific example of `incf', the expression `(incf
(point) N)' is essentially equivalent to `(forward-char N)'.
- - Special Form: decf PLACE &optional X
+ - Special Form: decf place &optional x
This macro decrements the number stored in PLACE by one, or by X
if specified.
- - Special Form: pop PLACE
+ - Special Form: pop place
This macro removes and returns the first element of the list stored
in PLACE. It is analogous to `(prog1 (car PLACE) (setf PLACE (cdr
PLACE)))', except that it takes care to evaluate all subforms only
once.
- - Special Form: push X PLACE
+ - Special Form: push x place
This macro inserts X at the front of the list stored in PLACE. It
is analogous to `(setf PLACE (cons X PLACE))', except for
evaluation of the subforms.
- - Special Form: pushnew X PLACE &key :test :test-not :key
+ - Special Form: pushnew x place &key :test :test-not :key
This macro inserts X at the front of the list stored in PLACE, but
only if X was not `eql' to any existing element of the list. The
optional keyword arguments are interpreted in the same way as for
`adjoin'. *Note Lists as Sets::.
- - Special Form: shiftf PLACE... NEWVALUE
+ - Special Form: shiftf place... newvalue
This macro shifts the PLACEs left by one, shifting in the value of
NEWVALUE (which may be any Lisp expression, not just a generalized
variable), and returning the value shifted out of the first PLACE.
except that the subforms of A, B, and C are actually evaluated
only once each and in the apparent order.
- - Special Form: rotatef PLACE...
+ - Special Form: rotatef place...
This macro rotates the PLACEs left by one in circular fashion.
Thus, `(rotatef A B C D)' is equivalent to
The following macros were invented for this package; they have no
analogues in Common Lisp.
- - Special Form: letf (BINDINGS...) FORMS...
+ - Special Form: letf (bindings...) forms...
This macro is analogous to `let', but for generalized variables
rather than just symbols. Each BINDING should be of the form
`(PLACE VALUE)'; the original contents of the PLACEs are saved,
not bound on entry, it is simply made unbound by `makunbound' or
`fmakunbound' on exit.
- - Special Form: letf* (BINDINGS...) FORMS...
+ - Special Form: letf* (bindings...) forms...
This macro is to `letf' what `let*' is to `let': It does the
bindings in sequential rather than parallel order.
that `callf' is an extension to standard Common Lisp.
- Special Form: callf2 FUNCTION ARG1 PLACE ARGS...
- This macro is like `callf', except that PLACE is the *second*
+ This macro is like `callf', except that PLACE is the _second_
argument of FUNCTION rather than the first. For example, `(push X
PLACE)' is equivalent to `(callf2 cons X PLACE)'.
The `callf' and `callf2' macros serve as building blocks for other
macros like `incf', `pushnew', and `define-modify-macro'. The `letf'
and `letf*' macros are used in the processing of symbol macros; *note
-Macro Bindings::..
+Macro Bindings::.
\1f
File: cl.info, Node: Customizing Setf, Prev: Modify Macros, Up: Generalized Variables
`define-setf-method', that allow the user to extend generalized
variables in various ways.
- - Special Form: define-modify-macro NAME ARGLIST FUNCTION [DOC-STRING]
+ - Special Form: define-modify-macro name arglist function [doc-string]
This macro defines a "read-modify-write" macro similar to `incf'
and `decf'. The macro NAME is defined to take a PLACE argument
followed by additional arguments described by ARGLIST. The call
`get-setf-method', or consult the source file `cl-macs.el' to see
how to use the internal `setf' building blocks.
- - Special Form: defsetf ACCESS-FN UPDATE-FN
+ - Special Form: defsetf access-fn update-fn
This is the simpler of two `defsetf' forms. Where ACCESS-FN is
the name of a function which accesses a place, this declares
UPDATE-FN to be the corresponding store function. From now on,
(defsetf symbol-value set)
(defsetf buffer-name rename-buffer t)
- - Special Form: defsetf ACCESS-FN ARGLIST (STORE-VAR) FORMS...
+ - Special Form: defsetf access-fn arglist (store-var) forms...
This is the second, more complex, form of `defsetf'. It is rather
like `defmacro' except for the additional STORE-VAR argument. The
FORMS should return a Lisp form which stores the value of
(defsetf nth (n x) (store)
(list 'setcar (list 'nthcdr n x) store))
- - Special Form: define-setf-method ACCESS-FN ARGLIST FORMS...
+ - Special Form: define-setf-method access-fn arglist forms...
This is the most general way to create new place forms. When a
`setf' to ACCESS-FN with arguments described by ARGLIST is
expanded, the FORMS are evaluated and must return a list of five
optimize away most temporaries that turn out to be unnecessary, so
there is little reason for the setf-method itself to optimize.
- - Function: get-setf-method PLACE &optional ENV
+ - Function: get-setf-method place &optional env
This function returns the setf-method for PLACE, by invoking the
definition previously recorded by `defsetf' or
`define-setf-method'. The result is a list of five values as
Modern Common Lisp defines a second, independent way to specify the
`setf' behavior of a function, namely "`setf' functions" whose names
are lists `(setf NAME)' rather than symbols. For example, `(defun
-(setf foo) ...)' defines the function that is used when `setf' is
+(setf foo) ...)' defines the function that is used when `setf' is
applied to `foo'. This package does not currently support `setf'
functions. In particular, it is a compile-time error to use `setf' on
a form which has not already been `defsetf''d or otherwise declared; in
compile-time. The `progv' form provides an easy way to bind variables
whose names are computed at run-time.
- - Special Form: progv SYMBOLS VALUES FORMS...
+ - Special Form: progv symbols values forms...
This form establishes `let'-style variable bindings on a set of
variables computed at run-time. The expressions SYMBOLS and
VALUES are evaluated, and must return lists of symbols and values,
The "CL" package defines the following macro which more closely follows
the Common Lisp `let' form:
- - Special Form: lexical-let (BINDINGS...) FORMS...
+ - Special Form: lexical-let (bindings...) forms...
This form is exactly like `let' except that the bindings it
establishes are purely lexical. Lexical bindings are similar to
local variables in a language like C: Only the code physically
The `lexical-let' form is an extension to Common Lisp. In true
Common Lisp, all bindings are lexical unless declared otherwise.
- - Special Form: lexical-let* (BINDINGS...) FORMS...
+ - Special Form: lexical-let* (bindings...) forms...
This form is just like `lexical-let', except that the bindings are
made sequentially in the manner of `let*'.
These forms make `let'-like bindings to functions instead of variables.
- - Special Form: flet (BINDINGS...) FORMS...
+ - Special Form: flet (bindings...) forms...
This form establishes `let'-style bindings on the function cells
of symbols rather than on the value cells. Each BINDING must be a
list of the form `(NAME ARGLIST FORMS...)', which defines a
enclosed in an implicit block as if by `defun*'. *Note Program
Structure::.
- - Special Form: labels (BINDINGS...) FORMS...
+ - Special Form: labels (bindings...) forms...
The `labels' form is a synonym for `flet'. (In Common Lisp,
`labels' and `flet' differ in ways that depend on their lexical
scoping; these distinctions vanish in dynamically scoped Emacs
These forms create local macros and "symbol macros."
- - Special Form: macrolet (BINDINGS...) FORMS...
+ - Special Form: macrolet (bindings...) forms...
This form is analogous to `flet', but for macros instead of
functions. Each BINDING is a list of the same form as the
arguments to `defmacro*' (i.e., a macro name, argument list, and
that appear physically within the body FORMS, possibly after
expansion of other macros in the body.
- - Special Form: symbol-macrolet (BINDINGS...) FORMS...
+ - Special Form: symbol-macrolet (bindings...) forms...
This form creates "symbol macros", which are macros that look like
variable references rather than function calls. Each BINDING is a
list `(VAR EXPANSION)'; any reference to VAR within the body FORMS
=> (2 3 4 5)
In this example, the `my-dolist' macro is similar to `dolist'
- (*note Iteration::.) except that the variable `x' becomes a true
+ (*note Iteration::) except that the variable `x' becomes a true
reference onto the elements of the list. The `my-dolist' call
shown here expands to
These conditional forms augment Emacs Lisp's simple `if', `and', `or',
and `cond' forms.
- - Special Form: when TEST FORMS...
+ - Special Form: when test forms...
This is a variant of `if' where there are no "else" forms, and
possibly several "then" forms. In particular,
(if TEST (progn A B C) nil)
- - Special Form: unless TEST FORMS...
+ - Special Form: unless test forms...
This is a variant of `if' where there are no "then" forms, and
possibly several "else" forms:
(when (not TEST) A B C)
- - Special Form: case KEYFORM CLAUSE...
+ - Special Form: case keyform clause...
This macro evaluates KEYFORM, then compares it with the key values
listed in the various CLAUSEs. Whichever clause matches the key
is executed; comparison is done by `eql'. If no clause matches,
((?\r ?\n) (do-ret-thing))
(t (do-other-thing)))
- - Special Form: ecase KEYFORM CLAUSE...
+ - Special Form: ecase keyform clause...
This macro is just like `case', except that if the key does not
match any of the clauses, an error is signalled rather than simply
returning `nil'.
- - Special Form: typecase KEYFORM CLAUSE...
+ - Special Form: typecase keyform clause...
This macro is a version of `case' that checks for types rather
than values. Each CLAUSE is of the form `(TYPE BODY...)'. *Note
Type Predicates::, for a description of type specifiers. For
`otherwise' is also allowed. To make one clause match any of
several types, use an `(or ...)' type specifier.
- - Special Form: etypecase KEYFORM CLAUSE...
+ - Special Form: etypecase keyform clause...
This macro is just like `typecase', except that if the key does
not match any of the clauses, an error is signalled rather than
simply returning `nil'.
costly `catch' step if the body of the block does not actually
`return-from' the block.
- - Special Form: block NAME FORMS...
+ - Special Form: block name forms...
The FORMS are evaluated as if by a `progn'. However, if any of
the FORMS execute `(return-from NAME)', they will jump out and
return directly from the `block' form. The `block' returns the
that `do' loops and `defun*' functions which don't use `return'
don't pay the overhead to support it.
- - Special Form: return-from NAME [RESULT]
+ - Special Form: return-from name [result]
This macro returns from the block named NAME, which must be an
(unevaluated) symbol. If a RESULT form is specified, it is
evaluated to produce the result returned from the `block'.
Otherwise, `nil' is returned.
- - Special Form: return [RESULT]
+ - Special Form: return [result]
This macro is exactly like `(return-from nil RESULT)'. Common
Lisp loops like `do' and `dolist' implicitly enclose themselves in
`nil' blocks.
The macros described here provide more sophisticated, high-level
looping constructs to complement Emacs Lisp's basic `while' loop.
- - Special Form: loop FORMS...
+ - Special Form: loop forms...
The "CL" package supports both the simple, old-style meaning of
`loop' and the extremely powerful and flexible feature known as
the "Loop Facility" or "Loop Macro". This more advanced facility
- is discussed in the following section; *note Loop Facility::..
- The simple form of `loop' is described here.
+ is discussed in the following section; *note Loop Facility::. The
+ simple form of `loop' is described here.
If `loop' is followed by zero or more Lisp expressions, then
`(loop EXPRS...)' simply creates an infinite loop executing the
the above notation would simply access and throw away the value of
a variable.)
- - Special Form: do (SPEC...) (END-TEST [RESULT...]) FORMS...
+ - Special Form: do (spec...) (end-test [result...]) forms...
This macro creates a general iterative loop. Each SPEC is of the
form
VAR has no STEP form, it is bound to its INIT value but not
otherwise modified during the `do' loop (unless the code
explicitly modifies it); this case is just a shorthand for putting
- a `(let ((VAR INIT)) ...)' around the loop. If INIT is also
+ a `(let ((VAR INIT)) ...)' around the loop. If INIT is also
omitted it defaults to `nil', and in this case a plain `VAR' can
be used in place of `(VAR)', again following the analogy with
`let'.
((or (null x) (null y))
(nreverse z)))
- - Special Form: do* (SPEC...) (END-TEST [RESULT...]) FORMS...
+ - Special Form: do* (spec...) (end-test [result...]) forms...
This is to `do' what `let*' is to `let'. In particular, the
initial values are bound as if by `let*' rather than `let', and
the steps are assigned as if by `setq' rather than `psetq'.
(nreverse z))
(push (f x y) z))
- - Special Form: dolist (VAR LIST [RESULT]) FORMS...
+ - Special Form: dolist (var list [result]) forms...
This is a more specialized loop which iterates across the elements
of a list. LIST should evaluate to a list; the body FORMS are
executed with VAR bound to each element of the list in turn.
`nil' to produce the result returned by the loop. The loop is
surrounded by an implicit `nil' block.
- - Special Form: dotimes (VAR COUNT [RESULT]) FORMS...
+ - Special Form: dotimes (var count [result]) forms...
This is a more specialized loop which iterates a specified number
of times. The body is executed with VAR bound to the integers
from zero (inclusive) to COUNT (exclusive), in turn. Then the
return value for the loop form. The loop is surrounded by an
implicit `nil' block.
- - Special Form: do-symbols (VAR [OBARRAY [RESULT]]) FORMS...
+ - Special Form: do-symbols (var [obarray [result]]) forms...
This loop iterates over all interned symbols. If OBARRAY is
specified and is not `nil', it loops over all symbols in that
obarray. For each symbol, the body FORMS are evaluated with VAR
bound to `nil') to get the return value. The loop is surrounded
by an implicit `nil' block.
- - Special Form: do-all-symbols (VAR [RESULT]) FORMS...
+ - Special Form: do-all-symbols (var [result]) forms...
This is identical to `do-symbols' except that the OBARRAY argument
is omitted; it always iterates over the default obarray.
place at byte-compile time; compiled `loop's are just as efficient as
the equivalent `while' loops written longhand.
- - Special Form: loop CLAUSES...
+ - Special Form: loop clauses...
A loop construct consists of a series of CLAUSEs, each introduced
by a symbol like `for' or `do'. Clauses are simply strung
together in the argument list of `loop', with minimal extra
-This is Info file ../info/cl.info, produced by Makeinfo version 1.68
-from the input file cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
This clause type is taken from older versions of the `loop' macro,
and is not present in modern Common Lisp. The `using (sequence
- ...)' term of the older macros is not supported.
+ ...)' term of the older macros is not supported.
`for VAR being the elements of-ref SEQUENCE'
This clause iterates over a sequence, with VAR a `setf'-able
Due to a minor implementation restriction, it will not work to have
more than one `for' clause iterating over symbols, hash tables,
keymaps, overlays, or intervals in a given `loop'. Fortunately,
- it would rarely if ever be useful to do so. It *is* legal to mix
+ it would rarely if ever be useful to do so. It _is_ legal to mix
one of these types of clauses with other clauses like `for ... to'
or `while'.
makes no attempt to emulate Common Lisp multiple return values; Emacs
versions of Common Lisp functions that return more than one value
either return just the first value (as in `compiler-macroexpand') or
-return a list of values (as in `get-setf-method'). This package *does*
+return a list of values (as in `get-setf-method'). This package _does_
define placeholders for the Common Lisp functions that work with
multiple values, but in Emacs Lisp these functions simply operate on
lists instead. The `values' form, for example, is a synonym for `list'
in Emacs.
- - Special Form: multiple-value-bind (VAR...) VALUES-FORM FORMS...
+ - Special Form: multiple-value-bind (var...) values-form forms...
This form evaluates VALUES-FORM, which must return a list of
values. It then binds the VARs to these respective values, as if
by `let', and then executes the body FORMS. If there are more
VARs than values, the extra VARs are bound to `nil'. If there are
fewer VARs than values, the excess values are ignored.
- - Special Form: multiple-value-setq (VAR...) FORM
+ - Special Form: multiple-value-setq (var...) form
This form evaluates FORM, which must return a list of values. It
then sets the VARs to these respective values, as if by `setq'.
Extra VARs or values are treated the same as in
Destructuring is made available to the user by way of the following
macro:
- - Special Form: destructuring-bind ARGLIST EXPR FORMS...
+ - Special Form: destructuring-bind arglist expr forms...
This macro expands to code which executes FORMS, with the
variables in ARGLIST bound to the list of values returned by EXPR.
The ARGLIST can include all the features allowed for `defmacro'
facility, which allows you to define compile-time expansions and
optimizations for your functions.
- - Special Form: define-compiler-macro NAME ARGLIST FORMS...
+ - Special Form: define-compiler-macro name arglist forms...
This form is similar to `defmacro', except that it only expands
calls to NAME at compile-time; calls processed by the Lisp
interpreter are not expanded, nor are they expanded by the
optimizes a number of other cases, including common `:test'
predicates.)
- - Function: compiler-macroexpand FORM
+ - Function: compiler-macroexpand form
This function is analogous to `macroexpand', except that it
expands compiler macros rather than regular macros. It returns
FORM unchanged if it is not a call to a function for which a
Under the earlier non-optimizing compiler, these declarations will
effectively be ignored.
- - Function: proclaim DECL-SPEC
+ - Function: proclaim decl-spec
This function records a "global" declaration specified by
DECL-SPEC. Since `proclaim' is a function, DECL-SPEC is evaluated
and thus should normally be quoted.
- - Special Form: declaim DECL-SPECS...
+ - Special Form: declaim decl-specs...
This macro is like `proclaim', except that it takes any number of
DECL-SPEC arguments, and the arguments are unevaluated and
unquoted. The `declaim' macro also puts an `(eval-when (compile
compiler treats the rest of the file that contains the `declaim'
form.)
- - Special Form: declare DECL-SPECS...
+ - Special Form: declare decl-specs...
This macro is used to make declarations within functions and other
code. Common Lisp allows declarations in various locations,
generally at the beginning of any of the many "implicit `progn's"
etc. Currently the only declaration understood by `declare' is
`special'.
- - Special Form: locally DECLARATIONS... FORMS...
+ - Special Form: locally declarations... forms...
In this package, `locally' is no different from `progn'.
- - Special Form: the TYPE FORM
+ - Special Form: the type form
Type information provided by `the' is ignored in this package; in
other words, `(the TYPE FORM)' is equivalent to FORM. Future
versions of the optimizing byte-compiler may make use of this
functions for working with property lists as first-class data
structures not attached to particular symbols.
- - Function: get* SYMBOL PROPERTY &optional DEFAULT
+ - Function: get* symbol property &optional default
This function is like `get', except that if the property is not
found, the DEFAULT argument provides the return value. (The Emacs
Lisp `get' function always uses `nil' as the default; this
The `get*' function is `setf'-able; when used in this fashion, the
DEFAULT argument is allowed but ignored.
- - Function: remprop SYMBOL PROPERTY
+ - Function: remprop symbol property
This function removes the entry for PROPERTY from the property
list of SYMBOL. It returns a true value if the property was
indeed found and removed, or `nil' if there was no such property.
was `nil'; thus, setting a property to `nil' was close enough to
`remprop' for most purposes.)
- - Function: getf PLACE PROPERTY &optional DEFAULT
+ - Function: getf place property &optional default
This function scans the list PLACE as if it were a property list,
i.e., a list of alternating property names and values. If an
even-numbered element of PLACE is found which is `eq' to PROPERTY,
When not used as a `setf' form, `getf' is just a regular function
and its PLACE argument can actually be any Lisp expression.
- - Special Form: remf PLACE PROPERTY
+ - Special Form: remf place property
This macro removes the property-value pair for PROPERTY from the
property list stored at PLACE, which is any `setf'-able place
expression. It returns true if the property was found. Note that
These functions create unique symbols, typically for use as temporary
variables.
- - Function: gensym &optional X
+ - Function: gensym &optional x
This function creates a new, uninterned symbol (using
`make-symbol') with a unique name. (The name of an uninterned
symbol is relevant only if the symbol is printed.) By default,
and uninterned symbols, so their names had to be treated more
carefully.
- - Function: gentemp &optional X
+ - Function: gentemp &optional x
This function is like `gensym', except that it produces a new
- *interned* symbol. If the symbol that is generated already
+ _interned_ symbol. If the symbol that is generated already
exists, the function keeps incrementing the counter and trying
again until a new symbol is generated.
These functions return `t' if the specified condition is true of the
numerical argument, or `nil' otherwise.
- - Function: plusp NUMBER
+ - Function: plusp number
This predicate tests whether NUMBER is positive. It is an error
if the argument is not a number.
- - Function: minusp NUMBER
+ - Function: minusp number
This predicate tests whether NUMBER is negative. It is an error
if the argument is not a number.
- - Function: oddp INTEGER
+ - Function: oddp integer
This predicate tests whether INTEGER is odd. It is an error if
the argument is not an integer.
- - Function: evenp INTEGER
+ - Function: evenp integer
This predicate tests whether INTEGER is even. It is an error if
the argument is not an integer.
- - Function: floatp-safe OBJECT
+ - Function: floatp-safe object
This predicate tests whether OBJECT is a floating-point number.
On systems that support floating-point, this is equivalent to
`floatp'. On other systems, this always returns `nil'.
These functions perform various arithmetic operations on numbers.
- - Function: abs NUMBER
+ - Function: abs number
This function returns the absolute value of NUMBER. (Newer
versions of Emacs provide this as a built-in function; this package
defines `abs' only for Emacs 18 versions which don't provide it as
a primitive.)
- - Function: expt BASE POWER
+ - Function: expt base power
This function returns BASE raised to the power of NUMBER. (Newer
versions of Emacs provide this as a built-in function; this
package defines `expt' only for Emacs 18 versions which don't
provide it as a primitive.)
- - Function: gcd &rest INTEGERS
+ - Function: gcd &rest integers
This function returns the Greatest Common Divisor of the arguments.
For one argument, it returns the absolute value of that argument.
For zero arguments, it returns zero.
- - Function: lcm &rest INTEGERS
+ - Function: lcm &rest integers
This function returns the Least Common Multiple of the arguments.
For one argument, it returns the absolute value of that argument.
For zero arguments, it returns one.
- - Function: isqrt INTEGER
+ - Function: isqrt integer
This function computes the "integer square root" of its integer
argument, i.e., the greatest integer less than or equal to the true
square root of the argument.
- - Function: floor* NUMBER &optional DIVISOR
+ - Function: floor* number &optional divisor
This function implements the Common Lisp `floor' function. It is
called `floor*' to avoid name conflicts with the simpler `floor'
function built-in to Emacs 19.
function, except that it returns the two results in a list since
Emacs Lisp does not support multiple-valued functions.
- - Function: ceiling* NUMBER &optional DIVISOR
+ - Function: ceiling* number &optional divisor
This function implements the Common Lisp `ceiling' function, which
is analogous to `floor' except that it rounds the argument or
quotient of the arguments up toward plus infinity. The remainder
will be between 0 and minus R.
- - Function: truncate* NUMBER &optional DIVISOR
+ - Function: truncate* number &optional divisor
This function implements the Common Lisp `truncate' function,
which is analogous to `floor' except that it rounds the argument
or quotient of the arguments toward zero. Thus it is equivalent
to `floor*' if the argument or quotient is positive, or to
`ceiling*' otherwise. The remainder has the same sign as NUMBER.
- - Function: round* NUMBER &optional DIVISOR
+ - Function: round* number &optional divisor
This function implements the Common Lisp `round' function, which
is analogous to `floor' except that it rounds the argument or
quotient of the arguments to the nearest integer. In the case of
a tie (the argument or quotient is exactly halfway between two
integers), it rounds to the even integer.
- - Function: mod* NUMBER DIVISOR
+ - Function: mod* number divisor
This function returns the same value as the second return value of
`floor'.
- - Function: rem* NUMBER DIVISOR
+ - Function: rem* number divisor
This function returns the same value as the second return value of
`truncate'.
which is much more likely to give statistically clean random numbers
than the simple generators supplied by many operating systems.
- - Function: random* NUMBER &optional STATE
+ - Function: random* number &optional state
This function returns a random nonnegative number less than
NUMBER, and of the same type (either integer or floating-point).
The STATE argument should be a `random-state' object which holds
sequence generated from this variable will be irreproducible for
all intents and purposes.
- - Function: make-random-state &optional STATE
+ - Function: make-random-state &optional state
This function creates or copies a `random-state' object. If STATE
is omitted or `nil', it returns a new copy of `*random-state*'.
This is a copy in the sense that future sequences of calls to
later rerun, it can read the original run's random-state from the
file.
- - Function: random-state-p OBJECT
+ - Function: random-state-p object
This predicate returns `t' if OBJECT is a `random-state' object,
or `nil' otherwise.
-This is Info file ../info/cl.info, produced by Makeinfo version 1.68
-from the input file cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
- Variable: most-positive-float
This constant equals the largest value a Lisp float can hold. For
those systems whose arithmetic supports infinities, this is the
- largest *finite* value. For IEEE machines, the value is
+ largest _finite_ value. For IEEE machines, the value is
approximately `1.79e+308'.
- Variable: most-negative-float
supported or `2.22e-308' if not.
- Variable: least-positive-normalized-float
- This constant equals the smallest *normalized* Lisp float greater
+ This constant equals the smallest _normalized_ Lisp float greater
than zero, i.e., the smallest value for which IEEE denormalization
will not result in a loss of precision. For IEEE machines, this
value is about `2.22e-308'. For machines that do not support the
===============
Many of the sequence functions take keyword arguments; *note Argument
-Lists::.. All keyword arguments are optional and, if specified, may
+Lists::. All keyword arguments are optional and, if specified, may
appear in any order.
The `:key' argument should be passed either `nil', or a function of
or, if they both come from the same sequence, in the same order as they
appear in that sequence.) The `:test' argument specifies a function
which must return true (non-`nil') to indicate a match; instead, you
-may use `:test-not' to give a function which returns *false* to
+may use `:test-not' to give a function which returns _false_ to
indicate a match. The default test function is `:test 'eql'.
Many functions which take ITEM and `:test' or `:test-not' arguments
these functions. For example, `:from-end' may cause the sequence to be
scanned actually in reverse, or it may be scanned forwards but
computing a result "as if" it were scanned backwards. (Some functions,
-like `mapcar*' and `every', *do* specify exactly the order in which the
+like `mapcar*' and `every', _do_ specify exactly the order in which the
function is called so side effects are perfectly acceptable in those
cases.)
lists or arrays. They are all variations on the theme of the built-in
function `mapcar'.
- - Function: mapcar* FUNCTION SEQ &rest MORE-SEQS
+ - Function: mapcar* function seq &rest more-seqs
This function calls FUNCTION on successive parallel sets of
elements from its argument sequences. Given a single SEQ argument
it is equivalent to `mapcar'; given N sequences, it calls the
argument. This package's `mapcar*' works as a compatible superset
of both.
- - Function: map RESULT-TYPE FUNCTION SEQ &rest MORE-SEQS
+ - Function: map result-type function seq &rest more-seqs
This function maps FUNCTION over the argument sequences, just like
`mapcar*', but it returns a sequence of type RESULT-TYPE rather
than a list. RESULT-TYPE must be one of the following symbols:
as for `mapcar*'), or `nil' (in which case the results are thrown
away and `map' returns `nil').
- - Function: maplist FUNCTION LIST &rest MORE-LISTS
+ - Function: maplist function list &rest more-lists
This function calls FUNCTION on each of its argument lists, then
on the `cdr's of those lists, and so on, until the shortest list
runs out. The results are returned in the form of a list. Thus,
pointers themselves rather than the `car's of the advancing
pointers.
- - Function: mapc FUNCTION SEQ &rest MORE-SEQS
+ - Function: mapc function seq &rest more-seqs
This function is like `mapcar*', except that the values returned
by FUNCTION are ignored and thrown away rather than being
collected into a list. The return value of `mapc' is SEQ, the
first sequence.
- - Function: mapl FUNCTION LIST &rest MORE-LISTS
+ - Function: mapl function list &rest more-lists
This function is like `maplist', except that it throws away the
values returned by FUNCTION.
- - Function: mapcan FUNCTION SEQ &rest MORE-SEQS
+ - Function: mapcan function seq &rest more-seqs
This function is like `mapcar*', except that it concatenates the
return values (which must be lists) using `nconc', rather than
simply collecting them into a list.
- - Function: mapcon FUNCTION LIST &rest MORE-LISTS
+ - Function: mapcon function list &rest more-lists
This function is like `maplist', except that it concatenates the
return values using `nconc'.
- - Function: some PREDICATE SEQ &rest MORE-SEQS
+ - Function: some predicate seq &rest more-seqs
This function calls PREDICATE on each element of SEQ in turn; if
PREDICATE returns a non-`nil' value, `some' returns that value,
otherwise it returns `nil'. Given several sequence arguments, it
order in which the elements are visited, and on the fact that
mapping stops immediately as soon as PREDICATE returns non-`nil'.
- - Function: every PREDICATE SEQ &rest MORE-SEQS
+ - Function: every predicate seq &rest more-seqs
This function calls PREDICATE on each element of the sequence(s)
in turn; it returns `nil' as soon as PREDICATE returns `nil' for
any element, or `t' if the predicate was true for all elements.
- - Function: notany PREDICATE SEQ &rest MORE-SEQS
+ - Function: notany predicate seq &rest more-seqs
This function calls PREDICATE on each element of the sequence(s)
in turn; it returns `nil' as soon as PREDICATE returns a non-`nil'
value for any element, or `t' if the predicate was `nil' for all
elements.
- - Function: notevery PREDICATE SEQ &rest MORE-SEQS
+ - Function: notevery predicate seq &rest more-seqs
This function calls PREDICATE on each element of the sequence(s)
in turn; it returns a non-`nil' value as soon as PREDICATE returns
`nil' for any element, or `t' if the predicate was true for all
elements.
- - Function: reduce FUNCTION SEQ &key :from-end :start :end
+ - Function: reduce function seq &key :from-end :start :end
:initial-value :key
This function combines the elements of SEQ using an associative
binary operation. Suppose FUNCTION is `*' and SEQ is the list `(2
If `:initial-value' is specified, it is effectively added to the
front (or rear in the case of `:from-end') of the sequence. The
- `:key' function is *not* applied to the initial value.
+ `:key' function is _not_ applied to the initial value.
If the sequence, including the initial value, has exactly one
element then that element is returned without ever calling
This section describes a number of Common Lisp functions for operating
on sequences.
- - Function: subseq SEQUENCE START &optional END
+ - Function: subseq sequence start &optional end
This function returns a given subsequence of the argument
SEQUENCE, which may be a list, string, or vector. The indices
START and END must be in range, and START must be no greater than
As an extension to Common Lisp, START and/or END may be negative,
in which case they represent a distance back from the end of the
sequence. This is for compatibility with Emacs' `substring'
- function. Note that `subseq' is the *only* sequence function that
+ function. Note that `subseq' is the _only_ sequence function that
allows negative START and END.
You can use `setf' on a `subseq' form to replace a specified range
of elements with elements from another sequence. The replacement
is done as if by `replace', described below.
- - Function: concatenate RESULT-TYPE &rest SEQS
+ - Function: concatenate result-type &rest seqs
This function concatenates the argument sequences together to form
a result sequence of type RESULT-TYPE, one of the symbols
`vector', `string', or `list'. The arguments are always copied,
even in cases such as `(concatenate 'list '(1 2 3))' where the
result is identical to an argument.
- - Function: fill SEQ ITEM &key :start :end
+ - Function: fill seq item &key :start :end
This function fills the elements of the sequence (or the specified
part of the sequence) with the value ITEM.
- - Function: replace SEQ1 SEQ2 &key :start1 :end1 :start2 :end2
+ - Function: replace seq1 seq2 &key :start1 :end1 :start2 :end2
This function copies part of SEQ2 into part of SEQ1. The sequence
SEQ1 is not stretched or resized; the amount of data copied is
simply the shorter of the source and destination (sub)sequences.
share storage but are not `eq', and the start and end arguments
specify overlapping regions, the effect is undefined.
- - Function: remove* ITEM SEQ &key :test :test-not :key :count :start
+ - Function: remove* item seq &key :test :test-not :key :count :start
:end :from-end
This returns a copy of SEQ with all elements matching ITEM
removed. The result may share storage with or be `eq' to SEQ in
sequence rather than the beginning (this matters only if COUNT was
also specified).
- - Function: delete* ITEM SEQ &key :test :test-not :key :count :start
+ - Function: delete* item seq &key :test :test-not :key :count :start
:end :from-end
This deletes all elements of SEQ which match ITEM. It is a
destructive operation. Since Emacs Lisp does not support
The predicate-oriented functions `remove-if', `remove-if-not',
`delete-if', and `delete-if-not' are defined similarly.
- - Function: delete ITEM LIST
+ - Function: delete item list
This MacLisp-compatible function deletes from LIST all elements
which are `equal' to ITEM. The `delete' function is built-in to
Emacs 19; this package defines it equivalently in Emacs 18.
- - Function: remove ITEM LIST
+ - Function: remove item list
This function removes from LIST all elements which are `equal' to
ITEM. This package defines it for symmetry with `delete', even
though `remove' is not built-in to Emacs 19.
- - Function: remq ITEM LIST
+ - Function: remq item list
This function removes from LIST all elements which are `eq' to
ITEM. This package defines it for symmetry with `delq', even
though `remq' is not built-in to Emacs 19.
- - Function: remove-duplicates SEQ &key :test :test-not :key :start
+ - Function: remove-duplicates seq &key :test :test-not :key :start
:end :from-end
This function returns a copy of SEQ with duplicate elements
removed. Specifically, if two elements from the sequence match
specified, only elements within that subsequence are examined or
removed.
- - Function: delete-duplicates SEQ &key :test :test-not :key :start
+ - Function: delete-duplicates seq &key :test :test-not :key :start
:end :from-end
This function deletes duplicate elements from SEQ. It is a
destructive version of `remove-duplicates'.
- - Function: substitute NEW OLD SEQ &key :test :test-not :key :count
+ - Function: substitute new old seq &key :test :test-not :key :count
:start :end :from-end
This function returns a copy of SEQ, with all elements matching
OLD replaced with NEW. The `:count', `:start', `:end', and
`:from-end' arguments may be used to limit the number of
substitutions made.
- - Function: nsubstitute NEW OLD SEQ &key :test :test-not :key :count
+ - Function: nsubstitute new old seq &key :test :test-not :key :count
:start :end :from-end
This is a destructive version of `substitute'; it performs the
substitution using `setcar' or `aset' rather than by returning a
===================
These functions search for elements or subsequences in a sequence.
-(See also `member*' and `assoc*'; *note Lists::..)
+(See also `member*' and `assoc*'; *note Lists::.)
- - Function: find ITEM SEQ &key :test :test-not :key :start :end
+ - Function: find item seq &key :test :test-not :key :start :end
:from-end
This function searches SEQ for an element matching ITEM. If it
finds a match, it returns the matching element. Otherwise, it
`:start' and `:end' arguments may be used to limit the range of
elements that are searched.
- - Function: position ITEM SEQ &key :test :test-not :key :start :end
+ - Function: position item seq &key :test :test-not :key :start :end
:from-end
This function is like `find', except that it returns the integer
position in the sequence of the matching item rather than the item
a whole, even if `:start' is non-zero. The function returns `nil'
if no matching element was found.
- - Function: count ITEM SEQ &key :test :test-not :key :start :end
+ - Function: count item seq &key :test :test-not :key :start :end
This function returns the number of elements of SEQ which match
ITEM. The result is always a nonnegative integer.
The `find-if', `find-if-not', `position-if', `position-if-not',
`count-if', and `count-if-not' functions are defined similarly.
- - Function: mismatch SEQ1 SEQ2 &key :test :test-not :key :start1 :end1
+ - Function: mismatch seq1 seq2 &key :test :test-not :key :start1 :end1
:start2 :end2 :from-end
This function compares the specified parts of SEQ1 and SEQ2. If
they are the same length and the corresponding elements match
An interesting example is `(mismatch str1 str2 :key 'upcase)',
which compares two strings case-insensitively.
- - Function: search SEQ1 SEQ2 &key :test :test-not :key :from-end
+ - Function: search seq1 seq2 &key :test :test-not :key :from-end
:start1 :end1 :start2 :end2
This function searches SEQ2 for a subsequence that matches SEQ1
(or part of it specified by `:start1' and `:end1'.) Only matches
`:end2' will be considered. The return value is the index of the
leftmost element of the leftmost match, relative to the start of
SEQ2, or `nil' if no matches were found. If `:from-end' is true,
- the function finds the *rightmost* matching subsequence.
+ the function finds the _rightmost_ matching subsequence.
\1f
File: cl.info, Node: Sorting Sequences, Prev: Searching Sequences, Up: Sequences
Sorting Sequences
=================
- - Function: sort* SEQ PREDICATE &key :key
+ - Function: sort* seq predicate &key :key
This function sorts SEQ into increasing order as determined by
using PREDICATE to compare pairs of elements. PREDICATE should
return true (non-`nil') if and only if its first argument is less
The `sort*' function is destructive; it sorts lists by actually
rearranging the `cdr' pointers in suitable fashion.
- - Function: stable-sort SEQ PREDICATE &key :key
+ - Function: stable-sort seq predicate &key :key
This function sorts SEQ "stably", meaning two elements which are
equal in terms of PREDICATE are guaranteed not to be rearranged
out of their original order by the sort.
However, this package reserves the right to use non-stable methods
for `sort*' in the future.
- - Function: merge TYPE SEQ1 SEQ2 PREDICATE &key :key
+ - Function: merge type seq1 seq2 predicate &key :key
This function merges two sequences SEQ1 and SEQ2 by interleaving
their elements. The result sequence, of type TYPE (in the sense
of `concatenate'), has length equal to the sum of the lengths of
This section describes a number of simple operations on lists, i.e.,
chains of cons cells.
- - Function: caddr X
+ - Function: caddr x
This function is equivalent to `(car (cdr (cdr X)))'. Likewise,
this package defines all 28 `cXXXr' functions where XXX is up to
four `a's and/or `d's. All of these functions are `setf'-able,
and calls to them are expanded inline by the byte-compiler for
maximum efficiency.
- - Function: first X
+ - Function: first x
This function is a synonym for `(car X)'. Likewise, the functions
`second', `third', ..., through `tenth' return the given element
of the list X.
- - Function: rest X
+ - Function: rest x
This function is a synonym for `(cdr X)'.
- - Function: endp X
+ - Function: endp x
Common Lisp defines this function to act like `null', but
signalling an error if `x' is neither a `nil' nor a cons cell.
This package simply defines `endp' as a synonym for `null'.
- - Function: list-length X
+ - Function: list-length x
This function returns the length of list X, exactly like `(length
X)', except that if X is a circular list (where the cdr-chain
forms a loop rather than terminating with `nil'), this function
returns `nil'. (The regular `length' function would get stuck if
given a circular list.)
- - Function: last X &optional N
+ - Function: last x &optional n
This function returns the last cons, or the Nth-to-last cons, of
the list X. If N is omitted it defaults to 1. The "last cons"
means the first cons cell of the list whose `cdr' is not another
cons cell. (For normal lists, the `cdr' of the last cons will be
`nil'.) This function returns `nil' if X is `nil' or shorter than
- N. Note that the last *element* of the list is `(car (last X))'.
+ N. Note that the last _element_ of the list is `(car (last X))'.
- - Function: butlast X &optional N
+ - Function: butlast x &optional n
This function returns the list X with the last element, or the
last N elements, removed. If N is greater than zero it makes a
copy of the list so as not to damage the original list. In
general, `(append (butlast X N) (last X N))' will return a list
equal to X.
- - Function: nbutlast X &optional N
+ - Function: nbutlast x &optional n
This is a version of `butlast' that works by destructively
modifying the `cdr' of the appropriate element, rather than making
a copy of the list.
- - Function: list* ARG &rest OTHERS
+ - Function: list* arg &rest others
This function constructs a list of its arguments. The final
argument becomes the `cdr' of the last cell constructed. Thus,
`(list* A B C)' is equivalent to `(cons A (cons B C))', and
it is not a name invented for this package like `member*' or
`defun*'.)
- - Function: ldiff LIST SUBLIST
+ - Function: ldiff list sublist
If SUBLIST is a sublist of LIST, i.e., is `eq' to one of the cons
cells of LIST, then this function returns a copy of the part of
LIST up to but not including SUBLIST. For example, `(ldiff x
result is a copy; the original LIST is not modified. If SUBLIST
is not a sublist of LIST, a copy of the entire LIST is returned.
- - Function: copy-list LIST
+ - Function: copy-list list
This function returns a copy of the list LIST. It copies dotted
lists like `(1 2 . 3)' correctly.
- - Function: copy-tree X &optional VECP
+ - Function: copy-tree x &optional vecp
This function returns a copy of the tree of cons cells X. Unlike
`copy-sequence' (and its alias `copy-list'), which copies only
along the `cdr' direction, this function copies (recursively)
VECP argument is true, this function copies vectors (recursively)
as well as cons cells.
- - Function: tree-equal X Y &key :test :test-not :key
+ - Function: tree-equal x y &key :test :test-not :key
This function compares two trees of cons cells. If X and Y are
both cons cells, their `car's and `cdr's are compared recursively.
If neither X nor Y is a cons cell, they are compared by `eql', or
(*Note Sequence Functions::, for the `substitute' function, which works
on just the top-level elements of a list.)
- - Function: subst NEW OLD TREE &key :test :test-not :key
+ - Function: subst new old tree &key :test :test-not :key
This function substitutes occurrences of OLD with NEW in TREE, a
tree of cons cells. It returns a substituted tree, which will be
a copy except that it may share storage with the argument TREE in
test (`eql' by default). The `:key' function is applied to the
elements of the tree but not to OLD.
- - Function: nsubst NEW OLD TREE &key :test :test-not :key
+ - Function: nsubst new old tree &key :test :test-not :key
This function is like `subst', except that it works by destructive
modification (by `setcar' or `setcdr') rather than copying.
The `subst-if', `subst-if-not', `nsubst-if', and `nsubst-if-not'
functions are defined similarly.
- - Function: sublis ALIST TREE &key :test :test-not :key
+ - Function: sublis alist tree &key :test :test-not :key
This function is like `subst', except that it takes an association
list ALIST of OLD-NEW pairs. Each element of the tree (after
applying the `:key' function, if any), is compared with the `car's
of ALIST; if it matches, it is replaced by the corresponding `cdr'.
- - Function: nsublis ALIST TREE &key :test :test-not :key
+ - Function: nsublis alist tree &key :test :test-not :key
This is a destructive version of `sublis'.
\1f
These functions perform operations on lists which represent sets of
elements.
- - Function: member ITEM LIST
+ - Function: member item list
This MacLisp-compatible function searches LIST for an element
which is `equal' to ITEM. The `member' function is built-in to
Emacs 19; this package defines it equivalently in Emacs 18. See
the following function for a Common-Lisp compatible version.
- - Function: member* ITEM LIST &key :test :test-not :key
+ - Function: member* item list &key :test :test-not :key
This function searches LIST for an element matching ITEM. If a
match is found, it returns the cons cell whose `car' was the
matching element. Otherwise, it returns `nil'. Elements are
The `member-if' and `member-if-not' functions analogously search for
elements which satisfy a given predicate.
- - Function: tailp SUBLIST LIST
+ - Function: tailp sublist list
This function returns `t' if SUBLIST is a sublist of LIST, i.e.,
if SUBLIST is `eql' to LIST or to any of its `cdr's.
- - Function: adjoin ITEM LIST &key :test :test-not :key
+ - Function: adjoin item list &key :test :test-not :key
This function conses ITEM onto the front of LIST, like `(cons ITEM
LIST)', but only if ITEM is not already present on the list (as
determined by `member*'). If a `:key' argument is specified, it
search, on the reasoning that ITEM is "about" to become part of
the list.
- - Function: union LIST1 LIST2 &key :test :test-not :key
+ - Function: union list1 list2 &key :test :test-not :key
This function combines two lists which represent sets of items,
returning a list that represents the union of those two sets. The
result list will contain all items which appear in LIST1 or LIST2,
result list. The order of elements in the result list is also
undefined.
- - Function: nunion LIST1 LIST2 &key :test :test-not :key
+ - Function: nunion list1 list2 &key :test :test-not :key
This is a destructive version of `union'; rather than copying, it
tries to reuse the storage of the argument lists if possible.
- - Function: intersection LIST1 LIST2 &key :test :test-not :key
+ - Function: intersection list1 list2 &key :test :test-not :key
This function computes the intersection of the sets represented by
LIST1 and LIST2. It returns the list of items which appear in
both LIST1 and LIST2.
- - Function: nintersection LIST1 LIST2 &key :test :test-not :key
+ - Function: nintersection list1 list2 &key :test :test-not :key
This is a destructive version of `intersection'. It tries to
- reuse storage of LIST1 rather than copying. It does *not* reuse
+ reuse storage of LIST1 rather than copying. It does _not_ reuse
the storage of LIST2.
- - Function: set-difference LIST1 LIST2 &key :test :test-not :key
+ - Function: set-difference list1 list2 &key :test :test-not :key
This function computes the "set difference" of LIST1 and LIST2,
- i.e., the set of elements that appear in LIST1 but *not* in LIST2.
+ i.e., the set of elements that appear in LIST1 but _not_ in LIST2.
- - Function: nset-difference LIST1 LIST2 &key :test :test-not :key
+ - Function: nset-difference list1 list2 &key :test :test-not :key
This is a destructive `set-difference', which will try to reuse
LIST1 if possible.
- - Function: set-exclusive-or LIST1 LIST2 &key :test :test-not :key
+ - Function: set-exclusive-or list1 list2 &key :test :test-not :key
This function computes the "set exclusive or" of LIST1 and LIST2,
i.e., the set of elements that appear in exactly one of LIST1 and
LIST2.
- - Function: nset-exclusive-or LIST1 LIST2 &key :test :test-not :key
+ - Function: nset-exclusive-or list1 list2 &key :test :test-not :key
This is a destructive `set-exclusive-or', which will try to reuse
LIST1 and LIST2 if possible.
- - Function: subsetp LIST1 LIST2 &key :test :test-not :key
+ - Function: subsetp list1 list2 &key :test :test-not :key
This function checks whether LIST1 represents a subset of LIST2,
i.e., whether every element of LIST1 also appears in LIST2.
values to another; any list whose elements are cons cells is an
association list.
- - Function: assoc* ITEM A-LIST &key :test :test-not :key
+ - Function: assoc* item a-list &key :test :test-not :key
This function searches the association list A-LIST for an element
whose `car' matches (in the sense of `:test', `:test-not', and
`:key', or by comparison with `eql') a given ITEM. It returns the
`assoc' ignores `nil's but considers any other non-cons elements
of A-LIST to be an error.)
- - Function: rassoc* ITEM A-LIST &key :test :test-not :key
+ - Function: rassoc* item a-list &key :test :test-not :key
This function searches for an element whose `cdr' matches ITEM.
If A-LIST represents a mapping, this applies the inverse of the
mapping to ITEM.
- - Function: rassoc ITEM A-LIST
+ - Function: rassoc item a-list
This function searches like `rassoc*' with a `:test' argument of
`equal'. It is analogous to Emacs Lisp's standard `assoc'
function, which derives from the MacLisp rather than the Common
Two simple functions for constructing association lists are:
- - Function: acons KEY VALUE ALIST
+ - Function: acons key value alist
This is equivalent to `(cons (cons KEY VALUE) ALIST)'.
- - Function: pairlis KEYS VALUES &optional ALIST
+ - Function: pairlis keys values &optional alist
This is equivalent to `(nconc (mapcar* 'cons KEYS VALUES) ALIST)'.
\1f
-This is Info file ../info/cl.info, produced by Makeinfo version 1.68
-from the input file cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
structures as vectors (or lists upon request) with a special "tag"
symbol to identify them.
- - Special Form: defstruct NAME SLOTS...
+ - Special Form: defstruct name slots...
The `defstruct' form defines a new structure type called NAME,
with the specified SLOTS. (The SLOTS may begin with a string
which documents the structure type.) In the simplest case, NAME
descriptor. It is legal to include arguments which don't
correspond to slot names; these are useful if they are
referred to in the defaults for optional, keyword, or `&aux'
- arguments which *do* correspond to slots.
+ arguments which _do_ correspond to slots.
You can specify any number of full-format `:constructor'
options on a structure. The default constructor is still
assertions. Because assertions might be optimized away, it is a bad
idea for them to include side-effects.
- - Special Form: assert TEST-FORM [SHOW-ARGS STRING ARGS...]
+ - Special Form: assert test-form [show-args string args...]
This form verifies that TEST-FORM is true (i.e., evaluates to a
non-`nil' value). If so, it returns `nil'. If the test is not
satisfied, `assert' signals an error.
Emacs Lisp does not support continuable errors, it makes no sense
to specify PLACES.
- - Special Form: check-type FORM TYPE [STRING]
+ - Special Form: check-type form type [string]
This form verifies that FORM evaluates to a value of type TYPE.
If so, it returns `nil'. If not, `check-type' signals a
`wrong-type-argument' error. The default error message lists the
The following error-related macro is also defined:
- - Special Form: ignore-errors FORMS...
+ - Special Form: ignore-errors forms...
This executes FORMS exactly like a `progn', except that errors are
ignored during the FORMS. More precisely, if an error is
signalled then `ignore-errors' immediately aborts execution of the
in Lisp. Thus, there is no performance penalty for using the more
readable `incf' and `push' forms in your compiled code.
- *Interpreted* code, on the other hand, must expand these macros
+ _Interpreted_ code, on the other hand, must expand these macros
every time they are executed. For this reason it is strongly
recommended that code making heavy use of macros be compiled. (The
features labelled "Special Form" instead of "Function" in this manual
You can find out how a macro expands by using the `cl-prettyexpand'
function.
- - Function: cl-prettyexpand FORM &optional FULL
+ - Function: cl-prettyexpand form &optional full
This function takes a single Lisp form as an argument and inserts
a nicely formatted copy of it in the current buffer (which must be
in Lisp mode so that indentation works properly). It also expands
just leaves it alone. The temporary variable `G1004' was created
by `gensym'.)
- If the optional argument FULL is true, then *all* macros are
+ If the optional argument FULL is true, then _all_ macros are
expanded, including `block', `eval-when', and compiler macros.
Expansion is done as if FORM were a top-level form in a file being
compiled. For example,
arguments, treating the trailing keyword as if it were followed by the
value `nil'.
- Argument lists (as processed by `defun*' and friends) *are* checked
+ Argument lists (as processed by `defun*' and friends) _are_ checked
rigorously except for the minor point just mentioned; in particular,
keyword arguments are checked for validity, and `&allow-other-keys' and
`:allow-other-keys' are fully implemented. Keyword validity checking
compiler which have already had a similar patch applied, nor will it
affect the optimizing Emacs 19 byte-compiler written by Jamie Zawinski
and Hallvard Furuseth. The patch is applied to the byte compiler's
-code in Emacs' memory, *not* to the `bytecomp.elc' file stored on disk.
+code in Emacs' memory, _not_ to the `bytecomp.elc' file stored on disk.
The Emacs 19 compiler (for Emacs 18) is available from various Emacs
Lisp archive sites such as `archive.cis.ohio-state.edu'. Its use is
In order to allow an efficient implementation, keyword arguments use
a slightly cheesy parser which may be confused if a keyword symbol is
-passed as the *value* of another keyword argument. (Specifically,
+passed as the _value_ of another keyword argument. (Specifically,
`(memq :KEYWORD REST-OF-ARGUMENTS)' is used to scan for `:KEYWORD'
among the supplied keyword arguments.)
The `eql' and `equal' predicates do not distinguish between IEEE
floating-point plus and minus zero. The `equalp' predicate has several
-differences with Common Lisp; *note Predicates::..
+differences with Common Lisp; *note Predicates::.
The `setf' mechanism is entirely compatible, except that
setf-methods return a list of five values rather than five values
macros will be compatible with Common Lisp if `values' or `values-list'
is always used to return to a `multiple-value-bind' or other
multiple-value receiver; if `values' is used without
-`multiple-value-...' or vice-versa the effect will be different from
+`multiple-value-...' or vice-versa the effect will be different from
Common Lisp.
Many Common Lisp declarations are ignored, and others match the
differences between Emacs Lisp and Common Lisp make it difficult to
port large Common Lisp applications to Emacs. For one, some of the
features in this package are not fully compliant with ANSI or Steele;
-*note Common Lisp Compatibility::.. But there are also quite a few
+*note Common Lisp Compatibility::. But there are also quite a few
features that this package does not provide at all. Here are some
major omissions that you will want watch out for when bringing Common
Lisp code into Emacs.
-This is Info file ../info/cl.info, produced by Makeinfo version 1.68
-from the input file cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-This is Info file ../../info/internals.info, produced by Makeinfo
-version 1.68 from the input file internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
This section contains some general guidance on how to write
Mule-aware code, as well as some pitfalls you should avoid.
-*Never use `char' and `char *'.*
+_Never use `char' and `char *'._
In XEmacs, the use of `char' and `char *' is almost always a
mistake. If you want to manipulate an Emacs character from "C",
use `Emchar'. If you want to examine a specific octet in the
pointer to move through the internal text, use `Bufbyte *'. Also
note that you almost certainly do not need `Emchar *'.
-*Be careful not to confuse `Charcount', `Bytecount', and `Bufpos'.*
+_Be careful not to confuse `Charcount', `Bytecount', and `Bufpos'._
The whole point of using different types is to avoid confusion
about the use of certain variables. Lest this effect be
nullified, you need to be careful about using the right types.
-*Always convert external data*
+_Always convert external data_
It is extremely important to always convert external data, because
XEmacs can crash if unexpected 8bit sequences are copied to its
internal buffers literally.
The basic rule is that you should assume builds using `--srcdir'
and the `#include <...>' syntax needs to be used when the
to-be-included generated file is in a potentially different
- directory *at compile time*. The non-obvious C rule is that
- `#include "..."' means to search for the included file in the
- same directory as the including file, *not* in the current
- directory.
+ directory _at compile time_. The non-obvious C rule is that
+ `#include "..."' means to search for the included file in the same
+ directory as the including file, _not_ in the current directory.
- * Header files should *not* include `<config.h>' and `"lisp.h"'. It
+ * Header files should _not_ include `<config.h>' and `"lisp.h"'. It
is the responsibility of the `.c' files that use it to do so.
* If the header uses `INLINE', either directly or through
should be made constant, and before all other Emacs files and all
libraries. In particular, the allocation modules `gmalloc.c',
`alloca.c', etc. are normally placed past `lastfile.c', and all of the
-files that implement Xt widget classes *must* be placed after
+files that implement Xt widget classes _must_ be placed after
`lastfile.c' because they contain various structures that must be
statically initialized and into which Xt writes at various times.)
`pre-crt0.c' and `lastfile.c' contain exported symbols that are used to
primitives and other special forms such as `while', `if', `eval',
`let', `and', `or', `progn', etc.; handling of non-local exits,
unwind-protects, and exception handlers; entering the debugger; methods
-for the subr Lisp object type; etc. It does *not* include the `read'
+for the subr Lisp object type; etc. It does _not_ include the `read'
function, the `print' function, or the handling of symbols and obarrays.
`backtrace.h' contains some structures related to stack frames and
`bytecode.c' implements the byte-code interpreter and
compiled-function objects, and `bytecode.h' contains associated
-structures. Note that the byte-code *compiler* is written in Lisp.
+structures. Note that the byte-code _compiler_ is written in Lisp.
\1f
File: internals.info, Node: Modules for Standard Editing Operations, Next: Editor-Level Control Flow Modules, Prev: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules
are permanent objects and stored in various ordered lists); retrieve or
change buffer properties; etc. It also contains the definitions of all
the built-in buffer-local variables (which can be viewed as buffer
-properties). It does *not* contain code to manipulate buffer-local
+properties). It does _not_ contain code to manipulate buffer-local
variables (that's in `symbols.c', described above); or code to
manipulate the text in a buffer.
Note that the choice of whether to use `event-Xt.c' or `event-tty.c'
is made at compile time! Or at the very latest, it is made at startup
-time. `event-Xt.c' handles events for *both* X and TTY frames;
+time. `event-Xt.c' handles events for _both_ X and TTY frames;
`event-tty.c' is only used when X support is not compiled into XEmacs.
The reason for this is that there is only one event loop in XEmacs:
thus, it needs to be able to receive events from all different kinds of
-This is Info file ../../info/internals.info, produced by Makeinfo
-version 1.68 from the input file internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Vectors have their size field munged, so anything that looks at
this field will fail.
- * Note that `XFOOBAR()' macros *will* work correctly on object
+ * Note that `XFOOBAR()' macros _will_ work correctly on object
pointers with their mark bit set, because the logical shift
operations that remove the tag also remove the mark bit.
1. For every `GCPRON', there have to be declarations of `struct gcpro
gcpro1, gcpro2', etc.
- 2. You *must* `UNGCPRO' anything that's `GCPRO'ed, and you *must not*
+ 2. You _must_ `UNGCPRO' anything that's `GCPRO'ed, and you _must not_
`UNGCPRO' if you haven't `GCPRO'ed. Getting either of these wrong
will lead to crashes, often in completely random places unrelated
to where the problem lies.
with `struct gcpro ngcpro1, ngcpro2', etc.), `NNGCPRON', etc.
This avoids compiler warnings about shadowed locals.
- 7. It is *always* better to err on the side of extra `GCPRO's rather
+ 7. It is _always_ better to err on the side of extra `GCPRO's rather
than too few. The extra cycles spent on this are almost never
going to make a whit of difference in the speed of anything.
One exception from this rule is if you ever plan to change the
parameter value, and store a new object in it. In that case, you
- *must* `GCPRO' the parameter, because otherwise the new object
+ _must_ `GCPRO' the parameter, because otherwise the new object
will not be protected.
So, if you create any Lisp objects (remember, this happens in all
sorts of circumstances, e.g. with `Fcons()', etc.), you are
- responsible for `GCPRO'ing them, unless you are *absolutely sure*
+ responsible for `GCPRO'ing them, unless you are _absolutely sure_
that there's no possibility that a garbage-collection can occur
while you need to use the object. Even then, consider `GCPRO'ing.
whenever a QUIT can occur where execution can continue past this.
(Remember, this is almost anywhere.)
- 10. If you have the *least smidgeon of doubt* about whether you need
+ 10. If you have the _least smidgeon of doubt_ about whether you need
to `GCPRO', you should `GCPRO'.
11. Beware of `GCPRO'ing something that is uninitialized. If you have
The first thing that anyone should know about garbage collection is:
when and how the garbage collector is invoked. One might think that this
could happen every time new memory is allocated, e.g. new objects are
-created, but this is *not* the case. Instead, we have the following
+created, but this is _not_ the case. Instead, we have the following
situation:
The entry point of any process of garbage collection is an invocation
of the function `garbage_collect_1' in file `alloc.c'. The invocation
-can occur *explicitly* by calling the function `Fgarbage_collect' (in
+can occur _explicitly_ by calling the function `Fgarbage_collect' (in
addition this function provides information about the freed memory), or
-can occur *implicitly* in four different situations:
+can occur _implicitly_ in four different situations:
1. In function `main_1' in file `emacs.c'. This function is called at
each startup of xemacs. The garbage collection is invoked after all
initial creations are completed, but only if a special internal
-This is Info file ../../info/internals.info, produced by Makeinfo
-version 1.68 from the input file internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
WARNING #1: The finalize method is also called at the end of the
dump phase; this time with the for_disksave parameter set to
- non-zero. The object is *not* about to disappear, so you have to
- make sure to *not* free any extra `malloc()'ed memory if you're
+ non-zero. The object is _not_ about to disappear, so you have to
+ make sure to _not_ free any extra `malloc()'ed memory if you're
going to need it later. (Also, signal an error if there are any
operating-system and window-system resources here, because they
can't be dumped.)
`for_disksave' proviso), we've gotten nastily burned in some cases
by not doing this.
- WARNING #2: The finalize method is *only* called for lcrecords,
- *not* for simply lrecords. If you need a finalize method for
+ WARNING #2: The finalize method is _only_ called for lcrecords,
+ _not_ for simply lrecords. If you need a finalize method for
simple lrecords, you have to stick it in the
`ADDITIONAL_FREE_foo()' macro in `alloc.c'.
- WARNING #3: Things are in an *extremely* bizarre state when
+ WARNING #3: Things are in an _extremely_ bizarre state when
`ADDITIONAL_FREE_foo()' is called, so you have to be incredibly
careful when writing one of these functions. See the comment in
`gc_sweep()'. If you ever have to add one of these, consider
5. A "hash" method. This is used to hash objects when they are to be
compared with `equal'. The rule here is that if two objects are
- `equal', they *must* hash to the same value; i.e. your hash
+ `equal', they _must_ hash to the same value; i.e. your hash
function should use some subset of the sub-fields of the object
that are compared in the "equal" method. If you specify this
method as `NULL', the object's pointer will be used as the hash,
- which will *fail* if the object has an `equal' method, so don't do
+ which will _fail_ if the object has an `equal' method, so don't do
this.
To hash a sub-Lisp-object, call `internal_hash()'. Bump the depth
statistics on memory allocation appropriately. This is used to good
effect by some extremely commonly-used code, to avoid generating extra
objects and thereby triggering GC sooner. However, you have to be
-*extremely* careful when doing this. If you mess this up, you will get
+_extremely_ careful when doing this. If you mess this up, you will get
BADLY BURNED, and it has happened before.
\1f
all are threaded through the variable `all_vectors'. Vectors are
marked strangely during garbage collection, by kludging the size field.
Note that the `struct Lisp_Vector' is declared with its `contents'
-field being a *stretchy* array of one element. It is actually
+field being a _stretchy_ array of one element. It is actually
`malloc()'ed with the right size, however, and access to any element
through the `contents' array works fine.
-This is Info file ../../info/internals.info, produced by Makeinfo
-version 1.68 from the input file internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
system-specific event loop can be operating at a time, and must be able
to receive all kinds of events simultaneously. For the two existing
event loops (implemented in `event-tty.c' and `event-Xt.c',
-respectively), the TTY event loop *only* handles TTY consoles, while
-the Xt event loop handles *both* TTY and X consoles. This situation is
+respectively), the TTY event loop _only_ handles TTY consoles, while
+the Xt event loop handles _both_ TTY and X consoles. This situation is
different from all of the output handlers, where you simply have one
per console type.
for the buffer text will be freed, but it will still be sitting on the
heap, taking up virtual memory, and will not be released back to the
operating system. (However, if you have compiled XEmacs with rel-alloc,
-the situation is different. In this case, the space *will* be released
+the situation is different. In this case, the space _will_ be released
back to the operating system. However, this tends to result in a
noticeable speed penalty.)
Astute readers may notice that the text in a buffer is represented as
-an array of *bytes*, while (at least in the MULE case) an Emchar is a
+an array of _bytes_, while (at least in the MULE case) an Emchar is a
19-bit integer, which clearly cannot fit in a byte. This means (of
course) that the text in a buffer uses a different representation from
an Emchar: specifically, the 19-bit Emchar becomes a series of one to
so, adding the size of the gap to it. By convention, memory
indices begin at 1, just like buffer positions and byte indices,
and when referring to the position that is "at" the gap, we always
- use the memory position at the *beginning*, not at the end, of the
+ use the memory position at the _beginning_, not at the end, of the
gap.
3. Fetch the appropriate bytes at the determined memory position.
-This is Info file ../../info/internals.info, produced by Makeinfo
-version 1.68 from the input file internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
For example, Latin-1 is a 96-character charset, and JISX0208 (the
Japanese national character set) is a 94x94-character charset.
- [Note that, although the ranges above define the *valid* position
+ [Note that, although the ranges above define the _valid_ position
codes for a charset, some of the slots in a particular charset may in
fact be empty. This is the case for JISX0208, for example, where (e.g.)
all the slots whose first position code is in the range 118 - 127 are
- Function: void Lstream_fungetc (Lstream *STREAM, int C)
Function equivalents of the above macros.
- - Function: int Lstream_read (Lstream *STREAM, void *DATA, int SIZE)
+ - Function: ssize_t Lstream_read (Lstream *STREAM, void *DATA, size_t
+ SIZE)
Read SIZE bytes of DATA from the stream. Return the number of
bytes read. 0 means EOF. -1 means an error occurred and no bytes
were read.
- - Function: int Lstream_write (Lstream *STREAM, void *DATA, int SIZE)
+ - Function: ssize_t Lstream_write (Lstream *STREAM, void *DATA, size_t
+ SIZE)
Write SIZE bytes of DATA to the stream. Return the number of
bytes written. -1 means an error occurred and no bytes were
written.
- - Function: void Lstream_unread (Lstream *STREAM, void *DATA, int SIZE)
+ - Function: void Lstream_unread (Lstream *STREAM, void *DATA, size_t
+ SIZE)
Push back SIZE bytes of DATA onto the input queue. The next call
to `Lstream_read()' with the same size will read the same bytes
back. Note that this will be the case even if there is other
Lstream Methods
===============
- - Lstream Method: int reader (Lstream *STREAM, unsigned char *DATA,
- int SIZE)
+ - Lstream Method: ssize_t reader (Lstream *STREAM, unsigned char
+ *DATA, size_t SIZE)
Read some data from the stream's end and store it into DATA, which
can hold SIZE bytes. Return the number of bytes read. A return
value of 0 means no bytes can be read at this time. This may be
This function can be `NULL' if the stream is output-only.
- - Lstream Method: int writer (Lstream *STREAM, CONST unsigned char
- *DATA, int SIZE)
+ - Lstream Method: ssize_t writer (Lstream *STREAM, CONST unsigned char
+ *DATA, size_t SIZE)
Send some data to the stream's end. Data to be sent is in DATA
and is SIZE bytes. Return the number of bytes sent. This
function can send and return fewer bytes than is passed in; in that
If a frame contains multiple windows (panes), they are always created
by splitting an existing window along the horizontal or vertical axis.
Terminology is a bit confusing here: to "split a window horizontally"
-means to create two side-by-side windows, i.e. to make a *vertical* cut
+means to create two side-by-side windows, i.e. to make a _vertical_ cut
in a window. Likewise, to "split a window vertically" means to create
-two windows, one above the other, by making a *horizontal* cut.
+two windows, one above the other, by making a _horizontal_ cut.
If you split a window and then split again along the same axis, you
will end up with a number of panes all arranged along the same axis.
5. All functions that accept windows must be prepared to accept
combination windows, and do something sane (e.g. signal an error
- if so). Combination windows *do* escape to the Lisp level.
+ if so). Combination windows _do_ escape to the Lisp level.
6. All windows have three fields governing their contents: these are
"hchild" (a list of horizontally-arrayed children), "vchild" (a
-This is Info file ../../info/internals.info, produced by Makeinfo
-version 1.68 from the input file internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
A list of extents is maintained as a double gap array: one gap array
is ordered by start index (the "display order") and the other is
ordered by end index (the "e-order"). Note that positions in an extent
-list should logically be conceived of as referring *to* a particular
+list should logically be conceived of as referring _to_ a particular
extent (as is the norm in programs) rather than sitting between two
extents. Note also that callers of these functions should not be aware
of the fact that the extent list is implemented as an array, except for
range; this is equivalent to treating a point P as the range [P,
P].
- * In the case of an *extent* overlapping a point or range, the extent
+ * In the case of an _extent_ overlapping a point or range, the extent
is normally treated as having closed endpoints. This applies
consistently in the discussion of stacks of extents and such below.
Note that this definition of overlap is not necessarily consistent
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
returned. Any time you change the value of the former variable, the
value of the latter is actually changed. This is useful in cases where
you want to rename a variable but still make old code work (*note
-Obsoleteness::.).
+Obsoleteness::).
- - Function: defvaralias VARIABLE ALIAS
+ - Function: defvaralias variable alias
This function defines VARIABLE as an alias for ALIAS.
Thenceforth, any operations performed on VARIABLE will actually be
performed on ALIAS. Both VARIABLE and ALIAS should be symbols.
variable, a variable that has a buffer-local value in any buffer,
or the symbols `nil' or `t'.
- - Function: variable-alias VARIABLE
+ - Function: variable-alias variable
If VARIABLE is aliased to another variable, this function returns
that variable. VARIABLE should be a symbol. If VARIABLE is not
aliased, this function returns `nil'.
- - Function: indirect-variable OBJECT
+ - Function: indirect-variable object
This function returns the variable at the end of OBJECT's
variable-alias chain. If OBJECT is a symbol, follow all variable
aliases and return the final (non-aliased) symbol. If OBJECT is
A "command" is an object that `command-execute' can invoke; it is
a possible definition for a key sequence. Some functions are
commands; a function written in Lisp is a command if it contains an
- interactive declaration (*note Defining Commands::.). Such a
+ interactive declaration (*note Defining Commands::). Such a
function can be called from Lisp expressions like other functions;
in this case, the fact that the function is a command makes no
difference.
A "compiled function" is a function that has been compiled by the
byte compiler. *Note Compiled-Function Type::.
- - Function: subrp OBJECT
+ - Function: subrp object
This function returns `t' if OBJECT is a built-in function (i.e.,
a Lisp primitive).
(subrp (symbol-function 'message))
=> t
- - Function: compiled-function-p OBJECT
+ - Function: compiled-function-p object
This function returns `t' if OBJECT is a compiled function. For
example:
It is not often useful to write a lambda expression as the CAR of a
form in this way. You can get the same result, of making local
variables and giving them values, using the special form `let' (*note
-Local Variables::.). And `let' is clearer and easier to use. In
+Local Variables::). And `let' is clearer and easier to use. In
practice, lambda expressions are either stored as the function
definitions of symbols, to produce named functions, or passed as
-arguments to other functions (*note Anonymous Functions::.).
+arguments to other functions (*note Anonymous Functions::).
However, calls to explicit lambda expressions were very useful in the
old days of Lisp, before the special form `let' was invented. At that
source file, but since these spaces come before the starting
double-quote, they are not part of the string. Some people make a
practice of indenting any additional lines of the string so that the
-text lines up in the program source. *This is a mistake.* The
+text lines up in the program source. _This is a mistake._ The
indentation of the following lines is inside the string; what looks
nice in the source code will look ugly when displayed by the help
commands.
However, a symbol can serve as the name of a function. This happens
when you put the function in the symbol's "function cell" (*note Symbol
-Components::.). Then the symbol itself becomes a valid, callable
+Components::). Then the symbol itself becomes a valid, callable
function, equivalent to the list or subr-object that its function cell
refers to. The contents of the function cell are also called the
symbol's "function definition". The procedure of using a symbol's
distinguish.
Even so, keep in mind that a function need not have a unique name.
-While a given function object *usually* appears in the function cell of
+While a given function object _usually_ appears in the function cell of
only one symbol, this is just a matter of convenience. It is easy to
store it in several symbols using `fset'; then each of the symbols is
equally well a name for the same function.
is called "defining a function", and it is done with the `defun'
special form.
- - Special Form: defun NAME ARGUMENT-LIST BODY-FORMS
+ - Special Form: defun name argument-list body-forms
`defun' is the usual way to define new Lisp functions. It defines
the symbol NAME as a function that looks like this:
`defun' stores this lambda expression in the function cell of
NAME. It returns the value NAME, but usually we ignore this value.
- As described previously (*note Lambda Expressions::.),
+ As described previously (*note Lambda Expressions::),
ARGUMENT-LIST is a list of argument names and may include the
keywords `&optional' and `&rest'. Also, the first two forms in
BODY-FORMS may be a documentation string and an interactive
distinguish deliberate redefinition from unintentional
redefinition.
- - Function: define-function NAME DEFINITION
- - Function: defalias NAME DEFINITION
+ - Function: define-function name definition
+ - Function: defalias name definition
These equivalent special forms define the symbol NAME as a
function, with definition DEFINITION (which can be any valid Lisp
function).
specific function name is being defined--especially where that
name appears explicitly in the source file being loaded. This is
because `define-function' and `defalias' record which file defined
- the function, just like `defun'. (*note Unloading::.).
+ the function, just like `defun'. (*note Unloading::).
By contrast, in programs that manipulate function definitions for
other purposes, it is better to use `fset', which does not keep
run time which function to call. To do that, use the functions
`funcall' and `apply'.
- - Function: funcall FUNCTION &rest ARGUMENTS
+ - Function: funcall function &rest arguments
`funcall' calls FUNCTION with ARGUMENTS, and returns whatever
FUNCTION returns.
that you can use any expression to obtain the function to be
called. It also means that `funcall' does not see the expressions
you write for the ARGUMENTS, only their values. These values are
- *not* evaluated a second time in the act of calling FUNCTION;
+ _not_ evaluated a second time in the act of calling FUNCTION;
`funcall' enters the normal procedure for calling a function at the
place where the arguments have already been evaluated.
Compare these example with the examples of `apply'.
- - Function: apply FUNCTION &rest ARGUMENTS
+ - Function: apply function &rest arguments
`apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
with one difference: the last of ARGUMENTS is a list of arguments
to give to FUNCTION, rather than a single argument. We also say
function as the argument. Here are two different kinds of no-op
function:
- - Function: identity ARG
+ - Function: identity arg
This function returns ARG and has no side effects.
- - Function: ignore &rest ARGS
+ - Function: ignore &rest args
This function ignores any arguments and returns `nil'.
\1f
`mapcar' and `mapconcat', which scan a list, are described here. For
the third mapping function, `mapatoms', see *Note Creating Symbols::.
- - Function: mapcar FUNCTION SEQUENCE
+ - Function: mapcar function sequence
`mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
returns a list of the results.
=> (2 3 4)
(mapcar 'char-to-string "abc")
=> ("a" "b" "c")
-
+
;; Call each function in `my-hooks'.
(mapcar 'funcall my-hooks)
-
+
(defun mapcar* (f &rest args)
"Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
(apply 'mapcar* f
;; Recurse for rest of elements.
(mapcar 'cdr args)))))
-
+
(mapcar* 'cons '(a b c) '(1 2 3 4))
=> ((a . 1) (b . 2) (c . 3))
- - Function: mapconcat FUNCTION SEQUENCE SEPARATOR
+ - Function: mapconcat function sequence separator
`mapconcat' applies FUNCTION to each element of SEQUENCE: the
results, which must be strings, are concatenated. Between each
pair of result strings, `mapconcat' inserts the string SEPARATOR.
'(The cat in the hat)
" ")
=> "The cat in the hat"
-
+
(mapconcat (function (lambda (x) (format "%c" (1+ x))))
"HAL-8000"
"")
=> (lambda (x) (+ 12 x))
This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
-it the value (*not* the function definition!) of `silly'.
+it the value (_not_ the function definition!) of `silly'.
Here is how we might call this function:
(funcall silly 1)
=> 13
-(It does *not* work to write `(silly 1)', because this function is not
-the *function definition* of `silly'. We have not given `silly' any
+(It does _not_ work to write `(silly 1)', because this function is not
+the _function definition_ of `silly'. We have not given `silly' any
function definition, just a value as a variable.)
Most of the time, anonymous functions are constants that appear in
In such cases, we usually use the special form `function' instead of
simple quotation to quote the anonymous function.
- - Special Form: function FUNCTION-OBJECT
+ - Special Form: function function-object
This special form returns FUNCTION-OBJECT without evaluating it.
In this, it is equivalent to `quote'. However, it serves as a
note to the XEmacs Lisp compiler that FUNCTION-OBJECT is intended
See also the function `indirect-function' in *Note Function
Indirection::.
- - Function: symbol-function SYMBOL
+ - Function: symbol-function symbol
This returns the object in the function cell of SYMBOL. If the
symbol's function cell is void, a `void-function' error is
signaled.
`fboundp'. After you have given a symbol a function definition, you
can make it void once more using `fmakunbound'.
- - Function: fboundp SYMBOL
+ - Function: fboundp symbol
This function returns `t' if the symbol has an object in its
function cell, `nil' otherwise. It does not check that the object
is a legitimate function.
- - Function: fmakunbound SYMBOL
+ - Function: fmakunbound symbol
This function makes SYMBOL's function cell void, so that a
subsequent attempt to access this cell will cause a `void-function'
error. (See also `makunbound', in *Note Local Variables::.)
(foo 1)
error--> Symbol's function definition is void: foo
- - Function: fset SYMBOL OBJECT
+ - Function: fset symbol object
This function stores OBJECT in the function cell of SYMBOL. The
result is OBJECT. Normally OBJECT should be a function or the
name of a function, but this is not checked.
(list 'setq var (list '1+ var)))
When this is called with `(inc x)', the argument `var' has the value
-`x'--*not* the *value* of `x'. The body of the macro uses this to
+`x'--_not_ the _value_ of `x'. The body of the macro uses this to
construct the expansion, which is `(setq x (1+ x))'. Once the macro
definition returns this expansion, Lisp proceeds to evaluate it, thus
incrementing `x'.
You can see the expansion of a given macro call by calling
`macroexpand'.
- - Function: macroexpand FORM &optional ENVIRONMENT
+ - Function: macroexpand form &optional environment
This function expands FORM, if it is a macro call. If the result
is another macro call, it is expanded in turn, until something
which is not a macro call results. That is the value returned by
(defmacro inc (var)
(list 'setq var (list '1+ var)))
=> inc
-
+
(macroexpand '(inc r))
=> (setq r (1+ r))
-
+
(defmacro inc2 (var1 var2)
(list 'progn (list 'inc var1) (list 'inc var2)))
=> inc2
-
+
(macroexpand '(inc2 r s))
=> (progn (inc r) (inc s)) ; `inc' not expanded here.
the file. This is in case the file needs the required packages for
proper compilation. One way to ensure that necessary macro definitions
are available during compilation is to require the files that define
-them (*note Named Features::.). To avoid loading the macro definition
-files when someone *runs* the compiled program, write
+them (*note Named Features::). To avoid loading the macro definition
+files when someone _runs_ the compiled program, write
`eval-when-compile' around the `require' calls (*note Eval During
-Compile::.).
+Compile::).
\1f
File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros
Lisp macros have names, and they are usually defined with the special
form `defmacro'.
- - Special Form: defmacro NAME ARGUMENT-LIST BODY-FORMS...
+ - Special Form: defmacro name argument-list body-forms...
`defmacro' defines the symbol NAME as a macro that looks like this:
(macro lambda ARGUMENT-LIST . BODY-FORMS)
The shape and meaning of ARGUMENT-LIST is the same as in a
function, and the keywords `&rest' and `&optional' may be used
- (*note Argument List::.). Macros may have a documentation string,
+ (*note Argument List::). Macros may have a documentation string,
but any `interactive' declaration is ignored since macros cannot be
called interactively.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Backquote allows you to quote a list, but selectively evaluate
elements of that list. In the simplest case, it is identical to the
-special form `quote' (*note Quoting::.). For example, these two forms
+special form `quote' (*note Quoting::). For example, these two forms
yield identical results:
`(a list of (+ 2 3) elements)
(cons 'while (cons (list '<= var final)
(append body (list (list 'inc var)))))))
=> for
+
(for i from 1 to 3 do
(setq square (* i i))
(princ (format "\n%d %d" i square)))
==>
-
(let ((i 1))
(while (<= i 3)
(setq square (* i i))
(princ (format "%d %d" i square))
(inc i)))
-
-
- -|1 1
+
+ -|1 1
-|2 4
-|3 9
=> nil
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
-
- `(let ((,var ,init)
+ `(let ((,var ,init)
(max ,final))
(while (<= ,var max)
,@body
binding made by `for'.
The way to correct this is to use an uninterned symbol instead of
-`max' (*note Creating Symbols::.). The uninterned symbol can be bound
+`max' (*note Creating Symbols::). The uninterned symbol can be bound
and referred to just like any other symbol, but since it is created by
`for', we know that it cannot already appear in the user's program.
Since it is not interned, there is no way the user can put it into the
Another problem can happen if you evaluate any of the macro argument
expressions during the computation of the expansion, such as by calling
-`eval' (*note Eval::.). If the argument is supposed to refer to the
+`eval' (*note Eval::). If the argument is supposed to refer to the
user's variables, you may have trouble if the user happens to use a
variable with the same name as one of the macro arguments. Inside the
macro body, the macro argument binding is the most local binding of this
(defmacro empty-object ()
(list 'quote (cons nil nil)))
-
+
(defun initialize (condition)
(let ((object (empty-object)))
(if condition
The way to declare new customization groups is with `defgroup'.
- - Macro: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]...
+ - Macro: defgroup group members doc [keyword value]...
Declare GROUP as a customization group containing MEMBERS. Do not
quote the symbol GROUP. The argument DOC specifies the
documentation string for the group.
are `custom-variable' for a variable, `custom-face' for a face,
and `custom-group' for a group.
- In addition to the common keywords (*note Common Keywords::.), you
+ In addition to the common keywords (*note Common Keywords::), you
can use this keyword in `defgroup':
`:prefix PREFIX'
Use `defcustom' to declare user-editable variables.
- - Macro: defcustom OPTION DEFAULT DOC [KEYWORD VALUE]...
+ - Macro: defcustom option default doc [keyword value]...
Declare OPTION as a customizable user option variable. Do not
quote OPTION. The argument DOC specifies the documentation string
for the variable.
symbol, one of the customization type names defined in the following
sections. After this symbol come a number of arguments, depending on
the symbol. Between the type symbol and its arguments, you can
-optionally write keyword-value pairs (*note Type Keywords::.).
+optionally write keyword-value pairs (*note Type Keywords::).
Some of the type symbols do not use any arguments; those are called
"simple types". For a simple type, if you do not use any keyword-value
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
-* 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.
XEmacs Lisp has several interfaces for loading. For example,
`autoload' creates a placeholder object for a function in a file;
trying to call the autoloading function loads the file to get the
-function's real definition (*note Autoload::.). `require' loads a file
-if it isn't already loaded (*note Named Features::.). Ultimately, all
+function's real definition (*note Autoload::). `require' loads a file
+if it isn't already loaded (*note Named Features::). Ultimately, all
these facilities call the `load' function to do the work.
- - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
+ - Function: load filename &optional missing-ok nomessage nosuffix
This function finds and opens a file of Lisp code, evaluates all
the forms in it, and closes the file.
should bind `load-path' locally with `let' around the calls to
`load'.
- - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE
+ - Function: locate-file filename path-list &optional suffixes mode
This function searches for a file in the same way that `load' does,
and returns the file found (if any). (In fact, `load' uses this
function to search through `load-path'.) It searches for FILENAME
you will have to call `locate-file-clear-hashing' to get it back
on track. See that function for details.
- - Function: locate-file-clear-hashing PATH
+ - Function: locate-file-clear-hashing path
This function clears the hash records for the specified list of
directories. `locate-file' uses a hashing scheme to speed lookup,
and will correctly track the following environmental changes:
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
most convenient way to make a function autoload, but only for packages
installed along with Emacs.
- - Function: autoload FUNCTION FILENAME &optional DOCSTRING INTERACTIVE
- TYPE
+ - Function: autoload function filename &optional docstring interactive
+ type
This function defines the function (or macro) named FUNCTION so as
to load automatically from FILENAME. The string FILENAME
specifies the file to load to get the real definition of FUNCTION.
In this case, `"prolog"' is the name of the file to load, 169681
refers to the documentation string in the `DOC' file (*note
- Documentation Basics::.), `t' means the function is interactive,
+ Documentation Basics::), `t' means the function is interactive,
and `nil' that it is not a macro or a keymap.
The autoloaded file usually contains other definitions and may
The same magic comment can copy any kind of form into `loaddefs.el'.
If the form following the magic comment is not a function definition,
it is copied verbatim. You can also use a magic comment to execute a
-form at build time *without* executing it when the file itself is
+form at build time _without_ executing it when the file itself is
loaded. To do this, write the form "on the same line" as the magic
comment. Since it is in a comment, it does nothing when you load the
source file; but `update-file-autoloads' copies it to `loaddefs.el',
(cons '(leif-mode " Leif") minor-mode-alist)))
To add an element to a list just once, use `add-to-list' (*note
-Setting Variables::.).
+Setting Variables::).
Occasionally you will want to test explicitly whether a library has
already been loaded. Here's one way to test, in a library, whether it
'comint)' will henceforth know that nothing needs to be done.
When `require' is used at top level in a file, it takes effect when
-you byte-compile that file (*note Byte Compilation::.) as well as when
+you byte-compile that file (*note Byte Compilation::) as well as when
you load it. This is in case the required package contains macros that
the byte compiler must know about.
`provide' call, so the subsequent `require' call does nothing while
loading.
- - Function: provide FEATURE
+ - Function: provide feature
This function announces that FEATURE is now loaded, or being
loaded, into the current XEmacs session. This means that the
facilities associated with FEATURE are or will be available for
or `provide' calls that occurred during the load are undone.
*Note Autoload::.
- - Function: require FEATURE &optional FILENAME
+ - Function: require feature &optional filename
This function checks whether FEATURE is present in the current
XEmacs session (using `(featurep FEATURE)'; see below). If it is
not, then `require' loads FILENAME with `load'. If FILENAME is
If loading the file fails to provide FEATURE, `require' signals an
error, `Required feature FEATURE was not provided'.
- - Function: featurep FEXP
+ - Function: featurep fexp
This function returns `t' if feature FEXP is present in this
Emacs. Use this to conditionalize execution of lisp code based on
the presence or absence of emacs or environment extensions.
reclaim memory for other Lisp objects. To do this, use the function
`unload-feature':
- - Command: unload-feature FEATURE &optional FORCE
+ - Command: unload-feature feature &optional force
This command unloads the library that provided feature FEATURE.
It undefines all functions, macros, and variables defined in that
library with `defconst', `defvar', `defun', `defmacro',
load the file. But it does execute any `require' calls at top level in
the file. One way to ensure that necessary macro definitions are
available during compilation is to `require' the file that defines them
-(*note Named Features::.). To avoid loading the macro definition files
-when someone *runs* the compiled program, write `eval-when-compile'
-around the `require' calls (*note Eval During Compile::.).
+(*note Named Features::). To avoid loading the macro definition files
+when someone _runs_ the compiled program, write `eval-when-compile'
+around the `require' calls (*note Eval During Compile::).
- - Function: byte-compile SYMBOL
+ - Function: byte-compile symbol
This function byte-compiles the function definition of SYMBOL,
replacing the previous definition with the compiled one. The
function definition of SYMBOL must be the actual code for the
except for certain primitives that are coded as special
instructions.
- - Command: compile-defun &optional ARG
+ - Command: compile-defun &optional arg
This command reads the defun containing point, compiles it, and
evaluates the result. If you use this on a defun that is actually
a function definition, the effect is to install a compiled version
If ARG is non-`nil', the result is inserted in the current buffer
after the form; otherwise, it is printed in the minibuffer.
- - Command: byte-compile-file FILENAME &optional LOAD
+ - Command: byte-compile-file filename &optional load
This function compiles a file of Lisp code named FILENAME into a
file of byte-code. The output file's name is made by appending
`c' to the end of FILENAME.
-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
-rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
- - Command: byte-recompile-directory DIRECTORY &optional FLAG
+ - Command: byte-recompile-directory directory &optional flag
This function recompiles every `.el' file in DIRECTORY that needs
recompilation. A file needs recompilation if a `.elc' file exists
but is older than the `.el' file.
normally `nil', but is bound to `t' by
`batch-byte-recompile-directory'.
- - Function: byte-code INSTRUCTIONS CONSTANTS STACK-SIZE
+ - Function: byte-code instructions constants stack-size
This function actually interprets byte-code. Don't call this
function yourself. Only the byte compiler knows how to generate
valid calls to this function.
If this is non-`nil', the byte compiler generates compiled files
that are set up for dynamic function loading.
- - Function: fetch-bytecode FUNCTION
+ - Function: fetch-bytecode function
This immediately finishes loading the definition of FUNCTION from
its byte-compiled file, if it is not fully loaded already. The
argument FUNCTION may be a compiled-function object or a function
These features permit you to write code to be evaluated during
compilation of a program.
- - Special Form: eval-and-compile BODY
+ - Special Form: eval-and-compile body
This form marks BODY to be evaluated both when you compile the
containing code and when you run it (whether compiled or not).
preferable if there is a substantial amount of code to be executed
in this way.
- - Special Form: eval-when-compile BODY
+ - Special Form: eval-when-compile body
This form marks BODY to be evaluated at compile time and not when
the compiled program is loaded. The result of evaluation by the
compiler becomes a constant which appears in the compiled program.
The documentation string (if any); otherwise, `nil'. The value may
be a number or a list, in case the documentation string is stored
in a file. Use the function `documentation' to get the real
- documentation string (*note Accessing Documentation::.).
+ documentation string (*note Accessing Documentation::).
INTERACTIVE
The interactive spec (if any). This can be a string or a Lisp
The primitive way to create a compiled-function object is with
`make-byte-code':
- - Function: make-byte-code ARGLIST INSTRUCTIONS CONSTANTS STACK-SIZE
- &optional DOC-STRING INTERACTIVE
+ - Function: make-byte-code arglist instructions constants stack-size
+ &optional doc-string interactive
This function constructs and returns a compiled-function object
with the specified attributes.
- *Please note:* Unlike all other Emacs-lisp functions, calling this
- with five arguments is *not* the same as calling it with six
+ _Please note:_ Unlike all other Emacs-lisp functions, calling this
+ with five arguments is _not_ the same as calling it with six
arguments, the last of which is `nil'. If the INTERACTIVE arg is
specified as `nil', then that means that this function was defined
with `(interactive)'. If the arg is not specified, then that means
The following primitives are provided for accessing the elements of
a compiled-function object.
- - Function: compiled-function-arglist FUNCTION
+ - Function: compiled-function-arglist function
This function returns the argument list of compiled-function object
FUNCTION.
- - Function: compiled-function-instructions FUNCTION
+ - Function: compiled-function-instructions function
This function returns a string describing the byte-code
instructions of compiled-function object FUNCTION.
- - Function: compiled-function-constants FUNCTION
+ - Function: compiled-function-constants function
This function returns the vector of Lisp objects referenced by
compiled-function object FUNCTION.
- - Function: compiled-function-stack-size FUNCTION
+ - Function: compiled-function-stack-size function
This function returns the maximum stack size needed by
compiled-function object FUNCTION.
- - Function: compiled-function-doc-string FUNCTION
+ - Function: compiled-function-doc-string function
This function returns the doc string of compiled-function object
FUNCTION, if available.
- - Function: compiled-function-interactive FUNCTION
+ - Function: compiled-function-interactive function
This function returns the interactive spec of compiled-function
object FUNCTION, if any. The return value is `nil' or a
two-element list, the first element of which is the symbol
`interactive' and the second element is the interactive spec (a
string or Lisp form).
- - Function: compiled-function-domain FUNCTION
+ - Function: compiled-function-domain function
This function returns the domain of compiled-function object
FUNCTION, if any. The result will be a string or `nil'. *Note
Domain Specification::.
ordinary Lisp variables, by transferring values between variables and
the stack.
- - Command: disassemble OBJECT &optional STREAM
+ - Command: disassemble object &optional stream
This function prints the disassembled code for OBJECT. If STREAM
is supplied, then output goes there. Otherwise, the disassembled
code is printed to the stream `standard-output'. The argument
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
called shortly before the problem, step quickly over the call to that
function, and then step through its caller.
- - Command: debug-on-entry FUNCTION-NAME
+ - Command: debug-on-entry function-name
This function requests FUNCTION-NAME to invoke the debugger each
time it is called. It works by inserting the form `(debug
'debug)' into the function definition as the first form.
(debug (quote debug))
(if (zerop n) 1 (* n (fact (1- n)))))
- - Command: cancel-debug-on-entry FUNCTION-NAME
+ - Command: cancel-debug-on-entry function-name
This function undoes the effect of `debug-on-entry' on
FUNCTION-NAME. When called interactively, it prompts for
FUNCTION-NAME in the minibuffer. If FUNCTION-NAME is `nil' or the
additional form can be evaluated and its value ignored. (If the value
of `(debug)' isn't ignored, it will alter the execution of the
program!) The most common suitable places are inside a `progn' or an
-implicit `progn' (*note Sequencing::.).
+implicit `progn' (*note Sequencing::).
\1f
File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger
windows to examine the buffer that was being edited at the time of the
error, switch buffers, visit files, or do any other sort of editing.
However, the debugger is a recursive editing level (*note Recursive
-Editing::.) and it is wise to go back to the backtrace buffer and exit
+Editing::) and it is wise to go back to the backtrace buffer and exit
the debugger (with the `q' command) when you are finished with it.
Exiting the debugger gets out of the recursive edit and kills the
backtrace buffer.
Here we describe fully the function used to invoke the debugger.
- - Function: debug &rest DEBUGGER-ARGS
+ - Function: debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer
named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
recursive entry to the debugger, etc.), and fills it with
was called. The convention for arguments is detailed in the
description of `debug'.
- - Command: backtrace &optional STREAM DETAILED
+ - Command: backtrace &optional stream detailed
This function prints a trace of Lisp function calls currently
active. This is the function used by `debug' to fill up the
`*Backtrace*' buffer. It is written in C, since it must have
(list 'testing (backtrace))))))))
=> nil
-
+
----------- Buffer: backtrace-output ------------
backtrace()
(list ...computing arguments...)
The `d' command in the debugger works by setting this variable.
- - Function: backtrace-debug LEVEL FLAG
+ - Function: backtrace-debug level flag
This function sets the debug-on-exit flag of the stack frame LEVEL
levels down the stack, giving it the value FLAG. If FLAG is
non-`nil', this will cause the debugger to be entered when that
another global variable is that the data will never carry over to a
subsequent command invocation.
- - Function: backtrace-frame FRAME-NUMBER
+ - Function: backtrace-frame frame-number
The function `backtrace-frame' is intended for use in Lisp
debuggers. It returns information about what computation is
happening in the stack frame FRAME-NUMBER levels down.
compiled, and point shows how far the byte compiler was able to read.
If the error was due to invalid Lisp syntax, point shows exactly
-where the invalid syntax was *detected*. The cause of the error is not
+where the invalid syntax was _detected_. The cause of the error is not
necessarily near by! Use the techniques in the previous section to find
the error.
* Provide rudimentary coverage testing and display of frequency
counts.
+
The first three sections should tell you enough about Edebug to
enable you to use it.
it instruments the definition before evaluating it. (The source code
itself is not modified.) If the variable `edebug-all-defs' is
non-`nil', that inverts the meaning of the prefix argument: then
-`C-M-x' instruments the definition *unless* it has a prefix argument.
+`C-M-x' instruments the definition _unless_ it has a prefix argument.
The default value of `edebug-all-defs' is `nil'. The command `M-x
edebug-all-defs' toggles the value of the variable `edebug-all-defs'.
If `edebug-all-defs' is non-`nil', then the commands `eval-region',
`eval-current-buffer', and `eval-buffer' also instrument any
definitions they evaluate. Similarly, `edebug-all-forms' controls
-whether `eval-region' should instrument *any* form, even non-defining
+whether `eval-region' should instrument _any_ form, even non-defining
forms. This doesn't apply to loading or evaluations in the minibuffer.
The command `M-x edebug-all-forms' toggles this option.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-------
In addition to automatic stepping through source code, which is also
-called *tracing* (see *Note Edebug Execution Modes::), Edebug can
+called _tracing_ (see *Note Edebug Execution Modes::), Edebug can
produce a traditional trace listing of execution in a separate buffer,
`*edebug-trace*'.
section explains precisely how it fails. Edebug operation unavoidably
alters some data in XEmacs, and this can interfere with debugging
certain programs. Also notice that Edebug's protection against change
-of outside data means that any side effects *intended* by the user in
+of outside data means that any side effects _intended_ by the user in
the course of debugging will be defeated.
* Menu:
Edebug is active, `executing-macro' is bound to
`edebug-continue-kbd-macro'.
+
\1f
File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context
* The Edebug Display Update, is saved and restored if
`edebug-save-windows' is non-`nil'. It is not restored on error
- or quit, but the outside selected window *is* reselected even on
+ or quit, but the outside selected window _is_ reselected even on
error or quit in case a `save-excursion' is active. If the value
of `edebug-save-windows' is a list, only the listed windows are
saved and restored.
* `cursor-in-echo-area' is locally bound to `nil' so that the cursor
shows up in the window.
+
\1f
File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context
While Edebug is active, `defining-kbd-macro' is bound to
`edebug-continue-kbd-macro'.
+
\1f
File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug
explain the format of macro call arguments by using `def-edebug-spec' to
define an "Edebug specification" for each macro.
- - Macro: def-edebug-spec MACRO SPECIFICATION
+ - Macro: def-edebug-spec macro specification
Specify which expressions of a call to macro MACRO are forms to be
evaluated. For simple macros, the SPECIFICATION often looks very
similar to the formal argument list of the macro definition, but
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
An `end-of-file' error is signaled if reading encounters an
unterminated list, vector, or string.
- - Function: read &optional STREAM
+ - Function: read &optional stream
This function reads one textual Lisp expression from STREAM,
returning it as a Lisp object. This is the basic Lisp input
function.
- - Function: read-from-string STRING &optional START END
+ - Function: read-from-string string &optional start end
This function reads the first textual Lisp expression from the
text in STRING. It returns a cons cell whose CAR is that
expression, and whose CDR is an integer giving the position of the
Finally, we show the use of a function as an output stream. The
function `eat-output' takes each character that it is given and conses
-it onto the front of the list `last-output' (*note Building Lists::.).
+it onto the front of the list `last-output' (*note Building Lists::).
At the end, the list contains all the characters output, but in reverse
order.
the previous section for a description of output streams.) If STREAM
is `nil' or omitted, it defaults to the value of `standard-output'.
- - Function: print OBJECT &optional STREAM
+ - Function: print object &optional stream
The `print' function is a convenient way of printing. It outputs
the printed representation of OBJECT to STREAM, printing in
addition one newline before OBJECT and another after it. Quoting
-|
=> " came back"
- - Function: prin1 OBJECT &optional STREAM
+ - Function: prin1 object &optional stream
This function outputs the printed representation of OBJECT to
STREAM. It does not print newlines to separate output as `print'
does, but it does use quoting characters just like `print'. It
-| The\ cat\ in"the hat"" came back"
=> " came back"
- - Function: princ OBJECT &optional STREAM
+ - Function: princ object &optional stream
This function outputs the printed representation of OBJECT to
STREAM. It returns OBJECT.
-| The cat in the "hat"
=> " in the \"hat\""
- - Function: terpri &optional STREAM
+ - Function: terpri &optional stream
This function outputs a newline to STREAM. The name stands for
"terminate print".
- - Function: write-char CHARACTER &optional STREAM
+ - Function: write-char character &optional stream
This function outputs CHARACTER to STREAM. It returns CHARACTER.
- - Function: prin1-to-string OBJECT &optional NOESCAPE
+ - Function: prin1-to-string object &optional noescape
This function returns a string containing the text that `prin1'
would have printed for the same argument.
objects will be written in `#[...]' form instead of in
`#<compiled-function [...]>' form, and two-element lists of the
form `(quote object)' will be written as the equivalent `'object'.
- Do not *set* this variable; bind it instead.
+ Do not _set_ this variable; bind it instead.
- Variable: print-length
The value of this variable is the maximum number of elements of a
===========================
In most ways, a minibuffer is a normal XEmacs buffer. Most
-operations *within* a buffer, such as editing commands, work normally
+operations _within_ a buffer, such as editing commands, work normally
in a minibuffer. However, many operations for managing buffers do not
apply to minibuffers. The name of a minibuffer always has the form
` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
`enable-recursive-minibuffers'.
Like other buffers, a minibuffer may use any of several local keymaps
-(*note Keymaps::.); these contain various exit commands and in some
-cases completion commands (*note Completion::.).
+(*note Keymaps::); these contain various exit commands and in some cases
+completion commands (*note Completion::).
* `minibuffer-local-map' is for ordinary input (no completion).
reading the arguments for a command, in the `interactive' spec. *Note
Defining Commands::.
- - Function: read-from-minibuffer PROMPT-STRING &optional
- INITIAL-CONTENTS KEYMAP READ HIST
+ - Function: read-from-minibuffer prompt-string &optional
+ initial-contents keymap read hist
This function is the most general way to get input through the
minibuffer. By default, it accepts arbitrary text and returns it
as a string; however, if READ is non-`nil', then it uses `read' to
- convert the text into a Lisp object (*note Input Functions::.).
+ convert the text into a Lisp object (*note Input Functions::).
The first thing this function does is to activate a minibuffer and
display it with PROMPT-STRING as the prompt. This value must be a
reads the text and returns the resulting Lisp object, unevaluated.
(*Note Input Functions::, for information about reading.)
- - Function: read-string PROMPT &optional INITIAL
+ - Function: read-string prompt &optional initial
This function reads a string from the minibuffer and returns it.
The arguments PROMPT and INITIAL are used as in
`read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
`M-s'
`previous-matching-history-element'
- - Function: read-no-blanks-input PROMPT &optional INITIAL
+ - Function: read-no-blanks-input prompt &optional initial
This function reads a string from the minibuffer, but does not
allow whitespace characters as part of the input: instead, those
characters terminate the input. The arguments PROMPT and INITIAL
This is a simplified interface to the `read-from-minibuffer'
function, and passes the value of the `minibuffer-local-ns-map'
keymap as the KEYMAP argument for that function. Since the keymap
- `minibuffer-local-ns-map' does not rebind `C-q', it *is* possible
+ `minibuffer-local-ns-map' does not rebind `C-q', it _is_ possible
to put a space into the string, by quoting it.
(read-no-blanks-input PROMPT INITIAL)
This section describes functions for reading Lisp objects with the
minibuffer.
- - Function: read-minibuffer PROMPT &optional INITIAL
+ - Function: read-minibuffer prompt &optional initial
This function reads a Lisp object in the minibuffer and returns it,
without evaluating it. The arguments PROMPT and INITIAL are used
as in `read-from-minibuffer'.
"Enter an expression: " (format "%s" '(testing)))
;; Here is how the minibuffer is displayed:
-
+
---------- Buffer: Minibuffer ----------
Enter an expression: (testing)-!-
---------- Buffer: Minibuffer ----------
The user can type <RET> immediately to use the initial input as a
default, or can edit the input.
- - Function: eval-minibuffer PROMPT &optional INITIAL
+ - Function: eval-minibuffer prompt &optional initial
This function reads a Lisp expression in the minibuffer, evaluates
it, then returns the result. The arguments PROMPT and INITIAL are
used as in `read-from-minibuffer'.
==
(eval (read-minibuffer PROMPT INITIAL))
- - Function: edit-and-eval-command PROMPT FORM
+ - Function: edit-and-eval-command prompt form
This function reads a Lisp expression in the minibuffer, and then
evaluates it. The difference between this command and
`eval-minibuffer' is that here the initial FORM is not optional
;; After evaluation of the preceding expression,
;; the following appears in the minibuffer:
-
+
---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)-!-
---------- Buffer: Minibuffer ----------
chapter so as to keep them near the higher-level completion features
that do use the minibuffer.
- - Function: try-completion STRING COLLECTION &optional PREDICATE
+ - Function: try-completion string collection &optional predicate
This function returns the longest common substring of all possible
completions of STRING in COLLECTION. The value of COLLECTION must
be an alist, an obarray, or a function that implements a virtual
longest initial sequence common to all the permissible completions
that match.
- If COLLECTION is an alist (*note Association Lists::.), the CARs
- of the alist elements form the set of permissible completions.
+ If COLLECTION is an alist (*note Association Lists::), the CARs of
+ the alist elements form the set of permissible completions.
- If COLLECTION is an obarray (*note Creating Symbols::.), the names
+ If COLLECTION is an obarray (*note Creating Symbols::), the names
of all symbols in the obarray form the set of permissible
completions. The global variable `obarray' holds an obarray
containing the names of all interned Lisp symbols.
of one argument. It is used to test each possible match, and the
match is accepted only if PREDICATE returns non-`nil'. The
argument given to PREDICATE is either a cons cell from the alist
- (the CAR of which is a string) or else it is a symbol (*not* a
+ (the CAR of which is a string) or else it is a symbol (_not_ a
symbol name) from the obarray.
You can also use a symbol that is a function as COLLECTION. Then
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
=> "fooba"
-
+
(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
=> t
(defun test (s)
(> (length (car s)) 6))
=> test
-
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
=> "foobar"
- - Function: all-completions STRING COLLECTION &optional PREDICATE
- NOSPACE
+ - Function: all-completions string collection &optional predicate
+ nospace
This function returns a list of all possible completions of
STRING. The parameters to this function are the same as to
`try-completion'.
(defun test (s)
(> (length (car s)) 6))
=> test
-
+
(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
This section describes the basic interface for reading from the
minibuffer with completion.
- - Function: completing-read PROMPT COLLECTION &optional PREDICATE
- REQUIRE-MATCH INITIAL HIST
+ - Function: completing-read prompt collection &optional predicate
+ require-match initial hist
This function reads a string in the minibuffer, assisting the user
by providing completion. It activates the minibuffer with prompt
PROMPT, which must be a string. If INITIAL is non-`nil',
"Complete a foo: "
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
nil t "fo")
-
+
;; After evaluation of the preceding expression,
;; the following appears in the minibuffer:
`minibuffer-complete'
with other characters bound as in `minibuffer-local-map' (*note
- Text from Minibuffer::.).
+ Text from Minibuffer::).
- Variable: minibuffer-local-must-match-map
`completing-read' uses this value as the local keymap when an
This function completes the minibuffer contents, and exits if
confirmation is not required, i.e., if
`minibuffer-completion-confirm' is non-`nil'. If confirmation
- *is* required, it is given by repeating this command
+ _is_ required, it is given by repeating this command
immediately--the command is programmed to work without confirmation
when run twice in succession.
list of completions is displayed as text in a buffer named
`*Completions*'.
- - Function: display-completion-list COMPLETIONS
+ - Function: display-completion-list completions
This function displays COMPLETIONS to the stream in
`standard-output', usually a buffer. (*Note Read and Print::, for
more information about streams.) The argument COMPLETIONS is
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
reading the arguments for a command, in the `interactive' spec. *Note
Defining Commands::.
- - Function: read-buffer PROMPT &optional DEFAULT EXISTING
+ - Function: read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a
string. The argument DEFAULT is the default name to use, the
value to return if the user exits with an empty minibuffer. If
;; The user types `minibuffer.t <RET>'.
=> "minibuffer.texi"
- - Function: read-command PROMPT
+ - Function: read-command prompt
This function reads the name of a command and returns it as a Lisp
symbol. The argument PROMPT is used as in `read-from-minibuffer'.
Recall that a command is anything for which `commandp' returns
(intern (completing-read PROMPT obarray
'commandp t nil))
- - Function: read-variable PROMPT
+ - Function: read-variable prompt
This function reads the name of a user variable and returns it as a
symbol.
a file name. It provides special features including automatic insertion
of the default directory.
- - Function: read-file-name PROMPT &optional DIRECTORY DEFAULT EXISTING
- INITIAL
+ - Function: read-file-name prompt &optional directory default existing
+ initial
This function reads a file name in the minibuffer, prompting with
PROMPT and providing completion. If DEFAULT is non-`nil', then
the function returns DEFAULT if the user just types <RET>.
Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
does not; but it seems best to describe them together.
- - Function: y-or-n-p PROMPT
+ - Function: y-or-n-p prompt
This function asks the user a question, expecting input in the echo
area. It returns `t' if the user types `y', `nil' if the user
types `n'. This function also accepts <SPC> to mean yes and <DEL>
This function does not actually use the minibuffer, since it does
not allow editing of the answer. It actually uses the echo area
- (*note The Echo Area::.), which uses the same screen space as the
+ (*note The Echo Area::), which uses the same screen space as the
minibuffer. The cursor moves to the echo area while the question
is being asked.
;; After evaluation of the preceding expression,
;; the following prompt appears in the echo area:
-
+
---------- Echo area ----------
Do you need a lift? (y or n)
---------- Echo area ----------
;; If the user then types `q', the following appears:
+
---------- Echo area ----------
Please answer y or n. Do you need a lift? (y or n)
---------- Echo area ----------
;; When the user types a valid answer,
;; it is displayed after the question:
+
---------- Echo area ----------
Do you need a lift? (y or n) y
---------- Echo area ----------
We show successive lines of echo area messages, but only one
actually appears on the screen at a time.
- - Function: yes-or-no-p PROMPT
+ - Function: yes-or-no-p prompt
This function asks the user a question, expecting input in the
minibuffer. It returns `t' if the user enters `yes', `nil' if the
user types `no'. The user must type <RET> to finalize the
;; After evaluation of the preceding expression,
;; the following prompt appears,
;; with an empty minibuffer:
-
+
---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
- - Function: yes-or-no-p-dialog-box PROMPT
+ - Function: yes-or-no-p-dialog-box prompt
This function asks the user a "y or n" question with a popup dialog
box. It returns `t' if the answer is "yes". PROMPT is the string
to display to ask the question.
are replaced with the following functions, so that menu items bring up
dialog boxes instead of minibuffer questions.
- - Function: y-or-n-p-maybe-dialog-box PROMPT
+ - Function: y-or-n-p-maybe-dialog-box prompt
This function asks user a "y or n" question, using either a dialog
box or the minibuffer, as appropriate.
- - Function: yes-or-no-p-maybe-dialog-box PROMPT
+ - Function: yes-or-no-p-maybe-dialog-box prompt
This function asks user a "yes or no" question, using either a
dialog box or the minibuffer, as appropriate.
each question individually. This gives the user certain convenient
facilities such as the ability to answer the whole series at once.
- - Function: map-y-or-n-p PROMPTER ACTOR LIST &optional HELP
- ACTION-ALIST
+ - Function: map-y-or-n-p prompter actor list &optional help
+ action-alist
This function, new in Emacs 19, asks the user a series of
questions, reading a single-character answer in the echo area for
each one.
If `map-y-or-n-p' is called in a command that was invoked using the
mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
- Info::.) is either `nil' or a list--then it uses a dialog box or
+ Info::) is either `nil' or a list--then it uses a dialog box or
pop-up menu to ask the question. In this case, it does not use
keyboard input or the echo area. You can force use of the mouse
or use of keyboard input by binding `last-nonmenu-event' to a
- Command: self-insert-and-exit
This command exits the active minibuffer after inserting the last
character typed on the keyboard (found in `last-command-char';
- *note Command Loop Info::.).
+ *note Command Loop Info::).
- - Command: previous-history-element N
+ - Command: previous-history-element n
This command replaces the minibuffer contents with the value of the
Nth previous (older) history element.
- - Command: next-history-element N
+ - Command: next-history-element n
This command replaces the minibuffer contents with the value of the
Nth more recent history element.
- - Command: previous-matching-history-element PATTERN
+ - Command: previous-matching-history-element pattern
This command replaces the minibuffer contents with the value of the
previous (older) history element that matches PATTERN (a regular
expression).
- - Command: next-matching-history-element PATTERN
+ - Command: next-matching-history-element pattern
This command replaces the minibuffer contents with the value of
the next (newer) history element that matches PATTERN (a regular
expression).
- Variable: minibuffer-help-form
The current value of this variable is used to rebind `help-form'
- locally inside the minibuffer (*note Help Functions::.).
+ locally inside the minibuffer (*note Help Functions::).
- Function: active-minibuffer-window
This function returns the currently active minibuffer window, or
`nil' if none is currently active.
- - Function: minibuffer-window &optional FRAME
+ - Function: minibuffer-window &optional frame
This function returns the minibuffer window used for frame FRAME.
If FRAME is `nil', that stands for the current frame. Note that
the minibuffer window used by a frame need not be part of that
frame--a frame that has no minibuffer of its own necessarily uses
some other frame's minibuffer window.
- - Function: window-minibuffer-p WINDOW
+ - Function: window-minibuffer-p window
This function returns non-`nil' if WINDOW is a minibuffer window.
It is not correct to determine whether a given window is a
because there can be more than one minibuffer window if there is more
than one frame.
- - Function: minibuffer-window-active-p WINDOW
+ - Function: minibuffer-window-active-p window
This function returns non-`nil' if WINDOW, assumed to be a
minibuffer window, is currently active.
minibuffer, it scrolls this window.
Finally, some functions and variables deal with recursive minibuffers
-(*note Recursive Editing::.):
+(*note Recursive Editing::):
- Function: minibuffer-depth
This function returns the current depth of activations of the
* Events:: What input looks like when you read it.
* Reading Input:: How to read input events from the keyboard or mouse.
* Waiting:: Waiting for user input or elapsed time.
-* Quitting:: How `C-g' works. How to catch or defer quitting.
+* Quitting:: How C-g works. How to catch or defer quitting.
* Prefix Command Arguments:: How the commands to set prefix args work.
* Recursive Editing:: Entering a recursive edit,
and why you usually shouldn't.
translation should be a keyboard macro or an interactively callable
function. If the key is `M-x', then it reads the name of another
command, which it then calls. This is done by the command
-`execute-extended-command' (*note Interactive Call::.).
+`execute-extended-command' (*note Interactive Call::).
To execute a command requires first reading the arguments for it.
-This is done by calling `command-execute' (*note Interactive Call::.).
+This is done by calling `command-execute' (*note Interactive Call::).
For commands written in Lisp, the `interactive' specification says how
to read the arguments. This may use the prefix argument (*note Prefix
-Command Arguments::.) or may read with prompting in the minibuffer
-(*note Minibuffers::.). For example, the command `find-file' has an
+Command Arguments::) or may read with prompting in the minibuffer
+(*note Minibuffers::). For example, the command `find-file' has an
`interactive' specification which says to read a file name using the
minibuffer. The command's function body does not use the minibuffer;
if you call this command from Lisp code as a function, you must supply
If the command is a string or vector (i.e., a keyboard macro) then
`execute-kbd-macro' is used to execute it. You can call this function
-yourself (*note Keyboard Macros::.).
+yourself (*note Keyboard Macros::).
To terminate the execution of a running command, type `C-g'. This
-character causes "quitting" (*note Quitting::.).
+character causes "quitting" (*note Quitting::).
- Variable: pre-command-hook
The editor command loop runs this normal hook before each command.
This section describes how to write the `interactive' form that
makes a Lisp function an interactively-callable command.
- - Special Form: interactive ARG-DESCRIPTOR
+ - Special Form: interactive arg-descriptor
This special form declares that the function in which it appears
is a command, and that it may therefore be called interactively
(via `M-x' or by entering a key sequence bound to it). The
output; if subprocess output arrives while the command is waiting
for input, it could relocate point and the mark.
- Here's an example of what *not* to do:
+ Here's an example of what _not_ to do:
(interactive
(list (region-beginning) (region-end)
The prompt string can use `%' to include previous argument values
(starting with the first argument) in the prompt. This is done
- using `format' (*note Formatting Strings::.). For example, here
- is how you could read the name of an existing buffer followed by a
+ using `format' (*note Formatting Strings::). For example, here is
+ how you could read the name of an existing buffer followed by a
new name to give to that buffer:
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
prompt string (starting with the first character that is not `*',
`@', or `_').
- - Function: function-interactive FUNCTION
+ - Function: function-interactive function
This function retrieves the interactive specification of FUNCTION,
which may be any funcallable object. The specification will be
returned as the list of the symbol `interactive' and the specs. If
Completion
Provide completion. <TAB>, <SPC>, and <RET> perform name
completion because the argument is read using `completing-read'
- (*note Completion::.). `?' displays a list of possible
- completions.
+ (*note Completion::). `?' displays a list of possible completions.
Existing
Require the name of an existing object. An invalid name is not
`b'
The name of an existing buffer. By default, uses the name of the
- current buffer (*note Buffers::.). Existing, Completion, Default,
+ current buffer (*note Buffers::). Existing, Completion, Default,
Prompt.
`B'
Completion, Prompt.
`d'
- The position of point, as an integer (*note Point::.). No I/O.
+ The position of point, as an integer (*note Point::). No I/O.
`D'
A directory name. The default is the current default directory of
the current buffer, `default-directory' (*note System
- Environment::.). Existing, Completion, Default, Prompt.
+ Environment::). Existing, Completion, Default, Prompt.
`e'
The last mouse-button or misc-user event in the key sequence that
such event.
`f'
- A file name of an existing file (*note File Names::.). The default
+ A file name of an existing file (*note File Names::). The default
directory is `default-directory'. Existing, Completion, Default,
Prompt.
Prompt.
`k'
- A key sequence (*note Keymap Terminology::.). This keeps reading
+ A key sequence (*note Keymap Terminology::). This keeps reading
events until a command (or undefined command) is found in the
current key maps. The key sequence argument is represented as a
vector of events. The cursor does not move into the echo area.
`s'
Arbitrary text, read in the minibuffer and returned as a string
- (*note Text from Minibuffer::.). Terminate the input with either
+ (*note Text from Minibuffer::). Terminate the input with either
<LFD> or <RET>. (`C-q' may be used to include either of these
characters in the input.) Prompt.
`command-execute' calls `call-interactively', which reads the arguments
and calls the command. You can also call these functions yourself.
- - Function: commandp OBJECT
+ - Function: commandp object
Returns `t' if OBJECT is suitable for calling interactively; that
is, if OBJECT is a command. Otherwise, returns `nil'.
A symbol is `commandp' if its function definition is `commandp'.
Keys and keymaps are not commands. Rather, they are used to look
- up commands (*note Keymaps::.).
+ up commands (*note Keymaps::).
See `documentation' in *Note Accessing Documentation::, for a
realistic example of using `commandp'.
- - Function: call-interactively COMMAND &optional RECORD-FLAG
+ - Function: call-interactively command &optional record-flag
This function calls the interactively callable function COMMAND,
reading arguments according to its interactive calling
specifications. An error is signaled if COMMAND is not a function
the command is added only if it uses the minibuffer to read an
argument. *Note Command History::.
- - Function: command-execute COMMAND &optional RECORD-FLAG
+ - Function: command-execute command &optional record-flag
This function executes COMMAND as an editing command. The
argument COMMAND must satisfy the `commandp' predicate; i.e., it
must be an interactively callable function or a keyboard macro.
Such a definition is handled by loading the specified library and
then rechecking the definition of the symbol.
- - Command: execute-extended-command PREFIX-ARGUMENT
+ - Command: execute-extended-command prefix-argument
This function reads a command name from the minibuffer using
- `completing-read' (*note Completion::.). Then it uses
+ `completing-read' (*note Completion::). Then it uses
`command-execute' to call the specified command. Whatever that
command returns becomes the value of `execute-extended-command'.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
is the nearest character equivalent to it (or `nil' if there is no
character equivalent). `last-command-char' is the character that
`self-insert-command' will insert in the buffer. Remember that
- there is *not* a one-to-one mapping between keyboard events and
+ there is _not_ a one-to-one mapping between keyboard events and
XEmacs characters: many keyboard events have no corresponding
character, and when the Mule feature is available, most characters
can not be input on standard keyboards, except possibly with help
For information about how exactly the XEmacs command loop works,
*Note Reading Input::.
- - Function: eventp OBJECT
+ - Function: eventp object
This function returns non-`nil' if EVENT is an input event.
* Menu:
modifiers
Which modifier keys were pressed. The special business
- mentioned above for the shift key does *not* apply to mouse
+ mentioned above for the shift key does _not_ apply to mouse
events.
x
modifiers
Which modifier keys were pressed. The special business
- mentioned above for the shift key does *not* apply to mouse
+ mentioned above for the shift key does _not_ apply to mouse
events.
misc-user event
modifiers
Which modifier keys were pressed. The special business
- mentioned above for the shift key does *not* apply to mouse
+ mentioned above for the shift key does _not_ apply to mouse
events.
x
The object to pass to the function. The function and object
are set when the event is created.
- - Function: event-type EVENT
+ - Function: event-type event
Return the type of EVENT.
This will be a symbol; one of
The following predicates return whether an object is an event of a
particular type.
- - Function: key-press-event-p OBJECT
+ - Function: key-press-event-p object
This is true if OBJECT is a key-press event.
- - Function: button-event-p OBJECT OBJECT
+ - Function: button-event-p object object
This is true if OBJECT is a mouse button-press or button-release
event.
- - Function: button-press-event-p OBJECT
+ - Function: button-press-event-p object
This is true if OBJECT is a mouse button-press event.
- - Function: button-release-event-p OBJECT
+ - Function: button-release-event-p object
This is true if OBJECT is a mouse button-release event.
- - Function: motion-event-p OBJECT
+ - Function: motion-event-p object
This is true if OBJECT is a mouse motion event.
- - Function: mouse-event-p OBJECT
+ - Function: mouse-event-p object
This is true if OBJECT is a mouse button-press, button-release or
motion event.
- - Function: eval-event-p OBJECT
+ - Function: eval-event-p object
This is true if OBJECT is an eval event.
- - Function: misc-user-event-p OBJECT
+ - Function: misc-user-event-p object
This is true if OBJECT is a misc-user event.
- - Function: process-event-p OBJECT
+ - Function: process-event-p object
This is true if OBJECT is a process event.
- - Function: timeout-event-p OBJECT
+ - Function: timeout-event-p object
This is true if OBJECT is a timeout event.
- - Function: event-live-p OBJECT
+ - Function: event-live-p object
This is true if OBJECT is any event that has not been deallocated.
\1f
The following functions return frame-level information about where a
mouse event occurred.
- - Function: event-frame EVENT
+ - Function: event-frame event
This function returns the "channel" or frame that the given mouse
motion, button press, button release, or misc-user event occurred
in. This will be `nil' for non-mouse events.
- - Function: event-x-pixel EVENT
+ - Function: event-x-pixel event
This function returns the X position in pixels of the given mouse
event. The value returned is relative to the frame the event
occurred in. This will signal an error if the event is not a
mouse event.
- - Function: event-y-pixel EVENT
+ - Function: event-y-pixel event
This function returns the Y position in pixels of the given mouse
event. The value returned is relative to the frame the event
occurred in. This will signal an error if the event is not a
The following functions return window-level information about where
a mouse event occurred.
- - Function: event-window EVENT
+ - Function: event-window event
Given a mouse motion, button press, button release, or misc-user
event, compute and return the window on which that event occurred.
This may be `nil' if the event occurred in the border or over a
toolbar. The modeline is considered to be within the window it
describes.
- - Function: event-buffer EVENT
+ - Function: event-buffer event
Given a mouse motion, button press, button release, or misc-user
event, compute and return the buffer of the window on which that
event occurred. This may be `nil' if the event occurred in the
`event-window' and then calling `window-buffer' on the result if
it is a window.
- - Function: event-window-x-pixel EVENT
+ - Function: event-window-x-pixel event
This function returns the X position in pixels of the given mouse
event. The value returned is relative to the window the event
occurred in. This will signal an error if the event is not a
mouse-motion, button-press, button-release, or misc-user event.
- - Function: event-window-y-pixel EVENT
+ - Function: event-window-y-pixel event
This function returns the Y position in pixels of the given mouse
event. The value returned is relative to the window the event
occurred in. This will signal an error if the event is not a
The following functions return information about the text (including
the modeline) that a mouse event occurred over or near.
- - Function: event-over-text-area-p EVENT
+ - Function: event-over-text-area-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over the text
area of a window. Otherwise, `nil' is returned. The modeline is
not considered to be part of the text area.
- - Function: event-over-modeline-p EVENT
+ - Function: event-over-modeline-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over the modeline
of a window. Otherwise, `nil' is returned.
- - Function: event-x EVENT
+ - Function: event-x event
This function returns the X position of the given mouse-motion,
button-press, button-release, or misc-user event in characters.
This is relative to the window the event occurred over.
- - Function: event-y EVENT
+ - Function: event-y event
This function returns the Y position of the given mouse-motion,
button-press, button-release, or misc-user event in characters.
This is relative to the window the event occurred over.
- - Function: event-point EVENT
+ - Function: event-point event
This function returns the character position of the given
mouse-motion, button-press, button-release, or misc-user event.
If the event did not occur over a window, or did not occur over
text, then this returns `nil'. Otherwise, it returns an index
into the buffer visible in the event's window.
- - Function: event-closest-point EVENT
+ - Function: event-closest-point event
This function returns the character position of the given
mouse-motion, button-press, button-release, or misc-user event.
If the event did not occur over a window or over text, it returns
The following functions return information about the glyph (if any)
that a mouse event occurred over.
- - Function: event-over-glyph-p EVENT
+ - Function: event-over-glyph-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over a glyph.
Otherwise, `nil' is returned.
- - Function: event-glyph-extent EVENT
+ - Function: event-glyph-extent event
If the given mouse-motion, button-press, button-release, or
misc-user event happened on top of a glyph, this returns its
extent; else `nil' is returned.
- - Function: event-glyph-x-pixel EVENT
+ - Function: event-glyph-x-pixel event
Given a mouse-motion, button-press, button-release, or misc-user
event over a glyph, this function returns the X position of the
pointer relative to the upper left of the glyph. If the event is
not over a glyph, it returns `nil'.
- - Function: event-glyph-y-pixel EVENT
+ - Function: event-glyph-y-pixel event
Given a mouse-motion, button-press, button-release, or misc-user
event over a glyph, this function returns the Y position of the
pointer relative to the upper left of the glyph. If the event is
Event Toolbar Position Info
...........................
- - Function: event-over-toolbar-p EVENT
+ - Function: event-over-toolbar-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over a toolbar.
Otherwise, `nil' is returned.
- - Function: event-toolbar-button EVENT
+ - Function: event-toolbar-button event
If the given mouse-motion, button-press, button-release, or
misc-user event happened on top of a toolbar button, this function
returns the button. Otherwise, `nil' is returned.
Other Event Position Info
.........................
- - Function: event-over-border-p EVENT
+ - Function: event-over-border-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over an internal
toolbar. Otherwise, `nil' is returned.
The following functions allow access to the contents of events other
than the position info described in the previous section.
- - Function: event-timestamp EVENT
+ - Function: event-timestamp event
This function returns the timestamp of the given event object.
- - Function: event-device EVENT
+ - Function: event-device event
This function returns the device that the given event occurred on.
- - Function: event-key EVENT
+ - Function: event-key event
This function returns the Keysym of the given key-press event.
This will be the ASCII code of a printing character, or a symbol.
- - Function: event-button EVENT
+ - Function: event-button event
This function returns the button-number of the given button-press
or button-release event.
- - Function: event-modifiers EVENT
+ - Function: event-modifiers event
This function returns a list of symbols, the names of the modifier
keys which were down when the given mouse or keyboard event was
produced.
- - Function: event-modifier-bits EVENT
+ - Function: event-modifier-bits event
This function returns a number representing the modifier keys
which were down when the given mouse or keyboard event was
produced.
- - Function: event-function EVENT
+ - Function: event-function event
This function returns the callback function of the given timeout,
misc-user, or eval event.
- - Function: event-object EVENT
+ - Function: event-object event
This function returns the callback function argument of the given
timeout, misc-user, or eval event.
- - Function: event-process EVENT
+ - Function: event-process event
This function returns the process of the given process event.
\1f
either an event object or `nil', creating the event object first in the
latter case.
- - Function: make-event &optional TYPE PLIST
+ - Function: make-event &optional type plist
This function creates a new event structure. If no arguments are
specified, the created event will be empty. To specify the event
type, use the TYPE argument. The allowed types are `empty',
The event timestamp, a non-negative integer. Allowed for all
types of events.
- *WARNING*: the event object returned by this function may be a
+ _WARNING_: the event object returned by this function may be a
reused one; see the function `deallocate-event'.
The events created by `make-event' can be used as non-interactive
;; Create an empty event.
(make-event)
=> #<empty-event>
-
+
;; Try creating a key-press event.
(make-event 'key-press)
error--> Undefined key for keypress event
-
+
;; Creating a key-press event, try 2
(make-event 'key-press '(key home))
=> #<keypress-event home>
-
+
;; Create a key-press event of dubious fame.
(make-event 'key-press '(key escape modifiers (meta alt control shift)))
=> #<keypress-event control-meta-alt-shift-escape>
-
+
;; Create a M-button1 event at coordinates defined by variables
;; X and Y.
(make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
=> #<buttondown-event meta-button1>
-
+
;; Create a similar button-release event.
(make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
=> #<buttonup-event meta-button1up>
-
+
;; Create a mouse-motion event.
(make-event 'motion '(x 20 y 30))
=> #<motion-event 20, 30>
(append '(modifiers nil)
(event-properties EVENT)))
- - Function: copy-event EVENT1 &optional EVENT2
+ - Function: copy-event event1 &optional event2
This function makes a copy of the given event object. If a second
argument is given, the first event is copied into the second and
the second is returned. If the second argument is not supplied
(or is `nil') then a new event will be made.
- - Function: deallocate-event EVENT
+ - Function: deallocate-event event
This function allows the given event structure to be reused. You
*MUST NOT* use this event object after calling this function with
it. You will lose. It is not necessary to call this function, as
events and other ways of representing keys. These are useful when
working with ASCII strings and with keymaps.
- - Function: character-to-event CH &optional EVENT DEVICE
+ - Function: character-to-event ch &optional event device
This function converts a numeric ASCII value to an event structure,
replete with modifier bits. CH is the character to convert, and
EVENT is the event object to fill in. This function contains
strictly inverse functions, since events contain much more
information than the ASCII character set can encode.
- - Function: event-to-character EVENT &optional ALLOW-EXTRA-MODIFIERS
- ALLOW-META ALLOW-NON-ASCII
+ - Function: event-to-character event &optional allow-extra-modifiers
+ allow-meta allow-non-ascii
This function returns the closest ASCII approximation to EVENT.
If the event isn't a keypress, this returns `nil'.
ambiguous, as both use the high bit; <M-x> and <oslash> will be
indistinguishable.
- - Function: events-to-keys EVENTS &optional NO-MICE
+ - Function: events-to-keys events &optional no-mice
Given a vector of event objects, this function returns a vector of
key descriptors, or a string (if they all fit in the ASCII range).
Optional arg NO-MICE means that button events are not allowed.
`read-key-sequence'; for example, `describe-key' uses it to read the
key to describe.
- - Function: read-key-sequence PROMPT
+ - Function: read-key-sequence prompt
This function reads a sequence of keystrokes or mouse clicks and
returns it as a vector of events. It keeps reading events until
it has accumulated a full key sequence; that is, enough to specify
actions), and other events, which serve as communication between XEmacs
and the window system.
- - Function: next-event &optional EVENT PROMPT
+ - Function: next-event &optional event prompt
This function reads and returns the next available event from the
window system or terminal driver, waiting if necessary until an
event is available. Pass this object to `dispatch-event' to
In most cases, the function `next-command-event' is more
appropriate.
- - Function: next-command-event &optional EVENT
+ - Function: next-command-event &optional event
This function returns the next available "user" event from the
window system or terminal driver. Pass this object to
`dispatch-event' to handle it. If an event object is supplied, it
compatibility with Emacs 18, and is most likely the wrong thing
for you to be using: consider using `next-command-event' instead.
- - Function: enqueue-eval-event FUNCTION OBJECT
+ - Function: enqueue-eval-event function object
This function adds an eval event to the back of the queue. The
eval event will be the next event read after all pending events.
Dispatching an Event
--------------------
- - Function: dispatch-event EVENT
+ - Function: dispatch-event event
Given an event object returned by `next-event', this function
executes it. This is the basic function that makes XEmacs respond
to user input; it also deals with notifications from the window
character conveniently, either literally or as an octal character code.
The command `quoted-insert' uses this function.
- - Function: read-quoted-char &optional PROMPT
+ - Function: read-quoted-char &optional prompt
This function is like `read-char', except that if the first
character read is an octal digit (0-7), it reads up to two more
octal digits (but stopping if a non-octal digit is found) and
- Variable: last-input-char
If the value of `last-input-event' is a keyboard event, then this
is the nearest ASCII equivalent to it. Remember that there is
- *not* a 1:1 mapping between keyboard events and ASCII characters:
+ _not_ a 1:1 mapping between keyboard events and ASCII characters:
the set of keyboard events is much larger, so writing code that
examines this variable to determine what key has been typed is bad
practice, unless you are certain that it will be one of a small
two arguments to specify the time (one integer and one float value),
instead of a single argument that can be either an integer or a float.
- - Function: sit-for SECONDS &optional NODISP
+ - Function: sit-for seconds &optional nodisp
This function performs redisplay (provided there is no pending
input from the user), then waits SECONDS seconds, or until input is
available. The result is `t' if `sit-for' waited the full time
The usual purpose of `sit-for' is to give the user time to read
text that you display.
- - Function: sleep-for SECONDS
+ - Function: sleep-for seconds
This function simply pauses for SECONDS seconds without updating
the display. This function pays no attention to available input.
It returns `nil'.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
In the minibuffer, `C-g' has a different definition: it aborts out
of the minibuffer. This means, in effect, that it exits the minibuffer
and then quits. (Simply quitting would return to the command loop
-*within* the minibuffer.) The reason why `C-g' does not quit directly
+_within_ the minibuffer.) The reason why `C-g' does not quit directly
when the command reader is reading input is so that its meaning can be
redefined in the minibuffer in this way. `C-g' following a prefix key
is not redefined in the minibuffer, and it has its normal effect of
value of the prefix argument directly in the variable
`current-prefix-arg', but this is less clean.
- - Function: prefix-numeric-value ARG
+ - Function: prefix-numeric-value arg
This function returns the numeric meaning of a valid raw prefix
argument value, ARG. The argument may be a symbol, a number, or a
list. If it is `nil', the value 1 is returned; if it is `-', the
returned.
- Variable: current-prefix-arg
- This variable holds the raw prefix argument for the *current*
+ This variable holds the raw prefix argument for the _current_
command. Commands may examine it directly, but the usual way to
access it is with `(interactive "P")'.
- Variable: prefix-arg
The value of this variable is the raw prefix argument for the
- *next* editing command. Commands that specify prefix arguments for
+ _next_ editing command. Commands that specify prefix arguments for
the following command work by setting this variable.
Do not call the functions `universal-argument', `digit-argument', or
`negative-argument' unless you intend to let the user enter the prefix
-argument for the *next* command.
+argument for the _next_ command.
- Command: universal-argument
This command reads input and specifies a prefix argument for the
following command. Don't call this command yourself unless you
know what you are doing.
- - Command: digit-argument ARG
+ - Command: digit-argument arg
This command adds to the prefix argument for the following
command. The argument ARG is the raw prefix argument as it was
before this command; it is used to compute the updated prefix
argument. Don't call this command yourself unless you know what
you are doing.
- - Command: negative-argument ARG
+ - Command: negative-argument arg
This command adds to the numeric argument for the next command.
The argument ARG is the raw prefix argument as it was before this
command; its value is negated to form the new prefix argument.
`recursive-edit'. This function contains the command loop; it also
contains a call to `catch' with tag `exit', which makes it possible to
exit the recursive editing level by throwing to `exit' (*note Catch and
-Throw::.). If you throw a value other than `t', then `recursive-edit'
+Throw::). If you throw a value other than `t', then `recursive-edit'
returns normally to the function that called it. The command `C-M-c'
(`exit-recursive-edit') does this. Throwing a `t' value causes
`recursive-edit' to quit, so that control returns to the command loop
when a disabled command is invoked interactively. Disabling a command
has no effect on calling it as a function from Lisp programs.
- - Command: enable-command COMMAND
+ - Command: enable-command command
Allow COMMAND to be executed without special confirmation from now
on, and (if the user confirms) alter the user's `.emacs' file so
that this will apply to future sessions.
- - Command: disable-command COMMAND
+ - Command: disable-command command
Require special confirmation to execute COMMAND from now on, and
(if the user confirms) alter the user's `.emacs' file so that this
will apply to future sessions.
represented as a form to evaluate. It continues to accumulate all
complex commands for the duration of the editing session, but all
but the first (most recent) thirty elements are deleted when a
- garbage collection takes place (*note Garbage Collection::.).
+ garbage collection takes place (*note Garbage Collection::).
command-history
=> ((switch-to-buffer "chistory.texi")
(find-tag "repeat-complex-command"))
This history list is actually a special case of minibuffer history
-(*note Minibuffer History::.), with one special twist: the elements are
+(*note Minibuffer History::), with one special twist: the elements are
expressions rather than strings.
There are a number of commands devoted to the editing and recall of
considered a command and made the definition of a key. The Lisp
representation of a keyboard macro is a string or vector containing the
events. Don't confuse keyboard macros with Lisp macros (*note
-Macros::.).
+Macros::).
- - Function: execute-kbd-macro MACRO &optional COUNT
+ - Function: execute-kbd-macro macro &optional count
This function executes MACRO as a sequence of events. If MACRO is
a string or vector, then the events in it are executed exactly as
- if they had been input by the user. The sequence is *not*
+ if they had been input by the user. The sequence is _not_
expected to be a single key sequence; normally a keyboard macro
definition consists of several key sequences concatenated.
execution by the command loop). Given an event (or an event type) and a
keymap, XEmacs can get the event's definition. Events mapped in keymaps
include keypresses, button presses, and button releases (*note
-Events::.).
+Events::).
A sequence of input events that form a unit is called a "key
sequence", or "key" for short. A sequence of one event is always a key
bindings. Note that this is different from Emacs 18 and FSF Emacs,
where keymaps are lists.
- - Function: keymapp OBJECT
+ - Function: keymapp object
This function returns `t' if OBJECT is a keymap, `nil' otherwise.
\1f
Here we describe the functions for creating keymaps.
- - Function: make-keymap &optional NAME
+ - Function: make-keymap &optional name
This function constructs and returns a new keymap object. All
entries in it are `nil', meaning "command undefined".
as in `set-keymap-name'. This name is only a debugging
convenience; it is not used except when printing the keymap.
- - Function: make-sparse-keymap &optional NAME
+ - Function: make-sparse-keymap &optional name
This function constructs and returns a new keymap object. All
entries in it are `nil', meaning "command undefined". The only
difference between this function and `make-keymap' is that this
as in `set-keymap-name'. This name is only a debugging
convenience; it is not used except when printing the keymap.
- - Function: set-keymap-name KEYMAP NEW-NAME
+ - Function: set-keymap-name keymap new-name
This function assigns a "name" to a keymap. The name is only a
debugging convenience; it is not used except when printing the
keymap.
- - Function: keymap-name KEYMAP
+ - Function: keymap-name keymap
This function returns the "name" of a keymap, as assigned using
`set-keymap-name'.
- - Function: copy-keymap KEYMAP
+ - Function: copy-keymap keymap
This function returns a copy of KEYMAP. Any keymaps that appear
directly as bindings in KEYMAP are also copied recursively, and so
on to any number of levels. However, recursive copying does not
`(current-global-map)' is the default parent of all keymaps.
- - Function: set-keymap-parents KEYMAP PARENTS
+ - Function: set-keymap-parents keymap parents
This function sets the parent keymaps of KEYMAP to the list
PARENTS.
`define-key' to change KEYMAP, that affects the bindings in that
map, but has no effect on any of the keymaps in PARENTS.
- - Function: keymap-parents KEYMAP
+ - Function: keymap-parents keymap
This function returns the list of parent keymaps of KEYMAP, or
`nil' if KEYMAP has no parents.
neither the keymap's parents nor the current global map are searched for
key bindings.
- - Function: set-keymap-default-binding KEYMAP COMMAND
+ - Function: set-keymap-default-binding keymap command
This function sets the default binding of KEYMAP to COMMAND, or
`nil' if no default is desired.
- - Function: keymap-default-binding KEYMAP
+ - Function: keymap-default-binding keymap
This function returns the default binding of KEYMAP, or `nil' if
it has none.
object, as returned by the `next-command-event' and `read-key-sequence'
functions.
- Note that in this context, the keystroke `control-b' is *not*
+ Note that in this context, the keystroke `control-b' is _not_
represented by the number 2 (the ASCII code for `^B') or the character
`?\^B'. See below.
system. If you're talking to XEmacs through a TTY connection, you
don't get any of these features.
- - Function: event-matches-key-specifier-p EVENT KEY-SPECIFIER
+ - Function: event-matches-key-specifier-p event key-specifier
This function returns non-`nil' if EVENT matches KEY-SPECIFIER,
which can be any valid form representing a key sequence. This can
be useful, e.g., to determine if the user pressed `help-char' or
* `esc-map' is an evil hack that is present for compatibility
purposes with Emacs 18. Defining a key in `esc-map' is equivalent
to defining the same key in `global-map' but with the <META>
- prefix added. You should *not* use this in your code. (This map is
+ prefix added. You should _not_ use this in your code. (This map is
also the function definition of `ESC-prefix'.)
The binding of a prefix key is the keymap to use for looking up the
(key-binding "\C-p6")
=> nil
- - Function: define-prefix-command SYMBOL &optional MAPVAR
+ - Function: define-prefix-command symbol &optional mapvar
This function defines SYMBOL as a prefix command: it creates a
keymap and stores it as SYMBOL's function definition. Storing the
symbol as the binding of a key makes the key a prefix key that has
* the current global map.
Note that if `overriding-local-map' or
-`overriding-terminal-local-map' is non-`nil', *only* those two maps and
+`overriding-terminal-local-map' is non-`nil', _only_ those two maps and
the current global map are searched.
The procedure for searching a single keymap is called "key lookup";
*Note Standard Keymaps::, for a list of standard keymaps.
- - Function: current-keymaps &optional EVENT-OR-KEYS
+ - Function: current-keymaps &optional event-or-keys
This function returns a list of the current keymaps that will be
searched for bindings. This lists keymaps such as the current
local map and the minor-mode maps, but does not list the parents
This function returns a list of the keymaps of currently enabled
minor modes.
- - Function: use-global-map KEYMAP
+ - Function: use-global-map keymap
This function makes KEYMAP the new current global keymap. It
returns `nil'.
It is very unusual to change the global keymap.
- - Function: use-local-map KEYMAP &optional BUFFER
+ - Function: use-local-map keymap &optional buffer
This function makes KEYMAP the new local keymap of BUFFER. BUFFER
defaults to the current buffer. If KEYMAP is `nil', then the
buffer has no local keymap. `use-local-map' returns `nil'. Most
normal mechanism if there is no binding for that click. This
buffer's value of `mode-motion-hook' will be consulted instead of
the `mode-motion-hook' of the buffer of the window under the mouse.
- You should *bind* this, not set it.
+ You should _bind_ this, not set it.
- Variable: overriding-local-map
If non-`nil', this variable holds a keymap to use instead of the
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
its function definition is invalid as a function. It is, however,
valid as a key binding. If the definition is a keyboard macro,
then the symbol is also valid as an argument to `command-execute'
- (*note Interactive Call::.).
+ (*note Interactive Call::).
The symbol `undefined' is worth special mention: it means to treat
the key as undefined. Strictly speaking, the key is defined, and
Here are the functions and variables pertaining to key lookup.
- - Function: lookup-key KEYMAP KEY &optional ACCEPT-DEFAULTS
+ - Function: lookup-key keymap key &optional accept-defaults
This function returns the definition of KEY in KEYMAP. If the
string or vector KEY is not a valid key sequence according to the
prefix keys specified in KEYMAP (which means it is "too long" and
Unlike `read-key-sequence', this function does not modify the
specified events in ways that discard information (*note Key
- Sequence Input::.). In particular, it does not convert letters to
+ Sequence Input::). In particular, it does not convert letters to
lower case.
- Command: undefined
this, invoking this key sequence causes a "key undefined" error,
just as if the key sequence had no binding.
- - Function: key-binding KEY &optional ACCEPT-DEFAULTS
+ - Function: key-binding key &optional accept-defaults
This function returns the binding for KEY in the current keymaps,
trying all the active keymaps. The result is `nil' if KEY is
undefined in the keymaps.
(key-binding [escape escape escape])
=> keyboard-escape-quit
- - Function: local-key-binding KEY &optional ACCEPT-DEFAULTS
+ - Function: local-key-binding key &optional accept-defaults
This function returns the binding for KEY in the current local
keymap, or `nil' if it is undefined there.
The argument ACCEPT-DEFAULTS controls checking for default
bindings, as in `lookup-key' (above).
- - Function: global-key-binding KEY &optional ACCEPT-DEFAULTS
+ - Function: global-key-binding key &optional accept-defaults
This function returns the binding for command KEY in the current
global keymap, or `nil' if it is undefined there.
The argument ACCEPT-DEFAULTS controls checking for default
bindings, as in `lookup-key' (above).
- - Function: minor-mode-key-binding KEY &optional ACCEPT-DEFAULTS
+ - Function: minor-mode-key-binding key &optional accept-defaults
This function returns a list of all the active minor mode bindings
of KEY. More precisely, it returns an alist of pairs `(MODENAME .
BINDING)', where MODENAME is the variable that enables the minor
This variable is the meta-prefix character code. It is used when
translating a two-character sequence to a meta character so it can
be looked up in a keymap. For useful results, the value should be
- a prefix event (*note Prefix Keys::.). The default value is
- `?\^[' (integer 27), which is the ASCII character usually produced
- by the <ESC> key.
+ a prefix event (*note Prefix Keys::). The default value is `?\^['
+ (integer 27), which is the ASCII character usually produced by the
+ <ESC> key.
As long as the value of `meta-prefix-char' remains `?\^[', key
lookup translates `<ESC> b' into `M-b', which is normally defined
meta-prefix-char ; The default value.
=> ?\^[ ; Under XEmacs 20.
=> 27 ; Under XEmacs 19.
-
(key-binding "\eb")
=> backward-word
-
?\C-x ; The print representation
; of a character.
=> ?\^X ; Under XEmacs 20.
=> 24 ; Under XEmacs 19.
-
(setq meta-prefix-char 24)
=> 24
-
(key-binding "\C-xb")
=> backward-word ; Now, typing `C-x b' is
; like typing `M-b'.
global binding with a local one). If you change the current buffer's
local map, that usually affects all buffers using the same major mode.
The `global-set-key' and `local-set-key' functions are convenient
-interfaces for these operations (*note Key Binding Commands::.). You
+interfaces for these operations (*note Key Binding Commands::). You
can also use `define-key', a more general function; then you must
specify explicitly the map to change.
The way to specify the key sequence that you want to rebind is
-described above (*note Key Sequences::.).
+described above (*note Key Sequences::).
For the functions below, an error is signaled if KEYMAP is not a
keymap or if KEY is not a string or vector representing a key sequence.
You can use event types (symbols) as shorthand for events that are
lists.
- - Function: define-key KEYMAP KEY BINDING
+ - Function: define-key keymap key binding
This function sets the binding for KEY in KEYMAP. (If KEY is more
than one event long, the change is actually made in another keymap
reached from KEYMAP.) The argument BINDING can be any Lisp
(setq map (make-sparse-keymap))
=> #<keymap 0 entries 0xbee>
-
(define-key map "\C-f" 'forward-char)
=> forward-char
-
map
=> #<keymap 1 entry 0xbee>
(describe-bindings-internal map)
=> ; (Inserted in buffer)
C-f forward-char
-
+
;; Build sparse submap for `C-x' and bind `f' in that.
(define-key map "\C-xf" 'forward-word)
=> forward-word
-
map
=> #<keymap 2 entries 0xbee>
(describe-bindings-internal map)
C-x << Prefix Command >>
C-x f forward-word
-
+
;; Bind `C-p' to the `ctl-x-map'.
(define-key map "\C-p" ctl-x-map)
;; `ctl-x-map'
=> #<keymap Control-X-prefix 77 entries 0x3bf>
-
+
;; Bind `C-f' to `foo' in the `ctl-x-map'.
(define-key map "\C-p\C-f" 'foo)
=> foo
-
map
=> #<keymap 3 entries 0xbee>
(describe-bindings-internal map)
changing an entry in `ctl-x-map', and this has the effect of changing
the bindings of both `C-p C-f' and `C-x C-f' in the default global map.
- - Function: substitute-key-definition OLDDEF NEWDEF KEYMAP &optional
- OLDMAP
+ - Function: substitute-key-definition olddef newdef keymap &optional
+ oldmap
This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
that were bound to OLDDEF. In other words, OLDDEF is replaced
with NEWDEF wherever it appears. The function returns `nil'.
are globally bound to the standard deletion command.
- - Function: suppress-keymap KEYMAP &optional NODIGITS
+ - Function: suppress-keymap keymap &optional nodigits
This function changes the contents of the full keymap KEYMAP by
making all the printing characters undefined. More precisely, it
binds them to the command `undefined'. This makes ordinary
The `suppress-keymap' function does not make it impossible to
modify a buffer, as it does not suppress commands such as `yank'
and `quoted-insert'. To prevent any modification of a buffer, make
- it read-only (*note Read Only Buffers::.).
+ it read-only (*note Read Only Buffers::).
Since this function modifies KEYMAP, you would normally use it on
a newly created keymap. Operating on an existing keymap that is
from the file `emacs/lisp/dired.el', showing how the local keymap
for Dired mode is set up:
- ...
+ ...
(setq dired-mode-map (make-keymap))
(suppress-keymap dired-mode-map)
(define-key dired-mode-map "r" 'dired-rename-file)
redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.
- - Command: global-set-key KEY DEFINITION
+ - Command: global-set-key key definition
This function sets the binding of KEY in the current global map to
DEFINITION.
==
(define-key (current-global-map) KEY DEFINITION)
- - Command: global-unset-key KEY
+ - Command: global-unset-key key
This function removes the binding of KEY from the current global
map.
(global-unset-key "\C-l")
=> nil
-
(global-set-key "\C-l\C-l" 'redraw-display)
=> nil
==
(define-key (current-global-map) KEY nil)
- - Command: local-set-key KEY DEFINITION
+ - Command: local-set-key key definition
This function sets the binding of KEY in the current local keymap
to DEFINITION.
==
(define-key (current-local-map) KEY DEFINITION)
- - Command: local-unset-key KEY
+ - Command: local-unset-key key
This function removes the binding of KEY from the current local
map.
keymaps, or all keys within a keymap, for the sake of printing help
information.
- - Function: accessible-keymaps KEYMAP &optional PREFIX
+ - Function: accessible-keymaps keymap &optional prefix
This function returns a list of all the keymaps that can be
accessed (via prefix keys) from KEYMAP. The value is an
association list with elements of the form `(KEY . MAP)', where
8 entries 0x3ef>)
2 entries 0x3f5>))
- - Function: map-keymap FUNCTION KEYMAP &optional SORT-FIRST
+ - Function: map-keymap function keymap &optional sort-first
This function applies FUNCTION to each element of `KEYMAP'.
FUNCTION will be called with two arguments: a key-description
list, and the binding. The order in which the elements of the
the function more than once.
The function will not be called on elements of this keymap's
- parents (*note Inheritance and Keymaps::.) or upon keymaps which
+ parents (*note Inheritance and Keymaps::) or upon keymaps which
are contained within this keymap (multi-character definitions).
It will be called on <META> characters since they are not really
two-character sequences.
canonical order. Otherwise, they will be passed in hash (that is,
random) order, which is faster.
- - Function: keymap-fullness KEYMAP
+ - Function: keymap-fullness keymap
This function returns the number of bindings in the keymap.
- - Function: where-is-internal DEFINITION &optional KEYMAPS FIRSTONLY
- NOINDIRECT EVENT-OR-KEYS
+ - Function: where-is-internal definition &optional keymaps firstonly
+ noindirect event-or-keys
This function returns a list of key sequences (of any length) that
are bound to DEFINITION in a set of keymaps.
(where-is-internal 'describe-function)
=> ([(control h) d] [(control h) f] [f1 d] [f1 f])
- - Function: describe-bindings-internal MAP &optional ALL SHADOW PREFIX
- MOUSE-ONLY-P
+ - Function: describe-bindings-internal map &optional all shadow prefix
+ mouse-only-p
This function inserts (into the current buffer) a list of all
defined keys and their definitions in MAP. Optional second
argument ALL says whether to include even "uninteresting"
`describe-bindings-internal' is used to implement the help command
`describe-bindings'.
- - Command: describe-bindings PREFIX MOUSE-ONLY-P
+ - Command: describe-bindings prefix mouse-only-p
This function creates a listing of all defined keys and their
definitions. It writes the listing in a buffer named `*Help*' and
displays it in a window.
Other Keymap Functions
======================
- - Function: set-keymap-prompt KEYMAP NEW-PROMPT
+ - Function: set-keymap-prompt keymap new-prompt
This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
`nil' if no prompt is desired. The prompt is shown in the
echo-area when reading a key-sequence to be looked-up in this
keymap.
- - Function: keymap-prompt KEYMAP &optional USE-INHERITED
+ - Function: keymap-prompt keymap &optional use-inherited
This function returns the "prompt" of the given keymap. If
USE-INHERITED is non-`nil', any parent keymaps will also be
searched for a prompt.
`current-menubar', and then calling `set-menubar-dirty-flag'. Note
that these functions copy their argument using `copy-sequence'.
- - Function: set-menubar MENUBAR
+ - Function: set-menubar menubar
This function sets the default menubar to be MENUBAR (*note Menu
- Format::.). This is the menubar that will be visible in buffers
+ Format::). This is the menubar that will be visible in buffers
that have not defined their own, buffer-local menubar.
- - Function: set-buffer-menubar MENUBAR
+ - Function: set-buffer-menubar menubar
This function sets the buffer-local menubar to be MENUBAR. This
does not change the menubar in any buffers other than the current
one.
menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under
the "Foo" submenu of "Menu".
- - Function: add-submenu MENU-PATH SUBMENU &optional BEFORE
+ - Function: add-submenu menu-path submenu &optional before
This function adds a menu to the menubar or one of its submenus.
If the named menu exists already, it is changed.
inserted. If MENU-PATH is `nil', then the menu will be added to
the menubar itself.
- SUBMENU is the new menu to add (*note Menu Format::.).
+ SUBMENU is the new menu to add (*note Menu Format::).
BEFORE, if provided, is the name of a menu before which this menu
should be added, if this menu is not on its parent already. If
the menu is already present, it will not be moved.
- - Function: add-menu-button MENU-PATH MENU-LEAF &optional BEFORE
+ - Function: add-menu-button menu-path menu-leaf &optional before
This function adds a menu item to some menu, creating the menu
first if necessary. If the named item exists already, it is
changed.
MENU-PATH identifies the menu under which the new menu item should
be inserted.
- MENU-LEAF is a menubar leaf node (*note Menu Format::.).
+ MENU-LEAF is a menubar leaf node (*note Menu Format::).
BEFORE, if provided, is the name of a menu before which this item
should be added, if this item is not on the menu already. If the
item is already present, it will not be moved.
- - Function: delete-menu-item MENU-ITEM-PATH
+ - Function: delete-menu-item menu-item-path
This function removes the menu item specified by MENU-ITEM-PATH
from the menu hierarchy.
- - Function: enable-menu-item MENU-ITEM-PATH
+ - Function: enable-menu-item menu-item-path
This function makes the menu item specified by MENU-ITEM-PATH be
selectable.
- - Function: disable-menu-item MENU-ITEM-PATH
+ - Function: disable-menu-item menu-item-path
This function makes the menu item specified by MENU-ITEM-PATH be
unselectable.
- - Function: relabel-menu-item MENU-ITEM-PATH NEW-NAME
+ - Function: relabel-menu-item menu-item-path new-name
This function changes the string of the menu item specified by
MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be
printed as from now on.
The following function can be used to search for a particular item in
a menubar specification, given a path to the item.
- - Function: find-menu-item MENUBAR MENU-ITEM-PATH &optional PARENT
+ - Function: find-menu-item menubar menu-item-path &optional parent
This function searches MENUBAR for the item given by
MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
of MENUBAR). This function returns `(ITEM . PARENT)', where
existing code can be understood. You should not use these functions in
new code.
- - Function: add-menu MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE
+ - Function: add-menu menu-path menu-name menu-items &optional before
This function adds a menu to the menubar or one of its submenus.
If the named menu exists already, it is changed. This is
obsolete; use `add-submenu' instead.
MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
a list of menu items, strings, and submenus. These two arguments
are the same as the first and following elements of a menu
- description (*note Menu Format::.).
+ description (*note Menu Format::).
BEFORE, if provided, is the name of a menu before which this menu
should be added, if this menu is not on its parent already. If the
menu is already present, it will not be moved.
- - Function: add-menu-item MENU-PATH ITEM-NAME FUNCTION ENABLED-P
- &optional BEFORE
+ - Function: add-menu-item menu-path item-name function enabled-p
+ &optional before
This function adds a menu item to some menu, creating the menu
first if necessary. If the named item exists already, it is
changed. This is obsolete; use `add-menu-button' instead.
MENU-PATH identifies the menu under which the new menu item should
be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
second, and third elements of a menu item vector (*note Menu
- Format::.).
+ Format::).
BEFORE, if provided, is the name of a menu item before which this
item should be added, if this item is not on the menu already. If
`default-menubar'. You may want to use them in your own menubar
description.
- - Function: file-menu-filter MENU-ITEMS
+ - Function: file-menu-filter menu-items
This function changes the arguments and sensitivity of these File
menu items:
`Delete Frame'
Sensitive only when there is more than one visible frame.
- - Function: edit-menu-filter MENU-ITEMS
+ - Function: edit-menu-filter menu-items
This function changes the arguments and sensitivity of these Edit
menu items:
Sensitive only when there is undo information. While in the
midst of an undo, this is changed to `Undo More'.
- - Function: buffers-menu-filter MENU-ITEMS
+ - Function: buffers-menu-filter menu-items
This function sets up the Buffers menu. *Note Buffers Menu::, for
more information.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Pop-Up Menus
============
- - Function: popup-menu MENU-DESC
+ - Function: popup-menu menu-desc
This function pops up a menu specified by MENU-DESC, which is a
- menu description (*note Menu Format::.). The menu is displayed at
+ menu description (*note Menu Format::). The menu is displayed at
the current mouse position.
- Function: popup-menu-up-p
The following convenience functions are provided for displaying
pop-up menus.
- - Function: popup-buffer-menu EVENT
+ - Function: popup-buffer-menu event
This function pops up a copy of the `Buffers' menu (from the
menubar) where the mouse is clicked.
- - Function: popup-menubar-menu EVENT
+ - Function: popup-menubar-menu event
This function pops up a copy of menu that also appears in the
menubar.
then all buffers will be shown. Setting this to a large number or
`nil' will slow down menu responsiveness.
- - Function: format-buffers-menu-line BUFFER
+ - Function: format-buffers-menu-line buffer
This function returns a string to represent BUFFER in the
`Buffers' menu. `nil' means the buffer shouldn't be listed. You
can redefine this.
Dialog Box Functions
====================
- - Function: popup-dialog-box DBOX-DESC
+ - Function: popup-dialog-box dbox-desc
This function pops up a dialog box. DBOX-DESC describes how the
- dialog box will appear (*note Dialog Box Format::.).
+ dialog box will appear (*note Dialog Box Format::).
*Note Yes-or-No Queries::, for functions to ask a yes/no question
using a dialog box.
the frame, and two or more different edges can be displaying toolbars
simultaneously. The contents, thickness, and visibility of the
toolbars can be controlled separately, and the values can be
-per-buffer, per-frame, etc., using specifiers (*note Specifiers::.).
+per-buffer, per-frame, etc., using specifiers (*note Specifiers::).
Normally, there is one toolbar displayed in a frame. Usually, this
is the standard toolbar, but certain modes will override this and
area. If omitted, it defaults to a device-specific value (8
pixels for X devices).
- - Function: toolbar-make-button-list UP &optional DOWN DISABLED CAP-UP
- CAP-DOWN CAP-DISABLED
+ - Function: toolbar-make-button-list up &optional down disabled cap-up
+ cap-down cap-disabled
This function calls `make-glyph' on each arg and returns a list of
the results. This is useful for setting the first argument of a
toolbar button descriptor (typically, the result of this function
is assigned to a symbol, which is specified as the first argument
of the toolbar button descriptor).
- - Function: check-toolbar-button-syntax BUTTON &optional NOERROR
+ - Function: check-toolbar-button-syntax button &optional noerror
Verify the syntax of entry BUTTON in a toolbar description list.
If you want to verify the syntax of a toolbar description list as a
whole, use `check-valid-instantiator' with a specifier type of
`right-toolbar-width', and the visibility status is controlled by the
specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
`left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
-Toolbar Variables::.).
+Toolbar Variables::).
- - Function: set-default-toolbar-position POSITION
+ - Function: set-default-toolbar-position position
This function sets the position that the `default-toolbar' will be
displayed at. Valid positions are the symbols `top', `bottom',
`left' and `right'. What this actually does is set the fallback
same thing for the position-specific thickness and visibility
specifiers, which inherit from one of `default-toolbar-height' or
`default-toolbar-width', and from `default-toolbar-visible-p',
- respectively (*note Other Toolbar Variables::.).
+ respectively (*note Other Toolbar Variables::).
- Function: default-toolbar-position
This function returns the position that the `default-toolbar' will
- Specifier: right-toolbar
Specifier for the toolbar at the right edge of the frame.
- - Function: toolbar-specifier-p OBJECT
+ - Function: toolbar-specifier-p object
This function returns non-nil if OBJECT is a toolbar specifier.
Toolbar specifiers are the actual objects contained in the toolbar
variables described above, and their valid instantiators are
- toolbar descriptors (*note Toolbar Descriptor Format::.).
+ toolbar descriptors (*note Toolbar Descriptor Format::).
\1f
File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar
Drag and Drop
*************
- *WARNING*: the Drag'n'Drop API is still under development and the
+ _WARNING_: the Drag'n'Drop API is still under development and the
interface may change! The current implementation is considered
experimental.
OffiX DND
---------
- *WARNING*: If you compile in OffiX, you may not be able to use
+ _WARNING_: If you compile in OffiX, you may not be able to use
multiple X displays successfully. If the two servers are from
different vendors, the results may be unpredictable.
modify the old one to serve two purposes, since it may become harder to
use and maintain. Instead, copy and rename an existing major mode
definition and alter the copy--or define a "derived mode" (*note
-Derived Modes::.). For example, Rmail Edit mode, which is in
+Derived Modes::). For example, Rmail Edit mode, which is in
`emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
mode except that it provides three additional commands. Its definition
is distinct from that of Text mode, but was derived from it.
;; Create mode-specific tables.
(defvar text-mode-syntax-table nil
"Syntax table used while in text mode.")
-
+
(if text-mode-syntax-table
() ; Do not change the table if it is already set up.
(setq text-mode-syntax-table (make-syntax-table))
(modify-syntax-entry ?\" ". " text-mode-syntax-table)
(modify-syntax-entry ?\\ ". " text-mode-syntax-table)
(modify-syntax-entry ?' "w " text-mode-syntax-table))
-
+
(defvar text-mode-abbrev-table nil
"Abbrev table used while in text mode.")
(define-abbrev-table 'text-mode-abbrev-table ())
-
+
(defvar text-mode-map nil) ; Create a mode-specific keymap.
(if text-mode-map
(defun text-mode ()
"Major mode for editing text intended for humans to read.
Special commands: \\{text-mode-map}
-
Turning on text-mode runs the hook `text-mode-hook'."
(interactive)
(kill-all-local-variables)
-
- (use-local-map text-mode-map) ; This provides the local keymap.
+ (use-local-map text-mode-map) ; This provides the local keymap.
(setq mode-name "Text") ; This name goes into the modeline.
(setq major-mode 'text-mode) ; This is how `describe-mode'
; finds the doc string to print.
(defvar lisp-mode-syntax-table nil "")
(defvar emacs-lisp-mode-syntax-table nil "")
(defvar lisp-mode-abbrev-table nil "")
-
+
(if (not emacs-lisp-mode-syntax-table) ; Do not change the table
; if it is already set.
(let ((i 0))
(setq emacs-lisp-mode-syntax-table (make-syntax-table))
-
- ;; Set syntax of chars up to 0 to class of chars that are
+
+ ;; Set syntax of chars up to 0 to class of chars that are
;; part of symbol names but not words.
;; (The number 0 is `48' in the ASCII character set.)
(while (< i ?0)
(modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
(setq i (1+ i)))
...
-
- ;; Set the syntax for other characters.
+ ;; Set the syntax for other characters.
(modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
(modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
...
-
- (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
+ (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
(modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
...))
;; Create an abbrev table for lisp-mode.
;; The Emacs Lisp mode syntax table always exists, but
;; the Lisp Mode syntax table is created the first time a
;; mode that needs it is called. This is to save space.
-
- (progn (setq lisp-mode-syntax-table
+ (progn (setq lisp-mode-syntax-table
(copy-syntax-table emacs-lisp-mode-syntax-table))
;; Change some entries for Lisp mode.
(modify-syntax-entry ?\| "\" "
lisp-mode-syntax-table)
(modify-syntax-entry ?\] "_ "
lisp-mode-syntax-table)))
-
- (set-syntax-table lisp-mode-syntax-table)))
+ (set-syntax-table lisp-mode-syntax-table)))
(setq local-abbrev-table lisp-mode-abbrev-table)
...)
`comment-indent-function'. The code to set these variables is the rest
of `lisp-mode-variables'.
- (make-local-variable 'paragraph-start)
+ (make-local-variable 'paragraph-start)
;; Having `^' is not clean, but `page-delimiter'
;; has them too, and removing those is a pain.
(setq paragraph-start (concat "^$\\|" page-delimiter))
...
-
- (make-local-variable 'comment-indent-function)
+ (make-local-variable 'comment-indent-function)
(setq comment-indent-function 'lisp-comment-indent))
Each of the different Lisp modes has a slightly different keymap.
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs. Semicolons start comments.
\\{emacs-lisp-mode-map}
-
Entry to this mode runs the hook `emacs-lisp-mode-hook'."
(interactive)
(kill-all-local-variables)
(use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
(set-syntax-table emacs-lisp-mode-syntax-table)
-
- (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
+ (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
; finds out what to describe.
(setq mode-name "Emacs-Lisp") ; This goes into the modeline.
(lisp-mode-variables nil) ; This defines various variables.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
anything in particular. Other major modes are defined in effect
by comparison with this one--their definitions say what to change,
starting from Fundamental mode. The `fundamental-mode' function
- does *not* run any hooks; you're not supposed to customize it.
+ does _not_ run any hooks; you're not supposed to customize it.
(If you want Emacs to behave differently in Fundamental mode,
- change the *global* state of Emacs.)
+ change the _global_ state of Emacs.)
- - Command: normal-mode &optional FIND-FILE
+ - Command: normal-mode &optional find-file
This function establishes the proper major mode and local variable
bindings for the current buffer. First it calls `set-auto-mode',
then it runs `hack-local-variables' to parse, and bind or evaluate
property are those such as Dired and Rmail that are useful only
with text that has been specially prepared.
- - Function: set-buffer-major-mode BUFFER
+ - Function: set-buffer-major-mode buffer
This function sets the major mode of BUFFER to the value of
`default-major-mode'. If that variable is `nil', it uses the
current buffer's major mode (if that is suitable).
- Variable: auto-mode-alist
This variable contains an association list of file name patterns
- (regular expressions; *note Regular Expressions::.) and
+ (regular expressions; *note Regular Expressions::) and
corresponding major mode functions. Usually, the file name
patterns test for suffixes, such as `.el' and `.c', but this need
not be the case. An ordinary element of the alist looks like
(("^/tmp/fol/" . text-mode)
("\\.texinfo\\'" . texinfo-mode)
("\\.texi\\'" . texinfo-mode)
-
- ("\\.el\\'" . emacs-lisp-mode)
+ ("\\.el\\'" . emacs-lisp-mode)
("\\.c\\'" . c-mode)
("\\.h\\'" . c-mode)
...)
When you visit a file whose expanded file name (*note File Name
- Expansion::.) matches a REGEXP, `set-auto-mode' calls the
+ Expansion::) matches a REGEXP, `set-auto-mode' calls the
corresponding MODE-FUNCTION. This feature enables XEmacs to select
the proper major mode for most files.
This variable is applicable only when the `auto-mode-alist' does
not indicate which major mode to use.
- - Function: hack-local-variables &optional FORCE
+ - Function: hack-local-variables &optional force
This function parses, and binds or evaluates as appropriate, any
local variables for the current buffer.
It's often useful to define a new major mode in terms of an existing
one. An easy way to do this is to use `define-derived-mode'.
- - Macro: define-derived-mode VARIANT PARENT NAME DOCSTRING BODY...
+ - Macro: define-derived-mode variant parent name docstring body...
This construct defines VARIANT as a major mode command, using NAME
as the string form of the mode name.
(> (prefix-numeric-value arg) 0)))
* Add an element to `minor-mode-alist' for each minor mode (*note
- Modeline Variables::.). This element should be a list of the
+ Modeline Variables::). This element should be a list of the
following form:
(MODE-VARIABLE STRING)
The modeline of a window is normally updated whenever a different
buffer is shown in the window, or when the buffer's modified-status
changes from `nil' to `t' or vice-versa. If you modify any of the
-variables referenced by `modeline-format' (*note Modeline
-Variables::.), you may want to force an update of the modeline so as to
-display the new information.
+variables referenced by `modeline-format' (*note Modeline Variables::),
+you may want to force an update of the modeline so as to display the
+new information.
- - Function: redraw-modeline &optional ALL
+ - Function: redraw-modeline &optional all
Force redisplay of the current buffer's modeline. If ALL is
non-`nil', then force redisplay of all modelines.
`mode-line-format'. The data structure is called a "modeline
construct", and it is built in recursive fashion out of simpler modeline
constructs. The same data structure is used for constructing frame
-titles (*note Frame Titles::.).
+titles (*note Frame Titles::).
- Variable: modeline-format
The value of this variable is a modeline construct with overall
If you do alter `modeline-format' itself, the new value should use
the same variables that appear in the default value (*note Modeline
-Variables::.), rather than duplicating their contents or displaying the
+Variables::), rather than duplicating their contents or displaying the
information in another fashion. This way, customizations made by the
user or by Lisp programs (such as `display-time' and major modes) via
changes to those variables remain effective.
The recommended way to add a hook function to a normal hook is by
calling `add-hook' (see below). The hook functions may be any of the
valid kinds of functions that `funcall' accepts (*note What Is a
-Function::.). Most normal hook variables are initially void;
-`add-hook' knows how to deal with this.
+Function::). Most normal hook variables are initially void; `add-hook'
+knows how to deal with this.
As for abnormal hooks, those whose names end in `-function' have a
value that is a single function. Those whose names end in `-hooks'
to customize the behavior of the mode, by overriding the local variable
assignments already made by the mode. But hooks are used in other
contexts too. For example, the hook `suspend-hook' runs just before
-XEmacs suspends itself (*note Suspending XEmacs::.).
+XEmacs suspends itself (*note Suspending XEmacs::).
Here's an expression that uses a mode hook to turn on Auto Fill mode
when in Lisp Interaction mode:
particular hooks. This function calls the hook functions you have
added with `add-hooks'.
- - Function: run-hooks &rest HOOKVAR
+ - Function: run-hooks &rest hookvar
This function takes one or more hook variable names as arguments,
and runs each hook in turn. Each HOOKVAR argument should be a
symbol that is a hook variable. These arguments are processed in
(run-hooks 'emacs-lisp-mode-hook)
- - Function: add-hook HOOK FUNCTION &optional APPEND LOCAL
+ - Function: add-hook hook function &optional append local
This function is the handy way to add function FUNCTION to hook
variable HOOK. The argument FUNCTION may be any valid Lisp
function with the proper number of arguments. For example,
buffer-local, then the value of LOCAL makes no difference--the
hook function is always global.
- - Function: remove-hook HOOK FUNCTION &optional LOCAL
+ - Function: remove-hook hook function &optional local
This function removes FUNCTION from the hook variable HOOK.
If LOCAL is non-`nil', that says to remove FUNCTION from the local
itself is not buffer-local, then the value of LOCAL makes no
difference.
- - Function: make-local-hook HOOK
+ - Function: make-local-hook hook
This function makes the hook variable `hook' local to the current
buffer. When a hook variable is local, it can have local and
global hook functions, and `run-hooks' runs all of them.
the function or variable that it describes:
* The documentation for a function is stored in the function
- definition itself (*note Lambda Expressions::.). The function
+ definition itself (*note Lambda Expressions::). The function
`documentation' knows how to extract it.
* The documentation for a variable is stored in the variable's
stored in the "internal doc file" `DOC'. The documentation for
functions and variables loaded during the XEmacs session from
byte-compiled files is stored in those very same byte-compiled files
-(*note Docs and Compilation::.).
+(*note Docs and Compilation::).
XEmacs does not keep documentation strings in memory unless
necessary. Instead, XEmacs maintains, for preloaded symbols, an
Access to Documentation Strings
===============================
- - Function: documentation-property SYMBOL PROPERTY &optional VERBATIM
+ - Function: documentation-property symbol property &optional verbatim
This function returns the documentation string that is recorded in
SYMBOL's property list under property PROPERTY. It retrieves the
text from a file if necessary, and runs `substitute-command-keys'
(documentation-property 'command-line-processed
'variable-documentation)
=> "t once command line has been processed"
-
(symbol-plist 'command-line-processed)
=> (variable-documentation 188902)
- - Function: documentation FUNCTION &optional VERBATIM
+ - Function: documentation function &optional verbatim
This function returns the documentation string of FUNCTION. It
reads the text from a file if necessary. Then (unless VERBATIM is
non-`nil') it calls `substitute-command-keys', to return a value
(let ((describe-func
(function
(lambda (s)
-
- ;; Print description of symbol.
+ ;; Print description of symbol.
(if (fboundp s) ; It is a function.
(princ
(format "%s\t%s\n%s\n\n" s
keys " "))
"Keys: none"))
"Function")
-
- (or (documentation s)
+ (or (documentation s)
"not documented"))))
(if (boundp s) ; It is a variable.
-
- (princ
+ (princ
(format "%s\t%s\n%s\n\n" s
(if (user-variable-p s)
"Option " "Variable")
-
- (or (documentation-property
+ (or (documentation-property
s 'variable-documentation)
"not documented")))))))
sym-list)
-
- ;; Build a list of symbols that match pattern.
+
+ ;; Build a list of symbols that match pattern.
(mapatoms (function
(lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list))))))
-
- ;; Display the data.
+
+ ;; Display the data.
(with-output-to-temp-buffer "*Help*"
(mapcar describe-func (sort sym-list 'string<))
(print-help-return-message))))
---------- Buffer: *Help* ----------
goal-column Option
*Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
-
+
set-goal-column Command: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
-
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
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.
-
+
temporary-goal-column Variable
Current goal column for vertical motion.
It is the column where point was
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------
- - Function: Snarf-documentation FILENAME
+ - Function: Snarf-documentation filename
This function is used only during XEmacs initialization, just
before the runnable XEmacs is dumped. It finds the file offsets
of the documentation strings stored in the file FILENAME, and
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
*Please note:* Each `\' must be doubled when written in a string in
XEmacs Lisp.
- - Function: substitute-command-keys STRING
+ - Function: substitute-command-keys string
This function scans STRING for the above special sequences and
replaces them by what they stand for, returning the result as a
string. This permits display of documentation that refers
(substitute-command-keys
"To abort recursive edit, type: \\[abort-recursive-edit]")
=> "To abort recursive edit, type: C-]"
-
+
(substitute-command-keys
"The keys that are defined for the minibuffer here are:
\\{minibuffer-local-must-match-map}")
RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
+
(substitute-command-keys
"To abort a recursive edit from the minibuffer, type\
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
=> "To abort a recursive edit from the minibuffer, type C-g."
-
+
(substitute-command-keys
"Substrings of the form \\=\\{MAPVAR} are replaced by summaries
\(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
characters. The description of a non-whitespace printing character is
the character itself.
- - Function: key-description SEQUENCE
+ - Function: key-description sequence
This function returns a string containing the XEmacs standard
notation for the input events in SEQUENCE. The argument SEQUENCE
may be a string, vector or list. *Note Events::, for more
information about valid events. See also the examples for
`single-key-description', below.
- - Function: single-key-description KEY
+ - Function: single-key-description key
This function returns a string describing KEY in the standard
XEmacs notation for keyboard input. A normal printing character
appears as itself, but a control character turns into a string
(single-key-description ?\C-x)
=> "C-x"
-
(key-description "\C-x \M-y \n \t \r \f123")
=> "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
-
(single-key-description 'kp_next)
=> "kp_next"
-
(single-key-description '(shift button1))
=> "Sh-button1"
- - Function: text-char-description CHARACTER
+ - Function: text-char-description character
This function returns a string describing CHARACTER in the
standard XEmacs notation for characters that appear in text--like
`single-key-description', except that control characters are
(text-char-description ?\C-c)
=> "^C"
-
(text-char-description ?\M-m)
=> "M-m"
-
(text-char-description ?\C-\M-m)
=> "M-^M"
`help'. For more information about them, see *Note Help: (emacs)Help.
Here we describe some program-level interfaces to the same information.
- - Command: apropos REGEXP &optional DO-ALL PREDICATE
+ - Command: apropos regexp &optional do-all predicate
This function finds all symbols whose names contain a match for the
regular expression REGEXP, and returns a list of them (*note
- Regular Expressions::.). It also displays the symbols in a buffer
+ Regular Expressions::). It also displays the symbols in a buffer
named `*Help*', each with a one-line description.
If DO-ALL is non-`nil', then `apropos' also shows key bindings for
=> (Buffer-menu-execute command-execute exec-directory
exec-path execute-extended-command execute-kbd-macro
executing-kbd-macro executing-macro)
-
+
(apropos "exec" nil 'commandp)
=> (Buffer-menu-execute execute-extended-command)
(define-key global-map "\C-h" 'help-command)
(fset 'help-command help-map)
- - Function: print-help-return-message &optional FUNCTION
+ - Function: print-help-return-message &optional function
This function builds a string that explains how to restore the
previous state of the windows after a help command. After
building the message, it applies FUNCTION to it if FUNCTION is
what the input is for and how to enter it properly.
Entry to the minibuffer binds this variable to the value of
- `minibuffer-help-form' (*note Minibuffer Misc::.).
+ `minibuffer-help-form' (*note Minibuffer Misc::).
- Variable: prefix-help-command
This variable holds a function to print help for a prefix
Lisp lets you mark a function or variable as "obsolete", and indicate
what should be used instead.
- - Function: make-obsolete FUNCTION NEW
+ - Function: make-obsolete function new
This function indicates that FUNCTION is an obsolete function, and
the function NEW should be used instead. The byte compiler will
issue a warning to this effect when it encounters a usage of the
should be a descriptive statement, such as "use FOO or BAR
instead" or "this function is unnecessary".
- - Function: make-obsolete-variable VARIABLE NEW
+ - Function: make-obsolete-variable variable new
This is like `make-obsolete' but is for variables instead of
functions.
- - Function: define-obsolete-function-alias OLDFUN NEWFUN
+ - Function: define-obsolete-function-alias oldfun newfun
This function combines `make-obsolete' and `define-function',
declaring OLDFUN to be an obsolete variant of NEWFUN and defining
OLDFUN as an alias for NEWFUN.
- - Function: define-obsolete-variable-alias OLDVAR NEWVAR
+ - Function: define-obsolete-variable-alias oldvar newvar
This is like `define-obsolete-function-alias' but for variables.
Note that you should not normally put obsoleteness information
documentation of the new function, making it more likely that he will
use the new function.
- - Function: function-obsoleteness-doc FUNCTION
+ - Function: function-obsoleteness-doc function
If FUNCTION is obsolete, this function returns a string describing
this. This is the message that is printed out during byte
compilation or in the function's documentation. If FUNCTION is
not obsolete, `nil' is returned.
- - Function: variable-obsoleteness-doc VARIABLE
+ - Function: variable-obsoleteness-doc variable
This is like `function-obsoleteness-doc' but for variables.
The obsoleteness information is stored internally by putting a
temporary buffer. Visiting the file is not necessary and takes longer.
*Note Reading from Files::.
- - Command: find-file FILENAME
+ - Command: find-file filename
This command selects a buffer visiting the file FILENAME, using an
existing buffer if there is one, and otherwise creating a new
buffer and reading the file into it. It also returns that buffer.
When `find-file' is called interactively, it prompts for FILENAME
in the minibuffer.
- - Function: find-file-noselect FILENAME &optional NOWARN
+ - Function: find-file-noselect filename &optional nowarn
This function is the guts of all the file-visiting functions. It
finds or creates a buffer visiting the file FILENAME, and returns
it. It uses an existing buffer if there is one, and otherwise
are suppressed.
The `find-file-noselect' function calls `after-find-file' after
- reading the file (*note Subroutines of Visiting::.). That function
+ reading the file (*note Subroutines of Visiting::). That function
sets the buffer major mode, parses local variables, warns the user
if there exists an auto-save file more recent than the file just
visited, and finishes by running the functions in
(find-file-noselect "/etc/fstab")
=> #<buffer fstab>
- - Command: find-file-other-window FILENAME
+ - Command: find-file-other-window filename
This command selects a buffer visiting the file FILENAME, but does
so in a window other than the selected window. It may use another
existing window or split a window; see *Note Displaying Buffers::.
When this command is called interactively, it prompts for FILENAME.
- - Command: find-file-read-only FILENAME
+ - Command: find-file-read-only filename
This command selects a buffer visiting the file FILENAME, like
`find-file', but it marks the buffer as read-only. *Note Read
Only Buffers::, for related functions and variables.
When this command is called interactively, it prompts for FILENAME.
- - Command: view-file FILENAME
+ - Command: view-file filename
This command visits FILENAME in View mode, and displays it in a
recursive edit, returning to the previous buffer when done. View
mode is a mode that allows you to skim rapidly through the file
`after-find-file' functions as subroutines. Sometimes it is useful to
call them directly.
- - Function: create-file-buffer FILENAME
+ - Function: create-file-buffer filename
This function creates a suitably named buffer for visiting
FILENAME, and returns it. It uses FILENAME (sans directory) as
the name if that name is free; otherwise, it appends a string such
as `<2>' to get an unused name. See also *Note Creating Buffers::.
- *Please note:* `create-file-buffer' does *not* associate the new
+ *Please note:* `create-file-buffer' does _not_ associate the new
buffer with a file and does not select the buffer. It also does
not use the default major mode.
=> #<buffer foo<3>>
This function is used by `find-file-noselect'. It uses
- `generate-new-buffer' (*note Creating Buffers::.).
+ `generate-new-buffer' (*note Creating Buffers::).
- - Function: after-find-file &optional ERROR WARN NOAUTO
+ - Function: after-find-file &optional error warn noauto
This function sets the buffer major mode, and parses local
- variables (*note Auto Major Mode::.). It is called by
+ variables (*note Auto Major Mode::). It is called by
`find-file-noselect' and by the default revert function (*note
- Reverting::.).
+ Reverting::).
If reading the file got an error because the file does not exist,
but its directory does exist, the caller should pass a non-`nil'
buffer do not change the file until you "save" the buffer, which means
copying the contents of the buffer into the file.
- - Command: save-buffer &optional BACKUP-OPTION
+ - Command: save-buffer &optional backup-option
This function saves the contents of the current buffer in its
visited file if the buffer has been modified since it was last
visited or saved. Otherwise it does nothing.
`save-buffer' function unconditionally backs up the previous
version of the file before saving it.
- - Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING
+ - Command: save-some-buffers &optional save-silently-p exiting
This command saves some modified file-visiting buffers. Normally
it asks the user about each buffer. But if SAVE-SILENTLY-P is
non-`nil', it saves all the file-visiting buffers without querying
variable is automatically local in all buffers. Normally, Mail
mode (used for editing outgoing mail) sets this to `t'.
- - Command: write-file FILENAME
+ - Command: write-file filename
This function writes the current buffer into file FILENAME, makes
the buffer visit that file, and marks it not modified. Then it
renames the buffer based on FILENAME, appending a string like `<2>'
- User Option: require-final-newline
This variable determines whether files may be written out that do
- *not* end with a newline. If the value of the variable is `t',
+ _not_ end with a newline. If the value of the variable is `t',
then `save-buffer' silently adds a newline at the end of the file
whenever the buffer being saved does not already end in one. If
the value of the variable is non-`nil', but not `t', then
the `insert-file-contents' function. Don't use the user-level command
`insert-file' in a Lisp program, as that sets the mark.
- - Function: insert-file-contents FILENAME &optional VISIT BEG END
- REPLACE
+ - Function: insert-file-contents filename &optional visit beg end
+ replace
This function inserts the contents of file FILENAME into the
current buffer after point. It returns a list of the absolute
file name and the length of the data inserted. An error is
functions. Don't use these functions to write to files that are being
visited; that could cause confusion in the mechanisms for visiting.
- - Command: append-to-file START END FILENAME
+ - Command: append-to-file start end filename
This function appends the contents of the region delimited by
START and END in the current buffer to the end of file FILENAME.
If that file does not exist, it is created. If that file exists
An error is signaled if FILENAME specifies a nonwritable file, or
a nonexistent file in a directory where files cannot be created.
- - Command: write-region START END FILENAME &optional APPEND VISIT
+ - Command: write-region start end filename &optional append visit
This function writes the region delimited by START and END in the
current buffer into the file specified by FILENAME.
modification of a buffer visiting a file changed on disk catches some
cases of simultaneous editing; see *Note Modification Time::.
- - Function: file-locked-p &optional FILENAME
+ - Function: file-locked-p &optional filename
This function returns `nil' if the file FILENAME is not locked by
this XEmacs process. It returns `t' if it is locked by this
XEmacs, and it returns the name of the user who has locked it if it
(file-locked-p "foo")
=> nil
- - Function: lock-buffer &optional FILENAME
+ - Function: lock-buffer &optional filename
This function locks the file FILENAME, if the current buffer is
modified. The argument FILENAME defaults to the current buffer's
visited file. Nothing is done if the current buffer is not
the file should not be locked, so this function does nothing. It
also does nothing if the current buffer is not visiting a file.
- - Function: ask-user-about-lock FILE OTHER-USER
+ - Function: ask-user-about-lock file other-user
This function is called when the user tries to modify FILE, but it
is locked by another user named OTHER-USER. The value it returns
determines what happens next:
These functions test for permission to access a file in specific
ways.
- - Function: file-exists-p FILENAME
+ - Function: file-exists-p filename
This function returns `t' if a file named FILENAME appears to
exist. This does not mean you can necessarily read the file, only
that you can find out its attributes. (On Unix, this is true if
prevent you from finding the attributes of the file, this function
returns `nil'.
- - Function: file-readable-p FILENAME
+ - Function: file-readable-p filename
This function returns `t' if a file named FILENAME exists and you
can read it. It returns `nil' otherwise.
(file-readable-p "/usr/spool/mqueue")
=> nil
- - Function: file-executable-p FILENAME
+ - Function: file-executable-p filename
This function returns `t' if a file named FILENAME exists and you
can execute it. It returns `nil' otherwise. If the file is a
directory, execute permission means you can check the existence and
attributes of files inside the directory, and open those files if
their modes permit.
- - Function: file-writable-p FILENAME
+ - Function: file-writable-p filename
This function returns `t' if the file FILENAME can be written or
created by you, and `nil' otherwise. A file is writable if the
file exists and you can write it. It is creatable if it does not
(file-writable-p "~/no-such-dir/foo")
=> nil
- - Function: file-accessible-directory-p DIRNAME
+ - Function: file-accessible-directory-p dirname
This function returns `t' if you have permission to open existing
files in the directory whose name as a file is DIRNAME; otherwise
(or if there is no such directory), it returns `nil'. The value
we can deduce that any attempt to read a file in `/foo/' will give
an error.
- - Function: file-ownership-preserved-p FILENAME
+ - Function: file-ownership-preserved-p filename
This function returns `t' if deleting the file FILENAME and then
creating it anew would keep the file's owner unchanged.
- - Function: file-newer-than-file-p FILENAME1 FILENAME2
+ - Function: file-newer-than-file-p filename1 filename2
This function returns `t' if the file FILENAME1 is newer than file
FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
FILENAME2 does not exist, it returns `t'.
This section describes how to distinguish various kinds of files,
such as directories, symbolic links, and ordinary files.
- - Function: file-symlink-p FILENAME
+ - Function: file-symlink-p filename
If the file FILENAME is a symbolic link, the `file-symlink-p'
function returns the file name to which it is linked. This may be
the name of a text file, a directory, or even another symbolic
=> "/pub/bin"
- - Function: file-directory-p FILENAME
+ - Function: file-directory-p filename
This function returns `t' if FILENAME is the name of an existing
directory, `nil' otherwise.
(substitute-in-file-name "$HOME"))
=> t
- - Function: file-regular-p FILENAME
+ - Function: file-regular-p filename
This function returns `t' if the file FILENAME exists and is a
regular file (not a directory, symbolic link, named pipe,
terminal, or other I/O device).
---------
The "truename" of a file is the name that you get by following
-symbolic links until none remain, then expanding to get rid of `.' and
+symbolic links until none remain, then expanding to get rid of `.' and
`..' as components. Strictly speaking, a file need not have a unique
truename; the number of distinct truenames a file has is equal to the
number of hard links to the file. However, truenames are useful
because they eliminate symbolic links as a cause of name variation.
- - Function: file-truename FILENAME &optional DEFAULT
+ - Function: file-truename filename &optional default
The function `file-truename' returns the true name of the file
FILENAME. This is the name that you get by following symbolic
links until none remain.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
the number of names, the inode number, the size, and the times of access
and modification.
- - Function: file-modes FILENAME
+ - Function: file-modes filename
This function returns the mode bits of FILENAME, as an integer.
The mode bits are also called the file permissions, and they
specify access control in the usual Unix fashion. If the
% ls -l diffs
-rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
- - Function: file-nlinks FILENAME
+ - Function: file-nlinks filename
This functions returns the number of names (i.e., hard links) that
file FILENAME has. If the file does not exist, then this function
returns `nil'. Note that symbolic links have no effect on this
(file-nlinks "doesnt-exist")
=> nil
- - Function: file-attributes FILENAME
+ - Function: file-attributes filename
This function returns a list of attributes of file FILENAME. If
the specified file cannot be opened, it returns `nil'.
1. The number of names the file has. Alternate names, also
known as hard links, can be created by using the
`add-name-to-file' function (*note Changing File
- Attributes::.).
+ Attributes::).
2. The file's UID.
* Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
is any other value.
- - Command: add-name-to-file OLDNAME NEWNAME &optional
- OK-IF-ALREADY-EXISTS
+ - Command: add-name-to-file oldname newname &optional
+ ok-if-already-exists
This function gives the file named OLDNAME the additional name
NEWNAME. This means that NEWNAME becomes a new "hard link" to
OLDNAME.
See also `file-nlinks' in *Note File Attributes::.
- - Command: rename-file FILENAME NEWNAME &optional OK-IF-ALREADY-EXISTS
+ - Command: rename-file filename newname &optional ok-if-already-exists
This command renames the file FILENAME as NEWNAME.
If FILENAME has additional names aside from FILENAME, it continues
NEWNAME in the minibuffer; also, it requests confirmation if
NEWNAME already exists.
- - Command: copy-file OLDNAME NEWNAME &optional OK-IF-EXISTS TIME
+ - Command: copy-file oldname newname &optional ok-if-exists time
This command copies the file OLDNAME to NEWNAME. An error is
signaled if OLDNAME does not exist.
NEWNAME in the minibuffer; also, it requests confirmation if
NEWNAME already exists.
- - Command: delete-file FILENAME
+ - Command: delete-file filename
This command deletes the file FILENAME, like the shell command `rm
FILENAME'. If the file has multiple names, it continues to exist
under the other names.
See also `delete-directory' in *Note Create/Delete Dirs::.
- - Command: make-symbolic-link FILENAME NEWNAME &optional OK-IF-EXISTS
+ - Command: make-symbolic-link filename newname &optional ok-if-exists
This command makes a symbolic link to FILENAME, named NEWNAME.
This is like the shell command `ln -s FILENAME NEWNAME'.
NEWNAME in the minibuffer; also, it requests confirmation if
NEWNAME already exists.
- - Function: define-logical-name VARNAME STRING
+ - Function: define-logical-name varname string
This function defines the logical name NAME to have the value
STRING. It is available only on VMS.
- - Function: set-file-modes FILENAME MODE
+ - Function: set-file-modes filename mode
This function sets mode bits of FILENAME to MODE (which must be an
integer). Only the low 12 bits of MODE are used.
- - Function: set-default-file-modes MODE
+ - Function: set-default-file-modes mode
This function sets the default file protection for new files
created by XEmacs and its subprocesses. Every file created with
XEmacs initially has this protection. On Unix, the default
omits the version number. Version numbers are found mostly in
directory lists.
- - Function: file-name-directory FILENAME
+ - Function: file-name-directory filename
This function returns the directory part of FILENAME (or `nil' if
FILENAME does not include a directory part). On Unix, the
function returns a string ending in a slash. On VMS, it returns a
(file-name-directory "[X]FOO.TMP") ; VMS example
=> "[X]"
- - Function: file-name-nondirectory FILENAME
+ - Function: file-name-nondirectory filename
This function returns the nondirectory part of FILENAME.
(file-name-nondirectory "lewis/foo")
(file-name-nondirectory "[X]FOO.TMP")
=> "FOO.TMP"
- - Function: file-name-sans-versions FILENAME &optional
- KEEP-BACKUP-VERSION
+ - Function: file-name-sans-versions filename &optional
+ keep-backup-version
This function returns FILENAME without any file version numbers,
backup version numbers, or trailing tildes.
(file-name-sans-versions "foo;23")
=> "foo"
- - Function: file-name-sans-extension FILENAME
+ - Function: file-name-sans-extension filename
This function returns FILENAME minus its "extension," if any. The
extension, in a file name, is the part that starts with the last
`.' in the last name component. For example,
names. They do nothing special with environment variable substitutions
such as `$HOME', and the constructs `~', and `..'.
- - Function: file-name-as-directory FILENAME
+ - Function: file-name-as-directory filename
This function returns a string representing FILENAME in a form
that the operating system will interpret as the name of a
directory. In Unix, this means appending a slash to the string.
(file-name-as-directory "~rms/lewis")
=> "~rms/lewis/"
- - Function: directory-file-name DIRNAME
+ - Function: directory-file-name dirname
This function returns a string representing DIRNAME in a form that
the operating system will interpret as the name of a file. On
Unix, this means removing a final slash from the string. On VMS,
If you wish to convert a directory name to its abbreviation, use this
function:
- - Function: abbreviate-file-name DIRNAME &optional HACK-HOMEDIR
+ - Function: abbreviate-file-name dirname &optional hack-homedir
This function applies abbreviations from `directory-abbrev-alist'
to its argument, and substitutes `~' for the user's home directory.
name. On Unix, an absolute file name starts with a slash or a tilde
(`~'), and a relative one does not. The rules on VMS are complicated.
- - Function: file-name-absolute-p FILENAME
+ - Function: file-name-absolute-p filename
This function returns `t' if file FILENAME is an absolute file
name, `nil' otherwise. On VMS, this function understands both
Unix syntax and VMS syntax.
be expanded. Expansion also simplifies file names by eliminating
redundancies such as `./' and `NAME/../'.
- - Function: expand-file-name FILENAME &optional DIRECTORY
+ - Function: expand-file-name filename &optional directory
This function converts FILENAME to an absolute file name. If
DIRECTORY is supplied, it is the directory to start with if
FILENAME is relative. (The value of DIRECTORY should itself be an
`~/' at the beginning is expanded into the user's home directory.
A `/' or `~' following a `/'.
- Note that `expand-file-name' does *not* expand environment
+ Note that `expand-file-name' does _not_ expand environment
variables; only `substitute-in-file-name' does that.
- - Function: file-relative-name FILENAME &optional DIRECTORY
+ - Function: file-relative-name filename &optional directory
This function does the inverse of expansion--it tries to return a
relative name that is equivalent to FILENAME when interpreted
relative to DIRECTORY.
default-directory
=> "/user/lewis/manual/"
- - Function: substitute-in-file-name FILENAME
+ - Function: substitute-in-file-name filename
This function replaces environment variable references in FILENAME
with the environment variable values. Following standard Unix
shell syntax, `$' is the prefix to substitute an environment
Note that the `temp-directory' function does not exist under FSF
Emacs.
- - Function: make-temp-name PREFIX
+ - Function: make-temp-name prefix
This function generates a temporary file name starting with
PREFIX. The Emacs process number forms part of the result, so
there is no danger of generating a name being used by another
This section describes low-level subroutines for completing a file
name. For other completion functions, see *Note Completion::.
- - Function: file-name-all-completions PARTIAL-FILENAME DIRECTORY
+ - Function: file-name-all-completions partial-filename directory
This function returns a list of all possible completions for a file
whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
The order of the completions is the order of the files in the
(file-name-all-completions "fo" "")
=> ("foo")
- - Function: file-name-completion FILENAME DIRECTORY
+ - Function: file-name-completion filename directory
This function completes the file name FILENAME in directory
DIRECTORY. It returns the longest prefix common to all file names
in directory DIRECTORY that start with FILENAME.
This section describes low-level subroutines for completing a user
name. For other completion functions, see *Note Completion::.
- - Function: user-name-all-completions PARTIAL-USERNAME
+ - Function: user-name-all-completions partial-username
This function returns a list of all possible completions for a user
whose name starts with PARTIAL-USERNAME. The order of the
completions is unpredictable and conveys no useful information.
The argument PARTIAL-USERNAME must be a partial user name
containing no tilde character and no slash.
- - Function: user-name-completion USERNAME
+ - Function: user-name-completion username
This function completes the user name USERNAME. It returns the
longest prefix common to all user names that start with USERNAME.
function returns `t'. The function returns `nil' if no user name
starting with USERNAME exists.
- - Function: user-name-completion-1 USERNAME
+ - Function: user-name-completion-1 username
This function completes the user name USERNAME, like
`user-name-completion', differing only in the return value. This
function returns the cons of the completion returned by
latter case, it can optionally display information about each file,
depending on the value of switches passed to the `ls' command.
- - Function: directory-files DIRECTORY &optional FULL-NAME MATCH-REGEXP
- NOSORT FILES-ONLY
+ - Function: directory-files directory &optional full-name match-regexp
+ nosort files-only
This function returns a list of the names of the files in the
directory DIRECTORY. By default, the list is in alphabetical
order.
An error is signaled if DIRECTORY is not the name of a directory
that can be read.
- - Function: insert-directory FILE SWITCHES &optional WILDCARD
- FULL-DIRECTORY-P
+ - Function: insert-directory file switches &optional wildcard
+ full-directory-p
This function inserts (in the current buffer) a directory listing
for directory FILE, formatted with `ls' according to SWITCHES. It
leaves point after the inserted text.
with `delete-file'. These special functions exist to create and delete
directories.
- - Command: make-directory DIRNAME &optional PARENTS
+ - Command: make-directory dirname &optional parents
This function creates a directory named DIRNAME. Interactively,
the default choice of directory to create is the current default
directory for file names. That is useful when you have visited a
create parent directories if they don't exist. (Interactively, this
always happens.)
- - Command: delete-directory DIRNAME
+ - Command: delete-directory dirname
This function deletes the directory named DIRNAME. The function
`delete-file' does not work for files that are directories; you
must use `delete-directory' in that case.
- Variable: inhibit-file-name-operation
The operation for which certain handlers are presently inhibited.
- - Function: find-file-name-handler FILE OPERATION
+ - Function: find-file-name-handler file operation
This function returns the handler function for file name FILE, or
`nil' if there is none. The argument OPERATION should be the
operation to be performed on the file--the value you will pass to
the handler as its first argument when you call it. The operation
is needed for comparison with `inhibit-file-name-operation'.
- - Function: file-local-copy FILENAME
+ - Function: file-local-copy filename
This function copies file FILENAME to an ordinary non-magic file,
if it isn't one already.
If FILENAME is an ordinary file name, not magic, then this function
does nothing and returns `nil'.
- - Function: unhandled-file-name-directory FILENAME
+ - Function: unhandled-file-name-directory filename
This function returns the name of a directory that is not magic.
It uses the directory part of FILENAME if that is not magic.
Otherwise, it asks the handler what to do.
Creating a Partial File
-----------------------
- - Function: make-file-part &optional START END NAME BUFFER
+ - Function: make-file-part &optional start end name buffer
Make a file part on buffer BUFFER out of the region. Call it
NAME. This command creates a new buffer containing the contents
of the region and marks the buffer as referring to the specified
encoding functions for the formats listed in `buffer-file-format', in
the order of appearance in the list.
- - Function: format-write-file FILE FORMAT
+ - Function: format-write-file file format
This command writes the current buffer contents into the file FILE
in format FORMAT, and makes that format the default for future
saves of the buffer. The argument FORMAT is a list of format
names.
- - Function: format-find-file FILE FORMAT
+ - Function: format-find-file file format
This command finds the file FILE, converting it according to
format FORMAT. It also makes FORMAT the default if the buffer is
saved later.
`nil', no conversion takes place. Interactively, typing just
<RET> for FORMAT specifies `nil'.
- - Function: format-insert-file FILE FORMAT &optional BEG END
+ - Function: format-insert-file file format &optional beg end
This command inserts the contents of file FILE, converting it
according to format FORMAT. If BEG and END are non-`nil', they
specify which part of the file to read, as in
- `insert-file-contents' (*note Reading from Files::.).
+ `insert-file-contents' (*note Reading from Files::).
The return value is like what `insert-file-contents' returns: a
list of the absolute file name and the length of the data inserted
`nil', no conversion takes place. Interactively, typing just
<RET> for FORMAT specifies `nil'.
- - Function: format-find-file FILE FORMAT
+ - Function: format-find-file file format
This command finds the file FILE, converting it according to
format FORMAT. It also makes FORMAT the default if the buffer is
saved later.
`nil', no conversion takes place. Interactively, typing just
<RET> for FORMAT specifies `nil'.
- - Function: format-insert-file FILE FORMAT &optional BEG END
+ - Function: format-insert-file file format &optional beg end
This command inserts the contents of file FILE, converting it
according to format FORMAT. If BEG and END are non-`nil', they
specify which part of the file to read, as in
- `insert-file-contents' (*note Reading from Files::.).
+ `insert-file-contents' (*note Reading from Files::).
The return value is like what `insert-file-contents' returns: a
list of the absolute file name and the length of the data inserted
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
file type of the buffer's visited file. The value is `nil' for
text, `t' for binary.
- - Function: find-buffer-file-type FILENAME
+ - Function: find-buffer-file-type filename
This function determines whether file FILENAME is a text file or a
binary file. It returns `nil' for text, `t' for binary.
don't indicate anything in particular. Its value should be `nil'
for text, or `t' for binary.
- - Command: find-file-text FILENAME
+ - Command: find-file-text filename
Like `find-file', but treat the file as text regardless of its
name.
- - Command: find-file-binary FILENAME
+ - Command: find-file-binary filename
Like `find-file', but treat the file as binary regardless of its
name.
variables have the value 2, then the backups numbered 1 and 2 are kept
as old versions and those numbered 5 and 7 are kept as new versions;
backup version 3 is excess. The function `find-backup-file-name'
-(*note Backup Names::.) is responsible for determining which backup
+(*note Backup Names::) is responsible for determining which backup
versions to delete, but does not delete them itself.
- User Option: trim-versions-without-asking
customize the naming conventions for backup files by redefining them.
If you change one, you probably need to change the rest.
- - Function: backup-file-name-p FILENAME
+ - Function: backup-file-name-p filename
This function returns a non-`nil' value if FILENAME is a possible
name for a backup file. A file with the name FILENAME need not
exist; the function just checks the name.
(backup-file-name-p "foo")
=> nil
-
(backup-file-name-p "foo~")
=> 3
This simple expression is placed in a separate function to make it
easy to redefine for customization.
- - Function: make-backup-file-name FILENAME
+ - Function: make-backup-file-name filename
This function returns a string that is the name to use for a
non-numbered backup file for file FILENAME. On Unix, this is just
FILENAME with a tilde appended.
(defun make-backup-file-name (filename)
(concat "." filename "~"))
-
+
(make-backup-file-name "backups.texi")
=> ".backups.texi~"
- - Function: find-backup-file-name FILENAME
+ - Function: find-backup-file-name filename
This function computes the file name for a new backup file for
FILENAME. It may also propose certain existing backup files for
deletion. `find-backup-file-name' returns a list whose CAR is the
(find-backup-file-name "~rms/foo")
=> ("~rms/foo.~5~" "~rms/foo.~3~")
- - Function: file-newest-backup FILENAME
+ - Function: file-newest-backup filename
This function returns the name of the most recent backup file for
FILENAME, or `nil' if that file has no backup files.
buffer-auto-save-file-name
=> "/xcssun/users/rms/lewis/#files.texi#"
- - Command: auto-save-mode ARG
+ - Command: auto-save-mode arg
When used interactively without an argument, this command is a
toggle switch: it turns on auto-saving of the current buffer if it
is off, and vice-versa. With an argument ARG, the command turns
auto-saving on if the value of ARG is `t', a nonempty list, or a
positive integer. Otherwise, it turns auto-saving off.
- - Function: auto-save-file-name-p FILENAME
+ - Function: auto-save-file-name-p filename
This function returns a non-`nil' value if FILENAME is a string
that could be the name of an auto-save file. It works based on
knowledge of the naming convention for auto-save files: a name that
If this variable is non-`nil', buffers that are visiting files
have auto-saving enabled by default. Otherwise, they do not.
- - Command: do-auto-save &optional NO-MESSAGE CURRENT-ONLY
+ - Command: do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved.
It saves all buffers for which auto-saving is enabled and that
have been changed since the previous auto-save.
version of the file with the `revert-buffer' command. *Note Reverting
a Buffer: (emacs)Reverting.
- - Command: revert-buffer &optional CHECK-AUTO-SAVE NOCONFIRM
+ - Command: revert-buffer &optional check-auto-save noconfirm
This command replaces the buffer text with the text of the visited
file on disk. This action undoes all changes since the file was
visited or saved.
* Buffer File Name:: The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is "modified" if it needs to be saved.
* Modification Time:: Determining whether the visited file was changed
- "behind XEmacs's back".
+ ``behind XEmacs's back''.
* Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
* The Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
variables related to the display of buffers in windows, see *Note
Buffers and Windows::.
- - Function: bufferp OBJECT
+ - Function: bufferp object
This function returns `t' if OBJECT is a buffer, `nil' otherwise.
\1f
time, one of them is designated as the "current buffer". This is the
buffer in which most editing takes place, because most of the primitives
for examining or changing text in a buffer operate implicitly on the
-current buffer (*note Text::.). Normally the buffer that is displayed
-on the screen in the selected window is the current buffer, but this is
-not always so: a Lisp program can designate any buffer as current
+current buffer (*note Text::). Normally the buffer that is displayed on
+the screen in the selected window is the current buffer, but this is not
+always so: a Lisp program can designate any buffer as current
temporarily in order to operate on its contents, without changing what
is displayed on the screen.
(unless, of course, that is the subroutine's purpose). Therefore, you
should normally use `set-buffer' within a `save-excursion' that will
restore the current buffer when your function is done (*note
-Excursions::.). Here is an example, the code for the command
+Excursions::). Here is an example, the code for the command
`append-to-buffer' (with the documentation string abridged):
(defun append-to-buffer (buffer start end)
It is not reliable to change the current buffer back with
`set-buffer', because that won't do the job if a quit happens while the
-wrong buffer is current. Here is what *not* to do:
+wrong buffer is current. Here is what _not_ to do:
(let (buffer-read-only
(obuf (current-buffer)))
(current-buffer)
=> #<buffer buffers.texi>
- - Function: set-buffer BUFFER-OR-NAME
+ - Function: set-buffer buffer-or-name
This function makes BUFFER-OR-NAME the current buffer. It does
not display the buffer in the currently selected window or in any
other window, so the user cannot necessarily see the buffer. But
`buffer-menu' commands don't mention them. A name starting with space
also initially disables recording undo information; see *Note Undo::.
- - Function: buffer-name &optional BUFFER
+ - Function: buffer-name &optional buffer
This function returns the name of BUFFER as a string. If BUFFER
is not supplied, it defaults to the current buffer.
foo
=> #<killed buffer>
- - Command: rename-buffer NEWNAME &optional UNIQUE
+ - Command: rename-buffer newname &optional unique
This function renames the current buffer to NEWNAME. An error is
signaled if NEWNAME is not a string, or if there is already a
buffer with that name. The function returns `nil'.
to some other name, thus making it possible to create a second
shell buffer under the name `*shell*'.
- - Function: get-buffer BUFFER-OR-NAME
+ - Function: get-buffer buffer-or-name
This function returns the buffer specified by BUFFER-OR-NAME. If
BUFFER-OR-NAME is a string and there is no buffer with that name,
the value is `nil'. If BUFFER-OR-NAME is a buffer, it is returned
See also the function `get-buffer-create' in *Note Creating
Buffers::.
- - Function: generate-new-buffer-name STARTING-NAME &optional IGNORE
+ - Function: generate-new-buffer-name starting-name &optional ignore
This function returns a name that would be unique for a new
buffer--but does not create the buffer. It starts with
STARTING-NAME, and produces a name not currently in use for any
the buffer name are distinct and can be set independently. *Note
Visiting Files::.
- - Function: buffer-file-name &optional BUFFER
+ - Function: buffer-file-name &optional buffer
This function returns the absolute file name of the file that
BUFFER is visiting. If BUFFER is not visiting any file,
`buffer-file-name' returns `nil'. If BUFFER is not supplied, it
accessible on the system. See the function `file-attributes', in
*Note File Attributes::, for more information about them.
- - Function: get-file-buffer FILENAME
+ - Function: get-file-buffer filename
This function returns the buffer visiting file FILENAME. If there
is no such buffer, it returns `nil'. The argument FILENAME, which
- must be a string, is expanded (*note File Name Expansion::.), then
+ must be a string, is expanded (*note File Name Expansion::), then
compared against the visited file names of all live buffers.
(get-file-buffer "buffers.texi")
visiting the same file name. In such cases, this function returns
the first such buffer in the buffer list.
- - Command: set-visited-file-name FILENAME
+ - Command: set-visited-file-name filename
If FILENAME is a non-empty string, this function changes the name
of the file visited in current buffer to FILENAME. (If the buffer
- had no visited file, this gives it one.) The *next time* the
+ had no visited file, this gives it one.) The _next time_ the
buffer is saved it will go in the newly-specified file. This
command marks the buffer as modified, since it does not (as far as
XEmacs knows) match the contents of FILENAME, even if it matched
set to `t' whenever you alter the contents of the buffer, and cleared
to `nil' when you save it. Thus, the flag shows whether there are
unsaved changes. The flag value is normally shown in the modeline
-(*note Modeline Variables::.), and controls saving (*note Saving
-Buffers::.) and auto-saving (*note Auto-Saving::.).
+(*note Modeline Variables::), and controls saving (*note Saving
+Buffers::) and auto-saving (*note Auto-Saving::).
Some Lisp programs set the flag explicitly. For example, the
function `set-visited-file-name' sets the flag to `t', because the text
The functions that modify the contents of buffers are described in
*Note Text::.
- - Function: buffer-modified-p &optional BUFFER
+ - Function: buffer-modified-p &optional buffer
This function returns `t' if the buffer BUFFER has been modified
since it was last read in from a file or saved, or `nil'
otherwise. If BUFFER is not supplied, the current buffer is
tested.
- - Function: set-buffer-modified-p FLAG
+ - Function: set-buffer-modified-p flag
This function marks the current buffer as modified if FLAG is
non-`nil', or as unmodified if the flag is `nil'.
(set-buffer-modified-p (buffer-modified-p))
- - Command: not-modified &optional ARG
+ - Command: not-modified &optional arg
This command marks the current buffer as unmodified, and not
needing to be saved. (If ARG is non-`nil', the buffer is instead
marked as modified.) Don't use this function in programs, since it
prints a message in the echo area; use `set-buffer-modified-p'
(above) instead.
- - Function: buffer-modified-tick &optional BUFFER
+ - Function: buffer-modified-tick &optional buffer
This function returns BUFFER`s modification-count. This is a
counter that increments every time the buffer is modified. If
BUFFER is `nil' (or omitted), the current buffer is used.
XEmacs therefore checks the file's modification time using the functions
described below before saving the file.
- - Function: verify-visited-file-modtime BUFFER
+ - Function: verify-visited-file-modtime buffer
This function compares what BUFFER has recorded for the
modification time of its visited file against the actual
modification time of the file as recorded by the operating system.
format that `file-attributes' uses to return time values; see
*Note File Attributes::.)
- - Function: set-visited-file-modtime &optional TIME
+ - Function: set-visited-file-modtime &optional time
This function updates the buffer's record of the last modification
time of the visited file, to the value specified by TIME if TIME
is not `nil', and otherwise to the last modification time of the
normally, or if the file itself has been changed for some known
benign reason.
- - Function: ask-user-about-supersession-threat FILENAME
+ - Function: ask-user-about-supersession-threat filename
This function is used to ask a user how to proceed after an
attempt to modify an obsolete buffer visiting file FILENAME. An
"obsolete buffer" is an unmodified buffer for which the associated
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Note that the different buffer lists all contain the same elements.
It is only the order of those elements that is different.
- - Function: buffer-list &optional FRAME
+ - Function: buffer-list &optional frame
This function returns a list of all buffers, including those whose
names begin with a space. The elements are actual buffers, not
their names. The order of the list is specific to FRAME, which
This list is a copy of a list used inside XEmacs; modifying it has
no effect on the buffers.
- - Function: other-buffer &optional BUFFER-OR-NAME FRAME VISIBLE-OK
+ - Function: other-buffer &optional buffer-or-name frame visible-ok
This function returns the first buffer in the buffer list other
than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
(FRAME defaults to the current frame. If FRAME is `t', then the
VISIBLE-OK is the second argument instead of the third. FSF Emacs
19.
- - Command: list-buffers &optional FILES-ONLY
+ - Command: list-buffers &optional files-only
This function displays a listing of the names of existing buffers.
It clears the buffer `*Buffer List*', then inserts the listing
into that buffer and displays it in a window. `list-buffers' is
intended for interactive use, and is described fully in `The XEmacs
Reference Manual'. It returns `nil'.
- - Command: bury-buffer &optional BUFFER-OR-NAME
+ - Command: bury-buffer &optional buffer-or-name
This function puts BUFFER-OR-NAME at the end of the buffer list
without changing the order of any of the other buffers on the list.
This buffer therefore becomes the least desirable candidate for
buffer and gives it a unique name.
Other functions you can use to create buffers include
-`with-output-to-temp-buffer' (*note Temporary Displays::.) and
-`create-file-buffer' (*note Visiting Files::.). Starting a subprocess
-can also create a buffer (*note Processes::.).
+`with-output-to-temp-buffer' (*note Temporary Displays::) and
+`create-file-buffer' (*note Visiting Files::). Starting a subprocess
+can also create a buffer (*note Processes::).
- - Function: get-buffer-create NAME
+ - Function: get-buffer-create name
This function returns a buffer named NAME. It returns an existing
buffer with that name, if one exists; otherwise, it creates a new
buffer. The buffer does not become the current buffer--this
variable `default-major-mode' is handled at a higher level. *Note
Auto Major Mode::.
- - Function: generate-new-buffer NAME
+ - Function: generate-new-buffer name
This function returns a newly created, empty buffer, but does not
make it current. If there is no buffer named NAME, then that is
the name of the new buffer. If that name is in use, this function
buffer has been killed, you can either use this feature or the function
`buffer-live-p'.
- - Function: buffer-live-p BUFFER
+ - Function: buffer-live-p buffer
This function returns `nil' if BUFFER is deleted, and `t'
otherwise.
- - Command: kill-buffer BUFFER-OR-NAME
+ - Command: kill-buffer buffer-or-name
This function kills the buffer BUFFER-OR-NAME, freeing all its
memory for use as space for other buffers. (Emacs version 18 and
older was unable to return the memory to the operating system.)
Killing an indirect buffer has no effect on its base buffer. Killing
the base buffer kills all its indirect children.
- - Command: make-indirect-buffer BASE-BUFFER NAME
+ - Command: make-indirect-buffer base-buffer name
This creates an indirect buffer named NAME whose base buffer is
BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string.
(make-indirect-buffer "*scratch*" "indirect")
=> #<buffer "indirect">
- - Function: buffer-base-buffer &optional BUFFER
+ - Function: buffer-base-buffer &optional buffer
This function returns the base buffer of BUFFER. If BUFFER is not
indirect, the value is `nil'. Otherwise, the value is another
buffer, which is never an indirect buffer. If BUFFER is not
(buffer-base-buffer (get-buffer "indirect"))
=> #<buffer "*scratch*">
- - Function: buffer-indirect-children &optional BUFFER
+ - Function: buffer-indirect-children &optional buffer
This function returns a list of all indirect buffers whose base
buffer is BUFFER. If BUFFER is indirect, the return value will
always be nil; see `make-indirect-buffer'. If BUFFER is not
For practical purposes, a window exists only while it is displayed in
a frame. Once removed from the frame, the window is effectively deleted
-and should not be used, *even though there may still be references to
-it* from other Lisp objects. Restoring a saved window configuration is
+and should not be used, _even though there may still be references to
+it_ from other Lisp objects. Restoring a saved window configuration is
the only way for a window no longer on the screen to come back to life.
(*Note Deleting Windows::.)
*Note Display::, for information on how the contents of the window's
buffer are displayed in the window.
- - Function: windowp OBJECT
+ - Function: windowp object
This function returns `t' if OBJECT is a window.
\1f
The functions described here are the primitives used to split a
window into two windows. Two higher level functions sometimes split a
window, but not always: `pop-to-buffer' and `display-buffer' (*note
-Displaying Buffers::.).
+Displaying Buffers::).
The functions described here do not accept a buffer as an argument.
The two "halves" of the split window initially display the same buffer
previously visible in the window that was split.
- - Function: one-window-p &optional NO-MINI ALL-FRAMES
+ - Function: one-window-p &optional no-mini all-frames
This function returns non-`nil' if there is only one window. The
argument NO-MINI, if non-`nil', means don't count the minibuffer
even if it is active; otherwise, the minibuffer window is
WINDOW's frame are counted, excluding the minibuffer in use
if it lies in some other frame.
- - Command: split-window &optional WINDOW SIZE HORIZONTAL
+ - Command: split-window &optional window size horizontal
This function splits WINDOW into two windows. The original window
WINDOW remains the selected window, but occupies only part of its
former screen area. The rest is occupied by a newly created
=> #<window 8 on windows.texi>
(window-edges) ; Edges in order:
=> (0 0 80 50) ; left-top-right-bottom
-
+
;; Returns window created
(setq w2 (split-window w 15))
=> #<window 28 on windows.texi>
-
(window-edges w2)
=> (0 15 80 50) ; Bottom window;
; top is line 15
-
(window-edges w)
=> (0 0 80 15) ; Top window
The frame looks like this:
- __________
+ __________
| | line 0
| w |
|__________|
(setq w3 (split-window w 35 t))
=> #<window 32 on windows.texi>
-
(window-edges w3)
=> (35 0 80 15) ; Left edge at column 35
-
(window-edges w)
=> (0 0 35 15) ; Right edge at column 35
-
(window-edges w2)
=> (0 15 80 50) ; Bottom window unchanged
Now, the screen looks like this:
- column 35
+ column 35
__________
| | | line 0
| w | w3 |
or `|' characters. The display table can specify alternative
border characters; see *Note Display Tables::.
- - Command: split-window-vertically &optional SIZE
+ - Command: split-window-vertically &optional size
This function splits the selected window into two windows, one
above the other, leaving the selected window with SIZE lines.
(interactive "P")
(split-window nil (and arg (prefix-numeric-value arg))))
- - Command: split-window-horizontally &optional SIZE
+ - Command: split-window-horizontally &optional size
This function splits the selected window into two windows
side-by-side, leaving the selected window with SIZE columns.
(interactive "P")
(split-window nil (and arg (prefix-numeric-value arg)) t))
- - Function: one-window-p &optional NO-MINI ALL-FRAMES
+ - Function: one-window-p &optional no-mini all-frames
This function returns non-`nil' if there is only one window. The
argument NO-MINI, if non-`nil', means don't count the minibuffer
even if it is active; otherwise, the minibuffer window is
appear on the screen, but continues to exist as a Lisp object until
there are no references to it. There is no way to cancel the deletion
of a window aside from restoring a saved window configuration (*note
-Window Configurations::.). Restoring a window configuration also
+Window Configurations::). Restoring a window configuration also
deletes any windows that aren't part of that configuration.
When you delete a window, the space it took up is given to one
adjacent sibling. (In Emacs version 18, the space was divided evenly
among all the siblings.)
- - Function: window-live-p WINDOW
+ - Function: window-live-p window
This function returns `nil' if WINDOW is deleted, and `t'
otherwise.
*Warning:* Erroneous information or fatal errors may result from
using a deleted window as if it were live.
- - Command: delete-window &optional WINDOW
+ - Command: delete-window &optional window
This function removes WINDOW from the display. If WINDOW is
omitted, then the selected window is deleted. An error is signaled
if there is only one window when `delete-window' is called.
When `delete-window' is called interactively, WINDOW defaults to
the selected window.
- - Command: delete-other-windows &optional WINDOW
+ - Command: delete-other-windows &optional window
This function makes WINDOW the only window on its frame, by
deleting the other windows in that frame. If WINDOW is omitted or
`nil', then the selected window is used by default.
The result is `nil'.
- - Command: delete-windows-on BUFFER &optional FRAME
+ - Command: delete-windows-on buffer &optional frame
This function deletes all windows showing BUFFER. If there are no
windows showing BUFFER, it does nothing.
When a window is selected, the buffer in the window becomes the
current buffer, and the cursor will appear in it.
- - Function: selected-window &optional DEVICE
+ - Function: selected-window &optional device
This function returns the selected window. This is the window in
which the cursor appears and to which many commands apply. Each
separate device can have its own selected window, which is
argument DEVICE specifies which device to return the selected
window for, and defaults to the selected device.
- - Function: select-window WINDOW &optional NORECORD
+ - Function: select-window window &optional norecord
This function makes WINDOW the selected window. The cursor then
appears in WINDOW (on redisplay). The buffer being displayed in
WINDOW is immediately designated the current buffer.
(select-window w)
=> #<window 65 on windows.texi>
- - Macro: save-selected-window FORMS...
+ - Macro: save-selected-window forms...
This macro records the selected window, executes FORMS in
sequence, then restores the earlier selected window. It does not
save or restore anything about the sizes, arrangement or contents
The following functions choose one of the windows on the screen,
offering various criteria for the choice.
- - Function: get-lru-window &optional FRAME
+ - Function: get-lru-window &optional frame
This function returns the window least recently "used" (that is,
selected). The selected window is always the most recently used
window.
* If it is a frame, consider windows on that frame.
- - Function: get-largest-window &optional FRAME
+ - Function: get-largest-window &optional frame
This function returns the window with the largest area (height
times width). If there are no side-by-side windows, then this is
the window with the most lines. A minibuffer window is never a
In general, within each set of siblings at any level in the window tree,
the order is left to right, or top to bottom.
- - Function: next-window &optional WINDOW MINIBUF ALL-FRAMES
+ - Function: next-window &optional window minibuf all-frames
This function returns the window following WINDOW in the cyclic
ordering of windows. This is the window that `C-x o' would select
if typed when WINDOW is selected. If WINDOW is the only window
(next-window (next-window (selected-window)))
=> #<window 56 on windows.texi>
- - Function: previous-window &optional WINDOW MINIBUF ALL-FRAMES
+ - Function: previous-window &optional window minibuf all-frames
This function returns the window preceding WINDOW in the cyclic
ordering of windows. The other arguments specify which windows to
include in the cycle, as in `next-window'.
- - Command: other-window COUNT &optional FRAME
+ - Command: other-window count &optional frame
This function selects the COUNTth following window in the cyclic
order. If count is negative, then it selects the -COUNTth
preceding window. It returns `nil'.
* If it is any other value, then the behavior is undefined.
- - Function: walk-windows PROC &optional MINIBUF ALL-FRAMES
+ - Function: walk-windows proc &optional minibuf all-frames
This function cycles through all windows, calling `proc' once for
each window with the window as its sole argument.
to use than these, but they employ heuristics in choosing or creating a
window; use these functions when you need complete control.
- - Function: set-window-buffer WINDOW BUFFER-OR-NAME
+ - Function: set-window-buffer window buffer-or-name
This function makes WINDOW display BUFFER-OR-NAME as its contents.
It returns `nil'.
(set-window-buffer (selected-window) "foo")
=> nil
- - Function: window-buffer &optional WINDOW
+ - Function: window-buffer &optional window
This function returns the buffer that WINDOW is displaying. If
WINDOW is omitted, this function returns the buffer for the
selected window.
(window-buffer)
=> #<buffer windows.texi>
- - Function: get-buffer-window BUFFER-OR-NAME &optional FRAME
+ - Function: get-buffer-window buffer-or-name &optional frame
This function returns a window currently displaying
BUFFER-OR-NAME, or `nil' if there is none. If there are several
such windows, then the function returns the first one in the
current so that a Lisp program can access or modify it; they are too
drastic for that purpose, since they change the display of buffers in
windows, which is gratuitous and will surprise the user. Instead, use
-`set-buffer' (*note Current Buffer::.) and `save-excursion' (*note
-Excursions::.), which designate buffers as current for programmed
-access without affecting the display of buffers in windows.
+`set-buffer' (*note Current Buffer::) and `save-excursion' (*note
+Excursions::), which designate buffers as current for programmed access
+without affecting the display of buffers in windows.
- - Command: switch-to-buffer BUFFER-OR-NAME &optional NORECORD
+ - Command: switch-to-buffer buffer-or-name &optional norecord
This function makes BUFFER-OR-NAME the current buffer, and also
displays the buffer in the selected window. This means that a
human can see the buffer and subsequent keyboard commands will
the binding of `C-x b'. It is also used frequently in programs.
It always returns `nil'.
- - Command: switch-to-buffer-other-window BUFFER-OR-NAME
+ - Command: switch-to-buffer-other-window buffer-or-name
This function makes BUFFER-OR-NAME the current buffer and displays
it in a window not currently selected. It then selects that
window. The handling of the buffer is the same as in
already displaying the buffer, then it continues to do so, but
another window is nonetheless found to display it in as well.
- - Function: pop-to-buffer BUFFER-OR-NAME &optional OTHER-WINDOW
- ON-FRAME
+ - Function: pop-to-buffer buffer-or-name &optional other-window
+ on-frame
This function makes BUFFER-OR-NAME the current buffer and switches
to it in some window, preferably not the window previously
selected. The "popped-to" window becomes the selected window
An example use of this function is found at the end of *Note
Filter Functions::.
- - Command: replace-buffer-in-windows BUFFER
+ - Command: replace-buffer-in-windows buffer
This function replaces BUFFER with some other buffer in all
windows displaying it. The other buffer used is chosen with
`other-buffer'. In the usual applications of this function, you
and commands use this subroutine. Here we describe how to use
`display-buffer' and how to customize it.
- - Command: display-buffer BUFFER-OR-NAME &optional NOT-THIS-WINDOW
+ - Command: display-buffer buffer-or-name &optional not-this-window
This command makes BUFFER-OR-NAME appear in some window, like
`pop-to-buffer', but it does not select that window and does not
make the buffer current. The identity of the selected window is
XEmacs will not automatically change which buffer appears in the
window, such as `display-buffer' might normally do.
- - Function: window-dedicated-p WINDOW
+ - Function: window-dedicated-p window
This function returns WINDOW's dedicated object, usually `t' or
`nil'.
- - Function: set-window-buffer-dedicated WINDOW BUFFER
+ - Function: set-window-buffer-dedicated window buffer
This function makes WINDOW display BUFFER and be dedicated to that
buffer. Then XEmacs will not automatically change which buffer
appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
The default value of this variable is
`special-display-popup-frame'.
- - Function: special-display-popup-frame BUFFER
+ - Function: special-display-popup-frame buffer
This function makes BUFFER visible in a frame of its own. If
BUFFER is already displayed in a window in some frame, it makes
the frame visible and raises it, to use that window. Otherwise, it
A window can be marked as "dedicated" to its buffer. Then
`display-buffer' does not try to use that window.
- - Function: window-dedicated-p WINDOW
+ - Function: window-dedicated-p window
This function returns `t' if WINDOW is marked as dedicated;
otherwise `nil'.
- - Function: set-window-dedicated-p WINDOW FLAG
+ - Function: set-window-dedicated-p window flag
This function marks WINDOW as dedicated if FLAG is non-`nil', and
nondedicated otherwise.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.
- - Function: window-point WINDOW
+ - Function: window-point window
This function returns the current position of point in WINDOW.
For a nonselected window, this is the value point would have (in
that window's buffer) if that window were selected.
"top-level" value of point, outside of any `save-excursion' forms.
But that value is hard to find.
- - Function: set-window-point WINDOW POSITION
+ - Function: set-window-point window position
This function positions point in WINDOW at position POSITION in
WINDOW's buffer.
the upper left corner of the window. It is usually, but not
inevitably, at the beginning of a text line.
- - Function: window-start &optional WINDOW
+ - Function: window-start &optional window
This function returns the display-start position of window WINDOW.
If WINDOW is `nil', the selected window is used. For example,
For a realistic example, see the description of `count-lines' in
*Note Text Lines::.
- - Function: window-end &optional WINDOW
+ - Function: window-end &optional window
This function returns the position of the end of the display in
window WINDOW. If WINDOW is `nil', the selected window is used.
correct. In a future version, `window-end' will return `nil' in
that case.
- - Function: set-window-start WINDOW POSITION &optional NOFORCE
+ - Function: set-window-start window position &optional noforce
This function sets the display-start position of WINDOW to
POSITION in WINDOW's buffer. It returns POSITION.
at the next redisplay, then redisplay computes a new window-start
position that works well with point, and thus POSITION is not used.
- - Function: pos-visible-in-window-p &optional POSITION WINDOW
+ - Function: pos-visible-in-window-p &optional position window
This function returns `t' if POSITION is within the range of text
currently visible on the screen in WINDOW. It returns `nil' if
POSITION is scrolled vertically out of view. The argument
unpredictable results if the current buffer is different from the buffer
that is displayed in the selected window. *Note Current Buffer::.
- - Command: scroll-up &optional COUNT
+ - Command: scroll-up &optional count
This function scrolls the text in the selected window upward COUNT
lines. If COUNT is negative, scrolling is actually downward.
`scroll-up' returns `nil'.
- - Command: scroll-down &optional COUNT
+ - Command: scroll-down &optional count
This function scrolls the text in the selected window downward
COUNT lines. If COUNT is negative, scrolling is actually upward.
`scroll-down' returns `nil'.
- - Command: scroll-other-window &optional COUNT
+ - Command: scroll-other-window &optional count
This function scrolls the text in another window upward COUNT
lines. Negative values of COUNT, or `nil', are handled as in
`scroll-up'.
bottom of the window appear instead at the top. The default value
is `2'.
- - Command: recenter &optional COUNT
+ - Command: recenter &optional count
This function scrolls the selected window to put the text where
point is located at a specified vertical position within the
window.
to how far left you can scroll, but eventually all the text will
disappear off the left edge.
- - Command: scroll-left COUNT
+ - Command: scroll-left count
This function scrolls the selected window COUNT columns to the
left (or to the right if COUNT is negative). The return value is
the total amount of leftward horizontal scrolling in effect after
the change--just like the value returned by `window-hscroll'
(below).
- - Command: scroll-right COUNT
+ - Command: scroll-right count
This function scrolls the selected window COUNT columns to the
right (or to the left if COUNT is negative). The return value is
the total amount of leftward horizontal scrolling in effect after
normal position where the total leftward scrolling is zero,
attempts to scroll any farther right have no effect.
- - Function: window-hscroll &optional WINDOW
+ - Function: window-hscroll &optional window
This function returns the total leftward horizontal scrolling of
WINDOW--the number of columns by which the text in WINDOW is
scrolled left past the left margin.
(window-hscroll)
=> 5
- - Function: set-window-hscroll WINDOW COLUMNS
+ - Function: set-window-hscroll window columns
This function sets the number of columns from the left margin that
WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS
should be zero or positive; if not, it is taken as zero.
The following functions return size information about a window:
- - Function: window-height &optional WINDOW
+ - Function: window-height &optional window
This function returns the number of lines in WINDOW, including its
modeline but not including the horizontal scrollbar, if any (this
is different from `window-pixel-height'). If WINDOW is `nil', the
(window-height)
=> 20
- - Function: window-width &optional WINDOW
+ - Function: window-width &optional window
This function returns the number of columns in WINDOW, not
including any left margin, right margin, or vertical scrollbar
(this is different from `window-pixel-width'). If WINDOW is
not for full-frame windows. You can change this using the variables
`truncate-lines' and `truncate-partial-width-windows'.)
- - Function: window-pixel-height &optional WINDOW
+ - Function: window-pixel-height &optional window
This function returns the height of WINDOW in pixels, including
its modeline and horizontal scrollbar, if any. If WINDOW is
`nil', the function uses the selected window.
(window-pixel-height)
=> 300
- - Function: window-pixel-width &optional WINDOW
+ - Function: window-pixel-width &optional window
This function returns the width of WINDOW in pixels, including any
left margin, right margin, or vertical scrollbar that may be
displayed alongside it. If WINDOW is `nil', the function uses the
(window-pixel-height)
=> 600
- - Function: window-text-area-pixel-height &optional WINDOW
+ - Function: window-text-area-pixel-height &optional window
This function returns the height in pixels of the text displaying
portion of WINDOW, which defaults to the selected window. Unlike
`window-pixel-height', the space occupied by the modeline and
horizontal scrollbar, if any, is not counted.
- - Function: window-text-area-pixel-width &optional WINDOW
+ - Function: window-text-area-pixel-width &optional window
This function returns the width in pixels of the text displaying
portion of WINDOW, which defaults to the selected window. Unlike
`window-pixel-width', the space occupied by the vertical scrollbar
and divider, if any, is not counted.
- - Function: window-displayed-text-pixel-height &optional WINDOW
- NOCLIPPED
+ - Function: window-displayed-text-pixel-height &optional window
+ noclipped
This function returns the height in pixels of the text displayed in
WINDOW, which defaults to the selected window. Unlike
`window-text-area-pixel-height', any blank space below the end of
windows within a frame, and the relative location of a window in
comparison to other windows in the same frame.
- - Function: window-pixel-edges &optional WINDOW
+ - Function: window-pixel-edges &optional window
This function returns a list of the pixel edge coordinates of
WINDOW. If WINDOW is `nil', the selected window is used.
make sense in a world with variable-width and variable-height lines, as
are allowed in XEmacs.
- - Function: window-highest-p WINDOW
+ - Function: window-highest-p window
This function returns non-`nil' if WINDOW is along the top of its
frame.
- - Function: window-lowest-p WINDOW
+ - Function: window-lowest-p window
This function returns non-`nil' if WINDOW is along the bottom of
its frame.
- - Function: window-text-area-pixel-edges &optional WINDOW
+ - Function: window-text-area-pixel-edges &optional window
This function allows one to determine the location of the
text-displaying portion of WINDOW, which defaults to the selected
window, with respect to the top left corner of the window. It
window size. XEmacs does not permit overlapping windows or gaps between
windows, so resizing one window affects other windows.
- - Command: enlarge-window SIZE &optional HORIZONTAL WINDOW
+ - Command: enlarge-window size &optional horizontal window
This function makes the selected window SIZE lines taller,
stealing lines from neighboring windows. It takes the lines from
one window at a time until that window is used up, then takes from
`enlarge-window' returns `nil'.
- - Command: enlarge-window-horizontally COLUMNS
+ - Command: enlarge-window-horizontally columns
This function makes the selected window COLUMNS wider. It could
be defined as follows:
(defun enlarge-window-horizontally (columns)
(enlarge-window columns t))
- - Command: enlarge-window-pixels COUNT &optional SIDE WINDOW
+ - Command: enlarge-window-pixels count &optional side window
This function makes the selected window COUNT pixels larger. When
called from Lisp, optional second argument SIDE non-`nil' means to
grow sideways COUNT pixels, and optional third argument WINDOW
specifies the window to change instead of the selected window.
- - Command: shrink-window SIZE &optional HORIZONTAL WINDOW
+ - Command: shrink-window size &optional horizontal window
This function is like `enlarge-window' but negates the argument
SIZE, making the selected window smaller by giving lines (or
columns) to the other windows. If the window shrinks below
If WINDOW is non-`nil', it specifies a window to change instead of
the selected window.
- - Command: shrink-window-horizontally COLUMNS
+ - Command: shrink-window-horizontally columns
This function makes the selected window COLUMNS narrower. It
could be defined as follows:
(defun shrink-window-horizontally (columns)
(shrink-window columns t))
- - Command: shrink-window-pixels COUNT &optional SIDE WINDOW
+ - Command: shrink-window-pixels count &optional side window
This function makes the selected window COUNT pixels smaller.
When called from Lisp, optional second argument SIDE non-`nil'
means to shrink sideways COUNT pixels, and optional third argument
the positions of point and the mark. An exception is made for
point in the current buffer, whose value is not saved.
- - Function: set-window-configuration CONFIGURATION
+ - Function: set-window-configuration configuration
This function restores the configuration of XEmacs's windows and
buffers to the state specified by CONFIGURATION. The argument
CONFIGURATION must be a value that was previously returned by
...)
(set-window-configuration config)))
- - Special Form: save-window-excursion FORMS...
+ - Special Form: save-window-excursion forms...
This special form records the window configuration, executes FORMS
in sequence, then restores the earlier window configuration. The
window configuration includes the value of point and the portion
=> do-something
;; The frame is now split again.
- - Function: window-configuration-p OBJECT
+ - Function: window-configuration-p object
This function returns `t' if OBJECT is a window configuration.
Primitives to look inside of window configurations would make sense,
display multiple X window frames at the same time, each in its own X
window.
- - Function: framep OBJECT
+ - Function: framep object
This predicate returns `t' if OBJECT is a frame, and `nil'
otherwise.
To create a new frame, call the function `make-frame'.
- - Function: make-frame &optional PROPS DEVICE
+ - Function: make-frame &optional props device
This function creates a new frame on DEVICE, if DEVICE permits
creation of frames. (An X server does; an ordinary terminal does
not (yet).) DEVICE defaults to the selected device if omitted.
These functions let you read and change the properties of a frame.
- - Function: frame-properties &optional FRAME
+ - Function: frame-properties &optional frame
This function returns a plist listing all the properties of FRAME
and their values.
- - Function: frame-property FRAME PROPERTY &optional DEFAULT
+ - Function: frame-property frame property &optional default
This function returns FRAME's value for the property PROPERTY.
- - Function: set-frame-properties FRAME PLIST
+ - Function: set-frame-properties frame plist
This function alters the properties of frame FRAME based on the
elements of property list PLIST. If you don't mention a property
in PLIST, its value doesn't change.
- - Function: set-frame-property FRAME PROP VAL
+ - Function: set-frame-property frame prop val
This function sets the property PROP of frame FRAME to the value
VAL.
then POS is positive!
`icon-left'
- The screen position of the left edge *of the frame's icon*, in
+ The screen position of the left edge _of the frame's icon_, in
pixels, counting from the left edge of the screen. This takes
effect if and when the frame is iconified.
`icon-top'
- The screen position of the top edge *of the frame's icon*, in
+ The screen position of the top edge _of the frame's icon_, in
pixels, counting from the top edge of the screen. This takes
effect if and when the frame is iconified.
Here are some special features for working with sizes and positions:
- - Function: set-frame-position FRAME LEFT TOP
+ - Function: set-frame-position frame left top
This function sets the position of the top left corner of FRAME to
LEFT and TOP. These arguments are measured in pixels, and count
from the top left corner of the screen. Negative property values
count up or rightward from the top left corner of the screen.
- - Function: frame-height &optional FRAME
- - Function: frame-width &optional FRAME
+ - Function: frame-height &optional frame
+ - Function: frame-width &optional frame
These functions return the height and width of FRAME, measured in
lines and columns. If you don't supply FRAME, they use the
selected frame.
- - Function: frame-pixel-height &optional FRAME
- - Function: frame-pixel-width &optional FRAME
+ - Function: frame-pixel-height &optional frame
+ - Function: frame-pixel-width &optional frame
These functions return the height and width of FRAME, measured in
pixels. If you don't supply FRAME, they use the selected frame.
- - Function: set-frame-size FRAME COLS ROWS &optional PRETEND
+ - Function: set-frame-size frame cols rows &optional pretend
This function sets the size of FRAME, measured in characters; COLS
and ROWS specify the new width and height. (If PRETEND is
non-nil, it means that redisplay should act as if the frame's size
not normally change over the lifetime of a frame. It is perfectly
allowable, and quite common, for multiple frames to have the same name.
- - Function: frame-name &optional FRAME
+ - Function: frame-name &optional frame
This function returns the name of FRAME, which defaults to the
selected frame if not specified. The name of a frame can also be
obtained from the frame's properties. *Note Frame Properties::.
frame, when you have not explicitly specified the frame title.
This title appears in the icon itself.
- - Function: x-set-frame-icon-pixmap FRAME PIXMAP &optional MASK
+ - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
This function sets the icon of the given frame to the given image
instance, which should be an image instance object (as returned by
`make-image-instance'), a glyph object (as returned by
them. A deleted frame cannot appear on the screen, but continues to
exist as a Lisp object until there are no references to it.
- - Command: delete-frame &optional FRAME
+ - Command: delete-frame &optional frame
This function deletes the frame FRAME. By default, FRAME is the
selected frame.
- - Function: frame-live-p FRAME
+ - Function: frame-live-p frame
The function `frame-live-p' returns non-`nil' if the frame FRAME
has not been deleted.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
buffers. The list that you get is newly created, so modifying the
list doesn't have any effect on the internals of XEmacs.
- - Function: device-frame-list &optional DEVICE
+ - Function: device-frame-list &optional device
This function returns a list of all frames on DEVICE. If DEVICE
is `nil', the selected device will be used.
- - Function: visible-frame-list &optional DEVICE
+ - Function: visible-frame-list &optional device
This function returns a list of just the currently visible frames.
If DEVICE is specified only frames on that device will be returned.
*Note Visibility of Frames::. (TTY frames always count as
"visible", even though only the selected one is actually
displayed.)
- - Function: next-frame &optional FRAME MINIBUF
+ - Function: next-frame &optional frame minibuf
The function `next-frame' lets you cycle conveniently through all
the frames from an arbitrary starting point. It returns the "next"
frame after FRAME in the cycle. If FRAME is omitted or `nil', it
anything else
Consider all frames.
- - Function: previous-frame &optional FRAME MINIBUF
+ - Function: previous-frame &optional frame minibuf
Like `next-frame', but cycles through all frames in the opposite
direction.
Each window is part of one and only one frame; you can get the frame
with `window-frame'.
- - Function: frame-root-window &optional FRAME
+ - Function: frame-root-window &optional frame
This returns the root window of frame FRAME. FRAME defaults to
the selected frame if not specified.
- - Function: window-frame &optional WINDOW
+ - Function: window-frame &optional window
This function returns the frame that WINDOW is on. WINDOW
defaults to the selected window if omitted.
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.
- - Function: frame-top-window FRAME
+ - Function: frame-top-window frame
This returns the topmost, leftmost window of frame FRAME.
At any time, exactly one window on any frame is "selected within the
frame also selects this window. You can get the frame's current
selected window with `frame-selected-window'.
- - Function: frame-selected-window &optional FRAME
+ - Function: frame-selected-window &optional frame
This function returns the window on FRAME that is selected within
FRAME. FRAME defaults to the selected frame if not specified.
Normally, each frame has its own minibuffer window at the bottom,
which is used whenever that frame is selected. If the frame has a
minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
-Misc::.).
+Misc::).
However, you can also create a frame with no minibuffer. Such a
frame must use the minibuffer window of some other frame. When you
moves from device to device, the selected frame on each device is
remembered and restored when the focus moves back to that device.
- - Function: selected-frame &optional DEVICE
+ - Function: selected-frame &optional device
This function returns the selected frame on DEVICE. If DEVICE is
not specified, the selected device will be used. If no frames
exist on the device, `nil' is returned.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
-`XEmacs' (*note Modeline Variables::.).
+`XEmacs' (*note Modeline Variables::).
- - Function: select-frame FRAME
+ - Function: select-frame frame
This function selects frame FRAME, temporarily disregarding the
focus of the X server if any. The selection of FRAME lasts until
the next time the user does something to select a different frame,
`set-buffer'. In order to effect a permanent focus change use
`focus-frame'.
- - Function: focus-frame FRAME
+ - Function: focus-frame frame
This function selects FRAME and gives it the window system focus.
The operation of `focus-frame' is not affected by the value of
`focus-follows-mouse'.
- - Macro: save-selected-frame FORMS...
+ - Macro: save-selected-frame forms...
This macro records the selected frame, executes FORMS in sequence,
then restores the earlier selected frame. The value returned is
the value of the last form.
- - Macro: with-selected-frame FRAME FORMS...
+ - Macro: with-selected-frame frame forms...
This macro records the selected frame, then selects FRAME and
executes FORMS in sequence. After the last form is finished, the
earlier selected frame is restored. The value returned is the
Visibility is meaningless for TTY frames, since only the selected
one is actually displayed in any case.
- - Command: make-frame-visible &optional FRAME
+ - Command: make-frame-visible &optional frame
This function makes frame FRAME visible. If you omit FRAME, it
makes the selected frame visible.
- - Command: make-frame-invisible &optional FRAME
+ - Command: make-frame-invisible &optional frame
This function makes frame FRAME invisible.
- - Command: iconify-frame &optional FRAME
+ - Command: iconify-frame &optional frame
This function iconifies frame FRAME.
- - Command: deiconify-frame &optional FRAME
+ - Command: deiconify-frame &optional frame
This function de-iconifies frame FRAME. Under X, this is
equivalent to `make-frame-visible'.
- - Function: frame-visible-p FRAME
+ - Function: frame-visible-p frame
This returns whether FRAME is currently "visible" (actually in use
for display). A frame that is not visible is not updated, and, if
it works through a window system, may not show at all.
- - Function: frame-iconified-p FRAME
+ - Function: frame-iconified-p frame
This returns whether FRAME is iconified. Not all window managers
use icons; some merely unmap the window, so this function is not
the inverse of `frame-visible-p'. It is possible for a frame to
functionality of this function is obtained through
`frame-visible-p'.)
- - Function: frame-totally-visible-p FRAME
+ - Function: frame-totally-visible-p frame
This returns whether FRAME is not obscured by any other X windows.
On TTY frames, this is the same as `frame-visible-p'.
You can raise and lower XEmacs's X windows with these functions:
- - Command: raise-frame &optional FRAME
+ - Command: raise-frame &optional frame
This function raises frame FRAME.
- - Command: lower-frame &optional FRAME
+ - Command: lower-frame &optional frame
This function lowers frame FRAME.
You can also specify auto-raise (raising automatically when a frame
Auto-raising and auto-lowering is implemented through functions
attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
-Hooks::.). Under normal circumstances, you should not call these
+Hooks::). Under normal circumstances, you should not call these
functions directly.
- Function: default-select-frame-hook
This function returns a frame configuration list that describes
the current arrangement of frames and their contents.
- - Function: set-frame-configuration CONFIGURATION
+ - Function: set-frame-configuration configuration
This function restores the state of frames described in
CONFIGURATION.
- Variable: select-frame-hook
This is a normal hook that is run just after a frame is selected.
The function `default-select-frame-hook', which implements
- auto-raising (*note Raising and Lowering::.), is normally attached
+ auto-raising (*note Raising and Lowering::), is normally attached
to this hook.
Note that calling `select-frame' does not necessarily set the
This is a normal hook that is run just before a frame is deselected
(and another frame is selected). The function
`default-deselect-frame-hook', which implements auto-lowering
- (*note Raising and Lowering::.), is normally attached to this hook.
+ (*note Raising and Lowering::), is normally attached to this hook.
- Variable: map-frame-hook
This hook is called each time a frame is mapped (i.e. made
specifying which device the function pertains to. If the argument is
omitted, it defaults to the selected device (see below).
- - Function: consolep OBJECT
+ - Function: consolep object
This returns non-`nil' if OBJECT is a console.
- - Function: devicep OBJECT
+ - Function: devicep object
This returns non-`nil' if OBJECT is a device.
* Menu:
- Function: console-list
This function returns a list of all existing consoles.
- - Function: console-device-list &optional CONSOLE
+ - Function: console-device-list &optional console
This function returns a list of all devices on CONSOLE. If
CONSOLE is `nil', the selected console will be used.
- Function: device-list
This function returns a list of all existing devices.
- - Function: device-or-frame-p OBJECT
+ - Function: device-or-frame-p object
This function returns non-`nil' if OBJECT is a device or frame.
This function is useful because devices and frames are similar in
many respects and many functions can operate on either one.
- - Function: device-frame-list DEVICE
+ - Function: device-frame-list device
This function returns a list of all frames on DEVICE.
- - Function: frame-device FRAME
+ - Function: frame-device frame
This function returns the device that FRAME is on.
\1f
`mono'
A device that can only display two colors (e.g. black and white).
- - Function: device-type DEVICE
+ - Function: device-type device
This function returns the type of DEVICE. This is a symbol whose
name is one of the device types mentioned above.
- - Function: device-or-frame-type DEVICE-OR-FRAME
+ - Function: device-or-frame-type device-or-frame
This function returns the type of DEVICE-OR-FRAME.
- - Function: device-class DEVICE
+ - Function: device-class device
This function returns the class (color behavior) of DEVICE. This
is a symbol whose name is one of the device classes mentioned
above.
- - Function: valid-device-type-p DEVICE-TYPE
+ - Function: valid-device-type-p device-type
This function returns whether DEVICE-TYPE (which should be a
symbol) species a valid device type.
- - Function: valid-device-class-p DEVICE-CLASS
+ - Function: valid-device-class-p device-class
This function returns whether DEVICE-CLASS (which should be a
symbol) species a valid device class.
Connecting to a Console or Device
=================================
- - Function: make-device &optional TYPE DEVICE-DATA
+ - Function: make-device &optional type device-data
This function creates a new device.
The following two functions create devices of specific types and are
written in terms of `make-device'.
- - Function: make-tty-device &optional TTY TERMINAL-TYPE
+ - Function: make-tty-device &optional tty terminal-type
This function creates a new tty device on TTY. This also creates
the tty's first frame. TTY should be a string giving the name of
a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
If it is `nil', the terminal type will be inferred from the
`TERM' environment variable.
- - Function: make-x-device &optional DISPLAY ARGV-LIST
+ - Function: make-x-device &optional display argv-list
This function creates a new device connected to DISPLAY. Optional
argument ARGV-LIST is a list of strings describing command line
options.
- - Function: delete-device DEVICE
+ - Function: delete-device device
This function deletes DEVICE, permanently eliminating it from use.
This disconnects XEmacs's connection to the device.
This variable, if non-`nil', should contain a list of functions,
which are called when a device is deleted.
- - Function: console-live-p OBJECT
+ - Function: console-live-p object
This function returns non-`nil' if OBJECT is a console that has
not been deleted.
- - Function: device-live-p OBJECT
+ - Function: device-live-p object
This function returns non-`nil' if OBJECT is a device that has not
been deleted.
- - Function: device-x-display DEVICE
+ - Function: device-x-display device
This function returns the X display which DEVICE is connected to,
if DEVICE is an X device.
The Selected Console and Device
===============================
- - Function: select-console CONSOLE
+ - Function: select-console console
This function selects the console CONSOLE. Subsequent editing
commands apply to its selected device, selected frame, and selected
window. The selection of CONSOLE lasts until the next time the
- Function: selected-console
This function returns the console which is currently active.
- - Function: select-device DEVICE
+ - Function: select-device device
This function selects the device DEVICE.
- - Function: selected-device &optional CONSOLE
+ - Function: selected-device &optional console
This function returns the device which is currently active. If
optional CONSOLE is non-`nil', this function returns the device
that would be currently active if CONSOLE were the selected
Console and Device I/O
======================
- - Function: console-disable-input CONSOLE
+ - Function: console-disable-input console
This function disables input on console CONSOLE.
- - Function: console-enable-input CONSOLE
+ - Function: console-enable-input console
This function enables input on console CONSOLE.
Each device has a "baud rate" value associated with it. On most
systems, changing this value will affect the amount of padding and
other strategic decisions made during redisplay.
- - Function: device-baud-rate &optional DEVICE
+ - Function: device-baud-rate &optional device
This function returns the output baud rate of DEVICE.
- - Function: set-device-baud-rate DEVICE RATE
+ - Function: set-device-baud-rate device rate
This function sets the output baud rate of DEVICE to RATE.
\1f
the character on which the cursor sits.
The value of point is a number between 1 and the buffer size plus 1.
-If narrowing is in effect (*note Narrowing::.), then point is
-constrained to fall within the accessible portion of the buffer
-(possibly at one end of it).
+If narrowing is in effect (*note Narrowing::), then point is constrained
+to fall within the accessible portion of the buffer (possibly at one end
+of it).
Each buffer has its own value of point, which is independent of the
value of point in other buffers. Each window also has a value of point,
so the distinction is rarely important. *Note Window Point::, for more
details.
- - Function: point &optional BUFFER
+ - Function: point &optional buffer
This function returns the value of point in BUFFER, as an integer.
BUFFER defaults to the current buffer if omitted.
(point)
=> 175
- - Function: point-min &optional BUFFER
+ - Function: point-min &optional buffer
This function returns the minimum accessible value of point in
BUFFER. This is normally 1, but if narrowing is in effect, it is
the position of the start of the region that you narrowed to.
(*Note Narrowing::.) BUFFER defaults to the current buffer if
omitted.
- - Function: point-max &optional BUFFER
+ - Function: point-max &optional buffer
This function returns the maximum accessible value of point in
BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
in effect, in which case it is the position of the end of the
- region that you narrowed to. (*note Narrowing::.). BUFFER
- defaults to the current buffer if omitted.
+ region that you narrowed to. (*note Narrowing::). BUFFER defaults
+ to the current buffer if omitted.
- - Function: buffer-end FLAG &optional BUFFER
+ - Function: buffer-end flag &optional buffer
This function returns `(point-min buffer)' if FLAG is less than 1,
`(point-max buffer)' otherwise. The argument FLAG must be a
number. BUFFER defaults to the current buffer if omitted.
- - Function: buffer-size &optional BUFFER
+ - Function: buffer-size &optional buffer
This function returns the total number of characters in BUFFER.
- In the absence of any narrowing (*note Narrowing::.), `point-max'
+ In the absence of any narrowing (*note Narrowing::), `point-max'
returns a value one larger than this. BUFFER defaults to the
current buffer if omitted.
These functions move point based on a count of characters.
`goto-char' is the fundamental primitive; the other functions use that.
- - Command: goto-char POSITION &optional BUFFER
+ - Command: goto-char position &optional buffer
This function sets point in `buffer' to the value POSITION. If
POSITION is less than 1, it moves point to the beginning of the
buffer. If POSITION is greater than the length of the buffer, it
`goto-char' returns POSITION.
- - Command: forward-char &optional COUNT BUFFER
+ - Command: forward-char &optional count buffer
This function moves point COUNT characters forward, towards the
end of the buffer (or backward, towards the beginning of the
buffer, if COUNT is negative). If the function attempts to move
In an interactive call, COUNT is the numeric prefix argument.
- - Command: backward-char &optional COUNT BUFFER
+ - Command: backward-char &optional count buffer
This function moves point COUNT characters backward, towards the
beginning of the buffer (or forward, towards the end of the
buffer, if COUNT is negative). If the function attempts to move
These functions for parsing words use the syntax table to decide
whether a given character is part of a word. *Note Syntax Tables::.
- - Command: forward-word COUNT &optional BUFFER
+ - Command: forward-word count &optional buffer
This function moves point forward COUNT words (or backward if
COUNT is negative). Normally it returns `t'. If this motion
encounters the beginning or end of the buffer, or the limits of the
In an interactive call, COUNT is set to the numeric prefix
argument.
- - Command: backward-word COUNT &optional BUFFER
+ - Command: backward-word count &optional buffer
This function is just like `forward-word', except that it moves
backward until encountering the front of a word, rather than
forward. BUFFER defaults to the current buffer if omitted.
documented here to warn you not to use them in Lisp programs, because
they set the mark and display messages in the echo area.
- - Command: beginning-of-buffer &optional N
+ - Command: beginning-of-buffer &optional n
This function moves point to the beginning of the buffer (or the
limits of the accessible portion, when narrowing is in effect),
setting the mark at the previous position. If N is non-`nil',
Don't use this function in Lisp programs!
- - Command: end-of-buffer &optional N
+ - Command: end-of-buffer &optional n
This function moves point to the end of the buffer (or the limits
of the accessible portion, when narrowing is in effect), setting
the mark at the previous position. If N is non-`nil', then it puts
the width of the window, by line continuation in display, or by how
tabs and control characters are displayed.
- - Command: goto-line LINE
+ - Command: goto-line line
This function moves point to the front of the LINEth line,
counting from line 1 at beginning of the buffer. If LINE is less
than 1, it moves point to the beginning of the buffer. If LINE is
greater than the number of lines in the buffer, it moves point to
- the end of the buffer--that is, the *end of the last line* of the
+ the end of the buffer--that is, the _end of the last line_ of the
buffer. This is the only case in which `goto-line' does not
necessarily move to the beginning of a line.
In an interactive call, LINE is the numeric prefix argument if one
has been provided. Otherwise LINE is read in the minibuffer.
- - Command: beginning-of-line &optional COUNT BUFFER
+ - Command: beginning-of-line &optional count buffer
This function moves point to the beginning of the current line.
With an argument COUNT not `nil' or 1, it moves forward COUNT-1
lines and then to the beginning of the line. BUFFER defaults to
accessible portion, if narrowing is in effect), it positions point
there. No error is signaled.
- - Command: end-of-line &optional COUNT BUFFER
+ - Command: end-of-line &optional count buffer
This function moves point to the end of the current line. With an
argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
then to the end of the line. BUFFER defaults to the current
accessible portion, if narrowing is in effect), it positions point
there. No error is signaled.
- - Command: forward-line &optional COUNT BUFFER
+ - Command: forward-line &optional count buffer
This function moves point forward COUNT lines, to the beginning of
the line. If COUNT is negative, it moves point -COUNT lines
backward, to the beginning of a line. If COUNT is zero, it moves
In an interactive call, COUNT is the numeric prefix argument.
- - Function: count-lines START END
+ - Function: count-lines start end
This function returns the number of lines between the positions
START and END in the current buffer. If START and END are equal,
then it returns 0. Otherwise it returns at least 1, even if START
use them heavily, Emacs provides caches which may improve the
performance of your code. *Note cache-long-line-scans: Text Lines.
- - Function: vertical-motion COUNT &optional WINDOW PIXELS
+ - Function: vertical-motion count &optional window pixels
This function moves point to the start of the frame line COUNT
frame lines down from the frame line containing point. If COUNT
is negative, it moves up instead. The optional second argument
WINDOW's point. (This differs from FSF Emacs, which buggily always
sets current buffer's point, regardless of WINDOW.)
- - Function: vertical-motion-pixels COUNT &optional WINDOW HOW
+ - Function: vertical-motion-pixels count &optional window how
This function moves point to the start of the frame line PIXELS
vertical pixels down from the frame line containing point, or up if
PIXELS is negative. The optional second argument WINDOW is the
least PIXELS. Any other value indicates that the motion should be
as close as possible to PIXELS.
- - Command: move-to-window-line COUNT &optional WINDOW
+ - Command: move-to-window-line count &optional window
This function moves point with respect to the text currently
displayed in WINDOW, which defaults to the selected window. It
moves point to the beginning of the screen line COUNT screen lines
sexps. For user-level commands, see *Note Lists and Sexps:
(emacs)Lists and Sexps.
- - Command: forward-list &optional ARG
+ - Command: forward-list &optional arg
This function moves forward across ARG balanced groups of
parentheses. (Other syntactic entities such as words or paired
string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
is negative, move backward across that many groups of parentheses.
- - Command: backward-list &optional ARG
+ - Command: backward-list &optional arg
This function moves backward across ARG balanced groups of
parentheses. (Other syntactic entities such as words or paired
string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
is negative, move forward across that many groups of parentheses.
- - Command: up-list ARG
+ - Command: up-list arg
This function moves forward out of ARG levels of parentheses. A
negative argument means move backward but still to a less deep
spot.
- - Command: down-list ARG
+ - Command: down-list arg
This function moves forward into ARG levels of parentheses. A
negative argument means move backward but still go deeper in
parentheses (-ARG levels).
- - Command: forward-sexp &optional ARG
+ - Command: forward-sexp &optional arg
This function moves forward across ARG balanced expressions.
Balanced expressions include both those delimited by parentheses
and other kinds, such as words and string constants. ARG defaults
(concat "foo " (car x) y-!- z)
---------- Buffer: foo ----------
- - Command: backward-sexp &optional ARG
+ - Command: backward-sexp &optional arg
This function moves backward across ARG balanced expressions. ARG
defaults to 1 if omitted. If ARG is negative, move forward across
that many balanced expressions.
- - Command: beginning-of-defun &optional ARG
+ - Command: beginning-of-defun &optional arg
This function moves back to the ARGth beginning of a defun. If
ARG is negative, this actually moves forward, but it still moves
to the beginning of a defun, not to the end of one. ARG defaults
to 1 if omitted.
- - Command: end-of-defun &optional ARG
+ - Command: end-of-defun &optional arg
This function moves forward to the ARGth end of a defun. If ARG
is negative, this actually moves backward, but it still moves to
the end of a defun, not to the beginning of one. ARG defaults to
characters. For example, they are often used to skip whitespace. For
related functions, see *Note Motion and Syntax::.
- - Function: skip-chars-forward CHARACTER-SET &optional LIMIT BUFFER
+ - Function: skip-chars-forward character-set &optional limit buffer
This function moves point in BUFFER forward, skipping over a given
set of characters. It examines the character following point,
then advances point if the character matches CHARACTER-SET. This
comes back" twice.
---------- Buffer: foo ----------
- - Function: skip-chars-backward CHARACTER-SET &optional LIMIT BUFFER
+ - Function: skip-chars-backward character-set &optional limit buffer
This function moves point backward, skipping characters that match
CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
except for the direction of motion.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
The forms for saving and restoring the configuration of windows are
described elsewhere (see *Note Window Configurations:: and *note Frame
-Configurations::.).
+Configurations::).
- - Special Form: save-excursion FORMS...
+ - Special Form: save-excursion forms...
The `save-excursion' special form saves the identity of the current
buffer and the values of point and the mark in it, evaluates
FORMS, and finally restores the buffer and its saved values of
point and the mark. All three saved values are restored even in
case of an abnormal exit via `throw' or error (*note Nonlocal
- Exits::.).
+ Exits::).
The `save-excursion' special form is the standard way to switch
buffers or move point within one part of a program and avoid
correspondences altered by functions such as `switch-to-buffer'.
One way to restore these correspondences, and the selected window,
is to use `save-window-excursion' inside `save-excursion' (*note
- Window Configurations::.).
+ Window Configurations::).
The value returned by `save-excursion' is the result of the last of
FORMS, or `nil' if no FORMS are given.
(goto-char old-pnt)
(set-marker (mark-marker) old-mark)))
- - Special Form: save-current-buffer FORMS...
+ - Special Form: save-current-buffer forms...
This special form is similar to `save-excursion' but it only saves
and restores the current buffer. Beginning with XEmacs 20.3,
`save-current-buffer' is a primitive.
- - Special Form: with-current-buffer BUFFER FORMS...
+ - Special Form: with-current-buffer buffer forms...
This special form evaluates FORMS with BUFFER as the current
buffer. It returns the value of the last form.
- - Special Form: with-temp-file FILE FORMS...
+ - Special Form: with-temp-file file forms...
This special form creates a new buffer, evaluates FORMS there, and
writes the buffer to FILE. It returns the value of the last form
evaluated.
- - Special Form: save-selected-window FORMS...
+ - Special Form: save-selected-window forms...
This special form is similar to `save-excursion' but it saves and
restores the selected window and nothing else.
The commands for saving buffers are unaffected by narrowing; they
save the entire buffer regardless of any narrowing.
- - Command: narrow-to-region START END &optional BUFFER
+ - Command: narrow-to-region start end &optional buffer
This function sets the accessible portion of BUFFER to start at
START and end at END. Both arguments should be character
positions. BUFFER defaults to the current buffer if omitted.
In an interactive call, START and END are set to the bounds of the
current region (point and the mark, with the smallest first).
- - Command: narrow-to-page &optional MOVE-COUNT
+ - Command: narrow-to-page &optional move-count
This function sets the accessible portion of the current buffer to
include just the current page. An optional first argument
MOVE-COUNT non-`nil' means to move forward or backward by
MOVE-COUNT pages and then narrow. The variable `page-delimiter'
- specifies where pages start and end (*note Standard Regexps::.).
+ specifies where pages start and end (*note Standard Regexps::).
In an interactive call, MOVE-COUNT is set to the numeric prefix
argument.
- - Command: widen &optional BUFFER
+ - Command: widen &optional buffer
This function cancels any narrowing in BUFFER, so that the entire
contents are accessible. This is called "widening". It is
equivalent to the following expression:
BUFFER defaults to the current buffer if omitted.
- - Special Form: save-restriction BODY...
+ - Special Form: save-restriction body...
This special form saves the current bounds of the accessible
portion, evaluates the BODY forms, and finally restores the saved
bounds, thus restoring the same state of narrowing (or absence
thereof) formerly in effect. The state of narrowing is restored
even in the event of an abnormal exit via `throw' or error (*note
- Nonlocal Exits::.). Therefore, this construct is a clean way to
+ Nonlocal Exits::). Therefore, this construct is a clean way to
narrow a buffer temporarily.
The value returned by `save-restriction' is that returned by the
restrictions it saved from), but it does not restore the identity
of the current buffer.
- `save-restriction' does *not* restore point and the mark; use
+ `save-restriction' does _not_ restore point and the mark; use
`save-excursion' for that. If you use both `save-restriction' and
`save-excursion' together, `save-excursion' should come first (on
the outside). Otherwise, the old point value would be restored
* Creating Markers:: Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Changing 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''.
\1f
File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
the characters immediately before and after the deleted text. Inserting
text at the position of a marker normally leaves the marker in front of
the new text--unless it is inserted with `insert-before-markers' (*note
-Insertion::.).
+Insertion::).
Insertion and deletion in a buffer must check all the markers and
relocate them if necessary. This slows processing in a buffer with a
marker. The latter tests are useful in connection with the arithmetic
functions that work with any of markers, integers, or characters.
- - Function: markerp OBJECT
+ - Function: markerp object
This function returns `t' if OBJECT is a marker, `nil' otherwise.
Note that integers are not markers, even though many functions
will accept either a marker or an integer.
- - Function: integer-or-marker-p OBJECT
+ - Function: integer-or-marker-p object
This function returns `t' if OBJECT is an integer or a marker,
`nil' otherwise.
- - Function: integer-char-or-marker-p OBJECT
+ - Function: integer-char-or-marker-p object
This function returns `t' if OBJECT is an integer, a character, or
a marker, `nil' otherwise.
- - Function: number-or-marker-p OBJECT
+ - Function: number-or-marker-p object
This function returns `t' if OBJECT is a number (either kind) or a
marker, `nil' otherwise.
- - Function: number-char-or-marker-p OBJECT
+ - Function: number-char-or-marker-p object
This function returns `t' if OBJECT is a number (either kind), a
character, or a marker, `nil' otherwise.
(make-marker)
=> #<marker in no buffer>
- - Function: point-marker &optional DONT-COPY-P BUFFER
+ - Function: point-marker &optional dont-copy-p buffer
This function returns a marker that points to the present position
of point in BUFFER, which defaults to the current buffer. *Note
Point::. For an example, see `copy-marker', below.
modifying the position of this marker will move point. It is
illegal to change the buffer of it, or make it point nowhere.
- - Function: point-min-marker &optional BUFFER
+ - Function: point-min-marker &optional buffer
This function returns a new marker that points to the beginning of
the accessible portion of BUFFER, which defaults to the current
buffer. This will be the beginning of the buffer unless narrowing
is in effect. *Note Narrowing::.
- - Function: point-max-marker &optional BUFFER
+ - Function: point-max-marker &optional buffer
This function returns a new marker that points to the end of the
accessible portion of BUFFER, which defaults to the current
buffer. This will be the end of the buffer unless narrowing is in
(point-max-marker)
=> #<marker at 200 in markers.texi>
- - Function: copy-marker MARKER-OR-INTEGER
+ - Function: copy-marker marker-or-integer
If passed a marker as its argument, `copy-marker' returns a new
marker that points to the same place and the same buffer as does
MARKER-OR-INTEGER. If passed an integer as its argument,
This section describes the functions for accessing the components of
a marker object.
- - Function: marker-position MARKER
+ - Function: marker-position marker
This function returns the position that MARKER points to, or `nil'
if it points nowhere.
- - Function: marker-buffer MARKER
+ - Function: marker-buffer marker
This function returns the buffer that MARKER points into, or `nil'
if it points nowhere.
moving it--otherwise, confusing things may happen in other parts of
Emacs.
- - Function: set-marker MARKER POSITION &optional BUFFER
+ - Function: set-marker marker position &optional buffer
This function moves MARKER to POSITION in BUFFER. If BUFFER is
not provided, it defaults to the current buffer.
(set-marker m 0 b)
=> #<marker at 1 in foo>
- - Function: move-marker MARKER POSITION &optional BUFFER
+ - Function: move-marker marker position &optional buffer
This is another name for `set-marker'.
\1f
maximum number of entries in the mark ring; once the list becomes this
long, adding a new element deletes the last element.
- - Function: mark &optional FORCE BUFFER
+ - Function: mark &optional force buffer
This function returns BUFFER's mark position as an integer.
BUFFER defaults to the current buffer if omitted.
If you are using this in an editing command, you are most likely
making a mistake; see the documentation of `set-mark' below.
- - Function: mark-marker INACTIVE-P BUFFER
+ - Function: mark-marker inactive-p buffer
This function returns BUFFER's mark. BUFFER defaults to the
current buffer if omitted. This is the very marker that records
the mark location inside XEmacs, not a copy. Therefore, changing
other than the one of which it is the mark. If you do, it will
yield perfectly consistent, but rather odd, results.
- - Function: set-mark POSITION &optional BUFFER
+ - Function: set-mark position &optional buffer
This function sets `buffer''s mark to POSITION, and activates the
mark. BUFFER defaults to the current buffer if omitted. The old
- value of the mark is *not* pushed onto the mark ring.
+ value of the mark is _not_ pushed onto the mark ring.
*Please note:* Use this function only if you want the user to see
that the mark has moved, and you want the previous mark position to
(forward-line 1)
(delete-region beg (point))).
- - Command: exchange-point-and-mark &optional DONT-ACTIVATE-REGION
+ - Command: exchange-point-and-mark &optional dont-activate-region
This function exchanges the positions of point and the mark. It
is intended for interactive use. The mark is also activated
unless DONT-ACTIVATE-REGION is non-`nil'.
- - Function: push-mark &optional POSITION NOMSG ACTIVATE BUFFER
+ - Function: push-mark &optional position nomsg activate buffer
This function sets BUFFER's mark to POSITION, and pushes a copy of
the previous mark onto `mark-ring'. BUFFER defaults to the
current buffer if omitted. If POSITION is `nil', then the value
If the last global mark pushed was not in BUFFER, also push
POSITION on the global mark ring (see below).
- The function `push-mark' normally *does not* activate the mark.
+ The function `push-mark' normally _does not_ activate the mark.
To do that, specify `t' for the argument ACTIVATE.
A `Mark set' message is displayed unless NOMSG is non-`nil'.
specify the bounds explicitly as arguments and automatically respects
the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
- - Function: region-beginning &optional BUFFER
+ - Function: region-beginning &optional buffer
This function returns the position of the beginning of BUFFER's
region (as an integer). This is the position of either point or
the mark, whichever is smaller. BUFFER defaults to the current
If the mark does not point anywhere, an error is signaled. Note
that this function ignores whether the region is active.
- - Function: region-end &optional BUFFER
+ - Function: region-end &optional buffer
This function returns the position of the end of BUFFER's region
(as an integer). This is the position of either point or the mark,
whichever is larger. BUFFER defaults to the current buffer if
- Variable: zmacs-deactivate-region-hook
This normal hook is called when an active region becomes inactive.
(Calling `zmacs-deactivate-region' when the region is inactive will
- *not* cause this hook to be called.) If ZMACS-REGIONS is false,
+ _not_ cause this hook to be called.) If ZMACS-REGIONS is false,
this hook will never get called.
- Variable: zmacs-update-region-hook
buffer. Most examine, insert, or delete text in the current buffer,
often in the vicinity of point. Many are interactive. All the
functions that change the text provide for undoing the changes (*note
-Undo::.).
+Undo::).
Many text-related functions operate on a region of text defined by
two buffer positions passed in arguments named START and END. These
-arguments should be either markers (*note Markers::.) or numeric
-character positions (*note Positions::.). The order of these arguments
+arguments should be either markers (*note Markers::) or numeric
+character positions (*note Positions::). The order of these arguments
does not matter; it is all right for START to be the end of the region
and END the beginning. For example, `(delete-region 1 10)' and
`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
usually did not have these optional BUFFER arguments and always
operated on the current buffer.)
- - Function: char-after POSITION &optional BUFFER
+ - Function: char-after position &optional buffer
This function returns the character in the buffer at (i.e.,
immediately after) position POSITION. If POSITION is out of range
for this purpose, either before the beginning of the buffer, or at
(char-to-string (char-after 1))
=> "@"
- - Function: following-char &optional BUFFER
+ - Function: following-char &optional buffer
This function returns the character following point in the buffer.
This is similar to `(char-after (point))'. However, if point is at
the end of the buffer, then the result of `following-char' is 0.
(char-to-string (following-char))
=> "c"
- - Function: preceding-char &optional BUFFER
+ - Function: preceding-char &optional buffer
This function returns the character preceding point in the buffer.
See above, under `following-char', for an example. If point is at
the beginning of the buffer, `preceding-char' returns 0. If
optional argument BUFFER is `nil', the current buffer is assumed.
- - Function: bobp &optional BUFFER
+ - Function: bobp &optional buffer
This function returns `t' if point is at the beginning of the
buffer. If narrowing is in effect, this means the beginning of the
accessible portion of the text. If optional argument BUFFER is
`nil', the current buffer is assumed. See also `point-min' in
*Note Point::.
- - Function: eobp &optional BUFFER
+ - Function: eobp &optional buffer
This function returns `t' if point is at the end of the buffer.
If narrowing is in effect, this means the end of accessible
portion of the text. If optional argument BUFFER is `nil', the
current buffer is assumed. See also `point-max' in *Note Point::.
- - Function: bolp &optional BUFFER
+ - Function: bolp &optional buffer
This function returns `t' if point is at the beginning of a line.
If optional argument BUFFER is `nil', the current buffer is
assumed. *Note Text Lines::. The beginning of the buffer (or its
accessible portion) always counts as the beginning of a line.
- - Function: eolp &optional BUFFER
+ - Function: eolp &optional buffer
This function returns `t' if point is at the end of a line. The
end of the buffer is always considered the end of a line. If
optional argument BUFFER is `nil', the current buffer is assumed.
This section describes two functions that allow a Lisp program to
convert any portion of the text in the buffer into a string.
- - Function: buffer-substring START END &optional BUFFER
- - Function: buffer-string START END &optional BUFFER
+ - Function: buffer-substring start end &optional buffer
+ - Function: buffer-string start end &optional buffer
These functions are equivalent and return a string containing a
copy of the text of the region defined by positions START and END
in the buffer. If the arguments are not positions in the
This function lets you compare portions of the text in a buffer,
without copying them into strings first.
- - Function: compare-buffer-substrings BUFFER1 START1 END1 BUFFER2
- START2 END2
+ - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
+ start2 end2
This function lets you compare two substrings of the same buffer
or two different buffers. The first three arguments specify one
substring, giving a buffer and two positions within the buffer.
Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text (*note
-Markers::.). When a marker points at the place of insertion, insertion
+Markers::). When a marker points at the place of insertion, insertion
normally doesn't relocate the marker, so that it points to the
beginning of the inserted text; however, certain special functions such
as `insert-before-markers' relocate such markers to point after the
characters specified as separate arguments, not part of a string or
buffer, inherit their text properties from the neighboring text.
- - Function: insert &rest ARGS
+ - Function: insert &rest args
This function inserts the strings and/or characters ARGS into the
current buffer, at point, moving point forward. In other words, it
inserts the text before point. An error is signaled unless all
ARGS are either strings or characters. The value is `nil'.
- - Function: insert-before-markers &rest ARGS
+ - Function: insert-before-markers &rest args
This function inserts the strings and/or characters ARGS into the
current buffer, at point, moving point forward. An error is
signaled unless all ARGS are either strings or characters. The
relocates markers initially pointing at the insertion point, to
point after the inserted text.
- - Function: insert-string STRING &optional BUFFER
+ - Function: insert-string string &optional buffer
This function inserts STRING into BUFFER before point. BUFFER
defaults to the current buffer if omitted. This function is
chiefly useful if you want to insert a string in a buffer other
than the current one (otherwise you could just use `insert').
- - Function: insert-char CHARACTER COUNT &optional BUFFER
+ - Function: insert-char character count &optional buffer
This function inserts COUNT instances of CHARACTER into BUFFER
before point. COUNT must be a number, and CHARACTER must be a
character. The value is `nil'. If optional argument BUFFER is
`nil', the current buffer is assumed. (In FSF Emacs, the third
argument is called INHERIT and refers to text properties.)
- - Function: insert-buffer-substring FROM-BUFFER-OR-NAME &optional
- START END
+ - Function: insert-buffer-substring from-buffer-or-name &optional
+ start end
This function inserts a portion of buffer FROM-BUFFER-OR-NAME
(which must already exist) into the current buffer before point.
The text inserted is the region from START and END. (These
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
commands intended primarily for the user but useful also in Lisp
programs.
- - Command: insert-buffer FROM-BUFFER-OR-NAME
+ - Command: insert-buffer from-buffer-or-name
This command inserts the entire contents of FROM-BUFFER-OR-NAME
(which must exist) into the current buffer after point. It leaves
the mark after the inserted text. The value is `nil'.
- - Command: self-insert-command COUNT
+ - Command: self-insert-command count
This command inserts the last character typed; it does so COUNT
times, before point, and returns `nil'. Most printing characters
are bound to this command. In routine use, `self-insert-command'
This command calls `auto-fill-function' whenever that is non-`nil'
and the character inserted is a space or a newline (*note Auto
- Filling::.).
+ Filling::).
This command performs abbrev expansion if Abbrev mode is enabled
and the inserted character does not have word-constituent syntax.
This is also responsible for calling `blink-paren-function' when
the inserted character has close parenthesis syntax (*note
- Blinking::.).
+ Blinking::).
- - Command: newline &optional NUMBER-OF-NEWLINES
+ - Command: newline &optional number-of-newlines
This command inserts newlines into the current buffer before point.
If NUMBER-OF-NEWLINES is supplied, that many newline characters
are inserted.
=============
Deletion means removing part of the text in a buffer, without saving
-it in the kill ring (*note The Kill Ring::.). Deleted text can't be
-yanked, but can be reinserted using the undo mechanism (*note Undo::.).
+it in the kill ring (*note The Kill Ring::). Deleted text can't be
+yanked, but can be reinserted using the undo mechanism (*note Undo::).
Some deletion functions do save text in the kill ring in some special
cases.
All of the deletion functions operate on the current buffer, and all
return a value of `nil'.
- - Function: erase-buffer &optional BUFFER
+ - Function: erase-buffer &optional buffer
This function deletes the entire text of BUFFER, leaving it empty.
If the buffer is read-only, it signals a `buffer-read-only'
error. Otherwise, it deletes the text without asking for any
future text is not really related to the former text, and its size
should not be compared with that of the former text.
- - Command: delete-region START END &optional BUFFER
+ - Command: delete-region start end &optional buffer
This command deletes the text in BUFFER in the region defined by
START and END. The value is `nil'. If optional argument BUFFER
is `nil', the current buffer is assumed.
- - Command: delete-char COUNT &optional KILLP
+ - Command: delete-char count &optional killp
This command deletes COUNT characters directly after point, or
before point if COUNT is negative. If KILLP is non-`nil', then it
saves the deleted characters in the kill ring.
The value returned is always `nil'.
- - Command: delete-backward-char COUNT &optional KILLP
+ - Command: delete-backward-char count &optional killp
This command deletes COUNT characters directly before point, or
after point if COUNT is negative. If KILLP is non-`nil', then it
saves the deleted characters in the kill ring.
The value returned is always `nil'.
- - Command: backward-delete-char-untabify COUNT &optional KILLP
+ - Command: backward-delete-char-untabify count &optional killp
This command deletes COUNT characters backward, changing tabs into
spaces. When the next character to be deleted is a tab, it is
first replaced with the proper number of spaces to preserve
You thought
---------- Buffer: foo ----------
- - Command: delete-indentation &optional JOIN-FOLLOWING-P
+ - Command: delete-indentation &optional join-following-p
This function joins the line point is on to the previous line,
deleting any whitespace at the join and in some cases replacing it
with one space. If JOIN-FOLLOWING-P is non-`nil',
(delete-indentation)
=> nil
+
---------- Buffer: foo ----------
When in the course of human-!- events, it becomes necessary
---------- Buffer: foo ----------
This has too many -!-spaces
This has too many spaces at the start of (-!- this list)
---------- Buffer: foo ----------
-
+
(fixup-whitespace)
=> nil
(fixup-whitespace)
=> nil
-
+
---------- Buffer: foo ----------
This has too many spaces
This has too many spaces at the start of (this list)
treat it as a ring.
Some people think this use of the word "kill" is unfortunate, since
-it refers to operations that specifically *do not* destroy the entities
+it refers to operations that specifically _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 life.
Therefore, other metaphors have been proposed. For example, the term
previous command was a kill command, and if so appends the killed text
to the most recent entry.
- - Command: kill-region START END
+ - Command: kill-region start end
This function kills the text in the region defined by START and
END. The text is deleted but saved in the kill ring, along with
its text properties. The value is always `nil'.
This is convenient because it lets the user use all the kill
commands to copy text into the kill ring from a read-only buffer.
- - Command: copy-region-as-kill START END
+ - Command: copy-region-as-kill start end
This command saves the region defined by START and END on the kill
ring (including text properties), but does not delete the text
from the buffer. It returns `nil'. It also indicates the extent
"Yanking" means reinserting an entry of previously killed text from
the kill ring. The text properties are copied too.
- - Command: yank &optional ARG
+ - Command: yank &optional arg
This command inserts before point the text in the first entry in
the kill ring. It positions the mark at the beginning of that
text, and point at the end.
`yank' does not alter the contents of the kill ring or rotate it.
It returns `nil'.
- - Command: yank-pop ARG
+ - Command: yank-pop arg
This command replaces the just-yanked entry from the kill ring
with a different entry from the kill ring.
care of interaction with X Window selections. They do not exist in
Emacs version 18.
- - Function: current-kill N &optional DO-NOT-MOVE
+ - Function: current-kill n &optional do-not-move
The function `current-kill' rotates the yanking pointer which
designates the "front" of the kill ring by N places (from newer
kills to older ones), and returns the text at that place in the
`current-kill' calls the value of `interprogram-paste-function'
(documented below) before consulting the kill ring.
- - Function: kill-new STRING
+ - Function: kill-new string
This function puts the text STRING into the kill ring as a new
entry at the front of the ring. It discards the oldest entry if
appropriate. It also invokes the value of
`interprogram-cut-function' (see below).
- - Function: kill-append STRING BEFORE-P
+ - Function: kill-append string before-p
This function appends the text STRING to the first entry in the
kill ring. Normally STRING goes at the end of the entry, but if
BEFORE-P is non-`nil', it goes at the beginning. This function
`query-replace' calls `undo-boundary' after each replacement, so
that the user can undo individual replacements one by one.
- - Function: primitive-undo COUNT LIST
+ - Function: primitive-undo count list
This is the basic function for undoing elements of an undo list.
It undoes the first COUNT elements of LIST, returning the rest of
LIST. You could write this function in Lisp, but it is convenient
disable undo recording with the following two functions, or by setting
`buffer-undo-list' yourself.
- - Command: buffer-enable-undo &optional BUFFER-OR-NAME
+ - Command: buffer-enable-undo &optional buffer-or-name
This command enables recording undo information for buffer
BUFFER-OR-NAME, so that subsequent changes can be undone. If no
argument is supplied, then the current buffer is used. This
In an interactive call, BUFFER-OR-NAME is the current buffer. You
cannot specify any other buffer.
- - Function: buffer-disable-undo &optional BUFFER
- - Function: buffer-flush-undo &optional BUFFER
+ - Function: buffer-disable-undo &optional buffer
+ - Function: buffer-flush-undo &optional buffer
This function discards the undo list of BUFFER, and disables
further recording of undo information. As a result, it is no
longer possible to undo either previous changes or any subsequent
precisely. The width is controlled by the variable `fill-column'. For
ease of reading, lines should be no longer than 70 or so columns.
- You can use Auto Fill mode (*note Auto Filling::.) to fill text
+ You can use Auto Fill mode (*note Auto Filling::) to fill text
automatically as you insert it, but changes to existing text may leave
it improperly filled. Then you must fill the text explicitly.
Most of the commands in this section return values that are not
meaningful. All the functions that do filling take note of the current
left margin, current right margin, and current justification style
-(*note Margins::.). If the current justification style is `none', the
+(*note Margins::). If the current justification style is `none', the
filling functions don't actually do anything.
Several of the filling functions have an argument JUSTIFY. If it is
When you call the filling functions interactively, using a prefix
argument implies the value `full' for JUSTIFY.
- - Command: fill-paragraph JUSTIFY
+ - Command: fill-paragraph justify
This command fills the paragraph at or after point. If JUSTIFY is
non-`nil', each line is justified as well. It uses the ordinary
paragraph motion commands to find paragraph boundaries. *Note
Paragraphs: (xemacs)Paragraphs.
- - Command: fill-region START END &optional JUSTIFY
+ - Command: fill-region start end &optional justify
This command fills each of the paragraphs in the region from START
to END. It justifies as well if JUSTIFY is non-`nil'.
The variable `paragraph-separate' controls how to distinguish
paragraphs. *Note Standard Regexps::.
- - Command: fill-individual-paragraphs START END &optional JUSTIFY
- MAIL-FLAG
+ - Command: fill-individual-paragraphs start end &optional justify
+ mail-flag
This command fills each paragraph in the region according to its
individual fill prefix. Thus, if the lines of a paragraph were
indented with spaces, the filled paragraph will remain indented in
This variable alters the action of `fill-individual-paragraphs' as
described above.
- - Command: fill-region-as-paragraph START END &optional JUSTIFY
+ - Command: fill-region-as-paragraph start end &optional justify
This command considers a region of text as a paragraph and fills
it. If the region was made up of many paragraphs, the blank lines
between paragraphs are removed. This function justifies as well
no fill prefix uses the indentation of the second line of the
paragraph as the fill prefix.
- - Command: justify-current-line HOW EOP NOSQUEEZE
+ - Command: justify-current-line how eop nosqueeze
This command inserts spaces between the words of the current line
so that the line ends exactly at `fill-column'. It returns `nil'.
lines. Its value should be an integer, which is a number of
columns. All the filling, justification and centering commands
are affected by this variable, including Auto Fill mode (*note
- Auto Filling::.).
+ Auto Filling::).
As a practical matter, if you are writing text for other people to
read, you should set `fill-column' to no more than 70. Otherwise
The default value for `default-fill-column' is 70.
- - Command: set-left-margin FROM TO MARGIN
+ - Command: set-left-margin from to margin
This sets the `left-margin' property on the text from FROM to TO
to the value MARGIN. If Auto Fill mode is enabled, this command
also refills the region to fit the new margin.
- - Command: set-right-margin FROM TO MARGIN
+ - Command: set-right-margin from to margin
This sets the `right-margin' property on the text from FROM to TO
to the value MARGIN. If Auto Fill mode is enabled, this command
also refills the region to fit the new margin.
`fill-column' variable, minus the value of the `right-margin'
property of the character after point.
- - Command: move-to-left-margin &optional N FORCE
+ - Command: move-to-left-margin &optional n force
This function moves point to the left margin of the current line.
The column moved to is determined by calling the function
`current-left-margin'. If the argument N is non-`nil',
If FORCE is non-`nil', that says to fix the line's indentation if
that doesn't match the left margin value.
- - Function: delete-to-left-margin FROM TO
+ - Function: delete-to-left-margin from to
This function removes left margin indentation from the text
between FROM and TO. The amount of indentation to delete is
determined by calling `current-left-margin'. In no case does this
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
The sorting functions described in this section all rearrange text in
a buffer. This is in contrast to the function `sort', which rearranges
-the order of the elements of a list (*note Rearrangement::.). The
+the order of the elements of a list (*note Rearrangement::). The
values returned by these functions are not meaningful.
- - Function: sort-subr REVERSE NEXTRECFUN ENDRECFUN &optional
- STARTKEYFUN ENDKEYFUN
+ - Function: sort-subr reverse nextrecfun endrecfun &optional
+ startkeyfun endkeyfun
This function is the general text-sorting routine that divides a
buffer into records and sorts them. Most of the commands in this
section use this function.
(skip-chars-forward "\n \t\f")))
'forward-paragraph)
- - Command: sort-regexp-fields REVERSE RECORD-REGEXP KEY-REGEXP START
- END
+ - Command: sort-regexp-fields reverse record-regexp key-regexp start
+ end
This command sorts the region between START and END alphabetically
as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a
negative integer, then sorting is in reverse order.
If you call `sort-regexp-fields' interactively, it prompts for
RECORD-REGEXP and KEY-REGEXP in the minibuffer.
- - Command: sort-lines REVERSE START END
+ - Command: sort-lines reverse start end
This command alphabetically sorts lines in the region between
START and END. If REVERSE is non-`nil', the sort is in reverse
order.
- - Command: sort-paragraphs REVERSE START END
+ - Command: sort-paragraphs reverse start end
This command alphabetically sorts paragraphs in the region between
START and END. If REVERSE is non-`nil', the sort is in reverse
order.
- - Command: sort-pages REVERSE START END
+ - Command: sort-pages reverse start end
This command alphabetically sorts pages in the region between
START and END. If REVERSE is non-`nil', the sort is in reverse
order.
- - Command: sort-fields FIELD START END
+ - Command: sort-fields field start end
This command sorts lines in the region between START and END,
comparing them alphabetically by the FIELDth field of each line.
Fields are separated by whitespace and numbered starting from 1.
If FIELD is negative, sorting is by the -FIELDth field from the
end of the line. This command is useful for sorting tables.
- - Command: sort-numeric-fields FIELD START END
+ - Command: sort-numeric-fields field start end
This command sorts lines in the region between START and END,
comparing them numerically by the FIELDth field of each line. The
specified field must contain a number in each line of the region.
If FIELD is negative, sorting is by the -FIELDth field from the
end of the line. This command is useful for sorting tables.
- - Command: sort-columns REVERSE &optional BEG END
+ - Command: sort-columns reverse &optional beg end
This command sorts the lines in the region between BEG and END,
comparing them alphabetically by a certain range of columns. The
column positions of BEG and END bound the range of columns to sort
For an example of using `current-column', see the description of
`count-lines' in *Note Text Lines::.
- - Function: move-to-column COLUMN &optional FORCE
+ - Function: move-to-column column &optional force
This function moves point to COLUMN in the current line. The
calculation of COLUMN takes into account the widths of the
displayed representations of the characters between the start of
contents are entirely blank, then this is the horizontal position
of the end of the line.
- - Command: indent-to COLUMN &optional MINIMUM
+ - Command: indent-to column &optional minimum
This function indents from point with tabs and spaces until COLUMN
is reached. If MINIMUM is specified and non-`nil', then at least
that many spaces are inserted even if this requires going beyond
This section describes commands that indent all the lines in the
region. They return unpredictable values.
- - Command: indent-region START END TO-COLUMN
+ - Command: indent-region start end to-column
This command indents each nonblank line starting between START
(inclusive) and END (exclusive). If TO-COLUMN is `nil',
`indent-region' indents each nonblank line by calling the current
`indent-region' with a non-`nil' argument TO-COLUMN has a
different meaning and does not use this variable.
- - Command: indent-rigidly START END COUNT
+ - Command: indent-rigidly start end count
This command indents all lines starting between START (inclusive)
and END (exclusive) sideways by COUNT columns. This "preserves
the shape" of the affected region, moving it as a rigid unit.
`indent-rigidly' to indent the text copied from the message being
replied to.
- - Function: indent-code-rigidly START END COLUMNS &optional
- NOCHANGE-REGEXP
+ - Function: indent-code-rigidly start end columns &optional
+ nochange-regexp
This is like `indent-rigidly', except that it doesn't alter lines
that start within strings or comments.
This section describes two commands that indent the current line
based on the contents of previous lines.
- - Command: indent-relative &optional UNINDENTED-OK
+ - Command: indent-relative &optional unindented-ok
This command inserts whitespace at point, extending to the same
column as the next "indent point" of the previous nonblank line.
An indent point is a non-whitespace character following
typewriter. The feature works by inserting an appropriate number of
spaces and tab characters to reach the next tab stop column; it does not
affect the display of tab characters in the buffer (*note Usual
-Display::.). Note that the <TAB> character as input uses this tab stop
+Display::). Note that the <TAB> character as input uses this tab stop
feature only in a few major modes, such as Text mode.
- Command: tab-to-tab-stop
the current line (which is the line in which point is located).
It returns `nil'.
- - Command: backward-to-indentation ARG
+ - Command: backward-to-indentation arg
This command moves point backward ARG lines and then to the first
nonblank character on that line. It returns `nil'.
- - Command: forward-to-indentation ARG
+ - Command: forward-to-indentation arg
This command moves point forward ARG lines and then to the first
nonblank character on that line. It returns `nil'.
on strings and characters. *Note Case Tables::, for how to customize
which characters are upper or lower case and how to convert them.
- - Command: capitalize-region START END
+ - Command: capitalize-region start end
This function capitalizes all words in the region defined by START
and END. To capitalize means to convert each word's first
character to upper case and convert the rest of each word to lower
This Is The Contents Of The 5th Foo.
---------- Buffer: foo ----------
- - Command: downcase-region START END
+ - Command: downcase-region start end
This function converts all of the letters in the region defined by
START and END to lower case. The function returns `nil'.
When `downcase-region' is called interactively, START and END are
point and the mark, with the smallest first.
- - Command: upcase-region START END
+ - Command: upcase-region start end
This function converts all of the letters in the region defined by
START and END to upper case. The function returns `nil'.
When `upcase-region' is called interactively, START and END are
point and the mark, with the smallest first.
- - Command: capitalize-word COUNT
+ - Command: capitalize-word count
This function capitalizes COUNT words after point, moving point
over as it does. To capitalize means to convert each word's first
character to upper case and convert the rest of each word to lower
When `capitalize-word' is called interactively, COUNT is set to
the numeric prefix argument.
- - Command: downcase-word COUNT
+ - Command: downcase-word count
This function converts the COUNT words after point to all lower
case, moving point over as it does. If COUNT is negative, it
converts the -COUNT previous words but does not move point. The
When `downcase-word' is called interactively, COUNT is set to the
numeric prefix argument.
- - Command: upcase-word COUNT
+ - Command: upcase-word count
This function converts the COUNT words after point to all upper
case, moving point over as it does. If COUNT is negative, it
converts the -COUNT previous words but does not move point. The
===============
Text properties are an alternative interface to extents (*note
-Extents::.), and are built on top of them. They are useful when you
+Extents::), and are built on top of them. They are useful when you
want to view textual properties as being attached to the characters
themselves rather than to intervals of characters. The text property
interface is compatible with FSF Emacs.
Each character position in a buffer or a string can have a "text
property list", much like the property list of a symbol (*note Property
-Lists::.). The properties belong to a particular character at a
+Lists::). The properties belong to a particular character at a
particular place, such as, the letter `T' at the beginning of this
sentence or the first `o' in `foo'--if the same character occurs in two
different places, the two occurrences generally have different
positions in a string start from 0, whereas positions in a buffer start
from 1.)
- - Function: get-text-property POS PROP &optional OBJECT
+ - Function: get-text-property pos prop &optional object
This function returns the value of the PROP property of the
character after position POS in OBJECT (a buffer or string). The
argument OBJECT is optional and defaults to the current buffer.
- - Function: get-char-property POS PROP &optional OBJECT
+ - Function: get-char-property pos prop &optional object
This function is like `get-text-property', except that it checks
all extents, not just text-property extents.
- - Function: text-properties-at POSITION &optional OBJECT
+ - Function: text-properties-at position &optional object
This function returns the entire property list of the character at
POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
defaults to the current buffer.
Since text properties are considered part of the buffer's contents,
and can affect how the buffer looks on the screen, any change in the
text properties is considered a buffer modification. Buffer text
-property changes are undoable (*note Undo::.).
+property changes are undoable (*note Undo::).
- - Function: put-text-property START END PROP VALUE &optional OBJECT
+ - Function: put-text-property start end prop value &optional object
This function sets the PROP property to VALUE for the text between
START and END in the string or buffer OBJECT. If OBJECT is `nil',
it defaults to the current buffer.
- - Function: add-text-properties START END PROPS &optional OBJECT
+ - Function: add-text-properties start end props &optional object
This function modifies the text properties for the text between
START and END in the string or buffer OBJECT. If OBJECT is `nil',
it defaults to the current buffer.
The argument PROPS specifies which properties to change. It
- should have the form of a property list (*note Property Lists::.):
+ should have the form of a property list (*note Property Lists::):
a list whose elements include the property names followed
alternately by the corresponding values.
(add-text-properties START END
'(comment t face highlight))
- - Function: remove-text-properties START END PROPS &optional OBJECT
+ - Function: remove-text-properties start end props &optional object
This function deletes specified text properties from the text
between START and END in the string or buffer OBJECT. If OBJECT
is `nil', it defaults to the current buffer.
The argument PROPS specifies which properties to delete. It
- should have the form of a property list (*note Property Lists::.):
+ should have the form of a property list (*note Property Lists::):
a list whose elements are property names alternating with
corresponding values. But only the names matter--the values that
accompany them are ignored. For example, here's how to remove the
property's value; `nil' otherwise (if PROPS is `nil' or if no
character in the specified text had any of those properties).
- - Function: set-text-properties START END PROPS &optional OBJECT
+ - Function: set-text-properties start end props &optional object
This function completely replaces the text property list for the
text between START and END in the string or buffer OBJECT. If
OBJECT is `nil', it defaults to the current buffer.
(set-text-properties START END nil)
See also the function `buffer-substring-without-properties' (*note
-Buffer Contents::.) which copies text from the buffer but does not copy
+Buffer Contents::) which copies text from the buffer but does not copy
its properties.
\1f
position returned by these functions is between two characters with
different properties.
- - Function: next-property-change POS &optional OBJECT LIMIT
+ - Function: next-property-change pos &optional object limit
The function scans the text forward from position POS in the
string or buffer OBJECT till it finds a change in some text
property, then returns the position of the change. In other
Process text from point to NEXT-CHANGE...
(goto-char next-change)))
- - Function: next-single-property-change POS PROP &optional OBJECT LIMIT
+ - Function: next-single-property-change pos prop &optional object limit
The function scans the text forward from position POS in the
string or buffer OBJECT till it finds a change in the PROP
property, then returns the position of the change. In other
it is a position greater than or equal to POS; it equals POS only
if LIMIT equals POS.
- - Function: previous-property-change POS &optional OBJECT LIMIT
+ - Function: previous-property-change pos &optional object limit
This is like `next-property-change', but scans back from POS
instead of forward. If the value is non-`nil', it is a position
less than or equal to POS; it equals POS only if LIMIT equals POS.
- - Function: previous-single-property-change POS PROP &optional OBJECT
- LIMIT
+ - Function: previous-single-property-change pos prop &optional object
+ limit
This is like `next-single-property-change', but scans back from
POS instead of forward. If the value is non-`nil', it is a
position less than or equal to POS; it equals POS only if LIMIT
equals POS.
- - Function: text-property-any START END PROP VALUE &optional OBJECT
+ - Function: text-property-any start end prop value &optional object
This function returns non-`nil' if at least one character between
START and END has a property PROP whose value is VALUE. More
precisely, it returns the position of the first such character.
buffer to scan. Positions are relative to OBJECT. The default
for OBJECT is the current buffer.
- - Function: text-property-not-all START END PROP VALUE &optional OBJECT
+ - Function: text-property-not-all start end prop value &optional object
This function returns non-`nil' if at least one character between
START and END has a property PROP whose value differs from VALUE.
More precisely, it returns the position of the first such
The following functions replace characters within a specified region
based on their character codes.
- - Function: subst-char-in-region START END OLD-CHAR NEW-CHAR &optional
- NOUNDO
+ - Function: subst-char-in-region start end old-char new-char &optional
+ noundo
This function replaces all occurrences of the character OLD-CHAR
with the character NEW-CHAR in the region of the current buffer
defined by START and END.
If NOUNDO is non-`nil', then `subst-char-in-region' does not
record the change for undo and does not mark the buffer as
modified. This feature is used for controlling selective display
- (*note Selective Display::.).
+ (*note Selective Display::).
`subst-char-in-region' does not move point and returns `nil'.
ThXs Xs the contents of the buffer before.
---------- Buffer: foo ----------
- - Function: translate-region START END TABLE
+ - Function: translate-region start end table
This function applies a translation table to the characters in the
buffer between positions START and END. The translation table
TABLE can be either a string, a vector, or a char-table.
represents a rectangle; its elements are strings, one per line of
the rectangle.
- - Function: get-register REG
+ - Function: get-register reg
This function returns the contents of the register REG, or `nil'
if it has no contents.
- - Function: set-register REG VALUE
+ - Function: set-register reg value
This function sets the contents of register REG to VALUE. A
register can be set to any value, but the other register functions
expect only certain data types. The return value is VALUE.
- - Command: view-register REG
+ - Command: view-register reg
This command displays what is contained in register REG.
- - Command: insert-register REG &optional BEFOREP
+ - Command: insert-register reg &optional beforep
This command inserts contents of register REG into the current
buffer.
This subroutine is used by the transposition commands.
- - Function: transpose-regions START1 END1 START2 END2 &optional
- LEAVE-MARKERS
+ - Function: transpose-regions start1 end1 start2 end2 &optional
+ leave-markers
This function exchanges two nonoverlapping portions of the buffer.
Arguments START1 and END1 specify the bounds of one portion and
arguments START2 and END2 specify the bounds of the other portion.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Emacs Lisp interface to MD5 consists of a single function `md5':
- - Function: md5 OBJECT &optional START END
+ - Function: md5 object &optional start end
This function returns the MD5 message digest of OBJECT, a buffer
or string.
The Lisp interface to base64 consists of four functions:
- - Function: base64-encode-region BEG END &optional NO-LINE-BREAK
+ - Function: base64-encode-region beg end &optional no-line-break
This function encodes the region between BEG and END of the
current buffer to base64 format. This means that the original
region is deleted, and replaced with its base64 equivalent.
The function can also be used interactively, in which case it
works on the currently active region.
- - Function: base64-encode-string STRING
+ - Function: base64-encode-string string
This function encodes STRING to base64, and returns the encoded
string.
(base64-encode-string "fubar")
=> "ZnViYXI="
- - Function: base64-decode-region BEG END
+ - Function: base64-decode-region beg end
This function decodes the region between BEG and END of the
current buffer. The region should be in base64 encoding.
;; Decode a base64 buffer, and replace it with the decoded version
(base64-decode-region (point-min) (point-max))
- - Function: base64-decode-string STRING
+ - Function: base64-decode-string string
This function decodes STRING to base64, and returns the decoded
string. STRING should be valid base64-encoded text.
interactively. If you do so, they prompt for the search string; LIMIT
and NOERROR are set to `nil', and REPEAT is set to 1.
- - Command: search-forward STRING &optional LIMIT NOERROR REPEAT
+ - Command: search-forward string &optional limit noerror repeat
This function searches forward from point for an exact match for
STRING. If successful, it sets point to the end of the occurrence
found, and returns the new value of point. If no match is found,
succeed, the function succeeds, moving point and returning its new
value. Otherwise the search fails.
- - Command: search-backward STRING &optional LIMIT NOERROR REPEAT
+ - Command: search-backward string &optional limit noerror repeat
This function searches backward from point for STRING. It is just
like `search-forward' except that it searches backwards and leaves
point at the beginning of the match.
- - Command: word-search-forward STRING &optional LIMIT NOERROR REPEAT
+ - Command: word-search-forward string &optional limit noerror repeat
This function searches forward from point for a "word" match for
STRING. If it finds a match, it sets point to the end of the
match found, and returns the new value of point.
If REPEAT is non-`nil', then the search is repeated that many
times. Point is positioned at the end of the last match.
- - Command: word-search-backward STRING &optional LIMIT NOERROR REPEAT
+ - Command: word-search-backward string &optional limit noerror repeat
This function searches backward from point for a word match to
STRING. This function is just like `word-search-forward' except
that it searches backward and normally leaves point at the
For example, `f' is not a special character, so it is ordinary, and
therefore `f' is a regular expression that matches the string `f' and
-no other string. (It does *not* match the string `ff'.) Likewise, `o'
+no other string. (It does _not_ match the string `ff'.) Likewise, `o'
is a regular expression that matches only `o'.
Any two regular expressions A and B can be concatenated. The result
matches one `f' followed by any number of `o's. The case of zero
`o's is allowed: `fo*' does match `f'.
- `*' always applies to the *smallest* possible preceding
+ `*' always applies to the _smallest_ possible preceding
expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
The matcher processes a `*' construct by matching, immediately, as
`[^ ... ]'
`[^' begins a "complement character set", which matches any
character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
- all characters *except* letters and digits.
+ all characters _except_ letters and digits.
`^' is not special in a character set unless it is the first
character. The character following the `^' is treated as if it
that matches only `[', and so on.
Note that `\' also has special meaning in the read syntax of Lisp
- strings (*note String Type::.), and must be quoted with `\'. For
+ strings (*note String Type::), and must be quoted with `\'. For
example, the regular expression that matches the `\' character is
`\\'. To write a Lisp string that contains the characters `\\',
Lisp syntax requires you to quote each `\' with another `\'.
separate word.
`\B'
- matches the empty string, but *not* at the beginning or end of a
+ matches the empty string, but _not_ at the beginning or end of a
word.
`\<'
`\'. If an invalid regular expression is passed to any of the search
functions, an `invalid-regexp' error is signaled.
- - Function: regexp-quote STRING
+ - Function: regexp-quote string
This function returns a regular expression string that matches
exactly STRING and nothing else. This allows you to request an
exact string match when calling a function that wants a regular
(emacs)Regexp Search. Here we describe only the search functions
useful in programs. The principal one is `re-search-forward'.
- - Command: re-search-forward REGEXP &optional LIMIT NOERROR REPEAT
+ - Command: re-search-forward regexp &optional limit noerror repeat
This function searches forward in the current buffer for a string
of text that is matched by the regular expression REGEXP. The
function skips over any amount of text that is not matched by
comes back" twice.
---------- Buffer: foo ----------
- - Command: re-search-backward REGEXP &optional LIMIT NOERROR REPEAT
+ - Command: re-search-backward regexp &optional limit noerror repeat
This function searches backward in the current buffer for a string
of text that is matched by the regular expression REGEXP, leaving
point at the beginning of the first text found.
feature for matching regexps from end to beginning. It's not
worth the trouble of implementing that.
- - Function: string-match REGEXP STRING &optional START
+ - Function: string-match regexp string &optional start
This function returns the index of the start of the first match for
the regular expression REGEXP in STRING, or `nil' if there is no
match. If START is non-`nil', the search starts at that index in
(match-end 0)
=> 32
- - Function: split-string STRING &optional PATTERN
+ - Function: split-string string &optional pattern
This function splits STRING to substrings delimited by PATTERN,
and returns a list of substrings. If PATTERN is omitted, it
defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
(split-string ":a::b:c" ":")
=> ("" "a" "" "b" "c")
- - Function: split-path PATH
+ - Function: split-path path
This function splits a search path into a list of strings. The
path components are separated with the characters specified with
`path-separator'. Under Unix, `path-separator' will normally be
`:', while under Windows, it will be `;'.
- - Function: looking-at REGEXP
+ - Function: looking-at regexp
This function determines whether the text in the current buffer
directly following point matches the regular expression REGEXP.
"Directly following" means precisely that: the search is
The usual regular expression functions do backtracking when necessary
to handle the `\|' and repetition constructs, but they continue this
-only until they find *some* match. Then they succeed and report the
+only until they find _some_ match. Then they succeed and report the
first match found.
This section describes alternative search functions which perform the
In Emacs versions prior to 19.29, these functions did not exist, and
the functions described above implemented full POSIX backtracking.
- - Function: posix-search-forward REGEXP &optional LIMIT NOERROR REPEAT
+ - Function: posix-search-forward regexp &optional limit noerror repeat
This is like `re-search-forward' except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
- - Function: posix-search-backward REGEXP &optional LIMIT NOERROR REPEAT
+ - Function: posix-search-backward regexp &optional limit noerror repeat
This is like `re-search-backward' except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
- - Function: posix-looking-at REGEXP
+ - Function: posix-looking-at regexp
This is like `looking-at' except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
- - Function: posix-string-match REGEXP STRING &optional START
+ - Function: posix-string-match regexp string &optional start
This is like `string-match' except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
Search and Replace
==================
- - Function: perform-replace FROM-STRING REPLACEMENTS QUERY-FLAG
- REGEXP-FLAG DELIMITED-FLAG &optional REPEAT-COUNT MAP
+ - Function: perform-replace from-string replacements query-flag
+ regexp-flag delimited-flag &optional repeat-count map
This function is the guts of `query-replace' and related commands.
It searches for occurrences of FROM-STRING and replaces some or
all of them. If QUERY-FLAG is `nil', it replaces all occurrences;
subexpressions--after a simple string search, the only information
available is about the entire match.
- - Function: match-string COUNT &optional IN-STRING
+ - Function: match-string count &optional in-string
This function returns, as a string, the text matched in the last
search or match operation. It returns the entire text if COUNT is
zero, or just the portion corresponding to the COUNTth
make sure that the current buffer when you call `match-string' is
the one in which you did the searching or matching.
- - Function: match-beginning COUNT
+ - Function: match-beginning count
This function returns the position of the start of text matched by
the last regular expression searched for, or a subexpression of it.
The value is `nil' for a subexpression inside a `\|' alternative
that wasn't used in the match.
- - Function: match-end COUNT
+ - Function: match-end count
This function is like `match-beginning' except that it returns the
position of the end of the match, rather than the position of the
beginning.
This function replaces the text matched by the last search with
REPLACEMENT.
- - Function: replace-match REPLACEMENT &optional FIXEDCASE LITERAL
- STRING
+ - Function: replace-match replacement &optional fixedcase literal
+ string
This function replaces the text in the buffer (or in STRING) that
was matched by the last search. It replaces that text with
REPLACEMENT.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
#<marker at 13 in foo>
#<marker at 17 in foo>)
- - Function: set-match-data MATCH-LIST
+ - Function: set-match-data match-list
This function sets the match data from the elements of MATCH-LIST,
which should be a list that was the value of a previous call to
`match-data'.
You can save and restore the match data with `save-match-data':
- - Macro: save-match-data BODY...
+ - Macro: save-match-data body...
This special form executes BODY, saving and restoring the match
data around it.
(set-match-data data)))
Emacs automatically saves and restores the match data when it runs
-process filter functions (*note Filter Functions::.) and process
-sentinels (*note Sentinels::.).
+process filter functions (*note Filter Functions::) and process
+sentinels (*note Sentinels::).
\1f
File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching
The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this
matches a line that starts with a formfeed character.
- The following two regular expressions should *not* assume the match
+ The following two regular expressions should _not_ assume the match
always starts at the beginning of a line; they should not use `^' to
anchor the match. Most often, the paragraph commands do check for a
match only at the beginning of a line, which means that `^' would be
- Variable: paragraph-start
This is the regular expression for recognizing the beginning of a
- line that starts *or* separates paragraphs. The default value is
+ line that starts _or_ separates paragraphs. The default value is
`"[ \t\n\f]"', which matches a line starting with a space, tab,
newline, or form feed (after its left margin).
character. This information is used by the parsing commands, the
complex movement commands, and others to determine where words, symbols,
and other syntactic constructs begin and end. The current syntax table
-controls the meaning of the word motion functions (*note Word Motion::.)
-and the list motion functions (*note List Motion::.) as well as the
+controls the meaning of the word motion functions (*note Word Motion::)
+and the list motion functions (*note List Motion::) as well as the
functions in this chapter.
* Menu:
used by the parsing commands, the complex movement commands, and others
to determine where words, symbols, and other syntactic constructs begin
and end. The current syntax table controls the meaning of the word
-motion functions (*note Word Motion::.) and the list motion functions
-(*note List Motion::.) as well as the functions in this chapter.
+motion functions (*note Word Motion::) and the list motion functions
+(*note List Motion::) as well as the functions in this chapter.
Under XEmacs 20, a syntax table is a particular subtype of the
-primitive char table type (*note Char Tables::.), and each element of
-the char table is an integer that encodes the syntax of the character in
+primitive char table type (*note Char Tables::), and each element of the
+char table is an integer that encodes the syntax of the character in
question, or a cons of such an integer and a matching character (for
characters with parenthesis syntax).
alphabetic characters in the range 128 to 255. Just changing the
standard syntax for these characters affects all major modes.
- - Function: syntax-table-p OBJECT
+ - Function: syntax-table-p object
This function returns `t' if OBJECT is a vector of length 256
elements. This means that the vector may be a syntax table.
However, according to this test, any vector of length 256 is
All the flags except `p' are used to describe multi-character
comment delimiters. The digit flags indicate that a character can
-*also* be part of a comment sequence, in addition to the syntactic
+_also_ be part of a comment sequence, in addition to the syntactic
properties associated with its character class. The flags are
independent of the class and each other for the sake of characters such
-as `*' in C mode, which is a punctuation character, *and* the second
-character of a start-of-comment sequence (`/*'), *and* the first
+as `*' in C mode, which is a punctuation character, _and_ the second
+character of a start-of-comment sequence (`/*'), _and_ the first
character of an end-of-comment sequence (`*/').
The flags for a character C are:
In this section we describe functions for creating, accessing and
altering syntax tables.
- - Function: make-syntax-table &optional TABLE
+ - Function: make-syntax-table &optional table
This function creates a new syntax table. Character codes 0
through 31 and 128 through 255 are set up to inherit from the
standard syntax table. The other character codes are set up by
Most major mode syntax tables are created in this way.
- - Function: copy-syntax-table &optional TABLE
+ - Function: copy-syntax-table &optional table
This function constructs a copy of TABLE and returns it. If TABLE
is not supplied (or is `nil'), it returns a copy of the current
syntax table. Otherwise, an error is signaled if TABLE is not a
syntax table.
- - Command: modify-syntax-entry CHAR SYNTAX-DESCRIPTOR &optional TABLE
+ - Command: modify-syntax-entry char syntax-descriptor &optional table
This function sets the syntax entry for CHAR according to
SYNTAX-DESCRIPTOR. The syntax is changed only for TABLE, which
defaults to the current buffer's syntax table, and not in any
(modify-syntax-entry ?/ ". 14")
=> nil
- - Function: char-syntax CHARACTER
+ - Function: char-syntax character
This function returns the syntax class of CHARACTER, represented
- by its mnemonic designator character. This *only* returns the
+ by its mnemonic designator character. This _only_ returns the
class, not any matching parenthesis or flags.
An error is signaled if CHAR is not a character.
(char-to-string (char-syntax ?\())
=> "("
- - Function: set-syntax-table TABLE &optional BUFFER
+ - Function: set-syntax-table table &optional buffer
This function makes TABLE the syntax table for BUFFER, which
defaults to the current buffer if omitted. It returns TABLE.
- - Function: syntax-table &optional BUFFER
+ - Function: syntax-table &optional buffer
This function returns the syntax table for BUFFER, which defaults
to the current buffer if omitted.
certain syntax classes. None of these functions exists in Emacs
version 18 or earlier.
- - Function: skip-syntax-forward SYNTAXES &optional LIMIT BUFFER
+ - Function: skip-syntax-forward syntaxes &optional limit buffer
This function moves point forward across characters having syntax
classes mentioned in SYNTAXES. It stops when it encounters the
end of the buffer, or position LIMIT (if specified), or a
character it is not supposed to skip. Optional argument BUFFER
defaults to the current buffer if omitted.
- - Function: skip-syntax-backward SYNTAXES &optional LIMIT BUFFER
+ - Function: skip-syntax-backward syntaxes &optional limit buffer
This function moves point backward across characters whose syntax
classes are mentioned in SYNTAXES. It stops when it encounters
the beginning of the buffer, or position LIMIT (if specified), or a
defaults to the current buffer if omitted.
- - Function: backward-prefix-chars &optional BUFFER
+ - Function: backward-prefix-chars &optional buffer
This function moves point backward over any number of characters
with expression prefix syntax. This includes both characters in
the expression prefix syntax class, and characters with the `p'
for C expressions when in C mode. *Note List Motion::, for convenient
higher-level functions for moving over balanced expressions.
- - Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH
- STOP-BEFORE STATE STOP-COMMENT BUFFER
+ - Function: parse-partial-sexp start limit &optional target-depth
+ stop-before state stop-comment buffer
This function parses a sexp in the current buffer starting at
START, not scanning past LIMIT. It stops at position LIMIT or
when certain criteria described below are met, and sets point to
This function is most often used to compute indentation for
languages that have nested parentheses.
- - Function: scan-lists FROM COUNT DEPTH &optional BUFFER NOERROR
+ - Function: scan-lists from count depth &optional buffer noerror
This function scans forward COUNT balanced parenthetical groupings
from character number FROM. It returns the character position
where the scan stops.
If optional arg NOERROR is non-`nil', `scan-lists' will return
`nil' instead of signalling an error.
- - Function: scan-sexps FROM COUNT &optional BUFFER NOERROR
+ - Function: scan-sexps from count &optional buffer noerror
This function scans forward COUNT sexps from character position
FROM. It returns the character position where the scan stops.
You can use `forward-comment' to move forward or backward over one
comment or several comments.
- - Function: forward-comment COUNT &optional BUFFER
+ - Function: forward-comment count &optional buffer
This function moves point forward across COUNT comments (backward,
if COUNT is negative). If it finds anything other than a comment
or whitespace, it stops, leaving point at the place where it
of one character: the syntax class, possible matching character, and
flags. Lisp programs don't usually work with the elements directly; the
Lisp-level syntax table functions usually work with syntax descriptors
-(*note Syntax Descriptors::.).
+(*note Syntax Descriptors::).
The low 8 bits of each element of a syntax table indicate the syntax
class.
An abbrev table is represented as an obarray containing a symbol for
each abbreviation. The symbol's name is the abbreviation; its value is
the expansion; its function definition is the hook function to do the
-expansion (*note Defining Abbrevs::.); its property list cell contains
+expansion (*note Defining Abbrevs::); its property list cell contains
the use count, the number of times the abbreviation has been expanded.
Because these symbols are not interned in the usual obarray, they will
never appear as the result of reading a Lisp expression; in fact,
This function creates and returns a new, empty abbrev table--an
obarray containing no symbols. It is a vector filled with zeros.
- - Function: clear-abbrev-table TABLE
+ - Function: clear-abbrev-table table
This function undefines all the abbrevs in abbrev table TABLE,
leaving it empty. The function returns `nil'.
- - Function: define-abbrev-table TABNAME DEFINITIONS
+ - Function: define-abbrev-table tabname definitions
This function defines TABNAME (a symbol) as an abbrev table name,
i.e., as a variable whose value is an abbrev table. It defines
abbrevs in the table according to DEFINITIONS, a list of elements
This is a list of symbols whose values are abbrev tables.
`define-abbrev-table' adds the new abbrev table name to this list.
- - Function: insert-abbrev-table-description NAME &optional HUMAN
+ - Function: insert-abbrev-table-description name &optional human
This function inserts before point a description of the abbrev
table named NAME. The argument NAME is a symbol whose value is an
abbrev table. The value is always `nil'.
`define-abbrev' is the low-level basic function, while `add-abbrev' is
used by commands that ask for information from the user.
- - Function: add-abbrev TABLE TYPE ARG
+ - Function: add-abbrev table type arg
This function adds an abbreviation to abbrev table TABLE based on
information from the user. The argument TYPE is a string
describing in English the kind of abbrev this will be (typically,
abbrev, or `nil' if the user declines to confirm redefining an
existing abbrev.
- - Function: define-abbrev TABLE NAME EXPANSION HOOK
+ - Function: define-abbrev table name expansion hook
This function defines an abbrev in TABLE named NAME, to expand to
EXPANSION, and call HOOK. The return value is an uninterned
symbol that represents the abbrev inside XEmacs; its name is NAME.
A file of saved abbrev definitions is actually a file of Lisp code.
The abbrevs are saved in the form of a Lisp program to define the same
abbrev tables with the same contents. Therefore, you can load the file
-with `load' (*note How Programs Do Loading::.). However, the function
+with `load' (*note How Programs Do Loading::). However, the function
`quietly-read-abbrev-file' is provided as a more convenient interface.
User-level facilities such as `save-some-buffers' can save abbrevs
- User Option: abbrev-file-name
This is the default file name for reading and saving abbrevs.
- - Function: quietly-read-abbrev-file FILENAME
+ - Function: quietly-read-abbrev-file filename
This function reads abbrev definitions from a file named FILENAME,
previously written with `write-abbrev-file'. If FILENAME is
`nil', the file specified in `abbrev-file-name' is used.
abbrevs. This serves as a flag for various XEmacs commands to
offer to save your abbrevs.
- - Command: write-abbrev-file FILENAME
+ - Command: write-abbrev-file filename
Save all abbrev definitions, in all abbrev tables, in the file
FILENAME, in the form of a Lisp program that when loaded will
define the same abbrevs. This function returns `nil'.
subroutines used in writing such functions, as well as the variables
they use for communication.
- - Function: abbrev-symbol ABBREV &optional TABLE
+ - Function: abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named
ABBREV. The value returned is `nil' if that abbrev is not
defined. The optional second argument TABLE is the abbrev table
the current buffer's local abbrev table, and second the global
abbrev table.
- - Function: abbrev-expansion ABBREV &optional TABLE
+ - Function: abbrev-expansion abbrev &optional table
This function returns the string that ABBREV would expand into (as
defined by the abbrev tables used for the current buffer). The
optional argument TABLE specifies the abbrev table to use, as in
does not follow an abbrev, this command does nothing. The command
returns `t' if it did expansion, `nil' otherwise.
- - Command: abbrev-prefix-mark &optional ARG
+ - Command: abbrev-prefix-mark &optional arg
Mark current point as the beginning of an abbrev. The next call to
`expand-abbrev' will use the text from here to point (where it is
then) as the abbrev to expand, rather than using the previous word
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
other. XEmacs efficiently handles buffers with large numbers of
extents in them.
- - Function: extentp OBJECT
+ - Function: extentp object
This returns `t' if OBJECT is an extent.
* Menu:
are invisible to functions that merely examine the text of a buffer or
string.
- *Please note:* An alternative way to add properties to a buffer or
+ _Please note:_ An alternative way to add properties to a buffer or
string is to use text properties. *Note Text Properties::.
An extent is logically a Lisp object consisting of a start position,
Creating and Modifying Extents
==============================
- - Function: make-extent FROM TO &optional OBJECT
+ - Function: make-extent from to &optional object
This function makes an extent for the range [FROM, TO) in OBJECT
(a buffer or string). OBJECT defaults to the current buffer.
Insertions at point TO will be outside of the extent; insertions
at FROM will be inside the extent, causing the extent to grow
- (*note Extent Endpoints::.). This is the same way that markers
+ (*note Extent Endpoints::). This is the same way that markers
behave. The extent is initially detached if both FROM and TO are
`nil', and in this case OBJECT defaults to `nil', meaning the
- extent is in no buffer or string (*note Detached Extents::.).
+ extent is in no buffer or string (*note Detached Extents::).
- - Function: delete-extent EXTENT
+ - Function: delete-extent extent
This function removes EXTENT from its buffer and destroys it.
This does not modify the buffer's text, only its display
properties. The extent cannot be used thereafter. To remove an
extent in such a way that it can be re-inserted later, use
`detach-extent'. *Note Detached Extents::.
- - Function: extent-object EXTENT
+ - Function: extent-object extent
This function returns the buffer or string that EXTENT is in. If
the return value is `nil', this means that the extent is detached;
however, a detached extent will not necessarily return a value of
`nil'.
- - Function: extent-live-p EXTENT
+ - Function: extent-live-p extent
This function returns `nil' if EXTENT is deleted, and `t'
otherwise.
Both endpoints can be equal, in which case the extent includes no
characters but still exists in the buffer or string. Zero-length
-extents are used to represent annotations (*note Annotations::.) and can
+extents are used to represent annotations (*note Annotations::) and can
be used as a more powerful form of a marker. Deletion of all the
characters in an extent may or may not result in a zero-length extent;
-this depends on the `detachable' property (*note Detached Extents::.).
+this depends on the `detachable' property (*note Detached Extents::).
Insertion at the position of a zero-length extent expands the extent if
both endpoints are closed; goes before the extent if it has the
`start-open' property; and goes after the extent if it has the
position, and then by decreasing end position (this is called the
"display order").
- - Function: extent-start-position EXTENT
+ - Function: extent-start-position extent
This function returns the start position of EXTENT.
- - Function: extent-end-position EXTENT
+ - Function: extent-end-position extent
This function returns the end position of EXTENT.
- - Function: extent-length EXTENT
+ - Function: extent-length extent
This function returns the length of EXTENT in characters. If the
extent is detached, this returns `0'. If the extent is not
detached, this is equivalent to
(- (extent-end-position EXTENT) (extent-start-position EXTENT))
- - Function: set-extent-endpoints EXTENT START END &optional
- BUFFER-OR-STRING
+ - Function: set-extent-endpoints extent start end &optional
+ buffer-or-string
This function sets the start and end position of EXTENT to START
and END. If both are `nil', this is equivalent to `detach-extent'.
The following functions provide a simple way of determining the
extents in a buffer or string. A number of more sophisticated
primitives for mapping over the extents in a range of a buffer or string
-are also provided (*note Mapping Over Extents::.). When reading through
+are also provided (*note Mapping Over Extents::). When reading through
this section, keep in mind the way that extents are ordered (*note
-Extent Endpoints::.).
+Extent Endpoints::).
- - Function: extent-list &optional BUFFER-OR-STRING FROM TO FLAGS
+ - Function: extent-list &optional buffer-or-string from to flags
This function returns a list of the extents in BUFFER-OR-STRING.
BUFFER-OR-STRING defaults to the current buffer if omitted. FROM
and TO can be used to limit the range over which extents are
extents by setting a particular property on them. The following
function makes it easier to locate those extents.
- - Function: extent-at POS &optional OBJECT PROPERTY BEFORE AT-FLAG
+ - Function: extent-at pos &optional object property before at-flag
This function finds the "smallest" extent (i.e., the last one in
the display order) at (i.e., overlapping) POS in OBJECT (a buffer
or string) having PROPERTY set. OBJECT defaults to the current
or loop using the BEFORE argument to `extent-at', rather than creating
a loop using `next-extent'.
- - Function: next-extent EXTENT
+ - Function: next-extent extent
Given an extent EXTENT, this function returns the next extent in
the buffer or string's display order. If EXTENT is a buffer or
string, this returns the first extent in the buffer or string.
- - Function: previous-extent EXTENT
+ - Function: previous-extent extent
Given an extent EXTENT, this function returns the previous extent
in the buffer or string's display order. If EXTENT is a buffer or
string, this returns the last extent in the buffer or string.
function to familiarize yourself with the concepts and optional
arguments involved. However, in practice you may find it more
convenient to use the function `mapcar-extents' or to create a loop
-using the `before' argument to `extent-at' (*note Finding Extents::.).
+using the `before' argument to `extent-at' (*note Finding Extents::).
- - Function: map-extents FUNCTION &optional OBJECT FROM TO MAPARG FLAGS
- PROPERTY VALUE
+ - Function: map-extents function &optional object from to maparg flags
+ property value
This function maps FUNCTION over the extents which overlap a
region in OBJECT. OBJECT is normally a buffer or string but could
be an extent (see below). The region is normally bounded by
region.
`negate-in-region'
- The condition specified by a `*-in-region' flag must *not*
+ The condition specified by a `*-in-region' flag must _not_
hold for the extent to be considered.
At most one of `all-extents-closed', `all-extents-open',
If you want to map over extents and accumulate a list of results,
the following function may be more convenient than `map-extents'.
- - Function: mapcar-extents FUNCTION &optional PREDICATE
- BUFFER-OR-STRING FROM TO FLAGS PROPERTY VALUE
+ - Function: mapcar-extents function &optional predicate
+ buffer-or-string from to flags property value
This function applies FUNCTION to all extents which overlap a
region in BUFFER-OR-STRING. The region is delimited by FROM and
TO. FUNCTION is called with one argument, the extent. A list of
VALUE may also be used to control the extents passed to PREDICATE
or FUNCTION, and have the same meaning as in `map-extents'.
- - Function: map-extent-children FUNCTION &optional OBJECT FROM TO
- MAPARG FLAGS PROPERTY VALUE
+ - Function: map-extent-children function &optional object from to
+ maparg flags property value
This function is similar to `map-extents', but differs in that:
* It only visits extents which start in the given region.
(defun walk-extents (buffer &optional ignore)
(map-extent-children 'walk-extents buffer))
- - Function: extent-in-region-p EXTENT &optional FROM TO FLAGS
+ - Function: extent-in-region-p extent &optional from to flags
This function returns T if `map-extents' would visit EXTENT if
called with the given arguments.
parent), and setting a property of the extent actually sets that
property on the parent. *Note Extent Parents::.
- - Function: extent-property EXTENT PROPERTY
+ - Function: extent-property extent property
This function returns the value of PROPERTY in EXTENT. If
PROPERTY is undefined, `nil' is returned.
- - Function: extent-properties EXTENT
+ - Function: extent-properties extent
This function returns a list of all of EXTENT's properties that do
not have the value of `nil' (or the default value, for properties
with predefined meanings).
- - Function: set-extent-property EXTENT PROPERTY VALUE
+ - Function: set-extent-property extent property value
This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
predefined meaning, only certain values are allowed, and some
values may be converted to others before being stored.)
- - Function: set-extent-properties EXTENT PLIST
+ - Function: set-extent-properties extent plist
Change some properties of EXTENT. PLIST is a property list. This
is useful to change many extent properties at once.
The following convenience functions are provided for accessing
particular properties of an extent.
- - Function: extent-face EXTENT
+ - Function: extent-face extent
This function returns the `face' property of EXTENT. This might
also return a list of face names. Do not modify this list
directly! Instead, use `set-extent-face'.
the return value of `extent-face' on the two extents will return
the identical list.
- - Function: extent-mouse-face EXTENT
+ - Function: extent-mouse-face extent
This function returns the `mouse-face' property of EXTENT. This
might also return a list of face names. Do not modify this list
directly! Instead, use `set-extent-mouse-face'.
Note that you can use `eq' to compare lists of faces as returned
by `extent-mouse-face', just like for `extent-face'.
- - Function: extent-priority EXTENT
+ - Function: extent-priority extent
This function returns the `priority' property of EXTENT.
- - Function: extent-keymap EXTENT
+ - Function: extent-keymap extent
This function returns the `keymap' property of EXTENT.
- - Function: extent-begin-glyph-layout EXTENT
+ - Function: extent-begin-glyph-layout extent
This function returns the `begin-glyph-layout' property of EXTENT,
i.e. the layout policy associated with the EXTENT's begin glyph.
- - Function: extent-end-glyph-layout EXTENT
+ - Function: extent-end-glyph-layout extent
This function returns the `end-glyph-layout' property of EXTENT,
i.e. the layout policy associated with the EXTENT's end glyph.
- - Function: extent-begin-glyph EXTENT
+ - Function: extent-begin-glyph extent
This function returns the `begin-glyph' property of EXTENT, i.e.
the glyph object displayed at the beginning of EXTENT. If there
is none, `nil' is returned.
- - Function: extent-end-glyph EXTENT
+ - Function: extent-end-glyph extent
This function returns the `end-glyph' property of EXTENT, i.e. the
glyph object displayed at the end of EXTENT. If there is none,
`nil' is returned.
The following convenience functions are provided for setting
particular properties of an extent.
- - Function: set-extent-priority EXTENT PRI
+ - Function: set-extent-priority extent pri
This function sets the `priority' property of EXTENT to PRI.
- - Function: set-extent-face EXTENT FACE
+ - Function: set-extent-face extent face
This function sets the `face' property of EXTENT to FACE.
- - Function: set-extent-mouse-face EXTENT FACE
+ - Function: set-extent-mouse-face extent face
This function sets the `mouse-face' property of EXTENT to FACE.
- - Function: set-extent-keymap EXTENT KEYMAP
+ - Function: set-extent-keymap extent keymap
This function sets the `keymap' property of EXTENT to KEYMAP.
KEYMAP must be either a keymap object, or `nil'.
- - Function: set-extent-begin-glyph-layout EXTENT LAYOUT
+ - Function: set-extent-begin-glyph-layout extent layout
This function sets the `begin-glyph-layout' property of EXTENT to
LAYOUT.
- - Function: set-extent-end-glyph-layout EXTENT LAYOUT
+ - Function: set-extent-end-glyph-layout extent layout
This function sets the `end-glyph-layout' property of EXTENT to
LAYOUT.
- - Function: set-extent-begin-glyph EXTENT BEGIN-GLYPH &optional LAYOUT
+ - Function: set-extent-begin-glyph extent begin-glyph &optional layout
This function sets the `begin-glyph' and `glyph-layout' properties
of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
defaults to `text' if not specified.)
- - Function: set-extent-end-glyph EXTENT END-GLYPH &optional LAYOUT
+ - Function: set-extent-end-glyph extent end-glyph &optional layout
This function sets the `end-glyph' and `glyph-layout' properties
of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
to `text' if not specified.)
- - Function: set-extent-initial-redisplay-function EXTENT FUNCTION
+ - Function: set-extent-initial-redisplay-function extent function
This function sets the `initial-redisplay-function' property of the
extent to FUNCTION.
(Zero-length extents with the `detachable' property set behave
specially. *Note zero-length extents: Extent Endpoints.)
- - Function: detach-extent EXTENT
+ - Function: detach-extent extent
This function detaches EXTENT from its buffer or string. If
EXTENT has the `duplicable' property, its detachment is tracked by
the undo mechanism. *Note Duplicable Extents::.
- - Function: extent-detached-p EXTENT
+ - Function: extent-detached-p extent
This function returns `nil' if EXTENT is detached, and `t'
otherwise.
- - Function: copy-extent EXTENT &optional OBJECT
+ - Function: copy-extent extent &optional object
This function makes a copy of EXTENT. It is initially detached.
Optional argument OBJECT defaults to EXTENT's object (normally a
buffer or string, but could be `nil').
- - Function: insert-extent EXTENT &optional START END NO-HOOKS OBJECT
+ - Function: insert-extent extent &optional start end no-hooks object
This function inserts EXTENT from START to END in OBJECT (a buffer
or string). If EXTENT is detached from a different buffer or
string, or in most cases when EXTENT is already attached, the
Parent extents are used to implement the extents over the modeline.
- - Function: set-extent-parent EXTENT PARENT
+ - Function: set-extent-parent extent parent
This function sets the parent of EXTENT to PARENT. If PARENT is
`nil', the extent is set to have no parent.
- - Function: extent-parent EXTENT
+ - Function: extent-parent extent
This function return the parents (if any) of EXTENT, or `nil'.
- - Function: extent-children EXTENT
+ - Function: extent-children extent
This function returns a list of the children (if any) of EXTENT.
The children of an extent are all those extents whose parent is
that extent. This function does not recursively trace children of
children.
- - Function: extent-descendants EXTENT
+ - Function: extent-descendants extent
This function returns a list of all descendants of EXTENT,
including EXTENT. This recursively applies `extent-children' to
any children of EXTENT, until no more children can be found.
* When a string is created using `buffer-substring' or
`buffer-string', any duplicable extents in the region corresponding
to the string will be copied into the string (*note Buffer
- Contents::.). When the string in inserted into a buffer using
+ Contents::). When the string in inserted into a buffer using
`insert', `insert-before-markers', `insert-buffer' or
`insert-buffer-substring', the extents in the string will be copied
- back into the buffer (*note Insertion::.). The extents in a
- string can, of course, be retrieved explicitly using the standard
- extent primitives over the string.
+ back into the buffer (*note Insertion::). The extents in a string
+ can, of course, be retrieved explicitly using the standard extent
+ primitives over the string.
* Similarly, when text is copied or cut into the kill ring, any
duplicable extents will be remembered and reinserted later when
by merging the extent's face with the face or faces specified by the
`mouse-face' property. The effect is as if a pseudo-extent with the
`mouse-face' face were inserted after the extent in the display order
-(*note Extent Endpoints::., display order).
+(*note Extent Endpoints::, display order).
- Variable: mouse-highlight-priority
This variable holds the priority to use when merging in the
extent at a time can be highlighted in this fashion, and any other
highlighted extent will be de-highlighted.
- - Function: highlight-extent EXTENT &optional HIGHLIGHT-P
+ - Function: highlight-extent extent &optional highlight-p
This function highlights (if HIGHLIGHT-P is non-`nil') or
de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
`mouse-face' property. (Nothing happens if EXTENT does not have
the `mouse-face' property.)
- - Function: force-highlight-extent EXTENT &optional HIGHLIGHT-P
+ - Function: force-highlight-extent extent &optional highlight-p
This function is similar to `highlight-extent' but highlights or
de-highlights the extent regardless of whether it has the
`mouse-face' property.
specifier object, in turn, is "instanced" in a particular situation to
yield the real value of the property in that situation.
- - Function: specifierp OBJECT
+ - Function: specifierp object
This function returns non-`nil' if OBJECT is a specifier.
* Menu:
(under user control) in a wide variety
of contexts.
* Specifiers In-Depth:: Gory details about specifier innards.
-* Specifier Instancing:: Instancing means obtaining the "value" of
+* Specifier Instancing:: Instancing means obtaining the ``value'' of
a specifier in a particular context.
* Specifier Types:: Specifiers come in different flavors.
-* Adding Specifications:: Specifications control a specifier's "value"
+* Adding Specifications:: Specifications control a specifier's ``value''
by giving conditions under which a
particular value is valid.
* Retrieving Specifications:: Querying a specifier's specifications.
The valid device types (normally `x', `tty', and `stream') and
device classes (normally `color', `grayscale', and `mono') can always
be used as tags, and match devices of the associated type or class
-(*note Consoles and Devices::.). User-defined tags may be defined,
-with an optional predicate specified. An application can create its
-own tag, use it to mark all its instantiators, and be fairly confident
-that it will not interfere with other applications that modify the same
+(*note Consoles and Devices::). User-defined tags may be defined, with
+an optional predicate specified. An application can create its own
+tag, use it to mark all its instantiators, and be fairly confident that
+it will not interfere with other applications that modify the same
specifier - Functions that add a specification to a specifier usually
only overwrite existing inst-pairs with the same tag set as was given,
and a particular tag or tag set can be specified when removing
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
information about image specifiers. *Note Toolbar::, for more
information on toolbar specifiers.
- - Function: specifier-type SPECIFIER
+ - Function: specifier-type specifier
This function returns the type of SPECIFIER. The returned value
will be a symbol: one of `integer', `boolean', etc., as listed in
the above table.
Functions are also provided to query whether an object is a
particular kind of specifier:
- - Function: boolean-specifier-p OBJECT
+ - Function: boolean-specifier-p object
This function returns non-`nil' if OBJECT is a boolean specifier.
- - Function: integer-specifier-p OBJECT
+ - Function: integer-specifier-p object
This function returns non-`nil' if OBJECT is an integer specifier.
- - Function: natnum-specifier-p OBJECT
+ - Function: natnum-specifier-p object
This function returns non-`nil' if OBJECT is a natnum specifier.
- - Function: generic-specifier-p OBJECT
+ - Function: generic-specifier-p object
This function returns non-`nil' if OBJECT is a generic specifier.
- - Function: face-boolean-specifier-p OBJECT
+ - Function: face-boolean-specifier-p object
This function returns non-`nil' if OBJECT is a face-boolean
specifier.
- - Function: toolbar-specifier-p OBJECT
+ - Function: toolbar-specifier-p object
This function returns non-`nil' if OBJECT is a toolbar specifier.
- - Function: font-specifier-p OBJECT
+ - Function: font-specifier-p object
This function returns non-`nil' if OBJECT is a font specifier.
- - Function: color-specifier-p OBJECT
+ - Function: color-specifier-p object
This function returns non-`nil' if OBJECT is a color specifier.
- - Function: image-specifier-p OBJECT
+ - Function: image-specifier-p object
This function returns non-`nil' if OBJECT is an image specifier.
\1f
Adding specifications to a Specifier
====================================
- - Function: add-spec-to-specifier SPECIFIER INSTANTIATOR &optional
- LOCALE TAG-SET HOW-TO-ADD
+ - Function: add-spec-to-specifier specifier instantiator &optional
+ locale tag-set how-to-add
This function adds a specification to SPECIFIER. The
specification maps from LOCALE (which should be a window, buffer,
frame, device, or the symbol `global', and defaults to `global')
locale type with the function `specifier-spec-list' or
`specifier-specs'.
- - Function: add-spec-list-to-specifier SPECIFIER SPEC-LIST &optional
- HOW-TO-ADD
+ - Function: add-spec-list-to-specifier specifier spec-list &optional
+ how-to-add
This function adds a "spec-list" (a list of specifications) to
SPECIFIER. The format of a spec-list is
* TAG-SET := an unordered list of zero or more TAGS, each of
which is a symbol
- * TAG := a device class (*note Consoles and Devices::.), a
+ * TAG := a device class (*note Consoles and Devices::), a
device type, or a tag defined with `define-specifier-tag'
* INSTANTIATOR := format determined by the type of specifier
In many circumstances, the higher-level function `set-specifier' is
more convenient and should be used instead.
- - Macro: let-specifier SPECIFIER-LIST &rest BODY
+ - Macro: let-specifier specifier-list &rest body
This special form temporarily adds specifications to specifiers,
evaluates forms in BODY and restores the specifiers to their
previous states. The specifiers and their temporary
(let-specifier ((modeline-shadow-thickness 0 (selected-window)))
(sit-for 1))
- - Function: set-specifier SPECIFIER VALUE &optional HOW-TO-ADD
+ - Function: set-specifier specifier value &optional how-to-add
This function adds some specifications to SPECIFIER. VALUE can be
a single instantiator or tagged instantiator (added as a global
specification), a list of tagged and/or untagged instantiators
functions always work with fully-qualified spec-lists; thus, there
is no ambiguity.
- - Function: canonicalize-inst-pair INST-PAIR SPECIFIER-TYPE &optional
- NOERROR
+ - Function: canonicalize-inst-pair inst-pair specifier-type &optional
+ noerror
This function canonicalizes the given INST-PAIR.
SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
If NOERROR is non-`nil', signal an error if the inst-pair is
invalid; otherwise return `t'.
- - Function: canonicalize-inst-list INST-LIST SPECIFIER-TYPE &optional
- NOERROR
+ - Function: canonicalize-inst-list inst-list specifier-type &optional
+ noerror
This function canonicalizes the given INST-LIST (a list of
inst-pairs).
If NOERROR is non-`nil', signal an error if the inst-list is
invalid; otherwise return `t'.
- - Function: canonicalize-spec SPEC SPECIFIER-TYPE &optional NOERROR
+ - Function: canonicalize-spec spec specifier-type &optional noerror
This function canonicalizes the given SPEC (a specification).
SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
If NOERROR is `nil', signal an error if the specification is
invalid; otherwise return `t'.
- - Function: canonicalize-spec-list SPEC-LIST SPECIFIER-TYPE &optional
- NOERROR
+ - Function: canonicalize-spec-list spec-list specifier-type &optional
+ noerror
This function canonicalizes the given SPEC-LIST (a list of
specifications).
Retrieving the Specifications from a Specifier
==============================================
- - Function: specifier-spec-list SPECIFIER &optional LOCALE TAG-SET
- EXACT-P
+ - Function: specifier-spec-list specifier &optional locale tag-set
+ exact-p
This function returns the spec-list of specifications for
SPECIFIER in LOCALE.
is non-`nil', however, TAG-SET must be equal to an instantiator's
tag set for the instantiator to be returned.
- - Function: specifier-specs SPECIFIER &optional LOCALE TAG-SET EXACT-P
+ - Function: specifier-specs specifier &optional locale tag-set exact-p
This function returns the specification(s) for SPECIFIER in LOCALE.
If LOCALE is a single locale or is a list of one element
from there being no instantiators at all.
- - Function: specifier-fallback SPECIFIER
+ - Function: specifier-fallback specifier
This function returns the fallback value for SPECIFIER. Fallback
values are provided by the C code for certain built-in specifiers
to make sure that instancing won't fail even if all specs are
Most of the time, a tag set is not specified, and the instantiator
gets a null tag set, which matches all devices.
- - Function: valid-specifier-tag-p TAG
+ - Function: valid-specifier-tag-p tag
This function returns non-`nil' if TAG is a valid specifier tag.
- - Function: valid-specifier-tag-set-p TAG-SET
+ - Function: valid-specifier-tag-set-p tag-set
This function returns non-`nil' if TAG-SET is a valid specifier
tag set.
- - Function: canonicalize-tag-set TAG-SET
+ - Function: canonicalize-tag-set tag-set
This function canonicalizes the given tag set. Two canonicalized
tag sets can be compared with `equal' to see if they represent the
same tag set. (Specifically, canonicalizing involves sorting by
symbol name and removing duplicates.)
- - Function: device-matches-specifier-tag-set-p DEVICE TAG-SET
+ - Function: device-matches-specifier-tag-set-p device tag-set
This function returns non-`nil' if DEVICE matches specifier tag
set TAG-SET. This means that DEVICE matches each tag in the tag
set.
- - Function: define-specifier-tag TAG &optional PREDICATE
+ - Function: define-specifier-tag tag &optional predicate
This function defines a new specifier tag. If PREDICATE is
specified, it should be a function of one argument (a device) that
specifies whether the tag matches that particular device. If
you cannot redefine the built-in specifier tags (the device types
and classes) or the symbols `nil', `t', `all', or `global'.
- - Function: device-matching-specifier-tag-list &optional DEVICE
+ - Function: device-matching-specifier-tag-list &optional device
This function returns a list of all specifier tags matching
DEVICE. DEVICE defaults to the selected device if omitted.
tags. This includes the built-in ones (the device types and
classes).
- - Function: specifier-tag-predicate TAG
+ - Function: specifier-tag-predicate tag
This function returns the predicate for the given specifier tag.
\1f
Functions for Instancing a Specifier
====================================
- - Function: specifier-instance SPECIFIER &optional DOMAIN DEFAULT
- NO-FALLBACK
+ - Function: specifier-instance specifier &optional domain default
+ no-fallback
This function instantiates SPECIFIER (return its value) in DOMAIN.
If no instance can be generated for this domain, return DEFAULT.
function), the returned value will be a font-instance object. For
images, the returned value will be a string, pixmap, or subwindow.
- - Function: specifier-instance-from-inst-list SPECIFIER DOMAIN
- INST-LIST &optional DEFAULT
+ - Function: specifier-instance-from-inst-list specifier domain
+ inst-list &optional default
This function attempts to convert a particular inst-list into an
instance. This attempts to instantiate INST-LIST in the given
DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
Creating New Specifier Objects
==============================
- - Function: make-specifier TYPE
+ - Function: make-specifier type
This function creates a new specifier.
A specifier is an object that can be used to keep track of a
`font-specifier-p', `image-specifier-p',
`face-boolean-specifier-p', and `toolbar-specifier-p'.
- - Function: make-specifier-and-init TYPE SPEC-LIST &optional
- DONT-CANONICALIZE
+ - Function: make-specifier-and-init type spec-list &optional
+ dont-canonicalize
This function creates and initialize a new specifier.
This is a front-end onto `make-specifier' that allows you to create
Functions for Checking the Validity of Specifier Components
===========================================================
- - Function: valid-specifier-domain-p DOMAIN
+ - Function: valid-specifier-domain-p domain
This function returns non-`nil' if DOMAIN is a valid specifier
domain. A domain is used to instance a specifier (i.e. determine
the specifier's value in that domain). Valid domains are a
window, frame, or device. (`nil' is not valid.)
- - Function: valid-specifier-locale-p LOCALE
+ - Function: valid-specifier-locale-p locale
This function returns non-`nil' if LOCALE is a valid specifier
locale. Valid locales are a device, a frame, a window, a buffer,
and `global'. (`nil' is not valid.)
- - Function: valid-specifier-locale-type-p LOCALE-TYPE
+ - Function: valid-specifier-locale-type-p locale-type
Given a specifier LOCALE-TYPE, this function returns non-nil if it
is valid. Valid locale types are the symbols `global', `device',
`frame', `window', and `buffer'. (Note, however, that in functions
that accept either a locale or a locale type, `global' is
considered an individual locale.)
- - Function: valid-specifier-type-p SPECIFIER-TYPE
+ - Function: valid-specifier-type-p specifier-type
Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
valid. Valid types are `generic', `integer', `boolean', `color',
`font', `image', `face-boolean', and `toolbar'.
- - Function: valid-specifier-tag-p TAG
+ - Function: valid-specifier-tag-p tag
This function returns non-`nil' if TAG is a valid specifier tag.
- - Function: valid-instantiator-p INSTANTIATOR SPECIFIER-TYPE
+ - Function: valid-instantiator-p instantiator specifier-type
This function returns non-`nil' if INSTANTIATOR is valid for
SPECIFIER-TYPE.
- - Function: valid-inst-list-p INST-LIST TYPE
+ - Function: valid-inst-list-p inst-list type
This function returns non-`nil' if INST-LIST is valid for
specifier type TYPE.
- - Function: valid-spec-list-p SPEC-LIST TYPE
+ - Function: valid-spec-list-p spec-list type
This function returns non-`nil' if SPEC-LIST is valid for
specifier type TYPE.
- - Function: check-valid-instantiator INSTANTIATOR SPECIFIER-TYPE
+ - Function: check-valid-instantiator instantiator specifier-type
This function signals an error if INSTANTIATOR is invalid for
SPECIFIER-TYPE.
- - Function: check-valid-inst-list INST-LIST TYPE
+ - Function: check-valid-inst-list inst-list type
This function signals an error if INST-LIST is invalid for
specifier type TYPE.
- - Function: check-valid-spec-list SPEC-LIST TYPE
+ - Function: check-valid-spec-list spec-list type
This function signals an error if SPEC-LIST is invalid for
specifier type TYPE.
Other Functions for Working with Specifications in a Specifier
==============================================================
- - Function: copy-specifier SPECIFIER &optional DEST LOCALE TAG-SET
- EXACT-P HOW-TO-ADD
+ - Function: copy-specifier specifier &optional dest locale tag-set
+ exact-p how-to-add
This function copies SPECIFIER to DEST, or creates a new one if
DEST is `nil'.
types are copied will first be completely erased in DEST.
Otherwise, it is the same as in `add-spec-to-specifier'.
- - Function: remove-specifier SPECIFIER &optional LOCALE TAG-SET EXACT-P
+ - Function: remove-specifier specifier &optional locale tag-set exact-p
This function removes specification(s) for SPECIFIER.
If LOCALE is a particular locale (a buffer, window, frame, device,
is non-`nil', however, TAG-SET must be equal to an instantiator's
tag set for the instantiator to be removed.
- - Function: map-specifier SPECIFIER FUNC &optional LOCALE MAPARG
+ - Function: map-specifier specifier func &optional locale maparg
This function applies FUNC to the specification(s) for LOCALE in
SPECIFIER.
will stop and the returned value becomes the value returned from
`map-specifier'. Otherwise, `map-specifier' returns `nil'.
- - Function: specifier-locale-type-from-locale LOCALE
+ - Function: specifier-locale-type-from-locale locale
Given a specifier LOCALE, this function returns its type.
\1f
The face named `default' is used for ordinary text. The face named
`modeline' is used for displaying the modeline. The face named
-`highlight' is used for highlighted extents (*note Extents::.). The
+`highlight' is used for highlighted extents (*note Extents::). The
faces named `left-margin' and `right-margin' are used for the left and
-right margin areas, respectively (*note Annotations::.). The face
-named `zmacs-region' is used for the highlighted region between point
-and mark.
+right margin areas, respectively (*note Annotations::). The face named
+`zmacs-region' is used for the highlighted region between point and
+mark.
* Menu:
Here are the basic primitives for working with faces.
- - Function: make-face NAME &optional DOC-STRING TEMPORARY
+ - Function: make-face name &optional doc-string temporary
This function defines and returns a new face named NAME, initially
with all properties unspecified. It does nothing if there is
already a face named NAME. Optional argument DOC-STRING specifies
or Lisp code (otherwise, the face will continue to exist
indefinitely even if it is not used).
- - Function: face-list &optional TEMPORARY
+ - Function: face-list &optional temporary
This function returns a list of the names of all defined faces. If
TEMPORARY is `nil', only the permanent faces are included. If it
is `t', only the temporary faces are included. If it is any other
non-`nil' value both permanent and temporary are included.
- - Function: facep OBJECT
+ - Function: facep object
This function returns whether the given object is a face.
- - Function: copy-face OLD-FACE NEW-NAME &optional LOCALE HOW-TO-ADD
+ - Function: copy-face old-face new-name &optional locale how-to-add
This function defines a new face named NEW-NAME which is a copy of
the existing face named OLD-FACE. If there is already a face
named NEW-NAME, then it alters the face to have the same
properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just
parts of the old face rather than the whole face, and are as in
- `copy-specifier' (*note Specifiers::.).
+ `copy-specifier' (*note Specifiers::).
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
specifier, unlike all the other built-in properties, and cannot
contain locale-specific values.
- - Function: set-face-property FACE PROPERTY VALUE &optional LOCALE TAG
- HOW-TO-ADD
+ - Function: set-face-property face property value &optional locale tag
+ how-to-add
This function changes a property of a FACE.
For built-in properties, the actual value of the property is a
If the value of the property is not a specifier, it will
automatically be converted into a `generic' specifier.
- - Function: face-property FACE PROPERTY &optional LOCALE
+ - Function: face-property face property &optional locale
This function returns FACE's value of the given PROPERTY.
If LOCALE is omitted, the FACE's actual value for PROPERTY will be
`face-property-instance' actually does all this, and is used to
determine how to display the face.
- - Function: face-property-instance FACE PROPERTY &optional DOMAIN
- DEFAULT NO-FALLBACK
+ - Function: face-property-instance face property &optional domain
+ default no-fallback
This function returns the instance of FACE's PROPERTY in the
specified DOMAIN.
Face Convenience Functions
--------------------------
- - Function: set-face-foreground FACE COLOR &optional LOCALE TAG
- HOW-TO-ADD
- - Function: set-face-background FACE COLOR &optional LOCALE TAG
- HOW-TO-ADD
+ - Function: set-face-foreground face color &optional locale tag
+ how-to-add
+ - Function: set-face-background face color &optional locale tag
+ how-to-add
These functions set the foreground (respectively, background)
color of face FACE to COLOR. The argument COLOR should be a
string (the name of a color) or a color object as returned by
- `make-color' (*note Colors::.).
+ `make-color' (*note Colors::).
- - Function: set-face-background-pixmap FACE PIXMAP &optional LOCALE
- TAG HOW-TO-ADD
+ - Function: set-face-background-pixmap face pixmap &optional locale
+ tag how-to-add
This function sets the background pixmap of face FACE to PIXMAP.
The argument PIXMAP should be a string (the name of a bitmap or
pixmap file; the directories listed in the variable
`x-bitmap-file-path' will be searched) or a glyph object as
- returned by `make-glyph' (*note Glyphs::.). The argument may also
+ returned by `make-glyph' (*note Glyphs::). The argument may also
be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
are the size in pixels, and DATA is a string, containing the raw
bits of the bitmap.
- - Function: set-face-font FACE FONT &optional LOCALE TAG HOW-TO-ADD
+ - Function: set-face-font face font &optional locale tag how-to-add
This function sets the font of face FACE. The argument FONT
should be a string or a font object as returned by `make-font'
- (*note Fonts::.).
+ (*note Fonts::).
- - Function: set-face-underline-p FACE UNDERLINE-P &optional LOCALE TAG
- HOW-TO-ADD
+ - Function: set-face-underline-p face underline-p &optional locale tag
+ how-to-add
This function sets the underline property of face FACE.
- - Function: face-foreground FACE &optional LOCALE
- - Function: face-background FACE &optional LOCALE
+ - Function: face-foreground face &optional locale
+ - Function: face-background face &optional locale
These functions return the foreground (respectively, background)
color specifier of face FACE. *Note Colors::.
- - Function: face-background-pixmap FACE &optional LOCALE
+ - Function: face-background-pixmap face &optional locale
This function return the background-pixmap glyph object of face
FACE.
- - Function: face-font FACE &optional LOCALE
+ - Function: face-font face &optional locale
This function returns the font specifier of face FACE. (Note:
This is not the same as the function `face-font' in FSF Emacs.)
*Note Fonts::.
- - Function: face-font-name FACE &optional DOMAIN
+ - Function: face-font-name face &optional domain
This function returns the name of the font of face FACE, or `nil'
if it is unspecified. This is basically equivalent to `(font-name
(face-font FACE) DOMAIN)' except that it does not cause an error
if FACE's font is `nil'. (This function is named `face-font' in
FSF Emacs.)
- - Function: face-underline-p FACE &optional LOCALE
+ - Function: face-underline-p face &optional locale
This function returns the underline property of face FACE.
- - Function: face-foreground-instance FACE &optional DOMAIN
- - Function: face-background-instance FACE &optional DOMAIN
+ - Function: face-foreground-instance face &optional domain
+ - Function: face-background-instance face &optional domain
These functions return the foreground (respectively, background)
color specifier of face FACE. *Note Colors::.
- - Function: face-background-pixmap-instance FACE &optional DOMAIN
+ - Function: face-background-pixmap-instance face &optional domain
This function return the background-pixmap glyph object of face
FACE.
- - Function: face-font-instance FACE &optional DOMAIN
+ - Function: face-font-instance face &optional domain
This function returns the font specifier of face FACE. *Note
Fonts::.
Other Face Display Functions
----------------------------
- - Function: invert-face FACE &optional LOCALE
+ - Function: invert-face face &optional locale
Swap the foreground and background colors of face FACE. If the
face doesn't specify both foreground and background, then its
foreground and background are set to the default background and
foreground.
- - Function: face-equal FACE1 FACE2 &optional DOMAIN
+ - Function: face-equal face1 face2 &optional domain
This returns `t' if the faces FACE1 and FACE2 will display in the
same way. DOMAIN is as in `face-property-instance'.
- - Function: face-differs-from-default-p FACE &optional DOMAIN
+ - Function: face-differs-from-default-p face &optional domain
This returns `t' if the face FACE displays differently from the
default face. DOMAIN is as in `face-property-instance'.
Font Specifiers
---------------
- - Function: font-specifier-p OBJECT
+ - Function: font-specifier-p object
This predicate returns `t' if OBJECT is a font specifier, and
`nil' otherwise.
Font Instances
--------------
- - Function: font-instance-p OBJECT
+ - Function: font-instance-p object
This predicate returns `t' if OBJECT is a font instance, and `nil'
otherwise.
- - Function: make-font-instance NAME &optional DEVICE NOERROR
+ - Function: make-font-instance name &optional device noerror
This function creates a new font-instance object of the specified
name. DEVICE specifies the device this object applies to and
defaults to the selected device. An error is signalled if the
Font Instance Names
-------------------
- - Function: list-fonts PATTERN &optional DEVICE
+ - Function: list-fonts pattern &optional device
This function returns a list of font names matching the given
pattern. DEVICE specifies which device to search for names, and
defaults to the currently selected device.
- - Function: font-instance-name FONT-INSTANCE
+ - Function: font-instance-name font-instance
This function returns the name used to allocate FONT-INSTANCE.
- - Function: font-instance-truename FONT-INSTANCE
+ - Function: font-instance-truename font-instance
This function returns the canonical name of the given font
instance. Font names are patterns which may match any number of
fonts, of which the first found is used. This returns an
Font Instance Size
------------------
- - Function: x-font-size FONT
+ - Function: x-font-size font
This function returns the nominal size of the given font. This is
done by parsing its name, so it's likely to lose. X fonts can be
specified (by the user) in either pixels or 10ths of points, and
this returns the first one it finds, so you have to decide which
units the returned value is measured in yourself ...
- - Function: x-find-larger-font FONT &optional DEVICE
+ - Function: x-find-larger-font font &optional device
This function loads a new, slightly larger version of the given
font (or font name). Returns the font if it succeeds, `nil'
otherwise. If scalable fonts are available, this returns a font
which is 1 point larger. Otherwise, it returns the next larger
version of this font that is defined.
- - Function: x-find-smaller-font FONT &optional DEVICE
+ - Function: x-find-smaller-font font &optional device
This function loads a new, slightly smaller version of the given
font (or font name). Returns the font if it succeeds, `nil'
otherwise. If scalable fonts are available, this returns a font
Font Instance Characteristics
-----------------------------
- - Function: font-instance-properties FONT
+ - Function: font-instance-properties font
This function returns the properties (an alist or `nil') of
FONT-INSTANCE.
- - Function: x-make-font-bold FONT &optional DEVICE
+ - Function: x-make-font-bold font &optional device
Given an X font specification, this attempts to make a "bold" font.
If it fails, it returns `nil'.
- - Function: x-make-font-unbold FONT &optional DEVICE
+ - Function: x-make-font-unbold font &optional device
Given an X font specification, this attempts to make a non-bold
font. If it fails, it returns `nil'.
- - Function: x-make-font-italic FONT &optional DEVICE
+ - Function: x-make-font-italic font &optional device
Given an X font specification, this attempts to make an "italic"
font. If it fails, it returns `nil'.
- - Function: x-make-font-unitalic FONT &optional DEVICE
+ - Function: x-make-font-unitalic font &optional device
Given an X font specification, this attempts to make a non-italic
font. If it fails, it returns `nil'.
- - Function: x-make-font-bold-italic FONT &optional DEVICE
+ - Function: x-make-font-bold-italic font &optional device
Given an X font specification, this attempts to make a
"bold-italic" font. If it fails, it returns `nil'.
Font Convenience Functions
--------------------------
- - Function: font-name FONT &optional DOMAIN
+ - Function: font-name font &optional domain
This function returns the name of the FONT in the specified
DOMAIN, if any. FONT should be a font specifier object and DOMAIN
is normally a window and defaults to the selected window if
omitted. This is equivalent to using `specifier-instance' and
applying `font-instance-name' to the result.
- - Function: font-truename FONT &optional DOMAIN
+ - Function: font-truename font &optional domain
This function returns the truename of the FONT in the specified
DOMAIN, if any. FONT should be a font specifier object and DOMAIN
is normally a window and defaults to the selected window if
omitted. This is equivalent to using `specifier-instance' and
applying `font-instance-truename' to the result.
- - Function: font-properties FONT &optional DOMAIN
+ - Function: font-properties font &optional domain
This function returns the properties of the FONT in the specified
DOMAIN, if any. FONT should be a font specifier object and DOMAIN
is normally a window and defaults to the selected window if
Color Specifiers
----------------
- - Function: color-specifier-p OBJECT
+ - Function: color-specifier-p object
This function returns non-`nil' if OBJECT is a color specifier.
\1f
color of the `default' face is displayed in the next window after the
selected one.
- - Function: color-instance-p OBJECT
+ - Function: color-instance-p object
This function returns non-`nil' if OBJECT is a color-instance.
\1f
Color Instance Properties
-------------------------
- - Function: color-instance-name COLOR-INSTANCE
+ - Function: color-instance-name color-instance
This function returns the name used to allocate COLOR-INSTANCE.
- - Function: color-instance-rgb-components COLOR-INSTANCE
+ - Function: color-instance-rgb-components color-instance
This function returns a three element list containing the red,
green, and blue color components of COLOR-INSTANCE.
Color Convenience Functions
---------------------------
- - Function: color-name COLOR &optional DOMAIN
+ - Function: color-name color &optional domain
This function returns the name of the COLOR in the specified
DOMAIN, if any. COLOR should be a color specifier object and
DOMAIN is normally a window and defaults to the selected window if
omitted. This is equivalent to using `specifier-instance' and
applying `color-instance-name' to the result.
- - Function: color-rgb-components COLOR &optional DOMAIN
+ - Function: color-rgb-components color &optional domain
This function returns the RGB components of the COLOR in the
specified DOMAIN, if any. COLOR should be a color specifier
object and DOMAIN is normally a window and defaults to the
just the actual image: e.g. the face it is displayed in (for text
images), the alignment of the image (when it is in a buffer), etc.
- - Function: glyphp OBJECT
+ - Function: glyphp object
This function returns `t' if OBJECT is a glyph.
* Menu:
Creating Glyphs
---------------
- - Function: make-glyph &optional SPEC-LIST TYPE
+ - Function: make-glyph &optional spec-list type
This function creates a new glyph object of type TYPE.
SPEC-LIST is used to initialize the glyph's image. It is
for the mouse-pointer), or `icon' (used for a frame's icon), and
defaults to `buffer'. *Note Glyph Types::.
- - Function: make-glyph-internal &optional TYPE
+ - Function: make-glyph-internal &optional type
This function creates a new, uninitialized glyph of type TYPE.
- - Function: make-pointer-glyph &optional SPEC-LIST
+ - Function: make-pointer-glyph &optional spec-list
This function is equivalent to calling `make-glyph' with a TYPE of
`pointer'.
- - Function: make-icon-glyph &optional SPEC-LIST
+ - Function: make-icon-glyph &optional spec-list
This function is equivalent to calling `make-glyph' with a TYPE of
`icon'.
Only for glyphs displayed inside of a buffer.
`face'
- Face of this glyph (*not* a specifier).
+ Face of this glyph (_not_ a specifier).
- - Function: set-glyph-property GLYPH PROPERTY VALUE &optional LOCALE
- TAG-SET HOW-TO-ADD
+ - Function: set-glyph-property glyph property value &optional locale
+ tag-set how-to-add
This function changes a property of a GLYPH.
For built-in properties, the actual value of the property is a
If the value of the property is not a specifier, it will
automatically be converted into a `generic' specifier.
- - Function: glyph-property GLYPH PROPERTY &optional LOCALE
+ - Function: glyph-property glyph property &optional locale
This function returns GLYPH's value of the given PROPERTY.
If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
`glyph-property-instance' actually does all this, and is used to
determine how to display the glyph.
- - Function: glyph-property-instance GLYPH PROPERTY &optional DOMAIN
- DEFAULT NO-FALLBACK
+ - Function: glyph-property-instance glyph property &optional domain
+ default no-fallback
This function returns the instance of GLYPH's PROPERTY in the
specified DOMAIN.
Optional arguments DEFAULT and NO-FALLBACK are the same as in
`specifier-instance'. *Note Specifiers::.
- - Function: remove-glyph-property GLYPH PROPERTY &optional LOCALE
- TAG-SET EXACT-P
+ - Function: remove-glyph-property glyph property &optional locale
+ tag-set exact-p
This function removes a property from a glyph. For built-in
properties, this is analogous to `remove-specifier'. *Note
remove-specifier-p: Specifiers, for the meaning of the LOCALE,
latter will return a boolean specifier or a list of specifications, and
you probably aren't concerned with these.)
- - Function: glyph-image GLYPH &optional LOCALE
+ - Function: glyph-image glyph &optional locale
This function is equivalent to calling `glyph-property' with a
property of `image'. The return value will be an image specifier
if LOCALE is `nil' or omitted; otherwise, it will be a
specification or list of specifications.
- - Function: set-glyph-image GLYPH SPEC &optional LOCALE TAG-SET
- HOW-TO-ADD
+ - Function: set-glyph-image glyph spec &optional locale tag-set
+ how-to-add
This function is equivalent to calling `set-glyph-property' with a
property of `image'.
- - Function: glyph-image-instance GLYPH &optional DOMAIN DEFAULT
- NO-FALLBACK
+ - Function: glyph-image-instance glyph &optional domain default
+ no-fallback
This function returns the instance of GLYPH's image in the given
DOMAIN, and is equivalent to calling `glyph-property-instance'
with a property of `image'. The return value will be an image
window), and an instance object describing how the image appears
in that particular window and buffer will be returned.
- - Function: glyph-contrib-p GLYPH &optional LOCALE
+ - Function: glyph-contrib-p glyph &optional locale
This function is equivalent to calling `glyph-property' with a
property of `contrib-p'. The return value will be a boolean
specifier if LOCALE is `nil' or omitted; otherwise, it will be a
specification or list of specifications.
- - Function: set-glyph-contrib-p GLYPH SPEC &optional LOCALE TAG-SET
- HOW-TO-ADD
+ - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
+ how-to-add
This function is equivalent to calling `set-glyph-property' with a
property of `contrib-p'.
- - Function: glyph-contrib-p-instance GLYPH &optional DOMAIN DEFAULT
- NO-FALLBACK
+ - Function: glyph-contrib-p-instance glyph &optional domain default
+ no-fallback
This function returns whether the glyph contributes to its line
height in the given DOMAIN, and is equivalent to calling
`glyph-property-instance' with a property of `contrib-p'. The
return value will be either `nil' or `t'. (Normally DOMAIN will be
a window or `nil', meaning the selected window.)
- - Function: glyph-baseline GLYPH &optional LOCALE
+ - Function: glyph-baseline glyph &optional locale
This function is equivalent to calling `glyph-property' with a
property of `baseline'. The return value will be a specifier if
LOCALE is `nil' or omitted; otherwise, it will be a specification
or list of specifications.
- - Function: set-glyph-baseline GLYPH SPEC &optional LOCALE TAG-SET
- HOW-TO-ADD
+ - Function: set-glyph-baseline glyph spec &optional locale tag-set
+ how-to-add
This function is equivalent to calling `set-glyph-property' with a
property of `baseline'.
- - Function: glyph-baseline-instance GLYPH &optional DOMAIN DEFAULT
- NO-FALLBACK
+ - Function: glyph-baseline-instance glyph &optional domain default
+ no-fallback
This function returns the instance of GLYPH's baseline value in
the given DOMAIN, and is equivalent to calling
`glyph-property-instance' with a property of `baseline'. The
window), and an instance object describing the baseline value
appears in that particular window and buffer will be returned.
- - Function: glyph-face GLYPH
+ - Function: glyph-face glyph
This function returns the face of GLYPH. (Remember, this is not a
specifier, but a simple property.)
- - Function: set-glyph-face GLYPH FACE
+ - Function: set-glyph-face glyph face
This function changes the face of GLYPH to FACE.
\1f
Glyph Dimensions
----------------
- - Function: glyph-width GLYPH &optional WINDOW
+ - Function: glyph-width glyph &optional window
This function returns the width of GLYPH on WINDOW. This may not
be exact as it does not take into account all of the context that
redisplay will.
- - Function: glyph-ascent GLYPH &optional WINDOW
+ - Function: glyph-ascent glyph &optional window
This function returns the ascent value of GLYPH on WINDOW. This
may not be exact as it does not take into account all of the
context that redisplay will.
- - Function: glyph-descent GLYPH &optional WINDOW
+ - Function: glyph-descent glyph &optional window
This function returns the descent value of GLYPH on WINDOW. This
may not be exact as it does not take into account all of the
context that redisplay will.
- - Function: glyph-height GLYPH &optional WINDOW
+ - Function: glyph-height glyph &optional window
This function returns the height of GLYPH on WINDOW. (This is
equivalent to the sum of the ascent and descent values.) This may
not be exact as it does not take into account all of the context
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
----------------
An image specifier is used to describe the actual image of a glyph.
-It works like other specifiers (*note Specifiers::.), in that it
-contains a number of specifications describing how the image should
-appear in a variety of circumstances. These specifications are called
-"image instantiators". When XEmacs wants to display the image, it
-instantiates the image into an "image instance". Image instances are
-their own primitive object type (similar to font instances and color
-instances), describing how the image appears in a particular domain.
-(On the other hand, image instantiators, which are just descriptions of
-how the image should appear, are represented using strings or vectors.)
-
- - Function: image-specifier-p OBJECT
+It works like other specifiers (*note Specifiers::), in that it contains
+a number of specifications describing how the image should appear in a
+variety of circumstances. These specifications are called "image
+instantiators". When XEmacs wants to display the image, it instantiates
+the image into an "image instance". Image instances are their own
+primitive object type (similar to font instances and color instances),
+describing how the image appears in a particular domain. (On the other
+hand, image instantiators, which are just descriptions of how the image
+should appear, are represented using strings or vectors.)
+
+ - Function: image-specifier-p object
This function returns non-`nil' if OBJECT is an image specifier.
Usually, an image specifier results from calling `glyph-image' on
a glyph.
- - Function: make-image-specifier SPEC-LIST
+ - Function: make-image-specifier spec-list
This function creates a new image specifier object and initializes
it according to SPEC-LIST. It is unlikely that you will ever want
to do this, but this function is provided for completeness and for
image, but does not need to exist at any other time (e.g. it may safely
be a temporary file).
- - Function: valid-image-instantiator-format-p FORMAT
+ - Function: valid-image-instantiator-format-p format
This function returns non-`nil' if FORMAT is a valid image
instantiator format. Note that the return value for many formats
listed above depends on whether XEmacs was compiled with support
`(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
string, which is the name of the color to define; the
FORM-TO-EVALUATE should evaluate to a color specifier object, or a
- string to be passed to `make-color-instance' (*note Colors::.). If
+ string to be passed to `make-color-instance' (*note Colors::). If
a loaded XPM file references a symbolic color called COLOR-NAME,
it will display as the computed color instead.
Image Instantiator Conversion
-----------------------------
- - Function: set-console-type-image-conversion-list CONSOLE-TYPE LIST
+ - Function: set-console-type-image-conversion-list console-type list
This function sets the image-conversion-list for consoles of the
given CONSOLE-TYPE. The image-conversion-list specifies how image
instantiators that are strings should be interpreted. Each
affects newly-added instantiators. Existing instantiators in
glyphs and image specifiers will not be affected.
- - Function: console-type-image-conversion-list CONSOLE-TYPE
+ - Function: console-type-image-conversion-list console-type
This function returns the image-conversion-list for consoles of
the given CONSOLE-TYPE.
to explicitly create image instances, if you want more control over the
instantiation process.
- - Function: image-instance-p OBJECT
+ - Function: image-instance-p object
This function returns non-`nil' if OBJECT is an image instance.
* Menu:
another program to be responsible for drawing into the window.
Not currently implemented.
- - Function: valid-image-instance-type-p TYPE
+ - Function: valid-image-instance-type-p type
This function returns non-`nil' if TYPE is a valid image instance
type.
- Function: image-instance-type-list
This function returns a list of the valid image instance types.
- - Function: image-instance-type IMAGE-INSTANCE
+ - Function: image-instance-type image-instance
This function returns the type of the given image instance. The
return value will be one of `nothing', `text', `mono-pixmap',
`color-pixmap', `pointer', or `subwindow'.
- - Function: text-image-instance-p OBJECT
+ - Function: text-image-instance-p object
This function returns non-`nil' if OBJECT is an image instance of
type `text'.
- - Function: mono-pixmap-image-instance-p OBJECT
+ - Function: mono-pixmap-image-instance-p object
This function returns non-`nil' if OBJECT is an image instance of
type `mono-pixmap'.
- - Function: color-pixmap-image-instance-p OBJECT
+ - Function: color-pixmap-image-instance-p object
This function returns non-`nil' if OBJECT is an image instance of
type `color-pixmap'.
- - Function: pointer-image-instance-p OBJECT
+ - Function: pointer-image-instance-p object
This function returns non-`nil' if OBJECT is an image instance of
type `pointer'.
- - Function: subwindow-image-instance-p OBJECT
+ - Function: subwindow-image-instance-p object
This function returns non-`nil' if OBJECT is an image instance of
type `subwindow'.
- - Function: nothing-image-instance-p OBJECT
+ - Function: nothing-image-instance-p object
This function returns non-`nil' if OBJECT is an image instance of
type `nothing'.
Image Instance Functions
........................
- - Function: make-image-instance DATA &optional DEVICE DEST-TYPES
- NO-ERROR
+ - Function: make-image-instance data &optional device dest-types
+ no-error
This function creates a new image-instance object.
DATA is an image instantiator, which describes the image (*note
- Image Specifiers::.).
+ Image Specifiers::).
DEST-TYPES should be a list of allowed image instance types that
can be generated. The DEST-TYPES list is unordered. If multiple
generated and this function returns NIL. If anything else, a
warning message is generated and this function returns NIL.
- - Function: colorize-image-instance IMAGE-INSTANCE FOREGROUND
- BACKGROUND
+ - Function: colorize-image-instance image-instance foreground
+ background
This function makes the image instance be displayed in the given
colors. Image instances come in two varieties: bitmaps, which are
1 bit deep which are rendered in the prevailing foreground and
instance was a pixmap already, nothing is done (and `nil' is
returned). Otherwise `t' is returned.
- - Function: image-instance-name IMAGE-INSTANCE
+ - Function: image-instance-name image-instance
This function returns the name of the given image instance.
- - Function: image-instance-string IMAGE-INSTANCE
+ - Function: image-instance-string image-instance
This function returns the string of the given image instance.
This will only be non-`nil' for text image instances.
- - Function: image-instance-file-name IMAGE-INSTANCE
+ - Function: image-instance-file-name image-instance
This function returns the file name from which IMAGE-INSTANCE was
read, if known.
- - Function: image-instance-mask-file-name IMAGE-INSTANCE
+ - Function: image-instance-mask-file-name image-instance
This function returns the file name from which IMAGE-INSTANCE's
mask was read, if known.
- - Function: image-instance-depth IMAGE-INSTANCE
+ - Function: image-instance-depth image-instance
This function returns the depth of the image instance. This is 0
for a mono pixmap, or a positive integer for a color pixmap.
- - Function: image-instance-height IMAGE-INSTANCE
+ - Function: image-instance-height image-instance
This function returns the height of the image instance, in pixels.
- - Function: image-instance-width IMAGE-INSTANCE
+ - Function: image-instance-width image-instance
This function returns the width of the image instance, in pixels.
- - Function: image-instance-hotspot-x IMAGE-INSTANCE
+ - Function: image-instance-hotspot-x image-instance
This function returns the X coordinate of the image instance's
hotspot, if known. This is a point relative to the origin of the
pixmap. When an image is used as a mouse pointer, the hotspot is
This will always be `nil' for a non-pointer image instance.
- - Function: image-instance-hotspot-y IMAGE-INSTANCE
+ - Function: image-instance-hotspot-y image-instance
This function returns the Y coordinate of the image instance's
hotspot, if known.
- - Function: image-instance-foreground IMAGE-INSTANCE
+ - Function: image-instance-foreground image-instance
This function returns the foreground color of IMAGE-INSTANCE, if
applicable. This will be a color instance or `nil'. (It will only
be non-`nil' for colorized mono pixmaps and for pointers.)
- - Function: image-instance-background IMAGE-INSTANCE
+ - Function: image-instance-background image-instance
This function returns the background color of IMAGE-INSTANCE, if
applicable. This will be a color instance or `nil'. (It will only
be non-`nil' for colorized mono pixmaps and for pointers.)
iconified. Their image can be instantiated as `mono-pixmap' and
`color-pixmap'.
- - Function: glyph-type GLYPH
+ - Function: glyph-type glyph
This function returns the type of the given glyph. The return
value will be a symbol, one of `buffer', `pointer', or `icon'.
- - Function: valid-glyph-type-p GLYPH-TYPE
+ - Function: valid-glyph-type-p glyph-type
Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
- Function: glyph-type-list
This function returns a list of valid glyph types.
- - Function: buffer-glyph-p OBJECT
+ - Function: buffer-glyph-p object
This function returns non-`nil' if OBJECT is a glyph of type
`buffer'.
- - Function: icon-glyph-p OBJECT
+ - Function: icon-glyph-p object
This function returns non-`nil' if OBJECT is a glyph of type
`icon'.
- - Function: pointer-glyph-p OBJECT
+ - Function: pointer-glyph-p object
This function returns non-`nil' if OBJECT is a glyph of type
`pointer'.
per-frame, per-window, or per-device basis.
You should use `set-glyph-image' to set the following variables,
-*not* `setq'.
+_not_ `setq'.
- Glyph: text-pointer-glyph
This variable specifies the shape of the mouse pointer when over
mouse moves. That function calls `set-frame-pointer', which sets the
current mouse pointer for a frame.
- - Function: set-frame-pointer FRAME IMAGE-INSTANCE
+ - Function: set-frame-pointer frame image-instance
This function sets the mouse pointer of FRAME to the given pointer
image instance. You should not call this function directly. (If
you do, the pointer will change again the next time the mouse
Subwindows are not currently implemented.
- - Function: subwindowp OBJECT
+ - Function: subwindowp object
This function returns non-`nil' if OBJECT is a subwindow.
\1f
Annotations can be displayed intermixed with text, in any whitespace at
the beginning or end of a line, or in a special area at the left or
right side of the frame called a "margin", whose size is controllable.
-Annotations are implemented using extents (*note Extents::.); but you
+Annotations are implemented using extents (*note Extents::); but you
can work with annotations without knowing how extents work.
* Menu:
Annotation Primitives
=====================
- - Function: make-annotation GLYPH &optional POSITION LAYOUT BUFFER
- WITH-EVENT D-GLYPH RIGHTP
+ - Function: make-annotation glyph &optional position layout buffer
+ with-event d-glyph rightp
This function creates a marginal annotation at position POS in
BUFFER. The annotation is displayed using GLYPH, which should be
a glyph object or a string, and is positioned using layout policy
The newly created annotation is returned.
- - Function: delete-annotation ANNOTATION
+ - Function: delete-annotation annotation
This function removes ANNOTATION from its buffer. This does not
modify the buffer text.
- - Function: annotationp ANNOTATION
+ - Function: annotationp annotation
This function returns `t' if ANNOTATION is an annotation, `nil'
otherwise.
Annotation Properties
=====================
- - Function: annotation-glyph ANNOTATION
+ - Function: annotation-glyph annotation
This function returns the glyph object used to display ANNOTATION.
- - Function: set-annotation-glyph ANNOTATION GLYPH &optional LAYOUT SIDE
+ - Function: set-annotation-glyph annotation glyph &optional layout side
This function sets the glyph of ANNOTATION to GLYPH, which should
be a glyph object. If LAYOUT is non-`nil', set the layout policy
of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
side of the buffer at which the annotation is displayed to the
given side. The new value of `annotation-glyph' is returned.
- - Function: annotation-down-glyph ANNOTATION
+ - Function: annotation-down-glyph annotation
This function returns the glyph used to display ANNOTATION when
the left mouse button is depressed on the annotation.
- - Function: set-annotation-down-glyph ANNOTATION GLYPH
+ - Function: set-annotation-down-glyph annotation glyph
This function returns the glyph used to display ANNOTATION when
the left mouse button is depressed on the annotation to GLYPH,
which should be a glyph object.
- - Function: annotation-face ANNOTATION
+ - Function: annotation-face annotation
This function returns the face associated with ANNOTATION.
- - Function: set-annotation-face ANNOTATION FACE
+ - Function: set-annotation-face annotation face
This function sets the face associated with ANNOTATION to FACE.
- - Function: annotation-layout ANNOTATION
+ - Function: annotation-layout annotation
This function returns the layout policy of ANNOTATION.
- - Function: set-annotation-layout ANNOTATION LAYOUT
+ - Function: set-annotation-layout annotation layout
This function sets the layout policy of ANNOTATION to LAYOUT.
- - Function: annotation-side ANNOTATION
+ - Function: annotation-side annotation
This function returns the side of the buffer that ANNOTATION is
displayed on. Return value is a symbol, either `left' or `right'.
- - Function: annotation-data ANNOTATION
+ - Function: annotation-data annotation
This function returns the data associated with ANNOTATION.
- - Function: set-annotation-data ANNOTATION DATA
+ - Function: set-annotation-data annotation data
This function sets the data field of ANNOTATION to DATA. DATA is
returned.
- - Function: annotation-action ANNOTATION
+ - Function: annotation-action annotation
This function returns the action associated with ANNOTATION.
- - Function: set-annotation-action ANNOTATION ACTION
+ - Function: set-annotation-action annotation action
This function sets the action field of ANNOTATION to ACTION.
ACTION is returned..
- - Function: annotation-menu ANNOTATION
+ - Function: annotation-menu annotation
This function returns the menu associated with ANNOTATION.
- - Function: set-annotation-menu ANNOTATION MENU
+ - Function: set-annotation-menu annotation menu
This function sets the menu associated with ANNOTATION to MENU.
This menu will be displayed when the right mouse button is pressed
over the annotation.
- - Function: annotation-visible ANNOTATION
+ - Function: annotation-visible annotation
This function returns `t' if there is enough available space to
display ANNOTATION, `nil' otherwise.
- - Function: annotation-width ANNOTATION
+ - Function: annotation-width annotation
This function returns the width of ANNOTATION in pixels.
- - Function: hide-annotation ANNOTATION
+ - Function: hide-annotation annotation
This function removes ANNOTATION's glyph, making it invisible.
- - Function: reveal-annotation ANNOTATION
+ - Function: reveal-annotation annotation
This function restores ANNOTATION's glyph, making it visible.
\1f
Locating Annotations
====================
- - Function: annotations-in-region START END BUFFER
+ - Function: annotations-in-region start end buffer
This function returns a list of all annotations in BUFFER which
are between START and END inclusively.
- - Function: annotations-at &optional POSITION BUFFER
+ - Function: annotations-at &optional position buffer
This function returns a list of all annotations at POSITION in
BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
the current buffer is used.
- - Function: annotation-list &optional BUFFER
+ - Function: annotation-list &optional buffer
This function returns a list of all annotations in BUFFER. If
BUFFER is `nil', the current buffer is used.
to `nil'. This is a specifier variable; use `set-specifier' to
change its value.
- - Function: window-left-margin-pixel-width &optional WINDOW
+ - Function: window-left-margin-pixel-width &optional window
This function returns the width in pixels of the left outside
margin of WINDOW. If WINDOW is `nil', the selected window is
assumed.
- - Function: window-right-margin-pixel-width &optional WINDOW
+ - Function: window-right-margin-pixel-width &optional window
This function returns the width in pixels of the right outside
margin of WINDOW. If WINDOW is `nil', the selected window is
assumed.
The function `redraw-frame' redisplays the entire contents of a
given frame. *Note Frames::.
- - Function: redraw-frame FRAME
+ - Function: redraw-frame frame
This function clears and redisplays frame FRAME.
Even more powerful is `redraw-display':
- - Command: redraw-display &optional DEVICE
+ - Command: redraw-display &optional device
This function redraws all frames on DEVICE marked as having their
image garbled. DEVICE defaults to the selected device. If DEVICE
is `t', all devices will have their frames checked.
- User Option: truncate-partial-width-windows
This variable controls display of lines that extend beyond the
right edge of the window, in side-by-side windows (*note Splitting
- Windows::.). If it is non-`nil', these lines are truncated;
+ Windows::). If it is non-`nil', these lines are truncated;
otherwise, `truncate-lines' says what to do with them.
The backslash and curved arrow used to indicate truncated or
continued lines are only defaults, and can be changed. These images
-are actually glyphs (*note Glyphs::.). XEmacs provides a great deal of
+are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
flexibility in how glyphs can be controlled. (This differs from FSF
Emacs, which uses display tables to control these images.)
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
area; see *Note Errors::.
You can write output in the echo area by using the Lisp printing
-functions with `t' as the stream (*note Output Functions::.), or as
+functions with `t' as the stream (*note Output Functions::), or as
follows:
- - Function: message STRING &rest ARGUMENTS
+ - Function: message string &rest arguments
This function displays a one-line message in the echo area. The
argument STRING is similar to a C language `printf' control
string. See `format' in *Note String Conversion::, for the details
programs may access these messages, or remove them as appropriate, via
the message stack.
- - Function: display-message LABEL MESSAGE &optional FRAME STDOUT-P
+ - Function: display-message label message &optional frame stdout-p
This function displays MESSAGE (a string) labeled as LABEL, as
described above.
(display-message 'command "Mark set")
- - Function: lmessage LABEL STRING &rest ARGUMENTS
+ - Function: lmessage label string &rest arguments
This function displays a message STRING with label LABEL. It is
similar to `message' in that it accepts a `printf'-like strings
and any number of arguments.
;; Display a message that should not be logged.
(lmessage 'no-log "Done")
- - Function: clear-message &optional LABEL FRAME STDOUT-P NO-RESTORE
+ - Function: clear-message &optional label frame stdout-p no-restore
This function remove any message with the given LABEL from the
message-stack, erasing it from the echo area if it's currently
displayed there.
Unless you need the return value or you need to specify a label,
you should just use `(message nil)'.
- - Function: current-message &optional FRAME
+ - Function: current-message &optional frame
This function returns the current message in the echo area, or
`nil'. The FRAME argument is currently unused.
`debug', `info', `notice', `warning', `error', `critical', `alert' and
`emergency'.
- - Function: display-warning CLASS MESSAGE &optional LEVEL
+ - Function: display-warning class message &optional level
This function displays a warning message MESSAGE (a string).
CLASS should be a warning class symbol, as described above, or a
list of such symbols. LEVEL describes the warning priority level.
you use the specifier and/or `set-face-*' functions.
---------- Warning buffer ----------
- - Function: lwarn CLASS LEVEL MESSAGE &rest ARGS
+ - Function: lwarn class level message &rest args
This function displays a formatted labeled warning message. As
above, CLASS should be the warning class symbol, or a list of such
symbols, and LEVEL should specify the warning priority level
character invisible. This is the default case--if you don't alter the
default value of `buffer-invisibility-spec', this is how the
`invisibility' property works. This feature is much like selective
-display (*note Selective Display::.), but more general and cleaner.
+display (*note Selective Display::), but more general and cleaner.
More generally, you can use the variable `buffer-invisibility-spec'
to control which values of the `invisible' property make text
a Lisp program. The program controls which lines are hidden by altering
the text. Outline mode has traditionally used this variant. It has
been partially replaced by the invisible text feature (*note Invisible
-Text::.); there is a new version of Outline mode which uses that
-instead.
+Text::); there is a new version of Outline mode which uses that instead.
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed to be a
not skip the invisible portion, and it is possible (if tricky) to
insert or delete text in an invisible portion.
- In the examples below, we show the *display appearance* of the
+ In the examples below, we show the _display appearance_ of the
buffer `foo', which changes with the value of `selective-display'.
- The *contents* of the buffer do not change.
+ The _contents_ of the buffer do not change.
(setq selective-display nil)
=> nil
This variable holds the string to display to call attention to a
particular line, or `nil' if the arrow feature is not in use.
Despite its name, the value of this variable can be either a string
- or a glyph (*note Glyphs::.).
+ or a glyph (*note Glyphs::).
- Variable: overlay-arrow-position
This variable holds a marker that indicates where to display the
and then present it to the user for perusal rather than for editing.
Many of the help commands use this feature.
- - Special Form: with-output-to-temp-buffer BUFFER-NAME FORMS...
+ - Special Form: with-output-to-temp-buffer buffer-name forms...
This function executes FORMS while arranging to insert any output
they print into the buffer named BUFFER-NAME. The buffer is then
shown in some window for viewing, displayed but not selected.
In Emacs versions 18 and earlier, this variable was called
`temp-buffer-show-hook'.
- - Function: momentary-string-display STRING POSITION &optional CHAR
- MESSAGE
+ - Function: momentary-string-display string position &optional char
+ message
This function momentarily displays STRING in the current buffer at
POSITION. It has no effect on the undo list or on the buffer's
modification status.
(defun interactive-blink-matching-open ()
"Indicate momentarily the start of sexp before point."
(interactive)
-
- (let ((blink-matching-paren-distance
+ (let ((blink-matching-paren-distance
(buffer-size))
(blink-matching-paren t))
(blink-matching-open)))
The usual display conventions define how to display each character
code. You can override these conventions by setting up a display table
-(*note Display Tables::.). Here are the usual display conventions:
+(*note Display Tables::). Here are the usual display conventions:
* Character codes 32 through 126 map to glyph codes 32 through 126.
Normally this means they display as themselves.
The 256 elements correspond to character codes; the Nth element says
how to display the character code N. The value should be `nil', a
string, a glyph, or a vector of strings and glyphs (*note Character
-Descriptors::.). If an element is `nil', it says to display that
+Descriptors::). If an element is `nil', it says to display that
character according to the usual display conventions (*note Usual
-Display::.).
+Display::).
If you use the display table to change the display of newline
characters, the whole buffer will be displayed as one long "line."
`nil'
Display according to the standard interpretation (*note Usual
- Display::.).
+ Display::).
\1f
File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
this; frequent bells can become irritating. Also be careful not to use
beeping alone when signaling an error is appropriate. (*Note Errors::.)
- - Function: ding &optional DONT-TERMINATE SOUND DEVICE
+ - Function: ding &optional dont-terminate sound device
This function beeps, or flashes the screen (see `visible-bell'
below). It also terminates any keyboard macro currently executing
unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
specifies what device to make the sound on, and defaults to the
selected device.
- - Function: beep &optional DONT-TERMINATE SOUND DEVICE
+ - Function: beep &optional dont-terminate sound device
This is a synonym for `ding'.
- User Option: visible-bell
- Command: load-default-sounds
This function loads and installs some sound files as beep-types.
- - Command: load-sound-file FILENAME SOUND-NAME &optional VOLUME
+ - Command: load-sound-file filename sound-name &optional volume
This function reads in an audio file and adds it to `sound-alist'.
The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
should be a symbol, specifying the name of the sound. If VOLUME
is specified, the sound will be played at that volume; otherwise,
the value of BELL-VOLUME will be used.
- - Function: play-sound SOUND &optional VOLUME DEVICE
+ - Function: play-sound sound &optional volume device
This function plays sound SOUND, which should be a symbol
mentioned in `sound-alist'. If VOLUME is specified, it overrides
the value (if any) specified in `sound-alist'. DEVICE specifies
the device to play the sound on, and defaults to the selected
device.
- - Command: play-sound-file FILE &optional VOLUME DEVICE
+ - Command: play-sound-file file &optional volume device
This function plays the named sound file at volume VOLUME, which
defaults to `bell-volume'. DEVICE specifies the device to play
the sound on, and defaults to the selected device.
Hash Tables
***********
- - Function: hash-table-p OBJECT
+ - Function: hash-table-p object
This function returns `t' if OBJECT is a hash table, else `nil'.
* Menu:
called "values". A key/value pair is sometimes called an "entry" in
the hash table. There are many ways other than hash tables of
implementing the same sort of mapping, e.g. association lists (*note
-Association Lists::.) and property lists (*note Property Lists::.), but
+Association Lists::) and property lists (*note Property Lists::), but
hash tables provide much faster lookup when there are many entries in
the mapping. Hash tables are an implementation of the abstract data
type "dictionary", also known as "associative array".
remain in the hash table if the value is pointed to by something
other than a weak hash table, even if the key is not.
- - Function: copy-hash-table HASH-TABLE
+ - Function: copy-hash-table hash-table
This function returns a new hash table which contains the same
keys and values as HASH-TABLE. The keys and values will not
themselves be copied.
- - Function: hash-table-count HASH-TABLE
+ - Function: hash-table-count hash-table
This function returns the number of entries in HASH-TABLE.
- - Function: hash-table-test HASH-TABLE
+ - Function: hash-table-test hash-table
This function returns the test function of HASH-TABLE. This can
be one of `eq', `eql' or `equal'.
- - Function: hash-table-size HASH-TABLE
+ - Function: hash-table-size hash-table
This function returns the current number of slots in HASH-TABLE,
whether occupied or not.
- - Function: hash-table-rehash-size HASH-TABLE
+ - Function: hash-table-rehash-size hash-table
This function returns the current rehash size of HASH-TABLE. This
is a float greater than 1.0; the factor by which HASH-TABLE is
enlarged when the rehash threshold is exceeded.
- - Function: hash-table-rehash-threshold HASH-TABLE
+ - Function: hash-table-rehash-threshold hash-table
This function returns the current rehash threshold of HASH-TABLE.
This is a float between 0.0 and 1.0; the maximum "load factor" of
HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
- - Function: hash-table-weakness HASH-TABLE
+ - Function: hash-table-weakness hash-table
This function returns the weakness of HASH-TABLE. This can be one
of `nil', `t', `key' or `value'.
Working With Hash Tables
========================
- - Function: puthash KEY VALUE HASH-TABLE
+ - Function: puthash key value hash-table
This function hashes KEY to VALUE in HASH-TABLE.
- - Function: gethash KEY HASH-TABLE &optional DEFAULT
+ - Function: gethash key hash-table &optional default
This function finds the hash value for KEY in HASH-TABLE. If
there is no entry for KEY in HASH-TABLE, DEFAULT is returned
(which in turn defaults to `nil').
- - Function: remhash KEY HASH-TABLE
+ - Function: remhash key hash-table
This function removes the entry for KEY from HASH-TABLE. Does
nothing if there is no entry for KEY in HASH-TABLE.
- - Function: clrhash HASH-TABLE
+ - Function: clrhash hash-table
This function removes all entries from HASH-TABLE, leaving it
empty.
- - Function: maphash FUNCTION HASH-TABLE
+ - Function: maphash function hash-table
This function maps FUNCTION over entries in HASH-TABLE, calling it
with two args, each key and value in the hash table.
This maps integers in the range (-3, 2) to `foo' and integers in the
range (5, 20) to `bar'.
- - Function: range-table-p OBJECT
+ - Function: range-table-p object
Return non-`nil' if OBJECT is a range table.
* Menu:
- Function: make-range-table
Make a new, empty range table.
- - Function: copy-range-table OLD-TABLE
+ - Function: copy-range-table old-table
Make a new range table which contains the same values for the same
ranges as the given table. The values will not themselves be
copied.
Working With Range Tables
=========================
- - Function: get-range-table POS TABLE &optional DEFAULT
+ - Function: get-range-table pos table &optional default
This function finds value for position POS in TABLE. If there is
no corresponding value, return DEFAULT (defaults to `nil').
- - Function: put-range-table START END VAL TABLE
+ - Function: put-range-table start end val table
This function sets the value for range (START, END) to be VAL in
TABLE.
- - Function: remove-range-table START END TABLE
+ - Function: remove-range-table start end table
This function removes the value for range (START, END) in TABLE.
- - Function: clear-range-table TABLE
+ - Function: clear-range-table table
This function flushes TABLE.
- - Function: map-range-table FUNCTION TABLE
+ - Function: map-range-table function table
This function maps FUNCTION over entries in TABLE, calling it with
three args, the beginning and end of the range and the
corresponding value.
Databases
*********
- - Function: databasep OBJECT
+ - Function: databasep object
This function returns non-`nil' if OBJECT is a database.
* Menu:
Connecting to a Database
========================
- - Function: open-database FILE &optional TYPE SUBTYPE ACCESS MODE
+ - Function: open-database file &optional type subtype access mode
This function opens database FILE, using database method TYPE and
SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
can be any combination of `r' `w' and `+', for read, write, and
available: `'hash', `'btree', and `'recno'. See the manpages for
the Berkeley DB functions to more information about these types.
- - Function: close-database OBJ
+ - Function: close-database obj
This function closes database OBJ.
- - Function: database-live-p OBJ
+ - Function: database-live-p obj
This function returns `t' iff OBJ is an active database, else
`nil'.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Working With a Database
=======================
- - Function: get-database KEY DBASE &optional DEFAULT
+ - Function: get-database key dbase &optional default
This function finds the value for KEY in DATABASE. If there is no
corresponding value, DEFAULT is returned (`nil' if DEFAULT is
omitted).
- - Function: map-database FUNCTION DBASE
+ - Function: map-database function dbase
This function maps FUNCTION over entries in DATABASE, calling it
with two args, each key and value in the database.
- - Function: put-database KEY VAL DBASE &optional REPLACE
+ - Function: put-database key val dbase &optional replace
This function stores KEY and VAL in DATABASE. If optional fourth
arg REPLACE is non-`nil', replace any existing entry in the
database.
- - Function: remove-database KEY DBASE
+ - Function: remove-database key dbase
This function removes KEY from DATABASE.
\1f
Other Database Functions
========================
- - Function: database-file-name OBJ
+ - Function: database-file-name obj
This function returns the filename associated with the database
OBJ.
- - Function: database-last-error &optional OBJ
+ - Function: database-last-error &optional obj
This function returns the last error associated with database OBJ.
- - Function: database-subtype OBJ
+ - Function: database-subtype obj
This function returns the subtype of database OBJ, if any.
- - Function: database-type OBJ
+ - Function: database-type obj
This function returns the type of database OBJ.
\1f
signals, obtain status information, receive output from the process, or
send input to it.
- - Function: processp OBJECT
+ - Function: processp object
This function returns `t' if OBJECT is a process, `nil' otherwise.
* Menu:
There are three functions that create a new subprocess in which to
run a program. One of them, `start-process', creates an asynchronous
-process and returns a process object (*note Asynchronous Processes::.).
+process and returns a process object (*note Asynchronous Processes::).
The other two, `call-process' and `call-process-region', create a
synchronous process and do not return a process object (*note
-Synchronous Processes::.).
+Synchronous Processes::).
Synchronous and asynchronous processes are explained in following
sections. Since the three functions are all called in a similar
variable `PATH'. The standard file name constructs, `~', `.', and
`..', are interpreted as usual in `exec-path', but environment variable
substitutions (`$HOME', etc.) are not recognized; use
-`substitute-in-file-name' to perform them (*note File Name
-Expansion::.).
+`substitute-in-file-name' to perform them (*note File Name Expansion::).
Each of the subprocess-creating functions has a BUFFER-OR-NAME
argument which specifies where the standard output from the program will
ARGS to provide those.
The subprocess gets its current directory from the value of
-`default-directory' (*note File Name Expansion::.).
+`default-directory' (*note File Name Expansion::).
The subprocess inherits its environment from XEmacs; but you can
specify overrides for it with `process-environment'. *Note System
The synchronous subprocess functions returned `nil' in version 18.
In version 19, they return an indication of how the process terminated.
- - Function: call-process PROGRAM &optional INFILE DESTINATION DISPLAY
- &rest ARGS
+ - Function: call-process program &optional infile destination display
+ &rest args
This function calls PROGRAM in a separate process and waits for it
to finish.
---------- Buffer: foo ----------
/usr/user/lewis/manual
---------- Buffer: foo ----------
-
+
(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
=> nil
(concat (file-name-as-directory file) ".")
file))
- - Function: call-process-region START END PROGRAM &optional DELETE
- DESTINATION DISPLAY &rest ARGS
+ - Function: call-process-region start end program &optional delete
+ destination display &rest args
This function sends the text between START to END as standard
input to a process running PROGRAM. It deletes the text sent if
DELETE is non-`nil'; this is useful when BUFFER is `t', to insert
---------- Buffer: foo ----------
input-!-
---------- Buffer: foo ----------
-
+
(call-process-region 1 6 "cat" nil t)
=> nil
using the functions described in following sections. Here we describe
how to create an asynchronous process with `start-process'.
- - Function: start-process NAME BUFFER-OR-NAME PROGRAM &rest ARGS
+ - Function: start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the
program PROGRAM running in it. It returns a process object that
stands for the new subprocess in Lisp. The argument NAME
(start-process "my-process" "foo" "sleep" "100")
=> #<process my-process>
-
+
(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
=> #<process my-process<1>>
Process my-process finished
---------- Buffer: foo ----------
- - Function: start-process-shell-command NAME BUFFER-OR-NAME COMMAND
- &rest COMMAND-ARGS
+ - Function: start-process-shell-command name buffer-or-name command
+ &rest command-args
This function is like `start-process' except that it uses a shell
to execute the specified command. The argument COMMAND is a shell
command name, and COMMAND-ARGS are the arguments for the shell
To determine whether a given subprocess actually got a pipe or a
PTY, use the function `process-tty-name' (*note Process
- Information::.).
+ Information::).
\1f
File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
`list-processes'. Otherwise, they are deleted immediately after
they exit.
- - Function: delete-process NAME
+ - Function: delete-process name
This function deletes the process associated with NAME, killing it
with a `SIGHUP' signal. The argument NAME may be a process, the
name of a process, a buffer, or the name of a buffer.
(delete-process "*shell*")
=> nil
- - Function: process-kill-without-query PROCESS &optional
- REQUIRE-QUERY-P
+ - Function: process-kill-without-query process &optional
+ require-query-p
This function declares that XEmacs need not query the user if
PROCESS is still running when XEmacs is exited. The process will
be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
- *will* query the user (this is the default). The return value is
+ _will_ query the user (this is the default). The return value is
`t' if a query was formerly required, and `nil' otherwise.
(process-kill-without-query (get-process "shell"))
(process-list)
=> (#<process display-time> #<process shell>)
- - Function: get-process NAME
+ - Function: get-process name
This function returns the process named NAME, or `nil' if there is
none. An error is signaled if NAME is not a string.
(get-process "shell")
=> #<process shell>
- - Function: process-command PROCESS
+ - Function: process-command process
This function returns the command that was executed to start
PROCESS. This is a list of strings, the first string being the
program executed and the rest of the strings being the arguments
(process-command (get-process "shell"))
=> ("/bin/csh" "-i")
- - Function: process-id PROCESS
+ - Function: process-id process
This function returns the PID of PROCESS. This is an integer that
distinguishes the process PROCESS from all other processes running
on the same computer at the current time. The PID of a process is
chosen by the operating system kernel when the process is started
and remains constant as long as the process exists.
- - Function: process-name PROCESS
+ - Function: process-name process
This function returns the name of PROCESS.
- - Function: process-status PROCESS-NAME
+ - Function: process-status process-name
This function returns the status of PROCESS-NAME as a symbol. The
argument PROCESS-NAME must be a process, a buffer, a process name
(string) or a buffer name (string).
(process-status "shell")
=> run
-
(process-status (get-buffer "*shell*"))
=> run
-
x
=> #<process xx<1>>
(process-status x)
In earlier Emacs versions (prior to version 19), the status of a
network connection was `run' if open, and `exit' if closed.
- - Function: process-kill-without-query-p PROCESS
+ - Function: process-kill-without-query-p process
This function returns whether PROCESS will be killed without
querying the user, if it is running when XEmacs is exited. The
default value is `nil'.
- - Function: process-exit-status PROCESS
+ - Function: process-exit-status process
This function returns the exit status of PROCESS or the signal
number that killed it. (Use the result of `process-status' to
determine which of those it is.) If PROCESS has not yet
terminated, the value is 0.
- - Function: process-tty-name PROCESS
+ - Function: process-tty-name process
This function returns the terminal name that PROCESS is using for
its communication with Emacs--or `nil' if it is using pipes
instead of a terminal (see `process-connection-type' in *Note
other characters, to force them through. For most programs, these EOFs
do no harm.
- - Function: process-send-string PROCESS-NAME STRING
+ - Function: process-send-string process-name string
This function sends PROCESS-NAME the contents of STRING as
standard input. The argument PROCESS-NAME must be a process or
the name of a process. If it is `nil', the current buffer's
(process-send-string "shell<1>" "ls\n")
=> nil
-
+
+
---------- Buffer: *shell* ----------
...
introduction.texi syntax-tables.texi~
...
---------- Buffer: *shell* ----------
- - Command: process-send-region PROCESS-NAME START END
+ - Command: process-send-region process-name start end
This function sends the text in the region defined by START and
END as standard input to PROCESS-NAME, which is a process or a
process name. (If it is `nil', the current buffer's process is
markers that indicate positions in the current buffer. (It is
unimportant which number is larger.)
- - Function: process-send-eof &optional PROCESS-NAME
+ - Function: process-send-eof &optional process-name
This function makes PROCESS-NAME see an end-of-file in its input.
The EOF comes after any text already sent to it.
job-control shells won't work when a pipe is used. See
`process-connection-type' in *Note Asynchronous Processes::.
- - Function: interrupt-process &optional PROCESS-NAME CURRENT-GROUP
+ - Function: interrupt-process &optional process-name current-group
This function interrupts the process PROCESS-NAME by sending the
signal `SIGINT'. Outside of XEmacs, typing the "interrupt
character" (normally `C-c' on some systems, and `DEL' on others)
you can think of this function as "typing `C-c'" on the terminal
by which XEmacs talks to the subprocess.
- - Function: kill-process &optional PROCESS-NAME CURRENT-GROUP
+ - Function: kill-process &optional process-name current-group
This function kills the process PROCESS-NAME by sending the signal
`SIGKILL'. This signal kills the subprocess immediately, and
cannot be handled by the subprocess.
- - Function: quit-process &optional PROCESS-NAME CURRENT-GROUP
+ - Function: quit-process &optional process-name current-group
This function sends the signal `SIGQUIT' to the process
PROCESS-NAME. This signal is the one sent by the "quit character"
(usually `C-b' or `C-\') when you are not inside XEmacs.
- - Function: stop-process &optional PROCESS-NAME CURRENT-GROUP
+ - Function: stop-process &optional process-name current-group
This function stops the process PROCESS-NAME by sending the signal
`SIGTSTP'. Use `continue-process' to resume its execution.
non-`nil', you can think of this function as "typing `C-z'" on the
terminal XEmacs uses to communicate with the subprocess.
- - Function: continue-process &optional PROCESS-NAME CURRENT-GROUP
+ - Function: continue-process &optional process-name current-group
This function resumes execution of the process PROCESS by sending
it the signal `SIGCONT'. This presumes that PROCESS-NAME was
stopped previously.
- - Function: signal-process PID SIGNAL
+ - Function: signal-process pid signal
This function sends a signal to process PID, which need not be a
child of XEmacs. The argument SIGNAL specifies which signal to
send; it should be an integer.
Many applications of processes also use the buffer for editing input to
be sent to the process, but this is not built into XEmacs Lisp.
- Unless the process has a filter function (*note Filter Functions::.),
+ Unless the process has a filter function (*note Filter Functions::),
its output is inserted in the associated buffer. The position to insert
the output is determined by the `process-mark', which is then updated
to point to the end of the text just inserted. Usually, but not
always, the `process-mark' is at the end of the buffer.
- - Function: process-buffer PROCESS
+ - Function: process-buffer process
This function returns the associated buffer of the process PROCESS.
(process-buffer (get-process "shell"))
=> #<buffer *shell*>
- - Function: process-mark PROCESS
+ - Function: process-mark process
This function returns the process marker for PROCESS, which is the
marker that says where to insert output from the process.
transmission to the process, the process marker is useful for
distinguishing the new input from previous output.
- - Function: set-process-buffer PROCESS BUFFER
+ - Function: set-process-buffer process buffer
This function sets the buffer associated with PROCESS to BUFFER.
If BUFFER is `nil', the process becomes associated with no buffer.
- - Function: get-buffer-process BUFFER-OR-NAME
+ - Function: get-buffer-process buffer-or-name
This function returns the process associated with BUFFER-OR-NAME.
If there are several processes associated with it, then one is
chosen. (Presently, the one chosen is the one most recently
=> #<process shell>
Killing the process's buffer deletes the process, which kills the
- subprocess with a `SIGHUP' signal (*note Signals to Processes::.).
+ subprocess with a `SIGHUP' signal (*note Signals to Processes::).
\1f
File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
A process "filter function" is a function that receives the standard
output from the associated process. If a process has a filter, then
-*all* output from that process is passed to the filter. The process
+_all_ output from that process is passed to the filter. The process
buffer is used directly for output from the process only when there is
no filter.
avoids the timing errors that could result from running filters at
random places in the middle of other Lisp programs. You may explicitly
cause Emacs to wait, so that filter functions will run, by calling
-`sit-for' or `sleep-for' (*note Waiting::.), or `accept-process-output'
-(*note Accepting Output::.). Emacs is also waiting when the command
-loop is reading input.
+`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
+(*note Accepting Output::). Emacs is also waiting when the command loop
+is reading input.
Quitting is normally inhibited within a filter function--otherwise,
the effect of typing `C-g' at command level or to quit a user command
(let (moving)
(set-buffer (process-buffer proc))
(setq moving (= (point) (process-mark proc)))
-
- (save-excursion
+ (save-excursion
;; Insert the text, moving the process-marker.
(goto-char (process-mark proc))
(insert string)
that produces the same output twice in a row may send it as one batch
of 200 characters one time, and five batches of 40 characters the next.
- - Function: set-process-filter PROCESS FILTER
+ - Function: set-process-filter process filter
This function gives PROCESS the filter function FILTER. If FILTER
is `nil', then the process will have no filter. If FILTER is `t',
then no output from the process will be accepted until the filter
but is queued, and will be processed as soon as the filter is
changed.)
- - Function: process-filter PROCESS
+ - Function: process-filter process
This function returns the filter function of PROCESS, or `nil' if
it has none. `t' means that output processing has been stopped.
(defun keep-output (process output)
(setq kept (cons output kept)))
=> keep-output
-
(setq kept nil)
=> nil
-
(set-process-filter (get-process "shell") 'keep-output)
=> keep-output
-
(process-send-string "shell" "ls ~/other\n")
=> nil
kept
=> ("lewis@slug[8] % "
-
"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
address.txt backup.psf kolstad.psf
backup.bib~ david.mss resume-Dec-86.mss~
explicitly permit output to arrive at a specific point, or even to wait
until output arrives from a process.
- - Function: accept-process-output &optional PROCESS SECONDS MILLISEC
+ - Function: accept-process-output &optional process seconds millisec
This function allows XEmacs to read pending output from processes.
The output is inserted in the associated buffers or given to
their filter functions. If PROCESS is non-`nil' then this
timing errors that could result from running them at random places in
the middle of other Lisp programs. A program can wait, so that
sentinels will run, by calling `sit-for' or `sleep-for' (*note
-Waiting::.), or `accept-process-output' (*note Accepting Output::.).
+Waiting::), or `accept-process-output' (*note Accepting Output::).
Emacs is also waiting when the command loop is reading input.
Quitting is normally inhibited within a sentinel--otherwise, the
Emacs does this automatically; sentinels never need to do it explicitly.
*Note Match Data::.
- - Function: set-process-sentinel PROCESS SENTINEL
+ - Function: set-process-sentinel process sentinel
This function associates SENTINEL with PROCESS. If SENTINEL is
`nil', then the process will have no sentinel. The default
behavior when there is no sentinel is to insert a message in the
(format "Process: %s had the event `%s'" process event)))
(set-process-sentinel (get-process "shell") 'msg-me)
=> msg-me
-
(kill-process (get-process "shell"))
-| Process: #<process shell> had the event `killed'
=> #<process shell>
- - Function: process-sentinel PROCESS
+ - Function: process-sentinel process
This function returns the sentinel of PROCESS, or `nil' if it has
none.
Process Window Size
===================
- - Function: set-process-window-size PROCESS HEIGHT WIDTH
+ - Function: set-process-window-size process height width
This function tells PROCESS that its logical window size is HEIGHT
by WIDTH characters. This is principally useful with pty's.
a transaction queue communicating with a specified process. Then you
can call `tq-enqueue' to send a transaction.
- - Function: tq-create PROCESS
+ - Function: tq-create process
This function creates and returns a transaction queue
communicating with PROCESS. The argument PROCESS should be a
subprocess capable of sending and receiving streams of bytes. It
may be a child process, or it may be a TCP connection to a server,
possibly on another machine.
- - Function: tq-enqueue QUEUE QUESTION REGEXP CLOSURE FN
+ - Function: tq-enqueue queue question regexp closure fn
This function sends a transaction to queue QUEUE. Specifying the
queue has the effect of specifying the subprocess to talk to.
The return value of `tq-enqueue' itself is not meaningful.
- - Function: tq-close QUEUE
+ - Function: tq-close queue
Shut down transaction queue QUEUE, waiting for all pending
transactions to complete, and then terminate the connection or
child process.
connection, and it never returns either of those values for a real
subprocess. *Note Process Information::.
- - Function: open-network-stream NAME BUFFER-OR-NAME HOST SERVICE
+ - Function: open-network-stream name buffer-or-name host service
This function opens a TCP connection for a service to a host. It
returns a process object to represent the connection.
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
A site may have a "default init file", which is the library named
`default.el'. XEmacs finds the `default.el' file through the standard
-search path for libraries (*note How Programs Do Loading::.). The
+search path for libraries (*note How Programs Do Loading::). The
XEmacs distribution does not come with this file; sites may provide one
for local customizations. If the default init file exists, it is
loaded whenever you start Emacs, except in batch mode or if `-q' is
not subsequently load the `default.el' file.
Another file for site-customization is `site-start.el'. Emacs loads
-this *before* the user's init file. You can inhibit the loading of
+this _before_ the user's init file. You can inhibit the loading of
this file with the option `-no-site-file'.
- Variable: site-run-file
If there is a great deal of code in your `.emacs' file, you should
move it into another file named `SOMETHING.el', byte-compile it (*note
-Byte Compilation::.), and make your `.emacs' file load the other file
-using `load' (*note Loading::.).
+Byte Compilation::), and make your `.emacs' file load the other file
+using `load' (*note Loading::).
*Note Init File Examples: (xemacs)Init File Examples, for examples
of how to make various commonly desired customizations in your `.emacs'
parent process normally resumes control. The low-level primitive for
killing XEmacs is `kill-emacs'.
- - Function: kill-emacs &optional EXIT-DATA
+ - Function: kill-emacs &optional exit-data
This function exits the XEmacs process and kills it.
If EXIT-DATA is an integer, then it is used as the exit status of
moving to a different window. Therefore, suspending is not allowed
when XEmacs is an X client.
- - Function: suspend-emacs STRING
+ - Function: suspend-emacs string
This function stops XEmacs and returns control to the superior
process. If and when the superior process resumes XEmacs,
`suspend-emacs' returns `nil' to its caller in Lisp.
The next redisplay after resumption will redraw the entire screen,
unless the variable `no-redraw-on-reenter' is non-`nil' (*note
- Refresh Screen::.).
+ Refresh Screen::).
In the following example, note that `pwd' is not echoed after
XEmacs is suspended. But it is read and executed by the shell.
(suspend-emacs)
=> nil
-
+
(add-hook 'suspend-hook
(function (lambda ()
(or (y-or-n-p
=> (lambda nil
(or (y-or-n-p "Really suspend? ")
(error "Suspend cancelled")))
-
(add-hook 'suspend-resume-hook
(function (lambda () (message "Resumed!"))))
=> (lambda nil (message "Resumed!"))
-
(suspend-emacs "pwd")
=> nil
-
---------- Buffer: Minibuffer ----------
Really suspend? y
---------- Buffer: Minibuffer ----------
-
+
---------- Parent Shell ----------
lewis@slug[23] % /user/lewis/manual
lewis@slug[24] % fg
-
+
---------- Echo Area ----------
Resumed!
fact, the function returns whatever value the variable `system-name'
currently holds. Thus, you can set the variable `system-name' in case
Emacs is confused about the name of your system. The variable is also
-useful for constructing frame titles (*note Frame Titles::.).
+useful for constructing frame titles (*note Frame Titles::).
- Variable: mail-host-address
If this variable is non-`nil', it is used instead of `system-name'
starts up, the value actually used is the one saved when XEmacs
was dumped. *Note Building XEmacs::.)
- - Function: getenv VAR
+ - Function: getenv var
This function returns the value of the environment variable VAR,
as a string. Within XEmacs, the environment variable values are
kept in the Lisp variable `process-environment'.
SHELL=/bin/csh
HOME=/user/lewis
- - Command: setenv VARIABLE VALUE
+ - Command: setenv variable value
This command sets the value of the environment variable named
VARIABLE to VALUE. Both arguments should be strings. This
function works by modifying `process-environment'; binding that
=> ("l=/usr/stanford/lib/gnuemacs/lisp"
"PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
"USER=lewis"
-
- "TERM=ibmapa16"
+ "TERM=ibmapa16"
"SHELL=/bin/csh"
"HOME=/user/lewis")
locations, but can find them in a directory related somehow to the
one containing the Emacs executable.
- - Function: load-average &optional USE-FLOATS
+ - Function: load-average &optional use-floats
This function returns a list of the current 1-minute, 5-minute and
15-minute load averages. The values are integers that are 100
times the system load averages. (The load averages indicate the
- Function: emacs-pid
This function returns the process ID of the Emacs process.
- - Function: setprv PRIVILEGE-NAME &optional SETP GETPRV
+ - Function: setprv privilege-name &optional setp getprv
This function sets or resets a VMS privilege. (It does not exist
on Unix.) The first arg is the privilege name, as a string. The
second argument, SETP, is `t' or `nil', indicating whether the
usually right, but users often set this themselves when the
default value is not right.
- - Function: user-login-name &optional UID
+ - Function: user-login-name &optional uid
If you don't specify UID, this function returns the name under
which the user is logged in. If the environment variable `LOGNAME'
is set, that value is used. Otherwise, if the environment variable
variable. You can change the value of this variable to alter the
result of the `user-full-name' function.
- - Function: user-full-name &optional USER
+ - Function: user-full-name &optional user
This function returns the full name of USER. If USER is `nil', it
defaults to the user running this Emacs. In that case, the value
of `user-full-name' variable, if non-`nil', will be used.
return the same values that the variables hold. These variables allow
you to "fake out" Emacs by telling the functions what to return. The
variables are also useful for constructing frame titles (*note Frame
-Titles::.).
+Titles::).
- Function: user-real-uid
This function returns the real UID of the user.
This section explains how to determine the current time and the time
zone.
- - Function: current-time-string &optional TIME-VALUE
+ - Function: current-time-string &optional time-value
This function returns the current time and date as a
humanly-readable string. The format of the string is unvarying;
the number of characters used for each part is always the same, so
instead of the current time. The argument should be a list whose
first two elements are integers. Thus, you can use times obtained
from `current-time' (see below) and from `file-attributes' (*note
- File Attributes::.).
+ File Attributes::).
(current-time-string)
=> "Wed Oct 14 22:21:05 1987"
as you get with the function `file-attributes'. *Note File
Attributes::.
- - Function: current-time-zone &optional TIME-VALUE
+ - Function: current-time-zone &optional time-value
This function returns a list describing the time zone that the
user is in.
instead of the current time. The argument should be a cons cell
containing two integers, or a list whose first two elements are
integers. Thus, you can use times obtained from `current-time'
- (see above) and from `file-attributes' (*note File Attributes::.).
+ (see above) and from `file-attributes' (*note File Attributes::).
\1f
File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
These functions convert time values (lists of two or three integers)
to strings or to calendrical information. There is also a function to
convert calendrical information to a time value. You can get time
-values from the functions `current-time' (*note Time of Day::.) and
-`file-attributes' (*note File Attributes::.).
+values from the functions `current-time' (*note Time of Day::) and
+`file-attributes' (*note File Attributes::).
- - Function: format-time-string FORMAT-STRING &optional TIME
+ - Function: format-time-string format-string &optional time
This function converts TIME to a string according to
FORMAT-STRING. If TIME is omitted, it defaults to the current
time. The argument FORMAT-STRING may contain `%'-sequences which
`%Z'
This stands for the time zone abbreviation.
- - Function: decode-time TIME
+ - Function: decode-time time
This function converts a time value into calendrical information.
The return value is a list of nine elements, as follows:
Note that Common Lisp has different meanings for DOW and ZONE.
- - Function: encode-time SECONDS MINUTES HOUR DAY MONTH YEAR &optional
- ZONE
+ - Function: encode-time seconds minutes hour day month year &optional
+ zone
This function is the inverse of `decode-time'. It converts seven
items of calendrical data into a time value. For the meanings of
the arguments, see the table above under `decode-time'.
You can set up a timer to call a function at a specified future time.
- - Function: add-timeout SECS FUNCTION OBJECT &optional RESIGNAL
+ - Function: add-timeout secs function object &optional resignal
This function adds a timeout, to be signaled after the timeout
period has elapsed. SECS is a number of seconds, expressed as an
integer or a float. FUNCTION will be called after that many
(NOTE: In FSF Emacs, this function is called `run-at-time' and has
different semantics.)
- - Function: disable-timeout ID
+ - Function: disable-timeout id
Cancel the requested action for ID, which should be a value
previously returned by `add-timeout'. This cancels the effect of
that call to `add-timeout'; the arrival of the specified time will
Input Modes
-----------
- - Function: set-input-mode INTERRUPT FLOW META QUIT-CHAR
+ - Function: set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input. If
INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
`nil', then it uses CBREAK mode. When XEmacs communicates
events.
If `function-key-map' "binds" a key sequence K to a vector V, then
- when K appears as a subsequence *anywhere* in a key sequence, it
+ when K appears as a subsequence _anywhere_ in a key sequence, it
is replaced with the events in V.
For example, VT100 terminals send `<ESC> O P' when the keypad PF1
Recording Input
---------------
- - Function: recent-keys &optional NUMBER
+ - Function: recent-keys &optional number
This function returns a vector containing recent input events from
the keyboard or mouse. By default, 100 events are recorded, which
is how many `recent-keys' returns.
internally. This is also the maximum number of events
`recent-keys' can return. By default, 100 events are stored.
- - Function: set-recent-keys-ring-size SIZE
+ - Function: set-recent-keys-ring-size size
This function changes the number of events stored by XEmacs and
returned by `recent-keys'.
remember last 250 events and will make `recent-keys' return last
250 events by default.
- - Command: open-dribble-file FILENAME
+ - Command: open-dribble-file filename
This function opens a "dribble file" named FILENAME. When a
dribble file is open, each input event from the keyboard or mouse
(but not those from keyboard macros) is written in that file. A
(open-dribble-file "~/dribble")
=> nil
- See also the `open-termscript' function (*note Terminal Output::.).
+ See also the `open-termscript' function (*note Terminal Output::).
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
track of output sent to the terminal. The function `device-baud-rate'
tells you what XEmacs thinks is the output speed of the terminal.
- - Function: device-baud-rate &optional DEVICE
+ - Function: device-baud-rate &optional device
This function's value is the output speed of the terminal
associated with DEVICE, as far as XEmacs knows. DEVICE defaults
to the selected device (usually the only device) if omitted.
makes decisions that are less than optimal. To fix the problem, use
`set-device-baud-rate'.
- - Function: set-device-baud-rate &optional DEVICE
+ - Function: set-device-baud-rate &optional device
This function sets the output speed of DEVICE. See
`device-baud-rate'. DEVICE defaults to the selected device
(usually the only device) if omitted.
- - Function: send-string-to-terminal CHAR-OR-STRING &optional STDOUT-P
- DEVICE
+ - Function: send-string-to-terminal char-or-string &optional stdout-p
+ device
This function sends CHAR-OR-STRING to the terminal without
alteration. Control characters in CHAR-OR-STRING have
terminal-dependent effects.
(send-string-to-terminal "\eF4\^U\^F")
=> nil
- - Command: open-termscript FILENAME
+ - Command: open-termscript filename
This function is used to open a "termscript file" that will record
all the characters sent by XEmacs to the terminal. (If there are
multiple tty or stream devices, all characters sent to all such
This function enables use of `C-s' and `C-q' for output flow
control, and provides the characters `C-\' and `C-^' as aliases
for them using `keyboard-translate-table' (*note Translating
- Input::.).
+ Input::).
You can use the function `enable-flow-control-on' in your `.emacs'
file to enable flow control automatically on certain terminal types.
- - Function: enable-flow-control-on &rest TERMTYPES
+ - Function: enable-flow-control-on &rest termtypes
This function enables flow control, and the aliases `C-\' and
`C-^', if the terminal type is one of TERMTYPES. For example:
X clients including XEmacs can read or set the selection for any given
type.
- - Function: x-own-selection DATA &optional TYPE
+ - Function: x-own-selection data &optional type
This function sets a "selection" in the X server. It takes two
arguments: a value, DATA, and the selection type TYPE to assign it
to. DATA may be a string, a cons of two markers, or an extent.
This function accesses selections set up by XEmacs or by other X
clients. It returns the value of the current primary selection.
- - Function: x-disown-selection &optional SECONDARY-P
+ - Function: x-disown-selection &optional secondary-p
Assuming we own the selection, this function disowns it. If
SECONDARY-P is non-`nil', the secondary selection instead of the
primary selection is discarded.
are considered obsolete, but XEmacs supports them for the sake of X
clients that still use them.
- - Function: x-get-cutbuffer &optional N
+ - Function: x-get-cutbuffer &optional n
This function returns the contents of cut buffer number N. (This
function is called `x-get-cut-buffer' in FSF Emacs.)
- - Function: x-store-cutbuffer STRING
+ - Function: x-store-cutbuffer string
This function stores STRING into the first cut buffer (cut buffer
0), moving the other values down through the series of cut buffers,
kill-ring-style. (This function is called `x-set-cut-buffer' in FSF
This function return the default X device for resourcing. This is
the first-created X device that still exists.
- - Function: x-get-resource NAME CLASS TYPE &optional LOCALE DEVICE
- NOERROR
+ - Function: x-get-resource name class type &optional locale device
+ noerror
This function retrieves a resource value from the X resource
manager.
`boolean', then the returned value is the list `(t)' for true,
`(nil)' for false, and is `nil' to mean "unspecified".
- - Function: x-put-resource RESOURCE-LINE &optional DEVICE
+ - Function: x-put-resource resource-line &optional device
This function adds a resource to the resource database for DEVICE.
RESOURCE-LINE specifies the resource to add and should be a
standard resource specification.
corresponding to a particular device. The device argument is generally
optional and defaults to the selected device.
- - Function: x-server-version &optional DEVICE
+ - Function: x-server-version &optional device
This function returns the list of version numbers of the X server
DEVICE is on. The returned value is a list of three integers: the
major and minor version numbers of the X protocol in use, and the
vendor-specific release number.
- - Function: x-server-vendor &optional DEVICE
+ - Function: x-server-vendor &optional device
This function returns the vendor supporting the X server DEVICE is
on.
- - Function: x-display-visual-class &optional DEVICE
+ - Function: x-display-visual-class &optional device
This function returns the visual class of the display DEVICE is
on. The value is one of the symbols `static-gray', `gray-scale',
`static-color', `pseudo-color', `true-color', and `direct-color'.
Restricting Access to the Server by Other Apps
----------------------------------------------
- - Function: x-grab-keyboard &optional DEVICE
+ - Function: x-grab-keyboard &optional device
This function grabs the keyboard on the given device (defaulting
to the selected one). So long as the keyboard is grabbed, all
keyboard events will be delivered to XEmacs - it is not possible
with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
if the grab was successful; `nil' otherwise.
- - Function: x-ungrab-keyboard &optional DEVICE
+ - Function: x-ungrab-keyboard &optional device
This function releases a keyboard grab made with `x-grab-keyboard'.
- - Function: x-grab-pointer &optional DEVICE CURSOR IGNORE-KEYBOARD
+ - Function: x-grab-pointer &optional device cursor ignore-keyboard
This function grabs the pointer and restricts it to its current
window. If optional DEVICE argument is `nil', the selected device
will be used. If optional CURSOR argument is non-`nil', change
all keyboard events during the grab. Returns `t' if the grab is
successful, `nil' otherwise.
- - Function: x-ungrab-pointer &optional DEVICE
+ - Function: x-ungrab-pointer &optional device
This function releases a pointer grab made with `x-grab-pointer'.
If optional first arg DEVICE is `nil' the selected device is used.
If it is `t' the pointer will be released on all X devices.
This variable holds the search path used by `read-color' to find
`rgb.txt'.
- - Function: x-valid-keysym-name-p KEYSYM
+ - Function: x-valid-keysym-name-p keysym
This function returns true if KEYSYM names a keysym that the X
library knows about. Valid keysyms are listed in the files
`/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
whatever the equivalents are on your system.
- - Function: x-window-id &optional FRAME
+ - Function: x-window-id &optional frame
This function returns the ID of the X11 window. This gives us a
chance to manipulate the Emacs window from within a different
program. Since the ID is an unsigned long, we return it as a
ignored. Beware: allowing XEmacs to process SendEvents opens a
big security hole.
- - Function: x-debug-mode ARG &optional DEVICE
+ - Function: x-debug-mode arg &optional device
With a true arg, make the connection to the X server synchronous.
With false, make it asynchronous. Synchronous connections are
much slower, but are useful for debugging. (If you get X errors,
Elisp Interface for Sending Messages
------------------------------------
- - Function: make-tooltalk-message ATTRIBUTES
+ - Function: make-tooltalk-message attributes
Create a ToolTalk message and initialize its attributes. The
value of ATTRIBUTES must be a list of alternating keyword/values,
where keywords are symbols that name valid message attributes.
the `ToolTalk Programmer's Guide'.
- - Function: send-tooltalk-message MSG
+ - Function: send-tooltalk-message msg
Send the message on its way. Once the message has been sent it's
almost always a good idea to get rid of it with
`destroy-tooltalk-message'.
- - Function: return-tooltalk-message MSG &optional MODE
+ - Function: return-tooltalk-message msg &optional mode
Send a reply to this message. The second argument can be `reply',
`reject' or `fail'; the default is `reply'. Before sending a
reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
should have been filled in - see `set-tooltalk-message-attribute'.
- - Function: get-tooltalk-message-attribute MSG ATTRIBUTE &optional ARGN
+ - Function: get-tooltalk-message-attribute msg attribute &optional argn
Returns the indicated ToolTalk message attribute. Attributes are
identified by symbols with the same name (underscores and all) as
the suffix of the ToolTalk `tt_message_<attribute>' function that
`arg_bval' like a string is fine.
- - Function: set-tooltalk-message-attribute VALUE MSG ATTRIBUTE
- &optional ARGN
+ - Function: set-tooltalk-message-attribute value msg attribute
+ &optional argn
Initialize one ToolTalk message attribute.
Attribute names and values are the same as for
with `add-tooltalk-message-arg'.
- - Function: add-tooltalk-message-arg MSG MODE TYPE &optional VALUE
+ - Function: add-tooltalk-message-arg msg mode type &optional value
Append one new argument to the message. MODE must be one of
`TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
can be a string or an integer. ToolTalk doesn't define any
initialize a message.
- - Function: destroy-tooltalk-message MSG
+ - Function: destroy-tooltalk-message msg
Apply `tt_message_destroy' to the message. It's not necessary to
destroy messages after they've been processed by a message or
pattern callback, the Lisp/ToolTalk callback machinery does this
Elisp Interface for Receiving Messages
--------------------------------------
- - Function: make-tooltalk-pattern ATTRIBUTES
+ - Function: make-tooltalk-pattern attributes
Create a ToolTalk pattern and initialize its attributes. The
value of attributes must be a list of alternating keyword/values,
where keywords are symbols that name valid pattern attributes or
the `ToolTalk Programmer's Guide'.
- - Function: register-tooltalk-pattern PAT
+ - Function: register-tooltalk-pattern pat
XEmacs will begin receiving messages that match this pattern.
- - Function: unregister-tooltalk-pattern PAT
+ - Function: unregister-tooltalk-pattern pat
XEmacs will stop receiving messages that match this pattern.
- - Function: add-tooltalk-pattern-attribute VALUE PAT INDICATOR
+ - Function: add-tooltalk-pattern-attribute value pat indicator
Add one value to the indicated pattern attribute. The names of
attributes are the same as the ToolTalk accessors used to set them
less the `tooltalk_pattern_' prefix and the `_add' suffix. For
argument. It will be called each time the pattern matches an
incoming message.
- - Function: add-tooltalk-pattern-arg PAT MODE TYPE VALUE
+ - Function: add-tooltalk-pattern-arg pat mode type value
Add one fully-specified argument to a ToolTalk pattern. MODE must
be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
string. VALUE can be an integer, string or `nil'. If VALUE is an
Create a new ToolTalk pattern and initialize its session attribute
to be the default session.
- - Function: destroy-tooltalk-pattern PAT
+ - Function: destroy-tooltalk-pattern pat
Apply `tt_pattern_destroy' to the pattern. This effectively
unregisters the pattern.
- - Function: describe-tooltalk-message MSG &optional STREAM
+ - Function: describe-tooltalk-message msg &optional stream
Print the message's attributes and arguments to STREAM. This is
often useful for debugging.
linking to an external LDAP client library. As of 21.2, XEmacs has been
successfully built and tested with
- * OpenLDAP 1.0.3 (`http://www.openldap.org/')
+ * OpenLDAP 1.0.3 (<http://www.openldap.org/>)
* University of Michigan's LDAP 3.3
- (`http://www.umich.edu/~dirsvcs/ldap/')
+ (<http://www.umich.edu/~dirsvcs/ldap/>)
- * LDAP SDK 1.0 from Netscape Corp. (`http://developer.netscape.com/')
+ * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
Other libraries conforming to RFC 1823 will probably work also but
may require some minor tweaking at C level.
- Variable: ldap-host-parameters-alist
An alist of per host options for LDAP transactions. The list
- elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
+ elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
name of an LDAP server. A TCP port number can be appended to that
name using a colon as a separator. PROPN and VALN are
property/value pairs describing parameters for the server. Valid
perform LDAP searches. It opens a connection to a host, performs the
query and cleanly closes the connection thus insulating the user from
all the details of the low-level interface such as LDAP Lisp objects
-*note The Low-Level LDAP API::.
+*note The Low-Level LDAP API::
- - Function: ldap-search FILTER &optional HOST ATTRIBUTES ATTRSONLY
+ - Function: ldap-search filter &optional host attributes attrsonly
Perform an LDAP search. FILTER is the search filter *note Syntax
- of Search Filters::. HOST is the LDAP host on which to perform
- the search ATTRIBUTES is the specific attributes to retrieve,
- `nil' means retrieve all ATTRSONLY if non-`nil' retrieves the
- attributes only without their associated values. Additional
- search parameters can be specified through
- `ldap-host-parameters-alist'.
+ of Search Filters:: HOST is the LDAP host on which to perform the
+ search ATTRIBUTES is the specific attributes to retrieve, `nil'
+ means retrieve all ATTRSONLY if non-`nil' retrieves the attributes
+ only without their associated values. Additional search
+ parameters can be specified through `ldap-host-parameters-alist'.
\1f
File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
An internal built-in `ldap' lisp object represents a LDAP connection.
- - Function: ldapp OBJECT
+ - Function: ldapp object
This function returns non-`nil' if OBJECT is a `ldap' object.
- - Function: ldap-host LDAP
+ - Function: ldap-host ldap
Return the server host of the connection represented by LDAP
- - Function: ldap-live-p LDAP
+ - Function: ldap-live-p ldap
Return non-`nil' if LDAP is an active LDAP connection
\1f
Opening and Closing a LDAP Connection
.....................................
- - Function: ldap-open HOST &optional PLIST
+ - Function: ldap-open host &optional plist
Open a LDAP connection to HOST. PLIST is a property list
containing additional parameters for the connection. Valid keys
in that list are:
The maximum number of matches to return for searches
performed on this connection.
- - Function: ldap-close LDAP
+ - Function: ldap-close ldap
Close the connection represented by LDAP
\1f
can be made on the same connection, then the session must be closed
with `ldap-close'.
- - Function: ldap-search-internal LDAP FILTER BASE SCOPE ATTRS ATTRSONLY
+ - Function: ldap-search-internal ldap filter base scope attrs attrsonly
Perform a search on an open connection LDAP created with
`ldap-open'. FILTER is a filter string for the search *note
- Syntax of Search Filters::. BASE is the distinguished name at
- which to start the search. SCOPE is one of the symbols `base',
+ Syntax of Search Filters:: BASE is the distinguished name at which
+ to start the search. SCOPE is one of the symbols `base',
`onelevel' or `subtree' indicating the scope of the search limited
to a base object, to a single level or to the whole subtree. The
default is `subtree'. `attrs' is a list of strings indicating
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Level 3 Primitives
------------------
- - Function: gettext STRING
+ - Function: gettext string
This function looks up STRING in the default message domain and
returns its translation. If `I18N3' was not enabled when XEmacs
was compiled, it just returns STRING.
- - Function: dgettext DOMAIN STRING
+ - Function: dgettext domain string
This function looks up STRING in the specified message domain and
returns its translation. If `I18N3' was not enabled when XEmacs
was compiled, it just returns STRING.
- - Function: bind-text-domain DOMAIN PATHNAME
+ - Function: bind-text-domain domain pathname
This function associates a pathname with a message domain. Here's
how the path to message file is constructed under SunOS 5.x:
If `I18N3' was not enabled when XEmacs was compiled, this function
does nothing.
- - Special Form: domain STRING
+ - Special Form: domain string
This function specifies the text domain used for translating
documentation strings and interactive prompts of a function. For
example, write:
The "call" to `domain' is actually a declaration rather than a
function; when actually called, `domain' just returns `nil'.
- - Function: domain-of FUNCTION
+ - Function: domain-of function
This function returns the text domain of FUNCTION; it returns
`nil' if it is the default domain. If `I18N3' was not enabled
when XEmacs was compiled, it always returns `nil'.
For variables and constants which have documentation strings,
specify the domain after the documentation.
- - Special Form: defvar SYMBOL [VALUE [DOC-STRING [DOMAIN]]]
+ - Special Form: defvar symbol [value [doc-string [domain]]]
Example:
(defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
- - Special Form: defconst SYMBOL [VALUE [DOC-STRING [DOMAIN]]]
+ - Special Form: defconst symbol [value [doc-string [domain]]]
Example:
(defconst limbs 4 "Number of limbs" "emacs-gorilla")
extracted into the main message base. However, for autoloaded functions
which are specified in a separate package, use following syntax:
- - Function: autoload SYMBOL FILENAME &optional DOCSTRING INTERACTIVE
- MACRO DOMAIN
+ - Function: autoload symbol filename &optional docstring interactive
+ macro domain
Example:
(autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
has thousands of characters, and is of dimension two - every character
is indexed by two position codes, each in the range 33 through 126.
(Note that the choice of the range here is somewhat arbitrary.
-Although a character set such as JISX0208 defines an *ordering* of all
+Although a character set such as JISX0208 defines an _ordering_ of all
its characters, it does not define the actual mapping between numbers
and characters. You could just as easily index the characters in
JISX0208 using numbers in the range 0 through 93, 1 through 94, 2
character set as well as an ordering of those characters. Charsets are
permanent objects and are named using symbols, like faces.
- - Function: charsetp OBJECT
+ - Function: charsetp object
This function returns non-`nil' if OBJECT is a charset.
* Menu:
Basic Charset Functions
-----------------------
- - Function: find-charset CHARSET-OR-NAME
+ - Function: find-charset charset-or-name
This function retrieves the charset of the given name. If
CHARSET-OR-NAME is a charset object, it is simply returned.
Otherwise, CHARSET-OR-NAME should be a symbol. If there is no
such charset, `nil' is returned. Otherwise the associated charset
object is returned.
- - Function: get-charset NAME
+ - Function: get-charset name
This function retrieves the charset of the given name. Same as
`find-charset' except an error is signalled if there is no such
charset instead of returning `nil'.
- Function: charset-list
This function returns a list of the names of all defined charsets.
- - Function: make-charset NAME DOC-STRING PROPS
+ - Function: make-charset name doc-string props
This function defines a new character set. This function is for
use with Mule support. NAME is a symbol, the name by which the
character set is normally referred. DOC-STRING is a string
`chars', `final', `graphic', `direction', and `ccl-program', as
previously described.
- - Function: make-reverse-direction-charset CHARSET NEW-NAME
+ - Function: make-reverse-direction-charset charset new-name
This function makes a charset equivalent to CHARSET but which goes
in the opposite direction. NEW-NAME is the name of the new
charset. The new charset is returned.
- - Function: charset-from-attributes DIMENSION CHARS FINAL &optional
- DIRECTION
+ - Function: charset-from-attributes dimension chars final &optional
+ direction
This function returns a charset with the given DIMENSION, CHARS,
FINAL, and DIRECTION. If DIRECTION is omitted, both directions
will be checked (left-to-right will be returned if character sets
exist for both directions).
- - Function: charset-reverse-direction-charset CHARSET
+ - Function: charset-reverse-direction-charset charset
This function returns the charset (if any) with the same dimension,
number of characters, and final byte as CHARSET, but which is
displayed in the opposite direction.
All of these functions accept either a charset name or charset
object.
- - Function: charset-property CHARSET PROP
+ - Function: charset-property charset prop
This function returns property PROP of CHARSET. *Note Charset
Properties::.
Convenience functions are also provided for retrieving individual
properties of a charset.
- - Function: charset-name CHARSET
+ - Function: charset-name charset
This function returns the name of CHARSET. This will be a symbol.
- - Function: charset-doc-string CHARSET
+ - Function: charset-doc-string charset
This function returns the doc string of CHARSET.
- - Function: charset-registry CHARSET
+ - Function: charset-registry charset
This function returns the registry of CHARSET.
- - Function: charset-dimension CHARSET
+ - Function: charset-dimension charset
This function returns the dimension of CHARSET.
- - Function: charset-chars CHARSET
+ - Function: charset-chars charset
This function returns the number of characters per dimension of
CHARSET.
- - Function: charset-columns CHARSET
+ - Function: charset-columns charset
This function returns the number of display columns per character
(in TTY mode) of CHARSET.
- - Function: charset-direction CHARSET
+ - Function: charset-direction charset
This function returns the display direction of CHARSET - either
`l2r' or `r2l'.
- - Function: charset-final CHARSET
+ - Function: charset-final charset
This function returns the final byte of the ISO 2022 escape
sequence designating CHARSET.
- - Function: charset-graphic CHARSET
+ - Function: charset-graphic charset
This function returns either 0 or 1, depending on whether the
position codes of characters in CHARSET map to the left or right
half of their font, respectively.
- - Function: charset-ccl-program CHARSET
+ - Function: charset-ccl-program charset
This function returns the CCL program, if any, for converting
position codes of characters in CHARSET into font indices.
The only property of a charset that can currently be set after the
charset has been created is the CCL program.
- - Function: set-charset-ccl-program CHARSET CCL-PROGRAM
+ - Function: set-charset-ccl-program charset ccl-program
This function sets the `ccl-program' property of CHARSET to
CCL-PROGRAM.
MULE Characters
===============
- - Function: make-char CHARSET ARG1 &optional ARG2
+ - Function: make-char charset arg1 &optional arg2
This function makes a multi-byte character from CHARSET and octets
ARG1 and ARG2.
- - Function: char-charset CH
+ - Function: char-charset ch
This function returns the character set of char CH.
- - Function: char-octet CH &optional N
+ - Function: char-octet ch &optional n
This function returns the octet (i.e. position code) numbered N
(should be 0 or 1) of char CH. N defaults to 0 if omitted.
- - Function: find-charset-region START END &optional BUFFER
+ - Function: find-charset-region start end &optional buffer
This function returns a list of the charsets in the region between
START and END. BUFFER defaults to the current buffer if omitted.
- - Function: find-charset-string STRING
+ - Function: find-charset-string string
This function returns a list of the charsets in STRING.
\1f
Composite characters are not yet completely implemented.
- - Function: make-composite-char STRING
+ - Function: make-composite-char string
This function converts a string into a single composite character.
The character is the result of overstriking all the characters in
the string.
- - Function: composite-char-string CH
+ - Function: composite-char-string ch
This function returns a string of the characters comprising a
composite character.
- - Function: compose-region START END &optional BUFFER
+ - Function: compose-region start end &optional buffer
This function composes the characters in the region from START to
END in BUFFER into one composite character. The composite
character replaces the composed characters. BUFFER defaults to
the current buffer if omitted.
- - Function: decompose-region START END &optional BUFFER
+ - Function: decompose-region start end &optional buffer
This function decomposes any composite characters in the region
from START to END in BUFFER. This converts each composite
character into one or more characters, the individual characters
a coding system is called for. (This is similar to how faces and
charsets work.)
- - Function: coding-system-p OBJECT
+ - Function: coding-system-p object
This function returns non-`nil' if OBJECT is a coding system.
* Menu:
Basic Coding System Functions
-----------------------------
- - Function: find-coding-system CODING-SYSTEM-OR-NAME
+ - Function: find-coding-system coding-system-or-name
This function retrieves the coding system of the given name.
If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply
If there is no such coding system, `nil' is returned. Otherwise
the associated coding system object is returned.
- - Function: get-coding-system NAME
+ - Function: get-coding-system name
This function retrieves the coding system of the given name. Same
as `find-coding-system' except an error is signalled if there is no
such coding system instead of returning `nil'.
This function returns a list of the names of all defined coding
systems.
- - Function: coding-system-name CODING-SYSTEM
+ - Function: coding-system-name coding-system
This function returns the name of the given coding system.
- - Function: make-coding-system NAME TYPE &optional DOC-STRING PROPS
+ - Function: make-coding-system name type &optional doc-string props
This function registers symbol NAME as a coding system.
TYPE describes the conversion method used and should be one of the
character set. Recognized properties are as in *Note Coding
System Properties::.
- - Function: copy-coding-system OLD-CODING-SYSTEM NEW-NAME
+ - Function: copy-coding-system old-coding-system new-name
This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME
does not name an existing coding system, a new one will be created.
- - Function: subsidiary-coding-system CODING-SYSTEM EOL-TYPE
+ - Function: subsidiary-coding-system coding-system eol-type
This function returns the subsidiary coding system of
CODING-SYSTEM with eol type EOL-TYPE.
Coding System Property Functions
--------------------------------
- - Function: coding-system-doc-string CODING-SYSTEM
+ - Function: coding-system-doc-string coding-system
This function returns the doc string for CODING-SYSTEM.
- - Function: coding-system-type CODING-SYSTEM
+ - Function: coding-system-type coding-system
This function returns the type of CODING-SYSTEM.
- - Function: coding-system-property CODING-SYSTEM PROP
+ - Function: coding-system-property coding-system prop
This function returns the PROP property of CODING-SYSTEM.
\1f
Encoding and Decoding Text
--------------------------
- - Function: decode-coding-region START END CODING-SYSTEM &optional
- BUFFER
+ - Function: decode-coding-region start end coding-system &optional
+ buffer
This function decodes the text between START and END which is
encoded in CODING-SYSTEM. This is useful if you've read in
encoded text from a file without decoding it (e.g. you read in a
encoded text is returned. BUFFER defaults to the current buffer
if unspecified.
- - Function: encode-coding-region START END CODING-SYSTEM &optional
- BUFFER
+ - Function: encode-coding-region start end coding-system &optional
+ buffer
This function encodes the text between START and END using
CODING-SYSTEM. This will, for example, convert Japanese
characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
- Function: coding-category-list
This function returns a list of all recognized coding categories.
- - Function: set-coding-priority-list LIST
+ - Function: set-coding-priority-list list
This function changes the priority order of the coding categories.
LIST should be a list of coding categories, in descending order of
priority. Unspecified coding categories will be lower in priority
This function returns a list of coding categories in descending
order of priority.
- - Function: set-coding-category-system CODING-CATEGORY CODING-SYSTEM
+ - Function: set-coding-category-system coding-category coding-system
This function changes the coding system associated with a coding
category.
- - Function: coding-category-system CODING-CATEGORY
+ - Function: coding-category-system coding-category
This function returns the coding system associated with a coding
category.
- - Function: detect-coding-region START END &optional BUFFER
+ - Function: detect-coding-region start end &optional buffer
This function detects coding system of the text in the region
between START and END. Returned value is a list of possible coding
systems ordered by priority. If only ASCII characters are found,
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
These are special functions for working with the non-standard
Shift-JIS and Big5 encodings.
- - Function: decode-shift-jis-char CODE
+ - Function: decode-shift-jis-char code
This function decodes a JISX0208 character of Shift-JIS
coding-system. CODE is the character code in Shift-JIS as a cons
of type bytes. The corresponding character is returned.
- - Function: encode-shift-jis-char CH
+ - Function: encode-shift-jis-char ch
This function encodes a JISX0208 character CH to SHIFT-JIS
coding-system. The corresponding character code in SHIFT-JIS is
returned as a cons of two bytes.
- - Function: decode-big5-char CODE
+ - Function: decode-big5-char code
This function decodes a Big5 character CODE of BIG5 coding-system.
CODE is the character code in BIG5. The corresponding character
is returned.
- - Function: encode-big5-char CH
+ - Function: encode-big5-char ch
This function encodes the Big5 character CHAR to BIG5
coding-system. The corresponding character code in Big5 is
returned.
they return parts of their values in `r7'. Y may be an expression,
register, or integer, while Z must be a register or an integer.
-Name Operator Code C-like Description
-CCL_PLUS `+' 0x00 X = Y + Z
-CCL_MINUS `-' 0x01 X = Y - Z
-CCL_MUL `*' 0x02 X = Y * Z
-CCL_DIV `/' 0x03 X = Y / Z
-CCL_MOD `%' 0x04 X = Y % Z
-CCL_AND `&' 0x05 X = Y & Z
-CCL_OR `|' 0x06 X = Y | Z
-CCL_XOR `^' 0x07 X = Y ^ Z
-CCL_LSH `<<' 0x08 X = Y << Z
-CCL_RSH `>>' 0x09 X = Y >> Z
-CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z
-CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF
-CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z
-CCL_LS `<' 0x10 X = (X < Y)
-CCL_GT `>' 0x11 X = (X > Y)
-CCL_EQ `==' 0x12 X = (X == Y)
-CCL_LE `<=' 0x13 X = (X <= Y)
-CCL_GE `>=' 0x14 X = (X >= Y)
-CCL_NE `!=' 0x15 X = (X != Y)
-CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z))
- r[7] = LOWER_BYTE (SJIS (Y, Z)
-CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z))
- r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
+Name Operator Code C-like Description
+CCL_PLUS `+' 0x00 X = Y + Z
+CCL_MINUS `-' 0x01 X = Y - Z
+CCL_MUL `*' 0x02 X = Y * Z
+CCL_DIV `/' 0x03 X = Y / Z
+CCL_MOD `%' 0x04 X = Y % Z
+CCL_AND `&' 0x05 X = Y & Z
+CCL_OR `|' 0x06 X = Y | Z
+CCL_XOR `^' 0x07 X = Y ^ Z
+CCL_LSH `<<' 0x08 X = Y << Z
+CCL_RSH `>>' 0x09 X = Y >> Z
+CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z
+CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF
+CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z
+CCL_LS `<' 0x10 X = (X < Y)
+CCL_GT `>' 0x11 X = (X > Y)
+CCL_EQ `==' 0x12 X = (X == Y)
+CCL_LE `<=' 0x13 X = (X <= Y)
+CCL_GE `>=' 0x14 X = (X >= Y)
+CCL_NE `!=' 0x15 X = (X != Y)
+CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z))
+ r[7] = LOWER_BYTE (SJIS (Y, Z)
+CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z))
+ r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
The CCL operators are as in C, with the addition of CCL_LSH8,
CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The
CCL programs are called automatically during Emacs buffer I/O when
the external representation has a coding system type of `shift-jis',
`big5', or `ccl'. The program is specified by the coding system (*note
-Coding Systems::.). You can also call CCL programs from other CCL
+Coding Systems::). You can also call CCL programs from other CCL
programs, and from Lisp using these functions:
- - Function: ccl-execute CCL-PROGRAM STATUS
+ - Function: ccl-execute ccl-program status
Execute CCL-PROGRAM with registers initialized by STATUS.
CCL-PROGRAM is a vector of compiled CCL code created by
`ccl-compile'. It is an error for the program to try to execute a
side-effect) to contain the ending values for the corresponding
registers and IC.
- - Function: ccl-execute-on-string CCL-PROGRAM STATUS STR &optional
- CONTINUE
+ - Function: ccl-execute-on-string ccl-program status str &optional
+ continue
Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is
a vector of compiled CCL code created by `ccl-compile'. STATUS
must be a vector of nine values, specifying the initial value for
To call a CCL program from another CCL program, it must first be
registered:
- - Function: register-ccl-program NAME CCL-PROGRAM
+ - Function: register-ccl-program name ccl-program
Register NAME for CCL program PROGRAM in `ccl-program-table'.
PROGRAM should be the compiled form of a CCL program, or nil.
Return index number of the registered CCL program.
Special Lisp functions are provided that abstract this, so you do not
have to directly manipulate bit vectors.
- - Function: category-table-p OBJ
+ - Function: category-table-p obj
This function returns `t' if ARG is a category table.
- - Function: category-table &optional BUFFER
+ - Function: category-table &optional buffer
This function returns the current category table. This is the one
specified by the current buffer, or by BUFFER if it is non-`nil'.
This function returns the standard category table. This is the
one used for new buffers.
- - Function: copy-category-table &optional TABLE
+ - Function: copy-category-table &optional table
This function constructs a new category table and return it. It
is a copy of the TABLE, which defaults to the standard category
table.
- - Function: set-category-table TABLE &optional BUFFER
+ - Function: set-category-table table &optional buffer
This function selects a new category table for BUFFER. One
argument, a category table. BUFFER defaults to the current buffer
if omitted.
- - Function: category-designator-p OBJ
+ - Function: category-designator-p obj
This function returns `t' if ARG is a category designator (a char
in the range `' '' to `'~'').
- - Function: category-table-value-p OBJ
+ - Function: category-table-value-p obj
This function returns `t' if ARG is a category table value. Valid
values are `nil' or a bit vector of size 95.
right. *Note Compiling Macros::.
Using `eval-when-compile' avoids loading BAR when the compiled
- version of FOO is *used*.
+ version of FOO is _used_.
* If you define a major mode, make sure to run a hook variable using
`run-hooks', just as the existing major modes do. *Note Hooks::.
* When a package provides a modification of ordinary Emacs behavior,
it is good to include a command to enable and disable the feature,
Provide a command named `WHATEVER-mode' which turns the feature on
- or off, and make it autoload (*note Autoload::.). Design the
+ or off, and make it autoload (*note Autoload::). Design the
package so that simply loading it has no visible effect--that
should not enable the feature. Users will request the feature by
invoking the command.
the function is handled specially.
For example, the following input will show you that `aref' is
- compiled specially (*note Array Functions::.) while `elt' is not
- (*note Sequence Functions::.):
+ compiled specially (*note Array Functions::) while `elt' is not
+ (*note Sequence Functions::):
(get 'aref 'byte-compile)
=> byte-compile-two-args
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
To create `xemacs', use the command `temacs -batch -l loadup dump'.
The purpose of `-batch' here is to tell `temacs' to run in
-non-interactive, command-line mode. (`temacs' can *only* run in this
+non-interactive, command-line mode. (`temacs' can _only_ run in this
fashion. Part of the code required to initialize frames and faces is
in Lisp, and must be loaded before XEmacs is able to create any frames.)
The argument `dump' tells `loadup.el' to dump a new executable named
You can specify additional files to preload by writing a library
named `site-load.el' that loads them. You may need to increase the
value of `PURESIZE', in `src/puresize.h', to make room for the
-additional files. You should *not* modify this file directly, however;
+additional files. You should _not_ modify this file directly, however;
instead, use the `--puresize' configuration option. (If you run out of
pure space while dumping `xemacs', you will be told how much pure space
you actually will need.) However, the advantage of preloading
Before `loadup.el' dumps the new executable, it finds the
documentation strings for primitive and preloaded functions (and
variables) in the file where they are stored, by calling
-`Snarf-documentation' (*note Accessing Documentation::.). These
-strings were moved out of the `xemacs' executable to make it smaller.
-*Note Documentation Basics::.
+`Snarf-documentation' (*note Accessing Documentation::). These strings
+were moved out of the `xemacs' executable to make it smaller. *Note
+Documentation Basics::.
- - Function: dump-emacs TO-FILE FROM-FILE
+ - Function: dump-emacs to-file from-file
This function dumps the current state of XEmacs into an executable
file TO-FILE. It takes symbols from FROM-FILE (this is normally
the executable file `temacs').
must set `command-line-processed' to `nil' first for good results.
*Note Command Line Arguments::.
- - Function: run-emacs-from-temacs &rest ARGS
+ - Function: run-emacs-from-temacs &rest args
This is the function that implements the `run-temacs' command-line
argument. It is called from `loadup.el' as appropriate. You
- should most emphatically *not* call this yourself; it will
+ should most emphatically _not_ call this yourself; it will
reinitialize your XEmacs process and you'll be sorry.
- Command: emacs-version
you try to preload additional libraries or add features to the standard
ones.
- - Function: purecopy OBJECT
+ - Function: purecopy object
This function makes a copy of OBJECT in pure storage and returns
it. It copies strings by simply making a new string with the same
characters in pure storage. It recursively copies the contents of
define such variables for their internal use; we don't list them here.
`abbrev-mode'
- *note Abbrevs::.
+ *note Abbrevs::
`auto-fill-function'
- *note Auto Filling::.
+ *note Auto Filling::
`buffer-auto-save-file-name'
- *note Auto-Saving::.
+ *note Auto-Saving::
`buffer-backed-up'
- *note Backup Files::.
+ *note Backup Files::
`buffer-display-table'
- *note Display Tables::.
+ *note Display Tables::
`buffer-file-format'
- *note Format Conversion::.
+ *note Format Conversion::
`buffer-file-name'
- *note Buffer File Name::.
+ *note Buffer File Name::
`buffer-file-number'
- *note Buffer File Name::.
+ *note Buffer File Name::
`buffer-file-truename'
- *note Buffer File Name::.
+ *note Buffer File Name::
`buffer-file-type'
- *note Files and MS-DOS::.
+ *note Files and MS-DOS::
`buffer-invisibility-spec'
- *note Invisible Text::.
+ *note Invisible Text::
`buffer-offer-save'
- *note Saving Buffers::.
+ *note Saving Buffers::
`buffer-read-only'
- *note Read Only Buffers::.
+ *note Read Only Buffers::
`buffer-saved-size'
- *note Point::.
+ *note Point::
`buffer-undo-list'
- *note Undo::.
+ *note Undo::
`cache-long-line-scans'
- *note Text Lines::.
+ *note Text Lines::
`case-fold-search'
- *note Searching and Case::.
+ *note Searching and Case::
`ctl-arrow'
- *note Usual Display::.
+ *note Usual Display::
`comment-column'
*note Comments: (emacs)Comments.
`default-directory'
- *note System Environment::.
+ *note System Environment::
`defun-prompt-regexp'
- *note List Motion::.
+ *note List Motion::
`fill-column'
- *note Auto Filling::.
+ *note Auto Filling::
`goal-column'
*note Moving Point: (emacs)Moving Point.
`left-margin'
- *note Indentation::.
+ *note Indentation::
`local-abbrev-table'
- *note Abbrevs::.
+ *note Abbrevs::
`local-write-file-hooks'
- *note Saving Buffers::.
+ *note Saving Buffers::
`major-mode'
- *note Mode Help::.
+ *note Mode Help::
`mark-active'
- *note The Mark::.
+ *note The Mark::
`mark-ring'
- *note The Mark::.
+ *note The Mark::
`minor-modes'
- *note Minor Modes::.
+ *note Minor Modes::
`modeline-format'
- *note Modeline Data::.
+ *note Modeline Data::
`modeline-buffer-identification'
- *note Modeline Variables::.
+ *note Modeline Variables::
`modeline-format'
- *note Modeline Data::.
+ *note Modeline Data::
`modeline-modified'
- *note Modeline Variables::.
+ *note Modeline Variables::
`modeline-process'
- *note Modeline Variables::.
+ *note Modeline Variables::
`mode-name'
- *note Modeline Variables::.
+ *note Modeline Variables::
`overwrite-mode'
- *note Insertion::.
+ *note Insertion::
`paragraph-separate'
- *note Standard Regexps::.
+ *note Standard Regexps::
`paragraph-start'
- *note Standard Regexps::.
+ *note Standard Regexps::
`point-before-scroll'
Used for communication between mouse commands and scroll-bar
commands.
`require-final-newline'
- *note Insertion::.
+ *note Insertion::
`selective-display'
- *note Selective Display::.
+ *note Selective Display::
`selective-display-ellipses'
- *note Selective Display::.
+ *note Selective Display::
`tab-width'
- *note Usual Display::.
+ *note Usual Display::
`truncate-lines'
- *note Truncation::.
+ *note Truncation::
`vc-mode'
- *note Modeline Variables::.
+ *note Modeline Variables::
\1f
File: lispref.info, Node: Standard Keymaps, Next: Standard Hooks, Prev: Standard Buffer-Local Variables, Up: Top
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* check-valid-spec-list: Specifier Validation Functions.
* child process: Processes.
* children, of extent: Extent Parents.
-* CL note---allocate more storage: Garbage Collection.
-* CL note---case of letters: Symbol Type.
-* CL note---default optional arg: Argument List.
-* CL note---integers vrs eq: Comparison of Numbers.
-* CL note---lack union, set: Sets And Lists.
-* CL note---no continuable errors: Signaling Errors.
-* CL note---only throw in Emacs: Catch and Throw.
-* CL note---rplaca vrs setcar: Modifying Lists.
-* CL note---set local: Setting Variables.
-* CL note---special forms compared: Special Forms.
-* CL note---special variables: Variable Scoping.
-* CL note---symbol in obarrays: Creating Symbols.
+* CL note--allocate more storage: Garbage Collection.
+* CL note--case of letters: Symbol Type.
+* CL note--default optional arg: Argument List.
+* CL note--integers vrs eq: Comparison of Numbers.
+* CL note--lack union, set: Sets And Lists.
+* CL note--no continuable errors: Signaling Errors.
+* CL note--only throw in Emacs: Catch and Throw.
+* CL note--rplaca vrs setcar: Modifying Lists.
+* CL note--set local: Setting Variables.
+* CL note--special forms compared: Special Forms.
+* CL note--special variables: Variable Scoping.
+* CL note--symbol in obarrays: Creating Symbols.
* cl-read: Reading in Edebug.
* cl-specs.el: Instrumenting.
* cl.el (Edebug): Instrumenting.
-This is Info file ../../info/new-users-guide.info, produced by Makeinfo
-version 1.68 from the input file new-users-guide.texi.
+This is ../info/new-users-guide.info, produced by makeinfo version 4.0
+from new-users-guide/new-users-guide.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
- -- The Detailed Node Listing --
+ --- The Detailed Node Listing ---
Entering and Exiting Emacs
Cut
Removes the selected text block from the current buffer, makes it
the X clipboard selection, and places it in the kill ring (*note
- Moving Text::.). Before executing this command, you have to select
+ Moving Text::). Before executing this command, you have to select
a region using Emacs region selection commands or with the mouse.
*Note Selecting Text::.
Some of the functions which are available to you for customization
are:
- 1. add-menu-item: (MENU-NAME ITEM-NAME FUNCTION ENABLED-P &OPTIONAL
+ 1. add-menu-item: (MENU-NAME ITEM-NAME FUNCTION ENABLED-P &optional
BEFORE)
This function will add a menu item to a menu, creating the menu
first if necessary. If the named item already exists, the menu
will remain unchanged. For example, if you add the following
example to your `.emacs' file or evaluate it (*note Customization
- Basics::.),
+ Basics::),
(add-menu-item '("Edit") "Replace String" replace-string t "Clear")
-This is Info file ../../info/new-users-guide.info, produced by Makeinfo
-version 1.68 from the input file new-users-guide.texi.
+This is ../info/new-users-guide.info, produced by makeinfo version 4.0
+from new-users-guide/new-users-guide.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
will create a "backup" file. Select the Describe variable option from
the Help menu and look at the documentation for this variable. Its
default value should be `t'. However, if its not then use `M-x
-set-variable' to set it to `t' (*note Setting Variables::.). The backup
+set-variable' to set it to `t' (*note Setting Variables::). The backup
file will contain the contents from the last time you visited the file.
Emacs also provides options for creating numbered backups. For more
information on backups, *Note Backup: (xemacs)Backup.
example above.
Similarly, to enable the "font-lock mode" which displays your
-program in different fonts and colors(*note Modes::.), put the
-following in your `.emacs' file. The comments above the statement
-explain what the statements do.
+program in different fonts and colors(*note Modes::), put the following
+in your `.emacs' file. The comments above the statement explain what the
+statements do.
;;; enables the font-lock-mode in Lisp Mode
(add-hook 'lisp-mode-hook 'turn-on-font-lock)
examples in
`/usr/local/lib/xemacs-20.0/lisp/packages/big-menubar.el' file.
+
For more information on initializing your `.emacs' file, *Note Init
File: (xemacs)Init File. You should also look at
`/usr/local/lib/xemacs-20.0/etc/sample.emacs', which is a sample
-This is Info file ../../info/new-users-guide.info, produced by Makeinfo
-version 1.68 from the input file new-users-guide.texi.
+This is ../info/new-users-guide.info, produced by makeinfo version 4.0
+from new-users-guide/new-users-guide.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-This is Info file ../info/standards.info, produced by Makeinfo version
-1.68 from the input file standards.texi.
+This is ../info/standards.info, produced by makeinfo version 4.0 from
+standards.texi.
START-INFO-DIR-ENTRY
* Standards: (standards). GNU coding standards.
END-INFO-DIR-ENTRY
- GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
-Software Foundation, Inc.
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
Version
*******
- Last updated 17 May 1996.
+ Last updated June 24, 1999.
* Menu:
-* Preface:: About the GNU Coding Standards
-* Intellectual Property:: Keeping Free Software Free
-* Design Advice:: General Program Design
-* Program Behavior:: Program Behavior for All Programs
-* Writing C:: Making The Best Use of C
-* Documentation:: Documenting Programs
-* Managing Releases:: The Release Process
+* Preface:: About the GNU Coding Standards
+* Legal Issues:: Keeping Free Software Free
+* Design Advice:: General Program Design
+* Program Behavior:: Program Behavior for All Programs
+* Writing C:: Making The Best Use of C
+* Documentation:: Documenting Programs
+* Managing Releases:: The Release Process
+* References:: References to Non-Free Software or Documentation
\1f
-File: standards.info, Node: Preface, Next: Intellectual Property, Prev: Top, Up: Top
+File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
About the GNU Coding Standards
******************************
even if you write in another programming language. The rules often
state reasons for writing in a certain way.
- Corrections or suggestions regarding this document should be sent to
-`gnu@prep.ai.mit.edu'. If you make a suggestion, please include a
-suggested new wording for it; our time is limited. We prefer a context
-diff to the `standards.texi' or `make-stds.texi' files, but if you
-don't have those files, please mail your suggestion anyway.
+ Corrections or suggestions for this document should be sent to
+<gnu@gnu.org>. If you make a suggestion, please include a suggested
+new wording for it; our time is limited. We prefer a context diff to
+the `standards.texi' or `make-stds.texi' files, but if you don't have
+those files, please mail your suggestion anyway.
- This release of the GNU Coding Standards was last updated 17 May
-1996.
+ This release of the GNU Coding Standards was last updated June 24,
+1999.
\1f
-File: standards.info, Node: Intellectual Property, Next: Design Advice, Prev: Preface, Up: Top
+File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
Keeping Free Software Free
**************************
* Menu:
-* Reading Non-Free Code:: Referring to Proprietary Programs
-* Contributions:: Accepting Contributions
+* Reading Non-Free Code:: Referring to Proprietary Programs
+* Contributions:: Accepting Contributions
\1f
-File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Intellectual Property
+File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
Referring to Proprietary Programs
=================================
obstacks.
\1f
-File: standards.info, Node: Contributions, Prev: Reading Non-Free Code, Up: Intellectual Property
+File: standards.info, Node: Contributions, Prev: Reading Non-Free Code, Up: Legal Issues
Accepting Contributions
=======================
- If someone else sends you a piece of code to add to the program you
-are working on, we need legal papers to use it--the same sort of legal
-papers we will need to get from you. *Each* significant contributor to
-a program must sign some sort of legal papers in order for us to have
-clear title to the program. The main author alone is not enough.
-
- So, before adding in any contributions from other people, tell us so
-we can arrange to get the papers. Then wait until we tell you that we
-have received the signed papers, before you actually use the
+ If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it--just as we asked you to
+sign papers initially. _Each_ person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+ So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers. Then wait until we tell you
+that we have received the signed papers, before you actually use the
contribution.
This applies both before you release the program and afterward. If
you receive diffs to fix a bug, and they make significant changes, we
-need legal papers for it.
+need legal papers for that change.
+
+ This also applies to comments and documentation files. For copyright
+law, comments and code are just text. Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+ We know it is frustrating to ask for legal papers; it's frustrating
+for us as well. But if you don't wait, you are going out on a limb--for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
You don't need papers for changes of a few lines here or there, since
they are not significant for copyright purposes. Also, you don't need
papers if all you get from the suggestion is some ideas, not actual code
-which you use. For example, if you write a different solution to the
-problem, you don't need to get papers.
-
- We know this is frustrating; it's frustrating for us as well. But if
-you don't wait, you are going out on a limb--for example, what if the
-contributor's employer won't sign a disclaimer? You might have to take
-that code out again!
+which you use. For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
The very worst thing is if you forget to tell us about the other
contributor. We could be very embarrassed in court some day as a
result.
+ We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+
\1f
-File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Intellectual Property, Up: Top
+File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
General Program Design
**********************
* Menu:
-* Compatibility:: Compatibility with other implementations
-* Using Extensions:: Using non-standard features
+* Compatibility:: Compatibility with other implementations
+* Using Extensions:: Using non-standard features
* ANSI C:: Using ANSI C features
-* Source Language:: Using languages other than C
+* Source Language:: Using languages other than C
\1f
File: standards.info, Node: Compatibility, Next: Using Extensions, Up: Design Advice
feature as well. (There is a free `vi' clone, so we offer it.)
Additional useful features not in Berkeley Unix are welcome.
-Additional programs with no counterpart in Unix may be useful, but our
-first priority is usually to duplicate what Unix already has.
\1f
File: standards.info, Node: Using Extensions, Next: ANSI C, Prev: Compatibility, Up: Design Advice
compilers). And if a program is already written in ANSI C, there's no
need to convert it to support non-ANSI compilers.
+ If you don't know non-ANSI C, there's no need to learn it; just
+write in ANSI C.
+
However, it is easy to support non-ANSI compilers in most programs,
-so you might still consider doing so when you write a program. Instead
-of writing function definitions in ANSI prototype form,
+so you might still consider doing so when you write a program. And if a
+program you are maintaining has such support, you should try to keep it
+working.
+
+ To support pre-ANSI C, instead of writing function definitions in
+ANSI prototype form,
int
foo (int x, int y)
You need such a declaration anyway, in a header file, to get the
benefit of ANSI C prototypes in all the files where the function is
-called. And once you have it, you lose nothing by writing the function
-definition in the pre-ANSI style.
-
- If you don't know non-ANSI C, there's no need to learn it; just
-write in ANSI C.
+called. And once you have the declaration, you normally lose nothing
+by writing the function definition in the pre-ANSI style.
+
+ This technique does not work for integer types narrower than `int'.
+If you think of an argument as being of a type narrower than `int',
+declare it as `int' instead.
+
+ There are a few special cases where this technique is hard to use.
+For example, if a function argument needs to hold the system type
+`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
+some machines; but you cannot use `int' instead, because `dev_t' is
+wider than `int' on some machines. There is no type you can safely use
+on all machines in a non-ANSI definition. The only way to support
+non-ANSI C and pass such an argument is to check the width of `dev_t'
+using Autoconf and choose the argument type accordingly. This may not
+be worth the trouble.
\1f
File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice
Using a language other than C is like using a non-standard feature:
it will cause trouble for users. Even if GCC supports the other
language, users may find it inconvenient to have to install the
-compiler for that other language in order to build your program. So
-please write in C.
+compiler for that other language in order to build your program. For
+example, if you write your program in C++, people will have to install
+the C++ compiler in order to compile your program. Thus, it is better
+if you write in C.
- There are three exceptions for this rule:
+ But there are three situations when there is no disadvantage in using
+some other language:
- * It is okay to use a special language if the same program contains
- an interpreter for that language.
+ * It is okay to use another language if your program contains an
+ interpreter for that language.
For example, if your program links with GUILE, it is ok to write
part of the program in Scheme or another language supported by
This is okay because the only people who want to build the tool
will be those who have installed the other language anyway.
- * If an application is not of extremely widespread interest, then
+ * If an application is of interest to a narrow community, then
perhaps it's not important if the application is inconvenient to
install.
+ C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
\1f
File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
* Menu:
-* Semantics:: Writing robust programs
-* Libraries:: Library behavior
-* Errors:: Formatting error messages
-* User Interfaces:: Standards for command line interfaces
+* Semantics:: Writing robust programs
+* Libraries:: Library behavior
+* Errors:: Formatting error messages
+* User Interfaces:: Standards for command line interfaces
+* Option Table:: Table of long options.
* Memory Usage:: When and how to care about memory needs
\1f
Writing Robust Programs
=======================
- Avoid arbitrary limits on the length or number of *any* data
+ Avoid arbitrary limits on the length or number of _any_ data
structure, including file names, lines, files, and symbols, by
allocating all data structures dynamically. In most Unix utilities,
"long lines are silently truncated". This is not acceptable in a GNU
utility.
Utilities reading files should not drop NUL characters, or any other
-nonprinting characters *including those with codes above 0177*. The
+nonprinting characters _including those with codes above 0177_. The
only sensible exceptions would be utilities specifically intended for
-interface to certain types of printers that can't handle those
-characters.
+interface to certain types of terminals or printers that can't handle
+those characters. Whenever possible, try to make programs work
+properly with sequences of bytes that represent multibyte characters,
+using encodings such as UTF-8 and others.
Check every system call for an error return, unless you know you
wish to ignore errors. Include the system error text (from `perror' or
-equivalent) in *every* error message resulting from a failing system
+equivalent) in _every_ error message resulting from a failing system
call, as well as the name of the file if any and the name of the
utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
(such as file directories, utmp, or the layout of kernel memory), since
these are less likely to work compatibly. If you need to find all the
files in a directory, use `readdir' or some other high-level interface.
-These will be supported compatibly by GNU.
+These are supported compatibly by GNU.
+
+ The preferred signal handling facilities are the BSD variant of
+`signal', and the POSIX `sigaction' function; the alternative USG
+`signal' interface is an inferior design.
- By default, the GNU system will provide the signal handling
-functions of BSD and of POSIX. So GNU software should be written to use
-these.
+ Nowadays, using the POSIX signal functions may be the easiest way to
+make a program portable. If you use `signal', then on GNU/Linux
+systems running GNU libc version 1, you should include `bsd/signal.h'
+instead of `signal.h', so as to get BSD behavior. It is up to you
+whether to support systems where `signal' has only the USG behavior, or
+give up on them.
In error checks that detect "impossible" conditions, just abort.
There is usually no point in printing any message. These checks
elsewhere.
Do not use a count of errors as the exit status for a program.
-*That does not work*, because exit status values are limited to 8 bits
+_That does not work_, because exit status values are limited to 8 bits
(0 through 255). A single run of the program might have 256 errors; if
you try to return 256 as the exit status, the parent process will see 0
as the status, and it will appear that the program succeeded.
SOURCE-FILE-NAME:LINENO: MESSAGE
+If you want to mention the column number, use this format:
+
+ SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line. (Both
+of these conventions are chosen for compatibility.) Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+
Error messages from other noninteractive programs should look like
this:
when there is no relevant source file.
+ If you want to mention the column number, use this format:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
In an interactive program (one that is reading commands from a
terminal), it is better not to include the program name in an error
message. The place to indicate which program is running is in the
end with a period.
\1f
-File: standards.info, Node: User Interfaces, Next: Memory Usage, Prev: Errors, Up: Program Behavior
+File: standards.info, Node: User Interfaces, Next: Option Table, Prev: Errors, Up: Program Behavior
Standards for Command Line Interfaces
=====================================
Likewise, please don't make the behavior of the program depend on the
type of output device it is used with. Device independence is an
important principle of the system's design; do not compromise it merely
-to save someone from typing an option now and then.
+to save someone from typing an option now and then. (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
If you think one behavior is most useful when the output is to a
terminal, and another is most useful when the output is a file or a
to expect the "verbose" option of any GNU program which has one, to be
spelled precisely `--verbose'. To achieve this uniformity, look at the
table of common long-option names when you choose the option names for
-your program. The table appears below.
-
- If you use names not already in the table, please send
-`gnu@prep.ai.mit.edu' a list of them, with their meanings, so we can
-update the table.
+your program (*note Option Table::).
It is usually a good idea for file names given as ordinary arguments
to be input files only; any output files would be specified using
-options (preferably `-o'). Even if you allow an output file name as an
-ordinary argument for compatibility, try to provide a suitable option
-as well. This will lead to more consistency among GNU utilities, so
-that there are fewer idiosyncracies for users to remember.
+options (preferably `-o' or `--output'). Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it. This will lead to more consistency
+among GNU utilities, and fewer idiosyncracies for users to remember.
+
+ All programs should support two standard options: `--version' and
+`--help'.
+
+`--version'
+ This option should direct the program to print information about
+ its name, version, origin and legal status, all on standard
+ output, and then exit successfully. Other options and arguments
+ should be ignored once this is seen, and the program should not
+ perform its normal function.
+
+ The first line is meant to be easy for a program to parse; the
+ version number proper starts after the last space. In addition,
+ it contains the canonical name for this program, in this format:
+
+ GNU Emacs 19.30
+
+ The program's name should be a constant string; _don't_ compute it
+ from `argv[0]'. The idea is to state the standard or canonical
+ name for the program, not its file name. There are other ways to
+ find out the precise file name where a command is found in `PATH'.
+
+ If the program is a subsidiary part of a larger package, mention
+ the package name in parentheses, like this:
+
+ emacsserver (GNU Emacs) 19.30
+
+ If the package has a version number which is different from this
+ program's version number, you can mention the package version
+ number just before the close-parenthesis.
+
+ If you *need* to mention the version numbers of libraries which
+ are distributed separately from the package which contains this
+ program, you can do so by printing an additional line of version
+ info for each library you want to mention. Use the same format
+ for these lines as for the first line.
+
+ Please do not mention all of the libraries that the program uses
+ "just for completeness"--that would produce a lot of unhelpful
+ clutter. Please mention library version numbers only if you find
+ in practice that they are very important to you in debugging.
+
+ The following line, after the version number line or lines, should
+ be a copyright notice. If more than one copyright notice is
+ called for, put each on a separate line.
+
+ Next should follow a brief statement that the program is free
+ software, and that users are free to copy and change it on certain
+ conditions. If the program is covered by the GNU GPL, say so
+ here. Also mention that there is no warranty, to the extent
+ permitted by law.
+
+ It is ok to finish the output with a list of the major authors of
+ the program, as a way of giving credit.
+
+ Here's an example of output that follows these rules:
+
+ GNU Emacs 19.34.5
+ Copyright (C) 1996 Free Software Foundation, Inc.
+ GNU Emacs comes with NO WARRANTY,
+ to the extent permitted by law.
+ You may redistribute copies of GNU Emacs
+ under the terms of the GNU General Public License.
+ For more information about these matters,
+ see the files named COPYING.
+
+ You should adapt this to your program, of course, filling in the
+ proper year, copyright holder, name of program, and the references
+ to distribution terms, and changing the rest of the wording as
+ necessary.
+
+ This copyright notice only needs to mention the most recent year in
+ which changes were made--there's no need to list the years for
+ previous versions' changes. You don't have to mention the name of
+ the program in these notices, if that is inconvenient, since it
+ appeared in the first line.
+
+`--help'
+ This option should output brief documentation for how to invoke the
+ program, on standard output, then exit successfully. Other
+ options and arguments should be ignored once this is seen, and the
+ program should not perform its normal function.
+
+ Near the end of the `--help' option's output there should be a line
+ that says where to mail bug reports. It should have this format:
+
+ Report bugs to MAILING-ADDRESS.
- Programs should support an option `--version' which prints the
-program's version number on standard output and exits successfully, and
-an option `--help' which prints option usage information on standard
-output and exits successfully. These options should inhibit the normal
-function of the command; they should do nothing except print the
-requested information.
+\1f
+File: standards.info, Node: Option Table, Next: Memory Usage, Prev: User Interfaces, Up: Program Behavior
- Here is the table of long options used by GNU programs.
+Table of Long Options
+=====================
+
+ Here is a table of long options used by GNU programs. It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with. If you use names not already in the table,
+please send <gnu@gnu.org> a list of them, with their meanings, so we
+can update the table.
`after-date'
`-N' in `tar'.
`avoid-wraps'
`-n' in `wdiff'.
+`background'
+ For server programs, run in the background.
+
`backward-search'
`-B' in `ctags'.
`dereference-args'
`-D' in `du'.
+`device'
+ Specify an I/O device (special file name).
+
`diacritics'
`-d' in `recode'.
`force-prefix'
`-F' in `shar'.
+`foreground'
+ For server programs, run in the foreground; in other words, don't
+ do anything special to run the server in the background.
+
`format'
Used in `ls', `time', and `ptx'.
`machine'
No listing of which programs already use this; someone should
- check to see if any actually do and tell `gnu@prep.ai.mit.edu'.
+ check to see if any actually do, and tell <gnu@gnu.org>.
`macro-name'
`-M' in `ptx'.
`no-validate'
Used in `makeinfo'.
+`no-wait'
+ Used in `emacsclient'.
+
`no-warn'
Used in various programs to inhibit warnings.
`only-time'
`-F' in `gprof'.
+`options'
+ `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
+
`output'
In various programs, specify the output file name.
`prompt'
`-p' in `ed'.
+`proxy'
+ Specify an HTTP proxy.
+
`query-user'
`-X' in `shar'.
`-q' in Make.
`quiet'
- Used in many programs to inhibit the usual output. *Please note:*
- every program accepting `--quiet' should accept `--silent' as a
- synonym.
+ Used in many programs to inhibit the usual output. *Note:* every
+ program accepting `--quiet' should accept `--silent' as a synonym.
`quiet-unshar'
`-Q' in `shar'
`-T' in `cat'.
`silent'
- Used in many programs to inhibit the usual output. *Please note:*
- every program accepting `--silent' should accept `--quiet' as a
- synonym.
+ Used in many programs to inhibit the usual output. *Note:* every
+ program accepting `--silent' should accept `--quiet' as a synonym.
`size'
`-s' in `ls'.
+`socket'
+ Specify a file descriptor for a network server to use for its
+ socket, instead of opening and binding a new socket. This
+ provides a way to run, in a nonpriveledged process, a server that
+ normally needs a reserved port number.
+
`sort'
Used in `ls'.
`time'
Used in `ls' and `touch'.
+`timeout'
+ Specify how long to wait before giving up on some operation.
+
`to-stdout'
`-O' in `tar'.
`-z' in `gprof'.
\1f
-File: standards.info, Node: Memory Usage, Prev: User Interfaces, Up: Program Behavior
+File: standards.info, Node: Memory Usage, Prev: Option Table, Up: Program Behavior
Memory Usage
============
* Menu:
-* Formatting:: Formatting Your Source Code
-* Comments:: Commenting Your Work
-* Syntactic Conventions:: Clean Use of C Constructs
-* Names:: Naming Variables and Functions
-* System Portability:: Portability between different operating systems
+* Formatting:: Formatting Your Source Code
+* Comments:: Commenting Your Work
+* Syntactic Conventions:: Clean Use of C Constructs
+* Names:: Naming Variables and Functions
+* System Portability:: Portability between different operating systems
* CPU Portability:: Supporting the range of CPU types
-* System Functions:: Portability and "standard" library functions
+* System Functions:: Portability and ``standard'' library functions
* Internationalization:: Techniques for internationalization
+* Mmap:: How you can safely use `mmap'.
\1f
File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
just how long the pages are, since they do not have to fit on a printed
page. The formfeeds should appear alone on lines by themselves.
-\1f
-File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
-
-Commenting Your Work
-====================
-
- Every program should start with a comment saying briefly what it is
-for. Example: `fmt - filter for simple filling of text'.
-
- Please put a comment on each function saying what the function does,
-what sorts of arguments it gets, and what the possible values of
-arguments mean and are used for. It is not necessary to duplicate in
-words the meaning of the C argument declarations, if a C type is being
-used in its customary fashion. If there is anything nonstandard about
-its use (such as an argument of type `char *' which is really the
-address of the second character of a string, not the first), or any
-possible values that would not work the way one would expect (such as,
-that strings containing newlines are not guaranteed to work), be sure
-to say so.
-
- Also explain the significance of the return value, if there is one.
-
- Please put two spaces after the end of a sentence in your comments,
-so that the Emacs sentence commands will work. Also, please write
-complete sentences and capitalize the first word. If a lower-case
-identifier comes at the beginning of a sentence, don't capitalize it!
-Changing the spelling makes it a different identifier. If you don't
-like starting a sentence with a lower case letter, write the sentence
-differently (e.g., "The identifier lower-case is ...").
-
- The comment on a function is much clearer if you use the argument
-names to speak about the argument values. The variable name itself
-should be lower case, but write it in upper case when you are speaking
-about the value rather than the variable itself. Thus, "the inode
-number NODE_NUM" rather than "an inode".
-
- There is usually no purpose in restating the name of the function in
-the comment before it, because the reader can see that for himself.
-There might be an exception when the comment is so long that the
-function itself would be off the bottom of the screen.
-
- There should be a comment on each static variable as well, like this:
-
- /* Nonzero means truncate lines in the display;
- zero means continue them. */
- int truncate_lines;
-
- Every `#endif' should have a comment, except in the case of short
-conditionals (just a few lines) that are not nested. The comment should
-state the condition of the conditional that is ending, *including its
-sense*. `#else' should have a comment describing the condition *and
-sense* of the code that follows. For example:
-
- #ifdef foo
- ...
- #else /* not foo */
- ...
- #endif /* not foo */
-
-but, by contrast, write the comments this way for a `#ifndef':
-
- #ifndef foo
- ...
- #else /* foo */
- ...
- #endif /* foo */
-
-\1f
-File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
-
-Clean Use of C Constructs
-=========================
-
- Please explicitly declare all arguments to functions. Don't omit
-them just because they are `int's.
-
- Declarations of external functions and functions to appear later in
-the source file should all go in one place near the beginning of the
-file (somewhere before the first function definition in the file), or
-else should go in a header file. Don't put `extern' declarations inside
-functions.
-
- It used to be common practice to use the same local variables (with
-names like `tem') over and over for different values within one
-function. Instead of doing this, it is better declare a separate local
-variable for each distinct purpose, and give it a name which is
-meaningful. This not only makes programs easier to understand, it also
-facilitates optimization by good compilers. You can also move the
-declaration of each local variable into the smallest scope that includes
-all its uses. This makes the program even cleaner.
-
- Don't use local variables or parameters that shadow global
-identifiers.
-
- Don't declare multiple variables in one declaration that spans lines.
-Start a new declaration on each line, instead. For example, instead of
-this:
-
- int foo,
- bar;
-
-write either this:
-
- int foo, bar;
-
-or this:
-
- int foo;
- int bar;
-
-(If they are global variables, each should have a comment preceding it
-anyway.)
-
- When you have an `if'-`else' statement nested in another `if'
-statement, always put braces around the `if'-`else'. Thus, never write
-like this:
-
- if (foo)
- if (bar)
- win ();
- else
- lose ();
-
-always like this:
-
- if (foo)
- {
- if (bar)
- win ();
- else
- lose ();
- }
-
- If you have an `if' statement nested inside of an `else' statement,
-either write `else if' on one line, like this,
-
- if (foo)
- ...
- else if (bar)
- ...
-
-with its `then'-part indented like the preceding `then'-part, or write
-the nested `if' within braces like this:
-
- if (foo)
- ...
- else
- {
- if (bar)
- ...
- }
-
- Don't declare both a structure tag and variables or typedefs in the
-same declaration. Instead, declare the structure tag separately and
-then use it to declare the variables or typedefs.
-
- Try to avoid assignments inside `if'-conditions. For example, don't
-write this:
-
- if ((foo = (char *) malloc (sizeof *foo)) == 0)
- fatal ("virtual memory exhausted");
-
-instead, write this:
-
- foo = (char *) malloc (sizeof *foo);
- if (foo == 0)
- fatal ("virtual memory exhausted");
-
- Don't make the program ugly to placate `lint'. Please don't insert
-any casts to `void'. Zero without a cast is perfectly fine as a null
-pointer constant, except when calling a varargs function.
-
-\1f
-File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
-
-Naming Variables and Functions
-==============================
-
- Please use underscores to separate words in a name, so that the Emacs
-word commands can be useful within them. Stick to lower case; reserve
-upper case for macros and `enum' constants, and for name-prefixes that
-follow a uniform convention.
-
- For example, you should use names like `ignore_space_change_flag';
-don't use names like `iCantReadThis'.
-
- Variables that indicate whether command-line options have been
-specified should be named after the meaning of the option, not after
-the option-letter. A comment should state both the exact meaning of
-the option and its letter. For example,
-
- /* Ignore changes in horizontal whitespace (-b). */
- int ignore_space_change_flag;
-
- When you want to define names with constant integer values, use
-`enum' rather than `#define'. GDB knows about enumeration constants.
-
- Use file names of 14 characters or less, to avoid creating gratuitous
-problems on older System V systems. You can use the program `doschk'
-to test for this. `doschk' also tests for potential name conflicts if
-the files were loaded onto an MS-DOS file system--something you may or
-may not care about.
-
-\1f
-File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
-
-Portability between System Types
-================================
-
- In the Unix world, "portability" refers to porting to different Unix
-versions. For a GNU program, this kind of portability is desirable, but
-not paramount.
-
- The primary purpose of GNU software is to run on top of the GNU
-kernel, compiled with the GNU C compiler, on various types of CPU. The
-amount and kinds of variation among GNU systems on different CPUs will
-be comparable to the variation among Linux-based GNU systems or among
-BSD systems today. So the kinds of portability that are absolutely
-necessary are quite limited.
-
- But many users do run GNU software on non-GNU Unix or Unix-like
-systems. So supporting a variety of Unix-like systems is desirable,
-although not paramount.
-
- The easiest way to achieve portability to most Unix-like systems is
-to use Autoconf. It's unlikely that your program needs to know more
-information about the host platform than Autoconf can provide, simply
-because most of the programs that need such knowledge have already been
-written.
-
- Avoid using the format of semi-internal data bases (e.g.,
-directories) when there is a higher-level alternative (`readdir').
-
- As for systems that are not like Unix, such as MSDOS, Windows, the
-Macintosh, VMS, and MVS, supporting them is usually so much work that it
-is better if you don't.
-
- The planned GNU kernel is not finished yet, but you can tell which
-facilities it will provide by looking at the GNU C Library Manual. The
-GNU kernel is based on Mach, so the features of Mach will also be
-available. However, if you use Mach features, you'll probably have
-trouble debugging your program today.
-
-This is Info file ../info/standards.info, produced by Makeinfo version
-1.68 from the input file standards.texi.
+This is ../info/standards.info, produced by makeinfo version 4.0 from
+standards.texi.
START-INFO-DIR-ENTRY
* Standards: (standards). GNU coding standards.
END-INFO-DIR-ENTRY
- GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
-Software Foundation, Inc.
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
+
+Commenting Your Work
+====================
+
+ Every program should start with a comment saying briefly what it is
+for. Example: `fmt - filter for simple filling of text'.
+
+ Please write the comments in a GNU program in English, because
+English is the one language that nearly all programmers in all
+countries can read. If you do not write English well, please write
+comments in English as well as you can, then ask other people to help
+rewrite them. If you can't write comments in English, please find
+someone to work with you and translate your comments into English.
+
+ Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for. It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion. If there is anything nonstandard about
+its use (such as an argument of type `char *' which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+ Also explain the significance of the return value, if there is one.
+
+ Please put two spaces after the end of a sentence in your comments,
+so that the Emacs sentence commands will work. Also, please write
+complete sentences and capitalize the first word. If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier. If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., "The identifier lower-case is ...").
+
+ The comment on a function is much clearer if you use the argument
+names to speak about the argument values. The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself. Thus, "the inode
+number NODE_NUM" rather than "an inode".
+
+ There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the
+function itself would be off the bottom of the screen.
+
+ There should be a comment on each static variable as well, like this:
+
+ /* Nonzero means truncate lines in the display;
+ zero means continue them. */
+ int truncate_lines;
+
+ Every `#endif' should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested. The comment should
+state the condition of the conditional that is ending, _including its
+sense_. `#else' should have a comment describing the condition _and
+sense_ of the code that follows. For example:
+
+ #ifdef foo
+ ...
+ #else /* not foo */
+ ...
+ #endif /* not foo */
+ #ifdef foo
+ ...
+ #endif /* foo */
+
+but, by contrast, write the comments this way for a `#ifndef':
+
+ #ifndef foo
+ ...
+ #else /* foo */
+ ...
+ #endif /* foo */
+ #ifndef foo
+ ...
+ #endif /* not foo */
+
+\1f
+File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
+
+Clean Use of C Constructs
+=========================
+
+ Please explicitly declare all arguments to functions. Don't omit
+them just because they are `int's.
+
+ Declarations of external functions and functions to appear later in
+the source file should all go in one place near the beginning of the
+file (somewhere before the first function definition in the file), or
+else should go in a header file. Don't put `extern' declarations inside
+functions.
+
+ It used to be common practice to use the same local variables (with
+names like `tem') over and over for different values within one
+function. Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+ Don't use local variables or parameters that shadow global
+identifiers.
+
+ Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead of
+this:
+
+ int foo,
+ bar;
+
+write either this:
+
+ int foo, bar;
+
+or this:
+
+ int foo;
+ int bar;
+
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+ When you have an `if'-`else' statement nested in another `if'
+statement, always put braces around the `if'-`else'. Thus, never write
+like this:
+
+ if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+
+always like this:
+
+ if (foo)
+ {
+ if (bar)
+ win ();
+ else
+ lose ();
+ }
+
+ If you have an `if' statement nested inside of an `else' statement,
+either write `else if' on one line, like this,
+
+ if (foo)
+ ...
+ else if (bar)
+ ...
+
+with its `then'-part indented like the preceding `then'-part, or write
+the nested `if' within braces like this:
+
+ if (foo)
+ ...
+ else
+ {
+ if (bar)
+ ...
+ }
+
+ Don't declare both a structure tag and variables or typedefs in the
+same declaration. Instead, declare the structure tag separately and
+then use it to declare the variables or typedefs.
+
+ Try to avoid assignments inside `if'-conditions. For example, don't
+write this:
+
+ if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+
+instead, write this:
+
+ foo = (char *) malloc (sizeof *foo);
+ if (foo == 0)
+ fatal ("virtual memory exhausted");
+
+ Don't make the program ugly to placate `lint'. Please don't insert
+any casts to `void'. Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+\1f
+File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
+
+Naming Variables and Functions
+==============================
+
+ The names of global variables and functions in a program serve as
+comments of a sort. So don't choose terse names--instead, look for
+names that give useful information about the meaning of the variable or
+function. In a GNU program, names should be English, like other
+comments.
+
+ Local variable names can be shorter, because they are used only
+within one context, where (presumably) comments explain their purpose.
+
+ Try to limit your use of abbreviations in symbol names. It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+ Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them. Stick to lower case; reserve
+upper case for macros and `enum' constants, and for name-prefixes that
+follow a uniform convention.
+
+ For example, you should use names like `ignore_space_change_flag';
+don't use names like `iCantReadThis'.
+
+ Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter. A comment should state both the exact meaning of
+the option and its letter. For example,
+
+ /* Ignore changes in horizontal whitespace (-b). */
+ int ignore_space_change_flag;
+
+ When you want to define names with constant integer values, use
+`enum' rather than `#define'. GDB knows about enumeration constants.
+
+ Use file names of 14 characters or less, to avoid creating gratuitous
+problems on older System V systems. You can use the program `doschk'
+to test for this. `doschk' also tests for potential name conflicts if
+the files were loaded onto an MS-DOS file system--something you may or
+may not care about.
+
+\1f
+File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
+
+Portability between System Types
+================================
+
+ In the Unix world, "portability" refers to porting to different Unix
+versions. For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+ The primary purpose of GNU software is to run on top of the GNU
+kernel, compiled with the GNU C compiler, on various types of CPU. The
+amount and kinds of variation among GNU systems on different CPUs will
+be comparable to the variation among Linux-based GNU systems or among
+BSD systems today. So the kinds of portability that are absolutely
+necessary are quite limited.
+
+ But many users do run GNU software on non-GNU Unix or Unix-like
+systems. So supporting a variety of Unix-like systems is desirable,
+although not paramount.
+
+ The easiest way to achieve portability to most Unix-like systems is
+to use Autoconf. It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+ Avoid using the format of semi-internal data bases (e.g.,
+directories) when there is a higher-level alternative (`readdir').
+
+ As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work. When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+\1f
File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
Portability between CPUs
error (s, a1, a2, a3)
char *s;
- int a1, a2, a3;
+ char *a1, *a2, *a3;
{
fprintf (stderr, "error: ");
fprintf (stderr, s, a1, a2, a3);
}
-In practice, this works on all machines, and it is much simpler than any
-"correct" alternative. Be sure *not* to use a prototype for such
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument, and it is much simpler than any
+"correct" alternative. Be sure _not_ to use a prototype for such
functions.
However, avoid casting pointers to integers unless you really need
-to. These assumptions really reduce portability, and in most programs
-they are easy to avoid. In the cases where casting pointers to
-integers is essential--such as, a Lisp interpreter which stores type
-information as well as an address in one word--it is ok to do so, but
-you'll have to make explicit provisions to handle different word sizes.
+to. Outside of special situations, such casts greatly reduce
+portability, and in most programs they are easy to avoid. In the cases
+where casting pointers to integers is essential--such as, a Lisp
+interpreter which stores type information as well as an address in one
+word--it is ok to do it, but you'll have to make explicit provisions to
+handle different word sizes.
\1f
File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
* Don't use the value of `sprintf'. It returns the number of
characters written on some systems, but not on all systems.
+ * `main' should be declared to return type `int'. It should
+ terminate either by calling `exit' or by returning the integer
+ status code; make sure it cannot ever return an undefined value.
+
* Don't declare system functions explicitly.
Almost any declaration for a system function is wrong on some
get them properly defined is to use Autoconf.
\1f
-File: standards.info, Node: Internationalization, Prev: System Functions, Up: Writing C
+File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C
Internationalization
====================
Normally, the text domain name should be the same as the name of the
package--for example, `fileutils' for the GNU file utilities.
- To enable gettext to work, avoid writing code that makes assumptions
-about the structure of words. Don't construct words from parts. Here
-is an example of what not to do:
+ To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences. When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
- prinf ("%d file%s processed", nfiles,
- nfiles > 1 ? "s" : "");
+ Here is an example of what not to do:
+
+ printf ("%d file%s processed", nfiles,
+ nfiles != 1 ? "s" : "");
The problem with that example is that it assumes that plurals are made
by adding `s'. If you apply gettext to the format string, like this,
- prinf (gettext ("%d file%s processed"), nfiles,
- nfiles > 1 ? "s" : "");
+ printf (gettext ("%d file%s processed"), nfiles,
+ nfiles != 1 ? "s" : "");
the message can use different words, but it will still be forced to use
`s' for the plural. Here is a better way:
- prinf ((nfiles > 1 ? "%d files processed"
- : "%d file processed"),
- nfiles);
+ printf ((nfiles != 1 ? "%d files processed"
+ : "%d file processed"),
+ nfiles);
This way, you can apply gettext to each of the two strings
independently:
- prinf ((nfiles > 1 ? gettext ("%d files processed")
- : gettext ("%d file processed")),
- nfiles);
+ printf ((nfiles != 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+
+This can be any method of forming the plural of the word for "file", and
+also handles languages that require agreement in the word for
+"processed".
+
+ A similar problem appears at the level of sentence structure with
+this code:
+
+ printf ("# Implicit rule search has%s been done.\n",
+ f->tried_implicit ? "" : " not");
+
+Adding `gettext' calls to this code cannot give correct results for all
+languages, because negation in some languages requires adding words at
+more than one place in the sentence. By contrast, adding `gettext'
+calls does the job straightfowardly if the code starts out like this:
+
+ printf (f->tried_implicit
+ ? "# Implicit rule search has been done.\n",
+ : "# Implicit rule search has not been done.\n");
-This can handle any language, no matter how it forms the plural of the
-word for "file."
+\1f
+File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C
+
+Mmap
+====
+
+ Don't assume that `mmap' either works on all files or fails for all
+files. It may work on some files and fail on others.
+
+ The proper way to use `mmap' is to try it on the specific file for
+which you want to use it--and if `mmap' doesn't work, fall back on
+doing the job in another way using `read' and `write'.
+
+ The reason this precaution is needed is that the GNU kernel (the
+HURD) provides a user-extensible file system, in which there can be many
+different kinds of "ordinary files." Many of them support `mmap', but
+some do not. It is important to make programs handle all these kinds
+of files.
\1f
File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
* GNU Manuals:: Writing proper manuals.
* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
* NEWS File:: NEWS files supplement manuals.
-* Change Logs:: Recording Changes
+* Change Logs:: Recording Changes
* Man Pages:: Man pages are secondary.
* Reading other Manuals:: How far you can go in learning
from other manuals.
===========
The preferred way to document part of the GNU system is to write a
-manual in the Texinfo formatting language. See the Texinfo manual,
-either the hardcopy, or the on-line version available through `info' or
-the Emacs Info subsystem (`C-h i').
-
- The manual should document all of the program's command-line options
-and all of its commands. It should give examples of their use. But
-don't organize the manual as a list of features. Instead, organize it
-logically, by subtopics. Address the goals that a user will have in
-mind, and explain how to accomplish them.
+manual in the Texinfo formatting language. This makes it possible to
+produce a good quality formatted book, using TeX, and to generate an
+Info file. It is also possible to generate HTML output from Texinfo
+source. See the Texinfo manual, either the hardcopy, or the on-line
+version available through `info' or the Emacs Info subsystem (`C-h i').
+
+ Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know. But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+
+ At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it. Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented--but
+often they are different. Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+
+ For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual. That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+ Instead, each manual should cover a coherent _topic_. For example,
+instead of a manual for `diff' and a manual for `diff3', we have one
+manual for "comparison of files" which covers both of those programs,
+as well as `cmp'. By documenting these programs together, we can make
+the whole subject clearer.
+
+ The manual which discusses a program should document all of the
+program's command-line options and all of its commands. It should give
+examples of their use. But don't organize the manual as a list of
+features. Instead, organize it logically, by subtopics. Address the
+questions that a user will ask when thinking about the job that the
+program does.
In general, a GNU manual should serve both as tutorial and reference.
It should be set up for convenient access to each topic through Info,
and for reading straight through (appendixes aside). A GNU manual
should give a good introduction to a beginner reading through from the
-start, and should also provide all the details that hackers want.
+start, and should also provide all the details that hackers want. The
+Bison manual is a good example of this--please take a look at it to see
+what we mean.
That is not as hard as it first sounds. Arrange each chapter as a
logical breakdown of its topic, but order the sections, and write their
text, so that reading the chapter straight through makes sense. Do
likewise when structuring the book into chapters, and when structuring a
-section into paragraphs. The watchword is, *at each point, address the
-most fundamental and important issue raised by the preceding text.*
+section into paragraphs. The watchword is, _at each point, address the
+most fundamental and important issue raised by the preceding text._
If necessary, add extra chapters at the beginning of the manual which
are purely tutorial and cover the basics of the subject. These provide
Bison manual provides a good example of how to do this.
Don't use Unix man pages as a model for how to write GNU
-documentation; they are a bad example to follow.
+documentation; most of them are terse, badly structured, and give
+inadequate explanation of the underlying concepts. (There are, of
+course exceptions.) Also Unix man pages use a particular format which
+is different from what we use in GNU manuals.
+
+ Please include an email address in the manual for where to report
+bugs _in the manual_.
Please do not use the term "pathname" that is used in Unix
documentation; use "file name" (two words) instead. We use the term
-"path" only for search paths, which are lists of file names.
+"path" only for search paths, which are lists of directory names.
+
+ Please do not use the term "illegal" to refer to erroneous input to a
+computer program. Please use "invalid" for this, and reserve the term
+"illegal" for violations of law.
\1f
-File: standards.info, Node: Manual Structure Details, Next: NEWS File, Prev: GNU Manuals, Up: Documentation
+File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: GNU Manuals, Up: Documentation
Manual Structure Details
========================
- The title page of the manual should state the version of the program
-to which the manual applies. The Top node of the manual should also
-contain this information. If the manual is changing more frequently
-than or independent of the program, also state a version number for the
-manual in both of these places.
-
- The manual should have a node named `PROGRAM Invocation' or
-`Invoking PROGRAM', where PROGRAM stands for the name of the program
-being described, as you would type it in the shell to run the program.
-This node (together with its subnodes, if any) should describe the
-program's command line arguments and how to run it (the sort of
-information people would look in a man page for). Start with an
-`@example' containing a template for all the options and arguments that
-the program uses.
+ The title page of the manual should state the version of the
+programs or packages documented in the manual. The Top node of the
+manual should also contain this information. If the manual is changing
+more frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+ Each program documented in the manual should have a node named
+`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
+its subnodes, if any) should describe the program's command line
+arguments and how to run it (the sort of information people would look
+in a man page for). Start with an `@example' containing a template for
+all the options and arguments that the program uses.
Alternatively, put a menu item in some menu whose item name fits one
of the above patterns. This identifies the node which that item points
for each program described.
\1f
-File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Manual Structure Details, Up: Documentation
+File: standards.info, Node: License for Manuals, Next: NEWS File, Prev: Manual Structure Details, Up: Documentation
+
+License for Manuals
+===================
+
+ If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
+contains chapters that make political or personal statements, please
+copy the distribution terms of the GNU Emacs Manual, and adapt it by
+modifying appropriately the list of special chapters that may not be
+modified or deleted.
+
+ If the manual does not contain any such chapters, then imitate the
+simpler distribution terms of the Texinfo manual.
+
+\1f
+File: standards.info, Node: NEWS File, Next: Change Logs, Prev: License for Manuals, Up: Documentation
The NEWS File
=============
files. The purpose of this is so that people investigating bugs in the
future will know about the changes that might have introduced the bug.
Often a new bug can be found by looking at what was recently changed.
-More importantly, change logs can help eliminate conceptual
-inconsistencies between different parts of a program; they can give you
-a history of how the conflicting concepts arose.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+* Menu:
+
+* Change Log Concepts::
+* Style of Change Logs::
+* Simple Changes::
+* Conditional Changes::
+
+\1f
+File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
+
+Change Log Concepts
+-------------------
- A change log file is normally called `ChangeLog' and covers an
+ You can think of the change log as a conceptual "undo list" which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log to
+tell them what is in it. What they want from a change log is a clear
+explanation of how the earlier version differed.
+
+ The change log file is normally called `ChangeLog' and covers an
entire directory. Each directory can have its own change log, or a
directory can use the change log of its parent directory-it's up to you.
Another alternative is to record change log information with a
version control system such as RCS or CVS. This can be converted
-automatically to a `ChangeLog' file.
+automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
+command `C-x v a' (`vc-update-change-log') does the job.
+
+ There's no need to describe the full purpose of the changes or how
+they work together. If you think that a change calls for explanation,
+you're probably right. Please do explain it--but please put the
+explanation in comments in the code, where people will see it whenever
+they see the code. For example, "New function" is enough for the
+change log when you add a function, because there should be a comment
+before the function definition to explain what it does.
+
+ However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
The easiest way to add an entry to `ChangeLog' is with the Emacs
command `M-x add-change-log-entry'. An entry should have an asterisk,
changed functions, variables or whatever, followed by a colon. Then
describe the changes you made to that function or variable.
- Separate unrelated entries with blank lines. When two entries
-represent parts of the same change, so that they work together, then
-don't put blank lines between them. Then you can omit the file name
-and the asterisk when successive entries are in the same file.
+\1f
+File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
+
+Style of Change Logs
+--------------------
- Here are some examples:
+ Here are some examples of change log entries:
* register.el (insert-register): Return nil.
(jump-to-register): Likewise.
It's important to name the changed function or variable in full.
Don't abbreviate function or variable names, and don't combine them.
-Subsequent maintainers will often search for a function name to find
-all the change log entries that pertain to it; if you abbreviate the
-name, they won't find it when they search. For example, some people
-are tempted to abbreviate groups of function names by writing `*
-register.el ({insert,jump-to}-register)'; this is not a good idea,
-since searching for `jump-to-register' or `insert-register' would not
-find the entry.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
- There's no need to describe the full purpose of the changes or how
-they work together. It is better to put such explanations in comments
-in the code. That's why just "New function" is enough; there is a
-comment with the function in the source to explain what it does.
+ For example, some people are tempted to abbreviate groups of function
+names by writing `* register.el ({insert,jump-to}-register)'; this is
+not a good idea, since searching for `jump-to-register' or
+`insert-register' would not find that entry.
- However, sometimes it is useful to write one line to describe the
-overall purpose of a large batch of changes.
+ Separate unrelated change log entries with blank lines. When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them. Then you can omit the file
+name and the asterisk when successive entries are in the same file.
- You can think of the change log as a conceptual "undo list" which
-explains how earlier versions were different from the current version.
-People can see the current version; they don't need the change log to
-tell them what is in it. What they want from a change log is a clear
-explanation of how the earlier version differed.
+\1f
+File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
+
+Simple Changes
+--------------
+
+ Certain simple kinds of changes don't need much detail in the change
+log.
When you change the calling sequence of a function in a simple
fashion, and you change all the callers of the function, there is no
-need to make individual entries for all the callers. Just write in the
-entry for the function being called, "All callers changed."
+need to make individual entries for all the callers that you changed.
+Just write in the entry for the function being called, "All callers
+changed."
+
+ * keyboard.c (Fcommand_execute): New arg SPECIAL.
+ All callers changed.
When you change just comments or doc strings, it is enough to write
-an entry for the file, without mentioning the functions. Write just,
-"Doc fix."
+an entry for the file, without mentioning the functions. Just "Doc
+fixes" is enough for the change log.
There's no need to make change log entries for documentation files.
This is because documentation is not susceptible to bugs that are hard
to fix. Documentation does not consist of parts that must interact in a
precisely engineered fashion. To correct an error, you need not know
-the history of the erroneous passage; it is enough to compare the
-passage with the way the program actually works.
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+
+\1f
+File: standards.info, Node: Conditional Changes, Prev: Simple Changes, Up: Change Logs
+
+Conditional Changes
+-------------------
+
+ C programs often contain compile-time `#if' conditionals. Many
+changes are conditional; sometimes you add a new definition which is
+entirely contained in a conditional. It is very useful to indicate in
+the change log the conditions for which the change applies.
+
+ Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+
+ Here is a simple example, describing a change which is conditional
+but does not have a function or entity name associated with it:
+
+ * xterm.c [SOLARIS2]: Include string.h.
+
+ Here is an entry describing a new definition which is entirely
+conditional. This new definition for the macro `FRAME_WINDOW_P' is
+used only when `HAVE_X_WINDOWS' is defined:
+
+ * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+
+ Here is an entry for a change within the function `init_display',
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
+
+ * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+
+ Here is an entry for a change that takes affect only when a certain
+macro is _not_ defined:
+
+ (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
\1f
File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
with the FSF about the individual case.
\1f
-File: standards.info, Node: Managing Releases, Prev: Documentation, Up: Top
+File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
The Release Process
*******************
* Menu:
-* Configuration:: How Configuration Should Work
+* Configuration:: How Configuration Should Work
* Makefile Conventions:: Makefile Conventions
-* Releases:: Making Releases
+* Releases:: Making Releases
\1f
File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
One way to do this is to make a link from a standard name such as
`config.h' to the proper configuration file for the chosen system. If
-you use this technique, the distribution should *not* contain a file
+you use this technique, the distribution should _not_ contain a file
named `config.h'. This is so that people won't be able to build the
program without configuring it first.
Another thing that `configure' can do is to edit the Makefile. If
-you do this, the distribution should *not* contain a file named
+you do this, the distribution should _not_ contain a file named
`Makefile'. Instead, it should include a file `Makefile.in' which
contains the input used for editing. Once again, this is so that people
won't be able to build the program without configuring it first.
The package PACKAGE will be installed, so configure this package
to work with PACKAGE.
- Possible values of PACKAGE include `x', `x-toolkit', `gnu-as' (or
- `gas'), `gnu-ld', `gnu-libc', and `gdb'.
+ Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
+ `gnu-libc', `gdb', `x', and `x-toolkit'.
Do not use a `--with' option to specify the file name to use to
find certain files. That is outside the scope of what `--with'
====================
This node describes conventions for writing the Makefiles for GNU
-programs.
+programs. Using Automake will help you write a Makefile that follows
+these conventions.
* Menu:
* Command Variables:: Variables for Specifying Commands
* Directory Variables:: Variables for Installation Directories
* Standard Targets:: Standard Targets for Users
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
\1f
File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
the source code. Without one of these prefixes, the current search
path is used.
- The distinction between `./' and `$(srcdir)/' is important when
-using the `--srcdir' option to `configure'. A rule of the form:
+ The distinction between `./' (the "build directory") and
+`$(srcdir)/' (the "source directory") is important because users can
+build in a separate directory using the `--srcdir' option to
+`configure'. A rule of the form:
foo.1 : foo.man sedscript
sed -e sedscript foo.man > foo.1
-will fail when the current directory is not the source directory,
-because `foo.man' and `sedscript' are not in the current directory.
+will fail when the build directory is not the source directory, because
+`foo.man' and `sedscript' are in the the source directory.
When using GNU `make', relying on `VPATH' to find the source file
will work in the case where there is a single dependency file, since
foo.1 : foo.man sedscript
sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
- Try to make the build and installation targets, at least (and all
-their subtargets) work correctly with a parallel `make'.
-
-\1f
-File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
-
-Utilities in Makefiles
-----------------------
-
- Write the Makefile commands (and any shell scripts, such as
-`configure') to run in `sh', not in `csh'. Don't use any special
-features of `ksh' or `bash'.
-
- The `configure' script and the Makefile rules for building and
-installation should not use any utilities directly except these:
+ GNU distributions usually contain some files which are not source
+files--for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex. Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory. So Makefile rules to update them should put the
+updated files in the source directory.
- cat cmp cp echo egrep expr false grep
- ln mkdir mv pwd rm rmdir sed test touch true
+ However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
- Stick to the generally supported options for these programs. For
-example, don't use `mkdir -p', convenient as it may be, because most
-systems don't support it.
-
- It is a good idea to avoid creating symbolic links in makefiles,
-since a few systems don't support them.
-
- The Makefile rules for building and installation can also use
-compilers and related programs, but should do so via `make' variables
-so that the user can substitute alternatives. Here are some of the
-programs we mean:
-
- ar bison cc flex install ld lex
- make makeinfo ranlib texi2dvi yacc
-
- Use the following `make' variables:
-
- $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX)
- $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
-
- When you use `ranlib', you should make sure nothing bad happens if
-the system does not have `ranlib'. Arrange to ignore an error from
-that command, and print a message before the command to tell the user
-that failure of the `ranlib' command does not mean a problem. (The
-Autoconf `AC_PROG_RANLIB' macro can help with this.)
-
- If you use symbolic links, you should implement a fallback for
-systems that don't have symbolic links.
-
- It is ok to use other utilities in Makefile portions (or scripts)
-intended only for particular systems where you know those utilities
-exist.
-
-\1f
-File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
-
-Variables for Specifying Commands
----------------------------------
-
- Makefiles should provide variables for overriding certain commands,
-options, and so on.
-
- In particular, you should run most utility programs via variables.
-Thus, if you use Bison, have a variable named `BISON' whose default
-value is set with `BISON = bison', and refer to it with `$(BISON)'
-whenever you need to use Bison.
-
- File management utilities such as `ln', `rm', `mv', and so on, need
-not be referred to through variables in this way, since users don't
-need to replace them with other programs.
-
- Each program-name variable should come with an options variable that
-is used to supply options to the program. Append `FLAGS' to the
-program-name variable name to get the options variable name--for
-example, `BISONFLAGS'. (The name `CFLAGS' is an exception to this
-rule, but we keep it because it is standard.) Use `CPPFLAGS' in any
-compilation command that runs the preprocessor, and use `LDFLAGS' in
-any compilation command that does linking as well as in any direct use
-of `ld'.
-
- If there are C compiler options that *must* be used for proper
-compilation of certain files, do not include them in `CFLAGS'. Users
-expect to be able to specify `CFLAGS' freely themselves. Instead,
-arrange to pass the necessary options to the C compiler independently
-of `CFLAGS', by writing them explicitly in the compilation commands or
-by defining an implicit rule, like this:
-
- CFLAGS = -g
- ALL_CFLAGS = -I. $(CFLAGS)
- .c.o:
- $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
-
- Do include the `-g' option in `CFLAGS', because that is not
-*required* for proper compilation. You can consider it a default that
-is only recommended. If the package is set up so that it is compiled
-with GCC by default, then you might as well include `-O' in the default
-value of `CFLAGS' as well.
-
- Put `CFLAGS' last in the compilation command, after other variables
-containing compiler options, so the user can use `CFLAGS' to override
-the others.
-
- Every Makefile should define the variable `INSTALL', which is the
-basic command for installing a file into the system.
-
- Every Makefile should also define the variables `INSTALL_PROGRAM'
-and `INSTALL_DATA'. (The default for each of these should be
-`$(INSTALL)'.) Then it should use those variables as the commands for
-actual installation, for executables and nonexecutables respectively.
-Use these variables as follows:
-
- $(INSTALL_PROGRAM) foo $(bindir)/foo
- $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
-
-Always use a file name, not a directory name, as the second argument of
-the installation commands. Use a separate command for each file to be
-installed.
-
-\1f
-File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
-
-Variables for Installation Directories
---------------------------------------
-
- Installation directories should always be named by variables, so it
-is easy to install in a nonstandard place. The standard names for these
-variables are described below. They are based on a standard filesystem
-layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
-other modern operating systems.
-
- These two variables set the root for the installation. All the other
-installation directories should be subdirectories of one of these two,
-and nothing should be directly installed into these two directories.
-
-`prefix'
- A prefix used in constructing the default values of the variables
- listed below. The default value of `prefix' should be
- `/usr/local'. When building the complete GNU system, the prefix
- will be empty and `/usr' will be a symbolic link to `/'. (If you
- are using Autoconf, write it as `@prefix@'.)
-
-`exec_prefix'
- A prefix used in constructing the default values of some of the
- variables listed below. The default value of `exec_prefix' should
- be `$(prefix)'. (If you are using Autoconf, write it as
- `@exec_prefix@'.)
-
- Generally, `$(exec_prefix)' is used for directories that contain
- machine-specific files (such as executables and subroutine
- libraries), while `$(prefix)' is used directly for other
- directories.
-
- Executable programs are installed in one of the following
-directories.
-
-`bindir'
- The directory for installing executable programs that users can
- run. This should normally be `/usr/local/bin', but write it as
- `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
- `@bindir@'.)
-
-`sbindir'
- The directory for installing executable programs that can be run
- from the shell, but are only generally useful to system
- administrators. This should normally be `/usr/local/sbin', but
- write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
- write it as `@sbindir@'.)
-
-`libexecdir'
- The directory for installing executable programs to be run by other
- programs rather than by users. This directory should normally be
- `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
- (If you are using Autoconf, write it as `@libexecdir@'.)
-
- Data files used by the program during its execution are divided into
-categories in two ways.
-
- * Some files are normally modified by programs; others are never
- normally modified (though users may edit some of these).
-
- * Some files are architecture-independent and can be shared by all
- machines at a site; some are architecture-dependent and can be
- shared only by machines of the same kind and operating system;
- others may never be shared between two machines.
-
- This makes for six different possibilities. However, we want to
-discourage the use of architecture-dependent files, aside from object
-files and libraries. It is much cleaner to make other data files
-architecture-independent, and it is generally not hard.
-
- Therefore, here are the variables Makefiles should use to specify
-directories:
-
-`datadir'
- The directory for installing read-only architecture independent
- data files. This should normally be `/usr/local/share', but write
- it as `$(prefix)/share'. (If you are using Autoconf, write it as
- `@datadir@'.) As a special exception, see `$(infodir)' and
- `$(includedir)' below.
-
-`sysconfdir'
- The directory for installing read-only data files that pertain to a
- single machine-that is to say, files for configuring a host.
- Mailer and network configuration files, `/etc/passwd', and so
- forth belong here. All the files in this directory should be
- ordinary ASCII text files. This directory should normally be
- `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
- using Autoconf, write it as `@sysconfdir@'.)
-
- Do not install executables in this directory (they probably belong
- in `$(libexecdir)' or `$(sbindir)'). Also do not install files
- that are modified in the normal course of their use (programs
- whose purpose is to change the configuration of the system
- excluded). Those probably belong in `$(localstatedir)'.
-
-`sharedstatedir'
- The directory for installing architecture-independent data files
- which the programs modify while they run. This should normally be
- `/usr/local/com', but write it as `$(prefix)/com'. (If you are
- using Autoconf, write it as `@sharedstatedir@'.)
-
-`localstatedir'
- The directory for installing data files which the programs modify
- while they run, and that pertain to one specific machine. Users
- should never need to modify files in this directory to configure
- the package's operation; put such configuration information in
- separate files that go in `$(datadir)' or `$(sysconfdir)'.
- `$(localstatedir)' should normally be `/usr/local/var', but write
- it as `$(prefix)/var'. (If you are using Autoconf, write it as
- `@localstatedir@'.)
-
-`libdir'
- The directory for object files and libraries of object code. Do
- not install executables here, they probably ought to go in
- `$(libexecdir)' instead. The value of `libdir' should normally be
- `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
- are using Autoconf, write it as `@libdir@'.)
-
-`infodir'
- The directory for installing the Info files for this package. By
- default, it should be `/usr/local/info', but it should be written
- as `$(prefix)/info'. (If you are using Autoconf, write it as
- `@infodir@'.)
-
-`includedir'
- The directory for installing header files to be included by user
- programs with the C `#include' preprocessor directive. This
- should normally be `/usr/local/include', but write it as
- `$(prefix)/include'. (If you are using Autoconf, write it as
- `@includedir@'.)
-
- Most compilers other than GCC do not look for header files in
- `/usr/local/include'. So installing the header files this way is
- only useful with GCC. Sometimes this is not a problem because some
- libraries are only really intended to work with GCC. But some
- libraries are intended to work with other compilers. They should
- install their header files in two places, one specified by
- `includedir' and one specified by `oldincludedir'.
-
-`oldincludedir'
- The directory for installing `#include' header files for use with
- compilers other than GCC. This should normally be `/usr/include'.
- (If you are using Autoconf, you can write it as `@oldincludedir@'.)
-
- The Makefile commands should check whether the value of
- `oldincludedir' is empty. If it is, they should not try to use
- it; they should cancel the second installation of the header files.
-
- A package should not replace an existing header in this directory
- unless the header came from the same package. Thus, if your Foo
- package provides a header file `foo.h', then it should install the
- header file in the `oldincludedir' directory if either (1) there
- is no `foo.h' there or (2) the `foo.h' that exists came from the
- Foo package.
-
- To tell whether `foo.h' came from the Foo package, put a magic
- string in the file--part of a comment--and `grep' for that string.
-
- Unix-style man pages are installed in one of the following:
-
-`mandir'
- The top-level directory for installing the man pages (if any) for
- this package. It will normally be `/usr/local/man', but you should
- write it as `$(prefix)/man'. (If you are using Autoconf, write it
- as `@mandir@'.)
-
-`man1dir'
- The directory for installing section 1 man pages. Write it as
- `$(mandir)/man1'.
-
-`man2dir'
- The directory for installing section 2 man pages. Write it as
- `$(mandir)/man2'
-
-`...'
- *Don't make the primary documentation for any GNU software be a
- man page. Write a manual in Texinfo instead. Man pages are just
- for the sake of people running GNU software on Unix, which is a
- secondary application only.*
-
-`manext'
- The file name extension for the installed man page. This should
- contain a period followed by the appropriate digit; it should
- normally be `.1'.
-
-`man1ext'
- The file name extension for installed section 1 man pages.
-
-`man2ext'
- The file name extension for installed section 2 man pages.
-
-`...'
- Use these names instead of `manext' if the package needs to
- install man pages in more than one section of the manual.
-
- And finally, you should set the following variable:
-
-`srcdir'
- The directory for the sources being compiled. The value of this
- variable is normally inserted by the `configure' shell script.
- (If you are using Autconf, use `srcdir = @srcdir@'.)
-
- For example:
-
- # Common prefix for installation directories.
- # NOTE: This directory must exist when you start the install.
- prefix = /usr/local
- exec_prefix = $(prefix)
- # Where to put the executable for the command `gcc'.
- bindir = $(exec_prefix)/bin
- # Where to put the directories used by the compiler.
- libexecdir = $(exec_prefix)/libexec
- # Where to put the Info files.
- infodir = $(prefix)/info
-
- If your program installs a large number of files into one of the
-standard user-specified directories, it might be useful to group them
-into a subdirectory particular to that program. If you do this, you
-should write the `install' rule to create these subdirectories.
-
- Do not expect the user to include the subdirectory name in the value
-of any of the variables listed above. The idea of having a uniform set
-of variable names for installation directories is to enable the user to
-specify the exact same values for several different GNU packages. In
-order for this to be useful, all the packages must be designed so that
-they will work sensibly when the user does so.
+ Try to make the build and installation targets, at least (and all
+their subtargets) work correctly with a parallel `make'.
-This is Info file ../info/standards.info, produced by Makeinfo version
-1.68 from the input file standards.texi.
+This is ../info/standards.info, produced by makeinfo version 4.0 from
+standards.texi.
START-INFO-DIR-ENTRY
* Standards: (standards). GNU coding standards.
END-INFO-DIR-ENTRY
- GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
-Software Foundation, Inc.
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
-File: standards.info, Node: Standard Targets, Prev: Directory Variables, Up: Makefile Conventions
+File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
+
+Utilities in Makefiles
+----------------------
+
+ Write the Makefile commands (and any shell scripts, such as
+`configure') to run in `sh', not in `csh'. Don't use any special
+features of `ksh' or `bash'.
+
+ The `configure' script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+ cat cmp cp diff echo egrep expr false grep install-info
+ ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+
+ The compression program `gzip' can be used in the `dist' rule.
+
+ Stick to the generally supported options for these programs. For
+example, don't use `mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+ It is a good idea to avoid creating symbolic links in makefiles,
+since a few systems don't support them.
+
+ The Makefile rules for building and installation can also use
+compilers and related programs, but should do so via `make' variables
+so that the user can substitute alternatives. Here are some of the
+programs we mean:
+
+ ar bison cc flex install ld ldconfig lex
+ make makeinfo ranlib texi2dvi yacc
+
+ Use the following `make' variables to run those programs:
+
+ $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+ $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+ When you use `ranlib' or `ldconfig', you should make sure nothing
+bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
+
+ If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+ Additional utilities that can be used via Make variables are:
+
+ chgrp chmod chown mknod
+
+ It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+\1f
+File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
+
+Variables for Specifying Commands
+---------------------------------
+
+ Makefiles should provide variables for overriding certain commands,
+options, and so on.
+
+ In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named `BISON' whose default
+value is set with `BISON = bison', and refer to it with `$(BISON)'
+whenever you need to use Bison.
+
+ File management utilities such as `ln', `rm', `mv', and so on, need
+not be referred to through variables in this way, since users don't
+need to replace them with other programs.
+
+ Each program-name variable should come with an options variable that
+is used to supply options to the program. Append `FLAGS' to the
+program-name variable name to get the options variable name--for
+example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
+`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
+but we keep them because they are standard.) Use `CPPFLAGS' in any
+compilation command that runs the preprocessor, and use `LDFLAGS' in
+any compilation command that does linking as well as in any direct use
+of `ld'.
+
+ If there are C compiler options that _must_ be used for proper
+compilation of certain files, do not include them in `CFLAGS'. Users
+expect to be able to specify `CFLAGS' freely themselves. Instead,
+arrange to pass the necessary options to the C compiler independently
+of `CFLAGS', by writing them explicitly in the compilation commands or
+by defining an implicit rule, like this:
+
+ CFLAGS = -g
+ ALL_CFLAGS = -I. $(CFLAGS)
+ .c.o:
+ $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+ Do include the `-g' option in `CFLAGS', because that is not
+_required_ for proper compilation. You can consider it a default that
+is only recommended. If the package is set up so that it is compiled
+with GCC by default, then you might as well include `-O' in the default
+value of `CFLAGS' as well.
+
+ Put `CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use `CFLAGS' to override
+the others.
+
+ `CFLAGS' should be used in every invocation of the C compiler, both
+those which do compilation and those which do linking.
+
+ Every Makefile should define the variable `INSTALL', which is the
+basic command for installing a file into the system.
+
+ Every Makefile should also define the variables `INSTALL_PROGRAM'
+and `INSTALL_DATA'. (The default for each of these should be
+`$(INSTALL)'.) Then it should use those variables as the commands for
+actual installation, for executables and nonexecutables respectively.
+Use these variables as follows:
+
+ $(INSTALL_PROGRAM) foo $(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+
+ Optionally, you may prepend the value of `DESTDIR' to the target
+filename. Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later. Do not
+set the value of `DESTDIR' in your Makefile, and do not include it in
+any installed files. With support for `DESTDIR', the above examples
+become:
+
+ $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands. Use a separate command for each file to be
+installed.
+
+\1f
+File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
+
+Variables for Installation Directories
+--------------------------------------
+
+ Installation directories should always be named by variables, so it
+is easy to install in a nonstandard place. The standard names for these
+variables are described below. They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
+other modern operating systems.
+
+ These two variables set the root for the installation. All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+`prefix'
+ A prefix used in constructing the default values of the variables
+ listed below. The default value of `prefix' should be
+ `/usr/local'. When building the complete GNU system, the prefix
+ will be empty and `/usr' will be a symbolic link to `/'. (If you
+ are using Autoconf, write it as `@prefix@'.)
+
+ Running `make install' with a different value of `prefix' from the
+ one used to build the program should NOT recompile the program.
+
+`exec_prefix'
+ A prefix used in constructing the default values of some of the
+ variables listed below. The default value of `exec_prefix' should
+ be `$(prefix)'. (If you are using Autoconf, write it as
+ `@exec_prefix@'.)
+
+ Generally, `$(exec_prefix)' is used for directories that contain
+ machine-specific files (such as executables and subroutine
+ libraries), while `$(prefix)' is used directly for other
+ directories.
+
+ Running `make install' with a different value of `exec_prefix'
+ from the one used to build the program should NOT recompile the
+ program.
+
+ Executable programs are installed in one of the following
+directories.
+
+`bindir'
+ The directory for installing executable programs that users can
+ run. This should normally be `/usr/local/bin', but write it as
+ `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
+ `@bindir@'.)
+
+`sbindir'
+ The directory for installing executable programs that can be run
+ from the shell, but are only generally useful to system
+ administrators. This should normally be `/usr/local/sbin', but
+ write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
+ write it as `@sbindir@'.)
+
+`libexecdir'
+ The directory for installing executable programs to be run by other
+ programs rather than by users. This directory should normally be
+ `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
+ (If you are using Autoconf, write it as `@libexecdir@'.)
+
+ Data files used by the program during its execution are divided into
+categories in two ways.
+
+ * Some files are normally modified by programs; others are never
+ normally modified (though users may edit some of these).
+
+ * Some files are architecture-independent and can be shared by all
+ machines at a site; some are architecture-dependent and can be
+ shared only by machines of the same kind and operating system;
+ others may never be shared between two machines.
+
+ This makes for six different possibilities. However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries. It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+ Therefore, here are the variables Makefiles should use to specify
+directories:
+
+`datadir'
+ The directory for installing read-only architecture independent
+ data files. This should normally be `/usr/local/share', but write
+ it as `$(prefix)/share'. (If you are using Autoconf, write it as
+ `@datadir@'.) As a special exception, see `$(infodir)' and
+ `$(includedir)' below.
+
+`sysconfdir'
+ The directory for installing read-only data files that pertain to a
+ single machine-that is to say, files for configuring a host.
+ Mailer and network configuration files, `/etc/passwd', and so
+ forth belong here. All the files in this directory should be
+ ordinary ASCII text files. This directory should normally be
+ `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
+ using Autoconf, write it as `@sysconfdir@'.)
+
+ Do not install executables here in this directory (they probably
+ belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
+ files that are modified in the normal course of their use (programs
+ whose purpose is to change the configuration of the system
+ excluded). Those probably belong in `$(localstatedir)'.
+
+`sharedstatedir'
+ The directory for installing architecture-independent data files
+ which the programs modify while they run. This should normally be
+ `/usr/local/com', but write it as `$(prefix)/com'. (If you are
+ using Autoconf, write it as `@sharedstatedir@'.)
+
+`localstatedir'
+ The directory for installing data files which the programs modify
+ while they run, and that pertain to one specific machine. Users
+ should never need to modify files in this directory to configure
+ the package's operation; put such configuration information in
+ separate files that go in `$(datadir)' or `$(sysconfdir)'.
+ `$(localstatedir)' should normally be `/usr/local/var', but write
+ it as `$(prefix)/var'. (If you are using Autoconf, write it as
+ `@localstatedir@'.)
+
+`libdir'
+ The directory for object files and libraries of object code. Do
+ not install executables here, they probably ought to go in
+ `$(libexecdir)' instead. The value of `libdir' should normally be
+ `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
+ are using Autoconf, write it as `@libdir@'.)
+
+`infodir'
+ The directory for installing the Info files for this package. By
+ default, it should be `/usr/local/info', but it should be written
+ as `$(prefix)/info'. (If you are using Autoconf, write it as
+ `@infodir@'.)
+
+`lispdir'
+ The directory for installing any Emacs Lisp files in this package.
+ By default, it should be `/usr/local/share/emacs/site-lisp', but
+ it should be written as `$(prefix)/share/emacs/site-lisp'.
+
+ If you are using Autoconf, write the default as `@lispdir@'. In
+ order to make `@lispdir@' work, you need the following lines in
+ your `configure.in' file:
+
+ lispdir='${datadir}/emacs/site-lisp'
+ AC_SUBST(lispdir)
+
+`includedir'
+ The directory for installing header files to be included by user
+ programs with the C `#include' preprocessor directive. This
+ should normally be `/usr/local/include', but write it as
+ `$(prefix)/include'. (If you are using Autoconf, write it as
+ `@includedir@'.)
+
+ Most compilers other than GCC do not look for header files in
+ directory `/usr/local/include'. So installing the header files
+ this way is only useful with GCC. Sometimes this is not a problem
+ because some libraries are only really intended to work with GCC.
+ But some libraries are intended to work with other compilers.
+ They should install their header files in two places, one
+ specified by `includedir' and one specified by `oldincludedir'.
+
+`oldincludedir'
+ The directory for installing `#include' header files for use with
+ compilers other than GCC. This should normally be `/usr/include'.
+ (If you are using Autoconf, you can write it as `@oldincludedir@'.)
+
+ The Makefile commands should check whether the value of
+ `oldincludedir' is empty. If it is, they should not try to use
+ it; they should cancel the second installation of the header files.
+
+ A package should not replace an existing header in this directory
+ unless the header came from the same package. Thus, if your Foo
+ package provides a header file `foo.h', then it should install the
+ header file in the `oldincludedir' directory if either (1) there
+ is no `foo.h' there or (2) the `foo.h' that exists came from the
+ Foo package.
+
+ To tell whether `foo.h' came from the Foo package, put a magic
+ string in the file--part of a comment--and `grep' for that string.
+
+ Unix-style man pages are installed in one of the following:
+
+`mandir'
+ The top-level directory for installing the man pages (if any) for
+ this package. It will normally be `/usr/local/man', but you should
+ write it as `$(prefix)/man'. (If you are using Autoconf, write it
+ as `@mandir@'.)
+
+`man1dir'
+ The directory for installing section 1 man pages. Write it as
+ `$(mandir)/man1'.
+
+`man2dir'
+ The directory for installing section 2 man pages. Write it as
+ `$(mandir)/man2'
+
+`...'
+ *Don't make the primary documentation for any GNU software be a
+ man page. Write a manual in Texinfo instead. Man pages are just
+ for the sake of people running GNU software on Unix, which is a
+ secondary application only.*
+
+`manext'
+ The file name extension for the installed man page. This should
+ contain a period followed by the appropriate digit; it should
+ normally be `.1'.
+
+`man1ext'
+ The file name extension for installed section 1 man pages.
+
+`man2ext'
+ The file name extension for installed section 2 man pages.
+
+`...'
+ Use these names instead of `manext' if the package needs to
+ install man pages in more than one section of the manual.
+
+ And finally, you should set the following variable:
+
+`srcdir'
+ The directory for the sources being compiled. The value of this
+ variable is normally inserted by the `configure' shell script.
+ (If you are using Autconf, use `srcdir = @srcdir@'.)
+
+ For example:
+
+ # Common prefix for installation directories.
+ # NOTE: This directory must exist when you start the install.
+ prefix = /usr/local
+ exec_prefix = $(prefix)
+ # Where to put the executable for the command `gcc'.
+ bindir = $(exec_prefix)/bin
+ # Where to put the directories used by the compiler.
+ libexecdir = $(exec_prefix)/libexec
+ # Where to put the Info files.
+ infodir = $(prefix)/info
+
+ If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the `install' rule to create these subdirectories.
+
+ Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above. The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+\1f
+File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
Standard Targets for Users
--------------------------
that don't have the Unix man page documentation system installed.
The way to install Info files is to copy them into `$(infodir)'
- with `$(INSTALL_DATA)' (*note Command Variables::.), and then run
+ with `$(INSTALL_DATA)' (*note Command Variables::), and then run
the `install-info' program if it is present. `install-info' is a
program that edits the Info `dir' file to add or update the menu
entry for the given Info file; it is part of the Texinfo package.
Here is a sample rule to install an Info file:
- $(infodir)/foo.info: foo.info
+ $(DESTDIR)$(infodir)/foo.info: foo.info
+ $(POST_INSTALL)
# There may be a newer info file in . than in srcdir.
-if test -f foo.info; then d=.; \
else d=$(srcdir); fi; \
- $(INSTALL_DATA) $$d/foo.info $@; \
+ $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
# Run install-info only if it exists.
# Use `if' instead of just prepending `-' to the
# line so we notice real errors from install-info.
# fail gracefully when there is an unknown command.
if $(SHELL) -c 'install-info --version' \
>/dev/null 2>&1; then \
- install-info --dir-file=$(infodir)/dir \
- $(infodir)/foo.info; \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/foo.info; \
else true; fi
+ When writing the `install' target, you must classify all the
+ commands into three categories: normal ones, "pre-installation"
+ commands and "post-installation" commands. *Note Install Command
+ Categories::.
+
`uninstall'
- Delete all the installed files that the `install' target would
- create (but not the noninstalled files such as `make all' would
- create).
+ Delete all the installed files--the copies that the `install'
+ target creates.
This rule should not modify the directories where compilation is
done, only the directories where files are installed.
+ The uninstallation commands are divided into three categories,
+ just like the installation commands. *Note Install Command
+ Categories::.
+
`install-strip'
Like `install', but strip the executable files while installing
- them. The definition of this target can be very simple:
+ them. In many cases, the definition of this target can be very
+ simple:
install-strip:
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
run the `makeinfo' program, which is part of the Texinfo
distribution.
+ Normally a GNU distribution comes with Info files, and that means
+ the Info files are present in the source directory. Therefore,
+ the Make rule for an info file should update it in the source
+ directory. When users build the package, ordinarily Make will not
+ update the Info files because they will already be up to date.
+
`dvi'
Generate DVI files for all Texinfo documentation. For example:
appropriately named, use `ln' or `cp' to install the proper files
in it, and then `tar' that subdirectory.
- Compress the tar file with `gzip'. For example, the actual
+ Compress the tar file file with `gzip'. For example, the actual
distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
The `dist' target should explicitly depend on all non-source files
not distributed with Texinfo.
\1f
+File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
+
+Install Command Categories
+--------------------------
+
+ When writing the `install' target, you must classify all the
+commands into three categories: normal ones, "pre-installation"
+commands and "post-installation" commands.
+
+ Normal commands move files into their proper places, and set their
+modes. They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+ Pre-installation and post-installation commands may alter other
+files; in particular, they can edit global configuration files or data
+bases.
+
+ Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+ The most common use for a post-installation command is to run
+`install-info'. This cannot be done with a normal command, since it
+alters a file (the Info directory) which does not come entirely and
+solely from the package being installed. It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+ Most programs don't need any pre-installation commands, but we have
+the feature just in case it is needed.
+
+ To classify the commands in the `install' rule into these three
+categories, insert "category lines" among them. A category line
+specifies the category for the commands that follow.
+
+ A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end. There are three
+variables you can use, one for each category; the variable name
+specifies the category. Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+_should not_ define them in the makefile).
+
+ Here are the three possible category lines, each with a comment that
+explains what it means:
+
+ $(PRE_INSTALL) # Pre-install commands follow.
+ $(POST_INSTALL) # Post-install commands follow.
+ $(NORMAL_INSTALL) # Normal commands follow.
+
+ If you don't use a category line at the beginning of the `install'
+rule, all the commands are classified as normal until the first category
+line. If you don't use any category lines, all the commands are
+classified as normal.
+
+ These are the category lines for `uninstall':
+
+ $(PRE_UNINSTALL) # Pre-uninstall commands follow.
+ $(POST_UNINSTALL) # Post-uninstall commands follow.
+ $(NORMAL_UNINSTALL) # Normal commands follow.
+
+ Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+ If the `install' or `uninstall' target has any dependencies which
+act as subroutines of installation, then you should start _each_
+dependency's commands with a category line, and start the main target's
+commands with a category line also. This way, you can ensure that each
+command is placed in the right category regardless of which of the
+dependencies actually run.
+
+ Pre-installation and post-installation commands should not run any
+programs except for these:
+
+ [ basename bash cat chgrp chmod chown cmp cp dd diff echo
+ egrep expand expr false fgrep find getopt grep gunzip gzip
+ hostname install install-info kill ldconfig ln ls md5sum
+ mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+ test touch true uname xargs yes
+
+ The reason for distinguishing the commands in this way is for the
+sake of making binary packages. Typically a binary package contains
+all the executables and other files that need to be installed, and has
+its own method of installing them--so it does not need to run the normal
+installation commands. But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+ Programs to build binary packages work by extracting the
+pre-installation and post-installation commands. Here is one way of
+extracting the pre-installation commands:
+
+ make -n install -o all \
+ PRE_INSTALL=pre-install \
+ POST_INSTALL=post-install \
+ NORMAL_INSTALL=normal-install \
+ | gawk -f pre-install.awk
+
+where the file `pre-install.awk' could contain this:
+
+ $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
+ on {print $0}
+ $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
+
+ The resulting file of pre-installation commands is executed as a
+shell script as part of installing the binary package.
+
+\1f
File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
Making Releases
===============
- Package the distribution of Foo version 69.96 in a gzipped tar file
-named `foo-69.96.tar.gz'. It should unpack into a subdirectory named
-`foo-69.96'.
+ Package the distribution of `Foo version 69.96' up in a gzipped tar
+file with the name `foo-69.96.tar.gz'. It should unpack into a
+subdirectory named `foo-69.96'.
Building and installing the program should never modify any of the
files contained in the distribution. This means that all the files
never changed automatically; non-source files are produced from source
files by programs under the control of the Makefile.
+ The distribution should contain a file named `README' which gives
+the name of the package, and a general description of what it does. It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any. The `README' file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+ The `README' file should refer to the file `INSTALL', which should
+contain an explanation of the installation procedure.
+
+ The `README' file should also refer to the file which contains the
+copying conditions. The GNU GPL, if used, should be in a file called
+`COPYING'. If the GNU LGPL is used, it should be in a file called
+`COPYING.LIB'.
+
Naturally, all the source files must be in the distribution. It is
okay to include non-source files in the distribution, provided they are
up-to-date and machine-independent, so that building the distribution
smaller at the expense of possible inconvenience to a user who doesn't
know what other files to get.
+\1f
+File: standards.info, Node: References, Prev: Managing Releases, Up: Top
+
+References to Non-Free Software and Documentation
+*************************************************
+
+ A GNU program should not recommend use of any non-free program. We
+can't stop some people from writing proprietary programs, or stop other
+people from using them. But we can and should avoid helping to
+advertise them to new customers.
+
+ Sometimes it is important to mention how to build your package on
+top of some non-free operating system or other non-free base package.
+In such cases, please mention the name of the non-free package or
+system in the briefest possible way. Don't include any references for
+where to find more information about the proprietary program. The goal
+should be that people already using the proprietary program will get
+the advice they need about how to use your free program, while people
+who don't already use the proprietary program will not see anything to
+encourage them to take an interest in it.
+
+ Likewise, a GNU package should not refer the user to any non-free
+documentation for free software. The need for free documentation to go
+with free software is now a major focus of the GNU project; to show that
+we are serious about the need for free documentation, we must not
+undermine our position by recommending use of documentation that isn't
+free.
+
-This is Info file ../info/termcap.info, produced by Makeinfo version
-1.68 from the input file termcap.texi.
+This is ../info/termcap.info, produced by makeinfo version 4.0 from
+termcap.texi.
START-INFO-DIR-ENTRY
* Termcap: (termcap). Termcap library of the GNU system.
This function finds the description and remembers it internally so that
you can interrogate it about specific terminal capabilities (*note
-Interrogate::.).
+Interrogate::).
The argument TERMTYPE is a string which is the name for the type of
terminal to look up. Usually you would obtain this from the environment
the standard capability names.
Once you have found the proper terminal description with `tgetent'
-(*note Find::.), your application program must "interrogate" it for
+(*note Find::), your application program must "interrogate" it for
various terminal capabilities. You must specify the two-letter code of
the capability whose value you seek.
* Initialize various global variables which termcap library output
functions refer to. These include `PC' and `ospeed' for padding
- (*note Output Padding::.) and `UP' and `BC' for cursor motion
- (*note tgoto::.).
+ (*note Output Padding::) and `UP' and `BC' for cursor motion
+ (*note tgoto::).
* Tell the kernel to turn off alteration and padding of
horizontal-tab characters sent to the terminal.
Use the termcap function `tputs' to output a string containing an
optional padding spec of the form described above (*note Describe
-Padding::.). The function `tputs' strips off and decodes the padding
+Padding::). The function `tputs' strips off and decodes the padding
spec, outputs the rest of the string, and then outputs the appropriate
padding. Here is its declaration in ANSI C:
You are responsible for storing suitable values into these variables
before using `tputs'. The value stored into the `PC' variable should be
taken from the `pc' capability in the terminal description (*note Pad
-Specs::.). Store zero in `PC' if there is no `pc' capability.
+Specs::). Store zero in `PC' if there is no `pc' capability.
The argument NLINES requires some thought. Normally, it should be
the number of lines whose contents will be cleared or moved by the
or `tgoto' to encode parameters according to the specifications. These
functions produce a string containing the actual commands to be output
(as well a padding spec which must be processed with `tputs'; *note
-Padding::.).
+Padding::).
* Menu:
`%3'
Like `%03d' in `printf': output the next parameter in decimal, and
always use at least three digits. Note that `%4' and so on are
- *not* defined.
+ _not_ defined.
`%.'
Output the next parameter as a single character whose ASCII code is
A terminal description starts with one or more names for the
terminal type. The information in the description is a series of
"capability names" and values. The capability names have standard
-meanings (*note Capabilities::.) and their values describe the terminal.
+meanings (*note Capabilities::) and their values describe the terminal.
* Menu:
flag.
The string value will often contain digits at the front to specify
-padding (*note Padding::.) and/or `%'-sequences within to specify how
-to encode parameters (*note Parameters::.). Although these things are
-not to be output literally to the terminal, they are considered part of
-the value of the capability. They are special only when the string
-value is processed by `tputs', `tparam' or `tgoto'. By contrast, `\'
-and `^' are considered part of the syntax for specifying the characters
-in the string.
+padding (*note Padding::) and/or `%'-sequences within to specify how to
+encode parameters (*note Parameters::). Although these things are not
+to be output literally to the terminal, they are considered part of the
+value of the capability. They are special only when the string value
+is processed by `tputs', `tparam' or `tgoto'. By contrast, `\' and `^'
+are considered part of the syntax for specifying the characters in the
+string.
Let's look at the VT52 example again:
`bs' and `pt', and many string-valued capabilities. Most of the
strings start with <ESC> represented as `\E'. The rest contain control
characters represented using `^'. The meanings of the individual
-capabilities are defined elsewhere (*note Capabilities::.).
+capabilities are defined elsewhere (*note Capabilities::).
\1f
File: termcap.info, Node: Naming, Next: Inheriting, Prev: Capability Format, Up: Data Base
`-s'
"Status". Says to enable use of a status line which ordinary
- output does not touch (*note Status Line::.).
+ output does not touch (*note Status Line::).
Some terminals have a special line that is used only as a status
line. For these terminals, there is no need for an `-s' variant;
text shown above followed by the text of the description of `aaa-unk'.
The `tc' capability is handled automatically by `tgetent', which finds
the description thus referenced and combines the two descriptions
-(*note Find::.). Therefore, only the implementor of the terminal
+(*note Find::). Therefore, only the implementor of the terminal
descriptions needs to think about using `tc'. Users and application
programmers do not need to be concerned with it.
-This is Info file ../info/termcap.info, produced by Makeinfo version
-1.68 from the input file termcap.texi.
+This is ../info/termcap.info, produced by makeinfo version 4.0 from
+termcap.texi.
START-INFO-DIR-ENTRY
* Termcap: (termcap). Termcap library of the GNU system.
fill in the capabilities described there.
String capabilities that are display commands may require numeric
-parameters (*note Parameters::.). Most such capabilities do not use
+parameters (*note Parameters::). Most such capabilities do not use
parameters. When a capability requires parameters, this is explicitly
stated at the beginning of its definition. In simple cases, the first
or second sentence of the definition mentions all the parameters, in
* Meta Key:: <META> acts like an extra shift key.
* Initialization:: Commands used to initialize or reset the terminal.
* Pad Specs:: Info for the kernel on how much padding is needed.
-* Status Line:: A status line displays "background" information.
+* Status Line:: A status line displays ``background'' information.
* Half-Line:: Moving by half-lines, for superscripts and subscripts.
* Printer:: Controlling auxiliary printers of display terminals.
carriage-return newline sequence. But many terminal descriptions
do use newline in the `do' string, so this is not possible; a
program which sends the `do' string must disable output conversion
- in the kernel (*note Initialize::.).
+ in the kernel (*note Initialize::).
`bw'
Flag whose presence says that `le' may be used in column zero to
New programs should not assume any default for `ta', so they need
not look at `xt' in connection with cursor motion. Note that `xt'
- also has implications for standout mode (*note Standout::.). It
- is obsolete in regard to cursor motion but not in regard to
- standout.
+ also has implications for standout mode (*note Standout::). It is
+ obsolete in regard to cursor motion but not in regard to standout.
In fact, `xt' means that the terminal is a Teleray 1061.
use the newline character for this purpose. These programs follow
a bad practice, but because they exist, it is still desirable to
define the `nl' capability in a terminal description if the best
- way to move down is *not* a newline.
+ way to move down is _not_ a newline.
\1f
File: termcap.info, Node: Wrapping, Next: Scrolling, Prev: Cursor Motion, Up: Capabilities
Writing in the last column of the last line should be avoided on
terminals with `am', as it may or may not cause scrolling to occur
- (*note Scrolling::.). Scrolling is surely not what you would
+ (*note Scrolling::). Scrolling is surely not what you would
intend.
If your program needs to check the `am' flag, then it also needs
cursor is on. The existing line, and all lines below it, are
moved down. The last line in the screen (or in the scroll region,
if one is set) disappears and in most circumstances is discarded.
- It may not be discarded if the `db' is present (*note
- Scrolling::.).
+ It may not be discarded if the `db' is present (*note Scrolling::).
The cursor must be at the left margin before this command is used.
This command does not move the cursor.
bottom of the screen (or scroll region). Very often these commands
require padding proportional to this number of lines. *Note Padding::.
- For `AL' and `DL' the NLINES argument should *not* depend on the
+ For `AL' and `DL' the NLINES argument should _not_ depend on the
number of lines inserted or deleted; only the total number of lines
affected. This is because it is just as fast to insert two or N lines
with `AL' as to insert one line with `al'.
If your terminal offers a choice of ways to insert--either use
insert mode or use a special command--then define `im' and do not
define `ic', since this gives the most efficient operation when
- several characters are to be inserted. *Do not* define both
- strings, for that means that *both* must be used each time
+ several characters are to be inserted. _Do not_ define both
+ strings, for that means that _both_ must be used each time
insertion is done.
`ip'
String of commands to output following an inserted graphic
character in insert mode. Often it is used just for a padding
spec, when padding is needed after an inserted character (*note
- Padding::.).
+ Padding::).
`IC'
String of commands to insert N character positions at and after
positions which have been cleared.
An application program can assume that the terminal can do character
-insertion if *any one of* the capabilities `IC', `im', `ic' or `ip' is
+insertion if _any one of_ the capabilities `IC', `im', `ic' or `ip' is
provided.
To insert N blank character positions, move the cursor to the place
-This is Info file ../info/termcap.info, produced by Makeinfo version
-1.68 from the input file termcap.texi.
+This is ../info/termcap.info, produced by makeinfo version 4.0 from
+termcap.texi.
START-INFO-DIR-ENTRY
* Termcap: (termcap). Termcap library of the GNU system.
with non-standout text must check for the `xs' flag. In a per-character
terminal, this flag says that the only way to remove standout once
written is to clear that portion of the line with the `ce' string or
-something even more powerful (*note Clearing::.); just writing new
+something even more powerful (*note Clearing::); just writing new
characters at those screen positions will not change the modes in
effect there. In a magic cookie terminal, `xs' says that the only way
to remove a cookie is to clear a portion of the line that includes the
also be possible to remove a cookie which is not at the beginning of a
line by clearing that line.) The `xt' capability also has implications
for the use of tab characters, but in that regard it is obsolete (*note
-Cursor Motion::.).
+Cursor Motion::).
`so'
String of commands to enter standout mode.
Here are all the terminal capability names in alphabetical order
with a brief description of each. For cross references to their
-definitions, see the index of capability names (*note Cap Index::.).
+definitions, see the index of capability names (*note Cap Index::).
`ae'
String to turn off alternate character set mode.
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
-File: texinfo.info, Node: Tips, Next: Sample Texinfo File, Prev: Command List, Up: Top
+File: texinfo.info, Node: Command List, Next: Tips, Prev: Creating and Installing Info Files, Up: Top
-Tips and Hints
+@-Command List
**************
- Here are some tips for writing Texinfo documentation:
-
- * Write in the present tense, not in the past or the future.
-
- * Write actively! For example, write "We recommend that ..." rather
- than "It is recommended that ...".
-
- * Use 70 or 72 as your fill column. Longer lines are hard to read.
-
- * Include a copyright notice and copying permissions.
-
-Index, Index, Index!
-....................
-
- Write many index entries, in different ways. Readers like indices;
-they are helpful and convenient.
-
- Although it is easiest to write index entries as you write the body of
-the text, some people prefer to write entries afterwards. In either
-case, write an entry before the paragraph to which it applies. This
-way, an index entry points to the first page of a paragraph that is
-split across pages.
-
- Here are more hints we have found valuable:
-
- * Write each index entry differently, so each entry refers to a
- different place in the document.
-
- * Write index entries only where a topic is discussed significantly.
- For example, it is not useful to index "debugging information" in
- a chapter on reporting bugs. Someone who wants to know about
- debugging information will certainly not find it in that chapter.
-
- * Consistently capitalize the first word of every concept index
- entry, or else consistently use lower case. Terse entries often
- call for lower case; longer entries for capitalization. Whichever
- case convention you use, please use one or the other consistently!
- Mixing the two styles looks bad.
-
- * Always capitalize or use upper case for those words in an index for
- which this is proper, such as names of countries or acronyms.
- Always use the appropriate case for case-sensitive names, such as
- those in C or Lisp.
-
- * Write the indexing commands that refer to a whole section
- immediately after the section command, and write the indexing
- commands that refer to the paragraph before the paragraph.
-
- In the example that follows, a blank line comes after the index
- entry for "Leaping":
-
- @section The Dog and the Fox
- @cindex Jumping, in general
- @cindex Leaping
-
- @cindex Dog, lazy, jumped over
- @cindex Lazy dog jumped over
- @cindex Fox, jumps over dog
- @cindex Quick fox jumps over dog
- The quick brown fox jumps over the lazy dog.
-
- (Note that the example shows entries for the same concept that are
- written in different ways--`Lazy dog', and `Dog, lazy'--so readers
- can look up the concept in different ways.)
-
-Blank Lines
-...........
-
- * Insert a blank line between a sectioning command and the first
- following sentence or paragraph, or between the indexing commands
- associated with the sectioning command and the first following
- sentence or paragraph, as shown in the tip on indexing.
- Otherwise, a formatter may fold title and paragraph together.
-
- * Always insert a blank line before an `@table' command and after an
- `@end table' command; but never insert a blank line after an
- `@table' command or before an `@end table' command.
-
- For example,
-
- Types of fox:
-
- @table @samp
- @item Quick
- Jump over lazy dogs.
-
- @item Brown
- Also jump over lazy dogs.
- @end table
- @noindent
- On the other hand, ...
-
- Insert blank lines before and after `@itemize' ... `@end itemize'
- and `@enumerate' ... `@end enumerate' in the same way.
-
-Complete Phrases
-................
-
- Complete phrases are easier to read than ...
-
- * Write entries in an itemized list as complete sentences; or at
- least, as complete phrases. Incomplete expressions ... awkward
- ... like this.
-
- * Write the prefatory sentence or phrase for a multi-item list or
- table as a complete expression. Do not write "You can set:";
- instead, write "You can set these variables:". The former
- expression sounds cut off.
-
-Editions, Dates and Versions
-............................
-
- Write the edition and version numbers and date in three places in
-every manual:
-
- 1. In the first `@ifinfo' section, for people reading the Texinfo
- file.
-
- 2. In the `@titlepage' section, for people reading the printed manual.
-
- 3. In the `Top' node, for people reading the Info file.
-
-Also, it helps to write a note before the first `@ifinfo' section to
-explain what you are doing.
-
-For example:
-
- @c ===> NOTE! <==
- @c Specify the edition and version numbers and date
- @c in *three* places:
- @c 1. First ifinfo section 2. title page 3. top node
- @c To find the locations, search for !!set
-
- @ifinfo
- @c !!set edition, date, version
- This is Edition 4.03, January 1992,
- of the @cite{GDB Manual} for GDB Version 4.3.
- ...
-
---or use `@set' and `@value' (*note `@value' Example: value Example.).
-
-Definition Commands
-...................
-
- Definition commands are `@deffn', `@defun', `@defmac', and the like,
-and enable you to write descriptions in a uniform format.
-
- * Write just one definition command for each entity you define with a
- definition command. The automatic indexing feature creates an
- index entry that leads the reader to the definition.
-
- * Use `@table' ... `@end table' in an appendix that contains a
- summary of functions, not `@deffn' or other definition commands.
-
-Capitalization
-..............
-
- * Capitalize "Texinfo"; it is a name. Do not write the `x' or `i'
- in upper case.
-
- * Capitalize "Info"; it is a name.
-
- * Write TeX using the `@TeX{}' command. Note the uppercase `T' and
- `X'. This command causes the formatters to typeset the name
- according to the wishes of Donald Knuth, who wrote TeX.
-
-Spaces
-......
-
- Do not use spaces to format a Texinfo file, except inside of
-`@example' ... `@end example' and similar commands.
-
- For example, TeX fills the following:
-
- @kbd{C-x v}
- @kbd{M-x vc-next-action}
- Perform the next logical operation
- on the version-controlled file
- corresponding to the current buffer.
-
-so it looks like this:
-
- `C-x v' `M-x vc-next-action' Perform the next logical operation on
- the version-controlled file corresponding to the current buffer.
-
-In this case, the text should be formatted with `@table', `@item', and
-`@itemx', to create a table.
-
-@code, @samp, @var, and `---'
-.............................
-
- * Use `@code' around Lisp symbols, including command names. For
- example,
-
- The main function is @code{vc-next-action}, ...
-
- * Avoid putting letters such as `s' immediately after an `@code'.
- Such letters look bad.
-
- * Use `@var' around meta-variables. Do not write angle brackets
- around them.
-
- * Use three hyphens in a row, `---', to indicate a long dash. TeX
- typesets these as a long dash and the Info formatters reduce three
- hyphens to two.
-
-Periods Outside of Quotes
-.........................
-
- Place periods and other punctuation marks *outside* of quotations,
-unless the punctuation is part of the quotation. This practice goes
-against publishing conventions in the United States, but enables the
-reader to distinguish between the contents of the quotation and the
-whole passage.
-
- For example, you should write the following sentence with the period
-outside the end quotation marks:
-
- Evidently, `au' is an abbreviation for ``author''.
-
-since `au' does *not* serve as an abbreviation for `author.' (with a
-period following the word).
-
-Introducing New Terms
-.....................
-
- * Introduce new terms so that a reader who does not know them can
- understand them from context; or write a definition for the term.
-
- For example, in the following, the terms "check in", "register" and
- "delta" are all appearing for the first time; the example sentence
- should be rewritten so they are understandable.
-
- The major function assists you in checking in a file to your
- version control system and registering successive sets of
- changes to it as deltas.
-
- * Use the `@dfn' command around a word being introduced, to indicate
- that the reader should not expect to know the meaning already, and
- should expect to learn the meaning from this passage.
-
-@pxref
-......
-
- Absolutely never use `@pxref' except in the special context for which
-it is designed: inside parentheses, with the closing parenthesis
-following immediately after the closing brace. One formatter
-automatically inserts closing punctuation and the other does not. This
-means that the output looks right both in printed output and in an Info
-file, but only when the command is used inside parentheses.
-
-Invoking from a Shell
-.....................
-
- You can invoke programs such as Emacs, GCC, and `gawk' from a shell.
-The documentation for each program should contain a section that
-describes this. Unfortunately, if the node names and titles for these
-sections are all different, readers find it hard to search for the
-section.
-
- Name such sections with a phrase beginning with the word
-`Invoking ...', as in `Invoking Emacs'; this way users can find the
-section easily.
-
-ANSI C Syntax
-.............
-
- When you use `@example' to describe a C function's calling
-conventions, use the ANSI C syntax, like this:
-
- void dld_init (char *@var{path});
-
-And in the subsequent discussion, refer to the argument values by
-writing the same argument names, again highlighted with `@var'.
-
- Avoid the obsolete style that looks like this:
-
- #include <dld.h>
-
- dld_init (path)
- char *path;
-
- Also, it is best to avoid writing `#include' above the declaration
-just to indicate that the function is declared in a header file. The
-practice may give the misimpression that the `#include' belongs near
-the declaration of the function. Either state explicitly which header
-file holds the declaration or, better yet, name the header file used
-for a group of functions at the beginning of the section that describes
-the functions.
-
-Bad Examples
-............
-
- Here are several examples of bad writing to avoid:
-
- In this example, say, " ... you must `@dfn'{check in} the new
-version." That flows better.
-
- When you are done editing the file, you must perform a
- `@dfn'{check in}.
-
- In the following example, say, "... makes a unified interface such as
-VC mode possible."
-
- SCCS, RCS and other version-control systems all perform similar
- functions in broadly similar ways (it is this resemblance which
- makes a unified control mode like this possible).
-
- And in this example, you should specify what `it' refers to:
-
- If you are working with other people, it assists in coordinating
- everyone's changes so they do not step on each other.
-
-And Finally ...
-...............
-
- * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
- in the name `Bach'. But pronounce Texinfo as in `speck':
- "teckinfo".
-
- * Write notes for yourself at the very end of a Texinfo file after
- the `@bye'. None of the formatters process text after the `@bye';
- it is as if the text were within `@ignore' ... `@end ignore'.
-
-\1f
-File: texinfo.info, Node: Sample Texinfo File, Next: Sample Permissions, Prev: Tips, Up: Top
-
-A Sample Texinfo File
-*********************
-
- Here is a complete, short sample Texinfo file, without any commentary.
-You can see this file, with comments, in the first chapter. *Note A
-Short Sample Texinfo File: Short Sample.
-
- \input texinfo @c -*-texinfo-*-
- @c %**start of header
- @setfilename sample.info
- @settitle Sample Document
- @c %**end of header
-
- @setchapternewpage odd
-
- @ifinfo
- This is a short example of a complete Texinfo file.
-
- Copyright 1990 Free Software Foundation, Inc.
- @end ifinfo
-
- @titlepage
- @sp 10
- @comment The title is printed in a large font.
- @center @titlefont{Sample Title}
-
- @c The following two commands start the copyright page.
- @page
- @vskip 0pt plus 1filll
- Copyright @copyright{} 1990 Free Software Foundation, Inc.
- @end titlepage
-
- @node Top, First Chapter, , (dir)
- @comment node-name, next, previous, up
-
- @menu
- * First Chapter:: The first chapter is the
- only chapter in this sample.
- * Concept Index:: This index has two entries.
- @end menu
-
- @node First Chapter, Concept Index, Top, Top
- @comment node-name, next, previous, up
- @chapter First Chapter
- @cindex Sample index entry
-
- This is the contents of the first chapter.
- @cindex Another sample index entry
-
- Here is a numbered list.
-
- @enumerate
- @item
- This is the first item.
-
- @item
- This is the second item.
- @end enumerate
-
- The @code{makeinfo} and @code{texinfo-format-buffer}
- commands transform a Texinfo file such as this into
- an Info file; and @TeX{} typesets it for a printed
- manual.
-
- @node Concept Index, , First Chapter, Top
- @comment node-name, next, previous, up
- @unnumbered Concept Index
-
- @printindex cp
-
- @contents
- @bye
-
-\1f
-File: texinfo.info, Node: Sample Permissions, Next: Include Files, Prev: Sample Texinfo File, Up: Top
-
-Sample Permissions
-******************
-
- Texinfo files should contain sections that tell the readers that they
-have the right to copy and distribute the Texinfo file, the Info file,
-and the printed manual.
-
- Also, if you are writing a manual about software, you should explain
-that the software is free and either include the GNU General Public
-License (GPL) or provide a reference to it. *Note Distribution:
-(xemacs)Distrib, for an example of the text that could be used in the
-software "Distribution", "General Public License", and "NO WARRANTY"
-sections of a document. *Note Texinfo Copying Conditions: Copying, for
-an example of a brief explanation of how the copying conditions provide
-you with rights.
-
-* Menu:
-
-* Inserting Permissions:: How to put permissions in your document.
-* ifinfo Permissions:: Sample `ifinfo' copying permissions.
-* Titlepage Permissions:: Sample Titlepage copying permissions.
-
-\1f
-File: texinfo.info, Node: Inserting Permissions, Next: ifinfo Permissions, Prev: Sample Permissions, Up: Sample Permissions
-
-Inserting Permissions
-=====================
-
- In a Texinfo file, the first `@ifinfo' section usually begins with a
-line that says what the file documents. This is what a person reading
-the unprocessed Texinfo file or using the advanced Info command `g *'
-sees first. *note Advanced Info commands: (info)Expert, for more
-information. (A reader using the regular Info commands usually starts
-reading at the first node and skips this first section, which is not in
-a node.)
-
- In the `@ifinfo' section, the summary sentence is followed by a
-copyright notice and then by the copying permission notice. One of the
-copying permission paragraphs is enclosed in `@ignore' and `@end
-ignore' commands. This paragraph states that the Texinfo file can be
-processed through TeX and printed, provided the printed manual carries
-the proper copying permission notice. This paragraph is not made part
-of the Info file since it is not relevant to the Info file; but it is a
-mandatory part of the Texinfo file since it permits people to process
-the Texinfo file in TeX and print the results.
-
- In the printed manual, the Free Software Foundation copying permission
-notice follows the copyright notice and publishing information and is
-located within the region delineated by the `@titlepage' and `@end
-titlepage' commands. The copying permission notice is exactly the same
-as the notice in the `@ifinfo' section except that the paragraph
-enclosed in `@ignore' and `@end ignore' commands is not part of the
-notice.
-
- To make it simple to insert a permission notice into each section of
-the Texinfo file, sample permission notices for each section are
-reproduced in full below.
-
- Note that you may need to specify the correct name of a section
-mentioned in the permission notice. For example, in `The GDB Manual',
-the name of the section referring to the General Public License is
-called the "GDB General Public License", but in the sample shown below,
-that section is referred to generically as the "GNU General Public
-License". If the Texinfo file does not carry a copy of the General
-Public License, leave out the reference to it, but be sure to include
-the rest of the sentence.
-
-\1f
-File: texinfo.info, Node: ifinfo Permissions, Next: Titlepage Permissions, Prev: Inserting Permissions, Up: Sample Permissions
-
-`ifinfo' Copying Permissions
-============================
-
- In the `@ifinfo' section of a Texinfo file, the standard Free
-Software Foundation permission notice reads as follows:
-
- This file documents ...
-
- Copyright 1998 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim
- copies of this manual provided the copyright notice and
- this permission notice are preserved on all copies.
-
- @ignore
- Permission is granted to process this file through TeX
- and print the results, provided the printed document
- carries a copying permission notice identical to this
- one except for the removal of this paragraph (this
- paragraph not being relevant to the printed manual).
-
- @end ignore
- Permission is granted to copy and distribute modified
- versions of this manual under the conditions for
- verbatim copying, provided also that the sections
- entitled ``Copying'' and ``GNU General Public License''
- are included exactly as in the original, and provided
- that the entire resulting derived work is distributed
- under the terms of a permission notice identical to this
- one.
-
- Permission is granted to copy and distribute
- translations of this manual into another language,
- under the above conditions for modified versions,
- except that this permission notice may be stated in a
- translation approved by the Free Software Foundation.
-
-\1f
-File: texinfo.info, Node: Titlepage Permissions, Prev: ifinfo Permissions, Up: Sample Permissions
-
-Titlepage Copying Permissions
-=============================
-
- In the `@titlepage' section of a Texinfo file, the standard Free
-Software Foundation copying permission notice follows the copyright
-notice and publishing information. The standard phrasing is as follows:
-
- Permission is granted to make and distribute verbatim
- copies of this manual provided the copyright notice and
- this permission notice are preserved on all copies.
-
- Permission is granted to copy and distribute modified
- versions of this manual under the conditions for
- verbatim copying, provided also that the sections
- entitled ``Copying'' and ``GNU General Public License''
- are included exactly as in the original, and provided
- that the entire resulting derived work is distributed
- under the terms of a permission notice identical to this
- one.
-
- Permission is granted to copy and distribute
- translations of this manual into another language,
- under the above conditions for modified versions,
- except that this permission notice may be stated in a
- translation approved by the Free Software Foundation.
-
-\1f
-File: texinfo.info, Node: Include Files, Next: Headings, Prev: Sample Permissions, Up: Top
-
-Include Files
-*************
-
- When TeX or an Info formatting command sees an `@include' command in
-a Texinfo file, it processes the contents of the file named by the
-command and incorporates them into the DVI or Info file being created.
-Index entries from the included file are incorporated into the indices
-of the output file.
-
- Include files let you keep a single large document as a collection of
-conveniently small parts.
-
-* Menu:
-
-* Using Include Files:: How to use the `@include' command.
-* texinfo-multiple-files-update:: How to create and update nodes and
- menus when using included files.
-* Include File Requirements:: What `texinfo-multiple-files-update' expects.
-* Sample Include File:: A sample outer file with included files
- within it; and a sample included file.
-* Include Files Evolution:: How use of the `@include' command
- has changed over time.
-
-\1f
-File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Prev: Include Files, Up: Include Files
-
-How to Use Include Files
-========================
-
- To include another file within a Texinfo file, write the `@include'
-command at the beginning of a line and follow it on the same line by
-the name of a file to be included. For example:
-
- @include buffers.texi
-
- An included file should simply be a segment of text that you expect to
-be included as is into the overall or "outer" Texinfo file; it should
-not contain the standard beginning and end parts of a Texinfo file. In
-particular, you should not start an included file with a line saying
-`\input texinfo'; if you do, that phrase is inserted into the output
-file as is. Likewise, you should not end an included file with an
-`@bye' command; nothing after `@bye' is formatted.
-
- In the past, you were required to write an `@setfilename' line at the
-beginning of an included file, but no longer. Now, it does not matter
-whether you write such a line. If an `@setfilename' line exists in an
-included file, it is ignored.
-
- Conventionally, an included file begins with an `@node' line that is
-followed by an `@chapter' line. Each included file is one chapter.
-This makes it easy to use the regular node and menu creating and
-updating commands to create the node pointers and menus within the
-included file. However, the simple Emacs node and menu creating and
-updating commands do not work with multiple Texinfo files. Thus you
-cannot use these commands to fill in the `Next', `Previous', and `Up'
-pointers of the `@node' line that begins the included file. Also, you
-cannot use the regular commands to create a master menu for the whole
-file. Either you must insert the menus and the `Next', `Previous', and
-`Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
-command, `texinfo-multiple-files-update', that is designed for
-`@include' files.
-
-\1f
-File: texinfo.info, Node: texinfo-multiple-files-update, Next: Include File Requirements, Prev: Using Include Files, Up: Include Files
-
-`texinfo-multiple-files-update'
-===============================
-
- GNU Emacs Texinfo mode provides the `texinfo-multiple-files-update'
-command. This command creates or updates `Next', `Previous', and `Up'
-pointers of included files as well as those in the outer or overall
-Texinfo file, and it creates or updates a main menu in the outer file.
-Depending whether you call it with optional arguments, the command
-updates only the pointers in the first `@node' line of the included
-files or all of them:
-
-`M-x texinfo-multiple-files-update'
- Called without any arguments:
-
- - Create or update the `Next', `Previous', and `Up' pointers of
- the first `@node' line in each file included in an outer or
- overall Texinfo file.
-
- - Create or update the `Top' level node pointers of the outer or
- overall file.
-
- - Create or update a main menu in the outer file.
-
-`C-u M-x texinfo-multiple-files-update'
- Called with `C-u' as a prefix argument:
-
- - Create or update pointers in the first `@node' line in each
- included file.
-
- - Create or update the `Top' level node pointers of the outer
- file.
-
- - Create and insert a master menu in the outer file. The
- master menu is made from all the menus in all the included
- files.
-
-`C-u 8 M-x texinfo-multiple-files-update'
- Called with a numeric prefix argument, such as `C-u 8':
-
- - Create or update *all* the `Next', `Previous', and `Up'
- pointers of all the included files.
-
- - Create or update *all* the menus of all the included files.
-
- - Create or update the `Top' level node pointers of the outer or
- overall file.
-
- - And then create a master menu in the outer file. This is
- similar to invoking `texinfo-master-menu' with an argument
- when you are working with just one file.
-
- Note the use of the prefix argument in interactive use: with a regular
-prefix argument, just `C-u', the `texinfo-multiple-files-update'
-command inserts a master menu; with a numeric prefix argument, such as
-`C-u 8', the command updates *every* pointer and menu in *all* the
-files and then inserts a master menu.
-
-\1f
-File: texinfo.info, Node: Include File Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files
-
-Include File Requirements
-=========================
-
- If you plan to use the `texinfo-multiple-files-update' command, the
-outer Texinfo file that lists included files within it should contain
-nothing but the beginning and end parts of a Texinfo file, and a number
-of `@include' commands listing the included files. It should not even
-include indices, which should be listed in an included file of their
-own.
-
- Moreover, each of the included files must contain exactly one highest
-level node (conventionally, `@chapter' or equivalent), and this node
-must be the first node in the included file. Furthermore, each of
-these highest level nodes in each included file must be at the same
-hierarchical level in the file structure. Usually, each is an
-`@chapter', an `@appendix', or an `@unnumbered' node. Thus, normally,
-each included file contains one, and only one, chapter or
-equivalent-level node.
-
- The outer file should contain only *one* node, the `Top' node. It
-should *not* contain any nodes besides the single `Top' node. The
-`texinfo-multiple-files-update' command will not process them.
-
-\1f
-File: texinfo.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include File Requirements, Up: Include Files
-
-Sample File with `@include'
-===========================
-
- Here is an example of a complete outer Texinfo file with `@include'
-files within it before running `texinfo-multiple-files-update', which
-would insert a main or master menu:
-
- \input texinfo @c -*-texinfo-*-
- @setfilename include-example.info
- @settitle Include Example
-
- @setchapternewpage odd
- @titlepage
- @sp 12
- @center @titlefont{Include Example}
- @sp 2
- @center by Whom Ever
-
- @page
- @vskip 0pt plus 1filll
- Copyright @copyright{} 1998 Free Software Foundation, Inc.
- @end titlepage
-
- @ifinfo
- @node Top, First, , (dir)
- @top Master Menu
- @end ifinfo
-
- @include foo.texinfo
- @include bar.texinfo
- @include concept-index.texinfo
-
- @summarycontents
- @contents
-
- @bye
-
- An included file, such as `foo.texinfo', might look like this:
-
- @node First, Second, , Top
- @chapter First Chapter
-
- Contents of first chapter ...
-
- The full contents of `concept-index.texinfo' might be as simple as
-this:
-
- @node Concept Index, , Second, Top
- @unnumbered Concept Index
-
- @printindex cp
-
- The outer Texinfo source file for `The XEmacs Lisp Reference Manual'
-is named `elisp.texi'. This outer file contains a master menu with 417
-entries and a list of 41 `@include' files.
-
-\1f
-File: texinfo.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files
-
-Evolution of Include Files
-==========================
-
- When Info was first created, it was customary to create many small
-Info files on one subject. Each Info file was formatted from its own
-Texinfo source file. This custom meant that Emacs did not need to make
-a large buffer to hold the whole of a large Info file when someone
-wanted information; instead, Emacs allocated just enough memory for the
-small Info file that contained the particular information sought. This
-way, Emacs could avoid wasting memory.
-
- References from one file to another were made by referring to the file
-name as well as the node name. (*Note Referring to Other Info Files:
-Other Info Files. Also, see *Note `@xref' with Four and Five
-Arguments: Four and Five Arguments.)
-
- Include files were designed primarily as a way to create a single,
-large printed manual out of several smaller Info files. In a printed
-manual, all the references were within the same document, so TeX could
-automatically determine the references' page numbers. The Info
-formatting commands used include files only for creating joint indices;
-each of the individual Texinfo files had to be formatted for Info
-individually. (Each, therefore, required its own `@setfilename' line.)
-
- However, because large Info files are now split automatically, it is
-no longer necessary to keep them small.
-
- Nowadays, multiple Texinfo files are used mostly for large documents,
-such as `The XEmacs Lisp Reference Manual', and for projects in which
-several different people write different sections of a document
-simultaneously.
-
- In addition, the Info formatting commands have been extended to work
-with the `@include' command so as to create a single large Info file
-that is split into smaller files if necessary. This means that you can
-write menus and cross references without naming the different Texinfo
-files.
-
-\1f
-File: texinfo.info, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top
-
-Page Headings
-*************
-
- Most printed manuals contain headings along the top of every page
-except the title and copyright pages. Some manuals also contain
-footings. (Headings and footings have no meaning to Info, which is not
-paginated.)
-
-* Menu:
-
-* Headings Introduced:: Conventions for using page headings.
-* Heading Format:: Standard page heading formats.
-* Heading Choice:: How to specify the type of page heading.
-* Custom Headings:: How to create your own headings and footings.
-
-\1f
-File: texinfo.info, Node: Headings Introduced, Next: Heading Format, Prev: Headings, Up: Headings
-
-Headings Introduced
-===================
-
- Texinfo provides standard page heading formats for manuals that are
-printed on one side of each sheet of paper and for manuals that are
-printed on both sides of the paper. Typically, you will use these
-formats, but you can specify your own format if you wish.
-
- In addition, you can specify whether chapters should begin on a new
-page, or merely continue the same page as the previous chapter; and if
-chapters begin on new pages, you can specify whether they must be
-odd-numbered pages.
-
- By convention, a book is printed on both sides of each sheet of paper.
-When you open a book, the right-hand page is odd-numbered, and chapters
-begin on right-hand pages--a preceding left-hand page is left blank if
-necessary. Reports, however, are often printed on just one side of
-paper, and chapters begin on a fresh page immediately following the end
-of the preceding chapter. In short or informal reports, chapters often
-do not begin on a new page at all, but are separated from the preceding
-text by a small amount of whitespace.
-
- The `@setchapternewpage' command controls whether chapters begin on
-new pages, and whether one of the standard heading formats is used. In
-addition, Texinfo has several heading and footing commands that you can
-use to generate your own heading and footing formats.
-
- In Texinfo, headings and footings are single lines at the tops and
-bottoms of pages; you cannot create multiline headings or footings.
-Each header or footer line is divided into three parts: a left part, a
-middle part, and a right part. Any part, or a whole line, may be left
-blank. Text for the left part of a header or footer line is set
-flushleft; text for the middle part is centered; and, text for the
-right part is set flushright.
-
-\1f
-File: texinfo.info, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings
-
-Standard Heading Formats
-========================
-
- Texinfo provides two standard heading formats, one for manuals printed
-on one side of each sheet of paper, and the other for manuals printed
-on both sides of the paper.
-
- By default, nothing is specified for the footing of a Texinfo file,
-so the footing remains blank.
-
- The standard format for single-sided printing consists of a header
-line in which the left-hand part contains the name of the chapter, the
-central part is blank, and the right-hand part contains the page number.
-
- A single-sided page looks like this:
-
- _______________________
- | |
- | chapter page number |
- | |
- | Start of text ... |
- | ... |
- | |
-
- The standard format for two-sided printing depends on whether the page
-number is even or odd. By convention, even-numbered pages are on the
-left- and odd-numbered pages are on the right. (TeX will adjust the
-widths of the left- and right-hand margins. Usually, widths are
-correct, but during double-sided printing, it is wise to check that
-pages will bind properly--sometimes a printer will produce output in
-which the even-numbered pages have a larger right-hand margin than the
-odd-numbered pages.)
-
- In the standard double-sided format, the left part of the left-hand
-(even-numbered) page contains the page number, the central part is
-blank, and the right part contains the title (specified by the
-`@settitle' command). The left part of the right-hand (odd-numbered)
-page contains the name of the chapter, the central part is blank, and
-the right part contains the page number.
-
- Two pages, side by side as in an open book, look like this:
-
- _______________________ _______________________
- | | | |
- | page number title | | chapter page number |
- | | | |
- | Start of text ... | | More text ... |
- | ... | | ... |
- | | | |
-
-The chapter name is preceded by the word "Chapter", the chapter number
-and a colon. This makes it easier to keep track of where you are in the
-manual.
-
-\1f
-File: texinfo.info, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings
-
-Specifying the Type of Heading
-==============================
-
- TeX does not begin to generate page headings for a standard Texinfo
-file until it reaches the `@end titlepage' command. Thus, the title
-and copyright pages are not numbered. The `@end titlepage' command
-causes TeX to begin to generate page headings according to a standard
-format specified by the `@setchapternewpage' command that precedes the
-`@titlepage' section.
-
- There are four possibilities:
-
-No `@setchapternewpage' command
- Cause TeX to specify the single-sided heading format, with chapters
- on new pages. This is the same as `@setchapternewpage on'.
-
-`@setchapternewpage on'
- Specify the single-sided heading format, with chapters on new
- pages.
-
-`@setchapternewpage off'
- Cause TeX to start a new chapter on the same page as the last page
- of the preceding chapter, after skipping some vertical whitespace.
- Also cause TeX to typeset for single-sided printing. (You can
- override the headers format with the `@headings double' command;
- see *Note The `@headings' Command: headings on off.)
-
-`@setchapternewpage odd'
- Specify the double-sided heading format, with chapters on new
- pages.
-
-Texinfo lacks an `@setchapternewpage even' command.
-
-\1f
-File: texinfo.info, Node: Custom Headings, Prev: Heading Choice, Up: Headings
-
-How to Make Your Own Headings
-=============================
-
- You can use the standard headings provided with Texinfo or specify
-your own. By default, Texinfo has no footers, so if you specify them,
-the available page size for the main text will be slightly reduced.
-
- Texinfo provides six commands for specifying headings and footings.
-The `@everyheading' command and `@everyfooting' command generate page
-headers and footers that are the same for both even- and odd-numbered
-pages. The `@evenheading' command and `@evenfooting' command generate
-headers and footers for even-numbered (left-hand) pages; and the
-`@oddheading' command and `@oddfooting' command generate headers and
-footers for odd-numbered (right-hand) pages.
-
- Write custom heading specifications in the Texinfo file immediately
-after the `@end titlepage' command. Enclose your specifications
-between `@iftex' and `@end iftex' commands since the
-`texinfo-format-buffer' command may not recognize them. Also, you must
-cancel the predefined heading commands with the `@headings off' command
-before defining your own specifications.
-
- Here is how to tell TeX to place the chapter name at the left, the
-page number in the center, and the date at the right of every header
-for both even- and odd-numbered pages:
-
- @iftex
- @headings off
- @everyheading @thischapter @| @thispage @| @today{}
- @end iftex
-
-You need to divide the left part from the central part and the central
-part from the right part by inserting `@|' between parts. Otherwise,
-the specification command will not be able to tell where the text for
-one part ends and the next part begins.
-
- Each part can contain text or @-commands. The text is printed as if
-the part were within an ordinary paragraph in the body of the page.
-The @-commands replace themselves with the page number, date, chapter
-name, or whatever.
-
- Here are the six heading and footing commands:
-
-`@everyheading LEFT @| CENTER @| RIGHT'
-`@everyfooting LEFT @| CENTER @| RIGHT'
- The `every' commands specify the format for both even- and
- odd-numbered pages. These commands are for documents that are
- printed on one side of each sheet of paper, or for documents in
- which you want symmetrical headers or footers.
-
-`@evenheading LEFT @| CENTER @| RIGHT'
-`@oddheading LEFT @| CENTER @| RIGHT'
-`@evenfooting LEFT @| CENTER @| RIGHT'
-`@oddfooting LEFT @| CENTER @| RIGHT'
- The `even' and `odd' commands specify the format for even-numbered
- pages and odd-numbered pages. These commands are for books and
- manuals that are printed on both sides of each sheet of paper.
-
- Use the `@this...' series of @-commands to provide the names of
-chapters and sections and the page number. You can use the `@this...'
-commands in the left, center, or right portions of headers and footers,
-or anywhere else in a Texinfo file so long as they are between `@iftex'
-and `@end iftex' commands.
-
- Here are the `@this...' commands:
-
-`@thispage'
- Expands to the current page number.
-
-`@thischaptername'
- Expands to the name of the current chapter.
+ Here is an alphabetical list of the @-commands in Texinfo. Square
+brackets, [ ], indicate optional arguments; an ellipsis, `...',
+indicates repeated text.
+
+
+`@WHITESPACE'
+ An `@' followed by a space, tab, or newline produces a normal,
+ stretchable, interword space. *Note Multiple Spaces::.
+
+`@!'
+ Generate an exclamation point that really does end a sentence
+ (usually after an end-of-sentence capital letter). *Note Ending a
+ Sentence::.
+
+`@"'
+`@''
+ Generate an umlaut or acute accent, respectively, over the next
+ character, as in o" and o'. *Note Inserting Accents::.
+
+`@*'
+ Force a line break. Do not end a paragraph that uses `@*' with an
+ `@refill' command. *Note Line Breaks::.
+
+`@,{C}'
+ Generate a cedilla accent under C, as in c,. *Note Inserting
+ Accents::.
+
+`@-'
+ Insert a discretionary hyphenation point. *Note - and
+ hyphenation::.
+
+`@.'
+ Produce a period that really does end a sentence (usually after an
+ end-of-sentence capital letter). *Note Ending a Sentence::.
+
+`@:'
+ Indicate to TeX that an immediately preceding period, question
+ mark, exclamation mark, or colon does not end a sentence. Prevent
+ TeX from inserting extra whitespace as it does at the end of a
+ sentence. The command has no effect on the Info file output.
+ *Note Not Ending a Sentence::.
+
+`@='
+ Generate a macron (bar) accent over the next character, as in o=.
+ *Note Inserting Accents::.
+
+`@?'
+ Generate a question mark that really does end a sentence (usually
+ after an end-of-sentence capital letter). *Note Ending a
+ Sentence::.
+
+`@@'
+ Stands for an at sign, `@'. *Note Inserting @ and braces: Braces
+ Atsigns.
+
+`@^'
+`@`'
+ Generate a circumflex (hat) or grave accent, respectively, over
+ the next character, as in o^. *Note Inserting Accents::.
+
+`@{'
+ Stands for a left brace, `{'. *Note Inserting @ and braces:
+ Braces Atsigns.
+
+`@}'
+ Stands for a right-hand brace, `}'.
+ *Note Inserting @ and braces: Braces Atsigns.
+
+`@~'
+ Generate a tilde accent over the next character, as in N~. *Note
+ Inserting Accents::.
+
+`@AA{}'
+`@aa{}'
+ Generate the uppercase and lowercase Scandinavian A-ring letters,
+ respectively: AA, aa. *Note Inserting Accents::.
+
+`@acronym{ABBREV}'
+ Tag ABBREV as an acronym, that is, an abbreviation written in all
+ capital letters, such as `NASA'. *Note `acronym': acronym.
+
+`@AE{}'
+`@ae{}'
+ Generate the uppercase and lowercase AE ligatures, respectively:
+ AE, ae. *Note Inserting Accents::.
+
+`@afourlatex'
+`@afourpaper'
+`@afourwide'
+ Change page dimensions for the A4 paper size. *Note A4 Paper::.
+
+`@alias NEW=EXISTING'
+ Make the command `@NEW' an alias for the existing command
+ `@EXISTING'. *Note alias::.
+
+`@anchor{NAME}'
+ Define NAME as the current location for use as a cross-reference
+ target. *Note `@anchor': anchor.
+
+`@appendix TITLE'
+ Begin an appendix. The title appears in the table of contents of
+ a printed manual. In Info, the title is underlined with
+ asterisks. *Note The `@unnumbered' and `@appendix' Commands:
+ unnumbered & appendix.
+
+`@appendixsec TITLE'
+`@appendixsection TITLE'
+ Begin an appendix section within an appendix. The section title
+ appears in the table of contents of a printed manual. In Info,
+ the title is underlined with equal signs. `@appendixsection' is a
+ longer spelling of the `@appendixsec' command. *Note Section
+ Commands: unnumberedsec appendixsec heading.
+
+`@appendixsubsec TITLE'
+ Begin an appendix subsection within an appendix. The title appears
+ in the table of contents of a printed manual. In Info, the title
+ is underlined with hyphens. *Note Subsection Commands:
+ unnumberedsubsec appendixsubsec subheading.
+
+`@appendixsubsubsec TITLE'
+ Begin an appendix subsubsection within an appendix subsection. The
+ title appears in the table of contents of a printed manual. In
+ Info, the title is underlined with periods. *Note The `subsub'
+ Commands: subsubsection.
+
+`@asis'
+ Used following `@table', `@ftable', and `@vtable' to print the
+ table's first column without highlighting ("as is"). *Note Making
+ a Two-column Table: Two-column Tables.
+
+`@author AUTHOR'
+ Typeset AUTHOR flushleft and underline it. *Note The `@title' and
+ `@author' Commands: title subtitle author.
+
+`@b{TEXT}'
+ Print TEXT in bold font. No effect in Info. *Note Fonts::.
+
+`@bullet{}'
+ Generate a large round dot, or the closest possible thing to one.
+ *Note `@bullet': bullet.
+
+`@bye'
+ Stop formatting a file. The formatters do not see the contents of
+ a file following an `@bye' command. *Note Ending a File::.
+
+`@c COMMENT'
+ Begin a comment in Texinfo. The rest of the line does not appear
+ in either the Info file or the printed manual. A synonym for
+ `@comment'. *Note Comments: Comments.
+
+`@cartouche'
+ Highlight an example or quotation by drawing a box with rounded
+ corners around it. Pair with `@end cartouche'. No effect in
+ Info. *Note Drawing Cartouches Around Examples: cartouche.)
+
+`@center LINE-OF-TEXT'
+ Center the line of text following the command. *Note `@center':
+ titlefont center sp.
+
+`@centerchap LINE-OF-TEXT'
+ Like `@chapter', but centers the chapter title. *Note `@chapter':
+ chapter.
+
+`@chapheading TITLE'
+ Print a chapter-like heading in the text, but not in the table of
+ contents of a printed manual. In Info, the title is underlined
+ with asterisks. *Note `@majorheading' and `@chapheading':
+ majorheading & chapheading.
+
+`@chapter TITLE'
+ Begin a chapter. The chapter title appears in the table of
+ contents of a printed manual. In Info, the title is underlined
+ with asterisks. *Note `@chapter': chapter.
+
+`@cindex ENTRY'
+ Add ENTRY to the index of concepts. *Note Defining the Entries of
+ an Index: Index Entries.
+
+`@cite{REFERENCE}'
+ Highlight the name of a book or other reference that lacks a
+ companion Info file. *Note `@cite': cite.
+
+`@clear FLAG'
+ Unset FLAG, preventing the Texinfo formatting commands from
+ formatting text between subsequent pairs of `@ifset FLAG' and
+ `@end ifset' commands, and preventing `@value{FLAG}' from
+ expanding to the value to which FLAG is set. *Note `@set'
+ `@clear' `@value': set clear value.
+
+`@code{SAMPLE-CODE}'
+ Highlight text that is an expression, a syntactically complete
+ token of a program, or a program name. *Note `@code': code.
+
+`@command{COMMAND-NAME}'
+ Indicate a command name, such as `ls'. *Note `@command': command.
+
+`@comment COMMENT'
+ Begin a comment in Texinfo. The rest of the line does not appear
+ in either the Info file or the printed manual. A synonym for `@c'.
+ *Note Comments::.
+
+`@contents'
+ Print a complete table of contents. Has no effect in Info, which
+ uses menus instead. *Note Generating a Table of Contents:
+ Contents.
+
+`@copyright{}'
+ Generate a copyright symbol. *Note `@copyright': copyright symbol.
+
+`@defcodeindex INDEX-NAME'
+ Define a new index and its indexing command. Print entries in an
+ `@code' font. *Note Defining New Indices: New Indices.
+
+`@defcv CATEGORY CLASS NAME'
+`@defcvx CATEGORY CLASS NAME'
+ Format a description for a variable associated with a class in
+ object-oriented programming. Takes three arguments: the category
+ of thing being defined, the class to which it belongs, and its
+ name. *Note Definition Commands::, and *Note Def Cmds in Detail:
+ deffnx.
+
+`@deffn CATEGORY NAME ARGUMENTS...'
+`@deffnx CATEGORY NAME ARGUMENTS...'
+ Format a description for a function, interactive command, or
+ similar entity that may take arguments. `@deffn' takes as
+ arguments the category of entity being described, the name of this
+ particular entity, and its arguments, if any. *Note Definition
+ Commands::.
+
+`@defindex INDEX-NAME'
+ Define a new index and its indexing command. Print entries in a
+ roman font. *Note Defining New Indices: New Indices.
+
+`@definfoenclose NEWCMD, BEFORE, AFTER,'
+ Create new @-command NEWCMD for Info that marks text by enclosing
+ it in strings that precede and follow the text. *Note
+ definfoenclose::.
+
+`@defivar CLASS INSTANCE-VARIABLE-NAME'
+`@defivarx CLASS INSTANCE-VARIABLE-NAME'
+ This command formats a description for an instance variable in
+ object-oriented programming. The command is equivalent to `@defcv
+ {Instance Variable} ...'. *Note Definition Commands::, and *Note
+ Def Cmds in Detail: deffnx.
+
+`@defmac MACRONAME ARGUMENTS...'
+`@defmacx MACRONAME ARGUMENTS...'
+ Format a description for a macro. The command is equivalent to
+ `@deffn Macro ...'. *Note Definition Commands::, and *Note Def
+ Cmds in Detail: deffnx.
+
+`@defmethod CLASS METHOD-NAME ARGUMENTS...'
+`@defmethodx CLASS METHOD-NAME ARGUMENTS...'
+ Format a description for a method in object-oriented programming.
+ The command is equivalent to `@defop Method ...'. Takes as
+ arguments the name of the class of the method, the name of the
+ method, and its arguments, if any. *Note Definition Commands::,
+ and *Note Def Cmds in Detail: deffnx.
+
+`@defop CATEGORY CLASS NAME ARGUMENTS...'
+`@defopx CATEGORY CLASS NAME ARGUMENTS...'
+ Format a description for an operation in object-oriented
+ programming. `@defop' takes as arguments the overall name of the
+ category of operation, the name of the class of the operation, the
+ name of the operation, and its arguments, if any. *Note
+ Definition Commands::, and *Note Abstract Objects::.
+
+`@defopt OPTION-NAME'
+`@defoptx OPTION-NAME'
+ Format a description for a user option. The command is equivalent
+ to `@defvr {User Option} ...'. *Note Definition Commands::, and
+ *Note Def Cmds in Detail: deffnx.
+
+`@defspec SPECIAL-FORM-NAME ARGUMENTS...'
+`@defspecx SPECIAL-FORM-NAME ARGUMENTS...'
+ Format a description for a special form. The command is
+ equivalent to `@deffn {Special Form} ...'. *Note Definition
+ Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
+`@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...'
+ Format a description for a data type. `@deftp' takes as arguments
+ the category, the name of the type (which is a word like `int' or
+ `float'), and then the names of attributes of objects of that type.
+ *Note Definition Commands::, and *Note Data Types::.
+
+`@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
+`@deftypefnx CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
+ Format a description for a function or similar entity that may take
+ arguments and that is typed. `@deftypefn' takes as arguments the
+ classification of entity being described, the type, the name of the
+ entity, and its arguments, if any. *Note Definition Commands::,
+ and *Note Def Cmds in Detail: deffnx.
+
+`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
+`@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...'
+ Format a description for a function in a typed language. The
+ command is equivalent to `@deftypefn Function ...'. *Note
+ Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftypeivar CLASS DATA-TYPE VARIABLE-NAME'
+`@deftypeivarx CLASS DATA-TYPE VARIABLE-NAME'
+ Format a description for a typed instance variable in
+ object-oriented programming. *Note Definition Commands::, and
+ *Note Abstract Objects::.
+
+`@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
+`@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
+ Format a description for a typed method in object-oriented
+ programming. *Note Definition Commands::, and *Note Def Cmds in
+ Detail: deffnx.
+
+`@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
+`@deftypeopx CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
+ Format a description for a typed operation in object-oriented
+ programming. *Note Definition Commands::, and *Note Abstract
+ Objects::.
+
+`@deftypevar DATA-TYPE VARIABLE-NAME'
+`@deftypevarx DATA-TYPE VARIABLE-NAME'
+ Format a description for a variable in a typed language. The
+ command is equivalent to `@deftypevr Variable ...'. *Note
+ Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftypevr CLASSIFICATION DATA-TYPE NAME'
+`@deftypevrx CLASSIFICATION DATA-TYPE NAME'
+ Format a description for something like a variable in a typed
+ language--an entity that records a value. Takes as arguments the
+ classification of entity being described, the type, and the name
+ of the entity. *Note Definition Commands::, and *Note Def Cmds in
+ Detail: deffnx.
+
+`@defun FUNCTION-NAME ARGUMENTS...'
+`@defunx FUNCTION-NAME ARGUMENTS...'
+ Format a description for functions. The command is equivalent to
+ `@deffn Function ...'. *Note Definition Commands::, and *Note Def
+ Cmds in Detail: deffnx.
+
+`@defvar VARIABLE-NAME'
+`@defvarx VARIABLE-NAME'
+ Format a description for variables. The command is equivalent to
+ `@defvr Variable ...'. *Note Definition Commands::, and *Note Def
+ Cmds in Detail: deffnx.
+
+`@defvr CATEGORY NAME'
+`@defvrx CATEGORY NAME'
+ Format a description for any kind of variable. `@defvr' takes as
+ arguments the category of the entity and the name of the entity.
+ *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@detailmenu'
+ Avoid `makeinfo' confusion stemming from the detailed node listing
+ in a master menu. *Note Master Menu Parts::.
+
+`@dfn{TERM}'
+ Highlight the introductory or defining use of a term. *Note
+ `@dfn': dfn.
+
+`@dircategory DIRPART'
+ Specify a part of the Info directory menu where this file's entry
+ should go. *Note Installing Dir Entries::.
+
+`@direntry'
+ Begin the Info directory menu entry for this file. Pair with
+ `@end direntry'. *Note Installing Dir Entries::.
+
+`@display'
+ Begin a kind of example. Like `@example' (indent text, do not
+ fill), but do not select a new font. Pair with `@end display'.
+ *Note `@display': display.
+
+`@dmn{DIMENSION}'
+ Format a unit of measure, as in 12pt. Causes TeX to insert a thin
+ space before DIMENSION. No effect in Info. *Note `@dmn': dmn.
+
+`@documentencoding ENC'
+ Declare the input encoding as ENC. *Note `@documentencoding':
+ documentencoding.
+
+`@documentlanguage CC'
+ Declare the document language as the two-character ISO-639
+ abbreviation CC. *Note `@documentlanguage': documentlanguage.
+
+`@dotaccent{C}'
+ Generate a dot accent over the character C, as in o.. *Note
+ Inserting Accents::.
+
+`@dots{}'
+ Insert an ellipsis: `...'. *Note `@dots': dots.
+
+`@email{ADDRESS[, DISPLAYED-TEXT]}'
+ Indicate an electronic mail address. *Note `@email': email.
+
+`@emph{TEXT}'
+ Highlight TEXT; text is displayed in _italics_ in printed output,
+ and surrounded by asterisks in Info. *Note Emphasizing Text:
+ Emphasis.
+
+`@end ENVIRONMENT'
+ Ends ENVIRONMENT, as in `@end example'. *Note @-commands:
+ Formatting Commands.
+
+`@env{ENVIRONMENT-VARIABLE}'
+ Indicate an environment variable name, such as `PATH'. *Note
+ `@env': env.
+
+`@enddots{}'
+ Generate an end-of-sentence of ellipsis, like this .... *Note
+ `@dots{}': dots.
+
+`@enumerate [NUMBER-OR-LETTER]'
+ Begin a numbered list, using `@item' for each entry. Optionally,
+ start list with NUMBER-OR-LETTER. Pair with `@end enumerate'.
+ *Note `@enumerate': enumerate.
+
+`@equiv{}'
+ Indicate to the reader the exact equivalence of two forms with a
+ glyph: `=='. *Note Equivalence::.
+
+`@error{}'
+ Indicate to the reader with a glyph that the following text is an
+ error message: `error-->'. *Note Error Glyph::.
+
+`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
+ Specify page footings resp. headings for even-numbered (left-hand)
+ pages. Only allowed inside `@iftex'. *Note How to Make Your Own
+ Headings: Custom Headings.
+
+`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
+ Specify page footings resp. headings for every page. Not relevant
+ to Info. *Note How to Make Your Own Headings: Custom Headings.
+
+`@example'
+ Begin an example. Indent text, do not fill, and select
+ fixed-width font. Pair with `@end example'. *Note `@example':
+ example.
+
+`@exampleindent INDENT'
+ Indent example-like environments by INDENT number of spaces
+ (perhaps 0). *Note Paragraph Indenting: exampleindent.
+
+`@exclamdown{}'
+ Produce an upside-down exclamation point. *Note Inserting
+ Accents::.
+
+`@exdent LINE-OF-TEXT'
+ Remove any indentation a line might have. *Note Undoing the
+ Indentation of a Line: exdent.
+
+`@expansion{}'
+ Indicate the result of a macro expansion to the reader with a
+ special glyph: `==>'. *Note ==> Indicating an Expansion:
+ expansion.
+
+`@file{FILENAME}'
+ Highlight the name of a file, buffer, node, or directory. *Note
+ `@file': file.
+
+`@finalout'
+ Prevent TeX from printing large black warning rectangles beside
+ over-wide lines. *Note Overfull hboxes::.
+
+`@findex ENTRY'
+ Add ENTRY to the index of functions. *Note Defining the Entries
+ of an Index: Index Entries.
+
+`@flushleft'
+`@flushright'
+ Left justify every line but leave the right end ragged. Leave
+ font as is. Pair with `@end flushleft'. `@flushright' analogous.
+ *Note `@flushleft' and `@flushright': flushleft & flushright.
+
+`@footnote{TEXT-OF-FOOTNOTE}'
+ Enter a footnote. Footnote text is printed at the bottom of the
+ page by TeX; Info may format in either `End' node or `Separate'
+ node style. *Note Footnotes::.
+
+`@footnotestyle STYLE'
+ Specify an Info file's footnote style, either `end' for the end
+ node style or `separate' for the separate node style. *Note
+ Footnotes::.
+
+`@format'
+ Begin a kind of example. Like `@display', but do not narrow the
+ margins. Pair with `@end format'. *Note `@example': example.
+
+`@ftable FORMATTING-COMMAND'
+ Begin a two-column table, using `@item' for each entry.
+ Automatically enter each of the items in the first column into the
+ index of functions. Pair with `@end ftable'. The same as
+ `@table', except for indexing. *Note `@ftable' and `@vtable':
+ ftable vtable.
+
+`@group'
+ Hold text together that must appear on one printed page. Pair with
+ `@end group'. Not relevant to Info. *Note `@group': group.
+
+`@H{C}'
+ Generate the long Hungarian umlaut accent over C, as in o''.
+
+`@heading TITLE'
+ Print an unnumbered section-like heading in the text, but not in
+ the table of contents of a printed manual. In Info, the title is
+ underlined with equal signs. *Note Section Commands:
+ unnumberedsec appendixsec heading.
+
+`@headings ON-OFF-SINGLE-DOUBLE'
+ Turn page headings on or off, and/or specify single-sided or
+ double-sided page headings for printing. *Note The `@headings'
+ Command: headings on off.
+
+`@html'
+ Enter HTML completely. Pair with `@end html'. *Note Raw
+ Formatter Commands::.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Explicitly define hyphenation points. *Note `@-' and
+ `@hyphenation': - and hyphenation.
+
+`@i{TEXT}'
+ Print TEXT in italic font. No effect in Info. *Note Fonts::.
+
+`@ifclear FLAG'
+ If FLAG is cleared, the Texinfo formatting commands format text
+ between `@ifclear FLAG' and the following `@end ifclear' command.
+ *Note `@set' `@clear' `@value': set clear value.
+
+`@ifhtml'
+`@ifinfo'
+ Begin a stretch of text that will be ignored by TeX when it
+ typesets the printed manual. The text appears only in the HTML
+ resp. Info file. Pair with `@end ifhtml' resp. `@end ifinfo'.
+ *Note Conditionals::.
+
+`@ifnothtml'
+`@ifnotinfo'
+`@ifnottex'
+ Begin a stretch of text that will be ignored in one output format
+ but not the others. The text appears only in the format not
+ specified. Pair with `@end ifnothtml' resp. `@end ifnotinfo' resp.
+ `@end ifnotinfo'. *Note Conditionals::.
+
+`@ifset FLAG'
+ If FLAG is set, the Texinfo formatting commands format text
+ between `@ifset FLAG' and the following `@end ifset' command.
+ *Note `@set' `@clear' `@value': set clear value.
+
+`@iftex'
+ Begin a stretch of text that will not appear in the Info file, but
+ will be processed only by TeX. Pair with `@end iftex'. *Note
+ Conditionally Visible Text: Conditionals.
+
+`@ignore'
+ Begin a stretch of text that will not appear in either the Info
+ file or the printed output. Pair with `@end ignore'. *Note
+ Comments and Ignored Text: Comments.
+
+`@image{FILENAME, [WIDTH], [HEIGHT]}'
+ Include graphics image in external FILENAME scaled to the given
+ WIDTH and/or HEIGHT. *Note Images::.
+
+`@include FILENAME'
+ Incorporate the contents of the file FILENAME into the Info file
+ or printed document. *Note Include Files::.
+
+`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
+ Make a cross reference to an Info file for which there is no
+ printed manual. *Note Cross references using `@inforef': inforef.
+
+`\input MACRO-DEFINITIONS-FILE'
+ Use the specified macro definitions file. This command is used
+ only in the first line of a Texinfo file to cause TeX to make use
+ of the `texinfo' macro definitions file. The backslash in `\input'
+ is used instead of an `@' because TeX does not recognize `@' until
+ after it has read the definitions file. *Note The Texinfo File
+ Header: Header.
+
+`@item'
+ Indicate the beginning of a marked paragraph for `@itemize' and
+ `@enumerate'; indicate the beginning of the text of a first column
+ entry for `@table', `@ftable', and `@vtable'. *Note Lists and
+ Tables::.
+
+`@itemize MARK-GENERATING-CHARACTER-OR-COMMAND'
+ Produce a sequence of indented paragraphs, with a mark inside the
+ left margin at the beginning of each paragraph. Pair with `@end
+ itemize'. *Note `@itemize': itemize.
+
+`@itemx'
+ Like `@item' but do not generate extra vertical space above the
+ item text. *Note `@itemx': itemx.
+
+`@kbd{KEYBOARD-CHARACTERS}'
+ Indicate text that is characters of input to be typed by users.
+ *Note `@kbd': kbd.
+
+`@kbdinputstyle STYLE'
+ Specify when `@kbd' should use a font distinct from `@code'.
+ *Note `@kbd': kbd.
+
+`@key{KEY-NAME}'
+ Indicate a name for a key on a keyboard. *Note `@key': key.
+
+`@kindex ENTRY'
+ Add ENTRY to the index of keys. *Note Defining the Entries of an
+ Index: Index Entries.
+
+`@L{}'
+`@l{}'
+ Generate the uppercase and lowercase Polish suppressed-L letters,
+ respectively: /L, /l.
+
+`@lisp'
+ Begin an example of Lisp code. Indent text, do not fill, and
+ select fixed-width font. Pair with `@end lisp'. *Note `@lisp':
+ lisp.
+
+`@lowersections'
+ Change subsequent chapters to sections, sections to subsections,
+ and so on. *Note `@raisesections' and `@lowersections':
+ Raise/lower sections.
+
+`@macro MACRONAME {PARAMS}'
+ Define a new Texinfo command `@MACRONAME{PARAMS}'. Only supported
+ by `makeinfo' and `texi2dvi'. *Note Defining Macros::.
+
+`@majorheading TITLE'
+ Print a chapter-like heading in the text, but not in the table of
+ contents of a printed manual. Generate more vertical whitespace
+ before the heading than the `@chapheading' command. In Info, the
+ chapter heading line is underlined with asterisks. *Note
+ `@majorheading' and `@chapheading': majorheading & chapheading.
+
+`@math{MATHEMATICAL-EXPRESSION}'
+ Format a mathematical expression. *Note `@math': Inserting
+ Mathematical Expressions: math.
+
+`@menu'
+ Mark the beginning of a menu of nodes in Info. No effect in a
+ printed manual. Pair with `@end menu'. *Note Menus::.
+
+`@minus{}'
+ Generate a minus sign, `-'. *Note `@minus': minus.
+
+`@multitable COLUMN-WIDTH-SPEC'
+ Begin a multi-column table. Pair with `@end multitable'. *Note
+ Multitable Column Widths::.
+
+`@need N'
+ Start a new page in a printed manual if fewer than N mils
+ (thousandths of an inch) remain on the current page. *Note
+ `@need': need.
+
+`@node NAME, NEXT, PREVIOUS, UP'
+ Define the beginning of a new node in Info, and serve as a locator
+ for references for TeX. *Note `@node': node.
+
+`@noindent'
+ Prevent text from being indented as if it were a new paragraph.
+ *Note `@noindent': noindent.
+
+`@novalidate'
+ Suppress validation of node references, omit creation of auxiliary
+ files with TeX. Use before `@setfilename'. *Note Pointer
+ Validation::.
+
+`@O{}'
+`@o{}'
+ Generate the uppercase and lowercase O-with-slash letters,
+ respectively: /O, /o.
+
+`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
+ Specify page footings resp. headings for odd-numbered (right-hand)
+ pages. Only allowed inside `@iftex'. *Note How to Make Your Own
+ Headings: Custom Headings.
+
+`@OE{}'
+`@oe{}'
+ Generate the uppercase and lowercase OE ligatures, respectively:
+ OE, oe. *Note Inserting Accents::.
+
+`@option{OPTION-NAME}'
+ Indicate a command-line option, such as `-l' or `--help'. *Note
+ `@option': option.
+
+`@page'
+ Start a new page in a printed manual. No effect in Info. *Note
+ `@page': page.
+
+`@pagesizes [WIDTH][, HEIGHT]'
+ Change page dimensions. *Note pagesizes::.
+
+`@paragraphindent INDENT'
+ Indent paragraphs by INDENT number of spaces (perhaps 0); preserve
+ source file indentation if INDENT is `asis'. *Note Paragraph
+ Indenting: paragraphindent.
+
+`@pindex ENTRY'
+ Add ENTRY to the index of programs. *Note Defining the Entries of
+ an Index: Index Entries.
+
+`@point{}'
+ Indicate the position of point in a buffer to the reader with a
+ glyph: `-!-'. *Note Indicating Point in a Buffer: Point Glyph.
+
+`@pounds{}'
+ Generate the pounds sterling currency sign. *Note `@pounds{}':
+ pounds.
+
+`@print{}'
+ Indicate printed output to the reader with a glyph: `-|'. *Note
+ Print Glyph::.
+
+`@printindex INDEX-NAME'
+ Print an alphabetized two-column index in a printed manual or
+ generate an alphabetized menu of index entries for Info. *Note
+ Printing Indices & Menus::.
+
+`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+ Make a reference that starts with a lower case `see' in a printed
+ manual. Use within parentheses only. Do not follow command with a
+ punctuation mark--the Info formatting commands automatically insert
+ terminating punctuation as needed. Only the first argument is
+ mandatory. *Note `@pxref': pxref.
+
+`@questiondown{}'
+ Generate an upside-down question mark. *Note Inserting Accents::.
+
+`@quotation'
+ Narrow the margins to indicate text that is quoted from another
+ real or imaginary work. Write command on a line of its own. Pair
+ with `@end quotation'. *Note `@quotation': quotation.
+
+`@r{TEXT}'
+ Print TEXT in roman font. No effect in Info. *Note Fonts::.
+
+`@raisesections'
+ Change subsequent sections to chapters, subsections to sections,
+ and so on. *Note `@raisesections' and `@lowersections':
+ Raise/lower sections.
+
+`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+ Make a reference. In a printed manual, the reference does not
+ start with a `See'. Follow command with a punctuation mark. Only
+ the first argument is mandatory. *Note `@ref': ref.
+
+`@refill'
+ In Info, refill and indent the paragraph after all the other
+ processing has been done. No effect on TeX, which always refills.
+ This command is no longer needed, since all formatters now
+ automatically refill. *Note Refilling Paragraphs::.
+
+`@result{}'
+ Indicate the result of an expression to the reader with a special
+ glyph: `=>'. *Note `@result': result.
+
+`@ringaccent{C}'
+ Generate a ring accent over the next character, as in o*. *Note
+ Inserting Accents::.
+
+`@samp{TEXT}'
+ Highlight TEXT that is a literal example of a sequence of
+ characters. Used for single characters, for statements, and often
+ for entire shell commands. *Note `@samp': samp.
+
+`@sc{TEXT}'
+ Set TEXT in a printed output in THE SMALL CAPS FONT and set text
+ in the Info file in uppercase letters. *Note Smallcaps::.
+
+`@section TITLE'
+ Begin a section within a chapter. In a printed manual, the section
+ title is numbered and appears in the table of contents. In Info,
+ the title is underlined with equal signs. *Note `@section':
+ section.
+
+`@set FLAG [STRING]'
+ Make FLAG active, causing the Texinfo formatting commands to
+ format text between subsequent pairs of `@ifset FLAG' and `@end
+ ifset' commands. Optionally, set value of FLAG to STRING. *Note
+ `@set' `@clear' `@value': set clear value.
+
+`@setchapternewpage ON-OFF-ODD'
+ Specify whether chapters start on new pages, and if so, whether on
+ odd-numbered (right-hand) new pages. *Note `@setchapternewpage':
+ setchapternewpage.
+
+`@setcontentsaftertitlepage'
+ Put the table of contents after the `@end titlepage' even if the
+ `@contents' command is not there. *Note Contents::.
+
+`@setfilename INFO-FILE-NAME'
+ Provide a name to be used by the Info file. This command is
+ essential for TeX formatting as well, even though it produces no
+ output. *Note `@setfilename': setfilename.
+
+`@setshortcontentsaftertitlepage'
+ Place the short table of contents after the `@end titlepage'
+ command even if the `@shortcontents' command is not there. *Note
+ Contents::.
+
+`@settitle TITLE'
+ Provide a title for page headers in a printed manual. *Note
+ `@settitle': settitle.
+
+`@shortcontents'
+ Print a short table of contents. Not relevant to Info, which uses
+ menus rather than tables of contents. A synonym for
+ `@summarycontents'. *Note Generating a Table of Contents:
+ Contents.
+
+`@shorttitlepage TITLE'
+ Generate a minimal title page. *Note `@titlepage': titlepage.
+
+`@smallbook'
+ Cause TeX to produce a printed manual in a 7 by 9.25 inch format
+ rather than the regular 8.5 by 11 inch format. *Note Printing
+ Small Books: smallbook. Also, see *Note small::.
+
+`@smalldisplay'
+ Begin a kind of example. Like `@smallexample' (indent text, no
+ filling), but do not select the fixed-width font. In `@smallbook'
+ format, print text in a smaller font than with `@display'. Pair
+ with `@end smalldisplay'. *Note small::.
+
+`@smallexample'
+ Indent text to indicate an example. Do not fill, select
+ fixed-width font. In `@smallbook' format, print text in a smaller
+ font than with `@example'. Pair with `@end smallexample'. *Note
+ small::.
+
+`@smallformat'
+ Begin a kind of example. Like `@smalldisplay', but do not narrow
+ the margins and do not select the fixed-width font. In
+ `@smallbook' format, print text in a smaller font than with
+ `@format'. Pair with `@end smallformat'. *Note small::.
+
+`@smalllisp'
+ Begin an example of Lisp code. Indent text, do not fill, select
+ fixed-width font. In `@smallbook' format, print text in a smaller
+ font. Pair with `@end smalllisp'. *Note small::.
+
+`@sp N'
+ Skip N blank lines. *Note `@sp': sp.
+
+`@ss{}'
+ Generate the German sharp-S es-zet letter, ss. *Note Inserting
+ Accents::.
+
+`@strong {TEXT}'
+ Emphasize TEXT by typesetting it in a *bold* font for the printed
+ manual and by surrounding it with asterisks for Info. *Note
+ Emphasizing Text: emph & strong.
+
+`@subheading TITLE'
+ Print an unnumbered subsection-like heading in the text, but not in
+ the table of contents of a printed manual. In Info, the title is
+ underlined with hyphens. *Note `@unnumberedsubsec'
+ `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
+ subheading.
+
+`@subsection TITLE'
+ Begin a subsection within a section. In a printed manual, the
+ subsection title is numbered and appears in the table of contents.
+ In Info, the title is underlined with hyphens. *Note
+ `@subsection': subsection.
+
+`@subsubheading TITLE'
+ Print an unnumbered subsubsection-like heading in the text, but
+ not in the table of contents of a printed manual. In Info, the
+ title is underlined with periods. *Note The `subsub' Commands:
+ subsubsection.
+
+`@subsubsection TITLE'
+ Begin a subsubsection within a subsection. In a printed manual,
+ the subsubsection title is numbered and appears in the table of
+ contents. In Info, the title is underlined with periods. *Note
+ The `subsub' Commands: subsubsection.
+
+`@subtitle TITLE'
+ In a printed manual, set a subtitle in a normal sized font flush to
+ the right-hand side of the page. Not relevant to Info, which does
+ not have title pages. *Note `@title' `@subtitle' and `@author'
+ Commands: title subtitle author.
+
+`@summarycontents'
+ Print a short table of contents. Not relevant to Info, which uses
+ menus rather than tables of contents. A synonym for
+ `@shortcontents'. *Note Generating a Table of Contents: Contents.
+
+`@syncodeindex FROM-INDEX INTO-INDEX'
+ Merge the index named in the first argument into the index named in
+ the second argument, printing the entries from the first index in
+ `@code' font. *Note Combining Indices::.
+
+`@synindex FROM-INDEX INTO-INDEX'
+ Merge the index named in the first argument into the index named in
+ the second argument. Do not change the font of FROM-INDEX
+ entries. *Note Combining Indices::.
+
+`@t{TEXT}'
+ Print TEXT in a fixed-width, typewriter-like font. No effect in
+ Info. *Note Fonts::.
+
+`@tab'
+ Separate columns in a multitable. *Note Multitable Rows::.
+
+`@table FORMATTING-COMMAND'
+ Begin a two-column table, using `@item' for each entry. Write
+ each first column entry on the same line as `@item'. First column
+ entries are printed in the font resulting from FORMATTING-COMMAND.
+ Pair with `@end table'. *Note Making a Two-column Table:
+ Two-column Tables. Also see *Note `@ftable' and `@vtable': ftable
+ vtable, and *Note `@itemx': itemx.
+
+`@TeX{}'
+ Insert the logo TeX. *Note Inserting TeX and (C): TeX and
+ copyright.
+
+`@tex'
+ Enter TeX completely. Pair with `@end tex'. *Note Raw Formatter
+ Commands::.
`@thischapter'
- Expands to the number and name of the current chapter, in the
- format `Chapter 1: Title'.
-
-`@thistitle'
- Expands to the name of the document, as specified by the
- `@settitle' command.
-
+`@thischaptername'
`@thisfile'
- For `@include' files only: expands to the name of the current
- `@include' file. If the current Texinfo source file is not an
- `@include' file, this command has no effect. This command does
- *not* provide the name of the current Texinfo source file unless
- it is an `@include' file. (*Note Include Files::, for more
- information about `@include' files.)
-
-You can also use the `@today{}' command, which expands to the current
-date, in `1 Jan 1900' format.
-
- Other @-commands and text are printed in a header or footer just as
-if they were in the body of a page. It is useful to incorporate text,
-particularly when you are writing drafts:
-
- @iftex
- @headings off
- @everyheading @emph{Draft!} @| @thispage @| @thischapter
- @everyfooting @| @| Version: 0.27: @today{}
- @end iftex
-
- Beware of overlong titles: they may overlap another part of the
-header or footer and blot it out.
-
-\1f
-File: texinfo.info, Node: Catching Mistakes, Next: Refilling Paragraphs, Prev: Headings, Up: Top
-
-Formatting Mistakes
-*******************
-
- Besides mistakes in the content of your documentation, there are two
-kinds of mistake you can make with Texinfo: you can make mistakes with
-@-commands, and you can make mistakes with the structure of the nodes
-and chapters.
-
- Emacs has two tools for catching the @-command mistakes and two for
-catching structuring mistakes.
-
- For finding problems with @-commands, you can run TeX or a region
-formatting command on the region that has a problem; indeed, you can
-run these commands on each region as you write it.
-
- For finding problems with the structure of nodes and chapters, you
-can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
-command and you can use the `M-x Info-validate' command.
-
-* Menu:
-
-* makeinfo Preferred:: `makeinfo' finds errors.
-* Debugging with Info:: How to catch errors with Info formatting.
-* Debugging with TeX:: How to catch errors with TeX formatting.
-* Using texinfo-show-structure:: How to use `texinfo-show-structure'.
-* Using occur:: How to list all lines containing a pattern.
-* Running Info-Validate:: How to find badly referenced nodes.
-
-\1f
-File: texinfo.info, Node: makeinfo Preferred, Next: Debugging with Info, Prev: Catching Mistakes, Up: Catching Mistakes
-
-`makeinfo' Find Errors
-======================
-
- The `makeinfo' program does an excellent job of catching errors and
-reporting them--far better than `texinfo-format-region' or
-`texinfo-format-buffer'. In addition, the various functions for
-automatically creating and updating node pointers and menus remove many
-opportunities for human error.
-
- If you can, use the updating commands to create and insert pointers
-and menus. These prevent many errors. Then use `makeinfo' (or its
-Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
-to format your file and check for other errors. This is the best way
-to work with Texinfo. But if you cannot use `makeinfo', or your
-problem is very puzzling, then you may want to use the tools described
-in this appendix.
-
-\1f
-File: texinfo.info, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo Preferred, Up: Catching Mistakes
-
-Catching Errors with Info Formatting
-====================================
-
- After you have written part of a Texinfo file, you can use the
-`texinfo-format-region' or the `makeinfo-region' command to see whether
-the region formats properly.
-
- Most likely, however, you are reading this section because for some
-reason you cannot use the `makeinfo-region' command; therefore, the
-rest of this section presumes that you are using
-`texinfo-format-region'.
-
- If you have made a mistake with an @-command, `texinfo-format-region'
-will stop processing at or after the error and display an error
-message. To see where in the buffer the error occurred, switch to the
-`*Info Region*' buffer; the cursor will be in a position that is after
-the location of the error. Also, the text will not be formatted after
-the place where the error occurred (or more precisely, where it was
-detected).
-
- For example, if you accidentally end a menu with the command `@end
-menus' with an `s' on the end, instead of with `@end menu', you will
-see an error message that says:
-
- @end menus is not handled by texinfo
-
-The cursor will stop at the point in the buffer where the error occurs,
-or not long after it. The buffer will look like this:
-
- ---------- Buffer: *Info Region* ----------
- * Menu:
-
- * Using texinfo-show-structure:: How to use
- `texinfo-show-structure'
- to catch mistakes.
- * Running Info-Validate:: How to check for
- unreferenced nodes.
- @end menus
- -!-
- ---------- Buffer: *Info Region* ----------
-
- The `texinfo-format-region' command sometimes provides slightly odd
-error messages. For example, the following cross reference fails to
-format:
-
- (@xref{Catching Mistakes, for more info.)
-
-In this case, `texinfo-format-region' detects the missing closing brace
-but displays a message that says `Unbalanced parentheses' rather than
-`Unbalanced braces'. This is because the formatting command looks for
-mismatches between braces as if they were parentheses.
-
- Sometimes `texinfo-format-region' fails to detect mistakes. For
-example, in the following, the closing brace is swapped with the
-closing parenthesis:
-
- (@xref{Catching Mistakes), for more info.}
-
-Formatting produces:
- (*Note for more info.: Catching Mistakes)
-
- The only way for you to detect this error is to realize that the
-reference should have looked like this:
-
- (*Note Catching Mistakes::, for more info.)
-
- Incidentally, if you are reading this node in Info and type `f <RET>'
-(`Info-follow-reference'), you will generate an error message that says:
-
- No such node: "Catching Mistakes) The only way ...
-
-This is because Info perceives the example of the error as the first
-cross reference in this node and if you type a <RET> immediately after
-typing the Info `f' command, Info will attempt to go to the referenced
-node. If you type `f catch <TAB> <RET>', Info will complete the node
-name of the correctly written example and take you to the `Catching
-Mistakes' node. (If you try this, you can return from the `Catching
-Mistakes' node by typing `l' (`Info-last').)
+`@thispage'
+`@thistitle'
+ Only allowed in a heading or footing. Stands for the number and
+ name of the current chapter (in the format `Chapter 1: Title'),
+ the chapter name only, the filename, the current page number, and
+ the title of the document, respectively. *Note How to Make Your
+ Own Headings: Custom Headings.
+
+`@tieaccent{CC}'
+ Generate a tie-after accent over the next two characters CC, as in
+ `oo['. *Note Inserting Accents::.
+
+`@tindex ENTRY'
+ Add ENTRY to the index of data types. *Note Defining the Entries
+ of an Index: Index Entries.
+
+`@title TITLE'
+ In a printed manual, set a title flush to the left-hand side of the
+ page in a larger than normal font and underline it with a black
+ rule. Not relevant to Info, which does not have title pages.
+ *Note The `@title' `@subtitle' and `@author' Commands: title
+ subtitle author.
+
+`@titlefont{TEXT}'
+ In a printed manual, print TEXT in a larger than normal font. Not
+ relevant to Info, which does not have title pages. *Note The
+ `@titlefont' `@center' and `@sp' Commands: titlefont center sp.
+
+`@titlepage'
+ Indicate to Texinfo the beginning of the title page. Write
+ command on a line of its own. Pair with `@end titlepage'.
+ Nothing between `@titlepage' and `@end titlepage' appears in Info.
+ *Note `@titlepage': titlepage.
+
+`@today{}'
+ Insert the current date, in `1 Jan 1900' style. *Note How to Make
+ Your Own Headings: Custom Headings.
+
+`@top TITLE'
+ In a Texinfo file to be formatted with `makeinfo', identify the
+ topmost `@node' line in the file, which must be written on the line
+ immediately preceding the `@top' command. Used for `makeinfo''s
+ node pointer insertion feature. The title is underlined with
+ asterisks. Both the `@node' line and the `@top' line normally
+ should be enclosed by `@ifinfo' and `@end ifinfo'. In TeX and
+ `texinfo-format-buffer', the `@top' command is merely a synonym
+ for `@unnumbered'. *Note Creating Pointers with `makeinfo':
+ makeinfo Pointer Creation.
+
+`@u{C}'
+`@ubaraccent{C}'
+`@udotaccent{C}'
+ Generate a breve, underbar, or underdot accent, respectively, over
+ or under the character C, as in o(, o_, .o. *Note Inserting
+ Accents::.
+
+`@unnumbered TITLE'
+ In a printed manual, begin a chapter that appears without chapter
+ numbers of any kind. The title appears in the table of contents
+ of a printed manual. In Info, the title is underlined with
+ asterisks. *Note `@unnumbered' and `@appendix': unnumbered &
+ appendix.
+
+`@unnumberedsec TITLE'
+ In a printed manual, begin a section that appears without section
+ numbers of any kind. The title appears in the table of contents
+ of a printed manual. In Info, the title is underlined with equal
+ signs. *Note Section Commands: unnumberedsec appendixsec heading.
+
+`@unnumberedsubsec TITLE'
+ In a printed manual, begin an unnumbered subsection within a
+ chapter. The title appears in the table of contents of a printed
+ manual. In Info, the title is underlined with hyphens. *Note
+ `@unnumberedsubsec' `@appendixsubsec' `@subheading':
+ unnumberedsubsec appendixsubsec subheading.
+
+`@unnumberedsubsubsec TITLE'
+ In a printed manual, begin an unnumbered subsubsection within a
+ chapter. The title appears in the table of contents of a printed
+ manual. In Info, the title is underlined with periods. *Note The
+ `subsub' Commands: subsubsection.
+
+`@uref{URL[, DISPLAYED-TEXT][, REPLACEMENT}'
+ Define a cross reference to an external uniform resource locator
+ for the World Wide Web. *Note `@uref': uref.
+
+`@url{URL}'
+ Indicate text that is a uniform resource locator for the World Wide
+ Web. *Note `@url': url.
+
+`@v{C}'
+ Generate check accent over the character C, as in o<. *Note
+ Inserting Accents::.
+
+`@value{FLAG}'
+ Replace FLAG with the value to which it is set by `@set FLAG'.
+ *Note `@set' `@clear' `@value': set clear value.
+
+`@var{METASYNTACTIC-VARIABLE}'
+ Highlight a metasyntactic variable, which is something that stands
+ for another piece of text. *Note Indicating Metasyntactic
+ Variables: var.
+
+`@vindex ENTRY'
+ Add ENTRY to the index of variables. *Note Defining the Entries
+ of an Index: Index Entries.
+
+`@vskip AMOUNT'
+ In a printed manual, insert whitespace so as to push text on the
+ remainder of the page towards the bottom of the page. Used in
+ formatting the copyright page with the argument `0pt plus 1filll'.
+ (Note spelling of `filll'.) `@vskip' may be used only in
+ contexts ignored for Info. *Note The Copyright Page and Printed
+ Permissions: Copyright & Permissions.
+
+`@vtable FORMATTING-COMMAND'
+ Begin a two-column table, using `@item' for each entry.
+ Automatically enter each of the items in the first column into the
+ index of variables. Pair with `@end vtable'. The same as
+ `@table', except for indexing. *Note `@ftable' and `@vtable':
+ ftable vtable.
+
+`@w{TEXT}'
+ Prevent TEXT from being split across two lines. Do not end a
+ paragraph that uses `@w' with an `@refill' command. *Note `@w': w.
+
+`@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+ Make a reference that starts with `See' in a printed manual.
+ Follow command with a punctuation mark. Only the first argument is
+ mandatory. *Note `@xref': xref.
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
-File: texinfo.info, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes
+File: texinfo.info, Node: Tips, Next: Sample Texinfo File, Prev: Command List, Up: Top
-Catching Errors with TeX Formatting
-===================================
+Tips and Hints
+**************
- You can also catch mistakes when you format a file with TeX.
+ Here are some tips for writing Texinfo documentation:
- Usually, you will want to do this after you have run
-`texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same
-file, because `texinfo-format-buffer' sometimes displays error messages
-that make more sense than TeX. (*Note Debugging with Info::, for more
-information.)
+ * Write in the present tense, not in the past or the future.
- For example, TeX was run on a Texinfo file, part of which is shown
-here:
+ * Write actively! For example, write "We recommend that ..." rather
+ than "It is recommended that ...".
- ---------- Buffer: texinfo.texi ----------
- name of the Texinfo file as an extension. The
- @samp{??} are `wildcards' that cause the shell to
- substitute all the raw index files. (@xref{sorting
- indices, for more information about sorting
- indices.)@refill
- ---------- Buffer: texinfo.texi ----------
+ * Use 70 or 72 as your fill column. Longer lines are hard to read.
-(The cross reference lacks a closing brace.) TeX produced the
-following output, after which it stopped:
+ * Include a copyright notice and copying permissions.
- ---------- Buffer: *tex-shell* ----------
- Runaway argument?
- {sorting indices, for more information about sorting
- indices.) @refill @ETC.
- ! Paragraph ended before @xref was complete.
- <to be read again>
- @par
- l.27
+Index, Index, Index!
+....................
+
+ Write many index entries, in different ways. Readers like indices;
+they are helpful and convenient.
+
+ Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards. In either
+case, write an entry before the paragraph to which it applies. This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+ Here are more hints we have found valuable:
+
+ * Write each index entry differently, so each entry refers to a
+ different place in the document.
+
+ * Write index entries only where a topic is discussed significantly.
+ For example, it is not useful to index "debugging information" in
+ a chapter on reporting bugs. Someone who wants to know about
+ debugging information will certainly not find it in that chapter.
+
+ * Consistently capitalize the first word of every concept index
+ entry, or else consistently use lower case. Terse entries often
+ call for lower case; longer entries for capitalization. Whichever
+ case convention you use, please use one or the other consistently!
+ Mixing the two styles looks bad.
+
+ * Always capitalize or use upper case for those words in an index for
+ which this is proper, such as names of countries or acronyms.
+ Always use the appropriate case for case-sensitive names, such as
+ those in C or Lisp.
+
+ * Write the indexing commands that refer to a whole section
+ immediately after the section command, and write the indexing
+ commands that refer to a paragraph before that paragraph.
+
+ In the example that follows, a blank line comes after the index
+ entry for "Leaping":
+
+ @section The Dog and the Fox
+ @cindex Jumping, in general
+ @cindex Leaping
+
+ @cindex Dog, lazy, jumped over
+ @cindex Lazy dog jumped over
+ @cindex Fox, jumps over dog
+ @cindex Quick fox jumps over dog
+ The quick brown fox jumps over the lazy dog.
+
+ (Note that the example shows entries for the same concept that are
+ written in different ways--`Lazy dog', and `Dog, lazy'--so readers
+ can look up the concept in different ways.)
+
+Blank Lines
+...........
+
+ * Insert a blank line between a sectioning command and the first
+ following sentence or paragraph, or between the indexing commands
+ associated with the sectioning command and the first following
+ sentence or paragraph, as shown in the tip on indexing.
+ Otherwise, a formatter may fold title and paragraph together.
+
+ * Always insert a blank line before an `@table' command and after an
+ `@end table' command; but never insert a blank line after an
+ `@table' command or before an `@end table' command.
+
+ For example,
+
+ Types of fox:
+
+ @table @samp
+ @item Quick
+ Jump over lazy dogs.
+
+ @item Brown
+ Also jump over lazy dogs.
+ @end table
+ @noindent
+ On the other hand, ...
+
+ Insert blank lines before and after `@itemize' ... `@end itemize'
+ and `@enumerate' ... `@end enumerate' in the same way.
+
+Complete Phrases
+................
+
+ Complete phrases are easier to read than ...
+
+ * Write entries in an itemized list as complete sentences; or at
+ least, as complete phrases. Incomplete expressions ... awkward
+ ... like this.
+
+ * Write the prefatory sentence or phrase for a multi-item list or
+ table as a complete expression. Do not write "You can set:";
+ instead, write "You can set these variables:". The former
+ expression sounds cut off.
+
+Editions, Dates and Versions
+............................
+
+ Write the edition and version numbers and date in three places in
+every manual:
+
+ 1. In the first `@ifinfo' section, for people reading the Texinfo
+ file.
+
+ 2. In the `@titlepage' section, for people reading the printed manual.
+
+ 3. In the `Top' node, for people reading the Info file.
+
+Also, it helps to write a note before the first `@ifinfo' section to
+explain what you are doing.
+
+For example:
+
+ @c ===> NOTE! <==
+ @c Specify the edition and version numbers and date
+ @c in *three* places:
+ @c 1. First ifinfo section 2. title page 3. top node
+ @c To find the locations, search for !!set
- ?
- ---------- Buffer: *tex-shell* ----------
+ @ifinfo
+ @c !!set edition, date, version
+ This is Edition 4.03, January 1992,
+ of the @cite{GDB Manual} for GDB Version 4.3.
+ ...
- In this case, TeX produced an accurate and understandable error
-message:
+--or use `@set' and `@value' (*note `@value' Example: value Example.).
- Paragraph ended before @xref was complete.
+Definition Commands
+...................
-`@par' is an internal TeX command of no relevance to Texinfo. `l.27'
-means that TeX detected the problem on line 27 of the Texinfo file.
-The `?' is the prompt TeX uses in this circumstance.
+ Definition commands are `@deffn', `@defun', `@defmac', and the like,
+and enable you to write descriptions in a uniform format.
- Unfortunately, TeX is not always so helpful, and sometimes you must
-truly be a Sherlock Holmes to discover what went wrong.
+ * Write just one definition command for each entity you define with a
+ definition command. The automatic indexing feature creates an
+ index entry that leads the reader to the definition.
- In any case, if you run into a problem like this, you can do one of
-three things.
+ * Use `@table' ... `@end table' in an appendix that contains a
+ summary of functions, not `@deffn' or other definition commands.
- 1. You can tell TeX to continue running and ignore just this error by
- typing <RET> at the `?' prompt.
+Capitalization
+..............
- 2. You can tell TeX to continue running and to ignore all errors as
- best it can by typing `r <RET>' at the `?' prompt.
+ * Capitalize "Texinfo"; it is a name. Do not write the `x' or `i'
+ in upper case.
- This is often the best thing to do. However, beware: the one error
- may produce a cascade of additional error messages as its
- consequences are felt through the rest of the file. To stop TeX
- when it is producing such an avalanche of error messages, type
- `C-c' (or `C-c C-c', if you are running a shell inside Emacs).
+ * Capitalize "Info"; it is a name.
- 3. You can tell TeX to stop this run by typing `x <RET>' at the `?'
- prompt.
+ * Write TeX using the `@TeX{}' command. Note the uppercase `T' and
+ `X'. This command causes the formatters to typeset the name
+ according to the wishes of Donald Knuth, who wrote TeX.
- Please note that if you are running TeX inside Emacs, you need to
-switch to the shell buffer and line at which TeX offers the `?' prompt.
+Spaces
+......
- Sometimes TeX will format a file without producing error messages even
-though there is a problem. This usually occurs if a command is not
-ended but TeX is able to continue processing anyhow. For example, if
-you fail to end an itemized list with the `@end itemize' command, TeX
-will write a DVI file that you can print out. The only error message
-that TeX will give you is the somewhat mysterious comment that
+ Do not use spaces to format a Texinfo file, except inside of
+`@example' ... `@end example' and similar commands.
- (@end occurred inside a group at level 1)
+ For example, TeX fills the following:
-However, if you print the DVI file, you will find that the text of the
-file that follows the itemized list is entirely indented as if it were
-part of the last item in the itemized list. The error message is the
-way TeX says that it expected to find an `@end' command somewhere in
-the file; but that it could not determine where it was needed.
+ @kbd{C-x v}
+ @kbd{M-x vc-next-action}
+ Perform the next logical operation
+ on the version-controlled file
+ corresponding to the current buffer.
- Another source of notoriously hard-to-find errors is a missing `@end
-group' command. If you ever are stumped by incomprehensible errors,
-look for a missing `@end group' command first.
+so it looks like this:
- If the Texinfo file lacks header lines, TeX may stop in the beginning
-of its run and display output that looks like the following. The `*'
-indicates that TeX is waiting for input.
+ `C-x v' `M-x vc-next-action' Perform the next logical operation on
+ the version-controlled file corresponding to the current buffer.
- This is TeX, Version 3.14159 (Web2c 7.0)
- (test.texinfo [1])
- *
+In this case, the text should be formatted with `@table', `@item', and
+`@itemx', to create a table.
-In this case, simply type `\end <RET>' after the asterisk. Then write
-the header lines in the Texinfo file and run the TeX command again.
-(Note the use of the backslash, `\'. TeX uses `\' instead of `@'; and
-in this circumstance, you are working directly with TeX, not with
-Texinfo.)
+@code, @samp, @var, and `---'
+.............................
-\1f
-File: texinfo.info, Node: Using texinfo-show-structure, Next: Using occur, Prev: Debugging with TeX, Up: Catching Mistakes
+ * Use `@code' around Lisp symbols, including command names. For
+ example,
-Using `texinfo-show-structure'
-==============================
+ The main function is @code{vc-next-action}, ...
- It is not always easy to keep track of the nodes, chapters, sections,
-and subsections of a Texinfo file. This is especially true if you are
-revising or adding to a Texinfo file that someone else has written.
-
- In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
-lists all the lines that begin with the @-commands that specify the
-structure: `@chapter', `@section', `@appendix', and so on. With an
-argument (`C-u' as prefix argument, if interactive), the command also
-shows the `@node' lines. The `texinfo-show-structure' command is bound
-to `C-c C-s' in Texinfo mode, by default.
-
- The lines are displayed in a buffer called the `*Occur*' buffer,
-indented by hierarchical level. For example, here is a part of what was
-produced by running `texinfo-show-structure' on this manual:
-
- Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
- unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
- in buffer texinfo.texi.
- ...
- 4177:@chapter Nodes
- 4198: @heading Two Paths
- 4231: @section Node and Menu Illustration
- 4337: @section The @code{@@node} Command
- 4393: @subheading Choosing Node and Pointer Names
- 4417: @subsection How to Write an @code{@@node} Line
- 4469: @subsection @code{@@node} Line Tips
- ...
-
- This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
-with the `@section', `@subheading', and `@subsection' commands
-respectively. If you move your cursor into the `*Occur*' window, you
-can position the cursor over one of the lines and use the `C-c C-c'
-command (`occur-mode-goto-occurrence'), to jump to the corresponding
-spot in the Texinfo file. *Note Using Occur: (xemacs)Other Repeating
-Search, for more information about `occur-mode-goto-occurrence'.
-
- The first line in the `*Occur*' window describes the "regular
-expression" specified by TEXINFO-HEADING-PATTERN. This regular
-expression is the pattern that `texinfo-show-structure' looks for.
-*Note Using Regular Expressions: (xemacs)Regexps, for more information.
-
- When you invoke the `texinfo-show-structure' command, Emacs will
-display the structure of the whole buffer. If you want to see the
-structure of just a part of the buffer, of one chapter, for example,
-use the `C-x n n' (`narrow-to-region') command to mark the region.
-(*Note Narrowing: (xemacs)Narrowing.) This is how the example used
-above was generated. (To see the whole buffer again, use `C-x n w'
-(`widen').)
-
- If you call `texinfo-show-structure' with a prefix argument by typing
-`C-u C-c C-s', it will list lines beginning with `@node' as well as the
-lines beginning with the @-sign commands for `@chapter', `@section',
-and the like.
-
- You can remind yourself of the structure of a Texinfo file by looking
-at the list in the `*Occur*' window; and if you have mis-named a node
-or left out a section, you can correct the mistake.
+ * Avoid putting letters such as `s' immediately after an `@code'.
+ Such letters look bad.
-\1f
-File: texinfo.info, Node: Using occur, Next: Running Info-Validate, Prev: Using texinfo-show-structure, Up: Catching Mistakes
+ * Use `@var' around meta-variables. Do not write angle brackets
+ around them.
+
+ * Use three hyphens in a row, `---', to indicate a long dash. TeX
+ typesets these as a long dash and the Info formatters reduce three
+ hyphens to two.
+
+Periods Outside of Quotes
+.........................
+
+ Place periods and other punctuation marks _outside_ of quotations,
+unless the punctuation is part of the quotation. This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
-Using `occur'
-=============
+ For example, you should write the following sentence with the period
+outside the end quotation marks:
- Sometimes the `texinfo-show-structure' command produces too much
-information. Perhaps you want to remind yourself of the overall
-structure of a Texinfo file, and are overwhelmed by the detailed list
-produced by `texinfo-show-structure'. In this case, you can use the
-`occur' command directly. To do this, type
+ Evidently, `au' is an abbreviation for ``author''.
- M-x occur
+since `au' does _not_ serve as an abbreviation for `author.' (with a
+period following the word).
-and then, when prompted, type a "regexp", a regular expression for the
-pattern you want to match. (*Note Regular Expressions:
-(xemacs)Regexps.) The `occur' command works from the current location
-of the cursor in the buffer to the end of the buffer. If you want to
-run `occur' on the whole buffer, place the cursor at the beginning of
-the buffer.
+Introducing New Terms
+.....................
- For example, to see all the lines that contain the word `@chapter' in
-them, just type `@chapter'. This will produce a list of the chapters.
-It will also list all the sentences with `@chapter' in the middle of
-the line.
+ * Introduce new terms so that a reader who does not know them can
+ understand them from context; or write a definition for the term.
- If you want to see only those lines that start with the word
-`@chapter', type `^@chapter' when prompted by `occur'. If you want to
-see all the lines that end with a word or phrase, end the last word
-with a `$'; for example, `catching mistakes$'. This can be helpful
-when you want to see all the nodes that are part of the same chapter or
-section and therefore have the same `Up' pointer.
+ For example, in the following, the terms "check in", "register" and
+ "delta" are all appearing for the first time; the example sentence
+ should be rewritten so they are understandable.
- *Note Using Occur: (xemacs)Other Repeating Search, for more
-information.
+ The major function assists you in checking in a file to your
+ version control system and registering successive sets of
+ changes to it as deltas.
+
+ * Use the `@dfn' command around a word being introduced, to indicate
+ that the reader should not expect to know the meaning already, and
+ should expect to learn the meaning from this passage.
+
+@pxref
+......
+
+ Absolutely never use `@pxref' except in the special context for which
+it is designed: inside parentheses, with the closing parenthesis
+following immediately after the closing brace. One formatter
+automatically inserts closing punctuation and the other does not. This
+means that the output looks right both in printed output and in an Info
+file, but only when the command is used inside parentheses.
+
+Invoking from a Shell
+.....................
+
+ You can invoke programs such as Emacs, GCC, and `gawk' from a shell.
+The documentation for each program should contain a section that
+describes this. Unfortunately, if the node names and titles for these
+sections are all different, readers find it hard to search for the
+section.
+
+ Name such sections with a phrase beginning with the word
+`Invoking ...', as in `Invoking Emacs'; this way users can find the
+section easily.
+
+ANSI C Syntax
+.............
+
+ When you use `@example' to describe a C function's calling
+conventions, use the ANSI C syntax, like this:
+
+ void dld_init (char *@var{path});
+
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with `@var'.
+
+ Avoid the obsolete style that looks like this:
+
+ #include <dld.h>
+
+ dld_init (path)
+ char *path;
+
+ Also, it is best to avoid writing `#include' above the declaration
+just to indicate that the function is declared in a header file. The
+practice may give the misimpression that the `#include' belongs near
+the declaration of the function. Either state explicitly which header
+file holds the declaration or, better yet, name the header file used
+for a group of functions at the beginning of the section that describes
+the functions.
+
+Bad Examples
+............
+
+ Here are several examples of bad writing to avoid:
+
+ In this example, say, " ... you must `@dfn'{check in} the new
+version." That flows better.
+
+ When you are done editing the file, you must perform a
+ `@dfn'{check in}.
+
+ In the following example, say, "... makes a unified interface such as
+VC mode possible."
+
+ SCCS, RCS and other version-control systems all perform similar
+ functions in broadly similar ways (it is this resemblance which
+ makes a unified control mode like this possible).
+
+ And in this example, you should specify what `it' refers to:
+
+ If you are working with other people, it assists in coordinating
+ everyone's changes so they do not step on each other.
+
+And Finally ...
+...............
+
+ * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
+ in the name `Bach'. But pronounce Texinfo as in `speck':
+ "teckinfo".
+
+ * Write notes for yourself at the very end of a Texinfo file after
+ the `@bye'. None of the formatters process text after the `@bye';
+ it is as if the text were within `@ignore' ... `@end ignore'.
\1f
-File: texinfo.info, Node: Running Info-Validate, Prev: Using occur, Up: Catching Mistakes
+File: texinfo.info, Node: Sample Texinfo File, Next: Sample Permissions, Prev: Tips, Up: Top
-Finding Badly Referenced Nodes
-==============================
+A Sample Texinfo File
+*********************
+
+ Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter. *Note A
+Short Sample Texinfo File: Short Sample.
+
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename sample.info
+ @settitle Sample Document
+ @c %**end of header
+
+ @setchapternewpage odd
+
+ @ifinfo
+ This is a short example of a complete Texinfo file.
+
+ Copyright 1990 Free Software Foundation, Inc.
+ @end ifinfo
+
+ @titlepage
+ @sp 10
+ @comment The title is printed in a large font.
+ @center @titlefont{Sample Title}
+
+ @c The following two commands start the copyright page.
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} 1990 Free Software Foundation, Inc.
+ @end titlepage
+
+ @node Top, First Chapter, , (dir)
+ @comment node-name, next, previous, up
+
+ @menu
+ * First Chapter:: The first chapter is the
+ only chapter in this sample.
+ * Concept Index:: This index has two entries.
+ @end menu
+
+ @node First Chapter, Concept Index, Top, Top
+ @comment node-name, next, previous, up
+ @chapter First Chapter
+ @cindex Sample index entry
+
+ This is the contents of the first chapter.
+ @cindex Another sample index entry
+
+ Here is a numbered list.
+
+ @enumerate
+ @item
+ This is the first item.
+
+ @item
+ This is the second item.
+ @end enumerate
+
+ The @code{makeinfo} and @code{texinfo-format-buffer}
+ commands transform a Texinfo file such as this into
+ an Info file; and @TeX{} typesets it for a printed
+ manual.
+
+ @node Concept Index, , First Chapter, Top
+ @comment node-name, next, previous, up
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ @contents
+ @bye
+
+\1f
+File: texinfo.info, Node: Sample Permissions, Next: Include Files, Prev: Sample Texinfo File, Up: Top
+
+Sample Permissions
+******************
- You can use the `Info-validate' command to check whether any of the
-`Next', `Previous', `Up' or other node pointers fail to point to a
-node. This command checks that every node pointer points to an
-existing node. The `Info-validate' command works only on Info files,
-not on Texinfo files.
+ Texinfo files should contain sections that tell the readers that they
+have the right to copy and distribute the Texinfo file, the Info file,
+and the printed manual.
- The `makeinfo' program validates pointers automatically, so you do
-not need to use the `Info-validate' command if you are using
-`makeinfo'. You only may need to use `Info-validate' if you are unable
-to run `makeinfo' and instead must create an Info file using
-`texinfo-format-region' or `texinfo-format-buffer', or if you write an
-Info file from scratch.
+ Also, if you are writing a manual about software, you should explain
+that the software is free and either include the GNU General Public
+License (GPL) or provide a reference to it. *Note Distribution:
+(emacs)Distrib, for an example of the text that could be used in the
+software "Distribution", "General Public License", and "NO WARRANTY"
+sections of a document. *Note Texinfo Copying Conditions: Copying, for
+an example of a brief explanation of how the copying conditions provide
+you with rights.
* Menu:
-* Using Info-validate:: How to run `Info-validate'.
-* Unsplit:: How to create an unsplit file.
-* Tagifying:: How to tagify a file.
-* Splitting:: How to split a file manually.
+* Inserting Permissions:: How to put permissions in your document.
+* ifinfo Permissions:: Sample `ifinfo' copying permissions.
+* Titlepage Permissions:: Sample Titlepage copying permissions.
\1f
-File: texinfo.info, Node: Using Info-validate, Next: Unsplit, Prev: Running Info-Validate, Up: Running Info-Validate
+File: texinfo.info, Node: Inserting Permissions, Next: ifinfo Permissions, Prev: Sample Permissions, Up: Sample Permissions
+
+Inserting Permissions
+=====================
+
+ In a Texinfo file, the first `@ifinfo' section usually begins with a
+line that says what the file documents. This is what a person reading
+the unprocessed Texinfo file or using the advanced Info command `g *'
+sees first. *note Advanced Info commands: (info)Expert, for more
+information. (A reader using the regular Info commands usually starts
+reading at the first node and skips this first section, which is not in
+a node.)
+
+ In the `@ifinfo' section, the summary sentence is followed by a
+copyright notice and then by the copying permission notice. One of the
+copying permission paragraphs is enclosed in `@ignore' and `@end
+ignore' commands. This paragraph states that the Texinfo file can be
+processed through TeX and printed, provided the printed manual carries
+the proper copying permission notice. This paragraph is not made part
+of the Info file since it is not relevant to the Info file; but it is a
+mandatory part of the Texinfo file since it permits people to process
+the Texinfo file in TeX and print the results.
+
+ In the printed manual, the Free Software Foundation copying permission
+notice follows the copyright notice and publishing information and is
+located within the region delineated by the `@titlepage' and `@end
+titlepage' commands. The copying permission notice is exactly the same
+as the notice in the `@ifinfo' section except that the paragraph
+enclosed in `@ignore' and `@end ignore' commands is not part of the
+notice.
+
+ To make it simple to insert a permission notice into each section of
+the Texinfo file, sample permission notices for each section are
+reproduced in full below.
+
+ You may need to specify the correct name of a section mentioned in the
+permission notice. For example, in `The GDB Manual', the name of the
+section referring to the General Public License is called the "GDB
+General Public License", but in the sample shown below, that section is
+referred to generically as the "GNU General Public License". If the
+Texinfo file does not carry a copy of the General Public License, leave
+out the reference to it, but be sure to include the rest of the
+sentence.
-Running `Info-validate'
------------------------
+\1f
+File: texinfo.info, Node: ifinfo Permissions, Next: Titlepage Permissions, Prev: Inserting Permissions, Up: Sample Permissions
- To use `Info-validate', visit the Info file you wish to check and
-type:
+`ifinfo' Copying Permissions
+============================
- M-x Info-validate
+ In the `@ifinfo' section of a Texinfo file, the standard Free
+Software Foundation permission notice reads as follows:
-(Note that the `Info-validate' command requires an upper case `I'. You
-may also need to create a tag table before running `Info-validate'.
-*Note Tagifying::.)
+ This file documents ...
+
+ Copyright 1999 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim
+ copies of this manual provided the copyright notice and
+ this permission notice are preserved on all copies.
+
+ @ignore
+ Permission is granted to process this file through TeX
+ and print the results, provided the printed document
+ carries a copying permission notice identical to this
+ one except for the removal of this paragraph (this
+ paragraph not being relevant to the printed manual).
+
+ @end ignore
+ Permission is granted to copy and distribute modified
+ versions of this manual under the conditions for
+ verbatim copying, provided also that the sections
+ entitled ``Copying'' and ``GNU General Public License''
+ are included exactly as in the original, and provided
+ that the entire resulting derived work is distributed
+ under the terms of a permission notice identical to this
+ one.
+
+ Permission is granted to copy and distribute
+ translations of this manual into another language,
+ under the above conditions for modified versions,
+ except that this permission notice may be stated in a
+ translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Titlepage Permissions, Prev: ifinfo Permissions, Up: Sample Permissions
- If your file is valid, you will receive a message that says "File
-appears valid". However, if you have a pointer that does not point to
-a node, error messages will be displayed in a buffer called `*problems
-in info file*'.
+Titlepage Copying Permissions
+=============================
- For example, `Info-validate' was run on a test file that contained
-only the first node of this manual. One of the messages said:
+ In the `@titlepage' section of a Texinfo file, the standard Free
+Software Foundation copying permission notice follows the copyright
+notice and publishing information. The standard phrasing is as follows:
- In node "Overview", invalid Next: Texinfo Mode
+ Permission is granted to make and distribute verbatim
+ copies of this manual provided the copyright notice and
+ this permission notice are preserved on all copies.
+
+ Permission is granted to copy and distribute modified
+ versions of this manual under the conditions for
+ verbatim copying, provided also that the sections
+ entitled ``Copying'' and ``GNU General Public License''
+ are included exactly as in the original, and provided
+ that the entire resulting derived work is distributed
+ under the terms of a permission notice identical to this
+ one.
+
+ Permission is granted to copy and distribute
+ translations of this manual into another language,
+ under the above conditions for modified versions,
+ except that this permission notice may be stated in a
+ translation approved by the Free Software Foundation.
-This meant that the node called `Overview' had a `Next' pointer that
-did not point to anything (which was true in this case, since the test
-file had only one node in it).
+\1f
+File: texinfo.info, Node: Include Files, Next: Headings, Prev: Sample Permissions, Up: Top
- Now suppose we add a node named `Texinfo Mode' to our test case but
-we do not specify a `Previous' for this node. Then we will get the
-following error message:
+Include Files
+*************
- In node "Texinfo Mode", should have Previous: Overview
+ When TeX or an Info formatting command sees an `@include' command in
+a Texinfo file, it processes the contents of the file named by the
+command and incorporates them into the DVI or Info file being created.
+Index entries from the included file are incorporated into the indices
+of the output file.
-This is because every `Next' pointer should be matched by a `Previous'
-(in the node where the `Next' points) which points back.
+ Include files let you keep a single large document as a collection of
+conveniently small parts.
- `Info-validate' also checks that all menu entries and cross references
-point to actual nodes.
+* Menu:
- Note that `Info-validate' requires a tag table and does not work with
-files that have been split. (The `texinfo-format-buffer' command
-automatically splits large files.) In order to use `Info-validate' on
-a large file, you must run `texinfo-format-buffer' with an argument so
-that it does not split the Info file; and you must create a tag table
-for the unsplit file.
+* Using Include Files:: How to use the `@include' command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What `texinfo-multiple-files-update' expects.
+* Sample Include File:: A sample outer file with included files
+ within it; and a sample included file.
+* Include Files Evolution:: How use of the `@include' command
+ has changed over time.
\1f
-File: texinfo.info, Node: Unsplit, Next: Tagifying, Prev: Using Info-validate, Up: Running Info-Validate
+File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Prev: Include Files, Up: Include Files
+
+How to Use Include Files
+========================
+
+ To include another file within a Texinfo file, write the `@include'
+command at the beginning of a line and follow it on the same line by
+the name of a file to be included. For example:
+
+ @include buffers.texi
+
+ An included file should simply be a segment of text that you expect to
+be included as is into the overall or "outer" Texinfo file; it should
+not contain the standard beginning and end parts of a Texinfo file. In
+particular, you should not start an included file with a line saying
+`\input texinfo'; if you do, that phrase is inserted into the output
+file as is. Likewise, you should not end an included file with an
+`@bye' command; nothing after `@bye' is formatted.
+
+ In the past, you were required to write an `@setfilename' line at the
+beginning of an included file, but no longer. Now, it does not matter
+whether you write such a line. If an `@setfilename' line exists in an
+included file, it is ignored.
+
+ Conventionally, an included file begins with an `@node' line that is
+followed by an `@chapter' line. Each included file is one chapter.
+This makes it easy to use the regular node and menu creating and
+updating commands to create the node pointers and menus within the
+included file. However, the simple Emacs node and menu creating and
+updating commands do not work with multiple Texinfo files. Thus you
+cannot use these commands to fill in the `Next', `Previous', and `Up'
+pointers of the `@node' line that begins the included file. Also, you
+cannot use the regular commands to create a master menu for the whole
+file. Either you must insert the menus and the `Next', `Previous', and
+`Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
+command, `texinfo-multiple-files-update', that is designed for
+`@include' files.
-Creating an Unsplit File
-------------------------
+\1f
+File: texinfo.info, Node: texinfo-multiple-files-update, Next: Include File Requirements, Prev: Using Include Files, Up: Include Files
- You can run `Info-validate' only on a single Info file that has a tag
-table. The command will not work on the indirect subfiles that are
-generated when a master file is split. If you have a large file
-(longer than 70,000 bytes or so), you need to run the
-`texinfo-format-buffer' or `makeinfo-buffer' command in such a way that
-it does not create indirect subfiles. You will also need to create a
-tag table for the Info file. After you have done this, you can run
-`Info-validate' and look for badly referenced nodes.
+`texinfo-multiple-files-update'
+===============================
- The first step is to create an unsplit Info file. To prevent
-`texinfo-format-buffer' from splitting a Texinfo file into smaller Info
-files, give a prefix to the `M-x texinfo-format-buffer' command:
+ GNU Emacs Texinfo mode provides the `texinfo-multiple-files-update'
+command. This command creates or updates `Next', `Previous', and `Up'
+pointers of included files as well as those in the outer or overall
+Texinfo file, and it creates or updates a main menu in the outer file.
+Depending whether you call it with optional arguments, the command
+updates only the pointers in the first `@node' line of the included
+files or all of them:
- C-u M-x texinfo-format-buffer
+`M-x texinfo-multiple-files-update'
+ Called without any arguments:
-or else
+ - Create or update the `Next', `Previous', and `Up' pointers of
+ the first `@node' line in each file included in an outer or
+ overall Texinfo file.
- C-u C-c C-e C-b
+ - Create or update the `Top' level node pointers of the outer or
+ overall file.
-When you do this, Texinfo will not split the file and will not create a
-tag table for it.
+ - Create or update a main menu in the outer file.
-\1f
-File: texinfo.info, Node: Tagifying, Next: Splitting, Prev: Unsplit, Up: Running Info-Validate
+`C-u M-x texinfo-multiple-files-update'
+ Called with `C-u' as a prefix argument:
-Tagifying a File
-----------------
+ - Create or update pointers in the first `@node' line in each
+ included file.
- After creating an unsplit Info file, you must create a tag table for
-it. Visit the Info file you wish to tagify and type:
+ - Create or update the `Top' level node pointers of the outer
+ file.
- M-x Info-tagify
+ - Create and insert a master menu in the outer file. The
+ master menu is made from all the menus in all the included
+ files.
-(Note the upper case `I' in `Info-tagify'.) This creates an Info file
-with a tag table that you can validate.
+`C-u 8 M-x texinfo-multiple-files-update'
+ Called with a numeric prefix argument, such as `C-u 8':
- The third step is to validate the Info file:
+ - Create or update *all* the `Next', `Previous', and `Up'
+ pointers of all the included files.
- M-x Info-validate
+ - Create or update *all* the menus of all the included files.
-(Note the upper case `I' in `Info-validate'.) In brief, the steps are:
+ - Create or update the `Top' level node pointers of the outer or
+ overall file.
- C-u M-x texinfo-format-buffer
- M-x Info-tagify
- M-x Info-validate
+ - And then create a master menu in the outer file. This is
+ similar to invoking `texinfo-master-menu' with an argument
+ when you are working with just one file.
- After you have validated the node structure, you can rerun
-`texinfo-format-buffer' in the normal way so it will construct a tag
-table and split the file automatically, or you can make the tag table
-and split the file manually.
+ Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just `C-u', the `texinfo-multiple-files-update'
+command inserts a master menu; with a numeric prefix argument, such as
+`C-u 8', the command updates *every* pointer and menu in *all* the
+files and then inserts a master menu.
\1f
-File: texinfo.info, Node: Splitting, Prev: Tagifying, Up: Running Info-Validate
+File: texinfo.info, Node: Include File Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files
+
+Include File Requirements
+=========================
+
+ If you plan to use the `texinfo-multiple-files-update' command, the
+outer Texinfo file that lists included files within it should contain
+nothing but the beginning and end parts of a Texinfo file, and a number
+of `@include' commands listing the included files. It should not even
+include indices, which should be listed in an included file of their
+own.
+
+ Moreover, each of the included files must contain exactly one highest
+level node (conventionally, `@chapter' or equivalent), and this node
+must be the first node in the included file. Furthermore, each of
+these highest level nodes in each included file must be at the same
+hierarchical level in the file structure. Usually, each is an
+`@chapter', an `@appendix', or an `@unnumbered' node. Thus, normally,
+each included file contains one, and only one, chapter or
+equivalent-level node.
+
+ The outer file should contain only _one_ node, the `Top' node. It
+should _not_ contain any nodes besides the single `Top' node. The
+`texinfo-multiple-files-update' command will not process them.
-Splitting a File Manually
--------------------------
-
- You should split a large file or else let the `texinfo-format-buffer'
-or `makeinfo-buffer' command do it for you automatically. (Generally
-you will let one of the formatting commands do this job for you. *Note
-Create an Info File::.)
+\1f
+File: texinfo.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include File Requirements, Up: Include Files
- The split-off files are called the indirect subfiles.
+Sample File with `@include'
+===========================
- Info files are split to save memory. With smaller files, Emacs does
-not have make such a large buffer to hold the information.
+ Here is an example of a complete outer Texinfo file with `@include'
+files within it before running `texinfo-multiple-files-update', which
+would insert a main or master menu:
- If an Info file has more than 30 nodes, you should also make a tag
-table for it. *Note Using Info-validate::, for information about
-creating a tag table. (Again, tag tables are usually created
-automatically by the formatting command; you only need to create a tag
-table yourself if you are doing the job manually. Most likely, you
-will do this for a large, unsplit file on which you have run
-`Info-validate'.)
+ \input texinfo @c -*-texinfo-*-
+ @setfilename include-example.info
+ @settitle Include Example
+
+ @setchapternewpage odd
+ @titlepage
+ @sp 12
+ @center @titlefont{Include Example}
+ @sp 2
+ @center by Whom Ever
+
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} 1999 Free Software Foundation, Inc.
+ @end titlepage
+
+ @ifinfo
+ @node Top, First, , (dir)
+ @top Master Menu
+ @end ifinfo
+
+ @include foo.texinfo
+ @include bar.texinfo
+ @include concept-index.texinfo
+
+ @summarycontents
+ @contents
+
+ @bye
- Visit the Info file you wish to tagify and split and type the two
-commands:
+ An included file, such as `foo.texinfo', might look like this:
- M-x Info-tagify
- M-x Info-split
+ @node First, Second, , Top
+ @chapter First Chapter
+
+ Contents of first chapter ...
-(Note that the `I' in `Info' is upper case.)
+ The full contents of `concept-index.texinfo' might be as simple as
+this:
- When you use the `Info-split' command, the buffer is modified into a
-(small) Info file which lists the indirect subfiles. This file should
-be saved in place of the original visited file. The indirect subfiles
-are written in the same directory the original file is in, with names
-generated by appending `-' and a number to the original file name.
+ @node Concept Index
+ @unnumbered Concept Index
+
+ @printindex cp
- The primary file still functions as an Info file, but it contains just
-the tag table and a directory of subfiles.
+ The outer Texinfo source file for `The GNU Emacs Lisp Reference
+Manual' is named `elisp.texi'. This outer file contains a master menu
+with 417 entries and a list of 41 `@include' files.
\1f
-File: texinfo.info, Node: Refilling Paragraphs, Next: Command Syntax, Prev: Catching Mistakes, Up: Top
-
-Refilling Paragraphs
-********************
-
- The `@refill' command refills and, optionally, indents the first line
-of a paragraph.(1) (*note Refilling Paragraphs-Footnotes::) The
-`@refill' command is no longer important, but we describe it here
-because you once needed it. You will see it in many old Texinfo files.
-
- Without refilling, paragraphs containing long @-constructs may look
-bad after formatting because the formatter removes @-commands and
-shortens some lines more than others. In the past, neither the
-`texinfo-format-region' command nor the `texinfo-format-buffer' command
-refilled paragraphs automatically. The `@refill' command had to be
-written at the end of every paragraph to cause these formatters to fill
-them. (Both TeX and `makeinfo' have always refilled paragraphs
-automatically.) Now, all the Info formatters automatically fill and
-indent those paragraphs that need to be filled and indented.
-
- The `@refill' command causes `texinfo-format-region' and
-`texinfo-format-buffer' to refill a paragraph in the Info file *after*
-all the other processing has been done. For this reason, you can not
-use `@refill' with a paragraph containing either `@*' or `@w{ ... }'
-since the refilling action will override those two commands.
-
- The `texinfo-format-region' and `texinfo-format-buffer' commands now
-automatically append `@refill' to the end of each paragraph that should
-be filled. They do not append `@refill' to the ends of paragraphs that
-contain `@*' or `@w{ ...}' and therefore do not refill or indent them.
+File: texinfo.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files
+
+Evolution of Include Files
+==========================
+
+ When Info was first created, it was customary to create many small
+Info files on one subject. Each Info file was formatted from its own
+Texinfo source file. This custom meant that Emacs did not need to make
+a large buffer to hold the whole of a large Info file when someone
+wanted information; instead, Emacs allocated just enough memory for the
+small Info file that contained the particular information sought. This
+way, Emacs could avoid wasting memory.
+
+ References from one file to another were made by referring to the file
+name as well as the node name. (*Note Referring to Other Info Files:
+Other Info Files. Also, see *Note `@xref' with Four and Five
+Arguments: Four and Five Arguments.)
+
+ Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files. In a printed
+manual, all the references were within the same document, so TeX could
+automatically determine the references' page numbers. The Info
+formatting commands used include files only for creating joint indices;
+each of the individual Texinfo files had to be formatted for Info
+individually. (Each, therefore, required its own `@setfilename' line.)
+
+ However, because large Info files are now split automatically, it is
+no longer necessary to keep them small.
+
+ Nowadays, multiple Texinfo files are used mostly for large documents,
+such as `The GNU Emacs Lisp Reference Manual', and for projects in
+which several different people write different sections of a document
+simultaneously.
+
+ In addition, the Info formatting commands have been extended to work
+with the `@include' command so as to create a single large Info file
+that is split into smaller files if necessary. This means that you can
+write menus and cross references without naming the different Texinfo
+files.
\1f
-File: texinfo.info, Node: Refilling Paragraphs-Footnotes, Up: Refilling Paragraphs
+File: texinfo.info, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top
+
+Page Headings
+*************
+
+ Most printed manuals contain headings along the top of every page
+except the title and copyright pages. Some manuals also contain
+footings. (Headings and footings have no meaning to Info, which is not
+paginated.)
+
+* Menu:
- (1) Perhaps the command should have been called the
-`@refillandindent' command, but `@refill' is shorter and the name was
-chosen before indenting was possible.
+* Headings Introduced:: Conventions for using page headings.
+* Heading Format:: Standard page heading formats.
+* Heading Choice:: How to specify the type of page heading.
+* Custom Headings:: How to create your own headings and footings.
\1f
-File: texinfo.info, Node: Command Syntax, Next: Obtaining TeX, Prev: Refilling Paragraphs, Up: Top
-
-@-Command Syntax
-****************
-
- The character `@' is used to start special Texinfo commands. (It has
-the same meaning that `\' has in plain TeX.) Texinfo has four types of
-@-command:
-
-1. Non-alphabetic commands.
- These commands consist of an @ followed by a punctuation mark or
- other character that is not part of the alphabet. Non-alphabetic
- commands are almost always part of the text within a paragraph,
- and never take any argument. The two characters (@ and the other
- one) are complete in themselves; none is followed by braces. The
- non-alphabetic commands are: `@.', `@:', `@*', `@SPACE', `@TAB',
- `@NL', `@@', `@{', and `@}'.
-
-2. Alphabetic commands that do not require arguments.
- These commands start with @ followed by a word followed by left-
- and right-hand braces. These commands insert special symbols in
- the document; they do not require arguments. For example,
- `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and
- `@bullet{}' => `*'.
-
-3. Alphabetic commands that require arguments within braces.
- These commands start with @ followed by a letter or a word,
- followed by an argument within braces. For example, the command
- `@dfn' indicates the introductory or defining use of a term; it is
- used as follows: `In Texinfo, @@-commands are @dfn{mark-up}
- commands.'
-
-4. Alphabetic commands that occupy an entire line.
- These commands occupy an entire line. The line starts with @,
- followed by the name of the command (a word); for example,
- `@center' or `@cindex'. If no argument is needed, the word is
- followed by the end of the line. If there is an argument, it is
- separated from the command name by a space. Braces are not used.
-
- Thus, the alphabetic commands fall into classes that have different
-argument syntaxes. You cannot tell to which class a command belongs by
-the appearance of its name, but you can tell by the command's meaning:
-if the command stands for a glyph, it is in class 2 and does not
-require an argument; if it makes sense to use the command together with
-other text as part of a paragraph, the command is in class 3 and must
-be followed by an argument in braces; otherwise, it is in class 4 and
-uses the rest of the line as its argument.
-
- The purpose of having a different syntax for commands of classes 3 and
-4 is to make Texinfo files easier to read, and also to help the GNU
-Emacs paragraph and filling commands work properly. There is only one
-exception to this rule: the command `@refill', which is always used at
-the end of a paragraph immediately following the final period or other
-punctuation character. `@refill' takes no argument and does *not*
-require braces. `@refill' never confuses the Emacs paragraph commands
-because it cannot appear at the beginning of a line.
+File: texinfo.info, Node: Headings Introduced, Next: Heading Format, Prev: Headings, Up: Headings
+
+Headings Introduced
+===================
+
+ Texinfo provides standard page heading formats for manuals that are
+printed on one side of each sheet of paper and for manuals that are
+printed on both sides of the paper. Typically, you will use these
+formats, but you can specify your own format if you wish.
+
+ In addition, you can specify whether chapters should begin on a new
+page, or merely continue the same page as the previous chapter; and if
+chapters begin on new pages, you can specify whether they must be
+odd-numbered pages.
+
+ By convention, a book is printed on both sides of each sheet of paper.
+When you open a book, the right-hand page is odd-numbered, and chapters
+begin on right-hand pages--a preceding left-hand page is left blank if
+necessary. Reports, however, are often printed on just one side of
+paper, and chapters begin on a fresh page immediately following the end
+of the preceding chapter. In short or informal reports, chapters often
+do not begin on a new page at all, but are separated from the preceding
+text by a small amount of whitespace.
+
+ The `@setchapternewpage' command controls whether chapters begin on
+new pages, and whether one of the standard heading formats is used. In
+addition, Texinfo has several heading and footing commands that you can
+use to generate your own heading and footing formats.
+
+ In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part. Any part, or a whole line, may be left
+blank. Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set flushright.
\1f
-File: texinfo.info, Node: Obtaining TeX, Next: Command and Variable Index, Prev: Command Syntax, Up: Top
+File: texinfo.info, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings
+
+Standard Heading Formats
+========================
+
+ Texinfo provides two standard heading formats, one for manuals printed
+on one side of each sheet of paper, and the other for manuals printed
+on both sides of the paper.
+
+ By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains blank.
+
+ The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page number.
+
+ A single-sided page looks like this:
+
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
+
+ The standard format for two-sided printing depends on whether the page
+number is even or odd. By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right. (TeX will adjust the
+widths of the left- and right-hand margins. Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly--sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)
+
+ In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
+`@settitle' command). The left part of the right-hand (odd-numbered)
+page contains the name of the chapter, the central part is blank, and
+the right part contains the page number.
+
+ Two pages, side by side as in an open book, look like this:
+
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
+
+The chapter name is preceded by the word "Chapter", the chapter number
+and a colon. This makes it easier to keep track of where you are in the
+manual.
-How to Obtain TeX
-*****************
+\1f
+File: texinfo.info, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings
- TeX is freely redistributable. You can obtain TeX for Unix systems
-via anonymous ftp or on physical media. The core material consists of
-the Web2c TeX distribution (`http://tug.org/web2c').
+Specifying the Type of Heading
+==============================
- Instructions for retrieval by anonymous ftp and information on other
-available distributions:
- `ftp://tug.org/tex/unixtex.ftp'
- `http://tug.org/unixtex.ftp'
+ TeX does not begin to generate page headings for a standard Texinfo
+file until it reaches the `@end titlepage' command. Thus, the title
+and copyright pages are not numbered. The `@end titlepage' command
+causes TeX to begin to generate page headings according to a standard
+format specified by the `@setchapternewpage' command that precedes the
+`@titlepage' section.
- The Free Software Foundation provides a core distribution on its
-Source Code CD-ROM suitable for printing Texinfo manuals; the
-University of Washington maintains and supports a tape distribution;
-the TeX Users Group co-sponsors a complete CD-ROM TeX distribution.
+ There are four possibilities:
- * For the FSF Source Code CD-ROM, please contact:
+No `@setchapternewpage' command
+ Cause TeX to specify the single-sided heading format, with chapters
+ on new pages. This is the same as `@setchapternewpage on'.
- Free Software Foundation, Inc.
- 59 Temple Place Suite 330
- Boston, MA 02111-1307
- USA
-
- Telephone: +1-617-542-5942
- Fax: (including Japan) +1-617-542-2652
- Free Dial Fax (in Japan):
- 0031-13-2473 (KDD)
- 0066-3382-0158 (IDC)
- Electronic mail: `gnu@gnu.org'
-
- * To order a complete distribution on CD-ROM, please see
- `http://tug.org/tex-live.html'. (This distribution is also
- available by FTP; see the URL's above.)
-
- * To order a full distribution from the University of Washington on
- either a 1/4in 4-track QIC-24 cartridge or a 4mm DAT cartridge,
- send $210 to:
-
- Pierre A. MacKay
- Denny Hall, Mail Stop DH-10
- University of Washington
- Seattle, WA 98195
- USA
- Telephone: +1-206-543-2268
- Electronic mail: `mackay@cs.washington.edu'
-
- Please make checks payable to the University of Washington.
- Checks must be in U.S. dollars, drawn on a U.S. bank. Overseas
- sites: please add to the base cost, if desired, $20.00 for
- shipment via air parcel post, or $30.00 for shipment via courier.
-
- Many other TeX distributions are available; see `http://tug.org/'.
+`@setchapternewpage on'
+ Specify the single-sided heading format, with chapters on new
+ pages.
+
+`@setchapternewpage off'
+ Cause TeX to start a new chapter on the same page as the last page
+ of the preceding chapter, after skipping some vertical whitespace.
+ Also cause TeX to typeset for single-sided printing. (You can
+ override the headers format with the `@headings double' command;
+ see *Note The `@headings' Command: headings on off.)
+
+`@setchapternewpage odd'
+ Specify the double-sided heading format, with chapters on new
+ pages.
+
+Texinfo lacks an `@setchapternewpage even' command.
+
+\1f
+File: texinfo.info, Node: Custom Headings, Prev: Heading Choice, Up: Headings
+
+How to Make Your Own Headings
+=============================
+
+ You can use the standard headings provided with Texinfo or specify
+your own. By default, Texinfo has no footers, so if you specify them,
+the available page size for the main text will be slightly reduced.
+
+ Texinfo provides six commands for specifying headings and footings:
+ * `@everyheading' `@everyfooting' generate page headers and footers
+ that are the same for both even- and odd-numbered pages.
+
+ * `@evenheading' and `@evenfooting' command generate headers and
+ footers for even-numbered (left-hand) pages.
+
+ * `@oddheading' and `@oddfooting' generate headers and footers for
+ odd-numbered (right-hand) pages.
+
+ Write custom heading specifications in the Texinfo file immediately
+after the `@end titlepage' command. Enclose your specifications
+between `@iftex' and `@end iftex' commands since the
+`texinfo-format-buffer' command may not recognize them. Also, you must
+cancel the predefined heading commands with the `@headings off' command
+before defining your own specifications.
+
+ Here is how to tell TeX to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:
+
+ @iftex
+ @headings off
+ @everyheading @thischapter @| @thispage @| @today{}
+ @end iftex
+
+You need to divide the left part from the central part and the central
+part from the right part by inserting `@|' between parts. Otherwise,
+the specification command will not be able to tell where the text for
+one part ends and the next part begins.
+
+ Each part can contain text or @-commands. The text is printed as if
+the part were within an ordinary paragraph in the body of the page.
+The @-commands replace themselves with the page number, date, chapter
+name, or whatever.
+
+ Here are the six heading and footing commands:
+
+`@everyheading LEFT @| CENTER @| RIGHT'
+`@everyfooting LEFT @| CENTER @| RIGHT'
+ The `every' commands specify the format for both even- and
+ odd-numbered pages. These commands are for documents that are
+ printed on one side of each sheet of paper, or for documents in
+ which you want symmetrical headers or footers.
+
+`@evenheading LEFT @| CENTER @| RIGHT'
+`@oddheading LEFT @| CENTER @| RIGHT'
+`@evenfooting LEFT @| CENTER @| RIGHT'
+`@oddfooting LEFT @| CENTER @| RIGHT'
+ The `even' and `odd' commands specify the format for even-numbered
+ pages and odd-numbered pages. These commands are for books and
+ manuals that are printed on both sides of each sheet of paper.
+
+ Use the `@this...' series of @-commands to provide the names of
+chapters and sections and the page number. You can use the `@this...'
+commands in the left, center, or right portions of headers and footers,
+or anywhere else in a Texinfo file so long as they are between `@iftex'
+and `@end iftex' commands.
+
+ Here are the `@this...' commands:
+
+`@thispage'
+ Expands to the current page number.
+
+`@thischaptername'
+ Expands to the name of the current chapter.
+
+`@thischapter'
+ Expands to the number and name of the current chapter, in the
+ format `Chapter 1: Title'.
+
+`@thistitle'
+ Expands to the name of the document, as specified by the
+ `@settitle' command.
+
+`@thisfile'
+ For `@include' files only: expands to the name of the current
+ `@include' file. If the current Texinfo source file is not an
+ `@include' file, this command has no effect. This command does
+ _not_ provide the name of the current Texinfo source file unless
+ it is an `@include' file. (*Note Include Files::, for more
+ information about `@include' files.)
+
+You can also use the `@today{}' command, which expands to the current
+date, in `1 Jan 1900' format.
+
+ Other @-commands and text are printed in a header or footer just as
+if they were in the body of a page. It is useful to incorporate text,
+particularly when you are writing drafts:
+
+ @iftex
+ @headings off
+ @everyheading @emph{Draft!} @| @thispage @| @thischapter
+ @everyfooting @| @| Version: 0.27: @today{}
+ @end iftex
+
+ Beware of overlong titles: they may overlap another part of the
+header or footer and blot it out.
\1f
-File: texinfo.info, Node: Command and Variable Index, Next: Concept Index, Prev: Obtaining TeX, Up: Top
+File: texinfo.info, Node: Catching Mistakes, Next: Refilling Paragraphs, Prev: Headings, Up: Top
+
+Formatting Mistakes
+*******************
+
+ Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
-Command and Variable Index
-**************************
+ Emacs has two tools for catching the @-command mistakes and two for
+catching structuring mistakes.
- This is an alphabetical list of all the @-commands, assorted Emacs
-Lisp functions, and several variables. To make the list easier to use,
-the commands are listed without their preceding `@'.
+ For finding problems with @-commands, you can run TeX or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write it.
+
+ For finding problems with the structure of nodes and chapters, you
+can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
+command and you can use the `M-x Info-validate' command.
* Menu:
-* ! (end of sentence): Ending a Sentence.
-* ": Inserting Accents.
-* ': Inserting Accents.
-* (newline): Multiple Spaces.
-* (space): Multiple Spaces.
-* (tab): Multiple Spaces.
-* * (force line break): Line Breaks.
-* ,: Inserting Accents.
-* -: - and hyphenation.
-* . (end of sentence): Ending a Sentence.
-* : (suppress widening): Not Ending a Sentence.
-* =: Inserting Accents.
-* ? (end of sentence): Ending a Sentence.
-* @ (single @): Inserting An Atsign.
-* ^: Inserting Accents.
-* `: Inserting Accents.
-* aa: Inserting Accents.
-* AA: Inserting Accents.
-* AE: Inserting Accents.
-* ae: Inserting Accents.
-* afourpaper: A4 Paper.
-* appendix: unnumbered & appendix.
-* appendixsec: unnumberedsec appendixsec heading.
-* appendixsection: unnumberedsec appendixsec heading.
-* appendixsubsec: unnumberedsubsec appendixsubsec subheading.
-* appendixsubsubsec: subsubsection.
-* apply: Sample Function Definition.
-* asis: table.
-* author: title subtitle author.
-* b (bold font): Fonts.
-* buffer-end: Def Cmd Template.
-* bullet: bullet.
-* bye <1>: File End.
-* bye: Ending a File.
-* c (comment): Comments.
-* cartouche: cartouche.
-* center: titlefont center sp.
-* centerchap: chapter.
-* chapheading: majorheading & chapheading.
-* chapter: chapter.
-* cindex: Indexing Commands.
-* cite: cite.
-* clear: ifset ifclear.
-* code: code.
-* columnfractions: Multitable Column Widths.
-* comment: Comments.
-* contents: Contents.
-* copyright <1>: Copyright & Permissions.
-* copyright: copyright symbol.
-* cropmarks: Cropmarks and Magnification.
-* defcodeindex: New Indices.
-* defcv: Abstract Objects.
-* deffn: Functions Commands.
-* deffnx: deffnx.
-* defindex: New Indices.
-* definfoenclose: Customized Highlighting.
-* defivar: Abstract Objects.
-* defmac: Functions Commands.
-* defmethod: Abstract Objects.
-* defop: Abstract Objects.
-* defopt: Variables Commands.
-* defspec: Functions Commands.
-* deftp: Data Types.
-* deftypefn: Typed Functions.
-* deftypefun: Typed Functions.
-* deftypevar: Typed Variables.
-* deftypevr: Typed Variables.
-* defun: Functions Commands.
-* defvar: Variables Commands.
-* defvr: Variables Commands.
-* dfn: dfn.
-* dircategory: Installing Dir Entries.
-* direntry: Installing Dir Entries.
-* display: display.
-* dmn: dmn.
-* dotaccent: Inserting Accents.
-* dotless: Inserting Accents.
-* dots: dots.
-* email: email.
-* emph: emph & strong.
-* end <1>: Introducing Lists.
-* end: Quotations and Examples.
-* end titlepage: end titlepage.
-* enumerate: enumerate.
-* evenfooting: Custom Headings.
-* evenheading: Custom Headings.
-* everyfooting: Custom Headings.
-* everyheading: Custom Headings.
-* example: example.
-* exclamdown: Inserting Accents.
-* exdent: exdent.
-* file: file.
-* filll: Copyright & Permissions.
-* finalout: Overfull hboxes.
-* findex: Indexing Commands.
-* flushleft: flushleft & flushright.
-* flushright: flushleft & flushright.
-* foobar: Optional Arguments.
-* footnote: Footnotes.
-* footnotestyle: Footnote Styles.
-* format: format.
-* forward-word: Def Cmd Template.
-* ftable: ftable vtable.
-* group: group.
-* H: Inserting Accents.
-* heading: unnumberedsec appendixsec heading.
-* headings: headings on off.
-* html: Raw Formatter Commands.
-* hyphenation: - and hyphenation.
-* i (italic font): Fonts.
-* ifclear: ifset ifclear.
-* ifhtml <1>: Raw Formatter Commands.
-* ifhtml: Conditional Commands.
-* ifinfo: Conditional Commands.
-* ifnothtml: Conditional Not Commands.
-* ifnotinfo: Conditional Not Commands.
-* ifnottex: Conditional Not Commands.
-* ifset: ifset ifclear.
-* iftex: Conditional Commands.
-* ignore: Comments.
-* image: Images.
-* include: Using Include Files.
-* Info-validate: Running Info-Validate.
-* inforef: inforef.
-* input (TeX command): Minimum.
-* isearch-backward: deffnx.
-* isearch-forward: deffnx.
-* item <1>: itemize.
-* item <2>: Multitable Rows.
-* item: table.
-* itemize: itemize.
-* itemx: itemx.
-* kbd: kbd.
-* kbdinputstyle: kbd.
-* key: key.
-* kindex: Indexing Commands.
-* L: Inserting Accents.
-* l: Inserting Accents.
-* lisp: Lisp Example.
-* lowersections: Raise/lower sections.
-* macro: Defining Macros.
-* mag (TeX command): Cropmarks and Magnification.
-* majorheading: majorheading & chapheading.
-* makeinfo-buffer: makeinfo in Emacs.
-* makeinfo-kill-job: makeinfo in Emacs.
-* makeinfo-recenter-output-buffer: makeinfo in Emacs.
-* makeinfo-region: makeinfo in Emacs.
-* math: math.
-* menu: Menus.
-* minus: minus.
-* multitable: Multi-column Tables.
-* need: need.
-* next-error: makeinfo in Emacs.
-* noindent: noindent.
-* o: Inserting Accents.
-* O: Inserting Accents.
-* occur: Using occur.
-* occur-mode-goto-occurrence: Showing the Structure.
-* oddfooting: Custom Headings.
-* oddheading: Custom Headings.
-* oe: Inserting Accents.
-* OE: Inserting Accents.
-* page: page.
-* paragraphindent: paragraphindent.
-* pindex: Indexing Commands.
-* pounds: pounds.
-* printindex: Printing Indices & Menus.
-* pxref: pxref.
-* questiondown: Inserting Accents.
-* quotation: quotation.
-* r (Roman font): Fonts.
-* raisesections: Raise/lower sections.
-* ref: ref.
-* refill: Refilling Paragraphs.
-* ringaccent: Inserting Accents.
-* samp: samp.
-* sc (small caps font): Smallcaps.
-* section: section.
-* set: ifset ifclear.
-* setchapternewpage: setchapternewpage.
-* setfilename: setfilename.
-* settitle: settitle.
-* shortcontents: Contents.
-* shorttitlepage: titlepage.
-* smallbook: smallbook.
-* smallexample: smallexample & smalllisp.
-* smalllisp: smallexample & smalllisp.
-* sp (line spacing): sp.
-* sp (titlepage line spacing): titlefont center sp.
-* ss: Inserting Accents.
-* strong: emph & strong.
-* subheading: unnumberedsubsec appendixsubsec subheading.
-* subsection: subsection.
-* subsubheading: subsubsection.
-* subsubsection: subsubsection.
-* subtitle: title subtitle author.
-* summarycontents: Contents.
-* syncodeindex: syncodeindex.
-* synindex: synindex.
-* t (typewriter font): Fonts.
-* table: Two-column Tables.
-* tex: Raw Formatter Commands.
-* tex (command): tex.
-* texinfo-all-menus-update: Updating Commands.
-* texinfo-every-node-update: Updating Commands.
-* texinfo-format-buffer <1>: texinfo-format commands.
-* texinfo-format-buffer: Info Formatting.
-* texinfo-format-region <1>: texinfo-format commands.
-* texinfo-format-region: Info Formatting.
-* texinfo-indent-menu-description: Other Updating Commands.
-* texinfo-insert-@code: Inserting.
-* texinfo-insert-@dfn: Inserting.
-* texinfo-insert-@end: Inserting.
-* texinfo-insert-@example: Inserting.
-* texinfo-insert-@item: Inserting.
-* texinfo-insert-@kbd: Inserting.
-* texinfo-insert-@node: Inserting.
-* texinfo-insert-@noindent: Inserting.
-* texinfo-insert-@samp: Inserting.
-* texinfo-insert-@table: Inserting.
-* texinfo-insert-@var: Inserting.
-* texinfo-insert-braces: Inserting.
-* texinfo-insert-node-lines: Other Updating Commands.
-* texinfo-make-menu: Updating Commands.
-* texinfo-master-menu: Updating Commands.
-* texinfo-multiple-files-update: texinfo-multiple-files-update.
-* texinfo-multiple-files-update (in brief): Other Updating Commands.
-* texinfo-sequential-node-update: Other Updating Commands.
-* texinfo-show-structure <1>: Showing the Structure.
-* texinfo-show-structure: Using texinfo-show-structure.
-* texinfo-start-menu-description: Inserting.
-* texinfo-tex-buffer: Printing.
-* texinfo-tex-print: Printing.
-* texinfo-tex-region: Printing.
-* texinfo-update-node: Updating Commands.
-* thischapter: Custom Headings.
-* thischaptername: Custom Headings.
-* thisfile: Custom Headings.
-* thispage: Custom Headings.
-* thistitle: Custom Headings.
-* tieaccent: Inserting Accents.
-* tindex: Indexing Commands.
-* title: title subtitle author.
-* titlefont: titlefont center sp.
-* titlepage: titlepage.
-* today: Custom Headings.
-* top (@-command): makeinfo top command.
-* u: Inserting Accents.
-* ubaraccent: Inserting Accents.
-* udotaccent: Inserting Accents.
-* unmacro: Defining Macros.
-* unnumbered: unnumbered & appendix.
-* unnumberedsec: unnumberedsec appendixsec heading.
-* unnumberedsubsec: unnumberedsubsec appendixsubsec subheading.
-* unnumberedsubsubsec: subsubsection.
-* up-list: Inserting.
-* uref: uref.
-* url: url.
-* v: Inserting Accents.
-* value: value.
-* var: var.
-* vindex: Indexing Commands.
-* vskip: Copyright & Permissions.
-* vtable: ftable vtable.
-* w (prevent line break): w.
-* xref: xref.
-* { (single {): Inserting Braces.
-* } (single }): Inserting Braces.
-* ~: Inserting Accents.
+* makeinfo Preferred:: `makeinfo' finds errors.
+* Debugging with Info:: How to catch errors with Info formatting.
+* Debugging with TeX:: How to catch errors with TeX formatting.
+* Using texinfo-show-structure:: How to use `texinfo-show-structure'.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
+
+\1f
+File: texinfo.info, Node: makeinfo Preferred, Next: Debugging with Info, Prev: Catching Mistakes, Up: Catching Mistakes
+
+`makeinfo' Find Errors
+======================
+
+ The `makeinfo' program does an excellent job of catching errors and
+reporting them--far better than `texinfo-format-region' or
+`texinfo-format-buffer'. In addition, the various functions for
+automatically creating and updating node pointers and menus remove many
+opportunities for human error.
+
+ If you can, use the updating commands to create and insert pointers
+and menus. These prevent many errors. Then use `makeinfo' (or its
+Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
+to format your file and check for other errors. This is the best way
+to work with Texinfo. But if you cannot use `makeinfo', or your
+problem is very puzzling, then you may want to use the tools described
+in this appendix.
+
+\1f
+File: texinfo.info, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo Preferred, Up: Catching Mistakes
+
+Catching Errors with Info Formatting
+====================================
+
+ After you have written part of a Texinfo file, you can use the
+`texinfo-format-region' or the `makeinfo-region' command to see whether
+the region formats properly.
+
+ Most likely, however, you are reading this section because for some
+reason you cannot use the `makeinfo-region' command; therefore, the
+rest of this section presumes that you are using
+`texinfo-format-region'.
+
+ If you have made a mistake with an @-command, `texinfo-format-region'
+will stop processing at or after the error and display an error
+message. To see where in the buffer the error occurred, switch to the
+`*Info Region*' buffer; the cursor will be in a position that is after
+the location of the error. Also, the text will not be formatted after
+the place where the error occurred (or more precisely, where it was
+detected).
+
+ For example, if you accidentally end a menu with the command `@end
+menus' with an `s' on the end, instead of with `@end menu', you will
+see an error message that says:
+
+ @end menus is not handled by texinfo
+
+The cursor will stop at the point in the buffer where the error occurs,
+or not long after it. The buffer will look like this:
+
+ ---------- Buffer: *Info Region* ----------
+ * Menu:
+
+ * Using texinfo-show-structure:: How to use
+ `texinfo-show-structure'
+ to catch mistakes.
+ * Running Info-Validate:: How to check for
+ unreferenced nodes.
+ @end menus
+ -!-
+ ---------- Buffer: *Info Region* ----------
+
+ The `texinfo-format-region' command sometimes provides slightly odd
+error messages. For example, the following cross reference fails to
+format:
+
+ (@xref{Catching Mistakes, for more info.)
+
+In this case, `texinfo-format-region' detects the missing closing brace
+but displays a message that says `Unbalanced parentheses' rather than
+`Unbalanced braces'. This is because the formatting command looks for
+mismatches between braces as if they were parentheses.
+
+ Sometimes `texinfo-format-region' fails to detect mistakes. For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:
+
+ (@xref{Catching Mistakes), for more info.}
+
+Formatting produces:
+ (*Note for more info.: Catching Mistakes)
+
+ The only way for you to detect this error is to realize that the
+reference should have looked like this:
+
+ (*Note Catching Mistakes::, for more info.)
+
+ Incidentally, if you are reading this node in Info and type `f <RET>'
+(`Info-follow-reference'), you will generate an error message that says:
+
+ No such node: "Catching Mistakes) The only way ...
+
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a <RET> immediately after
+typing the Info `f' command, Info will attempt to go to the referenced
+node. If you type `f catch <TAB> <RET>', Info will complete the node
+name of the correctly written example and take you to the `Catching
+Mistakes' node. (If you try this, you can return from the `Catching
+Mistakes' node by typing `l' (`Info-last').)
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
-File: texinfo.info, Node: Concept Index, Prev: Command and Variable Index, Up: Top
+File: texinfo.info, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes
-Concept Index
-*************
+Catching Errors with TeX Formatting
+===================================
+
+ You can also catch mistakes when you format a file with TeX.
+
+ Usually, you will want to do this after you have run
+`texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same
+file, because `texinfo-format-buffer' sometimes displays error messages
+that make more sense than TeX. (*Note Debugging with Info::, for more
+information.)
+
+ For example, TeX was run on a Texinfo file, part of which is shown
+here:
+
+ ---------- Buffer: texinfo.texi ----------
+ name of the Texinfo file as an extension. The
+ @samp{??} are `wildcards' that cause the shell to
+ substitute all the raw index files. (@xref{sorting
+ indices, for more information about sorting
+ indices.)@refill
+ ---------- Buffer: texinfo.texi ----------
+
+(The cross reference lacks a closing brace.) TeX produced the
+following output, after which it stopped:
+
+ ---------- Buffer: *tex-shell* ----------
+ Runaway argument?
+ {sorting indices, for more information about sorting
+ indices.) @refill @ETC.
+ ! Paragraph ended before @xref was complete.
+ <to be read again>
+ @par
+ l.27
+
+ ?
+ ---------- Buffer: *tex-shell* ----------
+
+ In this case, TeX produced an accurate and understandable error
+message:
+
+ Paragraph ended before @xref was complete.
+
+`@par' is an internal TeX command of no relevance to Texinfo. `l.27'
+means that TeX detected the problem on line 27 of the Texinfo file.
+The `?' is the prompt TeX uses in this circumstance.
+
+ Unfortunately, TeX is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went wrong.
+
+ In any case, if you run into a problem like this, you can do one of
+three things.
+
+ 1. You can tell TeX to continue running and ignore just this error by
+ typing <RET> at the `?' prompt.
+
+ 2. You can tell TeX to continue running and to ignore all errors as
+ best it can by typing `r <RET>' at the `?' prompt.
+
+ This is often the best thing to do. However, beware: the one error
+ may produce a cascade of additional error messages as its
+ consequences are felt through the rest of the file. To stop TeX
+ when it is producing such an avalanche of error messages, type
+ `C-c' (or `C-c C-c', if you are running a shell inside Emacs).
+
+ 3. You can tell TeX to stop this run by typing `x <RET>' at the `?'
+ prompt.
+
+ If you are running TeX inside Emacs, you need to switch to the shell
+buffer and line at which TeX offers the `?' prompt.
+
+ Sometimes TeX will format a file without producing error messages even
+though there is a problem. This usually occurs if a command is not
+ended but TeX is able to continue processing anyhow. For example, if
+you fail to end an itemized list with the `@end itemize' command, TeX
+will write a DVI file that you can print out. The only error message
+that TeX will give you is the somewhat mysterious comment that
+
+ (@end occurred inside a group at level 1)
+
+However, if you print the DVI file, you will find that the text of the
+file that follows the itemized list is entirely indented as if it were
+part of the last item in the itemized list. The error message is the
+way TeX says that it expected to find an `@end' command somewhere in
+the file; but that it could not determine where it was needed.
+
+ Another source of notoriously hard-to-find errors is a missing `@end
+group' command. If you ever are stumped by incomprehensible errors,
+look for a missing `@end group' command first.
+
+ If the Texinfo file lacks header lines, TeX may stop in the beginning
+of its run and display output that looks like the following. The `*'
+indicates that TeX is waiting for input.
+
+ This is TeX, Version 3.14159 (Web2c 7.0)
+ (test.texinfo [1])
+ *
+
+In this case, simply type `\end <RET>' after the asterisk. Then write
+the header lines in the Texinfo file and run the TeX command again.
+(Note the use of the backslash, `\'. TeX uses `\' instead of `@'; and
+in this circumstance, you are working directly with TeX, not with
+Texinfo.)
+
+\1f
+File: texinfo.info, Node: Using texinfo-show-structure, Next: Using occur, Prev: Debugging with TeX, Up: Catching Mistakes
+
+Using `texinfo-show-structure'
+==============================
+
+ It is not always easy to keep track of the nodes, chapters, sections,
+and subsections of a Texinfo file. This is especially true if you are
+revising or adding to a Texinfo file that someone else has written.
+
+ In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
+lists all the lines that begin with the @-commands that specify the
+structure: `@chapter', `@section', `@appendix', and so on. With an
+argument (`C-u' as prefix argument, if interactive), the command also
+shows the `@node' lines. The `texinfo-show-structure' command is bound
+to `C-c C-s' in Texinfo mode, by default.
+
+ The lines are displayed in a buffer called the `*Occur*' buffer,
+indented by hierarchical level. For example, here is a part of what was
+produced by running `texinfo-show-structure' on this manual:
+
+ Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
+ unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+ in buffer texinfo.texi.
+ ...
+ 4177:@chapter Nodes
+ 4198: @heading Two Paths
+ 4231: @section Node and Menu Illustration
+ 4337: @section The @code{@@node} Command
+ 4393: @subheading Choosing Node and Pointer Names
+ 4417: @subsection How to Write an @code{@@node} Line
+ 4469: @subsection @code{@@node} Line Tips
+ ...
+
+ This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
+with the `@section', `@subheading', and `@subsection' commands
+respectively. If you move your cursor into the `*Occur*' window, you
+can position the cursor over one of the lines and use the `C-c C-c'
+command (`occur-mode-goto-occurrence'), to jump to the corresponding
+spot in the Texinfo file. *Note Using Occur: (emacs)Other Repeating
+Search, for more information about `occur-mode-goto-occurrence'.
+
+ The first line in the `*Occur*' window describes the "regular
+expression" specified by TEXINFO-HEADING-PATTERN. This regular
+expression is the pattern that `texinfo-show-structure' looks for.
+*Note Using Regular Expressions: (emacs)Regexps, for more information.
+
+ When you invoke the `texinfo-show-structure' command, Emacs will
+display the structure of the whole buffer. If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the `C-x n n' (`narrow-to-region') command to mark the region.
+(*Note Narrowing: (emacs)Narrowing.) This is how the example used
+above was generated. (To see the whole buffer again, use `C-x n w'
+(`widen').)
+
+ If you call `texinfo-show-structure' with a prefix argument by typing
+`C-u C-c C-s', it will list lines beginning with `@node' as well as the
+lines beginning with the @-sign commands for `@chapter', `@section',
+and the like.
+
+ You can remind yourself of the structure of a Texinfo file by looking
+at the list in the `*Occur*' window; and if you have mis-named a node
+or left out a section, you can correct the mistake.
+
+\1f
+File: texinfo.info, Node: Using occur, Next: Running Info-Validate, Prev: Using texinfo-show-structure, Up: Catching Mistakes
+
+Using `occur'
+=============
+
+ Sometimes the `texinfo-show-structure' command produces too much
+information. Perhaps you want to remind yourself of the overall
+structure of a Texinfo file, and are overwhelmed by the detailed list
+produced by `texinfo-show-structure'. In this case, you can use the
+`occur' command directly. To do this, type
+
+ M-x occur
+
+and then, when prompted, type a "regexp", a regular expression for the
+pattern you want to match. (*Note Regular Expressions:
+(emacs)Regexps.) The `occur' command works from the current location
+of the cursor in the buffer to the end of the buffer. If you want to
+run `occur' on the whole buffer, place the cursor at the beginning of
+the buffer.
+
+ For example, to see all the lines that contain the word `@chapter' in
+them, just type `@chapter'. This will produce a list of the chapters.
+It will also list all the sentences with `@chapter' in the middle of
+the line.
+
+ If you want to see only those lines that start with the word
+`@chapter', type `^@chapter' when prompted by `occur'. If you want to
+see all the lines that end with a word or phrase, end the last word
+with a `$'; for example, `catching mistakes$'. This can be helpful
+when you want to see all the nodes that are part of the same chapter or
+section and therefore have the same `Up' pointer.
+
+ *Note Using Occur: (emacs)Other Repeating Search, for more
+information.
+
+\1f
+File: texinfo.info, Node: Running Info-Validate, Prev: Using occur, Up: Catching Mistakes
+
+Finding Badly Referenced Nodes
+==============================
+
+ You can use the `Info-validate' command to check whether any of the
+`Next', `Previous', `Up' or other node pointers fail to point to a
+node. This command checks that every node pointer points to an
+existing node. The `Info-validate' command works only on Info files,
+not on Texinfo files.
+
+ The `makeinfo' program validates pointers automatically, so you do
+not need to use the `Info-validate' command if you are using
+`makeinfo'. You only may need to use `Info-validate' if you are unable
+to run `makeinfo' and instead must create an Info file using
+`texinfo-format-region' or `texinfo-format-buffer', or if you write an
+Info file from scratch.
+
+* Menu:
+
+* Using Info-validate:: How to run `Info-validate'.
+* Unsplit:: How to create an unsplit file.
+* Tagifying:: How to tagify a file.
+* Splitting:: How to split a file manually.
+
+\1f
+File: texinfo.info, Node: Using Info-validate, Next: Unsplit, Prev: Running Info-Validate, Up: Running Info-Validate
+
+Running `Info-validate'
+-----------------------
+
+ To use `Info-validate', visit the Info file you wish to check and
+type:
+
+ M-x Info-validate
+
+Note that the `Info-validate' command requires an upper case `I'. You
+may also need to create a tag table before running `Info-validate'.
+*Note Tagifying::.
+
+ If your file is valid, you will receive a message that says "File
+appears valid". However, if you have a pointer that does not point to
+a node, error messages will be displayed in a buffer called `*problems
+in info file*'.
+
+ For example, `Info-validate' was run on a test file that contained
+only the first node of this manual. One of the messages said:
+
+ In node "Overview", invalid Next: Texinfo Mode
+
+This meant that the node called `Overview' had a `Next' pointer that
+did not point to anything (which was true in this case, since the test
+file had only one node in it).
+
+ Now suppose we add a node named `Texinfo Mode' to our test case but
+we do not specify a `Previous' for this node. Then we will get the
+following error message:
+
+ In node "Texinfo Mode", should have Previous: Overview
+
+This is because every `Next' pointer should be matched by a `Previous'
+(in the node where the `Next' points) which points back.
+
+ `Info-validate' also checks that all menu entries and cross references
+point to actual nodes.
+
+ `Info-validate' requires a tag table and does not work with files
+that have been split. (The `texinfo-format-buffer' command
+automatically splits large files.) In order to use `Info-validate' on
+a large file, you must run `texinfo-format-buffer' with an argument so
+that it does not split the Info file; and you must create a tag table
+for the unsplit file.
+
+\1f
+File: texinfo.info, Node: Unsplit, Next: Tagifying, Prev: Using Info-validate, Up: Running Info-Validate
+
+Creating an Unsplit File
+------------------------
+
+ You can run `Info-validate' only on a single Info file that has a tag
+table. The command will not work on the indirect subfiles that are
+generated when a master file is split. If you have a large file
+(longer than 70,000 bytes or so), you need to run the
+`texinfo-format-buffer' or `makeinfo-buffer' command in such a way that
+it does not create indirect subfiles. You will also need to create a
+tag table for the Info file. After you have done this, you can run
+`Info-validate' and look for badly referenced nodes.
+
+ The first step is to create an unsplit Info file. To prevent
+`texinfo-format-buffer' from splitting a Texinfo file into smaller Info
+files, give a prefix to the `M-x texinfo-format-buffer' command:
+
+ C-u M-x texinfo-format-buffer
+
+or else
+
+ C-u C-c C-e C-b
+
+When you do this, Texinfo will not split the file and will not create a
+tag table for it.
+
+\1f
+File: texinfo.info, Node: Tagifying, Next: Splitting, Prev: Unsplit, Up: Running Info-Validate
+
+Tagifying a File
+----------------
+
+ After creating an unsplit Info file, you must create a tag table for
+it. Visit the Info file you wish to tagify and type:
+
+ M-x Info-tagify
+
+(Note the upper case `I' in `Info-tagify'.) This creates an Info file
+with a tag table that you can validate.
+
+ The third step is to validate the Info file:
+
+ M-x Info-validate
+
+(Note the upper case `I' in `Info-validate'.) In brief, the steps are:
+
+ C-u M-x texinfo-format-buffer
+ M-x Info-tagify
+ M-x Info-validate
+
+ After you have validated the node structure, you can rerun
+`texinfo-format-buffer' in the normal way so it will construct a tag
+table and split the file automatically, or you can make the tag table
+and split the file manually.
+
+\1f
+File: texinfo.info, Node: Splitting, Prev: Tagifying, Up: Running Info-Validate
+
+Splitting a File Manually
+-------------------------
+
+ You should split a large file or else let the `texinfo-format-buffer'
+or `makeinfo-buffer' command do it for you automatically. (Generally
+you will let one of the formatting commands do this job for you. *Note
+Creating an Info File::.)
+
+ The split-off files are called the indirect subfiles.
+
+ Info files are split to save memory. With smaller files, Emacs does
+not have make such a large buffer to hold the information.
+
+ If an Info file has more than 30 nodes, you should also make a tag
+table for it. *Note Using Info-validate::, for information about
+creating a tag table. (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually. Most likely, you
+will do this for a large, unsplit file on which you have run
+`Info-validate'.)
+
+ Visit the Info file you wish to tagify and split and type the two
+commands:
+
+ M-x Info-tagify
+ M-x Info-split
+
+(Note that the `I' in `Info' is upper case.)
+
+ When you use the `Info-split' command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles. This file should
+be saved in place of the original visited file. The indirect subfiles
+are written in the same directory the original file is in, with names
+generated by appending `-' and a number to the original file name.
+
+ The primary file still functions as an Info file, but it contains just
+the tag table and a directory of subfiles.
+
+\1f
+File: texinfo.info, Node: Refilling Paragraphs, Next: Command Syntax, Prev: Catching Mistakes, Up: Top
+
+Refilling Paragraphs
+********************
+
+ The `@refill' command refills and, optionally, indents the first line
+of a paragraph.(1) (*note Refilling Paragraphs-Footnote-1::) The
+`@refill' command is no longer important, but we describe it here
+because you once needed it. You will see it in many old Texinfo files.
+
+ Without refilling, paragraphs containing long @-constructs may look
+bad after formatting because the formatter removes @-commands and
+shortens some lines more than others. In the past, neither the
+`texinfo-format-region' command nor the `texinfo-format-buffer' command
+refilled paragraphs automatically. The `@refill' command had to be
+written at the end of every paragraph to cause these formatters to fill
+them. (Both TeX and `makeinfo' have always refilled paragraphs
+automatically.) Now, all the Info formatters automatically fill and
+indent those paragraphs that need to be filled and indented.
+
+ The `@refill' command causes `texinfo-format-region' and
+`texinfo-format-buffer' to refill a paragraph in the Info file _after_
+all the other processing has been done. For this reason, you can not
+use `@refill' with a paragraph containing either `@*' or `@w{ ... }'
+since the refilling action will override those two commands.
+
+ The `texinfo-format-region' and `texinfo-format-buffer' commands now
+automatically append `@refill' to the end of each paragraph that should
+be filled. They do not append `@refill' to the ends of paragraphs that
+contain `@*' or `@w{ ...}' and therefore do not refill or indent them.
+
+\1f
+File: texinfo.info, Node: Refilling Paragraphs-Footnotes, Up: Refilling Paragraphs
+
+ (1) Perhaps the command should have been called the
+`@refillandindent' command, but `@refill' is shorter and the name was
+chosen before indenting was possible.
+
+\1f
+File: texinfo.info, Node: Command Syntax, Next: Obtaining TeX, Prev: Refilling Paragraphs, Up: Top
+
+@-Command Syntax
+****************
+
+ The character `@' is used to start special Texinfo commands. (It has
+the same meaning that `\' has in plain TeX.) Texinfo has four types of
+@-command:
+
+1. Non-alphabetic commands.
+ These commands consist of an @ followed by a punctuation mark or
+ other character that is not part of the alphabet. Non-alphabetic
+ commands are almost always part of the text within a paragraph,
+ and never take any argument. The two characters (@ and the other
+ one) are complete in themselves; none is followed by braces. The
+ non-alphabetic commands are: `@.', `@:', `@*', `@SPACE', `@TAB',
+ `@NL', `@@', `@{', and `@}'.
+
+2. Alphabetic commands that do not require arguments.
+ These commands start with @ followed by a word followed by left-
+ and right-hand braces. These commands insert special symbols in
+ the document; they do not require arguments. For example,
+ `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and
+ `@bullet{}' => `*'.
+
+3. Alphabetic commands that require arguments within braces.
+ These commands start with @ followed by a letter or a word,
+ followed by an argument within braces. For example, the command
+ `@dfn' indicates the introductory or defining use of a term; it is
+ used as follows: `In Texinfo, @@-commands are @dfn{mark-up}
+ commands.'
+
+4. Alphabetic commands that occupy an entire line.
+ These commands occupy an entire line. The line starts with @,
+ followed by the name of the command (a word); for example,
+ `@center' or `@cindex'. If no argument is needed, the word is
+ followed by the end of the line. If there is an argument, it is
+ separated from the command name by a space. Braces are not used.
+
+ Thus, the alphabetic commands fall into classes that have different
+argument syntaxes. You cannot tell to which class a command belongs by
+the appearance of its name, but you can tell by the command's meaning:
+if the command stands for a glyph, it is in class 2 and does not
+require an argument; if it makes sense to use the command together with
+other text as part of a paragraph, the command is in class 3 and must
+be followed by an argument in braces; otherwise, it is in class 4 and
+uses the rest of the line as its argument.
+
+ The purpose of having a different syntax for commands of classes 3 and
+4 is to make Texinfo files easier to read, and also to help the GNU
+Emacs paragraph and filling commands work properly. There is only one
+exception to this rule: the command `@refill', which is always used at
+the end of a paragraph immediately following the final period or other
+punctuation character. `@refill' takes no argument and does _not_
+require braces. `@refill' never confuses the Emacs paragraph commands
+because it cannot appear at the beginning of a line.
+
+\1f
+File: texinfo.info, Node: Obtaining TeX, Next: Command and Variable Index, Prev: Command Syntax, Up: Top
+
+How to Obtain TeX
+*****************
+
+ TeX is freely redistributable. You can obtain TeX for Unix systems
+via anonymous ftp or on physical media. The core material consists of
+the Web2c TeX distribution (`http://tug.org/web2c').
+
+ Instructions for retrieval by anonymous ftp and information on other
+available distributions:
+ `ftp://tug.org/tex/unixtex.ftp'
+ `http://tug.org/unixtex.ftp'
+
+ The Free Software Foundation provides a core distribution on its
+Source Code CD-ROM suitable for printing Texinfo manuals. To order it,
+contact:
+
+ Free Software Foundation, Inc.
+ 59 Temple Place Suite 330
+ Boston, MA 02111-1307
+ USA
+ Telephone: +1-617-542-5942
+ Fax: (including Japan) +1-617-542-2652
+ Free Dial Fax (in Japan):
+ 0031-13-2473 (KDD)
+ 0066-3382-0158 (IDC)
+ Electronic mail: `gnu@gnu.org'
+
+ Many other TeX distributions are available; see `http://tug.org/'.
+
+\1f
+File: texinfo.info, Node: Command and Variable Index, Next: Concept Index, Prev: Obtaining TeX, Up: Top
+
+Command and Variable Index
+**************************
+
+ This is an alphabetical list of all the @-commands, assorted Emacs
+Lisp functions, and several variables. To make the list easier to use,
+the commands are listed without their preceding `@'.
* Menu:
-* !: Inserting Accents.
-* (dir) as Up node of Top node: First Node.
-* -D VAR: makeinfo options.
-* -delete: Invoking install-info.
-* -dir-file=NAME: Invoking install-info.
-* -entry=TEXT: Invoking install-info.
-* -error-limit=LIMIT: makeinfo options.
-* -fill-column=WIDTH: makeinfo options.
-* -footnote-style=STYLE: makeinfo options.
-* -force: makeinfo options.
-* -help <1>: makeinfo options.
-* -help: Invoking install-info.
-* -I DIR: makeinfo options.
-* -info-dir=DIR: Invoking install-info.
-* -info-file=FILE: Invoking install-info.
-* -item=TEXT: Invoking install-info.
-* -no-headers: makeinfo options.
-* -no-number-footnotes: makeinfo options.
-* -no-pointer-validate: makeinfo options.
-* -no-split: makeinfo options.
-* -no-validate: makeinfo options.
-* -no-warn: makeinfo options.
-* -o FILE: makeinfo options.
-* -output=FILE: makeinfo options.
-* -P DIR: makeinfo options.
-* -paragraph-indent=INDENT: makeinfo options.
-* -quiet: Invoking install-info.
-* -reference-limit=LIMIT: makeinfo options.
-* -remove: Invoking install-info.
-* -section=SEC: Invoking install-info.
-* -verbose: makeinfo options.
-* -version <1>: Invoking install-info.
-* -version: makeinfo options.
-* .cshrc initialization file: Preparing for TeX.
-* .profile initialization file: Preparing for TeX.
-* ?: Inserting Accents.
-* @-command in nodename: Node Line Requirements.
-* @-command list: Command List.
-* @-command syntax: Command Syntax.
-* @-commands: Formatting Commands.
-* @include file sample: Sample Include File.
-* @menu parts: Menu Parts.
-* @node line writing: Writing a Node.
-* A4 paper, printing on: A4 Paper.
+* ! (end of sentence): Ending a Sentence.
+* ": Inserting Accents.
+* ': Inserting Accents.
+* (newline): Multiple Spaces.
+* (space): Multiple Spaces.
+* (tab): Multiple Spaces.
+* * (force line break): Line Breaks.
+* ,: Inserting Accents.
+* -: - and hyphenation.
+* . (end of sentence): Ending a Sentence.
+* : (suppress widening): Not Ending a Sentence.
+* =: Inserting Accents.
+* ? (end of sentence): Ending a Sentence.
+* @ (single @): Inserting An Atsign.
+* \emergencystretch: Overfull hboxes.
+* ^: Inserting Accents.
+* `: Inserting Accents.
* aa: Inserting Accents.
* AA: Inserting Accents.
-* Abbreviations for keys: key.
-* Accents, inserting: Inserting Accents.
-* Acute accent: Inserting Accents.
-* Adding a new info file: New Info File.
-* AE: Inserting Accents.
+* acronym: acronym.
* ae: Inserting Accents.
-* Alphabetical @-command list: Command List.
-* Another Info directory: Other Info Directories.
-* Apostrophe in nodename: Node Line Requirements.
-* Arguments, repeated and optional: Optional Arguments.
-* Aspect ratio of images: Images.
-* Automatic pointer creation with makeinfo: makeinfo Pointer Creation.
-* Automatically insert nodes, menus: Updating Nodes and Menus.
-* Backslash, and macros: Invoking Macros.
-* Badly referenced nodes: Running Info-Validate.
-* Batch formatting for Info: Batch Formatting.
-* Beginning a Texinfo file: Beginning a File.
-* Beginning line of a Texinfo file: First Line.
-* Berry, Karl: Acknowledgements.
-* Big points: Images.
-* Black rectangle in hardcopy: Overfull hboxes.
-* Blank lines: sp.
-* Body of a macro: Defining Macros.
-* Book characteristics, printed: Printed Books.
-* Book, printing small: smallbook.
-* Box with rounded corners: cartouche.
-* Braces and argument syntax: Command Syntax.
-* Braces, inserting: Braces Atsigns.
-* Braces, when to use: Formatting Commands.
-* Breaks in a line: Line Breaks.
-* Breve accent: Inserting Accents.
-* Buffer formatting and printing: Printing.
-* Bullets, inserting: Dots Bullets.
-* Case in nodename: Node Line Requirements.
-* Catching errors with Info formatting: Debugging with Info.
-* Catching errors with TeX formatting: Debugging with TeX.
-* Catching mistakes: Catching Mistakes.
-* Cedilla accent: Inserting Accents.
-* Centimeters: Images.
-* Chapter structuring: Structuring.
-* Characteristics, printed books or manuals: Printed Books.
-* Chassell, Robert J.: Acknowledgements.
-* Check accent: Inserting Accents.
-* Checking for badly referenced nodes: Running Info-Validate.
-* Ciceros: Images.
-* Circumflex accent: Inserting Accents.
-* code, arg to @kbdinputstyle: kbd.
-* colon last in INFOPATH: Other Info Directories.
-* Column widths, defining for multitables: Multitable Column Widths.
-* Combining indices: Combining Indices.
-* Comma in nodename: Node Line Requirements.
-* Command definitions: Sample Function Definition.
-* Commands to insert special characters: Braces Atsigns.
-* Commands using raw HTML: Raw Formatter Commands.
-* Commands using raw TeX: Raw Formatter Commands.
-* Commands, inserting them: Inserting.
-* Comments: Comments.
-* Compile command for formatting: Compile-Command.
-* Conditionally visible text: Conditionals.
-* Conditions for copying Texinfo: Copying.
-* Contents, Table of: Contents.
-* Contents-like outline of file structure: Showing the Structure.
-* Conventions for writing definitions: Def Cmd Conventions.
-* Conventions, syntactic: Conventions.
-* Copying conditions: Copying.
-* Copying permissions: Sample Permissions.
-* Copying software: Software Copying Permissions.
-* Copyright page: Copyright & Permissions.
-* Correcting mistakes: Catching Mistakes.
-* Create nodes, menus automatically: Updating Nodes and Menus.
-* Creating an Info file: Create an Info File.
-* Creating an unsplit file: Unsplit.
-* Creating index entries: Indexing Commands.
-* Creating indices: Indices.
-* Creating pointers with makeinfo: makeinfo Pointer Creation.
-* Cropmarks for printing: Cropmarks and Magnification.
-* Cross reference parts: Cross Reference Parts.
-* Cross references: Cross References.
-* Cross references using @inforef: inforef.
-* Cross references using @pxref: pxref.
-* Cross references using @ref: ref.
-* Cross references using @xref: xref.
-* Customized highlighting: Customized Highlighting.
-* Customizing of TeX for Texinfo: Preparing for TeX.
-* Debugging the Texinfo structure: Catching Mistakes.
-* Debugging with Info formatting: Debugging with Info.
-* Debugging with TeX formatting: Debugging with TeX.
-* Defining indexing entries: Indexing Commands.
-* Defining macros: Defining Macros.
-* Defining new indices: New Indices.
-* Defining new Texinfo commands: Macros.
-* Definition commands: Definition Commands.
-* Definition conventions: Def Cmd Conventions.
-* Definition template: Def Cmd Template.
-* Definitions grouped together: deffnx.
-* Description for menu, start: Inserting.
-* Did^ot points: Images.
-* Different cross reference commands: Cross Reference Commands.
-* Dimension formatting: dmn.
-* Dimensions and image sizes: Images.
-* dir directory for Info installation: Install an Info File.
-* dir file listing: New Info File.
-* dir, created by install-info: Invoking install-info.
-* Display formatting: display.
-* distinct, arg to @kbdinputstyle: kbd.
-* Distorting images: Images.
-* Distribution: Software Copying Permissions.
-* Dot accent: Inserting Accents.
-* Dotless i, j: Inserting Accents.
-* Dots, inserting <1>: dots.
-* Dots, inserting: Dots Bullets.
-* Double-colon menu entries: Less Cluttered Menu Entry.
-* DVI file: Format with tex/texindex.
-* Ellipsis, inserting: Dots Bullets.
-* Emacs: Texinfo Mode.
-* Emacs shell, format, print from: Within Emacs.
-* Emphasizing text: Emphasis.
-* Emphasizing text, font for: emph & strong.
-* Enclosure command for Info: Customized Highlighting.
-* End node footnote style: Footnote Styles.
-* End of header line: End of Header.
-* End titlepage starts headings: end titlepage.
-* Ending a Sentence: Ending a Sentence.
-* Ending a Texinfo file: Ending a File.
-* Entries for an index: Indexing Commands.
-* Entries, making index: Index Entries.
-* Enumeration: enumerate.
-* epsf.tex: Images.
-* epsf.tex, installing: Preparing for TeX.
-* Equivalence, indicating it: Equivalence.
-* Error message, indicating it: Error Glyph.
-* Errors, parsing: makeinfo in Emacs.
-* Es-zet: Inserting Accents.
-* European A4 paper: A4 Paper.
-* Evaluation glyph: result.
-* Example for a small book: smallexample & smalllisp.
-* Example menu: Menu Example.
-* example, arg to @kbdinputstyle: kbd.
-* Examples, formatting them: example.
-* Expansion, indicating it: expansion.
-* File beginning: Beginning a File.
-* File ending: Ending a File.
-* File section structure, showing it: Showing the Structure.
-* Filling paragraphs: Refilling Paragraphs.
-* Final output: Overfull hboxes.
-* Finding badly referenced nodes: Running Info-Validate.
-* Fine-tuning, and hyphenation: - and hyphenation.
-* First line of a Texinfo file: First Line.
-* First node: First Node.
-* Floating accents, inserting: Inserting Accents.
-* Fonts for indices: syncodeindex.
-* Fonts for printing, not for Info: Fonts.
-* Footings: Headings.
-* Footnotes: Footnotes.
-* Format a dimension: dmn.
-* Format and print hardcopy: Format/Print Hardcopy.
-* Format and print in Texinfo mode: Texinfo Mode Printing.
-* Format with the compile command: Compile-Command.
-* Format, print from Emacs shell: Within Emacs.
-* Formats for images: Images.
-* Formatting a file for Info: Create an Info File.
-* Formatting commands: Formatting Commands.
-* Formatting examples: example.
-* Formatting for Info: Info Formatting.
-* Formatting for printing: Printing.
-* Formatting headings and footings: Headings.
-* Formatting requirements: Requirements Summary.
-* Formatting with tex and texindex: Format with tex/texindex.
-* Frequently used commands, inserting: Inserting.
-* Function definitions: Sample Function Definition.
-* General syntactic conventions: Conventions.
-* Generating menus with indices: Printing Indices & Menus.
-* German S: Inserting Accents.
-* Globbing: Format with tex/texindex.
-* Glyphs: Glyphs.
-* GNU Emacs: Texinfo Mode.
-* GNU Emacs shell, format, print from: Within Emacs.
-* Going to other Info files' nodes: Other Info Files.
-* Grave accent: Inserting Accents.
-* Group (hold text together vertically): group.
-* Grouping two definitions together: deffnx.
-* Hardcopy, printing it: Format/Print Hardcopy.
-* hboxes, overfull: Overfull hboxes.
-* Header for Texinfo files: Header.
-* Header of a Texinfo file: First Line.
-* Headings: Headings.
-* Headings, page, begin to appear: end titlepage.
-* Height of images: Images.
-* Highlighting text: Indicating.
-* Highlighting, customized: Customized Highlighting.
-* Hints: Tips.
-* Holding text together vertically: group.
-* HTML commands, using ordinary: Raw Formatter Commands.
-* Hungariam umlaut accent: Inserting Accents.
-* Hyphenation, helping TeX do: - and hyphenation.
-* Hyphenation, preventing: w.
-* i: Inserting Accents.
-* If text conditionally visible: Conditionals.
-* ifinfo permissions: ifinfo Permissions.
-* Ignored before @setfilename: setfilename.
-* Ignored text: Comments.
-* Image formats: Images.
-* Images, inserting: Images.
-* Inches: Images.
-* Include file requirements: Include File Requirements.
-* Include file sample: Sample Include File.
-* Include files: Include Files.
-* Include files, and section levels: Raise/lower sections.
-* Indentation undoing: exdent.
-* Indenting paragraphs: paragraphindent.
-* Index entries: Indexing Commands.
-* Index entries, making: Index Entries.
-* Index entry writing: Indexing Commands.
-* Index font types: Indexing Commands.
-* Indexing commands, predefined: Indexing Commands.
-* Indexing table entries automatically: ftable vtable.
-* Indicating commands, definitions, etc.: Indicating.
-* Indicating evaluation: result.
-* Indices: Indices.
-* Indices, combining them: Combining Indices.
-* Indices, defining new: New Indices.
-* Indices, printing and menus: Printing Indices & Menus.
-* Indices, sorting: Format/Print Hardcopy.
-* Indices, two letter names: syncodeindex.
-* Indirect subfiles: Tag and Split Files.
-* Info batch formatting: Batch Formatting.
-* Info file installation: Install an Info File.
-* Info file requires @setfilename: setfilename.
-* Info file, listing new one: New Info File.
-* Info file, splitting manually: Splitting.
-* Info files: Info Files.
-* Info formatting: Info Formatting.
-* Info installed in another directory: Other Info Directories.
-* Info validating a large file: Using Info-validate.
-* Info, creating an on-line file: Create an Info File.
-* Info-directory-list: Other Info Directories.
-* Info; other files' nodes: Other Info Files.
-* INFOPATH: Other Info Directories.
-* Initialization file for TeX input: Preparing for TeX.
-* Insert nodes, menus automatically: Updating Nodes and Menus.
-* Inserting @, braces: Braces Atsigns.
-* Inserting accents: Inserting Accents.
-* Inserting dots <1>: Dots Bullets.
-* Inserting dots: dots.
-* Inserting ellipsis: Dots Bullets.
-* Inserting frequently used commands: Inserting.
-* Inserting space: Inserting Space.
-* Inserting special characters and symbols: Insertions.
-* install-info: Invoking install-info.
-* Installing an Info file: Install an Info File.
-* Installing Info in another directory: Other Info Directories.
-* Introduction, as part of file: Software Copying Permissions.
-* Invoking macros: Invoking Macros.
-* Itemization: itemize.
-* j: Inserting Accents.
-* keyboard input: kbd.
-* Keys, recommended names: key.
-* Knuth, Donald: Printed Books.
-* l/: Inserting Accents.
-* L/: Inserting Accents.
-* Larger or smaller pages: Cropmarks and Magnification.
-* Less cluttered menu entry: Less Cluttered Menu Entry.
-* License agreement: Software Copying Permissions.
-* Line breaks: Line Breaks.
-* Line breaks, preventing: w.
-* Line length, column widths as fraction of: Multitable Column Widths.
-* Line spacing: sp.
-* Lisp example: Lisp Example.
-* Lisp example for a small book: smallexample & smalllisp.
-* List of @-commands: Command List.
-* Listing a new info file: New Info File.
-* Lists and tables, making: Lists and Tables.
-* Local variables: Compile-Command.
-* Location of menus: Menu Location.
-* Looking for badly referenced nodes: Running Info-Validate.
-* lpr (DVI print command): Print with lpr.
-* Macro definitions <1>: Sample Function Definition.
-* Macro definitions: Defining Macros.
-* Macro invocation: Invoking Macros.
-* Macron accent: Inserting Accents.
-* Macros: Macros.
-* Macros, undefining: Defining Macros.
-* Magnified printing: Cropmarks and Magnification.
-* mailto link: email.
-* makeinfo inside Emacs: makeinfo in Emacs.
-* makeinfo options: makeinfo options.
-* Making a printed manual: Format/Print Hardcopy.
-* Making a tag table automatically: Tag and Split Files.
-* Making a tag table manually: Unsplit.
-* Making cross references: Cross References.
-* Making line and page breaks: Breaks.
-* Making lists and tables: Lists and Tables.
-* Manual characteristics, printed: Printed Books.
-* Marking text within a paragraph: Marking Text.
-* Marking words and phrases: Marking Text.
-* Master menu: The Top Node.
-* Master menu parts: Master Menu Parts.
-* Mathematical expressions <1>: Raw Formatter Commands.
-* Mathematical expressions: math.
-* Menu description, start: Inserting.
-* Menu entries with two colons: Less Cluttered Menu Entry.
-* Menu example: Menu Example.
-* Menu location: Menu Location.
-* Menu parts: Menu Parts.
-* Menu writing: Writing a Menu.
-* Menus: Menus.
-* Menus generated with indices: Printing Indices & Menus.
-* META key: key.
-* Meta-syntactic chars for arguments: Optional Arguments.
-* Millimeters: Images.
-* Minimal requirements for formatting: Requirements Summary.
-* Minimal Texinfo file (requirements): Minimum.
-* Mistakes, catching: Catching Mistakes.
-* Mode, using Texinfo: Texinfo Mode.
-* Multiple spaces: Multiple Spaces.
-* Multitable column widths: Multitable Column Widths.
-* Multitable rows: Multitable Rows.
-* Must have in Texinfo file: Minimum.
-* Mutually recursive macros: Defining Macros.
-* Names for indices: syncodeindex.
-* Names of index files: Format with tex/texindex.
-* Names recommended for keys: key.
-* Naming a `Top' Node in references: Top Node Naming.
-* Need space at page bottom: need.
-* New index defining: New Indices.
-* New info file, listing it in dir file: New Info File.
-* New Texinfo commands, defining: Macros.
-* Node line requirements: Node Line Requirements.
-* Node line writing: Writing a Node.
-* Node, `Top': The Top Node.
-* Node, defined: node.
-* Nodename must be unique: Node Line Requirements.
-* Nodename, cannot contain: Node Line Requirements.
-* Nodes for menus are short: Menu Location.
-* Nodes in other Info files: Other Info Files.
-* Nodes, catching mistakes: Catching Mistakes.
-* Nodes, checking for badly referenced: Running Info-Validate.
-* Not ending a sentence: Not Ending a Sentence.
-* o/: Inserting Accents.
-* O/: Inserting Accents.
-* Obtaining TeX: Obtaining TeX.
-* Occurrences, listing with @occur: Using occur.
+* AE: Inserting Accents.
+* afourlatex: A4 Paper.
+* afourpaper: A4 Paper.
+* alias: alias.
+* anchor: anchor.
+* appendix: unnumbered & appendix.
+* appendixsec: unnumberedsec appendixsec heading.
+* appendixsection: unnumberedsec appendixsec heading.
+* appendixsubsec: unnumberedsubsec appendixsubsec subheading.
+* appendixsubsubsec: subsubsection.
+* apply: Sample Function Definition.
+* asis: table.
+* author: title subtitle author.
+* b (bold font): Fonts.
+* buffer-end: Def Cmd Template.
+* bullet: bullet.
+* bye <1>: File End.
+* bye: Ending a File.
+* c (comment): Comments.
+* cartouche: cartouche.
+* center: titlefont center sp.
+* centerchap: chapter.
+* chapheading: majorheading & chapheading.
+* chapter: chapter.
+* cindex: Indexing Commands.
+* cite: cite.
+* clear: ifset ifclear.
+* code: code.
+* columnfractions: Multitable Column Widths.
+* command: command.
+* comment: Comments.
+* contents: Contents.
+* copyright <1>: copyright symbol.
+* copyright: Copyright & Permissions.
+* cropmarks: Cropmarks and Magnification.
+* defcodeindex: New Indices.
+* defcv: Abstract Objects.
+* deffn: Functions Commands.
+* deffnx: deffnx.
+* defindex: New Indices.
+* definfoenclose: definfoenclose.
+* defivar: Abstract Objects.
+* defmac: Functions Commands.
+* defmethod: Abstract Objects.
+* defop: Abstract Objects.
+* defopt: Variables Commands.
+* defspec: Functions Commands.
+* deftp: Data Types.
+* deftypefn: Typed Functions.
+* deftypefun: Typed Functions.
+* deftypeivar: Abstract Objects.
+* deftypeop: Abstract Objects.
+* deftypevar: Typed Variables.
+* deftypevr: Typed Variables.
+* defun: Functions Commands.
+* defvar: Variables Commands.
+* defvr: Variables Commands.
+* Development/Docs/Texinfo Customize group: Texinfo Mode Printing.
+* dfn: dfn.
+* dircategory: Installing Dir Entries.
+* direntry: Installing Dir Entries.
+* display: display.
+* dmn: dmn.
+* documentencoding: documentencoding.
+* documentlanguage: documentlanguage.
+* dotaccent: Inserting Accents.
+* dotless: Inserting Accents.
+* dots: dots.
+* email: email.
+* emph: emph & strong.
+* end <1>: Introducing Lists.
+* end: Quotations and Examples.
+* end titlepage: end titlepage.
+* enddots: dots.
+* enumerate: enumerate.
+* env: env.
+* equiv: Equivalence.
+* error: Error Glyph.
+* evenfooting: Custom Headings.
+* evenheading: Custom Headings.
+* everyfooting: Custom Headings.
+* everyheading: Custom Headings.
+* example: example.
+* exampleindent: exampleindent.
+* exclamdown: Inserting Accents.
+* exdent: exdent.
+* expansion: expansion.
+* file: file.
+* filll: Copyright & Permissions.
+* finalout: Overfull hboxes.
+* findex: Indexing Commands.
+* flushleft: flushleft & flushright.
+* flushright: flushleft & flushright.
+* foobar: Optional Arguments.
+* footnote: Footnotes.
+* footnotestyle: Footnote Styles.
+* format: format.
+* forward-word: Def Cmd Template.
+* ftable: ftable vtable.
+* group: group.
+* H: Inserting Accents.
+* hbox: Overfull hboxes.
+* heading: unnumberedsec appendixsec heading.
+* headings: headings on off.
+* headword: definfoenclose.
+* html: Raw Formatter Commands.
+* hyphenation: - and hyphenation.
+* i (italic font): Fonts.
+* ifclear: ifset ifclear.
+* ifhtml <1>: Raw Formatter Commands.
+* ifhtml: Conditional Commands.
+* ifinfo: Conditional Commands.
+* ifnothtml: Conditional Not Commands.
+* ifnotinfo: Conditional Not Commands.
+* ifnottex: Conditional Not Commands.
+* ifset: ifset ifclear.
+* iftex: Conditional Commands.
+* ignore: Comments.
+* image: Images.
+* include: Using Include Files.
+* Info-validate: Running Info-Validate.
+* inforef: inforef.
+* input (TeX command): Minimum.
+* isearch-backward: deffnx.
+* isearch-forward: deffnx.
+* item <1>: itemize.
+* item <2>: table.
+* item: Multitable Rows.
+* itemize: itemize.
+* itemx: itemx.
+* kbd: kbd.
+* kbdinputstyle: kbd.
+* key: key.
+* kindex: Indexing Commands.
+* l: Inserting Accents.
+* L: Inserting Accents.
+* lisp: lisp.
+* lowersections: Raise/lower sections.
+* macro: Defining Macros.
+* mag (TeX command): Cropmarks and Magnification.
+* majorheading: majorheading & chapheading.
+* makeinfo-buffer: makeinfo in Emacs.
+* makeinfo-kill-job: makeinfo in Emacs.
+* makeinfo-recenter-output-buffer: makeinfo in Emacs.
+* makeinfo-region: makeinfo in Emacs.
+* math: math.
+* menu: Menus.
+* minus: minus.
+* multitable: Multi-column Tables.
+* need: need.
+* next-error: makeinfo in Emacs.
+* node: node.
+* noindent: noindent.
+* novalidate: Format with tex/texindex.
+* o: Inserting Accents.
+* O: Inserting Accents.
+* occur: Using occur.
+* occur-mode-goto-occurrence: Showing the Structure.
+* oddfooting: Custom Headings.
+* oddheading: Custom Headings.
* OE: Inserting Accents.
* oe: Inserting Accents.
-* Optional and repeated arguments: Optional Arguments.
-* Options for makeinfo: makeinfo options.
-* Ordinary HTML commands, using: Raw Formatter Commands.
-* Ordinary TeX commands, using: Raw Formatter Commands.
-* Other Info files' nodes: Other Info Files.
-* Outline of file structure, showing it: Showing the Structure.
-* Overfull hboxes: Overfull hboxes.
-* Overview of Texinfo: Overview.
-* Page breaks: page.
-* Page delimiter in Texinfo mode: Showing the Structure.
-* Page headings: Headings.
-* Page numbering: Headings.
-* Page sizes for books: smallbook.
-* page-delimiter: Showing the Structure.
-* Pages, starting odd: setchapternewpage.
-* Paper size, European A4: A4 Paper.
-* Paragraph indentation: paragraphindent.
-* Paragraph, marking text within: Marking Text.
-* Parsing errors: makeinfo in Emacs.
-* Part of file formatting and printing: Printing.
-* Parts of a cross reference: Cross Reference Parts.
-* Parts of a master menu: Master Menu Parts.
-* Parts of a menu: Menu Parts.
-* Periods, inserting: Not Ending a Sentence.
-* Permissions: Sample Permissions.
-* Permissions, printed: Copyright & Permissions.
-* Picas: Images.
-* Pictures, inserting: Images.
-* Pinard, Franc,ois: Acknowledgements.
-* plain TeX: Raw Formatter Commands.
-* Point, indicating it in a buffer: Point Glyph.
-* Pointer creation with makeinfo: makeinfo Pointer Creation.
-* Pointer validation with makeinfo: Pointer Validation.
-* Points (dimension): Images.
-* Predefined indexing commands: Indexing Commands.
-* Predefined names for indices: syncodeindex.
-* Preparing to use TeX: Preparing for TeX.
-* Preventing line and page breaks: Breaks.
-* Previous node of Top node: First Node.
-* Print and format in Texinfo mode: Texinfo Mode Printing.
-* Print, format from Emacs shell: Within Emacs.
-* Printed book and manual characteristics: Printed Books.
-* Printed output, indicating it: Print Glyph.
-* Printed permissions: Copyright & Permissions.
-* Printing a region or buffer: Printing.
-* Printing an index: Printing Indices & Menus.
-* Printing cropmarks: Cropmarks and Magnification.
-* Problems, catching: Catching Mistakes.
-* Prototype row, column widths defined by: Multitable Column Widths.
-* Quotations: quotation.
-* Raising and lowering sections: Raise/lower sections.
-* Raw formatter commands: Raw Formatter Commands.
-* Recommended names for keys: key.
-* Rectangle, ugly, black in hardcopy: Overfull hboxes.
-* Recursion, mutual: Defining Macros.
-* References: Cross References.
-* References using @inforef: inforef.
-* References using @pxref: pxref.
-* References using @ref: ref.
-* References using @xref: xref.
-* Referring to other Info files: Other Info Files.
-* Refilling paragraphs: Refilling Paragraphs.
-* Region formatting and printing: Printing.
-* Region printing in Texinfo mode: Texinfo Mode Printing.
-* Repeated and optional arguments: Optional Arguments.
-* Required in Texinfo file: Minimum.
-* Requirements for formatting: Requirements Summary.
-* Requirements for include files: Include File Requirements.
-* Requirements for updating commands: Updating Requirements.
-* Result of an expression: result.
-* ridt.eps: Images.
-* Ring accent: Inserting Accents.
-* Rows, of a multitable: Multitable Rows.
-* Running an Info formatter: Info Formatting.
-* Running Info-validate: Using Info-validate.
-* Running makeinfo in Emacs: makeinfo in Emacs.
-* Sample @include file: Sample Include File.
-* Sample function definition: Sample Function Definition.
-* Sample Texinfo file: Short Sample.
-* Sample Texinfo file, no comments: Sample Texinfo File.
-* Scaled points: Images.
-* Section structure of a file, showing it: Showing the Structure.
-* Sections, raising and lowering: Raise/lower sections.
-* Sentence ending punctuation: Ending a Sentence.
-* Sentence non-ending punctuation: Not Ending a Sentence.
-* Separate footnote style: Footnote Styles.
-* Sharp S: Inserting Accents.
-* Shell formatting with tex and texindex: Format with tex/texindex.
-* Shell, format, print from: Within Emacs.
-* Shell, running makeinfo in: makeinfo in Emacs.
-* Short nodes for menus: Menu Location.
-* Showing the section structure of a file: Showing the Structure.
-* Showing the structure of a file: Using texinfo-show-structure.
-* Site-wide Texinfo configuration file: Preparing for TeX.
-* Size of printed book: smallbook.
-* slanted typewriter font, for @kbd: kbd.
-* Small book example: smallexample & smalllisp.
-* Small book size: smallbook.
-* Small caps font: Smallcaps.
-* Software copying permissions: Software Copying Permissions.
-* Sorting indices: Format/Print Hardcopy.
-* Spaces (blank lines): sp.
-* Spacing, inserting: Inserting Space.
-* Special characters, commands to insert: Braces Atsigns.
-* Special insertions: Insertions.
-* Special typesetting commands: Dots Bullets.
-* Specifying index entries: Indexing Commands.
-* Splitting an Info file manually: Splitting.
+* option: option.
+* page: page.
+* page, within @titlepage: titlepage.
+* pagesizes: pagesizes.
+* paragraphindent: paragraphindent.
+* phoo: definfoenclose.
+* pindex: Indexing Commands.
+* point: Point Glyph.
+* pounds: pounds.
+* print: Print Glyph.
+* printindex: Printing Indices & Menus.
+* pxref: pxref.
+* questiondown: Inserting Accents.
+* quotation: quotation.
+* r (Roman font): Fonts.
+* raisesections: Raise/lower sections.
+* ref: ref.
+* refill: Refilling Paragraphs.
+* result: result.
+* ringaccent: Inserting Accents.
+* rmacro: Defining Macros.
+* samp: samp.
+* sc (small caps font): Smallcaps.
+* section: section.
+* set: ifset ifclear.
+* setchapternewpage: setchapternewpage.
+* setcontentsaftertitlepage: Contents.
+* setfilename: setfilename.
+* setshortcontentsaftertitlepage: Contents.
+* settitle: settitle.
+* shortcontents: Contents.
+* shorttitlepage: titlepage.
+* smallbook: smallbook.
+* smalldisplay <1>: small.
+* smalldisplay: display.
+* smallexample: small.
+* smallformat <1>: small.
+* smallformat: format.
+* smalllisp: small.
+* sp (line spacing): sp.
+* sp (titlepage line spacing): titlefont center sp.
* ss: Inserting Accents.
-* Stallman, Richard M.: Acknowledgements.
-* Start of header line: Start of Header.
-* Starting chapters: setchapternewpage.
-* Structure of a file, showing it: Showing the Structure.
-* Structure, catching mistakes in: Catching Mistakes.
-* Structuring of chapters: Structuring.
-* Subsection-like commands: unnumberedsubsec appendixsubsec subheading.
-* Subsub commands: subsubsection.
-* Syntactic conventions: Conventions.
-* Syntax, optional & repeated arguments: Optional Arguments.
+* strong: emph & strong.
+* subheading: unnumberedsubsec appendixsubsec subheading.
+* subsection: subsection.
+* subsubheading: subsubsection.
+* subsubsection: subsubsection.
+* subtitle: title subtitle author.
+* summarycontents: Contents.
+* syncodeindex: syncodeindex.
+* synindex: synindex.
+* t (typewriter font): Fonts.
* tab: Multitable Rows.
-* Table of contents: Contents.
-* Tables and lists, making: Lists and Tables.
-* Tables with indexes: ftable vtable.
-* Tables, making multi-column: Multi-column Tables.
-* Tables, making two-column: Two-column Tables.
-* Tabs; don't use!: Conventions.
-* Tag table, making automatically: Tag and Split Files.
-* Tag table, making manually: Unsplit.
-* Template for a definition: Def Cmd Template.
-* TeX commands, using ordinary: Raw Formatter Commands.
-* TeX index sorting: Format/Print Hardcopy.
-* TeX input initialization: Preparing for TeX.
-* TeX, how to obtain: Obtaining TeX.
-* texi2dvi: Format with tex/texindex.
-* texi2dvi (shell script): Format with texi2dvi.
-* texindex <1>: Format/Print Hardcopy.
-* texindex: Format with tex/texindex.
-* Texinfo commands, defining new: Macros.
-* Texinfo file beginning: Beginning a File.
-* Texinfo file ending: Ending a File.
-* Texinfo file header: Header.
-* Texinfo file minimum: Minimum.
-* Texinfo file section structure, showing it: Showing the Structure.
-* Texinfo mode: Texinfo Mode.
-* Texinfo overview: Overview.
-* Texinfo printed book characteristics: Printed Books.
-* texinfo.cnf <1>: A4 Paper.
-* texinfo.cnf: setfilename.
-* texinfo.cnf installation: Preparing for TeX.
-* texinfo.tex, installing: Preparing for TeX.
-* TEXINPUTS: Preparing for TeX.
-* TEXINPUTS environment variable: Preparing for TeX.
-* Text, conditionally visible: Conditionals.
-* Thin space between number, dimension: dmn.
-* Tie-after accent: Inserting Accents.
-* Tilde accent: Inserting Accents.
-* Tips: Tips.
-* Title page: titlepage.
-* Titlepage end starts headings: end titlepage.
-* Titlepage permissions: Titlepage Permissions.
-* Top node: The Top Node.
-* Top node is first: First Node.
-* Top node naming for references: Top Node Naming.
-* Top node summary: Top Node Summary.
-* Tree structuring: Tree Structuring.
-* Two `First' Lines for @deffn: deffnx.
-* Two letter names for indices: syncodeindex.
-* Two named items for @table: itemx.
-* Two part menu entry: Less Cluttered Menu Entry.
-* Typesetting commands for dots, etc.: Dots Bullets.
-* Umlaut accent: Inserting Accents.
-* Uncluttered menu entry: Less Cluttered Menu Entry.
-* Undefining macros: Defining Macros.
-* Underbar accent: Inserting Accents.
-* Underdot accent: Inserting Accents.
-* Uniform resource locator, indicating: url.
-* Uniform resource locator, referring to: uref.
-* Unique nodename requirement: Node Line Requirements.
-* Unprocessed text: Comments.
-* Unsplit file creation: Unsplit.
-* Up node of Top node: First Node.
-* Updating nodes and menus: Updating Nodes and Menus.
-* Updating requirements: Updating Requirements.
-* URL, indicating: url.
-* URL, referring to: uref.
-* Usage tips: Tips.
-* user input: kbd.
-* User options, marking: Variables Commands.
-* User-defined Texinfo commands: Macros.
-* Validating a large file: Using Info-validate.
-* Validation of pointers: Pointer Validation.
-* Value of an expression, indicating: result.
-* version number, finding: Invoking install-info.
-* Vertical whitespace (vskip): Copyright & Permissions.
-* Vertically holding text together: group.
-* Visibility of conditional text: Conditionals.
-* Weisshaus, Melissa: Acknowledgements.
-* Whitespace, inserting <1>: Inserting Space.
-* Whitespace, inserting: Multiple Spaces.
-* Width of images: Images.
-* Widths, defining multitable column: Multitable Column Widths.
-* Wildcards: Format with tex/texindex.
-* Words and phrases, marking them: Marking Text.
-* Writing a menu: Writing a Menu.
-* Writing an @node line: Writing a Node.
-* Writing index entries: Indexing Commands.
-* Zuhn, David D.: Acknowledgements.
-
+* table: Two-column Tables.
+* tex: Raw Formatter Commands.
+* tex (command): tex.
+* texinfo-all-menus-update: Updating Commands.
+* texinfo-every-node-update: Updating Commands.
+* texinfo-format-buffer <1>: texinfo-format commands.
+* texinfo-format-buffer <2>: Info Formatting.
+* texinfo-format-buffer: texinfo-format commands.
+* texinfo-format-region <1>: texinfo-format commands.
+* texinfo-format-region <2>: Info Formatting.
+* texinfo-format-region: texinfo-format commands.
+* texinfo-indent-menu-description: Other Updating Commands.
+* texinfo-insert-@code: Inserting.
+* texinfo-insert-@dfn: Inserting.
+* texinfo-insert-@end: Inserting.
+* texinfo-insert-@example: Inserting.
+* texinfo-insert-@item: Inserting.
+* texinfo-insert-@kbd: Inserting.
+* texinfo-insert-@node: Inserting.
+* texinfo-insert-@noindent: Inserting.
+* texinfo-insert-@samp: Inserting.
+* texinfo-insert-@table: Inserting.
+* texinfo-insert-@var: Inserting.
+* texinfo-insert-braces: Inserting.
+* texinfo-insert-node-lines: Other Updating Commands.
+* texinfo-make-menu: Updating Commands.
+* texinfo-master-menu: Updating Commands.
+* texinfo-multiple-files-update: texinfo-multiple-files-update.
+* texinfo-multiple-files-update (in brief): Other Updating Commands.
+* texinfo-sequential-node-update: Other Updating Commands.
+* texinfo-show-structure <1>: Using texinfo-show-structure.
+* texinfo-show-structure: Showing the Structure.
+* texinfo-start-menu-description: Inserting.
+* texinfo-tex-buffer: Printing.
+* texinfo-tex-print: Printing.
+* texinfo-tex-region: Printing.
+* texinfo-update-node: Updating Commands.
+* thischapter: Custom Headings.
+* thischaptername: Custom Headings.
+* thisfile: Custom Headings.
+* thispage: Custom Headings.
+* thistitle: Custom Headings.
+* tieaccent: Inserting Accents.
+* tindex: Indexing Commands.
+* title: title subtitle author.
+* titlefont: titlefont center sp.
+* titlepage: titlepage.
+* today: Custom Headings.
+* top (@-command): makeinfo top command.
+* u: Inserting Accents.
+* ubaraccent: Inserting Accents.
+* udotaccent: Inserting Accents.
+* unmacro: Defining Macros.
+* unnumbered: unnumbered & appendix.
+* unnumberedsec: unnumberedsec appendixsec heading.
+* unnumberedsubsec: unnumberedsubsec appendixsubsec subheading.
+* unnumberedsubsubsec: subsubsection.
+* up-list: Inserting.
+* uref: uref.
+* url: url.
+* v: Inserting Accents.
+* value: set value.
+* var: var.
+* vindex: Indexing Commands.
+* vskip: Copyright & Permissions.
+* vtable: ftable vtable.
+* w (prevent line break): w.
+* xref: xref.
+* { (single {): Inserting Braces.
+* } (single }): Inserting Braces.
+* ~: Inserting Accents.
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header
+
+`@setfilename'
+--------------
+
+ In order to serve as the primary input file for either `makeinfo' or
+TeX, a Texinfo file must contain a line that looks like this:
+
+ @setfilename INFO-FILE-NAME
+
+ Write the `@setfilename' command at the beginning of a line and
+follow it on the same line by the Info file name. Do not write anything
+else on the line; anything on the line after the command is considered
+part of the file name, including what would otherwise be a comment.
+
+ The `@setfilename' line specifies the name of the output file to be
+generated. This name should be different from the name of the Texinfo
+file. There are two conventions for choosing the name: you can either
+remove the extension (such as `.texi') from the input file name, or
+replace it with the `.info' extension. When producing HTML output,
+`makeinfo' will replace any extension with `html', or add `.html' if
+the given name has no extension.
+
+ Some operating systems cannot handle long file names. You can run
+into a problem even when the file name you specify is itself short
+enough. This occurs because the Info formatters split a long Info file
+into short indirect subfiles, and name them by appending `-1', `-2',
+..., `-10', `-11', and so on, to the original file name. (*Note Tag
+Files and Split Files: Tag and Split Files.) The subfile name
+`texinfo.info-10', for example, is too long for some systems; so the
+Info file name for this document is `texinfo' rather than
+`texinfo.info'. When `makeinfo' is running on operating systems such
+as MS-DOS which impose grave limits on file names, it will sometimes
+remove some characters from the original file name to leave enough
+space for the subfile suffix, thus producing files named `texin-10',
+`gcc.i12', etc.
+
+ The Info formatting commands ignore everything written before the
+`@setfilename' line, which is why the very first line of the file (the
+`\input' line) does not show up in the output.
+
+ The `@setfilename' line produces no output when you typeset a manual
+with TeX, but it is nevertheless essential: it opens the index,
+cross-reference, and other auxiliary files used by Texinfo, and also
+reads `texinfo.cnf' if that file is present on your system (*note
+Preparing for TeX: Preparing for TeX.).
+
+\1f
+File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header
+
+`@settitle'
+-----------
+
+ In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
+ @settitle TITLE
+
+ Write the `@settitle' command at the beginning of a line and follow
+it on the same line by the title. This tells TeX the title to use in a
+header or footer. Do not write anything else on the line; anything on
+the line after the command is considered part of the title, including a
+comment.
+
+ Conventionally, when TeX formats a Texinfo file for double-sided
+output, the title is printed in the left-hand (even-numbered) page
+headings and the current chapter title is printed in the right-hand
+(odd-numbered) page headings. (TeX learns the title of each chapter
+from each `@chapter' command.) Page footers are not printed.
+
+ Even if you are printing in a single-sided style, TeX looks for an
+`@settitle' command line, in case you include the manual title in the
+heading.
+
+ The `@settitle' command should precede everything that generates
+actual output in TeX.
+
+ Although the title in the `@settitle' command is usually the same as
+the title on the title page, it does not affect the title as it appears
+on the title page. Thus, the two do not need not match exactly; and
+the title in the `@settitle' command can be a shortened or expanded
+version of the title as it appears on the title page. (*Note
+`@titlepage': titlepage.)
+
+ TeX prints page headings only for that text that comes after the
+`@end titlepage' command in the Texinfo file, or that comes after an
+`@headings' command that turns on headings. (*Note The `@headings'
+Command: headings on off, for more information.)
+
+ You may, if you wish, create your own, customized headings and
+footings. *Note Page Headings: Headings, for a detailed discussion of
+this process.
+
+\1f
File: texinfo.info, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header
`@setchapternewpage'
--------------------
- In a book or a manual, text is usually printed on both sides of the
-paper, chapters start on right-hand pages, and right-hand pages have
+ In an officially bound book, text is usually printed on both sides of
+the paper, chapters start on right-hand pages, and right-hand pages have
odd numbers. But in short reports, text often is printed only on one
side of the paper. Also in short reports, chapters sometimes do not
start on new pages, but are printed on the same page as the end of the
preceding chapter, after a small amount of vertical whitespace.
You can use the `@setchapternewpage' command with various arguments
-to specify how TeX should start chapters and whether it should typeset
-pages for printing on one or both sides of the paper (single-sided or
+to specify how TeX should start chapters and whether it should format
+headers for printing on one or both sides of the paper (single-sided or
double-sided printing).
Write the `@setchapternewpage' command at the beginning of a line
see *Note The `@headings' Command: headings on off.)
`@setchapternewpage on'
- Cause TeX to start new chapters on new pages and to typeset page
+ Cause TeX to start new chapters on new pages and to format page
headers for single-sided printing. This is the form most often
- used for short reports.
+ used for short reports or personal printing.
This alternative is the default.
(right-handed pages) and to typeset for double-sided printing.
This is the form most often used for books and manuals.
-Texinfo does not have an `@setchapternewpage even' command.
+ Texinfo does not have an `@setchapternewpage even' command.
-(You can countermand or modify an `@setchapternewpage' command with an
-`@headings' command. *Note The `@headings' Command: headings on off.)
+ You can countermand or modify the effect on headers of an
+`@setchapternewpage' command with an `@headings' command. *Note The
+`@headings' Command: headings on off.
At the beginning of a manual or book, pages are not numbered--for
example, the title and copyright pages of a book are not numbered. By
Since an Info file does not have pages, the `@setchapternewpage'
command has no effect on it.
- Usually, you do not write an `@setchapternewpage' command for
-single-sided printing, but accept the default which is to typeset for
-single-sided printing and to start new chapters on new pages. Usually,
-you write an `@setchapternewpage odd' command for double-sided printing.
+ We recommend not including any `@setchapternewpage' command in your
+manual sources at all, since the desired output is not intrinsic to the
+document. Instead, if you don't want the default option (no blank
+pages, same headers on all pages) use the `--texinfo' option to
+`texi2dvi' to specify the output you want.
\1f
-File: texinfo.info, Node: paragraphindent, Next: End of Header, Prev: setchapternewpage, Up: Header
+File: texinfo.info, Node: paragraphindent, Next: exampleindent, Prev: setchapternewpage, Up: Header
Paragraph Indenting
-------------------
- The Info formatting commands may insert spaces at the beginning of the
-first line of each paragraph, thereby indenting that paragraph. You
-can use the `@paragraphindent' command to specify the indentation.
-Write an `@paragraphindent' command at the beginning of a line followed
-by either `asis' or a number. The template is:
+ The Texinfo processors may insert whitespace at the beginning of the
+first line of each paragraph, thereby indenting that paragraph. You can
+use the `@paragraphindent' command to specify this indentation. Write
+an `@paragraphindent' command at the beginning of a line followed by
+either `asis' or a number:
@paragraphindent INDENT
- The Info formatting commands indent according to the value of INDENT:
+ The indentation is according to the value of INDENT:
- * If the value of INDENT is `asis', the Info formatting commands do
- not change the existing indentation.
+`asis'
+ Do not change the existing indentation (not implemented in TeX).
- * If the value of INDENT is zero, the Info formatting commands delete
- existing indentation.
+0
+ Omit all indentation.
- * If the value of INDENT is greater than zero, the Info formatting
- commands indent the paragraph by that number of spaces.
+N
+ Indent by N space characters in Info output, by N ems in TeX.
- The default value of INDENT is `asis'.
+ The default value of INDENT is `asis'. `@paragraphindent' is ignored
+for HTML output.
Write the `@paragraphindent' command before or shortly after the
end-of-header line at the beginning of a Texinfo file. (If you write
A peculiarity of the `texinfo-format-buffer' and
`texinfo-format-region' commands is that they do not indent (nor fill)
paragraphs that contain `@w' or `@*' commands. *Note Refilling
-Paragraphs::, for a detailed description of what goes on.
+Paragraphs::, for further information.
\1f
-File: texinfo.info, Node: End of Header, Prev: paragraphindent, Up: Header
+File: texinfo.info, Node: exampleindent, Next: End of Header, Prev: paragraphindent, Up: Header
+
+`@exampleindent': Environment Indenting
+---------------------------------------
+
+ The Texinfo processors indent each line of `@example' and similar
+environments. You can use the `@exampleindent' command to specify this
+indentation. Write an `@exampleindent' command at the beginning of a
+line followed by either `asis' or a number:
+
+ @exampleindent INDENT
+
+ The indentation is according to the value of INDENT:
+
+`asis'
+ Do not change the existing indentation (not implemented in TeX).
+
+0
+ Omit all indentation.
+
+N
+ Indent environments by N space characters in Info output, by N ems
+ in TeX.
+
+ The default value of INDENT is 5. `@exampleindent' is ignored for
+HTML output.
+
+ Write the `@exampleindent' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you write
+the command between the start-of-header and end-of-header lines, the
+region formatting commands indent examples as specified.)
+
+\1f
+File: texinfo.info, Node: End of Header, Prev: exampleindent, Up: Header
End of Header
-------------
appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
Permissions, for the complete text.
- The permissions text appears in an Info file *before* the first node.
-This mean that a reader does *not* see this text when reading the file
+ The permissions text appears in an Info file _before_ the first node.
+This mean that a reader does _not_ see this text when reading the file
using Info, except when using the advanced Info command `g *'.
\1f
contains the text of the copying permissions that will appear in the
printed manual.
+ You may wish to include titlepage-like information for plain text
+output. Simply place any such leading material between `@ifinfo' and
+`@end ifinfo'; `makeinfo' includes this in its plain text output. It
+will not show up in the Info readers.
+
*Note Titlepage Copying Permissions: Titlepage Permissions, for the
standard text for the copyright permissions.
numbering. (*Note Page Headings: Headings, for details about how to
generate page headings.) All the material that you want to appear on
unnumbered pages should be put between the `@titlepage' and `@end
-titlepage' commands. By using the `@page' command you can force a page
-break within the region delineated by the `@titlepage' and `@end
-titlepage' commands and thereby create more than one unnumbered page.
-This is how the copyright page is produced. (The `@titlepage' command
-might perhaps have been better named the `@titleandadditionalpages'
-command, but that would have been rather long!)
+titlepage' commands. You can force the table of contents to appear
+there with the `@setcontentsaftertitlepage' command (*note Contents::).
+
+ By using the `@page' command you can force a page break within the
+region delineated by the `@titlepage' and `@end titlepage' commands and
+thereby create more than one unnumbered page. This is how the
+copyright page is produced. (The `@titlepage' command might perhaps
+have been better named the `@titleandadditionalpages' command, but that
+would have been rather long!)
When you write a manual about a computer program, you should write the
version of the program to which the manual applies on the title page.
-If the manual changes more frequently than the program or is
-independent of it, you should also include an edition number(1) (*note
-titlepage-Footnotes::) for the manual. This helps readers keep track
+If the manual changes more frequently than the program or is independent
+of it, you should also include an edition number(1) (*note
+titlepage-Footnote-1::) for the manual. This helps readers keep track
of which manual is for which version of the program. (The `Top' node
should also contain this information; see *Note `@top': makeinfo top.)
author lines and the subtitle text set flush to the right hand side of
the page. With this method, you do not specify any of the actual
formatting of the title page. You specify the text you want, and
-Texinfo does the formatting. You may use either method.
+Texinfo does the formatting.
+
+ You may use either method, or you may combine them; see the examples
+in the sections below.
- For extremely simple applications, Texinfo also provides a command
+ For extremely simple applications, and for the bastard title page in
+traditional book front matter, Texinfo also provides a command
`@shorttitlepage' which takes a single argument as the title. The
argument is typeset on a page by itself and followed by a blank page.
methods for creating a title page in Texinfo.)
Use the `@titlefont' command to select a large font suitable for the
-title itself.
+title itself. You can use `@titlefont' more than once if you have an
+especially long title.
For example:
...
@end titlepage
- The spacing of the example fits an 8 1/2 by 11 inch manual.
+ The spacing of the example fits an 8.5 by 11 inch manual.
\1f
File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page
You can use the `@title', `@subtitle', and `@author' commands to
create a title page in which the vertical and horizontal spacing is
-done for you automatically. This contrasts with the method described in
-the previous section, in which the `@sp' command is needed to adjust
+done for you automatically. This contrasts with the method described
+in the previous section, in which the `@sp' command is needed to adjust
vertical spacing.
Write the `@title', `@subtitle', or `@author' commands at the
The `@title' command produces a line in which the title is set flush
to the left-hand side of the page in a larger than normal font. The
-title is underlined with a black rule.
+title is underlined with a black rule. Only a single line is allowed;
+the `@*' command may not be used to break the title into two lines. To
+handle very long titles, you may find it profitable to use both
+`@title' and `@titlefont'; see the final example in this section.
The `@subtitle' command sets subtitles in a normal-sized font flush
to the right-hand side of the page.
...
@end titlepage
-Contrast this form with the form of a title page written using the
-`@sp', `@center', and `@titlefont' commands:
+ You may also combine the `@titlefont' method described in the
+previous section and `@title' method described in this one. This may
+be useful if you have a very long title. Here is a real-life example:
@titlepage
- @sp 10
- @center @titlefont{Name of Manual When Printed}
- @sp 2
- @center Subtitle, If Any
+ @titlefont{GNU Software}
@sp 1
- @center Second subtitle
- @sp 2
- @center Author
- @page
- ...
- @end titlepage
+ @title for MS-Windows and MS-DOS
+ @subtitle Edition @value{edition} for Release @value{cd-edition}
+ @author by Daniel Hagerty, Melissa Weisshaus
+ @author and Eli Zaretskii
+
+(The use of `@value' here is explained in *Note `@value' Example: value
+Example.)
\1f
File: texinfo.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page
It is customary to put information on how to get a manual after the
copyright notice, followed by the copying permissions for the manual.
- Note that permissions must be given here as well as in the summary
-segment within `@ifinfo' and `@end ifinfo' that immediately follows the
-header since this text appears only in the printed manual and the
-`ifinfo' text appears only in the Info file.
+ Permissions must be given here as well as in the summary segment
+within `@ifinfo' and `@end ifinfo' that immediately follows the header
+since this text appears only in the printed manual and the `ifinfo'
+text appears only in the Info file.
*Note Sample Permissions::, for the standard text.
Turn on page headings appropriate for single-sided printing.
`@headings double'
+`@headings on'
Turn on page headings appropriate for double-sided printing. The
two commands, `@headings on' and `@headings double', are
synonymous.
* Master Menu Parts:: A master menu has three or more parts.
\1f
-File: texinfo.info, Node: Title of Top Node, Next: Master Menu Parts, Prev: The Top Node, Up: The Top Node
+File: texinfo.info, Node: Title of Top Node, Next: Master Menu Parts, Up: The Top Node
`Top' Node Title
----------------
...
@end titlepage
- @ifinfo
+ @ifnottex
@node Top, Copying, , (dir)
@top Texinfo
This is edition...
...
- @end ifinfo
+ @end ifnottex
@menu
* Copying:: Texinfo is freely
Ending a Texinfo File
*********************
- The end of a Texinfo file should include the commands that create
-indices and generate detailed and summary tables of contents. And it
-must include the `@bye' command that marks the last line processed by
-TeX.
+ The end of a Texinfo file should include commands to create indices
+and (usually) to generate detailed and summary tables of contents. And
+it must include the `@bye' command that marks the last line processed
+by TeX.
For example:
generate an index, you must include the `@printindex' command at the
place in the document where you want the index to appear. Also, as
part of the process of creating a printed manual, you must run a
-program called `texindex' (*note Format/Print Hardcopy::.) to sort the
-raw data to produce a sorted index file. The sorted index file is what
-is actually used to print the index.
+program called `texindex' (*note Hardcopy::) to sort the raw data to
+produce a sorted index file. The sorted index file is what is actually
+used to print the index.
Texinfo offers six different types of predefined index: the concept
index, the function index, the variables index, the keystroke index, the
-program index, and the data type index (*note Predefined Indices::.).
+program index, and the data type index (*note Predefined Indices::).
Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
and `tp'. You may merge indices, or put them into separate sections
-(*note Combining Indices::.); or you may define your own indices (*note
+(*note Combining Indices::); or you may define your own indices (*note
Defining New Indices: New Indices.).
The `@printindex' command takes a two-letter index name, reads the
@unnumbered Variable Index
@printindex vr
-
+
@node Concept Index, , Variable Index, Top
@comment node-name, next, previous, up
@unnumbered Concept Index
@printindex cp
- @summarycontents
- @contents
- @bye
-
-(Readers often prefer that the concept index come last in a book, since
-that makes it easiest to find.)
+Readers often prefer that the concept index come last in a book, since
+that makes it easiest to find. Having just one index helps readers
+also, since then they have only one place to look (*note synindex::).
\1f
File: texinfo.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File
The `@chapter', `@section', and other structuring commands supply the
information to make up a table of contents, but they do not cause an
actual table to appear in the manual. To do this, you must use the
-`@contents' and `@summarycontents' commands:
+`@contents' and/or `@summarycontents' command(s).
`@contents'
Generate a table of contents in a printed manual, including all
chapters, sections, subsections, etc., as well as appendices and
unnumbered chapters. (Headings generated by the `@heading' series
- of commands do not appear in the table of contents.) The
- `@contents' command should be written on a line by itself.
+ of commands do not appear in the table of contents.)
`@shortcontents'
`@summarycontents'
subsections and subsubsections. Only a long manual needs a short
table of contents in addition to the full table of contents.
- Write the `@shortcontents' command on a line by itself right
- *before* the `@contents' command.
-
- The table of contents commands automatically generate a chapter-like
-heading at the top of the first table of contents page. Write the table
-of contents commands at the very end of a Texinfo file, just before the
-`@bye' command, following any index sections--anything in the Texinfo
-file after the table of contents commands will be omitted from the
-table of contents.
-
- When you print a manual with a table of contents, the table of
-contents are printed last and numbered with roman numerals. You need
-to place those pages in their proper place, after the title page,
-yourself. (This is the only collating you need to do for a printed
-manual. The table of contents is printed last because it is generated
-after the rest of the manual is typeset.)
-
- Here is an example of where to write table of contents commands:
-
- INDICES...
- @shortcontents
- @contents
- @bye
+ Both contents commands should be written on a line by themselves.
+The contents commands automatically generate a chapter-like heading at
+the top of the first table of contents page, so don't include any
+sectioning command such as `@unnumbered' before them.
Since an Info file uses menus instead of tables of contents, the Info
-formatting commands ignore the `@contents' and `@shortcontents'
-commands.
+formatting commands ignore the contents commands. But the contents are
+included in plain text output (generated by `makeinfo --no-headers').
+
+ The contents commands can be placed either at the very end of the
+file, after any indices (see the previous section) and just before the
+`@bye' (see the next section), or near the beginning of the file, after
+the `@end titlepage' (*note titlepage::). The advantage to the former
+is that then the contents output is always up to date, because it
+reflects the processing just done. The advantage to the latter is that
+the contents are printed in the proper place, thus you do not need to
+rearrange the DVI file with `dviselect' or shuffle paper. However,
+contents commands at the beginning of the document are ignored when
+outputting to standard output.
+
+ As an author, you can put the contents commands wherever you prefer.
+But if you are a user simply printing a manual, you may wish to print
+the contents after the title page even if the author put the contents
+commands at the end of the document (as is the case in most existing
+Texinfo documents). You can do this by specifying
+`@setcontentsaftertitlepage' and/or `@setshortcontentsaftertitlepage'.
+The first prints only the main contents after the `@end titlepage'; the
+second prints both the short contents and the main contents. In either
+case, any subsequent `@contents' or `@shortcontents' is ignored (unless
+no `@end titlepage' is ever encountered).
+
+ You need to include the `@set...contentsaftertitlepage' commands
+early in the document (just after `@setfilename', for example). Or, if
+you're using `texi2dvi' (*note Format with texi2dvi::), you can use its
+`--texinfo' option to specify this without altering the source file at
+all. For example:
+ texi2dvi --texinfo=@setshortcontentsaftertitlepage foo.texi
\1f
File: texinfo.info, Node: File End, Prev: Contents, Up: Ending a File
The chapter structuring commands do not create an Info node structure,
so normally you should put an `@node' command immediately before each
-chapter structuring command (*note Nodes::.). The only time you are
+chapter structuring command (*note Nodes::). The only time you are
likely to use the chapter structuring commands without using the node
structuring commands is if you are writing a document that contains no
cross references and will never be transformed into Info format.
* Raise/lower sections:: How to change commands' hierarchical level.
\1f
-File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Prev: Structuring, Up: Structuring
+File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Up: Structuring
Tree Structure of Sections
==========================
\1f
File: texinfo.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring
-Types of Structuring Commands
-=============================
+Structuring Command Types
+=========================
The chapter structuring commands fall into four groups or series, each
of which contains structuring commands corresponding to the
Here are the four groups of chapter structuring commands:
- No new pages
- Numbered Unnumbered Lettered and numbered Unnumbered
- In contents In contents In contents Not in contents
-
- @top @majorheading
- @chapter @unnumbered @appendix @chapheading
- @section @unnumberedsec @appendixsec @heading
- @subsection @unnumberedsubsec @appendixsubsec @subheading
- @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
+ No new page
+Numbered Unnumbered Lettered and numbered Unnumbered
+In contents In contents In contents Not in contents
+ `@top' `@majorheading'
+`@chapter' `@unnumbered' `@appendix' `@chapheading'
+`@section' `@unnumberedsec' `@appendixsec' `@heading'
+`@subsection' `@unnumberedsubsec' `@appendixsubsec' `@subheading'
+`@subsubsection'`@unnumberedsubsubsec' `@appendixsubsubsec' `@subsubheading'
\1f
File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring
The `@top' command is a special sectioning command that you use only
after an `@node Top' line at the beginning of a Texinfo file. The
`@top' command tells the `makeinfo' formatter which node is the `Top'
-node. It has the same typesetting effect as `@unnumbered' (*note
-`@unnumbered': (`@appendix')unnumbered & appendix.). For detailed
-information, see *Note The `@top' Command: makeinfo top command.
+node, so it can use it as the root of the node tree if your manual uses
+implicit pointers. It has the same typesetting effect as `@unnumbered'
+(*note `@unnumbered' and `@appendix': unnumbered & appendix.). For
+detailed information, see *Note The `@top' Command: makeinfo top
+command.
+
+ The `@top' node and its menu (if any) is conventionally wrapped in an
+`@ifnottex' conditional so that it will appear only in Info and HTML
+output, not TeX.
\1f
File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring
\1f
File: texinfo.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring
-`@unnumbered', `@appendix'
-==========================
+`@unnumbered' and `@appendix'
+=============================
Use the `@unnumbered' command to create a chapter that appears in a
printed manual without chapter numbers of any kind. Use the
In a printed manual, subsections are listed in the table of contents
and are numbered three levels deep.
-\1f
-File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring
-
-The `@subsection'-like Commands
-===============================
-
- The `@unnumberedsubsec', `@appendixsubsec', and `@subheading'
-commands are, respectively, the unnumbered, appendix-like, and
-heading-like equivalents of the `@subsection' command. (*Note
-`@subsection': subsection.)
-
- In Info, the `@subsection'-like commands generate a title underlined
-with hyphens. In a printed manual, an `@subheading' command produces a
-heading like that of a subsection except that it is not numbered and
-does not appear in the table of contents. Similarly, an
-`@unnumberedsubsec' command produces an unnumbered heading like that of
-a subsection and an `@appendixsubsec' command produces a
-subsection-like heading labelled with a letter and numbers; both of
-these commands produce headings that appear in the table of contents.
-
-\1f
-File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring
-
-The `subsub' Commands
-=====================
-
- The fourth and lowest level sectioning commands in Texinfo are the
-`subsub' commands. They are:
-
-`@subsubsection'
- Subsubsections are to subsections as subsections are to sections.
- (*Note `@subsection': subsection.) In a printed manual,
- subsubsection titles appear in the table of contents and are
- numbered four levels deep.
-
-`@unnumberedsubsubsec'
- Unnumbered subsubsection titles appear in the table of contents of
- a printed manual, but lack numbers. Otherwise, unnumbered
- subsubsections are the same as subsubsections. In Info, unnumbered
- subsubsections look exactly like ordinary subsubsections.
-
-`@appendixsubsubsec'
- Conventionally, appendix commands are used only for appendices and
- are lettered and numbered appropriately in a printed manual. They
- also appear in the table of contents. In Info, appendix
- subsubsections look exactly like ordinary subsubsections.
-
-`@subsubheading'
- The `@subsubheading' command may be used anywhere that you need a
- small heading that will not appear in the table of contents. In
- Info, subsubheadings look exactly like ordinary subsubsection
- headings.
-
- In Info, `subsub' titles are underlined with periods. For example,
-
- @subsubsection This is a subsubsection
-
-produces
-
- This is a subsubsection
- .......................
-
-\1f
-File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring
-
-`@raisesections' and `@lowersections'
-=====================================
-
- The `@raisesections' and `@lowersections' commands raise and lower
-the hierarchical level of chapters, sections, subsections and the like.
-The `@raisesections' command changes sections to chapters, subsections
-to sections, and so on. The `@lowersections' command changes chapters
-to sections, sections to subsections, and so on.
-
- An `@lowersections' command is useful if you wish to include text
-that is written as an outer or standalone Texinfo file in another
-Texinfo file as an inner, included file. If you write the command at
-the beginning of the file, all your `@chapter' commands are formatted
-as if they were `@section' commands, all your `@section' command are
-formatted as if they were `@subsection' commands, and so on.
-
- `@raisesections' raises a command one level in the chapter
-structuring hierarchy:
-
- Change To
-
- @subsection @section,
- @section @chapter,
- @heading @chapheading,
- etc.
-
- `@lowersections' lowers a command one level in the chapter
-structuring hierarchy:
-
- Change To
-
- @chapter @section,
- @subsection @subsubsection,
- @heading @subheading,
- etc.
-
- An `@raisesections' or `@lowersections' command changes only those
-structuring commands that follow the command in the Texinfo file.
-Write an `@raisesections' or `@lowersections' command on a line of its
-own.
-
- An `@lowersections' command cancels an `@raisesections' command, and
-vice versa. Typically, the commands are used like this:
-
- @lowersections
- @include somefile.texi
- @raisesections
-
- Without the `@raisesections', all the subsequent sections in your
-document will be lowered.
-
- Repeated use of the commands continue to raise or lower the
-hierarchical level a step at a time.
-
- An attempt to raise above `chapters' reproduces chapter commands; an
-attempt to lower below `subsubsections' reproduces subsubsection
-commands.
-
-\1f
-File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top
-
-Nodes
-*****
-
- "Nodes" are the primary segments of a Texinfo file. They do not
-themselves impose a hierarchic or any other kind of structure on a file.
-Nodes contain "node pointers" that name other nodes, and can contain
-"menus" which are lists of nodes. In Info, the movement commands can
-carry you to a pointed-to node or to a node listed in a menu. Node
-pointers and menus provide structure for Info files just as chapters,
-sections, subsections, and the like, provide structure for printed
-books.
-
-* Menu:
-
-* Two Paths:: Different commands to structure
- Info output and printed output.
-* Node Menu Illustration:: A diagram, and sample nodes and menus.
-* node:: How to write a node, in detail.
-* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
-
-\1f
-File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Prev: Nodes, Up: Nodes
-
-Two Paths
-=========
-
- The node and menu commands and the chapter structuring commands are
-independent of each other:
-
- * In Info, node and menu commands provide structure. The chapter
- structuring commands generate headings with different kinds of
- underlining--asterisks for chapters, hyphens for sections, and so
- on; they do nothing else.
-
- * In TeX, the chapter structuring commands generate chapter and
- section numbers and tables of contents. The node and menu
- commands provide information for cross references; they do nothing
- else.
-
- You can use node pointers and menus to structure an Info file any way
-you want; and you can write a Texinfo file so that its Info output has a
-different structure than its printed output. However, most Texinfo
-files are written such that the structure for the Info output
-corresponds to the structure for the printed output. It is not
-convenient to do otherwise.
-
- Generally, printed output is structured in a tree-like hierarchy in
-which the chapters are the major limbs from which the sections branch
-out. Similarly, node pointers and menus are organized to create a
-matching structure in the Info output.
-
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring
+
+The `@subsection'-like Commands
+===============================
+
+ The `@unnumberedsubsec', `@appendixsubsec', and `@subheading'
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the `@subsection' command. (*Note
+`@subsection': subsection.)
+
+ In Info, the `@subsection'-like commands generate a title underlined
+with hyphens. In a printed manual, an `@subheading' command produces a
+heading like that of a subsection except that it is not numbered and
+does not appear in the table of contents. Similarly, an
+`@unnumberedsubsec' command produces an unnumbered heading like that of
+a subsection and an `@appendixsubsec' command produces a
+subsection-like heading labelled with a letter and numbers; both of
+these commands produce headings that appear in the table of contents.
+
+\1f
+File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring
+
+The `subsub' Commands
+=====================
+
+ The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:
+
+`@subsubsection'
+ Subsubsections are to subsections as subsections are to sections.
+ (*Note `@subsection': subsection.) In a printed manual,
+ subsubsection titles appear in the table of contents and are
+ numbered four levels deep.
+
+`@unnumberedsubsubsec'
+ Unnumbered subsubsection titles appear in the table of contents of
+ a printed manual, but lack numbers. Otherwise, unnumbered
+ subsubsections are the same as subsubsections. In Info, unnumbered
+ subsubsections look exactly like ordinary subsubsections.
+
+`@appendixsubsubsec'
+ Conventionally, appendix commands are used only for appendices and
+ are lettered and numbered appropriately in a printed manual. They
+ also appear in the table of contents. In Info, appendix
+ subsubsections look exactly like ordinary subsubsections.
+
+`@subsubheading'
+ The `@subsubheading' command may be used anywhere that you need a
+ small heading that will not appear in the table of contents. In
+ Info, subsubheadings look exactly like ordinary subsubsection
+ headings.
+
+ In Info, `subsub' titles are underlined with periods. For example,
+
+ @subsubsection This is a subsubsection
+
+produces
+
+ This is a subsubsection
+ .......................
+
+\1f
+File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring
+
+`@raisesections' and `@lowersections'
+=====================================
+
+ The `@raisesections' and `@lowersections' commands raise and lower
+the hierarchical level of chapters, sections, subsections and the like.
+The `@raisesections' command changes sections to chapters, subsections
+to sections, and so on. The `@lowersections' command changes chapters
+to sections, sections to subsections, and so on.
+
+ An `@lowersections' command is useful if you wish to include text
+that is written as an outer or standalone Texinfo file in another
+Texinfo file as an inner, included file. If you write the command at
+the beginning of the file, all your `@chapter' commands are formatted
+as if they were `@section' commands, all your `@section' command are
+formatted as if they were `@subsection' commands, and so on.
+
+ `@raisesections' raises a command one level in the chapter
+structuring hierarchy:
+
+ Change To
+
+ @subsection @section,
+ @section @chapter,
+ @heading @chapheading,
+ etc.
+
+ `@lowersections' lowers a command one level in the chapter
+structuring hierarchy:
+
+ Change To
+
+ @chapter @section,
+ @subsection @subsubsection,
+ @heading @subheading,
+ etc.
+
+ An `@raisesections' or `@lowersections' command changes only those
+structuring commands that follow the command in the Texinfo file.
+Write an `@raisesections' or `@lowersections' command on a line of its
+own.
+
+ An `@lowersections' command cancels an `@raisesections' command, and
+vice versa. Typically, the commands are used like this:
+
+ @lowersections
+ @include somefile.texi
+ @raisesections
+
+ Without the `@raisesections', all the subsequent sections in your
+document will be lowered.
+
+ Repeated use of the commands continue to raise or lower the
+hierarchical level a step at a time.
+
+ An attempt to raise above `chapters' reproduces chapter commands; an
+attempt to lower below `subsubsections' reproduces subsubsection
+commands.
+
+\1f
+File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top
+
+Nodes
+*****
+
+ "Nodes" are the primary segments of a Texinfo file. They do not
+themselves impose a hierarchical or any other kind of structure on a
+file. Nodes contain "node pointers" that name other nodes, and can
+contain "menus" which are lists of nodes. In Info, the movement
+commands can carry you to a pointed-to node or to a node listed in a
+menu. Node pointers and menus provide structure for Info files just as
+chapters, sections, subsections, and the like, provide structure for
+printed books.
+
+* Menu:
+
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
+
+\1f
+File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Up: Nodes
+
+Two Paths
+=========
+
+ The node and menu commands and the chapter structuring commands are
+technically independent of each other:
+
+ * In Info, node and menu commands provide structure. The chapter
+ structuring commands generate headings with different kinds of
+ underlining--asterisks for chapters, hyphens for sections, and so
+ on; they do nothing else.
+
+ * In TeX, the chapter structuring commands generate chapter and
+ section numbers and tables of contents. The node and menu
+ commands provide information for cross references; they do nothing
+ else.
+
+ You can use node pointers and menus to structure an Info file any way
+you want; and you can write a Texinfo file so that its Info output has a
+different structure than its printed output. However, virtually all
+Texinfo files are written such that the structure for the Info output
+corresponds to the structure for the printed output. It is neither
+convenient nor understandable to the reader to do otherwise.
+
+ Generally, printed output is structured in a tree-like hierarchy in
+which the chapters are the major limbs from which the sections branch
+out. Similarly, node pointers and menus are organized to create a
+matching structure in the Info output.
+
+\1f
File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes
Node and Menu Illustration
Here is a copy of the diagram shown earlier that illustrates a Texinfo
file with three chapters, each of which contains two sections.
- Note that the "root" is at the top of the diagram and the "leaves"
-are at the bottom. This is how such a diagram is drawn conventionally;
-it illustrates an upside-down tree. For this reason, the root node is
+ The "root" is at the top of the diagram and the "leaves" are at the
+bottom. This is how such a diagram is drawn conventionally; it
+illustrates an upside-down tree. For this reason, the root node is
called the `Top' node, and `Up' node pointers carry you closer to the
root.
Section Section Section Section Section Section
1.1 1.2 2.1 2.2 3.1 3.2
- Write the beginning of the node for Chapter 2 like this:
+ The fully-written command to start Chapter 2 would be this:
- @node Chapter 2, Chapter 3, Chapter 1, top
+ @node Chapter 2, Chapter 3, Chapter 1, Top
@comment node-name, next, previous, up
This `@node' line says that the name of this node is "Chapter 2", the
name of the `Next' node is "Chapter 3", the name of the `Previous' node
-is "Chapter 1", and the name of the `Up' node is "Top".
+is "Chapter 1", and the name of the `Up' node is "Top". You can omit
+writing out these node names if your document is hierarchically
+organized (*note makeinfo Pointer Creation::), but the pointer
+relationships still obtain.
*Please Note:* `Next' refers to the next node at the same
hierarchical level in the manual, not necessarily to the next node
within the Texinfo file. In the Texinfo file, the subsequent node
- may be at a lower level--a section-level node may follow a
- chapter-level node, and a subsection-level node may follow a
- section-level node. `Next' and `Previous' refer to nodes at the
- *same* hierarchical level. (The `Top' node contains the exception
- to this rule. Since the `Top' node is the only node at that
- level, `Next' refers to the first following node, which is almost
- always a chapter or chapter-level node.)
+ may be at a lower level--a section-level node most often follows a
+ chapter-level node, for example. `Next' and `Previous' refer to
+ nodes at the _same_ hierarchical level. (The `Top' node contains
+ the exception to this rule. Since the `Top' node is the only node
+ at that level, `Next' refers to the first following node, which is
+ almost always a chapter or chapter-level node.)
To go to Sections 2.1 and 2.2 using Info, you need a menu inside
Chapter 2. (*Note Menus::.) You would write the menu just before the
subsection, and subsubsection.
To create a node, write an `@node' command at the beginning of a
-line, and follow it with four arguments, separated by commas, on the
-rest of the same line. These arguments are the name of the node, and
-the names of the `Next', `Previous', and `Up' pointers, in that order.
-You may insert spaces before each pointer if you wish; the spaces are
-ignored. You must write the name of the node, and the names of the
-`Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
+line, and follow it with up to four arguments, separated by commas, on
+the rest of the same line. The first argument is required; it is the
+name of this node. The subsequent arguments are the names of the
+`Next', `Previous', and `Up' pointers, in that order, and may be omitted
+if your Texinfo document is hierarchically organized (*note makeinfo
+Pointer Creation::).
+
+ You may insert spaces before each name if you wish; the spaces are
+ignored. You must write the name of the node and the names of the
+`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
the formatters fail. (*note info: (info)Top, for more information
about nodes in Info.)
Usually, you write one of the chapter-structuring command lines
immediately after an `@node' line--for example, an `@section' or
-`@subsection' line. (*Note Types of Structuring Commands: Structuring
-Command Types.)
+`@subsection' line. (*Note Structuring Command Types::.)
*Please note:* The GNU Emacs Texinfo mode updating commands work
only with Texinfo files in which `@node' lines are followed by
references. For this reason, you must write `@node' lines in a Texinfo
file that you intend to format for printing, even if you do not intend
to format it for Info. (Cross references, such as the one at the end
-of this sentence, are made with `@xref' and its related commands; see
-*Note Cross References::.)
+of this sentence, are made with `@xref' and related commands; see *Note
+Cross References::.)
* Menu:
* Top Node Summary:: Write a brief description for readers.
\1f
-File: texinfo.info, Node: Node Names, Next: Writing a Node, Prev: node, Up: node
+File: texinfo.info, Node: Node Names, Next: Writing a Node, Up: node
Choosing Node and Pointer Names
-------------------------------
`Top' node. *Note First Node::, for information on how to write the
first node of a Texinfo file.
+ Even when you explicitly specify all pointers, that does not mean you
+can write the nodes in the Texinfo source file in an arbitrary order!
+Because TeX processes the file sequentially, irrespective of node
+pointers, you must write the nodes in the order you wish them to appear
+in the printed output.
+
\1f
File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node
are for which pointers. This comment line is especially useful if you
are not familiar with Texinfo.
- The template for a node line with `Next', `Previous', and `Up'
-pointers looks like this:
+ The template for a fully-written-out node line with `Next',
+`Previous', and `Up' pointers looks like this:
@node NODE-NAME, NEXT, PREVIOUS, UP
The node to which a pointer points may come before or after the
node containing the pointer.
- * You cannot use any of the Texinfo @-commands in a node name;
- @-commands confuse Info.
+ * @-commands used in node names generally confuse Info, so you should
+ avoid them. For a few rare cases when this is useful, Texinfo has
+ limited support for using @-commands in node names; see *Note
+ Pointer Validation::.
Thus, the beginning of the section called `@chapter' looks like
this:
@section @code{@@chapter}
@findex chapter
- * You cannot use commas or apostrophes within a node name; these
- confuse TeX or the Info formatters.
+ * Unfortunately, you cannot use periods, commas, colons or
+ apostrophes within a node name; these confuse TeX or the Info
+ formatters.
For example, the following is a section title:
--------------
The first node of a Texinfo file is the "Top" node, except in an
-included file (*note Include Files::.). The Top node contains the main
+included file (*note Include Files::). The Top node contains the main
or master menu for the document, and a short summary of the document
-(*note Top Node Summary::.).
+(*note Top Node Summary::).
The Top node (which must be named `top' or `Top') should have as its
`Up' node the name of a node in another file, where there is a menu
contain this information: see *Note `@titlepage': titlepage.)
\1f
-File: texinfo.info, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes
+File: texinfo.info, Node: makeinfo Pointer Creation, Next: anchor, Prev: node, Up: Nodes
Creating Pointers with `makeinfo'
=================================
- The `makeinfo' program has a feature for automatically creating node
-pointers for a hierarchically organized file that lacks them.
+ The `makeinfo' program has a feature for automatically defining node
+pointers for a hierarchically organized file.
When you take advantage of this feature, you do not need to write the
`Next', `Previous', and `Up' pointers after the name of a node.
However, you must write a sectioning command, such as `@chapter' or
`@section', on the line immediately following each truncated `@node'
-line. You cannot write a comment line after a node line; the section
-line must follow it immediately.
+line (except that comment lines may intervene).
In addition, you must follow the `Top' `@node' line with a line
-beginning with `@top' to mark the `Top' node in the file. *Note `@top':
-makeinfo top.
+beginning with `@top' to mark the `Top' node in the file. *Note
+`@top': makeinfo top.
Finally, you must write the name of each node (except for the `Top'
node) in a menu that is one or more hierarchical levels above the
node's hierarchical level.
- This node pointer insertion feature in `makeinfo' is an alternative
-to the menu and pointer creation and update commands in Texinfo mode.
-(*Note Updating Nodes and Menus::.) It is especially helpful to people
-who do not use GNU Emacs for writing Texinfo documents.
+ This node pointer insertion feature in `makeinfo' relieves you from
+the need to update menus and pointers manually or with Texinfo mode
+commands. (*Note Updating Nodes and Menus::.)
+
+\1f
+File: texinfo.info, Node: anchor, Prev: makeinfo Pointer Creation, Up: Nodes
+
+`@anchor': Defining Arbitrary Cross-reference Targets
+=====================================================
+
+ An "anchor" is a position in your document, labeled so that
+cross-references can refer to it, just as they can to nodes. You create
+an anchor with the `@anchor' command, and give the label as a normal
+brace-delimited argument. For example:
+
+ This marks the @anchor{x-spot}spot.
+ ...
+ @xref{x-spot,,the spot}.
+
+produces:
+
+ This marks the spot.
+ ...
+ See [the spot], page 1.
+
+ As you can see, the `@anchor' command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an `@xref' or other cross-reference
+command, as shown. *Note Cross References::, for details on the
+cross-reference commands.
+
+ It is best to put `@anchor' commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor. You can put the `@anchor' command
+on a line by itself if that helps readability of the source. Spaces
+are always ignored after `@anchor'.
+
+ Anchor names and node names may not conflict. Anchors and nodes are
+given similar treatment in some ways; for example, the `goto-node'
+command in standalone Info takes either an anchor name or a node name as
+an argument. (*Note goto-node: (info-stnd)goto-node.)
\1f
File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top
*****
"Menus" contain pointers to subordinate nodes.(1) (*note
-Menus-Footnotes::) In Info, you use menus to go to such nodes. Menus
+Menus-Footnote-1::) In Info, you use menus to go to such nodes. Menus
have no effect in printed manuals and do not appear in them.
By convention, a menu is put at the end of a node since a reader who
-uses the menu may not see text that follows it.
-
- A node that has a menu should *not* contain much text. If you have a
-lot of text and a menu, move most of the text into a new subnode--all
-but a few lines.
+uses the menu may not see text that follows it. Furthermore, a node
+that has a menu should not contain much text. If you have a lot of text
+and a menu, move most of the text into a new subnode--all but a few
+lines. Otherwise, a reader with a terminal that displays only a few
+lines may miss the menu and its associated text. As a practical matter,
+you should locate a menu within 20 lines of the beginning of the node.
* Menu:
Menus Need Short Nodes
======================
- A reader can easily see a menu that is close to the beginning of the
-node. The node should be short. As a practical matter, you should
-locate a menu within 20 lines of the beginning of the node. Otherwise,
-a reader with a terminal that displays only a few lines may miss the
-menu and its associated text.
-
The short text before a menu may look awkward in a printed manual. To
avoid this, you can write a menu near the beginning of its node and
follow the menu by an `@node' line, and then an `@heading' line located
The Texinfo file for this document contains more than a dozen
examples of this procedure. One is at the beginning of this chapter;
-another is at the beginning of the "Cross References" chapter.
+another is at the beginning of *Note Cross References::.
\1f
File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus
an `* ' may also appear in a menu. Such a line is not a menu entry but
is a menu comment line that appears in the Info file. In the example
above, the line `Larger Units of Text' is a menu comment line; the two
-lines starting with `* ' are menu entries.
+lines starting with `* ' are menu entries. Space characters in a menu
+are preserved as-is; this allows you to format the menu as you wish.
\1f
File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus
(The `dir' top level directory for the Info system is an Info file, not
a Texinfo file, but a menu entry looks the same in both types of file.)
- Note that the GNU Emacs Texinfo mode menu updating commands only work
-with nodes within the current buffer, so you cannot use them to create
-menus that refer to other files. You must write such menus by hand.
+ The GNU Emacs Texinfo mode menu updating commands only work with nodes
+within the current buffer, so you cannot use them to create menus that
+refer to other files. You must write such menus by hand.
\1f
File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top
****************
"Cross references" are used to refer the reader to other parts of the
-same or different Texinfo files. In Texinfo, nodes are the places to
-which cross references can refer.
+same or different Texinfo files. In Texinfo, nodes and anchors are the
+places to which cross references can refer.
* Menu:
However, in any document, some information will be too detailed for
the current context, or incidental to it; use cross references to
-provide access to such information. Also, an on-line help system or a
+provide access to such information. Also, an online help system or a
reference manual is not like a novel; few read such documents in
sequence from beginning to end. Instead, people look up what they
need. For this reason, such creations should contain many cross
using the Info `f' command. (*note Some advanced Info commands:
(info)Help-Adv.)
- The various cross reference commands use nodes to define cross
-reference locations. This is evident in Info, in which a cross
-reference takes you to the specified node. TeX also uses nodes to
-define cross reference locations, but the action is less obvious. When
-TeX generates a DVI file, it records nodes' page numbers and uses the
-page numbers in making references. Thus, if you are writing a manual
-that will only be printed, and will not be used on-line, you must
-nonetheless write `@node' lines to name the places to which you make
-cross references.
+ The various cross reference commands use nodes (or anchors, *note
+`@anchor': anchor.) to define cross reference locations. This is
+evident in Info, in which a cross reference takes you to the specified
+location. TeX also uses nodes to define cross reference locations, but
+the action is less obvious. When TeX generates a DVI file, it records
+each node's page number and uses the page numbers in making references.
+Thus, if you are writing a manual that will only be printed, and will
+not be used online, you must nonetheless write `@node' lines to name
+the places to which you make cross references.
\1f
File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References
The five possible arguments for a cross reference are:
- 1. The node name (required). This is the node to which the cross
- reference takes you. In a printed document, the location of the
- node provides the page reference only for references within the
- same document.
+ 1. The node or anchor name (required). This is the location to which
+ the cross reference takes you. In a printed document, the
+ location of the node provides the page reference only for
+ references within the same document.
2. The cross reference name for the Info reference, if it is to be
different from the node name. If you include this argument, it
file and in the printed manual.
`@xref' must refer to an Info node by name. Use `@node' to define
-the node (*note Writing a Node::.).
+the node (*note Writing a Node::).
`@xref' is followed by several arguments inside braces, separated by
commas. Whitespace before and after these commas is ignored.
*Note Tropical Storms::, for more info.
+and
+
See Section 3.1 [Tropical Storms], page 24, for more info.
(Note that in the preceding example the closing brace is followed by a
reference, you need to write a title such as "Clouds, Mist, and Fog"
without the commas.
- Also, remember to write a comma or period after the closing brace of a
-`@xref' to terminate the cross reference. In the following examples, a
-clause follows a terminating comma.
+ Also, remember to write a comma or period after the closing brace of
+an `@xref' to terminate the cross reference. In the following
+examples, a clause follows a terminating comma.
The template is like this:
for more information.
@xref{Regexp, , Regular Expressions as Patterns}.
-\1f
-File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref
-
-`@xref' with Four and Five Arguments
-------------------------------------
-
- In a cross reference, a fourth argument specifies the name of another
-Info file, different from the file in which the reference appears, and
-a fifth argument specifies its title as a printed manual.
-
- Remember that a comma or period must follow the closing brace of an
-`@xref' command to terminate the cross reference. In the following
-examples, a clause follows a terminating comma.
-
-The template is:
-
- @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
- INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
-
-For example,
-
- @xref{Electrical Effects, Lightning, Thunder and Lightning,
- weather, An Introduction to Meteorology}, for details.
-
-produces
-
- *Note Lightning: (weather)Electrical Effects, for details.
-
-The name of the Info file is enclosed in parentheses and precedes the
-name of the node.
-
-In a printed manual, the reference looks like this:
-
- See section "Thunder and Lightning" in An Introduction to
- Meteorology, for details.
-
-The title of the printed manual is typeset in italics; and the
-reference lacks a page number since TeX cannot know to which page a
-reference refers when that reference is to another manual.
-
- Often, you will leave out the second argument when you use the long
-version of `@xref'. In this case, the third argument, the topic
-description, will be used as the cross reference name in Info.
-
-The template looks like this:
-
- @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
- PRINTED-MANUAL-TITLE}, for details.
-
-which produces
-
- *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
-
-and
-
- See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
-
-For example,
-
- @xref{Electrical Effects, , Thunder and Lightning,
- weather, An Introduction to Meteorology}, for details.
-
-produces
-
- *Note Thunder and Lightning: (weather)Electrical Effects,
- for details.
-
-and
-
- See section "Thunder and Lightning" in An Introduction to
- Meteorology, for details.
-
- On rare occasions, you may want to refer to another Info file that is
-within a single printed manual--when multiple Texinfo files are
-incorporated into the same TeX run but make separate Info files. In
-this case, you need to specify only the fourth argument, and not the
-fifth.
-
-\1f
-File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References
-
-Naming a `Top' Node
-===================
-
- In a cross reference, you must always name a node. This means that in
-order to refer to a whole manual, you must identify the `Top' node by
-writing it as the first argument to the `@xref' command. (This is
-different from the way you write a menu entry; see *Note Referring to
-Other Info Files: Other Info Files.) At the same time, to provide a
-meaningful section topic or title in the printed cross reference
-(instead of the word `Top'), you must write an appropriate entry for
-the third argument to the `@xref' command.
-
-Thus, to make a cross reference to `The GNU Make Manual', write:
-
- @xref{Top, , Overview, make, The GNU Make Manual}.
-
-which produces
-
- *Note Overview: (make)Top.
-
-and
-
- See section "Overview" in The GNU Make Manual.
-
-In this example, `Top' is the name of the first node, and `Overview' is
-the name of the first section of the manual.
-
-\1f
-File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References
-
-`@ref'
-======
-
- `@ref' is nearly the same as `@xref' except that it does not generate
-a `See' in the printed output, just the reference itself. This makes
-it useful as the last part of a sentence.
-
-For example,
-
- For more information, see @ref{Hurricanes}.
-
-produces
-
- For more information, see *Note Hurricanes.
-
-and
-
- For more information, see Section 8.2 [Hurricanes], page 123.
-
- The `@ref' command sometimes leads writers to express themselves in a
-manner that is suitable for a printed manual but looks awkward in the
-Info format. Bear in mind that your audience will be using both the
-printed and the Info format.
-
-For example,
-
- Sea surges are described in @ref{Hurricanes}.
-
-produces
-
- Sea surges are described in Section 6.7 [Hurricanes], page 72.
-
-in a printed document, and the following in Info:
-
- Sea surges are described in *Note Hurricanes::.
-
- *Caution:* You *must* write a period or comma immediately after an
- `@ref' command with two or more arguments. Otherwise, Info will
- not find the end of the cross reference entry and its attempt to
- follow the cross reference will fail. As a general rule, you
- should write a period or comma after every `@ref' command. This
- looks best in both the printed and the Info output.
-
-\1f
-File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References
-
-`@pxref'
-========
-
- The parenthetical reference command, `@pxref', is nearly the same as
-`@xref', but you use it *only* inside parentheses and you do *not* type
-a comma or period after the command's closing brace. The command
-differs from `@xref' in two ways:
-
- 1. TeX typesets the reference for the printed manual with a lower case
- `see' rather than an upper case `See'.
-
- 2. The Info formatting commands automatically end the reference with a
- closing colon or period.
-
- Because one type of formatting automatically inserts closing
-punctuation and the other does not, you should use `@pxref' *only*
-inside parentheses as part of another sentence. Also, you yourself
-should not insert punctuation after the reference, as you do with
-`@xref'.
-
- `@pxref' is designed so that the output looks right and works right
-between parentheses both in printed output and in an Info file. In a
-printed manual, a closing comma or period should not follow a cross
-reference within parentheses; such punctuation is wrong. But in an
-Info file, suitable closing punctuation must follow the cross reference
-so Info can recognize its end. `@pxref' spares you the need to use
-complicated methods to put a terminator into one form of the output and
-not the other.
-
-With one argument, a parenthetical cross reference looks like this:
-
- ... storms cause flooding (@pxref{Hurricanes}) ...
-
-which produces
-
- ... storms cause flooding (*Note Hurricanes::) ...
-
-and
-
- ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
- ...
-
- With two arguments, a parenthetical cross reference has this template:
-
- ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
-
-which produces
-
- ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
-
-and
-
- ... (see Section NNN [NODE-NAME], page PPP) ...
-
- `@pxref' can be used with up to five arguments just like `@xref'
-(*note `@xref': xref.).
-
- *Please note:* Use `@pxref' only as a parenthetical reference. Do
- not try to use `@pxref' as a clause in a sentence. It will look
- bad in either the Info file, the printed output, or both.
-
- Also, parenthetical cross references look best at the ends of
- sentences. Although you may write them in the middle of a
- sentence, that location breaks up the flow of text.
-
-\1f
-File: texinfo.info, Node: inforef, Next: uref, Prev: pxref, Up: Cross References
-
-`@inforef'
-==========
-
- `@inforef' is used for cross references to Info files for which there
-are no printed manuals. Even in a printed manual, `@inforef' generates
-a reference directing the user to look in an Info file.
-
- The command takes either two or three arguments, in the following
-order:
-
- 1. The node name.
-
- 2. The cross reference name (optional).
-
- 3. The Info file name.
-
-Separate the arguments with commas, as with `@xref'. Also, you must
-terminate the reference with a comma or period after the `}', as you do
-with `@xref'.
-
-The template is:
-
- @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
-
-Thus,
-
- @inforef{Expert, Advanced Info commands, info},
- for more information.
-
-produces
-
- *Note Advanced Info commands: (info)Expert,
- for more information.
-
-and
-
- See Info file `info', node `Expert', for more information.
-
-Similarly,
-
- @inforef{Expert, , info}, for more information.
-
-produces
-
- *Note (info)Expert::, for more information.
-
-and
-
- See Info file `info', node `Expert', for more information.
-
- The converse of `@inforef' is `@cite', which is used to refer to
-printed works for which no Info form exists. *Note `@cite': cite.
-
-\1f
-File: texinfo.info, Node: uref, Prev: inforef, Up: Cross References
-
-`@uref{URL[, DISPLAYED-TEXT]}'
-==============================
-
- `@uref' produces a reference to a uniform resource locator (URL). It
-takes one mandatory argument, the URL, and one optional argument, the
-text to display (the default is the URL itself). In HTML output,
-`@uref' produces a link you can follow. For example:
-
- The official GNU ftp site is
- @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
-
-produces (in text):
- The official GNU ftp site is
- `ftp://ftp.gnu.ai.mit.edu/pub/gnu'
-
-whereas
- The official
- @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
- GNU ftp site} holds programs and texts.
-
-produces (in text):
- The official GNU ftp site (ftp://ftp.gnu.ai.mit.edu/pub/gnu) holds
- programs and texts.
-
-and (in HTML):
- The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
- site</A> holds programs and texts.
-
- To merely indicate a URL, use `@url' (*note `@url': url.).
-
-\1f
-File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top
-
-Marking Words and Phrases
-*************************
-
- In Texinfo, you can mark words and phrases in a variety of ways. The
-Texinfo formatters use this information to determine how to highlight
-the text. You can specify, for example, whether a word or phrase is a
-defining occurrence, a metasyntactic variable, or a symbol used in a
-program. Also, you can emphasize text.
-
-* Menu:
-
-* Indicating:: How to indicate definitions, files, etc.
-* Emphasis:: How to emphasize text.
-
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref
+
+`@xref' with Four and Five Arguments
+------------------------------------
+
+ In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed manual.
+
+ Remember that a comma or period must follow the closing brace of an
+`@xref' command to terminate the cross reference. In the following
+examples, a clause follows a terminating comma.
+
+The template is:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
+ INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
+
+For example,
+
+ @xref{Electrical Effects, Lightning, Thunder and Lightning,
+ weather, An Introduction to Meteorology}, for details.
+
+produces
+
+ *Note Lightning: (weather)Electrical Effects, for details.
+
+The name of the Info file is enclosed in parentheses and precedes the
+name of the node.
+
+In a printed manual, the reference looks like this:
+
+ See section "Thunder and Lightning" in An Introduction to
+ Meteorology, for details.
+
+The title of the printed manual is typeset in italics; and the
+reference lacks a page number since TeX cannot know to which page a
+reference refers when that reference is to another manual.
+
+ Often, you will leave out the second argument when you use the long
+version of `@xref'. In this case, the third argument, the topic
+description, will be used as the cross reference name in Info.
+
+The template looks like this:
+
+ @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
+ PRINTED-MANUAL-TITLE}, for details.
+
+which produces
+
+ *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
+
+and
+
+ See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
+
+For example,
+
+ @xref{Electrical Effects, , Thunder and Lightning,
+ weather, An Introduction to Meteorology}, for details.
+
+produces
+
+ *Note Thunder and Lightning: (weather)Electrical Effects,
+ for details.
+
+and
+
+ See section "Thunder and Lightning" in An Introduction to
+ Meteorology, for details.
+
+ On rare occasions, you may want to refer to another Info file that is
+within a single printed manual--when multiple Texinfo files are
+incorporated into the same TeX run but make separate Info files. In
+this case, you need to specify only the fourth argument, and not the
+fifth.
+
+\1f
+File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References
+
+Naming a `Top' Node
+===================
+
+ In a cross reference, you must always name a node. This means that in
+order to refer to a whole manual, you must identify the `Top' node by
+writing it as the first argument to the `@xref' command. (This is
+different from the way you write a menu entry; see *Note Referring to
+Other Info Files: Other Info Files.) At the same time, to provide a
+meaningful section topic or title in the printed cross reference
+(instead of the word `Top'), you must write an appropriate entry for
+the third argument to the `@xref' command.
+
+Thus, to make a cross reference to `The GNU Make Manual', write:
+
+ @xref{Top, , Overview, make, The GNU Make Manual}.
+
+which produces
+
+ *Note Overview: (make)Top.
+
+and
+
+ See section "Overview" in The GNU Make Manual.
+
+In this example, `Top' is the name of the first node, and `Overview' is
+the name of the first section of the manual.
+
+\1f
+File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References
+
+`@ref'
+======
+
+ `@ref' is nearly the same as `@xref' except that it does not generate
+a `See' in the printed output, just the reference itself. This makes
+it useful as the last part of a sentence.
+
+For example,
+
+ For more information, see @ref{Hurricanes}.
+
+produces
+
+ For more information, see *Note Hurricanes::.
+
+and
+
+ For more information, see Section 8.2 [Hurricanes], page 123.
+
+ The `@ref' command sometimes leads writers to express themselves in a
+manner that is suitable for a printed manual but looks awkward in the
+Info format. Bear in mind that your audience will be using both the
+printed and the Info format.
+
+For example,
+
+ Sea surges are described in @ref{Hurricanes}.
+
+produces
+
+ Sea surges are described in Section 6.7 [Hurricanes], page 72.
+
+in a printed document, and the following in Info:
+
+ Sea surges are described in *Note Hurricanes::.
+
+ *Caution:* You _must_ write a period, comma, or right parenthesis
+ immediately after an `@ref' command with two or more arguments.
+ Otherwise, Info will not find the end of the cross reference entry
+ and its attempt to follow the cross reference will fail. As a
+ general rule, you should write a period or comma after every
+ `@ref' command. This looks best in both the printed and the Info
+ output.
+
+\1f
+File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References
+
+`@pxref'
+========
+
+ The parenthetical reference command, `@pxref', is nearly the same as
+`@xref', but you use it _only_ inside parentheses and you do _not_ type
+a comma or period after the command's closing brace. The command
+differs from `@xref' in two ways:
+
+ 1. TeX typesets the reference for the printed manual with a lower case
+ `see' rather than an upper case `See'.
+
+ 2. The Info formatting commands automatically end the reference with a
+ closing colon or period.
+
+ Because one type of formatting automatically inserts closing
+punctuation and the other does not, you should use `@pxref' _only_
+inside parentheses as part of another sentence. Also, you yourself
+should not insert punctuation after the reference, as you do with
+`@xref'.
+
+ `@pxref' is designed so that the output looks right and works right
+between parentheses both in printed output and in an Info file. In a
+printed manual, a closing comma or period should not follow a cross
+reference within parentheses; such punctuation is wrong. But in an
+Info file, suitable closing punctuation must follow the cross reference
+so Info can recognize its end. `@pxref' spares you the need to use
+complicated methods to put a terminator into one form of the output and
+not the other.
+
+With one argument, a parenthetical cross reference looks like this:
+
+ ... storms cause flooding (@pxref{Hurricanes}) ...
+
+which produces
+
+ ... storms cause flooding (*Note Hurricanes::) ...
+
+and
+
+ ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
+ ...
+
+ With two arguments, a parenthetical cross reference has this template:
+
+ ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
+
+which produces
+
+ ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
+
+and
+
+ ... (see Section NNN [NODE-NAME], page PPP) ...
+
+ `@pxref' can be used with up to five arguments just like `@xref'
+(*note `@xref': xref.).
+
+ *Please note:* Use `@pxref' only as a parenthetical reference. Do
+ not try to use `@pxref' as a clause in a sentence. It will look
+ bad in either the Info file, the printed output, or both.
+
+ Also, parenthetical cross references look best at the ends of
+ sentences. Although you may write them in the middle of a
+ sentence, that location breaks up the flow of text.
+
+\1f
+File: texinfo.info, Node: inforef, Next: uref, Prev: pxref, Up: Cross References
+
+`@inforef'
+==========
+
+ `@inforef' is used for cross references to Info files for which there
+are no printed manuals. Even in a printed manual, `@inforef' generates
+a reference directing the user to look in an Info file.
+
+ The command takes either two or three arguments, in the following
+order:
+
+ 1. The node name.
+
+ 2. The cross reference name (optional).
+
+ 3. The Info file name.
+
+Separate the arguments with commas, as with `@xref'. Also, you must
+terminate the reference with a comma or period after the `}', as you do
+with `@xref'.
+
+The template is:
+
+ @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
+
+Thus,
+
+ @inforef{Expert, Advanced Info commands, info},
+ for more information.
+
+produces
+
+ *Note Advanced Info commands: (info)Expert,
+ for more information.
+
+and
+
+ See Info file `info', node `Expert', for more information.
+
+Similarly,
+
+ @inforef{Expert, , info}, for more information.
+
+produces
+
+ *Note (info)Expert::, for more information.
+
+and
+
+ See Info file `info', node `Expert', for more information.
+
+ The converse of `@inforef' is `@cite', which is used to refer to
+printed works for which no Info form exists. *Note `@cite': cite.
+
+\1f
+File: texinfo.info, Node: uref, Prev: inforef, Up: Cross References
+
+`@uref{URL[, TEXT][, REPLACEMENT]}'
+===================================
+
+ `@uref' produces a reference to a uniform resource locator (url). It
+takes one mandatory argument, the url, and two optional arguments which
+control the text that is displayed. In HTML output, `@uref' produces a
+link you can follow.
+
+ The second argument, if specified, is the text to display (the default
+is the url itself); in Info and DVI output, but not in HTML output, the
+url is also output.
+
+ The third argument, on the other hand, if specified is also the text
+to display, but the url is _not_ output in any format. This is useful
+when the text is already sufficiently referential, as in a man page. If
+the third argument is given, the second argument is ignored.
+
+ The simple one argument form, where the url is both the target and the
+text of the link:
+
+ The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
+
+produces:
+ The official GNU ftp site is `ftp://ftp.gnu.org/gnu'.
+
+ An example of the two-argument form:
+ The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds
+ programs and texts.
+
+produces:
+ The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds
+ programs and texts.
+
+that is, the Info output is this:
+ The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds
+ programs and texts.
+
+and the HTML output is this:
+ The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> holds
+ programs and texts.
+
+ An example of the three-argument form:
+ The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program ...
+
+produces:
+ The ls(1) program ...
+
+but with HTML:
+ The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program ...
+
+ To merely indicate a url without creating a link people can follow,
+use `@url' (*note `@url': url.).
+
+ Some people prefer to display url's in the unambiguous format:
+
+ <URL:http://HOST/PATH>
+
+You can use this form in the input file if you wish. We feel it's not
+necessary to clutter up the output with the extra `<URL:' and `>',
+since any software that tries to detect url's in text already has to
+detect them without the `<URL:' to be useful.
+
+\1f
+File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top
+
+Marking Words and Phrases
+*************************
+
+ In Texinfo, you can mark words and phrases in a variety of ways. The
+Texinfo formatters use this information to determine how to highlight
+the text. You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program. Also, you can emphasize text, in several different ways.
+
+* Menu:
+
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
+
+\1f
File: texinfo.info, Node: Indicating, Next: Emphasis, Prev: Marking Text, Up: Marking Text
Indicating Definitions, Commands, etc.
`@var', and code by `@code'. Since the pieces of text are labelled by
commands that tell what kind of object they are, it is easy to change
the way the Texinfo formatters prepare such text. (Texinfo is an
-*intentional* formatting language rather than a *typesetting*
+_intentional_ formatting language rather than a _typesetting_
formatting language.)
For example, in a printed manual, code is usually illustrated in a
typewriter font; `@code' tells TeX to typeset this text in this font.
But it would be easy to change the way TeX highlights code to use
-another font, and this change would not effect how keystroke examples
+another font, and this change would not affect how keystroke examples
are highlighted. If straight typesetting commands were used in the body
of the file and you wanted to make a change, you would need to check
every single occurrence to make sure that you were changing code and
* Menu:
* Useful Highlighting:: Highlighting provides useful information.
-* code:: How to indicate code.
-* kbd:: How to show keyboard input.
-* key:: How to specify keys.
-* samp:: How to show a literal sequence of characters.
-* var:: How to indicate a metasyntactic variable.
-* file:: How to indicate the name of a file.
-* dfn:: How to specify a definition.
-* cite:: How to refer to a book that is not in Info.
-* url:: How to indicate a world wide web reference.
-* email:: How to indicate an electronic mail address.
+* code:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: Showing a literal sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
\1f
File: texinfo.info, Node: Useful Highlighting, Next: code, Prev: Indicating, Up: Indicating
Highlighting Commands are Useful
--------------------------------
- The highlighting commands can be used to generate useful information
+ The highlighting commands can be used to extract useful information
from the file, such as lists of functions or file names. It is
possible, for example, to write a program in Emacs Lisp (or a keyboard
macro) to insert an index entry after every paragraph that contains
`@var{METASYNTACTIC-VARIABLE}'
Indicate a metasyntactic variable.
-`@url{UNIFORM-RESOURCE-LOCATOR}'
- Indicate a uniform resource locator for the World Wide Web.
+`@env{ENVIRONMENT-VARIABLE}'
+ Indicate an environment variable.
`@file{FILE-NAME}'
Indicate the name of a file.
-`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
- Indicate an electronic mail address.
+`@command{COMMAND-NAME}'
+ Indicate the name of a command.
+
+`@option{OPTION}'
+ Indicate a command-line option.
`@dfn{TERM}'
Indicate the introductory or defining use of a term.
`@cite{REFERENCE}'
Indicate the name of a book.
+`@acronym{ACRONYM}'
+ Indicate an acronym.
+
+`@url{UNIFORM-RESOURCE-LOCATOR}'
+ Indicate a uniform resource locator for the World Wide Web.
+
+`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
+ Indicate an electronic mail address.
+
\1f
File: texinfo.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating
braces.
Thus, you should use `@code' for an expression in a program, for the
-name of a variable or function used in a program, or for a keyword.
-Also, you should use `@code' for the name of a program, such as `diff',
-that is a name used in the machine. (You should write the name of a
-program in the ordinary text font if you regard it as a new English
-word, such as `Emacs' or `Bison'.)
-
- Use `@code' for environment variables such as `TEXINPUTS', and other
-variables.
-
- Use `@code' for command names in command languages that resemble
-programming languages, such as Texinfo or the shell. For example,
-`@code' and `@samp' are produced by writing `@code{@@code}' and
-`@code{@@samp}' in the Texinfo source, respectively.
+name of a variable or function used in a program, or for a keyword in a
+programming language.
- Note, however, that you should not use `@code' for shell options such
-as `-c' when such options stand alone. (Use `@samp'.) Also, an entire
-shell command often looks better if written using `@samp' rather than
-`@code'. In this case, the rule is to choose the more pleasing format.
+ Use `@code' for command names in languages that resemble programming
+languages, such as Texinfo. For example, `@code' and `@samp' are
+produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo
+source, respectively.
It is incorrect to alter the case of a word inside an `@code' command
when it appears at the beginning of a sentence. Most computer
Even in languages which are not case sensitive, it is confusing to a
human reader to see identifiers spelled in different ways. Pick one
spelling and always use that. If you do not want to start a sentence
-with a command written all in lower case, you should rearrange the
+with a command name written all in lower case, you should rearrange the
sentence.
- Do not use the `@code' command for a string of characters shorter
-than a syntactic token. If you are writing about `TEXINPU', which is
-just a part of the name for the `TEXINPUTS' environment variable, you
-should use `@samp'.
-
- In particular, you should not use the `@code' command when writing
-about the characters used in a token; do not, for example, use `@code'
-when you are explaining what letters or printable symbols can be used
-in the names of functions. (Use `@samp'.) Also, you should not use
-`@code' to mark text that is considered input to programs unless the
-input is written in a language that is like a programming language.
-For example, you should not use `@code' for the keystroke commands of
-GNU Emacs (use `@kbd' instead) although you may use `@code' for the
-names of the Emacs Lisp functions that the keystroke commands invoke.
-
In the printed manual, `@code' causes TeX to typeset the argument in
a typewriter face. In the Info file, it causes the Info formatting
commands to use single quotation marks around the text.
For example,
- Use @code{diff} to compare two files.
+ The function returns @code{nil}.
produces this in the printed manual:
- Use `diff' to compare two files.
+ The function returns `nil'.
+
+ Here are some cases for which it is preferable not to use `@code':
+
+ * For shell command names such as `ls' (use `@command').
+
+ * For shell options such as `-c' when such options stand alone (use
+ `@option').
+
+ * Also, an entire shell command often looks better if written using
+ `@samp' rather than `@code'. In this case, the rule is to choose
+ the more pleasing format.
+
+ * For environment variable such as `TEXINPUTS' (use `@env').
+
+ * For a string of characters shorter than a syntactic token. For
+ example, if you are writing about `goto-ch', which is just a part
+ of the name for the `goto-char' Emacs Lisp function, you should use
+ `@samp'.
+
+ * In general, when writing about the characters used in a token; for
+ example, do not use `@code' when you are explaining what letters
+ or printable symbols can be used in the names of functions. (Use
+ `@samp'.) Also, you should not use `@code' to mark text that is
+ considered input to programs unless the input is written in a
+ language that is like a programming language. For example, you
+ should not use `@code' for the keystroke commands of GNU Emacs (use
+ `@kbd' instead) although you may use `@code' for the names of the
+ Emacs Lisp functions that the keystroke commands invoke.
+
+
+ Since `@command', `@option', and `@env' were introduced relatively
+recently, it is acceptable to use `@code' or `@samp' for command names,
+options, and environment variables. The new commands allow you to
+express the markup more precisely, but there is no real harm in using
+the older commands, and of course the long-standing manuals do so.
\1f
File: texinfo.info, Node: kbd, Next: key, Prev: code, Up: Indicating
Use the distinguishing font for `@kbd' only in `@example' and
similar environments.
-`example'
+`distinct'
(the default) Always use the distinguishing font for `@kbd'.
You can embed another @-command inside the braces of an `@kbd'
To match `foo' at the end of the line, use the regexp `foo$'.
Any time you are referring to single characters, you should use
-`@samp' unless `@kbd' or `@key' is more appropriate. Use `@samp' for
-the names of command-line options (except in an `@table', where `@code'
-seems to read more easily). Also, you may use `@samp' for entire
-statements in C and for entire shell commands--in this case, `@samp'
-often looks better than `@code'. Basically, `@samp' is a catchall for
-whatever is not covered by `@code', `@kbd', or `@key'.
+`@samp' unless `@kbd' or `@key' is more appropriate. Also, you may use
+`@samp' for entire statements in C and for entire shell commands--in
+this case, `@samp' often looks better than `@code'. Basically, `@samp'
+is a catchall for whatever is not covered by `@code', `@kbd', or `@key'.
Only include punctuation marks within braces if they are part of the
string you are specifying. Write punctuation marks outside the braces
`y'.
\1f
-File: texinfo.info, Node: var, Next: file, Prev: samp, Up: Indicating
+File: texinfo.info, Node: var, Next: env, Prev: samp, Up: Indicating
`@var'{METASYNTACTIC-VARIABLE}
------------------------------
Do not use `@var' for the names of particular variables in
programming languages. These are specific names from a program, so
-`@code' is correct for them. For example, the Emacs Lisp variable
-`texinfo-tex-command' is not a metasyntactic variable; it is properly
-formatted using `@code'.
+`@code' is correct for them (*note code::). For example, the Emacs
+Lisp variable `texinfo-tex-command' is not a metasyntactic variable; it
+is properly formatted using `@code'.
+
+ Do not use `@var' for environment variables either; `@env' is correct
+for them (see the next section).
The effect of `@var' in the Info file is to change the case of the
-argument to all upper case; in the printed manual, to italicize it.
+argument to all upper case. In the printed manual and HTML output, the
+argument is printed in slanted type.
For example,
To delete file @var{filename},
- type @code{rm @var{filename}}.
+ type @samp{rm @var{filename}}.
produces
..., type rm <filename>
However, that is not the style that Texinfo uses. (You can, of course,
-modify the sources to TeX and the Info formatting commands to output
-the `<...>' format if you wish.)
+modify the sources to `texinfo.tex' and the Info formatting commands to
+output the `<...>' format if you wish.)
+
+\1f
+File: texinfo.info, Node: env, Next: file, Prev: var, Up: Indicating
+
+`@env'{ENVIRONMENT-VARIABLE}
+----------------------------
+
+ Use the `@env' command to indicate environment variables, as used by
+many operating systems, including GNU. Do not use it for metasyntactic
+variables; use `@var' instead (see the previous section).
+
+ `@env' is equivalent to `@code' in its effects. For example:
+
+ The @env{PATH} environment variable sets the search path for commands.
+ produces
+ The `PATH' environment variable sets the search path for commands.
\1f
-File: texinfo.info, Node: file, Next: dfn, Prev: var, Up: Indicating
+File: texinfo.info, Node: file, Next: command, Prev: env, Up: Indicating
`@file'{FILE-NAME}
------------------
The `.el' files are in the `/usr/local/emacs/lisp' directory.
\1f
-File: texinfo.info, Node: dfn, Next: cite, Prev: file, Up: Indicating
+File: texinfo.info, Node: command, Next: option, Prev: file, Up: Indicating
+
+`@command'{COMMAND-NAME}
+------------------------
+
+ Use the `@command' command to indicate command names, such as `ls' or
+`cc'.
+
+ `@command' is equivalent to `@code' in its effects. For example:
+
+ The command @command{ls} lists directory contents.
+ produces
+ The command `ls' lists directory contents.
+
+ You should write the name of a program in the ordinary text font,
+rather than using `@command', if you regard it as a new English word,
+such as `Emacs' or `Bison'.
+
+ When writing an entire shell command invocation, as in `ls -l', you
+should use either `@samp' or `@code' at your discretion.
+
+\1f
+File: texinfo.info, Node: option, Next: dfn, Prev: command, Up: Indicating
+
+`@option'{OPTION-NAME}
+----------------------
+
+ Use the `@option' command to indicate a command-line option; for
+example, `-l' or `--version' or `--output=FILENAME'.
+
+ `@option' is equivalent to `@samp' in its effects. For example:
+
+ The option @option{-l} produces a long listing.
+ produces
+ The option `-l' produces a long listing.
+
+ In tables, putting options inside `@code' produces a more pleasing
+effect.
+
+\1f
+File: texinfo.info, Node: dfn, Next: cite, Prev: option, Up: Indicating
`@dfn'{TERM}
------------
information of a definition--it should make the meaning clear.
\1f
-File: texinfo.info, Node: cite, Next: url, Prev: dfn, Up: Indicating
+File: texinfo.info, Node: cite, Next: acronym, Prev: dfn, Up: Indicating
`@cite'{REFERENCE}
------------------
Use the `@cite' command for the name of a book that lacks a companion
-Info file. The command produces italics in the printed manual, and
+Info file. The command produces italics in the printed manual, and
quotation marks in the Info file.
- (If a book is written in Texinfo, it is better to use a cross
-reference command since a reader can easily follow such a reference in
-Info. *Note `@xref': xref.)
+ If a book is written in Texinfo, it is better to use a cross reference
+command since a reader can easily follow such a reference in Info.
+*Note `@xref': xref.
\1f
-File: texinfo.info, Node: url, Next: email, Prev: cite, Up: Indicating
+File: texinfo.info, Node: acronym, Next: url, Prev: cite, Up: Indicating
+
+`@acronym'{ACRONYM}
+-------------------
+
+ Use the `@acronym' command for abbreviations written in all capital
+letters, such as `NASA'. The abbreviation is given as the single
+argument in braces, as in `@acronym{NASA}'. As a matter of style, or
+for particular abbreviations, you may prefer to use periods, as in
+`@acronym{F.B.I.}'.
+
+ In TeX and HTML, the argument is printed in a slightly smaller font
+size. In Info or plain text output, this command changes nothing.
+
+\1f
+File: texinfo.info, Node: url, Next: email, Prev: acronym, Up: Indicating
`@url'{UNIFORM-RESOURCE-LOCATOR}
--------------------------------
- Use the `@url' to indicate a uniform resource locator on the World
-Wide Web. This is analogous to `@file', `@var', etc., and is purely
-for markup purposes. It does not produce a link you can follow in HTML
-output (the `@uref' command does, *note `@uref': uref.). It is useful
-for example URL's which do not actually exist. For example:
+ Use the `@url' command to indicate a uniform resource locator on the
+World Wide Web. This is analogous to `@file', `@var', etc., and is
+purely for markup purposes. It does not produce a link you can follow
+in HTML output (use the `@uref' command for that, *note `@uref':
+uref.). It is useful for url's which do not actually exist. For
+example:
+
+ For example, the url might be @url{http://example.org/path}.
+
+which produces:
- For example, the url might be
- @url{http://host.domain.org/path}.
+ For example, the url might be <http://example.org/path>.
\1f
File: texinfo.info, Node: email, Prev: url, Up: Indicating
Send bug reports to @email{bug-texinfo@@gnu.org}.
Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
-
-produces
+ produces
Send bug reports to <bug-texinfo@gnu.org>.
Send suggestions to the same place <bug-texinfo@gnu.org>.
will want to emphasize text without indicating a category. Texinfo has
two commands to do this. Also, Texinfo has several commands that
specify the font in which TeX will typeset text. These commands have
-no affect on Info and only one of them, the `@r' command, has any
+no effect on Info and only one of them, the `@r' command, has any
regular use.
* Menu:
* emph & strong:: How to emphasize text in Texinfo.
* Smallcaps:: How to use the small caps font.
* Fonts:: Various font commands for printed output.
-* Customized Highlighting:: How to define highlighting commands.
\1f
-File: texinfo.info, Node: emph & strong, Next: Smallcaps, Prev: Emphasis, Up: Emphasis
+File: texinfo.info, Node: emph & strong, Next: Smallcaps, Up: Emphasis
`@emph'{TEXT} and `@strong'{TEXT}
---------------------------------
The `@emph' and `@strong' commands are for emphasis; `@strong' is
-stronger. In printed output, `@emph' produces *italics* and `@strong'
+stronger. In printed output, `@emph' produces _italics_ and `@strong'
produces *bold*.
For example,
produces:
- *Caution*: `rm * .[^.]*' removes *all*
+ *Caution*: `rm * .[^.]*' removes _all_
files in the directory.
The `@strong' command is seldom used except to mark what is, in
effect, a typographical element, such as the word `Caution' in the
preceding example.
- In the Info file, both `@emph' and `@strong' put asterisks around the
-text.
+ In the Info output, `@emph' surrounds the text with underscores
+(`_'), and `@strong' puts asterisks around the text.
- *Caution:* Do not use `@emph' or `@strong' with the word `Note';
- Info will mistake the combination for a cross reference. Use a
- phrase such as *Please note* or *Caution* instead.
+ *Caution:* Do not use `@strong' with the word `Note'; Info will
+ mistake the combination for a cross reference. Use a phrase such
+ as *Please note* or *Caution* instead.
\1f
File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis
`@sc'{TEXT}: The Small Caps Font
--------------------------------
- Use the `@sc' command to set text in the printed output in a small
-caps font and set text in the Info file in upper case letters.
-
- Write the text between braces in lower case, like this:
+ Use the `@sc' command to set text in the printed and the HTML output
+in A SMALL CAPS FONT and set text in the Info file in upper case
+letters. Write the text you want to be in small caps (where possible)
+between braces in lower case, like this:
The @sc{acm} and @sc{ieee} are technical societies.
TeX typesets the small caps font in a manner that prevents the
letters from `jumping out at you on the page'. This makes small caps
-text easier to read than text in all upper case. The Info formatting
-commands set all small caps text in upper case.
+text easier to read than text in all upper case--but it's usually
+better to use regular mixed case anyway. The Info formatting commands
+set all small caps text in upper case. In HTML, the text is upper-cased
+and a smaller font is used to render it.
- If the text between the braces of an `@sc' command is upper case, TeX
-typesets in full-size capitals. Use full-size capitals sparingly.
+ If the text between the braces of an `@sc' command is uppercase, TeX
+typesets in FULL-SIZE CAPITALS. Use full-size capitals sparingly, if
+ever, and since it's redundant to mark all-uppercase text with `@sc',
+`makeinfo' warns about such usage.
You may also use the small caps font for a jargon word such as ATO (a
NASA word meaning `abort to orbit').
`@code' when the word refers to the Lisp function of the same spelling.
\1f
-File: texinfo.info, Node: Fonts, Next: Customized Highlighting, Prev: Smallcaps, Up: Emphasis
+File: texinfo.info, Node: Fonts, Prev: Smallcaps, Up: Emphasis
Fonts for Printing, Not Info
----------------------------
language.
\1f
-File: texinfo.info, Node: Customized Highlighting, Prev: Fonts, Up: Emphasis
-
-Customized Highlighting
------------------------
-
- You can use regular TeX commands inside of `@iftex' ... `@end iftex'
-to create your own customized highlighting commands for Texinfo. The
-easiest way to do this is to equate your customized commands with
-pre-existing commands, such as those for italics. Such new commands
-work only with TeX.
-
- You can use the `@definfoenclose' command inside of `@ifinfo' ...
-`@end ifinfo' to define commands for Info with the same names as new
-commands for TeX. `@definfoenclose' creates new commands for Info that
-mark text by enclosing it in strings that precede and follow the text.
-(1) (*note Customized Highlighting-Footnotes::)
-
- Here is how to create a new @-command called `@phoo' that causes TeX
-to typeset its argument in italics and causes Info to display the
-argument between `//' and `\\'.
-
- For TeX, write the following to equate the `@phoo' command with the
-existing `@i' italics command:
-
- @iftex
- @global@let@phoo=@i
- @end iftex
-
-This defines `@phoo' as a command that causes TeX to typeset the
-argument to `@phoo' in italics. `@global@let' tells TeX to equate the
-next argument with the argument that follows the equals sign.
-
- For Info, write the following to tell the Info formatters to enclose
-the argument between `//' and `\\':
-
- @ifinfo
- @definfoenclose phoo, //, \\
- @end ifinfo
-
-Write the `@definfoenclose' command on a line and follow it with three
-arguments separated by commas (commas are used as separators in an
-`@node' line in the same way).
-
- * The first argument to `@definfoenclose' is the @-command name
- *without* the `@';
-
- * the second argument is the Info start delimiter string; and,
-
- * the third argument is the Info end delimiter string.
-
-The latter two arguments enclose the highlighted text in the Info file.
-A delimiter string may contain spaces. Neither the start nor end
-delimiter is required. However, if you do not provide a start
-delimiter, you must follow the command name with two commas in a row;
-otherwise, the Info formatting commands will misinterpret the end
-delimiter string as a start delimiter string.
-
- After you have defined `@phoo' both for TeX and for Info, you can
-then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in
-italics in printed output.
-
- Note that each definition applies to its own formatter: one for TeX,
-the other for Info.
-
- Here is another example:
-
- @ifinfo
- @definfoenclose headword, , :
- @end ifinfo
- @iftex
- @global@let@headword=@b
- @end iftex
-
-This defines `@headword' as an Info formatting command that inserts
-nothing before and a colon after the argument and as a TeX formatting
-command to typeset its argument in bold.
-
-\1f
-File: texinfo.info, Node: Customized Highlighting-Footnotes, Up: Customized Highlighting
-
- (1) Currently, `@definfoenclose' works only with
-`texinfo-format-buffer' and `texinfo-format-region', not with
-`makeinfo'.
-
-\1f
File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top
Quotations and Examples
* quotation:: How to write a quotation.
* example:: How to write an example in a fixed-width font.
* noindent:: How to prevent paragraph indentation.
-* Lisp Example:: How to illustrate Lisp code.
-* smallexample & smalllisp:: Forms for the `@smallbook' option.
+* lisp:: How to illustrate Lisp code.
+* small:: Forms for `@smallbook'.
* display:: How to write an example in the current font.
* format:: How to write an example that does not narrow
the margins.
* cartouche:: How to draw cartouches around examples.
\1f
-File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Prev: Quotations and Examples, Up: Quotations and Examples
+File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Up: Quotations and Examples
-The Block Enclosing Commands
-============================
+Block Enclosing Commands
+========================
- Here are commands for quotations and examples:
+ Here are commands for quotations and examples, explained further in
+the following sections:
`@quotation'
Indicate text that is quoted. The text is filled, indented, and
Illustrate code, commands, and the like. The text is printed in a
fixed-width font, and indented but not filled.
-`@lisp'
- Illustrate Lisp code. The text is printed in a fixed-width font,
- and indented but not filled.
-
`@smallexample'
- Illustrate code, commands, and the like. Similar to `@example',
- except that in TeX this command typesets text in a smaller font
- for the smaller `@smallbook' format than for the 8.5 by 11 inch
- format.
+ Same as `@example', except that in TeX this command typesets text
+ in a smaller font for the `@smallbook' format than for the default
+ 8.5 by 11 inch format.
+
+`@lisp'
+ Like `@example', but specifically for illustrating Lisp code. The
+ text is printed in a fixed-width font, and indented but not filled.
`@smalllisp'
- Illustrate Lisp code. Similar to `@lisp', except that in TeX this
- command typesets text in a smaller font for the smaller
- `@smallbook' format than for the 8.5 by 11 inch format.
+ Is to `@lisp' as `@smallexample' is to `@example'.
`@display'
Display illustrative text. The text is indented but not filled,
- and no font is specified (so, by default, the font is roman).
+ and no font is selected (so, by default, the font is roman).
+
+`@smalldisplay'
+ Is to `@display' as `@smallexample' is to `@example'.
`@format'
- Print illustrative text. The text is not indented and not filled
- and no font is specified (so, by default, the font is roman).
+ Like `@display' (the text is not filled and no font is selected),
+ but the text is not indented.
+
+`@smallformat'
+ Is to `@format' as `@smallexample' is to `@example'.
The `@exdent' command is used within the above constructs to undo the
indentation of a line.
You can use the `@cartouche' command within one of the above
constructs to highlight the example or quotation by drawing a box with
-rounded corners around it. (The `@cartouche' command affects only the
-printed manual; it has no effect in the Info file; see *Note Drawing
-Cartouches Around Examples: cartouche.)
+rounded corners around it. *Note Drawing Cartouches Around Examples:
+cartouche.
\1f
File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples
obtained by indenting each line with five spaces.
Write an `@example' command at the beginning of a line by itself.
-This line will disappear from the output. Mark the end of the example
-with an `@end example' command, also written at the beginning of a line
-by itself. The `@end example' will disappear from the output.
+Mark the end of the example with an `@end example' command, also
+written at the beginning of a line by itself.
For example,
mv foo bar
- Since the lines containing `@example' and `@end example' will
-disappear, you should put a blank line before the `@example' and
-another blank line after the `@end example'. (Remember that blank
-lines between the beginning `@example' and the ending `@end example'
-will appear in the output.)
+ The lines containing `@example' and `@end example' will disappear
+from the output. To make the output look good, you should put a blank
+line before the `@example' and another blank line after the `@end
+example'. Note that blank lines inside the beginning `@example' and
+the ending `@end example' will appear in the output.
*Caution:* Do not use tabs in the lines of an example (or anywhere
else in Texinfo, for that matter)! TeX treats tabs as single
convert tabs in a region to multiple spaces.)
Examples are often, logically speaking, "in the middle" of a
-paragraph, and the text continues after an example should not be
+paragraph, and the text that continues after an example should not be
indented. The `@noindent' command prevents a piece of text from being
indented as if it were a new paragraph. (*Note noindent::.)
`@code': code.)
\1f
-File: texinfo.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples
+File: texinfo.info, Node: noindent, Next: lisp, Prev: example, Up: Quotations and Examples
`@noindent'
===========
Do not put braces after an `@noindent' command; they are not
necessary, since `@noindent' is a command used outside of paragraphs
-(*note Command Syntax::.).
+(*note Command Syntax::).
\1f
-File: texinfo.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples
+File: texinfo.info, Node: lisp, Next: small, Prev: noindent, Up: Quotations and Examples
`@lisp'
=======
Use `@lisp' instead of `@example' to preserve information regarding
the nature of the example. This is useful, for example, if you write a
function that evaluates only and all the Lisp code in a Texinfo file.
-Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp
-Example-Footnotes::)
+Then you can use the Texinfo file as a Lisp library.(1) (*note
+lisp-Footnote-1::)
Mark the end of `@lisp' with `@end lisp' on a line by itself.
\1f
-File: texinfo.info, Node: Lisp Example-Footnotes, Up: Lisp Example
+File: texinfo.info, Node: lisp-Footnotes, Up: lisp
(1) It would be straightforward to extend Texinfo to work in a
similar fashion for C, Fortran, or other languages.
\1f
-File: texinfo.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples
+File: texinfo.info, Node: small, Next: display, Prev: lisp, Up: Quotations and Examples
-`@smallexample' and `@smalllisp'
-================================
+`@small...' Block Commands
+==========================
In addition to the regular `@example' and `@lisp' commands, Texinfo
-has two other "example-style" commands. These are the `@smallexample'
-and `@smalllisp' commands. Both these commands are designed for use
-with the `@smallbook' command that causes TeX to produce a printed
-manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11
-inch format.
-
- In TeX, the `@smallexample' and `@smalllisp' commands typeset text in
-a smaller font for the smaller `@smallbook' format than for the 8.5 by
-11 inch format. Consequently, many examples containing long lines fit
-in a narrower, `@smallbook' page without needing to be shortened. Both
-commands typeset in the normal font size when you format for the 8.5 by
-11 inch size; indeed, in this situation, the `@smallexample' and
-`@smalllisp' commands are defined to be the `@example' and `@lisp'
-commands.
-
- In Info, the `@smallexample' and `@smalllisp' commands are equivalent
-to the `@example' and `@lisp' commands, and work exactly the same.
-
- Mark the end of `@smallexample' or `@smalllisp' with `@end
-smallexample' or `@end smalllisp', respectively.
+has "small" example-style commands. These are `@smalldisplay',
+`@smallexample', `@smallformat', and `@smalllisp'. All of these
+commands are designed for use with the `@smallbook' command (which
+causes TeX to format a printed book for a 7 by 9.25 inch trim size
+rather than the default 8.5 by 11 inch size).
+
+ In TeX, the `@small...' commands typeset text in a smaller font for
+the smaller `@smallbook' format than for the 8.5 by 11 inch format.
+Consequently, many examples containing long lines fit in a narrower,
+`@smallbook' page without needing to be shortened. Both commands
+typeset in the normal font size when you format for the 8.5 by 11 inch
+size. Indeed, in this situation, the `@small...' commands are
+equivalent to their non-small versions.
+
+ In Info, the `@small...' commands are also equivalent to their
+non-small companion commands.
+
+ Mark the end of an `@small...' block with a corresponding `@end
+small...'. For example, pair `@smallexample' with `@end smallexample'.
This is an example of text written between `@smallexample' and
`@end smallexample'. In Info and in an 8.5 by 11 inch manual,
this text appears in its normal size; but in a 7 by 9.25 inch manual,
this text appears in a smaller font.
- The `@smallexample' and `@smalllisp' commands make it easier to
-prepare smaller format manuals without forcing you to edit examples by
-hand to fit them onto narrower pages.
+ The `@small...' commands make it easier to prepare smaller format
+manuals without forcing you to edit examples by hand to fit them onto
+narrower pages.
- As a general rule, a printed document looks better if you write all
-the examples in a chapter consistently in `@example' or in
-`@smallexample'. Only occasionally should you mix the two formats.
+ As a general rule, a printed document looks better if you use only one
+of (for example) `@example' or in `@smallexample' consistently within a
+chapter. Only occasionally should you mix the two formats.
*Note Printing "Small" Books: smallbook, for more information about
the `@smallbook' command.
\1f
-File: texinfo.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples
+File: texinfo.info, Node: display, Next: format, Prev: small, Up: Quotations and Examples
-`@display'
-==========
+`@display' and `@smalldisplay'
+==============================
The `@display' command begins a kind of example. It is like the
`@example' command except that, in a printed manual, `@display' does
and an `@end display' command. The `@display' command
indents the text, but does not fill it.
+ Texinfo also provides a command `@smalldisplay', which is like
+`@display' but uses a smaller font in `@smallbook' format. *Note
+small::.
+
\1f
File: texinfo.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples
-`@format'
-=========
+`@format' and `@smallformat'
+============================
The `@format' command is similar to `@example' except that, in the
printed manual, `@format' does not select the fixed-width font and does
from this example,
the `@format' command does not fill the text.
+ Texinfo also provides a command `@smallformat', which is like
+`@format' but uses a smaller font in `@smallbook' format. *Note
+small::.
+
\1f
File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples
right justifies every line but leaves the
left end ragged.
-\1f
-File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples
-
-Drawing Cartouches Around Examples
-==================================
-
- In a printed manual, the `@cartouche' command draws a box with
-rounded corners around its contents. You can use this command to
-further highlight an example or quotation. For instance, you could
-write a manual in which one type of example is surrounded by a cartouche
-for emphasis.
-
- The `@cartouche' command affects only the printed manual; it has no
-effect in the Info file.
-
- For example,
-
- @example
- @cartouche
- % pwd
- /usr/local/share/emacs
- @end cartouche
- @end example
-
-surrounds the two-line example with a box with rounded corners, in the
-printed manual.
-
-\1f
-File: texinfo.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top
-
-Lists and Tables
-****************
-
- Texinfo has several ways of making lists and tables. Lists can be
-bulleted or numbered; two-column tables can highlight the items in the
-first column; multi-column tables are also supported.
-
-* Menu:
-
-* Introducing Lists:: Texinfo formats lists for you.
-* itemize:: How to construct a simple list.
-* enumerate:: How to construct a numbered list.
-* Two-column Tables:: How to construct a two-column table.
-* Multi-column Tables:: How to construct generalized tables.
-
-\1f
-File: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, Up: Lists and Tables
-
-Introducing Lists
-=================
-
- Texinfo automatically indents the text in lists or tables, and numbers
-an enumerated list. This last feature is useful if you modify the
-list, since you do not need to renumber it yourself.
-
- Numbered lists and tables begin with the appropriate @-command at the
-beginning of a line, and end with the corresponding `@end' command on a
-line by itself. The table and itemized-list commands also require that
-you write formatting information on the same line as the beginning
-@-command.
-
- Begin an enumerated list, for example, with an `@enumerate' command
-and end the list with an `@end enumerate' command. Begin an itemized
-list with an `@itemize' command, followed on the same line by a
-formatting command such as `@bullet', and end the list with an `@end
-itemize' command.
-
- Precede each element of a list with an `@item' or `@itemx' command.
-
-Here is an itemized list of the different kinds of table and lists:
-
- * Itemized lists with and without bullets.
-
- * Enumerated lists, using numbers or letters.
-
- * Two-column tables with highlighting.
-
-Here is an enumerated list with the same items:
-
- 1. Itemized lists with and without bullets.
-
- 2. Enumerated lists, using numbers or letters.
-
- 3. Two-column tables with highlighting.
-
-And here is a two-column table with the same items and their @-commands:
-
-`@itemize'
- Itemized lists with and without bullets.
-
-`@enumerate'
- Enumerated lists, using numbers or letters.
-
-`@table'
-`@ftable'
-`@vtable'
- Two-column tables with indexing.
-
-\1f
-File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables
-
-Making an Itemized List
-=======================
-
- The `@itemize' command produces sequences of indented paragraphs,
-with a bullet or other mark inside the left margin at the beginning of
-each paragraph for which such a mark is desired.
-
- Begin an itemized list by writing `@itemize' at the beginning of a
-line. Follow the command, on the same line, with a character or a
-Texinfo command that generates a mark. Usually, you will write
-`@bullet' after `@itemize', but you can use `@minus', or any character
-or any special symbol that results in a single character in the Info
-file. (When you write `@bullet' or `@minus' after an `@itemize'
-command, you may omit the `{}'.)
-
- Write the text of the indented paragraphs themselves after the
-`@itemize', up to another line that says `@end itemize'.
-
- Before each paragraph for which a mark in the margin is desired, write
-a line that says just `@item'. Do not write any other text on this
-line.
-
- Usually, you should put a blank line before an `@item'. This puts a
-blank line in the Info file. (TeX inserts the proper interline
-whitespace in either case.) Except when the entries are very brief,
-these blank lines make the list look better.
-
- Here is an example of the use of `@itemize', followed by the output
-it produces. Note that `@bullet' produces an `*' in Info and a round
-dot in TeX.
-
- @itemize @bullet
- @item
- Some text for foo.
-
- @item
- Some text
- for bar.
- @end itemize
-
-This produces:
-
- * Some text for foo.
-
- * Some text for bar.
-
- Itemized lists may be embedded within other itemized lists. Here is a
-list marked with dashes embedded in a list marked with bullets:
-
- @itemize @bullet
- @item
- First item.
-
- @itemize @minus
- @item
- Inner item.
-
- @item
- Second inner item.
- @end itemize
-
- @item
- Second outer item.
- @end itemize
-
-This produces:
-
- * First item.
-
- - Inner item.
-
- - Second inner item.
-
- * Second outer item.
-
-\1f
-File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables
-
-Making a Numbered or Lettered List
-==================================
-
- `@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
-that the labels on the items are successive integers or letters instead
-of bullets.
-
- Write the `@enumerate' command at the beginning of a line. The
-command does not require an argument, but accepts either a number or a
-letter as an option. Without an argument, `@enumerate' starts the list
-with the number `1'. With a numeric argument, such as `3', the command
-starts the list with that number. With an upper or lower case letter,
-such as `a' or `A', the command starts the list with that letter.
-
- Write the text of the enumerated list in the same way you write an
-itemized list: put `@item' on a line of its own before the start of
-each paragraph that you want enumerated. Do not write any other text
-on the line beginning with `@item'.
-
- You should put a blank line between entries in the list. This
-generally makes it easier to read the Info file.
-
- Here is an example of `@enumerate' without an argument:
-
- @enumerate
- @item
- Underlying causes.
-
- @item
- Proximate causes.
- @end enumerate
-
-This produces:
-
- 1. Underlying causes.
-
- 2. Proximate causes.
-
- Here is an example with an argument of `3':
-
- @enumerate 3
- @item
- Predisposing causes.
-
- @item
- Precipitating causes.
-
- @item
- Perpetuating causes.
- @end enumerate
-
-This produces:
-
- 3. Predisposing causes.
-
- 4. Precipitating causes.
-
- 5. Perpetuating causes.
-
- Here is a brief summary of the alternatives. The summary is
-constructed using `@enumerate' with an argument of `a'.
-
- a. `@enumerate'
-
- Without an argument, produce a numbered list, starting with the
- number 1.
-
- b. `@enumerate POSITIVE-INTEGER'
-
- With a (positive) numeric argument, start a numbered list with that
- number. You can use this to continue a list that you interrupted
- with other text.
-
- c. `@enumerate UPPER-CASE-LETTER'
-
- With an upper case letter as argument, start a list in which each
- item is marked by a letter, beginning with that upper case letter.
-
- d. `@enumerate LOWER-CASE-LETTER'
-
- With a lower case letter as argument, start a list in which each
- item is marked by a letter, beginning with that lower case letter.
-
- You can also nest enumerated lists, as in an outline.
-
-\1f
-File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables
-
-Making a Two-column Table
-=========================
-
- `@table' is similar to `@itemize' (*note `@itemize': itemize.), but
-allows you to specify a name or heading line for each item. The
-`@table' command is used to produce two-column tables, and is
-especially useful for glossaries, explanatory exhibits, and
-command-line option summaries.
-
-* Menu:
-
-* table:: How to construct a two-column table.
-* ftable vtable:: Automatic indexing for two-column tables.
-* itemx:: How to put more entries in the first column.
-
-\1f
-File: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables
-
-Using the `@table' Command
---------------------------
-
- Use the `@table' command to produce two-column tables.
-
- Write the `@table' command at the beginning of a line and follow it
-on the same line with an argument that is a Texinfo "indicating"
-command such as `@code', `@samp', `@var', or `@kbd' (*note
-Indicating::.). Although these commands are usually followed by
-arguments in braces, in this case you use the command name without an
-argument because `@item' will supply the argument. This command will
-be applied to the text that goes into the first column of each item and
-determines how it will be highlighted. For example, `@code' will cause
-the text in the first column to be highlighted with an `@code' command.
-(We recommend `@code' for `@table''s of command-line options.)
-
- You may also choose to use the `@asis' command as an argument to
-`@table'. `@asis' is a command that does nothing; if you use this
-command after `@table', TeX and the Info formatting commands output the
-first column entries without added highlighting ("as is").
-
- (The `@table' command may work with other commands besides those
-listed here. However, you can only use commands that normally take
-arguments in braces.)
-
- Begin each table entry with an `@item' command at the beginning of a
-line. Write the first column text on the same line as the `@item'
-command. Write the second column text on the line following the
-`@item' line and on subsequent lines. (You do not need to type
-anything for an empty second column entry.) You may write as many
-lines of supporting text as you wish, even several paragraphs. But
-only text on the same line as the `@item' will be placed in the first
-column.
-
- Normally, you should put a blank line before an `@item' line. This
-puts a blank like in the Info file. Except when the entries are very
-brief, a blank line looks better.
-
- The following table, for example, highlights the text in the first
-column with an `@samp' command:
-
- @table @samp
- @item foo
- This is the text for
- @samp{foo}.
-
- @item bar
- Text for @samp{bar}.
- @end table
-
-This produces:
-
-`foo'
- This is the text for `foo'.
-
-`bar'
- Text for `bar'.
-
- If you want to list two or more named items with a single block of
-text, use the `@itemx' command. (*Note `@itemx': itemx.)
-
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples
+
+Drawing Cartouches Around Examples
+==================================
+
+ In a printed manual, the `@cartouche' command draws a box with
+rounded corners around its contents. You can use this command to
+further highlight an example or quotation. For instance, you could
+write a manual in which one type of example is surrounded by a cartouche
+for emphasis.
+
+ `@cartouche' affects only the printed manual; it has no effect in
+other output files.
+
+ For example,
+
+ @example
+ @cartouche
+ % pwd
+ /usr/local/share/emacs
+ @end cartouche
+ @end example
+
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+\1f
+File: texinfo.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top
+
+Lists and Tables
+****************
+
+ Texinfo has several ways of making lists and tables. Lists can be
+bulleted or numbered; two-column tables can highlight the items in the
+first column; multi-column tables are also supported.
+
+* Menu:
+
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* enumerate:: How to construct a numbered list.
+* Two-column Tables:: How to construct a two-column table.
+* Multi-column Tables:: How to construct generalized tables.
+
+\1f
+File: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, Up: Lists and Tables
+
+Introducing Lists
+=================
+
+ Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list. This last feature is useful if you modify the
+list, since you do not need to renumber it yourself.
+
+ Numbered lists and tables begin with the appropriate @-command at the
+beginning of a line, and end with the corresponding `@end' command on a
+line by itself. The table and itemized-list commands also require that
+you write formatting information on the same line as the beginning
+@-command.
+
+ Begin an enumerated list, for example, with an `@enumerate' command
+and end the list with an `@end enumerate' command. Begin an itemized
+list with an `@itemize' command, followed on the same line by a
+formatting command such as `@bullet', and end the list with an `@end
+itemize' command.
+
+ Precede each element of a list with an `@item' or `@itemx' command.
+
+
+Here is an itemized list of the different kinds of table and lists:
+
+ * Itemized lists with and without bullets.
+
+ * Enumerated lists, using numbers or letters.
+
+ * Two-column tables with highlighting.
+
+
+Here is an enumerated list with the same items:
+
+ 1. Itemized lists with and without bullets.
+
+ 2. Enumerated lists, using numbers or letters.
+
+ 3. Two-column tables with highlighting.
+
+
+And here is a two-column table with the same items and their @-commands:
+
+`@itemize'
+ Itemized lists with and without bullets.
+
+`@enumerate'
+ Enumerated lists, using numbers or letters.
+
+`@table'
+`@ftable'
+`@vtable'
+ Two-column tables, optionally with indexing.
+
+\1f
+File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables
+
+`@itemize': Making an Itemized List
+===================================
+
+ The `@itemize' command produces sequences of indented paragraphs,
+with a bullet or other mark inside the left margin at the beginning of
+each paragraph for which such a mark is desired.
+
+ Begin an itemized list by writing `@itemize' at the beginning of a
+line. Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark. Usually, you will write
+`@bullet' after `@itemize', but you can use `@minus', or any command or
+character that results in a single character in the Info file. If you
+don't want any mark at all, use `@w'. (When you write the mark command
+such as `@bullet' after an `@itemize' command, you may omit the `{}'.)
+If you don't specify a mark command, the default is `@bullet'.
+
+ Write the text of the indented paragraphs themselves after the
+`@itemize', up to another line that says `@end itemize'.
+
+ Before each paragraph for which a mark in the margin is desired,
+write a line that says just `@item'. It is ok to have text following
+the `@item'.
+
+ Usually, you should put a blank line before an `@item'. This puts a
+blank line in the Info file. (TeX inserts the proper interline
+whitespace in either case.) Except when the entries are very brief,
+these blank lines make the list look better.
+
+ Here is an example of the use of `@itemize', followed by the output
+it produces. `@bullet' produces an `*' in Info and a round dot in TeX.
+
+ @itemize @bullet
+ @item
+ Some text for foo.
+
+ @item
+ Some text
+ for bar.
+ @end itemize
+
+This produces:
+
+ * Some text for foo.
+
+ * Some text for bar.
+
+ Itemized lists may be embedded within other itemized lists. Here is a
+list marked with dashes embedded in a list marked with bullets:
+
+ @itemize @bullet
+ @item
+ First item.
+
+ @itemize @minus
+ @item
+ Inner item.
+
+ @item
+ Second inner item.
+ @end itemize
+
+ @item
+ Second outer item.
+ @end itemize
+
+This produces:
+
+ * First item.
+
+ - Inner item.
+
+ - Second inner item.
+
+ * Second outer item.
+
+\1f
+File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables
+
+`@enumerate': Making a Numbered or Lettered List
+================================================
+
+ `@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
+that the labels on the items are successive integers or letters instead
+of bullets.
+
+ Write the `@enumerate' command at the beginning of a line. The
+command does not require an argument, but accepts either a number or a
+letter as an option. Without an argument, `@enumerate' starts the list
+with the number `1'. With a numeric argument, such as `3', the command
+starts the list with that number. With an upper or lower case letter,
+such as `a' or `A', the command starts the list with that letter.
+
+ Write the text of the enumerated list in the same way you write an
+itemized list: put `@item' on a line of its own before the start of
+each paragraph that you want enumerated. Do not write any other text
+on the line beginning with `@item'.
+
+ You should put a blank line between entries in the list. This
+generally makes it easier to read the Info file.
+
+ Here is an example of `@enumerate' without an argument:
+
+ @enumerate
+ @item
+ Underlying causes.
+
+ @item
+ Proximate causes.
+ @end enumerate
+
+This produces:
+
+ 1. Underlying causes.
+
+ 2. Proximate causes.
+
+
+
+ Here is an example with an argument of `3':
+
+
+ @enumerate 3
+ @item
+ Predisposing causes.
+
+ @item
+ Precipitating causes.
+
+ @item
+ Perpetuating causes.
+ @end enumerate
+
+This produces:
+
+ 3. Predisposing causes.
+
+ 4. Precipitating causes.
+
+ 5. Perpetuating causes.
+
+
+
+ Here is a brief summary of the alternatives. The summary is
+constructed using `@enumerate' with an argument of `a'.
+
+
+ a. `@enumerate'
+
+ Without an argument, produce a numbered list, starting with the
+ number 1.
+
+ b. `@enumerate POSITIVE-INTEGER'
+
+ With a (positive) numeric argument, start a numbered list with that
+ number. You can use this to continue a list that you interrupted
+ with other text.
+
+ c. `@enumerate UPPER-CASE-LETTER'
+
+ With an upper case letter as argument, start a list in which each
+ item is marked by a letter, beginning with that upper case letter.
+
+ d. `@enumerate LOWER-CASE-LETTER'
+
+ With a lower case letter as argument, start a list in which each
+ item is marked by a letter, beginning with that lower case letter.
+
+ You can also nest enumerated lists, as in an outline.
+
+\1f
+File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables
+
+Making a Two-column Table
+=========================
+
+ `@table' is similar to `@itemize' (*note `@itemize': itemize.), but
+allows you to specify a name or heading line for each item. The
+`@table' command is used to produce two-column tables, and is
+especially useful for glossaries, explanatory exhibits, and
+command-line option summaries.
+
+* Menu:
+
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
+
+\1f
+File: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables
+
+Using the `@table' Command
+--------------------------
+
+ Use the `@table' command to produce two-column tables.
+
+ Write the `@table' command at the beginning of a line and follow it
+on the same line with an argument that is a Texinfo "indicating"
+command such as `@code', `@samp', `@var', or `@kbd' (*note
+Indicating::). Although these commands are usually followed by
+arguments in braces, in this case you use the command name without an
+argument because `@item' will supply the argument. This command will
+be applied to the text that goes into the first column of each item and
+determines how it will be highlighted. For example, `@code' will cause
+the text in the first column to be highlighted with an `@code' command.
+(We recommend `@code' for `@table''s of command-line options.)
+
+ You may also choose to use the `@asis' command as an argument to
+`@table'. `@asis' is a command that does nothing; if you use this
+command after `@table', TeX and the Info formatting commands output the
+first column entries without added highlighting ("as is").
+
+ (The `@table' command may work with other commands besides those
+listed here. However, you can only use commands that normally take
+arguments in braces.)
+
+ Begin each table entry with an `@item' command at the beginning of a
+line. Write the first column text on the same line as the `@item'
+command. Write the second column text on the line following the
+`@item' line and on subsequent lines. (You do not need to type
+anything for an empty second column entry.) You may write as many
+lines of supporting text as you wish, even several paragraphs. But
+only text on the same line as the `@item' will be placed in the first
+column, including any footnote.
+
+ Normally, you should put a blank line before an `@item' line. This
+puts a blank like in the Info file. Except when the entries are very
+brief, a blank line looks better.
+
+ The following table, for example, highlights the text in the first
+column with an `@samp' command:
+
+ @table @samp
+ @item foo
+ This is the text for
+ @samp{foo}.
+
+ @item bar
+ Text for @samp{bar}.
+ @end table
+
+This produces:
+
+`foo'
+ This is the text for `foo'.
+
+`bar'
+ Text for `bar'.
+
+ If you want to list two or more named items with a single block of
+text, use the `@itemx' command. (*Note `@itemx': itemx.)
+
+\1f
File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables
`@ftable' and `@vtable'
into the index of variables. This simplifies the task of creating
indices. Only the items on the same line as the `@item' commands are
indexed, and they are indexed in exactly the form that they appear on
-that line. *Note Creating Indices: Indices, for more information about
-indices.
+that line. *Note Indices::, for more information about indices.
Begin a two-column table using `@ftable' or `@vtable' by writing the
@-command at the beginning of a line, followed on the same line by an
* Multitable Rows:: Defining multitable rows, with examples.
\1f
-File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Prev: Multi-column Tables, Up: Multi-column Tables
+File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Up: Multi-column Tables
Multitable Column Widths
------------------------
The fractions need not add up exactly to 1.0, as these do not.
This allows you to produce tables that do not need the full line
- length.
+ length. You can use a leading zero if you wish.
2. To specify a prototype row, write the longest entry for each column
enclosed in braces after the `@multitable' command. For example:
your source file as necessary.
Here is a complete example of a multi-column table (the text is from
-`The GNU Emacs Manual', *note Splitting Windows: (xemacs)Split Window.):
+`The GNU Emacs Manual', *note Splitting Windows: (emacs)Split Window.):
@multitable @columnfractions .15 .45 .4
@item Key @tab Command @tab Description
produces:
-Key Command Description
-C-x 2 `split-window-vertically' Split the selected window
- into two windows, with one
- above the other.
-C-x 3 `split-window-horizontally' Split the selected window
- into two windows positioned
- side by side.
-C-Mouse-2 In the mode line or scroll
- bar of a window, split that
- window.
+Key Command Description
+C-x 2 `split-window-vertically' Split the selected window
+ into two windows, with one
+ above the other.
+C-x 3 `split-window-horizontally' Split the selected window
+ into two windows positioned
+ side by side.
+C-Mouse-2 In the mode line or scroll
+ bar of a window, split that
+ window.
\1f
File: texinfo.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top
-Creating Indices
-****************
+Indices
+*******
Using Texinfo, you can generate indices without having to sort and
collate entries manually. In an index, the entries are listed in
====================
When you are making index entries, it is good practice to think of the
-different ways people may look for something. Different people *do
-not* think of the same words when they look something up. A helpful
+different ways people may look for something. Different people _do
+not_ think of the same words when they look something up. A helpful
index will have items indexed under all the different words that people
may use. For example, one reader may think it obvious that the
two-letter names for indices should be listed under "Indices,
font and entries for the other indices are printed in a small `@code'
font. You may change the way part of an entry is printed with the
usual Texinfo commands, such as `@file' for file names and `@emph' for
-emphasis (*note Marking Text::.).
+emphasis (*note Marking Text::).
The six indexing commands for predefined indices are:
Make an entry in the data type index for DATA TYPE.
*Caution:* Do not use a colon in an index entry. In Info, a colon
- separates the menu entry name from the node name. An extra colon
- confuses Info. *Note The Parts of a Menu: Menu Parts, for more
- information about the structure of a menu entry.
-
- If you write several identical index entries in different places in a
-Texinfo file, the index in the printed manual will list all the pages to
-which those entries refer. However, the index in the Info file will
-list *only* the node that references the *first* of those index
-entries. Therefore, it is best to write indices in which each entry
-refers to only one place in the Texinfo file. Fortunately, this
-constraint is a feature rather than a loss since it means that the index
-will be easy to use. Otherwise, you could create an index that lists
-several pages for one entry and your reader would not know to which page
-to turn. If you have two identical entries for one topic, change the
-topics slightly, or qualify them to indicate the difference.
+ separates the menu entry name from the node name, so a colon in
+ the entry itself confuses Info. *Note The Parts of a Menu: Menu
+ Parts, for more information about the structure of a menu entry.
You are not actually required to use the predefined indices for their
canonical purposes. For example, suppose you wish to index some C
You should define new indices within or right after the end-of-header
line of a Texinfo file, before any `@synindex' or `@syncodeindex'
-commands (*note Header::.).
+commands (*note Header::).
\1f
File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top
* math:: How to format a mathematical expression.
* Glyphs:: How to indicate results of evaluation,
expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
* Images:: How to include graphics.
\1f
* dmn:: How to format a dimension.
\1f
-File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Inserting Space, Up: Inserting Space
+File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Up: Inserting Space
Not Ending a Sentence
---------------------
Depending on whether a period or exclamation point or question mark is
inside or at the end of a sentence, less or more space is inserted after
-a period in a typeset manual. Since it is not always possible for
-Texinfo to determine when a period ends a sentence and when it is used
-in an abbreviation, special commands are needed in some circumstances.
-(Usually, Texinfo can guess how to handle periods, so you do not need to
+a period in a typeset manual. Since it is not always possible to
+determine when a period ends a sentence and when it is used in an
+abbreviation, special commands are needed in some circumstances.
+Usually, Texinfo can guess how to handle periods, so you do not need to
use the special commands; you just enter a period as you would if you
were using a typewriter, which means you put two spaces after the
-period, question mark, or exclamation mark that ends a sentence.)
+period, question mark, or exclamation mark that ends a sentence.
Use the `@:' command after a period, question mark, exclamation mark,
or colon that should not be followed by extra space. For example, use
The meanings of `@:' and `@.' in Texinfo are designed to work well
with the Emacs sentence motion commands (*note Sentences:
-(xemacs)Sentences.). This made it necessary for them to be
-incompatible with some other formatting systems that use @-commands.
+(emacs)Sentences.).
Do not put braces after any of these commands.
Spacey example.
Other possible uses of `@SPACE' have been subsumed by `@multitable'
-(*note Multi-column Tables::.).
+(*note Multi-column Tables::).
Do not follow any of these commands with braces.
Not everyone uses this style. Some people prefer `8.27 in.@:' or
`8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases,
however, the formatters may insert a line break between the number and
-the dimension, so use `@w' (*note w::.). Also, if you write a period
+the dimension, so use `@w' (*note w::). Also, if you write a period
after an abbreviation within a sentence, you should write `@:' after
the period to prevent TeX from inserting extra whitespace, as shown
-here. *Note Inserting Space::.
+here. *Note Not Ending a Sentence::.
\1f
File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions
Here is a table with the commands Texinfo provides for inserting
floating accents. The commands with non-alphabetic names do not take
braces around their argument (which is taken to be the next character).
-(Exception: `@,' *does* take braces around its argument.) This is so
+(Exception: `@,' _does_ take braces around its argument.) This is so
as to make the source as convenient to type and read as possible, since
accented characters are very common in some languages.
-Command Output What
-@"o "o umlaut accent
-@'o 'o acute accent
-@,{c} c, cedilla accent
-@=o =o macron/overbar accent
-@^o ^o circumflex accent
-@`o `o grave accent
-@~o ~o tilde accent
-@dotaccent{o} .o overdot accent
-@H{o} ''o long Hungarian umlaut
-@ringaccent{o} *o ring accent
-@tieaccent{oo} [oo tie-after accent
-@u{o} (o breve accent
-@ubaraccent{o} o_ underbar accent
-@udotaccent{o} o-. underdot accent
-@v{o} <o hacek or check accent
+Command Output What
+@"o o" umlaut accent
+@'o o' acute accent
+@,{c} c, cedilla accent
+@=o o= macron/overbar accent
+@^o o^ circumflex accent
+@`o o` grave accent
+@~o o~ tilde accent
+@dotaccent{o} o. overdot accent
+@H{o} o'' long Hungarian umlaut
+@ringaccent{o} o* ring accent
+@tieaccent{oo} oo[ tie-after accent
+@u{o} o( breve accent
+@ubaraccent{o} o_ underbar accent
+@udotaccent{o} .o underdot accent
+@v{o} o< hacek or check accent
This table lists the Texinfo commands for inserting other characters
commonly used in languages other than English.
-@exclamdown{} ! upside-down !
-@questiondown{} ? upside-down ?
-@aa{},@AA{} aa,AA A,a with circle
-@ae{},@AE{} ae,AE ae,AE ligatures
-@dotless{i} i dotless i
-@dotless{j} j dotless j
-@l{},@L{} l/,L/ suppressed-L,l
-@o{},@O{} o/,O/ O,o with slash
-@oe{},@OE{} oe,OE OE,oe ligatures
-@ss{} ss es-zet or sharp S
+@exclamdown{} ! upside-down !
+@questiondown{} ? upside-down ?
+@aa{},@AA{} aa,AA a,A with circle
+@ae{},@AE{} ae,AE ae,AE ligatures
+@dotless{i} i dotless i
+@dotless{j} j dotless j
+@l{},@L{} /l,/L suppressed-L,l
+@o{},@O{} /o,/O O,o with slash
+@oe{},@OE{} oe,OE oe,OE ligatures
+@ss{} ss es-zet or sharp S
\1f
File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions
-Inserting Ellipsis, Dots, and Bullets
-=====================================
+Inserting Ellipsis and Bullets
+==============================
An "ellipsis" (a line of dots) is not typeset as a string of periods,
so a special command is used for ellipsis in Texinfo. The `@bullet'
* bullet:: How to insert a bullet.
\1f
-File: texinfo.info, Node: dots, Next: bullet, Prev: Dots Bullets, Up: Dots Bullets
+File: texinfo.info, Node: dots, Next: bullet, Up: Dots Bullets
-`@dots'{} (...)
----------------
+`@dots'{} (...) and `@enddots'{} (....)
+---------------------------------------
Use the `@dots{}' command to generate an ellipsis, which is three
dots in a row, appropriately spaced, like this: `...'. Do not simply
* copyright symbol:: How to use `@copyright'{}.
\1f
-File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright
+File: texinfo.info, Node: tex, Next: copyright symbol, Up: TeX and copyright
`@TeX'{} (TeX)
--------------
\1f
File: texinfo.info, Node: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions
-`@pounds{}' (#): Pounds Sterling
+`@pounds'{} (#): Pounds Sterling
================================
Use the `@pounds{}' command to generate `#'. In a printed manual,
\1f
File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions
-`@math' - Inserting Mathematical Expressions
-============================================
+`@math': Inserting Mathematical Expressions
+===========================================
You can write a short mathematical expression with the `@math'
command. Write the mathematical expression between braces, like this:
Thus, the `@math' command has no effect on the Info output.
For complex mathematical expressions, you can also use TeX directly
-(*note Raw Formatter Commands::.). When you use TeX directly, remember
+(*note Raw Formatter Commands::). When you use TeX directly, remember
to write the mathematical expression between one or two `$'
(dollar-signs) as appropriate.
\1f
-File: texinfo.info, Node: Glyphs, Next: Images, Prev: math, Up: Insertions
+File: texinfo.info, Node: Glyphs, Next: Footnotes, Prev: math, Up: Insertions
Glyphs for Examples
===================
This indicates that evaluating `(make-sparse-keymap)' produces
identical results to evaluating `(list 'keymap)'.
-\1f
-File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs
-
-`@point{}' (-!-): Indicating Point in a Buffer
-----------------------------------------------
-
- Sometimes you need to show an example of text in an Emacs buffer. In
-such examples, the convention is to include the entire contents of the
-buffer in question between two lines of dashes containing the buffer
-name.
-
- You can use the `@point{}' command to show the location of point in
-the text in the buffer. (The symbol for point, of course, is not part
-of the text in the buffer; it indicates the place *between* two
-characters where point is located.)
-
- The `@point{}' command is displayed as `-!-' in Info and as a small
-five pointed star in the printed output.
-
- The following example shows the contents of buffer `foo' before and
-after evaluating a Lisp command to insert the word `changed'.
-
- ---------- Buffer: foo ----------
- This is the -!-contents of foo.
- ---------- Buffer: foo ----------
-
- (insert "changed ")
- => nil
- ---------- Buffer: foo ----------
- This is the changed -!-contents of foo.
- ---------- Buffer: foo ----------
-
- In a Texinfo source file, the example is written like this:
-
- @example
- ---------- Buffer: foo ----------
- This is the @point{}contents of foo.
- ---------- Buffer: foo ----------
-
- (insert "changed ")
- @result{} nil
- ---------- Buffer: foo ----------
- This is the changed @point{}contents of foo.
- ---------- Buffer: foo ----------
- @end example
-
-\1f
-File: texinfo.info, Node: Images, Prev: Glyphs, Up: Insertions
-
-Inserting Images
-================
-
- You can insert an image in an external file with the `@image' command:
-
- @image{FILENAME, [WIDTH], [HEIGHT]}
-
- The FILENAME argument is mandatory, and must not have an extension,
-because the different processors support different formats: TeX reads
-the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo'
-uses `FILENAME.txt' verbatim for Info output (more or less as if it was
-an `@example'). HTML output requires `FILENAME.jpg'.
-
- The optional WIDTH and HEIGHT arguments specify the size to scale the
-image to (they are ignored for Info output). If they are both
-specified, the image is presented in its natural size (given in the
-file); if only one is specified, the other is scaled proportionately;
-and if both are specified, both are respected, thus possibly distorting
-the original image by changing its aspect ratio.
-
- The WIDTH and HEIGHT may be specified using any valid TeX dimension,
-namely:
-
-pt
- point (72.27pt = 1in)
-
-pc
- pica (1pc = 12pt)
-
-bp
- big point (72bp = 1in)
-
-in
- inch
-
-cm
- centimeter (2.54cm = 1in)
-
-mm
- millimeter (10mm = 1cm)
-
-dd
- did^ot point (1157dd = 1238pt)
-
-cc
- cicero (1cc = 12dd)
-
-sp
- scaled point (65536sp = 1pt)
-
- For example, the following will scale a file `ridt.eps' to one inch
-vertically, with the width scaled proportionately:
-
- @image{ridt,,1in}
-
- For `@image' to work with TeX, the file `epsf.tex' must be installed
-somewhere that TeX can find it. This file is included in the Texinfo
-distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'.
-
-\1f
-File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
-
-Making and Preventing Breaks
-****************************
-
- Usually, a Texinfo file is processed both by TeX and by one of the
-Info formatting commands. Line, paragraph, or page breaks sometimes
-occur in the `wrong' place in one or other form of output. You must
-ensure that text looks right both in the printed manual and in the Info
-file.
-
- For example, in a printed manual, page breaks may occur awkwardly in
-the middle of an example; to prevent this, you can hold text together
-using a grouping command that keeps the text from being split across
-two pages. Conversely, you may want to force a page break where none
-would occur normally. Fortunately, problems like these do not often
-arise. When they do, use the break, break prevention, or pagination
-commands.
-
-* Menu:
-
-* Break Commands:: Cause and prevent splits.
-* Line Breaks:: How to force a single line to use two lines.
-* - and hyphenation:: How to tell TeX about hyphenation points.
-* w:: How to prevent unwanted line breaks.
-* sp:: How to insert blank lines.
-* page:: How to force the start of a new page.
-* group:: How to prevent unwanted page breaks.
-* need:: Another way to prevent unwanted page breaks.
-
-\1f
-File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks
-
-The Break Commands
-==================
-
- The break commands create or allow line and paragraph breaks:
-
-`@*'
- Force a line break.
-
-`@sp N'
- Skip N blank lines.
-
-`@-'
- Insert a discretionary hyphen.
-
-`@hyphenation{HY-PHEN-A-TED WORDS}'
- Define hyphen points in HY-PHEN-A-TED WORDS.
-
- The line-break-prevention command holds text together all on one line:
-
-`@w{TEXT}'
- Prevent TEXT from being split and hyphenated across two lines.
-
- The pagination commands apply only to printed output, since Info
-files do not have pages.
-
-`@page'
- Start a new page in the printed manual.
-
-`@group'
- Hold text together that must appear on one printed page.
-
-`@need MILS'
- Start a new printed page if not enough space on this one.
-
-\1f
-File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
-
-`@*': Generate Line Breaks
-==========================
-
- The `@*' command forces a line break in both the printed manual and
-in Info.
-
- For example,
-
- This line @* is broken @*in two places.
-
-produces
-
- This line
- is broken
- in two places.
-
-(Note that the space after the first `@*' command is faithfully carried
-down to the next line.)
-
- The `@*' command is often used in a file's copyright page:
-
- This is edition 2.0 of the Texinfo documentation,@*
- and is for ...
-
-In this case, the `@*' command keeps TeX from stretching the line
-across the whole page in an ugly manner.
-
- *Please note:* Do not write braces after an `@*' command; they are
- not needed.
-
- Do not write an `@refill' command at the end of a paragraph
- containing an `@*' command; it will cause the paragraph to be
- refilled after the line break occurs, negating the effect of the
- line break.
-
-\1f
-File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
-
-`@-' and `@hyphenation': Helping TeX hyphenate
-==============================================
-
- Although TeX's hyphenation algorithm is generally pretty good, it
-does miss useful hyphenation points from time to time. (Or, far more
-rarely, insert an incorrect hyphenation.) So, for documents with an
-unusual vocabulary or when fine-tuning for a printed edition, you may
-wish to help TeX out. Texinfo supports two commands for this:
-
-`@-'
- Insert a discretionary hyphen, i.e., a place where TeX can (but
- does not have to) hyphenate. This is especially useful when you
- notice an overfull hbox is due to TeX missing a hyphenation (*note
- Overfull hboxes::.). TeX will not insert any hyphenation points
- in a word containing `@-'.
-
-`@hyphenation{HY-PHEN-A-TED WORDS}'
- Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
- a `-' at each hyphenation point. For example:
- @hyphenation{man-u-script man-u-scripts}
-
- TeX only uses the specified hyphenation points when the words
- match exactly, so give all necessary variants.
-
- Info output is not hyphenated, so these commands have no effect there.
-
-\1f
-File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks
-
-`@w'{TEXT}: Prevent Line Breaks
-===============================
-
- `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
-
- You can use the `@w' command to prevent TeX from automatically
-hyphenating a long name or phrase that happens to fall near the end of a
-line.
-
- You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
-
-produces
-
- You can copy GNU software from `ftp.gnu.ai.mit.edu'.
-
- *Caution:* Do not write an `@refill' command at the end of a
- paragraph containing an `@w' command; it will cause the paragraph
- to be refilled and may thereby negate the effect of the `@w'
- command.
-
-\1f
-File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks
-
-`@sp' N: Insert Blank Lines
-===========================
-
- A line beginning with and containing only `@sp N' generates N blank
-lines of space in both the printed manual and the Info file. `@sp'
-also forces a paragraph break. For example,
-
- @sp 2
-
-generates two blank lines.
-
- The `@sp' command is most often used in the title page.
-
-\1f
-File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks
-
-`@page': Start a New Page
-=========================
-
- A line containing only `@page' starts a new page in a printed manual.
-The command has no effect on Info files since they are not paginated.
-An `@page' command is often used in the `@titlepage' section of a
-Texinfo file to start the copyright page.
-
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs Summary
+
+`@point{}' (-!-): Indicating Point in a Buffer
+----------------------------------------------
+
+ Sometimes you need to show an example of text in an Emacs buffer. In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
+name.
+
+ You can use the `@point{}' command to show the location of point in
+the text in the buffer. (The symbol for point, of course, is not part
+of the text in the buffer; it indicates the place _between_ two
+characters where point is located.)
+
+ The `@point{}' command is displayed as `-!-' in Info and as a small
+five pointed star in the printed output.
+
+ The following example shows the contents of buffer `foo' before and
+after evaluating a Lisp command to insert the word `changed'.
+
+ ---------- Buffer: foo ----------
+ This is the -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+ (insert "changed ")
+ => nil
+ ---------- Buffer: foo ----------
+ This is the changed -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+ In a Texinfo source file, the example is written like this:
+
+ @example
+ ---------- Buffer: foo ----------
+ This is the @point{}contents of foo.
+ ---------- Buffer: foo ----------
+
+ (insert "changed ")
+ @result{} nil
+ ---------- Buffer: foo ----------
+ This is the changed @point{}contents of foo.
+ ---------- Buffer: foo ----------
+ @end example
+
+\1f
+File: texinfo.info, Node: Footnotes, Next: Images, Prev: Glyphs, Up: Insertions
+
+Footnotes
+=========
+
+ A "footnote" is for a reference that documents or elucidates the
+primary text.(1) (*note Footnotes-Footnote-1::)
+
+* Menu:
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+
+\1f
+File: texinfo.info, Node: Footnotes-Footnotes, Up: Footnotes
+
+ (1) A footnote should complement or expand upon the primary text, but
+a reader should not need to read a footnote to understand the primary
+text. For a thorough discussion of footnotes, see `The Chicago Manual
+of Style', which is published by the University of Chicago Press.
+
+\1f
+File: texinfo.info, Node: Footnote Commands, Next: Footnote Styles, Up: Footnotes
+
+Footnote Commands
+-----------------
+
+ In Texinfo, footnotes are created with the `@footnote' command. This
+command is followed immediately by a left brace, then by the text of
+the footnote, and then by a terminating right brace. Footnotes may be
+of any length (they will be broken across pages if necessary), but are
+usually short. The template is:
+
+ ordinary text@footnote{TEXT OF FOOTNOTE}
+
+ As shown here, the `@footnote' command should come right after the
+text being footnoted, with no intervening space; otherwise, the footnote
+marker might end up starting a line.
+
+ For example, this clause is followed by a sample footnote(1) (*note
+Footnote Commands-Footnote-1::); in the Texinfo source, it looks like
+this:
+
+ ...a sample footnote@footnote{Here is the sample
+ footnote.}; in the Texinfo source...
+
+ In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+ In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: `(1)'. The reference
+mark is followed by a cross-reference link to the footnote's text.
+
+ In the HTML output, footnote references are marked with a small,
+superscripted number which is rendered as a hypertext link to the
+footnote text.
+
+ By the way, footnotes in the argument of an `@item' command for a
+`@table' must be on the same line as the `@item' (as usual). *Note
+Two-column Tables::.
+
+\1f
+File: texinfo.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands
+
+ (1) Here is the sample footnote.
+
+\1f
+File: texinfo.info, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes
+
+Footnote Styles
+---------------
+
+ Info has two footnote styles, which determine where the text of the
+footnote is located:
+
+ * In the `End' node style, all the footnotes for a single node are
+ placed at the end of that node. The footnotes are separated from
+ the rest of the node by a line of dashes with the word `Footnotes'
+ within it. Each footnote begins with an `(N)' reference mark.
+
+ Here is an example of a single footnote in the end of node style:
+
+ --------- Footnotes ---------
+
+ (1) Here is a sample footnote.
+
+ * In the `Separate' node style, all the footnotes for a single node
+ are placed in an automatically constructed node of their own. In
+ this style, a "footnote reference" follows each `(N)' reference
+ mark in the body of the node. The footnote reference is actually
+ a cross reference which you use to reach the footnote node.
+
+ The name of the node with the footnotes is constructed by
+ appending `-Footnotes' to the name of the node that contains the
+ footnotes. (Consequently, the footnotes' node for the `Footnotes'
+ node is `Footnotes-Footnotes'!) The footnotes' node has an `Up'
+ node pointer that leads back to its parent node.
+
+ Here is how the first footnote in this manual looks after being
+ formatted for Info in the separate node style:
+
+ File: texinfo.info Node: Overview-Footnotes, Up: Overview
+
+ (1) The first syllable of "Texinfo" is pronounced like "speck", not
+ "hex". ...
+
+ A Texinfo file may be formatted into an Info file with either footnote
+style.
+
+ Use the `@footnotestyle' command to specify an Info file's footnote
+style. Write this command at the beginning of a line followed by an
+argument, either `end' for the end node style or `separate' for the
+separate node style.
+
+ For example,
+
+ @footnotestyle end
+
+or
+ @footnotestyle separate
+
+ Write an `@footnotestyle' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you include
+the `@footnotestyle' command between the start-of-header and
+end-of-header lines, the region formatting commands will format
+footnotes as specified.)
+
+ If you do not specify a footnote style, the formatting commands use
+their default style. Currently, `texinfo-format-buffer' and
+`texinfo-format-region' use the `separate' style and `makeinfo' uses
+the `end' style.
+
+ This chapter contains two footnotes.
+
+\1f
+File: texinfo.info, Node: Images, Prev: Footnotes, Up: Insertions
+
+Inserting Images
+================
+
+ You can insert an image given in an external file with the `@image'
+command:
+
+ @image{FILENAME, [WIDTH], [HEIGHT]}
+
+ The FILENAME argument is mandatory, and must not have an extension,
+because the different processors support different formats:
+ * TeX reads the file `FILENAME.eps' (Encapsulated PostScript format).
+
+ * PDFTeX reads `FILENAME.pdf' (Adobe's Portable Document Format).
+
+ * `makeinfo' uses `FILENAME.txt' verbatim for Info output (more or
+ less as if it was an `@example').
+
+ * `makeinfo' producing HTML output tries `FILENAME.png'; if that
+ does not exist, it tries `FILENAME.jpg'. If that does not exist
+ either, it complains. (We cannot support GIF format due to
+ patents.)
+
+ The optional WIDTH and HEIGHT arguments specify the size to scale the
+image to (they are ignored for Info output). If neither is specified,
+the image is presented in its natural size (given in the file); if only
+one is specified, the other is scaled proportionately; and if both are
+specified, both are respected, thus possibly distorting the original
+image by changing its aspect ratio.
+
+ The WIDTH and HEIGHT may be specified using any valid TeX dimension,
+namely:
+
+pt
+ point (72.27pt = 1in)
+
+pc
+ pica (1pc = 12pt)
+
+bp
+ big point (72bp = 1in)
+
+in
+ inch
+
+cm
+ centimeter (2.54cm = 1in)
+
+mm
+ millimeter (10mm = 1cm)
+
+dd
+ dido^t point (1157dd = 1238pt)
+
+cc
+ cicero (1cc = 12dd)
+
+sp
+ scaled point (65536sp = 1pt)
+
+ For example, the following will scale a file `ridt.eps' to one inch
+vertically, with the width scaled proportionately:
+
+ @image{ridt,,1in}
+
+ For `@image' to work with TeX, the file `epsf.tex' must be installed
+somewhere that TeX can find it. (The standard location is
+`TEXMF/tex/generic/dvips/epsf.tex', where TEXMF is a root of your TeX
+directory tree.) This file is included in the Texinfo distribution and
+is available from `ftp://tug.org/tex/epsf.tex'.
+
+ `@image' can be used within a line as well as for displayed figures.
+Therefore, if you intend it to be displayed, be sure to leave a blank
+line before the command, or the output will run into the preceding text.
+
+\1f
+File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
+
+Making and Preventing Breaks
+****************************
+
+ Usually, a Texinfo file is processed both by TeX and by one of the
+Info formatting commands. Line, paragraph, or page breaks sometimes
+occur in the `wrong' place in one or other form of output. You must
+ensure that text looks right both in the printed manual and in the Info
+file.
+
+ For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages. Conversely, you may want to force a page break where none
+would occur normally. Fortunately, problems like these do not often
+arise. When they do, use the break, break prevention, or pagination
+commands.
+
+* Menu:
+
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell TeX about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+
+\1f
+File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks
+
+Break Commands
+==============
+
+ The break commands create or allow line and paragraph breaks:
+
+`@*'
+ Force a line break.
+
+`@sp N'
+ Skip N blank lines.
+
+`@-'
+ Insert a discretionary hyphen.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Define hyphen points in HY-PHEN-A-TED WORDS.
+
+ The line-break-prevention command holds text together all on one line:
+
+`@w{TEXT}'
+ Prevent TEXT from being split and hyphenated across two lines.
+
+ The pagination commands apply only to printed output, since Info
+files do not have pages.
+
+`@page'
+ Start a new page in the printed manual.
+
+`@group'
+ Hold text together that must appear on one printed page.
+
+`@need MILS'
+ Start a new printed page if not enough space on this one.
+
+\1f
+File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
+
+`@*': Generate Line Breaks
+==========================
+
+ The `@*' command forces a line break in both the printed manual and
+in Info.
+
+ For example,
+
+ This line @* is broken @*in two places.
+
+produces
+
+ This line
+ is broken
+ in two places.
+
+(Note that the space after the first `@*' command is faithfully carried
+down to the next line.)
+
+ The `@*' command is often used in a file's copyright page:
+
+ This is edition 2.0 of the Texinfo documentation,@*
+ and is for ...
+
+In this case, the `@*' command keeps TeX from stretching the line
+across the whole page in an ugly manner.
+
+ *Please note:* Do not write braces after an `@*' command; they are
+ not needed.
+
+ Do not write an `@refill' command at the end of a paragraph
+ containing an `@*' command; it will cause the paragraph to be
+ refilled after the line break occurs, negating the effect of the
+ line break.
+
+\1f
+File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
+
+`@-' and `@hyphenation': Helping TeX hyphenate
+==============================================
+
+ Although TeX's hyphenation algorithm is generally pretty good, it
+does miss useful hyphenation points from time to time. (Or, far more
+rarely, insert an incorrect hyphenation.) So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help TeX out. Texinfo supports two commands for this:
+
+`@-'
+ Insert a discretionary hyphen, i.e., a place where TeX can (but
+ does not have to) hyphenate. This is especially useful when you
+ notice an overfull hbox is due to TeX missing a hyphenation (*note
+ Overfull hboxes::). TeX will not insert any hyphenation points in
+ a word containing `@-'.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
+ a `-' at each hyphenation point. For example:
+ @hyphenation{man-u-script man-u-scripts}
+ TeX only uses the specified hyphenation points when the words
+ match exactly, so give all necessary variants.
+
+ Info output is not hyphenated, so these commands have no effect there.
+
+\1f
+File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks
+
+`@w'{TEXT}: Prevent Line Breaks
+===============================
+
+ `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
+
+ You can use the `@w' command to prevent TeX from automatically
+hyphenating a long name or phrase that happens to fall near the end of a
+line. For example:
+
+ You can copy GNU software from @w{@samp{ftp.gnu.org}}.
+
+produces
+
+ You can copy GNU software from `ftp.gnu.org'.
+
+ You can also use `@w' to produce a non-breakable space:
+
+ None of the formatters will break at this@w{ }space.
+
+\1f
+File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks
+
+`@sp' N: Insert Blank Lines
+===========================
+
+ A line beginning with and containing only `@sp N' generates N blank
+lines of space in both the printed manual and the Info file. `@sp'
+also forces a paragraph break. For example,
+
+ @sp 2
+
+generates two blank lines.
+
+ The `@sp' command is most often used in the title page.
+
+\1f
+File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks
+
+`@page': Start a New Page
+=========================
+
+ A line containing only `@page' starts a new page in a printed manual.
+The command has no effect on Info files since they are not paginated.
+An `@page' command is often used in the `@titlepage' section of a
+Texinfo file to start the copyright page.
+
+\1f
File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks
`@group': Prevent Page Breaks
the bottoms of printed pages).
\1f
-File: texinfo.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top
+File: texinfo.info, Node: Definition Commands, Next: Conditionals, Prev: Breaks, Up: Top
Definition Commands
*******************
produces
- - Command: forward-word COUNT
+ - Command: forward-word count
This function moves point forward COUNT words (or backward if
COUNT is negative). ...
produces
- - Function: buffer-end FLAG
+ - Function: buffer-end flag
This function returns `(point-min)' if FLAG is less than 1,
`(point-max)' otherwise. ...
- Interactive Command: isearch-backward
These two search commands are similar except ...
- Each of the other definition commands has an `x' form: `@defunx',
-`@defvrx', `@deftypefunx', etc.
+ Each definition command has an `x' form: `@defunx', `@defvrx',
+`@deftypefunx', etc.
The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
`@defspec NAME ARGUMENTS...'
The `@defspec' command is the definition command for special
forms. (In Lisp, a special form is an entity much like a function,
- *note Special Forms: (lispref)Special Forms..) `@defspec' is
+ *note Special Forms: (elisp)Special Forms..) `@defspec' is
equivalent to `@deffn {Special Form} ...' and works like `@defun'.
\1f
like a variable--an entity that records a value. You must choose
a term to describe the category of entity being defined; for
example, "Variable" could be used if the entity is a variable.
- Write the `@defvr' command at the beginning of a line and followed
+ Write the `@defvr' command at the beginning of a line and follow
it on the same line by the category of the entity and the name of
the entity.
`@defopt NAME'
The `@defopt' command is the definition command for "user
options", i.e., variables intended for users to change according to
- taste; Emacs has many such (*note Variables: (xemacs)Variables.).
+ taste; Emacs has many such (*note Variables: (emacs)Variables.).
`@defopt' is equivalent to `@defvr {User Option} ...' and works
like `@defvar'.
illustrates how you would write the first line of a definition of
the `border-pattern' class option of the class `Window'.
- The template is
-
+ The template is:
@defcv CATEGORY CLASS NAME
...
@end defcv
equivalent to `@defcv {Instance Variable} ...'
The template is:
-
@defivar CLASS INSTANCE-VARIABLE-NAME
BODY-OF-DEFINITION
@end defivar
`@defivar' creates an entry in the index of variables.
+`@deftypeivar CLASS DATA-TYPE NAME'
+ The `@deftypeivar' command is the definition command for typed
+ instance variables in object-oriented programming. It is similar
+ to `@defivar' with the addition of the DATA-TYPE parameter to
+ specify the type of the instance variable. `@deftypeivar' creates
+ an entry in the index of variables.
+
`@defop CATEGORY CLASS NAME ARGUMENTS...'
The `@defop' command is the general definition command for
entities that may resemble methods in object-oriented programming.
operation, and its arguments, if any.
The template is:
-
@defop CATEGORY CLASS NAME ARGUMENTS...
BODY-OF-DEFINITION
@end defop
`@defop' creates an entry, such as ``expose' on `windows'', in the
index of functions.
+`@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
+ The `@deftypeop' command is the definition command for typed
+ operations in object-oriented programming. It is similar to
+ `@defop' with the addition of the DATA-TYPE parameter to specify
+ the return type of the method. `@deftypeop' creates an entry in
+ the index of functions.
+
`@defmethod CLASS NAME ARGUMENTS...'
The `@defmethod' command is the definition command for methods in
object-oriented programming. A method is a kind of function that
implements an operation for a particular class of objects and its
- subclasses. In the Lisp Machine, methods actually were functions,
- but they were usually defined with `defmethod'.
+ subclasses.
`@defmethod' is equivalent to `@defop Method ...'. The command is
written at the beginning of a line and is followed by the name of
the class of the method, the name of the method, and its
arguments, if any.
- For example,
-
+ For example:
@defmethod `bar-class' bar-method argument
...
@end defmethod
The name of the function follows immediately after the `@defun' command
and it is followed, on the same line, by the parameter list.
- Here is a definition from *Note Calling Functions: (lispref)Calling
+ Here is a definition from *Note Calling Functions: (elisp)Calling
Functions.
- - Function: apply FUNCTION &rest ARGUMENTS
+ - Function: apply function &rest arguments
`apply' calls FUNCTION with ARGUMENTS, just like `funcall'
but with one difference: the last of ARGUMENTS is a list of
arguments to give to FUNCTION, rather than a single argument.
In the Texinfo source file, this example looks like this:
@defun apply function &rest arguments
-
@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
@end example
An interesting example of using @code{apply} is found
- in the description of @code{mapcar}.@refill
+ in the description of @code{mapcar}.
@end defun
In this manual, this function is listed in the Command and Variable
that for functions except that variables do not take arguments.
\1f
-File: texinfo.info, Node: Footnotes, Next: Conditionals, Prev: Definition Commands, Up: Top
-
-Footnotes
-*********
-
- A "footnote" is for a reference that documents or elucidates the
-primary text.(1) (*note Footnotes-Footnotes::)
-
-* Menu:
-
-* Footnote Commands:: How to write a footnote in Texinfo.
-* Footnote Styles:: Controlling how footnotes appear in Info.
-
-\1f
-File: texinfo.info, Node: Footnotes-Footnotes, Up: Footnotes
-
- (1) A footnote should complement or expand upon the primary text, but
-a reader should not need to read a footnote to understand the primary
-text. For a thorough discussion of footnotes, see `The Chicago Manual
-of Style', which is published by the University of Chicago Press.
-
-\1f
-File: texinfo.info, Node: Footnote Commands, Next: Footnote Styles, Prev: Footnotes, Up: Footnotes
-
-Footnote Commands
-=================
-
- In Texinfo, footnotes are created with the `@footnote' command. This
-command is followed immediately by a left brace, then by the text of
-the footnote, and then by a terminating right brace. Footnotes may be
-of any length (they will be broken across pages if necessary), but are
-usually short. The template is:
-
- ordinary text@footnote{TEXT OF FOOTNOTE}
-
- As shown here, the `@footnote' command should come right after the
-text being footnoted, with no intervening space; otherwise, the
-formatters the footnote mark might end up starting up a line.
-
- For example, this clause is followed by a sample footnote(1) (*note
-Footnote Commands-Footnotes::); in the Texinfo source, it looks like
-this:
-
- ...a sample footnote@footnote{Here is the sample
- footnote.}; in the Texinfo source...
-
- *Warning:* Don't use footnotes in the argument of the `@item' command
-for a `@table' table. This doesn't work, and because of limitations of
-TeX, there is no way to fix it. You must put the footnote into the
-body text of the table.
-
- In a printed manual or book, the reference mark for a footnote is a
-small, superscripted number; the text of the footnote appears at the
-bottom of the page, below a horizontal line.
-
- In Info, the reference mark for a footnote is a pair of parentheses
-with the footnote number between them, like this: `(1)'.
-
-\1f
-File: texinfo.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands
-
- (1) Here is the sample footnote.
-
-\1f
-File: texinfo.info, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes
-
-Footnote Styles
-===============
-
- Info has two footnote styles, which determine where the text of the
-footnote is located:
+File: texinfo.info, Node: Conditionals, Next: Internationalization, Prev: Definition Commands, Up: Top
- * In the `End' node style, all the footnotes for a single node are
- placed at the end of that node. The footnotes are separated from
- the rest of the node by a line of dashes with the word `Footnotes'
- within it. Each footnote begins with an `(N)' reference mark.
-
- Here is an example of a single footnote in the end of node style:
-
- --------- Footnotes ---------
-
- (1) Here is a sample footnote.
-
- * In the `Separate' node style, all the footnotes for a single node
- are placed in an automatically constructed node of their own. In
- this style, a "footnote reference" follows each `(N)' reference
- mark in the body of the node. The footnote reference is actually
- a cross reference which you use to reach the footnote node.
-
- The name of the node containing the footnotes is constructed by
- appending `-Footnotes' to the name of the node that contains the
- footnotes. (Consequently, the footnotes' node for the `Footnotes'
- node is `Footnotes-Footnotes'!) The footnotes' node has an `Up'
- node pointer that leads back to its parent node.
-
- Here is how the first footnote in this manual looks after being
- formatted for Info in the separate node style:
-
- File: texinfo.info Node: Overview-Footnotes, Up: Overview
-
- (1) Note that the first syllable of "Texinfo" is
- pronounced like "speck", not "hex". ...
-
- A Texinfo file may be formatted into an Info file with either footnote
-style.
-
- Use the `@footnotestyle' command to specify an Info file's footnote
-style. Write this command at the beginning of a line followed by an
-argument, either `end' for the end node style or `separate' for the
-separate node style.
-
- For example,
-
- @footnotestyle end
+Conditionally Visible Text
+**************************
-or
- @footnotestyle separate
+ Sometimes it is good to use different text for different output
+formats. For example, you can use the "conditional commands" to specify
+different text for the printed manual and the Info output.
- Write an `@footnotestyle' command before or shortly after the
-end-of-header line at the beginning of a Texinfo file. (If you include
-the `@footnotestyle' command between the start-of-header and
-end-of-header lines, the region formatting commands will format
-footnotes as specified.)
+ Conditional commands may not be nested.
- If you do not specify a footnote style, the formatting commands use
-their default style. Currently, `texinfo-format-buffer' and
-`texinfo-format-region' use the `separate' style and `makeinfo' uses
-the `end' style.
+ The conditional commands comprise the following categories.
- This chapter contains two footnotes.
+ * Commands for HTML, Info, or TeX.
-\1f
-File: texinfo.info, Node: Conditionals, Next: Macros, Prev: Footnotes, Up: Top
+ * Commands for not HTML, Info, or TeX.
-Conditionally Visible Text
-**************************
+ * Raw TeX or HTML commands.
- Sometimes it is good to use different text for a printed manual and
-its corresponding Info file. In this case, you can use the
-"conditional commands" to specify which text is for the printed manual
-and which is for the Info file.
+ * Substituting text for all formats, and testing if a flag is set or
+ clear.
* Menu:
flag to a string that you can insert.
\1f
-File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Prev: Conditionals, Up: Conditionals
+File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals
Conditional Commands
====================
`@ifinfo' begins segments of text that should be ignored by TeX when
it typesets the printed manual. The segment of text appears only in
the Info file. The `@ifinfo' command should appear on a line by
-itself; end the Info-only text with a line containing `@end ifinfo' by
+itself; end the Info-only text with a line containing `@end ifinfo' by
itself. At the beginning of a Texinfo file, the Info permissions are
contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
Info Summary and Permissions::.)
@ifinfo
However, this text will appear only in Info.
@end ifinfo
+ @ifhtml
+ And this text will only appear in HTML.
+ @end ifhtml
The preceding example produces the following line: However, this text
will appear only in Info.
-Note how you only see one of the two lines, depending on whether you
-are reading the Info version or the printed version of this manual.
-
- The `@titlepage' command is a special variant of `@iftex' that is
-used for making the title and copyright pages of the printed manual.
-(*Note `@titlepage': titlepage.)
+Notice that you only see one of the input lines, depending on which
+version of the manual you are reading.
\1f
File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals
Conditional Not Commands
========================
- You can specify text to be included in any output format *other* than
+ You can specify text to be included in any output format _other_ than
some given one with the `@ifnot...' commands:
@ifnothtml ... @end ifnothtml
@ifnotinfo ... @end ifnotinfo
is included. Otherwise, it is ignored.
The regions delimited by these commands are ordinary Texinfo source as
-with `@iftex', not raw formatter source as with `@tex'.
-
-\1f
-File: texinfo.info, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals
-
-Raw Formatter Commands
-======================
-
- Inside a region delineated by `@iftex' and `@end iftex', you can
-embed some raw TeX commands. Info will ignore these commands since
-they are only in that part of the file which is seen by TeX. You can
-write the TeX commands as you would write them in a normal TeX file,
-except that you must replace the `\' used by TeX with an `@'. For
-example, in the `@titlepage' section of a Texinfo file, you can use the
-TeX command `@vskip' to format the copyright page. (The `@titlepage'
-command causes Info to ignore the region automatically, as it does with
-the `@iftex' command.)
-
- However, many features of plain TeX will not work, as they are
-overridden by Texinfo features.
-
- You can enter plain TeX completely, and use `\' in the TeX commands,
-by delineating a region with the `@tex' and `@end tex' commands. (The
-`@tex' command also causes Info to ignore the region, like the `@iftex'
-command.) The sole exception is that `@' chracter still introduces a
-command, so that `@end tex' can be recognized properly.
-
- For example, here is a mathematical expression written in plain TeX:
-
- @tex
- $$ \chi^2 = \sum_{i=1}^N
- \left (y_i - (a + b x_i)
- \over \sigma_i\right)^2 $$
- @end tex
-
-The output of this example will appear only in a printed manual. If
-you are reading this in Info, you will not see the equation that appears
-in the printed manual.
-
- Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
-region to be included in HTML output only, and `@html ... @end ifhtml'
-for a region of raw HTML (again, except that `@' is still the escape
-character, so the `@end' command can be recognized.)
-
-\1f
-File: texinfo.info, Node: set clear value, Prev: Raw Formatter Commands, Up: Conditionals
-
-`@set', `@clear', and `@value'
-==============================
-
- You can direct the Texinfo formatting commands to format or ignore
-parts of a Texinfo file with the `@set', `@clear', `@ifset', and
-`@ifclear' commands.
-
- In addition, you can use the `@set FLAG' command to set the value of
-FLAG to a string of characters; and use `@value{FLAG}' to insert that
-string. You can use `@set', for example, to set a date and use
-`@value' to insert the date in several places in the Texinfo file.
-
-* Menu:
-
-* ifset ifclear:: Format a region if a flag is set.
-* value:: Replace a flag with a string.
-* value Example:: An easy way to update edition information.
-
-\1f
-File: texinfo.info, Node: ifset ifclear, Next: value, Prev: set clear value, Up: set clear value
-
-`@ifset' and `@ifclear'
------------------------
-
- When a FLAG is set, the Texinfo formatting commands format text
-between subsequent pairs of `@ifset FLAG' and `@end ifset' commands.
-When the FLAG is cleared, the Texinfo formatting commands do *not*
-format the text.
-
- Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
-can be any single word. The format for the command looks like this:
-
- @set FLAG
-
- Write the conditionally formatted text between `@ifset FLAG' and
-`@end ifset' commands, like this:
-
- @ifset FLAG
- CONDITIONAL-TEXT
- @end ifset
-
- For example, you can create one document that has two variants, such
-as a manual for a `large' and `small' model:
-
- You can use this machine to dig up shrubs
- without hurting them.
-
- @set large
-
- @ifset large
- It can also dig up fully grown trees.
- @end ifset
-
- Remember to replant promptly ...
-
-In the example, the formatting commands will format the text between
-`@ifset large' and `@end ifset' because the `large' flag is set.
-
- Use the `@clear FLAG' command to turn off, or "clear", a flag.
-Clearing a flag is the opposite of setting a flag. The command looks
-like this:
-
- @clear FLAG
-
-Write the command on a line of its own.
-
- When FLAG is cleared, the Texinfo formatting commands do *not* format
-the text between `@ifset FLAG' and `@end ifset'; that text is ignored
-and does not appear in either printed or Info output.
-
- For example, if you clear the flag of the preceding example by writing
-an `@clear large' command after the `@set large' command (but before
-the conditional text), then the Texinfo formatting commands ignore the
-text between the `@ifset large' and `@end ifset' commands. In the
-formatted output, that text does not appear; in both printed and Info
-output, you see only the lines that say, "You can use this machine to
-dig up shrubs without hurting them. Remember to replant promptly ...".
-
- If a flag is cleared with an `@clear FLAG' command, then the
-formatting commands format text between subsequent pairs of `@ifclear'
-and `@end ifclear' commands. But if the flag is set with `@set FLAG',
-then the formatting commands do *not* format text between an `@ifclear'
-and an `@end ifclear' command; rather, they ignore that text. An
-`@ifclear' command looks like this:
-
- @ifclear FLAG
-
- In brief, the commands are:
-
-`@set FLAG'
- Tell the Texinfo formatting commands that FLAG is set.
-
-`@clear FLAG'
- Tell the Texinfo formatting commands that FLAG is cleared.
-
-`@ifset FLAG'
- If FLAG is set, tell the Texinfo formatting commands to format the
- text up to the following `@end ifset' command.
-
- If FLAG is cleared, tell the Texinfo formatting commands to ignore
- text up to the following `@end ifset' command.
-
-`@ifclear FLAG'
- If FLAG is set, tell the Texinfo formatting commands to ignore the
- text up to the following `@end ifclear' command.
-
- If FLAG is cleared, tell the Texinfo formatting commands to format
- the text up to the following `@end ifclear' command.
-
-\1f
-File: texinfo.info, Node: value, Next: value Example, Prev: ifset ifclear, Up: set clear value
-
-`@value'
---------
-
- You can use the `@set' command to specify a value for a flag, which
-is expanded by the `@value' command. The value is a string a
-characters.
-
- Write the `@set' command like this:
-
- @set foo This is a string.
-
-This sets the value of `foo' to "This is a string."
-
- The Texinfo formatters replace an `@value{FLAG}' command with the
-string to which FLAG is set.
-
- Thus, when `foo' is set as shown above, the Texinfo formatters convert
-
- @value{foo}
-to
- This is a string.
-
- You can write an `@value' command within a paragraph; but you must
-write an `@set' command on a line of its own.
-
- If you write the `@set' command like this:
-
- @set foo
-
-without specifying a string, the value of `foo' is an empty string.
-
- If you clear a previously set flag with an `@clear FLAG' command, a
-subsequent `@value{flag}' command is invalid and the string is replaced
-with an error message that says `{No value for "FLAG"}'.
-
- For example, if you set `foo' as follows:
-
- @set how-much very, very, very
-
-then the formatters transform
-
- It is a @value{how-much} wet day.
-into
- It is a very, very, very wet day.
-
- If you write
-
- @clear how-much
-
-then the formatters transform
-
- It is a @value{how-much} wet day.
-into
- It is a {No value for "how-much"} wet day.
-
-\1f
-File: texinfo.info, Node: value Example, Prev: value, Up: set clear value
-
-`@value' Example
-----------------
-
- You can use the `@value' command to limit the number of places you
-need to change when you record an update to a manual. Here is how it
-is done in `The GNU Make Manual':
-
-Set the flags:
-
- @set EDITION 0.35 Beta
- @set VERSION 3.63 Beta
- @set UPDATED 14 August 1992
- @set UPDATE-MONTH August 1992
-
-Write text for the first `@ifinfo' section, for people reading the
-Texinfo file:
-
- This is Edition @value{EDITION},
- last updated @value{UPDATED},
- of @cite{The GNU Make Manual},
- for @code{make}, Version @value{VERSION}.
-
-Write text for the title page, for people reading the printed manual:
-
- @title GNU Make
- @subtitle A Program for Directing Recompilation
- @subtitle Edition @value{EDITION}, ...
- @subtitle @value{UPDATE-MONTH}
-
-(On a printed cover, a date listing the month and the year looks less
-fussy than a date listing the day as well as the month and year.)
-
-Write text for the Top node, for people reading the Info file:
-
- This is Edition @value{EDITION}
- of the @cite{GNU Make Manual},
- last updated @value{UPDATED}
- for @code{make} Version @value{VERSION}.
-
- After you format the manual, the text in the first `@ifinfo' section
-looks like this:
-
- This is Edition 0.35 Beta, last updated 14 August 1992,
- of `The GNU Make Manual', for `make', Version 3.63 Beta.
-
- When you update the manual, change only the values of the flags; you
-do not need to rewrite the three sections.
-
-\1f
-File: texinfo.info, Node: Macros, Next: Format/Print Hardcopy, Prev: Conditionals, Up: Top
-
-Macros: Defining New Texinfo Commands
-*************************************
-
- A Texinfo "macro" allows you to define a new Texinfo command as any
-sequence of text and/or existing commands (including other macros). The
-macro can have any number of "parameters"--text you supply each time
-you use the macro. (This has nothing to do with the `@defmac' command,
-which is for documenting macros in the subject of the manual; *note Def
-Cmd Template::..)
-
-* Menu:
-
-* Defining Macros:: Both defining and undefining new commands.
-* Invoking Macros:: Using a macro, once you've defined it.
-
-\1f
-File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Prev: Macros, Up: Macros
-
-Defining Macros
-===============
-
- You use the Texinfo `@macro' command to define a macro. For example:
-
- @macro MACRO-NAME{PARAM1, PARAM2, ...}
- TEXT ... \PARAM1\ ...
- @end macro
-
- The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
-when the macro is subsequently used in the document (see the next
-section).
-
- If a macro needs no parameters, you can define it either with an empty
-list (`@macro foo {}') or with no braces at all (`@macro foo').
-
- The definition or "body" of the macro can contain any Texinfo
-commands, including previously-defined macros. (It is not possible to
-have mutually recursive Texinfo macros.) In the body, instances of a
-parameter name surrounded by backslashes, as in `\PARAM1\' in the
-example above, are replaced by the corresponding argument from the
-macro invocation.
-
- You can undefine a macro FOO with `@unmacro FOO'. It is not an error
-to undefine a macro that is already undefined. For example:
-
- @unmacro foo
+with `@iftex', not raw formatter source as with `@tex' (*note Raw
+Formatter Commands::).
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
-File: texinfo.info, Node: Invoking Macros, Prev: Defining Macros, Up: Macros
+File: texinfo.info, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals
+
+Raw Formatter Commands
+======================
+
+ Inside a region delineated by `@iftex' and `@end iftex', you can
+embed some raw TeX commands. Info will ignore these commands since
+they are only in that part of the file which is seen by TeX. You can
+write the TeX commands as you would write them in a normal TeX file,
+except that you must replace the `\' used by TeX with an `@'. For
+example, in the `@titlepage' section of a Texinfo file, you can use the
+TeX command `@vskip' to format the copyright page. (The `@titlepage'
+command causes Info to ignore the region automatically, as it does with
+the `@iftex' command.)
+
+ However, many features of plain TeX will not work, as they are
+overridden by Texinfo features.
+
+ You can enter plain TeX completely, and use `\' in the TeX commands,
+by delineating a region with the `@tex' and `@end tex' commands. (The
+`@tex' command also causes Info to ignore the region, like the `@iftex'
+command.) The sole exception is that the `@' character still
+introduces a command, so that `@end tex' can be recognized properly.
+
+ For example, here is a mathematical expression written in plain TeX:
+
+ @tex
+ $$ \chi^2 = \sum_{i=1}^N
+ \left (y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
+ @end tex
+
+The output of this example will appear only in a printed manual. If
+you are reading this in Info, you will not see the equation that appears
+in the printed manual.
+
+ Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
+region to be included in HTML output only, and `@html ... @end html'
+for a region of raw HTML (again, except that `@' is still the escape
+character, so the `@end' command can be recognized.)
+
+\1f
+File: texinfo.info, Node: set clear value, Prev: Raw Formatter Commands, Up: Conditionals
+
+`@set', `@clear', and `@value'
+==============================
+
+ You can direct the Texinfo formatting commands to format or ignore
+parts of a Texinfo file with the `@set', `@clear', `@ifset', and
+`@ifclear' commands.
+
+ In addition, you can use the `@set FLAG' command to set the value of
+FLAG to a string of characters; and use `@value{FLAG}' to insert that
+string. You can use `@set', for example, to set a date and use
+`@value' to insert the date in several places in the Texinfo file.
+
+* Menu:
+
+* ifset ifclear:: Format a region if a flag is set.
+* set value:: Expand a flag variable to a string.
+* value Example:: An easy way to update edition information.
+
+\1f
+File: texinfo.info, Node: ifset ifclear, Next: set value, Up: set clear value
+
+`@ifset' and `@ifclear'
+-----------------------
+
+ When a FLAG is set, the Texinfo formatting commands format text
+between subsequent pairs of `@ifset FLAG' and `@end ifset' commands.
+When the FLAG is cleared, the Texinfo formatting commands do _not_
+format the text.
+
+ Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
+name can be any single word, containing letters, numerals, hyphens, or
+underscores.
+
+ The format for the command looks like this:
+
+ @set FLAG
+
+ Write the conditionally formatted text between `@ifset FLAG' and
+`@end ifset' commands, like this:
+
+ @ifset FLAG
+ CONDITIONAL-TEXT
+ @end ifset
+
+ For example, you can create one document that has two variants, such
+as a manual for a `large' and `small' model:
+
+ You can use this machine to dig up shrubs
+ without hurting them.
+
+ @set large
+
+ @ifset large
+ It can also dig up fully grown trees.
+ @end ifset
+
+ Remember to replant promptly ...
+
+In the example, the formatting commands will format the text between
+`@ifset large' and `@end ifset' because the `large' flag is set.
+
+ Use the `@clear FLAG' command to turn off, or "clear", a flag.
+Clearing a flag is the opposite of setting a flag. The command looks
+like this:
+
+ @clear FLAG
+
+Write the command on a line of its own.
+
+ When FLAG is cleared, the Texinfo formatting commands do _not_ format
+the text between `@ifset FLAG' and `@end ifset'; that text is ignored
+and does not appear in either printed or Info output.
+
+ For example, if you clear the flag of the preceding example by writing
+an `@clear large' command after the `@set large' command (but before
+the conditional text), then the Texinfo formatting commands ignore the
+text between the `@ifset large' and `@end ifset' commands. In the
+formatted output, that text does not appear; in both printed and Info
+output, you see only the lines that say, "You can use this machine to
+dig up shrubs without hurting them. Remember to replant promptly ...".
+
+ If a flag is cleared with an `@clear FLAG' command, then the
+formatting commands format text between subsequent pairs of `@ifclear'
+and `@end ifclear' commands. But if the flag is set with `@set FLAG',
+then the formatting commands do _not_ format text between an `@ifclear'
+and an `@end ifclear' command; rather, they ignore that text. An
+`@ifclear' command looks like this:
+
+ @ifclear FLAG
+
+ In brief, the commands are:
+
+`@set FLAG'
+ Tell the Texinfo formatting commands that FLAG is set.
+
+`@clear FLAG'
+ Tell the Texinfo formatting commands that FLAG is cleared.
+
+`@ifset FLAG'
+ If FLAG is set, tell the Texinfo formatting commands to format the
+ text up to the following `@end ifset' command.
+
+ If FLAG is cleared, tell the Texinfo formatting commands to ignore
+ text up to the following `@end ifset' command.
+
+`@ifclear FLAG'
+ If FLAG is set, tell the Texinfo formatting commands to ignore the
+ text up to the following `@end ifclear' command.
+
+ If FLAG is cleared, tell the Texinfo formatting commands to format
+ the text up to the following `@end ifclear' command.
+
+\1f
+File: texinfo.info, Node: set value, Next: value Example, Prev: ifset ifclear, Up: set clear value
+
+`@set' and `@value'
+-------------------
+
+ You can use the `@set' command to specify a value for a flag, which
+is expanded by the `@value' command. A flag is an identifier; for best
+results, use only letters and numerals in a flag name, not `-' or
+`_'--they will work in some contexts, but not all, due to limitations
+in TeX. The value is just a string of characters, the remainder of the
+input line.
+
+ Write the `@set' command like this:
+
+ @set foo This is a string.
+
+This sets the value of the flag `foo' to "This is a string.".
+
+ The Texinfo formatters then replace an `@value{FLAG}' command with
+the string to which FLAG is set. Thus, when `foo' is set as shown
+above, the Texinfo formatters convert
+
+ @value{foo}
+to
+ This is a string.
+
+ You can write an `@value' command within a paragraph; but you must
+write an `@set' command on a line of its own.
+
+ If you write the `@set' command like this:
+
+ @set foo
+
+without specifying a string, the value of `foo' is an empty string.
+
+ If you clear a previously set flag with `@clear FLAG', a subsequent
+`@value{flag}' command is invalid and the string is replaced with an
+error message that says `{No value for "FLAG"}'.
+
+ For example, if you set `foo' as follows:
+
+ @set how-much very, very, very
+
+then the formatters transform
+
+ It is a @value{how-much} wet day.
+into
+ It is a very, very, very wet day.
+
+ If you write
+
+ @clear how-much
+
+then the formatters transform
+
+ It is a @value{how-much} wet day.
+into
+ It is a {No value for "how-much"} wet day.
+
+\1f
+File: texinfo.info, Node: value Example, Prev: set value, Up: set clear value
+
+`@value' Example
+----------------
+
+ You can use the `@value' command to limit the number of places you
+need to change when you record an update to a manual. Here is how it is
+done in `The GNU Make Manual':
+
+ 1. Set the flags:
+
+ @set EDITION 0.35 Beta
+ @set VERSION 3.63 Beta
+ @set UPDATED 14 August 1992
+ @set UPDATE-MONTH August 1992
+
+ 2. Write text for the first `@ifinfo' section, for people reading the
+ Texinfo file:
+
+ This is Edition @value{EDITION},
+ last updated @value{UPDATED},
+ of @cite{The GNU Make Manual},
+ for @code{make}, version @value{VERSION}.
+
+ 3. Write text for the title page, for people reading the printed
+ manual:
+
+ @title GNU Make
+ @subtitle A Program for Directing Recompilation
+ @subtitle Edition @value{EDITION}, ...
+ @subtitle @value{UPDATE-MONTH}
+
+ (On a printed cover, a date listing the month and the year looks
+ less fussy than a date listing the day as well as the month and
+ year.)
+
+ 4. Write text for the Top node, for people reading the Info file:
+
+ This is Edition @value{EDITION}
+ of the @cite{GNU Make Manual},
+ last updated @value{UPDATED}
+ for @code{make} Version @value{VERSION}.
+
+ After you format the manual, the text in the first `@ifinfo'
+ section looks like this:
+
+ This is Edition 0.35 Beta, last updated 14 August 1992,
+ of `The GNU Make Manual', for `make', Version 3.63 Beta.
+
+ When you update the manual, change only the values of the flags; you
+do not need to edit the three sections.
+
+\1f
+File: texinfo.info, Node: Internationalization, Next: Defining New Texinfo Commands, Prev: Conditionals, Up: Top
+
+Internationalization
+********************
+
+ Texinfo has some support for writing in languages other than English,
+although this area still needs considerable work.
+
+ For a list of the various accented and special characters Texinfo
+supports, see *Note Inserting Accents::.
+
+* Menu:
+
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
+
+\1f
+File: texinfo.info, Node: documentlanguage, Next: documentencoding, Up: Internationalization
+
+`@documentlanguage CC': Set the Document Language
+=================================================
+
+ The `@documentlanguage' command declares the current document
+language. Write it on a line by itself, with a two-letter ISO-639
+language code following (list is included below). If you have a
+multilingual document, the intent is to be able to use this command
+multiple times, to declare each language change. If the command is not
+used at all, the default is `en' for English.
+
+ At present, this command is ignored in Info and HTML output. For
+TeX, it causes the file `txi-CC.tex' to be read (if it exists). Such a
+file appropriately redefines the various English words used in TeX
+output, such as `Chapter', `See', and so on.
+
+ It would be good if this command also changed TeX's ideas of the
+current hyphenation patterns (via the TeX primitive `\language'), but
+this is unfortunately not currently implemented.
+
+ Here is the list of valid language codes. This list comes from the
+free translation project
+(http://www.iro.umontreal.ca/contrib/po/iso-639). In the future we may
+wish to allow the 3-letter POV codes described at
+`http://www.sil.org/ethnologue/#contents'. This will be necessary to
+support African languages.
+
+`aa' Afar `ab'Abkhazian `af'Afrikaans
+`am' Amharic `ar'Arabic `as'Assamese
+`ay' Aymara `az'Azerbaijani `ba'Bashkir
+`be' Byelorussian `bg'Bulgarian `bh'Bihari
+`bi' Bislama `bn'Bengali; Bangla `bo'Tibetan
+`br' Breton `ca'Catalan `co'Corsican
+`cs' Czech `cy'Welsh `da'Danish
+`de' German `dz'Bhutani `el'Greek
+`en' English `eo'Esperanto `es'Spanish
+`et' Estonian `eu'Basque `fa'Persian
+`fi' Finnish `fj'Fiji `fo'Faroese
+`fr' French `fy'Frisian `ga'Irish
+`gd' Scots Gaelic `gl'Galician `gn'Guarani
+`gu' Gujarati `ha'Hausa `he'Hebrew
+`hi' Hindi `hr'Croatian `hu'Hungarian
+`hy' Armenian `ia'Interlingua `id'Indonesian
+`ie' Interlingue `ik'Inupiak `is'Icelandic
+`it' Italian `iu'Inuktitut `ja'Japanese
+`jw' Javanese `ka'Georgian `kk'Kazakh
+`kl' Greenlandic `km'Cambodian `kn'Kannada
+`ks' Kashmiri `ko'Korean `ku'Kurdish
+`ky' Kirghiz `la'Latin `ln'Lingala
+`lt' Lithuanian `lo'Laothian `lv'Latvian, Lettish
+`mg' Malagasy `mi'Maori `mk'Macedonian
+`ml' Malayalam `mn'Mongolian `mo'Moldavian
+`mr' Marathi `ms'Malay `mt'Maltese
+`my' Burmese `na'Nauru `ne'Nepali
+`nl' Dutch `no'Norwegian `oc'Occitan
+`om' (Afan) Oromo `or'Oriya `pa'Punjabi
+`pl' Polish `ps'Pashto, Pushto `pt'Portuguese
+`qu' Quechua `rm'Rhaeto-Romance `rn'Kirundi
+`ro' Romanian `ru'Russian `rw'Kinyarwanda
+`sa' Sanskrit `sd'Sindhi `sg'Sangro
+`sh' Serbo-Croatian `si'Sinhalese `sk'Slovak
+`sl' Slovenian `sm'Samoan `sn'Shona
+`so' Somali `sq'Albanian `sr'Serbian
+`ss' Siswati `st'Sesotho `su'Sundanese
+`sv' Swedish `sw'Swahili `ta'Tamil
+`te' Telugu `tg'Tajik `th'Thai
+`ti' Tigrinya `tk'Turkmen `tl'Tagalog
+`tn' Setswana `to'Tonga `tr'Turkish
+`ts' Tsonga `tt'Tatar `tw'Twi
+`ug' Uighur `uk'Ukrainian `ur'Urdu
+`uz' Uzbek `vi'Vietnamese `vo'Volapuk
+`wo' Wolof `xh'Xhosa `yi'Yiddish
+`yo' Yoruba `za'Zhuang `zh'Chinese
+`zu' Zulu
+
+\1f
+File: texinfo.info, Node: documentencoding, Prev: documentlanguage, Up: Internationalization
+
+`@documentencoding ENC': Set Input Encoding
+===========================================
+
+ The `@documentencoding' command declares the input document encoding.
+Write it on a line by itself, with a valid encoding specification
+following, such as `ISO-8859-1'.
+
+ At present, this is used only in HTML output from `makeinfo'. If a
+document encoding ENC is specified, it is used in the `<meta>' tag is
+included in the `<head>' of the output:
+
+ <meta http-equiv="Content-Type" content="text/html; charset=ENC">
+
+\1f
+File: texinfo.info, Node: Defining New Texinfo Commands, Next: Hardcopy, Prev: Internationalization, Up: Top
+
+Defining New Texinfo Commands
+*****************************
+
+ Texinfo provides several ways to define new commands:
+
+ * A Texinfo "macro" allows you to define a new Texinfo command as any
+ sequence of text and/or existing commands (including other
+ macros). The macro can have any number of "parameters"--text you
+ supply each time you use the macro.
+
+ Incidentally, these macros have nothing to do with the `@defmac'
+ command, which is for documenting macros in the subject of the
+ manual (*note Def Cmd Template::).
+
+ * `@alias' is a convenient way to define a new name for an existing
+ command.
+
+ * `@definfoenclose' allows you to define new commands with
+ customized output in the Info file.
+
+
+* Menu:
+
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
+
+\1f
+File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Up: Defining New Texinfo Commands
+
+Defining Macros
+===============
+
+ You use the Texinfo `@macro' command to define a macro, like this:
+
+ @macro MACRONAME{PARAM1, PARAM2, ...}
+ TEXT ... \PARAM1\ ...
+ @end macro
+
+ The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
+when the macro is subsequently used in the document (described in the
+next section).
+
+ For a macro to work with TeX, MACRONAME must consist entirely of
+letters: no digits, hyphens, underscores, or other special characters.
+
+ If a macro needs no parameters, you can define it either with an empty
+list (`@macro foo {}') or with no braces at all (`@macro foo').
+
+ The definition or "body" of the macro can contain most Texinfo
+commands, including previously-defined macros. Not-yet-defined macro
+invocations are not allowed; thus, it is not possible to have mutually
+recursive Texinfo macros. Also, a macro definition that defines another
+macro does not work in TeX due to limitations in the design of `@macro'.
+
+ In the macro body, instances of a parameter name surrounded by
+backslashes, as in `\PARAM1\' in the example above, are replaced by the
+corresponding argument from the macro invocation. You can use
+parameter names any number of times in the body, including zero.
+
+ To get a single `\' in the macro expansion, use `\\'. Any other use
+of `\' in the body yields a warning.
+
+ The newlines after the `@macro' line and before the `@end macro' line
+are ignored, that is, not included in the macro body. All other
+whitespace is treated according to the usual Texinfo rules.
+
+ To allow a macro to be used recursively, that is, in an argument to a
+call to itself, you must define it with `@rmacro', like this:
+
+ @rmacro rmac
+ a\arg\b
+ @end rmacro
+ ...
+ @rmac{1@rmac{text}2}
+
+ This produces the output `a1atextb2b'. With `@macro' instead of
+`@rmacro', an error message is given.
+
+ You can undefine a macro FOO with `@unmacro FOO'. It is not an error
+to undefine a macro that is already undefined. For example:
+
+ @unmacro foo
+
+\1f
+File: texinfo.info, Node: Invoking Macros, Next: Macro Details, Prev: Defining Macros, Up: Defining New Texinfo Commands
Invoking Macros
===============
After a macro is defined (see the previous section), you can use
("invoke") it in your document like this:
- @MACRO-NAME {ARG1, ARG2, ...}
+ @MACRONAME {ARG1, ARG2, ...}
-and the result will be just as if you typed the body of MACRO-NAME at
+and the result will be just as if you typed the body of MACRONAME at
that spot. For example:
@macro foo {p, q}
Thus, the arguments and parameters are separated by commas and
delimited by braces; any whitespace after (but not before) a comma is
-ignored. To insert a comma, brace, or backslash in an argument,
-prepend a backslash, as in
+ignored. The braces are required in the invocation (but not the
+definition), even when the macro takes no arguments, consistent with
+all other Texinfo commands. For example:
+
+ @macro argless {}
+ No arguments here.
+ @end macro
+ @argless{}
+
+produces:
- @MACRO-NAME {\\\{\}\,}
+ No arguments here.
+
+ To insert a comma, brace, or backslash in an argument, prepend a
+backslash, as in
+
+ @MACNAME {\\\{\}\,}
which will pass the (almost certainly error-producing) argument `\{},'
-to MACRO-NAME.
+to MACNAME.
If the macro is defined to take a single argument, and is invoked
without any braces, the entire rest of the line after the macro name is
supplied as the argument. For example:
@macro bar {p}
- Twice: \p\, \p\.
+ Twice: \p\ & \p\.
@end macro
@bar aah
produces:
- Twice: aah, aah.
+ Twice: aah & aah.
+
+ If the macro is defined to take a single argument, and is invoked with
+braces, the braced text is passed as the argument, regardless of
+commas. For example:
+
+ @macro bar {p}
+ Twice: \p\ & \p\.
+ @end macro
+ @bar{a,b}
+
+produces:
+
+ Twice: a,b & a,b.
+
+\1f
+File: texinfo.info, Node: Macro Details, Next: alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands
+
+Macro Details
+=============
+
+ Due to unavoidable disparities in the TeX and `makeinfo'
+implementations, Texinfo macros have the following limitations.
+
+ * All macros are expanded inside at least one TeX group. This means
+ that
+
+ * Macros containing a command which must be on a line by itself,
+ such as a conditional, cannot be invoked in the middle of a line.
+
+ * The TeX implementation cannot construct macros that define macros
+ in the natural way. To do this, you must use conditionals and raw
+ TeX. For example:
+
+ @ifinfo
+ @macro ctor {name, arg}
+ @macro \name\
+ something involving \arg\ somehow
+ @end macro
+ @end macro
+ @end ifinfo
+ @tex
+ \gdef\ctor#1{\ctorx#1,}
+ \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}}
+ @end tex
+
+ * It is best to avoid comments inside macro definitions.
+
+
+\1f
+File: texinfo.info, Node: alias, Next: definfoenclose, Prev: Macro Details, Up: Defining New Texinfo Commands
+
+`@alias NEW=EXISTING'
+=====================
+
+ The `@alias' command defines a new command to be just like an
+existing one. This is useful for defining additional markup names, thus
+preserving semantic information in the input even though the output
+result may be the same.
+
+ Write the `@alias' command on a line by itself, followed by the new
+command name, an equals sign, and the existing command name.
+Whitespace around the equals sign is ignored. Thus:
+ @alias NEW = EXISTING
+
+ For example, if your document contains citations for both books and
+some other media (movies, for example), you might like to define a
+macro `@moviecite{}' that does the same thing as an ordinary `@cite{}'
+but conveys the extra semantic information as well. You'd do this as
+follows:
+
+ @alias moviecite = cite
+
+ Macros do not always have the same effect due to vagaries of argument
+parsing. Also, aliases are much simpler to define than macros. So the
+command is not redundant. (It was also heavily used in the Jargon
+File!)
+
+ Aliases must not be recursive, directly or indirectly.
\1f
-File: texinfo.info, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Macros, Up: Top
+File: texinfo.info, Node: definfoenclose, Prev: alias, Up: Defining New Texinfo Commands
+
+`definfoenclose': Customized Highlighting
+=========================================
+
+ A `@definfoenclose' command may be used to define a highlighting
+command for Info, but not for TeX. A command defined using
+`@definfoenclose' marks text by enclosing it in strings that precede
+and follow the text. You can use this to get closer control of your
+Info output.
+
+ Presumably, if you define a command with `@definfoenclose' for Info,
+you will create a corresponding command for TeX, either in
+`texinfo.tex', `texinfo.cnf', or within an `@iftex' in your document.
+
+ Write a `@definfoenclose' command on a line and follow it with three
+arguments separated by commas. The first argument to `@definfoenclose'
+is the @-command name (without the `@'); the second argument is the
+Info start delimiter string; and the third argument is the Info end
+delimiter string. The latter two arguments enclose the highlighted
+text in the Info file. A delimiter string may contain spaces. Neither
+the start nor end delimiter is required. If you do not want a start
+delimiter but do want an end delimiter, you must follow the command
+name with two commas in a row; otherwise, the Info formatting commands
+will naturally misinterpret the end delimiter string you intended as
+the start delimiter string.
+
+ If you do a `@definfoenclose' on the name of a pre-defined macro
+(such as `@emph', `@strong', `@t', or `@i'), the enclosure definition
+will override the built-in definition.
+
+ An enclosure command defined this way takes one argument in braces;
+this is intended for new markup commands (*note Marking Text::).
+
+ For example, you can write:
+
+ @definfoenclose phoo,//,\\
+
+near the beginning of a Texinfo file to define `@phoo' as an Info
+formatting command that inserts `//' before and `\\' after the argument
+to `@phoo'. You can then write `@phoo{bar}' wherever you want
+`//bar\\' highlighted in Info.
+
+ Also, for TeX formatting, you could write
+
+ @iftex
+ @global@let@phoo=@i
+ @end iftex
+
+to define `@phoo' as a command that causes TeX to typeset the argument
+to `@phoo' in italics.
+
+ Note that each definition applies to its own formatter: one for TeX,
+the other for `texinfo-format-buffer' or `texinfo-format-region'. The
+`@definfoenclose' command need not be within `@ifinfo', but the raw TeX
+commands do need to be in `@iftex'.
+
+ Here is another example: write
+
+ @definfoenclose headword, , :
+
+near the beginning of the file, to define `@headword' as an Info
+formatting command that inserts nothing before and a colon after the
+argument to `@headword'.
-Format and Print Hardcopy
-*************************
+ `@definfoenclose' definitions must not be recursive, directly or
+indirectly.
+
+\1f
+File: texinfo.info, Node: Hardcopy, Next: Creating and Installing Info Files, Prev: Defining New Texinfo Commands, Up: Top
+
+Formatting and Printing Hardcopy
+********************************
There are three major shell commands for making a printed manual from
a Texinfo file: one for converting the Texinfo file into a file that
* Menu:
* Use TeX:: Use TeX to format for hardcopy.
-* Format with tex/texindex:: How to format in a shell.
-* Format with texi2dvi:: A simpler way to use the shell.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
* Print with lpr:: How to print.
* Within Emacs:: How to format and print from an Emacs shell.
* Texinfo Mode Printing:: How to format and print in Texinfo mode.
* Compile-Command:: How to print using Emacs's compile command.
* Requirements Summary:: TeX formatting requirements summary.
-* Preparing for TeX:: What you need to do to use TeX.
+* Preparing for TeX:: What to do before you use TeX.
* Overfull hboxes:: What are and what to do with overfull hboxes.
* smallbook:: How to print small format books and manuals.
* A4 Paper:: How to print on European A4 paper.
+* pagesizes:: How to print with customized page sizes.
* Cropmarks and Magnification:: How to print marks to indicate the size
of pages and how to print scaled up output.
+* PDF Output:: Portable Document Format output.
\1f
-File: texinfo.info, Node: Use TeX, Next: Format with tex/texindex, Prev: Format/Print Hardcopy, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Use TeX, Next: Format with tex/texindex, Up: Hardcopy
Use TeX
=======
The typesetting program called TeX is used for formatting a Texinfo
-file. TeX is a very powerful typesetting program and, if used right,
-does an exceptionally good job. (*Note How to Obtain TeX: Obtaining
-TeX, for information on how to obtain TeX.)
+file. TeX is a very powerful typesetting program and, if used
+correctly, does an exceptionally good job. (*Note How to Obtain TeX:
+Obtaining TeX, for information on how to obtain TeX.)
The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer'
commands read the very same @-commands in the Texinfo file as does TeX,
-but process them differently to make an Info file; see *Note Create an
-Info File::.
+but process them differently to make an Info file (*note Creating an
+Info File::).
\1f
-File: texinfo.info, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Hardcopy
-Format using `tex' and `texindex'
-=================================
+Format with `tex' and `texindex'
+================================
Format the Texinfo file with the shell command `tex' followed by the
name of the Texinfo file. For example:
TeX will produce a "DVI file" as well as several auxiliary files
containing information for indices, cross references, etc. The DVI
file (for "DeVice Independent" file) can be printed on virtually any
-printe (see the following sections).
+device (see the following sections).
The `tex' formatting command itself does not sort the indices; it
writes an output file of unsorted index data. (The `texi2dvi' command
-automatically generates indices; see *Note Format using `texi2dvi':
-Format with texi2dvi.) To generate a printed index after running the
-`tex' command, you first need a sorted index to work from. The
-`texindex' command sorts indices. (The source file `texindex.c' comes
-as part of the standard Texinfo distribution, among other places.)
+automatically generates indices; *note Format with `texi2dvi': Format
+with texi2dvi..) To generate a printed index after running the `tex'
+command, you first need a sorted index to work from. The `texindex'
+command sorts indices. (The source file `texindex.c' comes as part of
+the standard Texinfo distribution, among other places.)
The `tex' formatting command outputs unsorted index files under names
that obey a standard convention: the name of your main input file with
This command will run `texindex' on all the unsorted index files,
including any that you have defined yourself using `@defindex' or
-`@defcodeindex'. (You may execute `texindex foo.??' even if there are
+`@defcodeindex'. (You may execute `texindex foo.??' even if there are
similarly named files with two letter extensions that are not index
files, such as `foo.el'. The `texindex' command reports but otherwise
ignores such files.)
For each file specified, `texindex' generates a sorted index file
whose name is made by appending `s' to the input file name. The
-`@printindex' command knows to look for a file of that name (*note
-Printing Indices & Menus::.). `texindex' does not alter the raw index
-output file.
+`@printindex' command looks for a file with that name (*note Printing
+Indices & Menus::). `texindex' does not alter the raw index output
+file.
After you have sorted the indices, you need to rerun the `tex'
formatting command on the Texinfo file. This regenerates the DVI file,
Finally, you may need to run `tex' one more time, to get the page
numbers in the cross-references correct.
- To summarize, this is a four step process:
+ To summarize, this is a five step process:
1. Run `tex' on your Texinfo file. This generates a DVI file (with
undefined cross-references and no indices), and the raw index files
with page numbers for the cross-references from last time,
generally incorrect.
- 4. Run `tex' one last time. This time the correct page numbers are
+ 4. Sort the indices again, with `texindex'.
+
+ 5. Run `tex' one last time. This time the correct page numbers are
written for the cross-references.
- Alternatively, it's a one-step process: run `texi2dvi'.
+ Alternatively, it's a one-step process: run `texi2dvi' (*note Format
+with texi2dvi::).
You need not run `texindex' each time after you run `tex'. If you do
not, on the next run, the `tex' formatting command will use whatever
sorted index files happen to exist from the previous use of `texindex'.
This is usually ok while you are debugging.
+ Sometimes you may wish to print a document while you know it is
+incomplete, or to print just one chapter of a document. In that case,
+the usual auxiliary files that TeX creates and warnings TeX gives when
+cross-references are not satisfied are just nuisances. You can avoid
+them with the `@novalidate' command, which you must give _before_ the
+`@setfilename' command (*note `@setfilename': setfilename.). Thus, the
+beginning of your file would look approximately like this:
+
+ \input texinfo
+ @novalidate
+ @setfilename myfile.info
+ ...
+
+`@novalidate' also turns off validation in `makeinfo', just like its
+`--no-validate' option (*note Pointer Validation::).
+
\1f
-File: texinfo.info, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Hardcopy
-Format using `texi2dvi'
-=======================
+Format with `texi2dvi'
+======================
The `texi2dvi' command automatically runs both `tex' and `texindex'
-as many times as necessary to produce a DVI file with up-to-date,
-sorted indices. It simplifies the `tex'--`texindex'--`tex' sequence
-described in the previous section.
+as many times as necessary to produce a DVI file with sorted indices
+and all cross-references resolved. It simplifies the
+`tex'--`texindex'--`tex'--`tex' sequence described in the previous
+section.
+
+ To run `texi2dvi' on an input file `foo.texi', do this (where
+`prompt$ ' is your shell prompt):
- The syntax for `texi2dvi' is like this (where `prompt$' is your shell
-prompt):
+ prompt$ texi2dvi foo.texi
- prompt$ texi2dvi FILENAME...
+ As shown in this example, the input filenames to `texi2dvi' must
+include any extension (`.texi', `.texinfo', etc.). Under MS-DOS and
+perhaps in other circumstances, you may need to run `sh texi2dvi
+foo.texi' instead of relying on the operating system to invoke the
+shell on the `texi2dvi' script.
- For a list of options, run `texi2dvi --help'.
+ Perhaps the most useful option to `texi2dvi' is `--texinfo=CMD'.
+This inserts CMD on a line by itself after the `@setfilename' in a
+temporary copy of the input file before running TeX. With this, you
+can specify different printing formats, such as `@smallbook' (*note
+smallbook::), `@afourpaper' (*note A4 Paper::), or `@pageparams' (*note
+pagesizes::), without actually changing the document source. (You can
+also do this on a site-wide basis with `texinfo.cnf'; *note Preparing
+for TeX: Preparing for TeX.).
+
+ For a list of other options, run `texi2dvi --help'.
\1f
-File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Hardcopy
Shell Print Using `lpr -d'
==========================
file name without any extension or with a `.dvi' extension. (If it is
`lpr', you must include the `.dvi'.)
- The following commands, for example, will (probably) suffice to sort
+ For example, the following commands, will (perhaps) suffice to sort
the indices, format, and print the `Bison Manual':
tex bison.texinfo
texi2dvi bison.texinfo
lpr -d bison.dvi
+ `lpr' is a standard program on Unix systems, but it is usually absent
+on MS-DOS/MS-Windows. Some network packages come with a program named
+`lpr', but these are usually limited to sending files to a print server
+over the network, and generally don't support the `-d' option. If you
+are unfortunate enough to work on one of these systems, you have
+several alternative ways of printing DVI files:
+
+ * Find and install a Unix-like `lpr' program, or its clone. If you
+ can do that, you will be able to print DVI files just like
+ described above.
+
+ * Send the DVI files to a network printer queue for DVI files. Some
+ network printers have special queues for printing DVI files. You
+ should be able to set up your network software to send files to
+ that queue. In some cases, the version of `lpr' which comes with
+ your network software will have a special option to send a file to
+ specific queues, like this:
+
+ lpr -Qdvi -hprint.server.domain bison.dvi
+
+ * Convert the DVI file to a Postscript or PCL file and send it to
+ your local printer. *Note dvips invocation: (dvips)dvips
+ invocation, and the man pages for `dvilj', for detailed
+ description of these tools. Once the DVI file is converted to the
+ format your local printer understands directly, just send it to
+ the appropriate port, usually `PRN'.
+
\1f
-File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Hardcopy
From an Emacs Shell
===================
You can give formatting and printing commands from a shell within GNU
Emacs. To create a shell within Emacs, type `M-x shell'. In this
shell, you can format and print the document. *Note Format and Print
-Hardcopy: Format/Print Hardcopy, for details.
+Hardcopy: Hardcopy, for details.
You can switch to and from the shell buffer while `tex' is running
and do other editing. If you are formatting a long document on a slow
and printing in Texinfo mode.
\1f
-File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Hardcopy
Formatting and Printing in Texinfo Mode
=======================================
`C-c C-t C-k'
`M-x tex-kill-job'
- Kill the currently running TeX job started by `texinfo-tex-region'
- or `texinfo-tex-buffer', or any other process running in the
- Texinfo shell buffer.
+ Kill the currently running TeX job started by either
+ `texinfo-tex-region' or `texinfo-tex-buffer', or any other process
+ running in the Texinfo shell buffer.
`C-c C-t C-x'
`M-x texinfo-quit-job'
tex-show-queue-command "lpq"
You can change the values of these variables with the `M-x
-edit-options' command (*note Editing Variable Values: (xemacs)Edit
+edit-options' command (*note Editing Variable Values: (emacs)Edit
Options.), with the `M-x set-variable' command (*note Examining and
-Setting Variables: (xemacs)Examining.), or with your `.emacs'
-initialization file (*note Init File: (xemacs)Init File.).
+Setting Variables: (emacs)Examining.), or with your `.emacs'
+initialization file (*note Init File: (emacs)Init File.).
+
+ Beginning with version 20, GNU Emacs offers a user-friendly interface,
+called "Customize", for changing values of user-definable variables.
+*Note Easy Customization Interface: (emacs)Easy Customization, for more
+details about this. The Texinfo variables can be found in the
+`Development/Docs/Texinfo' group, once you invoke the `M-x customize'
+command.
\1f
-File: texinfo.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Hardcopy
Using the Local Variables List
==============================
End:
This technique is most often used by programmers who also compile
-programs this way; see *Note Compilation: (xemacs)Compilation.
+programs this way; see *Note Compilation: (emacs)Compilation.
\1f
-File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Hardcopy
TeX Formatting Requirements Summary
===================================
`\input' command and must contain an `@setfilename' command:
\input texinfo
- @setfilename ARG-NOT-USED-BY-@TEX{}
+ @setfilename ARG-NOT-USED-BY-TEX
The first command instructs TeX to load the macros it needs to process
a Texinfo file and the second command opens auxiliary files.
`@bye', the end of a file usually includes indices and a table of
contents. (And of course most manuals contain a body of text as well.)
-For more information, see
-*Note `@settitle': settitle,
-*Note `@setchapternewpage': setchapternewpage,
-*Note Page Headings: Headings,
-*Note Titlepage & Copyright Page::,
-*Note Printing Indices & Menus::, and
-*Note Contents::.
+ For more information, see:
+ * *Note `@settitle': settitle
+
+ * *Note `@setchapternewpage': setchapternewpage
+
+ * *Note Page Headings: Headings
+
+ * *Note Titlepage & Copyright Page::
+
+ * *Note Printing Indices & Menus::
+
+ * *Note Contents::
\1f
-File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Hardcopy
-Preparing to Use TeX
-====================
+Preparing for TeX
+=================
-TeX needs to know where to find the `texinfo.tex' file that you have
+ TeX needs to know where to find the `texinfo.tex' file that you have
told it to input with the `\input texinfo' command at the beginning of
the first line. The `texinfo.tex' file tells TeX how to handle
@-commands; it is included in all standard GNU distributions.
Also, you should install `epsf.tex' in the same place as
`texinfo.tex', if it is not already installed from another
distribution. This file is needed to support the `@image' command
-(*note Images::.).
+(*note Images::).
Optionally, you may create an additional `texinfo.cnf', and install
-it as well. This file is read by TeX at the `@setfilename' command
-(*note `@setfilename': setfilename.). You can put any commands you
-like there according to local site-wide conventions, and they will be
-read by TeX when processing any Texinfo document. For example, if
-`texinfo.cnf' contains the a single line `@afourpaper' (*note A4
-Paper::.), then all Texinfo documents will be processed with that page
-size in effect. If you have nothing to put in `texinfo.cnf', you do
-not need to create it.
+it as well. This file is read by TeX when the `@setfilename' command
+is executed (*note `@setfilename': setfilename.). You can put any
+commands you like there, according to local site-wide conventions. They
+will be read by TeX when processing any Texinfo document. For example,
+if `texinfo.cnf' contains the line `@afourpaper' (*note A4 Paper::),
+then all Texinfo documents will be processed with that page size in
+effect. If you have nothing to put in `texinfo.cnf', you do not need
+to create it.
If neither of the above locations for these system files suffice for
you, you can specify the directories explicitly. For `texinfo.tex',
TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
export TEXINPUTS
-This would cause TeX to look for `\input' file first in the current
-directory, indicated by the `.', then in a hypothetical user's
-`me/mylib' directory, and finally in a system directory.
+ On MS-DOS/MS-Windows, you would say it like this(1) (*note Preparing
+for TeX-Footnote-1::):
+
+ set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
+
+It is customary for DOS/Windows users to put such commands in the
+`autoexec.bat' file, or in the Windows Registry.
+
+These settings would cause TeX to look for `\input' file first in the
+current directory, indicated by the `.', then in a hypothetical user's
+`me/mylib' directory, and finally in a system directory
+`/usr/lib/tex/macros'.
+
+ Finally, you may wish to dump a `.fmt' file (*note Memory dumps:
+(web2c)Memory dumps.) so that TeX can load Texinfo faster. (The
+disadvantage is that then updating `texinfo.tex' requires redumping.)
+You can do this by running this command, assuming `epsf.tex' is
+findable by TeX:
+
+ initex texinfo @dump
+
+ (`@dump' is a TeX primitive.) You'll then need to move `texinfo.fmt'
+to wherever your `.fmt' files are found; typically this will be in the
+subdirectory `web2c' of your TeX installation, for example,
+`/usr/local/share/tex/web2c'.
+
+\1f
+File: texinfo.info, Node: Preparing for TeX-Footnotes, Up: Preparing for TeX
+
+ (1) Note the use of the `;' character, instead of `:', as directory
+separator on these systems.
\1f
-File: texinfo.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Format/Print Hardcopy
+File: texinfo.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Hardcopy
Overfull "hboxes"
=================
electronic mail network address or a very long title. When this
happens, TeX prints an error message like this:
- Overfull \hbox (20.76302pt too wide)
+ Overfull @hbox (20.76302pt too wide)
-(In TeX, lines are in "horizontal boxes", hence the term, "hbox". The
-backslash, `\', is the TeX equivalent of `@'.)
+(In TeX, lines are in "horizontal boxes", hence the term, "hbox".
+`@hbox' is a TeX primitive not needed in the Texinfo language.)
TeX also provides the line number in the Texinfo source file and the
text of the offending line, which is marked at all the places that TeX
-knows how to hyphenate words. *Note Catching Errors with TeX
-Formatting: Debugging with TeX, for more information about typesetting
-errors.
+considered hyphenation. *Note Catching Errors with TeX Formatting:
+Debugging with TeX, for more information about typesetting errors.
If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur, or you can decide to leave it. A
small excursion into the right margin often does not matter and may not
even be noticeable.
- However, unless told otherwise, TeX will print a large, ugly, black
-rectangle beside the line that contains the overfull hbox. This is so
-you will notice the location of the problem if you are correcting a
-draft.
+ If you have many overfull boxes and/or an antipathy to rewriting, you
+can coerce TeX into greatly increasing the allowable interword spacing,
+thus (if you're lucky) avoiding many of the bad line breaks, like this:
+
+ @tex
+ \global\emergencystretch = .9\hsize
+ @end tex
+
+(You can adjust the fraction as needed.) This huge value for
+`\emergencystretch' cannot be the default, since then the typeset
+output would generally be of noticeably lower quality. The default
+value is `.15\hsize'. `\hsize' is the TeX dimension containing the
+current line width.
+
+ For what overfull boxes you have, however, TeX will print a large,
+ugly, black rectangle beside the line that contains the overfull hbox
+unless told otherwise. This is so you will notice the location of the
+problem if you are correcting a draft.
To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
@finalout
\1f
-File: texinfo.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Format/Print Hardcopy
+File: texinfo.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Hardcopy
Printing "Small" Books
======================
@smallbook
-(Since regular sized books are often about 7 by 9.25 inches, this
-command might better have been called the `@regularbooksize' command,
-but it came to be called the `@smallbook' command by comparison to the
-8.5 by 11 inch format.)
+(Since many books are about 7 by 9.25 inches, this command might better
+have been called the `@regularbooksize' command, but it came to be
+called the `@smallbook' command by comparison to the 8.5 by 11 inch
+format.)
If you write the `@smallbook' command between the start-of-header and
end-of-header lines, the Texinfo mode TeX region formatting command,
`texinfo-tex-region', will format the region in "small" book size
-(*note Start of Header::.).
-
- The Free Software Foundation distributes printed copies of `The GNU
-Emacs Manual' and other manuals in the "small" book size. *Note
-`@smallexample' and `@smalllisp': smallexample & smalllisp, for
-information about commands that make it easier to produce examples for
-a smaller manual.
-
- Alternatively, to avoid embedding this physical paper size in your
-document, use `texi2dvi' to format your document (*note Format with
-texi2dvi::.), and supply `-t @smallbook' as an argument. Then other
-people do not have to change the document source file to format it
-differently.
-
-\1f
-File: texinfo.info, Node: A4 Paper, Next: Cropmarks and Magnification, Prev: smallbook, Up: Format/Print Hardcopy
-
-Printing on A4 Paper
-====================
-
- You can tell TeX to typeset a document for printing on European size
-A4 paper with the `@afourpaper' command. Write the command on a line
-by itself between `@iftex' and `@end iftex' lines near the beginning of
-the Texinfo file, before the title page:
-
- For example, this is how you would write the header for this manual:
-
- \input texinfo @c -*-texinfo-*-
- @c %**start of header
- @setfilename texinfo
- @settitle Texinfo
- @syncodeindex vr fn
- @iftex
- @afourpaper
- @end iftex
- @c %**end of header
-
- Alternatively, to avoid embedding this physical paper size in your
-document, use `texi2dvi' to format your document (*note Format with
-texi2dvi::.), and supply `-t @afourpaper' as an argument. Then other
-people do not have to change the document source file to format it
-differently.
-
- Another alternative: put the `@afourpaper' command in the file
-`texinfo.cnf' that TeX will read. (No need for `@iftex' there.) This
-will automatically typeset all the Texinfo documents at your site with
-that paper size in effect.
-
-\1f
-File: texinfo.info, Node: Cropmarks and Magnification, Prev: A4 Paper, Up: Format/Print Hardcopy
-
-Cropmarks and Magnification
-===========================
-
- You can attempt to direct TeX to print cropmarks at the corners of
-pages with the `@cropmarks' command. Write the `@cropmarks' command on
-a line by itself between `@iftex' and `@end iftex' lines near the
-beginning of the Texinfo file, before the title page, like this:
-
- @iftex
- @cropmarks
- @end iftex
-
- This command is mainly for printers that typeset several pages on one
-sheet of film; but you can attempt to use it to mark the corners of a
-book set to 7 by 9.25 inches with the `@smallbook' command. (Printers
-will not produce cropmarks for regular sized output that is printed on
-regular sized paper.) Since different printing machines work in
-different ways, you should explore the use of this command with a
-spirit of adventure. You may have to redefine the command in the
-`texinfo.tex' definitions file.
-
- You can attempt to direct TeX to typeset pages larger or smaller than
-usual with the `\mag' TeX command. Everything that is typeset is
-scaled proportionally larger or smaller. (`\mag' stands for
-"magnification".) This is *not* a Texinfo @-command, but is a plain
-TeX command that is prefixed with a backslash. You have to write this
-command between `@tex' and `@end tex' (*note Raw Formatter Commands::.).
-
- Follow the `\mag' command with an `=' and then a number that is 1000
-times the magnification you desire. For example, to print pages at 1.2
-normal size, write the following near the beginning of the Texinfo
-file, before the title page:
-
- @tex
- \mag=1200
- @end tex
-
- With some printing technologies, you can print normal-sized copies
-that look better than usual by using a larger-than-normal master.
-
- Depending on your system, `\mag' may not work or may work only at
-certain magnifications. Be prepared to experiment.
-
-\1f
-File: texinfo.info, Node: Create an Info File, Next: Install an Info File, Prev: Format/Print Hardcopy, Up: Top
-
-Creating an Info File
-*********************
-
- `makeinfo' is a utility that converts a Texinfo file into an Info
-file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs
-functions that do the same.
-
- A Texinfo file must contain an `@setfilename' line near its
-beginning, otherwise the Info formatting commands will fail.
-
- For information on installing the Info file in the Info system, see
-*Note Install an Info File::.
-
-* Menu:
-
-* makeinfo advantages:: `makeinfo' provides better error checking.
-* Invoking makeinfo:: How to run `makeinfo' from a shell.
-* makeinfo options:: Specify fill-column and other options.
-* Pointer Validation:: How to check that pointers point somewhere.
-* makeinfo in Emacs:: How to run `makeinfo' from Emacs.
-* texinfo-format commands:: Two Info formatting commands written
- in Emacs Lisp are an alternative
- to `makeinfo'.
-* Batch Formatting:: How to format for Info in Emacs Batch mode.
-* Tag and Split Files:: How tagged and split files help Info
- to run better.
-
-\1f
-File: texinfo.info, Node: makeinfo advantages, Next: Invoking makeinfo, Prev: Create an Info File, Up: Create an Info File
-
-`makeinfo' Preferred
-====================
-
- The `makeinfo' utility creates an Info file from a Texinfo source
-file more quickly than either of the Emacs formatting commands and
-provides better error messages. We recommend it. `makeinfo' is a C
-program that is independent of Emacs. You do not need to run Emacs to
-use `makeinfo', which means you can use `makeinfo' on machines that are
-too small to run Emacs. You can run `makeinfo' in any one of three
-ways: from an operating system shell, from a shell inside Emacs, or by
-typing a key command in Texinfo mode in Emacs.
-
- The `texinfo-format-region' and the `texinfo-format-buffer' commands
-are useful if you cannot run `makeinfo'. Also, in some circumstances,
-they format short regions or buffers more quickly than `makeinfo'.
-
-\1f
-File: texinfo.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Create an Info File
-
-Running `makeinfo' from a Shell
-===============================
-
- To create an Info file from a Texinfo file, type `makeinfo' followed
-by the name of the Texinfo file. Thus, to create the Info file for
-Bison, type the following to the shell: is the prompt):
-
- makeinfo bison.texinfo
-
- (You can run a shell inside Emacs by typing `M-x shell'.)
-
- Sometimes you will want to specify options. For example, if you wish
-to discover which version of `makeinfo' you are using, type:
-
- makeinfo --version
-
- *Note makeinfo options::, for more information.
-
-\1f
-File: texinfo.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Create an Info File
-
-Options for `makeinfo'
-======================
-
- The `makeinfo' command takes a number of options. Most often,
-options are used to set the value of the fill column and specify the
-footnote style. Each command line option is a word preceded by `--' or
-a letter preceded by `-'. You can use abbreviations for the long
-option names as long as they are unique.
-
- For example, you could use the following shell command to create an
-Info file for `bison.texinfo' in which each line is filled to only 68
-columns:
-
- makeinfo --fill-column=68 bison.texinfo
-
- You can write two or more options in sequence, like this:
-
- makeinfo --no-split --fill-column=70 ...
-
-This would keep the Info file together as one possibly very long file
-and would also set the fill column to 70.
-
- The options are:
-
-`-D VAR'
- Cause the variable VAR to be defined. This is equivalent to `@set
- VAR' in the Texinfo file (*note set clear value::.).
-
-`--error-limit=LIMIT'
- Set the maximum number of errors that `makeinfo' will report
- before exiting (on the assumption that continuing would be
- useless); default 100.
-
-`--fill-column=WIDTH'
- Specify the maximum number of columns in a line; this is the
- right-hand edge of a line. Paragraphs that are filled will be
- filled to this width. (Filling is the process of breaking up and
- connecting lines so that lines are the same length as or shorter
- than the number specified as the fill column. Lines are broken
- between words.) The default value is 72.
-
-`--footnote-style=STYLE'
- Set the footnote style to STYLE, either `end' for the end node
- style (the default) or `separate' for the separate node style.
- The value set by this option overrides the value set in a Texinfo
- file by an `@footnotestyle' command (*note Footnotes::.). When the
- footnote style is `separate', `makeinfo' makes a new node
- containing the footnotes found in the current node. When the
- footnote style is `end', `makeinfo' places the footnote references
- at the end of the current node.
-
-`--force'
- Ordinarily, if the input file has errors, the output files are not
- created. With this option, they are preserved.
-
-`--help'
- Print a usage message listing all available options, then exit
- successfully.
-
-`-I DIR'
- Add `dir' to the directory search list for finding files that are
- included using the `@include' command. By default, `makeinfo'
- searches only the current directory.
-
-`--no-headers'
- Do not include menus or node lines in the output. This results in
- an ASCII file that you cannot read in Info since it does not
- contain the requisite nodes or menus. It is primarily useful to
- extract certain pieces of a manual into separate files to be
- included in a distribution, such as `INSTALL' files.
-
-`--no-split'
- Suppress the splitting stage of `makeinfo'. By default, large
- output files (where the size is greater than 70k bytes) are split
- into smaller subfiles, each one approximately 50k bytes.
-
-`--no-pointer-validate'
-`--no-validate'
- Suppress the pointer-validation phase of `makeinfo'. Normally,
- after a Texinfo file is processed, some consistency checks are
- made to ensure that cross references can be resolved, etc. *Note
- Pointer Validation::.
-
-`--no-warn'
- Suppress warning messages (but *not* error messages). You might
- want this if the file you are creating has examples of Texinfo
- cross references within it, and the nodes that are referenced do
- not actually exist.
-
-`--no-number-footnotes'
- Suppress automatic footnote numbering. By default, `makeinfo'
- numbers each footnote sequentially in a single node, resetting the
- current footnote number to 1 at the start of each node.
-
-`--output=FILE'
-`-o FILE'
- Specify that the output should be directed to FILE and not to the
- file name specified in the `@setfilename' command found in the
- Texinfo source (*note setfilename::.). If FILE is `-', output
- goes to standard output and `--no-split' is implied.
-
-`-P DIR'
- Prepend `dir' to the directory search list for `@include'. See
- `-I' for more details.
-
-`--paragraph-indent=INDENT'
- Set the paragraph indentation style to INDENT. The value set by
- this option overrides the value set in a Texinfo file by an
- `@paragraphindent' command (*note paragraphindent::.). The value
- of INDENT is interpreted as follows:
-
- `asis'
- Preserve any existing indentation at the starts of paragraphs.
-
- `0' or `none'
- Delete any existing indentation.
-
- NUM
- Indent each paragraph by that number of spaces.
-
-`--reference-limit=LIMIT'
- Set the value of the number of references to a node that
- `makeinfo' will make without reporting a warning. If a node has
- more than this number of references in it, `makeinfo' will make the
- references but also report a warning. The default is 1000.
-
-`-U VAR'
- Cause VAR to be undefined. This is equivalent to `@clear VAR' in
- the Texinfo file (*note set clear value::.).
-
-`--verbose'
- Cause `makeinfo' to display messages saying what it is doing.
- Normally, `makeinfo' only outputs messages if there are errors or
- warnings.
-
-`--version'
- Print the version number, then exit successfully.
-
-\1f
-File: texinfo.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Create an Info File
-
-Pointer Validation
-==================
-
- If you do not suppress pointer-validation, `makeinfo' will check the
-validity of the final Info file. Mostly, this means ensuring that
-nodes you have referenced really exist. Here is a complete list of what
-is checked:
-
- 1. If a `Next', `Previous', or `Up' node reference is a reference to a
- node in the current file and is not an external reference such as
- to `(dir)', then the referenced node must exist.
-
- 2. In every node, if the `Previous' node is different from the `Up'
- node, then the `Previous' node must also be pointed to by a `Next'
- node.
-
- 3. Every node except the `Top' node must have an `Up' pointer.
-
- 4. The node referenced by an `Up' pointer must contain a reference to
- the current node in some manner other than through a `Next'
- reference. This includes menu entries and cross references.
-
- 5. If the `Next' reference of a node is not the same as the `Next'
- reference of the `Up' reference, then the node referenced by the
- `Next' pointer must have a `Previous' pointer that points back to
- the current node. This rule allows the last node in a section to
- point to the first node of the next chapter.
-
-\1f
-File: texinfo.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Create an Info File
-
-Running `makeinfo' inside Emacs
-===============================
-
- You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
-`makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode,
-the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
-
-`C-c C-m C-r'
-`M-x makeinfo-region'
- Format the current region for Info.
-
-`C-c C-m C-b'
-`M-x makeinfo-buffer'
- Format the current buffer for Info.
-
- When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
-prompts for a file name, offering the name of the visited file as the
-default. You can edit the default file name in the minibuffer if you
-wish, before pressing <RET> to start the `makeinfo' process.
-
- The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
-`makeinfo' program in a temporary shell buffer. If `makeinfo' finds
-any errors, Emacs displays the error messages in the temporary buffer.
-
- You can parse the error messages by typing `C-x `' (`next-error').
-This causes Emacs to go to and position the cursor on the line in the
-Texinfo source that `makeinfo' thinks caused the error. *Note Running
-`make' or Compilers Generally: (xemacs)Compilation, for more
-information about using the `next-error' command.
-
- In addition, you can kill the shell in which the `makeinfo' command
-is running or make the shell buffer display its most recent output.
-
-`C-c C-m C-k'
-`M-x makeinfo-kill-job'
- Kill the current running `makeinfo' job created by
- `makeinfo-region' or `makeinfo-buffer'.
-
-`C-c C-m C-l'
-`M-x makeinfo-recenter-output-buffer'
- Redisplay the `makeinfo' shell buffer to display its most recent
- output.
-
-(Note that the parallel commands for killing and recentering a TeX job
-are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.)
-
- You can specify options for `makeinfo' by setting the
-`makeinfo-options' variable with either the `M-x edit-options' or the
-`M-x set-variable' command, or by setting the variable in your `.emacs'
-initialization file.
-
- For example, you could write the following in your `.emacs' file:
-
- (setq makeinfo-options
- "--paragraph-indent=0 --no-split
- --fill-column=70 --verbose")
-
-For more information, see
-*Note Editing Variable Values: (xemacs)Edit Options,
-*Note Examining and Setting Variables: (xemacs)Examining,
-*Note Init File: (xemacs)Init File, and
-*Note Options for `makeinfo': makeinfo options.
-
-\1f
-File: texinfo.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Create an Info File
-
-The `texinfo-format...' Commands
-================================
-
-In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
-file with the `texinfo-format-region' command. This formats the
-current region and displays the formatted text in a temporary buffer
-called `*Info Region*'.
-
- Similarly, you can format a buffer with the `texinfo-format-buffer'
-command. This command creates a new buffer and generates the Info file
-in it. Typing `C-x C-s' will save the Info file under the name
-specified by the `@setfilename' line which must be near the beginning
-of the Texinfo file.
-
-`C-c C-e C-r'
-``texinfo-format-region''
- Format the current region for Info.
-
-`C-c C-e C-b'
-``texinfo-format-buffer''
- Format the current buffer for Info.
-
- The `texinfo-format-region' and `texinfo-format-buffer' commands
-provide you with some error checking, and other functions can provide
-you with further help in finding formatting errors. These procedures
-are described in an appendix; see *Note Catching Mistakes::. However,
-the `makeinfo' program is often faster and provides better error
-checking (*note makeinfo in Emacs::.).
-
-\1f
-File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Create an Info File
-
-Batch Formatting
-================
-
- You can format Texinfo files for Info using `batch-texinfo-format'
-and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
-including a shell inside of Emacs. (*Note Command Line Switches and
-Arguments: (xemacs)Command Switches.)
-
- Here is a shell command to format all the files that end in
-`.texinfo' in the current directory:
-
- emacs -batch -funcall batch-texinfo-format *.texinfo
-
-Emacs processes all the files listed on the command line, even if an
-error occurs while attempting to format some of them.
-
- Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it
-is not interactive. It kills the Batch mode Emacs on completion.
-
- `batch-texinfo-format' is convenient if you lack `makeinfo' and want
-to format several Texinfo files at once. When you use Batch mode, you
-create a new Emacs process. This frees your current Emacs, so you can
-continue working in it. (When you run `texinfo-format-region' or
-`texinfo-format-buffer', you cannot use that Emacs for anything else
-until the command finishes.)
-
-\1f
-File: texinfo.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Create an Info File
-
-Tag Files and Split Files
-=========================
-
- If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
-automatically creates a tag table for its Info file; `makeinfo' always
-creates a tag table. With a "tag table", Info can jump to new nodes
-more quickly than it can otherwise.
-
- In addition, if the Texinfo file contains more than about 70,000
-bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
-into shorter "indirect" subfiles of about 50,000 bytes each. Big files
-are split into smaller files so that Emacs does not need to make a
-large buffer to hold the whole of a large Info file; instead, Emacs
-allocates just enough memory for the small, split off file that is
-needed at the time. This way, Emacs avoids wasting memory when you run
-Info. (Before splitting was implemented, Info files were always kept
-short and "include files" were designed as a way to create a single,
-large printed manual out of the smaller Info files. *Note Include
-Files::, for more information. Include files are still used for very
-large documents, such as `The XEmacs Lisp Reference Manual', in which
-each chapter is a separate file.)
-
- When a file is split, Info itself makes use of a shortened version of
-the original file that contains just the tag table and references to
-the files that were split off. The split off files are called
-"indirect" files.
-
- The split off files have names that are created by appending `-1',
-`-2', `-3' and so on to the file name specified by the `@setfilename'
-command. The shortened version of the original file continues to have
-the name specified by `@setfilename'.
-
- At one stage in writing this document, for example, the Info file was
-saved as `test-texinfo' and that file looked like this:
-
- Info file: test-texinfo, -*-Text-*-
- produced by texinfo-format-buffer
- from file: new-texinfo-manual.texinfo
-
- ^_
- Indirect:
- test-texinfo-1: 102
- test-texinfo-2: 50422
- test-texinfo-3: 101300
- ^_^L
- Tag table:
- (Indirect)
- Node: overview^?104
- Node: info file^?1271
- Node: printed manual^?4853
- Node: conventions^?6855
- ...
-
-(But `test-texinfo' had far more nodes than are shown here.) Each of
-the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
-`test-texinfo-3', is listed in this file after the line that says
-`Indirect:'. The tag table is listed after the line that says `Tag
-table:'.
-
- In the list of indirect files, the number following the file name
-records the cumulative number of bytes in the preceding indirect files,
-not counting the file list itself, the tag table, or the permissions
-text in each file. In the tag table, the number following the node name
-records the location of the beginning of the node, in bytes from the
-beginning.
-
- If you are using `texinfo-format-buffer' to create Info files, you
-may want to run the `Info-validate' command. (The `makeinfo' command
-does such a good job on its own, you do not need `Info-validate'.)
-However, you cannot run the `M-x Info-validate' node-checking command
-on indirect files. For information on how to prevent files from being
-split and how to validate the structure of the nodes, see *Note Using
-Info-validate::.
-
-\1f
-File: texinfo.info, Node: Install an Info File, Next: Command List, Prev: Create an Info File, Up: Top
-
-Installing an Info File
-***********************
-
- Info files are usually kept in the `info' directory. You can read
-Info files using the standalone Info program or the Info reader built
-into Emacs. (*note info: (info)Top, for an introduction to Info.)
-
-* Menu:
-
-* Directory file:: The top level menu for all Info files.
-* New Info File:: Listing a new info file.
-* Other Info Directories:: How to specify Info files that are
- located in other directories.
-* Installing Dir Entries:: How to specify what menu entry to add
- to the Info directory.
-* Invoking install-info:: `install-info' options.
-
-\1f
-File: texinfo.info, Node: Directory file, Next: New Info File, Prev: Install an Info File, Up: Install an Info File
-
-The `dir' File
-==============
-
- For Info to work, the `info' directory must contain a file that
-serves as a top level directory for the Info system. By convention,
-this file is called `dir'. (You can find the location of this file
-within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
-to see the pathname to the `info' directory.)
-
- The `dir' file is itself an Info file. It contains the top level
-menu for all the Info files in the system. The menu looks like this:
-
- * Menu:
-
- * Info: (info). Documentation browsing system.
- * Emacs: (emacs). The extensible, self-documenting
- text editor.
- * Texinfo: (texinfo). With one source file, make
- either a printed manual using
- TeX or an Info file.
- ...
-
- Each of these menu entries points to the `Top' node of the Info file
-that is named in parentheses. (The menu entry does not need to specify
-the `Top' node, since Info goes to the `Top' node if no node name is
-mentioned. *Note Nodes in Other Info Files: Other Info Files.)
-
- Thus, the `Info' entry points to the `Top' node of the `info' file
-and the `Emacs' entry points to the `Top' node of the `emacs' file.
-
- In each of the Info files, the `Up' pointer of the `Top' node refers
-back to the `dir' file. For example, the line for the `Top' node of
-the Emacs manual looks like this in Info:
-
- File: emacs Node: Top, Up: (DIR), Next: Distrib
-
-(Note that in this case, the `dir' file name is written in upper case
-letters--it can be written in either upper or lower case. Info has a
-feature that it will change the case of the file name to lower case if
-it cannot find the name as written.)
-
-\1f
-File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory file, Up: Install an Info File
-
-Listing a New Info File
-=======================
-
- To add a new Info file to your system, you must write a menu entry to
-add to the menu in the `dir' file in the `info' directory. For
-example, if you were adding documentation for GDB, you would write the
-following new entry:
-
- * GDB: (gdb). The source-level C debugger.
-
-The first part of the menu entry is the menu entry name, followed by a
-colon. The second part is the name of the Info file, in parentheses,
-followed by a period. The third part is the description.
-
- The name of an Info file often has a `.info' extension. Thus, the
-Info file for GDB might be called either `gdb' or `gdb.info'. The Info
-reader programs automatically try the file name both with and without
-`.info'; so it is better to avoid clutter and not to write `.info'
-explicitly in the menu entry. For example, the GDB menu entry should
-use just `gdb' for the file name, not `gdb.info'.
-
-\1f
-File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Install an Info File
-
-Info Files in Other Directories
-===============================
-
- If an Info file is not in the `info' directory, there are three ways
-to specify its location:
-
- * Write the pathname in the `dir' file as the second part of the
- menu.
-
- * If you are using Emacs, list the name of the file in a second `dir'
- file, in its directory; and then add the name of that directory to
- the `Info-directory-list' variable in your personal or site
- initialization file.
-
- This tells Emacs where to look for `dir' files. Emacs merges the
- files named `dir' from each of the listed directories. (In Emacs
- version 18, you can set the `Info-directory' variable to the name
- of only one directory.)
-
- * Specify the Info directory name in the `INFOPATH' environment
- variable in your `.profile' or `.cshrc' initialization file.
- (Only you and others who set this environment variable will be
- able to find Info files whose location is specified this way.)
-
- For example, to reach a test file in the `/home/bob/manuals'
-directory, you could add an entry like this to the menu in the `dir'
-file:
-
- * Test: (/home/bob/manuals/info-test). Bob's own test file.
-
-In this case, the absolute file name of the `info-test' file is written
-as the second part of the menu entry.
-
- Alternatively, you could write the following in your `.emacs' file:
-
- (setq Info-directory-list
- '("/home/bob/manuals"
- "/usr/local/info"))
-
- This tells Emacs to merge the `dir' file from the `/home/bob/manuals'
-directory with the `dir' file from the `/usr/local/info' directory.
-Info will list the `/home/bob/manuals/info-test' file as a menu entry
-in the `/home/bob/manuals/dir' file.
-
- Finally, you can tell Info where to look by setting the `INFOPATH'
-environment variable in your `.cshrc' or `.profile' file. If you use a
-Bourne-compatible shell such as `sh' or `bash' for your shell command
-interpreter, you set the `INFOPATH' environment variable in the
-`.profile' initialization file; but if you use `csh' or `tcsh', you
-must set the variable in the `.cshrc' initialization file. The two
-types of shells use different syntax.
-
- * In a `.cshrc' file, you could set the `INFOPATH' variable as
- follows:
-
- setenv INFOPATH .:~/manuals:/usr/local/emacs/info
-
- * In a `.profile' file, you would achieve the same effect by writing:
-
- INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
- export INFOPATH
-
-The `.' indicates the current directory as usual. Emacs uses the
-`INFOPATH' environment variable to initialize the value of Emacs's own
-`Info-directory-list' variable.
-
- However you set `INFOPATH', if its last character is a colon, this is
-replaced by the default (compiled-in) path. This gives you a way to
-augment the default path with new directories without having to list all
-the standard places. For example (using `sh' syntax:
+(*note Start of Header::).
- INFOPATH=/local/info:
- export INFOPATH
+ *Note small::, for information about commands that make it easier to
+produce examples for a smaller manual.
-will search `/local/info' first, then the standard directories.
-Leading or doubled colons are not treated specially.
+ *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing
+for TeX, for other ways to format with `@smallbook' that do not require
+changing the source file.
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
+This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+texinfo.texi.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
END-INFO-DIR-ENTRY
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
Foundation, Inc.
- This edition is for Texinfo version 3.12.
+ This edition is for Texinfo version 4.0, 28 September 1999.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: texinfo.info, Node: A4 Paper, Next: pagesizes, Prev: smallbook, Up: Hardcopy
+
+Printing on A4 Paper
+====================
+
+ You can tell TeX to format a document for printing on European size
+A4 paper with the `@afourpaper' command. Write the command on a line
+by itself near the beginning of the Texinfo file, before the title
+page. For example, this is how you would write the header for this
+manual:
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename texinfo
+ @settitle Texinfo
+ @afourpaper
+ @c %**end of header
+
+ *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing
+for TeX, for other ways to format with `@afourpaper' that do not
+require changing the source file.
+
+ You may or may not prefer the formatting that results from the command
+`@afourlatex'. There's also `@afourwide' for A4 paper in wide format.
+
+\1f
+File: texinfo.info, Node: pagesizes, Next: Cropmarks and Magnification, Prev: A4 Paper, Up: Hardcopy
+
+`@pagesizes' [WIDTH][, HEIGHT]: Custom page sizes
+=================================================
+
+ You can explicitly specify the height and (optionally) width of the
+main text area on the page with the `@pagesizes' command. Write this
+on a line by itself near the beginning of the Texinfo file, before the
+title page. The height comes first, then the width if desired,
+separated by a comma. Examples:
+
+ @pagesizes 200mm,150mm
+ and
+ @pagesizes 11.5in
+
+ This would be reasonable for printing on B5-size paper. To emphasize,
+this command specifies the size of the _text area_, not the size of the
+paper (which is 250mm by 177mm for B5, 14in by 8.5in for legal).
+
+ To make more elaborate changes, such as changing any of the page
+margins, you must define a new command in `texinfo.tex' (or
+`texinfo.cnf', *note Preparing for TeX: Preparing for TeX.).
+
+ *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing
+for TeX, for other ways to specify `@pagesizes' that do not require
+changing the source file.
+
+ `@pagesizes' is ignored by `makeinfo'.
+
+\1f
+File: texinfo.info, Node: Cropmarks and Magnification, Next: PDF Output, Prev: pagesizes, Up: Hardcopy
+
+Cropmarks and Magnification
+===========================
+
+ You can (attempt to) direct TeX to print cropmarks at the corners of
+pages with the `@cropmarks' command. Write the `@cropmarks' command on
+a line by itself between `@iftex' and `@end iftex' lines near the
+beginning of the Texinfo file, before the title page, like this:
+
+ @iftex
+ @cropmarks
+ @end iftex
+
+ This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the `@smallbook' command. (Printers
+will not produce cropmarks for regular sized output that is printed on
+regular sized paper.) Since different printing machines work in
+different ways, you should explore the use of this command with a
+spirit of adventure. You may have to redefine the command in
+`texinfo.tex'.
+
+ You can attempt to direct TeX to typeset pages larger or smaller than
+usual with the `\mag' TeX command. Everything that is typeset is
+scaled proportionally larger or smaller. (`\mag' stands for
+"magnification".) This is _not_ a Texinfo @-command, but is a plain
+TeX command that is prefixed with a backslash. You have to write this
+command between `@tex' and `@end tex' (*note Raw Formatter Commands::).
+
+ Follow the `\mag' command with an `=' and then a number that is 1000
+times the magnification you desire. For example, to print pages at 1.2
+normal size, write the following near the beginning of the Texinfo
+file, before the title page:
+
+ @tex
+ \mag=1200
+ @end tex
+
+ With some printing technologies, you can print normal-sized copies
+that look better than usual by giving a larger-than-normal master to
+your print shop. They do the reduction, thus effectively increasing the
+resolution.
+
+ Depending on your system, DVI files prepared with a
+nonstandard-`\mag' may not print or may print only with certain
+magnifications. Be prepared to experiment.
+
+\1f
+File: texinfo.info, Node: PDF Output, Prev: Cropmarks and Magnification, Up: Hardcopy
+
+PDF Output
+==========
+
+ You can generate a PDF output file from Texinfo source by using the
+`pdftex' program to process your file instead of plain `tex'. Just run
+`pdftex foo.texi' instead of `tex foo.texi', or give the `--pdf' option
+to `texi2dvi'.
+
+ PDF stands for Portable Document Format, and was invented by Adobe
+Systems. The file format definition
+(http://www.adobe.com/prodindex/acrobat/adobepdf.html) is freely
+available, as is a free viewer (http://www.foolabs.com/xpdf/) for the X
+window system. Since PDF is a binary format, there is no `@ifpdf' or
+`@pdf' command by analogy with the other output formats.
+
+ Despite the `portable' in the name, PDF files are nowhere near as
+portable in practice as the plain ASCII formats (Info, HTML) Texinfo
+also supports (portability relative to DVI is arguable). They also tend
+to be much larger and do not support the bitmap fonts used by TeX (by
+default) very well. Nevertheless, a PDF file does preserve an actual
+printed document on a screen as faithfully as possible, unlike HTML,
+say, so have their place.
+
+ PDF support in Texinfo is fairly rudimentary.
+
+\1f
+File: texinfo.info, Node: Creating and Installing Info Files, Next: Command List, Prev: Hardcopy, Up: Top
+
+Creating and Installing Info Files
+**********************************
+
+ This chapter describes how to create and install info files. *Note
+Info Files::, for general information about the file format itself.
+
+* Menu:
+
+* Creating an Info File::
+* Install an Info File::
+
+\1f
+File: texinfo.info, Node: Creating an Info File, Next: Install an Info File, Up: Creating and Installing Info Files
+
+Creating an Info File
+=====================
+
+ `makeinfo' is a program that converts a Texinfo file into an Info
+file, HTML file, or plain text. `texinfo-format-region' and
+`texinfo-format-buffer' are GNU Emacs functions that convert Texinfo to
+Info.
+
+ For information on installing the Info file in the Info system, *note
+Install an Info File::.
+
+* Menu:
+
+* makeinfo advantages:: `makeinfo' provides better error checking.
+* Invoking makeinfo:: How to run `makeinfo' from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run `makeinfo' from Emacs.
+* texinfo-format commands:: Two Info formatting commands written
+ in Emacs Lisp are an alternative
+ to `makeinfo'.
+* Batch Formatting:: How to format for Info in Emacs Batch mode.
+* Tag and Split Files:: How tagged and split files help Info
+ to run better.
+* makeinfo html:: Generating HTML output.
+
+\1f
+File: texinfo.info, Node: makeinfo advantages, Next: Invoking makeinfo, Up: Creating an Info File
+
+`makeinfo' Preferred
+--------------------
+
+ The `makeinfo' utility creates an Info file from a Texinfo source
+file more quickly than either of the Emacs formatting commands and
+provides better error messages. We recommend it. `makeinfo' is a C
+program that is independent of Emacs. You do not need to run Emacs to
+use `makeinfo', which means you can use `makeinfo' on machines that are
+too small to run Emacs. You can run `makeinfo' in any one of three
+ways: from an operating system shell, from a shell inside Emacs, or by
+typing the `C-c C-m C-r' or the `C-c C-m C-b' command in Texinfo mode
+in Emacs.
+
+ The `texinfo-format-region' and the `texinfo-format-buffer' commands
+are useful if you cannot run `makeinfo'. Also, in some circumstances,
+they format short regions or buffers more quickly than `makeinfo'.
+
+\1f
+File: texinfo.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Creating an Info File
+
+Running `makeinfo' from a Shell
+-------------------------------
+
+ To create an Info file from a Texinfo file, type `makeinfo' followed
+by the name of the Texinfo file. Thus, to create the Info file for
+Bison, type the following to the shell:
+
+ makeinfo bison.texinfo
+
+ (You can run a shell inside Emacs by typing `M-x shell'.)
+
+ Sometimes you will want to specify options. For example, if you wish
+to discover which version of `makeinfo' you are using, type:
+
+ makeinfo --version
+
+ *Note makeinfo options::, for more information.
+
+\1f
+File: texinfo.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Creating an Info File
+
+Options for `makeinfo'
+----------------------
+
+ The `makeinfo' command takes a number of options. Most often,
+options are used to set the value of the fill column and specify the
+footnote style. Each command line option is a word preceded by `--' or
+a letter preceded by `-'. You can use abbreviations for the long
+option names as long as they are unique.
+
+ For example, you could use the following shell command to create an
+Info file for `bison.texinfo' in which each line is filled to only 68
+columns:
+
+ makeinfo --fill-column=68 bison.texinfo
+
+ You can write two or more options in sequence, like this:
+
+ makeinfo --no-split --fill-column=70 ...
+
+This would keep the Info file together as one possibly very long file
+and would also set the fill column to 70.
+
+ The options are:
+
+`-D VAR'
+ Cause the variable VAR to be defined. This is equivalent to `@set
+ VAR' in the Texinfo file (*note set clear value::).
+
+`--commands-in-node-names'
+ Allow `@'-commands in node names. This is not recommended, as it
+ can probably never be implemented in TeX. It also makes
+ `makeinfo' much slower. Also, this option is ignored when
+ `--no-validate' is used. *Note Pointer Validation::, for more
+ details.
+
+`--error-limit=LIMIT'
+`-e LIMIT'
+ Set the maximum number of errors that `makeinfo' will report
+ before exiting (on the assumption that continuing would be
+ useless); default 100.
+
+`--fill-column=WIDTH'
+`-f WIDTH'
+ Specify the maximum number of columns in a line; this is the
+ right-hand edge of a line. Paragraphs that are filled will be
+ filled to this width. (Filling is the process of breaking up and
+ connecting lines so that lines are the same length as or shorter
+ than the number specified as the fill column. Lines are broken
+ between words.) The default value is 72. Ignored with `--html'.
+
+`--footnote-style=STYLE'
+`-s STYLE'
+ Set the footnote style to STYLE, either `end' for the end node
+ style (the default) or `separate' for the separate node style.
+ The value set by this option overrides the value set in a Texinfo
+ file by an `@footnotestyle' command (*note Footnotes::). When the
+ footnote style is `separate', `makeinfo' makes a new node
+ containing the footnotes found in the current node. When the
+ footnote style is `end', `makeinfo' places the footnote references
+ at the end of the current node. Ignored with `--html'.
+
+`--force'
+`-F'
+ Ordinarily, if the input file has errors, the output files are not
+ created. With this option, they are preserved.
+
+`--help'
+`-h'
+ Print a usage message listing all available options, then exit
+ successfully.
+
+`--html'
+ Generate HTML output rather than Info. *Note makeinfo html::.
+
+`-I DIR'
+ Append DIR to the directory search list for finding files that are
+ included using the `@include' command. By default, `makeinfo'
+ searches only the current directory. If DIR is not given, the
+ current directory `.' is appended. Note that DIR can actually be
+ a list of several directories separated by the usual path
+ separator character (`:' on Unix, `;' on MS-DOS/MS-Windows).
+
+`--macro-expand=FILE'
+`-E FILE'
+ Output the Texinfo source with all the macros expanded to the named
+ file. Normally, the results of macro expansion are used
+ internally by `makeinfo' and then discarded. This option is used
+ by `texi2dvi' if you are using an old version of `texinfo.tex'
+ that does not support `@macro'.
+
+`--no-headers'
+ For Info output, do not include menus or node lines in the output
+ and write to standard output (unless `--output' is specified).
+ This results in an ASCII file that you cannot read in Info since
+ it does not contain the requisite nodes or menus. It is primarily
+ useful to extract certain pieces of a manual into separate files
+ to be included in a distribution, such as `INSTALL' files.
+
+ For HTML output, if `--no-split' is also specified, do not include
+ a navigation links at the top of each node. *Note makeinfo html::.
+
+`--no-split'
+ Suppress the splitting stage of `makeinfo'. By default, large
+ output files (where the size is greater than 70k bytes) are split
+ into smaller subfiles. For Info output, each one is approximately
+ 50k bytes. For HTML output, each file contains one node (*note
+ makeinfo html::).
+
+`--no-pointer-validate'
+`--no-validate'
+ Suppress the pointer-validation phase of `makeinfo'. This can also
+ be done with the `@novalidate' command (*note Use TeX: Use TeX.).
+ Normally, after a Texinfo file is processed, some consistency
+ checks are made to ensure that cross references can be resolved,
+ etc. *Note Pointer Validation::.
+
+`--no-warn'
+ Suppress warning messages (but _not_ error messages). You might
+ want this if the file you are creating has examples of Texinfo
+ cross references within it, and the nodes that are referenced do
+ not actually exist.
+
+`--number-sections'
+ Output chapter, section, and appendix numbers as in printed
+ manuals.
+
+`--no-number-footnotes'
+ Suppress automatic footnote numbering. By default, `makeinfo'
+ numbers each footnote sequentially in a single node, resetting the
+ current footnote number to 1 at the start of each node.
+
+`--output=FILE'
+`-o FILE'
+ Specify that the output should be directed to FILE and not to the
+ file name specified in the `@setfilename' command found in the
+ Texinfo source (*note setfilename::). If FILE is `-', output goes
+ to standard output and `--no-split' is implied. For split HTML
+ output, FILE is the name of the output file for the top node
+ (*note makeinfo html::).
+
+`-P DIR'
+ Prepend DIR to the directory search list for `@include'. If DIR
+ is not given, the current directory `.' is prepended. See `-I'
+ for more details.
+
+`--paragraph-indent=INDENT'
+`-p INDENT'
+ Set the paragraph indentation style to INDENT. The value set by
+ this option overrides the value set in a Texinfo file by an
+ `@paragraphindent' command (*note paragraphindent::). The value
+ of INDENT is interpreted as follows:
+
+ `asis'
+ Preserve any existing indentation at the starts of paragraphs.
+
+ `0' or `none'
+ Delete any existing indentation.
+
+ NUM
+ Indent each paragraph by NUM spaces.
+
+`--reference-limit=LIMIT'
+`-r LIMIT'
+ Set the value of the number of references to a node that
+ `makeinfo' will make without reporting a warning. If a node has
+ more than this number of references in it, `makeinfo' will make the
+ references but also report a warning. The default is 1000.
+
+`-U VAR'
+ Cause VAR to be undefined. This is equivalent to `@clear VAR' in
+ the Texinfo file (*note set clear value::).
+
+`--verbose'
+ Cause `makeinfo' to display messages saying what it is doing.
+ Normally, `makeinfo' only outputs messages if there are errors or
+ warnings.
+
+`--version'
+`-V'
+ Print the version number, then exit successfully.
+
+\1f
+File: texinfo.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Creating an Info File
+
+Pointer Validation
+------------------
+
+ If you do not suppress pointer validation with the `--no-validate'
+option or the `@novalidate' command in the source file (*note Use TeX:
+Use TeX.), `makeinfo' will check the validity of the final Info file.
+Mostly, this means ensuring that nodes you have referenced really
+exist. Here is a complete list of what is checked:
+
+ 1. If a `Next', `Previous', or `Up' node reference is a reference to a
+ node in the current file and is not an external reference such as
+ to `(dir)', then the referenced node must exist.
+
+ 2. In every node, if the `Previous' node is different from the `Up'
+ node, then the node pointed to by the `Previous' field must have a
+ `Next' field which points back to this node.
+
+ 3. Every node except the `Top' node must have an `Up' pointer.
+
+ 4. The node referenced by an `Up' pointer must itself reference the
+ current node through a menu item, unless the node referenced by
+ `Up' has the form `(FILE)'.
+
+ 5. If the `Next' reference of a node is not the same as the `Next'
+ reference of the `Up' reference, then the node referenced by the
+ `Next' pointer must have a `Previous' pointer that points back to
+ the current node. This rule allows the last node in a section to
+ point to the first node of the next chapter.
+
+ 6. Every node except `Top' should be referenced by at least one other
+ node, either via the `Previous' or `Next' links, or via a menu or a
+ cross-reference.
+
+ Some Texinfo documents might fail during the validation phase because
+they use commands like `@value' and `@definfoenclose' in node
+definitions and cross-references inconsistently. Consider the
+following example:
+
+ @set nodename Node 1
+
+ @node @value{nodename}, Node 2, Top, Top
+
+ This is node 1.
+
+ @node Node 2, , Node 1, Top
+
+ This is node 2.
+
+Here, the node "Node 1" was referenced both verbatim and through
+`@value'.
+
+ By default, `makeinfo' fails such cases, because node names are not
+fully expanded until they are written to the output file. You should
+always try to reference nodes consistently; e.g., in the above example,
+the second `@node' line should have also used `@value'. However, if,
+for some reason, you _must_ reference node names inconsistently, and
+`makeinfo' fails to validate the file, you can use the
+`--commands-in-node-names' option to force `makeinfo' to perform the
+expensive expansion of all node names it finds in the document. This
+might considerably slow down the program, though; twofold increase in
+conversion time was measured for large documents such as the Jargon
+file.
+
+ The support for `@'-commands in `@node' directives is not general
+enough to be freely used. For example, if the example above redefined
+`nodename' somewhere in the document, `makeinfo' will fail to convert
+it, even if invoked with the `--commands-in-node-names' option.
+
+ `--commands-in-node-names' has no effect if the `--no-validate'
+option is given.
+
+\1f
+File: texinfo.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Creating an Info File
+
+Running `makeinfo' inside Emacs
+-------------------------------
+
+ You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
+`makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode,
+the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
+
+`C-c C-m C-r'
+`M-x makeinfo-region'
+ Format the current region for Info.
+
+`C-c C-m C-b'
+`M-x makeinfo-buffer'
+ Format the current buffer for Info.
+
+ When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
+prompts for a file name, offering the name of the visited file as the
+default. You can edit the default file name in the minibuffer if you
+wish, before pressing <RET> to start the `makeinfo' process.
+
+ The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
+`makeinfo' program in a temporary shell buffer. If `makeinfo' finds
+any errors, Emacs displays the error messages in the temporary buffer.
+
+ You can parse the error messages by typing `C-x `' (`next-error').
+This causes Emacs to go to and position the cursor on the line in the
+Texinfo source that `makeinfo' thinks caused the error. *Note Running
+`make' or Compilers Generally: (emacs)Compilation, for more information
+about using the `next-error' command.
+
+ In addition, you can kill the shell in which the `makeinfo' command
+is running or make the shell buffer display its most recent output.
+
+`C-c C-m C-k'
+`M-x makeinfo-kill-job'
+ Kill the current running `makeinfo' job (from `makeinfo-region' or
+ `makeinfo-buffer').
+
+`C-c C-m C-l'
+`M-x makeinfo-recenter-output-buffer'
+ Redisplay the `makeinfo' shell buffer to display its most recent
+ output.
+
+(Note that the parallel commands for killing and recentering a TeX job
+are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.)
+
+ You can specify options for `makeinfo' by setting the
+`makeinfo-options' variable with either the `M-x edit-options' or the
+`M-x set-variable' command, or by setting the variable in your `.emacs'
+initialization file.
+
+ For example, you could write the following in your `.emacs' file:
+
+ (setq makeinfo-options
+ "--paragraph-indent=0 --no-split
+ --fill-column=70 --verbose")
+
+For more information, see
+*Note Editing Variable Values: (emacs)Edit Options,
+*Note Examining and Setting Variables: (emacs)Examining,
+*Note Init File: (emacs)Init File, and
+*Note Options for `makeinfo': makeinfo options.
+
+\1f
+File: texinfo.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Creating an Info File
+
+The `texinfo-format...' Commands
+--------------------------------
+
+In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
+file with the `texinfo-format-region' command. This formats the
+current region and displays the formatted text in a temporary buffer
+called `*Info Region*'.
+
+ Similarly, you can format a buffer with the `texinfo-format-buffer'
+command. This command creates a new buffer and generates the Info file
+in it. Typing `C-x C-s' will save the Info file under the name
+specified by the `@setfilename' line which must be near the beginning
+of the Texinfo file.
+
+`C-c C-e C-r'
+``texinfo-format-region''
+ Format the current region for Info.
+
+`C-c C-e C-b'
+``texinfo-format-buffer''
+ Format the current buffer for Info.
+
+ The `texinfo-format-region' and `texinfo-format-buffer' commands
+provide you with some error checking, and other functions can provide
+you with further help in finding formatting errors. These procedures
+are described in an appendix; see *Note Catching Mistakes::. However,
+the `makeinfo' program is often faster and provides better error
+checking (*note makeinfo in Emacs::).
+
+\1f
+File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Creating an Info File
+
+Batch Formatting
+----------------
+
+ You can format Texinfo files for Info using `batch-texinfo-format'
+and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
+including a shell inside of Emacs. (*Note Command Line Switches and
+Arguments: (emacs)Command Switches.)
+
+ Here is a shell command to format all the files that end in
+`.texinfo' in the current directory:
+
+ emacs -batch -funcall batch-texinfo-format *.texinfo
+
+Emacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of them.
+
+ Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it
+is not interactive. It kills the Batch mode Emacs on completion.
+
+ `batch-texinfo-format' is convenient if you lack `makeinfo' and want
+to format several Texinfo files at once. When you use Batch mode, you
+create a new Emacs process. This frees your current Emacs, so you can
+continue working in it. (When you run `texinfo-format-region' or
+`texinfo-format-buffer', you cannot use that Emacs for anything else
+until the command finishes.)
+
+\1f
+File: texinfo.info, Node: Tag and Split Files, Next: makeinfo html, Prev: Batch Formatting, Up: Creating an Info File
+
+Tag Files and Split Files
+-------------------------
+
+ If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
+automatically creates a tag table for its Info file; `makeinfo' always
+creates a tag table. With a "tag table", Info can jump to new nodes
+more quickly than it can otherwise.
+
+ In addition, if the Texinfo file contains more than about 70,000
+bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
+into shorter "indirect" subfiles of about 50,000 bytes each. Big files
+are split into smaller files so that Emacs does not need to make a
+large buffer to hold the whole of a large Info file; instead, Emacs
+allocates just enough memory for the small, split-off file that is
+needed at the time. This way, Emacs avoids wasting memory when you run
+Info. (Before splitting was implemented, Info files were always kept
+short and "include files" were designed as a way to create a single,
+large printed manual out of the smaller Info files. *Note Include
+Files::, for more information. Include files are still used for very
+large documents, such as `The Emacs Lisp Reference Manual', in which
+each chapter is a separate file.)
+
+ When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off. The split-off files are called
+"indirect" files.
+
+ The split-off files have names that are created by appending `-1',
+`-2', `-3' and so on to the file name specified by the `@setfilename'
+command. The shortened version of the original file continues to have
+the name specified by `@setfilename'.
+
+ At one stage in writing this document, for example, the Info file was
+saved as the file `test-texinfo' and that file looked like this:
+
+ Info file: test-texinfo, -*-Text-*-
+ produced by texinfo-format-buffer
+ from file: new-texinfo-manual.texinfo
+
+ ^_
+ Indirect:
+ test-texinfo-1: 102
+ test-texinfo-2: 50422
+ test-texinfo-3: 101300
+ ^_^L
+ Tag table:
+ (Indirect)
+ Node: overview^?104
+ Node: info file^?1271
+ Node: printed manual^?4853
+ Node: conventions^?6855
+ ...
+
+(But `test-texinfo' had far more nodes than are shown here.) Each of
+the split-off, indirect files, `test-texinfo-1', `test-texinfo-2', and
+`test-texinfo-3', is listed in this file after the line that says
+`Indirect:'. The tag table is listed after the line that says `Tag
+table:'.
+
+ In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect files,
+not counting the file list itself, the tag table, or the permissions
+text in each file. In the tag table, the number following the node name
+records the location of the beginning of the node, in bytes from the
+beginning of the (unsplit) output.
+
+ If you are using `texinfo-format-buffer' to create Info files, you
+may want to run the `Info-validate' command. (The `makeinfo' command
+does such a good job on its own, you do not need `Info-validate'.)
+However, you cannot run the `M-x Info-validate' node-checking command
+on indirect files. For information on how to prevent files from being
+split and how to validate the structure of the nodes, see *Note Using
+Info-validate::.
+
+\1f
+File: texinfo.info, Node: makeinfo html, Prev: Tag and Split Files, Up: Creating an Info File
+
+Generating HTML
+---------------
+
+ As an alternative to the normal Info format output you can use the
+`--html' option to generate output in HTML format, for installation on
+a web site (for example). In this release, HTML output from `makeinfo'
+is monolithic, splitting the output by chapter or node is not
+supported. We hope to implement this feature soon.
+
+ The HTML output file is named according to `@setfilename', but with
+any `.info' extension replaced with `.html'.
+
+ Texinfo input marked up with the `@ifhtml' command will produce
+output only with the `--html' option supplied. Input marked up with
+the `@html' is passed literally to the output (suppressing the normal
+escaping of input `<', `>' and `&' characters which have special
+significance in HTML).
+
+ The `--footnote-style' option is currently ignored for HTML output;
+footnotes are hyperlinked at the end of the output file.
+
+ The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866). The
+exception is that HTML 3.2 tables are generated from the `@multitable'
+command, but tagged to degrade as well as possible in browsers without
+table support. Please report output from an error-free run of
+`makeinfo' which violates the HTML 3.2 DTD as a bug.
+
+ Navigation bars are inserted at the start of nodes, similarly to Info
+output. The `--no-headers' option will suppress this if used with
+`--no-split'. Header `<link>' elements in split output can support
+info-like navigation with browsers like Lynx and Emacs W3 which
+implement this HTML 1.0 feature. You still won't normally get the
+multi-file regexp and index search facilities provided by Info readers.
+Otherwise, hyperlinks are generated from Texinfo commands where
+appropriate. `@xref' commands to other documents are generated
+assuming the other document is available in HTML form too, and `.html'
+is appended to the `@xref' Info file name. This presumably will often
+not work.
+
+\1f
+File: texinfo.info, Node: Install an Info File, Prev: Creating an Info File, Up: Creating and Installing Info Files
+
+Installing an Info File
+=======================
+
+ Info files are usually kept in the `info' directory. You can read
+Info files using the standalone Info program or the Info reader built
+into Emacs. (*note info: (info)Top, for an introduction to Info.)
+
+* Menu:
+
+* Directory File:: The top level menu for all Info files.
+* New Info File:: Listing a new info file.
+* Other Info Directories:: How to specify Info files that are
+ located in other directories.
+* Installing Dir Entries:: How to specify what menu entry to add
+ to the Info directory.
+* Invoking install-info:: `install-info' options.
+
+\1f
+File: texinfo.info, Node: Directory File, Next: New Info File, Up: Install an Info File
+
+The Directory File `dir'
+------------------------
+
+ For Info to work, the `info' directory must contain a file that
+serves as a top level directory for the Info system. By convention,
+this file is called `dir'. (You can find the location of this file
+within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
+to see the pathname to the `info' directory.)
+
+ The `dir' file is itself an Info file. It contains the top level
+menu for all the Info files in the system. The menu looks like this:
+
+ * Menu:
+ * Info: (info). Documentation browsing system.
+ * Emacs: (emacs). The extensible, self-documenting
+ text editor.
+ * Texinfo: (texinfo). With one source file, make
+ either a printed manual using
+ TeX or an Info file.
+ ...
+
+ Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses. (The menu entry does not need to specify
+the `Top' node, since Info goes to the `Top' node if no node name is
+mentioned. *Note Nodes in Other Info Files: Other Info Files.)
+
+ Thus, the `Info' entry points to the `Top' node of the `info' file
+and the `Emacs' entry points to the `Top' node of the `emacs' file.
+
+ In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the `dir' file. For example, the line for the `Top' node of
+the Emacs manual looks like this in Info:
+
+ File: emacs Node: Top, Up: (DIR), Next: Distrib
+
+In this case, the `dir' file name is written in upper case letters--it
+can be written in either upper or lower case. This is not true in
+general, it is a special case for `dir'.
+
+\1f
+File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory File, Up: Install an Info File
+
+Listing a New Info File
+-----------------------
+
+ To add a new Info file to your system, you must write a menu entry to
+add to the menu in the `dir' file in the `info' directory. For
+example, if you were adding documentation for GDB, you would write the
+following new entry:
+
+ * GDB: (gdb). The source-level C debugger.
+
+The first part of the menu entry is the menu entry name, followed by a
+colon. The second part is the name of the Info file, in parentheses,
+followed by a period. The third part is the description.
+
+ The name of an Info file often has a `.info' extension. Thus, the
+Info file for GDB might be called either `gdb' or `gdb.info'. The Info
+reader programs automatically try the file name both with and without
+`.info'(1) (*note New Info File-Footnote-1::); so it is better to avoid
+clutter and not to write `.info' explicitly in the menu entry. For
+example, the GDB menu entry should use just `gdb' for the file name,
+not `gdb.info'.
+
+\1f
+File: texinfo.info, Node: New Info File-Footnotes, Up: New Info File
+
+ (1) On MS-DOS/MS-Windows systems, Info will try the `.inf' extension
+as well.
+
+\1f
+File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Install an Info File
+
+Info Files in Other Directories
+-------------------------------
+
+ If an Info file is not in the `info' directory, there are three ways
+to specify its location:
+
+ 1. Write the pathname in the `dir' file as the second part of the
+ menu.
+
+ 2. If you are using Emacs, list the name of the file in a second `dir'
+ file, in its directory; and then add the name of that directory to
+ the `Info-directory-list' variable in your personal or site
+ initialization file.
+
+ This variable tells Emacs where to look for `dir' files (the files
+ must be named `dir'). Emacs merges the files named `dir' from
+ each of the listed directories. (In Emacs version 18, you can set
+ the `Info-directory' variable to the name of only one directory.)
+
+ 3. Specify the Info directory name in the `INFOPATH' environment
+ variable in your `.profile' or `.cshrc' initialization file.
+ (Only you and others who set this environment variable will be
+ able to find Info files whose location is specified this way.)
+
+ For example, to reach a test file in the `/home/bob/info' directory,
+you could add an entry like this to the menu in the standard `dir' file:
+
+ * Test: (/home/bob/info/info-test). Bob's own test file.
+
+In this case, the absolute file name of the `info-test' file is written
+as the second part of the menu entry.
+
+ Alternatively, you could write the following in your `.emacs' file:
+
+ (require 'info)
+ (setq Info-directory-list
+ (cons (expand-file-name "/home/bob/info") Info-directory-list))
+
+ This tells Emacs to merge the `dir' file from the `/home/bob/info'
+directory with the system `dir' file. Info will list the
+`/home/bob/info/info-test' file as a menu entry in the
+`/home/bob/info/dir' file. Emacs does the merging only when `M-x info'
+is first run, so if you want to set `Info-directory-list' in an Emacs
+session where you've already run `info', you must `(setq
+Info-dir-contents nil)' to force Emacs to recompose the `dir' file.
+
+ Finally, you can tell Info where to look by setting the `INFOPATH'
+environment variable in your shell startup file, such as `.cshrc',
+`.profile' or `autoexec.bat'. If you use a Bourne-compatible shell
+such as `sh' or `bash' for your shell command interpreter, you set the
+`INFOPATH' environment variable in the `.profile' initialization file;
+but if you use `csh' or `tcsh', you set the variable in the `.cshrc'
+initialization file. On MS-DOS/MS-Windows systems, you must set
+`INFOPATH' in your `autoexec.bat' file or in the Registry. Each type
+of shell uses a different syntax.
+
+ * In a `.cshrc' file, you could set the `INFOPATH' variable as
+ follows:
+
+ setenv INFOPATH .:~/info:/usr/local/emacs/info
+
+ * In a `.profile' file, you would achieve the same effect by writing:
+
+ INFOPATH=.:$HOME/info:/usr/local/emacs/info
+ export INFOPATH
+
+ * In a `autoexec.bat' file, you write this command(1) (*note Other
+ Info Directories-Footnote-1::):
+
+ set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
+
+The `.' indicates the current directory as usual. Emacs uses the
+`INFOPATH' environment variable to initialize the value of Emacs's own
+`Info-directory-list' variable. The stand-alone Info reader merges any
+files named `dir' in any directory listed in the `INFOPATH' variable
+into a single menu presented to you in the node called `(dir)Top'.
+
+ However you set `INFOPATH', if its last character is a colon(2)
+(*note Other Info Directories-Footnote-2::), this is replaced by the
+default (compiled-in) path. This gives you a way to augment the
+default path with new directories without having to list all the
+standard places. For example (using `sh' syntax):
+
+ INFOPATH=/local/info:
+ export INFOPATH
+
+will search `/local/info' first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
+ When you create your own `dir' file for use with
+`Info-directory-list' or `INFOPATH', it's easiest to start by copying
+an existing `dir' file and replace all the text after the `* Menu:'
+with your desired entries. That way, the punctuation and special
+CTRL-_ characters that Info needs will be present.
+
+\1f
+File: texinfo.info, Node: Other Info Directories-Footnotes, Up: Other Info Directories
+
+ (1) Note the use of `;' as the directory separator, and a different
+syntax for using values of other environment variables.
+
+ (2) On MS-DOS/MS-Windows systems, use semi-colon instead.
+
+\1f
File: texinfo.info, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Install an Info File
Installing Info Directory Files
-===============================
+-------------------------------
When you install an Info file onto your system, you can use the
program `install-info' to update the Info directory file `dir'.
copying the Info file into its proper installed location.
In order for the Info file to work with `install-info', you should
-use the commands `@dircategory' and `@direntry' in the Texinfo source
-file. Use `@direntry' to specify the menu entry to add to the Info
-directory file, and use `@dircategory' to specify which part of the
-Info directory to put it in. Here is how these commands are used in
-this manual:
+use the commands `@dircategory' and `@direntry'...`@end direntry' in
+the Texinfo source file. Use `@direntry' to specify the menu entries
+to add to the Info directory file, and use `@dircategory' to specify
+which part of the Info directory to put it in. Here is how these
+commands are used in this manual:
@dircategory Texinfo documentation system
@direntry
you use them later on in the input, `install-info' will not notice them.
If you use `@dircategory' more than once in the Texinfo source, each
-usage specifies one category; the new menu entry is added to the Info
-directory file in each of the categories you specify. If you use
-`@direntry' more than once, each usage specifies one menu entry; each
-of these menu entries is added to the directory in each of the
-specified categories.
+usage specifies the `current' category; any subsequent `@direntry'
+commands will add to that category.
+
+ Here are some recommended `@dircategory' categories: `GNU packages',
+`GNU programming tools', `GNU programming documentation', `GNU Emacs
+Lisp', `GNU libraries', `Linux', `TeX', `Individual utilities'. The
+idea is to include the `invoking' node for every program installed by a
+package under `Individual utilities', and an entry for the manual as a
+whole in the appropriate other category.
\1f
File: texinfo.info, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Install an Info File
Invoking install-info
-=====================
+---------------------
`install-info' inserts menu entries from an Info file into the
top-level `dir' file in the Info system (see the previous sections for
an explanation of how the `dir' file works). It's most often run as
-part of software installation, or when constructing a dir file for all
-manuals on a system. Synopsis:
+part of software installation, or when constructing a `dir' file for
+all manuals on a system. Synopsis:
install-info [OPTION]... [INFO-FILE [DIR-FILE]]
- If INFO-FILE or DIR-FILE are not specified, the various options
-(described below) that define them must be. There are no compile-time
-defaults, and standard input is never used. `install-info' can read
-only one info file and write only one dir file per invocation.
+ If INFO-FILE or DIR-FILE are not specified, the options (described
+below) that define them must be. There are no compile-time defaults,
+and standard input is never used. `install-info' can read only one
+Info file and write only one `dir' file per invocation.
If DIR-FILE (however specified) does not exist, `install-info'
creates it if possible (with no entries).
+ If any input file is compressed with `gzip' (*note Invoking gzip:
+(gzip)Invoking gzip.), `install-info' automatically uncompresses it for
+reading. And if DIR-FILE is compressed, `install-info' also
+automatically leaves it compressed after writing any changes. If
+DIR-FILE itself does not exist, `install-info' tries to open
+`DIR-FILE.gz'.
+
Options:
`--delete'
`.info' in either one). Don't insert any new entries.
`--dir-file=NAME'
+`-d NAME'
Specify file name of the Info directory file. This is equivalent
to using the DIR-FILE argument.
`--entry=TEXT'
+`-e TEXT'
Insert TEXT as an Info directory entry; TEXT should have the form
of an Info menu item line plus zero or more extra lines starting
with whitespace. If you specify more than one entry, they are all
information in the Info file itself.
`--help'
+`-h'
Display a usage message listing basic usage and all available
options, then exit successfully.
`--info-file=FILE'
- Specify Info file to install in the directory. This is equivalent
- to using the INFO-FILE argument.
+`-i FILE'
+ Specify Info file to install in the directory. Equivalent to
+ using the INFO-FILE argument.
`--info-dir=DIR'
- Equivalent to `--dir-file=DIR/dir'.
+`-D DIR'
+ Specify the directory where `dir' resides. Equivalent to
+ `--dir-file=DIR/dir'.
`--item=TEXT'
Same as `--entry=TEXT'. An Info directory entry is actually a
Suppress warnings.
`--remove'
+`-r'
Same as `--delete'.
`--section=SEC'
+`-s SEC'
Put this file's entries in section SEC of the directory. If you
specify more than one section, all the entries are added in each
of the sections. If you don't specify any sections, they are
determined from information in the Info file itself.
`--version'
+`-V'
Display version information and exit successfully.
-\1f
-File: texinfo.info, Node: Command List, Next: Tips, Prev: Install an Info File, Up: Top
-
-@-Command List
-**************
-
- Here is an alphabetical list of the @-commands in Texinfo. Square
-brackets, [ ], indicate optional arguments; an ellipsis, `...',
-indicates repeated text.
-
-`@WHITESPACE'
- An `@' followed by a space, tab, or newline produces a normal,
- stretchable, interword space. *Note Multiple Spaces::.
-
-`@!'
- Generate an exclamation point that really does end a sentence
- (usually after an end-of-sentence capital letter). *Note Ending a
- Sentence::.
-
-`@"'
-`@''
- Generate an umlaut or acute accent, respectively, over the next
- character, as in "o and 'o. *Note Inserting Accents::.
-
-`@*'
- Force a line break. Do not end a paragraph that uses `@*' with an
- `@refill' command. *Note Line Breaks::.
-
-`@,{C}'
- Generate a cedilla accent under C, as in c,. *Note Inserting
- Accents::.
-
-`@-'
- Insert a discretionary hyphenation point. *Note - and
- hyphenation::.
-
-`@.'
- Produce a period that really does end a sentence (usually after an
- end-of-sentence capital letter). *Note Ending a Sentence::.
-
-`@:'
- Indicate to TeX that an immediately preceding period, question
- mark, exclamation mark, or colon does not end a sentence. Prevent
- TeX from inserting extra whitespace as it does at the end of a
- sentence. The command has no effect on the Info file output.
- *Note Not Ending a Sentence::.
-
-`@='
- Generate a macro (bar) accent over the next character, as in =o.
- *Note Inserting Accents::.
-
-`@?'
- Generate a question mark that really does end a sentence (usually
- after an end-of-sentence capital letter). *Note Ending a
- Sentence::.
-
-`@@'
- Stands for an at sign, `@'. *Note Inserting @ and braces: Braces
- Atsigns.
-
-`@^'
-`@`'
- Generate a circumflex (hat) or grave accent, respectively, over
- the next character, as in ^o. *Note Inserting Accents::.
-
-`@{'
- Stands for a left brace, `{'. *Note Inserting @ and braces:
- Braces Atsigns.
-
-`@}'
- Stands for a right-hand brace, `}'.
- *Note Inserting @ and braces: Braces Atsigns.
-
-`@='
- Generate a tilde accent over the next character, as in ~N. *Note
- Inserting Accents::.
-
-`@AA{}'
-`@aa{}'
- Generate the uppercase and lowercase Scandinavian A-ring letters,
- respectively: AA, aa. *Note Inserting Accents::.
-
-`@AE{}'
-`@ae{}'
- Generate the uppercase and lowercase AE ligatures, respectively:
- AE, ae. *Note Inserting Accents::.
-
-`@afourpaper'
- Change page dimensions for the A4 paper size. Only allowed inside
- `@iftex' ... `@end iftex'. *Note A4 Paper::.
-
-`@appendix TITLE'
- Begin an appendix. The title appears in the table of contents of
- a printed manual. In Info, the title is underlined with
- asterisks. *Note The `@unnumbered' and `@appendix' Commands:
- unnumbered & appendix.
-
-`@appendixsec TITLE'
-`@appendixsection TITLE'
- Begin an appendix section within an appendix. The section title
- appears in the table of contents of a printed manual. In Info,
- the title is underlined with equal signs. `@appendixsection' is a
- longer spelling of the `@appendixsec' command. *Note Section
- Commands: unnumberedsec appendixsec heading.
-
-`@appendixsubsec TITLE'
- Begin an appendix subsection within an appendix. The title appears
- in the table of contents of a printed manual. In Info, the title
- is underlined with hyphens. *Note Subsection Commands:
- unnumberedsubsec appendixsubsec subheading.
-
-`@appendixsubsubsec TITLE'
- Begin an appendix subsubsection within an appendix subsection. The
- title appears in the table of contents of a printed manual. In
- Info, the title is underlined with periods. *Note The `subsub'
- Commands: subsubsection.
-
-`@asis'
- Used following `@table', `@ftable', and `@vtable' to print the
- table's first column without highlighting ("as is"). *Note Making
- a Two-column Table: Two-column Tables.
-
-`@author AUTHOR'
- Typeset AUTHOR flushleft and underline it. *Note The `@title' and
- `@author' Commands: title subtitle author.
-
-`@b{TEXT}'
- Print TEXT in bold font. No effect in Info. *Note Fonts::.
-
-`@bullet{}'
- Generate a large round dot, or the closest possible thing to one.
- *Note `@bullet': bullet.
-
-`@bye'
- Stop formatting a file. The formatters do not see the contents of
- a file following an `@bye' command. *Note Ending a File::.
-
-`@c COMMENT'
- Begin a comment in Texinfo. The rest of the line does not appear
- in either the Info file or the printed manual. A synonym for
- `@comment'. *Note Comments: Comments.
-
-`@cartouche'
- Highlight an example or quotation by drawing a box with rounded
- corners around it. Pair with `@end cartouche'. No effect in
- Info. *Note Drawing Cartouches Around Examples: cartouche.)
-
-`@center LINE-OF-TEXT'
- Center the line of text following the command. *Note `@center':
- titlefont center sp.
-
-`@centerchap LINE-OF-TEXT'
- Like `@chapter', but centers the chapter title. *Note `@chapter':
- chapter.
-
-`@chapheading TITLE'
- Print a chapter-like heading in the text, but not in the table of
- contents of a printed manual. In Info, the title is underlined
- with asterisks. *Note `@majorheading' and `@chapheading':
- majorheading & chapheading.
-
-`@chapter TITLE'
- Begin a chapter. The chapter title appears in the table of
- contents of a printed manual. In Info, the title is underlined
- with asterisks. *Note `@chapter': chapter.
-
-`@cindex ENTRY'
- Add ENTRY to the index of concepts. *Note Defining the Entries of
- an Index: Index Entries.
-
-`@cite{REFERENCE}'
- Highlight the name of a book or other reference that lacks a
- companion Info file. *Note `@cite': cite.
-
-`@clear FLAG'
- Unset FLAG, preventing the Texinfo formatting commands from
- formatting text between subsequent pairs of `@ifset FLAG' and
- `@end ifset' commands, and preventing `@value{FLAG}' from
- expanding to the value to which FLAG is set. *Note `@set'
- `@clear' `@value': set clear value.
-
-`@code{SAMPLE-CODE}'
- Highlight text that is an expression, a syntactically complete
- token of a program, or a program name. *Note `@code': code.
-
-`@comment COMMENT'
- Begin a comment in Texinfo. The rest of the line does not appear
- in either the Info file or the printed manual. A synonym for `@c'.
- *Note Comments: Comments.
-
-`@contents'
- Print a complete table of contents. Has no effect in Info, which
- uses menus instead. *Note Generating a Table of Contents:
- Contents.
-
-`@copyright{}'
- Generate a copyright symbol. *Note `@copyright': copyright symbol.
-
-`@defcodeindex INDEX-NAME'
- Define a new index and its indexing command. Print entries in an
- `@code' font. *Note Defining New Indices: New Indices.
-
-`@defcv CATEGORY CLASS NAME'
-`@defcvx CATEGORY CLASS NAME'
- Format a description for a variable associated with a class in
- object-oriented programming. Takes three arguments: the category
- of thing being defined, the class to which it belongs, and its
- name. *Note Definition Commands::, and *Note Def Cmds in Detail:
- deffnx.
-
-`@deffn CATEGORY NAME ARGUMENTS...'
-`@deffnx CATEGORY NAME ARGUMENTS...'
- Format a description for a function, interactive command, or
- similar entity that may take arguments. `@deffn' takes as
- arguments the category of entity being described, the name of this
- particular entity, and its arguments, if any. *Note Definition
- Commands::.
-
-`@defindex INDEX-NAME'
- Define a new index and its indexing command. Print entries in a
- roman font. *Note Defining New Indices: New Indices.
-
-`@definfoenclose NEW-COMMAND, BEFORE, AFTER,'
- Create new @-command for Info that marks text by enclosing it in
- strings that precede and follow the text. Write definition inside
- of `@ifinfo' ... `@end ifinfo'. *Note Customized Highlighting::.
-
-`@defivar CLASS INSTANCE-VARIABLE-NAME'
-`@defivarx CLASS INSTANCE-VARIABLE-NAME'
- This command formats a description for an instance variable in
- object-oriented programming. The command is equivalent to `@defcv
- {Instance Variable} ...'. *Note Definition Commands::, and *Note
- Def Cmds in Detail: deffnx.
-
-`@defmac MACRO-NAME ARGUMENTS...'
-`@defmacx MACRO-NAME ARGUMENTS...'
- Format a description for a macro. The command is equivalent to
- `@deffn Macro ...'. *Note Definition Commands::, and *Note Def
- Cmds in Detail: deffnx.
-
-`@defmethod CLASS METHOD-NAME ARGUMENTS...'
-`@defmethodx CLASS METHOD-NAME ARGUMENTS...'
- Format a description for a method in object-oriented programming.
- The command is equivalent to `@defop Method ...'. Takes as
- arguments the name of the class of the method, the name of the
- method, and its arguments, if any. *Note Definition Commands::,
- and *Note Def Cmds in Detail: deffnx.
-
-`@defop CATEGORY CLASS NAME ARGUMENTS...'
-`@defopx CATEGORY CLASS NAME ARGUMENTS...'
- Format a description for an operation in object-oriented
- programming. `@defop' takes as arguments the overall name of the
- category of operation, the name of the class of the operation, the
- name of the operation, and its arguments, if any. *Note
- Definition Commands::, and *Note Def Cmds in Detail: deffnx.
-
-`@defopt OPTION-NAME'
-`@defoptx OPTION-NAME'
- Format a description for a user option. The command is equivalent
- to `@defvr {User Option} ...'. *Note Definition Commands::, and
- *Note Def Cmds in Detail: deffnx.
-
-`@defspec SPECIAL-FORM-NAME ARGUMENTS...'
-`@defspecx SPECIAL-FORM-NAME ARGUMENTS...'
- Format a description for a special form. The command is
- equivalent to `@deffn {Special Form} ...'. *Note Definition
- Commands::, and *Note Def Cmds in Detail: deffnx.
-
-`@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
-`@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...'
- Format a description for a data type. `@deftp' takes as arguments
- the category, the name of the type (which is a word like `int' or
- `float'), and then the names of attributes of objects of that type.
- *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
-
-`@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
-`@deftypefnx CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
- Format a description for a function or similar entity that may take
- arguments and that is typed. `@deftypefn' takes as arguments the
- classification of entity being described, the type, the name of the
- entity, and its arguments, if any. *Note Definition Commands::,
- and *Note Def Cmds in Detail: deffnx.
-
-`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
-`@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...'
- Format a description for a function in a typed language. The
- command is equivalent to `@deftypefn Function ...'. *Note
- Definition Commands::, and *Note Def Cmds in Detail: deffnx.
-
-`@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
-`@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
- Format a description for a typed method in object-oriented
- programming. Takes as arguments the name of the class of the
- method, the return type of the method, the name of the method, and
- its arguments, if any. *Note Definition Commands::, and *Note Def
- Cmds in Detail: deffnx.
-
-`@deftypevr CLASSIFICATION DATA-TYPE NAME'
-`@deftypevrx CLASSIFICATION DATA-TYPE NAME'
- Format a description for something like a variable in a typed
- language--an entity that records a value. Takes as arguments the
- classification of entity being described, the type, and the name
- of the entity. *Note Definition Commands::, and *Note Def Cmds in
- Detail: deffnx.
-
-`@deftypevar DATA-TYPE VARIABLE-NAME'
-`@deftypevarx DATA-TYPE VARIABLE-NAME'
- Format a description for a variable in a typed language. The
- command is equivalent to `@deftypevr Variable ...'. *Note
- Definition Commands::, and *Note Def Cmds in Detail: deffnx.
-
-`@defun FUNCTION-NAME ARGUMENTS...'
-`@defunx FUNCTION-NAME ARGUMENTS...'
- Format a description for functions. The command is equivalent to
- `@deffn Function ...'. *Note Definition Commands::, and *Note Def
- Cmds in Detail: deffnx.
-
-`@defvar VARIABLE-NAME'
-`@defvarx VARIABLE-NAME'
- Format a description for variables. The command is equivalent to
- `@defvr Variable ...'. *Note Definition Commands::, and *Note Def
- Cmds in Detail: deffnx.
-
-`@defvr CATEGORY NAME'
-`@defvrx CATEGORY NAME'
- Format a description for any kind of variable. `@defvr' takes as
- arguments the category of the entity and the name of the entity.
- *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
-
-`@detailmenu{}'
- Avoid `makeinfo' confusion stemming from the detailed node listing
- in a master menu. *Note Master Menu Parts::.
-
-`@dfn{TERM}'
- Highlight the introductory or defining use of a term. *Note
- `@dfn': dfn.
-
-`@dircategory DIRPART'
- Specify a part of the Info directory menu where this file's entry
- should go. *Note Installing Dir Entries::.
-
-`@direntry'
- Begin the Info directory menu entry for this file. *Note
- Installing Dir Entries::.
-
-`@display'
- Begin a kind of example. Indent text, do not fill, do not select a
- new font. Pair with `@end display'. *Note `@display': display.
-
-`@dmn{DIMENSION}'
- Format a unit of measure, as in 12pt. Causes TeX to insert a thin
- space before DIMENSION. No effect in Info. *Note `@dmn': dmn.
-
-`@dotaccent{C}'
- Generate a dot accent over the character C, as in .oo. *Note
- Inserting Accents::.
-
-`@dots{}'
- Insert an ellipsis: `...'. *Note `@dots{}': dots.
-
-`@email{ADDRESS[, DISPLAYED-TEXT]}'
- Indicate an electronic mail address. *Note `@email': email.
-
-`@emph{TEXT}'
- Highlight TEXT; text is displayed in *italics* in printed output,
- and surrounded by asterisks in Info. *Note Emphasizing Text:
- Emphasis.
-
-`@end ENVIRONMENT'
- Ends ENVIRONMENT, as in `@end example'. *Note @-commands:
- Formatting Commands.
-
-`@enddots{}'
- Generate an end-of-sentence of ellipsis, like this .... *Note
- `@dots{}': dots.
-
-`@enumerate [NUMBER-OR-LETTER]'
- Begin a numbered list, using `@item' for each entry. Optionally,
- start list with NUMBER-OR-LETTER. Pair with `@end enumerate'.
- *Note `@enumerate': enumerate.
-
-`@equiv{}'
- Indicate to the reader the exact equivalence of two forms with a
- glyph: `=='. *Note Equivalence::.
-
-`@error{}'
- Indicate to the reader with a glyph that the following text is an
- error message: `error-->'. *Note Error Glyph::.
-
-`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
-`@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
- Specify page footings resp. headings for even-numbered (left-hand)
- pages. Only allowed inside `@iftex'. *Note How to Make Your Own
- Headings: Custom Headings.
-
-`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
-`@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
- Specify page footings resp. headings for every page. Not relevant
- to Info. *Note How to Make Your Own Headings: Custom Headings.
-
-`@example'
- Begin an example. Indent text, do not fill, and select
- fixed-width font. Pair with `@end example'. *Note `@example':
- example.
-
-`@exclamdown{}'
- Produce an upside-down exclamation point. *Note Inserting
- Accents::.
-
-`@exdent LINE-OF-TEXT'
- Remove any indentation a line might have. *Note Undoing the
- Indentation of a Line: exdent.
-
-`@expansion{}'
- Indicate the result of a macro expansion to the reader with a
- special glyph: `==>'. *Note ==> Indicating an Expansion:
- expansion.
-
-`@file{FILENAME}'
- Highlight the name of a file, buffer, node, or directory. *Note
- `@file': file.
-
-`@finalout'
- Prevent TeX from printing large black warning rectangles beside
- over-wide lines. *Note Overfull hboxes::.
-
-`@findex ENTRY'
- Add ENTRY to the index of functions. *Note Defining the Entries
- of an Index: Index Entries.
-
-`@flushleft'
-`@flushright'
- Left justify every line but leave the right end ragged. Leave
- font as is. Pair with `@end flushleft'. `@flushright' analogous.
- *Note `@flushleft' and `@flushright': flushleft & flushright.
-
-`@footnote{TEXT-OF-FOOTNOTE}'
- Enter a footnote. Footnote text is printed at the bottom of the
- page by TeX; Info may format in either `End' node or `Separate'
- node style. *Note Footnotes::.
-
-`@footnotestyle STYLE'
- Specify an Info file's footnote style, either `end' for the end
- node style or `separate' for the separate node style. *Note
- Footnotes::.
-
-`@format'
- Begin a kind of example. Like `@example' or `@display', but do
- not narrow the margins and do not select the fixed-width font.
- Pair with `@end format'. *Note `@example': example.
-
-`@ftable FORMATTING-COMMAND'
- Begin a two-column table, using `@item' for each entry.
- Automatically enter each of the items in the first column into the
- index of functions. Pair with `@end ftable'. The same as
- `@table', except for indexing. *Note `@ftable' and `@vtable':
- ftable vtable.
-
-`@group'
- Hold text together that must appear on one printed page. Pair with
- `@end group'. Not relevant to Info. *Note `@group': group.
-
-`@H{C}'
- Generate the long Hungarian umlaut accent over C, as in ''o.
-
-`@heading TITLE'
- Print an unnumbered section-like heading in the text, but not in
- the table of contents of a printed manual. In Info, the title is
- underlined with equal signs. *Note Section Commands:
- unnumberedsec appendixsec heading.
-
-`@headings ON-OFF-SINGLE-DOUBLE'
- Turn page headings on or off, and/or specify single-sided or
- double-sided page headings for printing. *Note The `@headings'
- Command: headings on off.
-
-`@html'
- Enter HTML completely. Pair with `@end html'. *Note Raw
- Formatter Commands::.
-
-`@hyphenation{HY-PHEN-A-TED WORDS}'
- Explicitly define hyphenation points. *Note `@-' and
- `@hyphenation': - and hyphenation.
-
-`@i{TEXT}'
- Print TEXT in italic font. No effect in Info. *Note Fonts::.
-
-`@ifclear FLAG'
- If FLAG is cleared, the Texinfo formatting commands format text
- between `@ifclear FLAG' and the following `@end ifclear' command.
- *Note `@set' `@clear' `@value': set clear value.
-
-`@ifhtml'
-`@ifinfo'
- Begin a stretch of text that will be ignored by TeX when it
- typesets the printed manual. The text appears only in the HTML
- resp. Info file. Pair with `@end ifhtml' resp. `@end ifinfo'.
- *Note Conditionals::.
-
-`@ifnothtml'
-`@ifnotinfo'
-`@ifnottex'
- Begin a stretch of text that will be ignored in one output format
- but not the others. The text appears only in the format not
- specified. Pair with `@end ifnothtml' resp. `@end ifnotinfo' resp.
- `@end ifnotinfo'. *Note Conditionals::.
-
-`@ifset FLAG'
- If FLAG is set, the Texinfo formatting commands format text
- between `@ifset FLAG' and the following `@end ifset' command.
- *Note `@set' `@clear' `@value': set clear value.
-
-`@iftex'
- Begin a stretch of text that will not appear in the Info file, but
- will be processed only by TeX. Pair with `@end iftex'. *Note
- Conditionally Visible Text: Conditionals.
-
-`@ignore'
- Begin a stretch of text that will not appear in either the Info
- file or the printed output. Pair with `@end ignore'. *Note
- Comments and Ignored Text: Comments.
-
-`@image{FILENAME, [WIDTH], [HEIGHT]}'
- Include graphics image in external FILENAME scaled to the given
- WIDTH and/or HEIGHT. *Note Images::.
-
-`@include FILENAME'
- Incorporate the contents of the file FILENAME into the Info file
- or printed document. *Note Include Files::.
-
-`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
- Make a cross reference to an Info file for which there is no
- printed manual. *Note Cross references using `@inforef': inforef.
-
-`\input MACRO-DEFINITIONS-FILE'
- Use the specified macro definitions file. This command is used
- only in the first line of a Texinfo file to cause TeX to make use
- of the `texinfo' macro definitions file. The backslash in `\input'
- is used instead of an `@' because TeX does not recognize `@' until
- after it has read the definitions file. *Note The Texinfo File
- Header: Header.
-
-`@item'
- Indicate the beginning of a marked paragraph for `@itemize' and
- `@enumerate'; indicate the beginning of the text of a first column
- entry for `@table', `@ftable', and `@vtable'. *Note Lists and
- Tables::.
-
-`@itemize MARK-GENERATING-CHARACTER-OR-COMMAND'
- Produce a sequence of indented paragraphs, with a mark inside the
- left margin at the beginning of each paragraph. Pair with `@end
- itemize'. *Note `@itemize': itemize.
-
-`@itemx'
- Like `@item' but do not generate extra vertical space above the
- item text. *Note `@itemx': itemx.
-
-`@kbd{KEYBOARD-CHARACTERS}'
- Indicate text that is characters of input to be typed by users.
- *Note `@kbd': kbd.
-
-`@kbdinputstyle STYLE'
- Specify when `@kbd' should use a font distinct from `@code'.
- *Note `@kbd': kbd.
-
-`@key{KEY-NAME}'
- Indicate a name for a key on a keyboard. *Note `@key': key.
-
-`@kindex ENTRY'
- Add ENTRY to the index of keys. *Note Defining the Entries of an
- Index: Index Entries.
-
-`@L{}'
-`@l{}'
- Generate the uppercase and lowercase Polish suppressed-L letters,
- respectively: L/, l/.
-
-`@lisp'
- Begin an example of Lisp code. Indent text, do not fill, and
- select fixed-width font. Pair with `@end lisp'. *Note `@lisp':
- Lisp Example.
-
-`@lowersections'
- Change subsequent chapters to sections, sections to subsections,
- and so on. *Note `@raisesections' and `@lowersections':
- Raise/lower sections.
-
-`@macro MACRO-NAME {PARAMS}'
- Define a new Texinfo command `@MACRO-NAME{PARAMS}'. Only
- supported by `makeinfo' and `texi2dvi'. *Note Defining Macros::.
-
-`@majorheading TITLE'
- Print a chapter-like heading in the text, but not in the table of
- contents of a printed manual. Generate more vertical whitespace
- before the heading than the `@chapheading' command. In Info, the
- chapter heading line is underlined with asterisks. *Note
- `@majorheading' and `@chapheading': majorheading & chapheading.
-
-`@math{MATHEMATICAL-EXPRESSION}'
- Format a mathematical expression. *Note `@math' - Inserting
- Mathematical Expressions: math.
-
-`@menu'
- Mark the beginning of a menu of nodes in Info. No effect in a
- printed manual. Pair with `@end menu'. *Note Menus::.
-
-`@minus{}'
- Generate a minus sign, `-'. *Note `@minus': minus.
-
-`@multitable COLUMN-WIDTH-SPEC'
- Begin a multi-column table. Pair with `@end multitable'. *Note
- Multitable Column Widths::.
-
-`@need N'
- Start a new page in a printed manual if fewer than N mils
- (thousandths of an inch) remain on the current page. *Note
- `@need': need.
-
-`@node NAME, NEXT, PREVIOUS, UP'
- Define the beginning of a new node in Info, and serve as a locator
- for references for TeX. *Note `@node': node.
-
-`@noindent'
- Prevent text from being indented as if it were a new paragraph.
- *Note `@noindent': noindent.
-
-`@O{}'
-`@o{}'
- Generate the uppercase and lowercase O-with-slash letters,
- respectively: O/, o/.
-
-`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
-`@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
- Specify page footings resp. headings for odd-numbered (right-hand)
- pages. Only allowed inside `@iftex'. *Note How to Make Your Own
- Headings: Custom Headings.
-
-`@OE{}'
-`@oe{}'
- Generate the uppercase and lowercase OE ligatures, respectively:
- OE, oe. *Note Inserting Accents::.
-
-`@page'
- Start a new page in a printed manual. No effect in Info. *Note
- `@page': page.
-
-`@paragraphindent INDENT'
- Indent paragraphs by INDENT number of spaces; delete indentation
- if the value of INDENT is 0; and do not change indentation if
- INDENT is `asis'. *Note Paragraph Indenting: paragraphindent.
-
-`@pindex ENTRY'
- Add ENTRY to the index of programs. *Note Defining the Entries of
- an Index: Index Entries.
-
-`@point{}'
- Indicate the position of point in a buffer to the reader with a
- glyph: `-!-'. *Note Indicating Point in a Buffer: Point Glyph.
-
-`@pounds{}'
- Generate the pounds sterling currency sign. *Note `@pounds{}':
- pounds.
-
-`@print{}'
- Indicate printed output to the reader with a glyph: `-|'. *Note
- Print Glyph::.
-
-`@printindex INDEX-NAME'
- Print an alphabetized two-column index in a printed manual or
- generate an alphabetized menu of index entries for Info. *Note
- Printing Indices & Menus::.
-
-`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
- Make a reference that starts with a lower case `see' in a printed
- manual. Use within parentheses only. Do not follow command with a
- punctuation mark--the Info formatting commands automatically insert
- terminating punctuation as needed. Only the first argument is
- mandatory. *Note `@pxref': pxref.
-
-`@questiondown{}'
- Generate an upside-down question mark. *Note Inserting Accents::.
-
-`@quotation'
- Narrow the margins to indicate text that is quoted from another
- real or imaginary work. Write command on a line of its own. Pair
- with `@end quotation'. *Note `@quotation': quotation.
-
-`@r{TEXT}'
- Print TEXT in roman font. No effect in Info. *Note Fonts::.
-
-`@raisesections'
- Change subsequent sections to chapters, subsections to sections,
- and so on. *Note `@raisesections' and `@lowersections':
- Raise/lower sections.
-
-`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
- Make a reference. In a printed manual, the reference does not
- start with a `See'. Follow command with a punctuation mark. Only
- the first argument is mandatory. *Note `@ref': ref.
-
-`@refill'
- In Info, refill and indent the paragraph after all the other
- processing has been done. No effect on TeX, which always refills.
- This command is no longer needed, since all formatters now
- automatically refill. *Note Refilling Paragraphs::.
-
-`@result{}'
- Indicate the result of an expression to the reader with a special
- glyph: `=>'. *Note `@result': result.
-
-`@ringaccent{C}'
- Generate a ring accent over the next character, as in *o. *Note
- Inserting Accents::.
-
-`@samp{TEXT}'
- Highlight TEXT that is a literal example of a sequence of
- characters. Used for single characters, for statements, and often
- for entire shell commands. *Note `@samp': samp.
-
-`@sc{TEXT}'
- Set TEXT in a printed output in THE SMALL CAPS FONT and set text
- in the Info file in uppercase letters. *Note Smallcaps::.
-
-`@section TITLE'
- Begin a section within a chapter. In a printed manual, the section
- title is numbered and appears in the table of contents. In Info,
- the title is underlined with equal signs. *Note `@section':
- section.
-
-`@set FLAG [STRING]'
- Make FLAG active, causing the Texinfo formatting commands to
- format text between subsequent pairs of `@ifset FLAG' and `@end
- ifset' commands. Optionally, set value of FLAG to STRING. *Note
- `@set' `@clear' `@value': set clear value.
-
-`@setchapternewpage ON-OFF-ODD'
- Specify whether chapters start on new pages, and if so, whether on
- odd-numbered (right-hand) new pages. *Note `@setchapternewpage':
- setchapternewpage.
-
-`@setfilename INFO-FILE-NAME'
- Provide a name to be used by the Info file. This command is
- essential for TeX formatting as well, even though it produces no
- output. *Note `@setfilename': setfilename.
-
-`@settitle TITLE'
- Provide a title for page headers in a printed manual. *Note
- `@settitle': settitle.
-
-`@shortcontents'
- Print a short table of contents. Not relevant to Info, which uses
- menus rather than tables of contents. A synonym for
- `@summarycontents'. *Note Generating a Table of Contents:
- Contents.
-
-`@shorttitlepage{TITLE}'
- Generate a minimal title page. *Note `@titlepage': titlepage.
-
-`@smallbook'
- Cause TeX to produce a printed manual in a 7 by 9.25 inch format
- rather than the regular 8.5 by 11 inch format. *Note Printing
- Small Books: smallbook. Also, see *Note `@smallexample' and
- `@smalllisp': smallexample & smalllisp.
-
-`@smallexample'
- Indent text to indicate an example. Do not fill, select
- fixed-width font. In `@smallbook' format, print text in a smaller
- font than with `@example'. Pair with `@end smallexample'. *Note
- `@smallexample' and `@smalllisp': smallexample & smalllisp.
-
-`@smalllisp'
- Begin an example of Lisp code. Indent text, do not fill, select
- fixed-width font. In `@smallbook' format, print text in a smaller
- font. Pair with `@end smalllisp'. *Note `@smallexample' and
- `@smalllisp': smallexample & smalllisp.
-
-`@sp N'
- Skip N blank lines. *Note `@sp': sp.
-
-`@ss{}'
- Generate the German sharp-S es-zet letter, ss. *Note Inserting
- Accents::.
-
-`@strong TEXT'
- Emphasize TEXT by typesetting it in a *bold* font for the printed
- manual and by surrounding it with asterisks for Info. *Note
- Emphasizing Text: emph & strong.
-
-`@subheading TITLE'
- Print an unnumbered subsection-like heading in the text, but not in
- the table of contents of a printed manual. In Info, the title is
- underlined with hyphens. *Note `@unnumberedsubsec'
- `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
- subheading.
-
-`@subsection TITLE'
- Begin a subsection within a section. In a printed manual, the
- subsection title is numbered and appears in the table of contents.
- In Info, the title is underlined with hyphens. *Note
- `@subsection': subsection.
-
-`@subsubheading TITLE'
- Print an unnumbered subsubsection-like heading in the text, but
- not in the table of contents of a printed manual. In Info, the
- title is underlined with periods. *Note The `subsub' Commands:
- subsubsection.
-
-`@subsubsection TITLE'
- Begin a subsubsection within a subsection. In a printed manual,
- the subsubsection title is numbered and appears in the table of
- contents. In Info, the title is underlined with periods. *Note
- The `subsub' Commands: subsubsection.
-
-`@subtitle TITLE'
- In a printed manual, set a subtitle in a normal sized font flush to
- the right-hand side of the page. Not relevant to Info, which does
- not have title pages. *Note `@title' `@subtitle' and `@author'
- Commands: title subtitle author.
-
-`@summarycontents'
- Print a short table of contents. Not relevant to Info, which uses
- menus rather than tables of contents. A synonym for
- `@shortcontents'. *Note Generating a Table of Contents: Contents.
-
-`@syncodeindex FROM-INDEX INTO-INDEX'
- Merge the index named in the first argument into the index named in
- the second argument, printing the entries from the first index in
- `@code' font. *Note Combining Indices::.
-
-`@synindex FROM-INDEX INTO-INDEX'
- Merge the index named in the first argument into the index named in
- the second argument. Do not change the font of FROM-INDEX
- entries. *Note Combining Indices::.
-
-`@t{TEXT}'
- Print TEXT in a fixed-width, typewriter-like font. No effect in
- Info. *Note Fonts::.
-
-`@tab'
- Separate columns in a multitable. *Note Multitable Rows::.
-
-`@table FORMATTING-COMMAND'
- Begin a two-column table, using `@item' for each entry. Write
- each first column entry on the same line as `@item'. First column
- entries are printed in the font resulting from FORMATTING-COMMAND.
- Pair with `@end table'. *Note Making a Two-column Table:
- Two-column Tables. Also see *Note `@ftable' and `@vtable': ftable
- vtable, and *Note `@itemx': itemx.
-
-`@TeX{}'
- Insert the logo TeX. *Note Inserting TeX and (C): TeX and
- copyright.
-
-`@tex'
- Enter TeX completely. Pair with `@end tex'. *Note Raw Formatter
- Commands::.
-
-`@thischapter'
-`@thischaptername'
-`@thisfile'
-`@thispage'
-`@thistitle'
- Only allowed in a heading or footing. Stands for the number and
- name of the current chapter (in the format `Chapter 1: Title'),
- the chapter name only, the filename, the current page number, and
- the title of the document, respectively. *Note How to Make Your
- Own Headings: Custom Headings.
-
-`@tieaccent{CC}'
- Generate a tie-after accent over the next two characters CC, as in
- `[oo'. *Note Inserting Accents::.
-
-`@tindex ENTRY'
- Add ENTRY to the index of data types. *Note Defining the Entries
- of an Index: Index Entries.
-
-`@title TITLE'
- In a printed manual, set a title flush to the left-hand side of the
- page in a larger than normal font and underline it with a black
- rule. Not relevant to Info, which does not have title pages.
- *Note The `@title' `@subtitle' and `@author' Commands: title
- subtitle author.
-
-`@titlefont{TEXT}'
- In a printed manual, print TEXT in a larger than normal font. Not
- relevant to Info, which does not have title pages. *Note The
- `@titlefont' `@center' and `@sp' Commands: titlefont center sp.
-
-`@titlepage'
- Indicate to Texinfo the beginning of the title page. Write
- command on a line of its own. Pair with `@end titlepage'.
- Nothing between `@titlepage' and `@end titlepage' appears in Info.
- *Note `@titlepage': titlepage.
-
-`@today{}'
- Insert the current date, in `1 Jan 1900' style. *Note How to Make
- Your Own Headings: Custom Headings.
-
-`@top TITLE'
- In a Texinfo file to be formatted with `makeinfo', identify the
- topmost `@node' line in the file, which must be written on the line
- immediately preceding the `@top' command. Used for `makeinfo''s
- node pointer insertion feature. The title is underlined with
- asterisks. Both the `@node' line and the `@top' line normally
- should be enclosed by `@ifinfo' and `@end ifinfo'. In TeX and
- `texinfo-format-buffer', the `@top' command is merely a synonym
- for `@unnumbered'. *Note Creating Pointers with `makeinfo':
- makeinfo Pointer Creation.
-
-`@u{C}'
-`@ubaraccent{C}'
-`@udotaccent{C}'
- Generate a breve, underbar, or underdot accent, respectively, over
- or under the character C, as in (o, o_, o-.. *Note Inserting
- Accents::.
-
-`@unnumbered TITLE'
- In a printed manual, begin a chapter that appears without chapter
- numbers of any kind. The title appears in the table of contents
- of a printed manual. In Info, the title is underlined with
- asterisks. *Note `@unnumbered' and `@appendix': unnumbered &
- appendix.
-
-`@unnumberedsec TITLE'
- In a printed manual, begin a section that appears without section
- numbers of any kind. The title appears in the table of contents
- of a printed manual. In Info, the title is underlined with equal
- signs. *Note Section Commands: unnumberedsec appendixsec heading.
-
-`@unnumberedsubsec TITLE'
- In a printed manual, begin an unnumbered subsection within a
- chapter. The title appears in the table of contents of a printed
- manual. In Info, the title is underlined with hyphens. *Note
- `@unnumberedsubsec' `@appendixsubsec' `@subheading':
- unnumberedsubsec appendixsubsec subheading.
-
-`@unnumberedsubsubsec TITLE'
- In a printed manual, begin an unnumbered subsubsection within a
- chapter. The title appears in the table of contents of a printed
- manual. In Info, the title is underlined with periods. *Note The
- `subsub' Commands: subsubsection.
-
-`@uref{URL[, DISPLAYED-TEXT}'
- Define a cross reference to an external uniform resource locator
- for the World Wide Web. *Note `@url': url.
-
-`@url{URL}'
- Indicate text that is a uniform resource locator for the World Wide
- Web. *Note `@url': url.
-
-`@v{C}'
- Generate check accent over the character C, as in <o. *Note
- Inserting Accents::.
-
-`@value{FLAG}'
- Replace FLAG with the value to which it is set by `@set FLAG'.
- *Note `@set' `@clear' `@value': set clear value.
-
-`@var{METASYNTACTIC-VARIABLE}'
- Highlight a metasyntactic variable, which is something that stands
- for another piece of text. *Note Indicating Metasyntactic
- Variables: var.
-
-`@vindex ENTRY'
- Add ENTRY to the index of variables. *Note Defining the Entries
- of an Index: Index Entries.
-
-`@vskip AMOUNT'
- In a printed manual, insert whitespace so as to push text on the
- remainder of the page towards the bottom of the page. Used in
- formatting the copyright page with the argument `0pt plus 1filll'.
- (Note spelling of `filll'.) `@vskip' may be used only in
- contexts ignored for Info. *Note The Copyright Page and Printed
- Permissions: Copyright & Permissions.
-
-`@vtable FORMATTING-COMMAND'
- Begin a two-column table, using `@item' for each entry.
- Automatically enter each of the items in the first column into the
- index of variables. Pair with `@end vtable'. The same as
- `@table', except for indexing. *Note `@ftable' and `@vtable':
- ftable vtable.
-
-`@w{TEXT}'
- Prevent TEXT from being split across two lines. Do not end a
- paragraph that uses `@w' with an `@refill' command. *Note `@w': w.
-
-`@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
- Make a reference that starts with `See' in a printed manual.
- Follow command with a punctuation mark. Only the first argument is
- mandatory. *Note `@xref': xref.
-
-This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
-1.68 from the input file xemacs-faq.texi.
+This is ../info/xemacs-faq.info, produced by makeinfo version 4.0 from
+xemacs-faq.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Menu:
-Customization--Emacs Lisp and `.emacs':
+Customization---Emacs Lisp and `.emacs':
* Q3.0.1:: What version of Emacs am I running?
* Q3.0.2:: How do I evaluate Elisp expressions?
* Q3.0.3:: `(setq tab-width 6)' behaves oddly.
* Q3.5.1:: How can I bind complex functions (or macros) to keys?
* Q3.5.2:: How can I stop down-arrow from adding empty lines to the bottom of my buffers?
* Q3.5.3:: How do I bind C-. and C-; to scroll one line up and down?
-* Q3.5.4:: Globally binding `Delete'?
+* Q3.5.4:: Globally binding Delete?
* Q3.5.5:: Scrolling one line at a time.
-* Q3.5.6:: How to map `Help' key alone on Sun type4 keyboard?
+* Q3.5.6:: How to map Help key alone on Sun type4 keyboard?
* Q3.5.7:: How can you type in special characters in XEmacs?
* Q3.5.8:: Why does `(global-set-key [delete-forward] 'delete-char)' complain?
* Q3.5.9:: How do I make the Delete key delete forward?
* Q3.7.5:: Why does cut-and-paste not work between XEmacs and a cmdtool?
* Q3.7.6:: How I can set XEmacs up so that it pastes where the text cursor is?
* Q3.7.7:: How do I select a rectangular region?
-* Q3.7.8:: Why does `M-w' take so long?
+* Q3.7.8:: Why does M-w take so long?
The Menubar and Toolbar:
* Q3.8.1:: How do I get rid of the menu (or menubar)?
* Q3.10.1:: How can I turn off or change highlighted selections?
* Q3.10.2:: How do I get that typing on an active region removes it?
* Q3.10.3:: Can I turn off the highlight during isearch?
-* Q3.10.4:: How do I turn off highlighting after `C-x C-p' (mark-page)?
+* Q3.10.4:: How do I turn off highlighting after C-x C-p (mark-page)?
* Q3.10.5:: The region disappears when I hit the end of buffer while scrolling.
\1f
variables.
Instead, use feature-tests, such as `featurep', `boundp', `fboundp',
-or even simple behavioral tests, eg.:
+or even simple behaviroal tests, eg.:
(defvar foo-old-losing-code-p
(condition-case nil (progn (losing-code t) nil)
You have to go to Options->Frame Appearance and unselect
`Frame-Local Font Menu'. If this option is selected, font changes
- are only applied to the *current* frame and do *not* get saved
+ are only applied to the _current_ frame and do _not_ get saved
when you save options.
For XEmacs 19.15 and later:
`-unmapped' on the command line, and setting the `initiallyUnmapped' X
Resource don't seem to help much either...
- Ben Wing <ben@666.com> writes:
+ Ben Wing <ben@xemacs.org> writes:
Ugh, this stuff is such an incredible mess that I've about given up
getting it to work. The principal problem is numerous
This is fine if you only need a few functions within the lambda body.
If you're doing more it's cleaner to define a separate function as in
-question 3.5.3 (*note Q3.5.3::.).
+question 3.5.3 (*note Q3.5.3::).
\1f
File: xemacs-faq.info, Node: Q3.5.2, Next: Q3.5.3, Prev: Q3.5.1, Up: Customization
The key point is that you can only bind simple functions to keys; you
can not bind a key to a function that you're also passing arguments to.
-(*note Q3.5.1::. for a better answer).
+(*note Q3.5.1:: for a better answer).
\1f
File: xemacs-faq.info, Node: Q3.5.4, Next: Q3.5.5, Prev: Q3.5.3, Up: Customization
(global-set-key [(shift help)] 'help-command);; Help
But it doesn't work alone. This is in the file `PROBLEMS' which
-should have come with your XEmacs installation: *Emacs ignores the
-`help' key when running OLWM*.
+should have come with your XEmacs installation: _Emacs ignores the
+`help' key when running OLWM_.
OLWM grabs the `help' key, and retransmits it to the appropriate
client using `XSendEvent'. Allowing Emacs to react to synthetic events
character typed come out in upper case. This will affect all the other
modifier keys like Control and Meta as well.
- Ben Wing <ben@666.com> writes:
+ Ben Wing <ben@xemacs.org> writes:
One thing about the sticky modifiers is that if you move the mouse
out of the frame and back in, it cancels all currently "stuck"
-This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
-1.68 from the input file xemacs-faq.texi.
+This is ../info/xemacs-faq.info, produced by makeinfo version 4.0 from
+xemacs-faq.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Sparcworks, EOS, and WorkShop:
* Q4.4.1:: What is SPARCworks, EOS, and WorkShop
+* Q4.4.2:: How do I start the Sun Workshop support in XEmacs 21?
Energize:
* Q4.5.1:: What is/was Energize?
(setq vm-reply-ignored-addresses
'("wing@nuspl@nvwls.cc.purdue.edu,netcom[0-9]*.netcom.com"
- "wing@netcom.com" "wing@666.com"))
+ "wing@netcom.com" "wing@xemacs.org"))
Note that each string is a regular expression.
directory of the lisp library.
`vm-vars.el' contains, initializes and carefully describes, with
- examples of usage, the plethora of user options that *fully*
+ examples of usage, the plethora of user options that _fully_
control VM's behavior.
Enter vm-vars, `forward-search' for toolbar, find the variables
--------------------------------------------------------------------------------
The Gnus numbering issues are not meant for mere mortals to know
-them. If you feel you *must* enter the muddy waters of Gnus, visit the
+them. If you feel you _must_ enter the muddy waters of Gnus, visit the
excellent FAQ, maintained by Justin Sheehy, at:
`http://www.ccs.neu.edu/software/contrib/gnus/'
Q4.3.3: Why isn't this `movemail' program working?
--------------------------------------------------
- Ben Wing <ben@666.com> writes:
+ Ben Wing <ben@xemacs.org> writes:
It wasn't chown'ed/chmod'd correctly.
Q4.3.4: Movemail is also distributed by Netscape? Can that cause problems?
---------------------------------------------------------------------------
- Steve Baur <steve@altair.xemacs.org> writes:
+ Steve Baur <steve@xemacs.org> writes:
Yes. Always use the movemail installed with your XEmacs. Failure
to do so can result in lost mail.
- Please refer to Jamie Zawinski's <jwz@netscape.com> notes at
+ Please refer to Jamie Zawinski's <jwz@jwz.org> notes at
`http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/movemail.html'.
In particular, this document will show you how to make Netscape use the
version of movemail configured for your system by the person who built
`ftp://ftp.cdrom.com/pub/tex/ctan/support/latex2html/'.
\1f
-File: xemacs-faq.info, Node: Q4.4.1, Next: Q4.5.1, Prev: Q4.3.5, Up: Subsystems
+File: xemacs-faq.info, Node: Q4.4.1, Next: Q4.4.2, Prev: Q4.3.5, Up: Subsystems
4.4: Sparcworks, EOS, and WorkShop
==================================
EOS is being replaced with a new graphical development environment
called Sun WorkShop, which is currently (07/96) in Alpha Test.
For more details, check out
+ `http://www.sun.com/software/Products/Developer-products/programs.html'.
+\1f
+File: xemacs-faq.info, Node: Q4.4.2, Next: Q4.5.1, Prev: Q4.4.1, Up: Subsystems
+Q4.4.2: How do I start the Sun Workshop support in XEmacs 21?
+-------------------------------------------------------------
-
-
-
-
- `http://www.sun.com/software/Products/Developer-products/programs.html'.
+ Add the switch --with-workshop to the configure command when building
+XEmacs and put the following in one of your startup files (e.g.
+site-start.el or .emacs):
+
+ (when (featurep 'tooltalk)
+ (load "tooltalk-macros")
+ (load "tooltalk-util")
+ (load "tooltalk-init"))
+ (when (featurep 'sparcworks)
+ (load "sunpro-init")
+ (load "ring")
+ (load "comint")
+ (load "annotations")
+ (sunpro-startup))
+
+ If you are not using the latest Workshop (5.0) you have to apply the
+following patch:
+
+--- /opt/SUNWspro/lib/eserve.el.ORIG Fri May 14 15:23:26 1999
++++ /opt/SUNWspro/lib/eserve.el Fri May 14 15:24:54 1999
+@@ -42,7 +42,7 @@
+ (defvar running-xemacs nil "t if we're running XEmacs")
+ (defvar running-emacs nil "t if we're running GNU Emacs 19")
+
+-(if (string-match "^\\(19\\|20\\)\..*\\(XEmacs\\|Lucid\\)" emacs-version)
++(if (string-match "\\(XEmacs\\|Lucid\\)" emacs-version)
+ (setq running-xemacs t)
+ (setq running-emacs t))
\1f
-File: xemacs-faq.info, Node: Q4.5.1, Next: Q4.6.1, Prev: Q4.4.1, Up: Subsystems
+File: xemacs-faq.info, Node: Q4.5.1, Next: Q4.6.1, Prev: Q4.4.2, Up: Subsystems
4.5: Energize
=============
Can I "teach" emacs what words are MatLab commands, comments, etc. ?
Ulrich Elsner <elsner@mathematik.tu-chemnitz.de> writes:
- One way to do this (and much more) is by using the
- matlab mode
+ One way to do this (and much more) is by using the matlab mode
(ftp://ftp.mathworks.com/pub/contrib/v5/tools/matlab.el).
Instructions on how to install this mode are included in this file.
* Q5.3.1:: How do you make XEmacs indent CL if-clauses correctly?
* Q5.3.2:: Fontifying hangs when editing a postscript file.
* Q5.3.3:: How can I print WYSIWYG a font-locked buffer?
-* Q5.3.4:: Getting `M-x lpr' to work with postscript printer.
+* Q5.3.4:: Getting M-x lpr to work with postscript printer.
* Q5.3.5:: How do I specify the paths that XEmacs uses for finding files?
* Q5.3.6:: [This question intentionally left blank]
* Q5.3.7:: Can I have the end of the buffer delimited in some way?
You can customize filling and adaptive filling with Customize.
Select from the `Options' menu
-`Customize->Emacs->->Editing->Fill->Fill...' or type `M-x customize
+`Customize->Emacs->->Editing->Fill->Fill...' or type `M-x customize
<RET> fill <RET>'.
Note that well-behaving text-lookalike modes will run
(setq auto-show-mode nil)
(setq-default auto-show-mode nil)
-\1f
-File: xemacs-faq.info, Node: Q5.0.17, Next: Q5.0.18, Prev: Q5.0.16, Up: Miscellaneous
-
-Q5.0.17: How can I get two instances of info?
----------------------------------------------
-
- You can't. The `info' package does not provide for multiple info
-buffers.
-
-\1f
-File: xemacs-faq.info, Node: Q5.0.18, Next: Q5.0.19, Prev: Q5.0.17, Up: Miscellaneous
-
-Q5.0.18: I upgraded to XEmacs 19.14 and gnuserv stopped working.
-----------------------------------------------------------------
-
- Mark Daku <daku@nortel.ca> writes:
-
- It turns out I was using an older version of gnuserv. The
- installation didn't put the binary into the public bin directory.
- It put it in `lib/xemacs-19.14/hppa1.1-hp-hpux9.05/gnuserv'.
- Shouldn't it have been put in `bin/hppa1.1-hp-hpux9.0'?
-
-\1f
-File: xemacs-faq.info, Node: Q5.0.19, Next: Q5.0.20, Prev: Q5.0.18, Up: Miscellaneous
-
-Q5.0.19: Is there something better than LaTeX mode?
----------------------------------------------------
-
- David Kastrup <dak@fsnif.neuroinformatik.ruhr-uni-bochum.de> writes:
-
- The standard TeX modes leave much to be desired, and are somewhat
- leniently maintained. Serious TeX users use AUC TeX (*note
- Q4.7.1::.).
-
-This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
-1.68 from the input file xemacs-faq.texi.
+This is ../info/xemacs-faq.info, produced by makeinfo version 4.0 from
+xemacs-faq.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
END-INFO-DIR-ENTRY
\1f
+File: xemacs-faq.info, Node: Q5.0.17, Next: Q5.0.18, Prev: Q5.0.16, Up: Miscellaneous
+
+Q5.0.17: How can I get two instances of info?
+---------------------------------------------
+
+ You can't. The `info' package does not provide for multiple info
+buffers.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.18, Next: Q5.0.19, Prev: Q5.0.17, Up: Miscellaneous
+
+Q5.0.18: I upgraded to XEmacs 19.14 and gnuserv stopped working.
+----------------------------------------------------------------
+
+ Mark Daku <daku@nortel.ca> writes:
+
+ It turns out I was using an older version of gnuserv. The
+ installation didn't put the binary into the public bin directory.
+ It put it in `lib/xemacs-19.14/hppa1.1-hp-hpux9.05/gnuserv'.
+ Shouldn't it have been put in `bin/hppa1.1-hp-hpux9.0'?
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.19, Next: Q5.0.20, Prev: Q5.0.18, Up: Miscellaneous
+
+Q5.0.19: Is there something better than LaTeX mode?
+---------------------------------------------------
+
+ David Kastrup <dak@fsnif.neuroinformatik.ruhr-uni-bochum.de> writes:
+
+ The standard TeX modes leave much to be desired, and are somewhat
+ leniently maintained. Serious TeX users use AUC TeX (*note
+ Q4.7.1::).
+
+\1f
File: xemacs-faq.info, Node: Q5.0.20, Next: Q5.1.1, Prev: Q5.0.19, Up: Miscellaneous
Q5.0.20: Is there a way to start a new XEmacs if there's no gnuserv running, and otherwise use gnuclient?
using the more readable `incf' and `push' forms in your compiled
code.
- *Interpreted* code, on the other hand, must expand these macros
+ _Interpreted_ code, on the other hand, must expand these macros
every time they are executed. For this reason it is strongly
recommended that code making heavy use of macros be compiled. (The
features labelled "Special Form" instead of "Function" in this
an easy way to find out where it spends time?
- zHrvoje Niksic <hniksic@srce.hr> writes:
+ zHrvoje Niksic <hniksic@xemacs.org> writes:
Under XEmacs 20.4 and later you can use `M-x
profile-key-sequence', press a key (say <RET> in the Gnus Group
buffer), and get the results using `M-x profile-results'. It
1. Emacs Info scans `Info-directory-list' from right-to-left
while XEmacs Info reads it from left-to-right, so append to
- the *correct* end of the list.
+ the _correct_ end of the list.
2. Use `Info-default-directory-list' to initialize
- `Info-directory-list' *if* it is available at startup, but not
+ `Info-directory-list' _if_ it is available at startup, but not
all Emacsen define it.
3. Emacs Info looks for a standard `dir' file in each of the
XEmacs 19.16 was the last 19 release, basically consisting of
19.15 plus the collected bugfixes.
- 3. As of December 1996, Steve Baur <steve@altair.xemacs.org> has
- become the lead maintainer of XEmacs.
+ 3. As of December 1996, Steve Baur <steve@xemacs.org> has become the
+ lead maintainer of XEmacs.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
comment lines. Optionally, new comment delimiters are inserted at the
end of the first line and the beginning of the second, so that each line
is a separate comment. The variable `comment-multi-line' controls the
-choice (*note Comments::.).
+choice (*note Comments::).
Auto Fill mode does not refill entire paragraphs. It can break
lines but cannot merge lines. Editing in the middle of a paragraph can
the region into paragraphs and fills each of them.
`Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
-paragraph boundaries (*note Paragraphs::.). For more control, you can
+paragraph boundaries (*note Paragraphs::). For more control, you can
use `M-x fill-region-as-paragraph', which refills everything between
point and mark. This command recognizes only blank lines as paragraph
separators.
Emacs has many commands designed to understand the syntax of
programming languages such as Lisp and C. These commands can:
- * Move over or kill balanced expressions or "sexps" (*note Lists::.).
+ * Move over or kill balanced expressions or "sexps" (*note Lists::).
* Move over or mark top-level balanced expressions ("defuns", in
Lisp; functions, in C).
- * Show how parentheses balance (*note Matching::.).
+ * Show how parentheses balance (*note Matching::).
- * Insert, kill, or align comments (*note Comments::.).
+ * Insert, kill, or align comments (*note Comments::).
* Follow the usual indentation conventions of the language (*note
- Grinding::.).
+ Grinding::).
The commands available for words, sentences, and paragraphs are
useful in editing code even though their canonical application is for
editing human language text. Most symbols contain words (*note
-Words::.); sentences can be found in strings and comments (*note
-Sentences::.). Paragraphs per se are not present in code, but the
+Words::); sentences can be found in strings and comments (*note
+Sentences::). Paragraphs per se are not present in code, but the
paragraph commands are useful anyway, because Lisp mode and C mode
-define paragraphs to begin and end at blank lines (*note
-Paragraphs::.). Judicious use of blank lines to make the program
-clearer also provides interesting chunks of text for the paragraph
-commands to work on.
+define paragraphs to begin and end at blank lines (*note Paragraphs::).
+Judicious use of blank lines to make the program clearer also provides
+interesting chunks of text for the paragraph commands to work on.
The selective display feature is useful for looking at the overall
-structure of a function (*note Selective Display::.). This feature
+structure of a function (*note Selective Display::). This feature
causes only the lines that are indented less than a specified amount to
appear on the screen.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
names and positions of the functions (or other named subunits) in each
file. Grouping the related files makes it possible to search or replace
through all the files with one command. Recording the function names
-and positions makes possible the `M-.' command which finds the
+and positions makes possible the `M-.' command which finds the
definition of a function by looking up which of the files it is in.
Tags tables are stored in files called "tags table files". The
* Tag Syntax:: Tag syntax for various types of code and text files.
* Create Tags Table:: Creating a tags table with `etags'.
+* Etags Regexps:: Create arbitrary tags using regular expressions.
* Select Tags Table:: How to visit a tags table.
* Find Tag:: Commands to find the definition of a specific tag.
* Tags Search:: Using a tags table for searching and replacing.
* List Tags:: Listing and finding tags defined in a file.
\1f
-File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Up: Tags
+File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Prev: Tags, Up: Tags
Source File Tag Syntax
----------------------
Here is how tag syntax is defined for the most popular languages:
* In C code, any C function or typedef is a tag, and so are
- definitions of `struct', `union' and `enum'. `#define' macro
- definitions and `enum' constants are also tags, unless you specify
- `--no-defines' when making the tags table. Similarly, global
- variables are tags, unless you specify `--no-globals'. Use of
- `--no-globals' and `--no-defines' can make the tags table file
- much smaller.
+ definitions of `struct', `union' and `enum'. You can tag function
+ declarations and external variables in addition to function
+ definitions by giving the `--declarations' option to `etags'.
+ `#define' macro definitions and `enum' constants are also tags,
+ unless you specify `--no-defines' when making the tags table.
+ Similarly, global variables are tags, unless you specify
+ `--no-globals'. Use of `--no-globals' and `--no-defines' can make
+ the tags table file much smaller.
* In C++ code, in addition to all the tag constructs of C code,
member functions are also recognized, and optionally member
variables if you use the `--members' option. Tags for variables
and functions in classes are named `CLASS::VARIABLE' and
- `CLASS::FUNCTION'.
+ `CLASS::FUNCTION'. `operator' functions tags are named, for
+ example `operator+'.
* In Java code, tags include all the constructs recognized in C++,
- plus the `extends' and `implements' constructs. Tags for variables
- and functions in classes are named `CLASS.VARIABLE' and
- `CLASS.FUNCTION'.
+ plus the `interface', `extends' and `implements' constructs. Tags
+ for variables and functions in classes are named `CLASS.VARIABLE'
+ and `CLASS.FUNCTION'.
* In LaTeX text, the argument of any of the commands `\chapter',
`\section', `\subsection', `\subsubsection', `\eqno', `\label',
Other commands can make tags as well, if you specify them in the
environment variable `TEXTAGS' before invoking `etags'. The value
of this environment variable should be a colon-separated list of
- commands names. For example,
+ command names. For example,
TEXTAGS="def:newcommand:newenvironment"
export TEXTAGS
Several other languages are also supported:
+ * In Ada code, functions, procedures, packages, tasks, and types are
+ tags. Use the `--packages-only' option to create tags for packages
+ only.
+
* In assembler code, labels appearing at the beginning of a line,
followed by a colon, are tags.
nonterminal it constructs. The portions of the file that contain
C code are parsed as C code.
- * In Cobol code, paragraphs names are the tags, i.e. any word
- starting in column 8 and followed by a full stop.
+ * In Cobol code, tags are paragraph names; that is, any word
+ starting in column 8 and followed by a period.
* In Erlang code, the tags are the functions, records, and macros
defined in the file.
- * In Fortran code, functions and subroutines are tags.
+ * In Fortran code, functions, subroutines and blockdata are tags.
* In Objective C code, tags include Objective C definitions for
- classes, class categories, methods and protocols.
+ classes, class categories, methods, and protocols.
* In Pascal code, the tags are the functions and procedures defined
in the file.
- * In Perl code, the tags are the procedures defined by the `sub'
- keyword.
+ * In Perl code, the tags are the procedures defined by the `sub',
+ `my' and `local' keywords. Use `--globals' if you want to tag
+ global variables.
* In Postscript code, the tags are the functions.
* In Prolog code, a tag name appears at the left margin.
- You can also generate tags based on regexp matching (*note Create
-Tags Table::.) to handle other formats and languages.
+ * In Python code, `def' or `class' at the beginning of a line
+ generate a tag.
+
+ You can also generate tags based on regexp matching (*note Etags
+Regexps::) to handle other formats and languages.
\1f
-File: xemacs.info, Node: Create Tags Table, Next: Select Tags Table, Prev: Tag Syntax, Up: Tags
+File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags
Creating Tags Tables
--------------------
etags INPUTFILES...
The `etags' program reads the specified files, and writes a tags table
-named `TAGS' in the current working directory. `etags' recognizes the
-language used in an input file based on its file name and contents.
-You can specify the language with the `--language=NAME' option,
-described below.
+named `TAGS' in the current working directory. You can intermix
+compressed and plain text source file names. `etags' knows about the
+most common compression formats, and does the right thing. So you can
+compress all your source files and have `etags' look for compressed
+versions of its file name arguments, if it does not find uncompressed
+versions. Under MS-DOS, `etags' also looks for file names like
+`mycode.cgz' if it is given `mycode.c' on the command line and
+`mycode.c' does not exist.
+
+ `etags' recognizes the language used in an input file based on its
+file name and contents. You can specify the language with the
+`--language=NAME' option, described below.
If the tags table data become outdated due to changes in the files
described in the table, the way to update the tags table is the same
tags file will contain absolute file names. This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place. Absolute file names start with
-`/', or with `DEVICE:/' on MS-DOS and Windows.
+`/', or with `DEVICE:/' on MS-DOS and MS-Windows.
When you want to make a tags table from a great number of files, you
may have problems listing them on the command line, because some systems
`etags' to resume guessing the language from the file names and file
contents. Specify `--language=none' to turn off language-specific
processing entirely; then `etags' recognizes tags by regexp matching
-alone. `etags --help' prints the list of the languages `etags' knows,
-and the file name rules for guessing the language.
+alone (*note Etags Regexps::).
+
+ `etags --help' prints the list of the languages `etags' knows, and
+the file name rules for guessing the language. It also prints a list of
+all the available `etags' options, together with a short explanation.
+
+\1f
+File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags
+
+Etags Regexps
+-------------
The `--regex' option provides a general way of recognizing tags
based on regexp matching. You can freely intermix it with file names.
You should not match more characters with TAGREGEXP than that needed
to recognize what you want to tag. If the match is such that more
-characters than needed are unavoidably matched by TAGREGEXP, you may
-find useful to add a NAMEREGEXP, in order to narrow the tag scope. You
-can find some examples below.
+characters than needed are unavoidably matched by TAGREGEXP (as will
+usually be the case), you should add a NAMEREGEXP, to pick out just the
+tag. This will enable Emacs to find tags more accurately and to do
+completion on tag names more reliably. You can find some examples
+below.
+
+ The option `--ignore-case-regex' (or `-c') is like `--regex', except
+that the regular expression provided will be matched without regard to
+case, which is appropriate for various programming languages.
The `-R' option deletes all the regexps defined with `--regex'
options. It applies to the file names following it, as you can see
additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no
regexp matching, to recognize tags in `los.er'.
+ A regular expression can be bound to a given language, by prepending
+it with `{lang}'. When you do this, `etags' will use the regular
+expression only for files of that language. `etags --help' prints the
+list of languages recognised by `etags'. The following example tags
+the `DEFVAR' macros in the Emacs source files. `etags' applies this
+regular expression to C files only:
+
+ --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+
+This feature is particularly useful when storing a list of regular
+expressions in a file. The following option syntax instructs `etags'
+to read two files of regular expressions. The regular expressions
+contained in the second file are matched without regard to case.
+
+ --regex=@first-file --ignore-case-regex=@second-file
+
+A regex file contains one regular expressions per line. Empty lines,
+and lines beginning with space or tab are ignored. When the first
+character in a line is `@', `etags' assumes that the rest of the line
+is the name of a file of regular expressions. This means that such
+files can be nested. All the other lines are taken to be regular
+expressions. For example, one can create a file called `emacs.tags'
+with the following contents (the first line in the file is a comment):
+
+ -- This is for GNU Emacs source files
+ {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
+
+and then use it like this:
+
+ etags --regex=@emacs.tags *.[ch] */*.[ch]
+
Here are some more examples. The regexps are quoted to protect them
from shell interpretation.
-Tag the `DEFVAR' macros in the emacs source files:
+ * Tag Octave files:
- --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+ etags --language=none \
+ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+ --regex='/###key \(.*\)/\1/' \
+ --regex='/[ \t]*global[ \t].*/' \
+ *.m
-Tag VHDL files (this example is a single long line, broken here for
-formatting reasons):
+ Note that tags are not generated for scripts so that you have to
+ add a line by yourself of the form `###key <script-name>' if you
+ want to jump to it.
- --language=none
- --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
- --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
- \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+ * Tag Tcl files:
-Tag TCL files (this last example shows the usage of a NAMEREGEXP):
+ etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
- --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
+ * Tag VHDL files:
- For a list of the other available `etags' options, execute `etags
---help'.
+ --language=none \
+ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
\1f
-File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Create Tags Table, Up: Tags
+File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags
Selecting a Tags Table
----------------------
The commands in this section visit and search all the files listed
in the selected tags table, one by one. For these commands, the tags
table serves only to specify a sequence of files to search. A related
-command is `M-x grep' (*note Compilation::.).
+command is `M-x grep' (*note Compilation::).
`M-x tags-search <RET> REGEXP <RET>'
Search for REGEXP through the files in the selected tags table.
comments start with `!' and can follow other text. Because only some
Fortran compilers accept this syntax, Fortran mode will not insert such
comments unless you have specified to do so in advance by setting the
-variable `comment-start' to `"!"' (*note Variables::.).
+variable `comment-start' to `"!"' (*note Variables::).
`M-;'
Align comment or insert new comment (`fortran-comment-indent').
Fortran mode provides many built-in abbrevs for common keywords and
declarations. These are the same sort of abbrevs that you can define
-yourself. To use them, you must turn on Abbrev mode. *note Abbrevs::..
+yourself. To use them, you must turn on Abbrev mode. *note Abbrevs::.
The built-in abbrevs are unusual in one way: they all start with a
semicolon. You cannot normally use semicolon in an abbrev, but Fortran
default. The default is taken from the variable `compile-command'; if
the appropriate compilation command for a file is something other than
`make -k', it can be useful to have the file specify a local value for
-`compile-command' (*note File Variables::.).
+`compile-command' (*note File Variables::).
When you start a compilation, the buffer `*compilation*' is
displayed in another window but not selected. Its mode line displays
Inferior Lisp mode
The mode for an interactive session with an inferior Lisp process.
This mode combines the special features of Lisp mode and Shell mode
- (*note Shell Mode::.).
+ (*note Shell Mode::).
Scheme mode
Like Lisp mode but for Scheme programs.
Lisp code for Emacs editing commands is stored in files whose names
conventionally end in `.el'. This ending tells Emacs to edit them in
-Emacs-Lisp mode (*note Lisp Modes::.).
+Emacs-Lisp mode (*note Lisp Modes::).
* Menu:
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
examine the buffer that was being edited at the time of the error, and
you can switch buffers, visit files, and perform any other editing
operations. However, the debugger is a recursive editing level (*note
-Recursive Edit::.); it is a good idea to return to the backtrace buffer
+Recursive Edit::); it is a good idea to return to the backtrace buffer
and explictly exit the debugger when you don't want to use it any more.
Exiting the debugger kills the backtrace buffer.
Lisp comes from text in the buffer. To give input to Lisp, go to the
end of the buffer and type the input, terminated by <RET>. The
`*lisp*' buffer is in Inferior Lisp mode, which has all the special
-characteristics of Lisp mode and Shell mode (*note Shell Mode::.).
+characteristics of Lisp mode and Shell mode (*note Shell Mode::).
Use Lisp mode to run the source files of programs in external Lisps.
You can select this mode with `M-x lisp-mode'. It is used automatically
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
of screen model does not affect beginnings of lines.
Insertion of text is adapted to the quarter-plane screen model
-through the use of Overwrite mode (*note Minor Modes::.).
+through the use of Overwrite mode (*note Minor Modes::).
Self-inserting characters replace existing text, column by column,
rather than pushing existing text to the right. <RET> runs
`picture-newline', which just moves to the beginning of the following
To actually delete parts of the picture, use `C-w', or with `C-c
C-d' (which is defined as `delete-char', as `C-d' is in other modes),
or with one of the picture rectangle commands (*note Rectangles in
-Picture::.).
+Picture::).
\1f
File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture
Picture mode defines commands for working on rectangular pieces of
the text in ways that fit with the quarter-plane model. The standard
-rectangle commands may also be useful (*note Rectangles::.).
+rectangle commands may also be useful (*note Rectangles::).
`C-c C-k'
Clear out the region-rectangle (`picture-clear-rectangle'). With
`o' (`calendar-other-month') prompts for a month and year, then
centers the three-month calendar around that month.
- You can return to today's date with `.' (`calendar-goto-today').
+ You can return to today's date with `.' (`calendar-goto-today').
\1f
File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary
-----------------------
The concept of the mark applies to the calendar just as to any other
-buffer, but it marks a *date*, not a *position* in the buffer. The
+buffer, but it marks a _date_, not a _position_ in the buffer. The
region consists of the days between the mark and point (including the
starting and stopping dates).
To determine the number of days in the region, type `M-='
(`calendar-count-days-region'). The numbers of days printed is
-*inclusive*; that is, it includes the days specified by mark and point.
+_inclusive_; that is, it includes the days specified by mark and point.
The main use of the mark in the calendar is to remember dates that
you may want to go back to. To make this feature more useful, the mark
-ring (*note Mark Ring::.) operates exactly as in other buffers: Emacs
+ring (*note Mark Ring::) operates exactly as in other buffers: Emacs
remembers 16 previous locations of the mark. To return to a marked
date, type `C-u C-SPC' (or `C-u C-@'); this is the command
`calendar-set-mark' given a numeric argument. It moves point to where
display with multiple faces is not available). The command applies both
to the currently visible months and to other months that subsequently
become visible by scrolling. To turn marking off and erase the current
-marks, type `u', which also erases any diary marks (*note Diary::.).
+marks, type `u', which also erases any diary marks (*note Diary::).
To get even more detailed information, use the `a' command, which
displays a separate buffer containing a list of all holidays in the
categories of holidays. You can use this command even if you don't have
a calendar window.
- The dates used by Emacs for holidays are based on *current
-practice*, not historical fact. Historically, for instance, the start
+ The dates used by Emacs for holidays are based on _current
+practice_, not historical fact. Historically, for instance, the start
of daylight savings time and even its existence have varied from year to
year, but present United States law mandates that daylight savings time
begins on the first Sunday in April. When the daylight savings rules
`C-u M-x sunrise-sunset'
Display times of sunrise and sunset for a specified date.
- Within the calendar, to display the *local times* of sunrise and
+ Within the calendar, to display the _local times_ of sunrise and
sunset in the echo area, move point to the date you want, and type `S'.
Alternatively, click `Button2' on the date, then choose
`Sunrise/Sunset' from the menu that appears. The command `M-x
between your local standard time and Coordinated Universal Time
(Greenwich time). The values of `calendar-standard-time-zone-name' and
`calendar-daylight-time-zone-name' are the abbreviations used in your
-time zone. Emacs displays the times of sunrise and sunset *corrected
-for daylight savings time*. *Note Daylight Savings::, for how daylight
+time zone. Emacs displays the times of sunrise and sunset _corrected
+for daylight savings time_. *Note Daylight Savings::, for how daylight
savings time is determined.
As a user, you might find it convenient to set the calendar location
Conversion To and From Other Calendars
--------------------------------------
- The Emacs calendar displayed is *always* the Gregorian calendar,
+ The Emacs calendar displayed is _always_ the Gregorian calendar,
sometimes called the "new style" calendar, which is used in most of the
world today. However, this calendar did not exist before the sixteenth
century and was not widely used before the eighteenth century; it did
Astronomers use a simple counting of days elapsed since noon, Monday,
January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
-is called the *Julian day number* or the *Astronomical day number*.
+is called the _Julian day number_ or the _Astronomical day number_.
The Hebrew calendar is used by tradition in the Jewish religion. The
Emacs calendar program uses the Hebrew calendar to determine the dates
abandoned this calendar at the end of 1805.
The Maya of Central America used three separate, overlapping calendar
-systems, the *long count*, the *tzolkin*, and the *haab*. Emacs knows
+systems, the _long count_, the _tzolkin_, and the _haab_. Emacs knows
about all three of these calendars. Experts dispute the exact
correlation between the Mayan calendar and our calendar; Emacs uses the
Goodman-Martinez-Thompson correlation in its calculations.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
These commands ask you for a date on the other calendar, move point
to the Gregorian calendar date equivalent to that date, and display the
other calendar's date in the echo area. Emacs uses strict completion
-(*note Completion::.) whenever it asks you to type a month name, so you
+(*note Completion::) whenever it asks you to type a month name, so you
don't have to worry about the spelling of Hebrew, Islamic, or French
names.
Similarly, type `g m n h' to go to the next occurrence of a haab date.
The Maya also used the combination of the tzolkin date and the haab
-date. This combination is a cycle of about 52 years called a *calendar
-round*. If you type `g m p c', Emacs asks you for both a haab and a
+date. This combination is a cycle of about 52 years called a _calendar
+round_. If you type `g m p c', Emacs asks you for both a haab and a
tzolkin date and then moves point to the previous occurrence of that
combination. Use `g m n c' to move point to the next occurrence of a
combination. These commands signal an error if the haab/tzolkin date
combination you have typed is impossible.
- Emacs uses strict completion (*note Completion::.) whenever it asks
+ Emacs uses strict completion (*note Completion::) whenever it asks
you to type a Mayan name, so you don't have to worry about spelling.
\1f
Although you probably will start by creating a diary manually, Emacs
provides a number of commands to let you view, add, and change diary
entries. You can also share diary entries with other users (*note
-Included Diary Files::.).
+Included Diary Files::).
* Menu:
multiple faces is not available). The command applies both to the
currently visible months and to other months that subsequently become
visible by scrolling. To turn marking off and erase the current marks,
-type `u', which also turns off holiday marks (*note Holidays::.).
+type `u', which also turns off holiday marks (*note Holidays::).
To see the full diary file, rather than just some of the entries, use
the `s' command.
The diary buffer as you see it is an illusion, so simply printing the
buffer does not print what you see on your screen. There is a special
-command to print hard copy of the diary buffer *as it appears*; this
+command to print hard copy of the diary buffer _as it appears_; this
command is `M-x print-diary-entries'. It sends the data directly to
-the printer. You can customize it like `lpr-region' (*note
-Hardcopy::.).
+the printer. You can customize it like `lpr-region' (*note Hardcopy::).
The command `M-x diary' displays the diary entries for the current
date, independently of the calendar display, and optionally for the next
few days as well; the variable `number-of-diary-entries' specifies how
-many days to include (*note Customization::.).
+many days to include (*note Customization::).
If you put `(diary)' in your `.emacs' file, this automatically
displays a window with the day's diary entries, when you enter Emacs.
entries.
You can edit the diary entries as they appear in the window, but it
-is important to remember that the buffer displayed contains the *entire*
+is important to remember that the buffer displayed contains the _entire_
diary file, with portions of it concealed from view. This means, for
instance, that the `C-f' (`forward-char') command can put point at what
appears to be the end of the line, but what is in reality the middle of
some concealed line.
- *Be careful when editing the diary entries!* Inserting additional
+ _Be careful when editing the diary entries!_ Inserting additional
lines or adding/deleting characters in the middle of a visible line
cannot cause problems, but editing at the end of a line may not do what
you expect. Deleting a line may delete other invisible entries that
If you prefer the European style of writing dates--in which the day
comes before the month--type `M-x european-calendar' while in the
-calendar, or set the variable `european-calendar-style' to `t' *before*
+calendar, or set the variable `european-calendar-style' to `t' _before_
using any calendar or diary command. This mode interprets all dates in
the diary in the European manner, and also uses European style for
displaying diary dates. (Note that there is no comma after the
nonmarking entry, give a numeric argument to the command. For example,
`C-u i a' makes a nonmarking anniversary diary entry.
- Marking sexp diary entries in the calendar is *extremely*
+ Marking sexp diary entries in the calendar is _extremely_
time-consuming, since every date visible in the calendar window must be
individually checked. So it's a good idea to make sexp diary entries
nonmarking (with `&') when possible.
based on any Emacs Lisp expression. You can use the library of built-in
functions or you can write your own functions. The built-in functions
include the ones shown in this section, plus a few others (*note Sexp
-Diary Entries::.).
+Diary Entries::).
The generality of sexps lets you specify any diary entry that you can
describe algorithmically. Suppose you get paid on the 21st of the month
on the variable `date'; this variable is a list (MONTH DAY YEAR) that
gives the Gregorian date for which the diary entries are being found.
If the value of the sexp is `t', the entry applies to that date. If
-the sexp evaluates to `nil', the entry does *not* apply to that date.
+the sexp evaluates to `nil', the entry does _not_ apply to that date.
\1f
File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary
You can set the variable `mark-diary-entries-in-calendar' to `t' in
order to mark any dates with diary entries. This takes effect whenever
the calendar window contents are recomputed. There are two ways of
-marking these dates: by changing the face (*note Faces::.), if the
+marking these dates: by changing the face (*note Faces::), if the
display supports that, or by placing a plus sign (`+') beside the date
otherwise.
terminal.
A similar normal hook, `today-invisible-calendar-hook' is run if the
-current date is *not* visible in the window.
+current date is _not_ visible in the window.
\1f
File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
the standard American nor European styles suits your needs, by setting
the variable `diary-date-forms'. This variable is a list of patterns
for recognizing a date. Each date pattern is a list whose elements may
-be regular expressions (*note Regexps::.) or the symbols `month',
-`day', `year', `monthname', and `dayname'. All these elements serve as
+be regular expressions (*note Regexps::) or the symbols `month', `day',
+`year', `monthname', and `dayname'. All these elements serve as
patterns that match certain kinds of text in the diary file. In order
for the date pattern, as a whole, to match, all of its elements must
match consecutively.
(lispref)Syntax Tables.), but with the `*' changed so that it is a word
constituent.
- The date patterns in the list must be *mutually exclusive* and must
+ The date patterns in the list must be _mutually exclusive_ and must
not match any portion of the diary entry itself, just the date and one
character of whitespace. If, to be mutually exclusive, the pattern
must match a portion of the diary entry text--beyond the whitespace
-that ends the date--then the first element of the date pattern *must*
+that ends the date--then the first element of the date pattern _must_
be `backup'. This causes the date recognizer to back up to the
beginning of the current word of the diary entry, after finishing the
match. Even if you use `backup', the date pattern must absolutely not
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
depend on the variable `date'; this variable is a list (MONTH DAY YEAR)
that gives the Gregorian date for which the diary entries are being
found. If the value of the expression is `t', the entry applies to
-that date. If the expression evaluates to `nil', the entry does *not*
+that date. If the expression evaluates to `nil', the entry does _not_
apply to that date.
The following sexp diary entries take advantage of the ability (in
scripture reading.
`%%(diary-sabbath-candles)'
- Make a Friday diary entry that tells the *local time* of Sabbath
+ Make a Friday diary entry that tells the _local time_ of Sabbath
candle lighting.
`%%(diary-omer)'
`%%(diary-yahrzeit MONTH DAY YEAR) NAME'
Make a diary entry marking the anniversary of a date of death.
- The date is the *Gregorian* (civil) date of death. The diary
+ The date is the _Gregorian_ (civil) date of death. The diary
entry appears on the proper Hebrew calendar anniversary and on the
day before. (In the European style, the order of the parameters
is changed to DAY, MONTH, YEAR.)
by XEmacs directly to the subshell, as "terminal input." Any "echo" of
your input is the responsibility of the subshell. (The exception is
the terminal escape character, which by default is `C-c'. *note Term
-Mode::..) Any "terminal output" from the subshell goes into the buffer,
+Mode::.) Any "terminal output" from the subshell goes into the buffer,
advancing point.
Some programs (such as XEmacs itself) need to control the appearance
values, and thereby alter and control the behavior of certain Emacs
commands. These variables are called "options". Most options are
documented in this manual and appear in the Variable Index (*note
-Variable Index::.).
+Variable Index::).
One example of a variable which is an option is `fill-column', which
specifies the position of the right margin (as a number of characters
-from the left margin) to be used by the fill commands (*note
-Filling::.).
+from the left margin) to be used by the fill commands (*note Filling::).
* Menu:
This says that the buffer displays the contents of the `Emacs' group.
The other groups are listed because they are its contents. But they
-are listed differently, without indentation and dashes, because *their*
+are listed differently, without indentation and dashes, because _their_
contents are not included. Each group has a single-line documentation
string; the `Emacs' group also has a `[State]' line.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
value in the usual ways.
Setting, saving and resetting a face work like the same operations
-for options (*note Changing an Option::.).
+for options (*note Changing an Option::).
A face can specify different appearances for different types of
display. For example, a face can make text red on a color display, but
customize-apropos'. You specify a regular expression as argument; then
all options, faces and groups whose names match this regular expression
are set up in the customization buffer. If you specify an empty regular
-expression, this includes *all* groups, options and faces in the
+expression, this includes _all_ groups, options and faces in the
customization buffer (but that takes a long time).
If you change option values and then decide the change was a mistake,
a matter of personal taste, not a matter of the contents of particular
files. If you want to use Auto Fill, set up major mode hooks with your
`.emacs' file to turn it on (when appropriate) for you alone (*note
-Init File::.). Don't try to use a local variable list that would
-impose your taste on everyone working with the file.
+Init File::). Don't try to use a local variable list that would impose
+your taste on everyone working with the file.
XEmacs allows you to specify local variables in the first line of a
file, in addition to specifying them in the `Local Variables' section
reads a name as an argument using the minibuffer and defines that name
to execute the macro. The macro name is a Lisp symbol, and defining it
in this way makes it a valid command name for calling with `M-x' or for
-binding a key to with `global-set-key' (*note Keymaps::.). If you
+binding a key to with `global-set-key' (*note Keymaps::). If you
specify a name that has a prior definition other than another keyboard
macro, Emacs prints an error message and nothing is changed.
same macro with the same definition it has now. You need not
understand Lisp code to do this, because `insert-kbd-macro' writes the
Lisp code for you. Then save the file. You can load the file with
-`load-file' (*note Lisp Libraries::.). If the file you save in is your
-initialization file `~/.emacs' (*note Init File::.), then the macro
-will be defined each time you run Emacs.
+`load-file' (*note Lisp Libraries::). If the file you save in is your
+initialization file `~/.emacs' (*note Init File::), then the macro will
+be defined each time you run Emacs.
If you give `insert-kbd-macro' a prefix argument, it creates
additional Lisp code to record the keys (if any) that you have bound to
1. The first character in the string specifies the syntactic class.
It is one of the characters in the previous table (*note Syntax
- Entry::.).
+ Entry::).
2. The second character is the matching delimiter. For a character
that is not an opening or closing delimiter, this should be a
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
home directory. This file, if it exists, should contain Lisp code. It
is called your initialization file or "init file". Use the command
line switch `-q' to tell Emacs whether to load an init file (*note
-Entering Emacs::.). Use the command line switch `-user-init-file'
-(*note Command Switches::.) to tell Emacs to load a different file
+Entering Emacs::). Use the command line switch `-user-init-file'
+(*note Command Switches::) to tell Emacs to load a different file
instead of `~/.emacs'.
When the `.emacs' file is read, the variable `user-init-file' says
If you have a large amount of code in your `.emacs' file, you should
move it into another file named `SOMETHING.el', byte-compile it (*note
-Lisp Libraries::.), and load that file from your `.emacs' file using
+Lisp Libraries::), and load that file from your `.emacs' file using
`load'.
* Menu:
expressions. Each consists of a function name followed by arguments,
all surrounded by parentheses. For example, `(setq fill-column 60)'
represents a call to the function `setq' which is used to set the
-variable `fill-column' (*note Filling::.) to 60.
+variable `fill-column' (*note Filling::) to 60.
The second argument to `setq' is an expression for the new value of
the variable. This can be a constant, a variable, or a function call
When the argument to `load' is a relative pathname, not starting
with `/' or `~', `load' searches the directories in `load-path'
- (*note Loading::.).
+ (*note Loading::).
* Load the compiled Lisp file `foo.elc' from your home directory.
`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
Color of the top and bottom shadows for the toolbars. NOTE: These
- resources do *not* have anything to do with the top and bottom
+ resources do _not_ have anything to do with the top and bottom
toolbars (i.e. the toolbars at the top and bottom of the frame)!
Rather, they affect the top and bottom shadows around the edges of
all four kinds of toolbars.
`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
Pixmap of the top and bottom shadows for the toolbars. If set,
these resources override the corresponding color resources. NOTE:
- These resources do *not* have anything to do with the top and
+ These resources do _not_ have anything to do with the top and
bottom toolbars (i.e. the toolbars at the top and bottom of the
frame)! Rather, they affect the top and bottom shadows around the
edges of all four kinds of toolbars.
`C-g' does not do this, and could not do this because it is used to
cancel a partially typed command within the recursive editing level.
Both operations are useful. For example, if you are in the Emacs
-debugger (*note Lisp Debug::.) and have typed `C-u 8' to enter a
-numeric argument, you can cancel that argument with `C-g' and remain in
-the debugger.
+debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
+argument, you can cancel that argument with `C-g' and remain in the
+debugger.
The command `M-x top-level' is equivalent to "enough" `C-]' commands
to get you out of all the levels of recursive edits that you are in.
* Screen Garbled:: Garbage on the screen.
* Text Garbled:: Garbage in the text.
* Unasked-for Search:: Spontaneous entry to incremental search.
-* Emergency Escape:: Emergency escape--
+* Emergency Escape:: Emergency escape---
What to do if Emacs stops responding.
* Total Frustration:: When you are at your wits' end.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
To make the backtrace, you must execute the Lisp expression `(setq
debug-on-error t)' before the error happens (that is to say, you must
execute that expression and then make the bug happen). This causes the
-Lisp debugger to run (*note Lisp Debug::.). The debugger's backtrace
+Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace
can be copied as text into the bug report. This use of the debugger is
possible only if you know how to make the bug happen again. Do note
the error message the first time the bug happens, so if you can't make
Balance Parentheses
Emacs can balance parentheses manually or automatically. Manual
balancing is done by the commands to move over balanced expressions
- (*note Lists::.). Automatic balancing is done by blinking the
+ (*note Lists::). Automatic balancing is done by blinking the
parenthesis that matches one just inserted (*note Matching Parens:
Matching.).
Command Name
A command name is the name of a Lisp symbol which is a command
- (*note Commands::.). You can invoke any command by its name using
- `M-x' (*note M-x::.).
+ (*note Commands::). You can invoke any command by its name using
+ `M-x' (*note M-x::).
Comments
A comment is text in a program which is intended only for the
Compilation
Compilation is the process of creating an executable program from
source code. Emacs has commands for compiling files of Emacs Lisp
- code (*note Lisp Libraries::.) and programs in C and other
- languages (*note Compilation::.).
+ code (*note Lisp Libraries::) and programs in C and other languages
+ (*note Compilation::).
Complete Key
A complete key is a character or sequence of characters which,
current one. *Note Buffers::.
Current Line
- The line point is on (*note Point::.).
+ The line point is on (*note Point::).
Current Paragraph
The paragraph that point is in. If point is between paragraphs,
Customization
Customization is making minor changes in the way Emacs works. It
- is often done by setting variables (*note Variables::.) or by
- rebinding keys (*note Keymaps::.).
+ is often done by setting variables (*note Variables::) or by
+ rebinding keys (*note Keymaps::).
Default Argument
The default for an argument is the value that is used if you do not
A prompt is text printed to ask the user for input. Printing a
prompt is called prompting. Emacs prompts always appear in the
echo area (q.v.). One kind of prompting happens when the
- minibuffer is used to read an argument (*note Minibuffer::.); the
+ minibuffer is used to read an argument (*note Minibuffer::); the
echoing which happens when you pause in the middle of typing a
multi-character key is also a kind of prompting (*note Echo
- Area::.).
+ Area::).
Quitting
Quitting means cancelling a partially typed command or a running
explicitly instructed to do so. *Note Bugs::.
Text
- Text has two meanings (*note Text::.):
+ Text has two meanings (*note Text::):
* Data consisting of a sequence of characters, as opposed to
binary numbers, images, graphics commands, executable
Transposing two units of text means putting each one into the place
formerly occupied by the other. There are Emacs commands to
transpose two adjacent characters, words, sexps (q.v.), or lines
- (*note Transpose::.).
+ (*note Transpose::).
Truncation
Truncating text lines in the display means leaving out any text on
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Insert File... menu item: File Menu.
* insertion: Basic.
* international scripts: Mule.
-* interval operator (in regexps): Create Tags Table.
+* interval operator (in regexps): Etags Regexps.
* invisible lines: Outline Mode.
* IPA: Mule.
* Islamic calendar: Calendar Systems.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
for later use. Text saved in a register can be copied into the buffer
once or many times; a position saved in a register is used by moving
point to that position. Rectangles can also be copied into and out of
-registers (*note Rectangles::.).
+registers (*note Rectangles::).
Each register has a name, which is a single character. A register
can store either a piece of text, a position, or a rectangle, but only
that each line of text is shifted sideways in the window, and one or
more characters at the beginning of each line are not displayed at all.
When a window has been scrolled horizontally in this way, text lines
-are truncated rather than continued (*note Continuation Lines::.), with
+are truncated rather than continued (*note Continuation Lines::), with
a `$' appearing in the first column when there is text truncated to the
left, and in the last column when there is text truncated to the right.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
buffer you must go to the beginning first. By default, all occurrences
up to the end of the buffer are replaced. To limit replacement to part
of the buffer, narrow to that part of the buffer before doing the
-replacement (*note Narrowing::.).
+replacement (*note Narrowing::).
When `replace-string' exits, point is left at the last occurrence
replaced. The value of point when the `replace-string' command was
At this point, you can type `C-r' (see below) to alter the
replaced text. To undo the replacement, you can type `C-x u'.
This exits the `query-replace'. If you want to do further
- replacement you must use `C-x ESC' to restart (*note
- Repetition::.).
+ replacement you must use `C-x ESC' to restart (*note Repetition::).
`<ESC>'
to exit without doing any more replacements.
transposes into `BAR, FOO' rather than `BAR FOO,'.
`C-M-t' (`transpose-sexps') is a similar command for transposing two
-expressions (*note Lists::.), and `C-x C-t' (`transpose-lines')
+expressions (*note Lists::), and `C-x C-t' (`transpose-lines')
exchanges lines. It works like `M-t' but in determines the division of
the text into syntactic units differently.
* Version Control:: Version control systems (RCS and SCCS).
* ListDir:: Listing the contents of a file directory.
* Comparing Files:: Finding where two files differ.
-* Dired:: "Editing" a directory to delete, rename, etc.
+* Dired:: ``Editing'' a directory to delete, rename, etc.
the files in it.
* Misc File Ops:: Other things you can do on files.
Most Emacs commands that operate on a file require you to specify the
file name. (Saving and reverting are exceptions; the buffer knows which
file name to use for them.) File names are specified in the minibuffer
-(*note Minibuffer::.). "Completion" is available, to make it easier to
+(*note Minibuffer::). "Completion" is available, to make it easier to
specify long file names. *Note Completion::.
There is always a "default file name" which is used if you enter an
<RET>. If you are using XEmacs under X, you can also use the Open...
command from the File menu bar item.
- The file name is read using the minibuffer (*note Minibuffer::.),
-with defaulting and completion in the standard manner (*note File
-Names::.). While in the minibuffer, you can abort `C-x C-f' by typing
-`C-g'.
+ The file name is read using the minibuffer (*note Minibuffer::), with
+defaulting and completion in the standard manner (*note File Names::).
+While in the minibuffer, you can abort `C-x C-f' by typing `C-g'.
`C-x C-f' has completed successfully when text appears on the screen
and a new buffer name appears in the mode line. If the specified file
visiting a file.
If the file you specify is actually a directory, Dired is called on
-that directory (*note Dired::.). To inhibit this, set the variable
+that directory (*note Dired::). To inhibit this, set the variable
`find-file-run-dired' to `nil'; then it is an error to try to visit a
directory.
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
there is a file whose owner should not change. Since most files should
change owners, it is a good idea to use local variable lists to set
`backup-by-copying-when-mismatch' for the special cases where the owner
-should not change (*note File Variables::.).
+should not change (*note File Variables::).
Three variables control the choice of renaming or copying.
Normally, renaming is done. If the variable `backup-by-copying' is
If the current buffer has been auto-saved more recently than it has
been saved explicitly, `revert-buffer' offers to read the auto save file
-instead of the visited file (*note Auto Save::.). Emacs asks you about
+instead of the visited file (*note Auto Save::). Emacs asks you about
the auto-save file before the request for confirmation of the
`revert-buffer' operation, and demands `y' or `n' as an answer. If you
have started to type `yes' for confirmation without realizing that the
Each time you visit a file, auto-saving is turned on for that file's
buffer if the variable `auto-save-default' is non-`nil' (but not in
-batch mode; *note Entering Emacs::.). The default for this variable is
+batch mode; *note Entering Emacs::). The default for this variable is
`t', so Emacs auto-saves buffers that visit files by default. You can
use the command `M-x auto-save-mode' to turn auto-saving for a buffer
on or off. Like other minor mode commands, `M-x auto-save-mode' turns
------------------
If you use RCS for a program and also maintain a change log file for
-it (*note Change Log::.), you can generate change log entries
+it (*note Change Log::), you can generate change log entries
automatically from the version control log entries:
`C-x v a'
If you supply a directory name instead of the name of a work file,
this command compares the two specified versions of all registered files
in that directory and its subdirectories. You can also specify a
-snapshot name (*note Snapshots::.) instead of one or both version
+snapshot name (*note Snapshots::) instead of one or both version
numbers.
You can specify a checked-in version by its number; you can specify
When you rename a registered file, you must also rename its master
file correspondingly to get proper results. Use `vc-rename-file' to
rename the source file as you specify, and rename its master file
-accordingly. It also updates any snapshots (*note Snapshots::.) that
+accordingly. It also updates any snapshots (*note Snapshots::) that
mention the file, so that they use the new name; despite this, the
snapshot thus modified may not completely work (*note Snapshot
-Caveats::.).
+Caveats::).
You cannot use `vc-rename-file' on a file that is locked by someone
else.
they are useful.
You can give a snapshot name as an argument to `C-x v =' or `C-x v
-~' (*note Old Versions::.). Thus, you can use it to compare a snapshot
+~' (*note Old Versions::). Thus, you can use it to compare a snapshot
against the current files, or two snapshots against each other, or a
snapshot against a named version.
`#'
Flag all auto-save files (files whose names start and end with `#')
- for deletion (*note Auto Save::.).
+ for deletion (*note Auto Save::).
`~'
Flag all backup files (files whose names end with `~') for deletion
- (*note Backup::.).
+ (*note Backup::).
`. (Period)'
Flag excess numeric backup files for deletion. The oldest and
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
`M-x delete-file' deletes a specified file, like the `rm' command in
the shell. If you are deleting many files in one directory, it may be
-more convenient to use Dired (*note Dired::.).
+more convenient to use Dired (*note Dired::).
`M-x insert-file' inserts a copy of the contents of a specified file
into the current buffer at point, leaving point unchanged before the
which is displayed there, but at any time only one of the windows is
selected and its chosen buffer is the selected buffer. Each window's
mode line displays the name of the buffer the window is displaying
-(*note Windows::.).
+(*note Windows::).
Each buffer has a name which can be of any length but is
case-sensitive. You can select a buffer using its name. Most buffers
Each buffer records what file it is visiting, whether it is
modified, and what major mode and minor modes are in effect in it
-(*note Major Modes::.). Any Emacs variable can be made "local to" a
+(*note Major Modes::). Any Emacs variable can be made "local to" a
particular buffer, meaning its value in that buffer can be different
from the value in other buffers. *Note Locals::.
To select a buffer named BUFNAME, type `C-x b BUFNAME <RET>'. This
is the command `switch-to-buffer' with argument BUFNAME. You can use
completion on an abbreviation for the buffer name you want (*note
-Completion::.). An empty argument to `C-x b' specifies the most
+Completion::). An empty argument to `C-x b' specifies the most
recently selected buffer that is not displayed in any window.
Most buffers are created when you visit files, or use Emacs commands
`C-x b BUFNAME <RET>', which creates a new, empty buffer that is not
visiting any file, and selects it for editing. The new buffer's major
mode is determined by the value of `default-major-mode' (*note Major
-Modes::.). Buffers not visiting files are usually used for making
-notes to yourself. If you try to save one, you are asked for the file
-name to use.
+Modes::). Buffers not visiting files are usually used for making notes
+to yourself. If you try to save one, you are asked for the file name
+to use.
The function `switch-to-buffer-other-frame' is similar to
`switch-to-buffer' except that it creates a new frame in which to
in the list shows one buffer's name, major mode, and visited file. A
`*' at the beginning of a line indicates the buffer has been
"modified". If several buffers are modified, it may be time to save
-some with `C-x s' (*note Saving::.). A `%' indicates a read-only
+some with `C-x s' (*note Saving::). A `%' indicates a read-only
buffer. A `.' marks the selected buffer. Here is an example of a
buffer list:
signalled and renaming is not done.
`M-x view-buffer' is similar to `M-x view-file' (*note Misc File
-Ops::.), but it examines an already existing Emacs buffer. View mode
+Ops::), but it examines an already existing Emacs buffer. View mode
provides convenient commands for scrolling through the buffer but not
for changing it. When you exit View mode, the resulting value of point
remains in effect.
wrapping around to the top or bottom of the current frame, when there
are no more windows.
- The usual scrolling commands (*note Display::.) apply to the selected
+ The usual scrolling commands (*note Display::) apply to the selected
window only. `M-C-v' (`scroll-other-window') scrolls the window that
`C-x o' would select. Like `C-v', it takes positive and negative
arguments.
`C-x 4 m'
Start composing a mail message in another window. This runs
`mail-other-window', and its same-window version is `C-x m' (*note
- Sending Mail::.).
+ Sending Mail::).
`C-x 4 .'
Find a tag in the current tag table in another window. This runs
`find-tag-other-window', the multiple-window variant of `M-.'
- (*note Tags::.).
+ (*note Tags::).
If the variable `display-buffer-function' is non-`nil', its value is
the function to call to handle `display-buffer'. It receives two
preferred script (more or less) rather that a choice of language.
The language environment controls which coding systems to recognize
-when reading text (*note Recognize Coding::.). This applies to files,
+when reading text (*note Recognize Coding::). This applies to files,
incoming mail, netnews, and any other text you read into XEmacs. It may
also specify the default coding system to use when you create a file.
Each language environment also specifies a default input method.
as argument; alternatively, with an empty argument, it describes the
coding systems currently selected for various purposes, both in the
current buffer and as the defaults, and the priority list for
-recognizing coding systems (*note Recognize Coding::.).
+recognizing coding systems (*note Recognize Coding::).
To display a list of all the supported coding systems, type `M-x
list-coding-systems'. The list gives information about each coding
system, including the letter that stands for it in the mode line (*note
-Mode Line::.).
+Mode Line::).
Each of the coding systems that appear in this list--except for
`binary', which means no conversion of any kind--specifies how and
contents assuming that they are represented in this coding system.
The priority list of coding systems depends on the selected language
-environment (*note Language Environments::.). For example, if you use
+environment (*note Language Environments::). For example, if you use
French, you probably want XEmacs to prefer Latin-1 to Latin-2; if you
use Czech, you probably want Latin-2 to be preferred. This is one of
the reasons to specify a language environment.
You can specify the coding system for a particular file using the
`-*-...-*-' construct at the beginning of a file, or a local variables
-list at the end (*note File Variables::.). You do this by defining a
+list at the end (*note File Variables::). You do this by defining a
value for the "variable" named `coding'. XEmacs does not really have a
variable `coding'; instead of setting a variable, it uses the specified
coding system for the file. For example, `-*-mode: C; coding:
file. This includes the commands `save-buffer' and `write-region'. If
you want to write files from this buffer using a different coding
system, you can specify a different coding system for the buffer using
-`set-buffer-file-coding-system' (*note Specify Coding::.).
+`set-buffer-file-coding-system' (*note Specify Coding::).
-This is Info file ../../info/xemacs.info, produced by Makeinfo version
-1.68 from the input file xemacs.texi.
+This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
the file. First use the command `C-x <RET> c'
(`universal-coding-system-argument'); this command uses the minibuffer
to read a coding system name. After you exit the minibuffer, the
-specified coding system is used for *the immediately following command*.
+specified coding system is used for _the immediately following command_.
So if the immediately following command is `C-x C-f', for example,
it reads the file using that coding system (and records the coding
editing English text. The remaining major modes are not intended for
use on users' files; they are used in buffers created by Emacs for
specific purposes and include Dired mode for buffers made by Dired
-(*note Dired::.), Mail mode for buffers made by `C-x m' (*note Sending
-Mail::.), and Shell mode for buffers used for communicating with an
-inferior shell process (*note Interactive Shell::.).
+(*note Dired::), Mail mode for buffers made by `C-x m' (*note Sending
+Mail::), and Shell mode for buffers used for communicating with an
+inferior shell process (*note Interactive Shell::).
Most programming language major modes specify that only blank lines
separate paragraphs. This is so that the paragraph commands remain
edit files of text in a human language. Invoke `M-x text-mode' to
enter Text mode. In Text mode, <TAB> runs the function
`tab-to-tab-stop', which allows you to use arbitrary tab stops set with
-`M-x edit-tab-stops' (*note Tab Stops::.). Features concerned with
+`M-x edit-tab-stops' (*note Tab Stops::). Features concerned with
comments in programs are turned off unless they are explicitly invoked.
The syntax table is changed so that periods are not considered part of a
word, while apostrophes, backspaces and underlines are.
A similar variant mode is Indented Text mode, intended for editing
text in which most lines are indented. This mode defines <TAB> to run
-`indent-relative' (*note Indentation::.), and makes Auto Fill indent
-the lines it creates. As a result, a line made by Auto Filling, or by
+`indent-relative' (*note Indentation::), and makes Auto Fill indent the
+lines it creates. As a result, a line made by Auto Filling, or by
<LFD>, is normally indented just like the previous line. Use `M-x
indented-text-mode' to select this mode.
The other feature of Nroff mode is Electric Nroff newline mode.
This is a minor mode that you can turn on or off with `M-x
-electric-nroff-mode' (*note Minor Modes::.). When the mode is on and
+electric-nroff-mode' (*note Minor Modes::). When the mode is on and
you use <RET> to end a line containing an nroff command that opens a
kind of grouping, Emacs automatically inserts the matching nroff
command to close that grouping on the following line. For example, if
of the paragraph for a few seconds and pushes a mark at that spot.
Scanning continues until the whole buffer has been checked or until you
type another key. The positions of the last several paragraphs with
-mismatches can be found in the mark ring (*note Mark Ring::.).
+mismatches can be found in the mark ring (*note Mark Ring::).
Note that square brackets and parentheses, not just braces, are
matched in TeX mode. This is wrong if you want to check TeX syntax.
The console output from TeX, including any error messages, appears
in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch
to this buffer and feed it input (this works as in Shell mode; *note
-Interactive Shell::.). Without switching to this buffer, you can scroll
+Interactive Shell::). Without switching to this buffer, you can scroll
it so that its last line is visible by typing `C-c C-l'.
Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
projects / chise / xemacs-chise.git- / commitdiff