(text_read_only): New function.

[gnu-emacs] / lispref / customize.texi

diff --git a/lispref/customize.texi b/lispref/customize.texi
index ff5f724cd74172eb8035c8e080595e9f3f791c3a..2ce5f5ed4ae48718d8fbb7e4ff76f7d6f40ff084 100644 (file)
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998 Free Software Foundation, Inc. 
+@c Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/customize
 @node Customization, Loading, Macros, Top
@@ -64,6 +64,10 @@ in the customization buffer with the Info node name.
 @item (url-link @var{url})
 Link to a web page; @var{url} is a string which specifies the @sc{url}.
 The link appears in the customization buffer as @var{url}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
 @end table
 
 You can specify the text to use in the customization buffer by adding
@@ -110,7 +114,6 @@ keyword.
   The way to declare new customization groups is with @code{defgroup}.
 
 @defmac defgroup group members doc [keyword value]...
-@tindex defgroup
 Declare @var{group} as a customization group containing @var{members}.
 Do not quote the symbol @var{group}.  The argument @var{doc} specifies
 the documentation string for the group.  It should not start with a
@@ -127,8 +130,20 @@ is a symbol, and @var{widget} is a widget type for editing that symbol.
 Useful widgets are @code{custom-variable} for a variable,
 @code{custom-face} for a face, and @code{custom-group} for a group.
 
+When a new group is introduced into Emacs, use this keyword in
+@code{defgroup}:
+
+@table @code
+@item :version @var{version}
+This option specifies that the group was first introduced in Emacs
+version @var{version}.  The value @var{version} must be a string.
+@end table
+
+Tag the group with a version like this when it is introduced, rather
+than the individual members (@pxref{Variable Definitions}).
+
 In addition to the common keywords (@pxref{Common Keywords}), you can
-use this keyword in @code{defgroup}:
+also use this keyword in @code{defgroup}:
 
 @table @code
 @item :prefix @var{prefix}
@@ -163,7 +178,6 @@ turn this feature back on, if someone would like to do the work.
   Use @code{defcustom} to declare user-editable variables.
 
 @defmac defcustom option default doc [keyword value]...
-@tindex defcustom
 Declare @var{option} as a customizable user option variable.  Do not
 quote @var{option}.  The argument @var{doc} specifies the documentation
 string for the variable; it should normally start with a @samp{*}.  This
@@ -257,6 +271,13 @@ Use the @code{:set} function to initialize the variable, if it is
 already set or has been customized; otherwise, just use
 @code{set-default}.
 @end table
+
+@item :set-after @var{variables}
+When setting variables according to saved customizations, make sure to
+set the variables @var{variables} before this one; in other words, delay
+setting this variable until after those others have been handled.  Use
+@code{:set-after} if setting this variable won't work properly unless
+those other variables already have their intended values.
 @end table
 
   The @code{:require} option is useful for an option that turns on the
@@ -267,7 +288,7 @@ Keywords}.  Here is an example, from the library @file{paren.el}:
 
 @example
 (defcustom show-paren-mode nil
-  "Toggle Show Paren mode@enddots{}"
+  "Toggle Show Paren mode..."
   :set (lambda (symbol value)
          (show-paren-mode (or value 0)))
   :initialize 'custom-initialize-default
@@ -490,13 +511,16 @@ key, using variations of this trick:
 (defcustom person-data '(("brian"  50 t) 
                          ("dorith" 55 nil)
                          ("ken"    52 t))
-  "Alist of people, each element has the form (NAME AGE MALE)."
+  "Alist of basic info about people.
+Each element has the form (NAME AGE MALE-FLAG)."
   :type '(alist :value-type (group age boolean)))
 
 (defcustom pets '(("brian") 
                   ("dorith" "dog" "guppy")
                   ("ken" "cat"))
-  "Alist where the KEY is a person, and the VALUE is a list of pets."
+  "Alist of people's pets.
+In an element (KEY . VALUE), KEY is the person's name,
+and the VALUE is a list of that person's pets."
   :type '(alist :value-type (repeat string)))
 @end smallexample
 
@@ -534,6 +558,14 @@ using @code{choice} and @code{const} together (see the next section),
 you can specify that the value must be @code{nil} or @code{t}, but also
 specify the text to describe each value in a way that fits the specific
 meaning of the alternative.
+
+@item coding-system
+The value must be a coding-system name, and you can do completion with
+@kbd{M-@key{TAB}}.
+
+@item color
+The value must be a valid color name, and you can do completion with
+@kbd{M-@key{TAB}}.  A sample is provided,
 @end table
 
 @node Composite Types
@@ -862,8 +894,11 @@ provide more information about the meanings of alternatives inside a
 
 @item :help-echo @var{motion-doc}
 When you move to this item with @code{widget-forward} or
-@code{widget-backward}, it will display the string @var{motion-doc}
-in the echo area.
+@code{widget-backward}, it will display the string @var{motion-doc} in
+the echo area.  In addition, @var{motion-doc} is used as the mouse
+@code{help-echo} string and may actually be a function or form evaluated
+to yield a help string as for @code{help-echo} text properties.
+@c @xref{Text help-echo}.
 
 @item :match @var{function}
 Specify how to decide whether a value matches the type.  The