Change defconst into defvar. Many doc fixes.

1 files changed, 53 insertions, 57 deletions

diff --git a/lisp/emacs-lisp/lisp-mnt.el b/lisp/emacs-lisp/lisp-mnt.el
index 1b88718b07d..8a6af05993f 100644
--- a/lisp/emacs-lisp/lisp-mnt.el
+++ b/lisp/emacs-lisp/lisp-mnt.el
@@ -5,7 +5,7 @@
 ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
 ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
 ;; Created: 14 Jul 1992
-;; Version: $Id: lisp-mnt.el,v 1.14 1996/02/04 21:30:40 rms Exp rms $
+;; Version: $Id: lisp-mnt.el,v 1.16 1996/02/06 21:35:20 erik Exp rms $
 ;; Keywords: docs
 ;; X-Bogus-Bureaucratic-Cruft: Gruad will get you if you don't watch out!
 
@@ -70,7 +70,7 @@
 ;; line, or an address only, or the string "FSF".  If there is no maintainer
 ;; line, the person(s) in the Author field are presumed to be it.  The example
 ;; in this file is mildly bogus because the maintainer line is redundant.
-;;    The idea behind these two fields is to be able to write a lisp function
+;;    The idea behind these two fields is to be able to write a Lisp function
 ;; that does "send mail to the author" without having to mine the name out by
 ;; hand. Please be careful about surrounding the network address with <> if
 ;; there's also a name in the field.
@@ -95,7 +95,7 @@
 ;; for any real purpose; this is the way to safely add random headers
 ;; without invoking the wrath of any program.
 ;;
-;;    * Commentary line --- enables lisp code to find the developer's and
+;;    * Commentary line --- enables Lisp code to find the developer's and
 ;; maintainers' explanations of the package internals.
 ;; 
 ;;    * Change log line --- optional, exists to terminate the commentary
@@ -119,10 +119,10 @@
 
 ;;; Variables:
 
-(defconst lm-header-prefix "^;;*[ \t]+\\(@\(#\)\\)?[ \t]*\\([\$]\\)?"
+(defvar lm-header-prefix "^;;*[ \t]+\\(@\(#\)\\)?[ \t]*\\([\$]\\)?"
   "Prefix that is ignored before the tag.
-Eg. you can write the 1st line synopsis string and headers like this
-in your lisp package:
+For example, you can write the 1st line synopsis string and headers like this
+in your Lisp package:
 
    ;; @(#) package.el -- pacakge description
    ;;
@@ -131,13 +131,13 @@ in your lisp package:
 The @(#) construct is used by unix what(1) and
 then $identifier: doc string $ is used by GNU ident(1)")
 
-(defconst lm-comment-column 16
+(defvar lm-comment-column 16
   "Column used for placing formatted output.")
 
-(defconst lm-commentary-header "Commentary\\|Documentation"
+(defvar lm-commentary-header "Commentary\\|Documentation"
   "Regexp which matches start of documentation section.")
 
-(defconst lm-history-header "Change Log\\|History"
+(defvar lm-history-header "Change Log\\|History"
   "Regexp which matches the start of code log section.")
 
 ;;; Functions:
@@ -145,13 +145,13 @@ then $identifier: doc string $ is used by GNU ident(1)")
 ;; These functions all parse the headers of the current buffer
 
 (defsubst lm-get-header-re (header &optional mode)
-  "Returns regexp for matching HEADER. If called with optional MODE and
-with value 'section, return section regexp instead."
-  (cond
-   ((eq mode 'section)
-    (concat "^;;;;* " header ":[ \t]*$"))
-   (t
-    (concat lm-header-prefix header ":[ \t]*"))))
+  "Returns regexp for matching HEADER.
+If called with optional MODE and with value `section',
+return section regexp instead."
+  (cond ((eq mode 'section)
+	 (concat "^;;;;* " header ":[ \t]*$"))
+	(t
+	 (concat lm-header-prefix header ":[ \t]*"))))
 
 (defsubst lm-get-package-name ()
   "Returns package name by looking at the first line."
@@ -166,8 +166,8 @@ with value 'section, return section regexp instead."
 
 (defun lm-section-mark (header &optional after)
   "Return the buffer location of a given section start marker.
-The HEADER is section mark string to find and AFTER is non-nil
-returns location of next line."
+The HEADER is the section mark string to search for.
+If AFTER is non-nil, return the location of the next line."
   (save-excursion
     (let ((case-fold-search t))
       (goto-char (point-min))
@@ -179,30 +179,30 @@ returns location of next line."
 	nil))))
 
 (defsubst lm-code-mark ()
-  "Return the buffer location of the 'Code' start marker."
+  "Return the buffer location of the `Code' start marker."
   (lm-section-mark "Code"))
 
 (defsubst lm-commentary-mark ()
-  "Return the buffer location of the 'Commentary' start marker."
+  "Return the buffer location of the `Commentary' start marker."
   (lm-section-mark lm-commentary-header))
 
 (defsubst lm-history-mark ()
-  "Return the buffer location of the 'history' start marker."
+  "Return the buffer location of the `History' start marker."
   (lm-section-mark lm-history-header))
 
 (defun lm-header (header)
-  "Return the contents of a named HEADER."
-    (goto-char (point-min))
-    (let ((case-fold-search t))
-      (if (and (re-search-forward (lm-get-header-re header) (lm-code-mark) t)
-		;;   RCS ident likes format "$identifier: data$"
-		(looking-at "\\([^$\n]+\\)")
-		(match-end 1))
-	  (buffer-substring (match-beginning 1) (match-end 1))
-	nil)))
+  "Return the contents of the header named HEADER."
+  (goto-char (point-min))
+  (let ((case-fold-search t))
+    (if (and (re-search-forward (lm-get-header-re header) (lm-code-mark) t)
+	     ;;   RCS ident likes format "$identifier: data$"
+	     (looking-at "\\([^$\n]+\\)")
+	     (match-end 1))
+	(buffer-substring (match-beginning 1) (match-end 1))
+      nil)))
 
 (defun lm-header-multiline (header)
-  "Return the contents of a named HEADER, with possible continuation lines.
+  "Return the contents of the header named HEADER, with continuation lines.
 The returned value is a list of strings, one per line."
   (save-excursion
     (goto-char (point-min))
@@ -229,7 +229,7 @@ The returned value is a list of strings, one per line."
 ;; These give us smart access to the header fields and commentary
 
 (defun lm-summary (&optional file)
-  "Return the buffer's or optional FILE's one-line summary."
+  "Return the one-line summary of file FILE, or current buffer if FILE is nil."
   (save-excursion
     (if file
 	(find-file file))
@@ -245,9 +245,8 @@ The returned value is a list of strings, one per line."
       )))
 
 (defun lm-crack-address (x)
-  "Cracks email address from string.
-Given a string 'x' containing a human and email address, parse it
-into a cons pair (NAME . ADDRESS)."
+  "Split up an email address into full name and real email address.
+The value is a cons of the form (FULLNAME . ADDRESS)."
   (cond ((string-match "\\(.+\\) [(<]\\(\\S-+@\\S-+\\)[>)]" x)
 	 (cons (substring x (match-beginning 1) (match-end 1))
 	       (substring x (match-beginning 2) (match-end 2))))
@@ -260,9 +259,9 @@ into a cons pair (NAME . ADDRESS)."
 	 (cons x nil))))
 
 (defun lm-authors (&optional file)
-  "Return the buffer's or optional FILE's author list.  Each element of the
-list is a cons; the car is a name-aming-humans, the cdr an email
-address."
+  "Return the author list of file FILE, or current buffer if FILE is nil.
+Each element of the list is a cons; the car is the full name,
+the cdr is an email address."
   (save-excursion
     (if file
 	(find-file file))
@@ -274,9 +273,8 @@ address."
 	))))
 
 (defun lm-maintainer (&optional file)
-  "Seearch for 'maintainer'. Get a package's bug-report & maintenance address.
-Parse it out of FILE, or the current buffer if FILE is nil.
-The return value is a (NAME . ADDRESS) cons."
+  "Return the maintainer of file FILE, or current buffer if FILE is nil.
+The return value has the form (NAME . ADDRESS)."
   (save-excursion
     (if file
 	(find-file file))
@@ -290,8 +288,7 @@ The return value is a (NAME . ADDRESS) cons."
       )))
 
 (defun lm-creation-date (&optional file)
-  "Seearch for 'created'. Return a package's creation date, if any.
-Parse it out of FILE, or the current buffer if FILE is nil."
+  "Return the created date given in file FILE, or current buffer if FILE is nil."
   (save-excursion
     (if file
 	(find-file file))
@@ -303,7 +300,7 @@ Parse it out of FILE, or the current buffer if FILE is nil."
 
 
 (defun lm-last-modified-date (&optional file)
-  "Return a package's last-modified date, if it has one."
+  "Return the modify-date given in file FILE, or current buffer if FILE is nil."
   (save-excursion 
     (if file
 	(find-file file))
@@ -326,8 +323,8 @@ Parse it out of FILE, or the current buffer if FILE is nil."
       )))
 
 (defun lm-version (&optional file)
-  "Search for RCS identifier '$Id'. Return the package's version field.
-If none, look for an RCS or SCCS header to crack it out of."
+  "Return the version listed in file FILE, or current buffer if FILE is nil.
+This can befound in an RCS or SCCS header to crack it out of."
   (save-excursion 
     (if file
 	(find-file file))
@@ -356,8 +353,7 @@ If none, look for an RCS or SCCS header to crack it out of."
       )))
 
 (defun lm-keywords (&optional file)
-  "Search for 'keywords'. Return the header containing the package's
-topic keywords. Parse them out of FILE, or the current buffer if FILE is nil."
+  "Return the keywords given in file FILE, or current buffer if FILE is nil."
   (save-excursion
     (if file
 	(find-file file))
@@ -369,9 +365,9 @@ topic keywords. Parse them out of FILE, or the current buffer if FILE is nil."
       )))
 
 (defun lm-adapted-by (&optional file)
-  "Search for 'adapted-by'. Return the name or code of the person who
-cleaned up this package for distribution.  Parse it out of FILE, or
-the current buffer if FILE is nil."
+  "Return the adapted-by names in file FILE, or current buffer if FILE is nil.
+This is the name of the person who cleaned up this package for
+distribution."
   (save-excursion
     (if file
 	(find-file file))
@@ -382,9 +378,9 @@ the current buffer if FILE is nil."
       )))
 
 (defun lm-commentary (&optional file)
-  "Return the commentary region of a file, as a string.
-The area is started with tag 'Commentary' and eded with tag
-'Change Log' or 'History'."
+  "Return the commentary in file FILE, or current buffer if FILE is nil.
+The value is returned as a string.  In the text, the commentary starts
+with tag `Commentary' and ends with tag `Change Log' or `History'."
   (save-excursion
     (if file
 	(find-file file))
@@ -414,7 +410,7 @@ The area is started with tag 'Commentary' and eded with tag
 
 (defun lm-verify (&optional file showok &optional verb)
   "Check that the current buffer (or FILE if given) is in proper format.
-If FILE is a directory, recurse on its files and generate a report into
+If FILE is a directory, recurse on its files and generate a report in
 a temporary buffer."
   (interactive)
   (let* ((verb    (or verb (interactive-p)))
@@ -498,8 +494,8 @@ a temporary buffer."
 
 (defun lm-synopsis (&optional file showall)
   "Generate a synopsis listing for the buffer or the given FILE if given.
-If FILE is a directory, recurse on its files and generate a report into
-a temporary buffer.  If SHOWALL is on, also generate a line for files
+If FILE is a directory, recurse on its files and generate a report in
+a temporary buffer.  If SHOWALL is non-nil, also generate a line for files
 which do not include a recognizable synopsis."
   (interactive
    (list