guile/guile-core/libguile guile-snarf.awk.in Ma...

[Neil Jerram]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Neil Jerram <address@hidden>    00/09/29 13:33:14

Modified files:
        guile-core/libguile: guile-snarf.awk.in Makefile.am ChangeLog 

Log message:
        * Enhance snarfing of libguile docstrings and postprocess them with 
makeinfo.

CVSWeb URLs:
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/guile-snarf.awk.in.diff?r1=1.8&r2=1.9
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/Makefile.am.diff?r1=1.116&r2=1.117
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/libguile/ChangeLog.diff?r1=1.1127&r2=1.1128

Patches:
Index: guile/guile-core/libguile/ChangeLog
diff -u guile/guile-core/libguile/ChangeLog:1.1127 
guile/guile-core/libguile/ChangeLog:1.1128
--- guile/guile-core/libguile/ChangeLog:1.1127  Fri Sep 29 13:22:31 2000
+++ guile/guile-core/libguile/ChangeLog Fri Sep 29 13:33:13 2000
@@ -1,5 +1,17 @@
 2000-09-29  Neil Jerram  <address@hidden>
 
+       * Makefile.am (guile-procedures.txt): Insert a new rule such that
+       the output from guile-snarf.awk is processed by makeinfo to
+       produce guile-procedures.txt.
+
+       * guile-snarf.awk.in: Modify the way we snarf docstrings such that
+       the output is Texinfo-compliant and suitable for post-processing
+       with makeinfo.  (Trim leading "./" from C file name if
+       present; reformat procedure prototype line in @deffn format;
+       improve representation of args to show optional and rest args;
+       explicitly quote quotation marks where they are used inside an AWK
+       regexp.)
+
        * net_db.c (scm_inet_ntoa): Docstring fix: missing newline
        inserted.
 
Index: guile/guile-core/libguile/Makefile.am
diff -u guile/guile-core/libguile/Makefile.am:1.116 
guile/guile-core/libguile/Makefile.am:1.117
--- guile/guile-core/libguile/Makefile.am:1.116 Sun Sep 10 13:21:42 2000
+++ guile/guile-core/libguile/Makefile.am       Fri Sep 29 13:33:13 2000
@@ -192,8 +192,13 @@
 posix.x: cpp_sig_symbols.c
 load.x: libpath.h
 
-guile-procedures.txt: $(DOT_DOC_FILES) $(EXTRA_DOT_DOC_FILES)
-       cat *.doc > $@
+guile.texi: $(DOT_DOC_FILES) $(EXTRA_DOT_DOC_FILES)
+       echo "@paragraphindent 0" > $@
+       cat *.doc >> $@
+
+guile-procedures.txt: guile.texi
+       rm -f $@
+       makeinfo --force -o $@ $< || test -f $@
 
 pkgdata_DATA = guile-procedures.txt
 
Index: guile/guile-core/libguile/guile-snarf.awk.in
diff -u guile/guile-core/libguile/guile-snarf.awk.in:1.8 
guile/guile-core/libguile/guile-snarf.awk.in:1.9
--- guile/guile-core/libguile/guile-snarf.awk.in:1.8    Wed Jun 21 01:43:12 2000
+++ guile/guile-core/libguile/guile-snarf.awk.in        Fri Sep 29 13:33:13 2000
@@ -32,6 +32,7 @@
                 sub(/^[ \t]*/,"",location);
                 sub(/[ \t]*$/,"",location);
                 sub(/: /,":",location);
+                sub(/^\.\//,"",location);
                 # Now whittle copy down to just the $1 field
                 #   (but do not use $1, since it hasn't been
                  #    altered by the above regexps)
@@ -40,29 +41,53 @@
                 # Now `copy' contains the nice scheme proc "prototype", e.g.
                 # (set-car! pair value)
                 # print copy > "/dev/stderr";  # for debugging
+                sub(/^\(/,"",copy);
+                sub(/\)[ \t]*$/,"",copy);
                 proc_and_args = copy;
                 curr_function_proto = copy;
+                proc_name = copy;
+                sub(/ .*$/,"",proc_name);
                 sub(/[^ \n]* /,"",proc_and_args);
-                sub(/\)[ \t]*/,"",proc_and_args);
                 split(proc_and_args,args," ");
                 # now args is an array of the arguments
                 # args[1] is the formal name of the first argument, etc.
                 if (numargs != numactuals && !registering) 
-                  { print location ":*** `" copy "' is improperly registered 
as having " numactuals " arguments" > std_err; }
-                print "\n" copy (registering?")":"") > dot_doc_file ; }
+                  { print location ":*** `" curr_function_proto "' is 
improperly registered as having " numactuals " arguments" > std_err; }
+                # Build a nicer function prototype than curr_function_proto
+                # that shows optional and rest arguments.
+                nicer_function_proto = proc_name;
+                if (!registering) {
+                  optional_args_tail = "";
+                  for (i = 1; i <= $2; i++) {
+                    nicer_function_proto = nicer_function_proto " " args[i];
+                  }
+                  for (; i <= $2 + $3; i++) {
+                    nicer_function_proto = nicer_function_proto " [" args[i];
+                    optional_args_tail = optional_args_tail "]";
+                  }
+                  nicer_function_proto = nicer_function_proto 
optional_args_tail;
+                  if ($4 != 0) {
+                    nicer_function_proto = nicer_function_proto " . " args[i];
+                  }
+                 }
+                # Now produce Texinfo format output.
+                print "\n" proc_name > dot_doc_file;
+                print "@c snarfed from " location > dot_doc_file;
+                print "@deffn primitive " nicer_function_proto > dot_doc_file;
+}
 
 /SCM_SNARF_DOCSTRING_START/,/SCM_SNARF_DOCSTRING_END.*$/ { copy = $0; 
                       gsub(/.*SCM_SNARF_DOCSTRING_START/,"",copy); 
-                     sub(/^[ \t]*"?/,"", copy);
+                     sub(/^[ \t]*\"?/,"", copy);
                      sub(/\"?[ \t]*SCM_SNARF_DOCSTRING_END.*$/,"", copy);
-                      gsub(/\\n\\n"?/,"\n",copy);
-                      gsub(/\\n"?[ \t]*$/,"",copy);
-                      gsub(/\\\"[ \t]*$/,"\"",copy);
+                      gsub(/\\n\\n\"?/,"\n",copy);
+                      gsub(/\\n\"?[ \t]*$/,"",copy);
+                      gsub(/\\\"/,"\"",copy);
                       gsub(/[ \t]*$/,"", copy);
                       if (copy != "") { print copy > dot_doc_file }
                 }
 
-/SCM_SNARF_DOCSTRING_END[ \t]/ { print "
[" location "]" >> dot_doc_file; }
+/SCM_SNARF_DOCSTRING_END[ \t]/ { print "@end deffn" >> dot_doc_file; }
 
 /\*&\*&\*&\*SCM_ARG_BETTER_BE_IN_POSITION/ { copy = $0;
          sub(/.*\*&\*&\*&\*SCM_ARG_BETTER_BE_IN_POSITION\([ \t]*/,"",copy);