Mercurial > forge
annotate extra/generate_html/inst/html_help_text.m @ 9932:0ae56b3486df octave-forge
html_help_text: reverting changes comitted by accident in r8745
| author | carandraug |
|---|---|
| date | Sat, 31 Mar 2012 21:36:13 +0000 |
| parents | c762ea517481 |
| children | c11796bf9e82 |
| rev | line source |
|---|---|
| 5625 | 1 ## Copyright (C) 2008 Soren 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} html_help_text (@var{name}, @var{outname}, @var{options}) | |
| 19 ## Writes a function help text to disk formatted as @t{HTML}. | |
| 20 ## | |
| 21 ## The help text of the function @var{name} is written to the file @var{outname} | |
| 22 ## formatted as @t{HTML}. The design of the generated @t{HTML} page is controlled | |
| 23 ## through the @var{options} variable. This is a structure with the following | |
| 24 ## optional fields. | |
| 25 ## | |
| 26 ## @table @samp | |
| 27 ## @item header | |
| 28 ## This field contains the @t{HTML} header of the generated file. Through this | |
| 29 ## things such as @t{CSS} style sheets can be set. | |
| 30 ## @item footer | |
| 31 ## This field contains the @t{HTML} footer of the generated file. This should | |
| 32 ## match the @samp{header} field to ensure all opened tags get closed. | |
| 33 ## @item title | |
| 34 ## This field sets the title of the @t{HTML} page. This is enforced even if the | |
| 35 ## @samp{header} field contains a title. | |
| 36 ## @end table | |
| 37 ## | |
| 38 ## @var{options} structures for various projects can be with the @code{get_html_options} | |
| 39 ## function. As a convenience, if @var{options} is a string, a structure will | |
| 40 ## be generated by calling @code{get_html_options}. | |
| 41 ## | |
| 42 ## @seealso{get_html_options, generate_package_html} | |
| 43 ## @end deftypefn | |
| 44 | |
| 45 function html_help_text (name, outname, options = struct (), root = "") | |
| 46 ## Get the help text of the function | |
| 47 [text, format] = get_help_text (name); | |
| 48 | |
| 49 ## If options is a string, call get_html_options | |
| 50 if (ischar (options)) | |
| 51 options = get_html_options (options); | |
| 52 endif | |
| 53 | |
| 54 ## Take action depending on help text format | |
| 55 switch (lower (format)) | |
| 56 case "plain text" | |
| 57 header = "<html><head><title></title></head><body>\n"; | |
| 58 text = sprintf ("<pre>%s</pre>\n", text); | |
| 59 footer = "</body></html>\n"; | |
| 60 | |
| 61 case "texinfo" | |
| 62 ## Add easily recognisable text before and after real text | |
| 63 start = "###### OCTAVE START ######"; | |
| 64 stop = "###### OCTAVE STOP ######"; | |
| 65 text = sprintf ("%s\n%s\n%s\n", start, text, stop); | |
| 66 | |
| 67 ## Handle @seealso | |
| 6793 | 68 if (isfield (options, "seealso")) |
| 69 seealso = @(args) options.seealso (root, args); | |
| 5625 | 70 else |
| 6793 | 71 seealso = @(args) html_see_also_with_prefix (root, args {:}); |
| 5625 | 72 endif |
| 73 | |
| 74 ## Run makeinfo | |
| 75 [text, status] = __makeinfo__ (text, "html", seealso); | |
| 76 if (status != 0) | |
| 77 error ("html_help_text: couln't parse file '%s'", name); | |
| 78 endif | |
| 79 | |
| 80 ## Split text into header, body, and footer using the text we added above | |
| 81 start_idx = strfind (text, start); | |
| 82 stop_idx = strfind (text, stop); | |
| 83 header = text (1:start_idx - 1); | |
| 84 footer = text (stop_idx + length (stop):end); | |
| 85 text = text (start_idx + length (start):stop_idx - 1); | |
| 86 | |
|
6131
06bed41ae641
First draft of html generation for new release system
hauberg
parents:
5755
diff
changeset
|
87 ## Hack around 'makeinfo' bug that forgets to put <p>'s before function declarations |
|
06bed41ae641
First draft of html generation for new release system
hauberg
parents:
5755
diff
changeset
|
88 text = strrep (text, "—", "<p class=\"functionfile\">"); |
|
06bed41ae641
First draft of html generation for new release system
hauberg
parents:
5755
diff
changeset
|
89 |
| 5625 | 90 case "not found" |
| 91 error ("html_help_text: `%s' not found\n", name); | |
| 92 otherwise | |
| 93 error ("html_help_text: internal error: unsupported help text format: '%s'\n", format); | |
| 94 endswitch | |
| 95 | |
| 96 ## Read 'options' input argument | |
| 97 [header, title, footer] = get_header_title_and_footer (options, name, root); | |
| 98 | |
| 99 ## Add demo:// links if requested | |
| 100 if (isfield (options, "include_demos") && options.include_demos) | |
| 101 ## Determine if we have demos | |
| 102 [code, idx] = test (name, "grabdemo"); | |
| 103 if (length (idx) > 1) | |
| 104 ## Demos to the main text | |
| 105 demo_text = ""; | |
| 106 | |
| 107 outdir = fileparts (outname); | |
| 108 imagedir = "images"; | |
| 109 full_imagedir = fullfile (outdir, imagedir); | |
| 110 num_demos = length (idx) - 1; | |
| 111 demo_num = 0; | |
| 112 for k = 1:num_demos | |
| 113 ## Run demo | |
| 114 code_k = code (idx (k):idx (k+1)-1); | |
| 115 try | |
| 116 [output, images] = get_output (code_k, imagedir, full_imagedir, name); | |
| 117 catch | |
| 6289 | 118 lasterr () |
| 5625 | 119 continue; |
| 120 end_try_catch | |
| 121 has_text = !isempty (output); | |
| 122 has_images = !isempty (images); | |
| 123 if (length (images) > 1) | |
| 124 ft = "figures"; | |
| 125 else | |
| 126 ft = "figure"; | |
| 127 endif | |
| 128 | |
| 129 ## Create text | |
| 130 demo_num ++; | |
| 131 demo_header = sprintf ("<h2>Demonstration %d</h2>\n<div class=\"demo\">\n", demo_num); | |
| 132 demo_footer = "</div>\n"; | |
| 133 | |
| 134 demo_k {1} = "<p>The following code</p>\n"; | |
| 135 demo_k {2} = sprintf ("<pre class=\"example\">%s</pre>\n", code_k); | |
| 136 if (has_text && has_images) | |
| 137 demo_k {3} = "<p>Produces the following output</p>\n"; | |
| 138 demo_k {4} = sprintf ("<pre class=\"example\">%s</pre>\n", output); | |
| 139 demo_k {5} = sprintf ("<p>and the following %s</p>\n", ft); | |
| 140 demo_k {6} = sprintf ("<p>%s</p>\n", images_in_html (images)); | |
| 141 elseif (has_text) # no images | |
| 142 demo_k {3} = "<p>Produces the following output</p>\n"; | |
| 143 demo_k {4} = sprintf ("<pre class=\"example\">%s</pre>\n", output); | |
| 144 elseif (has_images) # no text | |
| 145 demo_k {3} = sprintf ("<p>Produces the following %s</p>\n", ft); | |
| 146 demo_k {6} = sprintf ("<p>%s</p>\n", images_in_html (images)); | |
| 147 else # neither text nor images | |
| 148 demo_k {3} = sprintf ("<p>gives an example of how '%s' is used.</p>\n", name); | |
| 149 endif | |
| 150 | |
| 151 demo_text = strcat (demo_text, demo_header, demo_k {:}, demo_footer); | |
| 152 endfor | |
| 153 | |
| 154 text = strcat (text, demo_text); | |
| 155 endif | |
| 156 endif | |
| 157 | |
| 158 ## Write result to disk | |
| 159 fid = fopen (outname, "w"); | |
| 160 if (fid < 0) | |
| 161 error ("html_help_text: could not open '%s' for writing", outname); | |
| 162 endif | |
| 163 fprintf (fid, "%s\n%s\n%s", header, text, footer); | |
| 164 fclose (fid); | |
| 165 | |
| 166 endfunction | |
| 167 | |
| 6793 | 168 function expanded = html_see_also_with_prefix (prefix, root, varargin) |
| 5625 | 169 header = "@html\n<div class=\"seealso\">\n<b>See also</b>: "; |
| 170 footer = "\n</div>\n@end html\n"; | |
| 171 | |
| 172 format = sprintf (" <a href=\"%s%%s.html\">%%s</a> ", prefix); | |
| 173 | |
| 174 varargin2 = cell (1, 2*length (varargin)); | |
| 175 varargin2 (1:2:end) = varargin; | |
| 176 varargin2 (2:2:end) = varargin; | |
| 177 | |
| 178 list = sprintf (format, varargin2 {:}); | |
| 179 | |
| 180 expanded = strcat (header, list, footer); | |
| 181 endfunction | |
| 182 | |
| 183 function [text, images] = get_output (code, imagedir, full_imagedir, fileprefix) | |
| 184 ## Clear everything | |
| 185 close all | |
| 186 diary_file = "__diary__.txt"; | |
| 187 if (exist (diary_file, "file")) | |
| 188 delete (diary_file); | |
| 189 endif | |
| 5755 | 190 |
| 191 unwind_protect | |
| 192 ## Setup figure and pager properties | |
| 193 def = get (0, "defaultfigurevisible"); | |
| 194 set (0, "defaultfigurevisible", "off"); | |
| 195 more_val = page_screen_output (false); | |
| 5625 | 196 |
| 5755 | 197 ## Evaluate the code |
| 198 diary (diary_file); | |
| 199 eval (code); | |
| 200 diary ("off"); | |
| 5625 | 201 |
| 5755 | 202 ## Read the results |
| 203 fid = fopen (diary_file, "r"); | |
| 204 diary_data = char (fread (fid).'); | |
| 205 fclose (fid); | |
| 5625 | 206 |
| 5755 | 207 ## Remove 'diary ("off");' from the diary |
| 208 idx = strfind (diary_data, "diary (\"off\");"); | |
| 209 if (isempty (idx)) | |
| 210 text = diary_data; | |
| 211 else | |
| 212 text = diary_data (1:idx (end)-1); | |
| 213 endif | |
| 214 text = strtrim (text); | |
| 5625 | 215 |
| 5755 | 216 ## Save figures |
| 217 if (!isempty (get (0, "currentfigure")) && !exist (full_imagedir, "dir")) | |
| 218 mkdir (full_imagedir); | |
| 219 endif | |
| 5625 | 220 |
| 5755 | 221 images = {}; |
| 222 while (!isempty (get (0, "currentfigure"))) | |
| 223 fig = gcf (); | |
| 224 r = round (1000*rand ()); | |
| 225 name = sprintf ("%s_%d.png", fileprefix, r); | |
| 226 full_filename = fullfile (full_imagedir, name); | |
| 227 filename = fullfile (imagedir, name); | |
| 228 print (fig, full_filename); | |
| 229 images {end+1} = filename; | |
| 230 close (fig); | |
| 231 endwhile | |
| 5625 | 232 |
| 5755 | 233 ## Reverse image list, since we got them latest-first |
| 234 images = images (end:-1:1); | |
| 5625 | 235 |
| 5755 | 236 unwind_protect_cleanup |
| 237 delete (diary_file); | |
| 238 set (0, "defaultfigurevisible", def); | |
| 239 page_screen_output (more_val); | |
| 240 end_unwind_protect | |
| 5625 | 241 endfunction |
| 242 | |
| 243 function text = images_in_html (images) | |
| 244 header = "<table class=\"images\">\n<tr>\n"; | |
| 245 footer = "</tr></table>\n"; | |
| 246 headers = sprintf ("<th class=\"images\">Figure %d</th>\n", 1:numel (images)); | |
| 247 ims = sprintf ("<td class=\"images\"><img src=\"%s\" class=\"demo\"/></td>\n", images {:}); | |
| 248 text = strcat (header, headers, "</tr><tr>\n", ims, footer); | |
| 249 endfunction |