[Emacs-diffs] emacs/doc/misc ChangeLog sem-user.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/11/20 01:52:42

Modified files:
        doc/misc       : ChangeLog sem-user.texi 

Log message:
        * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes.
        (Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler):
        Numerous copyedits.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/ChangeLog?cvsroot=emacs&r1=1.341&r2=1.342
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/sem-user.texi?cvsroot=emacs&r1=1.3&r2=1.4

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/ChangeLog,v
retrieving revision 1.341
retrieving revision 1.342
diff -u -b -r1.341 -r1.342
--- ChangeLog   17 Nov 2009 01:52:48 -0000      1.341
+++ ChangeLog   20 Nov 2009 01:52:41 -0000      1.342
@@ -1,3 +1,9 @@
+2009-11-20  Chong Yidong  <address@hidden>
+
+       * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes.
+       (Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler):
+       Numerous copyedits.
+
 2009-11-17  Juanma Barranquero  <address@hidden>
 
        * semantic.texi (Semantic Internals, Glossary):

Index: sem-user.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/sem-user.texi,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- sem-user.texi       17 Nov 2009 04:44:58 -0000      1.3
+++ sem-user.texi       20 Nov 2009 01:52:42 -0000      1.4
@@ -202,7 +202,6 @@
 * Semanticdb Tag Storage::
 * Semanticdb Search Configuration::
 * Changing Backends::
-* Script Generated Cache Files::
 * Create System Databases::
 @end menu
 
@@ -277,59 +276,105 @@
 @subsection Semanticdb Search Configuration
 
   When another part of @semantic{} (or another Emacs package using
address@hidden) searches for a tag within SemanticDB, the SemanticDB
-library may perform a search in the locations of the database:
-
address@hidden
address@hidden
-The entries defined by the current file.
address@hidden
-The entries defined by the @dfn{include files} of the current file.
address@hidden
-The entries defined by the include files included from the include
-files (and so on, recursively).
address@hidden enumerate
-
-In C and C++, for instance, include files are defined with the
address@hidden 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:
-
address@hidden
address@hidden
-Whether the file is in the same directory as the current file
address@hidden
-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}).
address@hidden
-Whether the file is in the @dfn{system include path} (@pxref{Include
-paths}).
address@hidden enumerate
address@hidden) 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
address@hidden<>} 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
 
address@hidden Search Throttle
address@hidden SemanticDB Search Throttle
+
+The SemanticDB @dfn{search throttle} determines how aggressive
+SemanticDB searches are.  It is controlled by the variable
address@hidden  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
address@hidden  You can override its value,
+for a given major mode, like this:
+
address@hidden
+(setq-mode-local c-mode
+                semanticdb-find-default-throttle
+                '(project unloaded system recursive))
address@hidden example
+
address@hidden
address@hidden 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:
+
address@hidden @code
address@hidden file
+The file the search is being performed from.  This option is here for
+completeness only, and is assumed to always be on.
address@hidden 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.
address@hidden project
+Tables from the same local project are included If @code{project} is
+specified, then @code{local} is assumed.
address@hidden 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.
address@hidden system
+Tables from system databases.  These are specifically tables
+from system header files, or language equivalent.
address@hidden recursive
+For include based searches, includes tables referenced by included
+files.
address@hidden omniscience
+Included system databases which are omniscience, or somehow know
+everything.  Omniscience databases are found in
address@hidden  The Emacs Lisp system
address@hidden is an omniscience database.
address@hidden table
address@hidden 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
address@hidden 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,
address@hidden are determined by their top-level directories, or
address@hidden 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
address@hidden
 @end deffn
 
 @anchor{semanticdb-project-root-functions}
@@ -343,30 +388,27 @@
 overriding @code{semanticdb-project-roots}.
 @end defvar
 
-If you use EDE for project management, it will set
address@hidden automatically.
address@hidden,,,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 @@
 
 @c @xref{Search Optimization}, for more information on include paths.
 
address@hidden Search Throttle
address@hidden 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.
-
address@hidden semanticdb-find-default-throttle
address@hidden
-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:
-
address@hidden @code
address@hidden file
-The file the search is being performed from.  This option is here for
-completeness only, and is assumed to always be on.
address@hidden 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.
address@hidden project
-Tables from the same local project are included If @code{project} is
-specified, then @code{local} is assumed.
address@hidden 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.
address@hidden system
-Tables from system databases.  These are specifically tables
-from system header files, or language equivalent.
address@hidden recursive
-For include based searches, includes tables referenced by included
-files.
address@hidden omniscience
-Included system databases which are omniscience, or somehow know
-everything.  Omniscience databases are found in
address@hidden  The Emacs Lisp system
address@hidden is an omniscience database.
address@hidden table
-
address@hidden defvar
-
-To set the throttle, use a command like this:
-
address@hidden
-(setq-mode-local c-mode
-                semanticdb-find-default-throttle
-                '(project unloaded system recursive))
address@hidden 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
address@hidden 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.
 
address@hidden 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.
address@hidden 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
 
address@hidden Script Generated Cache Files
address@hidden 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.
-
address@hidden
-$ semanticdb.sh *.el
address@hidden example
-
-To use these generated tables, you would likely need to restart Emacs.
-
 @node Create System Databases
 @subsection Create System Databases
 
@@ -531,54 +496,39 @@
 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.
-
address@hidden 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.
address@hidden,global-semantic-idle-scheduler-mode}
address@hidden Command global-semantic-idle-scheduler-mode &optional arg
+This command toggles Semantic Idle Scheduler mode in every
address@hidden 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
address@hidden, such as Semantic Idle Summary mode (@pxref{Idle Summary
+Mode}) and Semantic Idle Completions mode (@pxref{Idle Completions
+Mode}).
 @end deffn
 
address@hidden, semantic-idle-scheduler-mode}
-
address@hidden 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.
address@hidden deffn
-
address@hidden Option semantic-idle-scheduler-mode-hook
address@hidden
-Hook run at the end of function @dfn{semantic-idle-scheduler-mode}.
address@hidden 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
 
address@hidden Option semantic-idle-scheduler-verbose-flag
 @anchor{semantic-idle-scheduler-verbose-flag}
address@hidden means that the idle scheduler should provide debug messages.
-Use this setting to debug idle activities.
address@hidden Option semantic-idle-scheduler-verbose-flag
+If this variable is address@hidden, 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
address@hidden 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
@@ -590,40 +540,42 @@
 @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.
 
address@hidden 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
address@hidden 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
 
address@hidden Option semantic-idle-scheduler-no-working-message
 @anchor{semantic-idle-scheduler-no-working-message}
-If address@hidden, disable display of working messages during parse.
address@hidden Option semantic-idle-scheduler-no-working-message
+If address@hidden, disable display of working messages whie reparsing.
 @end deffn
 
address@hidden Option semantic-idle-scheduler-working-in-modeline-flag
 @anchor{semantic-idle-scheduler-working-in-modeline-flag}
address@hidden 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.
address@hidden Option semantic-idle-scheduler-working-in-modeline-flag
+If address@hidden, 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
 
address@hidden semantic-before-idle-scheduler-reparse-hooks
address@hidden
-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.
address@hidden
address@hidden 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
 
address@hidden semantic-after-idle-scheduler-reparse-hooks
address@hidden
-Hooks run after option @code{semantic-idle-scheduler} has parsed.
-If any hook throws an error, this variable is reset to nil.
address@hidden
address@hidden 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