From cecb4a5e9dbaebcc28f3be0a02feac4263a2cfcc Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Fri, 16 Nov 2001 09:55:54 +0000 Subject: [PATCH] * These changes add a @deffnx C function declaration and function index entries for each Guile primitive to the copy of the doc snarf output that is used for reference manual synchronization. Online help is unchanged. --- libguile/ChangeLog | 20 +++++++++++ libguile/Makefile.am | 10 ++++-- libguile/guile-snarf-docs-texi.in | 37 -------------------- libguile/snarf.h | 13 ++++---- scripts/ChangeLog | 18 ++++++++++ scripts/snarf-check-and-output-texi | 52 ++++++++++++++++++++++++----- 6 files changed, 96 insertions(+), 54 deletions(-) rewrite libguile/guile-snarf-docs-texi.in (100%) diff --git a/libguile/ChangeLog b/libguile/ChangeLog index 1d2388a79..d89307087 100644 --- a/libguile/ChangeLog +++ b/libguile/ChangeLog @@ -1,3 +1,23 @@ +2001-11-16 Neil Jerram + + These changes add a @deffnx C function declaration and function + index entries for each Guile primitive to the copy of the doc + snarf output that is used for reference manual synchronization. + Online help is unchanged. + + * snarf.h (SCM_SNARF_DOCS): Output primitive's C function name. + (SCM_DEFINE, SCM_DEFINE1, SCM_REGISTER_PROC): Supply to C function + name to SCM_SNARF_DOCS. + + * guile-snarf-docs-texi.in: Pass the shell script's arguments into + snarf-check-and-output-texi. + + * Makefile.am (guile-procedures.texi): New rule. + (BUILT_SOURCES, guile.texi, guile-procedures.txt, CLEANFILES): + Changed so that the last stage of doc snarfing is now performed + twice, once to produce guile-procedures.txt for online help, and + once to produce guile.texi for reference manual synchronization. + 2001-11-15 Dirk Herrmann * eval.c (RETURN): Wrap in do{}while(0) in order to make it diff --git a/libguile/Makefile.am b/libguile/Makefile.am index d894befda..fd7724ff5 100644 --- a/libguile/Makefile.am +++ b/libguile/Makefile.am @@ -88,7 +88,7 @@ DOT_DOC_FILES = alist.doc arbiters.doc async.doc backtrace.doc \ EXTRA_DOT_DOC_FILES = @EXTRA_DOT_DOC_FILES@ BUILT_SOURCES = cpp_err_symbols.c cpp_sig_symbols.c libpath.h scmconfig.h \ - $(DOT_X_FILES) $(EXTRA_DOT_X_FILES) + $(DOT_X_FILES) $(EXTRA_DOT_X_FILES) guile.texi EXTRA_libguile_la_SOURCES = _scm.h \ alloca.c inet_aton.c memmove.c putenv.c strerror.c \ @@ -207,10 +207,14 @@ posix.x: cpp_sig_symbols.c load.x: libpath.h guile.texi: $(DOT_DOC_FILES) $(EXTRA_DOT_DOC_FILES) guile-snarf-docs-texi.in guile + cat $(DOT_DOC_FILES) $(EXTRA_DOT_DOC_FILES) | ./guile-snarf-docs-texi --manual > $@ \ + || { rm $@; false; } + +guile-procedures.texi: $(DOT_DOC_FILES) $(EXTRA_DOT_DOC_FILES) guile-snarf-docs-texi.in guile cat $(DOT_DOC_FILES) $(EXTRA_DOT_DOC_FILES) | ./guile-snarf-docs-texi > $@ \ || { rm $@; false; } -guile-procedures.txt: guile.texi +guile-procedures.txt: guile-procedures.texi rm -f $@ makeinfo --force -o $@ $< || test -f $@ @@ -268,6 +272,6 @@ MOSTLYCLEANFILES = \ cpp_err_symbols_here cpp_err_symbols_diff cpp_err_symbols_new \ cpp_sig_symbols_here cpp_sig_symbols_diff cpp_sig_symbols_new -CLEANFILES = libpath.h *.x *.doc guile-procedures.txt guile.texi +CLEANFILES = libpath.h *.x *.doc guile-procedures.txt guile-procedures.texi guile.texi MAINTAINERCLEANFILES = c-tokenize.c diff --git a/libguile/guile-snarf-docs-texi.in b/libguile/guile-snarf-docs-texi.in dissimilarity index 100% index 6481534b2..e69de29bb 100755 --- a/libguile/guile-snarf-docs-texi.in +++ b/libguile/guile-snarf-docs-texi.in @@ -1,37 +0,0 @@ -#!/bin/sh -# Massage the snarfed docs to texinfo. -# -# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this software; see the file COPYING. If not, write to -# the Free Software Foundation, Inc., 59 Temple Place, Suite 330, -# Boston, MA 02111-1307 USA - -srcdir=@srcdir@ -bindir=`dirname $0` - -bindir=`(cd $bindir; pwd)` -srcdir=`(cd $srcdir; pwd)` - -echo "@paragraphindent 0" - -# run the script that will generate texinfo -main='(module-ref (resolve-module '\''(scripts snarf-check-and-output-texi)) '\''main)' -apply_main="(apply $main (cdr (command-line)))" - -if [ `basename ${bindir}` = libguile ]; then - GUILE_LOAD_PATH=${srcdir}/..; export GUILE_LOAD_PATH -fi - -${bindir}/guile -c "${apply_main}" diff --git a/libguile/snarf.h b/libguile/snarf.h index c44484b3a..4e9448484 100644 --- a/libguile/snarf.h +++ b/libguile/snarf.h @@ -76,13 +76,14 @@ #ifdef SCM_MAGIC_SNARF_INITS # define SCM_SNARF_HERE(X) # define SCM_SNARF_INIT(X) ^^ X -# define SCM_SNARF_DOCS(TYPE, FNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) +# define SCM_SNARF_DOCS(TYPE, CNAME, FNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) #else # ifdef SCM_MAGIC_SNARF_DOCS # define SCM_SNARF_HERE(X) # define SCM_SNARF_INIT(X) -# define SCM_SNARF_DOCS(TYPE, FNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) \ +# define SCM_SNARF_DOCS(TYPE, CNAME, FNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) \ ^^ { \ +cname CNAME ^^ \ fname FNAME ^^ \ type TYPE ^^ \ location __FILE__ __LINE__ ^^ \ @@ -92,7 +93,7 @@ DOCSTRING ^^ } # else # define SCM_SNARF_HERE(X) X # define SCM_SNARF_INIT(X) -# define SCM_SNARF_DOCS(TYPE, FNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) +# define SCM_SNARF_DOCS(TYPE, CNAME, FNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) # endif #endif @@ -105,7 +106,7 @@ SCM_SNARF_INIT(\ scm_c_define_gsubr (s_ ## FNAME, REQ, OPT, VAR, \ (SCM_FUNC_CAST_ARBITRARY_ARGS) FNAME); \ )\ -SCM_SNARF_DOCS(primitive, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) +SCM_SNARF_DOCS(primitive, FNAME, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING) #define SCM_DEFINE1(FNAME, PRIMNAME, TYPE, ARGLIST, DOCSTRING) \ SCM_SNARF_HERE(\ @@ -113,7 +114,7 @@ static const char s_ ## FNAME [] = PRIMNAME; \ SCM FNAME ARGLIST\ )\ SCM_SNARF_INIT(scm_c_define_subr (s_ ## FNAME, TYPE, FNAME); ) \ -SCM_SNARF_DOCS(1, PRIMNAME, ARGLIST, 2, 0, 0, DOCSTRING) +SCM_SNARF_DOCS(1, FNAME, PRIMNAME, ARGLIST, 2, 0, 0, DOCSTRING) #define SCM_PROC(RANAME, STR, REQ, OPT, VAR, CFN) \ SCM_SNARF_HERE(static const char RANAME[]=STR) \ @@ -124,7 +125,7 @@ SCM_SNARF_INIT(scm_c_define_gsubr (RANAME, REQ, OPT, VAR, \ SCM_SNARF_HERE(static const char RANAME[]=STR) \ SCM_SNARF_INIT(scm_c_define_gsubr (RANAME, REQ, OPT, VAR, \ (SCM_FUNC_CAST_ARBITRARY_ARGS) CFN);) \ -SCM_SNARF_DOCS(register, STR, (), REQ, OPT, VAR, \ +SCM_SNARF_DOCS(register, CFN, STR, (), REQ, OPT, VAR, \ "implemented by the C function \"" #CFN "\"") #define SCM_GPROC(RANAME, STR, REQ, OPT, VAR, CFN, GF) \ diff --git a/scripts/ChangeLog b/scripts/ChangeLog index 0aff09883..01dd7eb19 100644 --- a/scripts/ChangeLog +++ b/scripts/ChangeLog @@ -1,3 +1,21 @@ +2001-11-16 Neil Jerram + + These changes add a @deffnx C function declaration and function + index entries for each Guile primitive to the copy of the doc + snarf output that is used for reference manual synchronization. + Online help is unchanged. + + * snarf-check-and-output-texi (*manual-flag*, + snarf-check-and-output-texi): Handle `--manual' invocation arg + passed through from libguile/Makefile.am. + (*c-function-name*, begin-multiline, do-command): Pick out C + function name from snarfed token stream. + (end-multiline): Add @deffnx C declaration and function index + entries to output. + (*primitive-deffnx-signature*, *primitive-deffnx-sig-length*): + Fluff to help insert the C declaration after any "@deffnx + primitive" lines in the snarfed docstring. + 2001-10-05 Thien-Thi Nguyen * read-scheme-source (quoted?, clump): New procs, exported. diff --git a/scripts/snarf-check-and-output-texi b/scripts/snarf-check-and-output-texi index a300ca78e..f6ca78757 100755 --- a/scripts/snarf-check-and-output-texi +++ b/scripts/snarf-check-and-output-texi @@ -39,7 +39,11 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@" (define-macro (unless cond . body) `(if (not ,cond) (begin ,@body))) -(define (snarf-check-and-output-texi) +(define *manual-flag* #f) + +(define (snarf-check-and-output-texi . flags) + (if (memq '--manual flags) + (set! *manual-flag* #t)) (process-stream (current-input-port))) (define (process-stream port) @@ -122,6 +126,7 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@" (define *file* #f) (define *line* #f) +(define *c-function-name* #f) (define *function-name* #f) (define *snarf-type* #f) (define *args* #f) @@ -131,12 +136,16 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@" (define (begin-multiline) (set! *file* #f) (set! *line* #f) + (set! *c-function-name* #f) (set! *function-name* #f) (set! *snarf-type* #f) (set! *args* #f) (set! *sig* #f) (set! *docstring* #f)) +(define *primitive-deffnx-signature* "@deffnx primitive ") +(define *primitive-deffnx-sig-length* (string-length *primitive-deffnx-signature*)) + (define (end-multiline) (let* ((req (car *sig*)) (opt (cadr *sig*)) @@ -170,16 +179,40 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@" (if (not (null? tail)) (begin (format #t "~A" (car tail)) - (loop-tail (cdr tail))))))))))))))) + (loop-tail (cdr tail)))))))))))))) + (scm-deffnx + (if (and *manual-flag* (eq? *snarf-type* 'primitive)) + (with-output-to-string + (lambda () + (format #t "@deffnx function SCM ~A (" *c-function-name*) + (unless (null? *args*) + (format #t "SCM ~A" (car *args*)) + (let loop ((args (cdr *args*))) + (unless (null? args) + (format #t ", SCM ~A" (car args)) + (loop (cdr args))))) + (format #t ")\n"))) + #f))) (format #t "\n ~A\n" *function-name*) (format #t "@c snarfed from ~A:~A\n" *file* *line*) (format #t "@deffn primitive ~A\n" nice-sig) - (let loop ((strings *docstring*)) - (if (not (null? strings)) - (begin - (display (car strings)) - (loop (cdr strings))))) - (display "\n@end deffn\n")))) + (let loop ((strings *docstring*) (scm-deffnx scm-deffnx)) + (cond ((null? strings)) + ((or (not scm-deffnx) + (and (>= (string-length (car strings)) + *primitive-deffnx-sig-length*) + (string=? (substring (car strings) + 0 *primitive-deffnx-sig-length*) + *primitive-deffnx-signature*))) + (display (car strings)) + (loop (cdr strings) scm-deffnx)) + (else (display scm-deffnx) + (loop strings #f)))) + (display "\n") + (when *manual-flag* + (format #t "@findex ~A\n" *function-name*) + (format #t "@findex ~A\n" *c-function-name*)) + (display "@end deffn\n")))) (define (texi-quote s) (let rec ((i 0)) @@ -221,6 +254,9 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@" (define do-command (match-lambda + (('cname ('id . name)) + (set! *c-function-name* (texi-quote (symbol->string name)))) + (('fname ('string . name)) (set! *function-name* (texi-quote name))) -- 2.20.1