code:
.\" Written by Robert Merkel (rgmerk@mira.net)
.\" augmented by Rob Browning <rlb@cs.utexas.edu>
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH GUILE 1
.SH NAME
guile \- a Scheme interpreter
.SH SYNOPSIS
.B guile [-q] [-ds] [--help] [--version] [--emacs] [--debug]
.B [-l FILE] [-e FUNCTION] [\]
.B [-c EXPR] [-s SCRIPT] [--]
.SH DESCRIPTION
GNU Guile is an interpreter for the Scheme programming language.  It
implements R5RS, providing additional features
necessary for real-world use.  It is extremely simple to embed guile
into a C program, calling C from Scheme and Scheme from C.  Guile's
design makes it very suitable for use as an "extension" or "glue"
language, but it also works well as a stand-alone scheme development
environment.

The
.B guile
executable itself provides a stand-alone interpreter for scheme
programs, for either interactive use or executing scripts.

This manpage provides only brief instruction in invoking
.B guile
from the command line.  Please consult the guile info documentation
(type
.B info guile
at a command prompt) for more information.  There is also a tutorial
.B (info guile-tut)
available.

.SH OPTIONS
.IP -l FILE
Load scheme source code from file.
.IP -e FUNCTION
After reading script, apply FUNCTION to command-line arguments
.IP -ds
do -s SCRIPT at this point (note that this argument must be used in
conjuction with -s)
.IP --help
Describe command line options and exit
.IP --debug
Start guile with debugging evaluator and backtraces enabled
(useful for debugging guile scripts)
.IP --version
Display guile version and exit.
.IP --emacs
Enable emacs protocol for use from within emacs (experimental)
.IP --
Stop argument processing, start guile in interactive mode.
.IP -c EXPR
Stop argument processing, evaluate EXPR as a scheme expression.
.IP -s SCRIPT-FILE
Load Scheme source from SCRIPT-FILE and execute as a script.

.SH ENVIRONMENT
.\".TP \w'MANROFFSEQ\ \ 'u
.TP
.B GUILE_LOAD_PATH
If
.RB $ GUILE_LOAD_PATH
is set, its value is used to agument the path to search for scheme
files when loading.  It should be a colon separated list of
directories which will be prepended to the default %load-path.

.SH FILES
.I ~/.guile
is a guile script that is executed before any other processing occurs.
For example, the following .guile activates guile's readline
interface:

.RS 4
(use-modules (ice-9 readline))
.RS 0
(activate-readline)

.SH "SEE ALSO"
The full documentation for guile is maintained as a Texinfo manual.  If
the info and guile programs are properly installed at your site, the
command
.IP
.B info guile
.PP
should give you access to the complete manual.

http://www.schemers.org provides a general introduction to the
Scheme language.

.SH AUTHORS
Robert Merkel <rgmerk@mira.net> wrote this manpage.
Rob Browning <rlb@cs.utexas.edu> has added to it.

.B guile
is GNU software.  Guile is originally based on Aubrey Jaffer's
SCM interpreter, and is the work of many individuals.

license: mit


code:
;;;; hacks.el --- a few functions to help me work on the manual
;;;; Jim Blandy <jimb@red-bean.com> --- October 1998

(defun jh-exemplify-region (start end)
  (interactive "r")
  (save-excursion
    (save-restriction
      (narrow-to-region start end)

      ;; Texinfo doesn't handle tabs well.
      (untabify (point-min) (point-max))

      ;; Quote any characters special to texinfo.
      (goto-char (point-min))
      (while (re-search-forward "[{}@]" nil t)
	(replace-match "@\\&")))))


code:
2004-08-25  Marius Vollmer  <mvo@zagadka.de>

	* docstring.el (docstring-process-alist): Consider entries in
	reverse order.  That puts them in new-docstrings.texi in the same
	order as in the C source.

2004-08-23  Marius Vollmer  <marius.vollmer@uni-dortmund.de>

	* docstring.el: Replaced all "@c module" markers with "@c
	module-for-docstring", making it less likely to collide with a
	real commentary.

2002-10-19  Neil Jerram  <neil@ossau.uklinux.net>

	* guile.texi: Replaced by regenerated libguile version.

2002-07-10  Gary Houston  <ghouston@arglist.com>

	* docstring.el: optional 2nd environment variable to locate
	built files.

2002-07-09  Gary Houston  <ghouston@arglist.com>

	* docstring.el: defined caddr, used in several places but missing
	for some reason.

2002-04-02  Thien-Thi Nguyen  <ttn@giblet.glug.org>

	* doctring.el: List commands in commentary; nfc.

2002-03-15  Neil Jerram  <neil@ossau.uklinux.net>

	* guile.texi: Replaced by regenerated libguile version.

2002-03-12  Neil Jerram  <neil@ossau.uklinux.net>

	* guile.texi: Replaced by regenerated libguile version.

2002-03-08  Neil Jerram  <neil@ossau.uklinux.net>

	* docstring.el (docstring-libguile-directory,
	docstring-display-location, docstring-show-source): New.

2001-11-16  Neil Jerram  <neil@ossau.uklinux.net>

	* guile.texi: Replaced by regenerated libguile version.

	* docstring.el (make-module-description-list): Exclude @deffn's
	with category {C Function}.
	(docstring-process-alist): Bind key "d" to
	docstring-ediff-this-line in the docstring output buffer.

2001-11-13  Neil Jerram  <neil@ossau.uklinux.net>

	* guile.texi: Replaced by libguile version (after automatically
	updating docstrings in the reference manual).

2001-11-07  Neil Jerram  <neil@ossau.uklinux.net>

	* guile.texi: Replaced by libguile version (after automatically
	updating docstrings in the reference manual).

	* docstring.el (docstring-manual-directory): Added "/ref" to end.
	(docstring-manual-files): Now calculated automatically, since by
	definition all the .texi files in doc/ref are reference manual
	files.

2001-04-03  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>

	* guile.texi: Automated docstring merging.

2001-03-23  Neil Jerram  <neil@ossau.uklinux.net>

	* ChangeLog, README, docstring.el, guile.texi: New files.


code:
README for guile-core/doc/maint                      -*- text -*-

The files in this directory are used by the maintainers to automate
the process of updating the Guile reference manual when the docstrings
in the libguile C source change.

- ChangeLog is the change log for files in this directory.

- README is this file.

- docstring.el is a helpful Emacs Lisp library (see source for
  customization).  The two key entry points are:
    `docstring-process-module' and
    `docstring-ediff-this-line'.

- guile.texi is a snapshot of the built file libguile/guile.texi,
  copied last time the reference manual was determined to be in sync
  with the libguile source.

docstring.el requires the setting of an environment variable, e.g.,

export GUILE_MAINTAINER_GUILE_CORE_DIR=$HOME/guile/guile-core

If the build directory differs from the source directory, an additional
variable is required:

export GUILE_MAINTAINER_BUILD_CORE_DIR=$HOME/guile/guile-core-build

If you've just fixed a docstring in, say, ../libguile/strop.c, do in emacs:

    M-x load-file RET .../doc/maint/docstring.el RET
    M-x docstring-process-module RET (guile) RET

Save all modified .texi files and copy the current ../libguile/guile.texi
to ./guile.texi, then commit.  See elisp var `docstring-snarfed-roots'.

path: doc/maint/README


code:
;;; docstring.el --- utilities for Guile docstring maintenance
;;;
;;; Copyright (C) 2001, 2004 Neil Jerram
;;;
;;; This file is not part of GUILE, but the same permissions apply.
;;;
;;; GUILE is free software; you can redistribute it and/or modify it
;;; under the terms of the GNU Lesser General Public License as
;;; published by the Free Software Foundation; either version 3, or
;;; (at your option) any later version.
;;;
;;; GUILE 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
;;; Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with GUILE; see the file COPYING.LESSER.  If not,
;;; write to the Free Software Foundation, Inc., 51 Franklin Street,
;;; Fifth Floor, Boston, MA 02110-1301, USA.

;;; Commentary:

;; The basic premise of these utilities is that - at least in the
;; short term - we can get a lot of reference manual mileage by
;; co-opting the docstrings that are snarfed automatically from
;; Guile's C and Scheme source code.  But this leads to problems of
;; synchronization...  How do you track when a docstring has been
;; updated in the source and so needs updating in the reference
;; manual.  What if a procedure is removed from the Guile source?  And
;; so on.  To complicate matters, the exact snarfed docstring text
;; will probably need to be modified so that it fits into the flow of
;; the manual section in which it appears.  Can we design solutions to
;; synchronization problems that continue to work even when the manual
;; text has been enhanced in this way?
;;
;; This file implements an approach to this problem that I have found
;; useful.  It involves keeping track of three copies of each
;; docstring:
;;
;; "MANUAL"   = the docstring as it appears in the reference manual.
;;
;; "SNARFED"  = the docstring as snarfed from the current C or Scheme
;;              source.
;;
;; "TRACKING" = the docstring as it appears in a tracking file whose
;;              purpose is to record the most recent snarfed docstrings
;;              that are known to be in sync with the reference manual.
;;
;; The approaches are as follows.
;;
;; 1. Comparison of MANUAL-DOC, SOURCE-DOC and TRACK-DOC, to produce a
;;    summary output buffer in which keystrokes are defined to bring up
;;    detailed comparisons.
;;
;; 2. Comparison of MANUAL-DOC, SOURCE-DOC and TRACK-DOC using Ediff.
;;
;; Here is a brief list of commands available (via "M-x COMMAND"):
;;
;;    docstring-process-current-buffer
;;    docstring-process-current-region BEG END
;;    docstring-process-module MODULE
;;    docstring-ediff-this-line
;;    docstring-show-source

(defvar guile-core-dir (or (getenv "GUILE_MAINTAINER_GUILE_CORE_DIR")
			   (error "GUILE_MAINTAINER_GUILE_CORE_DIR not set"))
  "*Full path of guile-core source directory.")

(defvar guile-build-dir (or (getenv "GUILE_MAINTAINER_BUILD_CORE_DIR")
			   guile-core-dir)
  "*Full path of guile-core build directory.  Defaults to guile-core-dir.")

(defvar docstring-manual-directory (expand-file-name "doc/ref" guile-core-dir)
  "*The directory containing the Texinfo source for the Guile reference manual.")

(defvar docstring-tracking-root (expand-file-name "doc/maint" guile-core-dir)
  "*Root directory for docstring tracking files.  The tracking file
for module (a b c) is expected to be in the file
<docstring-tracking-root>/a/b/c.texi.")

(defvar docstring-snarfed-roots (mapcar
                                 #'(lambda (frag)
                                     (expand-file-name frag guile-build-dir))
                                 '("libguile" "ice-9" "oop"))
  "*List of possible root directories for snarfed docstring files.
For each entry in this list, the snarfed docstring file for module (a
b c) is looked for in the file <entry>/a/b/c.texi.")

(defvar docstring-manual-files
  (directory-files docstring-manual-directory nil "\\.texi$" t)
  "List of Texinfo source files that comprise the Guile reference manual.")

(defvar docstring-new-docstrings-file "new-docstrings.texi"
  "The name of a file in the Guile reference manual source directory
to which new docstrings should be added.")

;; Apply FN in turn to each element in the list CANDIDATES until the
;; first application that returns non-nil.
(defun or-map (fn candidates args)
  (let ((result nil))
    (while candidates
      (setq result (apply fn (car candidates) args))
      (if result
          (setq result (cons (car candidates) result)
                candidates nil)
        (setq candidates (cdr candidates))))
    result))

;; Return t if the current buffer position is in the scope of the
;; specified MODULE, as determined by "@c module-for-docstring ..." comments in the
;; buffer.  DEFAULT-OK specifies the return value in the case that
;; there are no preceding module comments at all.
(defun docstring-in-module (module default-ok)
  (save-excursion
    (if (re-search-backward "^@c module-for-docstring " nil t)
        (progn
          (search-forward "@c module-for-docstring ")
          (equal module (read (current-buffer))))
      default-ok)))

;; Find a docstring in the specified FILE-NAME for the item in module
;; MODULE and with description DESCRIPTION.  MODULE should be a list
;; of symbols, Guile-style, for example: '(ice-9 session).
;; DESCRIPTION should be the string that is expected after the @deffn,
;; for example "primitive acons" or "syntax let*".
(defun find-docstring (file-name module description)
  (and (file-exists-p file-name)
       (let ((buf (find-file-noselect file-name))
             (deffn-regexp (concat "^@deffnx? "
                                   (regexp-quote description)
                                   "[ \n\t]"))
             found
             result)
         (save-excursion
           (set-buffer buf)
           (goto-char (point-min))
           (while (and (not found)
                       (re-search-forward deffn-regexp nil t))
             (save-excursion
               (goto-char (match-beginning 0))
               (beginning-of-line)
               (if (docstring-in-module module t)
                   (setq found t))))
           (if found
               (setq result
                     (list (current-buffer)
                           (progn
                             (re-search-backward "^@deffn ")
                             (beginning-of-line)
                             (point))
                           (progn
                             (re-search-forward "^@end deffn")
                             (forward-line 1)
                             (point))))))
         result)))

;; Find the reference manual version of the specified docstring.
;; MODULE and DESCRIPTION specify the docstring as per
;; `find-docstring'.  The set of files that `find-manual-docstring'
;; searches is determined by the value of the `docstring-manual-files'
;; variable.
(defun find-manual-docstring (module description)
  (let* ((result
          (or-map 'find-docstring
                  (mapcar (function (lambda (file-name)
                                      (concat docstring-manual-directory
                                              "/"
                                              file-name)))
                          (cons docstring-new-docstrings-file
                                docstring-manual-files))
                  (list module
                        description)))
         (matched-file-name (and (cdr result)
                                 (file-name-nondirectory (car result)))))
    (if matched-file-name
        (setq docstring-manual-files
              (cons matched-file-name
                    (delete matched-file-name docstring-manual-files))))
    (cdr result)))

;; Convert MODULE to a directory subpath.
(defun module-to-path (module)
  (mapconcat (function (lambda (component)
                         (symbol-name component)))
             module
             "/"))

;; Find the current snarfed version of the specified docstring.
;; MODULE and DESCRIPTION specify the docstring as per
;; `find-docstring'.  The file that `find-snarfed-docstring' looks in
;; is automatically generated from MODULE.
(defun find-snarfed-docstring (module description)
  (let ((modpath (module-to-path module)))
    (cdr (or-map (function (lambda (root)
                             (find-docstring (concat root
                                                     "/"
                                                     modpath
                                                     ".texi")
                                             module
                                             description)))
                 docstring-snarfed-roots
                 nil))))

;; Find the tracking version of the specified docstring.  MODULE and
;; DESCRIPTION specify the docstring as per `find-docstring'.  The
;; file that `find-tracking-docstring' looks in is automatically
;; generated from MODULE.
(defun find-tracking-docstring (module description)
  (find-docstring (concat docstring-tracking-root
                          "/"
                          (module-to-path module)
                          ".texi")
                  module
                  description))

;; Extract an alist of modules and descriptions from the current
;; buffer.
(defun make-module-description-list ()
  (let ((alist nil)
        (module '(guile)))
    (save-excursion
      (goto-char (point-min))
      (while (re-search-forward "^\\(@c module-for-docstring \\|@deffnx? \\({[^}]+}\\|[^ ]+\\) \\([^ \n]+\\)\\)"
                                nil
                                t)
        (let ((matched (buffer-substring (match-beginning 1)
                                         (match-end 1))))
          (if (string-equal matched "@c module-for-docstring ")
              (setq module (read (current-buffer)))
	    (let ((type (buffer-substring (match-beginning 2)
					  (match-end 2))))
	      (if (string-equal type "{C Function}")
		  nil
		(setq matched
		      (concat type
			      " "
			      (buffer-substring (match-beginning 3)
						(match-end 3))))
		(message "Found docstring: %S: %s" module matched)
		(let ((descriptions (assoc module alist)))
		  (setq alist
			(cons (cons module (cons matched (cdr-safe descriptions)))
			      (if descriptions
				  (delete descriptions alist)
				alist))))))))))
    alist))

;; missing in some environments?
(defun caddr (list)
  (nth 2 list))

;; Return the docstring from the specified LOCATION.  LOCATION is a
;; list of three elements: buffer, start position and end position.
(defun location-to-docstring (location)
  (and location
       (save-excursion
         (set-buffer (car location))
         (buffer-substring (cadr location) (caddr location)))))

;; Perform a comparison of the specified docstring.  MODULE and
;; DESCRIPTION are as per usual.
(defun docstring-compare (module description)
  (let* ((manual-location (find-manual-docstring module description))
         (snarf-location (find-snarfed-docstring module description))
         (track-location (find-tracking-docstring module description))

         (manual-docstring (location-to-docstring manual-location))
         (snarf-docstring (location-to-docstring snarf-location))
         (track-docstring (location-to-docstring track-location))

         action
         issue)

    ;; Decide what to do.
    (cond ((null snarf-location)
           (setq action nil
                 issue (if manual-location
                           'consider-removal
                         nil)))

          ((null manual-location)
           (setq action 'add-to-manual issue nil))

          ((null track-location)
           (setq action nil
                 issue (if (string-equal manual-docstring snarf-docstring)
                           nil
                         'check-needed)))

          ((string-equal track-docstring snarf-docstring)
           (setq action nil issue nil))

          ((string-equal track-docstring manual-docstring)
           (setq action 'auto-update-manual issue nil))

          (t
           (setq action nil issue 'update-needed)))

    ;; Return a pair indicating any automatic action that can be
    ;; taken, and any issue for resolution.
    (cons action issue)))

;; Add the specified docstring to the manual.
(defun docstring-add-to-manual (module description)
  (let ((buf (find-file-noselect (concat docstring-manual-directory
                                         "/"
                                         docstring-new-docstrings-file))))
    (save-excursion
      (set-buffer buf)
      (goto-char (point-max))
      (or (docstring-in-module module nil)
          (insert "\n@c module-for-docstring " (prin1-to-string module) "\n"))
      (insert "\n" (location-to-docstring (find-snarfed-docstring module
                                                                  description))))))

;; Auto-update the specified docstring in the manual.
(defun docstring-auto-update-manual (module description)
  (let ((manual-location (find-manual-docstring module description))
        (track-location (find-tracking-docstring module description)))
    (save-excursion
      (set-buffer (car manual-location))
      (goto-char (cadr manual-location))
      (delete-region (cadr manual-location) (caddr manual-location))
      (insert (location-to-docstring (find-snarfed-docstring module
                                                             description))))))

;; Process an alist of modules and descriptions, and produce a summary
;; buffer describing actions taken and issues to be resolved.
(defun docstring-process-alist (alist)
  (let (check-needed-list
        update-needed-list
        consider-removal-list
        added-to-manual-list
        auto-updated-manual-list)

    (mapcar
     (function (lambda (module-list)
                 (let ((module (car module-list)))
                   (message "Module: %S" module)
                   (mapcar
                    (function (lambda (description)
                                (message "Comparing docstring: %S: %s" module description)
                                (let* ((ai (docstring-compare module description))
                                       (action (car ai))
                                       (issue (cdr ai)))

                                  (cond ((eq action 'add-to-manual)
                                         (docstring-add-to-manual module description)
                                         (setq added-to-manual-list
                                               (cons (cons module description)
                                                     added-to-manual-list)))

                                        ((eq action 'auto-update-manual)
                                         (docstring-auto-update-manual module description)
                                         (setq auto-updated-manual-list
                                               (cons (cons module description)
                                                     auto-updated-manual-list))))

                                  (cond ((eq issue 'check-needed)
                                         (setq check-needed-list
                                               (cons (cons module description)
                                                     check-needed-list)))

                                        ((eq issue 'update-needed)
                                         (setq update-needed-list
                                               (cons (cons module description)
                                                     update-needed-list)))

                                        ((eq issue 'consider-removal)
                                         (setq consider-removal-list
                                               (cons (cons module description)
                                                     consider-removal-list)))))))
                    (reverse (cdr module-list))))))
     alist)

    ;; Prepare a buffer describing the results.
    (set-buffer (get-buffer-create "*Docstring Results*"))
    (erase-buffer)

    (insert "
The following items have been automatically added to the manual in
file `" docstring-manual-directory "/" docstring-new-docstrings-file "'.\n\n")
    (if added-to-manual-list
	(mapcar (function (lambda (moddesc)
			    (insert (prin1-to-string (car moddesc))
                                    ": "
                                    (cdr moddesc)
                                    "\n")))
		added-to-manual-list)
      (insert "(none)\n"))

    (insert "
The following items have been automatically updated in the manual.\n\n")
    (if auto-updated-manual-list
	(mapcar (function (lambda (moddesc)
			    (insert (prin1-to-string (car moddesc))
                                    ": "
                                    (cdr moddesc)
                                    "\n")))
		auto-updated-manual-list)
      (insert "(none)\n"))

    (insert "
The following items are already documented in the manual but are not
mentioned in the reference copy of the snarfed docstrings file.
You should check that the manual documentation matches the docstring
in the current snarfed docstrings file.\n\n")
    (if check-needed-list
	(mapcar (function (lambda (moddesc)
			    (insert (prin1-to-string (car moddesc))
                                    ": "
                                    (cdr moddesc)
                                    "\n")))
		check-needed-list)
      (insert "(none)\n"))

    (insert "
The following items have manual documentation that is different from
the docstring in the reference copy of the snarfed docstrings file,
and the snarfed docstring has changed.  You need to update the manual
documentation by hand with reference to the snarfed docstring changes.\n\n")
    (if update-needed-list
	(mapcar (function (lambda (moddesc)
			    (insert (prin1-to-string (car moddesc))
                                    ": "
                                    (cdr moddesc)
                                    "\n")))
		update-needed-list)
      (insert "(none)\n"))

    (insert "
The following items are documented in the manual but are no longer
present in the snarfed docstrings file.  You should consider whether
the existing manual documentation is still pertinent.  If it is, its
docstring module comment may need updating, to connect it with a
new snarfed docstring file.\n\n")
    (if consider-removal-list
	(mapcar (function (lambda (moddesc)
			    (insert (prin1-to-string (car moddesc))
                                    ": "
                                    (cdr moddesc)
                                    "\n")))
		consider-removal-list)
      (insert "(none)\n"))
    (insert "\n")

    (goto-char (point-min))
    (local-set-key "d" 'docstring-ediff-this-line)

    ;; Popup the issues buffer.
    (let ((pop-up-frames t))
      (set-window-point (display-buffer (current-buffer))
			(point-min)))))

(defun docstring-process-current-buffer ()
  (interactive)
  (docstring-process-alist (make-module-description-list)))

(defun docstring-process-current-region (beg end)
  (interactive "r")
  (narrow-to-region beg end)
  (unwind-protect
      (save-excursion
        (docstring-process-alist (make-module-description-list)))
    (widen)))

(defun docstring-process-module (module)
  (interactive "xModule: ")
  (let ((modpath (module-to-path module))
        (mdlist nil))
    (mapcar (function (lambda (root)
                        (let ((fn (concat root
                                          "/"
                                          modpath
                                          ".texi")))
                          (if (file-exists-p fn)
                              (save-excursion
                                (find-file fn)
                                (message "Getting docstring list from %s" fn)
                                (setq mdlist
                                      (append mdlist
                                              (make-module-description-list))))))))
            docstring-snarfed-roots)
    (docstring-process-alist mdlist)))

(defun docstring-ediff-this-line ()
  (interactive)
  (let (module
        description)
    (save-excursion
      (beginning-of-line)
      (setq module (read (current-buffer)))
      (forward-char 2)
      (setq description (buffer-substring (point)
                                          (progn
                                            (end-of-line)
                                            (point)))))

    (message "Ediff docstring: %S: %s" module description)

    (let ((track-location (or (find-tracking-docstring module description)
                              (docstring-temp-location "No docstring in tracking file")))
          (snarf-location (or (find-snarfed-docstring module description)
                              (docstring-temp-location "No docstring in snarfed file")))
          (manual-location (or (find-manual-docstring module description)
                               (docstring-temp-location "No docstring in manual"))))

      (setq docstring-ediff-buffers
            (list (car track-location)
                  (car snarf-location)
                  (car manual-location)))

      (docstring-narrow-to-location track-location)
      (docstring-narrow-to-location snarf-location)
      (docstring-narrow-to-location manual-location)

      (add-hook 'ediff-quit-hook 'docstring-widen-ediff-buffers)

    (ediff-buffers3 (nth 0 docstring-ediff-buffers)
		    (nth 1 docstring-ediff-buffers)
		    (nth 2 docstring-ediff-buffers)))))

(defun docstring-narrow-to-location (location)
  (save-excursion
    (set-buffer (car location))
    (narrow-to-region (cadr location) (caddr location))))

(defun docstring-temp-location (str)
  (let ((buf (generate-new-buffer "*Docstring Temp*")))
    (save-excursion
      (set-buffer buf)
      (erase-buffer)
      (insert str "\n")
      (list buf (point-min) (point-max)))))

(require 'ediff)

(defvar docstring-ediff-buffers '())

(defun docstring-widen-ediff-buffers ()
  (remove-hook 'ediff-quit-hook 'docstring-widen-ediff-buffers)
  (save-excursion
    (mapcar (function (lambda (buffer)
			(set-buffer buffer)
			(widen)))
	    docstring-ediff-buffers)))

;;; Tests:

;(find-docstring "/home/neil/Guile/cvs/guile-core/doc/maint/guile.texi" nil "primitive sloppy-assq")
;(find-manual-docstring '(guile) "primitive sloppy-assq")
;(find-tracking-docstring '(guile) "primitive sloppy-assq")
;(find-snarfed-docstring '(guile) "primitive sloppy-assq")

(defvar docstring-libguile-directory (expand-file-name "libguile"
						       guile-core-dir)
  "*The directory containing the C source for libguile.")

(defvar docstring-libguile-build-directory (expand-file-name "libguile"
							     guile-build-dir)
  "*The directory containing the libguile build directory.")

(defun docstring-display-location (file line)
  (let ((buffer (find-file-noselect
		 (expand-file-name file docstring-libguile-directory))))
    (if buffer
	(let* ((window (or (get-buffer-window buffer)
			   (display-buffer buffer)))
	       (pos (save-excursion
		      (set-buffer buffer)
		      (goto-line line)
		      (point))))
	  (set-window-point window pos)))))

(defun docstring-show-source ()
  "Given that point is sitting in a docstring in one of the Texinfo
source files for the Guile manual, and that that docstring may be
snarfed automatically from a libguile C file, determine whether the
docstring is from libguile and, if it is, display the relevant C file
at the line from which the docstring was snarfed.

Why?  When updating snarfed docstrings, you should usually edit the C
source rather than the Texinfo source, so that your updates benefit
Guile's online help as well.  This function locates the C source for a
docstring so that it is easy for you to do this."
  (interactive)
  (let* ((deffn-line
	   (save-excursion
	     (end-of-line)
	     (or (re-search-backward "^@deffn " nil t)
		 (error "No docstring here!"))
	     (buffer-substring (point)
			       (progn
				 (end-of-line)
				 (point)))))
	 (guile-texi-file
	  (expand-file-name "guile.texi" docstring-libguile-build-directory))
	 (source-location
	  (save-excursion
	    (set-buffer (find-file-noselect guile-texi-file))
	    (save-excursion
	      (goto-char (point-min))
	      (or (re-search-forward (concat "^"
					     (regexp-quote deffn-line)
					     "$")
				     nil t)
		  (error "Docstring not from libguile"))
	      (forward-line -1)
	      (if (looking-at "^@c snarfed from \\([^:]+\\):\\([0-9]+\\)$")
		  (cons (match-string 1)
			(string-to-int (match-string 2)))
		(error "Corrupt docstring entry in guile.texi"))))))
    (docstring-display-location (car source-location)
				(cdr source-location))))

(provide 'docstring)

;;; docstring.el ends here