octave_packages/m/help/doc.m

   1 ## Copyright (C) 2005-2012 Søren Hauberg
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn {Command} {} doc @var{function_name}
  21 ## Display documentation for the function @var{function_name}
  22 ## directly from an on-line version of
  23 ## the printed manual, using the GNU Info browser.  If invoked without
  24 ## any arguments, the manual is shown from the beginning.
  25 ##
  26 ## For example, the command @kbd{doc rand} starts the GNU Info browser
  27 ## at the @code{rand} node in the on-line version of the manual.
  28 ##
  29 ## Once the GNU Info browser is running, help for using it is available
  30 ## using the command @kbd{C-h}.
  31 ## @seealso{help}
  32 ## @end deftypefn
  33
  34 ## Author: Soren Hauberg <soren@hauberg.org>
  35 ## Adapted-by: jwe
  36
  37 function retval = doc (fname)
  38
  39   if (nargin == 0 || nargin == 1)
  40
  41     ftype = 0;
  42
  43     if (nargin == 1)
  44       ## Get the directory where the function lives.
  45       ## FIXME -- maybe we should have a better way of doing this.
  46
  47       if (ischar (fname))
  48         ftype = exist (fname);
  49       else
  50         error ("doc: expecting argument to be a character string");
  51       endif
  52     else
  53       fname = "";
  54     endif
  55
  56     if (ftype == 2 || ftype == 3)
  57       ffile = which (fname);
  58     else
  59       ffile = "";
  60     endif
  61
  62     if (isempty (ffile))
  63       info_dir = octave_config_info ("infodir");
  64     else
  65       info_dir = fileparts (ffile);
  66     endif
  67
  68     ## Determine if a file called doc.info exist in the same
  69     ## directory as the function.
  70
  71     info_file_name = fullfile (info_dir, "doc.info");
  72
  73     [stat_info, err] = stat (info_file_name);
  74
  75     if (err < 0)
  76       info_file_name = info_file ();
  77     endif
  78
  79     ## FIXME -- don't change the order of the arguments below because
  80     ## the info-emacs-info script currently expects --directory DIR as
  81     ## the third and fourth arguments.  Someone should fix that.
  82
  83     cmd = sprintf ("\"%s\" --file \"%s\" --directory \"%s\"",
  84                    info_program (), info_file_name, info_dir);
  85
  86     have_fname = ! isempty (fname);
  87
  88     if (have_fname)
  89       status = system (sprintf ("%s --index-search %s", cmd, fname));
  90     endif
  91
  92     if (! (have_fname && status == 0))
  93       status = system (cmd);
  94       if (status == 127)
  95         warning ("unable to find info program `%s'", info_program ());
  96       endif
  97     endif
  98
  99     if (nargout > 0)
 100       retval = status;
 101     endif
 102
 103   else
 104     print_usage ();
 105   endif
 106
 107 endfunction
 108
 109 %!test if exist( info_file ()) != 2 && exist (sprintf ("%s.gz", info_file ())) != 2
 110 %!       error ("Info file %s or %s.gz does not exist!", info_file (), info_file ());
 111 %!     endif