changeset 106061:014672c3a25f

* Makefile.in: Build the Semantic manual. * semantic.texi, sem-user.texi: New files, adapted from the Semantic repository.

--- a/doc/misc/ChangeLog	Mon Nov 16 20:36:06 2009 +0000
+++ b/doc/misc/ChangeLog	Mon Nov 16 22:25:49 2009 +0000
@@ -1,3 +1,10 @@
[phone]  Chong Yidong  <[e-mail]>
+
+	* Makefile.in: Build the Semantic manual.
+
+	* semantic.texi, sem-user.texi: New files, adapted from the Semantic
+	repository.
+
 2009-11-16  Michael Albinus  <[e-mail]>
 
 	* dbus.texi (Receiving Method Calls): New defun

--- a/doc/misc/Makefile.in	Mon Nov 16 20:36:06 2009 +0000
+++ b/doc/misc/Makefile.in	Mon Nov 16 22:25:49 2009 +0000
@@ -74,6 +74,7 @@
 	$(infodir)/reftex \
 	$(infodir)/sasl \
 	$(infodir)/sc \
+	$(infodir)/semantic \
 	$(infodir)/ses \
 	$(infodir)/sieve \
 	$(infodir)/smtpmail \
@@ -122,6 +123,7 @@
 	remember.dvi \
 	sasl.dvi \
 	sc.dvi \
+	semantic.dvi \
 	ses.dvi \
 	sieve.dvi \
 	smtpmail.dvi \
@@ -383,6 +385,12 @@
 sc.dvi: sc.texi
 	$(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi
 
+semantic : $(infodir)/semantic
+$(infodir)/semantic: semantic.texi sem-user.texi
+	cd $(srcdir); $(MAKEINFO) semantic.texi
+semantic.dvi: semantic.texi
+	$(ENVADD) $(TEXI2DVI) ${srcdir}/semantic.texi
+
 ses : $(infodir)/ses
 $(infodir)/ses: ses.texi
 	cd $(srcdir); $(MAKEINFO) ses.texi

--- a/doc/misc/ede.texi	Mon Nov 16 20:36:06 2009 +0000
+++ b/doc/misc/ede.texi	Mon Nov 16 22:25:49 2009 +0000
@@ -132,9 +132,9 @@
 @node EDE Mode, Creating a project, EDE Project Concepts, top
 @chapter @ede{} Mode
 
-@ede{} is implemented as a minor-mode, which augments other modes such as C
-mode, and Texinfo mode.  You can turn @ede{} on for all buffers by running
-the command @code{global-ede-mode}, or by putting this in your
+@ede{} is implemented as a minor-mode, which augments other modes such
+as C mode, and Texinfo mode.  You can enable @ede{} for all buffers by
+running the command @code{global-ede-mode}, or by putting this in your
 @file{~/.emacs} file:
 
 @example

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/misc/sem-user.texi	Mon Nov 16 22:25:49 2009 +0000
@@ -0,0 +1,787 @@
+@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''.
+
+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.
+
+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}.
+
+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.
+@end menu
+
+@node Semantic mode
+@section Semantic mode
+@cindex 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).
+
+In each parser-enabled buffer, a number of @semantic{} commands are
+available for navigating, querying, and editing source code.
+@xref{Semantic mode user commands}.  Enabling Semantic mode also
+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.
+
+@defvar semantic-new-buffer-setup-functions
+The value of this variable is an alist of functions to call for
+setting up @semantic{} parsing in the buffer.  Each element has the
+form @code{(@var{mode} . @var{fn})}, where @var{mode} is a value of
+@code{major-mode} for the buffer and @var{fn} is the corresponding
+function for setting up the parser.  @var{fn} is called, with no
+arguments, after the major mode is initialized (and after the mode
+hooks have been run).
+
+The default value enables @semantic{} for all supported major modes
+(i.e., C, C++, Scheme, Javascript, Java, HTML, SRecode, and Make), but
+you can remove modes from this list if you don't want to use
+@semantic{} with them.
+@end defvar
+
+@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
+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}
+@end itemize
+@end defvar
+
+@menu
+* Semantic mode user commands::
+@end menu
+
+@node Semantic mode user commands
+@subsection Semantic mode user commands
+
+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
+the C programming language).
+
+These commands may be used in any buffer that has been parsed by
+@semantic{}.  Several of them prompt for a tag name using the
+minibuffer; here, the @kbd{TAB} key can be used to complete tag names.
+Others act on the @dfn{current tag}, meaning the tag at (or around)
+point.
+
+@table @kbd
+@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
+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
+Display a list of the possible completions of the current tag
+(@code{semantic-analyze-possible-completions}).
+
+@item \C-c , g
+Prompt for a tag, and display a list of tags that call it
+(@code{semantic-symref-symbol}).
+
+@item \C-c , G
+Display a list of tags that call the current tag
+(@code{semantic-symref}).
+
+@item \C-c , p
+Move point to the previous tag (@code{senator-previous-tag}).
+
+@item \C-c , n
+Move point to the next tag (@code{senator-next-tag}).
+
+@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,\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
+Copy the current tag into the kill ring as well as the tag ring
+(@code{senator-copy-tag}).
+
+@item \C-c,\C-y
+Yank a tag from the tag ring (@code{senator-yank-tag}).
+
+@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}
+Transpose the current tag with the previous one
+(@code{senator-transpose-tags-up}).
+
+@item ?\C-c ?, @kbd{down}
+Transpose the current tag with the next one
+(@code{senator-transpose-tags-down}).
+@end table
+
+@node SemanticDB
+@section Semantic Database
+@cindex SemanticDB
+
+The Semantic Database (SemanticDB) caches the results of parsing
+source code files.  This data can be saved to disk when you exit
+Emacs, and reloaded automatically when you subsequently revisit the
+same source code files.  This saves time by eliminating the need to
+re-parse unmodified files.
+
+SemanticDB also provides an @acronym{API} that programs can use to
+acquire information about source code tags.  This information can be
+accessed without loading the original the source files into memory.
+It can also be used to create alternate ``back-ends'' for storing tag
+information in alternative on-disk formats.
+
+By default, SemanticDB is enabled together with Semantic mode.  To
+disable it, remove it from @code{semantic-default-submodes}
+(@pxref{Semantic mode}).  You can also enable or disable SemanticDB
+with @kbd{M-x global-semanticdb-minor-mode}.
+
+@deffn Command global-semanticdb-minor-mode
+Toggle SemanticDB mode.  When enabled, any source code parsed by
+@semantic{} is cached in a database.
+@end deffn
+
+SemanticDB offers a large number of customizable options, which are
+described in the following subsections.
+
+@menu
+* Semanticdb Tag Storage::
+* Semanticdb Search Configuration::
+* Changing Backends::
+* Script Generated Cache Files::
+* Create System Databases::
+@end menu
+
+@node Semanticdb Tag Storage
+@subsection Semanticdb Tag Storage
+
+Each time you exit Emacs, any data cached by SemanticDB is saved in
+the directory @file{.emacs.d/semanticdb/}, located in your home
+directory.  Within this directory, the cache data is written into a
+set of files according to a SemanticDB-specific filename convention.
+If the SemanticDB directory does not exist, Emacs first asks if you
+want to create it.
+
+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,
+in the current directory, whose filename is given by
+@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}.
+@end deffn
+
+You can force SemanticDB to save the data from only certain files, or
+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
+directory is saved.
+
+As a special exception, the value of this variable can be a list
+containing a single symbol: @code{never}, @code{always}, or
+@code{project}.  The symbol @code{never} disables saving anywhere;
+@code{always} enables saving everywhere; and @code{project} enables
+saving directory based on the variable
+@code{semanticdb-project-predicate-functions}.
+
+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
+@code{semanticdb-persistent-path} is @code{(project)}.  If the list is
+empty, all paths are considered valid.
+
+Project management packages, such as EDE (@pxref{Top,,,ede,EDE
+manual}), may add their own predicates with @dfn{add-hook} to this
+variable.  This allows SemanticDB to save tag caches in directories
+controlled by them.
+@end defvar
+
+@anchor{semanticdb-save-database-hooks}
+@deffn Option semanticdb-save-database-hooks
+Abnormal hook run after a database is saved.  Each function is called
+with one argument, the object representing the database recently
+written.
+@end deffn
+
+@node Semanticdb Search Configuration
+@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
+
+@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
+* 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.
+
+@defvar semanticdb-find-default-throttle
+@anchor{semanticdb-find-default-throttle}
+The default throttle for @code{semanticdb-find} routines.
+The throttle controls how detailed the list of database
+tables is for a symbol lookup.  The value is a list with
+the following keys:
+
+@table @code
+@item file
+The file the search is being performed from.  This option is here for
+completeness only, and is assumed to always be on.
+@item local
+Tables from the same local directory are included.  This includes
+files directly referenced by a file name which might be in a different
+directory.
+@item project
+Tables from the same local project are included If @code{project} is
+specified, then @code{local} is assumed.
+@item unloaded
+If a table is not in memory, load it.  If it is not cached on disk
+either, get the source, parse it, and create the table.
+@item system
+Tables from system databases.  These are specifically tables
+from system header files, or language equivalent.
+@item recursive
+For include based searches, includes tables referenced by included
+files.
+@item omniscience
+Included system databases which are omniscience, or somehow know
+everything.  Omniscience databases are found in
+@code{semanticdb-project-system-databases}.  The Emacs Lisp system
+@var{db} is an omniscience database.
+@end table
+
+@end defvar
+
+To set the throttle, use a command like this:
+
+@example
+(setq-mode-local c-mode
+		 semanticdb-find-default-throttle
+		 '(project unloaded system recursive))
+@end example
+
+The default value of the throttle is for maximum accuracy at the
+expense of time taken to perform a particular look-up.  The throttle
+is tweaked by @code{semantic-idle-summary-mode} to remove 'unloaded,
+thus removing poor speed at unexpected times.
+
+@node Semanticdb search debugging commands
+@subsubsection Semanticdb search debugging commands
+
+You can use @kbd{M-x semanticdb-dump-all-table-summary RET} to see the
+list of databases that will be searched from a given buffer.  It
+should include DBs for the directories you expect.  You can follow up
+with @kbd{M-x semanticdb-find-test-translate-path RET} to then make
+sure specific tables from the path are discovered correctly.
+
+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}.
+
+@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.
+@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
+
+@node Changing Backends
+@subsection Changing Backends
+
+If you want to use some other form of backend, you can use this
+variable to choose which back end class to use for your general tag
+storage.
+
+The default is to save databases in flat files.  Alternatively, you
+could write a new database backend that stores tags into a database,
+or other storage system.
+
+@defvar semanticdb-new-database-class
+@anchor{semanticdb-new-database-class}
+The default type of database created for new files.
+This can be changed on a per file basis, so that some directories
+are saved using one mechanism, and some directories via a different
+mechanism.
+@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
+
+If your supported language stores the system libraries in readily
+available parsable source code, you can pre-generate database files
+for them once, which will be used over and over for tools such as
+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.
+
+@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}
+@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}.
+@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.
+@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.
+@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.
+
+@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
+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.
+@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.
+@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.
+@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.
+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
+
+These features can be controlled with the following variables:
+
+@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.
+@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.
+@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.
+
+@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.
+
+
+@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
+@end deffn
+
+@obsolete{semantic-summary-mode, semantic-idle-summary-mode}
+
+@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}.
+@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.
+
+It might be useful to override this variable to add comment faces
+specific to a major mode.  For example, in jde mode:
+
+@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)))
+@end example
+
+@end defvar
+
+@node Idle Completions Mode
+@subsection Idle Completions Mode
+
+The definition of smart completion is described in the Analyzer
+section @ref{Analyzer}.
+
+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 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
+@end deffn
+
+This mode operates by using the command
+@code{semantic-complete-inline-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.
+
+@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.
+@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.
+
+Customize this variable to get a list of options, such as popup
+tooltips, ghosting text, or traditional completion tools.
+@end deffn

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/misc/semantic.texi	Mon Nov 16 22:25:49 2009 +0000
@@ -0,0 +1,638 @@
+\input texinfo
+@setfilename ../../info/semantic
+@set TITLE  Semantic Manual
+@set AUTHOR Eric M. Ludlam and David Ponce
+@settitle @value{TITLE}
+
+@c *************************************************************************
+@c @ Header
+@c *************************************************************************
+
+@c Merge all indexes into a single index for now.
+@c We can always separate them later into two or more as needed.
+@syncodeindex vr cp
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
+@c @footnotestyle separate
+@c @paragraphindent 2
+@c @@smallbook
+@c %**end of header
+
+@copying
+This manual documents the Semantic library and utilities.
+
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007,
+2009 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation License.''
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
+@end quotation
+@end copying
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Semantic: (semantic).      Source code parser library and utilities.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@titlepage
+@center @titlefont{Semantic}
+@sp 4
+@center by @value{AUTHOR}
+@end titlepage
+@page
+
+@macro semantic{}
+@i{Semantic}
+@end macro
+
+@macro keyword{kw}
+@anchor{\kw\}
+@b{\kw\}
+@end macro
+
+@macro obsolete{old,new}
+@sp 1
+@strong{Compatibility}:
+@code{\new\} introduced in @semantic{} version 2.0 supercedes
+@code{\old\} which is now obsolete.
+@end macro
+
+@c *************************************************************************
+@c @ Document
+@c *************************************************************************
+@contents
+
+@node top
+@top @value{TITLE}
+
+@semantic{} is a suite of Emacs libraries and utilities for parsing
+source code.  At its core is a lexical analyzer and two parser
+generators (@code{bovinator} and @code{wisent}) written in Emacs Lisp.
+@semantic{} provides a variety of tools for making use of the parser
+output, including user commands for code navigation and completion, as
+well as enhancements for imenu, speedbar, whichfunc, eldoc,
+hippie-expand, and several other parts of Emacs.
+
+To send bug reports, or participate in discussions about semantic,
+use the mailing list cedet-semantic@@sourceforge.net via the URL:
+@url{http://lists.sourceforge.net/lists/listinfo/cedet-semantic}
+
+@ifnottex
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction::
+* Using Semantic::
+* Semantic Internals::
+* Glossary::
+* GNU Free Documentation License::
+* Index::
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+This chapter gives an overview of @semantic{} and its goals.
+
+Ordinarily, Emacs uses regular expressions (and syntax tables) to
+analyze source code for purposes such as syntax highlighting.  This
+approach, though simple and efficient, has its limitations: roughly
+speaking, it only ``guesses'' the meaning of each piece of source code
+in the context of the programming language, instead of rigorously
+``understanding'' it.
+
+@semantic{} provides a new infrastructure to analyze source code using
+@dfn{parsers} instead of regular expressions.  It contains two
+built-in parser generators (an @acronym{LL} generator named
+@code{Bovine} and an @acronym{LALR} generator named @code{Wisent},
+both written in Emacs Lisp), and parsers for several common
+programming languages.  It can also make use of @dfn{external
+parsers}---programs such as GNU Global and GNU IDUtils.
+
+@semantic{} provides a uniform, language-independent @acronym{API} for
+accessing the parser output.  This output can be used by other Emacs
+Lisp programs to implement ``syntax-aware'' behavior.  @semantic{}
+itself includes several such utilities, including user-level Emacs
+commands for navigating, searching, and completing source code.
+
+The following diagram illustrates the structure of the @semantic{}
+package:
+
+@table @strong
+@item Please Note:
+The words in all-capital are those that @semantic{} itself provides.
+Others are current or future languages or applications that are not
+distributed along with @semantic{}.
+@end table
+
+@example
+                                                             Applications
+                                                                 and
+                                                              Utilities
+                                                                -------
+                                                               /       \
+               +---------------+    +--------+    +--------+
+         C --->| C      PARSER |--->|        |    |        |
+               +---------------+    |        |    |        |
+               +---------------+    | COMMON |    | COMMON |<--- SPEEDBAR
+      Java --->| JAVA   PARSER |--->| PARSE  |    |        |
+               +---------------+    | TREE   |    | PARSE  |<--- SEMANTICDB
+               +---------------+    | FORMAT |    | API    |<--- ecb
+    Scheme --->| SCHEME PARSER |--->|        |    |        |
+               +---------------+    |        |    |        |
+               +---------------+    |        |    |        |
+   Texinfo --->| TEXI.  PARSER |--->|        |    |        |
+               +---------------+    |        |    |        |
+
+                    ...                ...           ...         ...
+
+               +---------------+    |        |    |        |<--- app. 1
+   Lang. A --->| A      Parser |--->|        |    |        |
+               +---------------+    |        |    |        |<--- app. 2
+               +---------------+    |        |    |        |
+   Lang. B --->| B      Parser |--->|        |    |        |<--- app. 3
+               +---------------+    |        |    |        |
+
+                     ...        ...     ...          ...       ...
+
+               +---------------+    |        |    |        |
+   Lang. Y --->| Y      Parser |--->|        |    |        |<--- app. ?
+               +---------------+    |        |    |        |
+               +---------------+    |        |    |        |<--- app. ?
+   Lang. Z --->| Z      Parser |--->|        |    |        |
+               +---------------+    +--------+    +--------+
+@end example
+
+@menu
+* Semantic Components::
+@end menu
+
+@node Semantic Components
+@section Semantic Components
+
+In this section, we provide a more detailed description of the major
+components of @semantic{}, and how they interact with one another.
+
+The first step in parsing a source code file is to break it up into
+its fundamental components.  This step is called lexical analysis:
+
+@example
+        syntax table, keywords list, and options
+                         |
+                         |
+                         v
+    input file  ---->  Lexer   ----> token stream
+@end example
+
+@noindent
+The output of the lexical analyzer is a list of tokens that make up
+the file.  The next step is the actual parsing, shown below:
+
+@example
+                    parser tables
+                         |
+                         v
+    token stream --->  Parser  ----> parse tree
+@end example
+
+@noindent
+The end result, the parse tree, is @semantic{}'s internal
+representation of the language grammar.  @semantic{} provides an
+@acronym{API} for Emacs Lisp programs to access the parse tree.
+
+Parsing large files can take several seconds or more.  By default,
+@semantic{} automatically caches parse trees by saving them in your
+@file{.emacs.d} directory.  When you revisit a previously-parsed file,
+the parse tree is automatically reloaded from this cache, to save
+time.  @xref{SemanticDB}.
+
+@node Using Semantic
+@chapter Using Semantic
+
+@include sem-user.texi
+
+@node Semantic Internals
+@chapter Semantic Internals
+
+This chapter provides an overview of the internals of @semantic{}.
+This information would not be needed by neither application developers
+nor grammar developers.
+
+It would be useful mostly for the hackers who would like to learn
+more about how @semantic{} works.
+
+@menu
+* Parser code ::	  Code used for the parsers
+* Tag handling ::	  Code used for manipulating tags
+* Semanticdb internals :: Code used in the semantic database
+* Analyzer ::             Code used in the code analyzer
+* Tools ::                Code used in user tools.
+* Tests ::                Code used for testing.
+@end menu
+
+@node Parser code
+@section Parser code
+
+@semantic{} parsing code is spread across a range of files.
+
+@table @file
+@item semantic.el
+The core infrastructure sets up buffers for parsing, and has all the
+core parsing routines.  Most parsing routines are overloadable, so the
+actual implementation may be somewhere else.
+
+@item semantic-edit.el
+Incremental reparse based on user edits.
+
+@item semantic-grammar.el
+@itemx semantic-grammar.wy
+Parser for the different grammar languages, and a major mode for
+editing grammars in Emacs.
+
+@item semantic-lex.el
+Infrastructure for implementing lexical analyzers.  Provides macros
+for creating individual analyzers for specific features, and a way to
+combine them together.
+
+@item semantic-lex-spp.el
+Infrastructure for a lexical symbolic preprocessor.  This was written
+to implement the C preprocessor, but could be used for other lexical
+preprocessors.
+
+@item bovine/bovine-grammar.el
+@itemx bovine/bovine-grammar-macros.el
+@itemx bovine/semantic-bovine.el
+The ``bovine'' grammar.  This is the first grammar mode written for
+@semantic{} and is useful for simple creating simple parsers.
+
+@item wisent/wisent.el
+@itemx wisent/bison-wisent.el
+@itemx wisent/semantic-wisent.el
+@itemx wisent/semantic-debug-grammar.el
+A port of bison to Emacs.  This infrastructure lets you create LALR
+based parsers for @semantic{}.
+
+@item semantic-ast.el
+Manage Abstract Syntax Trees for parsers.
+
+@item semantic-debug.el
+Infrastructure for debugging grammars.
+
+@item semantic-util.el
+Various utilities for manipulating tags, such as describing the tag
+under point, adding labels, and the all important
+@code{semantic-something-to-tag-table}.
+
+@end table
+
+@node Tag handling
+@section Tag handling
+
+A tag represents an individual item found in a buffer, such as a
+function or variable.  Tag handling is handled in several source
+files.
+
+@table @file
+@item semantic-tag.el
+Basic tag creation, queries, cloning, binding, and unbinding.
+
+@item semantic-tag-write.el
+Write a tag or tag list to a stream.  These routines are used by
+@file{semanticdb-file.el} when saving a list of tags.
+
+@item semantic-tag-file.el
+Files associated with tags.  Goto-tag, file for include, and file for
+a prototype.
+
+@item semantic-tag-ls.el
+Language dependant features of a tag, such as parent calculation, slot
+protection, and other states like abstract, virtual, static, and leaf.
+
+@item semantic-dep.el
+Include file handling.  Contains the include path concepts, and
+routines for looking up file names in the include path.
+
+@item semantic-format.el
+Convert a tag into a nicely formatted and colored string.  Use
+@code{semantic-test-all-format-tag-functions} to test different output
+options.
+
+@item semantic-find.el
+Find tags matching different conditions in a tag table.
+These routines are used by @file{semanticdb-find.el} once the database
+has been converted into a simpler tag table.
+
+@item semantic-sort.el
+Sorting lists of tags in different ways.  Includes sorting a plain
+list of tags forward or backward.  Includes binning tags based on
+attributes (bucketize), and tag adoption for multiple references to
+the same thing.
+
+@item semantic-doc.el
+Capture documentation comments from near a tag.
+
+@end table
+
+@node Semanticdb internals
+@section Semanticdb internals
+
+@acronym{Semanticdb} complexity is certainly an issue.  It is a rather
+hairy problem to try and solve.
+
+@table @file
+@item semanticdb.el
+Defines a @dfn{database} and a @dfn{table} base class.  You can
+instantiate these classes, and use them, but they are not persistent.
+
+This file also provides support for @code{semanticdb-minor-mode},
+which automatically associates files with tables in databases so that
+tags are @emph{saved} while a buffer is not in memory.
+
+The database and tables both also provide applicate cache information,
+and cache flushing system.  The semanticdb search routines use caches
+to save datastructures that are complex to calculate.
+
+Lastly, it provides the concept of @dfn{project root}.  It is a system
+by which a file can be associated with the root of a project, so if
+you have a tree of directories and source files, it can find the root,
+and allow a tag-search to span all available databases in that
+directory hierarchy.
+
+@item semanticdb-file.el
+Provides a subclass of the basic table so that it can be saved to
+disk.  Implements all the code needed to unbind/rebind tags to a
+buffer and writing them to a file.
+
+@item semanticdb-el.el
+Implements a special kind of @dfn{system} database that uses Emacs
+internals to perform queries.
+
+@item semanticdb-ebrowse.el
+Implements a system database that uses Ebrowse to parse files into a
+table that can be queried for tag names.  Successful tag hits during a
+find causes @semantic{} to pick up and parse the reference files to
+get the full details.
+
+@item semanticdb-find.el
+Infrastructure for searching groups @semantic{} databases, and dealing
+with the search results format.
+
+@item semanticdb-ref.el
+Tracks crossreferences.   Cross references are needed when buffer is
+reparsed, and must alert other tables that any dependant caches may
+need to be flushed.  References are in the form of include files.
+
+@end table
+
+@node Analyzer
+@section Analyzer
+
+The @semantic{} analyzer is a complex engine which has been broken
+down across several modules.  When the @semantic{} analyzer fails,
+start with @code{semantic-analyze-debug-assist}, then dive into some
+of these files.
+
+@table @file
+@item semantic-analyze.el
+The core analyzer for defining the @dfn{current context}.  The
+current context is an object that contains references to aspects of
+the local context including the current prefix, and a tag list
+defining what the prefix means.
+
+@item semantic-analyze-complete.el
+Provides @code{semantic-analyze-possible-completions}.
+
+@item semantic-analyze-debug.el
+The analyzer debugger.  Useful when attempting to get everything
+configured.
+
+@item semantic-analyze-fcn.el
+Various support functions needed by the analyzer.
+
+@item semantic-ctxt.el
+Local context parser.  Contains overloadable functions used to move
+around through different scopes, get local variables, and collect the
+current prefix used when doing completion.
+
+@item semantic-scope.el
+Calculate @dfn{scope} for a location in a buffer.  The scope includes
+local variables, and tag lists in scope for various reasons, such as
+C++ using statements.
+
+@item semanticdb-typecache.el
+The typecache is part of @code{semanticdb}, but is used primarilly by
+the analyzer to look up datatypes and complex names.  The typecache is
+bound across source files and builds a master lookup table for data
+type names.
+
+@item semantic-ia.el
+Interactive Analyzer functions.  Simple routines that do completion or
+lookups based on the results from the Analyzer.  These routines are
+meant as examples for application writers, but are quite useful as
+they are.
+
+@item semantic-ia-sb.el
+Speedbar support for the analyzer, displaying context info, and
+completion lists.
+
+@end table
+
+@node Tools
+@section Tools
+
+These files contain various tools a user can use.
+
+@table @file
+@item semantic-idle.el
+Idle scheduler for @semantic{}.  Manages reparsing buffers after
+edits, and large work tasks in idle time.  Includes modes for showing
+summary help and pop-up completion.
+
+@item senator.el
+The @semantic{} navigator.  Provides many ways to move through a
+buffer based on the active tag table.
+
+@item semantic-decorate.el
+A minor mode for decorating tags based on details from the parser.
+Includes overlines for functions, or coloring class fields based on
+protection.
+
+@item semantic-decorate-include.el
+A decoration mode for include files, which assists users in setting up
+parsing for their includes.
+
+@item semantic-complete.el
+Advanced completion prompts for reading tag names in the minibuffer, or
+inline in a buffer.
+
+@item semantic-imenu.el
+Imenu support for using @semantic{} tags in imenu.
+
+@item semantic-mru-bookmark.el
+Automatic bookmarking based on tags.  Jump to locations you've been
+before based on tag name.
+
+@item semantic-sb.el
+Support for @semantic{} tag usage in Speedbar.
+
+@item semantic-util-modes.el
+A bunch of small minor-modes that exposes aspects of the semantic
+parser state.  Includes @code{semantic-stickyfunc-mode}.
+
+@item document.el
+@itemx document-vars.el
+Create an update comments for tags.
+
+@item semantic-adebug.el
+Extensions of @file{data-debug.el} for @semantic{}.
+
+@item semantic-chart.el
+Draw some charts from stats generated from parsing.
+
+
+@item semantic-elp.el
+Profiler for helping to optimize the @semantic{} analyzer.
+
+
+@end table
+
+@node Tests
+@section Tests
+
+@table @file
+
+@item semantic-utest.el
+Basic testing of parsing and incremental parsing for most supported
+languages.
+
+@item semantic-ia-utest.el
+Test the semantic analyzer's ability to provide smart completions.
+
+@item semantic-utest-c.el
+Tests for the C parser's lexical pre-processor.
+
+@item semantic-regtest.el
+Regression tests from the older Semantic 1.x API.
+
+@end table
+
+@node Glossary
+@appendix Glossary
+
+@table @keyword
+@item BNF
+In semantic 1.4, a BNF file represented ``Bovine Normal Form'', the
+grammar file used for the 1.4 parser generator.  This was a play on
+Backus-Naur Form which proved too confusing.
+
+@item bovinate
+A verb representing what happens when a bovine parser parses a file.
+
+@item bovine lambda
+In a bovine, or LL parser, the bovine lambda is a function to execute
+when a specific set of match rules has succeeded in matching text from
+the buffer.
+
+@item bovine parser
+A parser using the bovine parser generator.  It is an LL parser
+suitible for small simple languages.
+
+@item context
+
+@item LALR
+
+@item lexer
+A program which converts text into a stream of tokens by analyzing
+them lexically.  Lexers will commonly create strings, symbols,
+keywords and punctuation, and strip whitespaces and comments.
+
+@item LL
+
+@item nonterminal
+A nonterminal symbol or simply a nonterminal stands for a class of
+syntactically equivalent groupings. A nonterminal symbol name is used
+in writing grammar rules.
+
+@item overloadable
+Some functions are defined via @code{define-overload}.
+These can be overloaded via ....
+
+@item parser
+A program that converts @b{tokens} to @b{tags}.
+
+@item tag
+A tag is a representation of some entity in a language file, such as a
+function, variable, or include statement.  In semantic, the word tag is
+used the same way it is used for the etags or ctags tools.
+
+A tag is usually bound to a buffer region via overlay, or it just
+specifies character locations in a file.
+
+@item token
+A single atomic item returned from a lexer.  It represents some set
+of characters found in a buffer.
+
+@item token stream
+The output of the lexer as well as the input to the parser.
+
+@item wisent parser
+A parser using the wisent parser generator.  It is a port of bison to
+Emacs Lisp.  It is an LALR parser suitable for complex languages.
+@end table
+
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@iftex
+@contents
+@summarycontents
+@end iftex
+
+@bye
+
+@c Following comments are for the benefit of ispell.
+
+@c LocalWords: alist API APIs arg argc args argv asis assoc autoload Wisent
+@c LocalWords: backquote bnf bovinate bovinates LALR
+@c LocalWords: bovinating bovination bovinator bucketize
+@c LocalWords: cb cdr charquote checkcache cindex CLOS
+@c LocalWords: concat concocting const constantness ctxt Decl defcustom
+@c LocalWords: deffn deffnx defun defvar destructor's dfn diff dir
+@c LocalWords: doc docstring EDE EIEIO elisp emacsman emph enum
+@c LocalWords: eq Exp EXPANDFULL expresssion fn foo func funcall
+@c LocalWords: ia ids iff ifinfo imenu imenus init int isearch itemx java kbd
+@c LocalWords: keymap keywordtable lang languagemode lexer lexing Ludlam
+@c LocalWords: menubar metaparent metaparents min minibuffer Misc mode's
+@c LocalWords: multitable NAvigaTOR noindent nomedian nonterm noselect
+@c LocalWords: nosnarf obarray OLE OO outputfile paren parsetable POINT's
+@c LocalWords: popup positionalonly positiononly positionormarker pre
+@c LocalWords: printf printindex Programmatically pt punctuations quotemode
+@c LocalWords: ref regex regexp Regexps reparse resetfile samp sb
+@c LocalWords: scopestart SEmantic semanticdb setfilename setq
+@c LocalWords: settitle setupfunction sexp sp SPC speedbar speedbar's
+@c LocalWords: streamorbuffer struct subalist submenu submenus
+@c LocalWords: subsubsection sw sym texi texinfo titlefont titlepage
+@c LocalWords: tok TOKEN's toplevel typemodifiers uml unset untar
+@c LocalWords: uref usedb var vskip xref yak