[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111026: Import srecode manual from CEDET trunk

[Glenn Morris]

------------------------------------------------------------
revno: 111026
fixes bug: http://debbugs.gnu.org/9966
author: Eric Ludlam <address@hidden>
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-12-12 09:15:25 -0800
message:
  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 <address@hidden>
  David Engster <address@hidden>
  Vincent Belaïche <address@hidden>
  
  and from:
  address@hidden
  address@hidden
added:
  doc/misc/srecode.texi
modified:
  doc/misc/ChangeLog

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-12-12 16:47:07 +0000
+++ b/doc/misc/ChangeLog        2012-12-12 17:15:25 +0000
@@ -1,3 +1,7 @@
+2012-12-12  Eric Ludlam  <address@hidden>
+
+       * srecode.texi: New file, imported from CEDET trunk.
+
 2012-12-12  Bastien Guerry  <address@hidden>
 
        * org.texi (Summary, Code block specific header arguments)

=== added file 'doc/misc/srecode.texi'
--- a/doc/misc/srecode.texi     1970-01-01 00:00:00 +0000
+++ b/doc/misc/srecode.texi     2012-12-12 17:15:25 +0000
@@ -0,0 +1,1768 @@
+\input texinfo   @c -*-texinfo-*-
address@hidden
address@hidden $Id: srecode.texi,v 1.24 2010-05-30 20:22:40 scymtym Exp $
address@hidden
address@hidden %**start of header
address@hidden srecode.info
address@hidden TITLE SRecoder Manual
address@hidden AUTHOR Eric M. Ludlam
address@hidden @value{TITLE}
address@hidden %**end of header
+
address@hidden
address@hidden Emacs
address@hidden
+START-INFO-DIR-ENTRY
+* srecode: (srecode).       Template code generator
+END-INFO-DIR-ENTRY
address@hidden format
address@hidden ifinfo
+
address@hidden
address@hidden 10
address@hidden @titlefont{srecode}
address@hidden 0pt plus 1 fill
+Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Eric M. Ludlam
address@hidden titlepage
+
address@hidden semantic{}
address@hidden
address@hidden macro
+
address@hidden EIEIO{}
address@hidden
address@hidden macro
+
address@hidden srecode{}
address@hidden
address@hidden macro
+
address@hidden Top
address@hidden @value{TITLE}
+
address@hidden 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
address@hidden
+
+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.
+
address@hidden
+* 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::
address@hidden menu
+
+
address@hidden Quick Start
address@hidden 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:
+
address@hidden
+M-x srecode-minor-mode RET
address@hidden example
+or
address@hidden
+M-x global-srecode-minor-mode RET
address@hidden example
+
+or add
+
address@hidden
+(srecode-minor-mode 1)
address@hidden 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:
+
address@hidden Option srecode-map-load-path
address@hidden
+Global load path for SRecode template files.
address@hidden deffn
+
+
+Once installed, you can start inserting templates using the menu, or
+the command:
+
address@hidden Command srecode-insert template-name &rest dict-entries
address@hidden
+Insert the template @var{template-name} into the current buffer at point.
address@hidden are additional dictionary values to add.
address@hidden deffn
+
+SRecode Insert will prompt for a template name.  Template names are
+specific to each major mode.  A typical name is of the form:
address@hidden:NAME} where a @var{CONTEXT} might be something like
address@hidden or @code{declaration}.  The same @var{NAME} can occur in
+multiple contexts.
+
address@hidden User Templates
address@hidden User Templates
+
address@hidden 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
address@hidden map file.
+
address@hidden srecode-map-save-file
address@hidden
+The save location for SRecode's map file.
address@hidden 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
address@hidden:function} into themselves.
+
+You can also override variables.  Core variables are stored in the
address@hidden 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
address@hidden like this:
+
address@hidden
+set mode "default"
address@hidden example
+
address@hidden Parts of SRecode
address@hidden Parts of SRecode
+
+The @srecode{} system is made up of several layers which work together
+to generate code.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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
address@hidden object subclass.  See
address@hidden for more.
+
address@hidden 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
address@hidden:cpp} arguments.
address@hidden
+
address@hidden 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
address@hidden, @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}.
address@hidden
+
address@hidden 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
address@hidden application for creating comments for Semantic
+tags.  The CEDET application @i{EDE} has a project type that is an
address@hidden application.
+
address@hidden 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.
+
address@hidden SRecode Minor Mode
address@hidden 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
address@hidden<insert>} can also be used.
+
+The most important key is bound to @code{srecode-insert} which is
address@hidden / /}, or @key{insert insert}.  @ref{Quick Start}.
+
+Major keybindings are:
+
address@hidden @key
address@hidden C-c / /
+Insert a template whose name is typed into the minibuffer.
address@hidden C-c / <lower case letter>
+Reserved for direct binding of simple templates to keys using a
+keybinding command in the template file.
address@hidden C-c / <upper case letter>
+Reserved for template applications (Such as comment or get/set inserter.)
address@hidden C-c / E
+Edit the code of a template.
address@hidden C-c / .
+Insert template again.  This will cause the previously inserted
+template to be inserted again.
address@hidden table
+
address@hidden 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:
+
address@hidden srecode-insert-ask-variable-method
address@hidden
+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:
address@hidden @code
address@hidden ask
+Prompt in the minibuffer as the value is inserted.
address@hidden field
+Use the dictionary macro name as the inserted value,
+and place a field there.  Matched fields change together.
address@hidden table
+
address@hidden: The field feature does not yet work with XEmacs.
address@hidden 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.
+
address@hidden: Some conveniences in templates, such as completion, or
+character restrictins are lost when using field editing mode.
+
address@hidden Template Writing
address@hidden Template Writing
address@hidden@code{SRecode-template-mode}}
+
address@hidden 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:
+
address@hidden @asis
address@hidden template file
+A file with a @file{.srt} extension which contains settings,
+variables, and templates.
address@hidden 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.
address@hidden macro
+A macro is a text sequence within template text that is replaced with
+some other value.
address@hidden dictionary
+A table of variable names and values.
address@hidden subdictionary
+A dictionary that is subordinate under another dictionary as a value
+to some variable.
address@hidden variable
+A variable is an entry in a dictionary which has a value.
address@hidden table
+
address@hidden
+* Variables:: Creating special and regular variables.
+* Templates:: Creating templates
+* Contexts::  Templates are grouped by context
+* Prompts::   Setting prompts for interactive insert macros
address@hidden menu
+
address@hidden Variables
address@hidden 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:
address@hidden
+set VARNAME "some value"
address@hidden 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.
+
address@hidden
+* 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
address@hidden menu
+
address@hidden String Values
address@hidden 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
address@hidden, @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.
+
address@hidden Multi-string Values
address@hidden 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
+
address@hidden
+set NAME "this" "-mode"
address@hidden 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:
+
address@hidden
+set NAME macro "MODE" "-mode"
address@hidden example
+
+will extract the value of the dictionary variable MODE and append
+``-mode'' to the end.
+
address@hidden Section Show
address@hidden 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.
+
address@hidden
+show NAME
address@hidden example
+
+This will enable that section.
+
+
+NOTE: May 11, 2008 - I haven't used this yet, so I don't know if it works.
+
+
address@hidden Special Variables
address@hidden Special Variables
+
+Some variables have special meaning that changes attributes when
+templates are compiled, including:
+
address@hidden @code
address@hidden 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.
address@hidden escape-end
+This is the character sequence that escapes the end of a template
+macro name.
+
+Example:
address@hidden
+set escape_start "$"
+set escape_end "$"
address@hidden example
address@hidden 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:
address@hidden
+set mode "emacs-lisp-mode"
address@hidden example
+
address@hidden 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:
address@hidden
+set priority "35"
address@hidden example
+
address@hidden 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:
address@hidden
+set application "document"
address@hidden example
+
address@hidden 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:
address@hidden
+set project "/tmp/testproject"
address@hidden example
+
address@hidden table
+
+If you need to insert the characters that belong to the variables
address@hidden or @code{escape_end}, then place those into
+a variable.  For example
+
address@hidden
+set escape_start "$"
+set escape_end "$"
+set DOLLAR "$"
address@hidden example
+
address@hidden Automatic Loop Variables
address@hidden 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.
+
address@hidden @bullet
address@hidden @var{first} - The first entry in the table.
address@hidden @var{notfirst} - Not the first entry in the table.
address@hidden @var{last} - The last entry in the table
address@hidden @var{notlast} - Not the last entry in the table.
address@hidden itemize
+
address@hidden Compound Variable Values
address@hidden 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
address@hidden
+
+New compound variables can only be setup from Lisp code.  See
address@hidden Dictionary Values} for details on setting up compound
+variables from Lisp.
+
address@hidden Templates
address@hidden Templates
+
+A template represents a text pattern that can be inserted into
+a buffer.
+
+A basic template is declaired like this:
+
address@hidden
+template TEMPLATENAME :arg1 :arg2
+"Optional documentation string"
+----
+The text to your template goes here.
+----
+bind "a"
address@hidden 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 "-----".
+
address@hidden
+* Template Section Dictionaries::  Template Scoped Macro values
+* Template Macros::     Macros occuring in template patterns
address@hidden menu
+
address@hidden Template Section Dictionaries
address@hidden 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:
+
address@hidden
+template TEMPLATENAME :arg1 :arg2
+"Optional documentation string"
+sectiondictionary "A"
+set NAME "foo"
+----
+A beginning line @address@hidden@address@hidden
address@hidden@address@hidden@}Optional string @address@hidden@address@hidden 
address@hidden@{/address@hidden@}
+An end line
+----
address@hidden 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):
+
address@hidden
+template variable :el
+"Insert a variable.
+DOC is optional."
+----
+(defvar $?NAME$ $^$
+  "$DOC$")
+----
address@hidden 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.
+
address@hidden
+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$
+----
address@hidden example
+
+In this way, @var{NAME} can be set as a user posed question for
address@hidden 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.
+
address@hidden Template Macros
address@hidden Template Macros
+
+Template macros occur in the template text.  The default escape
+characters are address@hidden@{`` and address@hidden@}'', though they can be 
changed
+in the top-level variables.  See @ref{Variables}.
+
+Thus, if you have the template code that looks like this:
+
address@hidden
+;; Author: @address@hidden@address@hidden
address@hidden example
+
+Then the text between @address@hidden and @address@hidden 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.
+
address@hidden
+;; Author: @address@hidden:address@hidden@}
address@hidden 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:
+
address@hidden
address@hidden@{! This is a comment inside macro escape characters 
@address@hidden
address@hidden example
+
+shows that the ``!'' symbol is for comments.
+
+Alternately, a macro could query the user during insertion:
+
address@hidden
+(defun @address@hidden@address@hidden ()
+   @address@hidden@address@hidden
+   ) ;; End of @address@hidden@address@hidden
address@hidden 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:
+
address@hidden
+   | this | that |@address@hidden@address@hidden
+   | @address@hidden|THIS:address@hidden@} | 
@address@hidden|THAT:address@hidden@} |@address@hidden/address@hidden@}
address@hidden 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.
+
address@hidden
address@hidden@address@hidden@}
+Here is some text describing moose.
address@hidden@{/address@hidden@}
address@hidden 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.
address@hidden Template Functions}.
address@hidden
+
+Macros prefixed with ``>'' will include another template.  Include
+macros would look like this:
+
address@hidden
address@hidden@{>FOO:address@hidden@}
address@hidden 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:
+
address@hidden
address@hidden@{<FOO:address@hidden@}Handy Text goes 
address@hidden@{/address@hidden@}
address@hidden example
+
+In this case, @code{defun} is included just as above.  If the
address@hidden template has a @address@hidden@address@hidden 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 @address@hidden@address@hidden, 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:
+
address@hidden
address@hidden@{>FOO:declaration:address@hidden@}
address@hidden example
+
address@hidden Contexts
address@hidden 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:
+
address@hidden
+context NAME
address@hidden 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:
+
address@hidden
+context C1
+
+template foo
+"Foo template in C1"
+----
+----
+
+context C2
+
+temlate foo
+"Foo template in C2"
+----
+----
address@hidden 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.
+
address@hidden Prompts
address@hidden Prompt
+
+Some templates use promtping macro insertion.  A macro that needs a
+prompt looks like this:
+
address@hidden
address@hidden@address@hidden@}
address@hidden example
+
+where ? comes after the first escape character.
+
+by default, it will use a prompt like this when it is encountered:
+
address@hidden
+Specify NAME:
address@hidden 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:
+
address@hidden
+prompt VARNAME "Nice Way to ask for VARNAME: "
address@hidden example
+
+Now, if you put this in a template:
+
address@hidden
+template variable
+----
+(defvar @address@hidden@address@hidden nil
+   "")
+----
address@hidden example
+
+when VARNAME is encountered, it will use the nice prompt.
+
+Prompts can be extended as well.  For example:
+
address@hidden
+prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
address@hidden example
+
+In this case, the @code{default} keyword indicates that
address@hidden"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.
+
address@hidden
+prompt VARNAME "Varname: " defaultmacro "PREFIX"
address@hidden 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.
+
address@hidden Dictionaries
address@hidden 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.
+
address@hidden
+* 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
address@hidden menu
+
address@hidden Create a Dictionary
address@hidden Create a Dictionary
+
address@hidden srecode-create-dictionary &optional buffer
address@hidden
+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.
address@hidden defun
+
address@hidden Setting Dictionary Values
address@hidden 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.
+
address@hidden srecode-dictionary-set-value dict name value
address@hidden
+In dictionary @var{dict}, set @var{name} to have @var{value}.
address@hidden defun
+
+For section macros, you can have alternate values.  A section can
+either be toggled as visible, or it can act as a loop.
+
address@hidden srecode-dictionary-show-section dict name
address@hidden
+In dictionary @var{dict}, indicate that the section @var{name} should be 
exposed.
address@hidden defun
+
+
address@hidden srecode-dictionary-add-section-dictionary dict name show-only
address@hidden
+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 address@hidden, 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.
+
address@hidden @var
address@hidden first
+The first entry in the table.
address@hidden notfirst
+Not the first entry in the table.
address@hidden last
+The last entry in the table
address@hidden notlast
+Not the last entry in the table.
address@hidden table
+
+Adding a new dictionary will alter these values in previously
+inserted dictionaries.
address@hidden defun
+
address@hidden Compound Dictionary Values
address@hidden 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.
+
address@hidden Type srecode-dictionary-compound-value
address@hidden
+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.
address@hidden deffn
+
+Your new subclass of the compound value needs to implement these
+methods:
+
address@hidden srecode-compound-toString cp function dictionary
address@hidden
+Convert the compound dictionary value @var{cp} to a string.
+If @var{function} is address@hidden, 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.
address@hidden defun
+
+The next method is for dumping out tables during debugging.
+
address@hidden srecode-dump cp &optional indent
address@hidden
+Display information about this compound value.
address@hidden defun
+
+
+Here is an example of wrapping a semantic tag in a compound value:
+
address@hidden
+(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))
+    ))
address@hidden example
+
address@hidden Argument Resolution
address@hidden Argument Resolution
+
+Some dictionary entries can be set via template arguments in the
+template declaration.  For examples of template arguments, see
address@hidden Argument Dictionary Entries}.
+
+  You can resolve an argument list into a dictionary with:
+
address@hidden srecode-resolve-arguments temp dict
address@hidden
+Resolve all the arguments needed by the template @var{temp}.
+Apply anything learned to the dictionary @var{dict}.
address@hidden defun
+
address@hidden Creating new Arguments
address@hidden 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
address@hidden:user} argument:
+
address@hidden
+(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))
+   ;; ...
+  )
address@hidden example
+
+In this case, a function with the name prefix
address@hidden 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.
+
address@hidden Querying a Dictionary
address@hidden 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.
+
address@hidden srecode-dictionary-lookup-name dict name
address@hidden
+Return information about the current @var{DICT}'s value for @var{NAME}.
address@hidden 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}'.
address@hidden defun
+
+
+
address@hidden Template Argument Dictionary Entries
address@hidden 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:
+
address@hidden
+template template-name :arg1 :arg2
+----
+Your template goes here
+----
address@hidden example
+
+specifies two arguments :arg1, and :arg2.
+
+The following built-in simple arguments are available:
+
address@hidden
+* Base Arguments::
+* Semantic Arguments::
+* Language Arguments::
address@hidden menu
+
address@hidden Base Arguments
address@hidden Base Arguments
+
address@hidden Argument :indent
+
+Supplies the @code{INDENT} macro.  When @code{INDENT} is non-nil, then
+each line is individually indented with
address@hidden during macro processing.
+
address@hidden 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.
+
address@hidden Argument :region
+
+If there is an active region via @code{transient-mark-mode}, or
address@hidden, 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.
+
address@hidden Argument :user
+
+Sets up variables about the current user.
+
address@hidden @code
address@hidden AUTHOR
+Value of the Emacs function @code{user-full-name}
address@hidden EMAIL
+Current Emacs user's email address.
address@hidden LOGIN
+Current Emacs user's login name.
address@hidden UID
+Current Emacs user's login ID.
address@hidden EMACSINITFILE
+This Emacs sessions' init file.
address@hidden table
+
address@hidden Argument :time
+
+Sets up variables with the current date and time.
+
address@hidden @code
address@hidden YEAR
+The current year.
address@hidden MONTH
+The current month as a number.
address@hidden MONTHNAME
+The current month name, unabbreviated.
address@hidden DAY
+The current day as a number.
address@hidden WEEKDAY
+The current day of the week as an abbreviated name
address@hidden HOUR
+The current hour in 24 hour format.
address@hidden HOUR12
+The current hour in 12 hour format.
address@hidden AMPM
+Locale equivalent of AM or PM.  Usefule with HOUR12.
address@hidden MINUTE
+The current minute.
address@hidden SECOND
+The current second.
address@hidden TIMEZONE
+The timezone string.
address@hidden DATE
+The Locale supported date (%D).
address@hidden TIME
+The Locale supported time format (%X).
address@hidden table
+
address@hidden Argument :file
+
+Sets up variables with details about the current file.
+
address@hidden @code
address@hidden FILENAME
+The filename without the directory part of the current buffer.
address@hidden FILE
+The filename without the directory or extension
address@hidden EXTENSION
+The filename extension.
address@hidden DIRECTORY
+The directory in which the current buffer resides.
address@hidden MODE
+Major mode of this buffer.
address@hidden SHORTMODE
+Major mode of this buffer without ``-mode''.
+Useful for inserting the Emacs mode specifier.
address@hidden section RCS
+Show the section RCS if there is a CVS or RCS directory here.
address@hidden table
+
address@hidden Argument :system
+
+Sets up variables with computer system information.
+
address@hidden @code
address@hidden SYSTEMCONF
+The ``system-configuration''.
address@hidden SYSTEMTYPE
+The ``system-type''.
address@hidden SYSTEMNAME
+The ``system-name''.
address@hidden MAILHOST
+The name of the machine Emacs derived mail ``comes from''.
address@hidden table
+
address@hidden Argument :kill
+
address@hidden @code
address@hidden KILL
+The top-most item from the kill ring.
address@hidden KILL2
+The second item in the kill ring.
address@hidden KILL3
+The third item in the kill ring.
address@hidden KILL4
+The fourth item in the kill ring.
address@hidden table
+
address@hidden Semantic Arguments
address@hidden Semantic Arguments
+
address@hidden 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.
+
address@hidden @code
address@hidden TAG
+This is a compound value for the tag in the current senator kill ring,
+or something handled via the variable
address@hidden
+
address@hidden srecode-semantic-selected-tag
address@hidden
+The tag selected by a @code{:tag} template argument.
+If this is @code{nil}, then @code{senator-tag-ring} is used.
address@hidden defvar
+
+Use the function part of a macro insert to extract obscure parts
+of the tag.
address@hidden NAME
+The name of the tag as a string.
address@hidden TYPE
+The data type of the tag as a string.
address@hidden table
+
+If @var{tag} is a function, you will get these additional dictionary
+entries.
+
address@hidden @code
address@hidden ARGS
+A Loop macro value.  Each argument is inserted in ARGS.  To create a
+comma separated list of arguments, you might do this:
+
address@hidden
address@hidden@address@hidden@address@hidden@address@hidden@} 
@address@hidden@address@hidden@address@hidden@address@hidden,@address@hidden/address@hidden@address@hidden@{/address@hidden@}
address@hidden example
+
+Within the section dictionaries for each argument, you will find both
address@hidden and @var{TYPE}, in addition to the automatic section values
+for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
address@hidden PARENT
+The string name of the parent of this function, if the function is a
+method of some class.
address@hidden THROWS
+In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
address@hidden table
+
+If @var{tag} is a variable, you will get these dictionary entries.
+
address@hidden @code
address@hidden DEFAULTVALUE
+Enabled if there is a @var{VALUE}.
address@hidden VALUE
+An entry in the @var{HAVEDEFAULT} subdictionary that represents the
+textual representation of the default value of this variable.
address@hidden table
+
+If @var{tag} is a datatype, you will get these dictionary entries.
+
address@hidden @code
address@hidden PARENTS
+Section dictionaries for the parents of this class.  Each parent will
+have a @var{NAME}.
address@hidden INTERFACES
+Section dictionaries for all the implemented interfaces of this
+class.  Each interface will have a @var{NAME}.
address@hidden table
+
+Note that data type templates should always have a 
@address@hidden@address@hidden@}}
+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.
+
address@hidden Language Arguments
address@hidden language Arguments
+
+Each language typically has its own argument.  These arguments can be
+used to fill in language specific values that will be useful.
+
address@hidden Argument :srt
+
+Used for SRecoder template files.
+
address@hidden @code
address@hidden ESCAPE_START
+The characters used for an escape start
address@hidden ESCAPE_END
+The characters used for an escape end
address@hidden table
+
address@hidden Argument :cpp
+
address@hidden @code
address@hidden HEADER
+Shows this section if the current file is a header file.
address@hidden NOTHEADER
+The opposite of @code{HEADER}.
address@hidden FILENAME_SYMBOL
+The current filename reformatted as a C friendly symbol.
address@hidden table
+
address@hidden Argument :java
+
address@hidden @code
address@hidden FILENAME_AS_PACKAGE
+Converts the filename into text that would be suitable as a package
+name.
address@hidden FILENAME_AS_CLASS
+Converts the filename into text that would be suitable as a class-name
+for the main class in the file.
address@hidden CURRENT_PACKAGE
+Finds the occurance of ``package'' and gets its value.
address@hidden table
+
address@hidden 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.
+
address@hidden Argument :el-custom
+
address@hidden @code
address@hidden GROUP
+The name of the Emacs Custom group that instances of @code{defcustom}
+ought to use.
address@hidden FACEGROUP
+The name of the Emacs Custom group that faces delcared with
address@hidden ought to use.
address@hidden table
+
address@hidden Argument :texi
+
address@hidden @code
address@hidden LEVEL
+The current section level, such as @code{chapter} or @code{section}.
address@hidden NEXTLEVEL
+The next level down, so if @code{LEVEL} is @code{chapter}, then
address@hidden would be @code{section}.
address@hidden table
+
address@hidden 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.
+
address@hidden Argument :android
+
+The @code{:android} argument pulls in information from your current
+project.
+
+@@TODO - add more here.
+
address@hidden Developing Template Functions
address@hidden 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:
+
address@hidden
+(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)
+    ))
address@hidden example
+
+Lets look at the key functions involved above:
+
address@hidden Interactive Completion:
+
address@hidden srecode-read-template-name prompt
address@hidden
+Completing read for Semantic Recoder template names.
address@hidden is used to query for the name of the template desired.
address@hidden defun
+
address@hidden 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.
+
address@hidden srecode-table &optional mode
address@hidden
+Return the currently active Semantic Recoder table for this buffer.
+Optional argument @var{MODE} specifies the mode table to use.
address@hidden defun
+
+
address@hidden srecode-template-get-table tab template-name &optional context 
application
address@hidden
+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.
address@hidden defun
+
+For purposes of an @srecode{} application, it is important to decide
+what to call yoru application, and use that with this method call.
+
address@hidden Creating dictionaries
+
+Several dictionary calls are made in this example, including:
address@hidden @code
address@hidden srecode-create-dictionary
address@hidden srecode-dictionary-set-value
address@hidden srecode-dictionary-show-section
address@hidden srecode-dictionary-add-section-dictionary
address@hidden table
+
+These are documented more fully @ref{Dictionaries}.
+
+Also used is @code{srecode-resolve-arguments}.  To learn more about
+that, see @ref{Argument Resolution}.
+
address@hidden Template Insertion Commands
+
+There are several ways to insert a template.  It is easiest to just
+start with the main entry point.
+
address@hidden srecode-insert-fcn template dictionary &optional stream
address@hidden
+Insert @var{template} using @var{dictionary} into @var{stream}.
+If @var{stream} is nil, then use the current buffer.
address@hidden defun
+
address@hidden Template Naming Conventions
address@hidden 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
address@hidden
+
+
+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.
+
+
address@hidden Context: File
+
+Each language should support the @code{file:empty} template.  This
+will generally use the default copyright insertion mechanism.
+
address@hidden Context: Declaration
+
+Functional languages should attempt to support the following:
+
address@hidden @code
address@hidden function
+A standalone function.  Not a method, external method, or other.
address@hidden method
+A method belonging to some class declaired outside the textual bounds
+of that class' declaration.
address@hidden variable
+A global variable.
address@hidden type
+A data type.  If the language supports several types of datatypes
+then do not use this, use more specific ones instead.
address@hidden class
+For OO languages, use this instead of @code{type}.
address@hidden include
+Include files.
address@hidden table
+
+For any @semantic{} tag class in your language, you will likely want
+to have a corresponding template.
+
+In order for the @srecode{} function
address@hidden 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.
+
address@hidden Context: Classdef
+
+Inside a class definition.  These are to be inserted inside the
+textual bounds of a class declaration.
+
address@hidden @code
address@hidden function
+This would be a method of the class being inserted into.
address@hidden constructor
address@hidden destructor
+Like @code{function} but specific to alloc/delete of an object.
address@hidden variable
+This would be a field of the class being inserted into.
address@hidden table
+
address@hidden Context: Code
+
+Inside a body of code, such as a function or method body.
+
+ - no conventions yet.
+
address@hidden 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.
+
address@hidden @var
address@hidden NAME
+The name of the declaration being created.
address@hidden PARENT
+If the item belongs to some parent type, it would be the full name of
+that type, including namespaces.
address@hidden TYPE
+A datatype name for a variable, or the return value of a function.
address@hidden DOC
+If there is some documentation associated with the item, then DOC
+should contain the value.  (Optional)
address@hidden 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.
address@hidden table
+
+For templates used by @code{srecode-semantic-insert-tag}, there is
+also the following useful dictionary values.
+
address@hidden @var
address@hidden TAG
+A special insertion value TAG.  You can use semantic functions to turn
+the tag into a string.
address@hidden HAVEDEFAULT
address@hidden DEFAULT
+Default value for a variable.
address@hidden table
+
address@hidden Inserting Tag Lists
address@hidden Inserting Tag Lists
+
+Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
address@hidden 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.
+
address@hidden srecode-semantic-insert-tag tag &optional style-option 
point-insert-fcn &rest dict-entries
address@hidden
+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
address@hidden'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
address@hidden 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
address@hidden (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.
address@hidden defun
+
+
address@hidden Application Writing
address@hidden 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:
address@hidden
+set application "getset"
address@hidden example
+
+In your application Emacs Lisp code, you would then load those
+templates.  A typical initialization would look like this:
+
address@hidden
+  (srecode-load-tables-for-mode major-mode)
+  (srecode-load-tables-for-mode major-mode 'getset)
address@hidden example
+
+These two lines will load in the base templates for the major mode,
+and then the application specific templates.
+
address@hidden srecode-load-tables-for-mode mmode &optional appname
address@hidden
+Load all the template files for @var{mmode}.
+Templates are found in the SRecode Template Map.
+See @dfn{srecode-get-maps} for more.
address@hidden is the name of an application.  In this case,
+all template files for that application will be loaded.
address@hidden defun
+
+
+ todo - Add examples.  Most core stuff is already described above.
+
+
+
address@hidden Index
address@hidden Index
+
address@hidden
+
address@hidden