From 22c4cc60c956e280d39d1936dc7733deace7b527 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Thu, 8 Feb 1996 04:13:11 +0000 Subject: Change defconst into defvar. Many doc fixes. --- lisp/emacs-lisp/lisp-mnt.el | 110 +++++++++++++++++++++----------------------- 1 file 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 ;; Maintainer: Eric S. Raymond ;; 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 -- cgit v1.2.1