Don't overflow if computing approximate percentage

[gnu-emacs] / doc / lispref / customize.texi

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 56e091eabf2ff3621e8b0ccb60830986bd5e7185..f984dbe5870f5207181a878908d8e5734a849419 100644 (file)
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1997-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1997-2015 Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @node Customization
 @chapter Customization Settings
 @c See the file elisp.texi for copying conditions.
 @node Customization
 @chapter Customization Settings


@@ -77,7 +77,7 @@ item.  Please don't overdo this, since the result would be annoying.
 @item :link @var{link-data}
 @kindex link@r{, customization keyword}
 Include an external link after the documentation string for this item.
 @item :link @var{link-data}
 @kindex link@r{, customization keyword}
 Include an external link after the documentation string for this item.

-This is a sentence containing an active field which references some
+This is a sentence containing a button that references some

 other documentation.
 
 There are several alternatives you can use for @var{link-data}:
 other documentation.
 
 There are several alternatives you can use for @var{link-data}:


@@ -101,7 +101,7 @@ Link to a web page; @var{url} is a string which specifies the
 
 @item (emacs-commentary-link @var{library})
 Link to the commentary section of a library; @var{library} is a string
 
 @item (emacs-commentary-link @var{library})
 Link to the commentary section of a library; @var{library} is a string

-which specifies the library name.
+which specifies the library name.  @xref{Library Headers}.

 
 @item (emacs-library-link @var{library})
 Link to an Emacs Lisp library file; @var{library} is a string which
 
 @item (emacs-library-link @var{library})
 Link to an Emacs Lisp library file; @var{library} is a string which


@@ -287,13 +287,17 @@ customizable variable).  You should not quote @var{option}.
 
 The argument @var{standard} is an expression that specifies the
 standard value for @var{option}.  Evaluating the @code{defcustom} form
 
 The argument @var{standard} is an expression that specifies the
 standard value for @var{option}.  Evaluating the @code{defcustom} form

-evaluates @var{standard}, but does not necessarily install the
-standard value.  If @var{option} already has a default value,
-@code{defcustom} does not change it.  If the user has saved a
-customization for @var{option}, @code{defcustom} installs the user's
-customized value as @var{option}'s default value.  If neither of those
-cases applies, @code{defcustom} installs the result of evaluating
-@var{standard} as the default value.
+evaluates @var{standard}, but does not necessarily bind the option to
+that value.  If @var{option} already has a default value, it is left
+unchanged.  If the user has already saved a customization for
+@var{option}, the user's customized value is installed as the default
+value.  Otherwise, the result of evaluating @var{standard} is
+installed as the default value.
+
+Like @code{defvar}, this macro marks @code{option} as a special
+variable, meaning that it should always be dynamically bound.  If
+@var{option} is already lexically bound, that lexical binding remains
+in effect until the binding construct exits.  @xref{Variable Scoping}.

 
 The expression @var{standard} can be evaluated at various other times,
 too---whenever the customization facility needs to know @var{option}'s
 
 The expression @var{standard} can be evaluated at various other times,
 too---whenever the customization facility needs to know @var{option}'s


@@ -349,8 +353,9 @@ option when using the Customize interface.  The function
 @var{setfunction} should take two arguments, a symbol (the option
 name) and the new value, and should do whatever is necessary to update
 the value properly for this option (which may not mean simply setting
 @var{setfunction} should take two arguments, a symbol (the option
 name) and the new value, and should do whatever is necessary to update
 the value properly for this option (which may not mean simply setting

-the option as a Lisp variable).  The default for @var{setfunction} is
-@code{set-default}.
+the option as a Lisp variable); preferably, though, it should not
+modify its value argument destructively.  The default for
+@var{setfunction} is @code{set-default}.

 
 If you specify this keyword, the variable's documentation string
 should describe how to do the same job in hand-written Lisp code.
 
 If you specify this keyword, the variable's documentation string
 should describe how to do the same job in hand-written Lisp code.


@@ -567,7 +572,7 @@ The value must be an integer.
 The value must be a number (floating point or integer).
 
 @item float
 The value must be a number (floating point or integer).
 
 @item float

-The value must be a floating point number.
+The value must be floating point.

 
 @item string
 The value must be a string.  The customization buffer shows the string
 
 @item string
 The value must be a string.  The customization buffer shows the string


@@ -620,6 +625,11 @@ 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.
 
 specify the text to describe each value in a way that fits the specific
 meaning of the alternative.
 

+@item key-sequence
+The value is a key sequence.  The customization buffer shows the key
+sequence using the same syntax as the @kbd{kbd} function.  @xref{Key
+Sequences}.
+

 @item coding-system
 The value must be a coding-system name, and you can do completion with
 @kbd{M-@key{TAB}}.
 @item coding-system
 The value must be a coding-system name, and you can do completion with
 @kbd{M-@key{TAB}}.


@@ -832,7 +842,7 @@ symbols, and symbols are not treated like other Lisp expressions.
 
 @item (radio @var{element-types}@dots{})
 This is similar to @code{choice}, except that the choices are displayed
 
 @item (radio @var{element-types}@dots{})
 This is similar to @code{choice}, except that the choices are displayed

-using `radio buttons' rather than a menu.  This has the advantage of
+using ``radio buttons'' rather than a menu.  This has the advantage of

 displaying documentation for the choices when applicable and so is often
 a good choice for a choice between constant functions
 (@code{function-item} customization types).
 displaying documentation for the choices when applicable and so is often
 a good choice for a choice between constant functions
 (@code{function-item} customization types).


@@ -1077,8 +1087,7 @@ Substitute the item's documentation string.
 
 @item %h
 Like @samp{%d}, but if the documentation string is more than one line,
 
 @item %h
 Like @samp{%d}, but if the documentation string is more than one line,

-add an active field to control whether to show all of it or just the
-first line.
+add a button to control whether to show all of it or just the first line.

 
 @item %t
 Substitute the tag here.  You specify the tag with the @code{:tag}
 
 @item %t
 Substitute the tag here.  You specify the tag with the @code{:tag}


@@ -1218,6 +1227,8 @@ arguments, which will be used when creating the @code{radio-button} or
 
 @node Defining New Types
 @subsection Defining New Types
 
 @node Defining New Types
 @subsection Defining New Types

+@cindex customization types, define new
+@cindex define new customization types

 
 In the previous sections we have described how to construct elaborate
 type specifications for @code{defcustom}.  In some cases you may want
 
 In the previous sections we have described how to construct elaborate
 type specifications for @code{defcustom}.  In some cases you may want


@@ -1287,6 +1298,7 @@ its @code{:type} argument only when needed.
 
 @node Applying Customizations
 @section Applying Customizations
 
 @node Applying Customizations
 @section Applying Customizations

+@cindex applying customizations

 
 The following functions are responsible for installing the user's
 customization settings for variables and faces, respectively.  When
 
 The following functions are responsible for installing the user's
 customization settings for variables and faces, respectively.  When


@@ -1344,6 +1356,7 @@ evaluated.  @var{comment} is a string describing the customization.
 @node Custom Themes
 @section Custom Themes
 
 @node Custom Themes
 @section Custom Themes
 

+@cindex custom themes

   @dfn{Custom themes} are collections of settings that can be enabled
 or disabled as a unit.  @xref{Custom Themes,,, emacs, The GNU Emacs
 Manual}.  Each Custom theme is defined by an Emacs Lisp source file,
   @dfn{Custom themes} are collections of settings that can be enabled
 or disabled as a unit.  @xref{Custom Themes,,, emacs, The GNU Emacs
 Manual}.  Each Custom theme is defined by an Emacs Lisp source file,


@@ -1424,6 +1437,17 @@ loaded into Emacs, whether or not the theme is enabled).  Otherwise,
 it returns @code{nil}.
 @end defun
 
 it returns @code{nil}.
 @end defun
 

+@defvar custom-known-themes
+The value of this variable is a list of themes loaded into Emacs.
+Each theme is represented by a Lisp symbol (the theme name).  The
+default value of this variable is a list containing two ``dummy''
+themes: @code{(user changed)}.  The @code{changed} theme stores
+settings made before any Custom themes are applied (e.g., variables
+set outside of Customize).  The @code{user} theme stores settings the
+user has customized and saved.  Any additional themes declared with
+the @code{deftheme} macro are added to the front of this list.
+@end defvar
+

 @deffn Command load-theme theme &optional no-confirm no-enable
 This function loads the Custom theme named @var{theme} from its source
 file, looking for the source file in the directories specified by the
 @deffn Command load-theme theme &optional no-confirm no-enable
 This function loads the Custom theme named @var{theme} from its source
 file, looking for the source file in the directories specified by the