From maintainers-request at octave dot org Mon May  2 13:57:31 2005
Subject: Re: DOCSTRINGS patch (was Re: default ~/.octaverc template)
From: "John W. Eaton" <jwe at bevo dot che dot wisc dot edu>
To: Bill Denney <denney at seas dot upenn dot edu>
Cc: octave maintainers mailing list <maintainers at octave dot org>
Date: Mon, 2 May 2005 14:56:13 -0400

On 29-Apr-2005, Bill Denney wrote:

| > Thanks for looking at these, but the DOCSTRINGS files are generated 
| > automatically from the sources.  You want to change the definitions of 
| > these strings in the sources instead.
| 
| OK, here are patches for the sources.

I applied these changes.

| It may be useful to remove the 
| DOCSTRINGS file from the source tree (i.e. make it removed by a make clean 
| or something) so that other people don't make the same mistake I did.

How about adding a comment header at the top of the file saying that
it is generated automatically, as in the following patch?

Thanks,

jwe


scripts/ChangeLog:

2005-05-02  John W. Eaton  <jwe at octave dot org>

	* mkdoc: Print header message.


src/ChangeLog:

2005-05-02  John W. Eaton  <jwe at octave dot org>

	* mkgendoc (main): Print header message.


doc/ChangeLog:

2005-05-02  John W. Eaton  <jwe at octave dot org>

	* interpreter/munge-texi.cc (skip_comments): New function.
	(process_doc_file): Use it to skip comments at beginning of file.


Index: scripts/mkdoc
===================================================================
RCS file: /cvs/octave/scripts/mkdoc,v
retrieving revision 1.4
diff -u -r1.4 mkdoc
--- scripts/mkdoc	10 Oct 2002 05:20:20 -0000	1.4
+++ scripts/mkdoc	2 May 2005 18:13:26 -0000
 at @ -9,6 +9,13 @@
 fi
 
 if test -f gethelp; then
+  cat << EOF
+### DO NOT EDIT!
+###
+### This file is generated automatically from the Octave sources.
+### Edit those files instead and run make to update this file.
+
+EOF
   find $d -name '*.m' | \
     sed "s,\(.*\)/\(.*\)\.m,./gethelp \2 < & | sed 's/^ * at /@/',"|  | \
     /bin/sh
Index: src/mkgendoc
===================================================================
RCS file: /cvs/octave/src/mkgendoc,v
retrieving revision 1.11
diff -u -r1.11 mkgendoc
--- src/mkgendoc	16 Jan 2003 20:15:15 -0000	1.11
+++ src/mkgendoc	2 May 2005 18:13:32 -0000
 at @ -83,6 +83,13 @@
 int
 main (void)
 {
+  std::cout
+    << "### DO NOT EDIT!\n"
+    << "###\n"
+    << "### This file is generated automatically from the Octave sources.\n"
+    << "### Edit those files instead and run make to update this file.\n"
+    << std::endl;
+
 EOF
 
 for file in $DOC_FILES; do
Index: doc/interpreter/munge-texi.cc
===================================================================
RCS file: /cvs/octave/doc/interpreter/munge-texi.cc,v
retrieving revision 1.14
diff -u -r1.14 munge-texi.cc
--- doc/interpreter/munge-texi.cc	26 Apr 2005 19:24:27 -0000	1.14
+++ doc/interpreter/munge-texi.cc	2 May 2005 18:31:08 -0000
 at @ -74,12 +74,35 @@
 }
 
 static void
+skip_comments (std::ifstream& is)
+{
+  int c;
+
+  bool in_comment = false;
+
+  while ((c = is.get ()) != EOF)
+    {
+      if (c == '#')
+	in_comment = true;
+      else if (c == '\n')
+	in_comment = false;
+      else if (! (in_comment || ::isspace (c)))
+	{
+	  is.putback (c);
+	  break;
+	}
+    }
+}
+
+static void
 process_doc_file (const std::string& fname)
 {
   std::ifstream infile (fname.c_str ());
 
   if (infile)
     {
+      skip_comments (infile);
+
       if (infile.get () != doc_delim)
 	fatal ("invalid doc file format");