This is semantic-appdev.info, produced by makeinfo version 4.3 from
app-dev-guide.texi.

This manual documents Application Development with Semantic.

   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005 Eric M. Ludlam
Copyright (C) 2001, 2002, 2003, 2004 David Ponce Copyright (C) 2002,
2003 Richard Y. Kim

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with the Invariant Sections being list their titles,
     with the Front-Cover Texts being list, and with the Back-Cover
     Texts being list.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".
   
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Semantic Application Writer's guide: (semantic-appdev).
END-INFO-DIR-ENTRY

   This file documents Application Development with Semantic.
_Infrastructure for parser based text analysis in Emacs_

   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Eric M. Ludlam,
David Ponce, and Richard Y. Kim


File: semantic-appdev.info,  Node: DB Generic Brute Search,  Prev: DB Advanced Search,  Up: Semanticdb Tag Queries

DB Generic Brute Search
-----------------------

The generic search, "semanticdb-find-nonterminal-by-function"  will
call your function with every tag available.  (Very slow for  system
databases.)

NOTE:  There is no such function.  Hopefully we can get away without
implementing one, which will make system databases more useful.  If you
are really stuck, you can use the following, though I don't recommend
it.

 - Function: semanticdb-find-tags-collector function &optional path
          find-file-match brutish
     Search for all tags returned by FUNCTION over PATH.  See
     "semanticdb-find-translate-path" for details on PATH.
     FIND-FILE-MATCH indicates that any time a match is found, the file
     associated with that tag should be loaded into a buffer.  If
     optional argument BRUTISH is non-`nil', then ignore include
     statements, and search all tables in this project tree.


File: semantic-appdev.info,  Node: System Databases,  Prev: Semanticdb Tag Queries,  Up: Semantic Database

System Databases
================

System Databases are special implementations of the database and table
API which make some external tag source appear as though it were a
normal buffer with semantic parsed tags available.

Search routines for these databases return a special type of table not
associated with a file.  It is important to be aware of this possible
return value.

At this time, there is only one type:

 - Type: semanticdb-project-database-emacs-lisp
     Database representing Emacs core.

Semantic Prased System Databases
--------------------------------

Another kind of system database is one created by the semantic tools,
but saved in a special way.  These databases are created with a script,
or at some other convenient time.  They can then be searched normally.
They will appear on the same list of system databases as back ends that
refer to object files indirectly.


File: semantic-appdev.info,  Node: Idle Scheduling,  Next: Example Programs,  Prev: Semantic Database,  Up: Top

Idle Scheduling
***************

The Semantic Idle Scheduler is a minor mode which performs semantic
specific tasks in idle time.  See *note (semantic-user.info)Idle
Scheduler::.

It performs the following tasks in order:

  1. Reprarse the current buffer if needed

  2. Reparse other buffers that need it

  3. Execute other scheduled semantic related operations.

Care is take in the idle scheduler to exit immediatly if user input is
detected, improving editing performance.

The reason for grouping these tasks together is so that the automatic
reparsing code executes before other idle services.  This allows
lexically broken buffers to be detected so that the other applications
that follow do not accidentally reparse the buffer leaving unmatched
syntax all over.

You can create new minor modes that are automatically scheduled by the
semantic idle scheduler.  Create the new minor mode with:

 - Function: define-semantic-idle-service name doc &rest forms
     Create a new idle services with NAME.  DOC will be a documentation
     string describing FORMS.  FORMS will be called during idle time
     after the current buffer's semantic tag information has been
     updated.  This routines creates the following functions and
     variables:

User Input Handling
===================

When writing an idle service, it is important for tasks that can take a
long time to correctly exit upon user input.

You can test for user input in your idle handler with the following
routines:

 - Function: semantic-throw-on-input from
     Exit with "throw" when in "semantic-exit-on-input" on user input.
     FROM is an indication of where this function is called from as a
     value to pass to "throw".  It is recommended to use the name of
     the function calling this one.

If you need to carefully extract from your function, you can wrap just
a section of your function to exit on user input by wrapping it with
this macro:

 - Function: semantic-exit-on-input symbol &rest forms
     Using SYMBOL as an argument to "throw", execute FORMS.  If FORMS
     includes a call to `semantic-thow-on-input', then if a user
     presses any key during execution, this form macro will exit with
     the value passed to "semantic-throw-on-input".  If FORMS
     completes, then the return value is the same as "progn".

Upon catching user input, you can try to detect if there was an exit
from the return argument, and continue throwing with an additional call
to `semantic-throw-on-input'.


File: semantic-appdev.info,  Node: Example Programs,  Next: Current Context,  Prev: Idle Scheduling,  Up: Top

Programming Examples
********************

*** NOTE ***  These examples are for semantic 1.4.  Using the below
functions will generate compile time warnings with advice on what
functions to use in semantic 2.0.

Here are some simple examples that use different aspects of the
semantic library APIs.  For fully functional example programs with lots
of comments, see the file `semantic-examples.el'.

Interactively querying for a token name
=======================================

If you need a command that asks the user for a token name, you can get
full range completion using the query functions *Note Tag Completion::.

     (interactive (list (semantic-read-symbol "Symbol: ")))

Finding a symbol in a buffer
============================

If you have the name of a function or variable, and need to find its
location in a buffer, you need a search function.  There is a wide
range of searches you can perform *Note Searching Tag Tables::.

     (semantic-find-nonterminal-by-name
      "some-name"
      (current-buffer)
      t    ;; look inside structures and classes for these symbols
      nil) ;; do not look inside header files.

Finding a symbol in a project
=============================

If you have the name of a function or variable, and need to find its
location somewhere in a project, you need to use the Semantic Database
*note (semanticdb)semanticdb::.  There are many search functions
similar to the ones found in *Note Searching Tag Tables::.

The Semantic Database is interesting in that the return structure is not

Locating a token in a buffer
============================

If you have a nonterminal token, or a list of them, you may want to
find their position in a buffer.

     (semanticdb-find-nonterminal-by-name
      "symbol"
      nil   ;; Defaults to the current project's database list.
      t     ;; Search inside types
      nil   ;; Do not search include files
      nil   ;; Only search files in the same mode (all C files)
      t     ;; When a token is found, make sure it is loaded in a buffer.
      )

Of interesting note above, semanticdb can find symbols in files that
are not loaded into an Emacs buffer.  These tokens do not have an
associated overlay, and the function "semantic-token-buffer" will fail.

The last parameter's tells the search function to "find-file-noselect"
any file in which a matching token was found.  This will allow you to
merge all the tokens into a completion list, or other flat list needed
by most functions that use association lists.

If you do not ask semanticdb to load those files, you will need to
explicitly request the database object (found in the `car' of each
sublist) get the file loaded.  It is useful to not auto find all files
if you don't need to jump to that token.

Converting a token into a human readable string.
================================================

A tag is a rather unpleasant Lisp structure when trying to decipher
what is going on.  As such, there is a wide range of functions
available that can convert a token into a human readable, and colorful
string *Note Format Tag::.

If you program interfaces with lots of users, you will probably want to
have your program define a configurable variable that will let users
change the visible portion of your program.

     (defcustom my-summary-function 'semantic-uml-prototype-nonterminal
       "*Function to use when showing info about my tag."
       :group 'my-program
       :type semantic-format-tag-custom-list)

Note the special type provided by Semantic.

Next, you can call this function to create a string.

     (funcall my-summary-function tag
                                  tag-parent
                                  t ; use color
                                  )

In this case, TAG-PARENT is an optional argument.  In many cases,
parent is not used by the outputting function.  The parent must be a
tag whose `semantic-tag-componenets' contains TAG, or nil for top-level
definitions.  In particular, C++ needs the parent to correctly
calculate the protection of each method.


File: semantic-appdev.info,  Node: Current Context,  Next: GNU Free Documentation License,  Prev: Example Programs,  Up: Top

Deriving the Current Context
****************************

This chapter deals with how to derive the current context, and also how
a language maintainer can get the current context API to work with
their language.

By default, the behavior will function in C like languages.  This means
languages with parenthetical blocks, and type dereferencing which uses
a similar form.

* Menu:

* Blocks::
* Local Variables::             Getting lists of local variables.
* Derived Context::             What goes at a given location?
* Context Analysis::            Analysis information about the local context.


File: semantic-appdev.info,  Node: Blocks,  Next: Local Variables,  Up: Current Context

Blocks and Navigation
=====================

Source code is typically built up of control structures, and blocks of
context, or lexical scope.  Semantic terms these lexical scopes as a
"context".  The following functions can be used to navigate contexts.
Some of them are override functions.  Language authors can override a
subset of them to make them work for their language.

 - Function: semantic-up-context &optional point bounds-type
     Move point up one context from POINT.  Return non-`nil' if there
     are no more context levels.  Overloaded functions using
     `up-context' take no parameters.  BOUNDS-TYPE is a symbol
     representing a tag class to restrict movement to.  If this is
     `nil', `'function' is used.  This will find the smallest tag of
     that class (function, variable, type, etc) and make sure non-`nil'
     is returned if you cannot go up past the bounds of that tag.

 - Function: semantic-beginning-of-context &optional point
     Move POINT to the beginning of the current context.  Return
     non-`nil' if there is no upper context.  The default behavior uses
     "semantic-up-context".  This function can be overriden in semantic
     using the symbol `beginning-of-context'.

 - Function: semantic-end-of-context &optional point
     Move POINT to the end of the current context.  Return non-`nil' if
     there is no upper context.  Be default, this uses
     "semantic-up-context", and assumes parenthetical block delimiters.
     This function can be overriden in semantic using the symbol
     `end-of-context'.

These next set of functions can be used to navigate across commands.

 - Function: semantic-end-of-command
     Move to the end of the current command.  Be default, uses
     `semantic-command-separation-character'.  This function can be
     overriden in semantic using the symbol `end-of-command'.

 - Function: semantic-beginning-of-command
     Move to the beginning of the current command.  Be default, uses
     `semantic-command-separation-character'.  This function can be
     overriden in semantic using the symbol `beginning-of-command'.


File: semantic-appdev.info,  Node: Local Variables,  Next: Derived Context,  Prev: Blocks,  Up: Current Context

Deriving local variables
========================

Within a given context, or block of code, local variables are often
defined.  These functions can be used to retrieve lists of locally
scoped variables.

 - Function: semantic-get-local-variables &optional point
     Get the local variables based on POINT's context.  Local variables
     are returned in Semantic tag format.  This can be overriden with
     `get-local-variables'.

 - Function: semantic-get-local-arguments &optional point
     Get arguments (variables) from the current context at POINT.
     Parameters are available if the point is in a function or method.
     Return a list of tags unlinked from the originating buffer.
     Arguments are obtained by overriding `get-local-arguments', or by
     the default function "semantic-get-local-arguments-default".
     This, must return a list of tags, or a list of strings that will
     be converted to tags.

 - Function: semantic-get-all-local-variables &optional point
     Get all local variables for this context, and parent contexts.
     Local variables are returned in Semantic tag format.  Be default,
     this gets local variables, and local arguments.  Optional argument
     POINT is the location to start getting the variables from.  This
     function can be overriden in semantic using the symbol
     `get-all-local-variables'.


File: semantic-appdev.info,  Node: Derived Context,  Next: Context Analysis,  Prev: Local Variables,  Up: Current Context

Deriving the Current Context
============================

While a context has already been used to describe blocks of code, other
context include more local details, such as the symbol the cursor is
on, or the fact we are assigning into some other variable.

These context deriving functions can be overridden to provide language
specific behavior.  By default, it assumes a C like language.

 - Function: semantic-ctxt-current-symbol &optional point
     Return the current symbol the cursor is on at POINT in a list.
     This will include a list of type/field names when applicable.
     This function can be overriden in semantic using the symbol
     `ctxt-current-symbol'.

 - Function: semantic-ctxt-current-assignment &optional point
     Return the current assignment near the cursor at POINT.  Return a
     list as per "semantic-ctxt-current-symbol".  Return `nil' if there
     is nothing relevant.  This function can be overriden in semantic
     using the symbol `ctxt-current-assignment'.

 - Function: semantic-ctxt-current-function &optional point
     Return the current function call the cursor is in at POINT.  The
     function returned is the one accepting the arguments that the
     cursor is currently in.  It will not return function symbol if the
     cursor is on the text representing that function.  This function
     can be overriden in semantic using the symbol
     `ctxt-current-function'.

 - Function: semantic-ctxt-current-argument &optional point
     Return the index of the argument position the cursor is on at
     POINT.  This function can be overriden in semantic using the
     symbol `ctxt-current-argument'.

 - Function: semantic-ctxt-current-thing
     Calculate a thing identified by the current cursor position.
     Calls previously defined `semantic-ctxt-current-...' calls until
     something gets a match.  See "semantic-ctxt-current-symbol",
     "semantic-ctxt-current-function", and
     "semantic-ctxt-current-assignment" for details on the return value.

 - Function: semantic-ctxt-current-class-list &optional point
     Return a list of tag classes that are allowed at POINT.  If POINT
     is `nil', the current buffer location is used.  For example, in
     Emacs Lisp, the symbol after a ( is most likely a function.  In a
     makefile, symbols after a : are rules, and symbols after a $( are
     variables.  This function can be overriden in semantic using the
     symbol `ctxt-current-class-list'.

 - Function: semantic-ctxt-scoped-types &optional point
     Return a list of type names currently in scope at POINT.  The
     return value can be a mixed list of either strings (names of types
     that are in scope) or actual tags (type declared locally that may
     or may not have a name.)  This function can be overriden in
     semantic using the symbol `ctxt-scoped-types'.


File: semantic-appdev.info,  Node: Context Analysis,  Prev: Derived Context,  Up: Current Context

Analysis of the current context
===============================

The context parsing API is used in a context analysis library.  This
library provides high level routines for scanning through token
databases to create lists of token associates.  At it's core is a set
of EIEIO classes defining a context.  The context contains information
about what was parsed at a given position, such as the strings there,
and they type of assignment.  The analysis library then searches the
databases to determine the types and names available.

Two high level functions which can be run interactively are:

 - Command: semantic-analyze-current-context position
     Analyze the current context at POSITION.  If called interactively,
     display interesting information about POSITION in a separate
     buffer.  Returns an object based on symbol
     `semantic-analyze-context'.

 - Command: semantic-analyze-possible-completions point
     Return a list of semantic tokens which are possible completions.
     Analysis is done at POINT.

* Menu:

* Analysis Overview::           A description of how the analyzer works.
* Analysis Objects::            What is in the analysis object.
* Completion Overview::         How completions are calculated.


File: semantic-appdev.info,  Node: Analysis Overview,  Next: Analysis Objects,  Up: Context Analysis

Analysis Overview
-----------------

The semantic analysis function "semantic-analye-current-context" creats
an Analysis Object.  See *Note Analysis Objects::.  This object
contains many useful pieces of information needed to do any other kind
of intelligent action on the local context.

If you call this function interactively, it will popup a buffer with a
summary of the return value.  This is useful when debugging.

     +--------+   +----------------+   +----------------------------+
     | Buffer |---| Context Parser |---| Local Context Synax Result |
     +--------+   +----------------+   +----------------------------+
         |                                        |
     +--------+   +-----------+                   |
     | Parser |---| Tag Table |------------+      |
     +--------+   +-----------+            |      |
                                           V      V
     +-------------+                     +-------------------+
     | Semantic DB |-------------------->| Semantic Analyzer |
     +-------------+                     +-------------------+
                                                  |
                                                  V
                                          +-----------------+
                                          | Analysis Object |
                                          +-----------------+


File: semantic-appdev.info,  Node: Analysis Objects,  Next: Completion Overview,  Prev: Analysis Overview,  Up: Context Analysis

Analysis Objects
----------------


File: semantic-appdev.info,  Node: Completion Overview,  Prev: Analysis Objects,  Up: Context Analysis

Completion Overview
-------------------


File: semantic-appdev.info,  Node: GNU Free Documentation License,  Next: Index,  Prev: Current Context,  Up: Top

GNU Free Documentation License
******************************

                        Version 1.1, March 2000
     Copyright (C) 2000  Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.


  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone
     the effective freedom to copy and redistribute it, with or without
     modifying it, either commercially or noncommercially.  Secondarily,
     this License preserves for the author and publisher a way to get
     credit for their work, while not being considered responsible for
     modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.


  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed
     under the terms of this License.  The "Document", below, refers to
     any such manual or work.  Any member of the public is a licensee,
     and is addressed as "you".

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter
     section of the Document that deals exclusively with the
     relationship of the publishers or authors of the Document to the
     Document's overall subject (or to related matters) and contains
     nothing that could fall directly within that overall subject.
     (For example, if the Document is in part a textbook of
     mathematics, a Secondary Section may not explain any mathematics.)
     The relationship could be a matter of historical connection with
     the subject or with related matters, or of legal, commercial,
     philosophical, ethical or political position regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, whose contents can be viewed and edited directly
     and straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup has been designed
     to thwart or discourage subsequent modification by readers is not
     Transparent.  A copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML designed for human modification.
     Opaque formats include PostScript, PDF, proprietary formats that
     can be read and edited only by proprietary word processors, SGML
     or XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you
     must enclose the copies in covers that carry, clearly and legibly,
     all these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a publicly-accessible
     computer-network location containing a complete Transparent copy
     of the Document, free of added material, which the general
     network-using public has access to download anonymously at no
     charge using public-standard network protocols.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

     A. Use in the Title Page (and on the covers, if any) a title
     distinct    from that of the Document, and from those of previous
     versions    (which should, if there were any, be listed in the
     History section    of the Document).  You may use the same title
     as a previous version    if the original publisher of that version
     gives permission.
     B. List on the Title Page, as authors, one or more persons or
     entities    responsible for authorship of the modifications in the
     Modified    Version, together with at least five of the principal
     authors of the    Document (all of its principal authors, if it
     has less than five).
     C. State on the Title page the name of the publisher of the
     Modified Version, as the publisher.
     D. Preserve all the copyright notices of the Document.
     E. Add an appropriate copyright notice for your modifications
     adjacent to the other copyright notices.
     F. Include, immediately after the copyright notices, a license
     notice    giving the public permission to use the Modified Version
     under the    terms of this License, in the form shown in the
     Addendum below.
     G. Preserve in that license notice the full lists of Invariant
     Sections    and required Cover Texts given in the Document's
     license notice.
     H. Include an unaltered copy of this License.
     I. Preserve the section entitled "History", and its title, and add
     to    it an item stating at least the title, year, new authors, and
       publisher of the Modified Version as given on the Title Page.
     If    there is no section entitled "History" in the Document,
     create one    stating the title, year, authors, and publisher of
     the Document as    given on its Title Page, then add an item
     describing the Modified    Version as stated in the previous
     sentence.
     J. Preserve the network location, if any, given in the Document for
       public access to a Transparent copy of the Document, and
     likewise    the network locations given in the Document for
     previous versions    it was based on.  These may be placed in the
     "History" section.     You may omit a network location for a work
     that was published at    least four years before the Document
     itself, or if the original    publisher of the version it refers
     to gives permission.
     K. In any section entitled "Acknowledgements" or "Dedications",
     preserve the section's title, and preserve in the section all the
      substance and tone of each of the contributor acknowledgements
     and/or dedications given therein.
     L. Preserve all the Invariant Sections of the Document,
     unaltered in their text and in their titles.  Section numbers
     or the equivalent are not considered part of the section titles.
     M. Delete any section entitled "Endorsements".  Such a section
     may not be included in the Modified Version.
     N. Do not retitle any existing section as "Endorsements"    or to
     conflict in title with any Invariant Section.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties-for example, statements of peer review or that the text has
     been approved by an organization as the authoritative definition
     of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections entitled
     "History" in the various original documents, forming one section
     entitled "History"; likewise combine any sections entitled
     "Acknowledgements", and any sections entitled "Dedications".  You
     must delete all sections entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, does not as a whole count as a
     Modified Version of the Document, provided no compilation
     copyright is claimed for the compilation.  Such a compilation is
     called an "aggregate", and this License does not apply to the
     other self-contained works thus compiled with the Document, on
     account of their being thus compiled, if they are not themselves
     derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one
     quarter of the entire aggregate, the Document's Cover Texts may be
     placed on covers that surround only the Document within the
     aggregate.  Otherwise they must appear on covers around the whole
     aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License provided that you also include the
     original English version of this License.  In case of a
     disagreement between the translation and the original English
     version of this License, the original English version will prevail.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     http://www.gnu.org/copyleft/.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.


ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:


       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.1
       or any later version published by the Free Software Foundation;
       with the Invariant Sections being LIST THEIR TITLES, with the
       Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
       A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.
If you have no Invariant Sections, write "with no Invariant
Sections" instead of saying which ones are invariant.  If you have no
Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover
Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

