# HG changeset patch # User Chong Yidong # Date 1258681961 0 # Node ID 9c5f5e4df2acaeb7cebd32ac8047f14f1deffa2a # Parent 269b53d49dd98d311103bb0d45b30288d33490fb * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes. (Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler): Numerous copyedits. diff -r 269b53d49dd9 -r 9c5f5e4df2ac doc/misc/ChangeLog --- 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 + + * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes. + (Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler): + Numerous copyedits. + 2009-11-17 Juanma Barranquero * semantic.texi (Semantic Internals, Glossary): diff -r 269b53d49dd9 -r 9c5f5e4df2ac doc/misc/sem-user.texi --- 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