Mercurial > emacs

--- a/doc/misc/ChangeLog	Fri Nov 20 01:35:49 2009 +0000
+++ b/doc/misc/ChangeLog	Fri Nov 20 01:52:41 2009 +0000
@@ -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):
--- a/doc/misc/sem-user.texi	Fri Nov 20 01:35:49 2009 +0000
+++ b/doc/misc/sem-user.texi	Fri Nov 20 01:52:41 2009 +0000
@@ -202,7 +202,6 @@
 * Semanticdb Tag Storage::
 * Semanticdb Search Configuration::
 * Changing Backends::
-* Script Generated Cache Files::
 * Create System Databases::
 @end menu

@@ -277,123 +276,52 @@
 @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
+@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.

-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:
+  The variable @code{semanticdb-find-default-throttle} determines how
+aggressively SemanticDB searches for source code tags.  @xref{Search
+Throttle}.

-@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
+  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 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.
-
-@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}.
-@end deffn
-
-@anchor{semanticdb-project-root-functions}
-@defvar semanticdb-project-root-functions
-The value of this variable is a list of functions to determine a given
-directory's project root.  These functions are called, one at a time,
-with one argument (the directory name), and must return either
-@code{nil}, a string (the project root), or a list of strings
-(multiple project roots, for complex systems).  The first
-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:
-
-@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.
-@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}).
-@end deffn
-
-@anchor{semantic-customize-system-include-path}
-@deffn Command semantic-customize-system-include-path &optional mode
-Customize the system include path for the current major mode (or
-@var{mode}).
-@end deffn
-
-@anchor{semanticdb-implied-include-tags}
-@defun semanticdb-implied-include-tags
-Include tags implied for all files of a given mode.  You can set this
-variable with @code{defvar-mode-local} for a particular mode so that
-any symbols that exist for all files for that mode are included.
-@end defun
-
-@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.
+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
-@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
@@ -425,39 +353,90 @@
 @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
+
+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 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}
+@defvar semanticdb-project-root-functions
+The value of this variable is a list of functions to determine a given
+directory's project root.  These functions are called, one at a time,
+with one argument (the directory name), and must return either
+@code{nil}, a string (the project root), or a list of strings
+(multiple project roots, for complex systems).  The first
+non-@code{nil} return value, if any, is taken to be the project root,
+overriding @code{semanticdb-project-roots}.
 @end defvar

-To set the throttle, use a command like this:
+@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:
+
+@anchor{semantic-add-system-include}
+@deffn Command semantic-add-system-include dir &optional mode
+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

-@example
-(setq-mode-local c-mode
-		 semanticdb-find-default-throttle
-		 '(project unloaded system recursive))
-@end example
+@anchor{semantic-remove-system-include}
+@deffn Command semantic-remove-system-include dir &optional 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

-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.
+@anchor{semantic-customize-system-include-path}
+@deffn Command semantic-customize-system-include-path &optional mode
+Customize the system include path for the current major mode (or
+@var{mode}).
+@end deffn
+
+@anchor{semanticdb-implied-include-tags}
+@defun semanticdb-implied-include-tags
+Include tags implied for all files of a given mode.  You can set this
+variable with @code{defvar-mode-local} for a particular mode so that
+any symbols that exist for all files for that mode are included.
+@end defun
+
+@c @xref{Search Optimization}, for more information on include paths.

 @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 @@
 could write a new database backend that stores tags into a database,
 or other storage system.

+@anchor{semanticdb-new-database-class}
 @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.
+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 @@
 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 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.
+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.

+@anchor{global-semantic-idle-scheduler-mode}
 @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}
+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}
-
+@anchor{semantic-idle-scheduler-idle-time}
 @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}.
+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

+@anchor{semantic-idle-scheduler-verbose-flag}
 @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.
+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.

+@anchor{semantic-idle-scheduler-max-buffer-size}
 @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
+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

+@anchor{semantic-idle-scheduler-no-working-message}
 @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.
+If non-@code{nil}, disable display of working messages whie reparsing.
 @end deffn

+@anchor{semantic-idle-scheduler-working-in-modeline-flag}
 @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.
+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