# HG changeset patch
# User John W. Eaton <jwe@octave.org>
# Date 1349207603 14400
# Node ID bf0857c789f4e4e05a9ba6e75fc545e797f27359
# Parent  72868cae7624b4ae15adac736131038b51b7e44e
initialize docstrings for built-in functions from file

* libinterp/Makefile.am: Install DOCSTRINGS file in
$(octetcdir)/built-in-docstrings.
* defaults.cc (set_built_in_docstrings_file): New function.
(install_defaults): Call it.
(Vbuilt_in_docstrings_file): New variable.
* defaults.in.h (Vbuilt_in_docstrings_file): Provide decl.
* help.cc (Fbuilt_in_docstrings_file, install_built_in_docstrings):
New functions.
* help.h (install_built_in_docstrings): Provide decl.
* mkbuiltins: Generate call to install_built_in_docstrings at end of
install_builtins function.
* octave.cc: Handle new option --built-in-docstrings-file.
(octave_process_command_line): Handle BUILT_IN_DOCSTRINGS_FILE_OPTION.
* run-octave.in: Pass --built-in-docstrings-file option to Octave.

diff -r 72868cae7624 -r bf0857c789f4 libinterp/Makefile.am
--- a/libinterp/Makefile.am	Mon Oct 01 18:32:31 2012 -0400
+++ b/libinterp/Makefile.am	Tue Oct 02 15:53:23 2012 -0400
@@ -280,7 +280,7 @@
 all-local: $(OCT_STAMP_FILES) $(DLDFCN_PKG_ADD_FILE)
 endif
 
-install-data-hook: install-oct
+install-data-hook: install-oct install-built-in-docstrings
 
 uninstall-local: uninstall-oct
 
@@ -314,6 +314,10 @@
 endif
 .PHONY: install-oct uninstall-oct
 
+install-built-in-docstrings:
+	$(INSTALL_DATA) DOCSTRINGS $(DESTDIR)$(octetcdir)/built-in-docstrings
+.PHONY: install-built-in-docstrings
+
 CLEANFILES = \
   $(DLDFCN_PKG_ADD_FILE) \
   interpfcn/graphics-props.cc \
diff -r 72868cae7624 -r bf0857c789f4 libinterp/interpfcn/defaults.cc
--- a/libinterp/interpfcn/defaults.cc	Mon Oct 01 18:32:31 2012 -0400
+++ b/libinterp/interpfcn/defaults.cc	Tue Oct 02 15:53:23 2012 -0400
@@ -93,6 +93,8 @@
 std::string Vlocal_site_defaults_file;
 std::string Vsite_defaults_file;
 
+std::string Vbuilt_in_docstrings_file;
+
 std::string
 subst_octave_home (const std::string& s)
 {
@@ -371,6 +373,21 @@
     Vsite_defaults_file = sf;
 }
 
+static void
+set_built_in_docstrings_file (void)
+{
+  if (Vbuilt_in_docstrings_file.empty ())
+    {
+      std::string df = octave_env::getenv ("OCTAVE_BUILT_IN_DOCSTRINGS_FILE");
+
+      if (df.empty ())
+        Vbuilt_in_docstrings_file
+          = Voct_etc_dir + file_ops::dir_sep_str () + "built-in-docstrings";
+      else
+        Vbuilt_in_docstrings_file = df;
+    }
+}
+
 void
 install_defaults (void)
 {
@@ -424,6 +441,8 @@
   set_local_site_defaults_file ();
 
   set_site_defaults_file ();
+
+  set_built_in_docstrings_file ();
 }
 
 DEFUN (EDITOR, args, nargout,
diff -r 72868cae7624 -r bf0857c789f4 libinterp/interpfcn/defaults.in.h
--- a/libinterp/interpfcn/defaults.in.h	Mon Oct 01 18:32:31 2012 -0400
+++ b/libinterp/interpfcn/defaults.in.h	Tue Oct 02 15:53:23 2012 -0400
@@ -207,6 +207,8 @@
 extern OCTINTERP_API std::string Vlocal_site_defaults_file;
 extern OCTINTERP_API std::string Vsite_defaults_file;
 
+extern OCTINTERP_API std::string Vbuilt_in_docstrings_file;
+
 // Name of the FFTW wisdom program.
 extern OCTINTERP_API std::string Vfftw_wisdom_program;
 
diff -r 72868cae7624 -r bf0857c789f4 libinterp/interpfcn/help.cc
--- a/libinterp/interpfcn/help.cc	Mon Oct 01 18:32:31 2012 -0400
+++ b/libinterp/interpfcn/help.cc	Tue Oct 02 15:53:23 2012 -0400
@@ -922,6 +922,93 @@
   return h;
 }
 
+
+DEFUN (built_in_docstrings_file, args, nargout,
+  "-*- texinfo -*-\n\
+@deftypefn  {Built-in Function} {@var{val} =} built_in_docstrings_file ()\n\
+@deftypefnx {Built-in Function} {@var{old_val} =} built_in_docstrings_file (@var{new_val})\n\
+@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\
+\n\
+Note that this variable is only used when Octave is initializing itself,\n\
+so setting it will have no effect.\n\
+@end deftypefn")
+{
+  return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (built_in_docstrings_file);
+}
+
+void
+install_built_in_docstrings (void)
+{
+  std::string fname = Vbuilt_in_docstrings_file;
+
+  std::ifstream file (fname.c_str (), std::ios::in | std::ios::binary);
+
+  if (file)
+    {
+      // Ignore header;
+      file.ignore (1000, 0x1f);
+
+      if (file.gcount () == 1000)
+        {
+          // We use std::cerr here instead of calling Octave's warning
+          // function because install_built_in_docstrings is called
+          // before the interpreter is initialized, so warning messages
+          // won't work properly.
+
+          std::cerr << "warning: is builtin-docstrings file corrupted?"
+                    << std::endl;
+          return;
+        }
+
+      // FIXME -- eliminate fixed buffer size.
+      size_t bufsize = 100000;
+
+      OCTAVE_LOCAL_BUFFER (char, buf, bufsize);
+
+      while (! file.eof ())
+        {
+          file.getline (buf, bufsize, 0x1f);
+
+          std::string tmp (buf);
+
+          size_t pos = tmp.find ('\n');
+
+          std::string fcn = tmp.substr (0, pos);
+
+          octave_value ov = symbol_table::find_built_in_function (fcn);
+
+          if (ov.is_defined ())
+            {
+              octave_function *fp = ov.function_value ();
+
+              if (fp)
+                {
+                  tmp = tmp.substr (pos+1);
+
+                  while (tmp.length () > 2 && tmp[0] == '@' && tmp[1] == 'c')
+                    {
+                      pos = tmp.find ('\n');
+                      tmp = tmp.substr (pos+1);
+                    }
+
+                  fp->document (tmp);
+                }
+            }
+        }
+    }
+  else
+    {
+      // See note above about using std::cerr instead of warning.
+
+      std::cerr << "warning: docstring file '" << fname << "' not found"
+                << std::endl;
+    }
+
+  octave_time t2;
+}
+
 static void
 do_get_help_text (const std::string& name, std::string& text,
                   std::string& format)
diff -r 72868cae7624 -r bf0857c789f4 libinterp/interpfcn/help.h
--- a/libinterp/interpfcn/help.h	Mon Oct 01 18:32:31 2012 -0400
+++ b/libinterp/interpfcn/help.h	Tue Oct 02 15:53:23 2012 -0400
@@ -32,6 +32,8 @@
 
 extern OCTINTERP_API std::string raw_help (const std::string&, bool&);
 
+extern OCTINTERP_API void install_built_in_docstrings (void);
+
 // Name of the doc cache file specified on the command line.
 // (--doc-cache-file file)
 extern std::string Vdoc_cache_file;
diff -r 72868cae7624 -r bf0857c789f4 libinterp/mkbuiltins
--- a/libinterp/mkbuiltins	Mon Oct 01 18:32:31 2012 -0400
+++ b/libinterp/mkbuiltins	Tue Oct 02 15:53:23 2012 -0400
@@ -78,6 +78,7 @@
 #endif
 
 #include "defun.h"
+#include "help.h"
 #include "oct-obj.h"
 #include "variables.h"
 #include "builtins.h"
@@ -149,6 +150,8 @@
   done
 
   cat << \EOF
+
+  install_built_in_docstrings ();
 }
 
 EOF
diff -r 72868cae7624 -r bf0857c789f4 libinterp/octave.cc
--- a/libinterp/octave.cc	Mon Oct 01 18:32:31 2012 -0400
+++ b/libinterp/octave.cc	Tue Oct 02 15:53:23 2012 -0400
@@ -205,60 +205,61 @@
 
 // Long options.  See the comments in getopt.h for the meanings of the
 // fields in this structure.
-#define DOC_CACHE_FILE_OPTION 1
-#define EVAL_OPTION 2
-#define EXEC_PATH_OPTION 3
-#define FORCE_GUI_OPTION 4
-#define IMAGE_PATH_OPTION 5
-#define INFO_FILE_OPTION 6
-#define INFO_PROG_OPTION 7
-#define JIT_DEBUG_OPTION 8
-#define LINE_EDITING_OPTION 9
-#define NO_GUI_OPTION 10
-#define NO_INIT_FILE_OPTION 11
-#define NO_INIT_PATH_OPTION 12
-#define NO_JIT_COMPILER_OPTION 13
-#define NO_LINE_EDITING_OPTION 14
-#define NO_SITE_FILE_OPTION 15
-#define NO_WINDOW_SYSTEM_OPTION 16
-#define PERSIST_OPTION 17
-#define TEXI_MACROS_FILE_OPTION 18
-#define TRADITIONAL_OPTION 19
-struct option long_opts[] =
-  {
-    { "braindead",        no_argument,       0, TRADITIONAL_OPTION },
-    { "debug",            no_argument,       0, 'd' },
-    { "doc-cache-file",   required_argument, 0, DOC_CACHE_FILE_OPTION },
-    { "echo-commands",    no_argument,       0, 'x' },
-    { "eval",             required_argument, 0, EVAL_OPTION },
-    { "exec-path",        required_argument, 0, EXEC_PATH_OPTION },
-    { "force-gui",        no_argument,       0, FORCE_GUI_OPTION },
-    { "help",             no_argument,       0, 'h' },
-    { "image-path",       required_argument, 0, IMAGE_PATH_OPTION },
-    { "info-file",        required_argument, 0, INFO_FILE_OPTION },
-    { "info-program",     required_argument, 0, INFO_PROG_OPTION },
-    { "interactive",      no_argument,       0, 'i' },
-    { "jit-debug",        no_argument,       0, JIT_DEBUG_OPTION },
-    { "line-editing",     no_argument,       0, LINE_EDITING_OPTION },
-    { "no-gui",           no_argument,       0, NO_GUI_OPTION },
-    { "no-history",       no_argument,       0, 'H' },
-    { "no-init-file",     no_argument,       0, NO_INIT_FILE_OPTION },
-    { "no-init-path",     no_argument,       0, NO_INIT_PATH_OPTION },
-    { "no-jit",           no_argument,       0, NO_JIT_COMPILER_OPTION },
-    { "no-line-editing",  no_argument,       0, NO_LINE_EDITING_OPTION },
-    { "no-site-file",     no_argument,       0, NO_SITE_FILE_OPTION },
-    { "no-window-system", no_argument,       0, NO_WINDOW_SYSTEM_OPTION },
-    { "norc",             no_argument,       0, 'f' },
-    { "path",             required_argument, 0, 'p' },
-    { "persist",          no_argument,       0, PERSIST_OPTION },
-    { "quiet",            no_argument,       0, 'q' },
-    { "silent",           no_argument,       0, 'q' },
-    { "texi-macros-file", required_argument, 0, TEXI_MACROS_FILE_OPTION },
-    { "traditional",      no_argument,       0, TRADITIONAL_OPTION },
-    { "verbose",          no_argument,       0, 'V' },
-    { "version",          no_argument,       0, 'v' },
-    { 0,                  0,                 0, 0 }
-  };
+#define BUILT_IN_DOCSTRINGS_FILE_OPTION 1
+#define DOC_CACHE_FILE_OPTION 2
+#define EVAL_OPTION 3
+#define EXEC_PATH_OPTION 4
+#define FORCE_GUI_OPTION 5
+#define IMAGE_PATH_OPTION 6
+#define INFO_FILE_OPTION 7
+#define INFO_PROG_OPTION 8
+#define JIT_DEBUG_OPTION 9
+#define LINE_EDITING_OPTION 10
+#define NO_GUI_OPTION 11
+#define NO_INIT_FILE_OPTION 12
+#define NO_INIT_PATH_OPTION 13
+#define NO_JIT_COMPILER_OPTION 14
+#define NO_LINE_EDITING_OPTION 15
+#define NO_SITE_FILE_OPTION 16
+#define NO_WINDOW_SYSTEM_OPTION 17
+#define PERSIST_OPTION 18
+#define TEXI_MACROS_FILE_OPTION 19
+#define TRADITIONAL_OPTION 20
+struct option long_opts[] = {
+  { "braindead",                no_argument,       0, TRADITIONAL_OPTION },
+  { "built-in-docstrings-file", required_argument, 0, BUILT_IN_DOCSTRINGS_FILE_OPTION },
+  { "debug",                    no_argument,       0, 'd' },
+  { "doc-cache-file",           required_argument, 0, DOC_CACHE_FILE_OPTION },
+  { "echo-commands",            no_argument,       0, 'x' },
+  { "eval",                     required_argument, 0, EVAL_OPTION },
+  { "exec-path",                required_argument, 0, EXEC_PATH_OPTION },
+  { "force-gui",                no_argument,       0, FORCE_GUI_OPTION },
+  { "help",                     no_argument,       0, 'h' },
+  { "image-path",               required_argument, 0, IMAGE_PATH_OPTION },
+  { "info-file",                required_argument, 0, INFO_FILE_OPTION },
+  { "info-program",             required_argument, 0, INFO_PROG_OPTION },
+  { "interactive",              no_argument,       0, 'i' },
+  { "jit-debug",                no_argument,       0, JIT_DEBUG_OPTION },
+  { "line-editing",             no_argument,       0, LINE_EDITING_OPTION },
+  { "no-gui",                   no_argument,       0, NO_GUI_OPTION },
+  { "no-history",               no_argument,       0, 'H' },
+  { "no-init-file",             no_argument,       0, NO_INIT_FILE_OPTION },
+  { "no-init-path",             no_argument,       0, NO_INIT_PATH_OPTION },
+  { "no-jit",                   no_argument,       0, NO_JIT_COMPILER_OPTION },
+  { "no-line-editing",          no_argument,       0, NO_LINE_EDITING_OPTION },
+  { "no-site-file",             no_argument,       0, NO_SITE_FILE_OPTION },
+  { "no-window-system",         no_argument,       0, NO_WINDOW_SYSTEM_OPTION },
+  { "norc",                     no_argument,       0, 'f' },
+  { "path",                     required_argument, 0, 'p' },
+  { "persist",                  no_argument,       0, PERSIST_OPTION },
+  { "quiet",                    no_argument,       0, 'q' },
+  { "silent",                   no_argument,       0, 'q' },
+  { "texi-macros-file",         required_argument, 0, TEXI_MACROS_FILE_OPTION },
+  { "traditional",              no_argument,       0, TRADITIONAL_OPTION },
+  { "verbose",                  no_argument,       0, 'V' },
+  { "version",                  no_argument,       0, 'v' },
+  { 0,                          0,                 0, 0 }
+};
 
 // Store the command-line options for later use.
 
@@ -778,6 +779,11 @@
           print_version_and_exit ();
           break;
 
+        case BUILT_IN_DOCSTRINGS_FILE_OPTION:
+          if (optarg)
+            Vbuilt_in_docstrings_file = optarg;
+          break;
+
         case DOC_CACHE_FILE_OPTION:
           if (optarg)
             doc_cache_file = optarg;
diff -r 72868cae7624 -r bf0857c789f4 run-octave.in
--- a/run-octave.in	Mon Oct 01 18:32:31 2012 -0400
+++ b/run-octave.in	Tue Oct 02 15:53:23 2012 -0400
@@ -47,6 +47,7 @@
 LOADPATH="$d1_path:$d2_path:$d3_path"
 IMAGEPATH="$top_srcdir/scripts/image"
 DOCFILE="$builddir/doc/interpreter/doc-cache"
+BUILT_IN_DOCSTRINGS_FILE="$builddir/libinterp/DOCSTRINGS"
 TEXIMACROSFILE="$top_srcdir/doc/interpreter/macros.texi"
 INFOFILE="$top_srcdir/doc/interpreter/octave.info"
 
@@ -82,4 +83,5 @@
   exec $builddir/libtool --mode=execute $driver \
     "$octave_executable" --no-init-path --path="$LOADPATH" \
     --image-path="$IMAGEPATH" --doc-cache-file="$DOCFILE" \
+    --built-in-docstrings-file="$BUILT_IN_DOCSTRINGS_FILE" \
     --texi-macros-file="$TEXIMACROSFILE" --info-file="$INFOFILE" "$@"