octave_packages/m/help/__makeinfo__.m

   1 ## Copyright (C) 2009-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  {Function File} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type})
  21 ## @deftypefnx {Function File} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type}, @var{see_also})
  22 ## Undocumented internal function.
  23 ## @end deftypefn
  24
  25 ## Run @code{makeinfo} on a given text.
  26 ##
  27 ## The string @var{text} is run through the @code{__makeinfo__} program
  28 ## to generate output in various formats. This string must contain valid
  29 ## Texinfo formatted text.
  30 ##
  31 ## The @var{output_type} selects the format of the output. This can be either
  32 ## @t{"html"}, @t{"texinfo"}, or @t{"plain text"}. By default this is
  33 ## @t{"plain text"}. If @var{output_type} is @t{"texinfo"}, the @t{@@seealso}
  34 ## macro is expanded, but otherwise the text is unaltered.
  35 ##
  36 ## If the optional argument @var{see_also} is present, it is used to expand the
  37 ## Octave specific @t{@@seealso} macro. This argument must be a function handle,
  38 ## that accepts a cell array of strings as input argument (each elements of the
  39 ## array corresponds to the arguments to the @t{@@seealso} macro), and return
  40 ## the expanded string. If this argument is not given, the @t{@@seealso} macro
  41 ## will be expanded to the text
  42 ##
  43 ## @example
  44 ## See also: arg1, arg2, ...
  45 ## @end example
  46 ##
  47 ## @noindent
  48 ## for @t{"plain text"} output, and
  49 ##
  50 ## @example
  51 ## See also: @@ref@{arg1@}, @@ref@{arg2@}, ...
  52 ## @end example
  53 ##
  54 ## @noindent
  55 ## otherwise.
  56 ##
  57 ## The optional output argument @var{status} contains the exit status of the
  58 ## @code{makeinfo} program as returned by @code{system}.
  59
  60 function [retval, status] = __makeinfo__ (text, output_type = "plain text", fsee_also)
  61
  62   ## Check input
  63   if (nargin < 1 || nargin > 3)
  64     print_usage ();
  65   endif
  66
  67   if (! ischar (text))
  68     error ("__makeinfo__: first input argument must be a string");
  69   endif
  70
  71   if (! ischar (output_type))
  72     error ("__makeinfo__: second input argument must be a string");
  73   endif
  74
  75   if (nargin < 3)
  76     if (strcmpi (output_type, "plain text"))
  77       fsee_also = @(T) strcat ...
  78           ("\nSee also:", sprintf (" %s,", T{:})(1:end-1), "\n");
  79     else
  80       fsee_also = @(T) strcat ...
  81           ("\nSee also:", sprintf (" @ref{%s},", T{:})(1:end-1), "\n");
  82     endif
  83   endif
  84
  85   if (! isa (fsee_also, "function_handle"))
  86     error ("__makeinfo__: third input argument must be a function handle");
  87   endif
  88
  89
  90   ## It seems like makeinfo sometimes gets angry if the first character
  91   ## on a line is a space, so we remove these.
  92   text = strrep (text, "\n ", "\n");
  93
  94   ## Handle @seealso macro
  95   see_also_pat = '@seealso *\{(.*)\}';
  96   args = regexp (text, see_also_pat, 'tokens');
  97   for ii = 1:numel (args)
  98     expanded = fsee_also (strtrim (strsplit (args{ii}{:}, ',', true)));
  99     text = regexprep (text, see_also_pat, expanded, 'once');
 100   endfor
 101
 102   ## Handle @nospell macro
 103   text = regexprep (text, '@nospell *\{([^}]*)\}', "$1");
 104   ## Handle @xcode macro
 105   text = regexprep (text, '@xcode *\{([^}]*)\}', "$1");
 106
 107   if (strcmpi (output_type, "texinfo"))
 108     status = 0;
 109     retval = text;
 110     return;
 111   endif
 112
 113   ## Create the final TeXinfo input string
 114   text = sprintf ("\\input texinfo\n\n%s\n\n@bye\n", text);
 115
 116   unwind_protect
 117     ## Write Texinfo to tmp file
 118     template = "octave-help-XXXXXX";
 119     [fid, name] = mkstemp (fullfile (P_tmpdir, template), true);
 120     if (fid < 0)
 121       error ("__makeinfo__: could not create temporary file");
 122     endif
 123     fwrite (fid, text);
 124     fclose (fid);
 125
 126     ## Take action depending on output type
 127     switch (lower (output_type))
 128       case "plain text"
 129         cmd = sprintf ("%s --no-headers --no-warn --force --no-validate %s",
 130                        makeinfo_program (), name);
 131       case "html"
 132         cmd = sprintf ("%s --no-headers --html --no-warn --no-validate --force %s",
 133                        makeinfo_program (), name);
 134       otherwise
 135         error ("__makeinfo__: unsupported output type: '%s'", output_type);
 136     endswitch
 137
 138     ## Call makeinfo
 139     [status, retval] = system (cmd);
 140
 141   unwind_protect_cleanup
 142     if (exist (name, "file"))
 143       delete (name);
 144     endif
 145   end_unwind_protect
 146 endfunction
 147
 148 ## No test needed for internal helper function.
 149 %!assert (1)
 150