[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Patches to run makeinfo on snarfed libguile docstrings
|
From: |
Neil Jerram |
|
Subject: |
Patches to run makeinfo on snarfed libguile docstrings |
|
Date: |
Sun, 24 Sep 2000 16:39:04 +0100 |
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 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) 2)
+ (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)
------- End of forwarded message -------
>From address@hidden Tue Sep 26 14:13:11 2000
Received: from host97.newtonlabs.com ([206.125.74.97]
helo=quasar.newtonlabs.com)
by fencepost.gnu.org with esmtp (Exim 3.16 #1 (Debian))
id 13dzE6-0005Fc-00
for <address@hidden>; Tue, 26 Sep 2000 14:13:11 -0400
Received: from bogomips.newtonlabs.com (bogomips.newtonlabs.com [207.55.51.12])
by quasar.newtonlabs.com (8.9.3/8.9.3/Debian/GNU) with ESMTP id
LAA16126;
Tue, 26 Sep 2000 11:12:55 -0700
Received: (from address@hidden)
by bogomips.newtonlabs.com (8.9.3/8.9.3/Debian/GNU) id LAA23209;
Tue, 26 Sep 2000 11:12:54 -0700
To: Dirk Herrmann <address@hidden>
Cc: Keisuke Nishida <address@hidden>,
"Carl R. Witty" <address@hidden>,
Mikael Djurfeldt <address@hidden>,
Guile Development List <address@hidden>
Subject: Re: Another alternative string representation proposal
References: <address@hidden>
Mime-Version: 1.0 (generated by tm-edit 7.106)
Content-Type: text/plain; charset=US-ASCII
From: address@hidden (Carl R. Witty)
Date: 26 Sep 2000 11:12:54 -0700
In-Reply-To: Dirk Herrmann's message of "Tue, 26 Sep 2000 11:20:03 +0200 (MEST)"
Message-ID: <address@hidden>
Lines: 20
X-Mailer: Gnus v5.4.61/Emacs 19.34
Sender: address@hidden
Errors-To: address@hidden
X-BeenThere: address@hidden
X-Mailman-Version: 2.0beta6
Precedence: bulk
List-Help: <mailto:address@hidden>
List-Post: <mailto:address@hidden>
List-Subscribe: <http://mail.gnu.org/mailman/listinfo/guile-devel>,
<mailto:address@hidden>
List-Id: Developers list for Guile, the GNU extensibility library
<guile-devel.gnu.org>
List-Unsubscribe: <http://mail.gnu.org/mailman/listinfo/guile-devel>,
<mailto:address@hidden>
List-Archive: http://mail.gnu.org/pipermail/guile-devel/
Dirk Herrmann <address@hidden> writes:
> void
> g ()
> {
> char tmp_chars[4];
> SCM tmp_string = scm_make_mutable_not_owned_string (tmp_chars, 4);
>
> gh_display (f (tmp_string, 4));
> }
>
>
> It's obvious that this gives much better performance than having to allocate
> a small memory region just to have a mutable string.
I wouldn't want to maintain a program with code like the above. If
gh_display ever changed to hold on to its argument, you've got a nice
recipe for stack corruption.
Carl Witty