changeset 16809:2fd22fbaffa3

doc: Add built_in_docstrings_file() to documentation. * doc/interpreter/basics.txi: Add built_in_docstrings_file() to manual. * libinterp/interpfcn/help.cc(built_in_docstrings_file): Update docstring to mention environment variable and command line overrides.
author Rik <rik@octave.org>
date Sat, 22 Jun 2013 10:58:16 -0700
parents ab0454713ded
children 772f51539af8
files doc/interpreter/basics.txi libinterp/interpfcn/help.cc
diffstat 2 files changed, 23 insertions(+), 8 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/basics.txi
+++ b/doc/interpreter/basics.txi
@@ -67,6 +67,13 @@
 
 
 @table @code
+
+@item --built-in-docstrings-file @var{filename}
+@cindex @code{--built-in-docstrings-file @var{filename}}
+Specify the name of the file containing documentation strings for the
+built-in functions of Octave.  This value is normally correct and should
+only need to specified in extraordinary situations.
+
 @item  --debug
 @itemx -d
 @cindex @code{--debug}
@@ -75,8 +82,8 @@
 parser to print a lot of information about the commands it reads, and is
 probably only useful if you are actually trying to debug the parser.
 
-@item --docXcache-file @var{filename}
-@cindex @code{--docXcache-file @var{filename}}
+@item --doc-cache-file @var{filename}
+@cindex @code{--doc-cache-file @var{filename}}
 Specify the name of the doc cache file to use.  The value of @var{filename}
 specified on the command line will override any value of
 @w{@env{OCTAVE_DOC_CACHE_FILE}} found in the environment, but not any commands
@@ -426,6 +433,8 @@
 
 @DOCSTRING(doc_cache_file)
 
+@DOCSTRING(built_in_docstrings_file)
+
 @DOCSTRING(suppress_verbose_help_message)
 
 The following functions are principally used internally by Octave for
--- a/libinterp/interpfcn/help.cc
+++ b/libinterp/interpfcn/help.cc
@@ -935,7 +935,6 @@
   return h;
 }
 
-
 DEFUN (built_in_docstrings_file, args, nargout,
   "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {@var{val} =} built_in_docstrings_file ()\n\
@@ -943,9 +942,16 @@
 @deftypefnx {Built-in Function} {} built_in_docstrings_file (@var{new_val}, \"local\")\n\
 Query or set the internal variable that specifies the name of the\n\
 file containing docstrings for built-in Octave functions.\n\
+The default value is\n\
+@file{@var{octave-home}/share/octave/@var{version}/etc/built-in-docstrings},\n\
+in which @var{octave-home} is the root directory of the Octave installation,\n\
+and @var{version} is the Octave version number.\n\
+The default value may be overridden by the environment variable\n\
+@w{@env{OCTAVE_BUILT_IN_DOCSTRINGS_FILE}}, or the command line argument\n\
+@samp{--built-in-docstrings-file FNAME}.\n\
 \n\
-Note that this variable is only used when Octave is initializing itself,\n\
-so setting it will have no effect.\n\
+Note: This variable is only used when Octave is initializing itself.\n\
+Modifying it during a running session of Octave will have no effect.\n\
 @end deftypefn")
 {
   return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (built_in_docstrings_file);
@@ -1390,7 +1396,7 @@
 and @var{version} is the Octave version number.\n\
 The default value may be overridden by the environment variable\n\
 @w{@env{OCTAVE_DOC_CACHE_FILE}}, or the command line argument\n\
-@samp{--doc-cache-file NAME}.\n\
+@samp{--doc-cache-file FNAME}.\n\
 \n\
 When called from inside a function with the \"local\" option, the variable is\n\
 changed locally for the function and any subroutines it calls.  The original\n\
@@ -1414,7 +1420,7 @@
 and @var{version} is the Octave version number.\n\
 The default value may be overridden by the environment variable\n\
 @w{@env{OCTAVE_TEXI_MACROS_FILE}}, or the command line argument\n\
-@samp{--texi-macros-file NAME}.\n\
+@samp{--texi-macros-file FNAME}.\n\
 \n\
 When called from inside a function with the \"local\" option, the variable is\n\
 changed locally for the function and any subroutines it calls.  The original\n\
@@ -1436,7 +1442,7 @@
 which @var{octave-home} is the root directory of the Octave installation.\n\
 The default value may be overridden by the environment variable\n\
 @w{@env{OCTAVE_INFO_FILE}}, or the command line argument\n\
-@samp{--info-file NAME}.\n\
+@samp{--info-file FNAME}.\n\
 \n\
 When called from inside a function with the \"local\" option, the variable is\n\
 changed locally for the function and any subroutines it calls.  The original\n\