home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / texinfo.info-6 < prev    next >
Encoding:
GNU Info File  |  1996-10-12  |  47.0 KB  |  1,410 lines
  1. This is Info file texinfo.info, produced by Makeinfo-1.64 from the
  2. input file /ade-src/fsf/texinfo/texinfo.texi.
  3.  
  4.   This file documents Texinfo, a documentation system that uses a single
  5. source file to produce both on-line information and a printed manual.
  6.  
  7.   Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software
  8. Foundation, Inc.
  9.  
  10.   This is the second edition of the Texinfo documentation,
  11. and is consistent with version 2 of `texinfo.tex'.
  12.  
  13.   Permission is granted to make and distribute verbatim copies of this
  14. manual provided the copyright notice and this permission notice are
  15. preserved on all copies.
  16.  
  17.   Permission is granted to copy and distribute modified versions of this
  18. manual under the conditions for verbatim copying, provided that the
  19. entire resulting derived work is distributed under the terms of a
  20. permission notice identical to this one.
  21.  
  22.   Permission is granted to copy and distribute translations of this
  23. manual into another language, under the above conditions for modified
  24. versions, except that this permission notice may be stated in a
  25. translation approved by the Free Software Foundation.
  26.  
  27. 
  28. File: texinfo.info,  Node: syncodeindex,  Next: synindex,  Prev: Combining Indices,  Up: Combining Indices
  29.  
  30. `@syncodeindex'
  31. ---------------
  32.  
  33.   When you want to combine functions and concepts into one index, you
  34. should index the functions with `@findex' and index the concepts with
  35. `@cindex', and use the `@syncodeindex' command to redirect the function
  36. index entries into the concept index.
  37.  
  38.   The `@syncodeindex' command takes two arguments; they are the name of
  39. the index to redirect, and the name of the index to redirect it to.
  40. The template looks like this:
  41.  
  42.      @syncodeindex FROM TO
  43.  
  44.   For this purpose, the indices are given two-letter names:
  45.  
  46. `cp'
  47.      concept index
  48.  
  49. `fn'
  50.      function index
  51.  
  52. `vr'
  53.      variable index
  54.  
  55. `ky'
  56.      key index
  57.  
  58. `pg'
  59.      program index
  60.  
  61. `tp'
  62.      data type index
  63.  
  64.   Write an `@syncodeindex' command before or shortly after the
  65. end-of-header line at the beginning of a Texinfo file.  For example, to
  66. merge a function index with a concept index, write the following:
  67.  
  68.      @syncodeindex fn cp
  69.  
  70. This will cause all entries designated for the function index to merge
  71. in with the concept index instead.
  72.  
  73.   To merge both a variables index and a function index into a concept
  74. index, write the following:
  75.  
  76.      @syncodeindex vr cp
  77.      @syncodeindex fn cp
  78.  
  79.   The `@syncodeindex' command puts all the entries from the `from'
  80. index (the redirected index) into the `@code' font, overriding whatever
  81. default font is used by the index to which the entries are now
  82. directed.  This way, if you direct function names from a function index
  83. into a concept index, all the function names are printed in the `@code'
  84. font as you would expect.
  85.  
  86. 
  87. File: texinfo.info,  Node: synindex,  Prev: syncodeindex,  Up: Combining Indices
  88.  
  89. `@synindex'
  90. -----------
  91.  
  92.   The `@synindex' command is nearly the same as the `@syncodeindex'
  93. command, except that it does not put the `from' index  entries into the
  94. `@code' font; rather it puts them in the roman font.  Thus, you use
  95. `@synindex' when you merge a concept index into a function index.
  96.  
  97.   *Note Printing Indices & Menus::, for information about printing an
  98. index at the end of a book or creating an index menu in an Info file.
  99.  
  100. 
  101. File: texinfo.info,  Node: New Indices,  Prev: Combining Indices,  Up: Indices
  102.  
  103. Defining New Indices
  104. ====================
  105.  
  106.   In addition to the predefined indices, you may use the `@defindex'
  107. and `@defcodeindex' commands to define new indices.  These commands
  108. create new indexing @-commands with which you mark index entries.  The
  109. `@defindex 'command is used like this:
  110.  
  111.      @defindex NAME
  112.  
  113.   The name of an index should be a two letter word, such as `au'.  For
  114. example:
  115.  
  116.      @defindex au
  117.  
  118.   This defines a new index, called the `au' index.  At the same time,
  119. it creates a new indexing command, `@auindex', that you can use to make
  120. index entries.  Use the new indexing command just as you would use a
  121. predefined indexing command.
  122.  
  123.   For example, here is a section heading followed by a concept index
  124. entry and two `au' index entries.
  125.  
  126.      @section Cognitive Semantics
  127.      @cindex kinesthetic image schemas
  128.      @auindex Johnson, Mark
  129.      @auindex Lakoff, George
  130.  
  131. (Evidently, `au' serves here as an abbreviation for "author".) Texinfo
  132. constructs the new indexing command by concatenating the name of the
  133. index with `index'; thus, defining an `au' index leads to the automatic
  134. creation of an `@auindex' command.
  135.  
  136.   Use the `@printindex' command to print the index, as you do with the
  137. predefined indices.  For example:
  138.  
  139.      @node Author Index, Subject Index, , Top
  140.      @unnumbered Author Index
  141.      
  142.      @printindex au
  143.  
  144.   The `@defcodeindex' is like the `@defindex' command, except that, in
  145. the printed output, it prints entries in an `@code' font instead of a
  146. roman font.  Thus, it parallels the `@findex' command rather than the
  147. `@cindex' command.
  148.  
  149.   You should define new indices within or right after the end-of-header
  150. line of a Texinfo file, before any `@synindex' or `@syncodeindex'
  151. commands (*note Header::.).
  152.  
  153. 
  154. File: texinfo.info,  Node: Insertions,  Next: Glyphs,  Prev: Indices,  Up: Top
  155.  
  156. Special Insertions
  157. ******************
  158.  
  159.   Texinfo provides several commands for formatting dimensions, for
  160. inserting single characters that have special meaning in Texinfo, such
  161. as braces, and for inserting special graphic symbols that do not
  162. correspond to characters, such as dots and bullets.
  163.  
  164. * Menu:
  165.  
  166. * Braces Atsigns Periods::      How to insert braces, `@' and periods.
  167. * dmn::                         How to format a dimension.
  168. * Dots Bullets::                How to insert dots and bullets.
  169. * TeX and copyright::           How to insert the TeX logo
  170.                                   and the copyright symbol.
  171. * minus::                       How to insert a minus sign.
  172. * math::                        How to format a mathematical expression.
  173.  
  174. 
  175. File: texinfo.info,  Node: Braces Atsigns Periods,  Next: dmn,  Prev: Insertions,  Up: Insertions
  176.  
  177. Inserting `@', Braces, and Periods
  178. ==================================
  179.  
  180.   `@' and curly braces are special characters in Texinfo.  To insert
  181. these characters so they appear in text, you must put an `@' in front
  182. of these characters to prevent Texinfo from misinterpreting them.
  183.  
  184.   Periods are also special.  Depending on whether the period is inside
  185. or at the end of a sentence, less or more space is inserted after a
  186. period in a typeset manual.  Since it is not always possible for
  187. Texinfo to determine when a period ends a sentence and when it is used
  188. in an abbreviation, special commands are needed in some circumstances.
  189. (Usually, Texinfo can guess how to handle periods, so you do not need
  190. to use the special commands; you just enter a period as you would if
  191. you were using a typewriter, which means you put two spaces after the
  192. period, question mark, or exclamation mark that ends a sentence.)
  193.  
  194.   Do not put braces after any of these commands; they are not necessary.
  195.  
  196. * Menu:
  197.  
  198. * Inserting An Atsign::
  199. * Inserting Braces::            How to insert `{' and `}'
  200. * Controlling Spacing::         How to insert the right amount of space
  201.                                   after punctuation within a sentence.
  202.  
  203. 
  204. File: texinfo.info,  Node: Inserting An Atsign,  Next: Inserting Braces,  Prev: Braces Atsigns Periods,  Up: Braces Atsigns Periods
  205.  
  206. Inserting `@' with @@
  207. ---------------------
  208.  
  209.   `@@' stands for a single `@' in either printed or Info output.
  210.  
  211.   Do not put braces after an `@@' command.
  212.  
  213. 
  214. File: texinfo.info,  Node: Inserting Braces,  Next: Controlling Spacing,  Prev: Inserting An Atsign,  Up: Braces Atsigns Periods
  215.  
  216. Inserting `{' and `}'with @{ and @}
  217. -----------------------------------
  218.  
  219.   `@{' stands for a single `{' in either printed or Info output.
  220.  
  221.   `@}' stands for a single `}' in either printed or Info output.
  222.  
  223.   Do not put braces after either an `@{' or an `@}' command.
  224.  
  225. 
  226. File: texinfo.info,  Node: Controlling Spacing,  Prev: Inserting Braces,  Up: Braces Atsigns Periods
  227.  
  228. Spacing After Colons and Periods
  229. --------------------------------
  230.  
  231.   Use the `@:' command after a period, question mark, exclamation mark,
  232. or colon that should not be followed by extra space.  For example, use
  233. `@:' after periods that end abbreviations which are not at the ends of
  234. sentences.  `@:' has no effect on the Info file output.
  235.  
  236.   For example,
  237.  
  238.      The s.o.p.@: has three parts ...
  239.      The s.o.p. has three parts ...
  240.  
  241. produces
  242.  
  243.      The s.o.p. has three parts ...
  244.      The s.o.p. has three parts ...
  245.  
  246. `@:' has no effect on the Info output.  (`s.o.p' is an acronym for
  247. "Standard Operating Procedure".)
  248.  
  249.   Use `@.' instead of a period at the end of a sentence that ends with
  250. a single capital letter.  Otherwise, TeX will think the letter is an
  251. abbreviation and will not insert the correct end-of-sentence spacing.
  252. Here is an example:
  253.  
  254.      Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
  255.      Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
  256.  
  257. produces
  258.  
  259.      Give it to M.I.B. and to M.E.W®  Also, give it to R.J.C®
  260.      Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
  261.  
  262.   In the Info file output, `@.' is equivalent to a simple `.'.
  263.  
  264.   The meanings of `@:' and `@.' in Texinfo are designed to work well
  265. with the Emacs sentence motion commands.  This made it necessary for
  266. them to be incompatible with some other formatting systems that use
  267. @-commands.
  268.  
  269.   Do not put braces after either an `@:' or an `@.' command.
  270.  
  271. 
  272. File: texinfo.info,  Node: dmn,  Next: Dots Bullets,  Prev: Braces Atsigns Periods,  Up: Insertions
  273.  
  274. `@dmn'{DIMENSION}: Format a Dimension
  275. =====================================
  276.  
  277.   At times, you may want to write `12pt' or `8.5in' with little or no
  278. space between the number and the abbreviation for the dimension.  You
  279. can use the `@dmn' command to do this.  On seeing the command, TeX
  280. inserts just enough space for proper typesetting; the Info formatting
  281. commands insert no space at all, since the Info file does not require
  282. it.
  283.  
  284.   To use the `@dmn' command, write the number and then follow it
  285. immediately, with no intervening space, by `@dmn', and then by the
  286. dimension within braces.
  287.  
  288. For example,
  289.  
  290.      A4 paper is 8.27@dmn{in} wide.
  291.  
  292. produces
  293.  
  294.      A4 paper is 8.27in wide.
  295.  
  296.   Not everyone uses this style.  Instead of writing `8.27@dmn{in}' in
  297. the Texinfo file, you may write `8.27 in.' or `8.27 inches'.  (In these
  298. cases, the formatters may insert a line break between the number and the
  299. dimension.  Also, if you write a period after an abbreviation within a
  300. sentence, you should write `@:' after the period to prevent TeX from
  301. inserting extra whitespace.  *Note Spacing After Colons and Periods:
  302. Controlling Spacing.)
  303.  
  304. 
  305. File: texinfo.info,  Node: Dots Bullets,  Next: TeX and copyright,  Prev: dmn,  Up: Insertions
  306.  
  307. Inserting Ellipsis, Dots, and Bullets
  308. =====================================
  309.  
  310.   An "ellipsis" (a line of dots) is not typeset as a string of periods,
  311. so a special command is used for ellipsis in Texinfo.  The `@bullet'
  312. command is special, too.  Each of these commands is followed by a pair
  313. of braces, `{}', without any whitespace between the name of the command
  314. and the braces.  (You need to use braces with these commands because
  315. you can use them next to other text; without the braces, the formatters
  316. would be confused.  *Note @-Command Syntax: Command Syntax, for further
  317. information.)
  318.  
  319. * Menu:
  320.  
  321. * dots::                        How to insert dots ...
  322. * bullet::                      How to insert a bullet.
  323.  
  324. 
  325. File: texinfo.info,  Node: dots,  Next: bullet,  Prev: Dots Bullets,  Up: Dots Bullets
  326.  
  327. `@dots'{}
  328. ---------
  329.  
  330.   Use the `@dots{}' command to generate an ellipsis, which is three
  331. dots in a row, appropriately spaced, like this: `...'.  Do not simply
  332. write three periods in the input file; that would work for the Info
  333. file output, but would produce the wrong amount of space between the
  334. periods in the printed manual.
  335.  
  336.   Similarly, the `@enddots{}' command helps you correctly set an
  337. end-of-sentence ellipsis (four dots).
  338.  
  339. 
  340. File: texinfo.info,  Node: bullet,  Prev: dots,  Up: Dots Bullets
  341.  
  342. `@bullet'{}
  343. -----------
  344.  
  345.   Use the `@bullet{}' command to generate a large round dot, or the
  346. closest possible thing to one.  In Info, an asterisk is used.
  347.  
  348.   Here is a bullet: *
  349.  
  350.   When you use `@bullet' in `@itemize', you do not need to type the
  351. braces, because `@itemize' supplies them.  (*Note `@itemize': itemize.)
  352.  
  353. 
  354. File: texinfo.info,  Node: TeX and copyright,  Next: minus,  Prev: Dots Bullets,  Up: Insertions
  355.  
  356. Inserting TeX and the Copyright Symbol
  357. ======================================
  358.  
  359.   The logo `TeX' is typeset in a special fashion and it needs an
  360. @-command.  The copyright symbol, `(C)', is also special.  Each of
  361. these commands is followed by a pair of braces, `{}', without any
  362. whitespace between the name of the command and the braces.
  363.  
  364. * Menu:
  365.  
  366. * tex::                         How to insert the TeX logo.
  367. * copyright symbol::            How to use `@copyright'{}.
  368.  
  369. 
  370. File: texinfo.info,  Node: tex,  Next: copyright symbol,  Prev: TeX and copyright,  Up: TeX and copyright
  371.  
  372. `@TeX'{}
  373. --------
  374.  
  375.   Use the `@TeX{}' command to generate `TeX'.  In a printed manual,
  376. this is a special logo that is different from three ordinary letters.
  377. In Info, it just looks like `TeX'.  The `@TeX{}' command is unique
  378. among Texinfo commands in that the T and the X are in upper case.
  379.  
  380. 
  381. File: texinfo.info,  Node: copyright symbol,  Prev: tex,  Up: TeX and copyright
  382.  
  383. `@copyright'{}
  384. --------------
  385.  
  386.   Use the `@copyright{}' command to generate `(C)'.  In a printed
  387. manual, this is a `c' inside a circle, and in Info, this is `(C)'.
  388.  
  389. 
  390. File: texinfo.info,  Node: minus,  Next: math,  Prev: TeX and copyright,  Up: Insertions
  391.  
  392. `@minus'{}: Inserting a Minus Sign
  393. ==================================
  394.  
  395.   Use the `@minus{}' command to generate a minus sign.  In a
  396. fixed-width font, this is a single hyphen, but in a proportional font,
  397. the symbol is the customary length for a minus sign--a little longer
  398. than a hyphen.
  399.  
  400.   You can compare the two forms:
  401.  
  402.      `-' is a minus sign generated with `@minus{}',
  403.      
  404.      `-' is a hyphen generated with the character `-'.
  405.  
  406. In the fixed-width font used by Info, `@minus{}' is the same as a
  407. hyphen.
  408.  
  409.   You should not use `@minus{}' inside `@code' or `@example' because
  410. the width distinction is not made in the fixed-width font they use.
  411.  
  412.   When you use `@minus' to specify the mark beginning each entry in an
  413. itemized list, you do not need to type the braces (*note `@itemize':
  414. itemize..)
  415.  
  416. 
  417. File: texinfo.info,  Node: math,  Prev: minus,  Up: Insertions
  418.  
  419. `@math': Inserting Mathematical Expressions
  420. ===========================================
  421.  
  422.   You can write a short mathematical expression with the `@math'
  423. command.  Write the mathematical expression between braces, like this:
  424.  
  425.      @math{(a + b)(a + b) = a^2 + 2ab + b^2}
  426.  
  427. This produces the following in Info:
  428.  
  429.      (a + b)(a + b) = a^2 + 2ab + b^2
  430.  
  431.   The `@math' command has no effect on the Info output.  Currently, it
  432. has limited effect on typeset output.  However, this may change since
  433. TeX itself is designed for mathematical typesetting and does a splendid
  434. job.
  435.  
  436.   Certainly, for complex mathematical expressions, you could use TeX
  437. directly.  *Note Using Ordinary TeX Commands: Using Ordinary TeX
  438. Commands.  When you use TeX directly, remember to write the
  439. mathematical expression between one or two `$' (dollar-signs) as
  440. appropriate.
  441.  
  442. 
  443. File: texinfo.info,  Node: Glyphs,  Next: Breaks,  Prev: Insertions,  Up: Top
  444.  
  445. Glyphs for Examples
  446. *******************
  447.  
  448.   In Texinfo, code is often illustrated in examples that are delimited
  449. by `@example' and `@end example', or by `@lisp' and `@end lisp'.  In
  450. such examples, you can indicate the results of evaluation or an
  451. expansion using `=>' or `==>'.  Likewise, there are commands to insert
  452. glyphs to indicate printed output, error messages, equivalence of
  453. expressions, and the location of point.
  454.  
  455.   The glyph-insertion commands do not need to be used within an
  456. example, but most often they are.  Every  glyph-insertion command is
  457. followed by a pair of left- and right-hand braces.
  458.  
  459. * Menu:
  460.  
  461. * Glyphs Summary::
  462. * result::                      How to show the result of expression.
  463. * expansion::                   How to indicate an expansion.
  464. * Print Glyph::                 How to indicate printed output.
  465. * Error Glyph::                 How to indicate an error message.
  466. * Equivalence::                 How to indicate equivalence.
  467. * Point Glyph::                 How to indicate the location of point.
  468.  
  469. 
  470. File: texinfo.info,  Node: Glyphs Summary,  Next: result,  Prev: Glyphs,  Up: Glyphs
  471.  
  472. Glyphs Summary
  473. ==============
  474.  
  475.   Here are the different glyph commands:
  476.  
  477. =>
  478.      `@result{}' points to the result of an expression.
  479.  
  480. ==>
  481.      `@expansion{}' shows the results of a macro expansion.
  482.  
  483. -|
  484.      `@print{}' indicates printed output.
  485.  
  486. error-->
  487.      `@error{}' indicates that the following text is an error message.
  488.  
  489. ==
  490.      `@equiv{}' indicates the exact equivalence of two forms.
  491.  
  492. -!-
  493.      `@point{}' shows the location of point.
  494.  
  495. 
  496. File: texinfo.info,  Node: result,  Next: expansion,  Prev: Glyphs Summary,  Up: Glyphs
  497.  
  498. =>: Indicating Evaluation
  499. =========================
  500.  
  501.   Use the `@result{}' command to indicate the result of evaluating an
  502. expression.
  503.  
  504.   The `@result{}' command is displayed as `=>' in Info and as a double
  505. stemmed arrow in the printed output.
  506.  
  507.   Thus, the following,
  508.  
  509.      (cdr '(1 2 3))
  510.           => (2 3)
  511.  
  512. may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
  513.  
  514. 
  515. File: texinfo.info,  Node: expansion,  Next: Print Glyph,  Prev: result,  Up: Glyphs
  516.  
  517. ==>: Indicating an Expansion
  518. ============================
  519.  
  520.   When an expression is a macro call, it expands into a new expression.
  521. You can indicate the result of the expansion with the `@expansion{}'
  522. command.
  523.  
  524.   The `@expansion{}' command is displayed as `==>' in Info and as a
  525. long arrow with a flat base in the printed output.
  526.  
  527.   For example, the following
  528.  
  529.      @lisp
  530.      (third '(a b c))
  531.           @expansion{} (car (cdr (cdr '(a b c))))
  532.           @result{} c
  533.      @end lisp
  534.  
  535. produces
  536.  
  537.      (third '(a b c))
  538.           ==> (car (cdr (cdr '(a b c))))
  539.           => c
  540.  
  541. which may be read as:
  542.  
  543.      `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
  544.      result of evaluating the expression is `c'.
  545.  
  546. Often, as in this case, an example looks better if the `@expansion{}'
  547. and `@result{}' commands are indented five spaces.
  548.  
  549. 
  550. File: texinfo.info,  Node: Print Glyph,  Next: Error Glyph,  Prev: expansion,  Up: Glyphs
  551.  
  552. -|: Indicating Printed Output
  553. =============================
  554.  
  555.   Sometimes an expression will print output during its execution.  You
  556. can indicate the printed output with the `@print{}' command.
  557.  
  558.   The `@print{}' command is displayed as `-|' in Info and similarly, as
  559. a horizontal dash butting against a vertical bar, in the printed output.
  560.  
  561.   In the following example, the printed text is indicated with `-|',
  562. and the value of the expression follows on the last line.
  563.  
  564.      (progn (print 'foo) (print 'bar))
  565.           -| foo
  566.           -| bar
  567.           => bar
  568.  
  569. In a Texinfo source file, this example is written as follows:
  570.  
  571.      @lisp
  572.      (progn (print 'foo) (print 'bar))
  573.           @print{} foo
  574.           @print{} bar
  575.           @result{} bar
  576.      @end lisp
  577.  
  578. 
  579. File: texinfo.info,  Node: Error Glyph,  Next: Equivalence,  Prev: Print Glyph,  Up: Glyphs
  580.  
  581. error-->: Indicating an Error Message
  582. =====================================
  583.  
  584.   A piece of code may cause an error when you evaluate it.  You can
  585. designate the error message with the `@error{}' command.
  586.  
  587.   The `@error{}' command is displayed as `error-->' in Info and as the
  588. word `error' in a box in the printed output.
  589.  
  590.   Thus,
  591.  
  592.      @lisp
  593.      (+ 23 'x)
  594.      @error{} Wrong type argument: integer-or-marker-p, x
  595.      @end lisp
  596.  
  597. produces
  598.  
  599.      (+ 23 'x)
  600.      error--> Wrong type argument: integer-or-marker-p, x
  601.  
  602. This indicates that the following error message is printed when you
  603. evaluate the expression:
  604.  
  605.      Wrong type argument: integer-or-marker-p, x
  606.  
  607.   Note that `error-->' itself is not part of the error message.
  608.  
  609. 
  610. File: texinfo.info,  Node: Equivalence,  Next: Point Glyph,  Prev: Error Glyph,  Up: Glyphs
  611.  
  612. ==: Indicating Equivalence
  613. ==========================
  614.  
  615.   Sometimes two expressions produce identical results.  You can
  616. indicate the exact equivalence of two forms with the `@equiv{}' command.
  617.  
  618.   The `@equiv{}' command is displayed as `==' in Info and as a three
  619. parallel horizontal lines in the printed output.
  620.  
  621.   Thus,
  622.  
  623.      @lisp
  624.      (make-sparse-keymap) @equiv{} (list 'keymap)
  625.      @end lisp
  626.  
  627. produces
  628.  
  629.      (make-sparse-keymap) == (list 'keymap)
  630.  
  631. This indicates that evaluating `(make-sparse-keymap)' produces
  632. identical results to evaluating `(list 'keymap)'.
  633.  
  634. 
  635. File: texinfo.info,  Node: Point Glyph,  Prev: Equivalence,  Up: Glyphs
  636.  
  637. Indicating Point in a Buffer
  638. ============================
  639.  
  640.   Sometimes you need to show an example of text in an Emacs buffer.  In
  641. such examples, the convention is to include the entire contents of the
  642. buffer in question between two lines of dashes containing the buffer
  643. name.
  644.  
  645.   You can use the `@point{}' command to show the location of point in
  646. the text in the buffer.  (The symbol for point, of course, is not part
  647. of the text in the buffer; it indicates the place *between* two
  648. characters where point is located.)
  649.  
  650.   The `@point{}' command is displayed as `-!-' in Info and as a small
  651. five pointed star in the printed output.
  652.  
  653.   The following example shows the contents of buffer `foo' before and
  654. after evaluating a Lisp command to insert the word `changed'.
  655.  
  656.      ---------- Buffer: foo ----------
  657.      This is the -!-contents of foo.
  658.      ---------- Buffer: foo ----------
  659.  
  660.      (insert "changed ")
  661.           => nil
  662.      ---------- Buffer: foo ----------
  663.      This is the changed -!-contents of foo.
  664.      ---------- Buffer: foo ----------
  665.  
  666.   In a Texinfo source file, the example is written like this:
  667.  
  668.      @example
  669.      ---------- Buffer: foo ----------
  670.      This is the @point{}contents of foo.
  671.      ---------- Buffer: foo ----------
  672.      
  673.      (insert "changed ")
  674.           @result{} nil
  675.      ---------- Buffer: foo ----------
  676.      This is the changed @point{}contents of foo.
  677.      ---------- Buffer: foo ----------
  678.      @end example
  679.  
  680. 
  681. File: texinfo.info,  Node: Breaks,  Next: Definition Commands,  Prev: Glyphs,  Up: Top
  682.  
  683. Making and Preventing Breaks
  684. ****************************
  685.  
  686.   Usually, a Texinfo file is processed both by TeX and by one of the
  687. Info formatting commands.  Line, paragraph, or page breaks sometimes
  688. occur in the `wrong' place in one or other form of output.  You must
  689. ensure that text looks right both in the printed manual and in the Info
  690. file.
  691.  
  692.   For example, in a printed manual, page breaks may occur awkwardly in
  693. the middle of an example; to prevent this, you can hold text together
  694. using a grouping command that keeps the text from being split across
  695. two pages.  Conversely, you may want to force a page break where none
  696. would occur normally.  Fortunately, problems like these do not often
  697. arise.  When they do, use the break, break prevention, or pagination
  698. commands.
  699.  
  700. * Menu:
  701.  
  702. * Break Commands::              Cause and prevent splits.
  703. * Line Breaks::                 How to force a single line to use two lines.
  704. * w::                           How to prevent unwanted line breaks.
  705. * sp::                          How to insert blank lines.
  706. * page::                        How to force the start of a new page.
  707. * group::                       How to prevent unwanted page breaks.
  708. * need::                        Another way to prevent unwanted page breaks.
  709.  
  710. 
  711. File: texinfo.info,  Node: Break Commands,  Next: Line Breaks,  Prev: Breaks,  Up: Breaks
  712.  
  713. The Break Commands
  714. ==================
  715.  
  716.   The break commands create line and paragraph breaks:
  717.  
  718. `@*'
  719.      Force a line break.
  720.  
  721. `@sp N'
  722.      Skip N blank lines.
  723.  
  724.   The line-break-prevention command holds text together all on one line:
  725.  
  726. `@w{TEXT}'
  727.      Prevent TEXT from being split and hyphenated across two lines.
  728.  
  729.   The pagination commands apply only to printed output, since Info
  730. files do not have pages.
  731.  
  732. `@page'
  733.      Start a new page in the printed manual.
  734.  
  735. `@group'
  736.      Hold text together that must appear on one printed page.
  737.  
  738. `@need MILS'
  739.      Start a new printed page if not enough space on this one.
  740.  
  741. 
  742. File: texinfo.info,  Node: Line Breaks,  Next: w,  Prev: Break Commands,  Up: Breaks
  743.  
  744. `@*': Generate Line Breaks
  745. ==========================
  746.  
  747.   The `@*' command forces a line break in both the printed manual and
  748. in Info.
  749.  
  750.   For example,
  751.  
  752.      This line @* is broken @*in two places.
  753.  
  754. produces
  755.  
  756.      This line
  757.       is broken
  758.      in two places.
  759.  
  760. (Note that the space after the first `@*' command is faithfully carried
  761. down to the next line.)
  762.  
  763.   The `@*' command is often used in a file's copyright page:
  764.  
  765.      This is edition 2.0 of the Texinfo documentation,@*
  766.      and is for ...
  767.  
  768. In this case, the `@*' command keeps TeX from stretching the line
  769. across the whole page in an ugly manner.
  770.  
  771.      *Please note:* Do not write braces after an `@*' command; they are
  772.      not needed.
  773.  
  774.      Do not write an `@refill' command at the end of a paragraph
  775.      containing an `@*' command; it will cause the paragraph to be
  776.      refilled after the line break occurs, negating the effect of the
  777.      line break.
  778.  
  779. 
  780. File: texinfo.info,  Node: w,  Next: sp,  Prev: Line Breaks,  Up: Breaks
  781.  
  782. `@w'{TEXT}: Prevent Line Breaks
  783. ===============================
  784.  
  785.   `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
  786.  
  787.   You can use the `@w' command to prevent TeX from automatically
  788. hyphenating a long name or phrase that accidentally falls near the end
  789. of a line.
  790.  
  791.      You can copy GNU software from @w{@file{prep.ai.mit.edu}}.
  792.  
  793. produces
  794.  
  795.      You can copy GNU software from `prep.ai.mit.edu'.
  796.  
  797.   In the Texinfo file, you must write the `@w' command and its argument
  798. (all the affected text) all on one line.
  799.  
  800.      *Caution:* Do not write an `@refill' command at the end of a
  801.      paragraph containing an `@w' command; it will cause the paragraph
  802.      to be refilled and may thereby negate the effect of the `@w'
  803.      command.
  804.  
  805. 
  806. File: texinfo.info,  Node: sp,  Next: page,  Prev: w,  Up: Breaks
  807.  
  808. `@sp' N: Insert Blank Lines
  809. ===========================
  810.  
  811.   A line beginning with and containing only `@sp N' generates N blank
  812. lines of space in both the printed manual and the Info file.  `@sp'
  813. also forces a paragraph break.  For example,
  814.  
  815.      @sp 2
  816.  
  817. generates two blank lines.
  818.  
  819.   The `@sp' command is most often used in the title page.
  820.  
  821. 
  822. File: texinfo.info,  Node: page,  Next: group,  Prev: sp,  Up: Breaks
  823.  
  824. `@page': Start a New Page
  825. =========================
  826.  
  827.   A line containing only `@page' starts a new page in a printed manual.
  828. The command has no effect on Info files since they are not paginated.
  829. An `@page' command is often used in the `@titlepage' section of a
  830. Texinfo file to start the copyright page.
  831.  
  832. 
  833. File: texinfo.info,  Node: group,  Next: need,  Prev: page,  Up: Breaks
  834.  
  835. `@group': Prevent Page Breaks
  836. =============================
  837.  
  838.   The `@group' command (on a line by itself) is used inside an
  839. `@example' or similar construct to begin an unsplittable vertical
  840. group, which will appear entirely on one page in the printed output.
  841. The group is terminated by a line containing only `@end group'.  These
  842. two lines produce no output of their own, and in the Info file output
  843. they have no effect at all.
  844.  
  845.   Although `@group' would make sense conceptually in a wide variety of
  846. contexts, its current implementation works reliably only within
  847. `@example' and variants, and within `@display', `@format', `@flushleft'
  848. and `@flushright'.  *Note Quotations and Examples::.  (What all these
  849. commands have in common is that each line of input produces a line of
  850. output.)  In other contexts, `@group' can cause anomalous vertical
  851. spacing.
  852.  
  853.   This formatting requirement means that you should write:
  854.  
  855.      @example
  856.      @group
  857.      ...
  858.      @end group
  859.      @end example
  860.  
  861. with the `@group' and `@end group' commands inside the `@example' and
  862. `@end example' commands.
  863.  
  864.   The `@group' command is most often used to hold an example together
  865. on one page.  In this Texinfo manual, more than 100 examples contain
  866. text that is enclosed between `@group' and `@end group'.
  867.  
  868.   If you forget to end a group, you may get strange and unfathomable
  869. error messages when you run TeX.  This is because TeX keeps trying to
  870. put the rest of the Texinfo file onto the one page and does not start
  871. to generate error messages until it has processed considerable text.
  872. It is a good rule of thumb to look for a missing `@end group' if you
  873. get incomprehensible error messages in TeX.
  874.  
  875. 
  876. File: texinfo.info,  Node: need,  Prev: group,  Up: Breaks
  877.  
  878. `@need MILS': Prevent Page Breaks
  879. =================================
  880.  
  881.   A line containing only `@need N' starts a new page in a printed
  882. manual if fewer than N mils (thousandths of an inch) remain on the
  883. current page.  Do not use braces around the argument N.  The `@need'
  884. command has no effect on Info files since they are not paginated.
  885.  
  886.   This paragraph is preceded by an `@need' command that tells TeX to
  887. start a new page if fewer than 800 mils (eight-tenths inch) remain on
  888. the page.  It looks like this:
  889.  
  890.      @need 800
  891.      This paragraph is preceded by ...
  892.  
  893.   The `@need' command is useful for preventing orphans (single lines at
  894. the bottoms of printed pages).
  895.  
  896. 
  897. File: texinfo.info,  Node: Definition Commands,  Next: Footnotes,  Prev: Breaks,  Up: Top
  898.  
  899. Definition Commands
  900. *******************
  901.  
  902.   The `@deffn' command and the other "definition commands" enable you
  903. to describe functions, variables, macros, commands, user options,
  904. special forms and other such artifacts in a uniform format.
  905.  
  906.   In the Info file, a definition causes the entity
  907. category--`Function', `Variable', or whatever--to appear at the
  908. beginning of the first line of the definition, followed by the entity's
  909. name and arguments.  In the printed manual, the command causes TeX to
  910. print the entity's name and its arguments on the left margin and print
  911. the category next to the right margin.  In both output formats, the
  912. body of the definition is indented.  Also, the name of the entity is
  913. entered into the appropriate index: `@deffn' enters the name into the
  914. index of functions, `@defvr' enters it into the index of variables, and
  915. so on.
  916.  
  917.   A manual need not and should not contain more than one definition for
  918. a given name.  An appendix containing a summary should use `@table'
  919. rather than the definition commands.
  920.  
  921. * Menu:
  922.  
  923. * Def Cmd Template::            How to structure a description using a
  924.                                   definition command.
  925. * Optional Arguments::          How to handle optional and repeated arguments.
  926. * deffnx::                      How to group two or more `first' lines.
  927. * Def Cmds in Detail::          All the definition commands.
  928. * Def Cmd Conventions::         Conventions for writing definitions.
  929. * Sample Function Definition::
  930.  
  931. 
  932. File: texinfo.info,  Node: Def Cmd Template,  Next: Optional Arguments,  Prev: Definition Commands,  Up: Definition Commands
  933.  
  934. The Template for a Definition
  935. =============================
  936.  
  937.   The `@deffn' command is used for definitions of entities that
  938. resemble functions.  To write a definition using the `@deffn' command,
  939. write the `@deffn' command at the beginning of a line and follow it on
  940. the same line by the category of the entity, the name of the entity
  941. itself, and its arguments (if any).  Then write the body of the
  942. definition on succeeding lines.  (You may embed examples in the body.)
  943. Finally, end the definition with an `@end deffn' command written on a
  944. line of its own.  (The other definition commands follow the same
  945. format.)
  946.  
  947.   The template for a definition looks like this:
  948.  
  949.      @deffn CATEGORY NAME ARGUMENTS...
  950.      BODY-OF-DEFINITION
  951.      @end deffn
  952.  
  953. For example,
  954.  
  955.      @deffn Command forward-word count
  956.      This command moves point forward @var{count} words
  957.      (or backward if @var{count} is negative). ...
  958.      @end deffn
  959.  
  960. produces
  961.  
  962.       - Command: forward-word COUNT
  963.           This function moves point forward COUNT words (or backward if
  964.           COUNT is negative). ...
  965.  
  966.   Capitalize the category name like a title.  If the name of the
  967. category contains spaces, as in the phrase `Interactive Command', write
  968. braces around it.  For example:
  969.  
  970.      @deffn {Interactive Command} isearch-forward
  971.      ...
  972.      @end deffn
  973.  
  974. Otherwise, the second word will be mistaken for the name of the entity.
  975.  
  976.   Some of the definition commands are more general than others.  The
  977. `@deffn' command, for example, is the general definition command for
  978. functions and the like--for entities that may take arguments.  When you
  979. use this command, you specify the category to which the entity belongs.
  980. The `@deffn' command possesses three predefined, specialized
  981. variations, `@defun', `@defmac', and `@defspec', that specify the
  982. category for you: "Function", "Macro", and "Special Form" respectively.
  983. The `@defvr' command also is accompanied by several predefined,
  984. specialized variations for describing particular kinds of variables.
  985.  
  986.   The template for a specialized definition, such as `@defun', is
  987. similar to the template for a generalized definition, except that you
  988. do not need to specify the category:
  989.  
  990.      @defun NAME ARGUMENTS...
  991.      BODY-OF-DEFINITION
  992.      @end defun
  993.  
  994. Thus,
  995.  
  996.      @defun buffer-end flag
  997.      This function returns @code{(point-min)} if @var{flag}
  998.      is less than 1, @code{(point-max)} otherwise.
  999.      ...
  1000.      @end defun
  1001.  
  1002. produces
  1003.  
  1004.       - Function: buffer-end FLAG
  1005.           This function returns `(point-min)' if FLAG is less than 1,
  1006.           `(point-max)' otherwise.  ...
  1007.  
  1008. *Note Sample Function Definition: Sample Function Definition, for a
  1009. more detailed example of a function definition, including the use of
  1010. `@example' inside the definition.
  1011.  
  1012.   The other specialized commands work like `@defun'.
  1013.  
  1014. 
  1015. File: texinfo.info,  Node: Optional Arguments,  Next: deffnx,  Prev: Def Cmd Template,  Up: Definition Commands
  1016.  
  1017. Optional and Repeated Arguments
  1018. ===============================
  1019.  
  1020.   Some entities take optional or repeated arguments, which may be
  1021. specified by a distinctive glyph that uses square brackets and
  1022. ellipses.  For example, a special form often breaks its argument list
  1023. into separate arguments in more complicated ways than a straightforward
  1024. function.
  1025.  
  1026.   An argument enclosed within square brackets is optional.  Thus,
  1027. [OPTIONAL-ARG] means that OPTIONAL-ARG is optional.  An argument
  1028. followed by an ellipsis is optional and may be repeated more than once.
  1029. Thus, REPEATED-ARGS... stands for zero or more arguments.  Parentheses
  1030. are used when several arguments are grouped into additional levels of
  1031. list structure in Lisp.
  1032.  
  1033.   Here is the `@defspec' line of an example of an imaginary special
  1034. form:
  1035.  
  1036.       - Special Form: foobar (VAR [FROM TO [INC]]) BODY...
  1037.  
  1038. In this example, the arguments FROM and TO are optional, but must both
  1039. be present or both absent.  If they are present, INC may optionally be
  1040. specified as well.  These arguments are grouped with the argument VAR
  1041. into a list, to distinguish them from BODY, which includes all
  1042. remaining elements of the form.
  1043.  
  1044.   In a Texinfo source file, this `@defspec' line is written like this
  1045. (except it would not be split over two lines, as it is in this example).
  1046.  
  1047.      @defspec foobar (@var{var} [@var{from} @var{to}
  1048.           [@var{inc}]]) @var{body}@dots{}
  1049.  
  1050. The function is listed in the Command and Variable Index under `foobar'.
  1051.  
  1052. 
  1053. File: texinfo.info,  Node: deffnx,  Next: Def Cmds in Detail,  Prev: Optional Arguments,  Up: Definition Commands
  1054.  
  1055. Two or More `First' Lines
  1056. =========================
  1057.  
  1058.   To create two or more `first' or header lines for a definition, follow
  1059. the first `@deffn' line by a line beginning with `@deffnx'.  The
  1060. `@deffnx' command works exactly like `@deffn' except that it does not
  1061. generate extra vertical white space between it and the preceding line.
  1062.  
  1063.   For example,
  1064.  
  1065.      @deffn {Interactive Command} isearch-forward
  1066.      @deffnx {Interactive Command} isearch-backward
  1067.      These two search commands are similar except ...
  1068.      @end deffn
  1069.  
  1070. produces
  1071.  
  1072.  - Interactive Command: isearch-forward
  1073.  - Interactive Command: isearch-backward
  1074.      These two search commands are similar except ...
  1075.  
  1076.   Each of the other definition commands has an `x' form: `@defunx',
  1077. `@defvrx', `@deftypefunx', etc.
  1078.  
  1079.   The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
  1080.  
  1081. 
  1082. File: texinfo.info,  Node: Def Cmds in Detail,  Next: Def Cmd Conventions,  Prev: deffnx,  Up: Definition Commands
  1083.  
  1084. The Definition Commands
  1085. =======================
  1086.  
  1087.   Texinfo provides more than a dozen definition commands, all of which
  1088. are described in this section.
  1089.  
  1090.   The definition commands automatically enter the name of the entity in
  1091. the appropriate index: for example, `@deffn', `@defun', and `@defmac'
  1092. enter function names in the index of functions; `@defvr' and `@defvar'
  1093. enter variable names in the index of variables.
  1094.  
  1095.   Although the examples that follow mostly illustrate Lisp, the commands
  1096. can be used for other programming languages.
  1097.  
  1098. * Menu:
  1099.  
  1100. * Functions Commands::          Commands for functions and similar entities.
  1101. * Variables Commands::          Commands for variables and similar entities.
  1102. * Typed Functions::             Commands for functions in typed languages.
  1103. * Typed Variables::             Commands for variables in typed languages.
  1104. * Abstract Objects::            Commands for object-oriented programming.
  1105. * Data Types::                  The definition command for data types.
  1106.  
  1107. 
  1108. File: texinfo.info,  Node: Functions Commands,  Next: Variables Commands,  Prev: Def Cmds in Detail,  Up: Def Cmds in Detail
  1109.  
  1110. Functions and Similar Entities
  1111. ------------------------------
  1112.  
  1113.   This section describes the commands for describing functions and
  1114. similar entities:
  1115.  
  1116. `@deffn CATEGORY NAME ARGUMENTS...'
  1117.      The `@deffn' command is the general definition command for
  1118.      functions, interactive commands, and similar entities that may take
  1119.      arguments.  You must choose a term to describe the category of
  1120.      entity being defined; for example, "Function" could be used if the
  1121.      entity is a function.  The `@deffn' command is written at the
  1122.      beginning of a line and is followed on the same line by the
  1123.      category of entity being described, the name of this particular
  1124.      entity, and its arguments, if any.  Terminate the definition with
  1125.      `@end deffn' on a line of its own.
  1126.  
  1127.      For example, here is a definition:
  1128.  
  1129.           @deffn Command forward-char nchars
  1130.           Move point forward @var{nchars} characters.
  1131.           @end deffn
  1132.  
  1133.      This shows a rather terse definition for a "command" named
  1134.      `forward-char' with one argument, NCHARS.
  1135.  
  1136.      `@deffn' prints argument names such as NCHARS in italics or upper
  1137.      case, as if `@var' had been used, because we think of these names
  1138.      as metasyntactic variables--they stand for the actual argument
  1139.      values.  Within the text of the description, write an argument name
  1140.      explicitly with `@var' to refer to the value of the argument.  In
  1141.      the example above, we used `@var{nchars}' in this way.
  1142.  
  1143.      The template for `@deffn' is:
  1144.  
  1145.           @deffn CATEGORY NAME ARGUMENTS...
  1146.           BODY-OF-DEFINITION
  1147.           @end deffn
  1148.  
  1149. `@defun NAME ARGUMENTS...'
  1150.      The `@defun' command is the definition command for functions.
  1151.      `@defun' is equivalent to `@deffn Function ...'.
  1152.  
  1153.      For example,
  1154.  
  1155.           @defun set symbol new-value
  1156.           Change the value of the symbol @var{symbol}
  1157.           to @var{new-value}.
  1158.           @end defun
  1159.  
  1160.      shows a rather terse definition for a function `set' whose
  1161.      arguments are SYMBOL and NEW-VALUE.  The argument names on the
  1162.      `@defun' line automatically appear in italics or upper case as if
  1163.      they were enclosed in `@var'.  Terminate the definition with `@end
  1164.      defun' on a line of its own.
  1165.  
  1166.      The template is:
  1167.  
  1168.           @defun FUNCTION-NAME ARGUMENTS...
  1169.           BODY-OF-DEFINITION
  1170.           @end defun
  1171.  
  1172.      `@defun' creates an entry in the index of functions.
  1173.  
  1174. `@defmac NAME ARGUMENTS...'
  1175.      The `@defmac' command is the definition command for macros.
  1176.      `@defmac' is equivalent to `@deffn Macro ...' and works like
  1177.      `@defun'.
  1178.  
  1179. `@defspec NAME ARGUMENTS...'
  1180.      The `@defspec' command is the definition command for special
  1181.      forms.  (In Lisp, a special form is an entity much like a
  1182.      function.) `@defspec' is equivalent to `@deffn {Special Form} ...'
  1183.      and works like `@defun'.
  1184.  
  1185. 
  1186. File: texinfo.info,  Node: Variables Commands,  Next: Typed Functions,  Prev: Functions Commands,  Up: Def Cmds in Detail
  1187.  
  1188. Variables and Similar Entities
  1189. ------------------------------
  1190.  
  1191.   Here are the commands for defining variables and similar entities:
  1192.  
  1193. `@defvr CATEGORY NAME'
  1194.      The `@defvr' command is a general definition command for something
  1195.      like a variable--an entity that records a value.  You must choose
  1196.      a term to describe the category of entity being defined; for
  1197.      example, "Variable" could be used if the entity is a variable.
  1198.      Write the `@defvr' command at the beginning of a line and followed
  1199.      it on the same line by the category of the entity and the name of
  1200.      the entity.
  1201.  
  1202.      Capitalize the category name like a title.  If the name of the
  1203.      category contains spaces, as in the name `User Option', write
  1204.      braces around it.  Otherwise, the second word will be mistaken for
  1205.      the name of the entity, for example:
  1206.  
  1207.           @defvr {User Option} fill-column
  1208.           This buffer-local variable specifies
  1209.           the maximum width of filled lines.
  1210.           ...
  1211.           @end defvr
  1212.  
  1213.      Terminate the definition with `@end defvr' on a line of its own.
  1214.  
  1215.      The template is:
  1216.  
  1217.           @defvr CATEGORY NAME
  1218.           BODY-OF-DEFINITION
  1219.           @end defvr
  1220.  
  1221.      `@defvr' creates an entry in the index of variables for NAME.
  1222.  
  1223. `@defvar NAME'
  1224.      The `@defvar' command is the definition command for variables.
  1225.      `@defvar' is equivalent to `@defvr Variable ...'.
  1226.  
  1227.      For example:
  1228.  
  1229.           @defvar kill-ring
  1230.           ...
  1231.           @end defvar
  1232.  
  1233.      The template is:
  1234.  
  1235.           @defvar NAME
  1236.           BODY-OF-DEFINITION
  1237.           @end defvar
  1238.  
  1239.      `@defvar' creates an entry in the index of variables for NAME.
  1240.  
  1241. `@defopt NAME'
  1242.      The `@defopt' command is the definition command for user options.
  1243.      `@defopt' is equivalent to `@defvr {User Option} ...' and works
  1244.      like `@defvar'.
  1245.  
  1246. 
  1247. File: texinfo.info,  Node: Typed Functions,  Next: Typed Variables,  Prev: Variables Commands,  Up: Def Cmds in Detail
  1248.  
  1249. Functions in Typed Languages
  1250. ----------------------------
  1251.  
  1252.   The `@deftypefn' command and its variations are for describing
  1253. functions in C or any other language in which you must declare types of
  1254. variables and functions.
  1255.  
  1256. `@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
  1257.      The `@deftypefn' command is the general definition command for
  1258.      functions and similar entities that may take arguments and that are
  1259.      typed.  The `@deftypefn' command is written at the beginning of a
  1260.      line and is followed on the same line by the category of entity
  1261.      being described, the type of the returned value, the name of this
  1262.      particular entity, and its arguments, if any.
  1263.  
  1264.      For example,
  1265.  
  1266.           @deftypefn {Library Function} int foobar
  1267.              (int @var{foo}, float @var{bar})
  1268.           ...
  1269.           @end deftypefn
  1270.  
  1271.      (where the text before the "...", shown above as two lines, would
  1272.      actually be a single line in a real Texinfo file) produces the
  1273.      following in Info:
  1274.  
  1275.           -- Library Function: int foobar (int FOO, float BAR)
  1276.           ...
  1277.  
  1278.      This means that `foobar' is a "library function" that returns an
  1279.      `int', and its arguments are FOO (an `int') and BAR (a `float').
  1280.  
  1281.      The argument names that you write in `@deftypefn' are not subject
  1282.      to an implicit `@var'--since the actual names of the arguments in
  1283.      `@deftypefn' are typically scattered among data type names and
  1284.      keywords, Texinfo cannot find them without help.  Instead, you
  1285.      must write `@var' explicitly around the argument names.  In the
  1286.      example above, the argument names are `foo' and `bar'.
  1287.  
  1288.      The template for `@deftypefn' is:
  1289.  
  1290.           @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
  1291.           BODY-OF-DESCRIPTION
  1292.           @end deftypefn
  1293.  
  1294.      Note that if the CATEGORY or DATA TYPE is more than one word then
  1295.      it must be enclosed in braces to make it a single argument.
  1296.  
  1297.      If you are describing a procedure in a language that has packages,
  1298.      such as Ada, you might consider using `@deftypefn' in a manner
  1299.      somewhat contrary to the convention described in the preceding
  1300.      paragraphs.
  1301.  
  1302.      For example:
  1303.  
  1304.           @deftypefn stacks private push
  1305.                   (@var{s}:in out stack;
  1306.                   @var{n}:in integer)
  1307.           ...
  1308.           @end deftypefn
  1309.  
  1310.      (The `@deftypefn' arguments are shown split into three lines, but
  1311.      would be a single line in a real Texinfo file.)
  1312.  
  1313.      In this instance, the procedure is classified as belonging to the
  1314.      package `stacks' rather than classified as a `procedure' and its
  1315.      data type is described as `private'.  (The name of the procedure
  1316.      is `push', and its arguments are S and N.)
  1317.  
  1318.      `@deftypefn' creates an entry in the index of functions for NAME.
  1319.  
  1320. `@deftypefun DATA-TYPE NAME ARGUMENTS...'
  1321.      The `@deftypefun' command is the specialized definition command
  1322.      for functions in typed languages.  The command is equivalent to
  1323.      `@deftypefn Function ...'.
  1324.  
  1325.      Thus,
  1326.  
  1327.           @deftypefun int foobar (int @var{foo}, float @var{bar})
  1328.           ...
  1329.           @end deftypefun
  1330.  
  1331.      produces the following in Info:
  1332.  
  1333.           -- Function: int foobar (int FOO, float BAR)
  1334.           ...
  1335.  
  1336.      The template is:
  1337.  
  1338.           @deftypefun TYPE NAME ARGUMENTS...
  1339.           BODY-OF-DESCRIPTION
  1340.           @end deftypefun
  1341.  
  1342.      `@deftypefun' creates an entry in the index of functions for NAME.
  1343.  
  1344. 
  1345. File: texinfo.info,  Node: Typed Variables,  Next: Abstract Objects,  Prev: Typed Functions,  Up: Def Cmds in Detail
  1346.  
  1347. Variables in Typed Languages
  1348. ----------------------------
  1349.  
  1350.   Variables in typed languages are handled in a manner similar to
  1351. functions in typed languages.  *Note Typed Functions::.  The general
  1352. definition command `@deftypevr' corresponds to `@deftypefn' and the
  1353. specialized definition command `@deftypevar' corresponds to
  1354. `@deftypefun'.
  1355.  
  1356. `@deftypevr CATEGORY DATA-TYPE NAME'
  1357.      The `@deftypevr' command is the general definition command for
  1358.      something like a variable in a typed language--an entity that
  1359.      records a value.  You must choose a term to describe the category
  1360.      of the entity being defined; for example, "Variable" could be used
  1361.      if the entity is a variable.
  1362.  
  1363.      The `@deftypevr' command is written at the beginning of a line and
  1364.      is followed on the same line by the category of the entity being
  1365.      described, the data type, and the name of this particular entity.
  1366.  
  1367.      For example:
  1368.  
  1369.           @deftypevr {Global Flag} int enable
  1370.           ...
  1371.           @end deftypevr
  1372.  
  1373.      produces the following in Info:
  1374.  
  1375.           -- Global Flag: int enable
  1376.           ...
  1377.  
  1378.      The template is:
  1379.  
  1380.           @deftypevr CATEGORY DATA-TYPE NAME
  1381.           BODY-OF-DESCRIPTION
  1382.           @end deftypevr
  1383.  
  1384.      `@deftypevr' creates an entry in the index of variables for NAME.
  1385.  
  1386. `@deftypevar DATA-TYPE NAME'
  1387.      The `@deftypevar' command is the specialized definition command
  1388.      for variables in typed languages.  `@deftypevar' is equivalent to
  1389.      `@deftypevr Variable ...'.
  1390.  
  1391.      For example:
  1392.  
  1393.           @deftypevar int fubar
  1394.           ...
  1395.           @end deftypevar
  1396.  
  1397.      produces the following in Info:
  1398.  
  1399.           -- Variable: int fubar
  1400.           ...
  1401.  
  1402.      The template is:
  1403.  
  1404.           @deftypevar DATA-TYPE NAME
  1405.           BODY-OF-DESCRIPTION
  1406.           @end deftypevar
  1407.  
  1408.      `@deftypevar' creates an entry in the index of variables for NAME.
  1409.  
  1410.