--- a/lisp/ChangeLog	Thu Feb 22 16:19:44 2007 +0000
+++ b/lisp/ChangeLog	Thu Feb 22 16:53:27 2007 +0000
@@ -1,3 +1,11 @@
+2007-01-23  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* cus-face.el (custom-theme-reset-faces): Move code after docstring.
+
+2007-01-22  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* subr.el (lambda): Improve docstring.
+
 2007-01-21  Ville Skyttä  <scop@xemacs.org>
 
 	* mule/canna-leim.el (canna-activate): Look for canna_api, not

--- a/lisp/cus-face.el	Thu Feb 22 16:19:44 2007 +0000
+++ b/lisp/cus-face.el	Thu Feb 22 16:53:27 2007 +0000
@@ -359,7 +359,6 @@
 
 ;;;###autoload
 (defun custom-theme-reset-faces (theme &rest args)
-  (custom-check-theme theme)
   "Reset the value of the face to values previously defined.
 Associate this setting with THEME.
 
@@ -368,6 +367,7 @@
     (face to-theme)
 
 This means reset face to its value in to-theme."
+  (custom-check-theme theme)
   (mapc #'(lambda (arg)
 	    (apply #'custom-theme-reset-internal-face arg)
 	    (custom-push-theme (car arg) 'theme-face theme 'reset (cadr arg)))

--- a/lisp/subr.el	Thu Feb 22 16:19:44 2007 +0000
+++ b/lisp/subr.el	Thu Feb 22 16:53:27 2007 +0000
@@ -79,12 +79,24 @@
 funcall or mapcar, etc.
 
 ARGS should take the same form as an argument list for a `defun'.
-DOCSTRING is an optional documentation string.
- If present, it should describe how to call the function.
- But documentation strings are usually not useful in nameless functions.
-INTERACTIVE should be a call to the function `interactive', which see.
-It may also be omitted.
-BODY should be a list of lisp expressions."
+Optional DOCSTRING is a documentation string.
+If present, it should describe how to call the function.  Docstrings are
+rarely useful unless the lambda will be named, eg, using `fset'.
+Optional INTERACTIVE should be a call to the function `interactive'.
+BODY should be a list of lisp expressions.
+
+The byte-compiler treats lambda expressions specially.  If the lambda
+expression is syntactically a function to be called, it will be compiled
+unless protected by `quote'.  Conversely, quoting a lambda expression with
+`function' hints to the byte-compiler that it should compile the expression.
+\(The byte-compiler may or may not actually compile it; for example it will
+never compile lambdas nested in a data structure: `'(#'(lambda (x) x))').
+
+The byte-compiler will warn about common problems such as the form
+`(fset 'f '(lambda (x) x))' (the lambda cannot be byte-compiled; probably
+the programmer intended `#'', although leaving the lambda unquoted will
+normally suffice), but in general is it the programmer's responsibility to
+quote lambda expressions appropriately."
   `(function (lambda ,@cdr)))
 
 ;; FSF 21.2 has various basic macros here.  We don't because they're either

--- a/src/ChangeLog	Thu Feb 22 16:19:44 2007 +0000
+++ b/src/ChangeLog	Thu Feb 22 16:53:27 2007 +0000
@@ -1,3 +1,10 @@
+2007-01-22  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* eval.c (quote):
+	(function):
+	* fns.c (Frequire):
+	Improve docstrings.
+
 2007-02-21  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* objects-tty.c (tty_font_spec_matches_charset): Use Aidan's enum.

--- a/src/eval.c	Thu Feb 22 16:19:44 2007 +0000
+++ b/src/eval.c	Thu Feb 22 16:53:27 2007 +0000
@@ -1178,14 +1178,16 @@
 DEFUN ("quote", Fquote, 1, UNEVALLED, 0, /*
 Return the argument, without evaluating it.  `(quote x)' yields `x'.
 
-There is an alternative and more used reader syntax for `quote'.  Precede
-any Lisp object with a single apostrophe, and that Lisp object will be
-returned unevaluated. 'x is thus equivalent to (quote x).
-
-Do not use `quote' or the single apostrophe for lambda expressions that you
-would prefer to be byte-compiled.  Use `function', which see, or take
-advantage of the fact that lambda expressions are self-quoting and such
-lambda expressions will be automatically byte-compiled.
+`quote' differs from `function' in that it is a hint that an expression is
+data, not a function.  In particular, under some circumstances the byte
+compiler will compile an expression quoted with `function', but it will
+never do so for an expression quoted with `quote'.  These issues are most
+important for lambda expressions (see `lambda').
+
+There is an alternative, more readable, reader syntax for `quote':  a Lisp
+object preceded by `''. Thus, `'x' is equivalent to `(quote x)', in all
+contexts.  A print function may use either.  Internally the expression is
+represented as `(quote x)').
 */
        (args))
 {
@@ -1193,17 +1195,20 @@
 }
 
 DEFUN ("function", Ffunction, 1, UNEVALLED, 0, /*
-Like `quote', but preferred for objects which are functions.
-
-As with `quote' there is an alternative reader syntax for `function' which
-in practice is used more often.  Writing #'OBJECT is equivalent to writing
-\(function OBJECT), where OBJECT is some Lisp object.
-
-In byte compilation, `function' causes a lambda expression argument to be
-compiled.  `quote' cannot do that.  lambda expressions are, however,
-self-quoting, and self-quoted lambda expressions will be byte-compiled.
-Only lambda expressions explicitly quoted with `quote' or that occur in
-nested data lists will not be byte-compiled.
+Return the argument, without evaluating it.  `(function x)' yields `x'.
+
+`function' differs from `quote' in that it is a hint that an expression is
+a function, not data.  In particular, under some circumstances the byte
+compiler will compile an expression quoted with `function', but it will
+never do so for an expression quoted with `quote'.  However, the byte
+compiler will not compile an expression buried in a data structure such as
+a vector or a list which is not syntactically a function.  These issues are
+most important for lambda expressions (see `lambda').
+
+There is an alternative, more readable, reader syntax for `function':  a Lisp
+object preceded by `#''. Thus, #'x is equivalent to (function x), in all
+contexts.  A print function may use either.  Internally the expression is
+represented as `(function x)').
 */
        (args))
 {

--- a/src/fns.c	Thu Feb 22 16:19:44 2007 +0000
+++ b/src/fns.c	Thu Feb 22 16:53:27 2007 +0000
@@ -3576,19 +3576,26 @@
 }
 
 DEFUN ("require", Frequire, 1, 3, 0, /*
-If feature FEATURE is not loaded, load it from FILENAME.
-If FEATURE is not a member of the list `features', then the feature
-is not loaded; so load the file FILENAME.
-If FILENAME is omitted, the printname of FEATURE is used as the file name.
-If optional third argument NOERROR is non-nil, then return nil if the file
-is not found instead of signaling an error.
-Normally the return value is FEATURE.
-The normal messages at start and end of loading FILENAME are suppressed.
-
-In order to make it possible for a required package to provide macros to be
-expanded at byte-compilation time, top level calls of `require' are
-evaluated both at byte-compile time and at run time.  That is, any top-level
-call to `require' is wrapped in an implicit \(eval-and-compile ...\) block.
+Ensure that FEATURE is present in the Lisp environment.
+FEATURE is a symbol naming a collection of resources (functions, etc).
+Optional FILENAME is a library from which to load resources; it defaults to
+the print name of FEATURE.
+Optional NOERROR, if non-nil, causes require to return nil rather than signal
+`file-error' if loading the library fails.
+
+If feature FEATURE is present in `features', update `load-history' to reflect
+the require and return FEATURE.  Otherwise, try to load it from a library.
+The normal messages at start and end of loading are suppressed.
+If the library is successfully loaded and it calls `(provide FEATURE)', add
+FEATURE to `features', update `load-history' and return FEATURE.
+If the load succeeds but FEATURE is not provided by the library, signal
+`invalid-state'.
+
+The byte-compiler treats top-level calls to `require' specially, by evaluating
+them at compile time (and then compiling them normally).  Thus a library may
+request that definitions that should be inlined such as macros and defsubsts
+be loaded into its compilation environment.  Achieving this in other contexts
+requires an explicit \(eval-and-compile ...\) block.
 */
        (feature, filename, noerror))
 {