1 ## Copyright (C) 2009-2012 S�ren Hauberg
3 ## This file is part of Octave.
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.
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.
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/>.
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.
25 ## Run @code{makeinfo} on a given text.
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.
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.
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
44 ## See also: arg1, arg2, ...
48 ## for @t{"plain text"} output, and
51 ## See also: @@ref@{arg1@}, @@ref@{arg2@}, ...
57 ## The optional output argument @var{status} contains the exit status of the
58 ## @code{makeinfo} program as returned by @code{system}.
60 function [retval, status] = __makeinfo__ (text, output_type = "plain text", fsee_also)
63 if (nargin < 1 || nargin > 3)
68 error ("__makeinfo__: first input argument must be a string");
71 if (! ischar (output_type))
72 error ("__makeinfo__: second input argument must be a string");
76 if (strcmpi (output_type, "plain text"))
77 fsee_also = @(T) strcat ...
78 ("\nSee also:", sprintf (" %s,", T{:})(1:end-1), "\n");
80 fsee_also = @(T) strcat ...
81 ("\nSee also:", sprintf (" @ref{%s},", T{:})(1:end-1), "\n");
85 if (! isa (fsee_also, "function_handle"))
86 error ("__makeinfo__: third input argument must be a function handle");
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");
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');
102 ## Handle @nospell macro
103 text = regexprep (text, '@nospell *\{([^}]*)\}', "$1");
104 ## Handle @xcode macro
105 text = regexprep (text, '@xcode *\{([^}]*)\}', "$1");
107 if (strcmpi (output_type, "texinfo"))
113 ## Create the final TeXinfo input string
114 text = sprintf ("\\input texinfo\n\n%s\n\n@bye\n", text);
117 ## Write Texinfo to tmp file
118 template = "octave-help-XXXXXX";
119 [fid, name] = mkstemp (fullfile (P_tmpdir, template), true);
121 error ("__makeinfo__: could not create temporary file");
126 ## Take action depending on output type
127 switch (lower (output_type))
129 cmd = sprintf ("%s --no-headers --no-warn --force --no-validate %s",
130 makeinfo_program (), name);
132 cmd = sprintf ("%s --no-headers --html --no-warn --no-validate --force %s",
133 makeinfo_program (), name);
135 error ("__makeinfo__: unsupported output type: '%s'", output_type);
139 [status, retval] = system (cmd);
141 unwind_protect_cleanup
142 if (exist (name, "file"))
148 ## No test needed for internal helper function.