# HG changeset patch
# User jwe
# Date 941525836 0
# Node ID 7c03933635c6fb0769a0a483df7b4f861fce7116
# Parent  13cdcb7e5066fa33576fd28aa9b9c4546ec8765a
[project @ 1999-11-02 06:57:12 by jwe]

diff --git a/doc/interpreter/audio.txi b/doc/interpreter/audio.txi
--- a/doc/interpreter/audio.txi
+++ b/doc/interpreter/audio.txi
@@ -28,39 +28,13 @@
 files holding data in mu-law encoding end in @file{au}, @file{mu}, or
 @file{snd}.
 
-@deftypefn {Function File} {} lin2mu (@var{x})
-If the vector @var{x} represents mono audio data in 8- or 16-bit
-linear encoding, @code{lin2mu (@var{x})} is the corresponding mu-law
-encoding.
-@end deftypefn
+@DOCSTRING(lin2mu)
 
-@deftypefn {Function File} {} mu2lin (@var{x}, @var{bps})
-If the vector @var{x} represents mono audio data in mu-law encoding,
-@code{mu2lin} converts it to linear encoding.  The optional argument
-@var{bps} specifies whether the input data uses 8 bit per sample
-(default) or 16 bit.
-@end deftypefn
-
-@deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps})
-Loads audio data from the file @file{@var{name}.@var{ext}} into the
-vector @var{x}.  
+@DOCSTRING(mu2lin)
 
-The extension @var{ext} determines how the data in the audio file is
-interpreted;  the extensions @file{lin} (default) and @file{raw}
-correspond to linear, the extensions @file{au}, @file{mu}, or @file{snd}
-to mu-law encoding.
+@DOCSTRING(loadaudio)
 
-The argument @var{bps} can be either 8 (default) or 16, and specifies
-the number of bits per sample used in the audio file.
-@end deftypefn
-
-@deftypefn {Function File} {} saveaudio (@var{name}, @var{x}, @var{ext}, @var{bps})
-Saves a vector @var{x} of audio data to the file
-@file{@var{name}.@var{ext}}.  The optional parameters @var{ext} and
-@var{bps} determine the encoding and the number of bits per sample used
-in the audio file (see @code{loadaudio});  defaults are @file{lin} and
-8, respectively.
-@end deftypefn
+@DOCSTRING(saveaudio)
 
 The following functions for audio I/O require special A/D hardware and
 operating system support.  It is assumed that audio data in linear
@@ -70,29 +44,9 @@
 these functions will work without modification on a wide variety of
 hardware are welcome.
 
-@deftypefn {Function File} {} playaudio (@var{name}, @var{ext})
-@deftypefnx {Function File} {} playaudio (@var{x})
-Plays the audio file @file{@var{name}.@var{ext}} or the audio data
-stored in the vector @var{x}.
-@end deftypefn
-
-@deftypefn {Function File} {} record (@var{sec}, @var{sampling_rate})
-Records @var{sec} seconds of audio input into the vector @var{x}.  The
-default value for @var{sampling_rate} is 8000 samples per second, or
-8kHz.  The program waits until the user types @key{RET} and then
-immediately starts to record.
-@end deftypefn
+@DOCSTRING(playaudio)
 
-@deftypefn {Function File} {} setaudio (@var{type})
-@deftypefnx {Function File} {} setaudio (@var{type}, @var{value})
-Set or display various properties of your mixer hardware.
-
-For example, if @code{vol} corresponds to the volume property, you can
-set it to 50 (percent) by @code{setaudio ("vol", 50)}.
+@DOCSTRING(record)
 
-This is an simple experimental program to control the audio hardware
-settings.  It assumes that there is a @code{mixer} program which can be
-used as @code{mixer @var{type} @var{value}}, and simply executes
-@code{system ("mixer @var{type} @var{value}")}.  Future releases might
-get rid of this assumption by using the @code{fcntl} interface.
-@end deftypefn
+@DOCSTRING(setaudio)
+
diff --git a/doc/interpreter/basics.txi b/doc/interpreter/basics.txi
--- a/doc/interpreter/basics.txi
+++ b/doc/interpreter/basics.txi
@@ -189,39 +189,9 @@
 about the command line, including the number of arguments and all of the
 options.
 
-@defvr {Built-in Variable} argv
-The command line arguments passed to Octave are available in this
-variable.  For example, if you invoked Octave using the command
-
-@example
-octave --no-line-editing --silent
-@end example
-
-@noindent
-@code{argv} would be a list of strings with the elements
-@code{--no-line-editing} and @code{--silent}.
-
-If you write an executable Octave script, @code{argv} will contain the
-list of arguments passed to the script.  @pxref{Executable Octave Programs}.
-@end defvr
+@DOCSTRING(argv)
 
-@defvr {Built-in Variable} program_invocation_name
-@defvrx {Built-in Variable} program_name
-When Octave starts, the value of the built-in variable
-@code{program_invocation_name} is automatically set to the name that was
-typed at the shell prompt to run Octave, and the value of
-@code{program_name} is automatically set to the final component of
-@code{program_invocation_name}.  For example, if you typed
-@samp{@value{OCTAVEHOME}/bin/octave} to start Octave,
-@code{program_invocation_name} would have the value
-@code{"@value{OCTAVEHOME}/bin/octave"}, and @code{program_name} would
-have the value @code{"octave"}.
-
-If executing a script from the command line (e.g., @code{octave foo.m})
-or using an executable Octave script, the program name is set to the
-name of the script.  @xref{Executable Octave Programs} for an example of
-how to create an executable Octave script.
-@end defvr
+@DOCSTRING(program_invocation_name)
 
 Here is an example of using these variables to reproduce Octave's
 command line.
@@ -296,29 +266,9 @@
 @cindex exiting octave
 @cindex quitting octave
 
-@deftypefn {Built-in Function} {} exit (@var{status})
-@deftypefnx {Built-in Function} {} quit (@var{status})
-Exit the current Octave session.  If the optional integer value
-@var{status} is supplied, pass that value to the operating system as the
-Octave's exit status.
-@end deftypefn
-
-@deftypefn {Built-in Function} {} atexit (@var{fcn})
-Register function to be called when Octave exits.  For example,
+@DOCSTRING(quit)
 
-@example
-@group
-function print_flops_at_exit ()
-  printf ("\n%s\n", system ("fortune"));
-  fflush (stdout);
-endfunction
-atexit ("print_flops_at_exit");
-@end group
-@end example
-
-@noindent
-will print a message when Octave exits.
-@end deftypefn
+@DOCSTRING(atexit)
 
 @node Getting Help, Command Line Editing, Quitting Octave, Getting Started
 @section Commands for Getting Help
@@ -333,50 +283,17 @@
 functions and variables.  @xref{Function Files}, for more information
 about how to document the functions you write.
 
-@deffn {Command} help
-Octave's @code{help} command can be used to print brief usage-style
-messages, or to display information directly from an on-line version of
-the printed manual, using the GNU Info browser.  If invoked without any
-arguments, @code{help} prints a list of all the available operators,
-functions, and built-in variables.  If the first argument is @code{-i},
-the @code{help} command searches the index of the on-line version of
-this manual for the given topics.
-
-For example, the command @kbd{help help} prints a short message
-describing the @code{help} command, and @kbd{help -i help} starts the
-GNU Info browser at this node in the on-line version of the manual.
-
-Once the GNU Info browser is running, help for using it is available
-using the command @kbd{C-h}.
-@end deffn
+@DOCSTRING(help)
 
 The help command can give you information about operators, but not the
 comma and semicolons that are used as command separators.  To get help
 for those, you must type @kbd{help comma} or @kbd{help semicolon}.
 
-@defvr {Built-in Variable} INFO_FILE
-The variable @code{INFO_FILE} names the location of the Octave info file.
-The default value is @code{"@var{octave-home}/info/octave.info"}, where
-@var{octave-home} is the directory where all of Octave is installed.
-@end defvr
+@DOCSTRING(INFO_FILE)
 
-@defvr {Built-in Variable} INFO_PROGRAM
-The variable @code{INFO_PROGRAM} names the info program to run.  Its
-initial value is
-@code{"@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info"},
-where @var{octave-home} is the directory where all of Octave is
-installed, @var{version} is the Octave version number, and @var{arch} is
-the machine type.  The value of @code{INFO_PROGRAM} can be overridden by
-the environment variable @code{OCTAVE_INFO_PROGRAM}, or the command line
-argument @code{--info-program NAME}, or by setting the value of the
-built-in variable @code{INFO_PROGRAM} in a startup script.
-@end defvr
+@DOCSTRING(INFO_PROGRAM)
 
-@defvr {Built-in Variable} suppress_verbose_help_message
-If the value of @code{suppress_verbose_help_message} is nonzero, Octave
-will not add additional help information to the end of the output from
-the @code{help} command and usage messages for built-in commands.
-@end defvr
+@DOCSTRING(suppress_verbose_help_message)
 
 @node Command Line Editing, Errors, Getting Help, Getting Started
 @section Command Line Editing
@@ -474,10 +391,7 @@
 
 @cindex clearing the screen
 
-@deftypefn {Built-in Function} {} clc ()
-@deftypefnx {Built-in Function} {} home ()
-Clear the terminal screen and move the cursor to the upper left corner.
-@end deftypefn
+@DOCSTRING(clc)
 
 @node Killing and Yanking, Commands For Text, Cursor Motion, Command Line Editing
 @subsection Killing and Yanking
@@ -581,20 +495,9 @@
 List the possible completions of the text before the cursor.
 @end table
 
-@defvr {Built-in Variable} completion_append_char
-The value of @code{completion_append_char} is used as the character to
-append to successful command-line completion attempts.  The default
-value is @code{" "} (a single space).
-@end defvr
+@DOCSTRING(completion_append_char)
 
-@deftypefn {Built-in Function} {} completion_matches (@var{hint})
-Generate possible completions given @var{hint}.
-
-This function is provided for the benefit of programs like Emacs which
-might be controlling Octave and handling user input.  The current
-command number is not incremented when this function is called.  This is
-a feature, not a bug.
-@end deftypefn
+@DOCSTRING(completion_matches)
 
 @node Commands For History, Customizing the Prompt, Commands For Completion, Command Line Editing
 @subsection Commands For Manipulating The History
@@ -647,71 +550,11 @@
 list, Octave provides three functions for viewing, editing, and
 re-running chunks of commands from the history list.
 
-@deffn {Command} history options
-If invoked with no arguments, @code{history} displays a list of commands
-that you have executed.  Valid options are:
-
-@table @code
-@item -w @var{file}
-Write the current history to the file @var{file}.  If the name is
-omitted, use the default history file (normally @file{~/.octave_hist}).
-
-@item -r @var{file}
-Read the file @var{file}, replacing the current history list with its
-contents.  If the name is omitted, use the default history file
-(normally @file{~/.octave_hist}).
-
-@item @var{N}
-Only display the most recent @var{N} lines of history.
-
-@item -q
-Don't number the displayed lines of history.  This is useful for cutting
-and pasting commands if you are using the X Window System.
-@end table
-
-For example, to display the five most recent commands that you have
-typed without displaying line numbers, use the command
-@kbd{history -q 5}.
-@end deffn
+@DOCSTRING(history)
 
-@deffn {Command} edit_history options
-If invoked with no arguments, @code{edit_history} allows you to edit the
-history list using the editor named by the variable @code{EDITOR}.  The
-commands to be edited are first copied to a temporary file.  When you
-exit the editor, Octave executes the commands that remain in the file.
-It is often more convenient to use @code{edit_history} to define functions 
-rather than attempting to enter them directly on the command line.
-By default, the block of commands is executed as soon as you exit the
-editor.  To avoid executing any commands, simply delete all the lines
-from the buffer before exiting the editor.
-
-The @code{edit_history} command takes two optional arguments specifying
-the history numbers of first and last commands to edit.  For example,
-the command
-
-@example
-edit_history 13
-@end example
+@DOCSTRING(edit_history)
 
-@noindent
-extracts all the commands from the 13th through the last in the history
-list.  The command
-
-@example
-edit_history 13 169
-@end example
-
-@noindent
-only extracts commands 13 through 169.  Specifying a larger number for
-the first command than the last command reverses the list of commands
-before placing them in the buffer to be edited.  If both arguments are
-omitted, the previous command in the history list is used.
-@end deffn
-
-@deffn {Command} run_history
-Similar to @code{edit_history}, except that the editor is not invoked,
-and the commands are simply executed as they appear in the history list.
-@end deffn
+@DOCSTRING(run_history)
 
 @defvr {Built-in Variable} EDITOR
 A string naming the editor to use with the @code{edit_history} command.
@@ -720,23 +563,11 @@
 @code{"emacs"}.
 @end defvr
 
-@defvr {Built-in Variable} history_file
-This variable specifies the name of the file used to store command
-history.  The default value is @code{"~/.octave_hist"}, but may be
-overridden by the environment variable @code{OCTAVE_HISTFILE}.
-@end defvr
+@DOCSTRING(history_file)
 
-@defvr {Built-in Variable} history_size
-This variable specifies how many entries to store in the history file.
-The default value is @code{1024}, but may be overridden by the
-environment variable @code{OCTAVE_HISTSIZE}.
-@end defvr
+@DOCSTRING(history_size)
 
-@defvr {Built-in Variable} saving_history
-If the value of @code{saving_history} is nonzero, command entered
-on the command line are saved in the file specified by the variable
-@code{history_file}.
-@end defvr
+@DOCSTRING(saving_history)
 
 @node Customizing the Prompt, Diary and Echo Commands, Commands For History, Command Line Editing
 @subsection Customizing the Prompt
@@ -794,39 +625,11 @@
 A backslash.
 @end table
 
-@defvr {Built-in Variable} PS1
-The primary prompt string.  When executing interactively, Octave
-displays the primary prompt @code{PS1} when it is ready to read a
-command.
-
-The default value of @code{PS1} is @code{"\s:\#> "}.  To change it, use a
-command like
-
-@example
-octave:13> PS1 = "\\u@@\\H> "
-@end example
+@DOCSTRING(PS1)
 
-@noindent
-which will result in the prompt @samp{boris@@kremvax> } for the user
-@samp{boris} logged in on the host @samp{kremvax.kgb.su}.  Note that two
-backslashes are required to enter a backslash into a string.
-@xref{Strings}.
-@end defvr
+@DOCSTRING(PS2)
 
-@defvr {Built-in Variable} PS2
-The secondary prompt string, which is printed when Octave is
-expecting additional input to complete a command.  For example, when
-defining a function over several lines, Octave will print the value of
-@code{PS1} at the beginning of each line after the first.  The default
-value of @code{PS2} is @code{"> "}.
-@end defvr
-
-@defvr {Built-in Variable} PS4
-If Octave is invoked with the @code{--echo-input} option, the value of
-@code{PS4} is printed before each line of input that is echoed.  The
-default value of @code{PS4} is @code{"+ "}.  @xref{Invoking Octave}, for
-a description of @code{--echo-input}.
-@end defvr
+@DOCSTRING(PS4)
 
 @node Diary and Echo Commands,  , Customizing the Prompt, Command Line Editing
 @subsection Diary and Echo Commands
@@ -840,75 +643,15 @@
 interactive session by recording the input you type and the output that
 Octave produces in a separate file.
 
-@deffn {Command} diary options
-Create a list of all commands @emph{and} the output they produce, mixed
-together just as you see them on your terminal.  Valid options are:
-
-@table @code
-@item on
-Start recording your session in a file called @file{diary} in your
-current working directory.
-
-@item off
-Stop recording your session in the diary file.
-
-@item @var{file}
-Record your session in the file named @var{file}.
-@end table
-
-Without any arguments, @code{diary} toggles the current diary state.
-@end deffn
+@DOCSTRING(diary)
 
 Sometimes it is useful to see the commands in a function or script as
 they are being evaluated.  This can be especially helpful for debugging
 some kinds of problems.
 
-@deffn {Command} echo options
-Control whether commands are displayed as they are executed.  Valid
-options are:
-
-@table @code
-@item on
-Enable echoing of commands as they are executed in script files.
-
-@item off
-Disable echoing of commands as they are executed in script files.
-
-@item on all
-Enable echoing of commands as they are executed in script files and
-functions.
-
-@item off all
-Disable echoing of commands as they are executed in script files and
-functions.
-@end table
+@DOCSTRING(echo)
 
-@noindent
-If invoked without any arguments, @code{echo} toggles the current echo
-state.
-@end deffn
-
-@defvr {Built-in Variable} echo_executing_commands
-This variable may also be used to control the echo state.  It may be
-the sum of the following values:
-
-@table @asis
-@item 1
-Echo commands read from script files.
-
-@item 2
-Echo commands from functions.
-
-@item 4
-Echo commands read from command line.
-@end table
-
-More than one state can be active at once.  For example, a value of 3 is
-equivalent to the command @kbd{echo on all}.
-
-The value of @code{echo_executing_commands} is set by the @kbd{echo}
-command and the command line option @code{--echo-input}.
-@end defvr
+@DOCSTRING(echo_executing_commands)
 
 @node Errors, Executable Octave Programs, Command Line Editing, Getting Started
 @section How Octave Reports Errors
diff --git a/scripts/ChangeLog b/scripts/ChangeLog
--- a/scripts/ChangeLog
+++ b/scripts/ChangeLog
@@ -1,3 +1,12 @@
+1999-11-02  Ben Sapp <bsapp@nua.lampf.lanl.gov>
+
+	* scripts/audio/lin2mu.m: Texinfoize doc string.
+	* scripts/audio/loadaudio.m: Ditto.
+	* scripts/audio/mu2lin.m: Ditto.
+	* scripts/audio/playaudio.m: Ditto.
+	* scripts/audio/record.m: Ditto.
+	* scripts/audio/saveaudio.m: Ditto.
+
 1999-10-26  Ben Sapp <bsapp@nua.lampf.lanl.gov>
 
 	* elfun/acot.m: Texinfoize doc string.
diff --git a/scripts/audio/lin2mu.m b/scripts/audio/lin2mu.m
--- a/scripts/audio/lin2mu.m
+++ b/scripts/audio/lin2mu.m
@@ -17,10 +17,14 @@
 ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 ## 02111-1307, USA.
 
-## usage:  y = lin2mu (x)
-##
-## x is a vector of an 8- or 16-bit linearly encoded audio sample,
-## This is transformed into a mu-law encoded vector.
+## -*- texinfo -*-
+## @deftypefn {Function File} {} lin2mu (@var{x})
+## If the vector @var{x} represents mono audio data in 8- or 16-bit
+## linear encoding, @code{lin2mu (@var{x})} is the corresponding mu-law
+## encoding.
+## @end deftypefn
+
+## See also: mu2lin, loadaudio, saveaudio, playaudio, setaudio, record
 
 ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at>
 ## Created: 17 October 1994
diff --git a/scripts/audio/loadaudio.m b/scripts/audio/loadaudio.m
--- a/scripts/audio/loadaudio.m
+++ b/scripts/audio/loadaudio.m
@@ -17,20 +17,21 @@
 ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 ## 02111-1307, USA.
 
-## usage:  X = loadaudio (name [, ext [, bit]])
+## -*- texinfo -*-
+## @deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps})
+## Loads audio data from the file @file{@var{name}.@var{ext}} into the
+## vector @var{x}.  
 ##
-## Loads audio data from the file "name.ext" into the data vector X.
-## Default value for the "ext" argument, which has to be written
-## without the initial ".", is "lin".
-## Currently, the following audio formats are supported:
-## *) mu-law encoding with extension "mu", "au", or "snd"
-## *) linear encoding with extension "lin", "pcm", or "raw"
-##
-## The `bit' argument can be either 8 (default) or 16.
-## Depending on the value of bit, linearly encoded files are
-## interpreted as being in 8 and 16 bit format, respectively, and
-## mu-law encoded files are transformed to 8 and 16-bit linear
-## format, respectively.
+## The extension @var{ext} determines how the data in the audio file is
+## interpreted;  the extensions @file{lin} (default) and @file{raw}
+## correspond to linear, the extensions @file{au}, @file{mu}, or @file{snd}
+## to mu-law encoding.
+## 
+## The argument @var{bps} can be either 8 (default) or 16, and specifies
+## the number of bits per sample used in the audio file.
+## @end deftypefn
+
+## See also: lin2mu, mu2lin, saveaudio, playaudio, setaudio, record
 
 ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at>
 ## Created: 10 April 1994
diff --git a/scripts/audio/mu2lin.m b/scripts/audio/mu2lin.m
--- a/scripts/audio/mu2lin.m
+++ b/scripts/audio/mu2lin.m
@@ -17,12 +17,15 @@
 ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 ## 02111-1307, USA.
 
-## usage: y = mu2lin (x [, bit])
-##
-## If x is a vector of audio data with mu-law encoding, mu2lin (x)
-## holds the same data with linear encoding.
-## The optional argument bit specifies whether the input data is
-## 8 bit (default) or 16 bit.
+## -*- texinfo -*-
+## @deftypefn {Function File} {} mu2lin (@var{x}, @var{bps})
+## If the vector @var{x} represents mono audio data in mu-law encoding,
+## @code{mu2lin} converts it to linear encoding.  The optional argument
+## @var{bps} specifies whether the input data uses 8 bit per sample
+## (default) or 16 bit.
+## @end deftypefn
+
+## See also: lin2mu, loadaudio, saveaudio, playaudio, setaudio, record
 
 ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at>
 ## Created: 18 October 1994
diff --git a/scripts/audio/playaudio.m b/scripts/audio/playaudio.m
--- a/scripts/audio/playaudio.m
+++ b/scripts/audio/playaudio.m
@@ -17,19 +17,14 @@
 ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 ## 02111-1307, USA.
 
-## usage: playaudio (name [, ext])
-##        playaudio (X)
-##
-## `playaudio ("name" [, "ext"])' plays the audio file "name.ext". The
-## default value for the "ext" argument, which has to be written
-## without the initial ".", is "lin".
-## Currently, the following audio formats are suppored:
-## *) linear encoding with extension "lin" or "raw", played using
-##    /dev/dsp
-## *) mu-law encoding with extension "mu", "au" or "snd", played
-##    using /dev/audio
-##
-## `playaudio (X)' plays the audio data contained in the vector X.
+## -*- texinfo -*-
+## @deftypefn {Function File} {} playaudio (@var{name}, @var{ext})
+## @deftypefnx {Function File} {} playaudio (@var{x})
+## Plays the audio file @file{@var{name}.@var{ext}} or the audio data
+## stored in the vector @var{x}.
+## @end deftypefn
+
+## See also: lin2mu, mu2lin, loadaudio, saveaudio, setaudio, record
 
 ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at>
 ## Created: 11 April 1994
diff --git a/scripts/audio/record.m b/scripts/audio/record.m
--- a/scripts/audio/record.m
+++ b/scripts/audio/record.m
@@ -17,6 +17,16 @@
 ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 ## 02111-1307, USA.
 
+## -*- texinfo -*-
+## @deftypefn {Function File} {} record (@var{sec}, @var{sampling_rate})
+## Records @var{sec} seconds of audio input into the vector @var{x}.  The
+## default value for @var{sampling_rate} is 8000 samples per second, or
+## 8kHz.  The program waits until the user types @key{RET} and then
+## immediately starts to record.
+## @end deftypefn
+
+## See also: lin2mu, mu2lin, loadaudio, saveaudio, playaudio, setaudio
+
 ## usage:  X = record (sec [, sampling_rate])
 ##
 ## Records sec seconds of audio into the vector X.
diff --git a/scripts/audio/saveaudio.m b/scripts/audio/saveaudio.m
--- a/scripts/audio/saveaudio.m
+++ b/scripts/audio/saveaudio.m
@@ -17,17 +17,16 @@
 ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA
 ## 02111-1307, USA.
 
-## usage:  saveaudio (name, X, [, ext [, bit]])
-##
-## Saves a vector X of audio data in the file "name.ext".
-## The format of the audio file is determined by ext which has to be
-## written without an inital ".";  default value for ext is "lin".
-##
-## Currently, the following audio formats are supported:
-## *) mu-law files with extension "mu", "au" or "snd"
-## *) linearly encoded files with extension "lin" or "raw"
-## If the data is saved linearly, the bit argument decides whether an
-## 8-bit (default) or a 16-bit format is used.
+## -*- texinfo -*- 
+## @deftypefn {Function File} {} saveaudio (@var{name}, @var{x}, @var{ext}, @var{bps})
+## Saves a vector @var{x} of audio data to the file
+## @file{@var{name}.@var{ext}}.  The optional parameters @var{ext} and
+## @var{bps} determine the encoding and the number of bits per sample used
+## in the audio file (see @code{loadaudio});  defaults are @file{lin} and
+## 8, respectively.
+## @end deftypefn
+
+## See also: lin2mu, mu2lin, loadaudio, playaudio, setaudio, record
 
 ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at>
 ## Created: 5 September 1994
diff --git a/src/ChangeLog b/src/ChangeLog
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,18 @@
+1999-11-02  Ben Sapp <bsapp@nua.lampf.lanl.gov>
+
+	* src/help.cc (Fhelp): Texinfoize doc string.
+	* src/input.cc (Fecho, Fcompletion_matches): Ditto.
+	* src/oct-hist.cc (Fedit_history, Fhistory, Frun_history): Ditto.
+	* src/pager.cc (Fdiary): Ditto.
+	* src/sysdep.cc (Fclc): Ditto.
+	* src/toplev.cc (Fquit, Fatexit): Ditto.
+	
+1999-11-02  John W. Eaton  <jwe@bevo.che.wisc.edu>
+
+	* lex.l (yywrap): No longer static.
+	(have_continuation): Declare input character as int, not char, so
+	comparison to EOF will work.
+
 1999-11-01  John W. Eaton  <jwe@bevo.che.wisc.edu>
 
 	* defun.cc (print_usage): Use display_help_text instead of sending
diff --git a/src/help.cc b/src/help.cc
--- a/src/help.cc
+++ b/src/help.cc
@@ -827,9 +827,24 @@
 }
 
 DEFUN_TEXT (help, args, ,
-  "help [-i] [topic ...]\n\
+  "-*- texinfo -*-\n\
+@deffn {Command} help\n\
+Octave's @code{help} command can be used to print brief usage-style\n\
+messages, or to display information directly from an on-line version of\n\
+the printed manual, using the GNU Info browser.  If invoked without any\n\
+arguments, @code{help} prints a list of all the available operators,\n\
+functions, and built-in variables.  If the first argument is @code{-i},\n\
+the @code{help} command searches the index of the on-line version of\n\
+this manual for the given topics.\n\
 \n\
-print cryptic yet witty messages")
+For example, the command @kbd{help help} prints a short message\n\
+describing the @code{help} command, and @kbd{help -i help} starts the\n\
+GNU Info browser at this node in the on-line version of the manual.\n\
+\n\
+Once the GNU Info browser is running, help for using it is available\n\
+using the command @kbd{C-h}.\n\
+@end deffn\n\
+")
 {
   octave_value_list retval;
 
@@ -1174,14 +1189,31 @@
 symbols_of_help (void)
 {
   DEFVAR (INFO_FILE, Vinfo_file, info_file,
-    "name of the Octave info file");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} INFO_FILE\n\
+The variable @code{INFO_FILE} names the location of the Octave info file.\n\
+The default value is @code{\"@var{octave-home}/info/octave.info\"}, where\n\
+@var{octave-home} is the directory where all of Octave is installed.\n\
+@end defvr\n\
+");
 
   DEFVAR (INFO_PROGRAM, Vinfo_prog, info_prog,
-    "name of the Octave info reader");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} INFO_FILE\n\
+The variable @code{INFO_FILE} names the location of the Octave info file.\n\
+The default value is @code{\"@var{octave-home}/info/octave.info\"}, where\n\
+@var{octave-home} is the directory where all of Octave is installed.\n\
+@end defvr\n\
+");
 
   DEFVAR (suppress_verbose_help_message, 0.0, suppress_verbose_help_message,
-    "suppress printing of message pointing to additional help in the\n\
-help and usage functions");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} suppress_verbose_help_message\n\
+If the value of @code{suppress_verbose_help_message} is nonzero, Octave\n\
+will not add additional help information to the end of the output from\n\
+the @code{help} command and usage messages for built-in commands.\n\
+@end defvr\n\
+");
 }
 
 /*
diff --git a/src/input.cc b/src/input.cc
--- a/src/input.cc
+++ b/src/input.cc
@@ -647,15 +647,32 @@
 }
 
 DEFUN_TEXT(echo, args, ,
-  "echo [options]\n\
+  "-*- texinfo -*-\n\
+@deffn {Command} echo options\n\
+Control whether commands are displayed as they are executed.  Valid\n\
+options are:\n\
 \n\
-  echo [on|off]         -- enable or disable echoing of commands as\n\
-                           they are executed in script files\n\
+@table @code\n\
+@item on\n\
+Enable echoing of commands as they are executed in script files.\n\
+\n\
+@item off\n\
+Disable echoing of commands as they are executed in script files.\n\
 \n\
-  echo [on all|off all] -- enable or disable echoing of commands as they\n\
-                           are executed in script files and functions\n\
+@item on all\n\
+Enable echoing of commands as they are executed in script files and\n\
+functions.\n\
 \n\
-Without any arguments, toggle the current echo state.")
+@item off all\n\
+Disable echoing of commands as they are executed in script files and\n\
+functions.\n\
+@end table\n\
+\n\
+@noindent\n\
+If invoked without any arguments, @code{echo} toggles the current echo\n\
+state.\n\
+@end deffn\n\
+")
 {
   octave_value_list retval;
 
@@ -722,12 +739,16 @@
 }
 
 DEFUN (completion_matches, args, nargout,
-  "completion_matches (HINT): generate possible completions given HINT\n\
+  "-*- texinfo -*-\n\
+@deftypefn {Built-in Function} {} completion_matches (@var{hint})\n\
+Generate possible completions given @var{hint}.\n\
 \n\
 This function is provided for the benefit of programs like Emacs which\n\
-might be controlling Octave and handling user input.  The current command\n\
-number is not incremented when this function is called.  This is a feature,\n\
-not a bug.")
+might be controlling Octave and handling user input.  The current\n\
+command number is not incremented when this function is called.  This is\n\
+a feature, not a bug.\n\
+@end deftypefn\n\
+")
 {
   octave_value retval;
 
@@ -884,20 +905,82 @@
 symbols_of_input (void)
 {
   DEFVAR (PS1, "\\s:\\#> ", ps1,
-    "primary prompt string");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} PS1\n\
+The primary prompt string.  When executing interactively, Octave\n\
+displays the primary prompt @code{PS1} when it is ready to read a\n\
+command.\n\
+\n\
+The default value of @code{PS1} is @code{\"\\s:\\#> \"}.  To change it, use a\n\
+command like\n\
+\n\
+@example\n\
+octave:13> PS1 = \"\\\\u@@\\\\H> \"\n\
+@end example\n\
+\n\
+@noindent\n\
+which will result in the prompt @samp{boris@@kremvax> } for the user\n\
+@samp{boris} logged in on the host @samp{kremvax.kgb.su}.  Note that two\n\
+backslashes are required to enter a backslash into a string.\n\
+@xref{Strings}.\n\
+@end defvr\n\
+");
 
   DEFVAR (PS2, "> ", ps2,
-    "secondary prompt string");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} PS2\n\
+The secondary prompt string, which is printed when Octave is\n\
+expecting additional input to complete a command.  For example, when\n\
+defining a function over several lines, Octave will print the value of\n\
+@code{PS1} at the beginning of each line after the first.  The default\n\
+value of @code{PS2} is @code{\"> \"}.\n\
+@end defvr\n\
+");
 
   DEFVAR (PS4, "+ ", ps4,
-    "string printed before echoed input (enabled by --echo-input)");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} PS4\n\
+If Octave is invoked with the @code{--echo-input} option, the value of\n\
+@code{PS4} is printed before each line of input that is echoed.  The\n\
+default value of @code{PS4} is @code{"+ "}.  @xref{Invoking Octave}, for\n\
+a description of @code{--echo-input}.\n\
+@end defvr\n\
+");
 
   DEFVAR (completion_append_char, " ", completion_append_char,
-    "the string to append after successful command-line completion attempts");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} completion_append_char\n\
+The value of @code{completion_append_char} is used as the character to\n\
+append to successful command-line completion attempts.  The default\n\
+value is @code{\" \"} (a single space).\n\
+@end defvr\n\
+");
 
   DEFVAR (echo_executing_commands, static_cast<double> (ECHO_OFF),
 	  echo_executing_commands,
-    "echo commands as they are executed");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} echo_executing_commands\n\
+This variable may also be used to control the echo state.  It may be\n\
+the sum of the following values:\n\
+\n\
+@table @asis\n\
+@item 1\n\
+Echo commands read from script files.\n\
+\n\
+@item 2\n\
+Echo commands from functions.\n\
+\n\
+@item 4\n\
+Echo commands read from command line.\n\
+@end table\n\
+\n\
+More than one state can be active at once.  For example, a value of 3 is\n\
+equivalent to the command @kbd{echo on all}.\n\
+\n\
+The value of @code{echo_executing_commands} is set by the @kbd{echo}\n\
+command and the command line option @code{--echo-input}.\n\
+@end defvr\n\
+");
 }
 
 /*
diff --git a/src/lex.l b/src/lex.l
--- a/src/lex.l
+++ b/src/lex.l
@@ -741,7 +741,7 @@
 #ifdef yywrap
 #undef yywrap
 #endif
-static int
+int
 yywrap (void)
 {
   return 1;
@@ -1532,7 +1532,7 @@
   ostrstream buf;
 
   bool in_comment = false;
-  char c;
+  int c;
   while ((c = yyinput ()) != EOF)
     {
       buf << (char) c;
diff --git a/src/oct-hist.cc b/src/oct-hist.cc
--- a/src/oct-hist.cc
+++ b/src/oct-hist.cc
@@ -534,9 +534,41 @@
 }
 
 DEFUN_TEXT (edit_history, args, ,
-  "edit_history [first] [last]\n\
+  "-*- texinfo -*-\n\
+@deffn {Command} edit_history options\n\
+If invoked with no arguments, @code{edit_history} allows you to edit the\n\
+history list using the editor named by the variable @code{EDITOR}.  The\n\
+commands to be edited are first copied to a temporary file.  When you\n\
+exit the editor, Octave executes the commands that remain in the file.\n\
+It is often more convenient to use @code{edit_history} to define functions \n\
+rather than attempting to enter them directly on the command line.\n\
+By default, the block of commands is executed as soon as you exit the\n\
+editor.  To avoid executing any commands, simply delete all the lines\n\
+from the buffer before exiting the editor.\n\
+\n\
+The @code{edit_history} command takes two optional arguments specifying\n\
+the history numbers of first and last commands to edit.  For example,\n\
+the command\n\
 \n\
-edit commands from the history list")
+@example\n\
+edit_history 13\n\
+@end example\n\
+\n\
+@noindent\n\
+extracts all the commands from the 13th through the last in the history\n\
+list.  The command\n\
+\n\
+@example\n\
+edit_history 13 169\n\
+@end example\n\
+\n\
+@noindent\n\
+only extracts commands 13 through 169.  Specifying a larger number for\n\
+the first command than the last command reverses the list of commands\n\
+before placing them in the buffer to be edited.  If both arguments are\n\
+omitted, the previous command in the history list is used.\n\
+@end deffn\n\
+")
 {
   octave_value_list retval;
 
@@ -553,9 +585,34 @@
 }
 
 DEFUN_TEXT (history, args, ,
-  "history [N] [-w file] [-r file] [-q]\n\
+  "-*- texinfo -*-\n\
+@deffn {Command} history options\n\
+If invoked with no arguments, @code{history} displays a list of commands\n\
+that you have executed.  Valid options are:\n\
+\n\
+@table @code\n\
+@item -w @var{file}\n\
+Write the current history to the file @var{file}.  If the name is\n\
+omitted, use the default history file (normally @file{~/.octave_hist}).\n\
 \n\
-display, save, or load command history")
+@item -r @var{file}\n\
+Read the file @var{file}, replacing the current history list with its\n\
+contents.  If the name is omitted, use the default history file\n\
+(normally @file{~/.octave_hist}).\n\
+\n\
+@item @var{N}\n\
+Only display the most recent @var{N} lines of history.\n\
+\n\
+@item -q\n\
+Don't number the displayed lines of history.  This is useful for cutting\n\
+and pasting commands if you are using the X Window System.\n\
+@end table\n\
+\n\
+For example, to display the five most recent commands that you have\n\
+typed without displaying line numbers, use the command\n\
+@kbd{history -q 5}.\n\
+@end deffn\n\
+")
 {
   octave_value_list retval;
 
@@ -572,9 +629,12 @@
 }
 
 DEFUN_TEXT (run_history, args, ,
-  "run_history [first] [last]\n\
-\n\
-run commands from the history list")
+  "-*- texinfo -*-\n\
+@deffn {Command} run_history [first] [last]\n\
+Similar to @code{edit_history}, except that the editor is not invoked,\n\
+and the commands are simply executed as they appear in the history list.\n\
+@end deffn\n\
+")
 {
   octave_value_list retval;
 
@@ -644,15 +704,33 @@
 symbols_of_oct_hist (void)
 {
   DEFVAR (history_file, default_history_file (), history_file,
-    "name of command history file");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} history_file\n\
+This variable specifies the name of the file used to store command\n\
+history.  The default value is @code{\"~/.octave_hist\"}, but may be\n\
+overridden by the environment variable @code{OCTAVE_HISTFILE}.\n\
+@end defvr\n\
+");
 
   double tmp_hist_size = default_history_size ();
 
   DEFVAR (history_size, tmp_hist_size, history_size,
-    "number of commands to save in the history list");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} history_size\n\
+This variable specifies how many entries to store in the history file.\n\
+The default value is @code{1024}, but may be overridden by the\n\
+environment variable @code{OCTAVE_HISTSIZE}.\n\
+@end defvr\n\
+");
 
   DEFVAR (saving_history, 1.0, saving_history,
-    "save command history");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} saving_history\n\
+If the value of @code{saving_history} is nonzero, command entered\n\
+on the command line are saved in the file specified by the variable\n\
+@code{history_file}.\n\
+@end defvr\n\
+");
 }
 
 /*
diff --git a/src/pager.cc b/src/pager.cc
--- a/src/pager.cc
+++ b/src/pager.cc
@@ -358,10 +358,26 @@
 }
 
 DEFUN_TEXT (diary, args, ,
-  "diary [on|off]\n\
-diary [file]\n\
+  "-*- texinfo -*-\n\
+@deffn {Command} diary options\n\
+Create a list of all commands @emph{and} the output they produce, mixed\n\
+together just as you see them on your terminal.  Valid options are:\n\
+\n\
+@table @code\n\
+@item on\n\
+Start recording your session in a file called @file{diary} in your\n\
+current working directory.\n\
 \n\
-redirect all input and screen output to a file.")
+@item off\n\
+Stop recording your session in the diary file.\n\
+\n\
+@item @var{file}\n\
+Record your session in the file named @var{file}.\n\
+@end table\n\
+\n\
+Without any arguments, @code{diary} toggles the current diary state.\n\
+@end deffn\n\
+")
 {
   octave_value_list retval;
 
diff --git a/src/sysdep.cc b/src/sysdep.cc
--- a/src/sysdep.cc
+++ b/src/sysdep.cc
@@ -120,7 +120,7 @@
 {
   malloc_error (malloc_handler);
 }
-#endif
+endif
 
 #if defined (__EMX__)
 OS2_init (void)
@@ -320,7 +320,12 @@
 }
 
 DEFUN (clc, , ,
-  "clc (): clear screen")
+  "-*- texinfo -*-\n\
+@deftypefn {Built-in Function} {} clc ()\n\
+@deftypefnx {Built-in Function} {} home ()\n\
+Clear the terminal screen and move the cursor to the upper left corner.\n\
+@end deftypefn\n\
+")
 {
   command_editor::clear_screen ();
 
diff --git a/src/toplev.cc b/src/toplev.cc
--- a/src/toplev.cc
+++ b/src/toplev.cc
@@ -236,9 +236,14 @@
 }
 
 DEFUN (quit, args, nargout,
-  "quit (STATUS): exit Octave gracefully, returning STATUS to the system.\n\
-\n\
-STATUS should be an integer value.  If STATUS is missing, 0 is assumed.")
+  "-*- texinfo -*-\n\
+@deftypefn {Built-in Function} {} exit (@var{status})\n\
+@deftypefnx {Built-in Function} {} quit (@var{status})\n\
+Exit the current Octave session.  If the optional integer value\n\
+@var{status} is supplied, pass that value to the operating system as the\n\
+Octave's exit status.\n\
+@end deftypefn\n\
+")
 {
   octave_value_list retval;
 
@@ -532,10 +537,24 @@
 }
 
 DEFUN (atexit, args, ,
-  "atexit (NAME): register NAME as a function to call when Octave exits\n\
+  "-*- texinfo -*-\n\
+@deftypefn {Built-in Function} {} atexit (@var{fcn})\n\
+Register a function to be called when Octave exits.  For example,\n\
 \n\
-Functions are called with no arguments in the reverse of the order in\n\
-which they were registered with atexit()")
+@example\n\
+@group\n\
+function print_flops_at_exit ()\n\
+  printf (\"\\n%s\\n\", system (\"fortune\"));\n\
+  fflush (stdout);\n\
+endfunction\n\
+atexit (\"print_flops_at_exit\");\n\
+@end group\n\
+@end example\n\
+\n\
+@noindent\n\
+will print a message when Octave exits.\n\
+@end deftypefn\n\
+")
 {
   octave_value_list retval;
 
@@ -689,15 +708,66 @@
 symbols_of_toplev (void)
 {
   DEFCONST (argv, ,
-    "the command line arguments this program was invoked with");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} argv\n\
+The command line arguments passed to Octave are available in this\n\
+variable.  For example, if you invoked Octave using the command\n\
+\n\
+@example\n\
+octave --no-line-editing --silent\n\
+@end example\n\
+\n\
+@noindent\n\
+@code{argv} would be a list of strings with the elements\n\
+@code{--no-line-editing} and @code{--silent}.\n\
+\n\
+If you write an executable Octave script, @code{argv} will contain the\n\
+list of arguments passed to the script.  @pxref{Executable Octave Programs}.\n\
+@end defvr\n\
+");
 
   DEFCONST (program_invocation_name,
 	    octave_env::get_program_invocation_name (),
-    "the full name of the current program or script, including the\n\
-directory specification");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} program_invocation_name\n\
+@defvrx {Built-in Variable} program_name\n\
+When Octave starts, the value of the built-in variable\n\
+@code{program_invocation_name} is automatically set to the name that was\n\
+typed at the shell prompt to run Octave, and the value of\n\
+@code{program_name} is automatically set to the final component of\n\
+@code{program_invocation_name}.  For example, if you typed\n\
+@samp{@value{OCTAVEHOME}/bin/octave} to start Octave,\n\
+@code{program_invocation_name} would have the value\n\
+@code{\"@value{OCTAVEHOME}/bin/octave\"}, and @code{program_name} would\n\
+have the value @code{\"octave\"}.\n\
+\n\
+If executing a script from the command line (e.g., @code{octave foo.m})\n\
+or using an executable Octave script, the program name is set to the\n\
+name of the script.  @xref{Executable Octave Programs} for an example of\n\
+how to create an executable Octave script.\n\
+@end defvr\n\
+");
 
   DEFCONST (program_name, octave_env::get_program_name (),
-    "the name of the current program or script");
+    "-*- texinfo -*-\n\
+@defvr {Built-in Variable} program_invocation_name\n\
+@defvrx {Built-in Variable} program_name\n\
+When Octave starts, the value of the built-in variable\n\
+@code{program_invocation_name} is automatically set to the name that was\n\
+typed at the shell prompt to run Octave, and the value of\n\
+@code{program_name} is automatically set to the final component of\n\
+@code{program_invocation_name}.  For example, if you typed\n\
+@samp{@value{OCTAVEHOME}/bin/octave} to start Octave,\n\
+@code{program_invocation_name} would have the value\n\
+@code{\"@value{OCTAVEHOME}/bin/octave\"}, and @code{program_name} would\n\
+have the value @code{\"octave\"}.\n\
+\n\
+If executing a script from the command line (e.g., @code{octave foo.m})\n\
+or using an executable Octave script, the program name is set to the\n\
+name of the script.  @xref{Executable Octave Programs} for an example of\n\
+how to create an executable Octave script.\n\
+@end defvr\n\
+");
 }
 
 /*