From 97b0e41c5d9b4bd81ba35ba7d30d9bd26ec7b145 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 13 Jan 2018 12:48:07 +0200
Subject: [PATCH] Improve documentation of safe values of variables

* doc/lispref/variables.texi (File Local Variables): Mention the
autoload cookie as a means of defining safe values for variables.
See http://lists.gnu.org/archive/html/emacs-devel/2018-01/msg00261.html
for the details.
* doc/lispref/compile.texi (Compiler Errors): Document
'byte-compile-error-on-warn'.
---
 doc/lispref/compile.texi   |  5 +++++
 doc/lispref/variables.texi | 15 ++++++++++++++-
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 32162c9c22b..212b5a45dc6 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -524,6 +524,11 @@ one you intend to suppress.
 the variable @code{byte-compile-warnings}.  See its documentation
 string for details.
 
+@vindex byte-compile-error-on-warn
+  Sometimes you may wish the byte-compiler warnings to be reported
+using @code{error}.  If so, set @code{byte-compile-error-on-warn} to a
+non-nil value.
+
 @node Byte-Code Objects
 @section Byte-Code Function Objects
 @cindex compiled function
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 01cacb0b23c..fe69b7b8e7b 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1811,10 +1811,23 @@ variables have @code{safe-local-variable} properties; these include
 For boolean-valued variables that are safe, use @code{booleanp} as the
 property value.
 
+@cindex autoload cookie, and safe values of variable
   When defining a user option using @code{defcustom}, you can set its
 @code{safe-local-variable} property by adding the arguments
 @code{:safe @var{function}} to @code{defcustom} (@pxref{Variable
-Definitions}).
+Definitions}).  However, a safety predicate defined using @code{:safe}
+will only be known once the byte-compiler is loaded.  As an
+alternative, you can use the autoload cookie (@pxref{Autoload}) to
+assign the option its safety predicate, like this:
+
+@lisp
+;;;###autoload (put '@var{var} 'safe-local-variable '@var{pred})
+@end lisp
+
+@noindent
+The safe value definitions specified with @code{autoload} are copied
+into the @file{loaddefs.el} file, and are known to Emacs since the
+beginning of a session.
 
 @defopt safe-local-variable-values
 This variable provides another way to mark some variable values as
-- 
2.39.5