20 files changed, 125 insertions, 31 deletions
diff --git a/lisp/env.el b/lisp/env.el
index 721c835a187..3445d1c060e 100644
--- a/lisp/env.el
+++ b/lisp/env.el
@@ -3,7 +3,7 @@
 ;;; Copyright Free Software Foundation 1991
 
 ;; Maintainer: FSF
-;; Keywords: extensions
+;; Keywords: processes, unix
 
 ;;; This file is part of GNU Emacs.
 
@@ -21,6 +21,13 @@
 ;;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; UNIX processes inherit a list of name-to-string associations from
+;; their parents called their `environment'; these are commonly used
+;; to control program options.  This package permits you to set
+;; environment variables to be passed to any sub-process run under Emacs.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/help.el b/lisp/help.el
index 68b3f641593..5cf31dfeb78 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -21,6 +21,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This code implements GNU Emac's on-line help system, the one invoked by
+;;`M-x help-for-help'.
+
 ;;; Code:
 
 ;; Get the macro make-help-screen when this is compiled,
diff --git a/lisp/mail/rfc822.el b/lisp/mail/rfc822.el
index f23f3029a17..373b0a85a2c 100644
--- a/lisp/mail/rfc822.el
+++ b/lisp/mail/rfc822.el
@@ -22,6 +22,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Support functions for parsing RFC-822 headers, used by mail and news
+;; modes.  
+
 ;;; Code:
 
 ;; uses address-start free, throws to address
diff --git a/lisp/mail/sendmail.el b/lisp/mail/sendmail.el
index f0de0525ce5..0d2cb929f81 100644
--- a/lisp/mail/sendmail.el
+++ b/lisp/mail/sendmail.el
@@ -21,6 +21,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This mode provides mail-sending facilities from within Emacs.  It is
+;; documented in the Emacs user's manual.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/play/spook.el b/lisp/play/spook.el
index d1b31b757a1..1ba0b2dabb6 100644
--- a/lisp/play/spook.el
+++ b/lisp/play/spook.el
@@ -4,6 +4,7 @@
 
 ;; Maintainer: FSF
 ;; Keywords: games
+;; Created: May 1987
 
 ;; This file is part of GNU Emacs.
 
@@ -26,8 +27,7 @@
 ; Steve Strassmann (straz@media-lab.media.mit.edu) didn't write
 ; this, and even if he did, he really didn't mean for you to use it
 ; in an anarchistic way.
-; May 1987
-
+;
 ; To use this:
 ;  Make sure you have the variable SPOOK-PHRASES-FILE pointing to 
 ;  a valid phrase file. Phrase files are in the same format as
@@ -38,7 +38,7 @@
 ;  Just before sending mail, do M-x spook.
 ;  A number of phrases will be inserted into your buffer, to help
 ;  give your message that extra bit of attractiveness for automated
-;  keyword scanners.
+;  keyword scanners.  Help defeat the NSA trunk trawler!
 
 ;;; Code:
 
diff --git a/lisp/play/studly.el b/lisp/play/studly.el
index 1f215003c96..b5aafcab09a 100644
--- a/lisp/play/studly.el
+++ b/lisp/play/studly.el
@@ -5,6 +5,12 @@
 
 ;; Keywords: games
 
+;;; Commentary:
+
+;; Functions to studlycapsify a region, word, or buffer.  Possibly the
+;; esoteric significance of studlycapsification escapes you; that is,
+;; you suffer from autostudlycapsifibogotification.  Too bad.
+
 ;;; Code:
 
 (defun studlify-region (begin end)
diff --git a/lisp/progmodes/simula.el b/lisp/progmodes/simula.el
index e6757432ac3..6c3a41735a8 100644
--- a/lisp/progmodes/simula.el
+++ b/lisp/progmodes/simula.el
@@ -26,7 +26,11 @@
 
 ;;; Commentary:
 
-;; Hans Henrik Eriksen may be reached at:
+;; A major mode for editing the Simula language.  It knows about Simula
+;; syntax and standard indentation commands.  It also provides convenient
+;; abbrevs for Simula keywords.
+;;
+;; Hans Henrik Eriksen (the author) may be reached at:
 ;;         Institutt for informatikk,
 ;;         Universitetet i Oslo
 
diff --git a/lisp/register.el b/lisp/register.el
index 447c4c4a595..24487dac7b1 100644
--- a/lisp/register.el
+++ b/lisp/register.el
@@ -21,6 +21,13 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This package of functions emulates and somewhat extends the venerable
+;; TECO's `register' feature, which permits you to save various useful
+;; pieces of buffer state to named variables.  The entry points are
+;; documented in the Emacs user's manual.
+
 ;;; Code:
 
 (defvar register-alist nil
diff --git a/lisp/replace.el b/lisp/replace.el
index 3c195224ad9..449d5243ee3 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -18,6 +18,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This package supplies the string and regular-expression replace functions
+;; documented in the Emacs user's manual.
+
 ;;; Code:
 
 (defconst case-replace t "\
diff --git a/lisp/reposition.el b/lisp/reposition.el
index 9839c9afb69..d981eefec5e 100644
--- a/lisp/reposition.el
+++ b/lisp/reposition.el
@@ -3,6 +3,7 @@
 ;; Copyright (C) 1991 Free Software Foundation, Inc.
 
 ;; Author: Michael D. Ernst <mernst@theory.lcs.mit.edu>
+;; Created: Jan 1991
 ;; Maintainer: FSF
 
 ;; This file is part of GNU Emacs.
@@ -23,8 +24,6 @@
 
 ;;; Commentary:
 
-;;; Written by Michael D. Ernst, mernst@theory.lcs.mit.edu, Jan 1991.
-
 ;;; Reposition-window makes an entire function definition or comment visible,
 ;;; or, if it is already visible, places it at the top of the window;
 ;;; additional invocations toggle the visibility of comments preceding the
diff --git a/lisp/rlogin.el b/lisp/rlogin.el
index db0832c2d5b..bd6fc6ec3f6 100644
--- a/lisp/rlogin.el
+++ b/lisp/rlogin.el
@@ -3,28 +3,32 @@
 ;; Maintainer: Noah Friedman <friedman@prep.ai.mit.edu>
 ;; Keywords: unix, comm
 
-;;; Copyright (C) 1992 Free Software Foundation, Inc.
-;;;
-;;; This program 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.
-;;;
-;;; This program 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 this program; if not, you can either send email to this
-;;; program's author (see below) or write to:
-;;;
-;;;              The Free Software Foundation, Inc.
-;;;              675 Massachusetts Avenue.
-;;;              Cambridge, MA 02139, USA. 
-;;;
-
-;;; Todo: add directory tracking using ange-ftp style patchnames for the cwd.
+;; Copyright (C) 1992 Free Software Foundation, Inc.
+;;
+;; This program 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.
+;;
+;; This program 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 this program; if not, you can either send email to this
+;; program's author (see below) or write to:
+;;
+;;              The Free Software Foundation, Inc.
+;;              675 Massachusetts Avenue.
+;;              Cambridge, MA 02139, USA. 
+;;
+
+;;; Commentary:
+
+;; Support for remote login over Internet using rlogin(1).
+;;
+;; Todo: add directory tracking using ange-ftp style patchnames for the cwd.
 
 ;;; Code:
 
diff --git a/lisp/rot13.el b/lisp/rot13.el
index 30c1b3d41a4..75af4d1026d 100644
--- a/lisp/rot13.el
+++ b/lisp/rot13.el
@@ -23,8 +23,13 @@
 
 ;; Commentary:
 
+;; The single entry point, `rot13-other-window', oerforms a Caesar cipher
+;; encrypt/decrypt on the current buffer and displays the result in another 
+;; window.  Rot13 encryption is sometimes used on USENET as a read-at-yur-
+;; own-risk wrapper for material some might consider offensive, such as
+;; ethnic humor.
+;;
 ;; Written by Howard Gayle.  See case-table.el for details.
-
 ;; This hack is mainly to show off the char table stuff.
 
 ;;; Code:
diff --git a/lisp/scroll-bar.el b/lisp/scroll-bar.el
index a924295faaa..2aaf0d8e163 100644
--- a/lisp/scroll-bar.el
+++ b/lisp/scroll-bar.el
@@ -23,6 +23,12 @@
 
 ;;; Code:
 
+;;; Commentary:
+
+;; Window-system-independent bindings of mouse clicks on the scroll bar.
+;; Presently emulates the scroll-bar behavior of xterm.
+;;; Code:
+
 (require 'mouse)
 
 
diff --git a/lisp/simple.el b/lisp/simple.el
index 6577fb92d14..6d27c2122ef 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -18,6 +18,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; A grab-bag of basic Emacs commands not specifically related to some
+;; major mode or to file-handling.
+
 ;;; Code:
 
 (defun open-line (arg)
diff --git a/lisp/sort.el b/lisp/sort.el
index 8c3285e144a..0ee90121ae0 100644
--- a/lisp/sort.el
+++ b/lisp/sort.el
@@ -22,6 +22,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;;; This package provides the sorting facilities documented in the Emacs
+;;; user's manual.
+
 ;;; Code:
 
 (defun sort-subr (reverse nextrecfun endrecfun &optional startkeyfun endkeyfun)
diff --git a/lisp/tabify.el b/lisp/tabify.el
index b1a8e35fe2e..cccc99ea1a5 100644
--- a/lisp/tabify.el
+++ b/lisp/tabify.el
@@ -20,6 +20,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Commands to optimize spaces to tabs or expand tabs to spaces in a region
+;; (`tabify' and `untabify').  The variable tab-width does the obvious.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/textmodes/scribe.el b/lisp/textmodes/scribe.el
index 6954f5c6284..d664292c3d1 100644
--- a/lisp/textmodes/scribe.el
+++ b/lisp/textmodes/scribe.el
@@ -21,6 +21,12 @@
 ;; It should be in a file named COPYING.  Among other things, the
 ;; copyright notice and this notice must be preserved on all copies.
 
+;;; Commentary:
+
+;; A major mode for editing source in written for the Scribe text formatter.
+;; Knows about Scribe syntax and standard layout rules.  The command to
+;; run Scribe on a buffer is bogus; someone interested should fix it.
+
 ;;; Code:
 
 (defvar scribe-mode-syntax-table nil
diff --git a/lisp/textmodes/sgml-mode.el b/lisp/textmodes/sgml-mode.el
index b6200ac0bc7..676edaf0519 100644
--- a/lisp/textmodes/sgml-mode.el
+++ b/lisp/textmodes/sgml-mode.el
@@ -24,6 +24,8 @@
 
 ;;; Commentary:
 
+;; Major mode for editing the SGML document-markup language.
+;;
 ;; Some suggestions for your .emacs file:
 ;;
 ;; (autoload 'sgml-mode "sgml-mode" "SGML mode" t)
diff --git a/lisp/textmodes/spell.el b/lisp/textmodes/spell.el
index 6e05a8c0fad..e1ed847ca79 100644
--- a/lisp/textmodes/spell.el
+++ b/lisp/textmodes/spell.el
@@ -3,7 +3,7 @@
 ;; Copyright (C) 1985 Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
-;; Keywords: wp
+;; Keywords: wp, unix
 
 ;; This file is part of GNU Emacs.
 
@@ -21,6 +21,13 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This mode orovides an Emacs interface to the UNIX spell(1) program.
+;; Entry points are `spell-buffer', `spell-word', `spell-region' and
+;; `spell-string'.  These facilities are documented in the Emacs user's
+;; manual.
+
 ;;; Code:
 
 (defvar spell-command "spell"
diff --git a/lisp/textmodes/text-mode.el b/lisp/textmodes/text-mode.el
index 0f9229e80a3..b4b543f9a47 100644
--- a/lisp/textmodes/text-mode.el
+++ b/lisp/textmodes/text-mode.el
@@ -20,6 +20,12 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+
+;;; Commentary:
+
+;; This package provides the fundamental text mode documented in the
+;; Emacs user's manual.
+
 ;;; Code:
 
 (defvar text-mode-syntax-table nil