guile/guile-core/ice-9 ChangeLog documentation....

[Neil Jerram]

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

Modified files:
        guile-core/ice-9: ChangeLog documentation.scm session.scm 

Log message:
        * Enhancements to online help presentation.

CVSWeb URLs:
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/ice-9/ChangeLog.diff?r1=1.350&r2=1.351
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/ice-9/documentation.scm.diff?r1=1.1&r2=1.2
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-core/ice-9/session.scm.diff?r1=1.19&r2=1.20

Patches:
Index: guile/guile-core/ice-9/ChangeLog
diff -u guile/guile-core/ice-9/ChangeLog:1.350 
guile/guile-core/ice-9/ChangeLog:1.351
--- guile/guile-core/ice-9/ChangeLog:1.350      Wed Sep 20 14:06:06 2000
+++ guile/guile-core/ice-9/ChangeLog    Fri Sep 29 13:39:29 2000
@@ -1,3 +1,15 @@
+2000-09-29  Neil Jerram  <address@hidden>
+
+       * documentation.scm (find-documentation-in-file): Modified
+       according to changed format of guile-procedures.txt caused by my
+       snarfing/makeinfo changes in libguile.
+
+       * session.scm (help-doc): Improvements to (help) output: (i) a
+       friendlier Emacs-style introduction line; (ii) where the help arg
+       matches multiple documented entries, print an initial list of the
+       entries for which documentation is found, before printing the
+       actual documentation entries themselves.
+
 2000-09-20  Mikael Djurfeldt  <address@hidden>
 
        * boot-9.scm: Removed comment.  (Thanks to Brad Knotwell.)
Index: guile/guile-core/ice-9/documentation.scm
diff -u guile/guile-core/ice-9/documentation.scm:1.1 
guile/guile-core/ice-9/documentation.scm:1.2
--- guile/guile-core/ice-9/documentation.scm:1.1        Sun Jun 11 11:30:56 2000
+++ guile/guile-core/ice-9/documentation.scm    Fri Sep 29 13:39:29 2000
@@ -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: guile/guile-core/ice-9/session.scm
diff -u guile/guile-core/ice-9/session.scm:1.19 
guile/guile-core/ice-9/session.scm:1.20
--- guile/guile-core/ice-9/session.scm:1.19     Tue Jun 20 10:15:21 2000
+++ guile/guile-core/ice-9/session.scm  Fri Sep 29 13:39:29 2000
@@ -63,14 +63,21 @@
   (let ((entries (apropos-fold (lambda (module name object data)
                                 (cons (list module
                                             name
-                                            (object-documentation object))
+                                            (object-documentation object)
+                                            (cond ((closure? object)
+                                                   "a procedure")
+                                                  ((procedure? object)
+                                                   "a primitive procedure")
+                                                  (else
+                                                   "an object")))
                                       data))
                               '()
                               regexp
                               apropos-fold-exported))
        (module car)
        (name cadr)
-       (doc caddr))
+       (doc caddr)
+       (type cadddr))
     (if (null? entries)
        ;; no matches
        (begin
@@ -80,32 +87,55 @@
                             "named `~A'\n"
                             "matching regexp \"~A\"\n")
                         term))
-       (let ((first? #t))
-         (if (or-map doc entries)
-             ;; entries with documentation
-             (for-each (lambda (entry)
-                         ;; *fixme*: Use `describe' when we have GOOPS?
-                         (if (doc entry)
-                             (begin
-                               (if first?
-                                   (set! first? #f)
-                                   (newline))
-                               (simple-format #t "~S: ~S\n~A\n"
-                                              (module-name (module entry))
-                                              (name entry)
-                                              (doc entry)))))
-                       entries))
-         (if (or-map (lambda (x) (not (doc x))) entries)
-             ;; entries without documentation
+       (let ((first? #t)
+             (undocumented-entries '())
+             (documented-entries '())
+             (documentations '()))
+
+         (for-each (lambda (entry)
+                     (let ((entry-summary (simple-format #f
+                                                         "~S: ~S\n"
+                                                         (module-name (module 
entry))
+                                                         (name entry))))
+                       (if (doc entry)
+                           (begin
+                             (set! documented-entries
+                                   (cons entry-summary documented-entries))
+                             ;; *fixme*: Use `describe' when we have GOOPS?
+                             (set! documentations
+                                   (cons (simple-format #f
+                                                        "`~S' is ~A in the ~S 
module.\n\n~A\n"
+                                                        (name entry)
+                                                        (type entry)
+                                                        (module-name (module 
entry))
+                                                        (doc entry))
+                                         documentations)))
+                           (set! undocumented-entries
+                                 (cons entry-summary undocumented-entries)))))
+                   entries)
+
+         (if (and (not (null? documented-entries))
+                  (or (> (length documented-entries) 1)
+                      (not (null? undocumented-entries))))
              (begin
-               (if (not first?)
-                   (display "\nNo documentation found for:\n"))
-               (for-each (lambda (entry)
-                           (if (not (doc entry))
-                               (simple-format #t "~S: ~S\n"
-                                              (module-name (module entry))
-                                              (name entry))))
-                         entries)))))))
+               (display "Documentation found for:\n")
+               (for-each (lambda (entry) (display entry)) documented-entries)
+               (set! first? #f)))
+
+         (for-each (lambda (entry)
+                     (if first?
+                         (set! first? #f)
+                         (newline))
+                     (display entry))
+                   documentations)
+
+         (if (not (null? undocumented-entries))
+             (begin
+               (if first?
+                   (set! first? #f)
+                   (newline))
+               (display "No documentation found for:\n")
+               (for-each (lambda (entry) (display entry)) 
undocumented-entries)))))))
 
 (define (help-usage)
   (display "Usage: (help NAME) gives documentation about objects named NAME (a 
symbol)