Mercurial > hg > octave-lyh

comparison scripts/help/__makeinfo__.m @ 8768:e0fbf17a17bb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
__makeinfo__.m: rename from makeinfo.m
author John W. Eaton <jwe@octave.org>
date Mon, 16 Feb 2009 17:01:17 -0500
parents scripts/help/makeinfo.m@28b8bd2f6e66
children 2c8b2399247b
comparison
equal deleted inserted replaced
8767:026c6732ec7a 8768:e0fbf17a17bb
1 ## Copyright (C) 2009 Søren Hauberg
2 ##
3 ## This program is free software; you can redistribute it and/or modify it
4 ## under the terms of the GNU General Public License as published by
5 ## the Free Software Foundation; either version 3 of the License, or (at
6 ## your option) any later version.
7 ##
8 ## This program is distributed in the hope that it will be useful, but
9 ## WITHOUT ANY WARRANTY; without even the implied warranty of
10 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 ## General Public License for more details.
12 ##
13 ## You should have received a copy of the GNU General Public License
14 ## along with this program; see the file COPYING. If not, see
15 ## <http://www.gnu.org/licenses/>.
16
17 ## -*- texinfo -*-
18 ## @deftypefn {Function File} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type})
19 ## @deftypefnx{Function File} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type}, @var{see_also})
20 ## Undocumented internal function.
21 ## @end deftypefn
22
23 ## Run @code{makeinfo} on a given text.
24 ##
25 ## The string @var{text} is run through the @code{__makeinfo__} program
26 ## to generate output in various formats. This string must contain valid
27 ## Texinfo formatted text.
28 ##
29 ## The @var{output_type} selects the format of the output. This can be either
30 ## @t{"html"}, @t{"texinfo"}, or @t{"plain text"}. By default this is
31 ## @t{"plain text"}. If @var{output_type} is @t{"texinfo"}, the @t{@@seealso}
32 ## macro is expanded, but otherwise the text is unaltered.
33 ##
34 ## If the optional argument @var{see_also} is present, it is used to expand the
35 ## Octave specific @t{@@seealso} macro. This argument must be a function handle,
36 ## that accepts a cell array of strings as input argument (each elements of the
37 ## array corresponds to the arguments to the @t{@@seealso} macro), and return
38 ## the expanded string. If this argument is not given, the @t{@@seealso} macro
39 ## will be expanded to the text
40 ##
41 ## @example
42 ## See also: arg1, arg2@, ...
43 ## @end example
44 ##
45 ## @noindent
46 ## for @t{"plain text"} output, and
47 ##
48 ## @example
49 ## See also: @@ref@{arg1@}, @@ref@{arg2@}, ...
50 ## @end example
51 ##
52 ## @noindent
53 ## otherwise.
54 ##
55 ## The optional output argument @var{status} contains the exit status of the
56 ## @code{makeinfo} program as returned by @code{system}.
57
58 function [retval, status] = __makeinfo__ (text, output_type = "plain text", see_also = [])
59
60 ## Check input
61 if (nargin == 0)
62 print_usage ();
63 endif
64
65 if (!ischar (text))
66 error ("__makeinfo__: first input argument must be a string");
67 endif
68
69 if (!ischar (output_type))
70 error ("__makeinfo__: second input argument must be a string");
71 endif
72
73 ## Define the @seealso macro
74 if (isempty (see_also))
75 if (strcmpi (output_type, "plain text"))
76 see_also = @simple_see_also;
77 else
78 see_also = @simple_see_also_with_refs;
79 endif
80 endif
81
82 if (!isa (see_also, "function_handle"))
83 error ("__makeinfo__: third input argument must be the empty matrix, or a function handle");
84 endif
85
86 ## It seems like makeinfo sometimes gets angry if the character on a line is
87 ## a space, so we remove these.
88 text = strrep (text, "\n ", "\n");
89
90 ## Handle @seealso macro
91 SEE_ALSO = "@seealso";
92 start = strfind (text, SEE_ALSO);
93 if (!isempty (start))
94 if (start == 1 || (text (start-1) != "@"))
95 bracket_start = find (text (start:end) == "{", 1);
96 stop = find (text (start:end) == "}", 1);
97 if (!isempty (stop) && !isempty (bracket_start))
98 stop += start - 1;
99 bracket_start += start - 1;
100 else
101 bracket_start = start + length (SEE_ALSO);
102 stop = find (text (start:end) == "\n", 1);
103 if (isempty (stop))
104 stop = length (text);
105 else
106 stop += start - 1;
107 endif
108 endif
109 see_also_args = text (bracket_start+1:(stop-1));
110 see_also_args = strtrim (cellstr (split (see_also_args, ",")));
111 expanded = see_also (see_also_args);
112 text = strcat (text (1:start-1), expanded, text (stop+1:end));
113 endif
114 endif
115
116 if (strcmpi (output_type, "texinfo"))
117 status = 0;
118 retval = text;
119 return;
120 endif
121
122 ## Create the final TeXinfo input string
123 text = sprintf ("\\input texinfo\n\n%s\n\n@bye\n", text);
124
125 unwind_protect
126 ## Write Texinfo to tmp file
127 [fid, name, msg] = mkstemp ("octave_help_XXXXXX", true);
128 fwrite (fid, text);
129 fclose (fid);
130
131 ## Take action depending on output type
132 switch (lower (output_type))
133 case "plain text"
134 cmd = sprintf ("%s --no-headers --no-warn --force --no-validate %s",
135 makeinfo_program (), name);
136 case "html"
137 cmd = sprintf ("%s --no-headers --html --no-warn --no-validate --force %s",
138 makeinfo_program (), name);
139 otherwise
140 error ("__makeinfo__: unsupported output type: '%s'", output_type);
141 endswitch
142
143 ## Call makeinfo
144 [status, retval] = system (cmd);
145
146 unwind_protect_cleanup
147 if (exist (name, "file"))
148 delete (name);
149 endif
150 end_unwind_protect
151 endfunction
152
153 function expanded = simple_see_also (args)
154 expanded = strcat ("\nSee also:", sprintf (" %s,", args {:}));
155 expanded = strcat (expanded (1:end-1), "\n\n");
156 endfunction
157
158 function expanded = simple_see_also_with_refs (args)
159 expanded = strcat ("\nSee also:", sprintf (" @ref{%s},", args {:}));
160 expanded = strcat (expanded (1:end-1), "\n\n");
161 endfunction