* docstring.el (docstring-libguile-directory,

docstring-display-location, docstring-show-source): New.

doc/maint/ChangeLog

@@ -1,3 +1,8 @@
+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.

doc/maint/docstring.el

@@ -539,6 +539,64 @@ new snarfed docstring file.\n\n")
 ;(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.")
+
+(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-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