texinfo/doc texinfo.txi,1.28,1.29

[karl]

Update of /cvsroot/texinfo/texinfo/doc
In directory sheep:/tmp/cvs-serv30059

Modified Files:
        texinfo.txi 
Log Message:
(Definition Commands): describe the argument/@var
situation more accurately.


Index: texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.28
retrieving revision 1.29
diff -C2 -d -r1.28 -r1.29
*** texinfo.txi 18 Feb 2004 22:50:27 -0000      1.28
--- texinfo.txi 19 Feb 2004 00:04:10 -0000      1.29
***************
*** 11227,11231 ****
  @code{@@deffn} enters the name into the index of functions,
  @code{@@defvr} enters it into the index of variables, and so
! on.  @xref{Predefined Indices}.
  
  A manual need not and should not contain more than one definition for
--- 11227,11231 ----
  @code{@@deffn} enters the name into the index of functions,
  @code{@@defvr} enters it into the index of variables, and so
! on (@pxref{Predefined Indices}).
  
  A manual need not and should not contain more than one definition for
***************
*** 11489,11493 ****
  @code{@@defvrx}, @code{@@deftypefunx}, etc.
  
! The `x' forms work just like @code{@@itemx}; see @ref{itemx, , 
@code{@@itemx}}.
  
  
--- 11489,11493 ----
  @code{@@defvrx}, @code{@@deftypefunx}, etc.
  
! The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}).
  
  
***************
*** 11550,11559 ****
  @code{forward-char} with one argument, @var{nchars}.
  
! @code{@@deffn} prints argument names such as @var{nchars} in italics or
! upper case, as if @code{@@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 @code{@@var} to refer to the value of the argument.  In
! the example above, we used @samp{@@address@hidden@}} in this way.
  
  The template for @code{@@deffn} is:
--- 11550,11566 ----
  @code{forward-char} with one argument, @var{nchars}.
  
! @code{@@deffn} and prints argument names such as @var{nchars} in slanted
! type in the printed output, because we think of these names as
! metasyntactic variables---they stand for the actual argument values.
! Within the text of the description, however, write an argument name
! explicitly with @code{@@var} to refer to the value of the argument.
! In the example above, we used @samp{@@address@hidden@}} in this way.
! 
! In the unusual case when an argument name contains @samp{--}, or
! another character sequence which is treated specially
! (@pxref{Conventions}), use @code{@@var} around the argument.  This
! causes the name to be printed in slanted typewriter, instead of the
! regular slanted font, exactly as input.
! @c except for ?` and !`, but we won't explain that.
  
  The template for @code{@@deffn} is:
***************
*** 11567,11599 ****
  @end example
  
- @code{@@deffn} creates an entry in the index of functions.
- 
  @findex defun
  @item @@defun @var{name} @address@hidden
  The @code{@@defun} command is the definition command for functions.
! @code{@@defun} is equivalent to @samp{@@deffn Function
! @address@hidden
! 
! @need 800
! @noindent
! For example,
! 
! @example
! @group
! @@defun set symbol new-value
! Change the value of the symbol @@address@hidden@}
! to @@address@hidden@}.
! @@end defun
! @end group
! @end example
! 
! @noindent
! shows a rather terse definition for a function @code{set} whose
! arguments are @var{symbol} and @var{new-value}.  The argument names on
! the @code{@@defun} line automatically appear in italics or upper case as
! if they were enclosed in @code{@@var}.  Terminate the definition with
! @code{@@end defun} on a line of its address@hidden
! 
! The template is:
  
  @example
--- 11574,11583 ----
  @end example
  
  @findex defun
  @item @@defun @var{name} @address@hidden
  The @code{@@defun} command is the definition command for functions.
! @code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}.
! Terminate the definition with @code{@@end defun} on a line of its own.
! Thus, the template is:
  
  @example
***************
*** 11620,11625 ****
  @end table
  
! @code{@@defun}, @code{@@defmac}, and @code{@@defspec} create entries
! in the index of functions.
  
  
--- 11604,11608 ----
  @end table
  
! All these commands create entries in the index of functions.
  
  
***************
*** 11770,11779 ****
  @var{bar} (a @code{float})address@hidden
  
! The argument names that you write in @code{@@deftypefn} are not subject
! to an implicit @code{@@var}---since the actual names of the arguments in
! @code{@@deftypefn} are typically scattered among data type names and
! keywords, Texinfo cannot find them without help.  Instead, you must write
! @code{@@var} explicitly around the argument names.  In the example
! above, the argument names are @samp{foo} and @address@hidden
  
  The template for @code{@@deftypefn} is:@refill
--- 11753,11765 ----
  @var{bar} (a @code{float})address@hidden
  
! Since in typed languages, the actual names of the arguments are
! typically scattered among data type names and keywords, Texinfo cannot
! find them without help.  You can either (a)@tie{}write everything
! as straight text, and it will be printed in slanted type; (b)@tie{}use
! @code{@@var} for the variable names, which will uppercase the
! variable names in Info and use the slanted typewriter font in printed
! output; (c)@tie{}use @code{@@var} for the variable names and
! @code{@@code} for the type names and keywords, which will be dutifully
! obeyed.
  
  The template for @code{@@deftypefn} is:@refill
***************
*** 11794,11802 ****
  such as Ada, you might consider using @code{@@deftypefn} in a manner
  somewhat contrary to the convention described in the preceding
! address@hidden
! 
! @need 800
! @noindent
! For example:
  
  @example
--- 11780,11784 ----
  such as Ada, you might consider using @code{@@deftypefn} in a manner
  somewhat contrary to the convention described in the preceding
! paragraphs.  For example:
  
  @example
***************
*** 11827,11868 ****
  The @code{@@deftypefun} command is the specialized definition command
  for functions in typed languages.  The command is equivalent to
! @samp{@@deftypefn Function @address@hidden
! 
! @need 800
! @noindent
! Thus,
! 
! @smallexample
! @group
! @@deftypefun int foobar (int @@address@hidden@}, float @@address@hidden@})
! @dots{}
! @@end deftypefun
! @end group
! @end smallexample
! 
! @noindent
! produces the following in Info:
! 
! @example
! @group
! -- Function: int foobar (int FOO, float BAR)
! @dots{}
! @end group
! @end example
! @iftex
! 
! @need 800
! @noindent
! and the following in a printed manual:
! 
! @quotation
! @deftypefun int foobar (int @var{foo}, float @var{bar})
! @dots{}
! @end deftypefun
! @end quotation
! @end iftex
! 
! @need 800
! The template is:
  
  @example
--- 11809,11813 ----
  The @code{@@deftypefun} command is the specialized definition command
  for functions in typed languages.  The command is equivalent to
! @samp{@@deftypefn Function @dots{}}.  The template is:
  
  @example
***************
*** 11875,11879 ****
  
  @code{@@deftypefun} creates an entry in the index of functions for
! @address@hidden
  
  @end table
--- 11820,11824 ----
  
  @code{@@deftypefun} creates an entry in the index of functions for
! @var{name}.
  
  @end table
***************
*** 11945,11994 ****
  @end example
  
- @code{@@deftypevr} creates an entry in the index of variables for
- @address@hidden
- 
  @findex deftypevar
  @item @@deftypevar @var{data-type} @var{name}
  The @code{@@deftypevar} command is the specialized definition command
  for variables in typed languages.  @code{@@deftypevar} is equivalent
! to @samp{@@deftypevr Variable @address@hidden
! 
! @need 800
! @noindent
! For example:
! 
! @example
! @group
! @@deftypevar int fubar
! @dots{}
! @@end deftypevar
! @end group
! @end example
! 
! @noindent
! produces the following in Info:
! 
! @example
! @group
! -- Variable: int fubar
! @dots{}
! @end group
! @end example
! @iftex
! 
! @need 800
! @noindent
! and the following in a printed manual:
! 
! @quotation
! @deftypevar int fubar
! @dots{}
! @end deftypevar
! @end quotation
! @end iftex
! 
! @need 800
! @noindent
! The template is:
  
  @example
--- 11890,11898 ----
  @end example
  
  @findex deftypevar
  @item @@deftypevar @var{data-type} @var{name}
  The @code{@@deftypevar} command is the specialized definition command
  for variables in typed languages.  @code{@@deftypevar} is equivalent
! to @samp{@@deftypevr Variable @dots{}}.  The template is:
  
  @example
***************
*** 11999,12007 ****
  @end group
  @end example
- 
- @code{@@deftypevar} creates an entry in the index of variables for
- @address@hidden
  @end table
  
  
  @node Data Types
--- 11903,11909 ----
  @end group
  @end example
  @end table
  
+ These commands create entries in the index of variables.
  
  @node Data Types
***************
*** 12299,12302 ****
--- 12201,12205 ----
  contains the name of a type, such as @var{integer}, take care that the
  argument actually is of that address@hidden
+ 
  
  @node Sample Function Definition