Mercurial > hg > octave-lyh
changeset 3332:7c03933635c6
[project @ 1999-11-02 06:57:12 by jwe]
author | jwe |
---|---|
date | Tue, 02 Nov 1999 06:57:16 +0000 |
parents | 13cdcb7e5066 |
children | 15cddaacbc2d |
files | doc/interpreter/audio.txi doc/interpreter/basics.txi scripts/ChangeLog scripts/audio/lin2mu.m scripts/audio/loadaudio.m scripts/audio/mu2lin.m scripts/audio/playaudio.m scripts/audio/record.m scripts/audio/saveaudio.m src/ChangeLog src/help.cc src/input.cc src/lex.l src/oct-hist.cc src/pager.cc src/sysdep.cc src/toplev.cc |
diffstat | 17 files changed, 446 insertions(+), 429 deletions(-) [+] |
line wrap: on
line diff
--- 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) +
--- 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
--- 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.
--- 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
--- 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
--- 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
--- 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
--- 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.
--- 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
--- 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
--- 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\ +"); } /*
--- 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\ +"); } /*
--- 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;
--- 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\ +"); } /*
--- 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;
--- 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 ();
--- 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\ +"); } /*