Accessing Octave Help and Documentation Pages

Usage

o_help(NAME, character.only = FALSE, show = interactive(), format = c("plain", "rd", 
  "txt", "latex", "HTML"))

o_doc(FUNCTION_NAME)

Arguments

NAME

Octave symbol (e.g. command, function, operator) passed to Octave function help to retrieve the related documentation.

character.only

a logical indicating whether NAME can be assumed to be a character string (TRUE) or should be substituted with substitute before using them (default).

show

logical that specifies if the help page should be shown using the as R documentation file (default), e.g. using a pager, or only returned as a single string. Note that when show=TRUE, the string is still returned but invisibly.

format

a specification of the output format. If TRUE or 'rd', the result is Rd code that wraps the Octave documentation string and is suitable for inclusion into Rd files. If one of the strings 'txt', 'latex' or 'HTML', then the result is formated using the corresponding Rd conversion function from the tools package Rd2txt, Rd2latex or Rd2HTML.

FUNCTION_NAME

the name of the function from which to show the documentation. See the relevant Octave Documentation section below.

 -- Command: help NAME
 -- Command: help '--list'
     Display the help text for NAME.  For example, the command 'help
     help' prints a short message describing the 'help' command.

     Given the single argument '--list', list all operators, keywords,
     built-in functions, and loadable functions available in the current
     session of Octave.

     If invoked without any arguments, 'help' display instructions on
     how to access help from the command line.

     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 'help comma' or 'help semicolon'.

     See also: doc, lookfor, which

 -- Command: doc FUNCTION_NAME
     Display documentation for the function FUNCTION_NAME directly from
     an online version of the printed manual, using the GNU Info
     browser.  If invoked without any arguments, the manual is shown
     from the beginning.

     For example, the command 'doc rand' starts the GNU Info browser at
     the 'rand' node in the online version of the manual.

     Once the GNU Info browser is running, help for using it is
     available using the command 'C-h'.

     See also: help

Examples

## Don't show: 
# roxygen generated flag
options(R_CHECK_RUNNING_EXAMPLES_=TRUE)
## End Don't show

#----------
# o_help
#----------
## Don't show: 
    if( interactive() ){
        o_help <- function(..., show=FALSE){
            RcppOctave::o_help(..., show=show)
        }
    }
## End Don't show

o_help(print)

## [1] " -- Function File: print ()\n -- Function File: print (OPTIONS)\n -- Function File: print (FILENAME, OPTIONS)\n -- Function File: print (H, FILENAME, OPTIONS)\n     Print a graph, or save it to a file\n\n     FILENAME defines the file name of the output file.  If the file\n     name has no suffix, one is inferred from the specified device and\n     appended to the file name.  If no filename is specified, the output\n     is sent to the printer.\n\n     H specifies the figure handle.  If no handle is specified the\n     handle for the current figure is used.\n\n     OPTIONS:\n\n     '-fH'\n          Specify the handle, H, of the figure to be printed.  The\n          default is the current figure.\n\n     '-PPRINTER'\n          Set the PRINTER name to which the graph is sent if no FILENAME\n          is specified.\n\n     '-GGHOSTSCRIPT_COMMAND'\n          Specify the command for calling Ghostscript.  For Unix and\n          Windows, the defaults are 'gs' and 'gswin32c', respectively.\n\n     '-color'\n     '-mono'\n          Monochrome or color output.\n\n     '-solid'\n     '-dashed'\n          Forces all lines to be solid or dashed, respectively.\n\n     '-portrait'\n     '-landscape'\n          Specify the orientation of the plot for printed output.  For\n          non-printed output the aspect ratio of the output corresponds\n          to the plot area defined by the \"paperposition\" property in\n          the orientation specified.  This options is equivalent to\n          changing the figure's \"paperorientation\" property.\n\n     '-dDEVICE'\n          Output device, where DEVICE is one of:\n          'ps'\n          'ps2'\n          'psc'\n          'psc2'\n               Postscript (level 1 and 2, mono and color).  The FLTK\n               graphics toolkit generates Postscript level 3.0.\n\n          'eps'\n          'eps2'\n          'epsc'\n          'epsc2'\n               Encapsulated postscript (level 1 and 2, mono and color).\n               The FLTK graphic toolkit generates Postscript level 3.0.\n\n          'tex'\n          'epslatex'\n          'epslatexstandalone'\n          'pstex'\n          'pslatex'\n          'pdflatex'\n               Generate a LaTeX (or TeX) file for labels, and eps/ps/pdf\n               for graphics.  The file produced by 'epslatexstandalone'\n               can be processed directly by LaTeX.  The other formats\n               are intended to be included in a LaTeX (or TeX) document.\n               The 'tex' device is the same as the 'epslatex' device.\n               The 'pdflatex' device is only available for the FLTK\n               graphics toolkit.\n\n          'tikz'\n               Generate a LaTeX file using PGF/TikZ.  For the FLTK the\n               result is PGF.\n\n          'ill'\n          'aifm'\n               Adobe Illustrator (Obsolete for Gnuplot versions > 4.2)\n\n          'cdr'\n          'corel'\n               CorelDraw\n\n          'dxf'\n               AutoCAD\n\n          'emf'\n          'meta'\n               Microsoft Enhanced Metafile\n\n          'fig'\n               XFig.  For the Gnuplot graphics toolkit, the additional\n               options '-textspecial' or '-textnormal' can be used to\n               control whether the special flag should be set for the\n               text in the figure (default is '-textnormal').\n\n          'hpgl'\n               HP plotter language\n\n          'mf'\n               Metafont\n\n          'png'\n               Portable network graphics\n\n          'jpg'\n          'jpeg'\n               JPEG image\n\n          'gif'\n               GIF image (only available for the Gnuplot graphics\n               toolkit)\n\n          'pbm'\n               PBMplus\n\n          'svg'\n               Scalable vector graphics\n\n          'pdf'\n               Portable document format\n\n               NOTE: The gnuplot binary as shipped by Debian cannot\n               create PDF files, see http://bugs.debian.org/478677\n\n          If the device is omitted, it is inferred from the file\n          extension, or if there is no filename it is sent to the\n          printer as postscript.\n\n     '-dGHOSTSCRIPT_DEVICE'\n          Additional devices are supported by Ghostscript.  Some\n          examples are;\n\n          'ljet2p'\n               HP LaserJet IIP\n\n          'ljet3'\n               HP LaserJet III\n\n          'deskjet'\n               HP DeskJet and DeskJet Plus\n\n          'cdj550'\n               HP DeskJet 550C\n\n          'paintjet'\n               HP PointJet\n\n          'pcx24b'\n               24-bit color PCX file format\n\n          'ppm'\n               Portable Pixel Map file format\n\n          'pdfwrite'\n               Produces pdf output from eps\n\n          For a complete list, type 'system (\"gs -h\")' to see what\n          formats and devices are available.\n\n          When Ghostscript output is sent to a printer the size is\n          determined by the figure's \"papersize\" property.  When the\n          output is sent to a file the size is determined by the plot\n          box defined by the figure's \"paperposition\" property.\n\n     '-append'\n          Appends the PS, or PDF output to a pre-existing file of the\n          same type.\n\n     '-rNUM'\n          Resolution of bitmaps in pixels per inch.  For both metafiles\n          and SVG the default is the screen resolution, for other it is\n          150 dpi.  To specify screen resolution, use \"-r0\".\n\n     '-tight'\n          Forces a tight bounding box for eps-files.\n\n     '-PREVIEW'\n          Adds a preview to eps-files.  Supported formats are;\n\n          '-interchange'\n               Provides an interchange preview.\n\n          '-metalfile'\n               Provides a metafile preview.\n\n          '-pict'\n               Provides pict preview.\n\n          '-tiff'\n               Provides a tiff preview.\n\n     '-SXSIZE,YSIZE'\n          Plot size in pixels for EMF, GIF, JPEG, PBM, PNG and SVG.  For\n          PS, EPS, PDF, and other vector formats the plot size is in\n          points.  This option is equivalent to changing the size of the\n          plot box associated with \"paperposition\" property.  Using the\n          command form of the print function, you must quote the\n          XSIZE,YSIZE option.  For example, by writing '\"-S640,480\"'.\n\n     '-FFONTNAME'\n     '-FFONTNAME:SIZE'\n     '-F:SIZE'\n          Associates all text with the FONTNAME and/or FONTSIZE.\n          FONTNAME is ignored for some devices; dxf, fig, hpgl, etc.\n\n     The filename and options can be given in any order.\n\n     Example: Print to a file, using the svg device.\n\n          figure (1);\n          clf ();\n          surf (peaks);\n          print -dsvg figure1.svg\n\n     Example: Print to an HP Deskjet 550C.\n\n          figure (1);\n          clf ();\n          surf (peaks);\n          print -dcdj550\n\n     See also: figure, orient, saveas\n\n"

o_help(rand)

## [1] "USAGE: U = rand( n [, k])\n\nGenerates uniform random variates as R function 'runif' -- using the current RNG from R.\n\nPossible calls:\nrand(n, k)   returns a n*k matrix with uncorrelated U(0, 1) deviates drawn in columns\nrand(n)      returns a n*n matrix with uncorrelated U(0, 1) deviates drawn in columns\n\n\nNOTE:\nThis function substitutes Octave original function in calls from RcppOctave\n\n"

# or equivalently
o_help('rand')

## [1] "USAGE: U = rand( n [, k])\n\nGenerates uniform random variates as R function 'runif' -- using the current RNG from R.\n\nPossible calls:\nrand(n, k)   returns a n*k matrix with uncorrelated U(0, 1) deviates drawn in columns\nrand(n)      returns a n*n matrix with uncorrelated U(0, 1) deviates drawn in columns\n\n\nNOTE:\nThis function substitutes Octave original function in calls from RcppOctave\n\n"

# to include in Rd files, use argument rd=TRUE in an \Sexpr:
## Not run: 
##D  \Sexpr[results=rd,stage=render]{RcppOctave::o_help(rand, format='rd')}
## End(Not run)

# to see the included Rd code
o_help(rand, format=TRUE)

## [1] "\\if{html}{\\out{<pre>USAGE: U = rand( n [, k])\n\nGenerates uniform random variates as R function 'runif' -- using the current RNG from R.\n\nPossible calls:\nrand(n, k)   returns a n*k matrix with uncorrelated U(0, 1) deviates drawn in columns\nrand(n)      returns a n*n matrix with uncorrelated U(0, 1) deviates drawn in columns\n\n\nNOTE:\nThis function substitutes Octave original function in calls from RcppOctave\n\n</pre>}}\n\\if{text}{\\preformatted{USAGE: U = rand( n [, k])\n\nGenerates uniform random variates as R function 'runif' -- using the current RNG from R.\n\nPossible calls:\nrand(n, k)   returns a n*k matrix with uncorrelated U(0, 1) deviates drawn in columns\nrand(n)      returns a n*n matrix with uncorrelated U(0, 1) deviates drawn in columns\n\n\nNOTE:\nThis function substitutes Octave original function in calls from RcppOctave\n\n}}\n\\if{latex}{\\out{\\begin{verbatim}USAGE: U = rand( n [, k])\n\nGenerates uniform random variates as R function 'runif' -- using the current RNG from R.\n\nPossible calls:\nrand(n, k)   returns a n*k matrix with uncorrelated U(0, 1) deviates drawn in columns\nrand(n)      returns a n*n matrix with uncorrelated U(0, 1) deviates drawn in columns\n\n\nNOTE:\nThis function substitutes Octave original function in calls from RcppOctave\n\n\\end{verbatim}}}\n"

o_help(rand, format='HTML')
o_help(rand, format='latex')

#----------
# o_doc
#----------
try({ # may throw an error if Octave documentation is not installed

o_doc(text)
# or equivalently
o_doc('text')

})