85 |
format. |
format. |
86 |
</p> |
</p> |
87 |
<p>In the Info file, a definition causes the entity |
<p>In the Info file, a definition causes the entity |
88 |
category--`Function', `Variable', or whatever--to appear at the |
category—`Function', `Variable', or whatever—to appear at the |
89 |
beginning of the first line of the definition, followed by the |
beginning of the first line of the definition, followed by the |
90 |
entity's name and arguments. In the printed manual, the command |
entity's name and arguments. In the printed manual, the command |
91 |
causes TeX to print the entity's name and its arguments on the left |
causes TeX to print the entity's name and its arguments on the left |
187 |
</p> |
</p> |
188 |
<p>Some of the definition commands are more general than others. The |
<p>Some of the definition commands are more general than others. The |
189 |
<code>@deffn</code> command, for example, is the general definition command |
<code>@deffn</code> command, for example, is the general definition command |
190 |
for functions and the like--for entities that may take arguments. When |
for functions and the like—for entities that may take arguments. When |
191 |
you use this command, you specify the category to which the entity |
you use this command, you specify the category to which the entity |
192 |
belongs. The <code>@deffn</code> command possesses three predefined, |
belongs. The <code>@deffn</code> command possesses three predefined, |
193 |
specialized variations, <code>@defun</code>, <code>@defmac</code>, and |
specialized variations, <code>@defun</code>, <code>@defmac</code>, and |
194 |
<code>@defspec</code>, that specify the category for you: "Function", |
<code>@defspec</code>, that specify the category for you: “Function”, |
195 |
"Macro", and "Special Form" respectively. (In Lisp, a special form |
“Macro”, and “Special Form” respectively. (In Lisp, a special form |
196 |
is an entity much like a function.) The <code>@defvr</code> command also is |
is an entity much like a function.) The <code>@defvr</code> command also is |
197 |
accompanied by several predefined, specialized variations for describing |
accompanied by several predefined, specialized variations for describing |
198 |
particular kinds of variables. |
particular kinds of variables. |
432 |
<dd><p>The <code>@deffn</code> command is the general definition command for |
<dd><p>The <code>@deffn</code> command is the general definition command for |
433 |
functions, interactive commands, and similar entities that may take |
functions, interactive commands, and similar entities that may take |
434 |
arguments. You must choose a term to describe the category of entity |
arguments. You must choose a term to describe the category of entity |
435 |
being defined; for example, "Function" could be used if the entity is |
being defined; for example, “Function” could be used if the entity is |
436 |
a function. The <code>@deffn</code> command is written at the beginning of a |
a function. The <code>@deffn</code> command is written at the beginning of a |
437 |
line and is followed on the same line by the category of entity being |
line and is followed on the same line by the category of entity being |
438 |
described, the name of this particular entity, and its arguments, if |
described, the name of this particular entity, and its arguments, if |
446 |
@end deffn |
@end deffn |
447 |
</pre></td></tr></table> |
</pre></td></tr></table> |
448 |
|
|
449 |
<p>This shows a rather terse definition for a "command" named |
<p>This shows a rather terse definition for a “command” named |
450 |
<code>forward-char</code> with one argument, <var>nchars</var>. |
<code>forward-char</code> with one argument, <var>nchars</var>. |
451 |
</p> |
</p> |
452 |
<p><code>@deffn</code> prints argument names such as <var>nchars</var> in italics or |
<p><code>@deffn</code> prints argument names such as <var>nchars</var> in italics or |
453 |
upper case, as if <code>@var</code> had been used, because we think of these |
upper case, as if <code>@var</code> had been used, because we think of these |
454 |
names as metasyntactic variables--they stand for the actual argument |
names as metasyntactic variables—they stand for the actual argument |
455 |
values. Within the text of the description, write an argument name |
values. Within the text of the description, write an argument name |
456 |
explicitly with <code>@var</code> to refer to the value of the argument. In |
explicitly with <code>@var</code> to refer to the value of the argument. In |
457 |
the example above, we used <samp>`@var{nchars}'</samp> in this way. |
the example above, we used <samp>`@var{nchars}'</samp> in this way. |
539 |
</dd> |
</dd> |
540 |
<dt> <code>@defvr <var>category</var> <var>name</var></code></dt> |
<dt> <code>@defvr <var>category</var> <var>name</var></code></dt> |
541 |
<dd><p>The <code>@defvr</code> command is a general definition command for |
<dd><p>The <code>@defvr</code> command is a general definition command for |
542 |
something like a variable--an entity that records a value. You must |
something like a variable—an entity that records a value. You must |
543 |
choose a term to describe the category of entity being defined; for |
choose a term to describe the category of entity being defined; for |
544 |
example, "Variable" could be used if the entity is a variable. |
example, “Variable” could be used if the entity is a variable. |
545 |
Write the <code>@defvr</code> command at the beginning of a line and |
Write the <code>@defvr</code> command at the beginning of a line and |
546 |
follow it on the same line by the category of the entity and the |
follow it on the same line by the category of the entity and the |
547 |
name of the entity. |
name of the entity. |
548 |
</p> |
</p> |
549 |
<p>Capitalize the category name like a title. If the name of the category |
<p>Capitalize the category name like a title. If the name of the category |
550 |
contains spaces, as in the name "User Option", enclose it in braces. |
contains spaces, as in the name “User Option”, enclose it in braces. |
551 |
Otherwise, the second word will be mistaken for the name of the entity. |
Otherwise, the second word will be mistaken for the name of the entity. |
552 |
For example, |
For example, |
553 |
</p> |
</p> |
647 |
@end deftypefn |
@end deftypefn |
648 |
</pre></td></tr></table> |
</pre></td></tr></table> |
649 |
|
|
650 |
<p>(where the text before the "…", shown above as two lines, would |
<p>(where the text before the “…”, shown above as two lines, would |
651 |
actually be a single line in a real Texinfo file) produces the following |
actually be a single line in a real Texinfo file) produces the following |
652 |
in Info: |
in Info: |
653 |
</p> |
</p> |
654 |
<table><tr><td> </td><td><pre class="smallexample">-- Library Function: int foobar (int FOO, float BAR) |
<table><tr><td> </td><td><pre class="smallexample">-- Library Function: int foobar (int FOO, float BAR) |
655 |
… |
… |
656 |
</pre></td></tr></table> |
</pre></td></tr></table> |
657 |
<p>This means that <code>foobar</code> is a "library function" that returns an |
<p>This means that <code>foobar</code> is a “library function” that returns an |
658 |
<code>int</code>, and its arguments are <var>foo</var> (an <code>int</code>) and |
<code>int</code>, and its arguments are <var>foo</var> (an <code>int</code>) and |
659 |
<var>bar</var> (a <code>float</code>). |
<var>bar</var> (a <code>float</code>). |
660 |
</p> |
</p> |
661 |
<p>The argument names that you write in <code>@deftypefn</code> are not subject |
<p>The argument names that you write in <code>@deftypefn</code> are not subject |
662 |
to an implicit <code>@var</code>--since the actual names of the arguments in |
to an implicit <code>@var</code>—since the actual names of the arguments in |
663 |
<code>@deftypefn</code> are typically scattered among data type names and |
<code>@deftypefn</code> are typically scattered among data type names and |
664 |
keywords, Texinfo cannot find them without help. Instead, you must write |
keywords, Texinfo cannot find them without help. Instead, you must write |
665 |
<code>@var</code> explicitly around the argument names. In the example |
<code>@var</code> explicitly around the argument names. In the example |
766 |
</dd> |
</dd> |
767 |
<dt> <code>@deftypevr <var>category</var> <var>data-type</var> <var>name</var></code></dt> |
<dt> <code>@deftypevr <var>category</var> <var>data-type</var> <var>name</var></code></dt> |
768 |
<dd><p>The <code>@deftypevr</code> command is the general definition command for |
<dd><p>The <code>@deftypevr</code> command is the general definition command for |
769 |
something like a variable in a typed language--an entity that records |
something like a variable in a typed language—an entity that records |
770 |
a value. You must choose a term to describe the category of the |
a value. You must choose a term to describe the category of the |
771 |
entity being defined; for example, "Variable" could be used if the |
entity being defined; for example, “Variable” could be used if the |
772 |
entity is a variable. |
entity is a variable. |
773 |
</p> |
</p> |
774 |
<p>The <code>@deftypevr</code> command is written at the beginning of a line |
<p>The <code>@deftypevr</code> command is written at the beginning of a line |