GNU Octave  4.0.0
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
help.cc
Go to the documentation of this file.
1 /*
2 
3 Copyright (C) 1993-2015 John W. Eaton
4 
5 This file is part of Octave.
6 
7 Octave is free software; you can redistribute it and/or modify it
8 under the terms of the GNU General Public License as published by the
9 Free Software Foundation; either version 3 of the License, or (at your
10 option) any later version.
11 
12 Octave is distributed in the hope that it will be useful, but WITHOUT
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 for more details.
16 
17 You should have received a copy of the GNU General Public License
18 along with Octave; see the file COPYING. If not, see
19 <http://www.gnu.org/licenses/>.
20 
21 */
22 
23 #ifdef HAVE_CONFIG_H
24 #include <config.h>
25 #endif
26 
27 #include <cstdlib>
28 #include <cstring>
29 
30 #include <algorithm>
31 #include <iostream>
32 #include <fstream>
33 #include <sstream>
34 #include <string>
35 
36 #include <sys/types.h>
37 #include <unistd.h>
38 
39 #include "cmd-edit.h"
40 #include "file-ops.h"
41 #include "file-stat.h"
42 #include "oct-env.h"
43 #include "oct-locbuf.h"
44 #include "str-vec.h"
45 
46 #include <defaults.h>
47 #include "defun.h"
48 #include "dirfns.h"
49 #include "error.h"
50 #include "gripes.h"
51 #include "help.h"
52 #include "input.h"
53 #include "load-path.h"
54 #include "oct-obj.h"
55 #include "ov-usr-fcn.h"
56 #include "pager.h"
57 #include "parse.h"
58 #include "pathsearch.h"
59 #include "procstream.h"
60 #include "pt-pr-code.h"
61 #include "sighandlers.h"
62 #include "symtab.h"
63 #include "syswait.h"
64 #include "toplev.h"
65 #include "unwind-prot.h"
66 #include "utils.h"
67 #include "variables.h"
68 #include "version.h"
69 #include "quit.h"
70 
71 // Name of the doc cache file specified on the command line.
72 // (--doc-cache-file file)
73 std::string Vdoc_cache_file;
74 
75 // Name of the file containing local Texinfo macros that are prepended
76 // to doc strings before processing.
77 // (--texi-macros-file)
78 std::string Vtexi_macros_file;
79 
80 // Name of the info file specified on command line.
81 // (--info-file file)
82 std::string Vinfo_file;
83 
84 // Name of the info reader we'd like to use.
85 // (--info-program program)
86 std::string Vinfo_program;
87 
88 // Name of the makeinfo program to run.
89 static std::string Vmakeinfo_program = "makeinfo";
90 
91 // If TRUE, don't print additional help message in help and usage
92 // functions.
93 static bool Vsuppress_verbose_help_message = false;
94 
95 #include <map>
96 
97 typedef std::map<std::string, std::string> map_type;
98 typedef map_type::value_type pair_type;
99 typedef map_type::const_iterator map_iter;
100 
101 template<typename T, size_t z>
102 size_t
103 size (T const (&)[z])
104 {
105  return z;
106 }
107 
108 const static pair_type operators[] =
109 {
110  pair_type ("!",
111  "-*- texinfo -*-\n\
112 @deftypefn {Operator} {} !\n\
113 Logical 'not' operator.\n\
114 @seealso{~, not}\n\
115 @end deftypefn"),
116 
117  pair_type ("~",
118  "-*- texinfo -*-\n\
119 @deftypefn {Operator} {} ~\n\
120 Logical 'not' operator.\n\
121 @seealso{!, not}\n\
122 @end deftypefn"),
123 
124  pair_type ("!=",
125  "-*- texinfo -*-\n\
126 @deftypefn {Operator} {} !=\n\
127 Logical 'not equals' operator.\n\
128 @seealso{~=, ne}\n\
129 @end deftypefn"),
130 
131  pair_type ("~=",
132  "-*- texinfo -*-\n\
133 @deftypefn {Operator} {} ~=\n\
134 Logical 'not equals' operator.\n\
135 @seealso{!=, ne}\n\
136 @end deftypefn"),
137 
138  pair_type ("\"",
139  "-*- texinfo -*-\n\
140 @deftypefn {Operator} {} \"\n\
141 String delimiter.\n\
142 @end deftypefn"),
143 
144  pair_type ("#",
145  "-*- texinfo -*-\n\
146 @deftypefn {Operator} {} #\n\
147 Begin comment character.\n\
148 @seealso{%, #@\\{}\n\
149 @end deftypefn"),
150 
151  pair_type ("%",
152  "-*- texinfo -*-\n\
153 @deftypefn {Operator} {} %\n\
154 Begin comment character.\n\
155 @seealso{#, %@\\{}\n\
156 @end deftypefn"),
157 
158  pair_type ("#{",
159  "-*- texinfo -*-\n\
160 @deftypefn {Operator} {} #@{\n\
161 Begin block comment. There must be nothing else, other than\n\
162 whitespace, in the line both before and after @code{#@{}.\n\
163 It is possible to nest block comments.\n\
164 @seealso{%@\\{, #@\\}, #}\n\
165 @end deftypefn"),
166 
167  pair_type ("%{",
168  "-*- texinfo -*-\n\
169 @deftypefn {Operator} {} %@{\n\
170 Begin block comment. There must be nothing else, other than\n\
171 whitespace, in the line both before and after @code{%@{}.\n\
172 It is possible to nest block comments.\n\
173 @seealso{#@\\{, %@\\}, %}\n\
174 @end deftypefn"),
175 
176  pair_type ("#}",
177  "-*- texinfo -*-\n\
178 @deftypefn {Operator} {} #@}\n\
179 Close block comment. There must be nothing else, other than\n\
180 whitespace, in the line both before and after @code{#@}}.\n\
181 It is possible to nest block comments.\n\
182 @seealso{%@\\}, #@\\{, #}\n\
183 @end deftypefn"),
184 
185  pair_type ("%}",
186  "-*- texinfo -*-\n\
187 @deftypefn {Operator} {} %@}\n\
188 Close block comment. There must be nothing else, other than\n\
189 whitespace, in the line both before and after @code{%@}}.\n\
190 It is possible to nest block comments.\n\
191 @seealso{#@\\}, %@\\{, %}\n\
192 @end deftypefn"),
193 
194  pair_type ("...",
195  "-*- texinfo -*-\n\
196 @deftypefn {Operator} {} ...\n\
197 Continuation marker. Joins current line with following line.\n\
198 @end deftypefn"),
199 
200  pair_type ("&",
201  "-*- texinfo -*-\n\
202 @deftypefn {Operator} {} &\n\
203 Element by element logical 'and' operator.\n\
204 @seealso{&&, and}\n\
205 @end deftypefn"),
206 
207  pair_type ("&&",
208  "-*- texinfo -*-\n\
209 @deftypefn {Operator} {} &&\n\
210 Logical 'and' operator (with short-circuit evaluation).\n\
211 @seealso{&, and}\n\
212 @end deftypefn"),
213 
214  pair_type ("'",
215  "-*- texinfo -*-\n\
216 @deftypefn {Operator} {} '\n\
217 Matrix transpose operator. For complex matrices, computes the\n\
218 complex conjugate (Hermitian) transpose.\n\
219 \n\
220 The single quote character may also be used to delimit strings, but\n\
221 it is better to use the double quote character, since that is never\n\
222 ambiguous.\n\
223 @seealso{.', transpose}\n\
224 @end deftypefn"),
225 
226  pair_type ("(",
227  "-*- texinfo -*-\n\
228 @deftypefn {Operator} {} (\n\
229 Array index or function argument delimiter.\n\
230 @end deftypefn"),
231 
232  pair_type (")",
233  "-*- texinfo -*-\n\
234 @deftypefn {Operator} {})\n\
235 Array index or function argument delimiter.\n\
236 @end deftypefn"),
237 
238  pair_type ("*",
239  "-*- texinfo -*-\n\
240 @deftypefn {Operator} {} *\n\
241 Multiplication operator.\n\
242 @seealso{.*, times}\n\
243 @end deftypefn"),
244 
245  pair_type ("**",
246  "-*- texinfo -*-\n\
247 @deftypefn {Operator} {} **\n\
248 Power operator. This may return complex results for real inputs. Use\n\
249 @code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\
250 real results when possible.\n\
251 @seealso{power, ^, .**, .^, realpow, realsqrt, cbrt, nthroot}\n\
252 @end deftypefn"),
253 
254  pair_type ("^",
255  "-*- texinfo -*-\n\
256 @deftypefn {Operator} {} ^\n\
257 Power operator. This may return complex results for real inputs. Use\n\
258 @code{realsqrt}, @code{cbrt}, @code{nthroot}, or @code{realroot} to obtain\n\
259 real results when possible.\n\
260 @seealso{power, **, .^, .**, realpow, realsqrt, cbrt, nthroot}\n\
261 @end deftypefn"),
262 
263  pair_type ("+",
264  "-*- texinfo -*-\n\
265 @deftypefn {Operator} {} +\n\
266 Addition operator.\n\
267 @seealso{plus}\n\
268 @end deftypefn"),
269 
270  pair_type ("++",
271  "-*- texinfo -*-\n\
272 @deftypefn {Operator} {} ++\n\
273 Increment operator. As in C, may be applied as a prefix or postfix\n\
274 operator.\n\
275 @seealso{--}\n\
276 @end deftypefn"),
277 
278  pair_type (",",
279  "-*- texinfo -*-\n\
280 @deftypefn {Operator} {} ,\n\
281 Array index, function argument, or command separator.\n\
282 @end deftypefn"),
283 
284  pair_type ("-",
285  "-*- texinfo -*-\n\
286 @deftypefn {Operator} {} -\n\
287 Subtraction or unary negation operator.\n\
288 @seealso{minus}\n\
289 @end deftypefn"),
290 
291  pair_type ("--",
292  "-*- texinfo -*-\n\
293 @deftypefn {Operator} {} --\n\
294 Decrement operator. As in C, may be applied as a prefix or postfix\n\
295 operator.\n\
296 @seealso{++}\n\
297 @end deftypefn"),
298 
299  pair_type (".'",
300  "-*- texinfo -*-\n\
301 @deftypefn {Operator} {} .'\n\
302 Matrix transpose operator. For complex matrices, computes the\n\
303 transpose, @emph{not} the complex conjugate transpose.\n\
304 @seealso{', transpose}\n\
305 @end deftypefn"),
306 
307  pair_type (".*",
308  "-*- texinfo -*-\n\
309 @deftypefn {Operator} {} .*\n\
310 Element by element multiplication operator.\n\
311 @seealso{*, times}\n\
312 @end deftypefn"),
313 
314  pair_type (".**",
315  "-*- texinfo -*-\n\
316 @deftypefn {Operator} {} .*\n\
317 Element by element power operator. If several complex results are possible,\n\
318 returns the one with smallest non-negative argument (angle). Use\n\
319 @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
320 real result is preferred.\n\
321 @seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}\n\
322 @end deftypefn"),
323 
324  pair_type (".^",
325  "-*- texinfo -*-\n\
326 @deftypefn {Operator} {} .^\n\
327 Element by element power operator. If several complex results are possible,\n\
328 returns the one with smallest non-negative argument (angle). Use\n\
329 @code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
330 real result is preferred.\n\
331 @seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}\n\
332 @end deftypefn"),
333 
334  pair_type ("./",
335  "-*- texinfo -*-\n\
336 @deftypefn {Operator} {} ./\n\
337 Element by element right division operator.\n\
338 @seealso{/, .\\, rdivide, mrdivide}\n\
339 @end deftypefn"),
340 
341  pair_type ("/",
342  "-*- texinfo -*-\n\
343 @deftypefn {Operator} {} /\n\
344 Right division operator.\n\
345 @seealso{./, \\, rdivide, mrdivide}\n\
346 @end deftypefn"),
347 
348  pair_type (".\\",
349  "-*- texinfo -*-\n\
350 @deftypefn {Operator} {} .\\\n\
351 Element by element left division operator.\n\
352 @seealso{\\, ./, rdivide, mrdivide}\n\
353 @end deftypefn"),
354 
355  pair_type ("\\",
356  "-*- texinfo -*-\n\
357 @deftypefn {Operator} {} \\\n\
358 Left division operator.\n\
359 @seealso{.\\, /, ldivide, mldivide}\n\
360 @end deftypefn"),
361 
362  pair_type (":",
363  "-*- texinfo -*-\n\
364 @deftypefn {Operator} {} :\n\
365 Select entire rows or columns of matrices.\n\
366 @end deftypefn"),
367 
368  pair_type (";",
369  "-*- texinfo -*-\n\
370 @deftypefn {Operator} {} ;\n\
371 Array row or command separator.\n\
372 @seealso{,}\n\
373 @end deftypefn"),
374 
375  pair_type ("<",
376  "-*- texinfo -*-\n\
377 @deftypefn {Operator} {} <\n\
378 'Less than' operator.\n\
379 @seealso{lt}\n\
380 @end deftypefn"),
381 
382  pair_type ("<=",
383  "-*- texinfo -*-\n\
384 @deftypefn {Operator} {} <=\n\
385 'Less than' or 'equals' operator.\n\
386 @seealso{le}\n\
387 @end deftypefn"),
388 
389  pair_type ("=",
390  "-*- texinfo -*-\n\
391 @deftypefn {Operator} {} =\n\
392 Assignment operator.\n\
393 @end deftypefn"),
394 
395  pair_type ("==",
396  "-*- texinfo -*-\n\
397 @deftypefn {Operator} {} ==\n\
398 Equality test operator.\n\
399 @seealso{eq}\n\
400 @end deftypefn"),
401 
402  pair_type (">",
403  "-*- texinfo -*-\n\
404 @deftypefn {Operator} {} >\n\
405 'Greater than' operator.\n\
406 @seealso{gt}\n\
407 @end deftypefn"),
408 
409  pair_type (">=",
410  "-*- texinfo -*-\n\
411 @deftypefn {Operator} {} >=\n\
412 'Greater than' or 'equals' operator.\n\
413 @seealso{ge}\n\
414 @end deftypefn"),
415 
416  pair_type ("[",
417  "-*- texinfo -*-\n\
418 @deftypefn {Operator} {} [\n\
419 Return list delimiter.\n\
420 @seealso{]}\n\
421 @end deftypefn"),
422 
423  pair_type ("]",
424  "-*- texinfo -*-\n\
425 @deftypefn {Operator} {} ]\n\
426 Return list delimiter.\n\
427 @seealso{[}\n\
428 @end deftypefn"),
429 
430  pair_type ("|",
431  "-*- texinfo -*-\n\
432 @deftypefn {Operator} {} |\n\
433 Element by element logical 'or' operator.\n\
434 @seealso{||, or}\n\
435 @end deftypefn"),
436 
437  pair_type ("||",
438  "-*- texinfo -*-\n\
439 @deftypefn {Operator} {} ||\n\
440 Logical 'or' (with short-circuit evaluation) operator.\n\
441 @seealso{|, or}\n\
442 @end deftypefn"),
443 };
444 
445 const static pair_type keywords[] =
446 {
447  pair_type ("break",
448  "-*- texinfo -*-\n\
449 @deftypefn {Keyword} {} break\n\
450 Exit the innermost enclosing do, while or for loop.\n\
451 @seealso{do, while, for, parfor, continue}\n\
452 @end deftypefn"),
453 
454  pair_type ("case",
455  "-*- texinfo -*-\n\
456 @deftypefn {Keyword} {} case @var{value}\n\
457 @deftypefnx {Keyword} {} case @{@var{value}, @dots{}@}\n\
458 A case statement in a switch. Octave cases are exclusive and do not\n\
459 fall-through as do C-language cases. A switch statement must have at least\n\
460 one case. See @code{switch} for an example.\n\
461 @seealso{switch}\n\
462 @end deftypefn"),
463 
464  pair_type ("catch",
465  "-*- texinfo -*-\n\
466 @deftypefn {Keyword} {} catch\n\
467 @deftypefnx {Keyword} {} catch @var{value}\n\
468 Begin the cleanup part of a try-catch block.\n\
469 @seealso{try}\n\
470 @end deftypefn"),
471 
472  pair_type ("continue",
473  "-*- texinfo -*-\n\
474 @deftypefn {Keyword} {} continue\n\
475 Jump to the end of the innermost enclosing do, while or for loop.\n\
476 @seealso{do, while, for, parfor, break}\n\
477 @end deftypefn"),
478 
479  pair_type ("do",
480  "-*- texinfo -*-\n\
481 @deftypefn {Keyword} {} do\n\
482 Begin a do-until loop. This differs from a do-while loop in that the\n\
483 body of the loop is executed at least once.\n\
484 \n\
485 @example\n\
486 @group\n\
487 i = 0;\n\
488 do\n\
489  i++\n\
490 until (i == 10)\n\
491 @end group\n\
492 @end example\n\
493 @seealso{for, until, while}\n\
494 @end deftypefn"),
495 
496  pair_type ("else",
497  "-*- texinfo -*-\n\
498 @deftypefn {Keyword} {} else\n\
499 Alternate action for an if block. See @code{if} for an example.\n\
500 @seealso{if}\n\
501 @end deftypefn"),
502 
503  pair_type ("elseif",
504  "-*- texinfo -*-\n\
505 @deftypefn {Keyword} {} elseif (@var{condition})\n\
506 Alternate conditional test for an if block. See @code{if} for an example.\n\
507 @seealso{if}\n\
508 @end deftypefn"),
509 
510  pair_type ("end",
511  "-*- texinfo -*-\n\
512 @deftypefn {Keyword} {} end\n\
513 Mark the end of any @code{for}, @code{parfor}, @code{if}, @code{do},\n\
514 @code{while}, @code{function}, @code{switch}, @code{try}, or\n\
515 @code{unwind_protect} block.\n\
516 @seealso{for, parfor, if, do, while, function, switch, try, unwind_protect}\n\
517 @end deftypefn"),
518 
519  pair_type ("end_try_catch",
520  "-*- texinfo -*-\n\
521 @deftypefn {Keyword} {} end_try_catch\n\
522 Mark the end of an @code{try-catch} block.\n\
523 @seealso{try, catch}\n\
524 @end deftypefn"),
525 
526  pair_type ("end_unwind_protect",
527  "-*- texinfo -*-\n\
528 @deftypefn {Keyword} {} end_unwind_protect\n\
529 Mark the end of an unwind_protect block.\n\
530 @seealso{unwind_protect}\n\
531 @end deftypefn"),
532 
533  pair_type ("endfor",
534  "-*- texinfo -*-\n\
535 @deftypefn {Keyword} {} endfor\n\
536 Mark the end of a for loop. See @code{for} for an example.\n\
537 @seealso{for}\n\
538 @end deftypefn"),
539 
540  pair_type ("endfunction",
541  "-*- texinfo -*-\n\
542 @deftypefn {Keyword} {} endfunction\n\
543 Mark the end of a function.\n\
544 @seealso{function}\n\
545 @end deftypefn"),
546 
547  pair_type ("endif",
548  "-*- texinfo -*-\n\
549 @deftypefn {Keyword} {} endif\n\
550 Mark the end of an if block. See @code{if} for an example.\n\
551 @seealso{if}\n\
552 @end deftypefn"),
553 
554  pair_type ("endparfor",
555  "-*- texinfo -*-\n\
556 @deftypefn {Keyword} {} endparfor\n\
557 Mark the end of a parfor loop. See @code{parfor} for an example.\n\
558 @seealso{parfor}\n\
559 @end deftypefn"),
560 
561  pair_type ("endswitch",
562  "-*- texinfo -*-\n\
563 @deftypefn {Keyword} {} endswitch\n\
564 Mark the end of a switch block. See @code{switch} for an example.\n\
565 @seealso{switch}\n\
566 @end deftypefn"),
567 
568  pair_type ("endwhile",
569  "-*- texinfo -*-\n\
570 @deftypefn {Keyword} {} endwhile\n\
571 Mark the end of a while loop. See @code{while} for an example.\n\
572 @seealso{do, while}\n\
573 @end deftypefn"),
574 
575  pair_type ("for",
576  "-*- texinfo -*-\n\
577 @deftypefn {Keyword} {} for @var{i} = @var{range}\n\
578 Begin a for loop.\n\
579 \n\
580 @example\n\
581 @group\n\
582 for i = 1:10\n\
583  i\n\
584 endfor\n\
585 @end group\n\
586 @end example\n\
587 @seealso{do, parfor, while}\n\
588 @end deftypefn"),
589 
590  pair_type ("function",
591  "-*- texinfo -*-\n\
592 @deftypefn {Keyword} {} function @var{outputs} = function (@var{input}, @dots{})\n\
593 @deftypefnx {Keyword} {} function {} function (@var{input}, @dots{})\n\
594 @deftypefnx {Keyword} {} function @var{outputs} = function\n\
595 Begin a function body with @var{outputs} as results and @var{inputs} as\n\
596 parameters.\n\
597 @seealso{return}\n\
598 @end deftypefn"),
599 
600  pair_type ("global",
601  "-*- texinfo -*-\n\
602 @deftypefn {Keyword} {} global @var{var}\n\
603 Declare variables to have global scope.\n\
604 \n\
605 @example\n\
606 @group\n\
607 global @var{x};\n\
608 if (isempty (@var{x}))\n\
609  x = 1;\n\
610 endif\n\
611 @end group\n\
612 @end example\n\
613 @seealso{persistent}\n\
614 @end deftypefn"),
615 
616  pair_type ("if",
617  "-*- texinfo -*-\n\
618 @deftypefn {Keyword} {} if (@var{cond}) @dots{} endif\n\
619 @deftypefnx {Keyword} {} if (@var{cond}) @dots{} else @dots{} endif\n\
620 @deftypefnx {Keyword} {} if (@var{cond}) @dots{} elseif (@var{cond}) @dots{} endif\n\
621 @deftypefnx {Keyword} {} if (@var{cond}) @dots{} elseif (@var{cond}) @dots{} else @dots{} endif\n\
622 Begin an if block.\n\
623 \n\
624 @example\n\
625 @group\n\
626 x = 1;\n\
627 if (x == 1)\n\
628  disp (\"one\");\n\
629 elseif (x == 2)\n\
630  disp (\"two\");\n\
631 else\n\
632  disp (\"not one or two\");\n\
633 endif\n\
634 @end group\n\
635 @end example\n\
636 @seealso{switch}\n\
637 @end deftypefn"),
638 
639  pair_type ("otherwise",
640  "-*- texinfo -*-\n\
641 @deftypefn {Keyword} {} otherwise\n\
642 The default statement in a switch block (similar to else in an if block).\n\
643 @seealso{switch}\n\
644 @end deftypefn"),
645 
646  pair_type ("parfor",
647  "-*- texinfo -*-\n\
648 @deftypefn {Keyword} {} parfor @var{i} = @var{range}\n\
649 @deftypefnx {Keyword} {} parfor (@var{i} = @var{range}, @var{maxproc})\n\
650 Begin a for loop that may execute in parallel.\n\
651 \n\
652 @example\n\
653 @group\n\
654 parfor i = 1:10\n\
655  i\n\
656 endparfor\n\
657 @end group\n\
658 @end example\n\
659 @seealso{for, do, while}\n\
660 @end deftypefn"),
661 
662  pair_type ("persistent",
663  "-*- texinfo -*-\n\
664 @deftypefn {Keyword} {} persistent @var{var}\n\
665 Declare variables as persistent. A variable that has been declared\n\
666 persistent within a function will retain its contents in memory between\n\
667 subsequent calls to the same function. The difference between persistent\n\
668 variables and global variables is that persistent variables are local in\n\
669 scope to a particular function and are not visible elsewhere.\n\
670 @seealso{global}\n\
671 @end deftypefn"),
672 
673  pair_type ("return",
674  "-*- texinfo -*-\n\
675 @deftypefn {Keyword} {} return\n\
676 Return from a function.\n\
677 @seealso{function}\n\
678 @end deftypefn"),
679 
680  pair_type ("static",
681  "-*- texinfo -*-\n\
682 @deftypefn {Keyword} {} static\n\
683 This statement has been deprecated in favor of @code{persistent}.\n\
684 @seealso{persistent}\n\
685 @end deftypefn"),
686 
687  pair_type ("switch",
688  "-*- texinfo -*-\n\
689 @deftypefn {Keyword} {} switch @var{statement}\n\
690 Begin a switch block.\n\
691 \n\
692 @example\n\
693 @group\n\
694 yesno = \"yes\"\n\
695 \n\
696 switch yesno\n\
697  case @{\"Yes\" \"yes\" \"YES\" \"y\" \"Y\"@}\n\
698  value = 1;\n\
699  case @{\"No\" \"no\" \"NO\" \"n\" \"N\"@}\n\
700  value = 0;\n\
701  otherwise\n\
702  error (\"invalid value\");\n\
703 endswitch\n\
704 @end group\n\
705 @end example\n\
706 @seealso{if, case, otherwise}\n\
707 @end deftypefn"),
708 
709  pair_type ("try",
710  "-*- texinfo -*-\n\
711 @deftypefn {Keyword} {} try\n\
712 Begin a try-catch block.\n\
713 \n\
714 If an error occurs within a try block, then the catch code will be run and\n\
715 execution will proceed after the catch block (though it is often\n\
716 recommended to use the lasterr function to re-throw the error after cleanup\n\
717 is completed).\n\
718 @seealso{catch, unwind_protect}\n\
719 @end deftypefn"),
720 
721  pair_type ("until",
722  "-*- texinfo -*-\n\
723 @deftypefn {Keyword} {} until (@var{cond})\n\
724 End a do-until loop. See @code{do} for an example.\n\
725 @seealso{do}\n\
726 @end deftypefn"),
727 
728  pair_type ("unwind_protect",
729  "-*- texinfo -*-\n\
730 @deftypefn {Keyword} {} unwind_protect\n\
731 Begin an unwind_protect block.\n\
732 \n\
733 If an error occurs within the first part of an unwind_protect block\n\
734 the commands within the unwind_protect_cleanup block are executed before\n\
735 the error is thrown. If an error is not thrown, then the\n\
736 unwind_protect_cleanup block is still executed (in other words, the\n\
737 unwind_protect_cleanup will be run with or without an error in the\n\
738 unwind_protect block).\n\
739 @seealso{unwind_protect_cleanup, try}\n\
740 @end deftypefn"),
741 
742  pair_type ("unwind_protect_cleanup",
743  "-*- texinfo -*-\n\
744 @deftypefn {Keyword} {} unwind_protect_cleanup\n\
745 Begin the cleanup section of an unwind_protect block.\n\
746 @seealso{unwind_protect}\n\
747 @end deftypefn"),
748 
749  pair_type ("varargin",
750  "-*- texinfo -*-\n\
751 @deftypefn {Keyword} {} varargin\n\
752 Pass an arbitrary number of arguments into a function.\n\
753 @seealso{varargout, nargin, isargout, nargout, nthargout}\n\
754 @end deftypefn"),
755 
756  pair_type ("varargout",
757  "-*- texinfo -*-\n\
758 @deftypefn {Keyword} {} varargout\n\
759 Pass an arbitrary number of arguments out of a function.\n\
760 @seealso{varargin, nargin, isargout, nargout, nthargout}\n\
761 @end deftypefn"),
762 
763  pair_type ("while",
764  "-*- texinfo -*-\n\
765 @deftypefn {Keyword} {} while\n\
766 Begin a while loop.\n\
767 \n\
768 @example\n\
769 @group\n\
770 i = 0;\n\
771 while (i < 10)\n\
772  i++\n\
773 endwhile\n\
774 @end group\n\
775 @end example\n\
776 @seealso{do, endwhile, for, until}\n\
777 @end deftypefn"),
778 };
779 
780 // Return a copy of the operator or keyword names.
781 static string_vector
782 names (const map_type& lst)
783 {
784  string_vector retval (lst.size ());
785  int j = 0;
786  for (map_iter iter = lst.begin (); iter != lst.end (); iter ++)
787  retval[j++] = iter->first;
788  return retval;
789 }
790 
791 const static map_type operators_map (operators, operators + size (operators));
792 const static map_type keywords_map (keywords, keywords + size (keywords));
794 
795 // FIXME: It's not likely that this does the right thing now.
796 
799 {
800  const int key_len = keyword_names.length ();
801 
803  const int bif_len = bif.length ();
804 
806  const int cfl_len = cfl.length ();
807 
809  const int lcl_len = lcl.length ();
810 
811  const string_vector ffl = load_path::fcn_names ();
812  const int ffl_len = ffl.length ();
813 
814  const string_vector afl = autoloaded_functions ();
815  const int afl_len = afl.length ();
816 
817  const int total_len
818  = key_len + bif_len + cfl_len + lcl_len + ffl_len + afl_len;
819 
820  string_vector list (total_len);
821 
822  // Put all the symbols in one big list.
823 
824  int j = 0;
825  int i = 0;
826  for (i = 0; i < key_len; i++)
827  list[j++] = keyword_names[i];
828 
829  for (i = 0; i < bif_len; i++)
830  list[j++] = bif[i];
831 
832  for (i = 0; i < cfl_len; i++)
833  list[j++] = cfl[i];
834 
835  for (i = 0; i < lcl_len; i++)
836  list[j++] = lcl[i];
837 
838  for (i = 0; i < ffl_len; i++)
839  list[j++] = ffl[i];
840 
841  for (i = 0; i < afl_len; i++)
842  list[j++] = afl[i];
843 
844  return list;
845 }
846 
847 static bool
848 looks_like_html (const std::string& msg)
849 {
850  const size_t p1 = msg.find ('\n');
851  std::string t = msg.substr (0, p1);
852  // FIXME: this comparison should be case-insensitive
853  const size_t p2 = t.find ("<html");
854 
855  return (p2 != std::string::npos);
856 }
857 
858 static bool
859 looks_like_texinfo (const std::string& msg, size_t& p1)
860 {
861  p1 = msg.find ('\n');
862 
863  std::string t = msg.substr (0, p1);
864 
865  if (p1 == std::string::npos)
866  p1 = 0;
867 
868  size_t p2 = t.find ("-*- texinfo -*-");
869 
870  return (p2 != std::string::npos);
871 }
872 
873 static bool
874 raw_help_from_symbol_table (const std::string& nm, std::string& h,
875  std::string& w, bool& symbol_found)
876 {
877  bool retval = false;
878 
880 
881  if (val.is_defined ())
882  {
883  octave_function *fcn = val.function_value ();
884 
885  if (fcn)
886  {
887  symbol_found = true;
888 
889  h = fcn->doc_string ();
890 
891  retval = true;
892 
893  w = fcn->fcn_file_name ();
894 
895  if (w.empty ())
896  w = fcn->is_user_function ()
897  ? "command-line function" : "built-in function";
898  }
899  }
900 
901  return retval;
902 }
903 
904 static bool
905 raw_help_from_file (const std::string& nm, std::string& h,
906  std::string& file, bool& symbol_found)
907 {
908  bool retval = false;
909 
910  h = get_help_from_file (nm, symbol_found, file);
911 
912  if (h.length () > 0)
913  retval = true;
914 
915  return retval;
916 }
917 
918 static bool
919 raw_help_from_map (const std::string& nm, std::string& h,
920  const map_type& map, bool& symbol_found)
921 {
922  map_iter idx = map.find (nm);
923  symbol_found = (idx != map.end ());
924  h = (symbol_found) ? idx->second : "";
925  return symbol_found;
926 }
927 
928 std::string
929 raw_help (const std::string& nm, bool& symbol_found)
930 {
931  std::string h;
932  std::string w;
933  std::string f;
934 
935  bool found;
936 
937  found = raw_help_from_symbol_table (nm, h, w, symbol_found);
938  if (! found && ! error_state)
939  {
940  found = raw_help_from_file (nm, h, f, symbol_found);
941  if (! found && ! error_state)
942  {
943  found = raw_help_from_map (nm, h, operators_map, symbol_found);
944  if (! found && ! error_state)
945  {
946  raw_help_from_map (nm, h, keywords_map, symbol_found);
947  }
948  }
949  }
950 
951  return h;
952 }
953 
954 DEFUN (built_in_docstrings_file, args, nargout,
955  "-*- texinfo -*-\n\
956 @deftypefn {Built-in Function} {@var{val} =} built_in_docstrings_file ()\n\
957 @deftypefnx {Built-in Function} {@var{old_val} =} built_in_docstrings_file (@var{new_val})\n\
958 @deftypefnx {Built-in Function} {} built_in_docstrings_file (@var{new_val}, \"local\")\n\
959 Query or set the internal variable that specifies the name of the\n\
960 file containing docstrings for built-in Octave functions.\n\
961 \n\
962 The default value is\n\
963 @file{@var{octave-home}/share/octave/@var{version}/etc/built-in-docstrings},\n\
964 in which @var{octave-home} is the root directory of the Octave installation,\n\
965 and @var{version} is the Octave version number. The default value may be\n\
966 overridden by the environment variable\n\
967 @w{@env{OCTAVE_BUILT_IN_DOCSTRINGS_FILE}}, or the command line argument\n\
968 @option{--built-in-docstrings-file FNAME}.\n\
969 \n\
970 Note: This variable is only used when Octave is initializing itself.\n\
971 Modifying it during a running session of Octave will have no effect.\n\
972 @end deftypefn")
973 {
974  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (built_in_docstrings_file);
975 }
976 
977 void
979 {
980  std::string fname = Vbuilt_in_docstrings_file;
981 
982  std::ifstream file (fname.c_str (), std::ios::in | std::ios::binary);
983 
984  if (file)
985  {
986  // Ignore header;
987  file.ignore (1000, 0x1d);
988 
989  if (file.gcount () == 1000)
990  {
991  // We use std::cerr here instead of calling Octave's warning
992  // function because install_built_in_docstrings is called
993  // before the interpreter is initialized, so warning messages
994  // won't work properly.
995 
996  std::cerr << "warning: is builtin-docstrings file corrupted?"
997  << std::endl;
998  return;
999  }
1000 
1001  // FIXME: eliminate fixed buffer size.
1002  size_t bufsize = 100000;
1003 
1004  OCTAVE_LOCAL_BUFFER (char, buf, bufsize);
1005 
1006  while (! file.eof ())
1007  {
1008  file.getline (buf, bufsize, 0x1d);
1009 
1010  std::string tmp (buf);
1011 
1012  size_t pos = tmp.find ('\n');
1013 
1014  std::string fcn = tmp.substr (0, pos);
1015 
1017 
1018  if (ov.is_defined ())
1019  {
1020  octave_function *fp = ov.function_value ();
1021 
1022  if (fp)
1023  {
1024  tmp = tmp.substr (pos+1);
1025 
1026  // Strip @c FILENAME which is part of current DOCSTRINGS
1027  // syntax. This may disappear if a specific format for
1028  // docstring files is developed.
1029  while (tmp.length () > 2 && tmp[0] == '@' && tmp[1] == 'c')
1030  {
1031  pos = tmp.find ('\n');
1032  tmp = tmp.substr (pos+1);
1033  }
1034 
1035  fp->document (tmp);
1036  }
1037  }
1038  }
1039  }
1040  else
1041  {
1042  // See note above about using std::cerr instead of warning.
1043 
1044  std::cerr << "warning: docstring file '" << fname << "' not found"
1045  << std::endl;
1046  }
1047 
1048 }
1049 
1050 static void
1051 do_get_help_text (const std::string& name, std::string& text,
1052  std::string& format)
1053 {
1054  bool symbol_found = false;
1055  text = raw_help (name, symbol_found);
1056 
1057  format = "Not found";
1058  if (symbol_found)
1059  {
1060  size_t idx = -1;
1061  if (text.empty ())
1062  {
1063  format = "Not documented";
1064  }
1065  else if (looks_like_texinfo (text, idx))
1066  {
1067  format = "texinfo";
1068  text.erase (0, idx);
1069  }
1070  else if (looks_like_html (text))
1071  {
1072  format = "html";
1073  }
1074  else
1075  {
1076  format = "plain text";
1077  }
1078  }
1079 }
1080 
1081 DEFUN (get_help_text, args, , "-*- texinfo -*-\n\
1082 @deftypefn {Built-in Function} {[@var{text}, @var{format}] =} get_help_text (@var{name})\n\
1083 Return the raw help text of function @var{name}.\n\
1084 \n\
1085 The raw help text is returned in @var{text} and the format in @var{format}\n\
1086 The format is a string which is one of @qcode{\"texinfo\"},\n\
1087 @qcode{\"html\"}, or @qcode{\"plain text\"}.\n\
1088 @seealso{get_help_text_from_file}\n\
1089 @end deftypefn")
1090 {
1091  octave_value_list retval;
1092 
1093  if (args.length () == 1)
1094  {
1095  const std::string name = args(0).string_value ();
1096 
1097  if (! error_state)
1098  {
1099  std::string text;
1100  std::string format;
1101 
1102  do_get_help_text (name, text, format);
1103 
1104  retval(1) = format;
1105  retval(0) = text;
1106  }
1107  else
1108  error ("get_help_text: invalid input");
1109  }
1110  else
1111  print_usage ();
1112 
1113  return retval;
1114 }
1115 
1116 static void
1117 do_get_help_text_from_file (const std::string& fname, std::string& text,
1118  std::string& format)
1119 {
1120  bool symbol_found = false;
1121 
1122  std::string f;
1123 
1124  raw_help_from_file (fname, text, f, symbol_found);
1125 
1126  format = "Not found";
1127  if (symbol_found)
1128  {
1129  size_t idx = -1;
1130  if (text.empty ())
1131  {
1132  format = "Not documented";
1133  }
1134  else if (looks_like_texinfo (text, idx))
1135  {
1136  format = "texinfo";
1137  text.erase (0, idx);
1138  }
1139  else if (looks_like_html (text))
1140  {
1141  format = "html";
1142  }
1143  else
1144  {
1145  format = "plain text";
1146  }
1147  }
1148 }
1149 
1150 DEFUN (get_help_text_from_file, args, ,
1151  "-*- texinfo -*-\n\
1152 @deftypefn {Built-in Function} {[@var{text}, @var{format}] =} get_help_text_from_file (@var{fname})\n\
1153 Return the raw help text from the file @var{fname}.\n\
1154 \n\
1155 The raw help text is returned in @var{text} and the format in @var{format}\n\
1156 The format is a string which is one of @qcode{\"texinfo\"},\n\
1157 @qcode{\"html\"}, or @qcode{\"plain text\"}.\n\
1158 @seealso{get_help_text}\n\
1159 @end deftypefn")
1160 {
1161  octave_value_list retval;
1162 
1163  if (args.length () == 1)
1164  {
1165  const std::string fname = args(0).string_value ();
1166 
1167  if (! error_state)
1168  {
1169  std::string text;
1170  std::string format;
1171 
1172  do_get_help_text_from_file (fname, text, format);
1173 
1174  retval(1) = format;
1175  retval(0) = text;
1176  }
1177  else
1178  error ("get_help_text_from_file: invalid input");
1179  }
1180  else
1181  print_usage ();
1182 
1183  return retval;
1184 }
1185 
1186 // Return a cell array of strings containing the names of all
1187 // operators.
1188 
1189 DEFUN (__operators__, , ,
1190  "-*- texinfo -*-\n\
1191 @deftypefn {Function File} {} __operators__ ()\n\
1192 Undocumented internal function.\n\
1193 @end deftypefn")
1194 {
1195  return octave_value (Cell (names (operators_map)));
1196 }
1197 
1198 // Return a cell array of strings containing the names of all
1199 // keywords.
1200 
1201 DEFUN (__keywords__, , ,
1202  "-*- texinfo -*-\n\
1203 @deftypefn {Function File} {} __keywords__ ()\n\
1204 Undocumented internal function.\n\
1205 @end deftypefn")
1206 {
1207  return octave_value (Cell (names (keywords_map)));
1208 }
1209 
1210 // Return a cell array of strings containing the names of all builtin
1211 // functions.
1212 
1213 DEFUN (__builtins__, , ,
1214  "-*- texinfo -*-\n\
1215 @deftypefn {Function File} {} __builtins__ ()\n\
1216 Undocumented internal function.\n\
1217 @end deftypefn")
1218 {
1220 
1221  return octave_value (Cell (bif));
1222 }
1223 
1224 static std::string
1225 do_which (const std::string& name, std::string& type)
1226 {
1227  std::string file;
1228 
1229  type = std::string ();
1230 
1232 
1233  if (name.find_first_of ('.') == std::string::npos)
1234  {
1235  if (val.is_defined ())
1236  {
1237  octave_function *fcn = val.function_value ();
1238 
1239  if (fcn)
1240  {
1241  file = fcn->fcn_file_name ();
1242 
1243  if (file.empty ())
1244  {
1245  if (fcn->is_user_function ())
1246  type = "command-line function";
1247  else
1248  {
1249  file = fcn->src_file_name ();
1250  type = "built-in function";
1251  }
1252  }
1253  else
1254  type = val.is_user_script ()
1255  ? std::string ("script") : std::string ("function");
1256  }
1257  }
1258  else
1259  {
1260  // We might find a file that contains only a doc string.
1261 
1262  file = load_path::find_fcn_file (name);
1263  }
1264  }
1265  else
1266  {
1267  // File query.
1268 
1269  // For compatibility: "file." queries "file".
1270  if (name.size () > 1 && name[name.size () - 1] == '.')
1271  file = load_path::find_file (name.substr (0, name.size () - 1));
1272  else
1273  file = load_path::find_file (name);
1274 
1275  file = octave_env::make_absolute (file);
1276  }
1277 
1278 
1279  return file;
1280 }
1281 
1282 std::string
1283 do_which (const std::string& name)
1284 {
1285  std::string retval;
1286 
1287  std::string type;
1288 
1289  retval = do_which (name, type);
1290 
1291  return retval;
1292 }
1293 
1294 DEFUN (__which__, args, ,
1295  "-*- texinfo -*-\n\
1296 @deftypefn {Built-in Function} {} __which__ (@var{name}, @dots{})\n\
1297 Undocumented internal function.\n\
1298 @end deftypefn")
1299 {
1300  octave_value retval;
1301 
1302  string_vector argv = args.make_argv ("which");
1303 
1304  if (! error_state)
1305  {
1306  int argc = argv.length ();
1307 
1308  if (argc > 1)
1309  {
1310  octave_map m (dim_vector (1, argc-1));
1311 
1312  Cell names (1, argc-1);
1313  Cell files (1, argc-1);
1314  Cell types (1, argc-1);
1315 
1316  for (int i = 1; i < argc; i++)
1317  {
1318  std::string name = argv[i];
1319 
1320  std::string type;
1321 
1322  std::string file = do_which (name, type);
1323 
1324  names(i-1) = name;
1325  files(i-1) = file;
1326  types(i-1) = type;
1327  }
1328 
1329  m.assign ("name", names);
1330  m.assign ("file", files);
1331  m.assign ("type", types);
1332 
1333  retval = m;
1334  }
1335  else
1336  print_usage ();
1337  }
1338 
1339  return retval;
1340 }
1341 
1342 // FIXME: Are we sure this function always does the right thing?
1343 inline bool
1344 file_is_in_dir (const std::string filename, const std::string dir)
1345 {
1346  if (filename.find (dir) == 0)
1347  {
1348  const int dir_len = dir.size ();
1349  const int filename_len = filename.size ();
1350  const int max_allowed_seps = file_ops::is_dir_sep (dir[dir_len-1]) ? 0
1351  : 1;
1352 
1353  int num_seps = 0;
1354  for (int i = dir_len; i < filename_len; i++)
1355  if (file_ops::is_dir_sep (filename[i]))
1356  num_seps ++;
1357 
1358  return (num_seps <= max_allowed_seps);
1359  }
1360  else
1361  return false;
1362 }
1363 
1364 // Return a cell array of strings containing the names of all
1365 // functions available in DIRECTORY. If no directory is given, search
1366 // the current path.
1367 
1368 DEFUN (__list_functions__, args, ,
1369  "-*- texinfo -*-\n\
1370 @deftypefn {Function File} {@var{retval} =} __list_functions__ ()\n\
1371 @deftypefnx {Function File} {@var{retval} =} __list_functions__ (@var{directory})\n\
1372 Undocumented internal function.\n\
1373 @end deftypefn")
1374 {
1375  octave_value retval;
1376 
1377  // Get list of functions
1380 
1381  if (args.length () == 0)
1382  retval = Cell (ffl.append (afl));
1383  else if (args(0).is_string ())
1384  {
1385  std::string dir = args(0).string_value ();
1386 
1387  string_vector fl = load_path::files (dir, true);
1388 
1389  if (! error_state)
1390  {
1391  // Return a sorted list with unique entries (in case of
1392  // .m and .oct versions of the same function in a given
1393  // directory, for example).
1394  fl.sort (true);
1395 
1396  retval = Cell (fl);
1397  }
1398  }
1399  else
1400  error ("__list_functions__: DIRECTORY argument must be a string");
1401 
1402  return retval;
1403 }
1404 
1405 DEFUN (doc_cache_file, args, nargout,
1406  "-*- texinfo -*-\n\
1407 @deftypefn {Built-in Function} {@var{val} =} doc_cache_file ()\n\
1408 @deftypefnx {Built-in Function} {@var{old_val} =} doc_cache_file (@var{new_val})\n\
1409 @deftypefnx {Built-in Function} {} doc_cache_file (@var{new_val}, \"local\")\n\
1410 Query or set the internal variable that specifies the name of the\n\
1411 Octave documentation cache file.\n\
1412 \n\
1413 A cache file significantly improves the performance of the @code{lookfor}\n\
1414 command. The default value is\n\
1415 @file{@var{octave-home}/share/octave/@var{version}/etc/doc-cache},\n\
1416 in which @var{octave-home} is the root directory of the Octave installation,\n\
1417 and @var{version} is the Octave version number.\n\
1418 The default value may be overridden by the environment variable\n\
1419 @w{@env{OCTAVE_DOC_CACHE_FILE}}, or the command line argument\n\
1420 @option{--doc-cache-file FNAME}.\n\
1421 \n\
1422 When called from inside a function with the @qcode{\"local\"} option, the\n\
1423 variable is changed locally for the function and any subroutines it calls.\n\
1424 The original variable value is restored when exiting the function.\n\
1425 @seealso{doc_cache_create, lookfor, info_program, doc, help, makeinfo_program}\n\
1426 @seealso{lookfor}\n\
1427 @end deftypefn")
1428 {
1429  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (doc_cache_file);
1430 }
1431 
1432 DEFUN (texi_macros_file, args, nargout,
1433  "-*- texinfo -*-\n\
1434 @deftypefn {Built-in Function} {@var{val} =} texi_macros_file ()\n\
1435 @deftypefnx {Built-in Function} {@var{old_val} =} texi_macros_file (@var{new_val})\n\
1436 @deftypefnx {Built-in Function} {} texi_macros_file (@var{new_val}, \"local\")\n\
1437 Query or set the internal variable that specifies the name of the\n\
1438 file containing Texinfo macros that are prepended to documentation strings\n\
1439 before they are passed to makeinfo.\n\
1440 \n\
1441 The default value is\n\
1442 @file{@var{octave-home}/share/octave/@var{version}/etc/macros.texi},\n\
1443 in which @var{octave-home} is the root directory of the Octave installation,\n\
1444 and @var{version} is the Octave version number.\n\
1445 The default value may be overridden by the environment variable\n\
1446 @w{@env{OCTAVE_TEXI_MACROS_FILE}}, or the command line argument\n\
1447 @option{--texi-macros-file FNAME}.\n\
1448 \n\
1449 When called from inside a function with the @qcode{\"local\"} option, the\n\
1450 variable is changed locally for the function and any subroutines it calls.\n\
1451 The original variable value is restored when exiting the function.\n\
1452 @seealso{makeinfo_program}\n\
1453 @end deftypefn")
1454 {
1455  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (texi_macros_file);
1456 }
1457 
1458 DEFUN (info_file, args, nargout,
1459  "-*- texinfo -*-\n\
1460 @deftypefn {Built-in Function} {@var{val} =} info_file ()\n\
1461 @deftypefnx {Built-in Function} {@var{old_val} =} info_file (@var{new_val})\n\
1462 @deftypefnx {Built-in Function} {} info_file (@var{new_val}, \"local\")\n\
1463 Query or set the internal variable that specifies the name of the\n\
1464 Octave info file.\n\
1465 \n\
1466 The default value is\n\
1467 @file{@var{octave-home}/info/octave.info}, in\n\
1468 which @var{octave-home} is the root directory of the Octave installation.\n\
1469 The default value may be overridden by the environment variable\n\
1470 @w{@env{OCTAVE_INFO_FILE}}, or the command line argument\n\
1471 @option{--info-file FNAME}.\n\
1472 \n\
1473 When called from inside a function with the @qcode{\"local\"} option, the\n\
1474 variable is changed locally for the function and any subroutines it calls.\n\
1475 The original variable value is restored when exiting the function.\n\
1476 @seealso{info_program, doc, help, makeinfo_program}\n\
1477 @end deftypefn")
1478 {
1479  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (info_file);
1480 }
1481 
1482 DEFUN (info_program, args, nargout,
1483  "-*- texinfo -*-\n\
1484 @deftypefn {Built-in Function} {@var{val} =} info_program ()\n\
1485 @deftypefnx {Built-in Function} {@var{old_val} =} info_program (@var{new_val})\n\
1486 @deftypefnx {Built-in Function} {} info_program (@var{new_val}, \"local\")\n\
1487 Query or set the internal variable that specifies the name of the\n\
1488 info program to run.\n\
1489 \n\
1490 The default value is\n\
1491 @file{@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info}\n\
1492 in which @var{octave-home} is the root directory of the Octave installation,\n\
1493 @var{version} is the Octave version number, and @var{arch} is the system\n\
1494 type (for example, @code{i686-pc-linux-gnu}). The default value may be\n\
1495 overridden by the environment variable\n\
1496 @w{@env{OCTAVE_INFO_PROGRAM}}, or the command line argument\n\
1497 @option{--info-program NAME}.\n\
1498 \n\
1499 When called from inside a function with the @qcode{\"local\"} option, the\n\
1500 variable is changed locally for the function and any subroutines it calls.\n\
1501 The original variable value is restored when exiting the function.\n\
1502 @seealso{info_file, doc, help, makeinfo_program}\n\
1503 @end deftypefn")
1504 {
1505  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (info_program);
1506 }
1507 
1508 DEFUN (makeinfo_program, args, nargout,
1509  "-*- texinfo -*-\n\
1510 @deftypefn {Built-in Function} {@var{val} =} makeinfo_program ()\n\
1511 @deftypefnx {Built-in Function} {@var{old_val} =} makeinfo_program (@var{new_val})\n\
1512 @deftypefnx {Built-in Function} {} makeinfo_program (@var{new_val}, \"local\")\n\
1513 Query or set the internal variable that specifies the name of the\n\
1514 program that Octave runs to format help text containing\n\
1515 Texinfo markup commands.\n\
1516 \n\
1517 The default value is @code{makeinfo}.\n\
1518 \n\
1519 When called from inside a function with the @qcode{\"local\"} option, the\n\
1520 variable is changed locally for the function and any subroutines it calls.\n\
1521 The original variable value is restored when exiting the function.\n\
1522 @seealso{texi_macros_file, info_file, info_program, doc, help}\n\
1523 @end deftypefn")
1524 {
1525  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (makeinfo_program);
1526 }
1527 
1528 DEFUN (suppress_verbose_help_message, args, nargout,
1529  "-*- texinfo -*-\n\
1530 @deftypefn {Built-in Function} {@var{val} =} suppress_verbose_help_message ()\n\
1531 @deftypefnx {Built-in Function} {@var{old_val} =} suppress_verbose_help_message (@var{new_val})\n\
1532 @deftypefnx {Built-in Function} {} suppress_verbose_help_message (@var{new_val}, \"local\")\n\
1533 Query or set the internal variable that controls whether Octave\n\
1534 will add additional help information to the end of the output from\n\
1535 the @code{help} command and usage messages for built-in commands.\n\
1536 \n\
1537 When called from inside a function with the @qcode{\"local\"} option, the\n\
1538 variable is changed locally for the function and any subroutines it calls.\n\
1539 The original variable value is restored when exiting the function.\n\
1540 @end deftypefn")
1541 {
1542  return SET_INTERNAL_VARIABLE (suppress_verbose_help_message);
1543 }
static std::string do_which(const std::string &name, std::string &type)
Definition: help.cc:1225
Definition: Cell.h:35
void document(const std::string &ds)
Definition: ov-fcn.h:171
std::string Vinfo_file
Definition: help.cc:82
static std::list< std::string > cmdline_function_names(void)
Definition: symtab.h:2139
void assign(const std::string &k, const Cell &val)
Definition: oct-map.h:348
std::string Vinfo_program
Definition: help.cc:86
OCTINTERP_API void print_usage(void)
Definition: defun.cc:51
map_type::const_iterator map_iter
Definition: help.cc:99
bool is_defined(void) const
Definition: ov.h:520
std::string doc_string(void) const
Definition: ov-fcn.h:173
bool file_is_in_dir(const std::string filename, const std::string dir)
Definition: help.cc:1344
static std::string find_file(const std::string &file)
Definition: load-path.h:197
static bool raw_help_from_file(const std::string &nm, std::string &h, std::string &file, bool &symbol_found)
Definition: help.cc:905
std::map< std::string, std::string > map_type
Definition: help.cc:97
#define DEFUN(name, args_name, nargout_name, doc)
Definition: defun.h:44
void error(const char *fmt,...)
Definition: error.cc:476
string_vector autoloaded_functions(void)
Definition: oct-parse.cc:8172
std::string raw_help(const std::string &nm, bool &symbol_found)
Definition: help.cc:929
#define SET_INTERNAL_VARIABLE(NM)
Definition: variables.h:120
static octave_value find_built_in_function(const std::string &name)
Definition: symtab.h:1521
octave_value map(octave_base_value::unary_mapper_t umap) const
Definition: ov.h:1226
static string_vector names(const map_type &lst)
Definition: help.cc:782
std::string Vbuilt_in_docstrings_file
Definition: defaults.cc:98
virtual std::string src_file_name(void) const
Definition: ov-fcn.h:64
std::string get_help_from_file(const std::string &nm, bool &symbol_found, std::string &full_file)
Definition: oct-parse.cc:8107
map_type::value_type pair_type
Definition: help.cc:98
std::string Vdoc_cache_file
Definition: help.cc:73
static bool looks_like_html(const std::string &msg)
Definition: help.cc:848
static string_vector files(const std::string &dir, bool omit_exts=false)
Definition: load-path.h:238
static octave_value find_function(const std::string &name, const octave_value_list &args=octave_value_list(), bool local_funcs=true)
Definition: symtab.cc:1271
static std::string Vmakeinfo_program
Definition: help.cc:89
static string_vector fcn_names(void)
Definition: load-path.h:244
static void do_get_help_text_from_file(const std::string &fname, std::string &text, std::string &format)
Definition: help.cc:1117
static void do_get_help_text(const std::string &name, std::string &text, std::string &format)
Definition: help.cc:1051
F77_RET_T const double const double * f
std::string Vtexi_macros_file
Definition: help.cc:78
static const pair_type operators[]
Definition: help.cc:108
static std::string make_absolute(const std::string &s, const std::string &dot_path=get_current_directory())
Definition: oct-env.cc:132
std::complex< double > w(std::complex< double > z, double relerr=0)
int error_state
Definition: error.cc:101
string_vector & append(const std::string &s)
Definition: str-vec.cc:140
static const string_vector keyword_names
Definition: help.cc:793
bool is_user_script(void) const
Definition: ov.h:698
string_vector & sort(bool make_uniq=false)
Definition: str-vec.cc:107
virtual bool is_user_function(void) const
Definition: ov-base.h:441
size_t size(T const (&)[z])
Definition: help.cc:103
static const map_type keywords_map(keywords, keywords+size(keywords))
#define SET_NONEMPTY_INTERNAL_STRING_VARIABLE(NM)
Definition: variables.h:123
static bool raw_help_from_symbol_table(const std::string &nm, std::string &h, std::string &w, bool &symbol_found)
Definition: help.cc:874
static bool looks_like_texinfo(const std::string &msg, size_t &p1)
Definition: help.cc:859
octave_function * function_value(bool silent=false) const
Definition: ov.cc:1597
static std::list< std::string > variable_names(void)
Definition: symtab.h:2113
static std::string find_fcn_file(const std::string &fcn, const std::string &pack_name=std::string())
Definition: load-path.h:167
virtual std::string fcn_file_name(void) const
Definition: ov-fcn.h:62
octave_idx_type length(void) const
Number of elements in the array.
Definition: Array.h:267
static const map_type operators_map(operators, operators+size(operators))
static bool is_dir_sep(char c)
Definition: file-ops.h:73
#define OCTAVE_LOCAL_BUFFER(T, buf, size)
Definition: oct-locbuf.h:197
string_vector make_name_list(void)
Definition: help.cc:798
static const pair_type keywords[]
Definition: help.cc:445
static bool Vsuppress_verbose_help_message
Definition: help.cc:93
void install_built_in_docstrings(void)
Definition: help.cc:978
static std::list< std::string > built_in_function_names(void)
Definition: symtab.h:2120
static bool raw_help_from_map(const std::string &nm, std::string &h, const map_type &map, bool &symbol_found)
Definition: help.cc:919
return octave_value(v1.char_array_value().concat(v2.char_array_value(), ra_idx),((a1.is_sq_string()||a2.is_sq_string())? '\'': '"'))