* Automatic docstring updates.

* Commit utilities and tracking files for automatic docstring updates.

doc/ChangeLog

@@ -1,3 +1,11 @@
+2001-03-23  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* posix.texi, scheme-data.texi, scheme-evaluation.texi,
+	scheme-io.texi, scheme-memory.texi: Automatic docstring updates.
+
+	* new-docstrings.texi: New file.  Holds snarfed docstrings that
+	have not yet been incorporated into the reference manual.
+
 2001-03-20  Martin Grabmueller  <mgrabmue@cs.tu-berlin.de>
 
 	* scheme-options.texi (Evaluator options): Added evaluator

doc/maint/ChangeLog

@@ -0,0 +1,4 @@
+2001-03-23  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* ChangeLog, README, docstring.el, guile.texi: New files.
+

doc/maint/README

@@ -0,0 +1,16 @@
+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.  The usual entry point
+  is `docstring-process-current-buffer'.
+
+- guile.texi is a snapshot of the built file
+  guile-core/libguile/guile.texi, copied last time the reference
+  manual was determined to be in sync with the libguile source.

doc/maint/docstring.el

@@ -0,0 +1,563 @@
+;;; docstring.el --- utilities for Guile docstring maintenance
+;;;
+;;; Copyright (C) 2001 Neil Jerram
+;;;
+;;; This file is not part of GNU Emacs, but the same permissions apply.
+;;;
+;;; GNU Emacs 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.
+;;;
+;;; GNU Emacs 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 GNU Emacs; see the file COPYING.  If not, write to the
+;;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+;;; Boston, MA 02111-1307, 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.
+
+;;; Code:
+
+(defvar docstring-manual-directory (expand-file-name "~/Guile/cvs/guile-core/doc")
+  "*The directory containing the Texinfo source for the Guile reference manual.")
+
+(defvar docstring-tracking-root (expand-file-name "~/Guile/cvs/guile-core/doc/maint")
+  "*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 (list (expand-file-name "~/Guile/cvs/guile-core/libguile")
+                                      (expand-file-name "~/Guile/cvs/guile-core/ice-9")
+                                      (expand-file-name "~/Guile/cvs/guile-core/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 '("appendices.texi"
+				 "deprecated.texi"
+				 "expect.texi"
+				 "gh.texi"
+				 "goops.texi"
+				 "guile.texi"
+				 "indices.texi"
+				 "intro.texi"
+				 "posix.texi"
+				 "scheme-binding.texi"
+				 "scheme-control.texi"
+				 "scheme-data.texi"
+				 "scheme-debug.texi"
+				 "scheme-evaluation.texi"
+				 "scheme-ideas.texi"
+				 "scheme-indices.texi"
+				 "scheme-intro.texi"
+				 "scheme-io.texi"
+				 "scheme-memory.texi"
+				 "scheme-modules.texi"
+				 "scheme-options.texi"
+				 "scheme-procedures.texi"
+				 "scheme-reading.texi"
+				 "scheme-scheduling.texi"
+				 "scheme-translation.texi"
+				 "scheme-utility.texi"
+				 "scm.texi"
+				 "scripts.texi"
+				 "scsh.texi"
+				 "slib.texi"
+				 "tcltk.texi")
+  "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 ..." 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 " nil t)
+        (progn
+          (search-forward "@c module ")
+          (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 \\|@deffnx? \\({[^}]+}\\|[^ ]+\\) \\([^ \n]+\\)\\)"
+                                nil
+                                t)
+        (let ((matched (buffer-substring (match-beginning 1)
+                                         (match-end 1))))
+          (if (string-equal matched "@c module ")
+              (setq module (read (current-buffer)))
+            (setq matched
+                  (concat (buffer-substring (match-beginning 2)
+                                            (match-end 2))
+                          " "
+                          (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))
+
+;; 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 " (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)))))))
+                    (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))
+
+    ;; 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")
+
+(provide 'docstring)

doc/new-docstrings.texi

@@ -0,0 +1,599 @@
+
+@c module (guile)
+
+@deffn primitive environment? obj
+Return @code{#t} if @var{obj} is an environment, or @code{#f}
+otherwise.
+@end deffn
+
+@deffn primitive environment-bound? env sym
+Return @code{#t} if @var{sym} is bound in @var{env}, or
+@code{#f} otherwise.
+@end deffn
+
+@deffn primitive environment-ref env sym
+Return the value of the location bound to @var{sym} in
+@var{env}. If @var{sym} is unbound in @var{env}, signal an
+@code{environment:unbound} error.
+@end deffn
+
+@deffn primitive environment-fold env proc init
+Iterate over all the bindings in @var{env}, accumulating some
+value.
+For each binding in @var{env}, apply @var{proc} to the symbol
+bound, its value, and the result from the previous application
+of @var{proc}.
+Use @var{init} as @var{proc}'s third argument the first time
+@var{proc} is applied.
+If @var{env} contains no bindings, this function simply returns
+@var{init}.
+If @var{env} binds the symbol sym1 to the value val1, sym2 to
+val2, and so on, then this procedure computes:
+@example
+  (proc sym1 val1
+        (proc sym2 val2
+              ...
+              (proc symn valn
+                    init)))
+@end example
+Each binding in @var{env} will be processed exactly once.
+@code{environment-fold} makes no guarantees about the order in
+which the bindings are processed.
+Here is a function which, given an environment, constructs an
+association list representing that environment's bindings,
+using environment-fold:
+@example
+  (define (environment->alist env)
+    (environment-fold env
+                      (lambda (sym val tail)
+                        (cons (cons sym val) tail))
+                      '()))
+@end example
+@end deffn
+
+@deffn primitive environment-define env sym val
+Bind @var{sym} to a new location containing @var{val} in
+@var{env}. If @var{sym} is already bound to another location
+in @var{env} and the binding is mutable, that binding is
+replaced.  The new binding and location are both mutable. The
+return value is unspecified.
+If @var{sym} is already bound in @var{env}, and the binding is
+immutable, signal an @code{environment:immutable-binding} error.
+@end deffn
+
+@deffn primitive environment-undefine env sym
+Remove any binding for @var{sym} from @var{env}. If @var{sym}
+is unbound in @var{env}, do nothing.  The return value is
+unspecified.
+If @var{sym} is already bound in @var{env}, and the binding is
+immutable, signal an @code{environment:immutable-binding} error.
+@end deffn
+
+@deffn primitive environment-set! env sym val
+If @var{env} binds @var{sym} to some location, change that
+location's value to @var{val}.  The return value is
+unspecified.
+If @var{sym} is not bound in @var{env}, signal an
+@code{environment:unbound} error.  If @var{env} binds @var{sym}
+to an immutable location, signal an
+@code{environment:immutable-location} error.
+@end deffn
+
+@deffn primitive environment-cell env sym for_write
+Return the value cell which @var{env} binds to @var{sym}, or
+@code{#f} if the binding does not live in a value cell.
+The argument @var{for-write} indicates whether the caller
+intends to modify the variable's value by mutating the value
+cell.  If the variable is immutable, then
+@code{environment-cell} signals an
+@code{environment:immutable-location} error.
+If @var{sym} is unbound in @var{env}, signal an
+@code{environment:unbound} error.
+If you use this function, you should consider using
+@code{environment-observe}, to be notified when @var{sym} gets
+re-bound to a new value cell, or becomes undefined.
+@end deffn
+
+@deffn primitive environment-observe env proc
+Whenever @var{env}'s bindings change, apply @var{proc} to
+@var{env}.
+This function returns an object, token, which you can pass to
+@code{environment-unobserve} to remove @var{proc} from the set
+of procedures observing @var{env}.  The type and value of
+token is unspecified.
+@end deffn
+
+@deffn primitive environment-observe-weak env proc
+This function is the same as environment-observe, except that
+the reference @var{env} retains to @var{proc} is a weak
+reference. This means that, if there are no other live,
+non-weak references to @var{proc}, it will be
+garbage-collected, and dropped from @var{env}'s
+list of observing procedures.
+@end deffn
+
+@deffn primitive environment-unobserve token
+Cancel the observation request which returned the value
+@var{token}.  The return value is unspecified.
+If a call @code{(environment-observe env proc)} returns
+@var{token}, then the call @code{(environment-unobserve token)}
+will cause @var{proc} to no longer be called when @var{env}'s
+bindings change.
+@end deffn
+
+@deffn primitive make-leaf-environment
+Create a new leaf environment, containing no bindings.
+All bindings and locations created in the new environment
+will be mutable.
+@end deffn
+
+@deffn primitive leaf-environment? object
+Return @code{#t} if object is a leaf environment, or @code{#f}
+otherwise.
+@end deffn
+
+@deffn primitive make-eval-environment local imported
+Return a new environment object eval whose bindings are the
+union of the bindings in the environments @var{local} and
+@var{imported}, with bindings from @var{local} taking
+precedence. Definitions made in eval are placed in @var{local}.
+Applying @code{environment-define} or
+@code{environment-undefine} to eval has the same effect as
+applying the procedure to @var{local}.
+Note that eval incorporates @var{local} and @var{imported} by
+reference:
+If, after creating eval, the program changes the bindings of
+@var{local} or @var{imported}, those changes will be visible
+in eval.
+Since most Scheme evaluation takes place in eval environments,
+they transparently cache the bindings received from @var{local}
+and @var{imported}. Thus, the first time the program looks up
+a symbol in eval, eval may make calls to @var{local} or
+@var{imported} to find their bindings, but subsequent
+references to that symbol will be as fast as references to
+bindings in finite environments.
+In typical use, @var{local} will be a finite environment, and
+@var{imported} will be an import environment
+@end deffn
+
+@deffn primitive eval-environment? object
+Return @code{#t} if object is an eval environment, or @code{#f}
+otherwise.
+@end deffn
+
+@deffn primitive eval-environment-local env
+Return the local environment of eval environment @var{env}.
+@end deffn
+
+@deffn primitive eval-environment-set-local! env local
+Change @var{env}'s local environment to @var{local}.
+@end deffn
+
+@deffn primitive eval-environment-imported env
+Return the imported environment of eval environment @var{env}.
+@end deffn
+
+@deffn primitive eval-environment-set-imported! env imported
+Change @var{env}'s imported environment to @var{imported}.
+@end deffn
+
+@deffn primitive make-import-environment imports conflict_proc
+Return a new environment @var{imp} whose bindings are the union
+of the bindings from the environments in @var{imports};
+@var{imports} must be a list of environments. That is,
+@var{imp} binds a symbol to a location when some element of
+@var{imports} does.
+If two different elements of @var{imports} have a binding for
+the same symbol, the @var{conflict-proc} is called with the
+following parameters:  the import environment, the symbol and
+the list of the imported environments that bind the symbol.
+If the @var{conflict-proc} returns an environment @var{env},
+the conflict is considered as resolved and the binding from
+@var{env} is used.  If the @var{conflict-proc} returns some
+non-environment object, the conflict is considered unresolved
+and the symbol is treated as unspecified in the import
+environment.
+The checking for conflicts may be performed lazily, i. e. at
+the moment when a value or binding for a certain symbol is
+requested instead of the moment when the environment is
+created or the bindings of the imports change.
+All bindings in @var{imp} are immutable. If you apply
+@code{environment-define} or @code{environment-undefine} to
+@var{imp}, Guile will signal an
+ @code{environment:immutable-binding} error. However,
+notice that the set of bindings in @var{imp} may still change,
+if one of its imported environments changes.
+@end deffn
+
+@deffn primitive import-environment? object
+Return @code{#t} if object is an import environment, or
+@code{#f} otherwise.
+@end deffn
+
+@deffn primitive import-environment-imports env
+Return the list of environments imported by the import
+environment @var{env}.
+@end deffn
+
+@deffn primitive import-environment-set-imports! env imports
+Change @var{env}'s list of imported environments to
+@var{imports}, and check for conflicts.
+@end deffn
+
+@deffn primitive make-export-environment private signature
+Return a new environment @var{exp} containing only those
+bindings in private whose symbols are present in
+@var{signature}. The @var{private} argument must be an
+environment.
+
+The environment @var{exp} binds symbol to location when
+@var{env} does, and symbol is exported by @var{signature}.
+
+@var{signature} is a list specifying which of the bindings in
+@var{private} should be visible in @var{exp}. Each element of
+@var{signature} should be a list of the form:
+  (symbol attribute ...)
+where each attribute is one of the following:
+@table @asis
+@item the symbol @code{mutable-location}
+  @var{exp} should treat the
+  location bound to symbol as mutable. That is, @var{exp}
+  will pass calls to @code{environment-set!} or
+  @code{environment-cell} directly through to private.
+@item the symbol @code{immutable-location}
+  @var{exp} should treat
+  the location bound to symbol as immutable. If the program
+  applies @code{environment-set!} to @var{exp} and symbol, or
+  calls @code{environment-cell} to obtain a writable value
+  cell, @code{environment-set!} will signal an
+  @code{environment:immutable-location} error. Note that, even
+  if an export environment treats a location as immutable, the
+  underlying environment may treat it as mutable, so its
+  value may change.
+@end table
+It is an error for an element of signature to specify both
+@code{mutable-location} and @code{immutable-location}. If
+neither is specified, @code{immutable-location} is assumed.
+
+As a special case, if an element of signature is a lone
+symbol @var{sym}, it is equivalent to an element of the form
+@code{(sym)}.
+
+All bindings in @var{exp} are immutable. If you apply
+@code{environment-define} or @code{environment-undefine} to
+@var{exp}, Guile will signal an
+@code{environment:immutable-binding} error. However,
+notice that the set of bindings in @var{exp} may still change,
+if the bindings in private change.
+@end deffn
+
+@deffn primitive export-environment? object
+Return @code{#t} if object is an export environment, or
+@code{#f} otherwise.
+@end deffn
+
+@deffn primitive export-environment-private env
+Return the private environment of export environment @var{env}.
+@end deffn
+
+@deffn primitive export-environment-set-private! env private
+Change the private environment of export environment @var{env}.
+@end deffn
+
+@deffn primitive export-environment-signature env
+Return the signature of export environment @var{env}.
+@end deffn
+
+@deffn primitive export-environment-set-signature! env signature
+Change the signature of export environment @var{env}.
+@end deffn
+
+@deffn primitive %compute-slots class
+Return a list consisting of the names of all slots belonging to
+class @var{class}, i. e. the slots of @var{class} and of all of
+its superclasses.
+@end deffn
+
+@deffn primitive get-keyword key l default_value
+Determine an associated value for the keyword @var{key} from
+the list @var{l}.  The list @var{l} has to consist of an even
+number of elements, where, starting with the first, every
+second element is a keyword, followed by its associated value.
+If @var{l} does not hold a value for @var{key}, the value
+@var{default_value} is returned.
+@end deffn
+
+@deffn primitive slot-ref-using-class class obj slot_name
+@end deffn
+
+@deffn primitive slot-set-using-class! class obj slot_name value
+@end deffn
+
+@deffn primitive class-of x
+Return the class of @var{x}.
+@end deffn
+
+@deffn primitive %goops-loaded
+Announce that GOOPS is loaded and perform initialization
+on the C level which depends on the loaded GOOPS modules.
+@end deffn
+
+@deffn primitive %method-more-specific? m1 m2 targs
+@end deffn
+
+@deffn primitive find-method . l
+@end deffn
+
+@deffn primitive primitive-generic-generic subr
+@end deffn
+
+@deffn primitive enable-primitive-generic! . subrs
+@end deffn
+
+@deffn primitive generic-capability? proc
+@end deffn
+
+@deffn primitive %invalidate-method-cache! gf
+@end deffn
+
+@deffn primitive %invalidate-class class
+@end deffn
+
+@deffn primitive %modify-class old new
+@end deffn
+
+@deffn primitive %modify-instance old new
+@end deffn
+
+@deffn primitive %set-object-setter! obj setter
+@end deffn
+
+@deffn primitive %allocate-instance class initargs
+Create a new instance of class @var{class} and initialize it
+from the arguments @var{initargs}.
+@end deffn
+
+@deffn primitive slot-exists? obj slot_name
+Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
+@end deffn
+
+@deffn primitive slot-bound? obj slot_name
+Return @code{#t} if the slot named @var{slot_name} of @var{obj}
+is bound.
+@end deffn
+
+@deffn primitive slot-set! obj slot_name value
+Set the slot named @var{slot_name} of @var{obj} to @var{value}.
+@end deffn
+
+@deffn primitive slot-exists-using-class? class obj slot_name
+@end deffn
+
+@deffn primitive slot-bound-using-class? class obj slot_name
+@end deffn
+
+@deffn primitive %fast-slot-set! obj index value
+Set the slot with index @var{index} in @var{obj} to
+@var{value}.
+@end deffn
+
+@deffn primitive %fast-slot-ref obj index
+Return the slot value with index @var{index} from @var{obj}.
+@end deffn
+
+@deffn primitive @@assert-bound-ref obj index
+Like @code{assert-bound}, but use @var{index} for accessing
+the value from @var{obj}.
+@end deffn
+
+@deffn primitive assert-bound value obj
+Return @var{value} if it is bound, and invoke the
+@var{slot-unbound} method of @var{obj} if it is not.
+@end deffn
+
+@deffn primitive unbound? obj
+Return @code{#t} if @var{obj} is unbound.
+@end deffn
+
+@deffn primitive make-unbound
+Return the unbound value.
+@end deffn
+
+@deffn primitive accessor-method-slot-definition obj
+Return the slot definition of the accessor @var{obj}.
+@end deffn
+
+@deffn primitive method-procedure obj
+Return the procedure of the method @var{obj}.
+@end deffn
+
+@deffn primitive method-specializers obj
+Return specializers of the method @var{obj}.
+@end deffn
+
+@deffn primitive method-generic-function obj
+Return the generic function fot the method @var{obj}.
+@end deffn
+
+@deffn primitive generic-function-methods obj
+Return the methods of the generic function @var{obj}.
+@end deffn
+
+@deffn primitive generic-function-name obj
+Return the name of the generic function @var{obj}.
+@end deffn
+
+@deffn primitive class-environment obj
+Return the environment of the class @var{obj}.
+@end deffn
+
+@deffn primitive class-slots obj
+Return the slot list of the class @var{obj}.
+@end deffn
+
+@deffn primitive class-precedence-list obj
+Return the class precedence list of the class @var{obj}.
+@end deffn
+
+@deffn primitive class-direct-methods obj
+Return the direct methods of the class @var{obj}
+@end deffn
+
+@deffn primitive class-direct-subclasses obj
+Return the direct subclasses of the class @var{obj}.
+@end deffn
+
+@deffn primitive class-direct-slots obj
+Return the direct slots of the class @var{obj}.
+@end deffn
+
+@deffn primitive class-direct-supers obj
+Return the direct superclasses of the class @var{obj}.
+@end deffn
+
+@deffn primitive class-name obj
+Return the class name of @var{obj}.
+@end deffn
+
+@deffn primitive instance? obj
+Return @code{#t} if @var{obj} is an instance.
+@end deffn
+
+@deffn primitive %inherit-magic! class dsupers
+@end deffn
+
+@deffn primitive %prep-layout! class
+@end deffn
+
+@deffn primitive %initialize-object obj initargs
+Initialize the object @var{obj} with the given arguments
+@var{initargs}.
+@end deffn
+
+@deffn primitive make . args
+Make a new object.  @var{args} must contain the class and
+all necessary initialization information.
+@end deffn
+
+@deffn primitive slot-ref obj slot_name
+Return the value from @var{obj}'s slot with the name
+@var{slot_name}.
+@end deffn
+
+@deffn primitive builtin-bindings
+Create and return a copy of the global symbol table, removing all
+unbound symbols.
+@end deffn
+
+@deffn primitive object->string obj [printer]
+Return a Scheme string obtained by printing @var{obj}.
+Printing function can be specified by the optional second
+argument @var{printer} (default: @code{write}).
+@end deffn
+
+@deffn primitive gethostname
+Return the host name of the current processor.
+@end deffn
+
+@deffn primitive sethostname name
+Set the host name of the current processor to @var{name}. May
+only be used by the superuser.  The return value is not
+specified.
+@end deffn
+
+@deffn primitive flock file operation
+Apply or remove an advisory lock on an open file.
+@var{operation} specifies the action to be done:
+@table @code
+@item LOCK_SH
+Shared lock.  More than one process may hold a shared lock
+for a given file at a given time.
+@item LOCK_EX
+Exclusive lock.  Only one process may hold an exclusive lock
+for a given file at a given time.
+@item LOCK_UN
+Unlock the file.
+@item LOCK_NB
+Don't block when locking.  May be specified by bitwise OR'ing
+it to one of the other operations.
+@end table
+The return value is not specified. @var{file} may be an open
+file descriptor or an open file descriptior port.
+@end deffn
+
+@deffn primitive getpass prompt
+Display @var{prompt} to the standard error output and read
+a password from @file{/dev/tty}.  If this file is not
+accessible, it reads from standard input.  The password may be
+up to 127 characters in length.  Additional characters and the
+terminating newline character are discarded.  While reading
+the password, echoing and the generation of signals by special
+characters is disabled.
+@end deffn
+
+@deffn primitive setpriority which who prio
+Set the scheduling priority of the process, process group
+or user, as indicated by @var{which} and @var{who}. @var{which}
+is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
+or @code{PRIO_USER}, and @var{who} is interpreted relative to
+@var{which} (a process identifier for @code{PRIO_PROCESS},
+process group identifier for @code{PRIO_PGRP}, and a user
+identifier for @code{PRIO_USER}.  A zero value of @var{who}
+denotes the current process, process group, or user.
+@var{prio} is a value in the range -20 and 20, the default
+priority is 0; lower priorities cause more favorable
+scheduling.  Sets the priority of all of the specified
+processes.  Only the super-user may lower priorities.
+The return value is not specified.
+@end deffn
+
+@deffn primitive getpriority which who
+Return the scheduling priority of the process, process group
+or user, as indicated by @var{which} and @var{who}. @var{which}
+is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
+or @code{PRIO_USER}, and @var{who} is interpreted relative to
+@var{which} (a process identifier for @code{PRIO_PROCESS},
+process group identifier for @code{PRIO_PGRP}, and a user
+identifier for @code{PRIO_USER}.  A zero value of @var{who}
+denotes the current process, process group, or user.  Return
+the highest priority (lowest numerical value) of any of the
+specified processes.
+@end deffn
+
+@deffn primitive cuserid
+Return a string containing a user name associated with the
+effective user id of the process.  Return @code{#f} if this
+information cannot be obtained.
+@end deffn
+
+@deffn primitive getlogin
+Return a string containing the name of the user logged in on
+the controlling terminal of the process, or @code{#f} if this
+information cannot be obtained.
+@end deffn
+
+@deffn primitive chroot path
+Change the root directory to that specified in @var{path}.
+This directory will be used for path names beginning with
+@file{/}.  The root directory is inherited by all children
+of the current process.  Only the superuser may change the
+root directory.
+@end deffn
+
+@deffn primitive crypt key salt
+Encrypt @var{key} using @var{salt} as the salt value to the
+crypt(3) library call
+@end deffn
+
+@deffn primitive mkstemp! tmpl
+mkstemp creates a new unique file in the file system and
+returns a new buffered port open for reading and writing to
+the file.  @var{tmpl} is a string specifying where the
+file should be created: it must end with @code{XXXXXX}
+and will be changed in place to return the name of the
+temporary file.
+@end deffn
+
+@deffn primitive %tag-body body
+Internal GOOPS magic---don't use this function!
+@end deffn

doc/posix.texi

@@ -760,9 +760,11 @@ The return value is unspecified.
 
 @c docstring begin (texi-doc-string "guile" "tmpnam")
 @deffn primitive tmpnam
-Create a new file in the file system with a unique name.  The return
+tmpnam returns a name in the file system that does not match
-value is the name of the new file.  This function is implemented with
+any existing file.  However there is no guarantee that
-the @code{tmpnam} function in the system libraries.
+another process will not create the file after tmpnam
+is called.  Care should be taken if opening the file,
+e.g., use the O_EXCL open flag or use @code{mkstemp!} instead.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "dirname")
@@ -1469,8 +1471,8 @@ of seconds remaining otherwise.
 
 @c docstring begin (texi-doc-string "guile" "usleep")
 @deffn primitive usleep i
-Sleep for I microseconds.
+Sleep for I microseconds.  @code{usleep} is not available on
-`usleep' is not available on all platforms.
+all platforms.
 @end deffn
 
 @node Terminals and Ptys

doc/scheme-data.texi

@@ -274,8 +274,8 @@ completely invisible to the Scheme level programmer.
 @c on the C level, where the conversion is not so automatic - NJ
 
 @c docstring begin (texi-doc-string "guile" "integer?")
-@deffn primitive integer? obj
+@deffn primitive integer? x
-Return @code{#t} if @var{obj} is an integer number, @code{#f} else.
+Return @code{#t} if @var{x} is an integer number, @code{#f} else.
 
 @lisp
 (integer? 487)
@@ -343,11 +343,13 @@ if @var{obj} is an integer number or a rational number.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "rational?")
-@deffn primitive rational? obj
+@deffn primitive rational? x
-Return @code{#t} if @var{obj} is a rational number, @code{#f} else.
+Return @code{#t} if @var{x} is a rational number, @code{#f}
-Note that the set of integer values forms a subset of the set of
+else.  Note that the set of integer values forms a subset of
-rational numbers, so the predicate will also be fulfilled if @var{obj}
+the set of rational numbers, i. e. the predicate will also be
-is an integer number.
+fulfilled if @var{x} is an integer number.  Real numbers
+will also satisfy this predicate, because of their limited
+precision.
 @end deffn
 
 
@@ -379,11 +381,12 @@ real, so the real and imaginary parts of a complex number have the same
 properties of inexactness and limited precision as single real numbers.
 
 @c docstring begin (texi-doc-string "guile" "complex?")
-@deffn primitive complex? obj
+@deffn primitive complex? x
-Return @code{#t} if @var{obj} is a complex number, @code{#f} else.
+Return @code{#t} if @var{x} is a complex number, @code{#f}
-Note that the sets of real, rational and integer values form subsets of
+else.  Note that the sets of real, rational and integer
-the set of complex numbers, so the predicate will also be fulfilled if
+values form subsets of the set of complex numbers, i. e. the
-@var{obj} is a real, rational or integer number.
+predicate will also be fulfilled if @var{x} is a real,
+rational or integer number.
 @end deffn
 
 
@@ -404,12 +407,14 @@ an invocation of the @code{inexact->exact} procedure.
 
 @c docstring begin (texi-doc-string "guile" "exact?")
 @deffn primitive exact? x
-Return #t if X is an exact number, #f otherwise.
+Return @code{#t} if @var{x} is an exact number, @code{#f}
+otherwise.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "inexact?")
 @deffn primitive inexact? x
-Return #t if X is an inexact number, #f else.
+Return @code{#t} if @var{x} is an inexact number, @code{#f}
+else.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "inexact->exact")
@@ -502,12 +507,14 @@ multiplying by 10^N.
 
 @c docstring begin (texi-doc-string "guile" "odd?")
 @deffn primitive odd? n
-Return #t if N is an odd number, #f otherwise.
+Return @code{#t} if @var{n} is an odd number, @code{#f}
+otherwise.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "even?")
 @deffn primitive even? n
-Return #t if N is an even number, #f otherwise.
+Return @code{#t} if @var{n} is an even number, @code{#f}
+otherwise.
 @end deffn
 
 @c begin (texi-doc-string "guile" "quotient")
@@ -608,19 +615,20 @@ zero.
 @c docstring begin (texi-doc-string "guile" "number->string")
 @deffn primitive number->string n [radix]
 Return a string holding the external representation of the
-number N in the given RADIX.  If N is inexact, a radix of 10
+number @var{n} in the given @var{radix}.  If @var{n} is
-will be used.
+inexact, a radix of 10 will be used.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "string->number")
 @deffn primitive string->number string [radix]
 Returns a number of the maximally precise representation
-expressed by the given STRING. RADIX must be an exact integer,
+expressed by the given @var{string}. @var{radix} must be an
-either 2, 8, 10, or 16. If supplied, RADIX is a default radix
+exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}
-that may be overridden by an explicit radix prefix in STRING
+is a default radix that may be overridden by an explicit radix
-(e.g. "#o177"). If RADIX is not supplied, then the default
+prefix in @var{string} (e.g. "#o177"). If @var{radix} is not
-radix is 10. If string is not a syntactically valid notation
+supplied, then the default radix is 10. If string is not a
-for a number, then `string->number' returns #f.  (r5rs)
+syntactically valid notation for a number, then
+@code{string->number} returns @code{#f}.
 @end deffn
 
 
@@ -635,13 +643,13 @@ for a number, then `string->number' returns #f.  (r5rs)
 
 @c docstring begin (texi-doc-string "guile" "make-rectangular")
 @deffn primitive make-rectangular real imaginary
-Return a complex number constructed of the given REAL and
+Return a complex number constructed of the given @var{real} and
-IMAGINARY parts.
+@var{imaginary} parts.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "make-polar")
 @deffn primitive make-polar x y
-Return the complex number X * e^(i * Y).
+Return the complex number @var{x} * e^(i * @var{y}).
 @end deffn
 
 @c begin (texi-doc-string "guile" "real-part")
@@ -1026,15 +1034,16 @@ Example:
 @c ARGFIXME n/int cnt/count
 @c docstring begin (texi-doc-string "guile" "ash")
 @deffn primitive ash n cnt
-The function ash performs an arithmetic shift left by CNT bits
+The function ash performs an arithmetic shift left by @var{CNT}
-(or shift right, if CNT is negative).  'Arithmetic' means, that
+bits (or shift right, if @var{cnt} is negative).
-the function does not guarantee to keep the bit structure of N,
+'Arithmetic' means, that the function does not guarantee to
-but rather guarantees that the result will always be rounded
+keep the bit structure of @var{n}, but rather guarantees that
-towards minus infinity.  Therefore, the results of ash and a
+the result will always be rounded towards minus infinity.
-corresponding bitwise shift will differ if N is negative.
+Therefore, the results of ash and a corresponding bitwise
+shift will differ if N is negative.
 
 Formally, the function returns an integer equivalent to
-@code{(inexact->exact (floor (* N (expt 2 CNT))))}.@refill
+@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
 
 Example:
 @lisp
@@ -1481,7 +1490,7 @@ a portion of the string.  This procedure essentially implements the
 
 (qdocs:)  Returns the index of @var{char} in @var{str}, or @code{#f} if the
 @var{char} isn't in @var{str}. If @var{frm} is given and not @code{#f},
-it is used as the starting index; if @var{to} is given and not @var{#f},
+it is used as the starting index; if @var{to} is given and not @code{#f},
 it is used as the ending index (exclusive).
 
 @example
@@ -1695,7 +1704,7 @@ Capitalize every character in @code{str}.
 @c docstring begin (texi-doc-string "guile" "string-ci<=?")
 @deffn primitive string-ci<=? s1 s2
 Case insensitive lexicographic ordering predicate;
-returns @t{#t} if @var{s1} is lexicographically less than
+returns @code{#t} if @var{s1} is lexicographically less than
 or equal to @var{s2} regardless of case.  (r5rs)
 @end deffn
 
@@ -1703,72 +1712,77 @@ or equal to @var{s2} regardless of case.  (r5rs)
 @c docstring begin (texi-doc-string "guile" "string-ci<?")
 @deffn primitive string-ci<? s1 s2
 Case insensitive lexicographic ordering predicate;
-returns @t{#t} if @var{s1} is lexicographically less than
+returns @code{#t} if @var{s1} is lexicographically less than
 @var{s2} regardless of case.  (r5rs)
 @end deffn
 
 @r5index string-ci=?
 @c docstring begin (texi-doc-string "guile" "string-ci=?")
 @deffn primitive string-ci=? s1 s2
-Case-insensitive string equality predicate; returns @t{#t} if
+Case-insensitive string equality predicate; returns @code{#t}
-the two strings are the same length and their component characters
+if the two strings are the same length and their component
-match (ignoring case) at each position; otherwise returns @t{#f}. (r5rs)
+characters match (ignoring case) at each position; otherwise
+returns @code{#f}. (r5rs)
 @end deffn
 
 @r5index string-ci>=?
 @c docstring begin (texi-doc-string "guile" "string-ci>=?")
 @deffn primitive string-ci>=? s1 s2
 Case insensitive lexicographic ordering predicate;
-returns @t{#t} if @var{s1} is lexicographically greater than
+returns @code{#t} if @var{s1} is lexicographically greater
-or equal to @var{s2} regardless of case.  (r5rs)
+than or equal to @var{s2} regardless of case.  (r5rs)
 @end deffn
 
 @r5index string-ci>?
 @c docstring begin (texi-doc-string "guile" "string-ci>?")
 @deffn primitive string-ci>? s1 s2
 Case insensitive lexicographic ordering predicate;
-returns @t{#t} if @var{s1} is lexicographically greater than
+returns @code{#t} if @var{s1} is lexicographically greater
-@var{s2} regardless of case.  (r5rs)
+than @var{s2} regardless of case.  (r5rs)
 @end deffn
 
 @r5index string<=?
 @c docstring begin (texi-doc-string "guile" "string<=?")
 @deffn primitive string<=? s1 s2
-Lexicographic ordering predicate; returns @t{#t} if @var{s1}
+Lexicographic ordering predicate; returns @code{#t} if
-is lexicographically less than or equal to @var{s2}.  (r5rs)
+@var{s1} is lexicographically less than or equal to @var{s2}.
+(r5rs)
 @end deffn
 
 @r5index string<?
 @c docstring begin (texi-doc-string "guile" "string<?")
 @deffn primitive string<? s1 s2
-Lexicographic ordering predicate; returns @t{#t} if @var{s1}
+Lexicographic ordering predicate; returns @code{#t} if
-is lexicographically less than @var{s2}.  (r5rs)
+@var{s1} is lexicographically less than @var{s2}.  (r5rs)
 @end deffn
 
 @r5index string=?
 @c docstring begin (texi-doc-string "guile" "string=?")
 @deffn primitive string=? s1 s2
 Lexicographic equality predicate;
-Returns @t{#t} if the two strings are the same length and contain the same
+Returns @code{#t} if the two strings are the same length and
-characters in the same positions, otherwise returns @t{#f}. (r5rs)
+contain the same characters in the same positions, otherwise
+returns @code{#f}. (r5rs)
 
-@samp{String-ci=?} treats
+The procedure @code{string-ci=?} treats upper and lower case
-upper and lower case letters as though they were the same character, but
+letters as though they were the same character, but
-@samp{string=?} treats upper and lower case as distinct characters.
+@code{string=?} treats upper and lower case as distinct
+characters.
 @end deffn
 
 @r5index string>=?
 @c docstring begin (texi-doc-string "guile" "string>=?")
 @deffn primitive string>=? s1 s2
-Lexicographic ordering predicate; returns @t{#t} if @var{s1}
+Lexicographic ordering predicate; returns @code{#t} if
-is lexicographically greater than or equal to @var{s2}.  (r5rs)
+@var{s1} is lexicographically greater than or equal to
+@var{s2}.  (r5rs)
 @end deffn
 
 @r5index string>?
 @c docstring begin (texi-doc-string "guile" "string>?")
 @deffn primitive string>? s1 s2
-Lexicographic ordering predicate; returns @t{#t} if @var{s1}
+Lexicographic ordering predicate; returns @code{#t} if
-is lexicographically greater than @var{s2}.  (r5rs)
+@var{s1} is lexicographically greater than @var{s2}.  (r5rs)
 @end deffn
 
 @r5index string->list
@@ -2452,57 +2466,48 @@ Returns the symbol whose name is @var{string}.  This procedure can
 create symbols with names containing special characters or letters in
 the non-standard case, but it is usually a bad idea to create such
 symbols because in some implementations of Scheme they cannot be read as
-themselves.  See @samp{symbol->string}.
+themselves.  See @code{symbol->string}.
 
-The following examples assume that the implementation's standard case is
+The following examples assume that the implementation's
-lower case:
+standard case is lower case:
 
-@format
+@lisp
-@t{(eq? 'mISSISSIppi 'mississippi)
+(eq? 'mISSISSIppi 'mississippi) @result{} #t
-          ==>  #t
+(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
-(string->symbol "mISSISSIppi")
+(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
-          ==>
-  @r{}the symbol with name "mISSISSIppi"
-(eq? 'bitBlt (string->symbol "bitBlt"))
-          ==>  #f
 (eq? 'JollyWog
-     (string->symbol
+  (string->symbol (symbol->string 'JollyWog))) @result{} #t
-       (symbol->string 'JollyWog)))
-          ==>  #t
 (string=? "K. Harper, M.D."
-          (symbol->string
+  (symbol->string
-            (string->symbol "K. Harper, M.D.")))
+    (string->symbol "K. Harper, M.D."))) @result{}#t
-          ==>  #t
+@end lisp
-}
-@end format
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "symbol->string")
-@deffn primitive symbol->string symbol
+@deffn primitive symbol->string s
-Returns the name of @var{symbol} as a string.  If the symbol was part of
+Returns the name of @var{symbol} as a string.  If the symbol
-an object returned as the value of a literal expression (section
+was part of an object returned as the value of a literal
-@pxref{Literal expressions,,,r4rs, The Revised^4 Report on Scheme}) or
+expression (section @pxref{Literal expressions,,,r4rs, The
-by a call to the @samp{read} procedure, and its name contains alphabetic
+Revised^4 Report on Scheme}) or by a call to the @code{read}
-characters, then the string returned will contain characters in the
+procedure, and its name contains alphabetic characters, then
-implementation's preferred standard case---some implementations will
+the string returned will contain characters in the
-prefer upper case, others lower case.  If the symbol was returned by
+implementation's preferred standard case---some implementations
-@samp{string->symbol}, the case of characters in the string returned
+will prefer upper case, others lower case.  If the symbol was
-will be the same as the case in the string that was passed to
+returned by @code{string->symbol}, the case of characters in
-@samp{string->symbol}.  It is an error to apply mutation procedures like
+the string returned will be the same as the case in the string
-@code{string-set!} to strings returned by this procedure. (r5rs)
+that was passed to @code{string->symbol}.  It is an error to
+apply mutation procedures like @code{string-set!} to strings
+returned by this procedure. (r5rs)
 
-The following examples assume that the implementation's standard case is
+The following examples assume that the implementation's
-lower case:
+standard case is lower case:
 
-@format
+@lisp
-@t{(symbol->string 'flying-fish)
+(symbol->string 'flying-fish) @result{} "flying-fish"
-                                ==>  "flying-fish"
+(symbol->string 'Martin)      @result{}  "martin"
-(symbol->string 'Martin)               ==>  "martin"
 (symbol->string
-   (string->symbol "Malvina"))
+   (string->symbol "Malvina")) @result{} "Malvina"
-                           ==>  "Malvina"
+@end lisp
-}
-@end format
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "symbol-binding")
@@ -2515,11 +2520,12 @@ use the global symbol table.  If @var{string} is not interned in
 
 @c docstring begin (texi-doc-string "guile" "symbol-bound?")
 @deffn primitive symbol-bound? obarray string
-Return @var{#t} if @var{obarray} contains a symbol with name
+Return @code{#t} if @var{obarray} contains a symbol with name
 @var{string} bound to a defined value.  This differs from
-@var{symbol-interned?} in that the mere mention of a symbol usually causes
+@var{symbol-interned?} in that the mere mention of a symbol
-it to be interned; @code{symbol-bound?} determines whether a symbol has
+usually causes it to be interned; @code{symbol-bound?}
-been given any meaningful value.
+determines whether a symbol has been given any meaningful
+value.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "symbol-fref")
@@ -2539,8 +2545,8 @@ Return a hash value for @var{symbol}.
 
 @c docstring begin (texi-doc-string "guile" "symbol-interned?")
 @deffn primitive symbol-interned? obarray string
-Return @var{#t} if @var{obarray} contains a symbol with name
+Return @code{#t} if @var{obarray} contains a symbol with name
-@var{string}, and @var{#f} otherwise.
+@var{string}, and @code{#f} otherwise.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "symbol-pref")
@@ -2562,7 +2568,8 @@ in @var{obarray}.
 
 @c docstring begin (texi-doc-string "guile" "symbol?")
 @deffn primitive symbol? obj
-Returns @t{#t} if @var{obj} is a symbol, otherwise returns @t{#f}. (r5rs)
+Returns @code{#t} if @var{obj} is a symbol, otherwise returns
+@code{#f}. (r5rs)
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "unintern-symbol")
@@ -2905,53 +2912,51 @@ by @code{set-cdr!} is unspecified.
 
 @c docstring begin (texi-doc-string "guile" "list")
 @deffn primitive list . objs
-Return a list containing OBJS, the arguments to `list'.
+Return a list containing @var{objs}, the arguments to
+@code{list}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "cons*")
 @deffn primitive cons* arg . rest
-@deffnx primitive list* arg . rest
+Like @code{list}, but the last arg provides the tail of the
-Like `list', but the last arg provides the tail of the constructed list,
+constructed list, returning @code{(cons @var{arg1} (cons
-returning (cons ARG1 (cons ARG2 (cons ... ARGn))).
+@var{arg2} (cons @dots{} @var{argn}))).  Requires at least one
-Requires at least one argument.  If given one argument, that argument
+argument.  If given one argument, that argument is returned as
-is returned as result.
+result.  This function is called @code{list*} in some other
-This function is called `list*' in some other Schemes and in Common LISP.
+Schemes and in Common LISP.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "list?")
 @deffn primitive list? x
-Return #t iff X is a proper list, else #f.
+Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "null?")
 @deffn primitive null? x
-Return #t iff X is the empty list, else #f.
+Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "length")
 @deffn primitive length lst
-Return the number of elements in list LST.
+Return the number of elements in list @var{lst}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "append")
 @deffn primitive append . args
-Returns a list consisting of the elements of the first LIST
+Return a list consisting of the elements the lists passed as
-followed by the elements of the other LISTs.
+arguments.
-
 @example
-  (append '(x) '(y))          =>  (x y)
+(append '(x) '(y))          @result{}  (x y)
-  (append '(a) '(b c d))      =>  (a b c d)
+(append '(a) '(b c d))      @result{}  (a b c d)
-  (append '(a (b)) '((c)))    =>  (a (b) (c))
+(append '(a (b)) '((c)))    @result{}  (a (b) (c))
 @end example
-
+The resulting list is always newly allocated, except that it
-The resulting list is always newly allocated, except that it shares
+shares structure with the last list argument.  The last
-structure with the last LIST argument.  The last argument may
+argument may actually be any object; an improper list results
-actually be any object; an improper list results if the last
+if the last argument is not a proper list.
-argument is not a proper list.
-
 @example
-  (append '(a b) '(c . d))    =>  (a b c . d)
+(append '(a b) '(c . d))    @result{}  (a b c . d)
-  (append '() 'a)             =>  a
+(append '() 'a)             @result{}  a
 @end example
 @end deffn
 
@@ -2972,7 +2977,8 @@ Return a pointer to the last pair in @var{lst}, signalling an error if
 
 @c docstring begin (texi-doc-string "guile" "reverse")
 @deffn primitive reverse lst
-Return a new list that contains the elements of LST but in reverse order.
+Return a new list that contains the elements of @var{lst} but
+in reverse order.
 @end deffn
 
 @c NJFIXME explain new_tail
@@ -2993,7 +2999,7 @@ of the modified list is not lost, it is wise to save the return value of
 
 @c docstring begin (texi-doc-string "guile" "list-ref")
 @deffn primitive list-ref list k
-Return the Kth element from LIST.
+Return the @var{k}th element from @var{list}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "list-set!")
@@ -3031,53 +3037,56 @@ Return a (newly-created) copy of @var{lst}.
 
 @c docstring begin (texi-doc-string "guile" "memq")
 @deffn primitive memq x lst
-Return the first sublist of LST whose car is `eq?' to X
+Return the first sublist of @var{lst} whose car is @code{eq?}
-where the sublists of LST are the non-empty lists returned
+to @var{x} where the sublists of @var{lst} are the non-empty
-by `(list-tail LST K)' for K less than the length of LST.  If
+lists returned by @code{(list-tail @var{lst} @var{k})} for
-X does not occur in LST, then `#f' (not the empty list) is
+@var{k} less than the length of @var{lst}.  If @var{x} does not
+occur in @var{lst}, then @code{#f} (not the empty list) is
 returned.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "memv")
 @deffn primitive memv x lst
-Return the first sublist of LST whose car is `eqv?' to X
+Return the first sublist of @var{lst} whose car is @code{eqv?}
-where the sublists of LST are the non-empty lists returned
+to @var{x} where the sublists of @var{lst} are the non-empty
-by `(list-tail LST K)' for K less than the length of LST.  If
+lists returned by @code{(list-tail @var{lst} @var{k})} for
-X does not occur in LST, then `#f' (not the empty list) is
+@var{k} less than the length of @var{lst}.  If @var{x} does not
+occur in @var{lst}, then @code{#f} (not the empty list) is
 returned.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "member")
 @deffn primitive member x lst
-Return the first sublist of LST whose car is `equal?' to X
+Return the first sublist of @var{lst} whose car is
-where the sublists of LST are the non-empty lists returned
+@code{equal?} to @var{x} where the sublists of @var{lst} are
-by `(list-tail LST K)' for K less than the length of LST.  If
+the non-empty lists returned by @code{(list-tail @var{lst}
-X does not occur in LST, then `#f' (not the empty list) is
+@var{k})} for @var{k} less than the length of @var{lst}.  If
-returned.
+@var{x} does not occur in @var{lst}, then @code{#f} (not the
+empty list) is returned.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "delq")
 @deffn primitive delq item lst
-Return a newly-created copy of @var{lst} with elements `eq?' to @var{item} removed.
+Return a newly-created copy of @var{lst} with elements
-This procedure mirrors @code{memq}:
+@code{eq?} to @var{item} removed.  This procedure mirrors
-@code{delq} compares elements of @var{lst} against @var{item} with
+@code{memq}: @code{delq} compares elements of @var{lst} against
-@code{eq?}.
+@var{item} with @code{eq?}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "delv")
 @deffn primitive delv item lst
-Return a newly-created copy of @var{lst} with elements `eqv?' to @var{item} removed.
+Return a newly-created copy of @var{lst} with elements
-This procedure mirrors @code{memv}:
+@code{eqv?}  to @var{item} removed.  This procedure mirrors
-@code{delv} compares elements of @var{lst} against @var{item} with
+@code{memv}: @code{delv} compares elements of @var{lst} against
-@code{eqv?}.
+@var{item} with @code{eqv?}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "delete")
 @deffn primitive delete item lst
-Return a newly-created copy of @var{lst} with elements `equal?' to @var{item} removed.
+Return a newly-created copy of @var{lst} with elements
-This procedure mirrors @code{member}:
+@code{equal?}  to @var{item} removed.  This procedure mirrors
-@code{delete} compares elements of @var{lst} against @var{item} with
+@code{member}: @code{delete} compares elements of @var{lst}
-@code{equal?}.
+against @var{item} with @code{equal?}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "delq!")
@@ -3096,20 +3105,23 @@ destructive list functions, these functions cannot modify the binding of
 
 @c docstring begin (texi-doc-string "guile" "delq1!")
 @deffn primitive delq1! item lst
-Like `delq!', but only deletes the first occurrence of ITEM from LST.
+Like @code{delq!}, but only deletes the first occurrence of
-Tests for equality using `eq?'.  See also `delv1!' and `delete1!'.
+@var{item} from @var{lst}.  Tests for equality using
+@code{eq?}.  See also @code{delv1!} and @code{delete1!}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "delv1!")
 @deffn primitive delv1! item lst
-Like `delv!', but only deletes the first occurrence of ITEM from LST.
+Like @code{delv!}, but only deletes the first occurrence of
-Tests for equality using `eqv?'.  See also `delq1!' and `delete1!'.
+@var{item} from @var{lst}.  Tests for equality using
+@code{eqv?}.  See also @code{delq1!} and @code{delete1!}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "delete1!")
 @deffn primitive delete1! item lst
-Like `delete!', but only deletes the first occurrence of ITEM from LST.
+Like @code{delete!}, but only deletes the first occurrence of
-Tests for equality using `equal?'.  See also `delq1!' and `delv1!'.
+@var{item} from @var{lst}.  Tests for equality using
+@code{equal?}.  See also @code{delq1!} and @code{delv1!}.
 @end deffn
 
 [FIXME: is there any reason to have the `sloppy' functions available at
@@ -3450,7 +3462,8 @@ For more information, see the documentation for @code{make-vtable-vtable}.
 
 @c docstring begin (texi-doc-string "guile" "struct?")
 @deffn primitive struct? x
-Return #t iff @var{obj} is a structure object, else #f.
+Return @code{#t} iff @var{obj} is a structure object, else
+@code{#f}.
 @end deffn
 
 
@@ -3486,7 +3499,7 @@ Return the vtable structure that describes the type of @var{struct}.
 
 @c docstring begin (texi-doc-string "guile" "struct-vtable?")
 @deffn primitive struct-vtable? x
-Return #t iff obj is a vtable structure.
+Return @code{#t} iff obj is a vtable structure.
 @end deffn
 
 If you have a vtable structure, @code{V}, you can create an instance of
@@ -4543,8 +4556,8 @@ any Scheme object.
 @deffn primitive hashq-ref table obj [dflt]
 Look up @var{key} in the hash table @var{table}, and return the
 value (if any) associated with it.  If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument is
+return @var{default} (or @code{#f} if no @var{default} argument
-supplied).  Uses `eq?' for equality testing.
+is supplied).  Uses @code{eq?} for equality testing.
 @end deffn
 
 @c ARGFIXME obj/key
@@ -4552,8 +4565,8 @@ supplied).  Uses `eq?' for equality testing.
 @deffn primitive hashv-ref table obj [dflt]
 Look up @var{key} in the hash table @var{table}, and return the
 value (if any) associated with it.  If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument is
+return @var{default} (or @code{#f} if no @var{default} argument
-supplied).  Uses `eqv?' for equality testing.
+is supplied).  Uses @code{eqv?} for equality testing.
 @end deffn
 
 @c ARGFIXME obj/key
@@ -4561,50 +4574,51 @@ supplied).  Uses `eqv?' for equality testing.
 @deffn primitive hash-ref table obj [dflt]
 Look up @var{key} in the hash table @var{table}, and return the
 value (if any) associated with it.  If @var{key} is not found,
-return @var{default} (or @code{#f} if no @var{default} argument is
+return @var{default} (or @code{#f} if no @var{default} argument
-supplied).  Uses `equal?' for equality testing.
+is supplied).  Uses @code{equal?} for equality testing.
 @end deffn
 
 @c ARGFIXME obj/key
 @c docstring begin (texi-doc-string "guile" "hashq-set!")
 @deffn primitive hashq-set! table obj val
-Find the entry in @var{table} associated with @var{key}, and store
+Find the entry in @var{table} associated with @var{key}, and
-@var{value} there. Uses `eq?' for equality testing.
+store @var{value} there. Uses @code{eq?} for equality testing.
 @end deffn
 
 @c ARGFIXME obj/key
 @c docstring begin (texi-doc-string "guile" "hashv-set!")
 @deffn primitive hashv-set! table obj val
-Find the entry in @var{table} associated with @var{key}, and store
+Find the entry in @var{table} associated with @var{key}, and
-@var{value} there. Uses `eqv?' for equality testing.
+store @var{value} there. Uses @code{eqv?} for equality testing.
 @end deffn
 
 @c ARGFIXME obj/key
 @c docstring begin (texi-doc-string "guile" "hash-set!")
 @deffn primitive hash-set! table obj val
-Find the entry in @var{table} associated with @var{key}, and store
+Find the entry in @var{table} associated with @var{key}, and
-@var{value} there. Uses `equal?' for equality testing.
+store @var{value} there. Uses @code{equal?} for equality
+testing.
 @end deffn
 
 @c ARGFIXME obj/key
 @c docstring begin (texi-doc-string "guile" "hashq-remove!")
 @deffn primitive hashq-remove! table obj
-Remove @var{key} (and any value associated with it) from @var{table}.
+Remove @var{key} (and any value associated with it) from
-Uses `eq?' for equality tests.
+@var{table}.  Uses @code{eq?} for equality tests.
 @end deffn
 
 @c ARGFIXME obj/key
 @c docstring begin (texi-doc-string "guile" "hashv-remove!")
 @deffn primitive hashv-remove! table obj
-Remove @var{key} (and any value associated with it) from @var{table}.
+Remove @var{key} (and any value associated with it) from
-Uses `eqv?' for equality tests.
+@var{table}.  Uses @code{eqv?} for equality tests.
 @end deffn
 
 @c ARGFIXME obj/key
 @c docstring begin (texi-doc-string "guile" "hash-remove!")
 @deffn primitive hash-remove! table obj
-Remove @var{key} (and any value associated with it) from @var{table}.
+Remove @var{key} (and any value associated with it) from
-Uses `equal?' for equality tests.
+@var{table}.  Uses @code{equal?} for equality tests.
 @end deffn
 
 The standard hash table functions may be too limited for some
@@ -4624,36 +4638,38 @@ explanation of how hash tables are implemented.
 
 @c docstring begin (texi-doc-string "guile" "hashq")
 @deffn primitive hashq key size
-Determine a hash value for KEY that is suitable for lookups in
+Determine a hash value for @var{key} that is suitable for
-a hashtable of size SIZE, where eq? is used as the equality
+lookups in a hashtable of size @var{size}, where @code{eq?} is
-predicate.  The function returns an integer in the range 0 to
+used as the equality predicate.  The function returns an
-SIZE - 1.  NOTE that `hashq' may use internal addresses.
+integer in the range 0 to @var{size} - 1.  Note that
-Thus two calls to hashq where the keys are eq? are not
+@code{hashq} may use internal addresses.  Thus two calls to
-guaranteed to deliver the same value if the key object gets
+hashq where the keys are @code{eq?} are not guaranteed to
-garbage collected in between.  This can happen, for example
+deliver the same value if the key object gets garbage collected
-with symbols:  (hashq 'foo n) (gc) (hashq 'foo n) may produce two
+in between.  This can happen, for example with symbols:
-different values, since 'foo will be garbage collected.
+@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two
+different values, since @code{foo} will be garbage collected.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "hashv")
 @deffn primitive hashv key size
-Determine a hash value for KEY that is suitable for lookups in
+Determine a hash value for @var{key} that is suitable for
-a hashtable of size SIZE, where eqv? is used as the equality
+lookups in a hashtable of size @var{size}, where @code{eqv?} is
-predicate.  The function returns an integer in the range 0 to
+used as the equality predicate.  The function returns an
-SIZE - 1.  NOTE that (hashv key) may use internal addresses.
+integer in the range 0 to @var{size} - 1.  Note that
-Thus two calls to hashv where the keys are eqv? are not
+@code{(hashv key)} may use internal addresses.  Thus two calls
-guaranteed to deliver the same value if the key object gets
+to hashv where the keys are @code{eqv?} are not guaranteed to
-garbage collected in between.  This can happen, for example
+deliver the same value if the key object gets garbage collected
-with symbols:  (hashv 'foo n) (gc) (hashv 'foo n) may produce two
+in between.  This can happen, for example with symbols:
-different values, since 'foo will be garbage collected.
+@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two
+different values, since @code{foo} will be garbage collected.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "hash")
 @deffn primitive hash key size
-Determine a hash value for KEY that is suitable for lookups in
+Determine a hash value for @var{key} that is suitable for
-a hashtable of size SIZE, where equal? is used as the equality
+lookups in a hashtable of size @var{size}, where @code{equal?}
-predicate.  The function returns an integer in the range 0 to
+is used as the equality predicate.  The function returns an
-SIZE - 1.
+integer in the range 0 to @var{size} - 1.
 @end deffn
 
 @c ARGFIXME hash/hasher
@@ -4784,27 +4800,24 @@ Otherwise the initial contents of each element is unspecified. (r5rs)
 @c docstring begin (texi-doc-string "guile" "list->vector")
 @deffn primitive vector . l
 @deffnx primitive list->vector l
-Returns a newly allocated vector whose elements contain the given
+Returns a newly allocated vector whose elements contain the
-arguments.  Analogous to @samp{list}. (r5rs)
+given arguments.  Analogous to @code{list}. (r5rs)
 
-@format
+@lisp
-@t{(vector 'a 'b 'c)                      ==>  #(a b c) }
+(vector 'a 'b 'c) @result{}  #(a b c)
-@end format
+@end lisp
 @end deffn
 
 @r5index vector->list
 @c docstring begin (texi-doc-string "guile" "vector->list")
 @deffn primitive vector->list v
-@samp{Vector->list} returns a newly allocated list of the objects contained
+@samp{Vector->list} returns a newly allocated list of the
-in the elements of @var{vector}.  (r5rs)
+objects contained in the elements of @var{vector}.  (r5rs)
 
-@format
+@lisp
-@t{(vector->list '#(dah dah didah))
+(vector->list '#(dah dah didah)) @result{}  (dah dah didah)
-=>  (dah dah didah)
+(list->vector '(dididit dah)) @result{}  #(dididit dah)
-list->vector '(dididit dah))
+@end lisp
-=>  #(dididit dah)
-}
-@end format
 @end deffn
 
 @r5index vector-fill!
@@ -4812,13 +4825,14 @@ list->vector '(dididit dah))
 @c docstring begin (texi-doc-string "guile" "vector-fill!")
 @deffn primitive vector-fill! v fill_x
 Stores @var{fill} in every element of @var{vector}.
-The value returned by @samp{vector-fill!} is unspecified. (r5rs)
+The value returned by @code{vector-fill!} is unspecified. (r5rs)
 @end deffn
 
 @r5index vector?
 @c docstring begin (texi-doc-string "guile" "vector?")
 @deffn primitive vector? obj
-Returns @t{#t} if @var{obj} is a vector, otherwise returns @t{#f}. (r5rs)
+Returns @code{#t} if @var{obj} is a vector, otherwise returns
+@code{#f}. (r5rs)
 @end deffn
 
 @r5index vector-length

doc/scheme-evaluation.texi

@@ -132,9 +132,10 @@ dynamically typed by the user.
 
 @c docstring begin (texi-doc-string "guile" "eval-string")
 @deffn primitive eval-string string
-Evaluate @var{string} as the text representation of a Scheme form
+Evaluate @var{string} as the text representation of a Scheme
-or forms, and return whatever value they produce.
+form or forms, and return whatever value they produce.
-Evaluation takes place in (interaction-environment).
+Evaluation takes place in the environment returned by the
+procedure @code{interaction-environment}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "apply:nconc2last")
@@ -191,31 +192,34 @@ this section.
 @c ARGFIXME file/filename
 @c docstring begin (texi-doc-string "guile" "primitive-load")
 @deffn primitive primitive-load filename
-Load @var{file} and evaluate its contents in the top-level environment.
+Load the file named @var{filename} and evaluate its contents in
-The load paths are not searched; @var{file} must either be a full
+the top-level environment. The load paths are not searched;
-pathname or be a pathname relative to the current directory.  If the
+@var{filename} must either be a full pathname or be a pathname
-variable @code{%load-hook} is defined, it should be bound to a procedure
+relative to the current directory.  If the  variable
-that will be called before any code is loaded.  See documentation for
+@code{%load-hook} is defined, it should be bound to a procedure
-@code{%load-hook} later in this section.
+that will be called before any code is loaded.  See the
+documentation for @code{%load-hook} later in this section.
 @end deffn
 
 @c ARGFIXME file/filename
 @c docstring begin (texi-doc-string "guile" "primitive-load-path")
 @deffn primitive primitive-load-path filename
-Search @var{%load-path} for @var{file} and load it into the top-level
+Search @var{%load-path} for the file named @var{filename} and
-environment.  If @var{file} is a relative pathname and is not found in
+load it into the top-level environment.  If @var{filename} is a
-the list of search paths, an error is signalled.
+relative pathname and is not found in the list of search paths,
+an error is signalled.
 @end deffn
 
 @c ARGFIXME file/filename
 @c docstring begin (texi-doc-string "guile" "%search-load-path")
 @deffn primitive %search-load-path filename
-Search @var{%load-path} for @var{file}, which must be readable by the
+Search @var{%load-path} for the file named @var{filename},
-current user.  If @var{file} is found in the list of paths to search or
+which must be readable by the current user.  If @var{filename}
-is an absolute pathname, return its full pathname.  Otherwise, return
+is found in the list of paths to search or is an absolute
-@code{#f}.  Filenames may have any of the optional extensions in the
+pathname, return its full pathname.  Otherwise, return
-@code{%load-extensions} list; @code{%search-load-path} will try each
+@code{#f}.  Filenames may have any of the optional extensions
-extension automatically.
+in the @code{%load-extensions} list; @code{%search-load-path}
+will try each extension automatically.
 @end deffn
 
 @defvar %load-hook
@@ -255,7 +259,7 @@ list @code{("" ".scm")}.
 
 @c ARGFIXME x/obj
 @c docstring begin (texi-doc-string "guile" "promise?")
-@deffn primitive promise? x
+@deffn primitive promise? obj
 Return true if @var{obj} is a promise, i.e. a delayed computation
 (@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}).
 @end deffn
@@ -263,8 +267,9 @@ Return true if @var{obj} is a promise, i.e. a delayed computation
 @r5index force
 @c docstring begin (texi-doc-string "guile" "force")
 @deffn primitive force x
-If the promise X has not been computed yet, compute and return
+If the promise @var{x} has not been computed yet, compute and
-X, otherwise just return the previously computed value.
+return @var{x}, otherwise just return the previously computed
+value.
 @end deffn
 
 

doc/scheme-io.texi

@@ -51,7 +51,8 @@ Returns @code{#t} if @var{x} is an output port, otherwise returns
 @c docstring begin (texi-doc-string "guile" "port?")
 @deffn primitive port? x
 Returns a boolean indicating whether @var{x} is a port.
-Equivalent to @code{(or (input-port? X) (output-port? X))}.
+Equivalent to @code{(or (input-port? @var{x}) (output-port?
+@var{x}))}.
 @end deffn
 
 
@@ -135,13 +136,13 @@ characters) and returns the content as a single string.
 @c docstring begin (texi-doc-string "guile" "port-column")
 @c docstring begin (texi-doc-string "guile" "port-line")
 @deffn primitive port-column port
-@deffnx primitive port-line [input-port]
+@deffnx primitive port-line port
-Return the current column number or line number of @var{input-port},
+Return the current column number or line number of @var{port},
 using the current input port if none is specified.  If the number is
 unknown, the result is #f.  Otherwise, the result is a 0-origin integer
 - i.e. the first character of the first line is line 0, column 0.
 (However, when you display a file position, for example in an error
-message, we recommand you add 1 to get 1-origin integers.  This is
+message, we recommend you add 1 to get 1-origin integers.  This is
 because lines and column numbers traditionally start with 1, and that is
 what non-programmers will find most natural.)
 @end deffn
@@ -216,8 +217,9 @@ included print state @var{pstate}.
 @c docstring begin (texi-doc-string "guile" "print-options-interface")
 @deffn primitive print-options-interface [setting]
 Option interface for the print options. Instead of using
-this procedure directly, use the procedures @code{print-enable},
+this procedure directly, use the procedures
-@code{print-disable}, @code{print-set!} and @var{print-options}.
+@code{print-enable}, @code{print-disable}, @code{print-set!}
+and @code{print-options}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "simple-format")
@@ -460,19 +462,19 @@ internals.
 @c docstring begin (texi-doc-string "guile" "%read-delimited!")
 @deffn primitive %read-delimited! delims str gobble [port [start [end]]]
 Read characters from @var{port} into @var{str} until one of the
-characters in the @var{delims} string is encountered.  If @var{gobble}
+characters in the @var{delims} string is encountered.  If
-is true, discard the delimiter character; otherwise, leave it
+@var{gobble} is true, discard the delimiter character;
-in the input stream for the next read.
+otherwise, leave it in the input stream for the next read.  If
-If @var{port} is not specified, use the value of
+@var{port} is not specified, use the value of
-@code{(current-input-port)}.  If @var{start} or @var{end} are specified,
+@code{(current-input-port)}.  If @var{start} or @var{end} are
-store data only into the substring of @var{str} bounded by @var{start}
+specified, store data only into the substring of @var{str}
-and @var{end} (which default to the beginning and end of the string,
+bounded by @var{start} and @var{end} (which default to the
-respectively).
+beginning and end of the string, respectively).
-
+ Return a pair consisting of the delimiter that terminated the
-Return a pair consisting of the delimiter that terminated the string and
+string and the number of characters read.  If reading stopped
-the number of characters read.  If reading stopped at the end of file,
+at the end of file, the delimiter returned is the
-the delimiter returned is the @var{eof-object}; if the string was filled
+@var{eof-object}; if the string was filled without encountering
-without encountering a delimiter, this value is @var{#f}.
+a delimiter, this value is @code{#f}.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "%read-line")

doc/scheme-memory.texi

@@ -104,9 +104,9 @@ regular hash tables. (@pxref{Hash Tables})
 @deffn primitive weak-key-hash-table? x
 @deffnx primitive weak-value-hash-table? obj
 @deffnx primitive doubly-weak-hash-table? obj
-Return @var{#t} if @var{obj} is the specified weak hash table. Note
+Return @code{#t} if @var{obj} is the specified weak hash
-that a doubly weak hash table is neither a weak key nor a weak value
+table. Note that a doubly weak hash table is neither a weak key
-hash table.
+nor a weak value hash table.
 @end deffn
 
 @c docstring begin (texi-doc-string "guile" "make-weak-value-hash-table")
@@ -154,8 +154,8 @@ its arguments while @code{list->weak-vector} uses its only argument
 @c ARGFIXME x/obj
 @c docstring begin (texi-doc-string "guile" "weak-vector?")
 @deffn primitive weak-vector? x
-Return @var{#t} if @var{obj} is a weak vector. Note that all weak
+Return @code{#t} if @var{obj} is a weak vector. Note that all
-hashes are also weak vectors.
+weak hashes are also weak vectors.
 @end deffn