diff options
Diffstat (limited to 'gnu/usr.bin/texinfo/info-files/texi.info-6')
| -rw-r--r-- | gnu/usr.bin/texinfo/info-files/texi.info-6 | 1461 |
1 files changed, 0 insertions, 1461 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-6 b/gnu/usr.bin/texinfo/info-files/texi.info-6 deleted file mode 100644 index cac7b3a..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-6 +++ /dev/null @@ -1,1461 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 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: texi.info, Node: Inserting An Atsign, Next: Inserting Braces, Up: Braces Atsigns Periods - -Inserting `@' with @@ ---------------------- - - `@@' stands for a single `@' in either printed or Info output. - - Do not put braces after an `@@' command. - - -File: texi.info, Node: Inserting Braces, Next: Controlling Spacing, Prev: Inserting An Atsign, Up: Braces Atsigns Periods - -Inserting `{' and `}'with @{ and @} ------------------------------------ - - `@{' stands for a single `{' in either printed or Info output. - - `@}' stands for a single `}' in either printed or Info output. - - Do not put braces after either an `@{' or an `@}' command. - - -File: texi.info, Node: Controlling Spacing, Prev: Inserting Braces, Up: Braces Atsigns Periods - -Spacing After Colons and Periods --------------------------------- - - Use the `@:' command after a period, question mark, exclamation -mark, or colon that should not be followed by extra space. For -example, use `@:' after periods that end abbreviations which are not at -the ends of sentences. `@:' has no effect on the Info file output. - - For example, - - The s.o.p.@: has three parts ... - The s.o.p. has three parts ... - -produces - - The s.o.p. has three parts ... - The s.o.p. has three parts ... - -`@:' has no effect on the Info output. (`s.o.p' is an acronym for -"Standard Operating Procedure".) - - Use `@.' instead of a period at the end of a sentence that ends with -a single capital letter. Otherwise, TeX will think the letter is an -abbreviation and will not insert the correct end-of-sentence spacing. -Here is an example: - - Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@. - Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. - -produces - - Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. - Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. - - In the Info file output, `@.' is equivalent to a simple `.'. - - The meanings of `@:' and `@.' in Texinfo are designed to work well -with the Emacs sentence motion commands. This made it necessary for -them to be incompatible with some other formatting systems that use -@-commands. - - Do not put braces after either an `@:' or an `@.' command. - - -File: texi.info, Node: dmn, Next: Dots Bullets, Prev: Braces Atsigns Periods, Up: Insertions - -`@dmn'{DIMENSION}: Format a Dimension -===================================== - - At times, you may want to write `12pt' or `8.5in' with little or no -space between the number and the abbreviation for the dimension. You -can use the `@dmn' command to do this. On seeing the command, TeX -inserts just enough space for proper typesetting; the Info formatting -commands insert no space at all, since the Info file does not require -it. - - To use the `@dmn' command, write the number and then follow it -immediately, with no intervening space, by `@dmn', and then by the -dimension within braces. - -For example, - - A4 paper is 8.27@dmn{in} wide. - -produces - - A4 paper is 8.27in wide. - - Not everyone uses this style. Instead of writing `8.27@dmn{in}' in -the Texinfo file, you may write `8.27 in.' or `8.27 inches'. (In these -cases, the formatters may insert a line break between the number and the -dimension. 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. *Note Spacing After Colons and Periods: -Controlling Spacing.) - - -File: texi.info, Node: Dots Bullets, Next: TeX and copyright, Prev: dmn, Up: Insertions - -Inserting Ellipsis, Dots, and Bullets -===================================== - - An "ellipsis" (a line of dots) is not typeset as a string of -periods, so a special command is used for ellipsis in Texinfo. The -`@bullet' command is special, too. Each of these commands is followed -by a pair of braces, `{}', without any whitespace between the name of -the command and the braces. (You need to use braces with these -commands because you can use them next to other text; without the -braces, the formatters would be confused. *Note @-Command Syntax: -Command Syntax, for further information.) - -* Menu: - -* dots:: How to insert dots ... -* bullet:: How to insert a bullet. - - -File: texi.info, Node: dots, Next: bullet, Up: Dots Bullets - -`@dots'{} ---------- - - Use the `@dots{}' command to generate an ellipsis, which is three -dots in a row, appropriately spaced, like this: `...'. Do not simply -write three periods in the input file; that would work for the Info -file output, but would produce the wrong amount of space between the -periods in the printed manual. - - -File: texi.info, Node: bullet, Prev: dots, Up: Dots Bullets - -`@bullet'{} ------------ - - Use the `@bullet{}' command to generate a large round dot, or the -closest possible thing to one. In Info, an asterisk is used. - - Here is a bullet: * - - When you use `@bullet' in `@itemize', you do not need to type the -braces, because `@itemize' supplies them. *Note itemize::. - - -File: texi.info, Node: TeX and copyright, Next: minus, Prev: Dots Bullets, Up: Insertions - -Inserting TeX and the Copyright Symbol -====================================== - - The logo `TeX' is typeset in a special fashion and it needs an -@-command. The copyright symbol, `(C)', is also special. Each of -these commands is followed by a pair of braces, `{}', without any -whitespace between the name of the command and the braces. - -* Menu: - -* tex:: How to insert the TeX logo. -* copyright symbol:: How to use `@copyright'{}. - - -File: texi.info, Node: tex, Next: copyright symbol, Up: TeX and copyright - -`@TeX'{} --------- - - Use the `@TeX{}' command to generate `TeX'. In a printed manual, -this is a special logo that is different from three ordinary letters. -In Info, it just looks like `TeX'. The `@TeX{}' command is unique -among Texinfo commands in that the T and the X are in upper case. - - -File: texi.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright - -`@copyright'{} --------------- - - Use the `@copyright{}' command to generate `(C)'. In a printed -manual, this is a `c' inside a circle, and in Info, this is `(C)'. - - -File: texi.info, Node: minus, Prev: TeX and copyright, Up: Insertions - -`@minus'{}: Inserting a Minus Sign -================================== - - Use the `@minus{}' command to generate a minus sign. In a -fixed-width font, this is a single hyphen, but in a proportional font, -the symbol is the customary length for a minus sign--a little longer -than a hyphen. - - You can compare the two forms: - - `-' is a minus sign generated with `@minus{}', - - `-' is a hyphen generated with the character `-'. - -In the fixed-width font used by Info, `@minus{}' is the same as a -hyphen. - - You should not use `@minus{}' inside `@code' or `@example' because -the width distinction is not made in the fixed-width font they use. - - When you use `@minus' to specify the mark beginning each entry in an -itemized list, you do not need to type the braces (*note itemize::.). - - -File: texi.info, Node: Glyphs, Next: Breaks, Prev: Insertions, Up: Top - -Glyphs for Examples -******************* - - In Texinfo, code is often illustrated in examples that are delimited -by `@example' and `@end example', or by `@lisp' and `@end lisp'. In -such examples, you can indicate the results of evaluation or an -expansion using `=>' or `==>'. Likewise, there are commands to insert -glyphs to indicate printed output, error messages, equivalence of -expressions, and the location of point. - - The glyph-insertion commands do not need to be used within an -example, but most often they are. Every glyph-insertion command is -followed by a pair of left- and right-hand braces. - -* Menu: - -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. - - -File: texi.info, Node: Glyphs Summary, Next: result, Up: Glyphs - -Glyphs Summary -============== - - Here are the different glyph commands: - -=> - `@result{}' points to the result of an expression. - -==> - `@expansion{}' shows the results of a macro expansion. - --| - `@print{}' indicates printed output. - -error--> - `@error{}' indicates that the following text is an error message. - -== - `@equiv{}' indicates the exact equivalence of two forms. - --!- - `@point{}' shows the location of point. - - -File: texi.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs - -=>: Indicating Evaluation -========================= - - Use the `@result{}' command to indicate the result of evaluating an -expression. - - The `@result{}' command is displayed as `=>' in Info and as a double -stemmed arrow in the printed output. - - Thus, the following, - - (cdr '(1 2 3)) - => (2 3) - -may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'". - - -File: texi.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs - -==>: Indicating an Expansion -============================ - - When an expression is a macro call, it expands into a new expression. -You can indicate the result of the expansion with the `@expansion{}' -command. - - The `@expansion{}' command is displayed as `==>' in Info and as a -long arrow with a flat base in the printed output. - - For example, the following - - @lisp - (third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c - @end lisp - -produces - - (third '(a b c)) - ==> (car (cdr (cdr '(a b c)))) - => c - -which may be read as: - - `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the - result of evaluating the expression is `c'. - -Often, as in this case, an example looks better if the `@expansion{}' -and `@result{}' commands are indented five spaces. - - -File: texi.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs - --|: Indicating Printed Output -============================= - - Sometimes an expression will print output during its execution. You -can indicate the printed output with the `@print{}' command. - - The `@print{}' command is displayed as `-|' in Info and similarly, -as a horizontal dash butting against a vertical bar, in the printed -output. - - In the following example, the printed text is indicated with `-|', -and the value of the expression follows on the last line. - - (progn (print 'foo) (print 'bar)) - -| foo - -| bar - => bar - -In a Texinfo source file, this example is written as follows: - - @lisp - (progn (print 'foo) (print 'bar)) - @print{} foo - @print{} bar - @result{} bar - @end lisp - - -File: texi.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs - -error-->: Indicating an Error Message -===================================== - - A piece of code may cause an error when you evaluate it. You can -designate the error message with the `@error{}' command. - - The `@error{}' command is displayed as `error-->' in Info and as the -word `error' in a box in the printed output. - - Thus, - - @lisp - (+ 23 'x) - @error{} Wrong type argument: integer-or-marker-p, x - @end lisp - -produces - - (+ 23 'x) - error--> Wrong type argument: integer-or-marker-p, x - -This indicates that the following error message is printed when you -evaluate the expression: - - Wrong type argument: integer-or-marker-p, x - - Note that `error-->' itself is not part of the error message. - - -File: texi.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs - -==: Indicating Equivalence -========================== - - Sometimes two expressions produce identical results. You can -indicate the exact equivalence of two forms with the `@equiv{}' command. - - The `@equiv{}' command is displayed as `==' in Info and as a three -parallel horizontal lines in the printed output. - - Thus, - - @lisp - (make-sparse-keymap) @equiv{} (list 'keymap) - @end lisp - -produces - - (make-sparse-keymap) == (list 'keymap) - -This indicates that evaluating `(make-sparse-keymap)' produces -identical results to evaluating `(list 'keymap)'. - - -File: texi.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs - -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: texi.info, Node: Breaks, Next: Definition Commands, Prev: Glyphs, 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. -* 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: texi.info, Node: Break Commands, Next: Line Breaks, Up: Breaks - -The Break Commands -================== - - The break commands create line and paragraph breaks: - -`@*' - Force a line break. - -`@sp N' - Skip N blank lines. - - 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: texi.info, Node: Line Breaks, Next: w, 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: texi.info, Node: w, Next: sp, Prev: Line Breaks, 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 accidentally falls near the end -of a line. - - You can copy GNU software from @w{@file{prep.ai.mit.edu}}. - -produces - - You can copy GNU software from `prep.ai.mit.edu'. - - In the Texinfo file, you must write the `@w' command and its -argument (all the affected text) all on one line. - - *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: texi.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: texi.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: texi.info, Node: group, Next: need, Prev: page, Up: Breaks - -`@group': Prevent Page Breaks -============================= - - The `@group' command (on a line by itself) is used inside an -`@example' or similar construct to begin an unsplittable vertical -group, which will appear entirely on one page in the printed output. -The group is terminated by a line containing only `@end group'. These -two lines produce no output of their own, and in the Info file output -they have no effect at all. - - Although `@group' would make sense conceptually in a wide variety of -contexts, its current implementation works reliably only within -`@example' and variants, and within `@display', `@format', `@flushleft' -and `@flushright'. *Note Quotations and Examples::. (What all these -commands have in common is that each line of input produces a line of -output.) In other contexts, `@group' can cause anomalous vertical -spacing. - - This formatting requirement means that you should write: - - @example - @group - ... - @end group - @end example - -with the `@group' and `@end group' commands inside the `@example' and -`@end example' commands. - - The `@group' command is most often used to hold an example together -on one page. In this Texinfo manual, more than 100 examples contain -text that is enclosed between `@group' and `@end group'. - - If you forget to end a group, you may get strange and unfathomable -error messages when you run TeX. This is because TeX keeps trying to -put the rest of the Texinfo file onto the one page and does not start -to generate error messages until it has processed considerable text. -It is a good rule of thumb to look for a missing `@end group' if you -get incomprehensible error messages in TeX. - - -File: texi.info, Node: need, Prev: group, Up: Breaks - -`@need MILS': Prevent Page Breaks -================================= - - A line containing only `@need N' starts a new page in a printed -manual if fewer than N mils (thousandths of an inch) remain on the -current page. Do not use braces around the argument N. The `@need' -command has no effect on Info files since they are not paginated. - - This paragraph is preceded by an `@need' command that tells TeX to -start a new page if fewer than 800 mils (eight-tenths inch) remain on -the page. It looks like this: - - @need 800 - This paragraph is preceded by ... - - The `@need' command is useful for preventing orphans (single lines -at the bottoms of printed pages). - - -File: texi.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top - -Definition Commands -******************* - - The `@deffn' command and the other "definition commands" enable you -to describe functions, variables, macros, commands, user options, -special forms and other such artifacts in a uniform format. - - In the Info file, a definition causes the entity -category--`Function', `Variable', or whatever--to appear at the -beginning of the first line of the definition, followed by the entity's -name and arguments. In the printed manual, the command causes TeX to -print the entity's name and its arguments on the left margin and print -the category next to the right margin. In both output formats, the -body of the definition is indented. Also, the name of the entity is -entered into the appropriate index: `@deffn' enters the name into the -index of functions, `@defvr' enters it into the index of variables, and -so on. - - A manual need not and should not contain more than one definition for -a given name. An appendix containing a summary should use `@table' -rather than the definition commands. - -* Menu: - -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. -* Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: - - -File: texi.info, Node: Def Cmd Template, Next: Optional Arguments, Up: Definition Commands - -The Template for a Definition -============================= - - The `@deffn' command is used for definitions of entities that -resemble functions. To write a definition using the `@deffn' command, -write the `@deffn' command at the beginning of a line and follow it on -the same line by the category of the entity, the name of the entity -itself, and its arguments (if any). Then write the body of the -definition on succeeding lines. (You may embed examples in the body.) -Finally, end the definition with an `@end deffn' command written on a -line of its own. (The other definition commands follow the same -format.) - - The template for a definition looks like this: - - @deffn CATEGORY NAME ARGUMENTS... - BODY-OF-DEFINITION - @end deffn - -For example, - - @deffn Command forward-word count - This command moves point forward @var{count} words - (or backward if @var{count} is negative). ... - @end deffn - -produces - - - Command: forward-word COUNT - This function moves point forward COUNT words (or backward if - COUNT is negative). ... - - Capitalize the category name like a title. If the name of the -category contains spaces, as in the phrase `Interactive Command', write -braces around it. For example: - - @deffn {Interactive Command} isearch-forward - ... - @end deffn - -Otherwise, the second word will be mistaken for the name of the entity. - - Some of the definition commands are more general than others. The -`@deffn' command, for example, is the general definition command for -functions and the like--for entities that may take arguments. When you -use this command, you specify the category to which the entity belongs. -The `@deffn' command possesses three predefined, specialized -variations, `@defun', `@defmac', and `@defspec', that specify the -category for you: "Function", "Macro", and "Special Form" respectively. -The `@defvr' command also is accompanied by several predefined, -specialized variations for describing particular kinds of variables. - - The template for a specialized definition, such as `@defun', is -similar to the template for a generalized definition, except that you -do not need to specify the category: - - @defun NAME ARGUMENTS... - BODY-OF-DEFINITION - @end defun - -Thus, - - @defun buffer-end flag - This function returns @code{(point-min)} if @var{flag} - is less than 1, @code{(point-max)} otherwise. - ... - @end defun - -produces - - - Function: buffer-end FLAG - This function returns `(point-min)' if FLAG is less than 1, - `(point-max)' otherwise. ... - -*Note Sample Function Definition: Sample Function Definition, for a -more detailed example of a function definition, including the use of -`@example' inside the definition. - - The other specialized commands work like `@defun'. - - -File: texi.info, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Template, Up: Definition Commands - -Optional and Repeated Arguments -=============================== - - Some entities take optional or repeated arguments, which may be -specified by a distinctive glyph that uses square brackets and -ellipses. For example, a special form often breaks its argument list -into separate arguments in more complicated ways than a straightforward -function. - - An argument enclosed within square brackets is optional. Thus, -[OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument -followed by an ellipsis is optional and may be repeated more than once. -Thus, REPEATED-ARGS... stands for zero or more arguments. Parentheses -are used when several arguments are grouped into additional levels of -list structure in Lisp. - - Here is the `@defspec' line of an example of an imaginary special -form: - - - Special Form: foobar (VAR [FROM TO [INC]]) BODY... - -In this example, the arguments FROM and TO are optional, but must both -be present or both absent. If they are present, INC may optionally be -specified as well. These arguments are grouped with the argument VAR -into a list, to distinguish them from BODY, which includes all -remaining elements of the form. - - In a Texinfo source file, this `@defspec' line is written like this -(except it would not be split over two lines, as it is in this example). - - @defspec foobar (@var{var} [@var{from} @var{to} - [@var{inc}]]) @var{body}@dots{} - -The function is listed in the Command and Variable Index under `foobar'. - - -File: texi.info, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands - -Two or More `First' Lines -========================= - - To create two or more `first' or header lines for a definition, -follow the first `@deffn' line by a line beginning with `@deffnx'. The -`@deffnx' command works exactly like `@deffn' except that it does not -generate extra vertical white space between it and the preceding line. - - For example, - - @deffn {Interactive Command} isearch-forward - @deffnx {Interactive Command} isearch-backward - These two search commands are similar except ... - @end deffn - -produces - - - Interactive Command: isearch-forward - - 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. - - The `x' forms work just like `@itemx'; see *Note `@itemx': itemx. - - -File: texi.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands - -The Definition Commands -======================= - - Texinfo provides more than a dozen definition commands, all of which -are described in this section. - - The definition commands automatically enter the name of the entity in -the appropriate index: for example, `@deffn', `@defun', and `@defmac' -enter function names in the index of functions; `@defvr' and `@defvar' -enter variable names in the index of variables. - - Although the examples that follow mostly illustrate Lisp, the -commands can be used for other programming languages. - -* Menu: - -* Functions Commands:: Commands for functions and similar entities. -* Variables Commands:: Commands for variables and similar entities. -* Typed Functions:: Commands for functions in typed languages. -* Typed Variables:: Commands for variables in typed languages. -* Abstract Objects:: Commands for object-oriented programming. -* Data Types:: The definition command for data types. - - -File: texi.info, Node: Functions Commands, Next: Variables Commands, Up: Def Cmds in Detail - -Functions and Similar Entities ------------------------------- - - This section describes the commands for describing functions and -similar entities: - -`@deffn CATEGORY NAME ARGUMENTS...' - The `@deffn' command is the general definition command for - functions, interactive commands, and similar entities that may take - arguments. You must choose a term to describe the category of - entity being defined; for example, "Function" could be used if the - entity is a function. The `@deffn' command is written at the - beginning of a line and is followed on the same line by the - category of entity being described, the name of this particular - entity, and its arguments, if any. Terminate the definition with - `@end deffn' on a line of its own. - - For example, here is a definition: - - @deffn Command forward-char nchars - Move point forward @var{nchars} characters. - @end deffn - - This shows a rather terse definition for a "command" named - `forward-char' with one argument, NCHARS. - - `@deffn' prints argument names such as NCHARS in italics or upper - case, as if `@var' had been used, because we think of these names - as metasyntactic variables--they stand for the actual argument - values. Within the text of the description, write an argument name - explicitly with `@var' to refer to the value of the argument. In - the example above, we used `@var{nchars}' in this way. - - The template for `@deffn' is: - - @deffn CATEGORY NAME ARGUMENTS... - BODY-OF-DEFINITION - @end deffn - -`@defun NAME ARGUMENTS...' - The `@defun' command is the definition command for functions. - `@defun' is equivalent to `@deffn Function ...'. - - For example, - - @defun set symbol new-value - Change the value of the symbol @var{symbol} - to @var{new-value}. - @end defun - - shows a rather terse definition for a function `set' whose - arguments are SYMBOL and NEW-VALUE. The argument names on the - `@defun' line automatically appear in italics or upper case as if - they were enclosed in `@var'. Terminate the definition with `@end - defun' on a line of its own. - - The template is: - - @defun FUNCTION-NAME ARGUMENTS... - BODY-OF-DEFINITION - @end defun - - `@defun' creates an entry in the index of functions. - -`@defmac NAME ARGUMENTS...' - The `@defmac' command is the definition command for macros. - `@defmac' is equivalent to `@deffn Macro ...' and works like - `@defun'. - -`@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.) `@defspec' is equivalent to `@deffn {Special Form} ...' - and works like `@defun'. - - -File: texi.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail - -Variables and Similar Entities ------------------------------- - - Here are the commands for defining variables and similar entities: - -`@defvr CATEGORY NAME' - The `@defvr' command is a general definition command for something - 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 - it on the same line by the category of the entity and the name of - the entity. - - Capitalize the category name like a title. If the name of the - category contains spaces, as in the name `User Option', write - braces around it. Otherwise, the second word will be mistaken for - the name of the entity, for example: - - @defvr {User Option} fill-column - This buffer-local variable specifies - the maximum width of filled lines. - ... - @end defvr - - Terminate the definition with `@end defvr' on a line of its own. - - The template is: - - @defvr CATEGORY NAME - BODY-OF-DEFINITION - @end defvr - - `@defvr' creates an entry in the index of variables for NAME. - -`@defvar NAME' - The `@defvar' command is the definition command for variables. - `@defvar' is equivalent to `@defvr Variable ...'. - - For example: - - @defvar kill-ring - ... - @end defvar - - The template is: - - @defvar NAME - BODY-OF-DEFINITION - @end defvar - - `@defvar' creates an entry in the index of variables for NAME. - -`@defopt NAME' - The `@defopt' command is the definition command for user options. - `@defopt' is equivalent to `@defvr {User Option} ...' and works - like `@defvar'. - - -File: texi.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail - -Functions in Typed Languages ----------------------------- - - The `@deftypefn' command and its variations are for describing -functions in C or any other language in which you must declare types of -variables and functions. - -`@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...' - The `@deftypefn' command is the general definition command for - functions and similar entities that may take arguments and that are - typed. The `@deftypefn' command is written at the beginning of a - line and is followed on the same line by the category of entity - being described, the type of the returned value, the name of this - particular entity, and its arguments, if any. - - For example, - - @deftypefn {Library Function} int foobar - (int @var{foo}, float @var{bar}) - ... - @end deftypefn - - (where the text before the "...", shown above as two lines, would - actually be a single line in a real Texinfo file) produces the - following in Info: - - -- Library Function: int foobar (int FOO, float BAR) - ... - - This means that `foobar' is a "library function" that returns an - `int', and its arguments are FOO (an `int') and BAR (a `float'). - - The argument names that you write in `@deftypefn' are not subject - to an implicit `@var'--since the actual names of the arguments in - `@deftypefn' are typically scattered among data type names and - keywords, Texinfo cannot find them without help. Instead, you - must write `@var' explicitly around the argument names. In the - example above, the argument names are `foo' and `bar'. - - The template for `@deftypefn' is: - - @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ... - BODY-OF-DESCRIPTION - @end deftypefn - - Note that if the CATEGORY or DATA TYPE is more than one word then - it must be enclosed in braces to make it a single argument. - - If you are describing a procedure in a language that has packages, - such as Ada, you might consider using `@deftypefn' in a manner - somewhat contrary to the convention described in the preceding - paragraphs. - - For example: - - @deftypefn stacks private push - (@var{s}:in out stack; - @var{n}:in integer) - ... - @end deftypefn - - (The `@deftypefn' arguments are shown split into three lines, but - would be a single line in a real Texinfo file.) - - In this instance, the procedure is classified as belonging to the - package `stacks' rather than classified as a `procedure' and its - data type is described as `private'. (The name of the procedure - is `push', and its arguments are S and N.) - - `@deftypefn' creates an entry in the index of functions for NAME. - -`@deftypefun DATA-TYPE NAME ARGUMENTS...' - The `@deftypefun' command is the specialized definition command - for functions in typed languages. The command is equivalent to - `@deftypefn Function ...'. - - Thus, - - @deftypefun int foobar (int @var{foo}, float @var{bar}) - ... - @end deftypefun - - produces the following in Info: - - -- Function: int foobar (int FOO, float BAR) - ... - - The template is: - - @deftypefun TYPE NAME ARGUMENTS... - BODY-OF-DESCRIPTION - @end deftypefun - - `@deftypefun' creates an entry in the index of functions for NAME. - - -File: texi.info, Node: Typed Variables, Next: Abstract Objects, Prev: Typed Functions, Up: Def Cmds in Detail - -Variables in Typed Languages ----------------------------- - - Variables in typed languages are handled in a manner similar to -functions in typed languages. *Note Typed Functions::. The general -definition command `@deftypevr' corresponds to `@deftypefn' and the -specialized definition command `@deftypevar' corresponds to -`@deftypefun'. - -`@deftypevr CATEGORY DATA-TYPE NAME' - The `@deftypevr' command is the general definition command for - something like a variable in a typed language--an entity that - records a value. You must choose a term to describe the category - of the entity being defined; for example, "Variable" could be used - if the entity is a variable. - - The `@deftypevr' command is written at the beginning of a line and - is followed on the same line by the category of the entity being - described, the data type, and the name of this particular entity. - - For example: - - @deftypevr {Global Flag} int enable - ... - @end deftypevr - - produces the following in Info: - - -- Global Flag: int enable - ... - - The template is: - - @deftypevr CATEGORY DATA-TYPE NAME - BODY-OF-DESCRIPTION - @end deftypevr - - `@deftypevr' creates an entry in the index of variables for NAME. - -`@deftypevar DATA-TYPE NAME' - The `@deftypevar' command is the specialized definition command - for variables in typed languages. `@deftypevar' is equivalent to - `@deftypevr Variable ...'. - - For example: - - @deftypevar int fubar - ... - @end deftypevar - - produces the following in Info: - - -- Variable: int fubar - ... - - The template is: - - @deftypevar DATA-TYPE NAME - BODY-OF-DESCRIPTION - @end deftypevar - - `@deftypevar' creates an entry in the index of variables for NAME. - - -File: texi.info, Node: Abstract Objects, Next: Data Types, Prev: Typed Variables, Up: Def Cmds in Detail - -Object-Oriented Programming ---------------------------- - - Here are the commands for formatting descriptions about abstract -objects, such as are used in object-oriented programming. A class is a -defined type of abstract object. An instance of a class is a -particular object that has the type of the class. An instance variable -is a variable that belongs to the class but for which each instance has -its own value. - - In a definition, if the name of a class is truly a name defined in -the programming system for a class, then you should write an `@code' -around it. Otherwise, it is printed in the usual text font. - -`@defcv CATEGORY CLASS NAME' - The `@defcv' command is the general definition command for - variables associated with classes in object-oriented programming. - The `@defcv' command is followed by three arguments: the category - of thing being defined, the class to which it belongs, and its - name. Thus, - - @defcv {Class Option} Window border-pattern - ... - @end defcv - - illustrates how you would write the first line of a definition of - the `border-pattern' class option of the class `Window'. - - The template is - - @defcv CATEGORY CLASS NAME - ... - @end defcv - - `@defcv' creates an entry in the index of variables. - -`@defivar CLASS NAME' - The `@defivar' command is the definition command for instance - variables in object-oriented programming. `@defivar' is - 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. - -`@defop CATEGORY CLASS NAME ARGUMENTS...' - The `@defop' command is the general definition command for - entities that may resemble methods in object-oriented programming. - These entities take arguments, as functions do, but are associated - with particular classes of objects. - - For example, some systems have constructs called "wrappers" that - are associated with classes as methods are, but that act more like - macros than like functions. You could use `@defop Wrapper' to - describe one of these. - - Sometimes it is useful to distinguish methods and "operations". - You can think of an operation as the specification for a method. - Thus, a window system might specify that all window classes have a - method named `expose'; we would say that this window system - defines an `expose' operation on windows in general. Typically, - the operation has a name and also specifies the pattern of - arguments; all methods that implement the operation must accept - the same arguments, since applications that use the operation do - so without knowing which method will implement it. - - Often it makes more sense to document operations than methods. For - example, window application developers need to know about the - `expose' operation, but need not be concerned with whether a given - class of windows has its own method to implement this operation. - To describe this operation, you would write: - - @defop Operation windows expose - - The `@defop' command is written at the beginning of a line and is - followed on the same line by 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. - - The template is: - - @defop CATEGORY CLASS NAME ARGUMENTS... - BODY-OF-DEFINITION - @end defop - - `@defop' creates an entry, such as ``expose' on `windows'', in the - index of functions. - -`@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'. - - `@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, - - @defmethod `bar-class' bar-method argument - ... - @end defmethod - - illustrates the definition for a method called `bar-method' of the - class `bar-class'. The method takes an argument. - - The template is: - - @defmethod CLASS METHOD-NAME ARGUMENTS... - BODY-OF-DEFINITION - @end defmethod - - `@defmethod' creates an entry in the index of functions, such as - ``bar-method' on `bar-class''. - - -File: texi.info, Node: Data Types, Prev: Abstract Objects, Up: Def Cmds in Detail - -Data Types ----------- - - Here is the command for data types: - -`@deftp CATEGORY NAME ATTRIBUTES...' - The `@deftp' command is the generic definition command for data - types. The command is written at the beginning of a line and is - followed on the same line by the category, by the name of the type - (which is a word like `int' or `float'), and then by names of - attributes of objects of that type. Thus, you could use this - command for describing `int' or `float', in which case you could - use `data type' as the category. (A data type is a category of - certain objects for purposes of deciding which operations can be - performed on them.) - - In Lisp, for example, "pair" names a particular data type, and an - object of that type has two slots called the CAR and the CDR. - Here is how you would write the first line of a definition of - `pair'. - - @deftp {Data type} pair car cdr - ... - @end deftp - - The template is: - - @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES... - BODY-OF-DEFINITION - @end deftp - - `@deftp' creates an entry in the index of data types. - - -File: texi.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands - -Conventions for Writing Definitions -=================================== - - When you write a definition using `@deffn', `@defun', or one of the -other definition commands, please take care to use arguments that -indicate the meaning, as with the COUNT argument to the `forward-word' -function. Also, if the name of an argument contains the name of a -type, such as INTEGER, take care that the argument actually is of that -type. - - -File: texi.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands - -A Sample Function Definition -============================ - - A function definition uses the `@defun' and `@end defun' commands. -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 `The GNU Emacs Lisp Reference Manual'. -(*Note Calling Functions: (elisp)Calling Functions.) - - - 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 that this list is "appended" to the other - arguments. - - `apply' returns the result of calling FUNCTION. As with - `funcall', FUNCTION must either be a Lisp function or a - primitive function; special forms and macros do not make - sense in `apply'. - - (setq f 'list) - => list - (apply f 'x 'y 'z) - error--> Wrong type argument: listp, z - (apply '+ 1 2 '(3 4)) - => 10 - (apply '+ '(1 2 3 4)) - => 10 - - (apply 'append '((a b c) nil (x y z) nil)) - => (a b c x y z) - - An interesting example of using `apply' is found in the - description of `mapcar'. - - 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 - arguments to give to @var{function}, rather than a single - argument. We also say that this list is @dfn{appended} - to the other arguments. - - @code{apply} returns the result of calling - @var{function}. As with @code{funcall}, - @var{function} must either be a Lisp function or a - primitive function; special forms and macros do not make - sense in @code{apply}. - - @example - (setq f 'list) - @result{} list - (apply f 'x 'y 'z) - @error{} Wrong type argument: listp, z - (apply '+ 1 2 '(3 4)) - @result{} 10 - (apply '+ '(1 2 3 4)) - @result{} 10 - - (apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) - @end example - - An interesting example of using @code{apply} is found - in the description of @code{mapcar}.@refill - @end defun - -In this manual, this function is listed in the Command and Variable -Index under `apply'. - - Ordinary variables and user options are described using a format like -that for functions except that variables do not take arguments. - |
