From: tomo Date: Thu, 6 Jan 2000 06:17:30 +0000 (+0000) Subject: XEmacs 21.2.22 "Mercedes". X-Git-Tag: r21-2-22^2 X-Git-Url: http://git.chise.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c3f3c0bbb365c03a9551bba7c59cb5c67eac40d0;p=chise%2Fxemacs-chise.git- XEmacs 21.2.22 "Mercedes". --- diff --git a/info/cl.info-1 b/info/cl.info-1 index cc97278..39091b8 100644 --- a/info/cl.info-1 +++ b/info/cl.info-1 @@ -1,5 +1,4 @@ -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 @@ -231,7 +230,7 @@ name: 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 @@ -297,13 +296,13 @@ this package to implement Common Lisp argument lists seamlessly. 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 @@ -314,7 +313,7 @@ you must use if you need Common Lisp argument lists. 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 @@ -323,7 +322,7 @@ you must use if you need Common Lisp argument lists. 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. @@ -332,7 +331,7 @@ you must use if you need Common Lisp argument lists. 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. @@ -426,7 +425,7 @@ the scan for keyword arguments by calling `memq' to search for keywords 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 @@ -473,7 +472,7 @@ dotted, so that the argument list `(a b . c)' is functionally 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. @@ -492,7 +491,7 @@ certain top-level forms evaluated at compile-time. For example, the 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, @@ -563,7 +562,7 @@ construct and is described below. This package defines a version of `(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 @@ -572,7 +571,7 @@ this package. 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. @@ -617,7 +616,7 @@ Function Aliases 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 @@ -647,7 +646,7 @@ Type Predicates 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)'. @@ -704,7 +703,7 @@ beginning with a symbol. 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 @@ -715,13 +714,13 @@ related to `typep'. 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 @@ -753,7 +752,7 @@ Equality Predicates 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 @@ -784,7 +783,7 @@ This package defines two Common Lisp predicates, `eql' and `equalp'. 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 @@ -831,7 +830,7 @@ Assignment 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, @@ -853,7 +852,7 @@ are done in parallel rather than sequentially. 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'. @@ -896,7 +895,7 @@ Basic Setf 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 diff --git a/info/cl.info-2 b/info/cl.info-2 index cd1974e..8c49371 100644 --- a/info/cl.info-2 +++ b/info/cl.info-2 @@ -1,5 +1,4 @@ -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 @@ -37,14 +36,14 @@ This package defines a number of other macros besides `setf' that 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) @@ -57,7 +56,7 @@ when the PLACE is just a variable name. 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! @@ -72,28 +71,28 @@ when the PLACE is just a variable name. 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. @@ -108,7 +107,7 @@ when the PLACE is just a variable name. 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 @@ -123,7 +122,7 @@ when the PLACE is just a variable name. 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, @@ -168,7 +167,7 @@ analogues in Common Lisp. 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. @@ -188,14 +187,14 @@ analogues in Common Lisp. 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::.  File: cl.info, Node: Customizing Setf, Prev: Modify Macros, Up: Generalized Variables @@ -207,7 +206,7 @@ Common Lisp defines three macros, `define-modify-macro', `defsetf', and `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 @@ -237,7 +236,7 @@ variables in various ways. `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, @@ -270,7 +269,7 @@ variables in various ways. (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 @@ -295,7 +294,7 @@ variables in various ways. (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 @@ -334,7 +333,7 @@ variables in various ways. 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 @@ -357,7 +356,7 @@ variables in various ways. 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 @@ -393,7 +392,7 @@ The standard `let' form binds variables whose names are known at 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, @@ -412,7 +411,7 @@ Lexical Bindings 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 @@ -500,7 +499,7 @@ the Common Lisp `let' form: 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*'. @@ -512,7 +511,7 @@ Function Bindings 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 @@ -548,7 +547,7 @@ These forms make `let'-like bindings to functions instead of variables. 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 @@ -562,7 +561,7 @@ Macro Bindings 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 @@ -574,7 +573,7 @@ These forms create local macros and "symbol macros." 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 @@ -612,7 +611,7 @@ These forms create local macros and "symbol macros." => (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 @@ -637,7 +636,7 @@ Conditionals 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, @@ -647,7 +646,7 @@ and `cond' forms. (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: @@ -657,7 +656,7 @@ and `cond' 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, @@ -685,12 +684,12 @@ and `cond' forms. ((?\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 @@ -706,7 +705,7 @@ and `cond' forms. `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'. @@ -724,7 +723,7 @@ the lexical scoping allows the optimizing byte-compiler to omit the 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 @@ -762,13 +761,13 @@ costly `catch' step if the body of the block does not actually 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. @@ -782,12 +781,12 @@ Iteration 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 @@ -806,7 +805,7 @@ looping constructs to complement Emacs Lisp's basic `while' loop. 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 @@ -828,7 +827,7 @@ looping constructs to complement Emacs Lisp's basic `while' loop. 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'. @@ -845,7 +844,7 @@ looping constructs to complement Emacs Lisp's basic `while' loop. ((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'. @@ -861,7 +860,7 @@ looping constructs to complement Emacs Lisp's basic `while' loop. (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. @@ -869,7 +868,7 @@ looping constructs to complement Emacs Lisp's basic `while' loop. `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 @@ -878,7 +877,7 @@ looping constructs to complement Emacs Lisp's basic `while' loop. 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 @@ -887,7 +886,7 @@ looping constructs to complement Emacs Lisp's basic `while' loop. 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. @@ -933,7 +932,7 @@ to be very easy to learn and well-suited to its purpose. 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 diff --git a/info/cl.info-3 b/info/cl.info-3 index 40c734f..69e4664 100644 --- a/info/cl.info-3 +++ b/info/cl.info-3 @@ -1,5 +1,4 @@ -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 @@ -141,7 +140,7 @@ form you use is purely a matter of style. 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 @@ -168,7 +167,7 @@ form you use is purely a matter of style. 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'. @@ -553,20 +552,20 @@ functions, by contrast, always return exactly one result. This package 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 @@ -595,7 +594,7 @@ Argument Lists::. 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' @@ -608,7 +607,7 @@ macro: 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 @@ -640,7 +639,7 @@ optimizations for your functions. 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 @@ -673,12 +672,12 @@ when the optimizing Emacs 19 byte compiler is being used, however. 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 @@ -688,7 +687,7 @@ effectively be ignored. 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" @@ -696,10 +695,10 @@ effectively be ignored. 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 @@ -846,7 +845,7 @@ These functions augment the standard Emacs Lisp functions `get' and 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 @@ -855,7 +854,7 @@ structures not attached to particular symbols. 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. @@ -865,7 +864,7 @@ structures not attached to particular symbols. 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, @@ -896,7 +895,7 @@ structures not attached to particular symbols. 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 @@ -913,7 +912,7 @@ Creating Symbols 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, @@ -937,9 +936,9 @@ variables. 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. @@ -974,23 +973,23 @@ Predicates on Numbers 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'. @@ -1003,34 +1002,34 @@ Numerical Functions 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. @@ -1055,31 +1054,31 @@ These functions perform various arithmetic operations on numbers. 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'. @@ -1099,7 +1098,7 @@ number generator. It uses its own additive-congruential algorithm, 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 @@ -1116,7 +1115,7 @@ than the simple generators supplied by many operating systems. 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 @@ -1139,7 +1138,7 @@ than the simple generators supplied by many operating systems. 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. diff --git a/info/cl.info-4 b/info/cl.info-4 index 34e70ca..71656e9 100644 --- a/info/cl.info-4 +++ b/info/cl.info-4 @@ -1,5 +1,4 @@ -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 @@ -71,7 +70,7 @@ the constants' names. - 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 @@ -84,7 +83,7 @@ the constants' names. 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 @@ -136,7 +135,7 @@ Sequence Basics =============== 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 @@ -155,7 +154,7 @@ the original sequence function arguments from which they are derived, 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 @@ -188,7 +187,7 @@ elements. Therefore, it is a bad idea to depend on side effects of 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.) @@ -208,7 +207,7 @@ These functions "map" the function you specify over the elements of 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 @@ -224,7 +223,7 @@ function `mapcar'. 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: @@ -232,7 +231,7 @@ function `mapcar'. 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, @@ -240,26 +239,26 @@ function `mapcar'. 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 @@ -268,24 +267,24 @@ function `mapcar'. 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 @@ -308,7 +307,7 @@ function `mapcar'. 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 @@ -329,7 +328,7 @@ Sequence Functions 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 @@ -340,25 +339,25 @@ on sequences. 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. @@ -370,7 +369,7 @@ on 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 @@ -386,7 +385,7 @@ on sequences. 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 @@ -400,22 +399,22 @@ on sequences. 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 @@ -425,19 +424,19 @@ on sequences. 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 @@ -454,9 +453,9 @@ Searching Sequences =================== 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 @@ -465,7 +464,7 @@ These functions search for elements or subsequences in a sequence. `: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 @@ -473,14 +472,14 @@ These functions search for elements or subsequences in a sequence. 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 @@ -499,7 +498,7 @@ These functions search for elements or subsequences in a sequence. 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 @@ -507,7 +506,7 @@ These functions search for elements or subsequences in a sequence. `: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.  File: cl.info, Node: Sorting Sequences, Prev: Searching Sequences, Up: Sequences @@ -515,7 +514,7 @@ File: cl.info, Node: Sorting Sequences, Prev: Searching Sequences, Up: Sequen 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 @@ -538,7 +537,7 @@ Sorting Sequences 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. @@ -548,7 +547,7 @@ Sorting Sequences 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 @@ -586,54 +585,54 @@ List Functions 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 @@ -643,7 +642,7 @@ chains of cons cells. 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 @@ -651,11 +650,11 @@ chains of cons cells. 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) @@ -664,7 +663,7 @@ chains of cons cells. 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 @@ -682,7 +681,7 @@ These functions substitute elements throughout a tree of cons cells. (*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 @@ -695,20 +694,20 @@ on just the top-level elements of a list.) 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'.  @@ -720,13 +719,13 @@ Lists as Sets 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 @@ -742,11 +741,11 @@ elements. 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 @@ -754,7 +753,7 @@ elements which satisfy a given predicate. 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, @@ -764,38 +763,38 @@ elements which satisfy a given predicate. 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. @@ -809,7 +808,7 @@ An "association list" is a list representing a mapping from one set of 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 @@ -819,12 +818,12 @@ association list. `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 @@ -835,10 +834,10 @@ functions are defined similarly. 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)'.  diff --git a/info/cl.info-5 b/info/cl.info-5 index 6ea0a18..a2351b0 100644 --- a/info/cl.info-5 +++ b/info/cl.info-5 @@ -1,5 +1,4 @@ -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 @@ -46,7 +45,7 @@ provides no way to create new distinct types, this package implements 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 @@ -169,7 +168,7 @@ symbol to identify them. 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 @@ -354,7 +353,7 @@ is less than 3, then the byte-compiler will optimize away the following 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. @@ -376,7 +375,7 @@ idea for them to include side-effects. 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 @@ -395,7 +394,7 @@ idea for them to include side-effects. 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 @@ -428,7 +427,7 @@ which are the most efficient ways of doing these respective operations 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 @@ -440,7 +439,7 @@ thrown away a hundred times. 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 @@ -465,7 +464,7 @@ function. 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, @@ -508,7 +507,7 @@ Functions taking keyword arguments will accept an odd number of 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 @@ -532,7 +531,7 @@ top-level context. The patch will not harm versions of the Emacs 18 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 @@ -564,13 +563,13 @@ lists). 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 @@ -591,7 +590,7 @@ since Emacs Lisp cannot support multiple return values directly. The 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 @@ -709,7 +708,7 @@ an Emacs implementation of true Common Lisp. Some of the remaining 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. diff --git a/info/cl.info-6 b/info/cl.info-6 index 09892f7..57b8a68 100644 --- a/info/cl.info-6 +++ b/info/cl.info-6 @@ -1,5 +1,4 @@ -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 diff --git a/info/internals.info-3 b/info/internals.info-3 index b9844e5..7db06a9 100644 --- a/info/internals.info-3 +++ b/info/internals.info-3 @@ -1,5 +1,5 @@ -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 @@ -255,7 +255,7 @@ General Guidelines for Writing Mule-Aware Code 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 @@ -264,12 +264,12 @@ Mule-aware code, as well as some pitfalls you should avoid. 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. @@ -405,12 +405,11 @@ you can try to improve the test suite in `tests/automated'. 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 `' and `"lisp.h"'. It + * Header files should _not_ include `' 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 @@ -522,7 +521,7 @@ file linked, respectively. (Actually, this is not really true. 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 @@ -737,7 +736,7 @@ functions, traversing stack frames, and binding variables; the control 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 @@ -796,7 +795,7 @@ arithmetic. `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.  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 @@ -814,7 +813,7 @@ by other properties; manipulate lists of buffers (remember that buffers 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. @@ -973,7 +972,7 @@ provide another implementation of those API functions. 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 diff --git a/info/internals.info-4 b/info/internals.info-4 index f32214c..151d7cf 100644 --- a/info/internals.info-4 +++ b/info/internals.info-4 @@ -1,5 +1,5 @@ -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 @@ -776,7 +776,7 @@ and as such may not look like they normally do. In particular: * 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. @@ -829,7 +829,7 @@ some rules, though: 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. @@ -864,7 +864,7 @@ some rules, though: 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. @@ -874,12 +874,12 @@ some rules, though: 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. @@ -887,7 +887,7 @@ some rules, though: 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 @@ -945,14 +945,14 @@ Invocation 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 diff --git a/info/internals.info-5 b/info/internals.info-5 index cbb9a34..91df6a0 100644 --- a/info/internals.info-5 +++ b/info/internals.info-5 @@ -1,5 +1,5 @@ -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 @@ -654,8 +654,8 @@ create one of these, copy an existing model and modify as necessary. 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.) @@ -667,12 +667,12 @@ create one of these, copy an existing model and modify as necessary. `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 @@ -692,11 +692,11 @@ create one of these, copy an existing model and modify as necessary. 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 @@ -816,7 +816,7 @@ immediately puts the conses onto the cons free list, and decrements the 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.  @@ -829,7 +829,7 @@ Vector 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. diff --git a/info/internals.info-6 b/info/internals.info-6 index 2692bef..177e1a5 100644 --- a/info/internals.info-6 +++ b/info/internals.info-6 @@ -1,5 +1,5 @@ -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 @@ -204,8 +204,8 @@ is replaced but the rest stays the same. 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. @@ -954,12 +954,12 @@ characters back again). Once the buffer is killed, the memory allocated 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 @@ -986,7 +986,7 @@ at that position, we need to follow these steps: 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. diff --git a/info/internals.info-7 b/info/internals.info-7 index 79231c67..6f509c6 100644 --- a/info/internals.info-7 +++ b/info/internals.info-7 @@ -1,5 +1,5 @@ -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 @@ -277,7 +277,7 @@ later. 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 @@ -845,17 +845,20 @@ Lstream Functions - 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 @@ -879,8 +882,8 @@ File: internals.info, Node: Lstream Methods, Prev: Lstream Functions, Up: Lst 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 @@ -897,8 +900,8 @@ Lstream Methods 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 @@ -1028,9 +1031,9 @@ Window Hierarchy 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. @@ -1068,7 +1071,7 @@ combination window. 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 diff --git a/info/internals.info-8 b/info/internals.info-8 index 1d5c420..5467f97 100644 --- a/info/internals.info-8 +++ b/info/internals.info-8 @@ -1,5 +1,5 @@ -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 @@ -308,7 +308,7 @@ structure to be there. 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 @@ -376,7 +376,7 @@ overlap a range. 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 diff --git a/info/lispref.info-10 b/info/lispref.info-10 index 74ab646..7667fa8 100644 --- a/info/lispref.info-10 +++ b/info/lispref.info-10 @@ -1,5 +1,5 @@ -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 @@ -60,9 +60,9 @@ reference the former variable, the current value of the latter is 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. @@ -74,12 +74,12 @@ Obsoleteness::.). 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 @@ -169,7 +169,7 @@ function-like objects. 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. @@ -191,7 +191,7 @@ function-like objects. 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). @@ -200,7 +200,7 @@ function-like objects. (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: @@ -310,10 +310,10 @@ right. Then it applies the lambda expression to the argument values 1, 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 @@ -427,7 +427,7 @@ one or two complete sentences that summarize the function's purpose. 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. @@ -453,7 +453,7 @@ strictest sense has no name. It is simply a list whose first element is 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 @@ -483,7 +483,7 @@ function definition. For most purposes, there is no need to 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. @@ -501,7 +501,7 @@ Defining Functions 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: @@ -510,7 +510,7 @@ special form. `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 @@ -553,8 +553,8 @@ special form. 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). @@ -563,7 +563,7 @@ special form. 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 @@ -594,7 +594,7 @@ Usually that's just what you want. Occasionally you need to decide at 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. @@ -603,7 +603,7 @@ run time which function to call. To do that, use the functions 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. @@ -624,7 +624,7 @@ run time which function to call. To do that, use the functions 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 @@ -659,10 +659,10 @@ function arguments are often called "functionals". 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'.  @@ -676,7 +676,7 @@ list or other collection. XEmacs Lisp has three such functions; `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. @@ -692,10 +692,10 @@ the third mapping function, `mapatoms', see *Note Creating Symbols::. => (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." @@ -706,11 +706,11 @@ the third mapping function, `mapatoms', see *Note Creating Symbols::. (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. @@ -724,7 +724,7 @@ the third mapping function, `mapatoms', see *Note Creating Symbols::. '(The cat in the hat) " ") => "The cat in the hat" - + (mapconcat (function (lambda (x) (format "%c" (1+ x)))) "HAL-8000" "") @@ -750,15 +750,15 @@ this: => (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 @@ -776,7 +776,7 @@ a number by two: 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 @@ -826,7 +826,7 @@ and set the function cell of symbols. 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. @@ -858,12 +858,12 @@ cell contains no object whatsoever. `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::.) @@ -877,7 +877,7 @@ can make it void once more using `fmakunbound'. (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. @@ -1078,7 +1078,7 @@ macro definition that does the job: (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'. @@ -1119,7 +1119,7 @@ this is unusual. 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 @@ -1142,14 +1142,14 @@ this is unusual. (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. @@ -1184,10 +1184,10 @@ macro in the same file where it is used and before its first use. 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::).  File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros @@ -1206,7 +1206,7 @@ an anonymous macro to functionals such as `mapcar'. In practice, all 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) @@ -1217,7 +1217,7 @@ form `defmacro'. 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. diff --git a/info/lispref.info-11 b/info/lispref.info-11 index 9369659..a1b3017 100644 --- a/info/lispref.info-11 +++ b/info/lispref.info-11 @@ -1,5 +1,5 @@ -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 @@ -61,7 +61,7 @@ of constants and nonconstant parts. To make this easier, use the macro 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) @@ -148,19 +148,18 @@ find in Pascal. (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 @@ -224,8 +223,7 @@ number of times: (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 @@ -246,7 +244,7 @@ supposed to refer to the user's binding of `max', really access the 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 @@ -274,7 +272,7 @@ Evaluating Macro Arguments in Expansion 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 @@ -329,7 +327,7 @@ example: (defmacro empty-object () (list 'quote (cons nil nil))) - + (defun initialize (condition) (let ((object (empty-object))) (if condition @@ -458,7 +456,7 @@ and add your group to each of them using the `:group' keyword. 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. @@ -474,7 +472,7 @@ and add your group to each of them using the `:group' keyword. 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' @@ -492,7 +490,7 @@ Defining Customization Variables 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. @@ -621,7 +619,7 @@ example: 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 @@ -1007,7 +1005,7 @@ the forms are function definitions and variable definitions. * 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. @@ -1020,11 +1018,11 @@ How Programs Do Loading 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. @@ -1129,7 +1127,7 @@ these facilities call the `load' function to do the work. 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 @@ -1144,7 +1142,7 @@ these facilities call the `load' function to do the work. 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: diff --git a/info/lispref.info-12 b/info/lispref.info-12 index 994bfc1..5c5d7bf 100644 --- a/info/lispref.info-12 +++ b/info/lispref.info-12 @@ -1,5 +1,5 @@ -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 @@ -71,8 +71,8 @@ arranges to execute them when Emacs is built. Magic comments are the 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. @@ -118,7 +118,7 @@ installed along with Emacs. 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 @@ -150,7 +150,7 @@ for all files in the current directory. 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', @@ -216,7 +216,7 @@ avoid the problem, write this: (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 @@ -281,7 +281,7 @@ This adds `comint' to the global `features' list, so that `(require '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. @@ -300,7 +300,7 @@ loading the file in question. Loading the file does execute the `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 @@ -323,7 +323,7 @@ loading. 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 @@ -333,7 +333,7 @@ loading. 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. @@ -396,7 +396,7 @@ Unloading 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', @@ -564,11 +564,11 @@ Macros::. 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 @@ -603,7 +603,7 @@ around the `require' calls (*note Eval During Compile::.). 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 @@ -612,7 +612,7 @@ around the `require' calls (*note Eval During Compile::.). 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. @@ -640,7 +640,7 @@ around the `require' calls (*note Eval During Compile::.). -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. @@ -672,7 +672,7 @@ around the `require' calls (*note Eval During Compile::.). 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. @@ -786,7 +786,7 @@ files with file-local variable bindings, like this: 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 @@ -801,7 +801,7 @@ Evaluation During Compilation 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). @@ -810,7 +810,7 @@ compilation of a program. 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. @@ -862,7 +862,7 @@ DOC-STRING 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 @@ -886,13 +886,13 @@ representation. It is the definition of the command `backward-sexp'. 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 @@ -909,34 +909,34 @@ byte compiler to create these objects; it makes the elements consistent 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::. @@ -961,7 +961,7 @@ returns it as the value of the function. 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 diff --git a/info/lispref.info-13 b/info/lispref.info-13 index c94556d..17c20e6 100644 --- a/info/lispref.info-13 +++ b/info/lispref.info-13 @@ -1,5 +1,5 @@ -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 @@ -150,7 +150,7 @@ and then step through the function, or you can do this to a function 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. @@ -197,7 +197,7 @@ function, and then step through its caller. (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 @@ -223,7 +223,7 @@ file! 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::).  File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger @@ -245,7 +245,7 @@ usual XEmacs editing commands are available; thus, you can switch 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. @@ -366,7 +366,7 @@ Invoking the Debugger 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 @@ -468,7 +468,7 @@ debugger. 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 @@ -497,7 +497,7 @@ debugger. (list 'testing (backtrace)))))))) => nil - + ----------- Buffer: backtrace-output ------------ backtrace() (list ...computing arguments...) @@ -523,7 +523,7 @@ debugger. 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 @@ -543,7 +543,7 @@ debugger. 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. @@ -676,7 +676,7 @@ in `M-x list-buffers'.) This buffer contains the program being 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. @@ -721,6 +721,7 @@ provides the following features: * 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. @@ -828,14 +829,14 @@ redefined so that when invoked with a prefix argument on a definition, 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. diff --git a/info/lispref.info-14 b/info/lispref.info-14 index fb2b043..489d392 100644 --- a/info/lispref.info-14 +++ b/info/lispref.info-14 @@ -1,5 +1,5 @@ -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 @@ -321,7 +321,7 @@ Tracing ------- 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*'. @@ -418,7 +418,7 @@ for the evaluation. But Edebug is not completely successful and this 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: @@ -444,6 +444,7 @@ action, it needs to save and restore certain data. Edebug is active, `executing-macro' is bound to `edebug-continue-kbd-macro'. +  File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context @@ -471,7 +472,7 @@ error or quit signal occurs. * 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. @@ -490,6 +491,7 @@ error or quit signal occurs. * `cursor-in-echo-area' is locally bound to `nil' so that the cursor shows up in the window. +  File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context @@ -531,6 +533,7 @@ saves (and later restores) these additional data: While Edebug is active, `defining-kbd-macro' is bound to `edebug-continue-kbd-macro'. +  File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug @@ -545,7 +548,7 @@ the resulting expansion is evaluated, or any time later.) You must 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 diff --git a/info/lispref.info-15 b/info/lispref.info-15 index ce05ae6..21d545b 100644 --- a/info/lispref.info-15 +++ b/info/lispref.info-15 @@ -1,5 +1,5 @@ -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 @@ -203,12 +203,12 @@ value of `standard-input'. 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 @@ -336,7 +336,7 @@ of point, shown in the usual fashion, has no effect. 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. @@ -402,7 +402,7 @@ the current print operation: 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 @@ -420,7 +420,7 @@ is `nil' or omitted, it defaults to the value of `standard-output'. -| => " 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 @@ -432,7 +432,7 @@ is `nil' or omitted, it defaults to the value of `standard-output'. -| 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. @@ -447,14 +447,14 @@ is `nil' or omitted, it defaults to the value of `standard-output'. -| 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. @@ -517,7 +517,7 @@ Variables Affecting Output objects will be written in `#[...]' form instead of in `#' 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 @@ -622,7 +622,7 @@ Introduction to Minibuffers =========================== 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 @@ -649,8 +649,8 @@ forbid recursive minibuffers by setting the variable `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). @@ -678,12 +678,12 @@ middle of a Lisp function. Instead, do all minibuffer input as part of 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 @@ -715,7 +715,7 @@ Defining Commands::. 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'. @@ -752,7 +752,7 @@ Defining Commands::. `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 @@ -761,7 +761,7 @@ Defining Commands::. 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) @@ -792,7 +792,7 @@ Reading Lisp Objects with the Minibuffer 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'. @@ -811,7 +811,7 @@ minibuffer. "Enter an expression: " (format "%s" '(testing))) ;; Here is how the minibuffer is displayed: - + ---------- Buffer: Minibuffer ---------- Enter an expression: (testing)-!- ---------- Buffer: Minibuffer ---------- @@ -819,7 +819,7 @@ minibuffer. The user can type 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'. @@ -831,7 +831,7 @@ 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 @@ -854,7 +854,7 @@ minibuffer. ;; After evaluation of the preceding expression, ;; the following appears in the minibuffer: - + ---------- Buffer: Minibuffer ---------- Please edit: (forward-word 1)-!- ---------- Buffer: Minibuffer ---------- @@ -989,7 +989,7 @@ nothing in themselves to do with minibuffers. We describe them in this 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 @@ -1004,10 +1004,10 @@ that do use the minibuffer. 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. @@ -1020,7 +1020,7 @@ that do use the minibuffer. 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 @@ -1041,7 +1041,7 @@ that do use the minibuffer. "foo" '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) => "fooba" - + (try-completion "foo" '(("barfoo" 2) ("foo" 3))) => t @@ -1060,15 +1060,14 @@ that do use the minibuffer. (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'. @@ -1086,7 +1085,7 @@ that do use the minibuffer. (defun test (s) (> (length (car s)) 6)) => test - + (all-completions "foo" '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) @@ -1106,8 +1105,8 @@ Completion and the Minibuffer 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', @@ -1151,7 +1150,7 @@ minibuffer with completion. "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: @@ -1193,7 +1192,7 @@ the minibuffer to do completion. `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 @@ -1245,7 +1244,7 @@ the minibuffer to do completion. 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. @@ -1264,7 +1263,7 @@ the minibuffer to do completion. 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 diff --git a/info/lispref.info-16 b/info/lispref.info-16 index b61a7d9..618b47f 100644 --- a/info/lispref.info-16 +++ b/info/lispref.info-16 @@ -1,5 +1,5 @@ -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 @@ -63,7 +63,7 @@ Lisp function. When possible, do all minibuffer input as part of 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 @@ -94,7 +94,7 @@ Defining Commands::. ;; The user types `minibuffer.t '. => "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 @@ -123,7 +123,7 @@ Defining Commands::. (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. @@ -159,8 +159,8 @@ Reading File Names 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 . @@ -309,7 +309,7 @@ question. Otherwise, it uses keyboard input. 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 to mean yes and @@ -327,7 +327,7 @@ does not; but it seems best to describe them together. 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. @@ -342,18 +342,20 @@ does not; but it seems best to describe them together. ;; 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 ---------- @@ -361,7 +363,7 @@ does not; but it seems best to describe them together. 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 to finalize the @@ -382,7 +384,7 @@ does not; but it seems best to describe them together. ;; 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 ---------- @@ -396,7 +398,7 @@ does not; but it seems best to describe them together. 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. @@ -408,11 +410,11 @@ running on a window system, the functions `y-or-n-p' and `yes-or-no-p' 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. @@ -428,8 +430,8 @@ want to save this buffer" for each buffer in turn, you should use 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. @@ -494,7 +496,7 @@ facilities such as the ability to answer the whole series at once. 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 @@ -519,22 +521,22 @@ minibuffers. - 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). @@ -558,20 +560,20 @@ minibuffers. - 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 @@ -579,7 +581,7 @@ minibuffer by comparing it with the result of `(minibuffer-window)', 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. @@ -589,7 +591,7 @@ than one frame. 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 @@ -641,7 +643,7 @@ are done, and the subroutines that allow Lisp programs to do them. * 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. @@ -675,14 +677,14 @@ Key Lookup::, for information on how this is done. The result of the 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 @@ -690,10 +692,10 @@ the file name string as an ordinary Lisp function argument. 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. @@ -740,7 +742,7 @@ Using `interactive' 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 @@ -775,7 +777,7 @@ makes a Lisp function an interactively-callable command. 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) @@ -807,8 +809,8 @@ makes a Lisp function an interactively-callable command. 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: ") @@ -831,7 +833,7 @@ makes a Lisp function an interactively-callable command. 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 @@ -849,8 +851,7 @@ defined here as follows: Completion Provide completion. , , and 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 @@ -898,7 +899,7 @@ Special `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' @@ -914,12 +915,12 @@ Special 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 @@ -931,7 +932,7 @@ Special 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. @@ -940,7 +941,7 @@ Special 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. @@ -983,7 +984,7 @@ Special `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 or . (`C-q' may be used to include either of these characters in the input.) Prompt. @@ -1059,7 +1060,7 @@ definition, it invokes that definition using the function `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'. @@ -1073,12 +1074,12 @@ and calls the command. You can also call these functions yourself. 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 @@ -1096,7 +1097,7 @@ and calls the command. You can also call these functions yourself. 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. @@ -1111,9 +1112,9 @@ and calls the command. You can also call these functions yourself. 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'. diff --git a/info/lispref.info-17 b/info/lispref.info-17 index 15f004a..37d9cc3 100644 --- a/info/lispref.info-17 +++ b/info/lispref.info-17 @@ -1,5 +1,5 @@ -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 @@ -134,7 +134,7 @@ value at the end, like this: 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 @@ -184,7 +184,7 @@ command binding of the key sequence. 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: @@ -305,7 +305,7 @@ button-release 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 @@ -325,7 +325,7 @@ pointer-motion 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. misc-user event @@ -346,7 +346,7 @@ 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 @@ -390,7 +390,7 @@ eval event 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 @@ -432,39 +432,39 @@ Event Predicates 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.  @@ -497,18 +497,18 @@ Frame-Level Event Position Info 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 @@ -523,14 +523,14 @@ Window-Level Event Position Info 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 @@ -539,13 +539,13 @@ a mouse event occurred. `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 @@ -560,35 +560,35 @@ Event Text Position Info 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 @@ -611,23 +611,23 @@ Event Glyph Position Info 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 @@ -639,12 +639,12 @@ File: lispref.info, Node: Event Toolbar Position Info, Next: Other Event Posit 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. @@ -655,7 +655,7 @@ File: lispref.info, Node: Other Event Position Info, Prev: Event Toolbar Posit 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. @@ -669,39 +669,39 @@ Accessing the Other Contents of Events 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.  @@ -716,7 +716,7 @@ as an argument and fill in the fields of this event; or they make accept 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', @@ -770,7 +770,7 @@ latter case. 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 @@ -782,28 +782,28 @@ latter case. ;; Create an empty event. (make-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)) => # - + ;; Create a key-press event of dubious fame. (make-event 'key-press '(key escape modifiers (meta alt control shift))) => # - + ;; 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)) => # - + ;; Create a similar button-release event. (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x)) => # - + ;; Create a mouse-motion event. (make-event 'motion '(x 20 y 30)) => # @@ -831,13 +831,13 @@ latter case. (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 @@ -855,7 +855,7 @@ Converting Events 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 @@ -878,8 +878,8 @@ working with ASCII strings and with keymaps. 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'. @@ -904,7 +904,7 @@ working with ASCII strings and with keymaps. ambiguous, as both use the high bit; and 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. @@ -944,7 +944,7 @@ Key Sequence Input `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 @@ -994,7 +994,7 @@ single event. These functions often make a distinction between 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 @@ -1007,7 +1007,7 @@ and the window system. 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 @@ -1041,7 +1041,7 @@ and the window system. 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. @@ -1051,7 +1051,7 @@ File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, 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 @@ -1068,7 +1068,7 @@ specify a character, and allow the user to specify a control or meta 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 @@ -1163,7 +1163,7 @@ input. - 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 @@ -1201,7 +1201,7 @@ input comes in, while `sleep-for' pauses without updating the screen. 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 @@ -1224,7 +1224,7 @@ instead of a single argument that can be either an integer or a float. 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'. diff --git a/info/lispref.info-18 b/info/lispref.info-18 index 937c3df..00f586c 100644 --- a/info/lispref.info-18 +++ b/info/lispref.info-18 @@ -1,5 +1,5 @@ -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 @@ -69,7 +69,7 @@ effect is to cancel the prefix key as well as any prefix argument. 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 @@ -225,7 +225,7 @@ argument, either numeric or raw, in the `interactive' declaration. 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 @@ -234,32 +234,32 @@ value of the prefix argument directly in the variable 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. @@ -302,7 +302,7 @@ commands. `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 @@ -399,12 +399,12 @@ saying the command is disabled includes that string. For example: 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. @@ -439,7 +439,7 @@ considered complex. 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") @@ -448,7 +448,7 @@ considered complex. (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 @@ -467,12 +467,12 @@ Keyboard Macros 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. @@ -549,7 +549,7 @@ be any Lisp objects, though only certain types are meaningful for 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 @@ -604,7 +604,7 @@ Format of Keymaps 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.  @@ -615,7 +615,7 @@ Creating Keymaps 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". @@ -623,7 +623,7 @@ Creating Keymaps 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 @@ -635,16 +635,16 @@ Creating Keymaps 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 @@ -678,7 +678,7 @@ depth-first search of all the ancestors of the keymap is conducted. `(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. @@ -689,7 +689,7 @@ depth-first search of all the ancestors of the keymap is conducted. `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. @@ -701,11 +701,11 @@ format. Note that if you specify a default binding for a keymap, 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. @@ -740,7 +740,7 @@ and `(control 98)'. A keystroke may also be represented by an event 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. @@ -807,7 +807,7 @@ it is possible to redefine only one of those sequences like so: 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 @@ -845,7 +845,7 @@ their keymaps: * `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 - 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 @@ -882,7 +882,7 @@ The key sequence `C-p 6' is not found in any active keymap. (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 @@ -962,7 +962,7 @@ the maps. * 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"; @@ -985,7 +985,7 @@ completion and exit commands. *Note Intro to Minibuffers::. *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 @@ -1040,13 +1040,13 @@ completion and exit commands. *Note Intro to Minibuffers::. 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 @@ -1097,7 +1097,7 @@ completion and exit commands. *Note Intro to Minibuffers::. 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 diff --git a/info/lispref.info-19 b/info/lispref.info-19 index 6a53c4d..79195d7 100644 --- a/info/lispref.info-19 +++ b/info/lispref.info-19 @@ -1,5 +1,5 @@ -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 @@ -141,7 +141,7 @@ SYMBOL 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 @@ -170,7 +170,7 @@ Functions for Key Lookup 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 @@ -203,7 +203,7 @@ Functions for Key Lookup 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 @@ -211,7 +211,7 @@ Functions for Key Lookup 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. @@ -226,21 +226,21 @@ Functions for Key Lookup (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 @@ -259,9 +259,9 @@ Functions for Key Lookup 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 key. + a prefix event (*note Prefix Keys::). The default value is `?\^[' + (integer 27), which is the ASCII character usually produced by the + key. As long as the value of `meta-prefix-char' remains `?\^[', key lookup translates ` b' into `M-b', which is normally defined @@ -274,18 +274,14 @@ Functions for Key Lookup 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'. @@ -307,19 +303,19 @@ buffers (though it has no direct effect in buffers that shadow the 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 @@ -339,20 +335,17 @@ bindings in it: (setq map (make-sparse-keymap)) => # - (define-key map "\C-f" 'forward-char) => forward-char - map => # (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 => # (describe-bindings-internal map) @@ -361,16 +354,15 @@ bindings in it: 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' => # - + ;; Bind `C-f' to `foo' in the `ctl-x-map'. (define-key map "\C-p\C-f" 'foo) => foo - map => # (describe-bindings-internal map) @@ -409,8 +401,8 @@ Note that storing a new binding for `C-p C-f' actually works by 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'. @@ -434,7 +426,7 @@ the bindings of both `C-p C-f' and `C-x C-f' in the default global map. 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 @@ -447,7 +439,7 @@ the bindings of both `C-p C-f' and `C-x C-f' in the default global map. 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 @@ -461,7 +453,7 @@ the bindings of both `C-p C-f' and `C-x C-f' in the default global map. 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) @@ -501,7 +493,7 @@ redefines `C-x C-\' to move down a line. 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. @@ -509,7 +501,7 @@ set point where you click. == (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. @@ -519,7 +511,6 @@ set point where you click. (global-unset-key "\C-l") => nil - (global-set-key "\C-l\C-l" 'redraw-display) => nil @@ -529,7 +520,7 @@ set point where you click. == (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. @@ -537,7 +528,7 @@ set point where you click. == (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. @@ -555,7 +546,7 @@ Scanning Keymaps 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 @@ -622,7 +613,7 @@ information. 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 @@ -632,7 +623,7 @@ information. 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 characters since they are not really two-character sequences. @@ -642,11 +633,11 @@ information. 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. @@ -678,8 +669,8 @@ information. (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" @@ -694,7 +685,7 @@ information. `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. @@ -721,13 +712,13 @@ File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: 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. @@ -1023,12 +1014,12 @@ menubar. They are equivalent to doing the appropriate action to change `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. @@ -1087,7 +1078,7 @@ also specifies a particular item to be modified. For example, `("File" 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. @@ -1095,13 +1086,13 @@ the "Foo" submenu of "Menu". 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. @@ -1109,25 +1100,25 @@ the "Foo" submenu of "Menu". 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. @@ -1135,7 +1126,7 @@ the "Foo" submenu of "Menu". 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 @@ -1149,7 +1140,7 @@ a menubar specification, given a path to the item. 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. @@ -1161,14 +1152,14 @@ new code. 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. @@ -1176,7 +1167,7 @@ new code. 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 @@ -1192,7 +1183,7 @@ Menu Filters `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: @@ -1216,7 +1207,7 @@ description. `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: @@ -1239,7 +1230,7 @@ description. 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. diff --git a/info/lispref.info-20 b/info/lispref.info-20 index b30dff0..e14e62b 100644 --- a/info/lispref.info-20 +++ b/info/lispref.info-20 @@ -1,5 +1,5 @@ -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 @@ -55,9 +55,9 @@ File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying M 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 @@ -100,11 +100,11 @@ the binding for button3. 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. @@ -263,7 +263,7 @@ existence, and is updated dynamically. 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. @@ -334,9 +334,9 @@ File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: 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. @@ -372,7 +372,7 @@ the minibuffer when the mouse is over the button. 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 @@ -483,15 +483,15 @@ others specify blank areas in the toolbar. 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 @@ -531,9 +531,9 @@ thickness is controlled by the specifiers `top-toolbar-height', `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 @@ -543,7 +543,7 @@ Toolbar Variables::.). 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 @@ -568,11 +568,11 @@ this position. - 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::).  File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar @@ -688,7 +688,7 @@ File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: 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. @@ -732,7 +732,7 @@ File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols 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. @@ -873,7 +873,7 @@ writing a minor mode, which is often difficult). 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. @@ -1044,18 +1044,18 @@ conventions listed above: ;; 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 @@ -1070,12 +1070,10 @@ conventions listed above: (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. @@ -1093,26 +1091,24 @@ correspondingly more complicated. Here are excerpts from (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. @@ -1130,8 +1126,7 @@ mode functions: ;; 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 ?\| "\" " @@ -1140,8 +1135,7 @@ mode functions: 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) ...) @@ -1153,13 +1147,12 @@ and the Lisp modes need their own mode-specific `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. @@ -1198,14 +1191,12 @@ Emacs Lisp mode. 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. diff --git a/info/lispref.info-21 b/info/lispref.info-21 index e5391ea..c8cee5a 100644 --- a/info/lispref.info-21 +++ b/info/lispref.info-21 @@ -1,5 +1,5 @@ -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 @@ -64,11 +64,11 @@ visited. 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 @@ -131,7 +131,7 @@ visited. 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). @@ -147,7 +147,7 @@ visited. - 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 @@ -158,14 +158,13 @@ visited. (("^/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. @@ -203,7 +202,7 @@ visited. 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. @@ -246,7 +245,7 @@ Defining Derived Modes 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. @@ -373,7 +372,7 @@ minor modes. (> (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) @@ -433,11 +432,11 @@ appear the same (except for scrolling percentages and line numbers). 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. @@ -461,7 +460,7 @@ strings, symbols, and numbers kept in the buffer-local variable `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 @@ -524,7 +523,7 @@ value is a list, each element may be a list, a symbol, or a string. 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. @@ -783,8 +782,8 @@ name ends in `-hook'. 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' @@ -799,7 +798,7 @@ hook" as the last step of initialization. This makes it easy for a user 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: @@ -847,7 +846,7 @@ modified for a particular class of buffers only. 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 @@ -863,7 +862,7 @@ added with `add-hooks'. (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, @@ -892,7 +891,7 @@ added with `add-hooks'. 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 @@ -900,7 +899,7 @@ added with `add-hooks'. 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. @@ -979,7 +978,7 @@ rearranges the key bindings. (*Note Accessing Documentation::.) 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 @@ -991,7 +990,7 @@ variables (including primitive functions and autoloaded functions) is 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 @@ -1015,7 +1014,7 @@ File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation 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' @@ -1026,11 +1025,10 @@ Access to Documentation Strings (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 @@ -1053,8 +1051,7 @@ several symbols in a `*Help*' buffer. (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 @@ -1067,29 +1064,26 @@ several symbols in a `*Help*' buffer. 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)))) @@ -1102,16 +1096,15 @@ more information. ---------- 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 @@ -1119,7 +1112,7 @@ more information. 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 diff --git a/info/lispref.info-22 b/info/lispref.info-22 index 4204679..b11b775 100644 --- a/info/lispref.info-22 +++ b/info/lispref.info-22 @@ -1,5 +1,5 @@ -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 @@ -84,7 +84,7 @@ also call that function yourself. *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 @@ -95,7 +95,7 @@ XEmacs Lisp. (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}") @@ -108,11 +108,12 @@ XEmacs Lisp. RET minibuffer-complete-and-exit C-g abort-recursive-edit " + (substitute-command-keys "To abort a recursive edit from the minibuffer, type\ \\\\[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. @@ -142,14 +143,14 @@ convert non-printing and whitespace characters to sequences of printing 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 @@ -160,17 +161,14 @@ the character itself. (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 @@ -179,10 +177,8 @@ the character itself. (text-char-description ?\C-c) => "^C" - (text-char-description ?\M-m) => "M-m" - (text-char-description ?\C-\M-m) => "M-^M" @@ -197,10 +193,10 @@ to the user as subcommands of the prefix `C-h', or on some keyboards, `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 @@ -219,7 +215,7 @@ Here we describe some program-level interfaces to the same information. => (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) @@ -244,7 +240,7 @@ Here we describe some program-level interfaces to the same information. (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 @@ -291,7 +287,7 @@ Here we describe some program-level interfaces to the same information. 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 @@ -338,7 +334,7 @@ of that function should be told to use the newer one instead. XEmacs 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 @@ -348,16 +344,16 @@ what should be used instead. 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 @@ -373,13 +369,13 @@ the user is told about the obsoleteness and is forced to look at the 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 @@ -477,7 +473,7 @@ not alter it, the fastest way is to use `insert-file-contents' in 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. @@ -492,7 +488,7 @@ temporary buffer. Visiting the file is not necessary and takes longer. 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 @@ -516,7 +512,7 @@ temporary buffer. Visiting the file is not necessary and takes longer. 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 @@ -528,21 +524,21 @@ temporary buffer. Visiting the file is not necessary and takes longer. (find-file-noselect "/etc/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 @@ -582,13 +578,13 @@ Subroutines of Visiting `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. @@ -600,13 +596,13 @@ call them directly. => #> 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' @@ -635,7 +631,7 @@ copied into the buffer and the copy is what you edit. Changes to the 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. @@ -654,7 +650,7 @@ copying the contents of the buffer into the file. `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 @@ -674,7 +670,7 @@ copying the contents of the buffer into the file. 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>' @@ -741,7 +737,7 @@ copying the contents of the buffer into the file. - 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 @@ -762,8 +758,8 @@ Reading from Files 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 @@ -811,7 +807,7 @@ to a file on disk using the `append-to-file' and `write-region' 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 @@ -820,7 +816,7 @@ visited; that could cause confusion in the mechanisms for visiting. 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. @@ -877,7 +873,7 @@ still warn the user who saves second. Also, the detection of 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 @@ -886,7 +882,7 @@ cases of simultaneous editing; see *Note Modification Time::. (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 @@ -898,7 +894,7 @@ cases of simultaneous editing; see *Note Modification Time::. 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: @@ -953,7 +949,7 @@ Testing Accessibility 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 @@ -964,7 +960,7 @@ ways. 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. @@ -975,14 +971,14 @@ ways. (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 @@ -1000,7 +996,7 @@ ways. (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 @@ -1015,11 +1011,11 @@ ways. 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'. @@ -1049,7 +1045,7 @@ Distinguishing Kinds of Files 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 @@ -1068,7 +1064,7 @@ such as directories, symbolic links, and ordinary files. => "/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. @@ -1084,7 +1080,7 @@ such as directories, symbolic links, and ordinary files. (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). @@ -1096,13 +1092,13 @@ Truenames --------- 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. diff --git a/info/lispref.info-23 b/info/lispref.info-23 index cb2dcee..6f4fb86 100644 --- a/info/lispref.info-23 +++ b/info/lispref.info-23 @@ -1,5 +1,5 @@ -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 @@ -61,7 +61,7 @@ mode bits that control access permission, the owner and group numbers, 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 @@ -87,7 +87,7 @@ and modification. % 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 @@ -103,7 +103,7 @@ and modification. (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'. @@ -115,7 +115,7 @@ and modification. 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. @@ -227,8 +227,8 @@ of the argument OK-IF-ALREADY-EXISTS: * 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. @@ -272,7 +272,7 @@ of the argument OK-IF-ALREADY-EXISTS: 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 @@ -284,7 +284,7 @@ of the argument OK-IF-ALREADY-EXISTS: 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. @@ -296,7 +296,7 @@ of the argument OK-IF-ALREADY-EXISTS: 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. @@ -307,7 +307,7 @@ of the argument OK-IF-ALREADY-EXISTS: 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'. @@ -315,15 +315,15 @@ of the argument OK-IF-ALREADY-EXISTS: 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 @@ -404,7 +404,7 @@ number, but most of the time the file name actually used in XEmacs 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 @@ -417,7 +417,7 @@ directory lists. (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") @@ -428,8 +428,8 @@ directory lists. (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. @@ -446,7 +446,7 @@ directory lists. (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, @@ -479,7 +479,7 @@ acceptable. 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. @@ -489,7 +489,7 @@ such as `$HOME', and the constructs `~', and `..'. (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, @@ -508,7 +508,7 @@ abbreviation instead. 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. @@ -549,7 +549,7 @@ relative to a default directory; then it is called a "relative" file 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. @@ -573,7 +573,7 @@ you must specify the default directory name as well as the file name to 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 @@ -599,10 +599,10 @@ redundancies such as `./' and `NAME/../'. `~/' 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. @@ -628,7 +628,7 @@ redundancies such as `./' and `NAME/../'. 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 @@ -683,7 +683,7 @@ processes from trying to use the same name. 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 @@ -708,7 +708,7 @@ File Name Completion 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 @@ -730,7 +730,7 @@ name. For other completion functions, see *Note Completion::. (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. @@ -775,7 +775,7 @@ User Name Completion 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. @@ -783,7 +783,7 @@ name. For other completion functions, see *Note Completion::. 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. @@ -791,7 +791,7 @@ name. For other completion functions, see *Note Completion::. 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 @@ -812,8 +812,8 @@ or display the names in a buffer using the `ls' shell command. In the 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. @@ -847,8 +847,8 @@ depending on the value of switches passed to the `ls' command. 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. @@ -883,7 +883,7 @@ files that are directories. For example, you cannot delete a directory 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 @@ -893,7 +893,7 @@ directories. 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. @@ -991,14 +991,14 @@ that have two file names that may each have handlers. - 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. @@ -1009,7 +1009,7 @@ that have two file names that may each have handlers. 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. @@ -1062,7 +1062,7 @@ File: lispref.info, Node: Creating a Partial File, Next: Detached Partial File 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 @@ -1197,13 +1197,13 @@ buffer-local variable `buffer-file-format'. 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. @@ -1212,11 +1212,11 @@ the order of appearance in the list. `nil', no conversion takes place. Interactively, typing just 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 @@ -1226,7 +1226,7 @@ the order of appearance in the list. `nil', no conversion takes place. Interactively, typing just 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. @@ -1235,11 +1235,11 @@ the order of appearance in the list. `nil', no conversion takes place. Interactively, typing just 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 diff --git a/info/lispref.info-24 b/info/lispref.info-24 index 1233bf9..7d6e8a6 100644 --- a/info/lispref.info-24 +++ b/info/lispref.info-24 @@ -1,5 +1,5 @@ -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 @@ -72,7 +72,7 @@ visiting a file, and records the decision in the variable 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. @@ -89,11 +89,11 @@ visiting a file, and records the decision in the variable 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. @@ -307,7 +307,7 @@ automatically or it can ask the user whether to delete them. 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 @@ -331,14 +331,13 @@ Naming Backup Files 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 @@ -357,7 +356,7 @@ If you change one, you probably need to change the rest. 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. @@ -375,11 +374,11 @@ If you change one, you probably need to change the rest. (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 @@ -398,7 +397,7 @@ If you change one, you probably need to change the rest. (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. @@ -427,14 +426,14 @@ and the variables that control them. 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 @@ -529,7 +528,7 @@ and the variables that control them. 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. @@ -599,7 +598,7 @@ mind about them, you can get rid of them by reading in the previous 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. @@ -683,7 +682,7 @@ not be displayed in any windows. * 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. @@ -730,7 +729,7 @@ them, see *Note Buffer-Local Variables::. 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.  @@ -743,9 +742,9 @@ The Current Buffer 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. @@ -770,7 +769,7 @@ caller if the subroutine does not change which buffer is current (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) @@ -806,7 +805,7 @@ unbound. 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))) @@ -828,7 +827,7 @@ Using `save-excursion', as shown below, handles quitting, errors, and (current-buffer) => # - - 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 @@ -855,7 +854,7 @@ have names starting with a space, so that the `list-buffers' and `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. @@ -874,7 +873,7 @@ also initially disables recording undo information; see *Note Undo::. foo => # - - 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'. @@ -888,7 +887,7 @@ also initially disables recording undo information; see *Note Undo::. 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 @@ -905,7 +904,7 @@ also initially disables recording undo information; see *Note Undo::. 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 @@ -931,7 +930,7 @@ nondirectory part of the buffer file name, but the buffer file name and 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 @@ -972,10 +971,10 @@ Visiting Files::. 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") @@ -985,10 +984,10 @@ Visiting Files::. 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 @@ -1020,8 +1019,8 @@ record whether you have changed the text of the buffer. This flag is 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 @@ -1031,13 +1030,13 @@ file formerly visited. 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'. @@ -1047,14 +1046,14 @@ file formerly visited. (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. @@ -1072,7 +1071,7 @@ be what you want, but usually it would lose valuable information. 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. @@ -1098,7 +1097,7 @@ described below before saving the file. 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 @@ -1112,7 +1111,7 @@ described below before saving the file. 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 diff --git a/info/lispref.info-25 b/info/lispref.info-25 index 42513cf..7329de7 100644 --- a/info/lispref.info-25 +++ b/info/lispref.info-25 @@ -1,5 +1,5 @@ -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 @@ -72,7 +72,7 @@ that is independent of the buffer list orders for any particular frame. 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 @@ -96,7 +96,7 @@ It is only the order of those elements that is different. 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 @@ -128,14 +128,14 @@ It is only the order of those elements that is different. 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 @@ -162,11 +162,11 @@ with the specified name; `generate-new-buffer' always creates a new 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 @@ -181,7 +181,7 @@ can also create a buffer (*note Processes::.). 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 @@ -234,11 +234,11 @@ buffers, the indirect buffers are automatically killed as well. 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.) @@ -320,7 +320,7 @@ base buffer. 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. @@ -330,7 +330,7 @@ the base buffer kills all its indirect children. (make-indirect-buffer "*scratch*" "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 @@ -339,7 +339,7 @@ the base buffer kills all its indirect children. (buffer-base-buffer (get-buffer "indirect")) => # - - 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 @@ -404,8 +404,8 @@ has been used). *Note Current Buffer::. 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::.) @@ -454,7 +454,7 @@ Windows::, and *Note Size of Window::. *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.  @@ -466,13 +466,13 @@ Splitting Windows 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 @@ -497,7 +497,7 @@ previously visible in the window that was split. 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 @@ -524,21 +524,19 @@ previously visible in the window that was split. => # (window-edges) ; Edges in order: => (0 0 80 50) ; left-top-right-bottom - + ;; Returns window created (setq w2 (split-window w 15)) => # - (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 | |__________| @@ -552,19 +550,16 @@ previously visible in the window that was split. (setq w3 (split-window w 35 t)) => # - (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 | @@ -580,7 +575,7 @@ previously visible in the window that was split. 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. @@ -592,7 +587,7 @@ previously visible in the window that was split. (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. @@ -605,7 +600,7 @@ previously visible in the window that was split. (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 @@ -643,21 +638,21 @@ calling certain functions that delete windows. A deleted window cannot 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. @@ -667,14 +662,14 @@ among all the siblings.) 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. @@ -709,7 +704,7 @@ Selecting Windows 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 @@ -717,7 +712,7 @@ current buffer, and the cursor will appear in it. 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. @@ -732,7 +727,7 @@ current buffer, and the cursor will appear in it. (select-window w) => # - - 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 @@ -742,7 +737,7 @@ current buffer, and the cursor will appear in it. 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. @@ -765,7 +760,7 @@ offering various criteria for the choice. * 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 @@ -801,7 +796,7 @@ horizontal, the ordering is top to bottom in the left part, and so on. 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 @@ -852,12 +847,12 @@ the order is left to right, or top to bottom. (next-window (next-window (selected-window))) => # - - 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'. @@ -881,7 +876,7 @@ the order is left to right, or top to bottom. * 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. @@ -902,14 +897,14 @@ and specify a buffer for it. The functions described there are easier 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. @@ -917,7 +912,7 @@ window; use these functions when you need complete control. (window-buffer) => # - - 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 @@ -954,11 +949,11 @@ you more precise control. 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 @@ -979,7 +974,7 @@ access without affecting the display of buffers in windows. 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 @@ -991,8 +986,8 @@ access without affecting the display of buffers in windows. 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 @@ -1034,7 +1029,7 @@ access without affecting the display of buffers in windows. 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 @@ -1054,7 +1049,7 @@ display a buffer in--`display-buffer'. All the higher-level functions 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 @@ -1077,11 +1072,11 @@ and commands use this subroutine. Here we describe how to use 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 @@ -1168,7 +1163,7 @@ window, such as `display-buffer' might normally do. 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 @@ -1209,11 +1204,11 @@ window, such as `display-buffer' might normally do. 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. diff --git a/info/lispref.info-26 b/info/lispref.info-26 index 544c951..235bc4a 100644 --- a/info/lispref.info-26 +++ b/info/lispref.info-26 @@ -1,5 +1,5 @@ -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 @@ -80,7 +80,7 @@ to have multiple windows showing one buffer. 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. @@ -93,7 +93,7 @@ position of point in that buffer. "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. @@ -110,7 +110,7 @@ is called the "display-start" position of the window (or just the 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, @@ -124,7 +124,7 @@ inevitably, at the beginning of a text line. 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. @@ -138,7 +138,7 @@ inevitably, at the beginning of a text line. 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. @@ -189,7 +189,7 @@ inevitably, at the beginning of a text line. 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 @@ -236,7 +236,7 @@ names that fit the user's point of view. 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. @@ -246,7 +246,7 @@ that is displayed in the selected window. *Note Current Buffer::. `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. @@ -256,7 +256,7 @@ that is displayed in the selected window. *Note Current Buffer::. `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'. @@ -302,7 +302,7 @@ that is displayed in the selected window. *Note Current Buffer::. 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. @@ -361,14 +361,14 @@ far as to reduce the net horizontal scroll to zero. There is no limit 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 @@ -379,7 +379,7 @@ disappear off the left edge. 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. @@ -396,7 +396,7 @@ disappear off the left edge. (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. @@ -439,7 +439,7 @@ or various different fonts in the window. 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 @@ -452,7 +452,7 @@ or various different fonts in the window. (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 @@ -477,7 +477,7 @@ they wrap. This is usually the case for horizontally split windows but 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. @@ -489,7 +489,7 @@ not for full-frame windows. You can change this using the variables (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 @@ -506,20 +506,20 @@ not for full-frame windows. You can change this using the variables (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 @@ -537,7 +537,7 @@ The Position of a Window 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. @@ -561,15 +561,15 @@ comparison to other windows in the same frame. 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 @@ -588,7 +588,7 @@ that change the size of windows and low-level functions that access 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 @@ -614,20 +614,20 @@ windows, so resizing one window affects other windows. `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 @@ -639,14 +639,14 @@ windows, so resizing one window affects other windows. 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 @@ -717,7 +717,7 @@ Configurations::. 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 @@ -737,7 +737,7 @@ Configurations::. ...) (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 @@ -768,7 +768,7 @@ Configurations::. => 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, @@ -795,7 +795,7 @@ a TTY frame; instead, it starts with a single "X window frame". It can 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. @@ -826,7 +826,7 @@ Creating Frames 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. @@ -878,19 +878,19 @@ Access to Frame Properties 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. @@ -1001,12 +1001,12 @@ information in non-X frames. 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. @@ -1083,24 +1083,24 @@ in its usual fashion. 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 @@ -1124,7 +1124,7 @@ of the frame. A frame's name is used to look up its resources and does 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::. @@ -1160,7 +1160,7 @@ variable `frame-title-format'. 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 @@ -1188,11 +1188,11 @@ Deleting Frames 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. diff --git a/info/lispref.info-27 b/info/lispref.info-27 index fc1d7cc..7b2104f 100644 --- a/info/lispref.info-27 +++ b/info/lispref.info-27 @@ -1,5 +1,5 @@ -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 @@ -61,18 +61,18 @@ Finding All Frames 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 @@ -102,7 +102,7 @@ Finding All Frames 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. @@ -118,11 +118,11 @@ Frames and Windows 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. @@ -132,7 +132,7 @@ upper left corner, down and to the right, until it reaches the window at 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 @@ -140,7 +140,7 @@ frame". The significance of this designation is that selecting 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. @@ -159,7 +159,7 @@ Minibuffers and Frames 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 @@ -184,7 +184,7 @@ selected window always resides on the selected frame. As the focus 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. @@ -205,9 +205,9 @@ effect lasts until overridden by a subsequent call to `select-frame'. 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, @@ -224,17 +224,17 @@ number of the selected frame appears in the mode line after the word `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 @@ -254,26 +254,26 @@ frame is invisible, it doesn't show on the screen, not even as an icon. 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 @@ -282,7 +282,7 @@ one is actually displayed in any case. 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'. @@ -308,10 +308,10 @@ screen. 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 @@ -332,7 +332,7 @@ frame properties.) 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 @@ -356,7 +356,7 @@ all their properties, and the window configuration of each one. 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. @@ -380,7 +380,7 @@ frame's lifetime. *Note Hooks::. - 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 @@ -392,7 +392,7 @@ frame's lifetime. *Note Hooks::. 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 @@ -449,10 +449,10 @@ example the frame-creation functions) take an optional device argument 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: @@ -474,7 +474,7 @@ Basic Console Functions - 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. @@ -487,15 +487,15 @@ Basic Device Functions - 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.  @@ -536,23 +536,23 @@ particular "class", which describes other characteristics of the device `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. @@ -566,13 +566,13 @@ File: lispref.info, Node: Connecting to a Console or Device, Next: The Selecte 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 @@ -583,12 +583,12 @@ written in terms of `make-device'. 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. @@ -600,15 +600,15 @@ written in terms of `make-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. @@ -618,7 +618,7 @@ File: lispref.info, Node: The Selected Console and Device, Next: Console and D 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 @@ -628,10 +628,10 @@ The Selected Console and Device - 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 @@ -643,20 +643,20 @@ File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console a 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.  @@ -702,9 +702,9 @@ the character that immediately follows point; point is actually before 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, @@ -715,35 +715,35 @@ the buffer's point and the window's point normally have the same value, 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. @@ -786,7 +786,7 @@ Motion by Characters 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 @@ -804,7 +804,7 @@ Motion by Characters `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 @@ -815,7 +815,7 @@ Motion by Characters 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 @@ -835,7 +835,7 @@ Motion by Words 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 @@ -846,7 +846,7 @@ whether a given character is part of a word. *Note Syntax Tables::. 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. @@ -881,7 +881,7 @@ Likewise, to move to the end of the buffer, use: 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', @@ -893,7 +893,7 @@ they set the mark and display messages in the echo area. 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 @@ -918,12 +918,12 @@ newline. The division of the buffer into text lines is not affected by 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. @@ -943,7 +943,7 @@ tabs and control characters are displayed. 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 @@ -953,7 +953,7 @@ tabs and control characters are displayed. 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 @@ -963,7 +963,7 @@ tabs and control characters are displayed. 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 @@ -981,7 +981,7 @@ tabs and control characters are displayed. 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 @@ -1031,7 +1031,7 @@ thus take time proportional to the distance scanned. If you intend to 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 @@ -1050,7 +1050,7 @@ performance of your code. *Note cache-long-line-scans: Text Lines. 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 @@ -1061,7 +1061,7 @@ performance of your code. *Note cache-long-line-scans: Text Lines. 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 @@ -1095,29 +1095,29 @@ Expressions::, for lower-level primitives for scanning sexps or parts of 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 @@ -1135,18 +1135,18 @@ sexps. For user-level commands, see *Note Lists and Sexps: (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 @@ -1169,7 +1169,7 @@ Skipping Characters 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 @@ -1206,7 +1206,7 @@ related functions, see *Note Motion and Syntax::. 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. diff --git a/info/lispref.info-28 b/info/lispref.info-28 index 5fb9228..f4f4c69 100644 --- a/info/lispref.info-28 +++ b/info/lispref.info-28 @@ -1,5 +1,5 @@ -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 @@ -64,15 +64,15 @@ excursion. 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 @@ -87,7 +87,7 @@ Configurations::.). 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. @@ -104,21 +104,21 @@ Configurations::.). (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. @@ -146,7 +146,7 @@ which use them refuse to operate on text that is inaccessible. 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. @@ -154,17 +154,17 @@ save the entire buffer regardless of any narrowing. 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: @@ -173,13 +173,13 @@ save the entire buffer regardless of any narrowing. 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 @@ -194,7 +194,7 @@ save the entire buffer regardless of any narrowing. 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 @@ -262,8 +262,8 @@ deleted, so that it stays with the two characters on either side of it. * 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''.  File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers @@ -289,7 +289,7 @@ buffer. Relocation changes the integer equivalent of the marker. 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 @@ -386,24 +386,24 @@ is either an integer or a marker or either an integer, a character, or 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. @@ -425,7 +425,7 @@ marker. (make-marker) => # - - 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. @@ -437,13 +437,13 @@ marker. 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 @@ -465,7 +465,7 @@ marker. (point-max-marker) => # - - 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, @@ -525,11 +525,11 @@ Information from Markers 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. @@ -563,7 +563,7 @@ outside of your program, and, if so, what effects will result from 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. @@ -584,7 +584,7 @@ Emacs. (set-marker m 0 b) => # - - Function: move-marker MARKER POSITION &optional BUFFER + - Function: move-marker marker position &optional buffer This is another name for `set-marker'.  @@ -647,7 +647,7 @@ mark on the mark ring. The variable `mark-ring-max' specifies the 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. @@ -662,7 +662,7 @@ long, adding a new element deletes the last element. 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 @@ -684,10 +684,10 @@ long, adding a new element deletes the last element. 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 @@ -707,12 +707,12 @@ long, adding a new element deletes the last element. (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 @@ -721,7 +721,7 @@ long, adding a new element deletes the last element. 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'. @@ -795,7 +795,7 @@ the beginning and end of the region. This lets other Lisp programs 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 @@ -804,7 +804,7 @@ the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.) 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 @@ -872,7 +872,7 @@ the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.) - 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 @@ -891,12 +891,12 @@ Text 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 @@ -951,7 +951,7 @@ omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions 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 @@ -964,7 +964,7 @@ operated on the current buffer.) (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. @@ -988,32 +988,32 @@ operated on the current buffer.) (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. @@ -1029,8 +1029,8 @@ Examining Buffer Contents 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 @@ -1066,8 +1066,8 @@ Comparing Text 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. @@ -1104,7 +1104,7 @@ after point. 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 @@ -1126,13 +1126,13 @@ properties as the characters they were copied from. By contrast, 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 @@ -1142,21 +1142,21 @@ buffer, inherit their text properties from the neighboring text. 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 diff --git a/info/lispref.info-29 b/info/lispref.info-29 index 257c44c..7d0ee18 100644 --- a/info/lispref.info-29 +++ b/info/lispref.info-29 @@ -1,5 +1,5 @@ -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 @@ -59,12 +59,12 @@ User-Level Insertion Commands 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' @@ -75,7 +75,7 @@ programs. 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. @@ -83,9 +83,9 @@ programs. 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. @@ -125,15 +125,15 @@ Deleting Text ============= 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 @@ -146,12 +146,12 @@ return a value of `nil'. 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. @@ -164,7 +164,7 @@ return a value of `nil'. 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. @@ -177,7 +177,7 @@ return a value of `nil'. 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 @@ -232,7 +232,7 @@ programs. 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', @@ -254,6 +254,7 @@ programs. (delete-indentation) => nil + ---------- Buffer: foo ---------- When in the course of human-!- events, it becomes necessary ---------- Buffer: foo ---------- @@ -280,12 +281,12 @@ programs. 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) @@ -335,7 +336,7 @@ there are also specialized functions, described in this section, that 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 @@ -391,7 +392,7 @@ element. It uses the `last-command' variable to determine whether the 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'. @@ -403,7 +404,7 @@ to the most recent entry. 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 @@ -427,7 +428,7 @@ Functions for Yanking "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. @@ -443,7 +444,7 @@ the kill ring. The text properties are copied too. `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. @@ -476,7 +477,7 @@ lower level, but still convenient for use in Lisp programs. They take 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 @@ -490,13 +491,13 @@ Emacs version 18. `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 @@ -676,7 +677,7 @@ which is in the variable `buffer-undo-list'. `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 @@ -705,7 +706,7 @@ undo recording is initially disabled. You can explicitly enable or 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 @@ -715,8 +716,8 @@ disable undo recording with the following two functions, or by setting 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 @@ -761,14 +762,14 @@ inserting spaces to make the left and/or right margins line up 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 @@ -781,21 +782,21 @@ justification style for this part of the text (see 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 @@ -818,7 +819,7 @@ argument implies the value `full' for JUSTIFY. 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 @@ -831,7 +832,7 @@ argument implies the value `full' for JUSTIFY. 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'. @@ -901,7 +902,7 @@ Margins for Filling 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 @@ -915,12 +916,12 @@ Margins for Filling 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. @@ -938,7 +939,7 @@ Margins for Filling `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', @@ -947,7 +948,7 @@ Margins for Filling 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 diff --git a/info/lispref.info-30 b/info/lispref.info-30 index 1d25d6a..bfb3ed5 100644 --- a/info/lispref.info-30 +++ b/info/lispref.info-30 @@ -1,5 +1,5 @@ -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 @@ -57,11 +57,11 @@ Sorting Text 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. @@ -143,8 +143,8 @@ values returned by these functions are not meaningful. (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. @@ -206,29 +206,29 @@ values returned by these functions are not meaningful. 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. @@ -236,7 +236,7 @@ values returned by these functions are not meaningful. 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 @@ -281,7 +281,7 @@ arbitrarily high. The first (or leftmost) column is numbered 0. 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 @@ -343,7 +343,7 @@ primitives. 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 @@ -421,7 +421,7 @@ Indenting an Entire Region 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 @@ -455,7 +455,7 @@ region. They return unpredictable values. `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. @@ -470,8 +470,8 @@ region. They return unpredictable values. `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. @@ -487,7 +487,7 @@ Indentation Relative to Previous Lines 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 @@ -548,7 +548,7 @@ because the feature is similar to that of the tab stops on a 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 character as input uses this tab stop +Display::). Note that the character as input uses this tab stop feature only in a few major modes, such as Text mode. - Command: tab-to-tab-stop @@ -580,11 +580,11 @@ indentation in the text. 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'. @@ -599,7 +599,7 @@ buffer. *Note Character Case::, for case conversion commands that work 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 @@ -622,21 +622,21 @@ which characters are upper or lower case and how to convert them. 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 @@ -650,7 +650,7 @@ which characters are upper or lower case and how to convert them. 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 @@ -659,7 +659,7 @@ which characters are upper or lower case and how to convert them. 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 @@ -675,14 +675,14 @@ Text Properties =============== 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 @@ -724,17 +724,17 @@ to examine the properties of a number of characters at once. 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. @@ -767,20 +767,20 @@ name. 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. @@ -794,13 +794,13 @@ property changes are undoable (*note Undo::.). (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 @@ -812,7 +812,7 @@ property changes are undoable (*note Undo::.). 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. @@ -830,7 +830,7 @@ property changes are undoable (*note Undo::.). (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.  @@ -857,7 +857,7 @@ the buffer, if the property you are interested in does not change. 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 @@ -885,7 +885,7 @@ different properties. 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 @@ -902,19 +902,19 @@ different properties. 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. @@ -924,7 +924,7 @@ different properties. 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 @@ -1019,8 +1019,8 @@ Substituting for a Character Code 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. @@ -1028,7 +1028,7 @@ based on their character codes. 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'. @@ -1043,7 +1043,7 @@ based on their character codes. 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. @@ -1121,19 +1121,19 @@ otherwise stated. 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. @@ -1160,8 +1160,8 @@ Transposition of Text 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. diff --git a/info/lispref.info-31 b/info/lispref.info-31 index fdf8edd..138661a 100644 --- a/info/lispref.info-31 +++ b/info/lispref.info-31 @@ -1,5 +1,5 @@ -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 @@ -118,7 +118,7 @@ target digest. MD5 is used heavily by various authentication schemes. 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. @@ -146,7 +146,7 @@ binary bodies, and to encode binary characters in message headers. 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. @@ -169,7 +169,7 @@ binary bodies, and to encode binary characters in message headers. 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. @@ -179,7 +179,7 @@ binary bodies, and to encode binary characters in message headers. (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. @@ -190,7 +190,7 @@ binary bodies, and to encode binary characters in message headers. ;; 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. @@ -240,7 +240,7 @@ buffer. They are meant for use in programs, but you may call them 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, @@ -281,12 +281,12 @@ and NOERROR are set to `nil', and REPEAT is set to 1. 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. @@ -327,7 +327,7 @@ and NOERROR are set to `nil', and REPEAT is set to 1. 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 @@ -379,7 +379,7 @@ unless a `\' precedes it. 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 @@ -404,7 +404,7 @@ to use one of the special characters. Here is a list of them: 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 @@ -493,7 +493,7 @@ to use one of the special characters. Here is a list of them: `[^ ... ]' `[^' 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 @@ -527,7 +527,7 @@ to use one of the special characters. Here is a list of them: 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 `\'. @@ -660,7 +660,7 @@ match depends on the context. 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. `\<' @@ -675,7 +675,7 @@ exceptions, such as `[]]'), and so is a string that ends with a single `\'. 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 @@ -760,7 +760,7 @@ incrementally or not. Incremental search commands are described in the (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 @@ -801,7 +801,7 @@ useful in programs. The principal one is `re-search-forward'. 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. @@ -820,7 +820,7 @@ useful in programs. The principal one is `re-search-forward'. 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 @@ -849,7 +849,7 @@ useful in programs. The principal one is `re-search-forward'. (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 @@ -867,13 +867,13 @@ useful in programs. The principal one is `re-search-forward'. (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 @@ -904,7 +904,7 @@ POSIX Regular Expression Searching 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 @@ -917,22 +917,22 @@ functions only when you really need the longest match. 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. @@ -943,8 +943,8 @@ File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX R 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; @@ -1075,7 +1075,7 @@ numbered 1, the second 2, and so on. Only regular expressions can have 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 @@ -1090,7 +1090,7 @@ available is about the entire match. 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. @@ -1102,7 +1102,7 @@ available is about the entire match. 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. @@ -1164,8 +1164,8 @@ Replacing the Text That Matched 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. diff --git a/info/lispref.info-32 b/info/lispref.info-32 index 78abfe7..3173f9f 100644 --- a/info/lispref.info-32 +++ b/info/lispref.info-32 @@ -1,5 +1,5 @@ -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 @@ -85,7 +85,7 @@ entire match data, all at once. # #) - - 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'. @@ -116,7 +116,7 @@ that shows the problem that arises if you fail to save the 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. @@ -130,8 +130,8 @@ writing code that can run in Emacs 18. Here is how: (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::).  File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching @@ -190,7 +190,7 @@ used for certain purposes in editing: 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 @@ -208,7 +208,7 @@ never used. - 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). @@ -236,8 +236,8 @@ Syntax Tables 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: @@ -262,12 +262,12 @@ the syntactic use of each character in a buffer. 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 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). @@ -301,7 +301,7 @@ useful with character sets such as ISO Latin-1 that have additional 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 @@ -488,11 +488,11 @@ characters `1', `2', `3', `4', `b' and `p'. 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: @@ -571,7 +571,7 @@ Syntax Table Functions 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 @@ -579,13 +579,13 @@ altering syntax tables. 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 @@ -624,9 +624,9 @@ altering syntax tables. (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. @@ -648,11 +648,11 @@ altering syntax tables. (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. @@ -666,14 +666,14 @@ Motion and Syntax 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 @@ -681,7 +681,7 @@ version 18 or earlier. 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' @@ -701,8 +701,8 @@ these functions can be used for Lisp expressions when in Lisp mode and 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 @@ -757,7 +757,7 @@ higher-level functions for moving over balanced expressions. 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. @@ -782,7 +782,7 @@ higher-level functions for moving over balanced expressions. 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. @@ -813,7 +813,7 @@ higher-level functions for moving over balanced expressions. 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 @@ -860,7 +860,7 @@ Syntax Table Internals 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. @@ -933,7 +933,7 @@ abbrev table. Normally both are used. 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, @@ -986,11 +986,11 @@ Abbrev Tables 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 @@ -1001,7 +1001,7 @@ Abbrev Tables 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'. @@ -1021,7 +1021,7 @@ Defining Abbrevs `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, @@ -1032,7 +1032,7 @@ used by commands that ask for information from the user. 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. @@ -1063,7 +1063,7 @@ Saving Abbrevs in Files 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 @@ -1072,7 +1072,7 @@ in a file automatically, under the control of variables described here. - 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. @@ -1090,7 +1090,7 @@ in a file automatically, under the control of variables described here. 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'. @@ -1106,7 +1106,7 @@ including `self-insert-command'. This section describes the 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 @@ -1114,7 +1114,7 @@ they use for communication. 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 @@ -1125,7 +1125,7 @@ they use for communication. 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 diff --git a/info/lispref.info-33 b/info/lispref.info-33 index a4d32e0..9248a41 100644 --- a/info/lispref.info-33 +++ b/info/lispref.info-33 @@ -1,5 +1,5 @@ -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 @@ -61,7 +61,7 @@ other properties such as being read-only. Extents can overlap each 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: @@ -92,7 +92,7 @@ Extents can freely overlap each other in a buffer or string. Extents 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, @@ -158,30 +158,30 @@ File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoin 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. @@ -210,10 +210,10 @@ equivalent to `start-open' and `end-open' with the opposite sense. 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 @@ -228,20 +228,20 @@ open, the extent remains in the buffer, moving as necessary. 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'. @@ -262,11 +262,11 @@ Finding Extents 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 @@ -287,7 +287,7 @@ functions. To deal with this, functions typically mark their own 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 @@ -325,12 +325,12 @@ operation, you should probably use `mapcar-extents' or `map-extents', 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. @@ -346,10 +346,10 @@ called `map-extents'. You should read through the definition of this 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 @@ -426,7 +426,7 @@ using the `before' argument to `extent-at' (*note Finding Extents::.). 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', @@ -445,8 +445,8 @@ using the `before' argument to `extent-at' (*note Finding Extents::.). 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 @@ -456,8 +456,8 @@ the following function may be more convenient than `map-extents'. 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. @@ -470,7 +470,7 @@ the following function may be more convenient than `map-extents'. (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. @@ -497,21 +497,21 @@ from that parent (or from the root ancestor if the parent in turn has a 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. @@ -638,7 +638,7 @@ along with their allowable values. 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'. @@ -649,7 +649,7 @@ particular properties of an extent. 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'. @@ -657,26 +657,26 @@ particular properties of an extent. 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. @@ -684,38 +684,38 @@ particular properties of an extent. 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. @@ -734,21 +734,21 @@ this property is not set, the extent becomes a zero-length extent. (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 @@ -779,20 +779,20 @@ you cannot create an inheritance loop - this is explicitly disallowed. 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. @@ -811,12 +811,12 @@ strings, so that kill, yank, and undo commands will restore or copy it. * 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 @@ -874,7 +874,7 @@ highlighted when the mouse passes over it. Highlighting is accomplished 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 @@ -887,13 +887,13 @@ by merging the extent's face with the face or faces specified by 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. @@ -931,7 +931,7 @@ and `top-toolbar-height', is actually a specifier object. The 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: @@ -941,10 +941,10 @@ yield the real value of the property in that situation. (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. @@ -1058,10 +1058,10 @@ instantiable over that device. (A null tag set is perfectly valid.) 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 diff --git a/info/lispref.info-34 b/info/lispref.info-34 index bda5825..9b8b3d4 100644 --- a/info/lispref.info-34 +++ b/info/lispref.info-34 @@ -1,5 +1,5 @@ -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 @@ -195,7 +195,7 @@ fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more 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. @@ -203,32 +203,32 @@ information on toolbar specifiers. 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.  @@ -237,8 +237,8 @@ File: lispref.info, Node: Adding Specifications, Next: Retrieving Specificatio 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') @@ -290,8 +290,8 @@ Adding specifications to a Specifier 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 @@ -304,7 +304,7 @@ Adding specifications to a Specifier * 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 @@ -321,7 +321,7 @@ Adding specifications to a 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 @@ -355,7 +355,7 @@ Adding specifications to a Specifier (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 @@ -382,8 +382,8 @@ Adding specifications to a Specifier 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 @@ -397,8 +397,8 @@ Adding specifications to a Specifier 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). @@ -413,7 +413,7 @@ Adding specifications to a Specifier 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 @@ -427,8 +427,8 @@ Adding specifications to a Specifier 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). @@ -455,8 +455,8 @@ File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Funct 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. @@ -482,7 +482,7 @@ Retrieving the Specifications from a Specifier 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 @@ -507,7 +507,7 @@ Retrieving the Specifications from a Specifier 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 @@ -556,25 +556,25 @@ all tags in the tag set attached to that instantiator. 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 @@ -584,7 +584,7 @@ gets a null tag set, which matches all devices. 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. @@ -593,7 +593,7 @@ gets a null tag set, which matches all devices. 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.  @@ -602,8 +602,8 @@ File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Exam 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. @@ -655,8 +655,8 @@ Functions for Instancing a Specifier 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. @@ -738,7 +738,7 @@ File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Func 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 @@ -763,8 +763,8 @@ Creating New Specifier Objects `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 @@ -783,53 +783,53 @@ File: lispref.info, Node: Specifier Validation Functions, Next: Other Specific 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. @@ -839,8 +839,8 @@ File: lispref.info, Node: Other Specification Functions, Prev: Specifier Valid 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'. @@ -869,7 +869,7 @@ Other Functions for Working with Specifications in a Specifier 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, @@ -894,7 +894,7 @@ Other Functions for Working with Specifications in a Specifier 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. @@ -909,7 +909,7 @@ Other Functions for Working with Specifications in a 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.  @@ -945,11 +945,11 @@ for more information. 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: @@ -1019,7 +1019,7 @@ the corresponding property of the `default' face. 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 @@ -1029,20 +1029,20 @@ the corresponding property of the `default' face. 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::). diff --git a/info/lispref.info-35 b/info/lispref.info-35 index 75149c3..2b0ca0f 100644 --- a/info/lispref.info-35 +++ b/info/lispref.info-35 @@ -1,5 +1,5 @@ -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 @@ -100,8 +100,8 @@ the following functions. 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 @@ -159,7 +159,7 @@ the following functions. 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 @@ -204,8 +204,8 @@ the following functions. `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. @@ -254,69 +254,69 @@ File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display 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::. @@ -326,17 +326,17 @@ File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience 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'. @@ -366,7 +366,7 @@ File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts 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. @@ -376,11 +376,11 @@ File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Fo 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 @@ -399,15 +399,15 @@ File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev 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 @@ -420,21 +420,21 @@ File: lispref.info, Node: Font Instance Size, Next: Font Instance Characterist 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 @@ -447,27 +447,27 @@ File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenienc 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'. @@ -477,21 +477,21 @@ File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Char 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 @@ -519,7 +519,7 @@ File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors Color Specifiers ---------------- - - Function: color-specifier-p OBJECT + - Function: color-specifier-p object This function returns non-`nil' if OBJECT is a color specifier.  @@ -539,7 +539,7 @@ specifier is instanced in a particular domain. Functions such as 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.  @@ -548,10 +548,10 @@ File: lispref.info, Node: Color Instance Properties, Next: Color Convenience F 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. @@ -565,14 +565,14 @@ File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Pr 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 @@ -606,7 +606,7 @@ glyph object is made because the glyph includes other properties than 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: @@ -640,7 +640,7 @@ File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph 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 @@ -660,14 +660,14 @@ Creating Glyphs 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'. @@ -693,10 +693,10 @@ predefined meanings: 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 @@ -754,7 +754,7 @@ predefined meanings: 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 @@ -799,8 +799,8 @@ predefined meanings: `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. @@ -842,8 +842,8 @@ predefined meanings: 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, @@ -867,19 +867,19 @@ height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The 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 @@ -889,38 +889,38 @@ you probably aren't concerned with these.) 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 @@ -930,11 +930,11 @@ you probably aren't concerned with these.) 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.  @@ -943,22 +943,22 @@ File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, 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 diff --git a/info/lispref.info-36 b/info/lispref.info-36 index d389b0b..cac5eb8 100644 --- a/info/lispref.info-36 +++ b/info/lispref.info-36 @@ -1,5 +1,5 @@ -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 @@ -56,22 +56,22 @@ Image Specifiers ---------------- 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 @@ -262,7 +262,7 @@ implies that the file must exist when the instantiator is added to the 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 @@ -277,7 +277,7 @@ be a temporary file). `(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. @@ -298,7 +298,7 @@ File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances 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 @@ -315,7 +315,7 @@ Image Instantiator Conversion 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. @@ -333,7 +333,7 @@ instances; use a glyph instead. However, it may occasionally be useful 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: @@ -381,39 +381,39 @@ string, a mono pixmap, a color pixmap, etc. 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'. @@ -423,12 +423,12 @@ File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types 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 @@ -454,8 +454,8 @@ Image Instance Functions 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 @@ -465,32 +465,32 @@ Image Instance Functions 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 @@ -500,16 +500,16 @@ Image Instance Functions 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.) @@ -540,25 +540,25 @@ glyph's type. 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'. @@ -574,7 +574,7 @@ a glyph is a specifier, it can be controlled on a per-buffer, 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 @@ -629,7 +629,7 @@ per-frame, per-window, or per-device basis. 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 @@ -676,7 +676,7 @@ Subwindows Subwindows are not currently implemented. - - Function: subwindowp OBJECT + - Function: subwindowp object This function returns non-`nil' if OBJECT is a subwindow.  @@ -690,7 +690,7 @@ text but is displayed next to a particular location in a buffer. 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: @@ -802,8 +802,8 @@ File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, 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 @@ -820,11 +820,11 @@ Annotation Primitives 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. @@ -834,74 +834,74 @@ File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Pre 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.  @@ -910,16 +910,16 @@ File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: 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. @@ -959,12 +959,12 @@ of specifiers. *Note Specifiers::. 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. @@ -1028,12 +1028,12 @@ Refreshing the Screen 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. @@ -1108,12 +1108,12 @@ Filling::. - 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.) diff --git a/info/lispref.info-37 b/info/lispref.info-37 index 81d60dd..bb9e02e 100644 --- a/info/lispref.info-37 +++ b/info/lispref.info-37 @@ -1,5 +1,5 @@ -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 @@ -65,10 +65,10 @@ The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo 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 @@ -115,7 +115,7 @@ standard labels are: 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. @@ -125,7 +125,7 @@ the message stack. (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. @@ -139,7 +139,7 @@ the message stack. ;; 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. @@ -166,7 +166,7 @@ the message stack. 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. @@ -245,7 +245,7 @@ The recognized warning levels, in increased order of priority, are: `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. @@ -270,7 +270,7 @@ The recognized warning levels, in increased order of priority, are: 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 @@ -325,7 +325,7 @@ property or a property of an overlay. 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 @@ -383,8 +383,7 @@ the screen. 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 @@ -428,9 +427,9 @@ effect is seen only within XEmacs. 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 @@ -487,7 +486,7 @@ about to be executed. 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 @@ -514,7 +513,7 @@ Temporary Displays 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. @@ -557,8 +556,8 @@ Many of the help commands use this feature. 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. @@ -654,8 +653,7 @@ open parenthesis when the user inserts a close parenthesis. (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))) @@ -668,7 +666,7 @@ Usual Display Conventions 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. @@ -758,9 +756,9 @@ used. *Note Truncation::.) 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." @@ -826,7 +824,7 @@ a vector `nil' Display according to the standard interpretation (*note Usual - Display::.). + Display::).  File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display @@ -839,7 +837,7 @@ attract the user's attention. Be conservative about how often you do 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 @@ -851,7 +849,7 @@ beeping alone when signaling an error is appropriate. (*Note Errors::.) 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 @@ -936,21 +934,21 @@ beeping alone when signaling an error is appropriate. (*Note Errors::.) - 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. @@ -961,7 +959,7 @@ File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up 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: @@ -984,7 +982,7 @@ arbitrary Lisp objects called "keys" to other arbitrary Lisp objects 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". @@ -1067,33 +1065,33 @@ which specifies the initial hash table contents. 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'. @@ -1103,23 +1101,23 @@ File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, P 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. @@ -1187,7 +1185,7 @@ ranges of integers. 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: @@ -1205,7 +1203,7 @@ Introduction to Range Tables - 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. @@ -1216,21 +1214,21 @@ File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Ran 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. @@ -1241,7 +1239,7 @@ File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up Databases ********* - - Function: databasep OBJECT + - Function: databasep object This function returns non-`nil' if OBJECT is a database. * Menu: @@ -1256,7 +1254,7 @@ File: lispref.info, Node: Connecting to a Database, Next: Working With a Datab 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 @@ -1273,10 +1271,10 @@ Connecting to a Database 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'. diff --git a/info/lispref.info-38 b/info/lispref.info-38 index 2a2a68e..cfb33fd 100644 --- a/info/lispref.info-38 +++ b/info/lispref.info-38 @@ -1,5 +1,5 @@ -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 @@ -55,21 +55,21 @@ File: lispref.info, Node: Working With a Database, Next: Other Database Functi 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.  @@ -78,17 +78,17 @@ File: lispref.info, Node: Other Database Functions, Prev: Working With a Datab 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.  @@ -114,7 +114,7 @@ with the subprocess or to control it. For example, you can send 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: @@ -143,10 +143,10 @@ Functions that Create Subprocesses 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 @@ -160,8 +160,7 @@ contains a list of directories to search. Emacs initializes 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 @@ -182,7 +181,7 @@ program; it may not contain any command-line arguments. You must use 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 @@ -228,8 +227,8 @@ and quits immediately. *Note Quitting::. 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. @@ -297,7 +296,7 @@ In version 19, they return an indication of how the process terminated. ---------- Buffer: foo ---------- /usr/user/lewis/manual ---------- Buffer: foo ---------- - + (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") => nil @@ -314,8 +313,8 @@ In version 19, they return an indication of how the process terminated. (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 @@ -345,7 +344,7 @@ In version 19, they return an indication of how the process terminated. ---------- Buffer: foo ---------- input-!- ---------- Buffer: foo ---------- - + (call-process-region 1 6 "cat" nil t) => nil @@ -403,7 +402,7 @@ run in parallel with Emacs, and the two may communicate with each other 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 @@ -426,7 +425,7 @@ how to create an asynchronous process with `start-process'. (start-process "my-process" "foo" "sleep" "100") => # - + (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") => #> @@ -440,8 +439,8 @@ how to create an asynchronous process with `start-process'. 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 @@ -470,7 +469,7 @@ how to create an asynchronous process with `start-process'. To determine whether a given subprocess actually got a pipe or a PTY, use the function `process-tty-name' (*note Process - Information::.). + Information::).  File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes @@ -496,7 +495,7 @@ deleted automatically, no harm results. `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. @@ -504,12 +503,12 @@ deleted automatically, no harm results. (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")) @@ -536,14 +535,14 @@ Process Information (process-list) => (# #) - - 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") => # - - 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 @@ -552,17 +551,17 @@ Process Information (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). @@ -594,10 +593,8 @@ Process Information (process-status "shell") => run - (process-status (get-buffer "*shell*")) => run - x => #> (process-status x) @@ -610,18 +607,18 @@ Process Information 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 @@ -643,7 +640,7 @@ PTY. On these systems, Emacs sends an EOF periodically amidst the 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 @@ -653,7 +650,8 @@ do no harm. (process-send-string "shell<1>" "ls\n") => nil - + + ---------- Buffer: *shell* ---------- ... introduction.texi syntax-tables.texi~ @@ -662,7 +660,7 @@ do no harm. ... ---------- 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 @@ -672,7 +670,7 @@ do no harm. 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. @@ -736,7 +734,7 @@ support the distinction in the case of pipes. For the same reason, 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) @@ -744,17 +742,17 @@ job-control shells won't work when a pipe is used. See 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. @@ -763,12 +761,12 @@ job-control shells won't work when a pipe is used. See 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. @@ -807,19 +805,19 @@ normal practice only one process is associated with any given buffer. 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")) => # - - 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. @@ -840,11 +838,11 @@ always, the `process-mark' is at the end of the buffer. 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 @@ -855,7 +853,7 @@ always, the `process-mark' is at the end of the buffer. => # 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::).  File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes @@ -865,7 +863,7 @@ Process Filter Functions 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. @@ -878,9 +876,9 @@ terminal input, or for time to elapse, or for process output). This 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 @@ -909,8 +907,7 @@ Here is how to do these things: (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) @@ -946,7 +943,7 @@ insert into a dead buffer, it will get an error. If the buffer is dead, 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 @@ -954,7 +951,7 @@ of 200 characters one time, and five batches of 40 characters the next. 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. @@ -963,18 +960,14 @@ of 200 characters one time, and five batches of 40 characters the next. (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~ @@ -996,7 +989,7 @@ or terminal input. Occasionally it is useful in a Lisp program to 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 @@ -1045,7 +1038,7 @@ input, or for time to elapse, or for process output). This avoids the 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 @@ -1070,7 +1063,7 @@ or matching had to explicitly save and restore the match data. Now 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 @@ -1081,12 +1074,11 @@ Emacs does this automatically; sentinels never need to do it explicitly. (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: # had the event `killed' => # - - Function: process-sentinel PROCESS + - Function: process-sentinel process This function returns the sentinel of PROCESS, or `nil' if it has none. @@ -1102,7 +1094,7 @@ File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev 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. @@ -1117,14 +1109,14 @@ with subprocesses using transactions. First use `tq-create' to create 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. @@ -1139,7 +1131,7 @@ can call `tq-enqueue' to send a transaction. 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. @@ -1168,7 +1160,7 @@ function. It always returns either `open' or `closed' for a network 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. diff --git a/info/lispref.info-39 b/info/lispref.info-39 index 0227dd0..90be6be 100644 --- a/info/lispref.info-39 +++ b/info/lispref.info-39 @@ -1,5 +1,5 @@ -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 @@ -199,7 +199,7 @@ file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs. 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 @@ -208,7 +208,7 @@ it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does 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 @@ -217,8 +217,8 @@ this file with the option `-no-site-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' @@ -415,7 +415,7 @@ Killing XEmacs 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 @@ -469,7 +469,7 @@ case you can give input to some other job such as a shell merely by 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. @@ -490,14 +490,14 @@ when XEmacs is an X client. 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 @@ -506,22 +506,19 @@ when XEmacs is an X client. => (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! @@ -611,7 +608,7 @@ name of the system, the user's UID, and so on. 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' @@ -621,7 +618,7 @@ useful for constructing frame titles (*note Frame Titles::.). 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'. @@ -636,7 +633,7 @@ useful for constructing frame titles (*note Frame Titles::.). 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 @@ -651,8 +648,7 @@ useful for constructing frame titles (*note Frame Titles::.). => ("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") @@ -679,7 +675,7 @@ useful for constructing frame titles (*note Frame Titles::.). 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 @@ -708,7 +704,7 @@ useful for constructing frame titles (*note Frame Titles::.). - 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 @@ -731,7 +727,7 @@ User Identification 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 @@ -755,7 +751,7 @@ User Identification 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. @@ -776,7 +772,7 @@ User Identification 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. @@ -819,7 +815,7 @@ Time of Day 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 @@ -832,7 +828,7 @@ zone. 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" @@ -851,7 +847,7 @@ zone. 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. @@ -871,7 +867,7 @@ zone. 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::).  File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface @@ -882,10 +878,10 @@ Time Conversion 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 @@ -994,7 +990,7 @@ values from the functions `current-time' (*note Time of Day::.) and `%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: @@ -1035,8 +1031,8 @@ values from the functions `current-time' (*note Time of Day::.) and 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'. @@ -1059,7 +1055,7 @@ Timers for Delayed Execution 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 @@ -1091,7 +1087,7 @@ Timers for Delayed Execution (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 @@ -1121,7 +1117,7 @@ File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal 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 @@ -1189,7 +1185,7 @@ other input events before they become part of key sequences. 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 ` O P' when the keypad PF1 @@ -1274,7 +1270,7 @@ File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Termi 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. @@ -1294,7 +1290,7 @@ Recording Input 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'. @@ -1302,7 +1298,7 @@ Recording Input 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 @@ -1318,5 +1314,5 @@ Recording Input (open-dribble-file "~/dribble") => nil - See also the `open-termscript' function (*note Terminal Output::.). + See also the `open-termscript' function (*note Terminal Output::). diff --git a/info/lispref.info-40 b/info/lispref.info-40 index b79fe21..6cb3df7 100644 --- a/info/lispref.info-40 +++ b/info/lispref.info-40 @@ -1,5 +1,5 @@ -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 @@ -59,7 +59,7 @@ Terminal Output 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. @@ -82,13 +82,13 @@ the proper value, but others do not. If XEmacs has the wrong value, it 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. @@ -107,7 +107,7 @@ makes decisions that are less than optimal. To fix the problem, use (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 @@ -173,12 +173,12 @@ it: call the function `enable-flow-control'. 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: @@ -267,7 +267,7 @@ distinguished by "selection types", represented in XEmacs by symbols. 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. @@ -286,7 +286,7 @@ type. 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. @@ -296,11 +296,11 @@ store text or other data being moved between applications. Cut buffers 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 @@ -331,8 +331,8 @@ Resources 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. @@ -425,7 +425,7 @@ Resources `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. @@ -455,17 +455,17 @@ get information about the capabilities and origin of the X server 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'. @@ -478,7 +478,7 @@ File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server 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 @@ -486,10 +486,10 @@ Restricting Access to the Server by Other Apps 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 @@ -499,7 +499,7 @@ Restricting Access to the Server by Other Apps 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. @@ -521,13 +521,13 @@ Miscellaneous X Functions and Variables 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 @@ -538,7 +538,7 @@ Miscellaneous X Functions and Variables 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, @@ -649,7 +649,7 @@ File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example 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. @@ -682,20 +682,20 @@ Elisp Interface for Sending Messages 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_' function that @@ -731,8 +731,8 @@ Elisp Interface for Sending Messages `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 @@ -753,7 +753,7 @@ Elisp Interface for Sending Messages 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 @@ -774,7 +774,7 @@ Elisp Interface for Sending Messages 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 @@ -820,7 +820,7 @@ File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Exampl 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 @@ -857,13 +857,13 @@ Elisp Interface for Receiving Messages 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 @@ -877,7 +877,7 @@ Elisp Interface for Receiving Messages 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 @@ -890,11 +890,11 @@ Elisp Interface for Receiving Messages 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. @@ -924,12 +924,12 @@ Building XEmacs with LDAP support 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 () * University of Michigan's LDAP 3.3 - (`http://www.umich.edu/~dirsvcs/ldap/') + () - * LDAP SDK 1.0 from Netscape Corp. (`http://developer.netscape.com/') + * LDAP SDK 1.0 from Netscape Corp. () Other libraries conforming to RFC 1823 will probably work also but may require some minor tweaking at C level. @@ -980,7 +980,7 @@ LDAP Variables - 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 @@ -1043,16 +1043,15 @@ LDAP searches. Further support is planned in the future. 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'.  File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API @@ -1074,13 +1073,13 @@ The LDAP Lisp Object 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  @@ -1089,7 +1088,7 @@ File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Searchi 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: @@ -1133,7 +1132,7 @@ Opening and Closing a LDAP Connection 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  @@ -1148,11 +1147,11 @@ thus requiring a preliminary call to `ldap-open'. Multiple searches 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 diff --git a/info/lispref.info-41 b/info/lispref.info-41 index 73d9255..24be2e1 100644 --- a/info/lispref.info-41 +++ b/info/lispref.info-41 @@ -1,5 +1,5 @@ -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 @@ -55,17 +55,17 @@ File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: 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: @@ -74,7 +74,7 @@ Level 3 Primitives 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: @@ -85,7 +85,7 @@ Level 3 Primitives 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'. @@ -133,11 +133,11 @@ function body, before the `interactive' form. 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") @@ -146,8 +146,8 @@ to have a domain specification, because their documentation strings are 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") @@ -269,7 +269,7 @@ printing characters are considered). JISX0208, i.e. Japanese Kanji, 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 @@ -359,7 +359,7 @@ Charsets 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: @@ -474,14 +474,14 @@ File: lispref.info, Node: Basic Charset Functions, Next: Charset Property Func 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'. @@ -489,7 +489,7 @@ Basic Charset Functions - 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 @@ -499,19 +499,19 @@ Basic Charset Functions `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. @@ -525,54 +525,54 @@ Charset Property Functions 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. @@ -643,22 +643,22 @@ File: lispref.info, Node: MULE Characters, Next: Composite Characters, Prev: 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.  @@ -669,22 +669,22 @@ Composite Characters 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 @@ -898,7 +898,7 @@ symbol is accepted in place of the actual coding system object whenever 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: @@ -1107,7 +1107,7 @@ File: lispref.info, Node: Basic Coding System Functions, Next: Coding System P 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 @@ -1115,7 +1115,7 @@ Basic Coding System Functions 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'. @@ -1124,10 +1124,10 @@ Basic Coding System Functions 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 @@ -1139,11 +1139,11 @@ Basic Coding System Functions 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. @@ -1153,13 +1153,13 @@ File: lispref.info, Node: Coding System Property Functions, Next: Encoding and 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.  @@ -1168,8 +1168,8 @@ File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textu 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 @@ -1178,8 +1178,8 @@ Encoding and Decoding Text 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!8', `//', 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 @@ -363,10 +363,10 @@ Calling CCL 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 @@ -379,8 +379,8 @@ programs, and from Lisp using these functions: 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 @@ -398,7 +398,7 @@ programs, and from Lisp using these functions: 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. @@ -451,10 +451,10 @@ the character is in that category. 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'. @@ -462,21 +462,21 @@ have to directly manipulate bit vectors. 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. @@ -553,7 +553,7 @@ intended for widespread use: 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::. @@ -612,7 +612,7 @@ intended for widespread use: * 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. @@ -734,8 +734,8 @@ programs. 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 diff --git a/info/lispref.info-43 b/info/lispref.info-43 index 78cbdf4..aeb086b 100644 --- a/info/lispref.info-43 +++ b/info/lispref.info-43 @@ -1,5 +1,5 @@ -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 @@ -82,7 +82,7 @@ installed. 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 @@ -112,7 +112,7 @@ files even if they exist.) 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 @@ -129,11 +129,11 @@ override them if they wish. *Note Start-up Summary::. 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'). @@ -142,10 +142,10 @@ strings were moved out of the `xemacs' executable to make it smaller. 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 @@ -208,7 +208,7 @@ must increase the compilation parameter `PURESIZE' using the 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 @@ -650,143 +650,143 @@ automatically local (when set) in each buffer. Many Lisp packages 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::  File: lispref.info, Node: Standard Keymaps, Next: Standard Hooks, Prev: Standard Buffer-Local Variables, Up: Top diff --git a/info/lispref.info-44 b/info/lispref.info-44 index 1c75f09..82dbb65 100644 --- a/info/lispref.info-44 +++ b/info/lispref.info-44 @@ -1,5 +1,5 @@ -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 @@ -590,18 +590,18 @@ Index * 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. diff --git a/info/new-users-guide.info-1 b/info/new-users-guide.info-1 index 043aa9b..1c11e21 100644 --- a/info/new-users-guide.info-1 +++ b/info/new-users-guide.info-1 @@ -1,5 +1,5 @@ -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 @@ -51,7 +51,7 @@ Other Features of XEmacs - -- The Detailed Node Listing -- + --- The Detailed Node Listing --- Entering and Exiting Emacs @@ -617,7 +617,7 @@ Undo 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::. @@ -1149,14 +1149,14 @@ Pull-down Menus::. 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") diff --git a/info/new-users-guide.info-2 b/info/new-users-guide.info-2 index bbd6423..43e84c1 100644 --- a/info/new-users-guide.info-2 +++ b/info/new-users-guide.info-2 @@ -1,5 +1,5 @@ -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 @@ -546,7 +546,7 @@ if you set the variable MAKE-BACKUP-FILES to non-NIL i.e. `t', Emacs 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. @@ -596,9 +596,9 @@ turn on the auto-fill-mode, add the appropriate hook as shown in the 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) @@ -870,6 +870,7 @@ find any of them useful, just type them in your `.emacs' file: 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 diff --git a/info/new-users-guide.info-3 b/info/new-users-guide.info-3 index bc0bf7c..8a26339 100644 --- a/info/new-users-guide.info-3 +++ b/info/new-users-guide.info-3 @@ -1,5 +1,5 @@ -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 diff --git a/info/standards.info-1 b/info/standards.info-1 index 4ffe023..0ba5b2e 100644 --- a/info/standards.info-1 +++ b/info/standards.info-1 @@ -1,12 +1,12 @@ -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 @@ -28,20 +28,21 @@ File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir) 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  -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 ****************************** @@ -54,17 +55,17 @@ programs written in C, but many of the rules and principles are useful 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 +. 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.  -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 ************************** @@ -74,11 +75,11 @@ unencumbered. * Menu: -* Reading Non-Free Code:: Referring to Proprietary Programs -* Contributions:: Accepting Contributions +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions  -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 ================================= @@ -115,43 +116,54 @@ precisely when to free memory, or use a new GNU facility such as obstacks.  -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. +  -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 ********************** @@ -161,10 +173,10 @@ when designing your program. * 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  File: standards.info, Node: Compatibility, Next: Using Extensions, Up: Design Advice @@ -198,8 +210,6 @@ completely with something totally different and better. (For example, 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.  File: standards.info, Node: Using Extensions, Next: ANSI C, Prev: Compatibility, Up: Design Advice @@ -248,9 +258,16 @@ that use ANSI C features (and therefore will not work in non-ANSI 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) @@ -269,11 +286,22 @@ and use a separate declaration to specify the argument prototype: 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.  File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice @@ -284,13 +312,16 @@ Using Languages Other Than C 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 @@ -302,10 +333,14 @@ please write in C. 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. +  File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top @@ -318,10 +353,11 @@ how libraries should behave. * 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  @@ -330,21 +366,23 @@ File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior 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. @@ -380,11 +418,18 @@ for data that will not be changed. (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 @@ -395,7 +440,7 @@ are easy to examine with the debugger, so there is no point moving them 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. @@ -445,6 +490,16 @@ Formatting Error Messages 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: @@ -456,6 +511,10 @@ when there is an appropriate source file, or 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 @@ -472,7 +531,7 @@ usage messages, should start with a capital letter. But they should not end with a period.  -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 ===================================== @@ -487,7 +546,9 @@ select among the alternate behaviors. 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 @@ -520,27 +581,113 @@ consistent from program to program. For example, users should be able 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. + +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 a list of them, with their meanings, so we +can update the table. `after-date' `-N' in `tar'. @@ -590,6 +737,9 @@ requested information. `avoid-wraps' `-n' in `wdiff'. +`background' + For server programs, run in the background. + `backward-search' `-B' in `ctags'. @@ -710,6 +860,9 @@ requested information. `dereference-args' `-D' in `du'. +`device' + Specify an I/O device (special file name). + `diacritics' `-d' in `recode'. @@ -840,6 +993,10 @@ requested information. `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'. @@ -1012,7 +1169,7 @@ requested information. `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 . `macro-name' `-M' in `ptx'. @@ -1137,6 +1294,9 @@ requested information. `no-validate' Used in `makeinfo'. +`no-wait' + Used in `emacsclient'. + `no-warn' Used in various programs to inhibit warnings. @@ -1188,6 +1348,9 @@ requested information. `only-time' `-F' in `gprof'. +`options' + `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'. + `output' In various programs, specify the output file name. @@ -1272,6 +1435,9 @@ requested information. `prompt' `-p' in `ed'. +`proxy' + Specify an HTTP proxy. + `query-user' `-X' in `shar'. @@ -1279,9 +1445,8 @@ requested information. `-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' @@ -1392,13 +1557,18 @@ requested information. `-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'. @@ -1496,6 +1666,9 @@ requested information. `time' Used in `ls' and `touch'. +`timeout' + Specify how long to wait before giving up on some operation. + `to-stdout' `-O' in `tar'. @@ -1585,7 +1758,7 @@ requested information. `-z' in `gprof'.  -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 ============ @@ -1617,14 +1790,15 @@ writing GNU software. * 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'.  File: standards.info, Node: Formatting, Next: Comments, Up: Writing C @@ -1728,246 +1902,3 @@ pages at logical places (but not within a function). It does not matter 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. - -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 */ - - -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. - - -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. - - -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. - diff --git a/info/standards.info-2 b/info/standards.info-2 index 4473101..8fd19bd 100644 --- a/info/standards.info-2 +++ b/info/standards.info-2 @@ -1,12 +1,12 @@ -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 @@ -23,6 +23,271 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  +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 */ + + +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. + + +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. + + +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. + + File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C Portability between CPUs @@ -58,22 +323,24 @@ that pass their arguments along to `printf' and friends: 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.  File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C @@ -90,6 +357,10 @@ functions to avoid unnecessary loss of portability. * 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 @@ -184,7 +455,7 @@ defined in systems where the corresponding functions exist. One way to get them properly defined is to use Autoconf.  -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 ==================== @@ -212,35 +483,75 @@ translations for this package from the translations for other packages. 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." + +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.  File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top @@ -252,8 +563,9 @@ Documenting Programs * 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. @@ -265,28 +577,60 @@ GNU 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 @@ -294,32 +638,40 @@ the framework for a beginner to understand the rest of the manual. The 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.  -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 @@ -332,7 +684,22 @@ quickly reading just this part of its manual. for each program described.  -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. + + +File: standards.info, Node: NEWS File, Next: Change Logs, Prev: License for Manuals, Up: Documentation The NEWS File ============= @@ -358,17 +725,48 @@ Change Logs 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:: + + +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, @@ -376,12 +774,13 @@ the name of the changed file, and then in parentheses the name of the 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. + +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. @@ -398,43 +797,84 @@ and the asterisk when successive entries are in the same file. 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. + +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. + + +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.  File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation @@ -489,7 +929,7 @@ documentation. Copying from free documentation may be ok; please check with the FSF about the individual case.  -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 ******************* @@ -504,9 +944,9 @@ GNU software. * Menu: -* Configuration:: How Configuration Should Work +* Configuration:: How Configuration Should Work * Makefile Conventions:: Makefile Conventions -* Releases:: Making Releases +* Releases:: Making Releases  File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases @@ -523,12 +963,12 @@ they affect compilation. 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. @@ -604,8 +1044,8 @@ parts of the package: 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' @@ -668,7 +1108,8 @@ Makefile Conventions ==================== 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: @@ -677,6 +1118,8 @@ programs. * 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.  File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions @@ -710,14 +1153,16 @@ part of the make or `$(srcdir)/' if the file is an unchanging part of 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 @@ -741,349 +1186,18 @@ is best written as: 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'. - - -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. - - -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. - - -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'. diff --git a/info/standards.info-3 b/info/standards.info-3 index 426dd71..bac2c56 100644 --- a/info/standards.info-3 +++ b/info/standards.info-3 @@ -1,12 +1,12 @@ -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 @@ -23,7 +23,389 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -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. + + +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. + + +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. + + +File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions Standard Targets for Users -------------------------- @@ -68,17 +450,18 @@ Makefiles: 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. @@ -86,21 +469,30 @@ Makefiles: # 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' \ @@ -177,6 +569,12 @@ Makefiles: 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: @@ -203,7 +601,7 @@ Makefiles: 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 @@ -247,14 +645,120 @@ programs in which they are useful. not distributed with Texinfo.  +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. + + 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 @@ -263,6 +767,21 @@ files" and "non-source files". Source files are written by humans and 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 @@ -313,4 +832,32 @@ file. Leaving them out would make the distribution file a little smaller at the expense of possible inconvenience to a user who doesn't know what other files to get. + +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. + diff --git a/info/termcap.info-1 b/info/termcap.info-1 index d24e7ac..10aa505 100644 --- a/info/termcap.info-1 +++ b/info/termcap.info-1 @@ -1,5 +1,5 @@ -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. @@ -154,7 +154,7 @@ up the description of the terminal type in use. This is done by calling 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 @@ -236,7 +236,7 @@ of columns is named `co'. *Note Capabilities::, for definitions of all 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. @@ -366,8 +366,8 @@ application program should do two things: * 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. @@ -485,7 +485,7 @@ Performing Padding with `tputs' 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: @@ -510,7 +510,7 @@ characters. The value of `PC' is the character used for padding. 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 @@ -579,7 +579,7 @@ The language for parameter encoding is described in this section. 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: @@ -631,7 +631,7 @@ the following parameter. `%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 @@ -881,7 +881,7 @@ comments. 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: @@ -976,13 +976,13 @@ capability the value `ab:cd', it would also appear to define `cd' as a 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: @@ -996,7 +996,7 @@ in the string. `bs' and `pt', and many string-valued capabilities. Most of the strings start with 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::).  File: termcap.info, Node: Naming, Next: Inheriting, Prev: Capability Format, Up: Data Base @@ -1073,7 +1073,7 @@ are used for two reasons: `-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; @@ -1133,7 +1133,7 @@ to use that many lines. 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. diff --git a/info/termcap.info-2 b/info/termcap.info-2 index 156c7e7..fb9ec77 100644 --- a/info/termcap.info-2 +++ b/info/termcap.info-2 @@ -1,5 +1,5 @@ -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. @@ -36,7 +36,7 @@ For writing a terminal description, you must read each subsection and 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 @@ -76,7 +76,7 @@ should be omitted from terminal descriptions as well. * Meta Key:: 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. @@ -301,7 +301,7 @@ Even hardcopy terminals can support `nw'. 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 @@ -393,9 +393,8 @@ programs. 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. @@ -416,7 +415,7 @@ programs. 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.  File: termcap.info, Node: Wrapping, Next: Scrolling, Prev: Cursor Motion, Up: Capabilities @@ -441,7 +440,7 @@ column. 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 @@ -695,8 +694,7 @@ using any of these commands. 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. @@ -759,7 +757,7 @@ argument should be the total number of lines from the cursor to the 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'. @@ -867,15 +865,15 @@ of these capabilities. 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 @@ -895,7 +893,7 @@ of these capabilities. 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 diff --git a/info/termcap.info-3 b/info/termcap.info-3 index 973a2c1..35a54ef 100644 --- a/info/termcap.info-3 +++ b/info/termcap.info-3 @@ -1,5 +1,5 @@ -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. @@ -124,7 +124,7 @@ obsolete. 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 @@ -140,7 +140,7 @@ finds and removes the next `so' magic cookie on the screen. (It may 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. @@ -726,7 +726,7 @@ Summary of Capability Names 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. diff --git a/info/texinfo.info-10 b/info/texinfo.info-10 index 7b4fbcc..9944bfa 100644 --- a/info/texinfo.info-10 +++ b/info/texinfo.info-10 @@ -1,22 +1,22 @@ -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 @@ -33,1187 +33,1067 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -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_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'. - - -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 - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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 ' -(`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 immediately after -typing the Info `f' command, Info will attempt to go to the referenced -node. If you type `f catch ', 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. diff --git a/info/texinfo.info-11 b/info/texinfo.info-11 index 94a7f31..385b428 100644 --- a/info/texinfo.info-11 +++ b/info/texinfo.info-11 @@ -1,22 +1,22 @@ -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 @@ -33,816 +33,1190 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -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. - - @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 at the `?' prompt. +Capitalization +.............. - 2. You can tell TeX to continue running and to ignore all errors as - best it can by typing `r ' 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 ' 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 ' 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 `---' +............................. - -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. - -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_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'.  -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 + + +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.  -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' ------------------------ + +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. + + +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). + +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.  -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 ------------------------- + +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. - -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.  -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::.) + +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.  -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.  -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.  -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.  -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 -***************** + +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. + + +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.  -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. + + +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. + + +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 ' +(`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 immediately after +typing the Info `f' command, Info will attempt to go to the referenced +node. If you type `f catch ', 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').) diff --git a/info/texinfo.info-12 b/info/texinfo.info-12 index 84c76c7..4db996c 100644 --- a/info/texinfo.info-12 +++ b/info/texinfo.info-12 @@ -1,22 +1,22 @@ -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 @@ -33,609 +33,829 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -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. + + @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 at the `?' prompt. + + 2. You can tell TeX to continue running and to ignore all errors as + best it can by typing `r ' 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 ' 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 ' 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.) + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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: 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/'. + + +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. diff --git a/info/texinfo.info-3 b/info/texinfo.info-3 index e95f8a8..53de93d 100644 --- a/info/texinfo.info-3 +++ b/info/texinfo.info-3 @@ -1,22 +1,22 @@ -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 @@ -33,21 +33,115 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  +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.). + + +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. + + 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 @@ -69,9 +163,9 @@ start on a fresh odd-numbered page: 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. @@ -80,10 +174,11 @@ start on a fresh odd-numbered page: (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 @@ -93,37 +188,39 @@ and not in sequence with the rest of the document. 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.  -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 @@ -133,10 +230,43 @@ region formatting commands indent paragraphs as specified.) 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.  -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.) + + +File: texinfo.info, Node: End of Header, Prev: exampleindent, Up: Header End of Header ------------- @@ -181,8 +311,8 @@ and be put on a line by itself. 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 *'.  @@ -203,6 +333,11 @@ Info file. In addition, this part of the beginning of a Texinfo file 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. @@ -234,18 +369,21 @@ on a line by itself. 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.) @@ -258,9 +396,13 @@ commands to create a title page with black rules under the title and 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. @@ -283,7 +425,8 @@ a title page for a printed document. (This is the first of the two 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: @@ -316,7 +459,7 @@ for more information about the `@sp' command.) ... @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.  File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page @@ -326,8 +469,8 @@ File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions 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 @@ -335,7 +478,10 @@ beginning of a line followed by the title, subtitle, or author. 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. @@ -372,21 +518,20 @@ or you can write the names one above each other by using two (or more) ... @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.)  File: texinfo.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page @@ -427,10 +572,10 @@ itself has the following legally defined sequence: 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. @@ -493,6 +638,7 @@ after the `@end titlepage' command. 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. @@ -554,7 +700,7 @@ Text: Conditionals.) * Master Menu Parts:: A master menu has three or more parts.  -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 ---------------- @@ -571,7 +717,7 @@ information. It looks like this: ... @end titlepage - @ifinfo + @ifnottex @node Top, Copying, , (dir) @top Texinfo @@ -579,7 +725,7 @@ information. It looks like this: This is edition... ... - @end ifinfo + @end ifnottex @menu * Copying:: Texinfo is freely @@ -691,10 +837,10 @@ File: texinfo.info, Node: Ending a File, Next: Structuring, Prev: Beginning a 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: @@ -727,16 +873,16 @@ those just cause the raw data for the index to be accumulated. To 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 @@ -756,19 +902,16 @@ Precede the `@unnumbered' command with an `@node' line. @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::).  File: texinfo.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File @@ -779,14 +922,13 @@ Generating a Table of Contents 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' @@ -798,33 +940,43 @@ actual table to appear in the manual. To do this, you must use the 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  File: texinfo.info, Node: File End, Prev: Contents, Up: Ending a File @@ -857,7 +1009,7 @@ Contents.). 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. @@ -883,7 +1035,7 @@ heading at the top of each node--but you don't need to. * Raise/lower sections:: How to change commands' hierarchical level.  -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 ========================== @@ -921,8 +1073,8 @@ chapters. (*Note Nodes::, and see *Note Menus::.)  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 @@ -959,15 +1111,14 @@ that are listed in the table of contents of a printed book or manual. 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'  File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring @@ -978,9 +1129,15 @@ File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Comm 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.  File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring @@ -1014,8 +1171,8 @@ kind of stylistic choice is not usually offered by Texinfo.  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 @@ -1129,180 +1286,3 @@ produces In a printed manual, subsections are listed in the table of contents and are numbered three levels deep. - -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. - - -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 - ....................... - - -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. - - -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'. - - -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. - diff --git a/info/texinfo.info-4 b/info/texinfo.info-4 index 04bcd4c..27b9226 100644 --- a/info/texinfo.info-4 +++ b/info/texinfo.info-4 @@ -1,22 +1,22 @@ -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 @@ -33,6 +33,184 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  +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. + + +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 + ....................... + + +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. + + +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. + + +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. + + File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes Node and Menu Illustration @@ -41,9 +219,9 @@ 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. @@ -58,25 +236,27 @@ 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 @@ -135,19 +315,22 @@ chapter usually contains several nodes, one for each section, 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 @@ -157,8 +340,8 @@ Command Types.) 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: @@ -171,7 +354,7 @@ of this sentence, are made with `@xref' and its related commands; see * Top Node Summary:: Write a brief description for readers.  -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 ------------------------------- @@ -195,6 +378,12 @@ Also, it is helpful to include a brief description of the manual in the `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. +  File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node @@ -220,8 +409,8 @@ proper order. The comment line helps you keep track of which arguments 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 @@ -285,8 +474,10 @@ File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Nod 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: @@ -296,8 +487,9 @@ File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Nod @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: @@ -316,9 +508,9 @@ The First Node -------------- 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 @@ -398,33 +590,69 @@ include an edition number for the manual. (The title page should also contain this information: see *Note `@titlepage': titlepage.)  -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::.) + + +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.)  File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top @@ -433,15 +661,16 @@ Menus ***** "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: @@ -467,12 +696,6 @@ File: texinfo.info, Node: Menu Location, Next: Writing a Menu, Prev: Menus, 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 @@ -499,7 +722,7 @@ and title appear only in the Info file, not the printed document. 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::.  File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus @@ -526,7 +749,8 @@ command on a line by itself. 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.  File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus @@ -674,9 +898,9 @@ of each Info document. (*Note Install an Info File::.) (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.  File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top @@ -685,8 +909,8 @@ Cross References **************** "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: @@ -712,7 +936,7 @@ find information that should be presented to them as they need it. 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 @@ -727,15 +951,15 @@ reference names that manual. 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.  File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References @@ -810,10 +1034,10 @@ in a printed book. 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 @@ -902,7 +1126,7 @@ differently. *Note `@pxref': pxref.) 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. @@ -949,6 +1173,8 @@ which produces *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 @@ -1018,9 +1244,9 @@ a title or other section will divide it into two arguments. In 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: @@ -1068,331 +1294,3 @@ are different. for more information. @xref{Regexp, , Regular Expressions as Patterns}. - -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. - - -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. - - -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. - - -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. - - -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. - - -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 GNU ftp - site holds programs and texts. - - To merely indicate a URL, use `@url' (*note `@url': url.). - - -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. - diff --git a/info/texinfo.info-5 b/info/texinfo.info-5 index e7fea89..f0c7587 100644 --- a/info/texinfo.info-5 +++ b/info/texinfo.info-5 @@ -1,22 +1,22 @@ -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 @@ -33,6 +33,367 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  +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. + + +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. + + +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. + + +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. + + +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. + + +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 GNU ftp site 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 ls(1) 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: + + + +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 `', +since any software that tries to detect url's in text already has to +detect them without the ` 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.) + + +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.  -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} ------------------ @@ -420,7 +824,47 @@ produces The `.el' files are in the `/usr/local/emacs/lisp' directory.  -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. + + +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. + + +File: texinfo.info, Node: dfn, Next: cite, Prev: option, Up: Indicating `@dfn'{TERM} ------------ @@ -444,33 +888,52 @@ say explicitly that it is a definition, but it should contain the information of a definition--it should make the meaning clear.  -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.  -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. + + +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 .  File: texinfo.info, Node: email, Prev: url, Up: Indicating @@ -489,8 +952,7 @@ example: 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 . Send suggestions to the same place . @@ -506,7 +968,7 @@ Most often, this is the best way to mark words. However, sometimes you 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: @@ -514,16 +976,15 @@ regular use. * 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.  -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, @@ -535,19 +996,19 @@ produces *bold*. 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.  File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis @@ -555,10 +1016,10 @@ File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: E `@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. @@ -568,11 +1029,15 @@ This produces: 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'). @@ -584,7 +1049,7 @@ subsequent elements of a list (the CDR of the list), but you should use `@code' when the word refers to the Lisp function of the same spelling.  -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 ---------------------------- @@ -616,91 +1081,6 @@ you need to use one, it probably indicates a gap in the Texinfo language.  -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. - - -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'. - - File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top Quotations and Examples @@ -724,8 +1104,8 @@ on a line by itself, at the beginning of that line. * 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. @@ -734,12 +1114,13 @@ on a line by itself, at the beginning of that line. * cartouche:: How to draw cartouches around examples.  -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 @@ -749,28 +1130,31 @@ The Block Enclosing Commands 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. @@ -783,9 +1167,8 @@ to prevent the following text from being indented as a new paragraph. 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.  File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples @@ -843,9 +1226,8 @@ part of the running text, such as computer input or output. 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, @@ -857,11 +1239,11 @@ produces 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 @@ -870,7 +1252,7 @@ will appear in the output.) 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::.) @@ -879,7 +1261,7 @@ within sentences, not set off from preceding and following text. *Note `@code': code.)  -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' =========== @@ -920,10 +1302,10 @@ line, and neither does the `@end example' line. 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::).  -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' ======= @@ -937,66 +1319,65 @@ File: texinfo.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: 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.  -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.  -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.  -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 @@ -1008,11 +1389,15 @@ appeared in without the `@display' command. 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::. +  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 @@ -1023,6 +1408,10 @@ and an `@end format' command. As you can see 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::. +  File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples @@ -1096,349 +1485,3 @@ produces right justifies every line but leaves the left end ragged. - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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.) - diff --git a/info/texinfo.info-6 b/info/texinfo.info-6 index 5b8991a..20ec1e1 100644 --- a/info/texinfo.info-6 +++ b/info/texinfo.info-6 @@ -1,22 +1,22 @@ -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 @@ -33,6 +33,361 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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.) + + File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables `@ftable' and `@vtable' @@ -45,8 +400,7 @@ automatically enters each of the items in the first column of the table 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 @@ -110,7 +464,7 @@ completes the table. Details in the sections below. * Multitable Rows:: Defining multitable rows, with examples.  -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 ------------------------ @@ -128,7 +482,7 @@ entirely on the same line as the `@multitable' command. 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: @@ -159,7 +513,7 @@ not special within the table body, and you may break input lines in 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 @@ -179,22 +533,22 @@ your source file as necessary. 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.  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 @@ -224,8 +578,8 @@ Making Index Entries ==================== 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, @@ -322,7 +676,7 @@ case-sensitive, so use upper and lower case as required for them. 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: @@ -345,21 +699,9 @@ emphasis (*note Marking Text::.). 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 @@ -525,7 +867,7 @@ roman font. Thus, it parallels the `@findex' command rather than the 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::).  File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top @@ -551,6 +893,7 @@ elements that do not correspond to simple characters you can type. * 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.  @@ -609,20 +952,20 @@ various kinds within and after sentences. * dmn:: How to format a dimension.  -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 @@ -669,8 +1012,7 @@ for `@!' and `@?'. 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. @@ -704,7 +1046,7 @@ produces 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. @@ -734,10 +1076,10 @@ produces 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::.  File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions @@ -748,46 +1090,46 @@ Inserting Accents 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} 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 - - -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'. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - diff --git a/info/texinfo.info-7 b/info/texinfo.info-7 index 4ae5118..1e55bb3 100644 --- a/info/texinfo.info-7 +++ b/info/texinfo.info-7 @@ -1,22 +1,22 @@ -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 @@ -33,6 +33,448 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  +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 + + +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. + + +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. + + +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::. + + +File: texinfo.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands + + (1) Here is the sample footnote. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + +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. + + File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks `@group': Prevent Page Breaks @@ -97,7 +539,7 @@ the page. It looks like this: the bottoms of printed pages).  -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 ******************* @@ -162,7 +604,7 @@ For example, produces - - Command: forward-word COUNT + - Command: forward-word count This function moves point forward COUNT words (or backward if COUNT is negative). ... @@ -205,7 +647,7 @@ Thus, produces - - Function: buffer-end FLAG + - Function: buffer-end flag This function returns `(point-min)' if FLAG is less than 1, `(point-max)' otherwise. ... @@ -277,8 +719,8 @@ produces - 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. @@ -383,7 +825,7 @@ similar entities: `@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'.  @@ -399,7 +841,7 @@ Variables and Similar Entities 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. @@ -445,7 +887,7 @@ Variables and Similar Entities `@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'. @@ -644,8 +1086,7 @@ it. Otherwise, it is printed in the usual text font. 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 @@ -658,13 +1099,19 @@ it. Otherwise, it is printed in the usual text font. 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. @@ -700,7 +1147,6 @@ it. Otherwise, it is printed in the usual text font. operation, and its arguments, if any. The template is: - @defop CATEGORY CLASS NAME ARGUMENTS... BODY-OF-DEFINITION @end defop @@ -708,20 +1154,25 @@ it. Otherwise, it is printed in the usual text font. `@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 @@ -803,10 +1254,10 @@ A Sample Function Definition 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. @@ -836,7 +1287,6 @@ Functions. 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 @@ -865,7 +1315,7 @@ Functions. @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 @@ -875,147 +1325,27 @@ Index under `apply'. that for functions except that variables do not take arguments.  -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. - - -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. - - -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)'. - - -File: texinfo.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands - - (1) Here is the sample footnote. - - -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. - -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: @@ -1027,7 +1357,7 @@ and which is for the Info file. flag to a string that you can insert.  -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 ==================== @@ -1035,7 +1365,7 @@ 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::.) @@ -1054,16 +1384,15 @@ output. @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.  File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals @@ -1071,7 +1400,7 @@ File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Comman 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 @@ -1084,317 +1413,6 @@ lines by themselves.) 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'. - - -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.) - - -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. - - -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. - - -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. - - -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. - - -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. - - -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::). diff --git a/info/texinfo.info-8 b/info/texinfo.info-8 index 1f59eb6..9ebe6f2 100644 --- a/info/texinfo.info-8 +++ b/info/texinfo.info-8 @@ -1,22 +1,22 @@ -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 @@ -33,7 +33,476 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  -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.) + + +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. + + +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. + + +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. + + +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. + + +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. + + +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 + + +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 `' tag is +included in the `' of the output: + + + + +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. + + +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 + + +File: texinfo.info, Node: Invoking Macros, Next: Macro Details, Prev: Defining Macros, Up: Defining New Texinfo Commands Invoking Macros =============== @@ -41,9 +510,9 @@ 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} @@ -57,32 +526,192 @@ produces: 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. + + +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. + + + +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.  -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. + + +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 @@ -100,41 +729,43 @@ print queue, and delete a job from the print queue. * 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.  -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::).  -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: @@ -144,15 +775,15 @@ 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 @@ -169,16 +800,16 @@ you can use `??' as shell wildcards and give the command in this form: 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, @@ -187,7 +818,7 @@ this time with up-to-date index entries. 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 @@ -201,36 +832,71 @@ numbers in the cross-references correct. 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::). +  -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'.  -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' ========================== @@ -240,7 +906,7 @@ installation, but `lpr -d' is common. The command may require the DVI 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 @@ -256,8 +922,35 @@ these are commonly used versions.) 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'. +  -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 =================== @@ -265,7 +958,7 @@ 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 @@ -282,7 +975,7 @@ from a shell within Emacs: and printing in Texinfo mode.  -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 ======================================= @@ -322,9 +1015,9 @@ recentering the display of the buffer in which the operations occur. `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' @@ -369,13 +1062,20 @@ variables. The default values are: 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.  -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 ============================== @@ -393,10 +1093,10 @@ Emacs runs the compile command. For example, at the end of the 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.  -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 =================================== @@ -405,7 +1105,7 @@ 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. @@ -424,21 +1124,26 @@ command, a title page, a copyright page, and permissions. Besides an `@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::  -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. @@ -454,17 +1159,17 @@ and TeX will find it there. 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', @@ -490,12 +1195,40 @@ sequence: 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'. + + +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.  -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" ================= @@ -506,26 +1239,39 @@ interprets as a long word that it cannot hyphenate, such as an 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, @@ -534,7 +1280,7 @@ before the `@titlepage' command: @finalout  -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 ====================== @@ -547,719 +1293,20 @@ file, before the title page: @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. - - -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. - - -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. - - -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. - - -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'. - - -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. - - -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. - - -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. - - -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 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. - - -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::.). - - -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.) - - -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::. - - -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. - - -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.) - - -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'. - - -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. diff --git a/info/texinfo.info-9 b/info/texinfo.info-9 index d344328..58344b0 100644 --- a/info/texinfo.info-9 +++ b/info/texinfo.info-9 @@ -1,22 +1,22 @@ -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 @@ -33,10 +33,930 @@ versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  +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. + + +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'. + + +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. + + +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. + + +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:: + + +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. + + +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'. + + +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. + + +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. + + +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. + + +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 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. + + +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::). + + +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.) + + +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::. + + +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 `' 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. + + +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. + + +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'. + + +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'. + + +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. + + +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. + + +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. + + 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'. @@ -44,11 +964,11 @@ Normally the makefile for the package runs `install-info', just after 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 @@ -74,34 +994,45 @@ beginning of the Texinfo input, before the first `@node' command. If 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.  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' @@ -110,10 +1041,12 @@ creates it if possible (with no entries). `.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 @@ -121,15 +1054,19 @@ creates it if possible (with no entries). 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 @@ -139,1005 +1076,17 @@ creates it if possible (with no entries). 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. - -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 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: @@ -437,7 +437,7 @@ Q3.1.8: `-iconic' doesn't work. `-unmapped' on the command line, and setting the `initiallyUnmapped' X Resource don't seem to help much either... - Ben Wing writes: + Ben Wing writes: Ugh, this stuff is such an incredible mess that I've about given up getting it to work. The principal problem is numerous @@ -763,7 +763,7 @@ bound to keys. 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::).  File: xemacs-faq.info, Node: Q3.5.2, Next: Q3.5.3, Prev: Q3.5.1, Up: Customization @@ -799,7 +799,7 @@ and Wayne Newberry ) to `.emacs': 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).  File: xemacs-faq.info, Node: Q3.5.4, Next: Q3.5.5, Prev: Q3.5.3, Up: Customization @@ -876,8 +876,8 @@ Q3.5.6: How to map `Help' key alone on Sun type4 keyboard? (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 @@ -987,7 +987,7 @@ effect of being able to press and release Shift and have the next character typed come out in upper case. This will affect all the other modifier keys like Control and Meta as well. - Ben Wing writes: + Ben Wing 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" diff --git a/info/xemacs-faq.info-4 b/info/xemacs-faq.info-4 index ddfcd27..805e13f 100644 --- a/info/xemacs-faq.info-4 +++ b/info/xemacs-faq.info-4 @@ -1,5 +1,5 @@ -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 @@ -160,6 +160,7 @@ Other Mail & News: 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? @@ -243,7 +244,7 @@ Q4.0.6: I have various addresses at which I receive mail. How can I tell VM to (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. @@ -385,7 +386,7 @@ Q4.0.12: Customization of VM not covered in the manual, or here. 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 @@ -440,7 +441,7 @@ Q4.2.1: GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus, Quassia Gnus, argh! -------------------------------------------------------------------------------- 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/' @@ -569,7 +570,7 @@ File: xemacs-faq.info, Node: Q4.3.3, Next: Q4.3.4, Prev: Q4.3.2, Up: Subsyst Q4.3.3: Why isn't this `movemail' program working? -------------------------------------------------- - Ben Wing writes: + Ben Wing writes: It wasn't chown'ed/chmod'd correctly. @@ -579,12 +580,12 @@ File: xemacs-faq.info, Node: Q4.3.4, Next: Q4.3.5, Prev: Q4.3.3, Up: Subsyst Q4.3.4: Movemail is also distributed by Netscape? Can that cause problems? --------------------------------------------------------------------------- - Steve Baur writes: + Steve Baur 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 notes at + Please refer to Jamie Zawinski's 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 @@ -613,7 +614,7 @@ Q4.3.5: Where do I find pstogif (required by tm)? `ftp://ftp.cdrom.com/pub/tex/ctan/support/latex2html/'.  -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 ================================== @@ -650,17 +651,45 @@ time. 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'. + +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))  -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 ============= @@ -939,8 +968,7 @@ Q4.7.5: Is there a MatLab mode? Can I "teach" emacs what words are MatLab commands, comments, etc. ? Ulrich Elsner 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. @@ -1002,7 +1030,7 @@ Miscellaneous: * 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? @@ -1098,7 +1126,7 @@ standard with XEmacs. Put this into your `.emacs': 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 fill '. Note that well-behaving text-lookalike modes will run @@ -1330,37 +1358,3 @@ enabled by default. To turn it off, put the following in your `.emacs': (setq auto-show-mode nil) (setq-default auto-show-mode nil) - -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. - - -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 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'? - - -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 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::.). - diff --git a/info/xemacs-faq.info-5 b/info/xemacs-faq.info-5 index f7ed4c3..e67a395 100644 --- a/info/xemacs-faq.info-5 +++ b/info/xemacs-faq.info-5 @@ -1,5 +1,5 @@ -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 @@ -7,6 +7,40 @@ START-INFO-DIR-ENTRY END-INFO-DIR-ENTRY  +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. + + +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 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'? + + +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 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::). + + 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? @@ -306,7 +340,7 @@ performance: 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 @@ -391,7 +425,7 @@ Q5.1.11: My elisp program is horribly slow. Is there an easy way to find out where it spends time? - zHrvoje Niksic writes: + zHrvoje Niksic writes: Under XEmacs 20.4 and later you can use `M-x profile-key-sequence', press a key (say in the Gnus Group buffer), and get the results using `M-x profile-results'. It @@ -745,10 +779,10 @@ Q5.3.11: How do I add new Info directories? 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 @@ -897,7 +931,7 @@ Q6.0.4: Procedural changes in XEmacs development. XEmacs 19.16 was the last 19 release, basically consisting of 19.15 plus the collected bugfixes. - 3. As of December 1996, Steve Baur has - become the lead maintainer of XEmacs. + 3. As of December 1996, Steve Baur has become the + lead maintainer of XEmacs. diff --git a/info/xemacs.info-10 b/info/xemacs.info-10 index 082ad0c..1cb91de 100644 --- a/info/xemacs.info-10 +++ b/info/xemacs.info-10 @@ -1,5 +1,5 @@ -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 @@ -145,7 +145,7 @@ comment gets too long, the text of the comment is split into two 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 @@ -188,7 +188,7 @@ undone with `C-_'. *Note Undo::. 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. @@ -325,31 +325,30 @@ Editing Programs 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. diff --git a/info/xemacs.info-11 b/info/xemacs.info-11 index c9ba3be..7e31e57 100644 --- a/info/xemacs.info-11 +++ b/info/xemacs.info-11 @@ -1,5 +1,5 @@ -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 @@ -95,7 +95,7 @@ broken up into files. It lists the names of the component files and the 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 @@ -115,13 +115,14 @@ recorded is called a "tag". * 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.  -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 ---------------------- @@ -129,23 +130,26 @@ 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', @@ -155,7 +159,7 @@ Source File Tag Syntax 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 @@ -174,6 +178,10 @@ Source File Tag Syntax 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. @@ -181,32 +189,36 @@ Source File Tag Syntax 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.  -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 -------------------- @@ -218,10 +230,18 @@ Here is how to run `etags': 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 @@ -258,7 +278,7 @@ files. 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 @@ -274,8 +294,17 @@ the file names that follow it. Specify `--language=auto' to tell `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. + + +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. @@ -300,9 +329,15 @@ N times. 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 @@ -317,30 +352,65 @@ additional tags in `voo.doo', and both REG1 and REG2 to recognize 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 ' 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/'  -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 ---------------------- @@ -508,7 +578,7 @@ Searching and Replacing with Tags Tables 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 REGEXP ' Search for REGEXP through the files in the selected tags table. @@ -806,7 +876,7 @@ standard Emacs comment commands and defines some new variables. 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'). @@ -915,7 +985,7 @@ Fortran Keyword Abbrevs 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 @@ -1020,7 +1090,7 @@ line is used again. The first `M-x compile' provides `make -k' as the 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 @@ -1106,7 +1176,7 @@ Lisp mode 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. @@ -1123,7 +1193,7 @@ Libraries of Lisp Code for Emacs 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: diff --git a/info/xemacs.info-12 b/info/xemacs.info-12 index f5b2a5c..5192c01 100644 --- a/info/xemacs.info-12 +++ b/info/xemacs.info-12 @@ -1,5 +1,5 @@ -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 @@ -323,7 +323,7 @@ usual Emacs editing commands are available; you can switch windows to 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. @@ -442,7 +442,7 @@ will go into the buffer, advancing point, and any "terminal input" for 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 . 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 diff --git a/info/xemacs.info-13 b/info/xemacs.info-13 index d59e716..b6611e5 100644 --- a/info/xemacs.info-13 +++ b/info/xemacs.info-13 @@ -1,5 +1,5 @@ -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 @@ -50,7 +50,7 @@ character on the line. There was no need to change `C-a', as the choice 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. runs `picture-newline', which just moves to the beginning of the following @@ -73,7 +73,7 @@ below the current line. 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::).  File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture @@ -158,7 +158,7 @@ Picture Mode Rectangle Commands 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 @@ -725,7 +725,7 @@ the year in its entirety; that is, type `1990', not `90'. `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').  File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary @@ -780,7 +780,7 @@ The Mark and the Region ----------------------- 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). @@ -806,11 +806,11 @@ screen. This does not change the extent of the region. 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 @@ -975,7 +975,7 @@ holidays in a different face (or places a `*' after these dates, if 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 @@ -998,8 +998,8 @@ years, and allows you to choose all the holidays or one of several 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 @@ -1028,7 +1028,7 @@ the times of sunrise and sunset for any date. `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 @@ -1067,8 +1067,8 @@ The value of `calendar-time-zone' is the number of minutes difference 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 @@ -1117,7 +1117,7 @@ File: xemacs.info, Node: Other Calendars, Next: Calendar Systems, Prev: Lunar 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 @@ -1157,7 +1157,7 @@ nineteenth century. 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 @@ -1179,7 +1179,7 @@ measure similar to the metric system. The French government officially 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. diff --git a/info/xemacs.info-14 b/info/xemacs.info-14 index 25967a3..aaaefb4 100644 --- a/info/xemacs.info-14 +++ b/info/xemacs.info-14 @@ -1,5 +1,5 @@ -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 @@ -149,7 +149,7 @@ other than Mayan; for the Mayan calendar, see the following section. 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. @@ -227,14 +227,14 @@ date and moves point to the previous occurrence of that date. 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.  @@ -271,7 +271,7 @@ of the entries. Such formatting is purely a matter of taste. 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: @@ -334,7 +334,7 @@ different face (or places a `+' after these dates, if 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 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. @@ -344,15 +344,14 @@ to hide entries that don't apply. 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. @@ -412,13 +411,13 @@ entries, but can cause confusion if you ask for more than one day's 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 @@ -466,7 +465,7 @@ any day in March of any year; so does `march *'. 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 @@ -598,7 +597,7 @@ calendar style, the month and day are interchanged.) 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. @@ -624,7 +623,7 @@ year. 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 @@ -641,7 +640,7 @@ to just those dates. This example illustrates how the sexp can 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 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.  File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary @@ -692,7 +691,7 @@ period. The holiday list appears in a separate window. 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. @@ -738,7 +737,7 @@ default for this variable when Emacs supports multiple faces on your 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.  File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization @@ -1051,8 +1050,8 @@ order by day and time. 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. @@ -1083,11 +1082,11 @@ standard syntax table from Fundamental mode (*note Syntax Tables: (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 diff --git a/info/xemacs.info-15 b/info/xemacs.info-15 index 79ce826..60eb892 100644 --- a/info/xemacs.info-15 +++ b/info/xemacs.info-15 @@ -1,5 +1,5 @@ -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 @@ -156,7 +156,7 @@ applies to just those dates. This example illustrates how the sexp can 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 @@ -222,7 +222,7 @@ the Hebrew calendar in certain standard ways: 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)' @@ -230,7 +230,7 @@ the Hebrew calendar in certain standard ways: `%%(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.) @@ -602,7 +602,7 @@ and output going to that buffer. 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 @@ -1063,12 +1063,11 @@ ones that exist for the sake of customization. Emacs does not 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: @@ -1177,7 +1176,7 @@ it. It looks like this, in part: 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. diff --git a/info/xemacs.info-16 b/info/xemacs.info-16 index 457a018..60e6232 100644 --- a/info/xemacs.info-16 +++ b/info/xemacs.info-16 @@ -1,5 +1,5 @@ -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 @@ -202,7 +202,7 @@ field. When the attribute is enabled, you can change the attribute 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 @@ -261,7 +261,7 @@ can show their contents in the usual way, by invoking `[Show]'. 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, @@ -464,8 +464,8 @@ list. That is inappropriate. Whether you use Auto Fill mode or not is 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 @@ -604,7 +604,7 @@ one, you must give it a name using `M-x name-last-kbd-macro'. This 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. @@ -618,9 +618,9 @@ This inserts some Lisp code that, when executed later, will define the 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 @@ -1160,7 +1160,7 @@ argument defaults to the current buffer's syntax table. 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 diff --git a/info/xemacs.info-17 b/info/xemacs.info-17 index 375032b..e3c07cc 100644 --- a/info/xemacs.info-17 +++ b/info/xemacs.info-17 @@ -1,5 +1,5 @@ -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 @@ -39,8 +39,8 @@ The Init File, .emacs 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 @@ -56,7 +56,7 @@ loaded. 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: @@ -75,7 +75,7 @@ Init File Syntax 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 @@ -191,7 +191,7 @@ Lisp expressions: 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. @@ -693,7 +693,7 @@ Resource List `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. @@ -702,7 +702,7 @@ Resource List `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. @@ -968,9 +968,9 @@ editing level and cancel the command which invoked it. Quitting with `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. @@ -1000,7 +1000,7 @@ work, and how to recognize them and correct them. * 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. diff --git a/info/xemacs.info-18 b/info/xemacs.info-18 index 896c487..0789438 100644 --- a/info/xemacs.info-18 +++ b/info/xemacs.info-18 @@ -1,5 +1,5 @@ -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 @@ -145,7 +145,7 @@ backtrace showing how the Lisp program in Emacs arrived at the error. 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 @@ -253,7 +253,7 @@ Backup File 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.). @@ -308,8 +308,8 @@ Command 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 @@ -321,8 +321,8 @@ Comments 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, @@ -367,7 +367,7 @@ Current Buffer 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, @@ -387,8 +387,8 @@ Cursor 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 @@ -781,10 +781,10 @@ Prompt 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 @@ -923,7 +923,7 @@ Termscript File 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 @@ -946,7 +946,7 @@ Transposition 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 diff --git a/info/xemacs.info-19 b/info/xemacs.info-19 index cc37b6d..5ad3c61 100644 --- a/info/xemacs.info-19 +++ b/info/xemacs.info-19 @@ -1,5 +1,5 @@ -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 diff --git a/info/xemacs.info-20 b/info/xemacs.info-20 index aaede94..0522386 100644 --- a/info/xemacs.info-20 +++ b/info/xemacs.info-20 @@ -1,5 +1,5 @@ -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 diff --git a/info/xemacs.info-21 b/info/xemacs.info-21 index cc7f100..ba0998f 100644 --- a/info/xemacs.info-21 +++ b/info/xemacs.info-21 @@ -1,5 +1,5 @@ -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 @@ -528,7 +528,7 @@ Concept Index * 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. diff --git a/info/xemacs.info-5 b/info/xemacs.info-5 index a1374e0..9dc6019 100644 --- a/info/xemacs.info-5 +++ b/info/xemacs.info-5 @@ -1,5 +1,5 @@ -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 @@ -517,7 +517,7 @@ Registers 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 @@ -772,7 +772,7 @@ Horizontal Scrolling 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. diff --git a/info/xemacs.info-6 b/info/xemacs.info-6 index b86f3d6..db65e78 100644 --- a/info/xemacs.info-6 +++ b/info/xemacs.info-6 @@ -1,5 +1,5 @@ -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 @@ -358,7 +358,7 @@ Replacement occurs only after point: if you want to cover the whole 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 @@ -457,8 +457,7 @@ or a match for REGEXP are: 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::). `' to exit without doing any more replacements. @@ -624,7 +623,7 @@ characters between the words do not move. For example, `FOO, BAR' 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. @@ -730,7 +729,7 @@ rename, and append to files, and operate on file directories. * 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. @@ -743,7 +742,7 @@ File Names 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 @@ -867,10 +866,9 @@ the command with the name of the file you wish to visit, terminated by a . 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 @@ -919,7 +917,7 @@ modified). `C-x C-v' is allowed even if the current buffer is not 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. diff --git a/info/xemacs.info-7 b/info/xemacs.info-7 index b085ba1..4fa7c51 100644 --- a/info/xemacs.info-7 +++ b/info/xemacs.info-7 @@ -1,5 +1,5 @@ -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 @@ -52,7 +52,7 @@ owner is always the person who last edited the file. Occasionally 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 @@ -160,7 +160,7 @@ result in very extensive changes, you must confirm it with `yes'. 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 @@ -254,7 +254,7 @@ Controlling Auto-Saving 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 @@ -574,7 +574,7 @@ Change Logs and VC ------------------ 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' @@ -686,7 +686,7 @@ numbers, then compares those versions of the specified file. 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 @@ -744,10 +744,10 @@ Renaming VC Work Files and Master Files 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. @@ -797,7 +797,7 @@ snapshot. Thus, you need not hesitate to create snapshots whenever 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. @@ -1083,11 +1083,11 @@ delete them. `#' 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 diff --git a/info/xemacs.info-8 b/info/xemacs.info-8 index 5b6078b..811bbe5 100644 --- a/info/xemacs.info-8 +++ b/info/xemacs.info-8 @@ -1,5 +1,5 @@ -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 @@ -87,7 +87,7 @@ NEW. `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 @@ -140,7 +140,7 @@ commands do. 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 @@ -151,7 +151,7 @@ can use for evaluating Lisp expressions in Emacs. 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::. @@ -183,7 +183,7 @@ Creating and Selecting Buffers To select a buffer named BUFNAME, type `C-x b BUFNAME '. 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 @@ -191,9 +191,9 @@ that display text. You can also create a buffer explicitly by typing `C-x b BUFNAME ', 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 @@ -220,7 +220,7 @@ Listing Existing Buffers 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: @@ -277,7 +277,7 @@ you specify a name that is used by a different buffer, an error is 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. @@ -560,7 +560,7 @@ command selects a window on the next or previous frame instead of 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. @@ -604,12 +604,12 @@ buffer to select. `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 @@ -756,7 +756,7 @@ defaults. The language environment really represents a choice of 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. @@ -949,12 +949,12 @@ about particular coding systems. You can specify a coding system name 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 @@ -1024,7 +1024,7 @@ finds a coding system that fits the data. Then it converts the file 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. @@ -1051,7 +1051,7 @@ third argument says which coding system to use for these files. 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: @@ -1064,5 +1064,5 @@ system, by default, for operations that write from this buffer into a 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::). diff --git a/info/xemacs.info-9 b/info/xemacs.info-9 index c7381d1..0c68a6c 100644 --- a/info/xemacs.info-9 +++ b/info/xemacs.info-9 @@ -1,5 +1,5 @@ -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 @@ -66,7 +66,7 @@ file is saved. the file. First use the command `C-x 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 @@ -167,9 +167,9 @@ languages. Text mode, Nroff mode, TeX mode, and Outline mode are for 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 @@ -472,15 +472,15 @@ Text Mode edit files of text in a human language. Invoke `M-x text-mode' to enter Text mode. In Text mode, 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 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 , is normally indented just like the previous line. Use `M-x indented-text-mode' to select this mode. @@ -537,7 +537,7 @@ commands that are not available in Text 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 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 @@ -666,7 +666,7 @@ paragraph that contains a mismatch, it displays point at the beginning 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. @@ -721,7 +721,7 @@ being printed. 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