Import srecode manual from CEDET trunk

Ref
http://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00419.html
and preceding discussion

Imported from
bzr://cedet.bzr.sourceforge.net/bzrroot/cedet/code/trunk
doc/texi/srecode.texi

bzr log shows (very) tiny changes from authors with assignments:
Alex Ott <ottalex@users.sourceforge.net>
David Engster <dengste@eml.cc>
Vincent Belaïche <vincentb1@users.sourceforge.net>

and from:
emacsman@users.sourceforge.net
scymtym@users.sourceforge.net

Fixes: debbugs:9966

2 files changed, 1772 insertions, 0 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index b96345ba135..8bc178e005b 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,7 @@
+2012-12-12  Eric Ludlam  <zappo@gnu.org>
+
+        * srecode.texi: New file, imported from CEDET trunk.
+
 2012-12-12  Bastien Guerry  <bzg@gnu.org>
 
         * org.texi (Summary, Code block specific header arguments)
diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi
new file mode 100644
index 00000000000..e2f0ec79c2e
--- /dev/null
+++ b/doc/misc/srecode.texi
@@ -0,0 +1,1768 @@
+\input texinfo   @c -*-texinfo-*-
+@c
+@c $Id: srecode.texi,v 1.24 2010-05-30 20:22:40 scymtym Exp $
+@c
+@c %**start of header
+@setfilename srecode.info
+@set TITLE SRecoder Manual
+@set AUTHOR Eric M. Ludlam
+@settitle @value{TITLE}
+@c %**end of header
+
+@ifinfo
+@dircategory Emacs
+@format
+START-INFO-DIR-ENTRY
+* srecode: (srecode).       Template code generator
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@titlepage
+@sp 10
+@center @titlefont{srecode}
+@vskip 0pt plus 1 fill
+Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Eric M. Ludlam
+@end titlepage
+
+@macro semantic{}
+@i{semantic}
+@end macro
+
+@macro EIEIO{}
+@i{EIEIO}
+@end macro
+
+@macro srecode{}
+@i{SRecode}
+@end macro
+
+@node Top
+@top @value{TITLE}
+
+@srecode{} is the @i{Semantic Recoder}.  Where @semantic{} will parse
+source files into lists of tags, the @i{Semantic Recoder} will aid in
+converting @semantic{} tags and various other information back into
+various types of code.
+
+While the @srecode{} tool provides a template language, templates for
+several languages, and even a sequence of heuristics that aid the user
+in choosing a template to insert, this is not the main goal of
+@srecode{}.
+
+The goal of @srecode{} is to provide an application framework where
+someone can write a complex code generator, and the underlying
+template commonality allows it to work in multiple languages with
+ease.
+
+@menu
+* Quick Start::                 Basic Setup for template insertion.
+* User Templates::              Custom User Templates
+* Parts of SRecode::            Parts of the system
+* SRecode Minor Mode::          A minor mode for using templates
+* Template Writing::            How to write a template
+* Dictionaries::                How dictionaries work
+* Developing Template Functions:: How to write your own template insert functions.
+* Template Naming Conventions:: Creating a set of core templates
+* Inserting Tag Lists::         Inserting Semantic tags via templates
+* Application Writing::         Writing an @srecode{}r application
+* Index::
+@end menu
+
+
+@node Quick Start
+@chapter Quick Start
+
+When you install CEDET and enable @srecode{}, an @code{SRecoder} menu
+item should appear.
+
+To toggle @srecode{} minor mode on and off use:
+
+@example
+M-x srecode-minor-mode RET
+@end example
+or
+@example
+M-x global-srecode-minor-mode RET
+@end example
+
+or add
+
+@example
+(srecode-minor-mode 1)
+@end example
+
+into a language hook function to force it on (which is the default) or
+pass in @code{-1} to force it off.
+
+See @ref{SRecode Minor Mode} for more on using the minor mode.
+
+Use the menu to insert templates into the current file.
+
+You can add your own templates in @file{~/.srecode}, or update the
+template map path:
+
+@deffn Option srecode-map-load-path
+@anchor{srecode-map-load-path}
+Global load path for SRecode template files.
+@end deffn
+
+
+Once installed, you can start inserting templates using the menu, or
+the command:
+
+@deffn Command srecode-insert template-name &rest dict-entries
+@anchor{srecode-insert}
+Insert the template @var{template-name} into the current buffer at point.
+@var{dict-entries} are additional dictionary values to add.
+@end deffn
+
+SRecode Insert will prompt for a template name.  Template names are
+specific to each major mode.  A typical name is of the form:
+@code{CONTEXT:NAME} where a @var{CONTEXT} might be something like
+@code{file} or @code{declaration}.  The same @var{NAME} can occur in
+multiple contexts.
+
+@node User Templates
+@chapter User Templates
+
+@srecode{} builds and maintains a map of all template files.  The root
+template files resides in the @srecode{} distribution.  User written
+templates files are saved in @file{~/.srecode}, along with the
+@srecode{} map file.
+
+@defvar srecode-map-save-file
+@anchor{srecode-map-save-file}
+The save location for SRecode's map file.
+@end defvar
+
+Template files end with a @file{.srt} extension.  Details on how to
+write templates are in @ref{Template Writing}.
+
+Each template file you write is dedicated to a single major mode.  In
+it, you can write templates within the same context and with the same
+name as core templates.  You can force your templates to override the
+core templates for a particular major mode by setting the
+priority.  See @ref{Special Variables}.
+
+To get going quickly, open a new @file{.srt} file.  It will start in
+the @srecode{} template writing mode.  Use the @srecode{} minor mode
+menu to insert the @code{empty} file template.
+
+When using templates in other modes (such as C++ or Emacs Lisp
+templates), use the ``Edit Template'' menu to find a template you
+would like to update.  Copy it into your user template file, and
+change it.
+
+If you were to update @code{declaration:function} in your user
+template file, then you would get this new template instead of the one
+that comes with @srecode{}.  Higher level applications should always
+use @code{declaration:function} when generating their own code, so
+higher level templates will then adopt your changes to
+@code{declaration:function} into themselves.
+
+You can also override variables.  Core variables are stored in the
+@srecode{} root template file @file{default.srt}, and that contains
+the copyright usually used, and some basic file setup formats.
+Override variables like this by specifying a @code{mode} of
+@code{default} like this:
+
+@example
+set mode "default"
+@end example
+
+@node Parts of SRecode
+@chapter Parts of SRecode
+
+The @srecode{} system is made up of several layers which work together
+to generate code.
+
+@section Template Layer
+The template layer provides a way to write, and compile templates.  The
+template layer is the scheme used to insert text into an Emacs buffer.
+
+The @srecode{} template layer is more advanced than other modes like the
+Emacs packages @code{skeleton} or @code{tempo} in that it allows
+multiple layers of templates to be created with the same names.  This
+means that @srecode{} can provide a wide range of templates, and users
+can override only the small sections they want, instead of either
+accepting someone else's template, or writing large new templates of
+their own.
+
+Templates are written in @file{.srt} files.  You can learn how to
+author new @file{.srt} files @ref{Template Writing}.
+
+While the template system was designed for @srecode{} based
+applications it can also be used independently for simple template
+insertion during typical coding.
+
+@section Template Manager
+Once templates have been written, a scheme for loading and selecting
+templates is needed.  The template manager has a loader for finding
+template files, and determining which templates are relevant to the
+current buffer.  Template files are sorted by priority, with user
+templates being found first, and system level default templates last.
+Templates are also sorted by application.  Each application has its
+own templates, and are kept seperate from the generic templates.
+
+@section Dictionary
+Dictionaries contain values associated with variable.  Variables are
+used in macros in a template.  Variables are what allows a generic
+template such as a function to be made specific, such as a function
+named foo.  The value of a variable can be one of three things; a
+string, a list of more dictionaries, or a special
+@code{srecode-dictionary-compound-value} object subclass.  See
+@ref{Variables} for more.
+
+@section Template Insertion
+The template insertion layer involves extensions to the basic template
+layer.  A wide range of custom variables are available for mixing derived
+data as macros into the plain text of a template.
+
+In addition, templates can be declared with arguments.  These
+arguments represent predetermined sets of dictionary values, such as
+features of the current file name, user name, time, etc.
+
+Some arguments are major-mode specific, such as the @code{:el} or
+@code{:cpp} arguments.
+@refill
+
+@section Template Insertion Context
+A context can be provided for templates in a file.  This helps
+auto-selection of templates by name, or allows templates in different
+contexts to have the same name.  Some standard contexts are
+@code{file}, @code{declaration}, and @code{classdecl}.
+
+A context can be automatically derived as well based on the parsing
+state from @i{Semantic}.  @inforef{Top, Semantic Manual, semantic}.
+@refill
+
+@section Applications
+Commands that do a particular user task which involves also writing
+Emacs Lisp code.  Applications are at the top layer.  These
+applications have their own template files and logic needed to fill in
+dictionaries or position a cursor.  SRecode comes with an example
+@code{srecode-document} application for creating comments for Semantic
+tags.  The CEDET application @i{EDE} has a project type that is an
+@srecode{} application.
+
+@section Field Editing
+If the variable @code{srecode-insert-ask-variable-method} is set to
+'field, then variables that would normally ask a question, will
+instead create ``fields'' in the buffer.  A field-editing layer
+provides simple interaction through the fields.  Typing in a field
+will cause all variable locations that are the same to edit at the
+same time.  Pressing TAB on a field will move you to the next field.
+
+@node SRecode Minor Mode
+@chapter SRecode Minor Mode
+
+The Semantic Recode minor mode enables a keymap and menu that provides
+simple access to different templates or template applications.
+
+The key prefix is @key{C-c /}.
+
+If the variable @code{srecode-takeover-INS-key} is set, then the key
+@key{<insert>} can also be used.
+
+The most important key is bound to @code{srecode-insert} which is
+@key{C-c / /}, or @key{insert insert}.  @ref{Quick Start}.
+
+Major keybindings are:
+
+@table @key
+@item C-c / /
+Insert a template whose name is typed into the minibuffer.
+@item C-c / <lower case letter>
+Reserved for direct binding of simple templates to keys using a
+keybinding command in the template file.
+@item C-c / <upper case letter>
+Reserved for template applications (Such as comment or get/set inserter.)
+@item C-c / E
+Edit the code of a template.
+@item C-c / .
+Insert template again.  This will cause the previously inserted
+template to be inserted again.
+@end table
+
+@section Field Editing
+
+By default, when inserting a template, if the user needs to enter text
+to fill in a part of the template, then the minibuffer is used to
+query for that information.  SRecode also supports a field-edting mode
+that can be used instead.  To enable it set:
+
+@defun srecode-insert-ask-variable-method
+@anchor{srecode-insert-ask-variable-method}
+Determine how to ask for a dictionary value when inserting a template.
+Only the @var{ASK} style inserter will query the user for a value.
+Dictionary value references that ask begin with the ? character.
+Possible values are:
+@table @code
+@item ask
+Prompt in the minibuffer as the value is inserted.
+@item field
+Use the dictionary macro name as the inserted value,
+and place a field there.  Matched fields change together.
+@end table
+
+@b{NOTE}: The field feature does not yet work with XEmacs.
+@end defun
+
+Field editing mode is supported in newer versions of Emacs.  You
+will not be prompted to fill in values while the template is
+inserted.  Instead, short regions will be highlighted, and the cursor
+placed in a field.  Typing in the field will then fill in the value.
+Several fields might be linked together.  In that case, typing in one
+area will modify the other linked areas.  Pressing TAB will move
+between editable fields in the template.
+
+Once the cursor moves out of the are inserted by the template, all the
+fields are cancelled.
+
+@b{NOTE}: Some conveniences in templates, such as completion, or
+character restrictins are lost when using field editing mode.
+
+@node Template Writing
+@chapter Template Writing
+@anchor{@code{SRecode-template-mode}}
+
+@code{srecode-template-mode} is the major mode used for designing new
+templates.  @srecode{} files (Extension @file{.srt}) are made up of
+variable settings and template declarations.
+
+Here is an overview of the terminology you will need for the next few
+sections:
+
+@table @asis
+@item template file
+A file with a @file{.srt} extension which contains settings,
+variables, and templates.
+@item template
+One named entity which represents a block of text that will be
+inserted.  The text is compiled into a sequence of insertable
+entities.  The entities are string constants, and macros.
+@item macro
+A macro is a text sequence within template text that is replaced with
+some other value.
+@item dictionary
+A table of variable names and values.
+@item subdictionary
+A dictionary that is subordinate under another dictionary as a value
+to some variable.
+@item variable
+A variable is an entry in a dictionary which has a value.
+@end table
+
+@menu
+* Variables:: Creating special and regular variables.
+* Templates:: Creating templates
+* Contexts::  Templates are grouped by context
+* Prompts::   Setting prompts for interactive insert macros
+@end menu
+
+@node Variables
+@section Variables
+
+Variables can be set up and used in templates.  Many variables you may
+use are set up via template arguments, but some may be preferences a
+user can set up that are used in system templates.
+
+When expanding a template, variables are stored in a @dfn{dictionary}.
+Dictionary entries are variables.  Variables defined in templates can
+have string like values.
+
+A variable can be set like this:
+@example
+set VARNAME "some value"
+@end example
+
+Note that a VARIABLE is a name in a dictionary that can be used in a
+MACRO in a template.  The macro referernces some variable by name.
+
+@menu
+* String Values::       Basic Variable values
+* Multi-string Values:: Complex variable values
+* Section Show::        Enabling the display of a named section.
+* Special Variables::   Variables with special names
+* Automatic Loop Variables:: Variables automatically set in section loops.
+* Compound Variable Values:: Compound Variable Values
+@end menu
+
+@node String Values
+@subsection String Values
+
+Variables can be set to strings.  Strings may contain newlines or any
+other characters.  Strings are interpreted by the Emacs Lisp reader so
+@code{\n}, @code{\t}, and @code{\"} work.
+
+When a string is inserted as part of a template, nothing within the
+string is interperted, such as template escape characters.
+
+@node Multi-string Values
+@subsection Multi-string Values
+
+A variable can be set to multiple strings.  A compound value is
+usually used when you want to use dictionary entries as part of a
+variable later on.
+
+Multi-string variable values are set like string values except there
+are more than one.  For example
+
+@example
+set NAME "this" "-mode"
+@end example
+
+These two strings will be concatenated together.
+
+A more useful thing is to include dictionary variables and concatenate
+those into the string.  Use the ``macro'' keyword to include the name
+of a variable.  This is like macros in a template.  For example:
+
+@example
+set NAME macro "MODE" "-mode"
+@end example
+
+will extract the value of the dictionary variable MODE and append
+``-mode'' to the end.
+
+@node Section Show
+@subsection Section Show
+
+To set a variable to show a template section, use the @code{show}
+command.  Sections are blocks of a template wrapped in section macros.
+If there is a section macro using @var{NAME} it will be shown for each
+dictionary associated with the @var{NAME} macro.
+
+@example
+show NAME
+@end example
+
+This will enable that section.
+
+
+NOTE: May 11, 2008 - I haven't used this yet, so I don't know if it works.
+
+
+@node Special Variables
+@subsection Special Variables
+
+Some variables have special meaning that changes attributes when
+templates are compiled, including:
+
+@table @code
+@item escape-start
+This is the character sequence that escapes from raw text to template
+macro names.  The ability to change the escape characters are key for
+enabling @srecode{} templates to work across many kinds of languages.
+@item escape-end
+This is the character sequence that escapes the end of a template
+macro name.
+
+Example:
+@example
+set escape_start "$"
+set escape_end "$"
+@end example
+@item mode
+This is the major mode, as a string with the full Emacs Lisp symbol in
+it.  All templates in this file will be installed into the template
+table for this major mode.
+
+Multiple template files can use the same mode, and all those templates
+will be available in buffers of that mode.
+
+Example:
+@example
+set mode "emacs-lisp-mode"
+@end example
+
+@item priority
+The priority of a file is a number in a string constant that
+indicates where it lies in the template search order.  System
+templates default to low priority numbers.  User templates default to
+high priority numbers.  You can specify the priority of your template
+to insert it anywhere in the template search list.
+
+If there are multiple templates with the same context and name, the
+template with the highest priority number will be used.
+
+If multiple files have the same priority, then then sort order is
+unpredictable.  If no template names match, then it doesn't matter.
+
+Example:
+@example
+set priority "35"
+@end example
+
+@item application
+If a template file contains templates only needed for a particular
+application, then specify an application.  Template files for an
+application are stored in the template repository, but are not used in
+the generic template insertion case.
+
+The application with a particular name will access these templates
+from Lisp code.
+
+Example:
+@example
+set application "document"
+@end example
+
+@item project
+If a template file contains templates, or template overrides specific
+to a set of files under a particular directory, then that template
+file can specify a ``project'' that it belongs to.
+
+Set the ``project'' special variable to a directory name.  Only files
+under that directory will be able to access the templates in that
+file.
+
+Any template file that has a project specified will get have a
+priority that is set between SRecode base templates, and user defined
+templates.
+
+Templates can be compiled via a project system, such as EDE.  EDE
+loaded templates will get a @var{project} set automatically.
+
+Example:
+@example
+set project "/tmp/testproject"
+@end example
+
+@end table
+
+If you need to insert the characters that belong to the variables
+@code{escape_start} or @code{escape_end}, then place those into
+a variable.  For example
+
+@example
+set escape_start "$"
+set escape_end "$"
+set DOLLAR "$"
+@end example
+
+@node Automatic Loop Variables
+@subsection Automatic Loop Variables
+
+When section macros are used, that section is repeated for each
+subdictionary bound to the loop variable.
+
+Each dictionary added will automatically get values for positional
+macros which will enable different @var{sections}.  The automatic
+section variables are.
+
+@itemize @bullet
+@item @var{first} - The first entry in the table.
+@item @var{notfirst} - Not the first entry in the table.
+@item @var{last} - The last entry in the table
+@item @var{notlast} - Not the last entry in the table.
+@end itemize
+
+@node Compound Variable Values
+@subsection Compound Variable Values
+
+A variable can also have a compound value.  This means the value of
+the variable is an @EIEIO{} object, which is a subclass of
+@code{srecode-dictionary-compound-value}.
+
+New compound variables can only be setup from Lisp code.  See
+@ref{Compound Dictionary Values} for details on setting up compound
+variables from Lisp.
+
+@node Templates
+@section Templates
+
+A template represents a text pattern that can be inserted into
+a buffer.
+
+A basic template is declaired like this:
+
+@example
+template TEMPLATENAME :arg1 :arg2
+"Optional documentation string"
+----
+The text to your template goes here.
+----
+bind "a"
+@end example
+
+Templates are stored in a template table by name, and are inserted by
+the @var{templatename} provided.
+
+The documentation string is optional.  This documentation string will
+be used to aid users in selecting which template they want to use.
+
+The code that makes up the raw template occurs between the lines that
+contain the text "-----".
+
+@menu
+* Template Section Dictionaries::  Template Scoped Macro values
+* Template Macros::     Macros occuring in template patterns
+@end menu
+
+@node Template Section Dictionaries
+@subsection Template Section Dictionaries
+
+To add variable values to section dictionaries used within a specific
+template, you can add them to the beginning of the template
+declaration like this:
+
+@example
+template TEMPLATENAME :arg1 :arg2
+"Optional documentation string"
+sectiondictionary "A"
+set NAME "foo"
+----
+A beginning line @{@{NAME@}@}
+@{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@}
+An end line
+----
+@end example
+
+In this example, the @var{NAME} variable gets the value ``foo'', but
+only while it is inside section macro A.  The outer scoped NAME will
+be empty.
+
+This is particularly useful while using an include macro to pull in a
+second template.  In this way, you can pass values known from one
+template to a subordinate template where some value is not known.
+
+From the Emacs Lisp default template file, a syntax table is just a
+variable with a specialized value.
+
+If a variable is declared like this (where $ is the escape character):
+
+@example
+template variable :el
+"Insert a variable.
+DOC is optional."
+----
+(defvar $?NAME$ $^$
+  "$DOC$")
+----
+@end example
+
+then you can see that there is a NAME and DOC that is needed.
+The @code{^} point inserter is also a handy key here.
+
+The syntax table wants a variable, but knows the values of some of
+these variables, and can recast the problem like this by using
+template specific @code{sectiondictionary} macro declarations.
+
+@example
+template syntax-table
+"Create a syntax table."
+sectiondictionary "A"
+set NAME macro "?MODESYM" "-mode-syntax-table"
+set DOC "Syntax table used in " macro "?MODESYM" " buffers."
+----
+$<A:variable$
+  (let ((table (make-syntax-table (standard-syntax-table))))
+    (modify-syntax-entry ?\; ". 12"  table) ;; SEMI, Comment start ;;
+    ;; ...
+    table)
+$/A$
+----
+@end example
+
+In this way, @var{NAME} can be set as a user posed question for
+@var{MODESYM} with ``-mode-syntax-table'' appended.  A simplified doc
+string will also be inserted.
+
+Lastly, the @var{A} section contains more macro text which is inserted
+at the @code{^} point marker.
+
+By creating useful base templates for things like function or variable
+declarations, and recycling them in higher-order templates, an end
+user can override the basic declarator, and the higher order templates
+will then obey the new format, or perhaps even work in more than one
+major mode.
+
+@node Template Macros
+@subsection Template Macros
+
+Template macros occur in the template text.  The default escape
+characters are ``@{@{`` and ``@}@}'', though they can be changed
+in the top-level variables.  See @ref{Variables}.
+
+Thus, if you have the template code that looks like this:
+
+@example
+;; Author: @{@{AUTHOR@}@}
+@end example
+
+Then the text between @{@{ and @}@} are a macro, and substituted by
+the value of the variable @var{AUTHOR}.
+
+Macros can be specialized to be more than just a text string.  For
+example, the macro above could be augmented with an Emacs Lisp
+function.
+
+@example
+;; Author: @{@{AUTHOR:upcase@}@}
+@end example
+
+In this case, the Emacs Lisp function @code{upcase} will be called on
+the text value of the @var{AUTHOR} variable.
+
+Macros can also be specialized to have different behaviors by using a
+prefix, non-alpha character or symbol.  For example:
+
+@example
+@{@{! This is a comment inside macro escape characters @}@}
+@end example
+
+shows that the ``!'' symbol is for comments.
+
+Alternately, a macro could query the user during insertion:
+
+@example
+(defun @{@{?NAME@}@} ()
+   @{@{^@}@}
+   ) ;; End of @{@{NAME@}@}
+@end example
+
+the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the
+dictionary, then the user should be queried for the @var{NAME}
+variable.  If @var{NAME} appears again in the template, the original
+value specified by the user will be inserted again.
+
+If the text from a dictionary value is to be placed in column format,
+you can use the ``|'' symbol to indicate you want column control.  For
+example:
+
+@example
+   | this | that |@{@{#A@}@}
+   | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@}
+@end example
+
+For each repeated section ``#A'' the dictionary values for @var{THIS}
+and @var{THAT} will be inserted and either trimmed to, or expanded to
+4 characters in width.
+
+Macros that are prefixed with the ``#'' symbol denote a section.  A
+macro of the same name with a ``/'' prefix denotes the end of that
+section.
+
+@example
+@{@{#MOOSE@}@}
+Here is some text describing moose.
+@{@{/MOOSE@}@}
+@end example
+
+In this example if the section MOOSE was ``shown'' in the active
+dictionary, then the text between the # and / macros will also be
+inserted.
+
+All the text and macros within a section are either not shown at all
+(if that section is not 'visible') or the section is shown one time
+for each dictionary added to that symbol.
+@xref{Developing Template Functions}.
+@refill
+
+Macros prefixed with ``>'' will include another template.  Include
+macros would look like this:
+
+@example
+@{@{>FOO:defun@}@}
+@end example
+
+where @code{FOO} is the dictionary variable for the sub-dictionary used for
+expanding the template @code{defun}.  The @code{defun} template will
+be looked up in the template repository for the current mode, or in
+any inherited modes.
+
+Another way to include another template is with an include macro that
+will also wrap section text.  The includewrap insertion method looks
+like this:
+
+@example
+@{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@}
+@end example
+
+In this case, @code{defun} is included just as above.  If the
+@code{defun} template has a @{@{^@}@} macro in it, then the
+section text ``Handy Text goes here'' will be inserted at that point,
+and that location will not be saved as the cursor location.
+
+If there is no @{@{^@}@}, then the text will not be inserted.
+
+For both kinds of include macros, you may need to include a template
+from a different context.  You can use @code{:} separate the context
+from the name, like this:
+
+@example
+@{@{>FOO:declaration:function@}@}
+@end example
+
+@node Contexts
+@section Context
+
+Each template belongs to a context.  When promting for a template by
+name, such as with @kbd{C-c / /}, the name is prefixed by the current
+context.  If there is no context, it defaults to @code{declaration}.
+
+You can change context like this:
+
+@example
+context NAME
+@end example
+
+where @var{name} is some symbol that represents any context.
+
+A context resides over all templates that come after it until the next
+context statement.  Thus:
+
+@example
+context C1
+
+template foo
+"Foo template in C1"
+----
+----
+
+context C2
+
+temlate foo
+"Foo template in C2"
+----
+----
+@end example
+
+creates two @code{foo} templates.  The first one is when in context
+C1.  The second is available in context C2.
+
+This is useful if there are multiple ways to declare something like a
+function or variable that differ only by where it is in the syntax of
+the lanugage.  The name @code{foo} is not ambiguous because each is in
+a different context.
+
+@node Prompts
+@section Prompt
+
+Some templates use promtping macro insertion.  A macro that needs a
+prompt looks like this:
+
+@example
+@{@{?NAME@}@}
+@end example
+
+where ? comes after the first escape character.
+
+by default, it will use a prompt like this when it is encountered:
+
+@example
+Specify NAME:
+@end example
+
+For such macros, you can pre-define prompts for any dictionary entry.
+When that dictionary entry is first encountered, the user is prompted,
+and subsequent occurances of that dictionary entry use the same value.
+
+To get a different prompt, use a prompt command like this:
+
+@example
+prompt VARNAME "Nice Way to ask for VARNAME: "
+@end example
+
+Now, if you put this in a template:
+
+@example
+template variable
+----
+(defvar @{@{?VARNAME@}@} nil
+   "")
+----
+@end example
+
+when VARNAME is encountered, it will use the nice prompt.
+
+Prompts can be extended as well.  For example:
+
+@example
+prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
+@end example
+
+In this case, the @code{default} keyword indicates that
+@code{"srecode"} is the default string to use, and @code{y-or-n-p} is
+the function to use to ask the question.
+
+For @code{y-or-n-p} if you type ``y'' it inserts the default string,
+otherwise it inserts empty.
+
+For any other symbol that occurs after the @code{read} token, it is
+expected to take the same argument list as @code{read-string}.  As
+such, you can create your own prompts that do completing reads on
+deterministic values.
+
+To have the default be calculated later from a dictionary entry, you
+need to use the @code{defaultmacro} keyword instead.
+
+@example
+prompt VARNAME "Varname: " defaultmacro "PREFIX"
+@end example
+
+now, when it attempts to read in VARNAME, it will pre-populte the text
+editing section with whatever the value of PREFIX is.
+
+Some language arguments may supply possible prefixes for prompts.
+Look for these when creating your prompts.
+
+@node Dictionaries
+@chapter Dictionaries
+
+Dictionaries are a set of variables.  The values associated with the
+variable names could be anything, but how it is handled is dependent
+on the type of macro being inserted.
+
+Most of this chapter is for writing Lisp programs that use @srecode{}.
+If you only want to write template files, then you only need to read
+the @ref{Template Argument Dictionary Entries} section.
+
+@menu
+* Create a Dictionary::
+* Setting Dictionary Values::   Basic dictionary values
+* Compound Dictionary Values::  Complex dictionary values
+* Argument Resolution::         Automatic template argument resolution
+* Creating new Arguments::      Create new arguments for use in templates
+* Querying a Dictionary::       Querying a dictionary for values.
+* Template Argument Dictionary Entries:: Catalog of arguments
+@end menu
+
+@node Create a Dictionary
+@section Create a Dictionary
+
+@defun srecode-create-dictionary &optional buffer
+@anchor{srecode-create-dictionary}
+Create a dictionary for @var{buffer}.
+If @var{buffer} is not specified, use the current buffer.
+The dictionary is initialized with no variables or enabled sections.
+Any variables defined with @code{set} in the template, however,
+becomes a name in the dictionary.
+@end defun
+
+@node Setting Dictionary Values
+@section Setting Dictionary Values
+
+When building an @srecode{} based application, you will need to setup
+your dictionary values yourself.  There are several utility functions
+for this.
+
+In the simplest form, you can assocate a string with a variable.
+
+@defun srecode-dictionary-set-value dict name value
+@anchor{srecode-dictionary-set-value}
+In dictionary @var{dict}, set @var{name} to have @var{value}.
+@end defun
+
+For section macros, you can have alternate values.  A section can
+either be toggled as visible, or it can act as a loop.
+
+@defun srecode-dictionary-show-section dict name
+@anchor{srecode-dictionary-show-section}
+In dictionary @var{dict}, indicate that the section @var{name} should be exposed.
+@end defun
+
+
+@defun srecode-dictionary-add-section-dictionary dict name show-only
+@anchor{srecode-dictionary-add-section-dictionary}
+In dictionary @var{DICT}, add a section dictionary for section macro @var{NAME}.
+Return the new dictionary.
+
+You can add several dictionaries to the same section entry.
+For each dictionary added to a variable, the block of codes in
+the template will be repeated.
+
+If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add a new dictionarly
+if there is already one in place.  Also, don't add @var{FIRST}/@var{LAST} entries.
+These entries are not needed when we are just showing a section.
+
+Each dictionary added will automatically get values for positional macros
+which will enable @var{SECTIONS} to be enabled.
+
+@table @var
+@item first
+The first entry in the table.
+@item notfirst
+Not the first entry in the table.
+@item last
+The last entry in the table
+@item notlast
+Not the last entry in the table.
+@end table
+
+Adding a new dictionary will alter these values in previously
+inserted dictionaries.
+@end defun
+
+@node Compound Dictionary Values
+@section Compound Dictionary Values
+
+If you want to associate a non-string value with a dictionary
+variable, then you will need to use a compound value.  Compound
+dictionary values are derived using @EIEIO{} from a base class for
+handling arbitrary data in a macro.
+
+@deffn Type srecode-dictionary-compound-value
+@anchor{srecode-dictionary-compound-value}
+A compound dictionary value.
+Values stored in a dictionary must be a @var{string},
+a dictionary for showing sections, or an instance of a subclass
+of this class.
+
+Compound dictionary values derive from this class, and must
+provide a sequence of method implementations to convert into
+a string.
+@end deffn
+
+Your new subclass of the compound value needs to implement these
+methods:
+
+@defun srecode-compound-toString cp function dictionary
+@anchor{srecode-compound-toString}
+Convert the compound dictionary value @var{cp} to a string.
+If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect
+of the compound value.  The @var{function} could be a fraction
+of some function symbol with a logical prefix excluded.
+@end defun
+
+The next method is for dumping out tables during debugging.
+
+@defun srecode-dump cp &optional indent
+@anchor{srecode-dump}
+Display information about this compound value.
+@end defun
+
+
+Here is an example of wrapping a semantic tag in a compound value:
+
+@example
+(defclass srecode-semantic-tag (srecode-dictionary-compound-value)
+  ((prime :initarg :prime
+          :type semantic-tag
+          :documentation
+          "This is the primary insertion tag.")
+   )
+  "Wrap up a collection of semantic tag information.
+This class will be used to derive dictionary values.")
+
+(defmethod srecode-compound-toString((cp srecode-semantic-tag)
+                                     function
+                                     dictionary)
+  "Convert the compound dictionary value CP to a string.
+If FUNCTION is non-nil, then FUNCTION is somehow applied to an
+aspect of the compound value."
+  (if (not function)
+      ;; Just format it in some handy dandy way.
+      (semantic-format-tag-prototype (oref cp :prime))
+    ;; Otherwise, apply the function to the tag itself.
+    (funcall function (oref cp :prime))
+    ))
+@end example
+
+@node Argument Resolution
+@section Argument Resolution
+
+Some dictionary entries can be set via template arguments in the
+template declaration.  For examples of template arguments, see
+@ref{Template Argument Dictionary Entries}.
+
+  You can resolve an argument list into a dictionary with:
+
+@defun srecode-resolve-arguments temp dict
+@anchor{srecode-resolve-arguments}
+Resolve all the arguments needed by the template @var{temp}.
+Apply anything learned to the dictionary @var{dict}.
+@end defun
+
+@node Creating new Arguments
+@section Creating new Arguments
+
+You can create new arguments for use in template files by writing new
+Emacs Lisp functions.  Doing so is easy.  Here is an example for the
+@code{:user} argument:
+
+@example
+(defun srecode-semantic-handle-:user (dict)
+  "Add macros into the dictionary DICT based on the current :user."
+  (srecode-dictionary-set-value dict "AUTHOR" (user-full-name))
+  (srecode-dictionary-set-value dict "LOGIN" (user-login-name))
+   ;; ...
+  )
+@end example
+
+In this case, a function with the name prefix
+@code{srecode-semantic-handle-} that ends in @code{:user} creates a
+new argument @code{:user} that can be used in a template.
+
+Your argument handler must take one argument @var{dict}, which is the
+dictionary to fill in.  Inside your function, you can do whatever you
+want, but adding dictionary values is the right thing.
+
+@node Querying a Dictionary
+@section Querying a Dictionary
+
+When creating a new argument, it may be useful to ask the dicitonary
+what entries are already set there, and conditionally create new
+entries based on those.
+
+In this way, a template author can get additional logic through more
+advanced arguments.
+
+@defun srecode-dictionary-lookup-name dict name
+@anchor{srecode-dictionary-lookup-name}
+Return information about the current @var{DICT}'s value for @var{NAME}.
+@var{DICT} is a dictionary, and @var{NAME} is a string that is the name of
+a symbol in the dictionary.
+This function derives values for some special NAMEs, such as @var{FIRST}
+and '@var{LAST}'.
+@end defun
+
+
+
+@node Template Argument Dictionary Entries
+@section Template Argument Dictionary Entries
+
+When a dictionary is initialized for a template, then the dictionary
+will be initialized with a predefined set of macro values.
+
+A template of the form:
+
+@example
+template template-name :arg1 :arg2
+----
+Your template goes here
+----
+@end example
+
+specifies two arguments :arg1, and :arg2.
+
+The following built-in simple arguments are available:
+
+@menu
+* Base Arguments::
+* Semantic Arguments::
+* Language Arguments::
+@end menu
+
+@node Base Arguments
+@subsection Base Arguments
+
+@subsubsection Argument :indent
+
+Supplies the @code{INDENT} macro.  When @code{INDENT} is non-nil, then
+each line is individually indented with
+@code{indent-according-to-mode} during macro processing.
+
+@subsubsection Argument :blank
+
+Specifying this argument adds a special @code{:blank} handler at the
+beginning and end of the template.  This handler will insert @code{\n}
+if the insertion point is not on a line by itself.
+
+@subsubsection Argument :region
+
+If there is an active region via @code{transient-mark-mode}, or
+@code{mouse-drag-region}, then the @code{REGION} section will be
+enabled.
+
+In addition, @code{REGIONTEXT} will be set the the text in the region,
+and that region of text will be ``killed'' from the current buffer.
+
+If standard-output is NOT the current buffer, then the region will not
+be deleted.  In this way, you can safely use @code{:region} using
+templates in arbitrary output streams.
+
+@subsubsection Argument :user
+
+Sets up variables about the current user.
+
+@table @code
+@item AUTHOR
+Value of the Emacs function @code{user-full-name}
+@item EMAIL
+Current Emacs user's email address.
+@item LOGIN
+Current Emacs user's login name.
+@item UID
+Current Emacs user's login ID.
+@item EMACSINITFILE
+This Emacs sessions' init file.
+@end table
+
+@subsubsection Argument :time
+
+Sets up variables with the current date and time.
+
+@table @code
+@item YEAR
+The current year.
+@item MONTH
+The current month as a number.
+@item MONTHNAME
+The current month name, unabbreviated.
+@item DAY
+The current day as a number.
+@item WEEKDAY
+The current day of the week as an abbreviated name
+@item HOUR
+The current hour in 24 hour format.
+@item HOUR12
+The current hour in 12 hour format.
+@item AMPM
+Locale equivalent of AM or PM.  Usefule with HOUR12.
+@item MINUTE
+The current minute.
+@item SECOND
+The current second.
+@item TIMEZONE
+The timezone string.
+@item DATE
+The Locale supported date (%D).
+@item TIME
+The Locale supported time format (%X).
+@end table
+
+@subsubsection Argument :file
+
+Sets up variables with details about the current file.
+
+@table @code
+@item FILENAME
+The filename without the directory part of the current buffer.
+@item FILE
+The filename without the directory or extension
+@item EXTENSION
+The filename extension.
+@item DIRECTORY
+The directory in which the current buffer resides.
+@item MODE
+Major mode of this buffer.
+@item SHORTMODE
+Major mode of this buffer without ``-mode''.
+Useful for inserting the Emacs mode specifier.
+@item section RCS
+Show the section RCS if there is a CVS or RCS directory here.
+@end table
+
+@subsubsection Argument :system
+
+Sets up variables with computer system information.
+
+@table @code
+@item SYSTEMCONF
+The ``system-configuration''.
+@item SYSTEMTYPE
+The ``system-type''.
+@item SYSTEMNAME
+The ``system-name''.
+@item MAILHOST
+The name of the machine Emacs derived mail ``comes from''.
+@end table
+
+@subsubsection Argument :kill
+
+@table @code
+@item KILL
+The top-most item from the kill ring.
+@item KILL2
+The second item in the kill ring.
+@item KILL3
+The third item in the kill ring.
+@item KILL4
+The fourth item in the kill ring.
+@end table
+
+@node Semantic Arguments
+@subsection Semantic Arguments
+
+@subsubsection Argument :tag
+
+The :tag argument is filled in with information from Semantic.
+The tag in question is queried from the senator tag ring, or passed
+in from @srecode{} utilities that use tags in templates.
+
+@table @code
+@item TAG
+This is a compound value for the tag in the current senator kill ring,
+or something handled via the variable
+@code{srecode-semantic-selected-tag}.
+
+@defvar srecode-semantic-selected-tag
+@anchor{srecode-semantic-selected-tag}
+The tag selected by a @code{:tag} template argument.
+If this is @code{nil}, then @code{senator-tag-ring} is used.
+@end defvar
+
+Use the function part of a macro insert to extract obscure parts
+of the tag.
+@item NAME
+The name of the tag as a string.
+@item TYPE
+The data type of the tag as a string.
+@end table
+
+If @var{tag} is a function, you will get these additional dictionary
+entries.
+
+@table @code
+@item ARGS
+A Loop macro value.  Each argument is inserted in ARGS.  To create a
+comma separated list of arguments, you might do this:
+
+@example
+@{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@}
+@end example
+
+Within the section dictionaries for each argument, you will find both
+@var{NAME} and @var{TYPE}, in addition to the automatic section values
+for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
+@item PARENT
+The string name of the parent of this function, if the function is a
+method of some class.
+@item THROWS
+In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
+@end table
+
+If @var{tag} is a variable, you will get these dictionary entries.
+
+@table @code
+@item DEFAULTVALUE
+Enabled if there is a @var{VALUE}.
+@item VALUE
+An entry in the @var{HAVEDEFAULT} subdictionary that represents the
+textual representation of the default value of this variable.
+@end table
+
+If @var{tag} is a datatype, you will get these dictionary entries.
+
+@table @code
+@item PARENTS
+Section dictionaries for the parents of this class.  Each parent will
+have a @var{NAME}.
+@item INTERFACES
+Section dictionaries for all the implemented interfaces of this
+class.  Each interface will have a @var{NAME}.
+@end table
+
+Note that data type templates should always have a @code{@{@{^@}@}}
+macro in it where the core contents of that type will go.  This is why
+data types don't have subdictionaries full of the slots in the classes
+or structs.
+
+@node Language Arguments
+@subsection language Arguments
+
+Each language typically has its own argument.  These arguments can be
+used to fill in language specific values that will be useful.
+
+@subsubsection Argument :srt
+
+Used for SRecoder template files.
+
+@table @code
+@item ESCAPE_START
+The characters used for an escape start
+@item ESCAPE_END
+The characters used for an escape end
+@end table
+
+@subsubsection Argument :cpp
+
+@table @code
+@item HEADER
+Shows this section if the current file is a header file.
+@item NOTHEADER
+The opposite of @code{HEADER}.
+@item FILENAME_SYMBOL
+The current filename reformatted as a C friendly symbol.
+@end table
+
+@subsection Argument :java
+
+@table @code
+@item FILENAME_AS_PACKAGE
+Converts the filename into text that would be suitable as a package
+name.
+@item FILENAME_AS_CLASS
+Converts the filename into text that would be suitable as a class-name
+for the main class in the file.
+@item CURRENT_PACKAGE
+Finds the occurance of ``package'' and gets its value.
+@end table
+
+@subsubsection Argument :el
+
+Sets @code{PRENAME}.  This would be a common prefix from all the
+tags in the current buffer.
+
+Most Emacs Lisp packages have some common prefix used in a way similar
+to namespaces in other languages.
+
+@subsubsection Argument :el-custom
+
+@table @code
+@item GROUP
+The name of the Emacs Custom group that instances of @code{defcustom}
+ought to use.
+@item FACEGROUP
+The name of the Emacs Custom group that faces delcared with
+@code{defface} ought to use.
+@end table
+
+@subsubsection Argument :texi
+
+@table @code
+@item LEVEL
+The current section level, such as @code{chapter} or @code{section}.
+@item NEXTLEVEL
+The next level down, so if @code{LEVEL} is @code{chapter}, then
+@code{NEXTLEVEL} would be @code{section}.
+@end table
+
+@subsubsection Argument :texitag
+
+The @code{:texitag} argument is like the @code{:tag} argument, except that
+additional variable @code{TAGDOC} is provided for each tag.
+
+The @code{TAGDOC} is filled with derived documentation from the tag in
+question, and that documentation is also reformatted to be mostly
+texinfo compatible.
+
+@subsection Argument :android
+
+The @code{:android} argument pulls in information from your current
+project.
+
+@@TODO - add more here.
+
+@node Developing Template Functions
+@chapter Developing Template Functions
+
+You can develop your own custom template insertion functions.
+Doing so is relatively simple, and requires that you write an Emacs
+Lisp command.
+
+If the built in commands don't provide enough options, you will need
+to write your own function in order to provide your dictionaries with
+the values needed for custom templates.
+
+In this way, you can build your own code generator for any language
+based on a set of predefined macros whos values you need to derive
+from Emacs Lisp code yourself.
+
+For example:
+
+@example
+(defun my-srecode-insert (template-name)
+  "Insert the template TEMPLATE-NAME into the current buffer at point."
+
+  ;; Read in a template name.
+  (interactive (list (srecode-read-template-name "Template Name: ")))
+  (if (not (srecode-table))
+      (error "No template table found for mode %s" major-mode))
+  (let ((temp (srecode-template-get-table (srecode-table) template-name))
+
+       ;; Create a new dictionary
+        (newdict (srecode-create-dictionary)))
+
+    (if (not temp)
+        (error "No Template named %s" template-name))
+
+    ;; Add some values into the dictionary!
+    (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo))
+    ;; Optionally show a section
+    (srecode-dictionary-show-section newdict "BLARG")
+
+    ;; Add in several items over a loop
+    (let ((my-stuff (get-my-stuff-list)))
+       (while my-stuff
+          (let ((subdict (srecode-dictionary-add-section-dictionary
+                             newdict "LOOP")))
+             (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff))
+             (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff))
+             (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff))
+             )
+          (setq my-stuff (cdr my-stuff)))
+
+    ;; Some templates have arguments that need to be resolved.
+    (srecode-resolve-arguments temp newdict)
+
+    ;; Do the expansion
+    (srecode-insert-fcn temp newdict)
+    ))
+@end example
+
+Lets look at the key functions involved above:
+
+@section Interactive Completion:
+
+@defun srecode-read-template-name prompt
+@anchor{srecode-read-template-name}
+Completing read for Semantic Recoder template names.
+@var{prompt} is used to query for the name of the template desired.
+@end defun
+
+@section Template Lookup
+
+Even if your program does not query the user for a template name, you
+will need to locate a template.  First, you need to locate the table
+to look the template up in.
+
+@defun srecode-table &optional mode
+@anchor{srecode-table}
+Return the currently active Semantic Recoder table for this buffer.
+Optional argument @var{MODE} specifies the mode table to use.
+@end defun
+
+
+@defun srecode-template-get-table tab template-name &optional context application
+@anchor{srecode-template-get-table}
+Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}.
+Optional argument @var{CONTEXT} specifies a context a particular template
+would belong to.
+Optional argument @var{APPLICATION} restricts searches to only template tables
+belonging to a specific application.  If @var{APPLICATION} is @code{nil}, then only
+tables that do not belong to an application will be searched.
+@end defun
+
+For purposes of an @srecode{} application, it is important to decide
+what to call yoru application, and use that with this method call.
+
+@section Creating dictionaries
+
+Several dictionary calls are made in this example, including:
+@table @code
+@item srecode-create-dictionary
+@item srecode-dictionary-set-value
+@item srecode-dictionary-show-section
+@item srecode-dictionary-add-section-dictionary
+@end table
+
+These are documented more fully @ref{Dictionaries}.
+
+Also used is @code{srecode-resolve-arguments}.  To learn more about
+that, see @ref{Argument Resolution}.
+
+@section Template Insertion Commands
+
+There are several ways to insert a template.  It is easiest to just
+start with the main entry point.
+
+@defun srecode-insert-fcn template dictionary &optional stream
+@anchor{srecode-insert-fcn}
+Insert @var{template} using @var{dictionary} into @var{stream}.
+If @var{stream} is nil, then use the current buffer.
+@end defun
+
+@node Template Naming Conventions
+@chapter Template Naming Conventions
+
+For @srecode{} to work across langauges reliably, templates need to
+follow a predictable pattern.  For every language of similar nature
+(OO, functional, doc based) if they all provide the same base
+templates, then an application can be written against the base
+templates, and it will work in each of the supported language.
+
+Having consistent templates also makes it easy to use those templates
+from a user perspective during basic interactive insertion via
+@code{srecode-minor-mode}.
+
+
+NOTES ON THIS CHAPTER:
+
+These conventions are being worked on.  Check w/ CEDET-DEVEL mailing
+list if you want to support a language, or write an application and
+provide your opinions on this topic.  Any help is appreciated.
+
+
+@section Context: File
+
+Each language should support the @code{file:empty} template.  This
+will generally use the default copyright insertion mechanism.
+
+@section Context: Declaration
+
+Functional languages should attempt to support the following:
+
+@table @code
+@item function
+A standalone function.  Not a method, external method, or other.
+@item method
+A method belonging to some class declaired outside the textual bounds
+of that class' declaration.
+@item variable
+A global variable.
+@item type
+A data type.  If the language supports several types of datatypes
+then do not use this, use more specific ones instead.
+@item class
+For OO languages, use this instead of @code{type}.
+@item include
+Include files.
+@end table
+
+For any @semantic{} tag class in your language, you will likely want
+to have a corresponding template.
+
+In order for the @srecode{} function
+@code{srecode-semantic-insert-tag} to work, you can create templates
+similar to those mentioned above, except with @code{-tag} appended to
+the end.  This lets a template like @code{function} have user
+conveniences when referencing @code{function-tag}, while also
+allowing the tag inserter to do its job with a simpler template.
+
+@section Context: Classdef
+
+Inside a class definition.  These are to be inserted inside the
+textual bounds of a class declaration.
+
+@table @code
+@item function
+This would be a method of the class being inserted into.
+@item constructor
+@itemx destructor
+Like @code{function} but specific to alloc/delete of an object.
+@item variable
+This would be a field of the class being inserted into.
+@end table
+
+@section Context: Code
+
+Inside a body of code, such as a function or method body.
+
+ - no conventions yet.
+
+@section Standard Dictionary Values
+
+For these variables to be useful, standard names should be used.
+These values could be provided directly from a Semantic tag, or by an
+application.
+
+@table @var
+@item NAME
+The name of the declaration being created.
+@item PARENT
+If the item belongs to some parent type, it would be the full name of
+that type, including namespaces.
+@item TYPE
+A datatype name for a variable, or the return value of a function.
+@item DOC
+If there is some documentation associated with the item, then DOC
+should contain the value.  (Optional)
+@item ARGS
+The ARGS variable defines a section for 0 or more arguments to a function
+or method.  Each entry in ARGS will follow the rest of these naming
+conventions, such as for NAME and TYPE.
+@end table
+
+For templates used by @code{srecode-semantic-insert-tag}, there is
+also the following useful dictionary values.
+
+@table @var
+@item TAG
+A special insertion value TAG.  You can use semantic functions to turn
+the tag into a string.
+@item HAVEDEFAULT
+@itemx DEFAULT
+Default value for a variable.
+@end table
+
+@node Inserting Tag Lists
+@chapter Inserting Tag Lists
+
+Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
+@srecode{} is to convert lists of tags, as produced by @semantic{}
+back into code.
+
+A single function provides the interface for programs to do this, but
+it requires any particular language to have provided the correct
+templates to make it work.
+
+@defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries
+@anchor{srecode-semantic-insert-tag}
+Insert @var{tag} into a buffer using srecode templates at point.
+
+Optional @var{style-option} is a list of minor configuration of styles,
+such as the symbol @code{'prototype} for prototype functions, or
+@code{'system} for system includes, and @code{'doxygen}, for a doxygen style
+comment.
+
+Optional third argument @var{point-insert-fcn} is a hook that is run after
+@var{tag} is inserted that allows an opportunity to fill in the body of
+some thing.  This hook function is called with one argument, the @var{tag}
+being inserted.
+
+The rest of the arguments are @var{dict-entries}.  @var{dict-entries}
+is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn).
+
+The exact template used is based on the current context.
+The template used is found within the toplevel context as calculated
+by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl},
+or @code{code}.
+
+For various conditions, this function looks for a template with
+the name @var{class}-tag, where @var{class} is the tag class.  If it cannot
+find that, it will look for that template in the
+@code{declaration}context (if the current context was not @code{declaration}).
+
+If @var{prototype} is specified, it will first look for templates with
+the name @var{class}-tag-prototype, or @var{class}-prototype as above.
+
+See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in
+the dictionary when the templates are called.
+
+This function returns to location in the buffer where the
+inserted tag @var{ends}, and will leave point inside the inserted
+text based on any occurrence of a point-inserter.  Templates such
+as @dfn{function} will leave point where code might be inserted.
+@end defun
+
+
+@node Application Writing
+@chapter Application Writing
+
+The main goal of @srecode{} is to provide a strong platform for
+writing code generating applications.
+
+Any templates that are application specific should make an application
+declaration for each template file they use.  This prevents those
+templates from being used outside of that application.
+
+For example, add this to a file:
+@example
+set application "getset"
+@end example
+
+In your application Emacs Lisp code, you would then load those
+templates.  A typical initialization would look like this:
+
+@example
+  (srecode-load-tables-for-mode major-mode)
+  (srecode-load-tables-for-mode major-mode 'getset)
+@end example
+
+These two lines will load in the base templates for the major mode,
+and then the application specific templates.
+
+@defun srecode-load-tables-for-mode mmode &optional appname
+@anchor{srecode-load-tables-for-mode}
+Load all the template files for @var{mmode}.
+Templates are found in the SRecode Template Map.
+See @dfn{srecode-get-maps} for more.
+@var{appname} is the name of an application.  In this case,
+all template files for that application will be loaded.
+@end defun
+
+
+ todo - Add examples.  Most core stuff is already described above.
+
+
+
+@node Index
+@chapter Index
+
+@contents
+
+@bye