13.12 guile-tools doc-snarf

See Doc Extraction from Scheme Source, for discussion.

Usage: doc-snarf [OPTIONS] FILE

  -o, --output FILE  -- Specify output file [default=stdout]
  -t, --texinfo      -- Format output as texinfo
  -D, --dot-doc      -- Format output as GDFv1 .doc

This program reads in a Scheme source file and extracts docstrings
in the format specified below.  Additionally, a procedure protoype
is inferred from the procedure definition line starting with
(define... ).

Currently, three output modi are implemented: plaintext, texinfo
and GDFv1.  Default is plaintext, texinfo can be switched on with the
`--texinfo, -t' command line option, and GDFv1 with `--dot-doc, -D'.

A docstring is recognized: (1) as a comment block preceding and
"touching" a top-level `define' (or similar) form, with each line in
the comment beginning flush left and starting with two semicolons; or
(2) as a "standard internal docstring", i.e., a string occuring
immediately after the formals in the form.  If a form has both kinds
of docstring, then (2) takes precedence.  For example, the fragment:

  ;; This procedure foos, or bars, depending on @var{braz}.
  ;;-Author: Martin Grabmueller
  (define (foo/bar braz)
    (if braz 'foo 'bar))

results in the following docstring if texinfo output is enabled:

  ^Lfoo/bar
  @c snarfed from doc-snarf:81
  @deffn procedure foo/bar braz
  This procedure foos, or bars, depending on @var{braz}.
  @c Author: Martin Grabmueller
  @end deffn

or in this if plaintext output is used:

  Procedure: foo/bar braz
  This procedure foos, or bars, depending on BRAZ.
  ;; Author: Martin Grabmueller
  Snarfed from doc-snarf:81
  ^L

Note that for plaintext output, @var{foo} is replaced by FOO, in
both the docstring and the options.  Normally, if the signature of
a procedure ends in a dotted pair, the last symbol S is rendered as
"[S...]".  You can use the special option `sig' to override the
inferred signature.  For example:

  ;; Do something w/ @var{a} and optional arg @var{b}.
  ;;-sig: (a [b [c]])
  (define (my-proc a . rest) ...)

yields: (my-proc a [b [c]]).  Without `sig': (my-proc a [rest...]).


For Scheme programs, this module exports the following procs:
  (entry-symbol e) => symbol
  (entry-signature e) => string
  (entry-docstring e) => string
  (entry-options e [split]) => list of elements, either
                               "NAME: VALUE" or ("NAME" . "VALUE")
  (entry-filename e) => string
  (entry-line e) => integer
  (display-untexinfoized s)           ; see docstrings for these
  (format-texinfo entry)
  (format-dot-doc entry)
  (format-plain entry)
  (make-doc-snarfer formatter) => (lambda (file) ...)

If the provided format-* procs are not to your liking, you can use the
entry-* procs to create a custom formatter to pass to `make-doc-snarfer',
for example:

  (define (display-sig-and-docstring-only entry)
    (simple-format #t "(~A)~%~A~%"
                   (entry-signature entry)
                   (entry-docstring entry)))

  (define my-snarf (make-doc-snarfer display-sig-and-docstring-only))

  (for-each my-snarf (command-line-args))

The proc `display-untexinfoized' is useful for simple rendering of
@var and @code constructs, likely to be present in docstrings targeted
for "guile-tools twerp2texi" or other texinfo-based methodologies.


TODO: More parameterization.