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 c9d22851ed21e9cce2f6b6295b07242a24e1de13..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


@@ -162,7 +162,7 @@ value was changed in that version.  This keyword takes priority over
 @code{:version}.
 
 @var{package} should be the official name of the package, as a symbol
 @code{:version}.
 
 @var{package} should be the official name of the package, as a symbol

-(e.g.@: @code{MH-E}).  @var{version} should be a string.  If the
+(e.g., @code{MH-E}).  @var{version} should be a string.  If the

 package @var{package} is released as part of Emacs, @var{package} and
 @var{version} should appear in the value of
 @code{customize-package-emacs-version-alist}.
 package @var{package} is released as part of Emacs, @var{package} and
 @var{version} should appear in the value of
 @code{customize-package-emacs-version-alist}.


@@ -261,7 +261,7 @@ If this variable is non-@code{nil}, the prefixes specified by a
 group's @code{:prefix} keyword are omitted from tag names, whenever
 the user customizes the group.
 
 group's @code{:prefix} keyword are omitted from tag names, whenever
 the user customizes the group.
 

-The default value is @code{nil}, i.e.@: the prefix-discarding feature
+The default value is @code{nil}, i.e., the prefix-discarding feature

 is disabled.  This is because discarding prefixes often leads to
 confusing names for options and faces.
 @end defopt
 is disabled.  This is because discarding prefixes often leads to
 confusing names for options and faces.
 @end defopt


@@ -282,18 +282,22 @@ variable should be displayed in the Customize interface, the values it
 is allowed to take, etc.
 
 @defmac defcustom option standard doc [keyword value]@dots{}
 is allowed to take, etc.
 
 @defmac defcustom option standard doc [keyword value]@dots{}

-This macro declares @var{option} as a user option (i.e.@: a
+This macro declares @var{option} as a user option (i.e., a

 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
 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

-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


@@ -303,17 +307,21 @@ evaluate at any time.
 The argument @var{doc} specifies the documentation string for the
 variable.
 
 The argument @var{doc} specifies the documentation string for the
 variable.
 

-Every @code{defcustom} should specify @code{:group} at least once.
+If a @code{defcustom} does not specify any @code{:group}, the last group
+defined with @code{defgroup} in the same file will be used.  This way, most
+@code{defcustom} do not need an explicit @code{:group}.

 
 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
 mode (@code{eval-defun}), a special feature of @code{eval-defun}
 arranges to set the variable unconditionally, without testing whether
 
 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
 mode (@code{eval-defun}), a special feature of @code{eval-defun}
 arranges to set the variable unconditionally, without testing whether

-its value is void.  (The same feature applies to @code{defvar}.)
-@xref{Defining Variables}.
+its value is void.  (The same feature applies to @code{defvar},
+@pxref{Defining Variables}.)  Using @code{eval-defun} on a defcustom
+that is already defined calls the @code{:set} function (see below),
+if there is one.

 
 If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
 (@pxref{Building Emacs}), the standard value installed at dump time
 
 If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
 (@pxref{Building Emacs}), the standard value installed at dump time

-might be incorrect, e.g.@: because another variable that it depends on
+might be incorrect, e.g., because another variable that it depends on

 has not been assigned the right value yet.  In that case, use
 @code{custom-reevaluate-setting}, described below, to re-evaluate the
 standard value after Emacs starts up.
 has not been assigned the right value yet.  In that case, use
 @code{custom-reevaluate-setting}, described below, to re-evaluate the
 standard value after Emacs starts up.


@@ -345,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.


@@ -472,8 +481,8 @@ Internally, @code{defcustom} uses the symbol property
 @code{saved-value} to record the value saved by the user with the
 customization buffer, and @code{customized-value} to record the value
 set by the user with the customization buffer, but not saved.
 @code{saved-value} to record the value saved by the user with the
 customization buffer, and @code{customized-value} to record the value
 set by the user with the customization buffer, but not saved.

-@xref{Property Lists}.  These properties are lists, the car of which
-is an expression that evaluates to the value.
+@xref{Symbol Properties}.  These properties are lists, the car of
+which is an expression that evaluates to the value.

 
 @defun custom-reevaluate-setting symbol
 This function re-evaluates the standard value of @var{symbol}, which
 
 @defun custom-reevaluate-setting symbol
 This function re-evaluates the standard value of @var{symbol}, which


@@ -563,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


@@ -616,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}}.


@@ -828,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).


@@ -1073,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}


@@ -1214,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


@@ -1283,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


@@ -1340,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,


@@ -1415,11 +1432,22 @@ disabling themes:
 
 @defun custom-theme-p theme
 This function return a non-@code{nil} value if @var{theme} (a symbol)
 
 @defun custom-theme-p theme
 This function return a non-@code{nil} value if @var{theme} (a symbol)

-is the name of a Custom theme (i.e.@: a Custom theme which has been
+is the name of a Custom theme (i.e., a Custom theme which has been

 loaded into Emacs, whether or not the theme is enabled).  Otherwise,
 it returns @code{nil}.
 @end defun
 
 loaded into Emacs, whether or not the theme is enabled).  Otherwise,
 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