Patches to run makeinfo on snarfed libguile docstrings

[Neil Jerram]

Currently, the docstrings in the libguile source are - theoretically,
at least - written in Texinfo.  (In practice, many of them actually
are in Texinfo, but some - for example list? - are written in an
approximation to the plain text Info format.)  But there is no step in
the on-line documentation system which runs these docstrings through
makeinfo so that Texinfo markup is converted to plain text.

This means that when you type `(help acons)', what you see is:

guile> (help acons)
(guile): acons
(acons key value alist)
Adds a new key-value pair to @var{alist}.  A new pair is
created whose car is @var{key} and whose cdr is @var{value}, and the
pair is consed onto @var{alist}, and the new list is returned.  This
function is @emph{not} destructive; @var{alist} is not modified.
[alist.c:61]
guile> 

The patches below add in the missing makeinfo step, by
- modifying the snarf output to be Texinfo-compliant
- adding Makefile rules to produce guile-procedures.txt by running
  makeinfo over the snarfed output
- modifying documentation.scm according to the altered format of
  guile-procedures.txt.
They also modify session.scm to generate a documentation-introduction
line in a form similar to Emacs' C-h f, which I think is more friendly
that just `(module): name'.

So the result of all this...?  What you see with these patches is:

guile> (help acons)
`acons' is a primitive procedure in the (guile) module.

 - primitive: acons key value alist
     Adds a new key-value pair to ALIST.  A new pair is created whose
     car is KEY and whose cdr is VALUE, and the pair is consed onto
     ALIST, and the new list is returned.  This function is _not_
     destructive; ALIST is not modified.
guile> 

What do you think?  We definitely need the makeinfo step in some form,
but do you agree with me that the modified presentation is also much
clearer?  Should I commit these patches?

Regards,

        Neil


Index: guile-snarf.awk.in
===================================================================
RCS file: /cvs/guile/guile-core/libguile/guile-snarf.awk.in,v
retrieving revision 1.8
diff -u -r1.8 guile-snarf.awk.in
--- guile-snarf.awk.in  2000/06/21 08:43:12     1.8
+++ guile-snarf.awk.in  2000/09/23 14:23:55
@@ -31,7 +31,8 @@
                 gsub(/\"/,"",location);
                 sub(/^[ \t]*/,"",location);
                 sub(/[ \t]*$/,"",location);
-                sub(/: /,":",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,35 @@
                 # 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; }
+                print "\n" proc_name > dot_doc_file;
+                print "@c docstring begin (c-doc-string \"" location "\" \"" 
proc_name "\")" > dot_doc_file;
+                print "@deffn primitive " curr_function_proto 
(registering?")":"") > 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(/\\n\\n\"?/,"\n",copy);
+                      gsub(/\\n\"?[ \t]*$/,"",copy);
                       gsub(/\\\"[ \t]*$/,"\"",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);

Index: Makefile.am
===================================================================
RCS file: /cvs/guile/guile-core/libguile/Makefile.am,v
retrieving revision 1.116
diff -u -r1.116 Makefile.am
--- Makefile.am 2000/09/10 20:21:42     1.116
+++ Makefile.am 2000/09/23 14:23:08
@@ -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: documentation.scm
===================================================================
RCS file: /cvs/guile/guile-core/ice-9/documentation.scm,v
retrieving revision 1.1
diff -u -r1.1 documentation.scm
--- documentation.scm   2000/06/11 18:30:56     1.1
+++ documentation.scm   2000/09/23 13:19:49
@@ -38,28 +38,24 @@
          documentation-files))
 
 (define entry-delimiter "\f")
-(define entry-start 2)
 
 (define (find-documentation-in-file name file)
   (and (file-exists? file)
        (let ((port (open-input-file file))
             (name (symbol->string name)))
-        (let* ((len (string-length name))
-               (min-size (+ entry-start len))
-               (end (+ entry-start len)))
+        (let ((len (string-length name)))
           (read-delimited entry-delimiter port) ;skip to first entry
           (let loop ((entry (read-delimited entry-delimiter port)))
             (cond ((eof-object? entry) #f)
                   ;; match?
                   ((and ;; large enough?
-                        (>= (string-length entry) min-size)
+                        (>= (string-length entry) len)
                         ;; matching name?
-                        (string=? (substring entry entry-start end)
-                                  name)
+                        (string=? (substring entry 0 len) name)
                         ;; terminated?
-                        (memq (string-ref entry end) '(#\space #\))))
-                   ;; cut away starting and ending newline
-                   (substring entry 1 (- (string-length entry) 1)))
+                        (memq (string-ref entry len) '(#\newline)))
+                   ;; cut away name tag and extra surrounding newlines
+                   (substring entry (+ len 2) (- (string-length entry) 2)))
                   (else (loop (read-delimited entry-delimiter port)))))))))
 
 ;; helper until the procedure documentation property is cleaned up

Index: session.scm
===================================================================
RCS file: /cvs/guile/guile-core/ice-9/session.scm,v
retrieving revision 1.19
diff -u -r1.19 session.scm
--- session.scm 2000/06/20 17:15:21     1.19
+++ session.scm 2000/09/23 13:20:33
@@ -63,14 +63,21 @@
   (let ((entries (apropos-fold (lambda (module name object da
>From address@hidden  Sat Sep 23 17:04:03 2000
Received: from www.uklinux.net (ns0.uklinux.net [212.1.130.10])
        by mescaline.gnu.org (8.9.1a/8.9.1) with ESMTP id RAA00272;
        Sat, 23 Sep 2000 17:04:01 -0400
Received: from localhost.localdomain (IDENT:address@hidden [212.1.141.108])
        by www.uklinux.net (8.9.3/8.8.7) with ESMTP id QAA32739;
        Sat, 23 Sep 2000 16:10:43 +0100
Received: (from address@hidden)
        by localhost.localdomain (8.9.3/8.9.3) id QAA08611;
        Sat, 23 Sep 2000 16:04:30 +0100
Date: Sat, 23 Sep 2000 16:04:30 +0100
Message-Id: <address@hidden>
X-Authentication-Warning: localhost.localdomain: neil set sender to 
address@hidden using -f
From: Neil Jerram <address@hidden>
To: address@hidden
CC: address@hidden
In-reply-to: <address@hidden> (message from thi on Fri,
        22 Sep 2000 09:42:39 -0700)
Subject: Re: Errors in the Guile web pages
References: <address@hidden> <address@hidden>
Sender: address@hidden
Errors-To: address@hidden
X-BeenThere: address@hidden
X-Mailman-Version: 2.0beta4
Precedence: bulk
List-Id: Developers list for Guile, the GNU extensibility library 
<guile-devel.gnu.org>

thi writes:

   i believe originally the guile web pages were on red-bean.com, and may
   have been under some revision control system there.  then jimb moved
   them to www.gnu.org and put them under CVS there.  at this time, they
   are still under CVS.

OK, so I guess it's just a different CVS - and with a different set of
people with write access - than the rest of Guile.

The key question is, what is the right place to send web page bug
reports and patches?

Thanks,
        Neil