texinfo/doc texinfo.txi,1.14,1.15

[karl]

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

Modified Files:
        texinfo.txi 
Log Message:
document defun continuations

Index: texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** texinfo.txi 2003/12/24 14:08:23     1.14
--- texinfo.txi 2003/12/26 00:44:38     1.15
***************
*** 495,505 ****
  Definition Commands
  
! * 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::
  
  The Definition Commands
--- 495,505 ----
  Definition Commands
  
! * Def Cmd Template::            Writing descriptions using definition 
commands.
! * Def Cmd Continuation Lines::  Continuing the heading over source lines.
! * Optional Arguments::          Handling optional and repeated arguments.
! * deffnx::                      Group two or more `first' lines.
! * Def Cmds in Detail::          Reference for all the definition commands.
  * Def Cmd Conventions::         Conventions for writing definitions.
! * Sample Function Definition::  An example.
  
  The Definition Commands
***************
*** 11025,11037 ****
  
  @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::
  @end menu
  
  @node Def Cmd Template
  @section The Template for a Definition
--- 11025,11038 ----
  
  @menu
! * Def Cmd Template::            Writing descriptions using definition 
commands.
! * Def Cmd Continuation Lines::  Continuing the heading over source lines.
! * Optional Arguments::          Handling optional and repeated arguments.
! * deffnx::                      Group two or more `first' lines.
! * Def Cmds in Detail::          Reference for all the definition commands.
  * Def Cmd Conventions::         Conventions for writing definitions.
! * Sample Function Definition::  An example.
  @end menu
  
+ 
  @node Def Cmd Template
  @section The Template for a Definition
***************
*** 11088,11092 ****
  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:@refill
  
  @example
--- 11089,11093 ----
  Capitalize the category name like a title.  If the name of the
  category contains spaces, as in the phrase `Interactive Command',
! enclose it in braces.  For example:
  
  @example
***************
*** 11116,11120 ****
  particular kinds of variables.
  
- @noindent
  @xref{Sample Function Definition}, for a detailed example of a
  function definition, including the use of @code{@@example} inside the
--- 11117,11120 ----
***************
*** 11126,11129 ****
--- 11126,11188 ----
  
  
+ @node Def Cmd Continuation Lines
+ @section Definition Command Continuation Lines
+ @cindex Continuation lines in definition commands
+ @cindex Definition command headings, continuing
+ @cindex @samp{@@} as continuation in definition commands
+ 
+ The heading line of a definition command can get very long.
+ Therefore, Texinfo has a special syntax allowing them to be continued
+ over multiple lines of the source file: a lone @samp{@@} at the end of
+ each line to be continued.  Here's an example:
+ 
+ @example
+ @@defun fn-name @@
+   arg1 arg2 arg3
+ This is the basic continued defun.
+ @@end defun
+ @end example
+ 
+ @noindent produces:
+ 
+ @defun fn-name @
+   arg1 arg2 arg3
+ This is the basic continued defun.
+ @end defun
+ 
+ @noindent 
+ As you can see, the continued lines are combined, as if they had been
+ typed on one source line.
+ 
+ Although this example only shows a one-line continuation,
+ continuations may extend over any number of lines; simply put an
+ @code{@@} at the end of each line to be continued.
+ 
+ The @code{@@} character does not have to be the last character on the
+ physical line: whitespace is allowed (and ignored) afterwards.
+ 
+ @cindex Whitespace, collapsed around continuations
+ @cindex Collapsing whitespace around continuations
+ In general, any number of spaces or tabs around the @code{@@}
+ continuation character, both on the line with the @code{@@} and on the
+ continued line, are collapsed into a single space.  There is one
+ exception: the Texinfo processors will not fully collapse whitespace
+ around a continuation inside braces.  For example:
+ 
+ @example
+ @@deffn @{Category @@
+   address@hidden @dots{}
+ @end example
+ 
+ @noindent The output (not shown) has excess space between `Category'
+ and `Name'.  In this case, simply elide any unwanted whitespace in
+ your input, or put the continuation @code{@@} outside braces.
+ 
+ @code{@@} does not (currently) function as a continuation character in
+ @emph{any} other context.  Ordinarily, @samp{@@} followed by a
+ whitespace character (space, tab, newline) produces a normal interword
+ space (@pxref{Multiple Spaces}).
+ 
+ 
  @node Optional Arguments
  @section Optional and Repeated Arguments
***************
*** 11184,11187 ****
--- 11243,11247 ----
  @address@hidden
  
+ 
  @node deffnx
  @section Two or More `First' Lines
***************
*** 11222,11225 ****
--- 11282,11286 ----
  The `x' forms work just like @code{@@itemx}; see @ref{itemx, , 
@code{@@itemx}}.
  
+ 
  @node Def Cmds in Detail
  @section The Definition Commands
***************
*** 13249,13253 ****
  the printed version of a manual, try expanding the macros with
  @command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E}
! option (@ref{Format with texi2dvi}).
  
  @itemize @bullet
--- 13310,13314 ----
  the printed version of a manual, try expanding the macros with
  @command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E}
! option (@pxref{Format with texi2dvi}).
  
  @itemize @bullet
***************
*** 14743,14746 ****
--- 14804,14808 ----
  @end table
  
+ @vindex TEXINFO_OUTPUT
  @command{makeinfo} also reads the environment variable
  @env{TEXINFO_OUTPUT} to determine the output format, if not overridden