diff scripts/help/makeinfo.m @ 8575:f134925a1cfa

m-file implementation of help system
author Soren Hauberg <soren@hauberg.org>
date Thu, 22 Jan 2009 18:22:52 -0500
parents
children 28b8bd2f6e66
line wrap: on
line diff
new file mode 100644
--- /dev/null
+++ b/scripts/help/makeinfo.m
@@ -0,0 +1,160 @@
+## Copyright (C) 2009 Søren Hauberg
+##
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## This program is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} {[@var{retval}, @var{status}] =} makeinfo (@var{text}, @
+## @var{output_type})
+## @deftypefnx{Function File} {[@var{retval}, @var{status}] =} makeinfo (@var{text}, @
+## @var{output_type}, @var{see_also})
+## Run @code{makeinfo} on a given text.
+##
+## The string @var{text} is run through the @code{makeinfo} program to generate
+## output in various formats. This string must contain valid Texinfo formatted
+## text.
+##
+## The @var{output_type} selects the format of the output. This can be either
+## @t{"html"}, @t{"texinfo"}, or @t{"plain text"}. By default this is
+## @t{"plain text"}. If @var{output_type} is @t{"texinfo"}, the @t{@@seealso}
+## macro is expanded, but otherwise the text is unaltered.
+##
+## If the optional argument @var{see_also} is present, it is used to expand the
+## Octave specific @t{@@seealso} macro. This argument must be a function handle,
+## that accepts a cell array of strings as input argument (each elements of the
+## array corresponds to the arguments to the @t{@@seealso} macro), and return
+## the expanded string. If this argument is not given, the @t{@@seealso} macro
+## will be expanded to the text
+##
+## @example
+## See also: arg1, arg2@, ...
+## @end example
+##
+## @noindent
+## for @t{"plain text"} output, and
+##
+## @example
+## See also: @@ref@{arg1@}, @@ref@{arg2@}, ...
+## @end example
+##
+## @noindent
+## otherwise.
+##
+## The optional output argument @var{status} contains the exit status of the
+## @code{makeinfo} program as returned by @code{system}.
+## @end deftypefn
+
+function [retval, status] = makeinfo (text, output_type = "plain text", see_also = [])
+  ## Check input
+  if (nargin == 0)
+    print_usage ();
+  endif
+  
+  if (!ischar (text))
+    error ("makeinfo: first input argument must be a string");
+  endif
+  
+  if (!ischar (output_type))
+    error ("makeinfo: second input argument must be a string");
+  endif
+  
+  ## Define the @seealso macro
+  if (isempty (see_also))
+    if (strcmpi (output_type, "plain text"))
+      see_also = @simple_see_also;
+    else
+      see_also = @simple_see_also_with_refs;
+    endif
+  endif
+  
+  if (!isa (see_also, "function_handle"))
+    error ("makeinfo: third input argument must be the empty matrix, or a function handle");
+  endif
+  
+  ## It seems like makeinfo sometimes gets angry if the character on a line is
+  ## a space, so we remove these.
+  text = strrep (text, "\n ", "\n");
+  
+  ## Handle @seealso macro
+  SEE_ALSO = "@seealso";
+  start = strfind (text, SEE_ALSO);
+  if (!isempty (start))
+    if (start == 1 || (text (start-1) != "@"))
+      bracket_start = find (text (start:end) == "{", 1);
+      stop = find (text (start:end) == "}", 1);
+      if (!isempty (stop) && !isempty (bracket_start))
+        stop += start - 1;
+        bracket_start += start - 1;
+      else
+        bracket_start = start + length (SEE_ALSO);
+        stop = find (text (start:end) == "\n", 1);
+        if (isempty (stop))
+          stop = length (text);
+        else
+          stop += start - 1;
+        endif
+      endif
+      see_also_args = text (bracket_start+1:(stop-1));
+      see_also_args = strtrim (cellstr (split (see_also_args, ",")));
+      expanded = see_also (see_also_args);
+      text = strcat (text (1:start-1), expanded, text (stop+1:end));
+    endif
+  endif
+  
+  if (strcmpi (output_type, "texinfo"))
+    status = 0;
+    retval = text;
+    return;
+  endif
+  
+  ## Create the final TeXinfo input string
+  text = sprintf ("\\input texinfo\n\n%s\n\n@bye\n", text);
+  
+  unwind_protect
+    ## Write Texinfo to tmp file
+    [fid, name, msg] = mkstemp ("octave_help_XXXXXX", true);
+    fwrite (fid, text);
+    fclose (fid);
+
+    ## Take action depending on output type
+    switch (lower (output_type))
+      case "plain text"
+         cmd = sprintf ("%s --no-headers --no-warn --force --no-validate %s",
+                        makeinfo_program (), name);
+      case "html"
+         cmd = sprintf ("%s --no-headers --html --no-warn --no-validate --force %s",
+                        makeinfo_program (), name);
+      otherwise
+        error ("makeinfo: unsupported output type: '%s'", output_type);
+    endswitch
+  
+    ## Call makeinfo
+    [status, retval] = system (cmd);
+   
+  unwind_protect_cleanup
+    if (exist (name, "file"))
+      delete (name);
+    endif
+  end_unwind_protect
+endfunction
+
+function expanded = simple_see_also (args)
+  expanded = strcat ("\nSee also:", sprintf (" %s,", args {:}));
+  expanded = strcat (expanded (1:end-1), "\n\n");
+endfunction
+
+function expanded = simple_see_also_with_refs (args)
+  expanded = strcat ("\nSee also:", sprintf (" @ref{%s},", args {:}));
+  expanded = strcat (expanded (1:end-1), "\n\n");
+endfunction