;; 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!
;; 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.
;; 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
;;; 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
;;
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:
;; 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."
(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))
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))
;; 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))
)))
(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))))
(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))
))))
(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))
)))
(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))
(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))
)))
(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))
)))
(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))
)))
(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))
)))
(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))
(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)))
(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
projects / emacs.git / commitdiff