-@c This file is included by semantic.texi
-
-@c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007
-@c Free Software Foundation, Inc.
-
-@c Permission is granted to copy, distribute and/or modify this
-@c document under the terms of the GNU Free Documentation License,
-@c Version 1.3 or any later version published by the Free Software
-@c Foundation; with no Invariant Sections, no Front-Cover Texts, and
-@c no Back-Cover Texts. A copy of the license is included in the
-@c section entitled ``GNU Free Documentation License''.
+@c This is part of the Semantic manual.
+@c Copyright (C) 1999-2005, 2007, 2009-2013 Free Software Foundation,
+@c Inc.
+@c See file semantic.texi for copying conditions.
You can begin using @semantic{} by enabling Semantic mode, a global
-minor mode: type @kbd{M-x semantic-mode}, or click on the @samp{Source
-Code Parsers (Semantic)} menu item in the @samp{Tools} menu.
+minor mode: type @kbd{M-x semantic-mode}, or open the @samp{Tools}
+menu and click on the menu item named @samp{Source Code Parsers
+(Semantic)}. @xref{Semantic mode}.
When Semantic mode is turned on, Emacs automatically parses each file
-you visit. This allows you to use @semantic{} user commands in those
-buffers. It also enables a number of ``helper'' minor modes for
-saving tags, displaying tag information, and so forth. @xref{Semantic
-mode}.
+you visit. You can then use @semantic{} user commands in those
+buffers (@pxref{Semantic mode user commands}). You can also choose to
+enable a number of ``helper'' minor modes for saving tags, displaying
+tag information, and so forth.
To enable Semantic mode each time you start Emacs, add the line
@code{(semantic-mode 1)} to your initialization file. @xref{Init
File,,,emacs,Emacs manual}.
@menu
-* Semantic mode:: Global minor mode for @semantic{}.
-* SemanticDB:: Caching parsed buffers between sessions.
-* Idle Scheduler:: Performing @semantic{} operations when idle.
+* Semantic mode:: Global minor mode for @semantic{}.
+* SemanticDB:: Caching parsed buffers between sessions.
+* Idle Scheduler:: @semantic{} actions that occur when idle.
+* Analyzer:: Semantic tools for analyzing code.
+* Speedbar:: Using @semantic{} with the Speedbar.
+* SymRef:: Interface to symbol reference tools.
+* MRU Bookmarks:: Managing tag "bookmarks".
+* Sticky Func Mode:: Showing declarations in the header line.
+* Highlight Func Mode:: Highlight the current function declaration.
+* Tag Decoration Mode:: Minor mode to decorate tags.
@end menu
@node Semantic mode
Semantic mode is a global minor mode for @semantic{} as a whole. When
enabled, each file you visit is automatically parsed, provided its
major mode is specified in the variable
-@code{semantic-new-buffer-setup-functions} (the default is to parse
-every buffer @semantic{} knows how to parse).
+@code{semantic-new-buffer-setup-functions} (the default value of this
+variable sets up parsing for all the parsers included with Emacs, but
+you may add to it if you install additional parsers).
In each parser-enabled buffer, a number of @semantic{} commands are
available for navigating, querying, and editing source code.
installs a @samp{Development} menu on the menu-bar, with many of these
commands.
-In addition, enabling Semantic mode turns on certain auxilliary global
-minor modes, as specified by the variable
-@code{semantic-default-submodes}. The default auxilliary modes are
-SemanticDB mode (@pxref{SemanticDB}) and Global Semantic Idle
-Scheduler mode. You can also toggle the auxilliary minor modes
-separately, using their mode functions (e.g. @kbd{M-x
-semanticdb-minor-mode}), or via the @samp{Development} menu. These
-auxilliary minor modes are described in the following sections.
+In addition, enabling Semantic mode turns on certain auxiliary global
+minor modes. The variable @code{semantic-default-submodes} determines
+which auxiliary modes are enabled; the defaults are SemanticDB mode
+(@pxref{SemanticDB}) and Global Semantic Idle Scheduler mode
+(@pxref{Idle Scheduler}). You can also toggle the auxiliary minor
+modes separately, using their mode functions (e.g., @kbd{M-x
+semanticdb-minor-mode}), or via the @samp{Development} menu. The
+various auxiliary minor modes are described in the following sections.
@defvar semantic-new-buffer-setup-functions
The value of this variable is an alist of functions to call for
@defvar semantic-default-submodes
The value of this variable is a list of symbols, specifying the
-auxilliary minor modes to enable when enabling Semantic mode. The
+auxiliary minor modes to enable when enabling Semantic mode. The
valid mode symbols are:
@itemize
-@item @code{semantic-idle-scheduler-mode} (@pxref{Idle Scheduler}).
-@item @code{semanticdb-minor-mode} (@pxref{SemanticDB}).
-@item @code{semantic-idle-summary-mode} (@pxref{Idle Summary Mode}).
-@item @code{semantic-idle-completions-mode} (@pxref{Idle Completions Mode}).
-@item @code{semantic-highlight-func-mode}
-@item @code{semantic-decoration-mode}
-@item @code{semantic-stickyfunc-mode}
-@item @code{semantic-mru-bookmark-mode}
+@item @code{global-semantic-idle-scheduler-mode} (@pxref{Idle Scheduler}).
+@item @code{global-semanticdb-minor-mode} (@pxref{SemanticDB}).
+@item @code{global-semantic-idle-summary-mode} (@pxref{Idle Summary Mode}).
+@item @code{global-semantic-idle-completions-mode} (@pxref{Idle Completions Mode}).
+@item @code{global-semantic-highlight-func-mode} (@pxref{Highlight Func Mode}).
+@item @code{global-semantic-decoration-mode} (@pxref{Tag Decoration Mode}).
+@item @code{global-semantic-stickyfunc-mode} (@pxref{Sticky Func Mode}).
+@item @code{global-semantic-mru-bookmark-mode} (@pxref{MRU Bookmarks}).
@end itemize
@end defvar
Semantic mode provides a number of commands for navigating, querying,
and editing source code in a language-aware manner. These commands
generally act on @dfn{tags}, which are the source-code units deemed
-``important'' by the present programming language (e.g. functions in
+``important'' by the present programming language (e.g., functions in
the C programming language).
These commands may be used in any buffer that has been parsed by
point.
@table @kbd
-@item \C-c , j
+@item C-c , j
Prompt for a tag defined in the current file, and move point to it
(@code{semantic-complete-jump-local}).
-@item \C-c , J
+@item C-c , J
Prompt for a tag defined in any file that Emacs has parsed, and move
point to it (@code{semantic-complete-jump}).
-@item \C-c , l
+@item C-c , l
Display a list of the possible completions of the current tag
(@code{semantic-analyze-possible-completions}).
-@item \C-c , g
+@item C-c , g
Prompt for a tag, and display a list of tags that call it
-(@code{semantic-symref-symbol}).
+(@code{semantic-symref-symbol}). This relies on the presence of an
+external symbol reference tool. @xref{SymRef}.
-@item \C-c , G
+@item C-c , G
Display a list of tags that call the current tag
-(@code{semantic-symref}).
+(@code{semantic-symref}). This relies on the presence of an external
+symbol reference tool. @xref{SymRef}.
-@item \C-c , p
+@item C-c , p
Move point to the previous tag (@code{senator-previous-tag}).
-@item \C-c , n
+@item C-c , n
Move point to the next tag (@code{senator-next-tag}).
-@item \C-c , u
+@item C-c , u
Move point ``up'' one reference (@code{senator-go-to-up-reference}).
The meaning of ``up'' is language-dependent; in C++, for instance,
this means moving to the parent of the current tag.
-@item \C-c, @key{SPC}
-(@code{semantic-complete-analyze-inline})
+@item C-c, @key{SPC}
+Display a list of possible completions for the symbol at point
+(@code{semantic-complete-analyze-inline}). This also activates a
+special set of keybindings for choosing a completion: @key{RET}
+accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through
+possible completions, @key{TAB} completes as far as possible and then
+cycles, and @kbd{C-g} or any other key aborts the completion.
+@xref{Smart Completion}.
-@item \C-c,\C-w
+@item C-c , C-w
Kill the current tag (@code{senator-kill-tag}). This removes the text
for that tag, placing it in the kill ring. You can retrieve the text
with @kbd{C-y}. This also places the tag in the @dfn{tag ring}, so
that you can yank it with @kbd{\C-c,\C-y}, below.
-@item \C-c,\M-w
+@item C-c , M-w
Copy the current tag into the kill ring as well as the tag ring
(@code{senator-copy-tag}).
-@item \C-c,\C-y
+@item C-c , C-y
Yank a tag from the tag ring (@code{senator-yank-tag}).
-@item \C-c,r
+@item C-c , r
Copy the current tag into a register
(@code{senator-copy-tag-to-register}). With an optional argument,
kill it as well. This allows you to insert or jump to that tag with
the usual register commands. @xref{Registers,,,emacs,Emacs manual}.
-@item ?\C-c , @kbd{up}
+@item C-c , @kbd{up}
Transpose the current tag with the previous one
(@code{senator-transpose-tags-up}).
-@item ?\C-c ?, @kbd{down}
+@item C-c , @kbd{down}
Transpose the current tag with the next one
(@code{senator-transpose-tags-down}).
@end table
* Semanticdb Tag Storage::
* Semanticdb Search Configuration::
* Changing Backends::
-* Script Generated Cache Files::
* Create System Databases::
@end menu
You can change the name of the SemanticDB directory by customizing the
variable @code{semanticdb-default-save-directory}.
-@anchor{semanticdb-default-save-directory}
@deffn Option semanticdb-default-save-directory
The name of the directory where SemanticDB cache files are saved. If
the value is @code{nil}, SemanticDB saves its data into a single file,
@code{semanticdb-default-file-name}.
@end deffn
-@anchor{semanticdb-default-file-name}
@deffn Option semanticdb-default-file-name
The name of a cache file in which to save SemanticDB, when
@code{semanticdb-default-save-directory} is @code{nil}.
suppress saving altogether, by customizing
@code{semanticdb-persistent-path}:
-@anchor{semanticdb-persistent-path}
@deffn Option semanticdb-persistent-path
List of valid paths for SemanticDB to cache. Each element should be a
directory name (a string); then the parse data from any file in that
The default value is @code{(always)}.
@end deffn
-@anchor{semanticdb-project-predicate-functions}
@defvar semanticdb-project-predicate-functions
The value of this variable is a list of predicates for indicating that
a directory belongs to a project. This list is used when the value of
controlled by them.
@end defvar
-@anchor{semanticdb-save-database-hooks}
-@deffn Option semanticdb-save-database-hooks
+@deffn Option semanticdb-save-database-functions
Abnormal hook run after a database is saved. Each function is called
with one argument, the object representing the database recently
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
-* Semanticdb Roots:: Specifying the root of different projects
-* Include paths:: Add/Remove directories to include search paths
-* Search Throttle:: Controlling how semanticdb searches occur
+* Search Throttle:: Controlling how semanticdb searches occur.
+* Semanticdb Roots:: Specifying the root of different projects.
+* Include paths:: Specifying the directories to search.
* 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
-@code{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
@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
@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.
+
+@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 overridden by
+@code{semanticdb-project-root-functions}.
+@end deffn
+
+@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
-@example
-(setq-mode-local c-mode
- semanticdb-find-default-throttle
- '(project unloaded system recursive))
-@end example
+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:
+
+@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
+
+@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
+
+@deffn Command semantic-customize-system-include-path &optional mode
+Customize 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.
+@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}
Dump a list of all databases in Emacs memory.
@end deffn
@deffn Command semanticdb-find-test-translate-path &optional arg
-@anchor{semanticdb-find-test-translate-path}
-Call and output results of @dfn{semanticdb-find-translate-path}
-With @var{arg} non-@code{nil}, specify a @var{brutish} translation.
+Call and output results of @dfn{semanticdb-find-translate-path}. In
+the displayed buffer, you can type @key{SPC} to expand items. With
+@var{arg} non-@code{nil}, specify a @var{brutish} translation.
@end deffn
@deffn Command semanticdb-find-adebug-lost-includes
-@anchor{semanticdb-find-adebug-lost-includes}
Translate the current path, then display the lost includes.
Examines the variable @code{semanticdb-find-lost-includes}.
@end deffn
Lastly, you can test an explicit search term using this command:
@deffn Command semantic-adebug-searchdb regex
-@anchor{semantic-adebug-searchdb}
Search the semanticdb for @var{regex} for the current buffer.
Display the results as a debug list.
@end deffn
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.
+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
summary-mode, or the analyzer.
@deffn Command semanticdb-create-ebrowse-database dir
-@anchor{semanticdb-create-ebrowse-database}
Create an @var{ebrowse} database for directory @var{dir}.
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 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 during idle
+time. You can also use the Idle Scheduler to display function
+prototypes (@pxref{Idle Summary Mode}) or symbol completions
+(@pxref{Idle Completions 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}
-
@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
@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.
@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
@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 while 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.
+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.
+@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.
+@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
@node Idle Working Options
@subsection Idle Working Options
-Similiar to the reparsing that occurs at short intervals in idle
-time, there is extra work that can be controlled to occur in idle time
-also.
-
-Idle work occurs after a longer delay, and can be very time
-consuming. The work done includes:
-
-@table @asis
-@item Create Include Path Caches
-Create the optimized search caches needed for symbol lookup.
-@item Create Type Cache
-Create the datatype caches needed for intellisense features.
-@item Save Databases
-All file-based @semantic{} databases are saved to disk.
-@item Parse neighboring files
-All files in the same directory as the current buffer are
-speculatively parsed.
-@end table
+In addition to reparsing buffers, the Semantic idle scheduler performs
+additional operations, including the following:
+
+@itemize
+@item
+Creating the include path caches required for symbol lookup.
+@item
+Create data type caches.
+@item
+Saving SemanticDB caches to disk.
+@item
+Speculatively parsing the files in the same directory as the current
+buffer.
+@end itemize
-These features can be controlled with the following variables:
+Because this extra work is quite time-consuming, it is only carried
+out after a longer idle delay. The following features control how the
+idle work is performed.
@deffn Option semantic-idle-scheduler-work-idle-time
-@anchor{semantic-idle-scheduler-work-idle-time}
-Time in seconds of idle before scheduling big work.
-This time should be long enough that once any big work is started, it is
-unlikely the user would be ready to type again right away.
+The value of this variable is the amount of idle time, in seconds,
+before commencing idle work. The default is 60.
@end deffn
@deffn Option semantic-idle-work-parse-neighboring-files-flag
-@anchor{semantic-idle-work-parse-neighboring-files-flag}
-Non-@code{nil} means to parse files in the same dir as the current buffer.
-Disable to prevent lots of excessive parsing in idle time.
+If the value of this variable is non-@code{nil}, the Semantic idle
+scheduler uses idle work time to parse files in the same directory as
+the current buffer. This improves the accuracy of tag searches and
+saves time when visiting those files later, at the cost of doing a lot
+of parsing. The default is @code{t}.
@end deffn
@node Debugging Idle Time Issues
@subsection Debugging Idle Time Issues
-If you see errors produced in idle time, it could be an indication of a
-more serious issue elsewhere. It is not enough to enable
-@code{debug-on-error}, as the idle timer tries to keep errors under
-wraps.
-
-Instead, there are two commands you can use whenever you see an idle
-error.
+If you see an error signaled during idle time, it could be an
+indication of a more serious issue elsewhere. It is not enough to
+enable @code{debug-on-error}, because the idle scheduler inhibits the
+debugger. Instead, use the following commands to debug the error:
@deffn Command semantic-debug-idle-function
-@anchor{semantic-debug-idle-function}
Run the Semantic idle function with debugging turned on.
@end deffn
@deffn Command semantic-debug-idle-work-function
-@anchor{semantic-debug-idle-work-function}
Run the Semantic idle work function with debugging turned on.
@end deffn
-Once you identify the general location of the idle error, you can send
-the stack trace to the mailing list, or perhaps find a more focused
-way to reproduce the issue.
-
@node Idle Summary Mode
@subsection Idle Summary Mode
-Similar to the Emacs Lisp facility eldoc,
-@code{semantic-idle-summary-mode} will display the prototype, or other
-helpful doc about the symbol currently under point.
-
+Semantic Idle Summary mode is a minor mode that displays a short
+summary of the symbol at point, such as its function prototype, in the
+echo area. Its functionality is similar to what ElDoc mode provides
+for Emacs Lisp (@pxref{Lisp Doc,,,emacs,Emacs manual}).
-@deffn semantic-idle-summary-mode &optional arg
-@anchor{semantic-idle-summary-mode}
-Display a tag summary of the lexical token under the cursor.
-This means for getting the current tag to display information can
-be overriden with @code{idle-summary-current-symbol-info}.
-This is a minor mode which performs actions during idle time.
-With prefix argument ARG, turn on if positive, otherwise off. The
-minor mode can be turned on only if semantic feature is available and
-the current buffer was set up for parsing. Return non-nil if the
-minor mode is enabled
+@deffn global-semantic-idle-summary-mode &optional arg
+This command toggles Semantic Idle Summary mode in all
+@semantic{}-enabled buffers. You can also toggle it via the
+@samp{Show Tag Summaries} menu item in the @samp{Development} menu.
@end deffn
-@obsolete{semantic-summary-mode, semantic-idle-summary-mode}
+When Semantic Idle Summary mode is active, a summary of the tag at
+point is displayed in the echo area. This display takes place during
+the idle time, as given by @code{semantic-idle-scheduler-idle-time}
+(@pxref{Idle Scheduler}).
+
+You can override the method for getting the current tag to display by
+setting @code{idle-summary-current-symbol-info}.
@deffn Option semantic-idle-summary-function
-@anchor{semantic-idle-summary-function}
-Function to use when displaying tag information during idle time.
-Some useful functions are found in @code{semantic-format-tag-functions}.
+The value of this variable should be a function to call to display tag
+information during idle time. See the variable
+@code{semantic-format-tag-functions} for a list of useful functions.
@end deffn
@defvar semantic-idle-summary-out-of-context-faces
-@anchor{semantic-idle-summary-out-of-context-faces}
-List of font-lock faces that indicate a useless summary context.
-Those are generally faces used to highlight comments or strings.
+The value of this variable is a list of font-lock faces indicating
+useless summary contexts. These are generally faces used to highlight
+comments or strings. Semantic Idle Summary mode does not display its
+usual summary if the text at point has one of these faces.
+@end defvar
+
+@node Idle Completions Mode
+@subsection Idle Completions Mode
-It might be useful to override this variable to add comment faces
-specific to a major mode. For example, in jde mode:
+Semantic Idle Completions mode is a minor mode for performing
+@dfn{code completions} during idle time. The completions are
+displayed inline, with keybindings that allow you to cycle through
+different alternatives.
+
+Semantic Idle Completions mode performs completion based on the
+Semantic Analyzer (@pxref{Analyzer}).
+
+@deffn global-semantic-idle-completions-mode &optional arg
+This command toggles Semantic Idle Completions mode in every
+@semantic{}-enabled buffer. You can also toggle it via the @samp{Show
+Tag Completions} menu item in the @samp{Development} menu.
+@end deffn
+
+If the tag at point has at least one completion, Semantic Idle
+Completions mode displays that completion inline---i.e., as part of
+the buffer text (you can change the display method by customizing
+@code{semantic-complete-inline-analyzer-idle-displayor-class}, as
+described below). The completed part is highlighted, to indicate that
+it is not yet properly inserted into the buffer. The echo area shows
+the completion, and whether there are other possible completions, like
+this:
@example
-(defvar-mode-local jde-mode semantic-idle-summary-out-of-context-faces
- (append (default-value 'semantic-idle-summary-out-of-context-faces)
- '(jde-java-font-lock-doc-tag-face
- jde-java-font-lock-link-face
- jde-java-font-lock-bold-face
- jde-java-font-lock-underline-face
- jde-java-font-lock-pre-face
- jde-java-font-lock-code-face)))
+besselj [1 of 6 matches]
@end example
-@end defvar
+@noindent
+While the completion is being displayed, the following keybindings
+take effect:
-@node Idle Completions Mode
-@subsection Idle Completions Mode
+@table @kbd
+@item @key{RET}
+@itemx C-m
+Accept the current completion (@code{semantic-complete-inline-done}),
+placing it in the buffer and moving point to the end of the completed
+tag.
+@item M-n
+Select the next possible completion
+(@code{semantic-complete-inline-down}). The new completion is shown
+inline, replacing the old completion.
+@item M-p
+Select the previous possible completion
+(@code{semantic-complete-inline-up}).
+@item @key{TAB}
+@item C-i
+Accept as much of the completion as possible. If no additional
+completion can be accepted without ambiguity, select the next possible
+completion (@code{semantic-complete-inline-TAB}).
+@item C-g
+Quit without completing (@code{semantic-complete-inline-quit}).
+@end table
-The definition of smart completion is described in the Analyzer
-section @ref{Analyzer}.
+@noindent
+You can also exit inline completion by issuing any other Emacs
+command. The completion text then disappears from the buffer.
-The Idle Completions mode will calculate the list of possible
-completions in idle time, and display them in a popup list, or other
-inline completion mechanism.
+@deffn Command semantic-complete-analyze-inline-idle
+This is the command for performing inline code completion. It is
+called by Semantic Idle Completions mode during idle time, but you can
+also call it yourself. It returns immediately, leaving the buffer in
+a state for inline completion.
+@end deffn
+
+@deffn Option semantic-complete-inline-analyzer-idle-displayor-class
+The value of this variable determines how
+@code{semantic-complete-analyze-inline-idle} shows its completions.
+Possible values include:
+
+@table @code
+@item semantic-displayor-ghost
+Display completions ``inline'' with the buffer text, as described
+above. This is the default value.
-@deffn semantic-idle-completions-mode &optional arg
-@anchor{semantic-idle-completions-mode}
-Display a tooltip with a list of possible completions near the cursor.
-There is no convenience for performing a completion replacement. For
-that you should bind @code{semantic-ia-complete-symbol}.
-This is a minor mode which performs actions during idle time.
-With prefix argument ARG, turn on if positive, otherwise off. The
-minor mode can be turned on only if semantic feature is available and
-the current buffer was set up for parsing. Return non-nil if the
-minor mode is enabled
+@item semantic-displayor-tooltip
+Display completions in a tooltip.
+
+@item semantic-displayor-traditional
+Display completions in a separate window.
+@end table
@end deffn
-This mode operates by using the command
-@code{semantic-complete-inline-analyzer}.
+@node Analyzer
+@section Analyzer
+@cindex Analyzer
-Idle completion uses the completion function
-@code{semantic-complete-analyze-inline-idle}. Changing the behavior of
-the idle completion popups should be done through those utilities.
+The Semantic Analyzer is a library for performing context analysis on
+source code. It provides user commands for displaying, completing,
+and navigating through source code.
-@deffn Command semantic-complete-analyze-inline-idle
-@anchor{semantic-complete-analyze-inline-idle}
-Perform prompt completion to do in buffer completion.
-@dfn{semantic-analyze-possible-completions} is used to determine the
-possible values.
-The function returns immediately, leaving the buffer in a mode that
-will perform the completion.
-Configure @code{semantic-complete-inline-analyzer-idle-displayor-class}
-to change how completion options are displayed.
+@menu
+* Smart Completion:: Performing code completion.
+* Smart Summary:: Displaying help on a symbol.
+* Smart Jump:: Jumping to the definition of a tag.
+* Analyzer Debug:: Debugging problems with the analyzer.
+@end menu
+
+@node Smart Completion
+@subsection Smart Completion
+
+The Semantic Analyzer can be used to perform code completion in a
+manner that takes the local context into account. (In addition to the
+user commands in this section, Semantic Idle Completions mode also
+uses the Semantic Analyzer. @xref{Idle Completions Mode}.)
+
+@deffn Command semantic-analyze-possible-completions context
+This is the most basic command for Semantic Analyzer-based completion.
+Called interactively, it displays a list of the possible completions
+for the symbol at point.
+
+When called from a Lisp program,
+@code{semantic-analyze-possible-completions} does not display a
+completions list. The argument @var{context} should be either a
+buffer position, or a context object. The return value is a list of
+@semantic{} tag objects that complete the symbol for @var{context},
+based on the following criteria:
+
+@itemize
+@item Elements currently in scope.
+@item Constants currently in scope.
+@item Elements matching the context's @code{:prefix}.
+@item Type of the completion matching the type of the context.
+@end itemize
+
+Most of the other commands documented in this section call
+@code{semantic-analyze-possible-completions} internally.
+@end deffn
+
+@deffn Command semantic-complete-analyze-inline
+This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is
+enabled (@pxref{Semantic mode user commands}). It displays a list of
+possible completions for the symbol at point, and activates a special
+set of keybindings for choosing a completion.
+
+You can type @key{RET} to accept the current completion, @kbd{M-n} and
+@kbd{M-p} to cycle through the possible completions, @key{TAB} to
+complete as far as possible and then cycle through completions, and
+either @kbd{C-g} or any other key to abort the completion.
+
+This command is similar to the completion performed by Semantic Idle
+Completions mode. The main difference is that it is called
+explicitly, whereas Semantic Idle Completions mode completes during
+idle time (@pxref{Idle Completions Mode}).
@end deffn
@deffn Option semantic-complete-inline-analyzer-idle-displayor-class
-@anchor{semantic-complete-inline-analyzer-idle-displayor-class}
-Class for displayor to use with inline completion at idle time.
+The value of this variable determines how
+@code{semantic-complete-analyze-inline} shows its completions.
+Possible values include:
+
+@table @code
+@item semantic-displayor-traditional
+Display completions in a separate window. This is the default value.
+
+@item semantic-displayor-ghost
+Display completions ``inline'' with the buffer text, similar to the
+default behavior of Semantic Idle Completions mode (@pxref{Idle
+Completions Mode}).
+
+@item semantic-displayor-tooltip
+Display completions in a tooltip.
+@end table
+@end deffn
+
+In addition to @code{semantic-complete-analyze-inline}, you can use
+the simpler command @code{semantic-ia-complete-symbol point}. This
+behaves like the usual @kbd{M-@key{TAB}} (@code{complete-symbol})
+command (@pxref{Symbol Completion,,,emacs,Emacs manual}), except it
+uses the Semantic Analyzer.
+
+@deffn Command semantic-ia-complete-symbol point
+Complete the current symbol at @var{point}.
+@end deffn
+
+@node Smart Summary
+@subsection Smart Summary
+
+You can use the following commands to obtain information about the
+code at point:
+
+@deffn Command semantic-ia-show-summary pos
+Display a summary for the symbol at @var{pos}. Called interactively,
+@var{pos} defaults to point.
+@end deffn
+
+@deffn Command semantic-ia-show-doc pos
+Display the code-level documentation for the symbol at @var{pos}.
+Called interactively, @var{pos} defaults to point.
+@end deffn
+
+@deffn Command semantic-ia-describe-class typename
+Prompt for the name of a data type, @var{typename}, and display its
+components. For instance, if the type in question is a class, this
+displays the methods and member variables.
+@end deffn
+
+You can also use Semantic Idle Summary mode to show information about
+the current symbol in the echo area during idle time. @xref{Idle
+Summary Mode}.
+
+@node Smart Jump
+@subsection Smart Jump
+
+The Semantic Analyzer can be used to jump directly to the definition
+for a code symbol.
+
+@deffn Command semantic-ia-fast-jump pos
+Jump to the definition for the symbol at @var{pos}. Called
+interactively, @var{pos} defaults to point.
+@end deffn
+
+@defun semantic-ia-fast-mouse-jump event
+Jump to the definition for the symbol at the position of the mouse
+event @var{event}. This command is meant to be bound to a mouse
+command, like this:
+
+@example
+(global-set-key '[(S-mouse-1)] semantic-ia-fast-mouse-jump)
+@end example
+@end defun
+
+These commands are often more accurate than the @code{find-tag}
+command (@pxref{Tags,,,emacs,Emacs manual}), because the Semantic
+Analyzer is context-sensitive.
+
+You can also use @kbd{C-c , j} (@code{semantic-complete-jump-local})
+and @kbd{C-c , J} (@code{semantic-complete-jump}) to navigate tags.
+@xref{Semantic mode user commands}. Those commands do not make use of
+the Semantic Analyzer.
+
+@node Analyzer Debug
+@subsection Debugging the Semantic Analyzer
+
+If the Semantic Analyzer does not analyze your code properly, you can
+take steps to identify and solve the problem. This section was
+written with C/C++ in mind, but should be relevant for any typed
+language.
+
+@subsubsection Step 1: Check the context
+
+To check the current context, type @kbd{M-x
+semantic-analyze-current-context}.
+
+@deffn Command semantic-analyze-current-context pos
+Analyze the context at @var{pos}. This function is used by most of
+the other Semantic Analyzer commands to obtain the context of the code
+at a given buffer position. The return value is an EIEIO object
+describing the context at @var{pos} (@pxref{Top,,,eieio,EIEIO
+manual}).
+
+When called interactively, this displays a @samp{*Semantic Context
+Analysis*} buffer containing a summary of the context at point.
+@end deffn
+
+@noindent
+The Prefix section of the @samp{*Semantic Context Analysis*} buffer
+lists the tags based on the text at point. If it shows only a simple
+string, the Semantic was unable to identify what the data type was.
+
+The first item in the list of the prefix is the first lookup failure
+in the chain, and that is the item to focus debugging effort on. For
+example:
+
+@example
+Context Type: #<semantic-analyze-context context>
+Bounds: (182 . 185)
+Prefix: Foo* bar
+ int bbb (const char* y)
+Prefix Types: class Foo @{@}
+--------
+-> Local Vars: int argc
+ char** argv
+@end example
+
+In this example you can see that the prefix has two fully found tags.
+In the following example, the symbol ``bbb'' is incomplete, and could
+not be found:
+
+@example
+Context Type: #<semantic-analyze-context context>
+Bounds: (182 . 184)
+Prefix: Foo* bar
+ "bb"
+Prefix Classes: 'function
+ 'variable
+Prefix Types: class Foo @{@}
+--------
+-> Local Vars: int argc
+ char** argv
+@end example
+
+@subsubsection Step 2 : Check your include path
+
+Once you know the missing symbol, check your include path. The header
+or include file containing the needed definition may not be in the
+list of headers @semantic{} is searching through. To get a basic
+list, you can use @kbd{M-x semanticdb-find-test-translate-path}.
+@xref{Semanticdb search debugging commands}.
+
+If items should be loaded but aren't, or if you see some tables that
+have no tags in them, then you you may have an incorrectly-set search
+throttle (@pxref{Search Throttle}). For example,
+
+@example
+*#<semanticdb-table main.cpp (4 tags DIRTY)>
+*#<semanticdb-table foo.hh (0 tags DIRTY)>
+@end example
+
+Here, @semantic{} found @file{foo.hh}, but there are 0 tags. This may
+be because you had set the throttle to avoid reading and parsing files
+that Emacs has not visited. To fix this, visit the file and let
+@semantic{} parse it.
+
+For C++, check also that the @samp{#include} statements for your
+project-level files use quotes, not angle brackets; angle brackets are
+for system files.
+
+@subsubsection Step 3: Check the local scope
+
+If your data type is somehow abbreviated based on scope, such as from
+a @code{using} statement, you should make sure that the symbol you
+want is in the local scope. Examine the scope with @kbd{M-x
+semantic-calculate-scope}. The scope structure is displayed in ADEBUG
+mode, so use @kbd{SPC} to expand different elements and looking for
+your symbol.
+
+If your symbol should be in the scope, but you cannot find it, then
+you may have found a language support bug in the local-variable
+parser, or using statement parser.
+
+Calling @kbd{M-x bovinte} should force a reset on the scope in case
+there is merely some bad state.
+
+@example
+ ] Name: Cache
+ ] Class: #'semantic-scope-cache
+ ] :table #<semanticdb-table testsubclass.cpp (13 tags DIRTY)>
+ ] tag createMoose : class moose
+ ] scopetypes 'nil
+ ] parents #<TAG LIST: 1 entries>
+ ] scope #<TAG LIST: 22 entries>
+ ] fullscope #<TAG LIST: 23 entries>
+ ] localvar #<TAG LIST: 6 entries>
+@end example
+
+In the above sample output, the @code{tag} slot specifies where within
+you source this scope is relevant. @code{Parents} should contain any
+in scope parents, such as the class a method belongs to.
+@code{Localvar} should contain your local variables. @code{Scope}
+should contain datatypes in scope due to a @code{using} statement or
+the like.
+
+@subsubsection Step 4: Check the typecache
+
+For complex typed languages like C++, @semantic{} creates a typecache,
+or an optimized search table with all the various data types in it.
+Elements in the typecache do not obey local scope. It only contains
+fully qualified names. You can examine the typecache with
+@kbd{M-x semanticdb-typecache-dump}.
+
+If your data types are not in the typecache, there may be some parsing
+error or other bug. Calling @kbd{M-x bovinte} should force a reset on
+the typecache in case there is merely some bad state.
+
+@example
+]#<semanticdb-typecache /home/zappo/cedet/semantic/tests/testsubclass.cpp>
+ ] Name: /home/zappo/cedet/semantic/tests/testsubclass.cpp
+ ] Class: #'semanticdb-typecache
+ ] filestream 'nil
+ ] includestream #<TAG LIST: 84 entries>
+ ] stream 'nil
+ ] dependants 'nil
+@end example
+
+In the above example, the output of @kbd{M-x semanticdb-typecache-dump}
+was expanded one level. The @code{filestream} slot should contain
+datatypes in the current file. The @code{includestream} should
+contain all the datatypes in all included header files.
-Customize this variable to get a list of options, such as popup
-tooltips, ghosting text, or traditional completion tools.
+The @code{dependants} slot will specify other files that depend on
+this one.
+
+@subsubsection Step 5: Check the parser
+
+Go to the location where your unfound tag should be. You can call
+@kbd{M-x bovinate}, and see a dump of the raw tag structure. To see a
+navigable tree, use @kbd{M-x semantic-adebug-bovinate} instead. You
+can then look to make sure your tag has been properly parsed.
+
+If it has not, then you may have found a parser bug. To get a feel
+how @semantic{} treats your file, type @kbd{M-x
+global-semantic-show-unmatched-syntax-mode}. This causes any syntax
+it cannot parse to be underlined in red.
+
+If your type is not parsable, it could be for a couple of reasons:
+
+@enumerate
+@item
+If there is a MACRO keyword used in the definition of the type, you
+may need to update the @code{semantic-lex-c-preprocessor-symbol-map}
+to account for it.
+
+@item
+Or perhaps the parser needs to be fixed.
+@end enumerate
+
+@node Speedbar
+@section Speedbar
+@cindex speedbar
+
+You can integrate @semantic{} with the Speedbar.
+@xref{Speedbar,,,emacs,Emacs manual}. To do this, add the following
+line to your init file:
+
+@example
+(add-hook 'speedbar-load-hook (lambda () (require 'semantic/sb)))
+@end example
+
+@noindent
+Or, alternatively:
+
+@example
+(require 'semantic/sb)
+@end example
+
+Once installed, the Speedbar will use @semantic{} to find and display
+tags. Tags from @semantic{} are displayed with more details than
+ordinary Speedbar tags, such as function arguments and return type.
+
+In addition, you can use the Speedbar to show the output of the
+Semantic Analyzer (@pxref{Analyzer}). To do this, go to the
+@samp{Display} menu item on the Speedbar menu and select
+@samp{Analyze}; or type @kbd{M-x semantic-speedbar-analysis}.
+
+@deffn Command semantic-speedbar-analysis
+Start the Speedbar in Semantic Analysis mode.
+@end deffn
+
+In Semantic Analysis mode, the Speedbar displays information about the
+local context, such as the current function, local arguments and
+variables, and details on the prefix (the current symbol). Each entry
+has an @samp{<i>} button; clicking on this shows a summary of what
+@semantic{} knows about that variable or type. The Speedbar also
+displays a list of possible completions at point.
+
+@node SymRef
+@section Symbol References
+@cindex symref
+
+@semantic{} can interface with external @dfn{symbol reference tools},
+such as GNU Global and GNU Idutils. These tools provide information
+about where different tags or symbols appear.
+
+By default, @semantic{} tries to look for the best external symbol
+reference tool that can be used. The supported tools are GNU Global,
+GNU Idutils, CScope, and Grep (the fallback method). For best
+results, use GNU Global. However, @semantic{} does not manage your
+GNU Global tables for you; you must manage them yourself.
+
+@defvar semantic-symref-tool
+The value of this variable is a symbol that determines the external
+symbol reference tool to use. The default value, @code{detect}, says
+to look for the best available tool. Other possible values are
+@code{global}, @code{idutils}, @code{cscope}, and @code{grep}. Note
+that @code{grep} is much slower than the others.
+@end defvar
+
+The commands to display symbol references are @kbd{C-c , g}
+(@code{semantic-symref-symbol} and @kbd{C-c , G}
+(@code{semantic-symref}). These keybindings are available whenever
+Semantic mode is enabled (@pxref{Semantic mode user commands}).
+
+@deffn Command semantic-symref-symbol sym
+This command (normally bound to @kbd{C-c , g}) prompts for a symbol
+name, and uses an external reference tool to find references to that
+tag.
+@end deffn
+
+@deffn Command semantic-symref
+This command (normally bound to @kbd{C-c , G}) uses an external
+reference tool to find references to the current tag.
+@end deffn
+
+Both @code{semantic-symref-symbol} and @code{semantic-symref} display
+a list of symbol references in a separate buffer. The entries are
+organized by file, and by function name. Typing @key{RET} on the
+@samp{[+]} next to each function name ``expands'' that entry, listing
+all references to the target symbol occurring within that function.
+Typing @kbd{RET} on a reference line jumps to that reference.
+
+@node MRU Bookmarks
+@section MRU Bookmarks mode
+@cindex semantic-mru-bookmark-mode
+
+Semantic MRU Bookmarks mode is a minor mode that keeps track of the
+tags you have edited, allowing you to quickly return to them later
+(MRU stands for ``Most Recently Used'').
+
+@deffn Command global-semantic-mru-bookmark-mode &optional arg
+Toggle Semantic MRU Bookmarks mode globally. The minor mode can be
+turned on only if the current buffer was set up for parsing. With
+argument @var{arg}, turn the minor mode if @var{arg} is positive, and
+off otherwise.
+@end deffn
+
+Semantic MRU Bookmarks mode takes note of each tag you edit.
+Afterwards, you can type @kbd{C-x B}
+(@code{semantic-mrub-switch-tags}) to return to a tag. This command
+prompts for a tag name, completing with the names of edited tags; at
+the prompt, you can use @kbd{M-p} and @kbd{M-n} to cycle through tags
+in order of last modification time.
+
+@node Sticky Func Mode
+@section Sticky Function mode
+
+Semantic Sticky Function minor mode displays a header line that shows
+the declaration line of the function or tag on the topmost line in the
+text area. This allows you to keep that declaration line in view at
+all times, even if it is scrolls off the ``top'' of the screen.
+
+In addition, clicking @kbd{Mouse-1} on the header line opens a context
+menu that contains menu items for copying, killing, or narrowing to
+that tag.
+
+@deffn Command global-semantic-stickyfunc-mode &optional arg
+Toggle Semantic Sticky Function mode in all Semantic-enabled buffers.
+With an optional argument @var{arg}, enable if @var{arg} is positive,
+and disable otherwise.
@end deffn
+
+@defvar semantic-stickyfunc-sticky-classes
+The value of this variable is a list of tag classes that Semantic
+Sticky Function mode makes ``sticky''. The default is
+@code{'(function type)}, meaning function declarations and type
+declarations. Other possible tag classes are @code{variable},
+@code{include}, and @code{package}.
+@end defvar
+
+@node Highlight Func Mode
+@section Highlight Func Mode
+@cindex semantic-highlight-func-mode
+
+Semantic Highlight Function minor mode highlights the declaration line
+of the current function or tag (that is to say, the first line that
+describes the rest of the construct).
+
+In addition, clicking @kbd{Mouse-3} on the highlighted declaration
+line opens a context menu that contains menu items for copying,
+killing, or narrowing to that tag.
+
+The tag classes highlighted by Semantic Highlight Function mode are
+the same ones given by @code{semantic-stickyfunc-sticky-classes}.
+@xref{Sticky Func Mode}.
+
+@defun global-semantic-highlight-func-mode &optional arg
+Toggle Semantic Highlight Function mode in all Semantic-enabled
+buffers. With an optional argument @var{arg}, enable if @var{arg} is
+positive, and disable otherwise.
+@end defun
+
+@deffn Face semantic-highlight-func-current-tag-face
+This face is used to highlight declaration lines in Semantic Highlight
+Func mode.
+@end deffn
+
+@node Tag Decoration Mode
+@section Tag Decoration Mode
+@cindex semantic-decoration-mode
+
+Semantic Tag Decoration mode ``decorates'' each tag based on certain
+arbitrary features of that tag. Decorations are specified using the
+variable @code{semantic-decoration-styles}.
+
+@deffn Command global-semantic-decoration-mode &optional arg
+Toggle Semantic Tag Decoration mode in all Semantic-enabled buffers.
+With an optional argument @var{arg}, enable if @var{arg} is positive,
+and disable otherwise.
+@end deffn
+
+@defvar semantic-decoration-styles
+The value of this variable is a list of decoration styles for Semantic
+Tag Decoration mode. Each element in this list should have the form
+@code{(@var{name} . @var{flag})}, where @var{name} is a style name (a
+symbol) and @var{flag} is non-@code{nil} if the style is enabled.
+
+The following styles are available:
+
+@table @code
+@item semantic-tag-boundary
+Place an overline in front of each long tag (excluding prototypes).
+
+@item semantic-decoration-on-private-members
+Highlight class members that are designated as private.
+
+@item semantic-decoration-on-protected-members
+Highlight class members that are designated as protected.
+
+@item semantic-decoration-on-includes
+Highlight class members that are includes. Clicking on the
+highlighted include statements opens a context menu for configuring
+@semantic{} includes.
+@end table
+@end defvar
+
+To enable or disable specific decorations, use this function:
+
+@deffn Command semantic-toggle-decoration-style name &optional arg
+Prompt for a decoration style, @var{name}, and turn it on or off.
+With prefix argument @var{arg}, turn on if positive, otherwise off.
+Return non-@code{nil} if the decoration style is enabled.
+@end deffn
+
+@deffn Face semantic-tag-boundary-face
+Face for long tags in the @code{semantic-tag-boundary} decoration
+style.
+@end deffn
+
+@deffn Face semantic-decoration-on-private-members-face
+Face for privately-scoped tags in the
+@code{semantic-decoration-on-private-members} decoration style.
+@end deffn
+
+@deffn Face semantic-decoration-on-protected-members-face
+Face for protected tags in the
+@code{semantic-decoration-on-protected-members} decoration style.
+@end deffn
+
+@deffn Face semantic-decoration-on-includes
+Face for includes that are not in some other state, in the
+@code{semantic-decoration-on-includes} decoration style.
+@end deffn
+
+@deffn Face semantic-decoration-on-unknown-includes
+Face for includes that cannot be found, in the
+@code{semantic-decoration-on-includes} decoration style.
+@end deffn
+
+@deffn Face semantic-decoration-on-unparsed-includes
+Face for includes that have not yet been parsed, in the
+@code{semantic-decoration-on-includes} decoration style.
+@end deffn
+
+@subsection Creating New Decoration Modes
+
+You can create new types of decorations using the following function:
+
+@defun define-semantic-decoration-style name doc &rest flags
+Define a new decoration style with @var{name}.
+@var{doc} is a documentation string describing the decoration style @var{name}.
+It is appended to auto-generated doc strings.
+An Optional list of @var{flags} can also be specified. Flags are:
+ @code{:enabled} <value> - specify the default enabled value for @var{name}.
+
+
+This defines two new overload functions respectively called @code{NAME-p}
+and @code{NAME-highlight}, for which you must provide a default
+implementation in respectively the functions @code{NAME-p-default} and
+@code{NAME-highlight-default}. Those functions are passed a tag. @code{NAME-p}
+must return non-@code{nil} to indicate that the tag should be decorated by
+@code{NAME-highlight}.
+
+To put primary decorations on a tag @code{NAME-highlight}, use
+functions like @dfn{semantic-set-tag-face},
+@dfn{semantic-set-tag-intangible}, etc., found in the
+semantic-decorate library.
+
+To add other kind of decorations on a tag, @code{NAME-highlight} must use
+@dfn{semantic-decorate-tag}, and other functions of the semantic
+decoration @var{api} found in this library.
+@end defun
HCoop / bpt / emacs.git / blobdiff