* sem-user.texi (Semanticdb Search Configuration): Rearrange nodes.

(Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler):
Numerous copyedits.

2 files changed, 157 insertions, 199 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index f95f251d08e..cffce1a6996 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,9 @@
+2009-11-20  Chong Yidong  <cyd@stupidchicken.com>
+
+        * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes.
+        (Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler):
+        Numerous copyedits.
+
 2009-11-17  Juanma Barranquero  <lekktu@gmail.com>
 
         * semantic.texi (Semantic Internals, Glossary):
diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi
index dd8f23c2e4f..38bb1d6982e 100644
--- a/doc/misc/sem-user.texi
+++ b/doc/misc/sem-user.texi
@@ -202,7 +202,6 @@ described in the following subsections.
 * Semanticdb Tag Storage::
 * Semanticdb Search Configuration::
 * Changing Backends::
-* Script Generated Cache Files::
 * Create System Databases::
 @end menu
 
@@ -277,59 +276,105 @@ written.
 @subsection Semanticdb Search Configuration
 
   When another part of @semantic{} (or another Emacs package using
-@semantic{}) searches for a tag within SemanticDB, the SemanticDB
-library may perform a search in the locations of the database:
-
-@enumerate
-@item
-The entries defined by the current file.
-@item
-The entries defined by the @dfn{include files} of the current file.
-@item
-The entries defined by the include files included from the include
-files (and so on, recursively).
-@end enumerate
-
-In C and C++, for instance, include files are defined with the
-@samp{#include} preprocessor directive (SemanticDB tries to
-distinguish between project and system headers, based on the @code{""}
-and @code{<>} filename delimiters).  Include directives are matched to
-filenames in the SemanticDB cache using the following criteria:
-
-@enumerate
-@item
-Whether the file is in the same directory as the current file
-@item
-Whether the file is in the same project, as defined by EDE
-(@pxref{Top,,,ede,EDE manual}) or the @code{semanticdb-project-roots}
-variable (@pxref{Semanticdb Roots}).
-@item
-Whether the file is in the @dfn{system include path} (@pxref{Include
-paths}).
-@end enumerate
+@semantic{}) queries the SemanticDB library for a source code tag, the
+search need not be limited to tags defined within the current file.
+It can include tags defined elsewhere, such as @dfn{header files}
+referenced by the current file (e.g., via the C/C++ @code{#include}
+directive).  While performing the search, the SemanticDB library may
+even automatically visit other files and parse them, if necessary.
+
+  The variable @code{semanticdb-find-default-throttle} determines how
+aggressively SemanticDB searches for source code tags.  @xref{Search
+Throttle}.
+
+  The details of SemanticDB searches can vary from language to
+language.  In C/C++ code, for example, SemanticDB distinguishes
+between @dfn{project header files} and @dfn{system header files},
+based on whether the @code{#include} directive uses the @code{""} or
+@code{<>} filename delimiter.  SemanticDB looks for system header in
+the @dfn{system include path} (@pxref{Include paths}).
 
 @menu
+* Search Throttle::     Controlling how semanticdb searches occur
 * Semanticdb Roots::    Specifying the root of different projects
 * Include paths::       Add/Remove directories to include search paths
-* Search Throttle::     Controlling how semanticdb searches occur
 * Semanticdb search debugging commands::
 @end menu
 
+@node Search Throttle
+@subsubsection SemanticDB Search Throttle
+
+The SemanticDB @dfn{search throttle} determines how aggressive
+SemanticDB searches are.  It is controlled by the variable
+@code{semanticdb-find-default-throttle}.  The default value of this
+variable aims for maximum accuracy, at the expense of search time.
+
+Other parts of the @semantic{} package, particularly the different
+language parsers, may change the value of
+@code{semanticdb-find-default-throttle}.  You can override its value,
+for a given major mode, like this:
+
+@example
+(setq-mode-local c-mode
+                 semanticdb-find-default-throttle
+                 '(project unloaded system recursive))
+@end example
+
+@anchor{semanticdb-find-default-throttle}
+@defvar semanticdb-find-default-throttle
+The default throttle for @code{semanticdb-find} routines.
+The throttle controls how detailed the list of database
+tables is for a symbol lookup.  The value is a list with
+the following keys:
+
+@table @code
+@item file
+The file the search is being performed from.  This option is here for
+completeness only, and is assumed to always be on.
+@item local
+Tables from the same local directory are included.  This includes
+files directly referenced by a file name which might be in a different
+directory.
+@item project
+Tables from the same local project are included If @code{project} is
+specified, then @code{local} is assumed.
+@item unloaded
+If a table is not in memory, load it.  If it is not cached on disk
+either, get the source, parse it, and create the table.
+@item system
+Tables from system databases.  These are specifically tables
+from system header files, or language equivalent.
+@item recursive
+For include based searches, includes tables referenced by included
+files.
+@item omniscience
+Included system databases which are omniscience, or somehow know
+everything.  Omniscience databases are found in
+@code{semanticdb-project-system-databases}.  The Emacs Lisp system
+@var{db} is an omniscience database.
+@end table
+@end defvar
+
 @node Semanticdb Roots
 @subsubsection SemanticDB project roots
 
-Project roots are the ``top-level'' directories for a single code
-project.  With the exception of system directories, SemanticDB
-searches are usually limited to the current single code project.
-Therefore, it is helpful to specify the project root if you want
-@semantic{} tag searches to work correctly.
+The @code{project} setting in the SemanticDB search throttle
+(@pxref{Search Throttle}) tells SemanticDB to search within the
+current single code project.  For @semantic{}'s point of view,
+@dfn{projects} are determined by their top-level directories, or
+@dfn{project roots}; every subdirectory of a project root is
+considered part of the same project.
+
+If you use EDE for project management, it will set the project roots
+automatically.  @xref{Top,,,ede,EDE manual}.  You can also specify
+them yourself.
 
 @anchor{semanticdb-project-roots}
 @deffn Option semanticdb-project-roots
 The value of this variable is a list of directories (strings) that are
-project root.  All subdirectories of a project root are considered
-part of the same project.  This variable can be overriden by project
-management programs via @code{semanticdb-project-root-functions}.
+project roots.  All subdirectories of a project root are considered
+part of the same project.  This variable can be overriden by
+@code{semanticdb-project-root-functions}.
 @end deffn
 
 @anchor{semanticdb-project-root-functions}
@@ -343,30 +388,27 @@ non-@code{nil} return value, if any, is taken to be the project root,
 overriding @code{semanticdb-project-roots}.
 @end defvar
 
-If you use EDE for project management, it will set
-@code{semanticdb-project-root-functions} automatically.
-@xref{Top,,,ede,EDE manual}.
-
 @node Include paths
 @subsubsection Include Paths
 
 System include paths are standard locations to find source code tags,
 such as the @dfn{header files} in @file{/usr/include} and its
-subdirectories on Unix-like operating systems.  You can add and remove
-system include paths using the following commands:
+subdirectories on Unix-like operating systems.
+
+You can add and remove system include paths using the following
+commands:
 
 @anchor{semantic-add-system-include}
 @deffn Command semantic-add-system-include dir &optional mode
-This command prompts for a directory, @var{dir}, and adds it as a
-system include path for the current major mode.  When called
-non-interactively, the major mode can be specified with the @var{mode}
-argument.
+Prompts for a directory, @var{dir}, and add it as a system include
+path for the current major mode.  When called non-interactively, the
+major mode can be specified with the @var{mode} argument.
 @end deffn
 
 @anchor{semantic-remove-system-include}
 @deffn Command semantic-remove-system-include dir &optional mode
-This command prompt for a directory, @var{dir}, and removes it from
-the system include path for the current major mode (or @var{mode}).
+Prompt for a directory, @var{dir}, and remove it from the system
+include path for the current major mode (or @var{mode}).
 @end deffn
 
 @anchor{semantic-customize-system-include-path}
@@ -384,80 +426,17 @@ any symbols that exist for all files for that mode are included.
 
 @c @xref{Search Optimization}, for more information on include paths.
 
-@node Search Throttle
-@subsubsection SemanticDB Search Throttle
-
-The SemanticDB search throttle is a variable that may be configured by
-a language support author.  If you need to customize this for
-yourself, you may need to override the mode values in a mode support
-hook.
-
-@defvar semanticdb-find-default-throttle
-@anchor{semanticdb-find-default-throttle}
-The default throttle for @code{semanticdb-find} routines.
-The throttle controls how detailed the list of database
-tables is for a symbol lookup.  The value is a list with
-the following keys:
-
-@table @code
-@item file
-The file the search is being performed from.  This option is here for
-completeness only, and is assumed to always be on.
-@item local
-Tables from the same local directory are included.  This includes
-files directly referenced by a file name which might be in a different
-directory.
-@item project
-Tables from the same local project are included If @code{project} is
-specified, then @code{local} is assumed.
-@item unloaded
-If a table is not in memory, load it.  If it is not cached on disk
-either, get the source, parse it, and create the table.
-@item system
-Tables from system databases.  These are specifically tables
-from system header files, or language equivalent.
-@item recursive
-For include based searches, includes tables referenced by included
-files.
-@item omniscience
-Included system databases which are omniscience, or somehow know
-everything.  Omniscience databases are found in
-@code{semanticdb-project-system-databases}.  The Emacs Lisp system
-@var{db} is an omniscience database.
-@end table
-
-@end defvar
-
-To set the throttle, use a command like this:
-
-@example
-(setq-mode-local c-mode
-                 semanticdb-find-default-throttle
-                 '(project unloaded system recursive))
-@end example
-
-The default value of the throttle is for maximum accuracy at the
-expense of time taken to perform a particular look-up.  The throttle
-is tweaked by @code{semantic-idle-summary-mode} to remove 'unloaded,
-thus removing poor speed at unexpected times.
-
 @node Semanticdb search debugging commands
 @subsubsection Semanticdb search debugging commands
 
-You can use @kbd{M-x semanticdb-dump-all-table-summary RET} to see the
-list of databases that will be searched from a given buffer.  It
-should include DBs for the directories you expect.  You can follow up
-with @kbd{M-x semanticdb-find-test-translate-path RET} to then make
-sure specific tables from the path are discovered correctly.
+You can use @kbd{M-x semanticdb-dump-all-table-summary} to see the
+list of databases that will be searched from a given buffer.  You can
+follow up with @kbd{M-x semanticdb-find-test-translate-path} to then
+make sure specific tables from the path are discovered correctly.
 
 Alternately, you can get a list of include files @semantic{}
-encountered, but could not find on disk using
-@kbd{M-x semanticdb-find-adebug-lost-includes RET}.
-
-Once you have used the below functions to debug the problem, you may
-need to reconfigure how @semantic{} finds include files.
-See @ref{Semanticdb Search Configuration}.  If the search config is
-ok, you may need to configure the search throttle.  See @ref{Search Throttle}.
+encountered, but could not find on disk using @kbd{M-x
+semanticdb-find-adebug-lost-includes}.
 
 @deffn Command semanticdb-dump-all-table-summary
 @anchor{semanticdb-dump-all-table-summary}
@@ -495,27 +474,13 @@ The default is to save databases in flat files.  Alternatively, you
 could write a new database backend that stores tags into a database,
 or other storage system.
 
-@defvar semanticdb-new-database-class
 @anchor{semanticdb-new-database-class}
-The default type of database created for new files.
-This can be changed on a per file basis, so that some directories
-are saved using one mechanism, and some directories via a different
-mechanism.
+@defvar semanticdb-new-database-class
+The default type of database created for new files.  This can be
+changed on a per file basis, so that some directories are saved using
+one mechanism, and some directories via a different mechanism.
 @end defvar
 
-@node Script Generated Cache Files
-@subsection Script Generated Cache Files
-
-You can create new semantic databases with the @file{semanticdb.sh}
-script file.  Give this script the directory you want parsed, and it
-will create a cache file for you.
-
-@example
-$ semanticdb.sh *.el
-@end example
-
-To use these generated tables, you would likely need to restart Emacs.
-
 @node Create System Databases
 @subsection Create System Databases
 
@@ -531,99 +496,86 @@ The database file is stored in ~/.semanticdb, or whichever directory
 is specified by @code{semanticdb-default-system-save-directory}.
 @end deffn
 
-
 @node Idle Scheduler
 @section Idle Scheduler
 @cindex Idle Scheduler
 
-The Idle Scheduler in @semantic{} performs multiple duties.
+The @dfn{Semantic idle scheduler} is a part of @semantic{} that
+performs various operations while Emacs is waiting for user input
+(idle time).  Its primary job is to perform buffer parsing, but it is
+also used for other purposes, such as displaying information about
+tags.
 
-The primary job is to schedule buffer parsing in idle time.  The
-first buffer whose cache is checked is the current buffer.  After
-this, all other buffers are checked.
-
-Once that has been accomplished, scheduled idle processes that use the
-semantic tag tables are run.
-
-@deffn Command global-semantic-idle-scheduler-mode &optional arg
 @anchor{global-semantic-idle-scheduler-mode}
-Toggle global use of option @dfn{semantic-idle-scheduler-mode}.
-The idle scheduler with automatically reparse buffers in idle time,
-and then schedule other jobs setup with @dfn{semantic-idle-scheduler-add}.
-If @var{ARG} is positive, enable, if it is negative, disable.
-If @var{ARG} is @code{nil}, then toggle.
-@obsolete{global-semantic-auto-parse-mode,global-semantic-idle-scheduler-mode}
+@deffn Command global-semantic-idle-scheduler-mode &optional arg
+This command toggles Semantic Idle Scheduler mode in every
+@semantic{}-enabled buffer.  This minor mode ensures that the buffer
+is automatically reparsed whenever Emacs is idle.  If there is
+additional idle time, it runs jobs scheduled by other parts of
+@semantic{}, such as Semantic Idle Summary mode (@pxref{Idle Summary
+Mode}) and Semantic Idle Completions mode (@pxref{Idle Completions
+Mode}).
 @end deffn
 
-@obsolete{semantic-auto-parse-mode, semantic-idle-scheduler-mode}
-
-@deffn Option semantic-idle-scheduler-idle-time
 @anchor{semantic-idle-scheduler-idle-time}
-Time in seconds of idle before scheduling events.
-This time should be short enough to ensure that idle-scheduler will be
-run as soon as Emacs is idle.
-@end deffn
-
-@deffn Option semantic-idle-scheduler-mode-hook
-@anchor{semantic-idle-scheduler-mode-hook}
-Hook run at the end of function @dfn{semantic-idle-scheduler-mode}.
+@deffn Option semantic-idle-scheduler-idle-time
+The value of this variable is the amount of idle time, in seconds,
+before the Semantic idle scheduler activates.  The default is 1.
 @end deffn
 
-@deffn Option semantic-idle-scheduler-verbose-flag
 @anchor{semantic-idle-scheduler-verbose-flag}
-Non-@code{nil} means that the idle scheduler should provide debug messages.
-Use this setting to debug idle activities.
+@deffn Option semantic-idle-scheduler-verbose-flag
+If this variable is non-@code{nil}, the idle scheduler prints verbose
+messages while running, which are useful for debugging.
 @end deffn
 
-You can add new functionality to the idle scheduler by reading the
-Application Developers Guide
-@inforef{Idle Scheduling, , semantic-appdev.info}.
-
 @menu
-* Reparsing Options::           Reparsing the current buffer in idle time
-* Idle Working Options::        Options for extra work done at idle time
-* Debugging Idle Time Issues::  How to produce good bug reports
-* Idle Summary Mode::           Display prototype of symbol under cursor
-* Idle Completions Mode::       Smart completion pop-up help
+* Reparsing Options::          Reparsing the current buffer in idle time
+* Idle Working Options::       Options for extra work done at idle time
+* Debugging Idle Time Issues:: How to produce good bug reports
+* Idle Summary Mode::          Display prototype of symbol under cursor
+* Idle Completions Mode::      Smart completion pop-up help
 @end menu
 
 @node Reparsing Options
 @subsection Reparsing Options
 
-The Idle Scheduler will automatically reparse all buffers that need
-it.  User input at any time will cancel the operations and return to
-normal editing.
+When activated during idle time, the Semantic idle scheduler
+automatically reparses all buffers that need it.  Any arriving user
+input cancels this, returning Emacs to its normal editing behavior.
 
-@deffn Option semantic-idle-scheduler-max-buffer-size
 @anchor{semantic-idle-scheduler-max-buffer-size}
-Maximum size in bytes of buffers automatically reparsed.
-If this value is less than or equal to @var{0}, buffers are automatically
+@deffn Option semantic-idle-scheduler-max-buffer-size
+Maximum size in bytes of buffers automatically reparsed.  If this
+value is less than or equal to @var{0}, buffers are automatically
 reparsed regardless of their size.
 @end deffn
 
-@deffn Option semantic-idle-scheduler-no-working-message
 @anchor{semantic-idle-scheduler-no-working-message}
-If non-@code{nil}, disable display of working messages during parse.
+@deffn Option semantic-idle-scheduler-no-working-message
+If non-@code{nil}, disable display of working messages whie reparsing.
 @end deffn
 
-@deffn Option semantic-idle-scheduler-working-in-modeline-flag
 @anchor{semantic-idle-scheduler-working-in-modeline-flag}
-Non-@code{nil} means show working messages in the mode line.
-Typically, parsing will show messages in the minibuffer.
-This will move the parse message into the modeline.
+@deffn Option semantic-idle-scheduler-working-in-modeline-flag
+If non-@code{nil}, show working messages in the mode line.  Normally,
+re-parsing shows messages in the minibuffer; this moves the parse
+message to the modeline instead.
 @end deffn
 
-@defvar semantic-before-idle-scheduler-reparse-hooks
-@anchor{semantic-before-idle-scheduler-reparse-hooks}
-Hooks run before option @code{semantic-idle-scheduler} begins parsing.
-If any hook throws an error, this variable is reset to nil.
-This hook is not protected from lexical errors.
+@anchor{semantic-before-idle-scheduler-reparse-hook}
+@defvar semantic-before-idle-scheduler-reparse-hook
+This normal hook is run just before the idle scheduler begins
+reparsing.  If any hook function throws an error, the value of this
+variable is reset to @code{nil}.  This hook is not protected from
+lexical errors.
 @end defvar
 
-@defvar semantic-after-idle-scheduler-reparse-hooks
-@anchor{semantic-after-idle-scheduler-reparse-hooks}
-Hooks run after option @code{semantic-idle-scheduler} has parsed.
-If any hook throws an error, this variable is reset to nil.
+@anchor{semantic-after-idle-scheduler-reparse-hook}
+@defvar semantic-after-idle-scheduler-reparse-hook
+
+This normal hook is run after the idle scheduler finishes reparsing.
+If any hook throws an error, this variable is reset to @code{nil}.
 This hook is not protected from lexical errors.
 @end defvar